1.\" Copyright (c) 2011-2015 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 September 2, 2015 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 but unlike Xr sysctl 8 , 140.Ql name+=value 141is supported for adding items to values 142.Pq see APPENDING VALUES 143and 144.Ql name-=value 145is supported for removing items from values 146.Pq see SUBTRACTING VALUES . 147.Pp 148However, while 149.Xr sysctl 8 150serves to query/modify MIBs in the entrant kernel, 151.Nm 152instead works on values in the system 153.Xr rc.conf 5 154configuration files. 155.Pp 156The list of system configuration files is configured in the file 157.Ql /etc/defaults/rc.conf 158within the variable 159.Ql rc_conf_files , 160which by-default contains a space-separated list of pathnames. 161On all FreeBSD 162systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local". 163Each 164pathname is sourced in-order upon startup. 165It is in the same fashion that 166.Nm 167sources the configuration files before returning the value of the given 168variable. 169.Pp 170When supplied a variable name, 171.Nm 172will return the value of the variable. 173If the variable does not appear in any 174of the configured 175.Ql rc_conf_files , 176an error is printed and error status is returned. 177.Pp 178When changing values of a given variable, it does not matter if the variable 179appears in any of the 180.Ql rc_conf_files 181or not. 182If the variable does not appear in any of the files, it is appended to 183the end of the first pathname in the 184.Ql rc_conf_files 185variable. 186Otherwise, 187.Nm 188will replace only the last-occurrence in the last-file found to contain the 189variable. 190This gets the value to take effect next boot without heavily 191modifying these integral files (yet taking care not to allow the file to 192grow unwieldy should 193.Nm 194be called repeatedly). 195.Sh APPENDING VALUES 196When using the 197.Ql key+=value 198syntax to add items to existing values, 199the first character of the value is taken as the delimiter separating items 200.Pq usually Qo \ Qc or Qo , Qc . 201For example, in the following statement: 202.Bl -item -offset indent 203.It 204.Nm 205cloned_interfaces+=" gif0" 206.El 207.Pp 208the first character is a space, informing 209.Nm 210that existing values are to be considered separated by whitespace. 211If 212.Ql gif0 213is not found in the existing value for 214.Va cloned_interfaces , 215it is added 216.Pq with delimiter only if existing value is non-NULL . 217.Pp 218For convenience, if the first character is alpha-numeric 219.Pq letters A-Z, a-z, or numbers 0-9 , 220.Nm 221uses the default setting of whitespace as separator. 222For example, the above and below statements are equivalent since 223.Dq gif0 224starts with an alpha-numeric character 225.Pq the letter Li g : 226.Bl -item -offset indent 227.It 228.Nm 229cloned_interfaces+=gif0 230.El 231.Pp 232Take the following sequence for example: 233.Bl -item -offset indent 234.It 235.Nm 236cloned_interfaces= # start with NULL 237.It 238.Nm 239cloned_interfaces+=gif0 240.Dl # NULL -> `gif0' Pq NB: no preceding delimiter 241.It 242.Nm 243cloned_interfaces+=gif0 # no change 244.It 245.Nm 246cloned_interfaces+="tun0 gif0" 247.Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication 248.El 249.Pp 250.Nm 251prevents the same value from being added if already there. 252.Sh SUBTRACTING VALUES 253When using the 254.Ql key-=value 255syntax to remove items from existing values, 256the first character of the value is taken as the delimiter separating items 257.Pq usually Qo \ Qc or Qo , Qc . 258For example, in the following statement: 259.Pp 260.Dl Nm cloned_interfaces-=" gif0" 261.Pp 262the first character is a space, informing 263.Nm 264that existing values are to be considered separated by whitespace. 265If 266.Ql gif0 267is found in the existing value for 268.Va cloned_interfaces , 269it is removed 270.Pq extra delimiters removed . 271.Pp 272For convenience, if the first character is alpha-numeric 273.Pq letters A-Z, a-z, or numbers 0-9 , 274.Nm 275uses the default setting of whitespace as separator. 276For example, the above and below statements are equivalent since 277.Dq gif0 278starts with an alpha-numeric character 279.Pq the letter Li g : 280.Bl -item -offset indent 281.It 282.Nm 283cloned_interfaces-=gif0 284.El 285.Pp 286Take the following sequence for example: 287.Bl -item -offset indent 288.It 289.Nm 290foo="bar baz" # start 291.It 292.Nm 293foo-=bar # `bar baz' -> `baz' 294.It 295.Nm 296foo-=baz # `baz' -> NULL 297.El 298.Pp 299.Nm 300removes all occurrences of all items provided 301and collapses extra delimiters between items. 302.Sh ENVIRONMENT 303The following environment variables are referenced by 304.Nm : 305.Bl -tag -width ".Ev RC_DEFAULTS" 306.It Ev RC_CONFS 307Override default 308.Ql rc_conf_files 309.Pq even if set to NULL . 310.It Ev RC_DEFAULTS 311Location of 312.Ql /etc/defaults/rc.conf 313file. 314.El 315.Sh DEPENDENCIES 316The following standard commands are required by 317.Nm : 318.Pp 319.Xr awk 1 , 320.Xr cat 1 , 321.Xr chmod 1 , 322.Xr env 1 , 323.Xr grep 1 , 324.Xr jls 1 , 325.Xr mktemp 1 , 326.Xr mv 1 , 327.Xr rm 1 , 328.Xr sh 1 , 329.Xr stat 1 , 330.Xr tail 1 , 331.Xr chown 8 332and 333.Xr jexec 8 . 334.Sh FILES 335.Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact 336.It Pa /etc/defaults/rc.conf 337.It Pa /etc/rc.conf 338.It Pa /etc/rc.conf.local 339.El 340.Sh EXAMPLES 341Below are some simple examples of how 342.Nm 343can be used to query certain values from the 344.Xr rc.conf 5 345collection of system configuration files: 346.Pp 347.Nm 348sshd_enable 349.Dl returns the value of $sshd_enable, usually YES or NO . 350.Pp 351.Nm 352defaultrouter 353.Dl returns IP address of default router Pq if configured . 354.Pp 355Working on other files, such as 356.Xr crontab 5 : 357.Pp 358.Nm 359-f /etc/crontab MAILTO 360.Dl returns the value of the MAILTO setting Pq if configured . 361.Pp 362Appending to existing values: 363.Pp 364.Nm 365\&cloned_interfaces+=gif0 366.Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES . 367.Pp 368.Nm 369\&cloned_interfaces-=gif0 370.Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES . 371.Pp 372In addition to the above syntax, 373.Nm 374also supports inline 375.Xr sh 1 376PARAMETER expansion for changing the way values are reported, shown below: 377.Pp 378.Nm 379\&'hostname%%.*' 380.Dl returns $hostname up to (but not including) first `.' . 381.Pp 382.Nm 383\&'network_interfaces%%[$IFS]*' 384.Dl returns first word of $network_interfaces . 385.Pp 386.Nm 387\&'ntpdate_flags##*[$IFS]' 388.Dl returns last word of $ntpdate_flags (time server address) . 389.Pp 390.Nm 391usbd_flags-"default" 392.Dl returns $usbd_flags or "default" if unset or NULL . 393.Pp 394.Nm 395cloned_interfaces+"alternate" 396.Dl returns "alternate" if $cloned_interfaces is set . 397.Sh SEE ALSO 398.Xr jls 1 , 399.Xr rc.conf 5 , 400.Xr jail 8 , 401.Xr jexec 8 , 402.Xr rc 8 , 403.Xr sysctl 8 404.Sh HISTORY 405A 406.Nm 407utility first appeared in 408.Fx 9.2 . 409.Sh AUTHORS 410.An Devin Teske Aq Mt dteske@FreeBSD.org 411.Sh THANKS TO 412Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek, 413Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker, 414Allan Jude, and Lars Engels for suggestions, help, and testing. 415