SYSRC(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 SYSRC(8) — the safe way to edit your rc files, bestie

okay so picture this: it's the System Manager's Manual, it's SYSRC(8), and it's literally here to help you not break your box. Think of it as the group-chat friend who says "bestie no, let me edit the config for you" — sysrc grabs rc.conf(5) variables from your system rc files and lets processes with the right privileges change values in a safe and effective way. no cap. 🎀

✨ SYNOPSIS ✨

sysrc [-cdDeEFhinNqvx] [-s name] [-f file] [-j jail | -R dir]
      name[[+|-]=value] ...
sysrc [-cdDeEFhinNqvx] [-s name] [-f file] [-j jail | -R dir] -a | -A
sysrc [-E] [-s name] [-f file] -l
sysrc [-eEqv] -L [name ...]

🌸 DESCRIPTION 🌸

The sysrc utility retrieves rc.conf(5) variables from the collection of system rc files and allows processes with appropriate privilege to change values in a safe and effective manner. that's the whole vibe. 🦋

The following options are available:

  • -a — Dump a list of all non-default configuration variables.
  • -A — Dump a list of all configuration variables (incl. defaults). yes, even the default ones, icon behaviour.
  • -c — Check only. For querying, return success if all requested variables are set (even if NULL), otherwise return error status. For assignments, return success if no changes are required, otherwise failure. If verbose (see -v) prints a message stating whether variables are set and/or changes are required. it's giving "are we good or not" energy 💀
  • -d — Print a description of the given variable.
  • -D — Show default value(s) only (this is the same as setting RC_CONFS to NULL or passing -f with a NULL file-argument).
  • -e — Print query results as sh(1) compatible syntax (for example, var=value). Ignored if either -n or -F is specified. so quotable 🫶
  • -E — When given -l or -L to list configuration files, only list those that exist. When changing a setting, prefer to modify existing files. exist only, periodt.
  • -f file — Operate on the specified file(s) instead of the files obtained by reading the rc_conf_files entry in the RC_DEFAULTS file. This option can be specified multiple times for additional files. stack 'em up 💅
  • -F — Show only the last rc.conf(5) file each directive is in.
  • -h — Print a short usage message to stderr and exit.
  • --help — Print a full usage statement to stderr and exit. the deluxe version, obviously ✨
  • -i — Ignore unknown variables. live your truth, skip the mystery names.
  • -j jail — The jid or name of the jail to operate within (overrides -R dir; requires jexec(8)).
  • -l — List configuration files used at startup on stdout and exit.
  • -L — List all configuration files including rc.conf.d entries on stdout and exit. Can be combined with -v or -e to show service names. sysrc exits with success if all named services are installed, failure otherwise.
  • -n — Show only variable values, not their names. names? never heard of her.
  • -N — Show only variable names, not their values.
  • -q — Quiet. Disable verbose and hide certain errors. When combined with -L and one or more name arguments, provide only exit status and no output. the strong silent type 😭
  • -R dir — Operate within the root directory dir rather than /.
  • -s name — If an rc.d script of name exists (in /etc/rc.d or local_startup directories), process its rc.conf.d entries as potential overrides to rc_conf_files. See rc.subr(8) for additional information on rc.conf.d. Can be combined with -l to list configuration files used by service at startup.
  • -v — Verbose. Print the pathname of the specific rc.conf(5) file where the directive was found. receipts! 🧾
  • --version — Print version information to stdout and exit.
  • -x — Remove variable(s) from specified file(s). bye bye 👋

This utility has a similar syntax to sysctl(8). It shares the -e and -n options (detailed above) and also has the same name[=value] syntax for making queries/assignments. In addition (but unlike sysctl(8)), name+=value is supported for adding items to values (see APPENDING VALUES) and name-=value is supported for removing items from values (see SUBTRACTING VALUES). we love a glow-up that keeps the family resemblance 💖

However, while sysctl(8) serves to query/modify MIBs in the entrant kernel, sysrc instead works on values in the system rc.conf(5) configuration files. different lane, same slay.

The list of system configuration files is configured in the file /etc/defaults/rc.conf within the variable rc_conf_files, which by-default contains a space-separated list of pathnames. On all FreeBSD systems, this defaults to the value /etc/rc.conf /etc/rc.conf.local. Each pathname is sourced in-order upon startup. It is in the same fashion that sysrc sources the configuration files before returning the value of the given variable.

When supplied a variable name, sysrc will return the value of the variable. If the variable does not appear in any of the configured rc_conf_files, an error is printed and error status is returned. rude but fair 💀

When changing values of a given variable, it does not matter if the variable appears in any of the rc_conf_files or not. If the variable does not appear in any of the files, it is appended to the end of the first pathname in the rc_conf_files variable. Otherwise, sysrc will replace only the last-occurrence in the last-file found to contain the variable. This gets the value to take effect next boot without heavily modifying these integral files (yet taking care not to allow the file to grow unwieldy should sysrc be called repeatedly). it's giving considerate queen behaviour 👑

🍓 APPENDING VALUES 🍓

When using the key+=value syntax to add items to existing values, the first character of the value is taken as the delimiter separating items (usually " " or ","). For example, in the following statement:

sysrc cloned_interfaces+=" gif0"

the first character is a space, informing sysrc that existing values are to be considered separated by whitespace. If gif0 is not found in the existing value for cloned_interfaces, it is added (with delimiter only if existing value is non-NULL).

For convenience, if the first character is alpha-numeric (letters A-Z, a-z, or numbers 0-9), dot (.), or slash (/), sysrc uses the default setting of whitespace as separator. For example, the above and below statements are equivalent since gif0 starts with an alpha-numeric character (the letter g):

sysrc cloned_interfaces+=gif0

Take the following sequence for example:

sysrc cloned_interfaces= # start with NULL

sysrc cloned_interfaces+=gif0
      # NULL -> `gif0' (NB: no preceding delimiter)

sysrc cloned_interfaces+=gif0 # no change

sysrc cloned_interfaces+="tun0 gif0"
      # `gif0' -> `gif0 tun0' (NB: no duplication)

sysrc prevents the same value from being added if already there. no duplicates in this house, we don't do that 🙈

🦋 SUBTRACTING VALUES 🦋

When using the key-=value syntax to remove items from existing values, the first character of the value is taken as the delimiter separating items (usually " " or ","). For example, in the following statement:

cloned_interfaces-=" gif0"

the first character is a space, informing sysrc that existing values are to be considered separated by whitespace. If gif0 is found in the existing value for cloned_interfaces, it is removed (extra delimiters removed).

For convenience, if the first character is alpha-numeric (letters A-Z, a-z, or numbers 0-9), dot (.), or slash (/), sysrc uses the default setting of whitespace as separator. For example, the above and below statements are equivalent since gif0 starts with an alpha-numeric character (the letter g):

sysrc cloned_interfaces-=gif0

Take the following sequence for example:

sysrc foo="bar baz" # start

sysrc foo-=bar # `bar baz' -> `baz'

sysrc foo-=baz # `baz' -> NULL

sysrc removes all occurrences of all items provided and collapses extra delimiters between items. clean sweep, honestly iconic 🧹✨

🌈 ENVIRONMENT 🌈

The following environment variables are referenced by sysrc:

  • RC_CONFS — Override default rc_conf_files (even if set to NULL). even NULL, she said what she said.
  • RC_DEFAULTS — Location of /etc/defaults/rc.conf file.

🎀 DEPENDENCIES 🎀

The following standard commands are required by sysrc:

awk(1), cat(1), chmod(1), env(1), grep(1), mktemp(1), mv(1), rm(1), sh(1), stat(1), tail(1), chown(8), chroot(8), jls(8), and jexec(8).

the whole squad. no solo missions here 🫶

⭐ FILES ⭐

/etc/defaults/rc.conf
/etc/rc.conf
/etc/rc.conf.local
/etc/rc.conf.d/name
/etc/rc.conf.d/name/*
/usr/local/etc/rc.conf.d/name
/usr/local/etc/rc.conf.d/name/*

💜 EXAMPLES 💜

Working with rc.conf files

Ask the value of sshd_enable, usually YES or NO:

sysrc sshd_enable

Return the IP address of default router (if configured):

sysrc defaultrouter

Working with other files

Return the value of the MAILTO setting, if configured, from crontab(5):

sysrc -f /etc/crontab MAILTO

Append gif0 to $cloned_interfaces (see APPENDING VALUES):

sysrc cloned_interfaces+=gif0

Remove gif0 from $cloned_interfaces (see SUBTRACTING VALUES):

sysrc cloned_interfaces-=gif0

Inline shell parameter expansion

Return $hostname up to, but not including, first .:

sysrc 'hostname%%.*'

Return first word of $network_interfaces:

sysrc 'network_interfaces%%[$IFS]*'

Return last word of $ntpdate_flags (time server address):

sysrc 'ntpdate_flags##*[$IFS]'

Return $usbd_flags or default if unset or NULL:

sysrc usbd_flags-"default"

Return alternate if $cloned_interfaces is set:

sysrc cloned_interfaces+"alternate"

👑 SEE ALSO 👑

rc.conf(5), jail(8), jexec(8), jls(8), rc(8), rc.subr(8), sysctl(8)

go read the whole cinematic universe bestie 📚

💀 HISTORY 💀

A sysrc utility first appeared in FreeBSD 9.2. an elder, a legend.

🔥 AUTHORS 🔥

Devin Teske <dteske@FreeBSD.org> — the main character, truly.

🌸 THANKS TO 🌸

Brandon Gooch, Enji Cooper, Julian Elischer, Pawel Jakub Dawidek, Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker, Allan Jude, and Lars Engels for suggestions, help, and testing. the whole support system, we stan 😭💖

and that's the page babes — this Debian edition of the manual is dated April 3, 2022, and you can find the source/version line right at the bottom of the og. now go forth and sysrc responsibly 🧚‍♀️🌟

📦 where this page comes from