summaryrefslogtreecommitdiff
path: root/man1/ezjail-admin.1
blob: 864e2c076ccda2b11a6c2e85cbe03072b007961d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
.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 flavour] [-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 apply an ezjail \fBFLAVOUR\fR
to your ezjail (e.g. preinstall packages, add users, configure rc).
\fIflavour\fR is a directory tree under ezjail's root dir (default:
\fI/usr/jails/flavours\fR). 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 a flavour is selected on jail creation, the flavour root is
copied to the new jail's root, mostly containing an \fI/ezjail.flavour\fR.
When the jail starts up for the first time, this script is 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 <erdgeist@erdgeist.org>