5fda0d60c1
This change allows to specify a watchdog(9) timeout for a system shutdown. The timeout is activated when the watchdogd daemon is stopped. The idea is to a prevent any indefinite hang during late stages of the shutdown. The feature is implemented in rc.d/watchdogd, it builds upon watchdogd -x option. Note that the shutdown timeout is not actiavted when the watchdogd service is individually stopped by an operator. It is also not activated for the 'shutdown' to the single-user mode. In those cases it is assumed that the operator knows what they are doing and they have means to recover the system should it hang. Significant subchanges and implementation details: - the argument to rc.shutdown, completely unused before, is assigned to rc_shutdown variable that can be inspected by rc scripts - init(8) passes "single" or "reboot" as the argument, this is not changed - the argument is not mandatory and if it is not set then rc_shutdown is set to "unspecified" - however, the default jail management scripts and jail configuration examples have been updated to pass "jail" to rc.shutdown, just in case - the new timeout can be set via watchdogd_shutdown_timeout rc option - for consistency, the regular timeout can now be set via watchdogd_timeout rc option - watchdogd_shutdown_timeout and watchdogd_timeout override timeout specifications in watchdogd_flags - existing configurations, where the new rc options are not set, should keep working as before I am not particularly wed to any of the implementation specifics. I am open to changing or removing any of them as long as the provided functionality is the same (or very close) to the proposed one. For example, I think it can be implemented without using watchdogd -x, by means of watchdog(1) alone. In that case there would be a small window between stopping watchdogd and running watchdog, but I think that that is acceptable. Reviewed by: bcr (man page changes) MFC after: 5 weeks Relnotes: yes Differential Revision: https://reviews.freebsd.org/D21221
232 lines
7.0 KiB
Groff
232 lines
7.0 KiB
Groff
.\" Copyright (c) 2012 James Gritton
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 6, 2019
|
|
.Dt JAIL.CONF 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm jail.conf
|
|
.Nd configuration file for
|
|
.Xr jail 8
|
|
.Sh DESCRIPTION
|
|
A
|
|
.Xr jail 8
|
|
configuration file consists of one or more jail definitions statements,
|
|
and parameter or variable statements within those jail definitions.
|
|
A jail definition statement looks something like a C compound statement.
|
|
A parameter statement looks like a C assignment,
|
|
including a terminating semicolon.
|
|
.Pp
|
|
The general syntax of a jail definition is:
|
|
.Bd -literal -offset indent
|
|
jailname {
|
|
parameter = "value";
|
|
parameter = "value";
|
|
...
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Each jail is required to have a
|
|
.Va name
|
|
at the front of its definition.
|
|
This is used by
|
|
.Xr jail 8
|
|
to specify a jail on the command line and report the jail status,
|
|
and is also passed to the kernel when creating the jail.
|
|
.Ss Parameters
|
|
A jail is defined by a set of named parameters, specified inside the
|
|
jail definition.
|
|
See
|
|
.Xr jail 8
|
|
for a list of jail parameters passed to the kernel,
|
|
as well as internal parameters used when creating and removing jails.
|
|
.Pp
|
|
A typical parameter has a name and a value.
|
|
Some parameters are boolean and may be specified with values of
|
|
.Dq true
|
|
or
|
|
.Dq false ,
|
|
or as valueless shortcuts, with a
|
|
.Dq no
|
|
prefix indicating a false value.
|
|
For example, these are equivalent:
|
|
.Bd -literal -offset indent
|
|
allow.mount = "false";
|
|
allow.nomount;
|
|
.Ed
|
|
.Pp
|
|
Other parameters may have more than one value.
|
|
A comma-separated list of values may be set in a single statement,
|
|
or an existing parameter list may be appended to using
|
|
.Dq += :
|
|
.Bd -literal -offset indent
|
|
ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
|
|
|
|
ip4.addr = 10.1.1.1;
|
|
ip4.addr += 10.1.1.2;
|
|
ip4.addr += 10.1.1.3;
|
|
.Ed
|
|
.Pp
|
|
Note the
|
|
.Va name
|
|
parameter is implicitly set to the name in the jail definition.
|
|
.Ss String format
|
|
Parameter values, including jail names, can be single tokens or quoted
|
|
strings.
|
|
A token is any sequence of characters that aren't considered special in
|
|
the syntax of the configuration file (such as a semicolon or
|
|
whitespace).
|
|
If a value contains anything more than letters, numbers, dots, dashes
|
|
and underscores, it is advisable to put quote marks around that value.
|
|
Either single or double quotes may be used.
|
|
.Pp
|
|
Special characters may be quoted by preceding them with a backslash.
|
|
Common C-style backslash character codes are also supported, including
|
|
control characters and octal or hex ASCII codes.
|
|
A backslash at the end of a line will ignore the subsequent newline and
|
|
continue the string at the start of the next line.
|
|
.Ss Variables
|
|
A string may use shell-style variable substitution.
|
|
A parameter or variable name preceded by a dollar sign, and possibly
|
|
enclosed in braces, will be replaced with the value of that parameter or
|
|
variable.
|
|
For example, a jail's path may be defined in terms of its name or
|
|
hostname:
|
|
.Bd -literal -offset indent
|
|
path = "/var/jail/$name";
|
|
|
|
path = "/var/jail/${host.hostname}";
|
|
.Ed
|
|
.Pp
|
|
Variable substitution occurs in unquoted tokens or in double-quoted
|
|
strings, but not in single-quote strings.
|
|
.Pp
|
|
A variable is defined in the same way a parameter is, except that the
|
|
variable name is preceded with a dollar sign:
|
|
.Bd -literal -offset indent
|
|
$parentdir = "/var/jail";
|
|
path = "$parentdir/$name";
|
|
.Ed
|
|
.Pp
|
|
The difference between parameters and variables is that variables are
|
|
only used for substitution, while parameters are used both for
|
|
substitution and for passing to the kernel.
|
|
.Ss Wildcards
|
|
A jail definition with a name of
|
|
.Dq *
|
|
is used to define wildcard parameters.
|
|
Every defined jail will contain both the parameters from its own
|
|
definition statement, as well as any parameters in a wildcard
|
|
definition.
|
|
.Pp
|
|
Variable substitution is done on a per-jail basis, even when that
|
|
substitution is for a parameter defined in a wildcard section.
|
|
This is useful for wildcard parameters based on e.g. a jail's name.
|
|
.Pp
|
|
Later definitions in the configuration file supersede earlier ones, so a
|
|
wildcard section placed before (above) a jail definition defines
|
|
parameters that could be changed on a per-jail basis.
|
|
Or a wildcard section placed after (below) all jails would contain
|
|
parameters that always apply to every jail.
|
|
Multiple wildcard statements are allowed, and wildcard parameters may
|
|
also be specified outside of a jail definition statement.
|
|
.Pp
|
|
If hierarchical jails are defined, a partial-matching wildcard
|
|
definition may be specified.
|
|
For example, a definition with a name of
|
|
.Dq foo.*
|
|
would apply to jails with names like
|
|
.Dq foo.bar
|
|
and
|
|
.Dq foo.bar.baz .
|
|
.Ss Comments
|
|
The configuration file may contain comments in the common C, C++, and
|
|
shell formats:
|
|
.Bd -literal -offset indent
|
|
/* This is a C style comment.
|
|
* It may span multiple lines.
|
|
*/
|
|
|
|
// This is a C++ style comment.
|
|
|
|
# This is a shell style comment.
|
|
.Ed
|
|
.Pp
|
|
Comments are legal wherever whitespace is allowed, i.e. anywhere except
|
|
in the middle of a string or a token.
|
|
.Sh EXAMPLES
|
|
.Bd -literal
|
|
# Typical static defaults:
|
|
# Use the rc scripts to start and stop jails. Mount jail's /dev.
|
|
exec.start = "/bin/sh /etc/rc";
|
|
exec.stop = "/bin/sh /etc/rc.shutdown jail";
|
|
exec.clean;
|
|
mount.devfs;
|
|
|
|
# Dynamic wildcard parameter:
|
|
# Base the path off the jail name.
|
|
path = "/var/jail/$name";
|
|
|
|
# A typical jail.
|
|
foo {
|
|
host.hostname = "foo.com";
|
|
ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
|
|
}
|
|
|
|
# This jail overrides the defaults defined above.
|
|
bar {
|
|
exec.start = '';
|
|
exec.stop = '';
|
|
path = /;
|
|
mount.nodevfs;
|
|
persist; // Required because there are no processes
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr jail_set 2 ,
|
|
.Xr rc.conf 5 ,
|
|
.Xr jail 8 ,
|
|
.Xr jls 8
|
|
.Sh HISTORY
|
|
The
|
|
.Xr jail 8
|
|
utility appeared in
|
|
.Fx 4.0 .
|
|
The
|
|
.Nm
|
|
file was added in
|
|
.Fx 9.1 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The jail feature was written by
|
|
.An Poul-Henning Kamp
|
|
for R&D Associates
|
|
who contributed it to
|
|
.Fx .
|
|
.Pp
|
|
.An James Gritton
|
|
added the extensible jail parameters and configuration file.
|