summaryrefslogtreecommitdiff
path: root/man1/ezjail-admin.1
diff options
context:
space:
mode:
Diffstat (limited to 'man1/ezjail-admin.1')
-rwxr-xr-xman1/ezjail-admin.1128
1 files changed, 64 insertions, 64 deletions
diff --git a/man1/ezjail-admin.1 b/man1/ezjail-admin.1
index 02b5ee1..bd2984c 100755
--- a/man1/ezjail-admin.1
+++ b/man1/ezjail-admin.1
@@ -34,123 +34,123 @@ ezjail-admin \- Administrate ezjail
34The \fBezjail-admin\fR tool is used to manage the ezjail environment 34The \fBezjail-admin\fR tool is used to manage the ezjail environment
35and jails inside the ezjail scope. 35and jails inside the ezjail scope.
36 36
37It can also be used to start or stop and to get a console in ezjails 37It can also be used to start or stop and to get a console in ezjail's
38jails by proxying everything looking like 38jails by proxying everything looking like
39\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script. 39\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
40.SH ezjail-admin install 40.SH ezjail-admin install
41fetches everything needed to setup an ezjail environment from an FTP server and 41fetches everything needed to setup an ezjail environment from an FTP server and
42installs it. 42installs it.
43 43
44Default location for ezjails base jail is \fI/usr/jails\fR, so be sure you 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 45have enough space there (a FreeBSD base without man pages, sources and ports
46is around 120MB). 46is around 120MB).
47 47
48The -m and -s option will fetch and install man pages (ca. 10MB) and 48The -m and -s option will fetch and install man pages (ca. 10MB) and
49sources packages (ca. 450MB) respectively. The -p option invokes the 49sources packages (ca. 450MB) respectively. The -p option invokes the
50portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB). 50portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
51Parameters -M, -P or -S behave like their lower case pendants, plus they 51Options -M, -P or -S behave like their lower case pendants, but they
52disable (re)installing your basejail. 52disable (re)installing your basejail.
53 53
54Default OS version is, whatever uname -r returns. If this does not match 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 55"*-RELEASE", you will be prompted for a better guess. (Normally
56ftp-servers do not provide release candidates or CURRENT builds). You can 56ftp-servers do not provide release candidates or CURRENT builds). You can
57use the -r option to specify a release from command line. 57use the -r option to specify a release on the command line.
58 58
59Default host to fetch packages from is ftp.freebsd.org, you may want to 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). 60change this via the -h option or in ezjail.conf(5).
61 61
62If the specified location begins with file://, your local copy of the 62If the specified location begins with file://, your local copy of the
63release is used. That way you can do some modifications to install.sh 63release is used. That way you can modify the install.sh scripts before
64scripts before executing them. 64executing them.
65 65
66You can later update your world from CVS or update ports by \fIezjail-admin 66You can later update your world from CVS or update ports with \fIezjail-admin
67update\fR or rerun this subcommand with another OS version. 67update\fR or rerun this subcommand with another OS version.
68.SH ezjail-admin create 68.SH ezjail-admin create
69installs a new jail inside ezjails scope. It either copies the template 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 70jail or an ezjail archive to the root of that new jail, whose name and IP
71address are provided as mandatory parameters. 71address are provided as mandatory parameters.
72 72
73A new entry in ezjails config directory is created, a corresponding new 73A new entry in ezjail's config directory is created, a corresponding new
74\Fi/etc/fstab.hostname\fR allowes the jail to be brought up by next 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. 75reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
76 76
77If no jail root is specified via the -r option, it is derived from 77If no jail root is specified via the -r option, it is derived from
78the jails name. In this case or, if a jail root is given and does not 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 ezjails root dir 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 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 81ezjail root dir, a soft link is created inside this root dir pointing
82to the newly created jails location. 82to the newly created jail's location.
83 83
84The -i and the -c option both require a size passed via the -s option 84The -i and the -c options both require a size passed via the -s option
85and create a file based jail image; gbde or geli encrypted for the -c 85and create a file-based jail image; gbde or geli encrypted for the -c
86case. The image file is named after the jail root suffixed with \fI.img\fR. 86case. The image file is named after the jail root suffixed with \fI.img\fR.
87 87
88To install an ezjail archive instead of a vanilla copy of newjail use 88To install an ezjail archive instead of a vanilla copy of newjail use
89-a with the backups location. Note, that you will propably need to tidy 89-a with the backup's location. Note that you will probably need to tidy
90up things inside an ezjail if you migrate them between different ezjail 90up things inside an ezjail if you migrate it between different ezjail
91environments. This may include (but is not limited to) reinstalling ports 91environments. This may include (but is not limited to) reinstalling ports
92or packages for different CPUs or library versions. You may also need to 92or packages for different CPUs or library versions. You may also need to
93copy some libraries from the source host's basejail. Also consider using 93copy some libraries from the source host's basejail. Also consider using
94\fIezjail-admin restore\fR, if you only want to revert to an old jails 94\fIezjail-admin restore\fR, if you only want to revert to an old jail's
95state from a backup on the same host. 95state from a backup on the same host.
96 96
97The -x option indicates, that an ezjail already exists at the jail root. 97The -x option indicates that an ezjail already exists at the jail root.
98.B In this case nothing is copied. ezjail only updates its config. 98.B In this case nothing is copied. ezjail only updates its config.
99This is useful in situations where you just want to alter some of a 99This is useful in situations where you just want to alter some of a
100jail properties and called ezjail-admin delete without the -w option 100jail's properties and called ezjail-admin delete without the -w option
101before. However, sanity checks are being performed. 101before. However, sanity checks are performed.
102 102
103Using the -f \fIflavour\fR option you can apply an ezjail \fBFLAVOUR\fR 103Using the -f \fIflavour\fR option you can apply an ezjail \fBFLAVOUR\fR
104to your ezjail (e.g. preinstall packages, add users configure rc). 104to your ezjail (e.g. preinstall packages, add users, configure rc).
105\fIflavour\fR is a directory tree under ezjails root dir (default: 105\fIflavour\fR is a directory tree under ezjail's root dir (default:
106\fI/usr/jails/flavours\fR). See section \fBFLAVOURS\fR below for more 106\fI/usr/jails/flavours\fR). See \fBFLAVOURS\fR below for more details.
107details.
108 107
109Options for newly created jails are read from \fBezjail.conf\fR, refer to 108Options for newly created jails are read from \fBezjail.conf\fR; refer to
110ezjail.conf(5) for more information. 109ezjail.conf(5) for more information.
111.SH ezjail-admin console 110.SH ezjail-admin console
112Attaches your console to a jail by executing a jexec with its jid. 111Attaches your console to a jail by executing a jexec with its jid.
113 112
114The command executed in that jail defaults to \fI/usr/bin/login -f root\fR 113The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
115 but can be set with the -e modifier or by the ezjail_default_execute 114but can be set with the -e modifier or by setting the ezjail_default_execute
116config variable. A non-running jail is not started by default. If you want 115config variable. A non-running jail is not started by default. If you want
117that, force it with -f. 116that, force it with -f.
118.SH ezjail-admin list 117.SH ezjail-admin list
119lists all jails inside ezjails scope. They are sorted by the order they 118lists all jails inside ezjail's scope. They are sorted by the order they
120start up, as defined by rcorder. The list format is straight forward. 119start up, as defined by rcorder. The list format is straightforward.
121 120
122A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR 121A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR
123based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto 122based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto
124image based. The second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not 123image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
125running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see 124running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
126\fIezjail-admin config\fR). 125\fIezjail-admin config\fR).
127 126
128Rest of the row is jails jid (if available), its IP, hostname and root directory. 127The rest of the row is the jail's jid (if available), its IP address, hostname and
128root directory.
129.SH ezjail-admin config 129.SH ezjail-admin config
130manages specific ezjails. 130manages specific ezjails.
131 131
132You can prevent an ezjail from being run at system start by the -r norun 132You can prevent an ezjail from being run at system start with the -r norun
133option and reenable it by -r run. 133option and reenable it with -r run.
134 134
135You can rename an ezjail by using the -n newname option. If the specified 135You can rename an ezjail by using the -n newname option. If the specified
136ezjail is an image jail and the image has its default name, it is being 136ezjail is an image jail and the image has its default name, the image is
137renamed as well. 137renamed as well.
138 138
139You can attach image jails for administrative purposes by the -i attach 139You can attach image jails for administrative purposes with the -i attach
140option and detach them with -i detach. It is not possible to run or delete 140option, and detach them with -i detach. It is not possible to run or delete
141an attached jail. You can force fscking a jail image with the -i fsck command. 141an attached jail. You can force fscking a jail image with the -i fsck command.
142.SH ezjail-admin delete 142.SH ezjail-admin delete
143removes a jail from ezjails config and the corresponding \fI/etc/fstab.hostname\fR 143removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
144file, thus preventing the jail from being brought up on next reboot. 144file, thus preventing the jail from being brought up on next reboot.
145 145
146If the -w (wipe) option is given, the directory pointed to by the jail 146If the -w (wipe) option is given, the directory pointed to by the jail
147root entry is removed as well as the soft link in ezjails root dir. 147root entry is removed as well as the soft link in ezjail's root dir.
148.SH ezjail-admin archive 148.SH ezjail-admin archive
149creates a backup of one, multiple or all ezjails. 149creates a backup of one, multiple or all ezjails.
150 150
151Unless an archive name is given via -a switch, its file name is derived from 151Unless an archive name is given via -a switch, its file name is derived from
152jailname, date and time. It is being saved to a directory provided by -d switch 152jailname, date and time. It is saved to a directory provided by -d switch
153or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR and defaults to 153or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to
154\fI.\fR . 154\fI.\fR .
155 155
156Use -A with no further parameters to archive all jails \fBor\fR specify one or more 156Use -A with no further parameters to archive all jails \fBor\fR specify one or more
@@ -163,58 +163,58 @@ creates new ezjails from archived versions. It tries to collect all information
163necessary to do that without user interaction from the archives, thus allowing 163necessary to do that without user interaction from the archives, thus allowing
164it to be run from a script. 164it to be run from a script.
165 165
166Pass one or more archives or jail names. For jail names ezjail-admin will try to 166Pass one or more archives or jail names. For jail names, ezjail-admin will try to
167find the newest backup in its archive directory, as given in ezjail.conf(5) which 167find the newest backup in its archive directory, as given in ezjail.conf(5), which
168defaults to . and can be overridden via -d. 168defaults to \fI.\fR and can be overridden via -d.
169 169
170By default \fBezjail-admin restore\R refuses to restore on a host different from 170By default \fBezjail-admin restore\R refuses to restore on a host different from
171where it was archived. Use -f to force that. 171where it was archived. Use -f to force that.
172.SH ezjail-admin update 172.SH ezjail-admin update
173creates or updates ezjails environment (aka basejail) from source. To install it 173creates or updates ezjail's environment (aka basejail) from source. To install it
174from ftp servers, use ezjail-admin install. 174from ftp servers, use ezjail-admin install.
175 175
176Depending on the parameters given it will install the basejail from a source 176Depending on the parameters given, it will install the basejail from a source
177tree whose location is either provided in the \fBezjail.conf\fR config file or 177tree whose location is either provided in the \fBezjail.conf\fR config file or
178via the -s option. 178via the -s option.
179 179
180If the -p or -P options are given, the base jail also is given a copy of 180If the -p or -P option is given, the base jail also is given a copy of
181FreeBSDs ports tree, which is in turn linked into all newly created 181FreeBSDs ports tree, which is in turn linked into all newly created
182ezjails. The portsnap utility is invoked to do the actual work. 182ezjails. The portsnap utility is invoked to do the actual work.
183 183
184If the -P option is given, \fBonly the ports tree will be updated,\fR this can 184If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
185be done, while jails are running. 185be done while jails are running.
186 186
187If the -i (install only) option is given, \fBezjail-admin update\fR only 187If the -i (install only) option is given, \fBezjail-admin update\fR performs a
188performes a \fImake installworld,\fR otherwise \fImake world\fR is invoked. 188\fImake installworld,\fR otherwise \fImake world\fR is invoked.
189 189
190.SH NOTES 190.SH NOTES
191.B ezjail-admin update\fR uses a temporary directory to install its world to, 191.B ezjail-admin update\fR uses a temporary directory to install its world to,
192thus leaving intact all installed libraries, if a base jail already exists. 192thus leaving intact all installed libraries, if a base jail already exists.
193 193
194When using the \fBezjail-admin update\fR option, be careful to use the same 194When using the \fBezjail-admin update\fR option, be careful to use the same
195FreeBSD source tree used to build the host systems world, or at least its 195FreeBSD source tree used to build the host system's world, or at least its
196kernel. Combining a make world in the host system with \fBezjail-admin update\fR 196kernel. Combining a make world in the host system with \fBezjail-admin update\fR
197is considered a good idea. 197is considered a good idea.
198 198
199When a ports tree exists in base jail, a make.conf containing reasonable 199When a ports tree exists in basejail, a make.conf containing reasonable
200values for having ports in jails is created in the template jail. 200values for having ports in jails is created in the template jail.
201.SH FLAVOURS 201.SH FLAVOURS
202.B ezjail-admin\fR provides an easy way to create many jails with similar or 202.B ezjail-admin\fR provides an easy way to create many jails with similar or
203identical properties. 203identical properties.
204 204
205A sample flavour config directory resides under 205A sample flavour config directory resides under
206.I EZJAIL_PREFIX/share/examples/ezjail/default/.\fR Some typical Jail 206.I EZJAIL_PREFIX/share/examples/ezjail/default/.\fR Some typical jail
207initialization actions are demonstrated and you are encouraged to use it as a 207initialization actions are demonstrated, and you are encouraged to use it as
208template for your flavours. 208a template for your flavours.
209 209
210If a flavour is selected on jail creation, the flavour root is being 210If a flavour is selected on jail creation, the flavour root is
211copied to the new Jails root, mostly containing an \fI/ezjail.flavour\fR. 211copied to the new jail's root, mostly containing an \fI/ezjail.flavour\fR.
212If the Jail starts up for the first time this script is run. 212When the jail starts up for the first time, this script is run and deleted.
213 213
214In its default form it will create some groups and users, change the 214In its default form it will create some groups and users, change the
215ownership of some files and installs all packages residing under /pkg. 215ownership of some files and install all packages residing under /pkg.
216 216
217It allows you to add some post install actions. 217It allows you to add some post-install actions.
218.SH EXAMPLES 218.SH EXAMPLES
219ezjail-admin update -p 219ezjail-admin update -p
220.br 220.br
@@ -228,7 +228,7 @@ ezjail-admin delete ns.test.org
228.br 228.br
229ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1 229ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
230.SH BUGS 230.SH BUGS
231Due to the way ezjail handles jail config files it is not possible to 231Due to the way ezjail handles jail config files, it is not possible to
232create multiple jails if their names are identical when piped through 232create multiple jails if their names are identical when piped through
233.B tr -C [:alnum:] _ 233.B tr -C [:alnum:] _
234 234