Date: Mon, 11 Mar 2013 03:30:26 GMT From: Tom <trh411@gmail.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/176832: Proposed changes to jail.8 man page Message-ID: <201303110330.r2B3UQPu024540@red.freebsd.org> Resent-Message-ID: <201303110340.r2B3e0Cb004336@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 176832 >Category: docs >Synopsis: Proposed changes to jail.8 man page >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Mon Mar 11 03:40:00 UTC 2013 >Closed-Date: >Last-Modified: >Originator: Tom >Release: 9.1-RELEASE GENERIC >Organization: N/A >Environment: FreeBSD imacfbsd 9.1-RELEASE FreeBSD 9.1-RELEASE #0 r243825: Tue Dec 4 09:23:10 UTC 2012 root@farrell.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC amd64 >Description: Proposing the following changes to the jail.8 man page (r248141): 1) switch the order of the 'jail -c' and 'jail -r' commands in the description of the -rc option since as ordered they would do just the opposite of what the text states. 2) change all 30 instances of the word 'prison' to 'jail'. The word 'jail' is used 256 times in the man page, the word 'prison' is used 30 times. Since there does not seem to be any special meaning to the word 'prison' in the context of a jail, the text should consistently use the word 'jail' to refer to a 'jail' or its attributes. >How-To-Repeat: >Fix: See attached patch. Patch attached with submission follows: --- /usr/src/usr.sbin/jail/jail.8 2012-12-03 16:22:40.000000000 -0500 +++ jail.8 2013-03-10 23:09:24.000000000 -0400 @@ -102,9 +102,9 @@ .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 +and +.Dq Nm Fl c were run in succession. .It Fl cm Create a jail if it does not exist, or modify the jail if it does exist. @@ -134,7 +134,7 @@ parameter (or .Va hostname ) and add all IP addresses returned by the resolver -to the list of addresses for this prison. +to the list of addresses for this jail. This is equivalent to the .Va ip_hostname parameter. @@ -314,14 +314,14 @@ 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 +The directory which is to be the root of the jail. +Any commands run inside the jail, either by .Nm or from .Xr jexec 8 , are run from this directory. .It Va ip4.addr -A list of IPv4 addresses assigned to the prison. +A list of IPv4 addresses assigned to the jail. 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. @@ -333,7 +333,7 @@ assigned to itself. .It Va ip4.saddrsel A boolean option to change the formerly mentioned behaviour and disable -IPv4 source address selection for the prison in favour of the primary +IPv4 source address selection for the jail in favour of the primary IPv4 address of the jail. Source address selection is enabled by default for all jails and the .Va ip4.nosaddrsel @@ -354,14 +354,14 @@ parameter implies a value of .Dq new . .It Va ip6.addr , Va ip6.saddrsel , Va ip6 -A set of IPv6 options for the prison, the counterparts to +A set of IPv6 options for the jail, the counterparts to .Va ip4.addr , .Va ip4.saddrsel and .Va ip4 above. .It vnet -Create the prison with its own virtual network stack, +Create the jail 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 @@ -373,7 +373,7 @@ .Dq new to create a new network stack. .It Va host.hostname -The hostname of the prison. +The hostname of the jail. Other similar parameters are .Va host.domainname , .Va host.hostuuid @@ -488,12 +488,12 @@ within a jail would be able to communicate with (and potentially interfere with) processes outside of the jail, and in other jails. .It Va allow.raw_sockets -The prison root is allowed to create raw sockets. +The jail root is allowed to create raw sockets. Setting this parameter allows utilities like .Xr ping 8 and .Xr traceroute 8 -to operate inside the prison. +to operate inside the jail. If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail, regardless of whether or not the @@ -558,7 +558,7 @@ for information on how to configure the ZFS filesystem to operate from within a jail. .It Va allow.quotas -The prison root may administer quotas on the jail's filesystem(s). +The jail root may administer quotas on the jail's filesystem(s). This includes filesystems that the jail may share with other jails or with non-jailed parts of the system. .It Va allow.socket_af @@ -571,13 +571,13 @@ 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 +to set up the jail 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. +command lines that are run in either the system or jail environment. They may be given multiple values, which run would the specified commands in sequence. All commands must succeed (return a zero exit status), or the jail will @@ -586,15 +586,15 @@ 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. +Command(s) to run in the system environment before a jail is created. .It Va exec.start -Command(s) to run in the prison environment when a jail is created. +Command(s) to run in the jail 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. +for use when specifying a jail directly on the command line. Unlike other parameters whose value is a single string, .Va command uses the remainder of the @@ -608,7 +608,7 @@ .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, +Command(s) to run in the jail environment before a jail is removed, and after any .Va exec.prestop commands have completed. @@ -633,14 +633,14 @@ 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 user to run commands as, when running in the jail 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. +file, instead of in the jail'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. @@ -651,29 +651,29 @@ .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. +The FIB (routing table) to set when running commands inside the jail. .It Va stop.timeout -The maximum amount of time to wait for a prison's processes to exit +The maximum amount of time to wait for a jail'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 +After this many seconds have passed, the jail 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. +is sent and the jail is immediately removed. The default is 10 seconds. .It Va interface -A network interface to add the prison's IP addresses +A network interface to add the jail'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. +jail is created, and will be removed from the interface after the +jail 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 @@ -698,9 +698,9 @@ .Va ( ip4.addr or .Va ip6.addr ) -for this prison. +for this jail. This may affect default address selection for outgoing IPv4 connections -of prisons. +of jails. The address first returned by the resolver for each address family will be used as primary address. .It Va mount @@ -718,7 +718,7 @@ 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. +to restrict the devices visible inside the jail. .It Va allow.dying Allow making changes to a .Va dying @@ -1081,7 +1081,7 @@ .Pp The variable .Va security.jail.max_af_ips -determines how may address per address family a prison may have. +determines how may address per address family a jail may have. The default is 255. .Pp Some MIB variables have per-jail settings. >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201303110330.r2B3UQPu024540>