summaryrefslogtreecommitdiff
path: root/man8/ezjail-admin.8
diff options
context:
space:
mode:
authorerdgeist <erdgeist@erdgeist.org>2011-01-20 21:03:50 +0000
committererdgeist <erdgeist@erdgeist.org>2011-01-20 21:03:50 +0000
commit712cdc830d1456cec055ffd9a96540c047c96225 (patch)
treea9356100d7d2ee2b997037bd5f6bfc0944723c34 /man8/ezjail-admin.8
parent38bd97262a80fc5fb73b076115610eee501a6ea0 (diff)
New man pages, also put in new sections
Diffstat (limited to 'man8/ezjail-admin.8')
-rw-r--r--man8/ezjail-admin.8606
1 files changed, 606 insertions, 0 deletions
diff --git a/man8/ezjail-admin.8 b/man8/ezjail-admin.8
new file mode 100644
index 0000000..99b3110
--- /dev/null
+++ b/man8/ezjail-admin.8
@@ -0,0 +1,606 @@
1.Dd January 15, 2011
2.Dt EZJAIL-ADMIN 8 USD
3.Os FreeBSD
4.Sh NAME
5.Nm ezjail-admin
6.Nd Administrate ezjail environment
7.Sh SYNOPSIS
8.Nm Cm install
9.Op Fl mMpPsS
10.Op Fl h Ar host
11.Op Fl r Ar release
12.Nm
13.Cm create
14.Op Fl bx
15.Op Fl f Ar flavour
16.Op Fl r Ar jailroot
17.Op Fl a Ar archive
18.Op Fl A Ar options
19.Op Fl c Ar jailtype Fl s Ar imagesize Op Fl C Ar attachargs
20.Bk -words
21.Ar jailname ipaddress Ns Op Ar ,ipaddress2,...
22.Ek
23.Nm
24.Cm console
25.Op Fl f
26.Op Fl e Ar command
27.Ar jailname
28.Nm
29.Cm list
30.Nm
31.Cm start | stop | restart | cryptostart Ar jailname...
32.Nm
33.Cm config
34.Op Fl r Ar run | norun
35.Op Fl n Ar newname
36.Op Fl i Ar attach | detach | fsck
37.Op Fl z Ar newdataset
38.Op Fl c Ar newcpuset
39.Op Fl f Ar newfib
40.Ar jailname
41.Nm
42.Cm delete
43.Op Fl wf
44.Ar jailname
45.Nm
46.Cm archive
47.Op Fl Af
48.Op Fl a Ar archive
49.Op Fl d Ar archivedir
50.Ar jailname...
51.Nm
52.Cm restore
53.Op Fl f
54.Op Fl d Ar archivedir
55.Ar archive | jailname...
56.Nm
57.Cm update
58.Op Fl s Ar sourcetree
59.Op Fl p
60.Fl b | Fl i | Fl P | Fl u
61.Sh DESCRIPTION
62The
63.Nm
64utility is used to manage the ezjail environment and all the jails inside the
65ezjail scope. This man page describes the invocation of
66.Nm .
67Refer to
68.Xr ezjail 7
69in order to get an introduction to the usage of ezjail, as well as
70usage examples.
71.Pp
72The description of some options ends with
73.Sq Variable: Dq Li $ezjail_abcd .
74This means that the default value of the option may be overridden by setting
75this variable in
76.Xr ezjail.conf 5 ,
77which see.
78.Ss Nm Cm install
79This function sub-command is normally run once in the life of the ezjail
80environment. It allocates the directory structure used by ezjail and populates
81the base jail using the minimal distribution set from a FreeBSD FTP server.
82.Pp
83The default location for ezjail's basejail is in
84.Pa /usr/jails ,
85so be sure you have enough space there (a FreeBSD base release without man
86pages, sources and ports is around 120MB). This location may be modified in
87.Xr ezjail.conf 5 .
88.Pp
89See also
90.Nm
91.Cm update
92to install the base jail from source, as well as a method to update
93the base jail using
94.Xr freebsd-update 8 .
95.Pp
96The following options are available:
97.Bl -tag -width indent
98.It Fl m
99Fetch and install man pages (ca. 10MB).
100.It Fl M
101Fetch and install man pages, without (re)installing the base jail. May be used
102to add the man pages to the base jail after the intial installation.
103.It Fl s
104Fetch and install sources (ca. 450MB).
105.It Fl S
106Fetch and install sources, without (re)installing the base jail.
107.It Fl p
108Invoke the
109.Xr portsnap 8
110utility to fetch and extract a FreeBSD ports tree from
111.Li portsnap.FreeBSD.org
112(ca. 475MB). When a ports tree is added to the base jail, a modified
113.Pa make.conf
114containing reasonable values to function in the jailed environment is added to
115the new jail template so all jails created from the new jail template will
116have a working ports environment. See the appendix
117.%B Using Portsnap
118in the
119.%B FreeBSD Handbook
120for details or
121.Xr portsnap 8 .
122.It Fl P
123Fetch and extract a ports tree, without (re)installing the base jail.
124.It Fl h Ar host
125Set the remote host to fetch FreeBSD distribution sets from. If absent the
126default host
127.Li ftp.FreeBSD.org
128is used. Variable:
129.Dq Li $ezjail_ftphost .
130.Pp
131It is possible to install from the
132.Li disc1
133CDRom, or an extracted -RELEASE directory, by specifying the
134.Ar host
135argument as
136.Pa file://path/to/source .
137.It Fl r Ar release
138Install this release of FreeBSD in the base jail, instead of the version
139returned by
140.Dq Li uname -r
141on the host system. Note that the FreeBSD FTP servers usually provide only
142-RELEASE versions, not -STABLE nor -CURRENT versions; you will be prompted for
143confirmation when trying to install a non -RELEASE version. If you want to
144install a -CURRENT version, you may have to compile from source the base jail;
145see the
146.Nm Cm update
147sub-command for this.
148.El
149.Ss Nm Cm create
150Create a new jail inside ezjail's scope. It either copies the new jail
151directory tree template or an ezjail archive directory tree to
152.Pa /usr/jails/ Ns Ar jailname
153directory tree. Jailname and IP address are mandatory parameters.
154.Pp
155When a new jail is created, a corresponding new
156.Pa /etc/fstab. Ns Ar jailname
157file is also created, with a
158.Xr nullfs 5
159mount giving access to the base jail from the new jail.
160.Pp
161The following operands are mandatory:
162.Bl -tag -width indent
163.It Ar jailname
164The name of the jail. It is customary to use the network name of the jail,
165such as
166.Dq Li jail1.example.com
167(or maybe simply
168.Dq Li jail1 ) ,
169but really any name may be used.
170.Pp
171It is an error to have several jails of the same name.
172.It Ar ipaddress Ns Op Ar ,ipaddress2,...
173The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
174assign several several IPv4 or IPv6 addresses to a jail, by separating them
175with commas. Previous versions of FreeBSD allowed only a single IPv4 address
176per jail.
177.Pp
178The addresses of the jail are not configured on the host.
179.Nm
180will display a warning if the requested address is not found on any interface,
181and the jail will probably not start.
182.Pp
183XXX: is the following relevant, except maybe the warning about dynamic
184addresses?
185.Pp
186This is the static (premanent, never changes) public internet
187routable ip address assigned to you by your ISP. If you purchased a
188continous block of static public internet routable ip address, then each
189jail could be assigned one of those individual ip address from the block.
190.Pp
191Normally phone dialup PPP access and cable providers assign
192dynamic ip address. The assigned ip address may change every time you
193dialup and with cable providers when the lease time expires or you
194reboot your system. \fBUse dynamic ip address at your own risk.\fR
195.Pp
196On the host issue 'ifconfig -a' command to see your assigned ip address.
197Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is
198the 'unit name' of the NIC card facing the public internet. You will
199also need this same ifconfig_XXX="DHCP" statement in the rc.conf of
200each jail to enable the public network for that jail.
201.Pp
202If your host is acting as a 'gateway' (IE. has a LAN behind it), you
203can provide jails for LAN access only. In this configuration your host
204/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
205the 'unit name' of the NIC card facing the private LAN
206(local-area-network), where x.x.x.x is a private ip address from the
207list of reserved non-public routable ip address. You will also need
208this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
209jail to enable the lan network for that jail.
210.El
211.Pp
212The following options are available:
213.Bl -tag -width indent
214.It Fl r Ar jailroot
215Use this name as the directory name of the new jail. Without this option, it
216is derived from the jail's name. If this option is given and does not start
217with a '/', it is interpreted as relative to ezjail's root directory
218.Pa (/usr/jails
219by default). If a specified jailroot path lies outside the ezjail root
220directory, a soft link is created inside
221.Pa /usr/jails/
222pointing to the location of the newly created jail.
223.It Fl a Ar archive
224Restore a jail from an archive created with
225.Nm Cm archive .
226The archive files are kept in
227.Pa /usr/jails/archive
228by default. Use
229.Pa -
230to restore an archive from the standard input.
231.Pp
232You will probably need to tidy up things inside an ezjail if you migrate it
233between different ezjail environments. This may include (but is not limited
234to) reinstalling ports or packages for different CPUs or library versions. You
235may also need to copy some libraries from the source host's base jail.
236.Pp
237See also
238.Nm Cm restore ,
239if you only want to revert to an old jail's state from an archive on the same
240release version.
241.It Fl A Ar jailconf
242Copy the comments, in particular the
243.Dq Li PROVIDE ,
244.Dq Li REQUIRE
245and
246.Dq Li BEFORE
247lines, from this jail.
248.Pp
249XXX: This is my understanding from the code. Is that correct?
250.It Fl x
251This flag indicates that an jail of that name already exists. In this case,
252ezjail will only update the configuration of the jail. Sanity checks are
253performed.
254.It Fl f Ar flavour
255Install the requested
256.Ar flavour
257in the new jail.
258.Pp
259This option may not be used with the
260.Fl a
261option.
262.It Fl c Cm simple | bde | eli | zfs
263Create a jail of the given type.
264.Pp
265A
266.Cm simple
267jail is backed with a single file. The jail will not be allowed to grow beyond
268its allocated size. The base jail is included in the image, making it portable
269between hosts running the same (or sufficiently close) version of FreeBSD. The
270jail will be stored in a file named
271.Ar jailname Ns Pa .img ,
272unless
273.Fl r Ar jailroot
274is given, in which case the jail is stored in
275.Ar jailroot Ns Pa .img .
276.Pp
277A
278.Cm bde No or Cm eli
279jail is a
280.Cm simple
281jail whose file has been encrypted using
282.Xr gbde 4
283(for
284.Cm bde )
285or
286.Xr geli 8
287(for
288.Cm eli ) .
289See also the
290.Fl C
291flag when creating this kind of jail.
292.Pp
293A
294.Cm zfs
295jail is backed with a
296.Xr zfs 8
297volume, whose initial quota is given with the
298.Fl s
299option. The volume is compressed using the lzjb method. The volume is created
300in the
301.Cm ezjail_jailzfs
302data set, if set in
303.Xr ezjail.conf 5 .
304.Pp
305XXX: from the code, it looks like the user needs to have done
306ezjail-admin install with ezjail_use_zfs. Is that correct?
307.Pp
308In each case, the
309.Fl s
310flag is mandatory when creating such a jail. An empty directory (without the
311.Pa .img
312suffix in the case of file-based jails) will be created and used as a mount
313point when running the jail.
314.It Fl s Ar imagesize
315Allocate this size to the jail. Without an unit, the size is in bytes. The
316valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes,
317and g/G for gigabytes. As a reference point, a newly created jail requires
3182MB.
319.Pp
320It is not possible to increase the size of file-based jails after their
321creation, short of creating a new image jail with a larger size.
322.It Fl C Ar imageopt
323Pass this argument to
324.Li gbde No or Li geli init .
325.Fl P No and Fl K
326(and
327.Fl L
328for
329.Xr gbde 4 )
330will be translated and passed to
331.Li gbde No or Li geli attach
332when starting the jail.
333.It Fl i
334Synonym of
335.Fl c Cm simple .
336.It Fl b
337Don't start the jail at boot time.
338.El
339.Ss Nm Cm console
340Attach your console to the selected jail. You are logged in as root by
341default. The command line prompt shows the name of the jail. You have to
342use the pwd command to see where in the directory tree you are. Entering
343\fBexit\fR will terminate the jail console.
344.Pp
345The following options are available:
346.Bl -tag -width indent
347.It Fl f
348Start the jail if it is not running yet.
349.It Fl e Ar command
350Use
351.Ar command
352instead of
353.Dq /usr/bin/login -f root .
354A one time change to use a different user can be accomplished by using
355.Fl e Qq Li /usr/bin/login -f user .
356Variable:
357.Dq Li $ezjail_default_execute .
358.El
359.Ss Nm Cm list
360List all jails inside ezjail's scope. They are sorted by the order they start
361up, as defined by
362.Xr rcorder 1 .
363.Pp
364The first column is the status flag consisting of 2 or 3 letters. The first
365letter is the type of jail:
366.Bl -tag -width 4n -offset indent -compact
367.It Sy D
368Directory tree based jail.
369.It Sy I
370File-based jail.
371.It Sy E
372Geli encrypted file-based jail.
373.It Sy B
374Bde encrypted file-based jail.
375.It Sy Z
376ZFS filesystem-based jail.
377.El
378.Pp
379The second letter is the status of the jail:
380.Bl -tag -width 4n -offset indent -compact
381.It Sy R
382The jail is running.
383.It Sy A
384The image of the jail is mounted, but the jail is not running.
385.It Sy S
386The jail is stopped.
387.El
388.Pp
389If present, the third letter,
390.Sy N ,
391means that the jail is not automatically started.
392.Pp
393The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
394.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ...
395Execute the given action on
396.Ar jailname ,
397or on all jails if the operand is omitted. Several jails may be specified.
398.Pp
399As this is just a shortcut to the
400.Xr rc 8
401.Cm ezjail
402script, if ezjail is not enabled in
403.Xr rc.conf 5
404with
405.Dq Li ezjail_enable= Ns Qq Li YES ,
406nothing will be done. Prefix the action with
407.Cm one
408(as in
409.Cm onestart ,
410etc.) to force the action regardless of the value of
411.Dq Li $ezjail_enable .
412.Pp
413.Cm cryptostart
414is used to start jails that use
415.Xr gbde 4
416or
417.Xr geli 8
418encryption. Those jails require interaction with the administrator
419when starting.
420.Ss Nm Cm config Ar jailname
421Manage parameters of specific ezjails. For running jails, most of the
422configuration changes described below will not be applied until the next time
423the jail is restarted.
424.Pp
425The following options are available:
426.Bl -tag -width indent
427.It Fl r Cm run | norun
428Set the jail to be automatically started or not on boot.
429.It Fl n An newname
430Rename the jail. Unless a custom root directory was given with the
431.Fl r
432flag when creating the jail, the root directory will be renamed as well. A
433running jail may not be renamed.
434.It Fl i Cm attach | detach | fsck
435Only valid for stopped image jails. Attaching a jail means making the content
436of the root of the jail accessible from the host. No other sub-commands will
437function on an jail while its image is attached. With
438.Cm fsck ,
439the image jail is attached,
440.Xr fsck 8
441is run, then the image jail is detached. You can only fsck image based jails.
442.It Fl z Ar newdataset
443Set the given ZFS dataset to be mounted inside the jail file system
444when it is started.
445.It Fl f Ar newfib
446Change the FIB of the jail (see
447.Xr setfib 2 ) .
448.It Fl c Ar newcpuset
449Change the CPU affinity set of the jail (see
450.Xr cpuset 2 ) .
451.El
452.Ss Nm Cm delete Ar jailname
453Delete a jail. By default, this command only deletes ezjail's control file for
454the selected jail as well as
455.Pa /etc/fstab. Ns Ar jailname .
456The
457.Pa /usr/jails/ Ns Ar jailname
458directory is not deleted.
459.Pp
460.Bl -tag -width indent
461.It Fl f
462Stop the jail before deleting it.
463.It Fl w
464Delete the directory or the file backing the jail.
465.El
466.Ss Nm Cm archive
467Create a backup of one, multiple or all ezjails. The specified service
468jail's root directory tree is backed up as a
469.Xr pax 1
470file. The jail needs to be stopped.
471.Pp
472See
473.Nm Cm restore
474or
475.Nm Cm create Fl a Ar archive
476to restore an archive.
477.Pp
478The basejail can not be archived. There is no ezjail function to
479delete archive files; they may be removed from the host using
480.Xr rm 1 .
481.Bl -tag -width indent
482.It Fl a Ar archivename
483Use this name for the archive file. If absent, the archive file name
484is derived from the jail name, with the date and time of the archive
485appended to the file name.
486.It Fl d Ar directory
487Save the archive in this directory. If this option is not given and
488.Dq Li $ezjail_archivedir
489is not set, the archive is saved in the default directory.
490Variable:
491.Dq Li $ezjail_archivedir .
492.It Fl f
493Archive the jail even when it is running.
494.It Fl A
495Archive all jails.
496.It Ar jailname
497Archive only this jail. This argument is mandatory if
498.Fl a
499is not given.
500.El
501.Ss Nm Cm restore
502Create new ezjails from archived versions. It tries to collect all
503information necessary to do that without user interaction from the
504user.
505.Pp
506The following operand is mandatory:
507.Bl -tag -width indent
508.It Ar archive | jailname
509Restore this jail. If only the jail name is given,
510.Nm
511will use the most recent archive file matching the name you specified.
512To restore an older version, specify the complete archive file name
513(file name with the date and time of the archive appended to it).
514.El
515The following options are available:
516.Bl -tag -width indent
517.It Fl d Ar archivedir
518Search the archive file in this directory. If this option is not given and
519.Dq Li $ezjail_archivedir
520is not set, the archive is searched in the current directory. Variable:
521.Dq Li $ezjail_archivedir .
522.It Fl f
523Restore the archive even if running on a host different from
524where it was archived. Be default,
525.Nm
526will refuse to restore an archive if the hostname, the FreeBSD version
527or the CPU architecture is modified.
528.El
529.Ss Nm Cm update
530Creates or updates ezjail's basejail from source. This performs a
531.Dq make world ; make installworld
532using the basejail's RELEASE source located at
533.Pa /usr/src
534(but see the
535.Fl s
536option). Exactly one of
537.Fl b , i , u , P
538is mandatory.
539.Pp
540See the
541.Cm install
542command to install the basejail from binary packages.
543.Pp
544Exactly one of the following operand must be specified:
545.Bl -tag -width indent
546.It Fl b
547Build and install a world from source located in the basejail.
548.It Fl i
549Perform a
550.Qq make installworld ,
551assuming the world has already been built.
552.It Fl u
553Use
554.Xr freebsd-update 8
555to update the basejail. Note that as
556.Xr freebsd-update 8
557uses
558.Dq Li uname -r
559to determine the currently running system, the base jail and the host
560need to be updated at the same time, without rebooting on the new
561kernel in the meantime.
562.Pp
563Jails that are stored in a ZFS volume are snapshot first.
564.It Fl P
565Install only the ports tree, assuming the basejail has already been
566created.This can be done while jails are running. The
567.Xr portsnap 8
568utility is invoked to do the actual work.
569.El
570The following options are available:
571.Bl -tag -width indent
572.It Fl p
573Give the new basejail a copy of FreeBSD's ports tree. The
574.Xr portsnap 8
575utility is invoked to do the actual work.
576.It Fl s Ar sourcedir
577Use the sources in
578.Ar sourcedir
579instead of
580.Pa /usr/src .
581Variable:
582.Dq Li $ezjail_sourcetree .
583.El
584.Sh FILES
585.Pa EZJAIL_PREFIX/bin/ezjail-admin
586.br
587.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
588.br
589.Pa EZJAIL_PREFIX/etc/ezjail.conf
590.br
591.Pa EZJAIL_PREFIX/share/examples/ezjail/
592.br
593.Pa EZJAIL_PREFIX/etc/ezjail/*
594.br
595.Pa /usr/etc/fstab.*
596.Sh SEE ALSO
597.Xr ezjail 7 ,
598.Xr ezjail.conf 8 ,
599.Xr jail 8 ,
600.Xr devfs 5 ,
601.Xr fdescfs 5 ,
602.Xr procfs 5 ,
603.Xr portsnap 8 .
604.Sh AUTHOR
605.An Dirk Engling
606.Aq erdgeist@erdgeist.org .