Date: Wed, 23 May 2012 15:29:34 +0000 (UTC) From: Jamie Gritton <jamie@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org Subject: svn commit: r235839 - in stable/9: lib/libc/sys usr.sbin/jail Message-ID: <201205231529.q4NFTYZc080713@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jamie Date: Wed May 23 15:29:34 2012 New Revision: 235839 URL: http://svn.freebsd.org/changeset/base/235839 Log: MFC r234712, r234744, r234934, r234988, r235294, r235335, and bits of r235337 and r235355: A new jail(8) with a configuration file, ultimately to replace the work currently done by /etc/rc.d/jail. Added: stable/9/usr.sbin/jail/command.c - copied, changed from r234712, head/usr.sbin/jail/command.c stable/9/usr.sbin/jail/config.c - copied, changed from r234712, head/usr.sbin/jail/config.c stable/9/usr.sbin/jail/jail.conf.5 - copied, changed from r234712, head/usr.sbin/jail/jail.conf.5 stable/9/usr.sbin/jail/jaillex.l - copied, changed from r234712, head/usr.sbin/jail/jaillex.l stable/9/usr.sbin/jail/jailp.h - copied, changed from r234712, head/usr.sbin/jail/jailp.h stable/9/usr.sbin/jail/jailparse.y - copied unchanged from r234712, head/usr.sbin/jail/jailparse.y stable/9/usr.sbin/jail/state.c - copied unchanged from r234712, head/usr.sbin/jail/state.c Modified: stable/9/lib/libc/sys/jail.2 stable/9/usr.sbin/jail/Makefile stable/9/usr.sbin/jail/jail.8 stable/9/usr.sbin/jail/jail.c Directory Properties: stable/9/lib/libc/ (props changed) stable/9/lib/libc/sys/ (props changed) stable/9/usr.sbin/jail/ (props changed) Modified: stable/9/lib/libc/sys/jail.2 ============================================================================== --- stable/9/lib/libc/sys/jail.2 Wed May 23 15:10:41 2012 (r235838) +++ stable/9/lib/libc/sys/jail.2 Wed May 23 15:29:34 2012 (r235839) @@ -59,7 +59,7 @@ system call sets up a jail and locks the The argument is a pointer to a structure describing the prison: .Bd -literal -offset indent struct jail { - u_int32_t version; + uint32_t version; char *path; char *hostname; char *jailname; @@ -247,44 +247,6 @@ They return \-1 on failure, and set to indicate the error. .Pp .Rv -std jail_attach jail_remove -.Sh PRISON? -Once a process has been put in a prison, it and its descendants cannot escape -the prison. -.Pp -Inside the prison, the concept of -.Dq superuser -is very diluted. -In general, -it can be assumed that nothing can be mangled from inside a prison which -does not exist entirely inside that prison. -For instance the directory -tree below -.Dq Li path -can be manipulated all the ways a root can normally do it, including -.Dq Li "rm -rf /*" -but new device special nodes cannot be created because they reference -shared resources (the device drivers in the kernel). -The effective -.Dq securelevel -for a process is the greater of the global -.Dq securelevel -or, if present, the per-jail -.Dq securelevel . -.Pp -All IP activity will be forced to happen to/from the IP number specified, -which should be an alias on one of the network interfaces. -All connections to/from the loopback address -.Pf ( Li 127.0.0.1 -for IPv4, -.Li ::1 -for IPv6) will be changed to be to/from the primary address -of the jail for the given address family. -.Pp -It is possible to identify a process as jailed by examining -.Dq Li /proc/<pid>/status : -it will show a field near the end of the line, either as -a single hyphen for a process at large, or the name currently -set for the prison for jailed processes. .Sh ERRORS The .Fn jail @@ -334,7 +296,7 @@ flag is not set. The jail referred to by a .Va jid is not accessible by the process, because the process is in a different -jail. +jail. .It Bq Er EEXIST The jail referred to by a .Va jid @@ -382,7 +344,7 @@ parameter does not exist. The jail referred to by a .Va jid is not accessible by the process, because the process is in a different -jail. +jail. .It Bq Er ENOENT The .Va lastjid @@ -415,7 +377,7 @@ and .Fn jail_attach call .Xr chroot 2 -internally, so it can fail for all the same reasons. +internally, so they can fail for all the same reasons. Please consult the .Xr chroot 2 manual page for details. Modified: stable/9/usr.sbin/jail/Makefile ============================================================================== --- stable/9/usr.sbin/jail/Makefile Wed May 23 15:10:41 2012 (r235838) +++ stable/9/usr.sbin/jail/Makefile Wed May 23 15:29:34 2012 (r235839) @@ -3,9 +3,14 @@ .include <bsd.own.mk> PROG= jail -MAN= jail.8 -DPADD= ${LIBJAIL} ${LIBUTIL} -LDADD= -ljail -lutil +MAN= jail.8 jail.conf.5 +SRCS= jail.c command.c config.c state.c jailp.h jaillex.l jailparse.y y.tab.h + +DPADD= ${LIBJAIL} ${LIBKVM} ${LIBUTIL} ${LIBL} +LDADD= -ljail -lkvm -lutil -ll + +YFLAGS+=-v +CFLAGS+=-I. -I${.CURDIR} .if ${MK_INET6_SUPPORT} != "no" CFLAGS+= -DINET6 @@ -14,4 +19,6 @@ CFLAGS+= -DINET6 CFLAGS+= -DINET .endif +CLEANFILES= y.output + .include <bsd.prog.mk> Copied and modified: stable/9/usr.sbin/jail/command.c (from r234712, head/usr.sbin/jail/command.c) ============================================================================== --- head/usr.sbin/jail/command.c Thu Apr 26 17:36:05 2012 (r234712, copy source) +++ stable/9/usr.sbin/jail/command.c Wed May 23 15:29:34 2012 (r235839) @@ -100,7 +100,7 @@ next_command(struct cfjail *j) if (j->comstring == NULL) { j->comparam += create_failed ? -1 : 1; switch ((comparam = *j->comparam)) { - case 0: + case IP__NULL: return 0; case IP_MOUNT_DEVFS: if (!bool_param(j->intparams[IP_MOUNT_DEVFS])) Copied and modified: stable/9/usr.sbin/jail/config.c (from r234712, head/usr.sbin/jail/config.c) ============================================================================== --- head/usr.sbin/jail/config.c Thu Apr 26 17:36:05 2012 (r234712, copy source) +++ stable/9/usr.sbin/jail/config.c Wed May 23 15:29:34 2012 (r235839) @@ -328,7 +328,7 @@ add_param(struct cfjail *j, const struct } } else { flags = PF_APPEND; - if (ipnum != 0) { + if (ipnum != IP__NULL) { name = intparams[ipnum].name; flags |= intparams[ipnum].flags; } else if ((cs = strchr(value, '='))) { @@ -350,7 +350,7 @@ add_param(struct cfjail *j, const struct } /* See if this parameter has already been added. */ - if (ipnum != 0) + if (ipnum != IP__NULL) dp = j->intparams[ipnum]; else TAILQ_FOREACH(dp, &j->params, tq) @@ -375,10 +375,10 @@ add_param(struct cfjail *j, const struct np->flags = flags; np->gen = 0; TAILQ_INSERT_TAIL(&j->params, np, tq); - if (ipnum != 0) + if (ipnum != IP__NULL) j->intparams[ipnum] = np; else - for (ipnum = 1; ipnum < IP_NPARAM; ipnum++) + for (ipnum = IP__NULL + 1; ipnum < IP_NPARAM; ipnum++) if (!(intparams[ipnum].flags & PF_CONV) && equalopts(name, intparams[ipnum].name)) { j->intparams[ipnum] = np; Modified: stable/9/usr.sbin/jail/jail.8 ============================================================================== --- stable/9/usr.sbin/jail/jail.8 Wed May 23 15:10:41 2012 (r235838) +++ stable/9/usr.sbin/jail/jail.8 Wed May 23 15:29:34 2012 (r235839) @@ -1,6 +1,5 @@ -.\" .\" Copyright (c) 2000, 2003 Robert N. M. Watson -.\" Copyright (c) 2008 James Gritton +.\" Copyright (c) 2008-2012 James Gritton .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,186 +23,263 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" -.\" ---------------------------------------------------------------------------- -.\" "THE BEER-WARE LICENSE" (Revision 42): -.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you -.\" can do whatever you want with this stuff. If we meet some day, and you think -.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp -.\" ---------------------------------------------------------------------------- -.\" .\" $FreeBSD$ .\" -.Dd February 29, 2012 +.Dd May 23, 2012 .Dt JAIL 8 .Os .Sh NAME .Nm jail -.Nd "create or modify a system jail" +.Nd "manage system jails" .Sh SYNOPSIS .Nm -.Op Fl dhi +.Op Fl dhilqv .Op Fl J Ar jid_file -.Op Fl l u Ar username | Fl U Ar username -.Op Fl c | m -.Op Ar parameter=value ... +.Op Fl u Ar username +.Op Fl U Ar username +.Op Fl cmr +.Ar param Ns = Ns Ar value ... +.Op Cm command Ns = Ns Ar command ... .Nm -.Op Fl hi -.Op Fl n Ar jailname +.Op Fl dqv +.Op Fl f Ar conf_file +.Op Fl p Ar limit +.Op Fl cmr +.Op Ar jail +.Nm +.Op Fl qv +.Op Fl f Ar conf_file +.Op Fl rR +.Op Cm * | Ar jail ... +.Nm +.Op Fl dhilqv .Op Fl J Ar jid_file +.Op Fl u Ar username +.Op Fl U Ar username +.Op Fl n Ar jailname .Op Fl s Ar securelevel -.Op Fl l u Ar username | Fl U Ar username -.Op Ar path hostname [ip[,..]] command ... -.Nm -.Op Fl r Ar jail +.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ... .Sh DESCRIPTION The .Nm -utility creates a new jail or modifies an existing jail, optionally -imprisoning the current process (and future descendants) inside it. +utility creates new jails, or modifies or removes existing jails. +A jail is specified via parameters on the command line, or in the +.Xr jail.conf 5 +file. +.Pp +At least one of the options +.Fl c , +.Fl m +or +.Fl r +must be specified. +These options are used alone or in combination describe the operation to +perform: +.Bl -tag -width indent +.It Fl c +Create a new jail. +The jail +.Va jid +and +.Va name +parameters (if specified) on the command line, +or any jails +must not refer to an existing jail. +.It Fl m +Modify an existing jail. +One of the +.Va jid +or +.Va name +parameters must exist and refer to an existing jail. +Some parameters may not be changed on a running jail. +.It Fl r +Remove the +.Ar jail +specified by jid or name. +All jailed processes are killed, and all children of this jail are also +removed. +.It Fl rc +Restart an existing jail. +The jail is first removed and then re-created, as if +.Dq Nm Fl c +and +.Dq Nm Fl r +were run in succession. +.It Fl cm +Create a jail if it does not exist, or modify the jail if it does exist. +.It Fl mr +Modify an existing jail. +The jail may be restarted if necessary to modify parameters than could +not otherwise be changed. +.It Fl cmr +Create a jail if it doesn't exist, or modify (and possibly restart) the +jail if it does exist. +.El .Pp -The options are as follows: +Other available options are: .Bl -tag -width indent .It Fl d -Allow making changes to a dying jail. +Allow making changes to a dying jail, equivalent to the +.Va allow.dying +parameter. +.It Fl f Ar conf_file +Use configuration file +.Ar conf_file +instead of the default +.Pa /etc/jail.conf . .It Fl h Resolve the .Va host.hostname parameter (or .Va hostname ) and add all IP addresses returned by the resolver -to the list of -.Va ip -addresses for this prison. -This may affect default address selection for outgoing IPv4 connections -of prisons. -The address first returned by the resolver for each address family -will be used as primary address. -See the -.Va ip4.addr -and -.Va ip6.addr -parameters further down for details. -.It Fl i -Output the jail identifier of the newly created jail. -.It Fl n Ar jailname -Set the jail's name. -This is deprecated and is equivalent to setting the -.Va name +to the list of addresses for this prison. +This is equivalent to the +.Va ip_hostname parameter. +.It Fl i +Output (only) the jail identifier of the newly created jail(s). +This implies the +.Fl q +option. .It Fl J Ar jid_file Write a .Ar jid_file -file, containing jail identifier, path, hostname, IP and -command used to start the jail. +file, containing parameters used to start the jail. .It Fl l -Run program in the clean environment. -The environment is discarded except for -.Ev HOME , SHELL , TERM -and -.Ev USER . -.Ev HOME -and -.Ev SHELL -are set to the target login's default values. -.Ev USER -is set to the target login. -.Ev TERM -is imported from the current environment. -The environment variables from the login class capability database for the -target login are also set. +Run commands in a clean environment. +This is deprecated and is equivalent to the exec.clean parameter. +.It Fl n Ar jailname +Set the jail's name. +This is deprecated and is equivalent to the +.Va name +parameter. +.It Fl p Ar limit +Limit the number of commands from +.Va exec.* +that can run simultaneously. +.It Fl q +Suppress the message printed whenever a jail is created, modified or removed. +Only error messages will be printed. +.It Fl R +A variation of the +.Fl r +option that removes an existing jail without using the configuration file. +No removal-related parameters for this jail will be used - the jail will +simply be removed. .It Fl s Ar securelevel Set the .Va kern.securelevel MIB entry to the specified value inside the newly created jail. -This is deprecated and is equivalent to setting the +This is deprecated and is equivalent to the .Va securelevel parameter. .It Fl u Ar username -The user name from host environment as whom the -.Ar command -should run. -.It Fl U Ar username -The user name from jailed environment as whom the -.Ar command -should run. -.It Fl c -Create a new jail. -The -.Va jid +The user name from host environment as whom jailed commands should run. +This is deprecated and is equivalent to the +.Va exec.jail_user and -.Va name -parameters (if specified) must not refer to an existing jail. -.It Fl m -Modify an existing jail. -One of the -.Va jid -or -.Va name -parameters must exist and refer to an existing jail. -.It Fl cm -Create a jail if it does not exist, or modify a jail if it does exist. -.It Fl r -Remove the -.Ar jail -specified by jid or name. -All jailed processes are killed, and all children of this jail are also -removed. +.Va exec.system_jail_user +parameters. +.It Fl U Ar username +The user name from jailed environment as whom jailed commands should run. +This is deprecated and is equivalent to the +.Va exec.jail_user +parameter. +.It Fl v +Print a message on every operation, such as running commands and +mounting filesystems. .El .Pp -At least one of the -.Fl c , -.Fl m -or +If no arguments are given after the options, the operation (except +remove) will be performed on all jails specified in the +.Xr jail.conf 5 +file. +A single argument of a jail name will operate only on the specified jail. +The .Fl r -options must be specified. -.Pp -.Ar Parameters -are listed in -.Dq name=value -form, following the options. -Some parameters are boolean, and do not have a value but are set by the -name alone with or without a -.Dq no -prefix, e.g. -.Va persist -or -.Va nopersist . -Any parameters not set will be given default values, often based on the -current environment. +and +.Fl R +options can also remove running jails that aren't in the +.Xr jail.conf 5 +file, specified by name or jid. +.Pp +An argument of +.Dq * +is a wildcard that will operate on all jails, regardless of whether +they appear in +.Xr jail.conf 5 ; +this is the surest way for +.Fl r +to remove all jails. +If hierarchical jails exist, a partial-matching wildcard definition may +be specified. +For example, an argument of +.Dq foo.* +would apply to jails with names like +.Dq foo.bar +and +.Dq foo.bar.baz . .Pp -The pseudo-parameter -.Va command -specifies that the current process should enter the new (or modified) jail, -and run the specified command. -It must be the last parameter specified, because it includes not only -the value following the -.Sq = -sign, but also passes the rest of the arguments to the command. -.Pp -Instead of supplying named -.Ar parameters , -four fixed parameters may be supplied in order on the command line: +A jail may be specified with parameters directly on the command line. +In this case, the +.Xr jail.conf 5 +file will not be used. +For backward compatibility, the command line may also have four fixed +parameters, without names: .Ar path , .Ar hostname , .Ar ip , and .Ar command . -As the -.Va jid -and -.Va name -parameters aren't in this list, this mode will always create a new jail, and -the +This mode will always create a new jail, and the .Fl c and .Fl m options don't apply (and must not exist). +.Ss Jail Parameters +Parameters in the +.Xr jail.conf 5 +file, or on the command line, are generally in +.Dq name=value +form. +Some parameters are boolean, and do not have a value but are set by the +name alone with or without a +.Dq no +prefix, e.g. +.Va persist +or +.Va nopersist . +They can also be given the values +.Dq true +and +.Dq false . +Other partameters may have more than one value, specified as a +comma-separated list or with +.Dq += +in the configuration file (see +.Xr jail.conf 5 +for details). .Pp -Jails have a set a core parameters, and modules can add their own jail -parameters. +The +.Nm +utility recognizes two classes of parameters. There are the true jail +parameters that are passed to the kernel when the jail is created, +can be seen with +.Xr jls 8 , +and can (usually) be changed with +.Dq Nm Fl m. +Then there are pseudo-parameters that are only used by +.Nm +itself. +.Pp +Jails have a set a core parameters, and kernel modules can add their own +jail parameters. The current set of available parameters can be retrieved via .Dq Nm sysctl Fl d Va security.jail.param . +Any parameters not set will be given default values, often based on the +current environment. The core parameters are: .Bl -tag -width indent .It Va jid @@ -231,14 +307,21 @@ If no .Va name is supplied, a default is assumed that is the same as the .Va jid . -.It Va path -Directory which is to be the root of the prison. The -.Va command -(if any) is run from this directory, as are commands from -.Xr jexec 8 . +.Va name +parameter is implied by the +.Xr jail.conf 5 +file format, and need not be explicitly set when using the configuration +file. +.It Va path +The directory which is to be the root of the prison. +Any commands run inside the prison, either by +.Nm +or from +.Xr jexec 8 , +are run from this directory. .It Va ip4.addr -A comma-separated list of IPv4 addresses assigned to the prison. +A list of IPv4 addresses assigned to the prison. If this is set, the jail is restricted to using only these addresses. Any attempts to use other addresses fail, and attempts to use wildcard addresses silently use the jailed address instead. @@ -252,7 +335,7 @@ assigned to itself. A boolean option to change the formerly mentioned behaviour and disable IPv4 source address selection for the prison in favour of the primary IPv4 address of the jail. -Source address selection is enabled by default for all jails and a +Source address selection is enabled by default for all jails and the .Va ip4.nosaddrsel setting of a parent jail is not inherited for any child jails. .It Va ip4 @@ -277,8 +360,20 @@ A set of IPv6 options for the prison, th and .Va ip4 above. +.It vnet +Create the prison with its own virtual network stack, +with its own network interfaces, addresses, routing table, etc. +The kernel must have been compiled with the +.Sy VIMAGE option +for this to be available. +Possible values are +.Dq inherit +to use the system network stack, possibly with restricted IP addresses, +and +.Dq new +to create a new network stack. .It Va host.hostname -Hostname of the prison. +The hostname of the prison. Other similar parameters are .Va host.domainname , .Va host.hostuuid @@ -314,13 +409,24 @@ permissions are effective and .Va enforce_statfs is set to a value lower than 2. Devfs rules and rulesets cannot be viewed or modified from inside a jail. +.Pp +NOTE: It is important that only appropriate device nodes in devfs be +exposed to a jail; access to disk devices in the jail may permit processes +in the jail to bypass the jail sandboxing by modifying files outside of +the jail. +See +.Xr devfs 8 +for information on how to use devfs rules to limit access to entries +in the per-jail devfs. +A simple devfs ruleset for jails is available as ruleset #4 in +.Pa /etc/defaults/devfs.rules . .It Va children.max The number of child jails allowed to be created by this jail (or by other jails under this jail). This limit is zero by default, indicating the jail is not allowed to create child jails. See the -.Va "Hierarchical Jails" +.Sx "Hierarchical Jails" section for more information. .It Va children.cur The number of descendents of this jail, including its own child jails @@ -345,10 +451,13 @@ where the jail's chroot directory is loc .It Va persist Setting this boolean parameter allows a jail to exist without any processes. -Normally, a jail is destroyed as its last process exits. +Normally, a command is run as part of jail creation, and then the jail +is destroyed as its last process exits. A new jail must have either the .Va persist parameter or +.Va exec.start +or .Va command pseudo-parameter set. .It Va cpuset.id @@ -459,6 +568,171 @@ have not had jail functionality added to .El .El .Pp +There are pseudo-parameters that aren't passed to the kernel, but are +used by +.Nm +to set up the prison environment, often by running specified commands +when jails are created or removed. +The +.Va exec.* +command parameters are +.Xr sh 1 +command lines that are run in either the system or prison environment. +They may be given multiple values, which run would the specified +commands in sequence. +All commands must succed (return a zero exit status), or the jail will +not be created or removed. +.Pp +The pseudo-parameters are: +.Bl -tag -width indent +.It Va exec.prestart +Command(s) to run in the system environment before a prison is created. +.It Va exec.start +Command(s) to run in the prison environment when a jail is created. +A typical command to run is +.Dq sh /etc/rc . +.It Va command +A synonym for +.Va exec.start +for use when specifying a prison directly on the command line. +Unlike other parameters whose value is a single string, +.Va command +uses the remainder of the +.Nm +command line as its own arguments. +.It Va exec.poststart +Command(s) to run in the system environment after a jail is created, +and after any +.Va exec.start +commands have completed. +.It Va exec.prestop +Command(s) to run in the system environment before a jail is removed. +.It Va exec.stop +Command(s) to run in the prison environment before a jail is removed, +and after any +.Va exec.prestop +commands have completed. +A typical command to run is +.Dq sh /etc/rc.shutdown . +.It Va exec.poststop +Command(s) to run in the system environment after a jail is removed. +.It Va exec.clean +Run commands in a clean environment. +The environment is discarded except for +.Ev HOME , SHELL , TERM +and +.Ev USER . +.Ev HOME +and +.Ev SHELL +are set to the target login's default values. +.Ev USER +is set to the target login. +.Ev TERM +is imported from the current environment. +The environment variables from the login class capability database for the +target login are also set. +.It Va exec.jail_user +The user to run commands as, when running in the prison environment. +The default is to run the commands as the current user. +.It Va exec.system_jail_user +This boolean option looks for the +.Va exec.jail_user +in the system +.Xr passwd 5 +file, instead of in the prison's file. +.It Va exec.system_user +The user to run commands as, when running in the system environment. +The default is to run the commands as the current user. +.It Va exec.timeout +The maximum amount of time to wait for a command to complete. +If a command is still running after this many seconds have passed, +the jail not be created or removed. +.It Va exec.consolelog +A file to direct command output (stdout and stderr) to. +.It Va exec.fib +The FIB (routing table) to set when running commands inside the prison. +.It Va stop.timeout +The maximum amount of time to wait for a prison's processes to exit +after sending them a +.Dv SIGTERM +signal (which happens after the +.Va exec.stop commands have completed). +After this many seconds have passed, the prison will be removed, which +will kill any remaining processes. +If this is set to zero, no +.Dv SIGTERM +is sent and the prison is immediately removed. +The default is 10 seconds. +.It Va interface +A network interface to add the prison's IP addresses +.Va ( ip4.addr +and +.Va ip6.addr ) +to. +An alias for each address will be added to the interface before the +prison is created, and will be removed from the interface after the +prison is removed. +.It Op Va ip4.addr +In addition to the IP addresses that are passed to the kernel, and +interface and/or a netmask may also be specified, in the form +.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask . +If an interface is given before the IP address, an alias for the address +will be added to that interface, as it is with the +.Va interface +parameter. If a netmask in either dotted-quad or CIDR form is given +after IP address, it will be used when adding the IP alias. +.It Op Va ip6.addr +In addition to the IP addresses that are passed to the kernel, +and interface and/or a prefix may also be specified, in the form +.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix . +.It Va vnet.interface +A network interface to give to a vnet-enabled jail after is it created. +The interface will automatically be returned when the jail is removed. +.It Va ip_hostname +Resolve the +.Va host.hostname +parameter and add all IP addresses returned by the resolver +to the list of addresses +.Va ( ip4.addr +or +.Va ip6.addr ) +for this prison. +This may affect default address selection for outgoing IPv4 connections +of prisons. +The address first returned by the resolver for each address family +will be used as primary address. +.It Va mount +A filesystem to mount before creating the jail (and to unmount after +removing it), given as a single +.Xr fstab 5 +line. +.It Va mount.fstab +An +.Xr fstab 5 +format file containing filesystems to mount before creating a jail. +.It Va mount.devfs +Mount a +.Xr devfs +filesystem on the chrooted /dev directory, and apply the ruleset in the +.Va devfs_ruleset +parameter (or a default of ruleset 4: devfsrules_jail) +to restrict the devices visible inside the prison. +.It Va allow.dying +Allow making changes to a +.Va dying +jail. +.It Va depend +Specify a jail (or jails) that this jail depends on. +Any such jails must be fully created, up to the last +.Va exec.poststart +command, before any action will taken to create this jail. +When jails are removed the opposite is true: +this jail must be fully removed, up to the last +.Va exec.poststop +command, before the jail(s) it depends on are stopped. +.El +.Sh EXAMPLES Jails are typically set up using one of two philosophies: either to constrain a specific application (possibly running with privilege), or to create a @@ -476,7 +750,6 @@ process. This manual page documents the configuration steps necessary to support either of these steps, although the configuration steps may be refined based on local requirements. -.Sh EXAMPLES .Ss "Setting up a Jail Directory Tree" To set up a jail directory tree containing an entire .Fx @@ -489,20 +762,8 @@ cd /usr/src mkdir -p $D make world DESTDIR=$D make distribution DESTDIR=$D -mount -t devfs devfs $D/dev .Ed .Pp -NOTE: It is important that only appropriate device nodes in devfs be -exposed to a jail; access to disk devices in the jail may permit processes -in the jail to bypass the jail sandboxing by modifying files outside of -the jail. -See -.Xr devfs 8 -for information on how to use devfs rules to limit access to entries -in the per-jail devfs. -A simple devfs ruleset for jails is available as ruleset #4 in -.Pa /etc/defaults/devfs.rules . -.Pp In many cases this example would put far more in the jail than needed. In the other extreme case a jail might contain only one file: the executable to be run in the jail. @@ -520,8 +781,9 @@ Do what was described in to build the jail directory tree. For the sake of this example, we will assume you built it in -.Pa /data/jail/192.0.2.100 , -named for the jailed IP address. +.Pa /data/jail/testjail , +for a jail named +.Dq testjail . Substitute below as needed with your own directory, IP address, and hostname. .Ss "Setting up the Host Environment" @@ -619,7 +881,7 @@ or for running a virtual server. .Pp Start a shell in the jail: .Bd -literal -offset indent -jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\ +jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\ ip4.addr=192.0.2.100 command=/bin/sh .Ed .Pp @@ -633,15 +895,6 @@ etc. .Pp .Bl -bullet -offset indent -compact .It -Create an empty -.Pa /etc/fstab -to quell startup warnings about missing fstab (virtual server only) -.It -Disable the port mapper -.Pa ( /etc/rc.conf : -.Li rpcbind_enable="NO" ) -(virtual server only) -.It Configure .Pa /etc/resolv.conf so that name resolution within the jail will work correctly @@ -652,11 +905,6 @@ to quell .Xr sendmail 8 warnings. .It -Disable interface configuration to quell startup warnings about -.Xr ifconfig 8 -.Pq Li network_interfaces="" -(virtual server only) -.It Set a root password, probably different from the real host system .It Set the timezone @@ -674,36 +922,47 @@ If you are not using a virtual server, y .Xr syslogd 8 in the host environment to listen on the syslog socket in the jail environment; in this example, the syslog socket would be stored in -.Pa /data/jail/192.0.2.100/var/run/log . +.Pa /data/jail/testjail/var/run/log . .Pp Exit from the shell, and the jail will be shut down. .Ss "Starting the Jail" You are now ready to restart the jail and bring up the environment with all of its daemons and other programs. -If you are running a single application in the jail, substitute the -command used to start the application for -.Pa /etc/rc -in the examples below. +Create an entry for the jail in +.Pa /etc/jail.conf : +.Bd -literal -offset indent +testjail { + path = /tmp/jail/testjail; + mount.devfs; + host.hostname = testhostname; + ip4.addr = 192.0.2.100; + interface = ed0; + exec.start = "/bin/sh /etc/rc"; + exec.stop = "/bin/sh /etc/rc.shutdown"; +} +.Ed +.Pp To start a virtual server environment, .Pa /etc/rc -is run to launch various daemons and services. -To do this, first bring up the -virtual host interface, and then start the jail's -.Pa /etc/rc -script from within the jail. +is run to launch various daemons and services, and +.Pa /etc/rc.shutdown +is run to shut them down when the jail is removed. +If you are running a single application in the jail, +substitute the command used to start the application for +.Dq /bin/sh /etc/rc ; +there may be some script available to cleanly shut down the application, +or it may be sufficient to go without a stop command, and have +.Nm +send +.Dv SIGTERM +to the application. +.Pp +Start the jail by running: .Bd -literal -offset indent -ifconfig ed0 inet alias 192.0.2.100/32 -mount -t procfs proc /data/jail/192.0.2.100/proc -jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\ - ip4.addr=192.0.2.100 command=/bin/sh /etc/rc +jail -c testjail .Ed .Pp -A few warnings will be produced, because most -.Xr sysctl 8 -configuration variables cannot be set from within the jail, as they are -global across all jails and the host environment. -However, it should all -work properly. +A few warnings may be produced; however, it should all work properly. You should be able to see .Xr inetd 8 , .Xr syslogd 8 , @@ -726,15 +985,6 @@ Please refer to the variables in .Xr rc.conf 5 for more information. -The -.Xr rc 8 -jail script provides a flexible system to start/stop jails: -.Bd -literal -/etc/rc.d/jail start -/etc/rc.d/jail stop -/etc/rc.d/jail start myjail -/etc/rc.d/jail stop myjail -.Ed .Ss "Managing the Jail" Normal machine shutdown commands, such as .Xr halt 8 , @@ -742,9 +992,8 @@ Normal machine shutdown commands, such a and .Xr shutdown 8 , cannot be used successfully within the jail. -To kill all processes in a -jail, you may log into the jail and, as root, use one of the following -commands, depending on what you want to accomplish: +To kill all processes from within a jail, you may use one of the +following commands, depending on what you want to accomplish: .Bd -literal -offset indent kill -TERM -1 *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205231529.q4NFTYZc080713>