From 712cdc830d1456cec055ffd9a96540c047c96225 Mon Sep 17 00:00:00 2001 From: erdgeist Date: Thu, 20 Jan 2011 21:03:50 +0000 Subject: New man pages, also put in new sections --- man1/ezjail-admin.1 | 268 ---------------------------------------------------- 1 file changed, 268 deletions(-) delete mode 100755 man1/ezjail-admin.1 (limited to 'man1/ezjail-admin.1') diff --git a/man1/ezjail-admin.1 b/man1/ezjail-admin.1 deleted file mode 100755 index 18cea26..0000000 --- a/man1/ezjail-admin.1 +++ /dev/null @@ -1,268 +0,0 @@ -.TH ezjail\-admin 1 -.SH NAME -ezjail-admin \- Administrate ezjail -.SH SYNOPSIS -.T -.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release] - -.T -.B ezjail-admin create -[-f flavours] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip - -.T -.B ezjail-admin console\fR [-f] [-e command]\fI jailname - -.T -.B ezjail-admin list - -.T -.B ezjail-admin config\fR [-r run|norun] [-n newname] [-c cpu-list] [-z zfs-dataset] [-f fib-number] [-i attach|detach|fsck]\fI jailname - -.T -.B ezjail-admin delete \fR[-w] \fI hostname - -.T -.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...] - -.T -.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)... - -.T -.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP] - -.SH DESCRIPTION -The \fBezjail-admin\fR tool is used to manage the ezjail environment -and jails inside the ezjail scope. - -It can also be used to start or stop and to get a console in ezjail's -jails by proxying everything looking like -\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script. -.SH ezjail-admin install -fetches everything needed to setup an ezjail environment from an FTP server and -installs it. - -The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you -have enough space there (a FreeBSD base without man pages, sources and ports -is around 120MB). - -The -m and -s option will fetch and install man pages (ca. 10MB) and -sources packages (ca. 450MB) respectively. The -p option invokes the -portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB). -Options -M, -P or -S behave like their lower case pendants, but they -disable (re)installing your basejail. - -The default OS version is whatever uname -r returns. If this does not match -"*-RELEASE", you will be prompted for a better guess. (Normally -ftp-servers do not provide release candidates or CURRENT builds). You can -use the -r option to specify a release on the command line. - -The default host to fetch packages from is ftp.freebsd.org; you may want to -change this via the -h option or in ezjail.conf(5). - -If the specified location begins with file://, your local copy of the -release is used. That way you can modify the install.sh scripts before -executing them. - -You can later update your world from CVS or update ports with \fIezjail-admin -update\fR or rerun this subcommand with another OS version. -.SH ezjail-admin create -installs a new jail inside ezjail's scope. It either copies the template -jail or an ezjail archive to the root of that new jail, whose name and IP -address are provided as mandatory parameters. - -A new entry in ezjail's config directory is created, a corresponding new -\Fi/etc/fstab.hostname\fR allows the jail to be brought up by next -reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script. - -If no jail root is specified via the -r option, it is derived from -the jail's name. In this case or, if a jail root is given and does not -start with a '/', it is interpreted relative to ezjail's root dir -(default: \fI/usr/jails\fR). If a specified jail root lies outside the -ezjail root dir, a soft link is created inside this root dir pointing -to the newly created jail's location. - -The -i option requires a size passed via the -s option and creates a -file-backed jail image using md(4). -The image file is named after the jail root suffixed with \fI.img\fR. - -The -c options allows to generate a file-backed jail image encrypted -via gbde or geli, it requires a size passed via the -s option. -The image file is named after the jail root suffixed with \fI.img\fR. - -Starting with ZFS version 13 in FreeBSD, the -c option allows to -create a ZFS-backed jail with an optional ZFS filesystem-quota passed -via the -s option. The filesystem is named after the jailname. - -To install an ezjail archive instead of a vanilla copy of newjail use --a with the backup's location. Note that you will probably need to tidy -up things inside an ezjail if you migrate it between different ezjail -environments. This may include (but is not limited to) reinstalling ports -or packages for different CPUs or library versions. You may also need to -copy some libraries from the source host's basejail. Also consider using -\fIezjail-admin restore\fR, if you only want to revert to an old jail's -state from a backup on the same host. - -The -x option indicates that an ezjail already exists at the jail root. -.B In this case nothing is copied. ezjail only updates its config. -This is useful in situations where you just want to alter some of a -jail's properties and called ezjail-admin delete without the -w option -before. However, sanity checks are performed. - -Using the -f \fIflavour\fR option you can specify one or multiple space -separated ezjail \fBFLAVOUR\fRs to be installed in your ezjail (e.g. -preinstall packages, add users, configure rc). \fIflavours\fR points to -one or more directory trees under ezjail's root dir (default: -\fI/usr/jails/flavours\fR). If no flavours are passed, the global -ezjail_default_flavour (default: \fI""\fR) is used. See \fBFLAVOURS\fR below -for more details. - -Options for newly created jails are read from \fBezjail.conf\fR; refer to -ezjail.conf(5) for more information. -.SH ezjail-admin console -Attaches your console to a jail by executing a jexec with its jid. - -The command executed in that jail defaults to \fI/usr/bin/login -f root\fR -but can be set with the -e modifier or by setting the ezjail_default_execute -config variable. A non-running jail is not started by default. If you want -that, force it with -f. -.SH ezjail-admin list -lists all jails inside ezjail's scope. They are sorted by the order they -start up, as defined by rcorder. The list format is straightforward. - -A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR -based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto -image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not -running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see -\fIezjail-admin config\fR). - -The rest of the row is the jail's jid (if available), its IP address, hostname and -root directory. -.SH ezjail-admin config -manages specific ezjails. - -You can prevent an ezjail from being run at system start with the -r norun -option and reenable it with -r run. - -You can rename an ezjail by using the -n newname option. If the specified -ezjail is an image jail and the image has its default name, the image is -renamed as well. - -You can configure a cpuset(1) for the jail to use with the -c option. The setting -will be configured and, if the jail is running, appliedto the running jail. The specification -may include numbers separated by '-' for ranges and commas separating individual numbers. - -With the -z option, one or more zfs-datasets can be configured to be attached to the jail. -You need to configure the sysctl security.jail.mount_allowed=1 and security.jail.enforce_statfs=0, -set the jailed zfs property to on as well as "add path zfs unhide" in the devfs ruleset for the jail. - -You can configure an altered network view (FIB) for the jail with the -f option. For setting up FIBs, see -setfib(1). The jail needs to be restarted after the option has been applied to take effect. - -You can attach image jails for administrative purposes with the -i attach -option, and detach them with -i detach. It is not possible to run or delete -an attached jail. You can force fscking a jail image with the -i fsck command. -.SH ezjail-admin delete -removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR -file, thus preventing the jail from being brought up on next reboot. - -If the -w (wipe) option is given, the directory pointed to by the jail -root entry is removed as well as the soft link in ezjail's root dir. -.SH ezjail-admin archive -creates a backup of one, multiple or all ezjails. - -Unless an archive name is given via -a switch, its file name is derived from -jailname, date and time. It is saved to a directory provided by -d switch -or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to -\fI.\fR . - -Use -A with no further parameters to archive all jails \fBor\fR specify one or more -ezjails as parameters. - -Use \fIezjail-admin restore\fR or \fIezjail-admin create -a archive\fR to restore -an archive. -.SH ezjail-admin restore -creates new ezjails from archived versions. It tries to collect all information -necessary to do that without user interaction from the archives, thus allowing -it to be run from a script. - -Pass one or more archives or jail names. For jail names, ezjail-admin will try to -find the newest backup in its archive directory, as given in ezjail.conf(5), which -defaults to \fI.\fR and can be overridden via -d. - -By default \fIezjail-admin restore\fR refuses to restore on a host different from -where it was archived. Use -f to force that. -.SH ezjail-admin update -creates or updates ezjail's environment (aka basejail) from source. To install it -from ftp servers, use ezjail-admin install. - -Depending on the parameters given, it will install the basejail from a source -tree whose location is either provided in the \fBezjail.conf\fR config file or -via the -s option. - -If the -p or -P option is given, the base jail also is given a copy of -FreeBSDs ports tree, which is in turn linked into all newly created -ezjails. The portsnap utility is invoked to do the actual work. - -If the -P option is given, \fBonly the ports tree will be updated,\fR so this can -be done while jails are running. - -If the -i (install only) option is given, \fBezjail-admin update\fR performs a -\fImake installworld,\fR otherwise \fImake world\fR is invoked. - -.SH NOTES -.B ezjail-admin update\fR uses a temporary directory to install its world to, -thus leaving intact all installed libraries, if a base jail already exists. - -When using the \fBezjail-admin update\fR option, be careful to use the same -FreeBSD source tree used to build the host system's world, or at least its -kernel. Combining a make world in the host system with \fBezjail-admin update\fR -is considered a good idea. - -When a ports tree exists in basejail, a make.conf containing reasonable -values for having ports in jails is created in the template jail. -.SH FLAVOURS -.B ezjail-admin\fR provides an easy way to create many jails with similar or -identical properties. - -A sample flavour config directory resides under -.I EZJAIL_PREFIX/share/examples/ezjail/example/.\fR Some typical jail -initialization actions are demonstrated, and you are encouraged to use it as -a template for your flavours. - -If flavours are selected on jail creation, their root directories are -copied to the new jail's root, each containing an \fI/ezjail.flavour\fR. -When the jail starts up for the first time, these scripts are run and deleted. - -In its default form it will create some groups and users, change the -ownership of some files and install all packages residing under /pkg. - -It allows you to add some post-install actions. -.SH EXAMPLES -ezjail-admin update -p -.br -ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12 -.br -EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org -.br -EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org -.br -ezjail-admin delete ns.test.org -.br -ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1 -.SH BUGS -Due to the way ezjail handles jail config files, it is not possible to -create multiple jails if their names are identical when piped through -.B tr -C [:alnum:] _ - -Sure to be others. -.SH FILES -.T4 -EZJAIL_PREFIX/etc/ezjail.conf -.br -EZJAIL_PREFIX/etc/rc.d/ezjail.sh -.br -EZJAIL_PREFIX/share/examples/ezjail/ -.SH "SEE ALSO" -ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1) -.SH AUTHOR -Dirk Engling -- cgit v1.2.3