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