ruben/ezjail
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Several clarifications added to man pages

Browse Source
This commit is contained in:
erdgeist 2011-01-25 20:16:15 +00:00
parent 8172a352e7
commit 30547451e1
2 changed files with 166 additions and 171 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
man7/ezjail.7
View File

@ -352,46 +352,50 @@ librairies, you may want to remove the old library versions. It is
often a good idea to update the jails when a new kernel is installed
in the host, using the same sources.
.Ss Starting Jails
The ezjail script
Like all
.Xr rc 8
scripts, the ezjail script
.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
takes parameters
.Cm start , startcrypto , restart
and
.Cm stop .
It may be passed an additional list of jails. If no jail name is
specified (usually when the script is called by the rc system at boot
and shutdown time), all jails in ezjail's scope, except crypto image
jails (or jails marked as blocking), are started/stopped. To start all
crypto image jails (or those depending on them), use the
.Cm startcrypto
parameter.
accepts parameters
.Cm start , restart No and Cm stop, No running, restarting and stopping
all (non-blocking) jails under ezjail's control by default. When passed an
additional list of jails, only these jails are acted upon.
.Pp
The
.Nm Cm start
command provides the same functionnality.
The order in which jails are started is determined by the
.Xr rcorder 8
tool, using cues from the jail configurations in ezjails
.Pa EZJAIL_PREFIX/etc/ezjail
control directory.
.Pp
The script examines its config, attaches and mounts images, and sets
variables for each jail in the jail_list before passing its command on
variables for each jail in the list before passing its command on
to the
.Pa /etc/rc.d/jail
script.
.Pp
.Cm ezjail.sh
enforces the execution of \fB/etc/rc.d/jail\fR, by prepending
.Em one
to the start, restart, and stop commands so it is
.Em NOT NECESSARY
to set
.Dq Li $jail_enable
in the
.Xr /etc/rc.conf 5
config file.
To interactively start all crypto image jails (or those depending on
them), that were not automatically started during booting, use the
.Cm startcrypto
parameter.
.Pp
It is possible to set jails as either
Note that jails configured to be in the
.Em norun
(using
state (using
.Nm Cm config Fl r Ar norun Ar jailname )
or as blocking
are never started by the ezjail.sh script.
.Pp
As a convenient shortcut, the
.Nm Cm
command invokes the rc.d script and passes the corresponding parameters,
if they look like valid parameters.
.Pp
Even if ezjail is not enabled in the
.Xr rc.conf 5 ,
ezjail.sh can be used to start and stop jails by prepending
.Cm force No or Cm one No to the Cm start, restart No or Cm stop No parameter.
Refer to
.Xr rc 8
for details.
.Ss Remarks & Tips
Jails can be either accessed from the network, for instance by using
.Xr ssh 1 ,

275
man8/ezjail-admin.8
View File

@ -72,8 +72,7 @@ The description of some options ends with
.Sq Variable: Dq Li $ezjail_abcd .
This means that the default value of the option may be overridden by setting
this variable in
.Xr ezjail.conf 5 ,
which see.
.Xr ezjail.conf 5 .
.Ss Nm Cm install
This function sub-command is normally run once in the life of the ezjail
environment. It allocates the directory structure used by ezjail and populates
@ -98,7 +97,7 @@ The following options are available:
Fetch and install man pages (ca. 10MB).
.It Fl M
Fetch and install man pages, without (re)installing the base jail. May be used
to add the man pages to the base jail after the intial installation.
to add the man pages to the base jail after the initial installation.
.It Fl s
Fetch and install sources (ca. 450MB).
.It Fl S
@ -147,9 +146,10 @@ sub-command for this.
.El
.Ss Nm Cm create
Create a new jail inside ezjail's scope. It either copies the new jail
directory tree template or an ezjail archive directory tree to
directory tree template or an ezjail archive directory tree to new jail root
directory,
.Pa /usr/jails/ Ns Ar jailname
directory tree. Jailname and IP address are mandatory parameters.
by default. Jailname and IP address are mandatory parameters.
.Pp
When a new jail is created, a corresponding new
.Pa /etc/fstab. Ns Ar jailname
@ -167,7 +167,16 @@ such as
.Dq Li jail1 ) ,
but really any name may be used.
.Pp
It is an error to have several jails of the same name.
It is an error to have several jails of the same name, note that due to
ezjail's internal jailname sanitation,
.Dq Li sand-box.com
and
.Dq Li sand_box_com
are considered identical. Some names such as
.Dq Li basejail
and
.Dq Li flavours
are reserved for ezjails internal administrative purposes.
.It Ar ipaddress Ns Op Ar ,ipaddress2,...
The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
assign 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.
will display a warning if the requested address is not found on any interface,
and the jail will probably not start.
.Pp
XXX: is the following relevant, except maybe the warning about dynamic
addresses?
.Pp
This is the static (premanent, never changes) public internet
routable ip address assigned to you by your ISP. If you purchased a
continous block of static public internet routable ip address, then each
jail could be assigned one of those individual ip address from the block.
.Pp
Normally phone dialup PPP access and cable providers assign
dynamic ip address. The assigned ip address may change every time you
dialup and with cable providers when the lease time expires or you
reboot your system. \fBUse dynamic ip address at your own risk.\fR
.Pp
On the host issue 'ifconfig -a' command to see your assigned ip address.
Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is
the 'unit name' of the NIC card facing the public internet. You will
also need this same ifconfig_XXX="DHCP" statement in the rc.conf of
each jail to enable the public network for that jail.
.Pp
If your host is acting as a 'gateway' (IE. has a LAN behind it), you
can provide jails for LAN access only. In this configuration your host
/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
the 'unit name' of the NIC card facing the private LAN
(local-area-network), where x.x.x.x is a private ip address from the
list of reserved non-public routable ip address. You will also need
this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
jail to enable the lan network for that jail.
It is common to bind jails to loopback addresses, so they provide services
visible to other jails only.
.El
.Pp
The following options are available:
@ -238,37 +222,38 @@ See also
if you only want to revert to an old jail's state from an archive on the same
release version.
.It Fl x
This flag indicates that an jail of that name already exists. In this case,
ezjail will only update the configuration of the jail. Sanity checks are
performed.
This flag indicates that a jail root directory for that jail already exists.
In this case, ezjail will only import the jail to its control directory. Sanity
checks are performed.
.It Fl f Ar flavour
Install the requested
.Ar flavour
in the new jail.
in the new jail. Refer to
.Xr ezjail 7
for more details on flavours.
.Pp
This option may not be used with the
.Fl a
option.
.It Fl c Cm simple | bde | eli | zfs
Create a jail of the given type.
Create an image jail of the given type.
.Pp
A
.Cm simple
jail is backed with a single file. The jail will not be allowed to grow beyond
its allocated size. The base jail is included in the image, making it portable
between hosts running the same (or sufficiently close) version of FreeBSD. The
jail will be stored in a file named
.Cm simple, No Cm bde No and Cm eli
image jails are file backed memory discs attached as
.Xr md 4
devices, so the jail can never grow beyond its allocated size and can
even be mounted read only. The jail will be stored in a file named
.Ar jailname Ns Pa .img ,
unless
.Fl r Ar jailroot
is given, in which case the jail is stored in
.Ar jailroot Ns Pa .img .
.Pp
A
.Cm bde No or Cm eli
jail is a
.Cm simple
jail whose file has been encrypted using
Both
.Cm bde No and Cm eli
jails use the
.Xr geom 4
framework to encrypt all data written to the image file using
.Xr gbde 4
(for
.Cm bde )
@ -276,24 +261,27 @@ or
.Xr geli 8
(for
.Cm eli ) .
See also the
.Pp
Unless you pass some options to the encryption geom commands using the
.Fl C
flag when creating this kind of jail.
parameter, you will be prompted for a passphrase to protect the crypto
image. Note that, since starting normal encrypted image jails requires user
interaction to enter the passphrase, they will
.Cm NOT automatically be started at boot time. No Use
.Cm ezjail-admin startcrypto No to manually start all crypto image jails.
.Pp
A
.Cm zfs
jail is backed with a
.Xr zfs 8
volume, whose initial quota is given with the
filesystem, whose initial quota is given with the
.Fl s
option. The volume is compressed using the lzjb method. The volume is created
in the
.Cm ezjail_jailzfs
data set, if set in
.Xr ezjail.conf 5 .
.Pp
XXX: from the code, it looks like the user needs to have done
ezjail-admin install with ezjail_use_zfs. Is that correct?
option. The filesystem is created in the
.Dq Li $ezjail_jailzfs
zpool and by default compressed using the lzjb method, as set in the
.Dq Li ezjail_zfs_jail_properies
variable, both values configured in
.Xr ezjail.conf 5
.Pp
In each case, the
.Fl s
@ -303,34 +291,38 @@ suffix in the case of file-based jails) will be created and used as a mount
point when running the jail.
.It Fl s Ar imagesize
Allocate this size to the jail. Without an unit, the size is in bytes. The
valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes,
and g/G for gigabytes. As a reference point, a newly created jail requires
2MB.
valid suffix values are b/B for blocks (i. e. 512 bytes), k/K for kilobytes,
m/M for megabytes, and g/G for gigabytes. As a reference point, a newly
created jail requires 2 MB.
.Pp
It is not possible to increase the size of file-based jails after their
creation, short of creating a new image jail with a larger size.
.It Fl C Ar imageopt
Pass this argument to
.Li gbde No or Li geli init .
.Xr gbde 8
or
.Xr geli 8
when initialising crypto image jails. The
.Fl P No and Fl K
(and
.Fl L
for
.Xr gbde 4 )
will be translated and passed to
.Li gbde No or Li geli attach
when starting the jail.
options will be translated and passed to the respective attach command when
starting the jail. You will have to escape parameters with single ticks to
protect them from shell expansion.
.It Fl i
Synonym of
.Fl c Cm simple .
.It Fl b
Don't start the jail at boot time.
Tell ezjail that starting this jail would block unattended reboots. This may
happen when certain services need private SSL keys that require the user to
interactively enter a passphrase. The jail is then not automatically started
at boot time.
.El
.Ss Nm Cm console
Attach your console to the selected jail. You are logged in as root by
default. The command line prompt shows the name of the jail. You have to
use the pwd command to see where in the directory tree you are. Entering
\fBexit\fR will terminate the jail console.
default.
.Pp
The following options are available:
.Bl -tag -width indent
@ -339,9 +331,10 @@ Start the jail if it is not running yet.
.It Fl e Ar command
Use
.Ar command
instead of
instead of the default
.Dq /usr/bin/login -f root .
A one time change to use a different user can be accomplished by using
loogin command. A one time change to use a different user can be
accomplished by using
.Fl e Qq Li /usr/bin/login -f user .
Variable:
.Dq Li $ezjail_default_execute .
@ -381,32 +374,26 @@ If present, the third letter,
means that the jail is not automatically started.
.Pp
The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ...
Execute the given action on
.Ar jailname ,
or on all jails if the operand is omitted. Several jails may be specified.
.Ss Nm Cm start | restart | stop | startcrypto Op Ar jailname ...
.Pp
As this is just a shortcut to the
This is a shortcut to the
.Xr rc 8
.Cm ezjail
script, if ezjail is not enabled in
.Cm ezjail.sh
script. Refer to
.Xr ezjail 7
section
.Pa Starting jails
for details.
.Pp
Note that, if ezjail is not enabled in
.Xr rc.conf 5
with
.Dq Li ezjail_enable= Ns Qq Li YES ,
nothing will be done. Prefix the action with
.Cm one
(as in
.Cm onestart ,
etc.) to force the action regardless of the value of
.Dq Li $ezjail_enable .
nothing happens.
.Pp
.Cm cryptostart
is used to start jails that use
.Xr gbde 4
or
.Xr geli 8
encryption. Those jails require interaction with the administrator
when starting.
Since starting crypto image jails requires interaction with the administrator, they are not run at
boot time. Use
.Cm startcrypto No to run them all at once.
.Ss Nm Cm config Ar jailname
Manage parameters of specific ezjails. For running jails, most of the
configuration changes described below will not be applied until the next time
@ -416,7 +403,7 @@ The following options are available:
.Bl -tag -width indent
.It Fl r Cm run | norun
Set the jail to be automatically started or not on boot.
.It Fl n An newname
.It Fl n Ar newname
Rename the jail. Unless a custom root directory was given with the
.Fl r
flag when creating the jail, the root directory will be renamed as well. A
@ -453,26 +440,21 @@ Stop the jail before deleting it.
.It Fl w
Delete the directory or the file backing the jail.
.El
.Ss Nm Cm archive
Create a backup of one, multiple or all ezjails. The specified service
jail's root directory tree is backed up as a
.Ss Nm Cm archive Op jailname
Create a backup of one or all jails. The jail's root directory tree is backed
up as a
.Xr pax 1
file. The jail needs to be stopped.
.Pp
See
.Nm Cm restore
or
.Nm Cm create Fl a Ar archive
to restore an archive.
.Pp
The basejail can not be archived. There is no ezjail function to
delete archive files; they may be removed from the host using
.Xr rm 1 .
archive. By default, the jail needs to be stopped.
.Bl -tag -width indent
.It Fl A
Archive all jails. You must neither specify an archivename nor a jailname in
this case.
.It Fl a Ar archivename
Use this name for the archive file. If absent, the archive file name
is derived from the jail name, with the date and time of the archive
appended to the file name.
Use this name for the archive file. If absent, the archive file name is
derived from the jail name, with the current date and time appended to the
archive's file name. Use
.Pa -
to write to stdout.
.It Fl d Ar directory
Save the archive in this directory. If this option is not given and
.Dq Li $ezjail_archivedir
@ -481,13 +463,13 @@ Variable:
.Dq Li $ezjail_archivedir .
.It Fl f
Archive the jail even when it is running.
.It Fl A
Archive all jails.
.It Ar jailname
Archive only this jail. This argument is mandatory if
.Fl a
is not given.
.El
.Pp
Use
.Nm Cm restore
or
.Nm Cm create Fl a Ar archive
to restore an archive.
.Ss Nm Cm restore
Create new ezjails from archived versions. It tries to collect all
information 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.
To restore an older version, specify the complete archive file name
(file name with the date and time of the archive appended to it).
.El
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d Ar archivedir
Search the archive file in this directory. If this option is not given and
.Dq Li $ezjail_archivedir
is not set, the archive is searched in the current directory. Variable:
Search the archive file in this directory. If this option is not given, the
archive is searched in
.Dq Li $ezjail_archivedir .
.It Fl f
Restore the archive even if running on a host different from
where it was archived. Be default,
.Nm
will refuse to restore an archive if the hostname, the FreeBSD version
or the CPU architecture is modified.
will refuse to restore an archive if the archived host system's hostname,
its FreeBSD version or CPU architecture do not match the current host.
.El
.Ss Nm Cm update
Creates or updates ezjail's basejail from source. This performs a
.Dq make world ; make installworld
using the basejail's RELEASE source located at
.Pa /usr/src
(but see the
.Fl s
option). Exactly one of
.Fl b , i , u , P
is mandatory.
.Pp
See the
.Cm install
command to install the basejail from binary packages.
Updates ezjail's basejail, or in the
.Fl b
or
.Fl i
case, install a FreeBSD world from source to be used as basejail.
.Pp
Exactly one of the following operand must be specified:
.Bl -tag -width indent
.It Fl b
Build and install a world from source located in the basejail.
Build a world from source and install it as the (updated) basejail.
.Dq make buildworld ; make installworld
by default using the sources located at
.Pa /usr/src
(but see the
.Fl s
option).
.Pp
As the old basejail is not deleted, but merely overwritten, this usually
leaves all jails in a state where they still find older versions of libraries
they were linked against.
.It Fl i
Perform a
.Qq make installworld ,
assuming the world has already been built.
As above but only perform a
.Dq make installworld ,
assuming the world has already been built. That is highly likely since it is
recommended to update the basejail along with the host system.
.It Fl u
Use
.Xr freebsd-update 8
@ -549,14 +534,13 @@ uses
to determine the currently running system, the base jail and the host
need to be updated at the same time, without rebooting on the new
kernel in the meantime.
.Pp
Jails that are stored in a ZFS volume are snapshot first.
.It Fl P
Install only the ports tree, assuming the basejail has already been
created.This can be done while jails are running. The
created. This can be done while jails are running. The
.Xr portsnap 8
utility is invoked to do the actual work.
.El
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl p
@ -571,6 +555,13 @@ instead of
Variable:
.Dq Li $ezjail_sourcetree .
.El
.Pp
See the
.Cm install
sub command to install the basejail from binary packages.
.Pp
If the basejail is managed in its own ZFS filesystem, a snapshot of that
filesystem is taken first.
.Sh FILES
.Pa EZJAIL_PREFIX/bin/ezjail-admin
.br