summaryrefslogtreecommitdiff
path: root/man8/ezjail-admin.8
diff options
context:
space:
mode:
Diffstat (limited to 'man8/ezjail-admin.8')
-rw-r--r--man8/ezjail-admin.8277
1 files changed, 134 insertions, 143 deletions
diff --git a/man8/ezjail-admin.8 b/man8/ezjail-admin.8
index 78ae8df..be6fb33 100644
--- a/man8/ezjail-admin.8
+++ b/man8/ezjail-admin.8
@@ -72,8 +72,7 @@ The description of some options ends with
72.Sq Variable: Dq Li $ezjail_abcd . 72.Sq Variable: Dq Li $ezjail_abcd .
73This means that the default value of the option may be overridden by setting 73This means that the default value of the option may be overridden by setting
74this variable in 74this variable in
75.Xr ezjail.conf 5 , 75.Xr ezjail.conf 5 .
76which see.
77.Ss Nm Cm install 76.Ss Nm Cm install
78This function sub-command is normally run once in the life of the ezjail 77This function sub-command is normally run once in the life of the ezjail
79environment. It allocates the directory structure used by ezjail and populates 78environment. It allocates the directory structure used by ezjail and populates
@@ -98,7 +97,7 @@ The following options are available:
98Fetch and install man pages (ca. 10MB). 97Fetch and install man pages (ca. 10MB).
99.It Fl M 98.It Fl M
100Fetch and install man pages, without (re)installing the base jail. May be used 99Fetch and install man pages, without (re)installing the base jail. May be used
101to add the man pages to the base jail after the intial installation. 100to add the man pages to the base jail after the initial installation.
102.It Fl s 101.It Fl s
103Fetch and install sources (ca. 450MB). 102Fetch and install sources (ca. 450MB).
104.It Fl S 103.It Fl S
@@ -147,9 +146,10 @@ sub-command for this.
147.El 146.El
148.Ss Nm Cm create 147.Ss Nm Cm create
149Create a new jail inside ezjail's scope. It either copies the new jail 148Create a new jail inside ezjail's scope. It either copies the new jail
150directory tree template or an ezjail archive directory tree to 149directory tree template or an ezjail archive directory tree to new jail root
150directory,
151.Pa /usr/jails/ Ns Ar jailname 151.Pa /usr/jails/ Ns Ar jailname
152directory tree. Jailname and IP address are mandatory parameters. 152by default. Jailname and IP address are mandatory parameters.
153.Pp 153.Pp
154When a new jail is created, a corresponding new 154When a new jail is created, a corresponding new
155.Pa /etc/fstab. Ns Ar jailname 155.Pa /etc/fstab. Ns Ar jailname
@@ -167,7 +167,16 @@ such as
167.Dq Li jail1 ) , 167.Dq Li jail1 ) ,
168but really any name may be used. 168but really any name may be used.
169.Pp 169.Pp
170It is an error to have several jails of the same name. 170It is an error to have several jails of the same name, note that due to
171ezjail's internal jailname sanitation,
172.Dq Li sand-box.com
173and
174.Dq Li sand_box_com
175are considered identical. Some names such as
176.Dq Li basejail
177and
178.Dq Li flavours
179are reserved for ezjails internal administrative purposes.
171.It Ar ipaddress Ns Op Ar ,ipaddress2,... 180.It Ar ipaddress Ns Op Ar ,ipaddress2,...
172The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to 181The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
173assign several several IPv4 or IPv6 addresses to a jail, by separating them 182assign several several IPv4 or IPv6 addresses to a jail, by separating them
@@ -179,33 +188,8 @@ The addresses of the jail are not configured on the host.
179will display a warning if the requested address is not found on any interface, 188will display a warning if the requested address is not found on any interface,
180and the jail will probably not start. 189and the jail will probably not start.
181.Pp 190.Pp
182XXX: is the following relevant, except maybe the warning about dynamic 191It is common to bind jails to loopback addresses, so they provide services
183addresses? 192visible to other jails only.
184.Pp
185This is the static (premanent, never changes) public internet
186routable ip address assigned to you by your ISP. If you purchased a
187continous block of static public internet routable ip address, then each
188jail could be assigned one of those individual ip address from the block.
189.Pp
190Normally phone dialup PPP access and cable providers assign
191dynamic ip address. The assigned ip address may change every time you
192dialup and with cable providers when the lease time expires or you
193reboot your system. \fBUse dynamic ip address at your own risk.\fR
194.Pp
195On the host issue 'ifconfig -a' command to see your assigned ip address.
196Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is
197the 'unit name' of the NIC card facing the public internet. You will
198also need this same ifconfig_XXX="DHCP" statement in the rc.conf of
199each jail to enable the public network for that jail.
200.Pp
201If your host is acting as a 'gateway' (IE. has a LAN behind it), you
202can provide jails for LAN access only. In this configuration your host
203/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
204the 'unit name' of the NIC card facing the private LAN
205(local-area-network), where x.x.x.x is a private ip address from the
206list of reserved non-public routable ip address. You will also need
207this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
208jail to enable the lan network for that jail.
209.El 193.El
210.Pp 194.Pp
211The following options are available: 195The following options are available:
@@ -238,37 +222,38 @@ See also
238if you only want to revert to an old jail's state from an archive on the same 222if you only want to revert to an old jail's state from an archive on the same
239release version. 223release version.
240.It Fl x 224.It Fl x
241This flag indicates that an jail of that name already exists. In this case, 225This flag indicates that a jail root directory for that jail already exists.
242ezjail will only update the configuration of the jail. Sanity checks are 226In this case, ezjail will only import the jail to its control directory. Sanity
243performed. 227checks are performed.
244.It Fl f Ar flavour 228.It Fl f Ar flavour
245Install the requested 229Install the requested
246.Ar flavour 230.Ar flavour
247in the new jail. 231in the new jail. Refer to
232.Xr ezjail 7
233for more details on flavours.
248.Pp 234.Pp
249This option may not be used with the 235This option may not be used with the
250.Fl a 236.Fl a
251option. 237option.
252.It Fl c Cm simple | bde | eli | zfs 238.It Fl c Cm simple | bde | eli | zfs
253Create a jail of the given type. 239Create an image jail of the given type.
254.Pp 240.Pp
255A 241.Cm simple, No Cm bde No and Cm eli
256.Cm simple 242image jails are file backed memory discs attached as
257jail is backed with a single file. The jail will not be allowed to grow beyond 243.Xr md 4
258its allocated size. The base jail is included in the image, making it portable 244devices, so the jail can never grow beyond its allocated size and can
259between hosts running the same (or sufficiently close) version of FreeBSD. The 245even be mounted read only. The jail will be stored in a file named
260jail will be stored in a file named
261.Ar jailname Ns Pa .img , 246.Ar jailname Ns Pa .img ,
262unless 247unless
263.Fl r Ar jailroot 248.Fl r Ar jailroot
264is given, in which case the jail is stored in 249is given, in which case the jail is stored in
265.Ar jailroot Ns Pa .img . 250.Ar jailroot Ns Pa .img .
266.Pp 251.Pp
267A 252Both
268.Cm bde No or Cm eli 253.Cm bde No and Cm eli
269jail is a 254jails use the
270.Cm simple 255.Xr geom 4
271jail whose file has been encrypted using 256framework to encrypt all data written to the image file using
272.Xr gbde 4 257.Xr gbde 4
273(for 258(for
274.Cm bde ) 259.Cm bde )
@@ -276,24 +261,27 @@ or
276.Xr geli 8 261.Xr geli 8
277(for 262(for
278.Cm eli ) . 263.Cm eli ) .
279See also the 264.Pp
265Unless you pass some options to the encryption geom commands using the
280.Fl C 266.Fl C
281flag when creating this kind of jail. 267parameter, you will be prompted for a passphrase to protect the crypto
268image. Note that, since starting normal encrypted image jails requires user
269interaction to enter the passphrase, they will
270.Cm NOT automatically be started at boot time. No Use
271.Cm ezjail-admin startcrypto No to manually start all crypto image jails.
282.Pp 272.Pp
283A 273A
284.Cm zfs 274.Cm zfs
285jail is backed with a 275jail is backed with a
286.Xr zfs 8 276.Xr zfs 8
287volume, whose initial quota is given with the 277filesystem, whose initial quota is given with the
288.Fl s 278.Fl s
289option. The volume is compressed using the lzjb method. The volume is created 279option. The filesystem is created in the
290in the 280.Dq Li $ezjail_jailzfs
291.Cm ezjail_jailzfs 281zpool and by default compressed using the lzjb method, as set in the
292data set, if set in 282.Dq Li ezjail_zfs_jail_properies
293.Xr ezjail.conf 5 . 283variable, both values configured in
294.Pp 284.Xr ezjail.conf 5
295XXX: from the code, it looks like the user needs to have done
296ezjail-admin install with ezjail_use_zfs. Is that correct?
297.Pp 285.Pp
298In each case, the 286In each case, the
299.Fl s 287.Fl s
@@ -303,34 +291,38 @@ suffix in the case of file-based jails) will be created and used as a mount
303point when running the jail. 291point when running the jail.
304.It Fl s Ar imagesize 292.It Fl s Ar imagesize
305Allocate this size to the jail. Without an unit, the size is in bytes. The 293Allocate this size to the jail. Without an unit, the size is in bytes. The
306valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes, 294valid suffix values are b/B for blocks (i. e. 512 bytes), k/K for kilobytes,
307and g/G for gigabytes. As a reference point, a newly created jail requires 295m/M for megabytes, and g/G for gigabytes. As a reference point, a newly
3082MB. 296created jail requires 2 MB.
309.Pp 297.Pp
310It is not possible to increase the size of file-based jails after their 298It is not possible to increase the size of file-based jails after their
311creation, short of creating a new image jail with a larger size. 299creation, short of creating a new image jail with a larger size.
312.It Fl C Ar imageopt 300.It Fl C Ar imageopt
313Pass this argument to 301Pass this argument to
314.Li gbde No or Li geli init . 302.Xr gbde 8
303or
304.Xr geli 8
305when initialising crypto image jails. The
315.Fl P No and Fl K 306.Fl P No and Fl K
316(and 307(and
317.Fl L 308.Fl L
318for 309for
319.Xr gbde 4 ) 310.Xr gbde 4 )
320will be translated and passed to 311options will be translated and passed to the respective attach command when
321.Li gbde No or Li geli attach 312starting the jail. You will have to escape parameters with single ticks to
322when starting the jail. 313protect them from shell expansion.
323.It Fl i 314.It Fl i
324Synonym of 315Synonym of
325.Fl c Cm simple . 316.Fl c Cm simple .
326.It Fl b 317.It Fl b
327Don't start the jail at boot time. 318Tell ezjail that starting this jail would block unattended reboots. This may
319happen when certain services need private SSL keys that require the user to
320interactively enter a passphrase. The jail is then not automatically started
321at boot time.
328.El 322.El
329.Ss Nm Cm console 323.Ss Nm Cm console
330Attach your console to the selected jail. You are logged in as root by 324Attach your console to the selected jail. You are logged in as root by
331default. The command line prompt shows the name of the jail. You have to 325default.
332use the pwd command to see where in the directory tree you are. Entering
333\fBexit\fR will terminate the jail console.
334.Pp 326.Pp
335The following options are available: 327The following options are available:
336.Bl -tag -width indent 328.Bl -tag -width indent
@@ -339,9 +331,10 @@ Start the jail if it is not running yet.
339.It Fl e Ar command 331.It Fl e Ar command
340Use 332Use
341.Ar command 333.Ar command
342instead of 334instead of the default
343.Dq /usr/bin/login -f root . 335.Dq /usr/bin/login -f root .
344A one time change to use a different user can be accomplished by using 336loogin command. A one time change to use a different user can be
337accomplished by using
345.Fl e Qq Li /usr/bin/login -f user . 338.Fl e Qq Li /usr/bin/login -f user .
346Variable: 339Variable:
347.Dq Li $ezjail_default_execute . 340.Dq Li $ezjail_default_execute .
@@ -381,32 +374,26 @@ If present, the third letter,
381means that the jail is not automatically started. 374means that the jail is not automatically started.
382.Pp 375.Pp
383The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail. 376The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
384.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ... 377.Ss Nm Cm start | restart | stop | startcrypto Op Ar jailname ...
385Execute the given action on
386.Ar jailname ,
387or on all jails if the operand is omitted. Several jails may be specified.
388.Pp 378.Pp
389As this is just a shortcut to the 379This is a shortcut to the
390.Xr rc 8 380.Xr rc 8
391.Cm ezjail 381.Cm ezjail.sh
392script, if ezjail is not enabled in 382script. Refer to
383.Xr ezjail 7
384section
385.Pa Starting jails
386for details.
387.Pp
388Note that, if ezjail is not enabled in
393.Xr rc.conf 5 389.Xr rc.conf 5
394with 390with
395.Dq Li ezjail_enable= Ns Qq Li YES , 391.Dq Li ezjail_enable= Ns Qq Li YES ,
396nothing will be done. Prefix the action with 392nothing happens.
397.Cm one 393.Pp
398(as in 394Since starting crypto image jails requires interaction with the administrator, they are not run at
399.Cm onestart , 395boot time. Use
400etc.) to force the action regardless of the value of 396.Cm startcrypto No to run them all at once.
401.Dq Li $ezjail_enable .
402.Pp
403.Cm cryptostart
404is used to start jails that use
405.Xr gbde 4
406or
407.Xr geli 8
408encryption. Those jails require interaction with the administrator
409when starting.
410.Ss Nm Cm config Ar jailname 397.Ss Nm Cm config Ar jailname
411Manage parameters of specific ezjails. For running jails, most of the 398Manage parameters of specific ezjails. For running jails, most of the
412configuration changes described below will not be applied until the next time 399configuration changes described below will not be applied until the next time
@@ -416,7 +403,7 @@ The following options are available:
416.Bl -tag -width indent 403.Bl -tag -width indent
417.It Fl r Cm run | norun 404.It Fl r Cm run | norun
418Set the jail to be automatically started or not on boot. 405Set the jail to be automatically started or not on boot.
419.It Fl n An newname 406.It Fl n Ar newname
420Rename the jail. Unless a custom root directory was given with the 407Rename the jail. Unless a custom root directory was given with the
421.Fl r 408.Fl r
422flag when creating the jail, the root directory will be renamed as well. A 409flag when creating the jail, the root directory will be renamed as well. A
@@ -453,26 +440,21 @@ Stop the jail before deleting it.
453.It Fl w 440.It Fl w
454Delete the directory or the file backing the jail. 441Delete the directory or the file backing the jail.
455.El 442.El
456.Ss Nm Cm archive 443.Ss Nm Cm archive Op jailname
457Create a backup of one, multiple or all ezjails. The specified service 444Create a backup of one or all jails. The jail's root directory tree is backed
458jail's root directory tree is backed up as a 445up as a
459.Xr pax 1 446.Xr pax 1
460file. The jail needs to be stopped. 447archive. By default, the jail needs to be stopped.
461.Pp
462See
463.Nm Cm restore
464or
465.Nm Cm create Fl a Ar archive
466to restore an archive.
467.Pp
468The basejail can not be archived. There is no ezjail function to
469delete archive files; they may be removed from the host using
470.Xr rm 1 .
471.Bl -tag -width indent 448.Bl -tag -width indent
449.It Fl A
450Archive all jails. You must neither specify an archivename nor a jailname in
451this case.
472.It Fl a Ar archivename 452.It Fl a Ar archivename
473Use this name for the archive file. If absent, the archive file name 453Use this name for the archive file. If absent, the archive file name is
474is derived from the jail name, with the date and time of the archive 454derived from the jail name, with the current date and time appended to the
475appended to the file name. 455archive's file name. Use
456.Pa -
457to write to stdout.
476.It Fl d Ar directory 458.It Fl d Ar directory
477Save the archive in this directory. If this option is not given and 459Save the archive in this directory. If this option is not given and
478.Dq Li $ezjail_archivedir 460.Dq Li $ezjail_archivedir
@@ -481,13 +463,13 @@ Variable:
481.Dq Li $ezjail_archivedir . 463.Dq Li $ezjail_archivedir .
482.It Fl f 464.It Fl f
483Archive the jail even when it is running. 465Archive the jail even when it is running.
484.It Fl A
485Archive all jails.
486.It Ar jailname
487Archive only this jail. This argument is mandatory if
488.Fl a
489is not given.
490.El 466.El
467.Pp
468Use
469.Nm Cm restore
470or
471.Nm Cm create Fl a Ar archive
472to restore an archive.
491.Ss Nm Cm restore 473.Ss Nm Cm restore
492Create new ezjails from archived versions. It tries to collect all 474Create new ezjails from archived versions. It tries to collect all
493information necessary to do that without user interaction from the 475information necessary to do that without user interaction from the
@@ -502,43 +484,46 @@ will use the most recent archive file matching the name you specified.
502To restore an older version, specify the complete archive file name 484To restore an older version, specify the complete archive file name
503(file name with the date and time of the archive appended to it). 485(file name with the date and time of the archive appended to it).
504.El 486.El
487.Pp
505The following options are available: 488The following options are available:
506.Bl -tag -width indent 489.Bl -tag -width indent
507.It Fl d Ar archivedir 490.It Fl d Ar archivedir
508Search the archive file in this directory. If this option is not given and 491Search the archive file in this directory. If this option is not given, the
509.Dq Li $ezjail_archivedir 492archive is searched in
510is not set, the archive is searched in the current directory. Variable:
511.Dq Li $ezjail_archivedir . 493.Dq Li $ezjail_archivedir .
512.It Fl f 494.It Fl f
513Restore the archive even if running on a host different from 495Restore the archive even if running on a host different from
514where it was archived. Be default, 496where it was archived. Be default,
515.Nm 497.Nm
516will refuse to restore an archive if the hostname, the FreeBSD version 498will refuse to restore an archive if the archived host system's hostname,
517or the CPU architecture is modified. 499its FreeBSD version or CPU architecture do not match the current host.
518.El 500.El
519.Ss Nm Cm update 501.Ss Nm Cm update
520Creates or updates ezjail's basejail from source. This performs a 502Updates ezjail's basejail, or in the
521.Dq make world ; make installworld 503.Fl b
522using the basejail's RELEASE source located at 504or
523.Pa /usr/src 505.Fl i
524(but see the 506case, install a FreeBSD world from source to be used as basejail.
525.Fl s
526option). Exactly one of
527.Fl b , i , u , P
528is mandatory.
529.Pp
530See the
531.Cm install
532command to install the basejail from binary packages.
533.Pp 507.Pp
534Exactly one of the following operand must be specified: 508Exactly one of the following operand must be specified:
535.Bl -tag -width indent 509.Bl -tag -width indent
536.It Fl b 510.It Fl b
537Build and install a world from source located in the basejail. 511Build a world from source and install it as the (updated) basejail.
512.Dq make buildworld ; make installworld
513by default using the sources located at
514.Pa /usr/src
515(but see the
516.Fl s
517option).
518.Pp
519As the old basejail is not deleted, but merely overwritten, this usually
520leaves all jails in a state where they still find older versions of libraries
521they were linked against.
538.It Fl i 522.It Fl i
539Perform a 523As above but only perform a
540.Qq make installworld , 524.Dq make installworld ,
541assuming the world has already been built. 525assuming the world has already been built. That is highly likely since it is
526recommended to update the basejail along with the host system.
542.It Fl u 527.It Fl u
543Use 528Use
544.Xr freebsd-update 8 529.Xr freebsd-update 8
@@ -549,14 +534,13 @@ uses
549to determine the currently running system, the base jail and the host 534to determine the currently running system, the base jail and the host
550need to be updated at the same time, without rebooting on the new 535need to be updated at the same time, without rebooting on the new
551kernel in the meantime. 536kernel in the meantime.
552.Pp
553Jails that are stored in a ZFS volume are snapshot first.
554.It Fl P 537.It Fl P
555Install only the ports tree, assuming the basejail has already been 538Install only the ports tree, assuming the basejail has already been
556created.This can be done while jails are running. The 539created. This can be done while jails are running. The
557.Xr portsnap 8 540.Xr portsnap 8
558utility is invoked to do the actual work. 541utility is invoked to do the actual work.
559.El 542.El
543.Pp
560The following options are available: 544The following options are available:
561.Bl -tag -width indent 545.Bl -tag -width indent
562.It Fl p 546.It Fl p
@@ -571,6 +555,13 @@ instead of
571Variable: 555Variable:
572.Dq Li $ezjail_sourcetree . 556.Dq Li $ezjail_sourcetree .
573.El 557.El
558.Pp
559See the
560.Cm install
561sub command to install the basejail from binary packages.
562.Pp
563If the basejail is managed in its own ZFS filesystem, a snapshot of that
564filesystem is taken first.
574.Sh FILES 565.Sh FILES
575.Pa EZJAIL_PREFIX/bin/ezjail-admin 566.Pa EZJAIL_PREFIX/bin/ezjail-admin
576.br 567.br