sysconf(8) · carta

NAME

sysconf – read and modify system configuration files

SYNOPSIS

sysconf target [-AcDeFinNqsvVx] [-j jail | -R dir] [-f file | -k module] name[[+|-]=value] ...

sysconf target [-ADeFnNqvV] [-j jail | -R dir] [-f file | -k module] -a

sysconf target [-AaDinNq] [-j jail | -R dir] -d [name ...]

sysconf target [-E] [-j jail | -R dir] [-k module] -l | -L

sysconf rc [sysrc_argument ...]

sysconf poudriere [--jail name] [--ports name] [--tree name] [--set name] [sysrc_argument ...]

sysconf poudriere {make|src|src-env} [-ceFinNqsvVx] [--jail name] [--ports name] [--tree name] [--set name] [-j jail | -R dir] [-f file] name[[+|-]=value] ...

sysconf poudriere {make|src|src-env} [-eFnNqvV] [--jail name] [--ports name] [--tree name] [--set name] [-f file] -a

sysconf poudriere {make|src|src-env} [-E] [--jail name] [--ports name] [--tree name] [--set name] [-f file] -l | -L

DESCRIPTION

The sysconf utility reads and modifies the system configuration files of the base system, completing the native configuration trinity alongside sysctl(8) (kernel state) and sysrc(8) (rc.conf(5)). The first positional argument selects a target keyword (or a unique prefix of one; see TARGETS); options are equally accepted before it. Each target is documented on its own page (see TARGETS); shared options and assignment syntax are documented here.

Assignment syntax

A name alone reads the current value of the directive, while name=value atomically writes it. Writes echo ‘name: old -> new’ when the stored value changes, or ‘name: value (unchanged)’ when it is already set as requested (the file is left untouched in that case). With -e those echoes use ‘name=...’ instead of ‘name: ...’ (matching read output). The echo is suppressed by -q; -c writes nothing to stdout. A directive not previously set anywhere shows an empty old value.

On the make and src targets, a ‘WITH_*’ or ‘WITHOUT_*’ build knob (presence matters; src.conf(5) ignores the value) is shown as ‘name (present)’ when defined( any value, including ‘=’ or ‘=t’), rather than printing the value after the colon; -e prints the real assignment( e.g. ‘name=’ or ‘name=t’), and -n prints that same value alone (empty when the assignment is ‘name=’). Setting such a knob with -s echoes ‘name: (not present) -> (present)’( or ‘(present) (unchanged)’ when it is already defined). An explicit name= (including empty) always writes the requested value; a change of placeholder while the knob stays defined echoes ‘name: old -> new’ like other assignments. A write of ‘WITH_foo=no’ (exact lowercase ‘no’) is still performed but warns to use ‘WITHOUT_foo=1’ instead. That message matches share/mk/bsd.mkopt.mk and is emitted here as a precursor so a bad make.conf(5) or src.conf(5) assignment is caught at write time. The same advisory is printed on reads( named queries and -a dump), with ‘file:line:’ when the authoritative statement is known, so an existing ‘WITH_*=no’ is not overlooked when presence display shows only ‘(present)’. -q suppresses the read-time form. make(1) itself typically warns later during a /usr/src build, when bsd.opts.mk (or src.opts.mk) reloads bsd.mkopt.mk for recognized options such as MANCOMPRESS. The same make.conf(5) line stays silent for a bare make(1) (e.g. -C /tmp) or for ports, which do not run that option pass. ‘WITHOUT_*=no’, ‘WITH_*=NO’, and other values do not warn here or there. WITHOUT_MODULES is not a presence knob (its value is a module list) and is excluded from -s and presence display.

For directives whose value is a space-separated list( kld_list-style; see for example kernels in loader.conf(5)), name+=word appends each given word not already present and name-=word strikes each given word, after the fashion of sysrc(8). Striking words from a directive set nowhere is reported like any other unknown directive.

For make(1)-syntax targets( make and src; see sysconf-make(8) and sysconf-src(8)), ‘+=’ is instead the make(1) append operator and ‘-=’ strikes words from the last matching assignment fragment.

Files are never modified in place: updates are streamed to a temporary file which is flushed to stable storage and atomically renamed over the target (see bsdconf_put(3)). How multi-file targets choose the file to read or rewrite is documented in sysconf-targets(8).

TARGETS

The following target keywords are supported:

loader: Boot loader configuration (loader.conf(5)). See sysconf-loader(8).
sysctl: Kernel state set at boot (sysctl.conf(5)). See sysconf-sysctl(8).
make: System-wide make(1) settings (/etc/make.conf). See sysconf-make(8).
src: The /usr/src build triad (src-env.conf, make.conf, src.conf). See sysconf-src(8).
rc: Pass-through to sysrc(8). See sysconf-rc(8).
poudriere: poudriere.conf collection via sysrc(8); poudriere make, poudriere src, and poudriere src-env for the make(1) overlays under poudriere.d. See sysconf-poudriere(8).
generic: Foreign or unknown format; requires -f. See sysconf-generic(8).

A unique prefix of a target keyword is accepted: ‘sy’ selects sysctl and ‘sr’ selects src. ‘s’ matches both and is rejected with a list of matches. An exact keyword always wins. Prefix matching is case-sensitive and applies to the start of the keyword only, so ‘ctl’ does not select sysctl.

Cross-cutting rules for multi-file sourcing, defaults, and where writes versus removals land are in sysconf-targets(8). Built-in format descriptors and file-list discovery are in bsdconf_format(3).

OPTIONS

The options are as follows:

-A

Widen dump scope to include directives still at their system default( named reads always reflect the defaults; see sysconf-targets(8)). With no name arguments, dumps everything( as -a, defaults included).

Combined with -D, the scoping of -D wins and -A retains only its dump-implying role, so ‘-ADd’ describes all defaults and only defaults, as in sysrc(8). Only valid for targets with a defaults file (see sysconf-loader(8)).

-a

Dump all configured directives from the target: the union of the target's files, wherein directives in later files override earlier ones. Directives whose value still comes from the defaults file alone are out of scope (widen with -A).

-c

Check mode. For each name=value argument, compare the effective value against value without modifying any file( with -x, check that name is absent). Exit with success if no changes would be required, else error.

-D

Consult only the target's defaults file, reporting the system default value of each name( or, with -a, dumping every default). Defaults are read-only; combining -D with an assignment is an error. Only valid for targets with a defaults file (see sysconf-loader(8)).

-d

Show the description of each name instead of its value.

For targets with a defaults file, the description is the inline comment trailing the directive's default assignment, continued across subsequent lines of whitespace followed by a comment character. A commented-out default (e.g., ‘#comconsole_speed="115200" # Set the ...’) still yields its description. For the ‘sysctl’ target, descriptions come from the running kernel( as with sysctl(8) -d; see sysconf-sysctl(8)).

Combined with -a, -A, or -D, dumps the description of every directive in scope( of the configured directives, of everything defaults included, or of the defaults alone, respectively), after the fashion of sysrc(8) -Ad. A directive the defaults never mention prints an empty description.

-E

With -l or -L, list only files that exist on disk.

-e

Print values in name=value format, suitable for feeding back into the configuration file. Applies to both reads and the informational echo from assignments( replacing the default ‘name: value’ form; changed writes use ‘name=old # -> new’, matching sysrc(8)). For the ‘loader’ target the value is quoted.

-F

Show the pathname of the file holding each directive's effective (authoritative) value instead of the value itself. For a directive still at its system default, this truthfully names the defaults file.

-f file

Operate on file, in the format of the target keyword, instead of the target's standard files; mutually exclusive with -k. For read operations file may be a non-seekable stream( a fifo or /dev/stdin, for example); write operations require a regular file. A file of ‘-’ means standard input (a synonym for /dev/stdin), exempt from -R. See sysconf-targets(8) and sysconf-generic(8).

-h, --help

Print a short usage statement (or, for the long form, the full option summary) to stderr and exit.

--version

Print sysconf and linked bsdconf(3) versions and exit.

-i

Ignore unknown names (and suppress the warning when writing an unknown sysctl OID).

-j jail

Operate within the jail jail (name or numeric id); mutually exclusive with -R.

-k module

Include the kernel module drop-in file for module in the target's file list (e.g., /etc/sysctl.kld.d/module.conf). Only valid for targets with a module drop-in directory (see sysconf-sysctl(8)).

-l

List the pathnames of the files backing the target, in sourcing order, and exit. The read-only defaults file is never listed( -l enumerates only files sysconf may modify; see sysconf-targets(8)).

-L

Like -l, but additionally list every drop-in candidate: for targets with a module drop-in directory, one candidate per loaded kernel module (whether or not the file exists yet) plus any drop-in already on disk. The read-only defaults file is likewise never listed.

-n

Show only directive values, not their names.

-N

Show only directive names, not their values.

-q

Quiet. Suppress warnings about unknown directives and the ‘old -> new’ echo of write operations.

-R dir

Operate within the root directory dir rather than /; mutually exclusive with -j.

-s

Set empty ‘WITH_*’ and ‘WITHOUT_*’ build knobs on the make and src targets( equivalent to name= with no value; see sysconf-make(8) and sysconf-src(8)). Each bare name must begin with ‘WITH_’ or ‘WITHOUT_’. An already-present knob (any value) is left unchanged by -s. An explicit name= including empty always writes. Mutually exclusive with -x.

-v

Verbose. Print the pathname of the configuration file holding the final effective value (the last file in sourcing order that assigned the directive).

-V

Trail. For each named read (and for -a), print every assignment step that contributed to the effective value: ‘file:line: nameopfragment’, and when the running effective value differs from the fragment, ‘-> effective’.

For writes, print the same ‘file:line:’ shape for the change: ‘file:line: name=old -> name=new’, ‘name=value (unchanged)’, ‘name=value (added)’ when a new statement is created, or ‘nameopfragment (removed)’ when a statement is deleted, using the statement operator ‘= / += / ...’ as appropriate .

Uses the same accumulation model as ordinary reads (make(1) `+=' et al.), so the last effective value matches -v and, for linear conf files without ‘.if’, make -V (see sysconf-make(8) and sysconf-src(8)).

-x

Remove the named directive(s) from every file of the target listing them (see sysconf-targets(8)). With -v or -V, a successful removal echoes ‘name (removed)’ (or a trail form with -V).

ENVIRONMENT

BSDCONF_MAX_BYTES: Maximum bytes sysconf will read from a configuration file or stream; see bsdconf(3).
LOADER_DEFAULTS: Defaults file for the ‘loader’ target; see sysconf-loader(8).
SRC_ENV_CONF, __MAKE_CONF, SRCCONF: Paths for the src triad; see sysconf-src(8).

FILES

See the per-target manuals (sysconf-loader(8), sysconf-sysctl(8), sysconf-make(8), sysconf-src(8)) for the files each keyword consults. Common paths include /boot/loader.conf, /etc/sysctl.conf, /etc/make.conf, and /etc/src.conf.

EXIT STATUS

The sysconf utility exits 0 on success, and >0 if an error occurs. In check mode (-c), an exit status of zero means no changes are required.

EXAMPLES

Read and set a boot loader directive:

sysconf loader zfs_load

sysconf loader zfs_load="YES"

Raise a sysctl applied at boot:

sysconf sysctl kern.maxfiles=65536

List files backing the loader target:

sysconf loader -l

Append to a space-separated list:

sysconf loader kernels+=kernel_test

Append a make(1) flag and set a src.conf knob:

sysconf make CFLAGS+=-DDEBUG

sysconf src -s WITHOUT_LLDB

sysconf src WITHOUT_LLDB=

Further examples for each target appear in sysconf-loader(8), sysconf-sysctl(8), sysconf-make(8), sysconf-src(8), sysconf-rc(8), sysconf-poudriere(8), and sysconf-generic(8).

HISTORY

The sysconf utility first appeared in FreeBSD 16.0.

AUTHORS

Devin Teske ⟨[email protected]⟩ Faraz Vahedi ⟨[email protected]⟩

SECURITY CONSIDERATIONS

Read-only invocations( including -c checks, which never modify files) run inside a capsicum(4) sandbox: the backing files are opened first and the process then relinquishes all other capabilities before any file content is parsed.

Write operations replace files atomically and never in place; see the SECURITY CONSIDERATIONS section of bsdconf_put(3) for the properties of the write transaction.