summaryrefslogtreecommitdiff
path: root/man1/ezjail-admin.1
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 /man1/ezjail-admin.1
parent38bd97262a80fc5fb73b076115610eee501a6ea0 (diff)
New man pages, also put in new sections
Diffstat (limited to 'man1/ezjail-admin.1')
-rwxr-xr-xman1/ezjail-admin.1268
1 files changed, 0 insertions, 268 deletions
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 @@
1.TH ezjail\-admin 1
2.SH NAME
3ezjail-admin \- Administrate ezjail
4.SH SYNOPSIS
5.T
6.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release]
7
8.T
9.B ezjail-admin create
10[-f flavours] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip
11
12.T
13.B ezjail-admin console\fR [-f] [-e command]\fI jailname
14
15.T
16.B ezjail-admin list
17
18.T
19.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
20
21.T
22.B ezjail-admin delete \fR[-w] \fI hostname
23
24.T
25.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]
26
27.T
28.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)...
29
30.T
31.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
32
33.SH DESCRIPTION
34The \fBezjail-admin\fR tool is used to manage the ezjail environment
35and jails inside the ezjail scope.
36
37It can also be used to start or stop and to get a console in ezjail's
38jails by proxying everything looking like
39\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
40.SH ezjail-admin install
41fetches everything needed to setup an ezjail environment from an FTP server and
42installs it.
43
44The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you
45have enough space there (a FreeBSD base without man pages, sources and ports
46is around 120MB).
47
48The -m and -s option will fetch and install man pages (ca. 10MB) and
49sources packages (ca. 450MB) respectively. The -p option invokes the
50portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
51Options -M, -P or -S behave like their lower case pendants, but they
52disable (re)installing your basejail.
53
54The default OS version is whatever uname -r returns. If this does not match
55"*-RELEASE", you will be prompted for a better guess. (Normally
56ftp-servers do not provide release candidates or CURRENT builds). You can
57use the -r option to specify a release on the command line.
58
59The default host to fetch packages from is ftp.freebsd.org; you may want to
60change this via the -h option or in ezjail.conf(5).
61
62If the specified location begins with file://, your local copy of the
63release is used. That way you can modify the install.sh scripts before
64executing them.
65
66You can later update your world from CVS or update ports with \fIezjail-admin
67update\fR or rerun this subcommand with another OS version.
68.SH ezjail-admin create
69installs a new jail inside ezjail's scope. It either copies the template
70jail or an ezjail archive to the root of that new jail, whose name and IP
71address are provided as mandatory parameters.
72
73A new entry in ezjail's config directory is created, a corresponding new
74\Fi/etc/fstab.hostname\fR allows the jail to be brought up by next
75reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
76
77If no jail root is specified via the -r option, it is derived from
78the jail's name. In this case or, if a jail root is given and does not
79start with a '/', it is interpreted relative to ezjail's root dir
80(default: \fI/usr/jails\fR). If a specified jail root lies outside the
81ezjail root dir, a soft link is created inside this root dir pointing
82to the newly created jail's location.
83
84The -i option requires a size passed via the -s option and creates a
85file-backed jail image using md(4).
86The image file is named after the jail root suffixed with \fI.img\fR.
87
88The -c options allows to generate a file-backed jail image encrypted
89via gbde or geli, it requires a size passed via the -s option.
90The image file is named after the jail root suffixed with \fI.img\fR.
91
92Starting with ZFS version 13 in FreeBSD, the -c option allows to
93create a ZFS-backed jail with an optional ZFS filesystem-quota passed
94via the -s option. The filesystem is named after the jailname.
95
96To install an ezjail archive instead of a vanilla copy of newjail use
97-a with the backup's location. Note that you will probably need to tidy
98up things inside an ezjail if you migrate it between different ezjail
99environments. This may include (but is not limited to) reinstalling ports
100or packages for different CPUs or library versions. You may also need to
101copy some libraries from the source host's basejail. Also consider using
102\fIezjail-admin restore\fR, if you only want to revert to an old jail's
103state from a backup on the same host.
104
105The -x option indicates that an ezjail already exists at the jail root.
106.B In this case nothing is copied. ezjail only updates its config.
107This is useful in situations where you just want to alter some of a
108jail's properties and called ezjail-admin delete without the -w option
109before. However, sanity checks are performed.
110
111Using the -f \fIflavour\fR option you can specify one or multiple space
112separated ezjail \fBFLAVOUR\fRs to be installed in your ezjail (e.g.
113preinstall packages, add users, configure rc). \fIflavours\fR points to
114one or more directory trees under ezjail's root dir (default:
115\fI/usr/jails/flavours\fR). If no flavours are passed, the global
116ezjail_default_flavour (default: \fI""\fR) is used. See \fBFLAVOURS\fR below
117for more details.
118
119Options for newly created jails are read from \fBezjail.conf\fR; refer to
120ezjail.conf(5) for more information.
121.SH ezjail-admin console
122Attaches your console to a jail by executing a jexec with its jid.
123
124The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
125but can be set with the -e modifier or by setting the ezjail_default_execute
126config variable. A non-running jail is not started by default. If you want
127that, force it with -f.
128.SH ezjail-admin list
129lists all jails inside ezjail's scope. They are sorted by the order they
130start up, as defined by rcorder. The list format is straightforward.
131
132A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR
133based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto
134image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
135running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
136\fIezjail-admin config\fR).
137
138The rest of the row is the jail's jid (if available), its IP address, hostname and
139root directory.
140.SH ezjail-admin config
141manages specific ezjails.
142
143You can prevent an ezjail from being run at system start with the -r norun
144option and reenable it with -r run.
145
146You can rename an ezjail by using the -n newname option. If the specified
147ezjail is an image jail and the image has its default name, the image is
148renamed as well.
149
150You can configure a cpuset(1) for the jail to use with the -c option. The setting
151will be configured and, if the jail is running, appliedto the running jail. The specification
152may include numbers separated by '-' for ranges and commas separating individual numbers.
153
154With the -z option, one or more zfs-datasets can be configured to be attached to the jail.
155You need to configure the sysctl security.jail.mount_allowed=1 and security.jail.enforce_statfs=0,
156set the jailed zfs property to on as well as "add path zfs unhide" in the devfs ruleset for the jail.
157
158You can configure an altered network view (FIB) for the jail with the -f option. For setting up FIBs, see
159setfib(1). The jail needs to be restarted after the option has been applied to take effect.
160
161You can attach image jails for administrative purposes with the -i attach
162option, and detach them with -i detach. It is not possible to run or delete
163an attached jail. You can force fscking a jail image with the -i fsck command.
164.SH ezjail-admin delete
165removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
166file, thus preventing the jail from being brought up on next reboot.
167
168If the -w (wipe) option is given, the directory pointed to by the jail
169root entry is removed as well as the soft link in ezjail's root dir.
170.SH ezjail-admin archive
171creates a backup of one, multiple or all ezjails.
172
173Unless an archive name is given via -a switch, its file name is derived from
174jailname, date and time. It is saved to a directory provided by -d switch
175or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to
176\fI.\fR .
177
178Use -A with no further parameters to archive all jails \fBor\fR specify one or more
179ezjails as parameters.
180
181Use \fIezjail-admin restore\fR or \fIezjail-admin create -a archive\fR to restore
182an archive.
183.SH ezjail-admin restore
184creates new ezjails from archived versions. It tries to collect all information
185necessary to do that without user interaction from the archives, thus allowing
186it to be run from a script.
187
188Pass one or more archives or jail names. For jail names, ezjail-admin will try to
189find the newest backup in its archive directory, as given in ezjail.conf(5), which
190defaults to \fI.\fR and can be overridden via -d.
191
192By default \fIezjail-admin restore\fR refuses to restore on a host different from
193where it was archived. Use -f to force that.
194.SH ezjail-admin update
195creates or updates ezjail's environment (aka basejail) from source. To install it
196from ftp servers, use ezjail-admin install.
197
198Depending on the parameters given, it will install the basejail from a source
199tree whose location is either provided in the \fBezjail.conf\fR config file or
200via the -s option.
201
202If the -p or -P option is given, the base jail also is given a copy of
203FreeBSDs ports tree, which is in turn linked into all newly created
204ezjails. The portsnap utility is invoked to do the actual work.
205
206If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
207be done while jails are running.
208
209If the -i (install only) option is given, \fBezjail-admin update\fR performs a
210\fImake installworld,\fR otherwise \fImake world\fR is invoked.
211
212.SH NOTES
213.B ezjail-admin update\fR uses a temporary directory to install its world to,
214thus leaving intact all installed libraries, if a base jail already exists.
215
216When using the \fBezjail-admin update\fR option, be careful to use the same
217FreeBSD source tree used to build the host system's world, or at least its
218kernel. Combining a make world in the host system with \fBezjail-admin update\fR
219is considered a good idea.
220
221When a ports tree exists in basejail, a make.conf containing reasonable
222values for having ports in jails is created in the template jail.
223.SH FLAVOURS
224.B ezjail-admin\fR provides an easy way to create many jails with similar or
225identical properties.
226
227A sample flavour config directory resides under
228.I EZJAIL_PREFIX/share/examples/ezjail/example/.\fR Some typical jail
229initialization actions are demonstrated, and you are encouraged to use it as
230a template for your flavours.
231
232If flavours are selected on jail creation, their root directories are
233copied to the new jail's root, each containing an \fI/ezjail.flavour\fR.
234When the jail starts up for the first time, these scripts are run and deleted.
235
236In its default form it will create some groups and users, change the
237ownership of some files and install all packages residing under /pkg.
238
239It allows you to add some post-install actions.
240.SH EXAMPLES
241ezjail-admin update -p
242.br
243ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12
244.br
245EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org
246.br
247EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org
248.br
249ezjail-admin delete ns.test.org
250.br
251ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
252.SH BUGS
253Due to the way ezjail handles jail config files, it is not possible to
254create multiple jails if their names are identical when piped through
255.B tr -C [:alnum:] _
256
257Sure to be others.
258.SH FILES
259.T4
260EZJAIL_PREFIX/etc/ezjail.conf
261.br
262EZJAIL_PREFIX/etc/rc.d/ezjail.sh
263.br
264EZJAIL_PREFIX/share/examples/ezjail/
265.SH "SEE ALSO"
266ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1)
267.SH AUTHOR
268Dirk Engling <erdgeist@erdgeist.org>