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