1.\" Copyright (c) 2011-2016 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 April 3, 2022 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 cdDeEFhinNqvx 36.Op Fl s Ar name 37.Op Fl f Ar file 38.Op Fl j Ar jail | Fl R Ar dir 39.Ar name Ns Op Ns Oo +|- Oc Ns = Ns Ar value 40.Ar ... 41.Nm 42.Op Fl cdDeEFhinNqvx 43.Op Fl s Ar name 44.Op Fl f Ar file 45.Op Fl j Ar jail | Fl R Ar dir 46.Fl a | A 47.Nm 48.Op Fl E 49.Op Fl s Ar name 50.Op Fl f Ar file 51.Fl l 52.Nm 53.Op Fl eEqv 54.Fl L 55.Op Ar name ... 56.Sh DESCRIPTION 57The 58.Nm 59utility retrieves 60.Xr rc.conf 5 61variables from the collection of system rc files and allows processes with 62appropriate privilege to change values in a safe and effective manner. 63.Pp 64The following options are available: 65.Bl -tag -width indent+ 66.It Fl a 67Dump a list of all non-default configuration variables. 68.It Fl A 69Dump a list of all configuration variables 70.Pq incl. defaults . 71.It Fl c 72Check only. 73For querying, return success if all requested variables are set 74.Pq even if NULL , 75otherwise return error status. 76For assignments, return success if no changes are required, otherwise failure. 77If verbose 78.Pq see Dq Fl v 79prints a message stating whether variables are set and/or changes are required. 80.It Fl d 81Print a description of the given variable. 82.It Fl D 83Show default value(s) only (this is the same as setting RC_CONFS to NULL or 84passing `-f' with a NULL file-argument). 85.It Fl e 86Print query results as 87.Xr sh 1 88compatible syntax 89.Pq for example, Ql var=value . 90Ignored if either 91.Ql Fl n 92or 93.Ql Fl F 94is specified. 95.It Fl E 96When given 97.Sq Fl l 98or 99.Sq Fl L 100to list configuration files, only list those that exist. 101When changing a setting, prefer to modify existing files. 102.It Fl f Ar file 103Operate on the specified file(s) instead of the files obtained by reading the 104.Sq rc_conf_files 105entry in the 106.Ev RC_DEFAULTS 107file. 108This option can be specified multiple times for additional files. 109.It Fl F 110Show only the last 111.Xr rc.conf 5 112file each directive is in. 113.It Fl h 114Print a short usage message to stderr and exit. 115.It Fl -help 116Print a full usage statement to stderr and exit. 117.It Fl i 118Ignore unknown variables. 119.It Fl j Ar jail 120The 121.Ar jid 122or name of the 123.Ar jail 124to operate within 125.Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 . 126.It Fl l 127List configuration files used at startup on stdout and exit. 128.It Fl L 129List all configuration files including rc.conf.d entries on stdout and exit. 130Can be combined with 131.Sq Fl v 132or 133.Sq Fl e 134to show service names. 135.Nm 136exits with success if all named services are installed, failure otherwise. 137.It Fl n 138Show only variable values, not their names. 139.It Fl N 140Show only variable names, not their values. 141.It Fl q 142Quiet. 143Disable verbose and hide certain errors. 144When combined with 145.Sq Fl L 146and one or more 147.Ar name 148arguments, provide only exit status and no output. 149.It Fl R Ar dir 150Operate within the root directory 151.Sq Ar dir 152rather than 153.Sq / . 154.It Fl s Ar name 155If an 156.Li rc.d 157script of 158.Ar name 159exists 160.Po 161in 162.Dq /etc/rc.d 163or 164.Li local_startup 165directories 166.Pc , 167process its 168.Dq rc.conf.d 169entries as potential overrides to 170.Sq rc_conf_files . 171See 172.Xr rc.subr 8 173for additional information on 174.Dq rc.conf.d . 175Can be combined with 176.Sq Fl l 177to list configuration files used by service at startup. 178.It Fl v 179Verbose. 180Print the pathname of the specific 181.Xr rc.conf 5 182file where the directive was found. 183.It Fl -version 184Print version information to stdout and exit. 185.It Fl x 186Remove variable(s) from specified file(s). 187.El 188.Pp 189This utility has a similar syntax to 190.Xr sysctl 8 . 191It shares the `-e' and `-n' options 192.Pq detailed above 193and also has the same 194.Ql name[=value] 195syntax for making queries/assignments. 196In addition 197.Pq but unlike Xr sysctl 8 , 198.Ql name+=value 199is supported for adding items to values 200.Pq see APPENDING VALUES 201and 202.Ql name-=value 203is supported for removing items from values 204.Pq see SUBTRACTING VALUES . 205.Pp 206However, while 207.Xr sysctl 8 208serves to query/modify MIBs in the entrant kernel, 209.Nm 210instead works on values in the system 211.Xr rc.conf 5 212configuration files. 213.Pp 214The list of system configuration files is configured in the file 215.Ql /etc/defaults/rc.conf 216within the variable 217.Ql rc_conf_files , 218which by-default contains a space-separated list of pathnames. 219On all 220.Fx 221systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local". 222Each 223pathname is sourced in-order upon startup. 224It is in the same fashion that 225.Nm 226sources the configuration files before returning the value of the given 227variable. 228.Pp 229When supplied a variable name, 230.Nm 231will return the value of the variable. 232If the variable does not appear in any 233of the configured 234.Ql rc_conf_files , 235an error is printed and error status is returned. 236.Pp 237When changing values of a given variable, it does not matter if the variable 238appears in any of the 239.Ql rc_conf_files 240or not. 241If the variable does not appear in any of the files, it is appended to 242the end of the first pathname in the 243.Ql rc_conf_files 244variable. 245Otherwise, 246.Nm 247will replace only the last-occurrence in the last-file found to contain the 248variable. 249This gets the value to take effect next boot without heavily 250modifying these integral files (yet taking care not to allow the file to 251grow unwieldy should 252.Nm 253be called repeatedly). 254.Sh APPENDING VALUES 255When using the 256.Ql key+=value 257syntax to add items to existing values, 258the first character of the value is taken as the delimiter separating items 259.Pq usually Qo " " Qc or Qo , Qc . 260For example, in the following statement: 261.Bl -item -offset indent 262.It 263.Nm 264cloned_interfaces+=" gif0" 265.El 266.Pp 267the first character is a space, informing 268.Nm 269that existing values are to be considered separated by whitespace. 270If 271.Ql gif0 272is not found in the existing value for 273.Va cloned_interfaces , 274it is added 275.Pq with delimiter only if existing value is non-NULL . 276.Pp 277For convenience, if the first character is alpha-numeric 278.Pq letters A-Z, a-z, or numbers 0-9 , 279dot 280.Pq Li \&. , 281or slash 282.Pq Li / , 283.Nm 284uses the default setting of whitespace as separator. 285For example, the above and below statements are equivalent since 286.Dq gif0 287starts with an alpha-numeric character 288.Pq the letter Li g : 289.Bl -item -offset indent 290.It 291.Nm 292cloned_interfaces+=gif0 293.El 294.Pp 295Take the following sequence for example: 296.Bl -item -offset indent 297.It 298.Nm 299cloned_interfaces= # start with NULL 300.It 301.Nm 302cloned_interfaces+=gif0 303.Dl # NULL -> `gif0' Pq NB: no preceding delimiter 304.It 305.Nm 306cloned_interfaces+=gif0 # no change 307.It 308.Nm 309cloned_interfaces+="tun0 gif0" 310.Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication 311.El 312.Pp 313.Nm 314prevents the same value from being added if already there. 315.Sh SUBTRACTING VALUES 316When using the 317.Ql key-=value 318syntax to remove items from existing values, 319the first character of the value is taken as the delimiter separating items 320.Pq usually Qo " " Qc or Qo , Qc . 321For example, in the following statement: 322.Pp 323.Dl Nm cloned_interfaces-=" gif0" 324.Pp 325the first character is a space, informing 326.Nm 327that existing values are to be considered separated by whitespace. 328If 329.Ql gif0 330is found in the existing value for 331.Va cloned_interfaces , 332it is removed 333.Pq extra delimiters removed . 334.Pp 335For convenience, if the first character is alpha-numeric 336.Pq letters A-Z, a-z, or numbers 0-9 , 337dot 338.Pq Li \&. , 339or slash 340.Pq Li / , 341.Nm 342uses the default setting of whitespace as separator. 343For example, the above and below statements are equivalent since 344.Dq gif0 345starts with an alpha-numeric character 346.Pq the letter Li g : 347.Bl -item -offset indent 348.It 349.Nm 350cloned_interfaces-=gif0 351.El 352.Pp 353Take the following sequence for example: 354.Bl -item -offset indent 355.It 356.Nm 357foo="bar baz" # start 358.It 359.Nm 360foo-=bar # `bar baz' -> `baz' 361.It 362.Nm 363foo-=baz # `baz' -> NULL 364.El 365.Pp 366.Nm 367removes all occurrences of all items provided 368and collapses extra delimiters between items. 369.Sh ENVIRONMENT 370The following environment variables are referenced by 371.Nm : 372.Bl -tag -width ".Ev RC_DEFAULTS" 373.It Ev RC_CONFS 374Override default 375.Ql rc_conf_files 376.Pq even if set to NULL . 377.It Ev RC_DEFAULTS 378Location of 379.Ql /etc/defaults/rc.conf 380file. 381.El 382.Sh DEPENDENCIES 383The following standard commands are required by 384.Nm : 385.Pp 386.Xr awk 1 , 387.Xr cat 1 , 388.Xr chmod 1 , 389.Xr env 1 , 390.Xr grep 1 , 391.Xr mktemp 1 , 392.Xr mv 1 , 393.Xr rm 1 , 394.Xr sh 1 , 395.Xr stat 1 , 396.Xr tail 1 , 397.Xr chown 8 , 398.Xr chroot 8 , 399.Xr jls 8 , 400and 401.Xr jexec 8 . 402.Sh FILES 403.Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact 404.It Pa /etc/defaults/rc.conf 405.It Pa /etc/rc.conf 406.It Pa /etc/rc.conf.local 407.It Pa /etc/rc.conf.d/name 408.It Pa /etc/rc.conf.d/name/* 409.It Pa /usr/local/etc/rc.conf.d/name 410.It Pa /usr/local/etc/rc.conf.d/name/* 411.El 412.Sh EXAMPLES 413Below are some simple examples of how 414.Nm 415can be used to query certain values from the 416.Xr rc.conf 5 417collection of system configuration files: 418.Pp 419.Nm 420sshd_enable 421.Dl returns the value of $sshd_enable, usually YES or NO . 422.Pp 423.Nm 424defaultrouter 425.Dl returns IP address of default router Pq if configured . 426.Pp 427Working on other files, such as 428.Xr crontab 5 : 429.Pp 430.Nm 431-f /etc/crontab MAILTO 432.Dl returns the value of the MAILTO setting Pq if configured . 433.Pp 434Appending to existing values: 435.Pp 436.Nm 437\&cloned_interfaces+=gif0 438.Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES . 439.Pp 440.Nm 441\&cloned_interfaces-=gif0 442.Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES . 443.Pp 444In addition to the above syntax, 445.Nm 446also supports inline 447.Xr sh 1 448PARAMETER expansion for changing the way values are reported, shown below: 449.Pp 450.Nm 451\&'hostname%%.*' 452.Dl returns $hostname up to (but not including) first `.' . 453.Pp 454.Nm 455\&'network_interfaces%%[$IFS]*' 456.Dl returns first word of $network_interfaces . 457.Pp 458.Nm 459\&'ntpdate_flags##*[$IFS]' 460.Dl returns last word of $ntpdate_flags (time server address) . 461.Pp 462.Nm 463usbd_flags-"default" 464.Dl returns $usbd_flags or "default" if unset or NULL . 465.Pp 466.Nm 467cloned_interfaces+"alternate" 468.Dl returns "alternate" if $cloned_interfaces is set . 469.Sh SEE ALSO 470.Xr rc.conf 5 , 471.Xr jail 8 , 472.Xr jexec 8 , 473.Xr jls 8 , 474.Xr rc 8 , 475.Xr rc.subr 8 , 476.Xr sysctl 8 477.Sh HISTORY 478A 479.Nm 480utility first appeared in 481.Fx 9.2 . 482.Sh AUTHORS 483.An Devin Teske Aq Mt dteske@FreeBSD.org 484.Sh THANKS TO 485Brandon Gooch, Enji Cooper, Julian Elischer, Pawel Jakub Dawidek, 486Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker, 487Allan Jude, and Lars Engels for suggestions, help, and testing. 488