1.\" Copyright (c) 2011-2014 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd November 4, 2014 28.Dt SYSRC 8 29.Os 30.Sh NAME 31.Nm sysrc 32.Nd safely edit system rc files 33.Sh SYNOPSIS 34.Nm 35.Op Fl cdDeFhinNqvx 36.Op Fl f Ar file 37.Op Fl j Ar jail | Fl R Ar dir 38.Ar name Ns Op Ns Oo + Oc Ns = Ns Ar value 39.Ar ... 40.Nm 41.Op Fl cdDeFhinNqvx 42.Op Fl f Ar file 43.Op Fl j Ar jail | Fl R Ar dir 44.Fl a | A 45.Sh DESCRIPTION 46The 47.Nm 48utility retrieves 49.Xr rc.conf 5 50variables from the collection of system rc files and allows processes with 51appropriate privilege to change values in a safe and effective manner. 52.Pp 53The following options are available: 54.Bl -tag -width indent+ 55.It Fl a 56Dump a list of all non-default configuration variables. 57.It Fl A 58Dump a list of all configuration variables 59.Pq incl. defaults . 60.It Fl c 61Check only. 62For querying, return success if all requested variables are set 63.Pq even if NULL , 64otherwise return error status. 65For assignments, return success if no changes are required, otherwise failure. 66If verbose 67.Pq see Dq Fl v 68prints a message stating whether variables are set and/or changes are required. 69.It Fl d 70Print a description of the given variable. 71.It Fl D 72Show default value(s) only (this is the same as setting RC_CONFS to NULL or 73passing `-f' with a NULL file-argument). 74.It Fl e 75Print query results as 76.Xr sh 1 77compatible syntax 78.Pq for example, Ql var=value . 79Ignored if either 80.Ql Fl n 81or 82.Ql Fl F 83is specified. 84.It Fl f Ar file 85Operate on the specified file(s) instead of the files obtained by reading the 86.Sq rc_conf_files 87entry in the 88.Ev RC_DEFAULTS 89file. 90This option can be specified multiple times for additional files. 91.It Fl F 92Show only the last 93.Xr rc.conf 5 94file each directive is in. 95.It Fl h 96Print a short usage message to stderr and exit. 97.It Fl -help 98Print a full usage statement to stderr and exit. 99.It Fl i 100Ignore unknown variables. 101.It Fl j Ar jail 102The 103.Ar jid 104or name of the 105.Ar jail 106to operate within 107.Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 . 108.It Fl n 109Show only variable values, not their names. 110.It Fl N 111Show only variable names, not their values. 112.It Fl q 113Quiet. 114Disable verbose and hide certain errors. 115.It Fl R Ar dir 116Operate within the root directory 117.Sq Ar dir 118rather than 119.Sq / . 120.It Fl v 121Verbose. 122Print the pathname of the specific 123.Xr rc.conf 5 124file where the directive was found. 125.It Fl -version 126Print version information to stdout and exit. 127.It Fl x 128Remove variable(s) from specified file(s). 129.El 130.Pp 131This utility has a similar syntax to 132.Xr sysctl 8 . 133It shares the `-e' and `-n' options 134.Pq detailed above 135and also has the same 136.Ql name[=value] 137syntax for making queries/assignments. 138In addition 139.Pq unlike Xr sysctl 8 , 140.Ql name+=value 141is supported for appending values. 142.Pp 143However, while 144.Xr sysctl 8 145serves to query/modify MIBs in the entrant kernel, 146.Nm 147instead works on values in the system 148.Xr rc.conf 5 149configuration files. 150.Pp 151The list of system configuration files is configured in the file 152.Ql /etc/defaults/rc.conf 153within the variable 154.Ql rc_conf_files , 155which by-default contains a space-separated list of pathnames. 156On all FreeBSD 157systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local". 158Each 159pathname is sourced in-order upon startup. 160It is in the same fashion that 161.Nm 162sources the configuration files before returning the value of the given 163variable. 164.Pp 165When supplied a variable name, 166.Nm 167will return the value of the variable. 168If the variable does not appear in any 169of the configured 170.Ql rc_conf_files , 171an error is printed and error status is returned. 172.Pp 173When changing values of a given variable, it does not matter if the variable 174appears in any of the 175.Ql rc_conf_files 176or not. 177If the variable does not appear in any of the files, it is appended to 178the end of the first pathname in the 179.Ql rc_conf_files 180variable. 181Otherwise, 182.Nm 183will replace only the last-occurrence in the last-file found to contain the 184variable. 185This gets the value to take effect next boot without heavily 186modifying these integral files (yet taking care not to allow the file to 187grow unwieldy should 188.Nm 189be called repeatedly). 190.Sh ENVIRONMENT 191The following environment variables are referenced by 192.Nm : 193.Bl -tag -width ".Ev RC_DEFAULTS" 194.It Ev RC_CONFS 195Override default 196.Ql rc_conf_files 197.Pq even if set to NULL . 198.It Ev RC_DEFAULTS 199Location of 200.Ql /etc/defaults/rc.conf 201file. 202.El 203.Sh DEPENDENCIES 204The following standard commands are required by 205.Nm : 206.Pp 207.Xr awk 1 , 208.Xr cat 1 , 209.Xr chmod 1 , 210.Xr env 1 , 211.Xr grep 1 , 212.Xr jls 1 , 213.Xr mktemp 1 , 214.Xr mv 1 , 215.Xr rm 1 , 216.Xr sh 1 , 217.Xr stat 1 , 218.Xr tail 1 , 219.Xr chown 8 220and 221.Xr jexec 8 . 222.Sh FILES 223.Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact 224.It Pa /etc/defaults/rc.conf 225.It Pa /etc/rc.conf 226.It Pa /etc/rc.conf.local 227.El 228.Sh EXAMPLES 229Below are some simple examples of how 230.Nm 231can be used to query certain values from the 232.Xr rc.conf 5 233collection of system configuration files: 234.Pp 235.Nm 236sshd_enable 237.Dl returns the value of $sshd_enable, usually YES or NO . 238.Pp 239.Nm 240defaultrouter 241.Dl returns IP address of default router Pq if configured . 242.Pp 243Working on other files, such as 244.Xr crontab 5 : 245.Pp 246.Nm 247-f /etc/crontab MAILTO 248.Dl returns the value of the MAILTO setting Pq if configured . 249.Pp 250Appending to existing values: 251.Pp 252.Nm 253\&cloned_interfaces+=" gif0" 254.Dl appends Qo \ gif0 Qc to $cloned_interfaces . 255.Pp 256In addition to the above syntax, 257.Nm 258also supports inline 259.Xr sh 1 260PARAMETER expansion for changing the way values are reported, shown below: 261.Pp 262.Nm 263\&'hostname%%.*' 264.Dl returns $hostname up to (but not including) first `.' . 265.Pp 266.Nm 267\&'network_interfaces%%[$IFS]*' 268.Dl returns first word of $network_interfaces . 269.Pp 270.Nm 271\&'ntpdate_flags##*[$IFS]' 272.Dl returns last word of $ntpdate_flags (time server address) . 273.Pp 274.Nm 275usbd_flags-"default" 276.Dl returns $usbd_flags or "default" if unset or NULL . 277.Pp 278.Nm 279cloned_interfaces+"alternate" 280.Dl returns "alternate" if $cloned_interfaces is set . 281.Pp 282.Nm 283\&'#kern_securelevel' 284.Dl returns length in characters of $kern_securelevel . 285.Pp 286.Nm 287\&'hostname?' 288.Dl returns NULL and error status 2 if $hostname is unset Pq or if set, returns the value of $hostname with no error status . 289.Pp 290.Nm 291\&'hostname:?' 292.Dl returns NULL and error status 2 if $hostname is unset or NULL Pq or if set and non-NULL, returns value without error status . 293.Sh LIMITATIONS 294The 295.Nm 296utility presently does not support the 297.Ql rc.conf.d 298collection of system configuration files 299.Pq which requires a service name to be known during execution . 300.Pp 301This will be corrected by a future enhancement. 302.Sh SEE ALSO 303.Xr jls 1 , 304.Xr rc.conf 5 , 305.Xr jail 8 , 306.Xr jexec 8 , 307.Xr rc 8 , 308.Xr sysctl 8 309.Sh HISTORY 310A 311.Nm 312utility first appeared in 313.Fx 9.2 . 314.Sh AUTHORS 315.An Devin Teske Aq Mt dteske@FreeBSD.org 316.Sh THANKS TO 317Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek, 318Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker, 319Allan Jude, and Lars Engels for suggestions, help, and testing. 320