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 February 2, 2016 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.Li 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 FreeBSD 220systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local". 221Each 222pathname is sourced in-order upon startup. 223It is in the same fashion that 224.Nm 225sources the configuration files before returning the value of the given 226variable. 227.Pp 228When supplied a variable name, 229.Nm 230will return the value of the variable. 231If the variable does not appear in any 232of the configured 233.Ql rc_conf_files , 234an error is printed and error status is returned. 235.Pp 236When changing values of a given variable, it does not matter if the variable 237appears in any of the 238.Ql rc_conf_files 239or not. 240If the variable does not appear in any of the files, it is appended to 241the end of the first pathname in the 242.Ql rc_conf_files 243variable. 244Otherwise, 245.Nm 246will replace only the last-occurrence in the last-file found to contain the 247variable. 248This gets the value to take effect next boot without heavily 249modifying these integral files (yet taking care not to allow the file to 250grow unwieldy should 251.Nm 252be called repeatedly). 253.Sh APPENDING VALUES 254When using the 255.Ql key+=value 256syntax to add items to existing values, 257the first character of the value is taken as the delimiter separating items 258.Pq usually Qo " " Qc or Qo , Qc . 259For example, in the following statement: 260.Bl -item -offset indent 261.It 262.Nm 263cloned_interfaces+=" gif0" 264.El 265.Pp 266the first character is a space, informing 267.Nm 268that existing values are to be considered separated by whitespace. 269If 270.Ql gif0 271is not found in the existing value for 272.Va cloned_interfaces , 273it is added 274.Pq with delimiter only if existing value is non-NULL . 275.Pp 276For convenience, if the first character is alpha-numeric 277.Pq letters A-Z, a-z, or numbers 0-9 , 278dot 279.Pq Li . , 280or slash 281.Pq Li / , 282.Nm 283uses the default setting of whitespace as separator. 284For example, the above and below statements are equivalent since 285.Dq gif0 286starts with an alpha-numeric character 287.Pq the letter Li g : 288.Bl -item -offset indent 289.It 290.Nm 291cloned_interfaces+=gif0 292.El 293.Pp 294Take the following sequence for example: 295.Bl -item -offset indent 296.It 297.Nm 298cloned_interfaces= # start with NULL 299.It 300.Nm 301cloned_interfaces+=gif0 302.Dl # NULL -> `gif0' Pq NB: no preceding delimiter 303.It 304.Nm 305cloned_interfaces+=gif0 # no change 306.It 307.Nm 308cloned_interfaces+="tun0 gif0" 309.Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication 310.El 311.Pp 312.Nm 313prevents the same value from being added if already there. 314.Sh SUBTRACTING VALUES 315When using the 316.Ql key-=value 317syntax to remove items from existing values, 318the first character of the value is taken as the delimiter separating items 319.Pq usually Qo " " Qc or Qo , Qc . 320For example, in the following statement: 321.Pp 322.Dl Nm cloned_interfaces-=" gif0" 323.Pp 324the first character is a space, informing 325.Nm 326that existing values are to be considered separated by whitespace. 327If 328.Ql gif0 329is found in the existing value for 330.Va cloned_interfaces , 331it is removed 332.Pq extra delimiters removed . 333.Pp 334For convenience, if the first character is alpha-numeric 335.Pq letters A-Z, a-z, or numbers 0-9 , 336dot 337.Pq Li . , 338or slash 339.Pq Li / , 340.Nm 341uses the default setting of whitespace as separator. 342For example, the above and below statements are equivalent since 343.Dq gif0 344starts with an alpha-numeric character 345.Pq the letter Li g : 346.Bl -item -offset indent 347.It 348.Nm 349cloned_interfaces-=gif0 350.El 351.Pp 352Take the following sequence for example: 353.Bl -item -offset indent 354.It 355.Nm 356foo="bar baz" # start 357.It 358.Nm 359foo-=bar # `bar baz' -> `baz' 360.It 361.Nm 362foo-=baz # `baz' -> NULL 363.El 364.Pp 365.Nm 366removes all occurrences of all items provided 367and collapses extra delimiters between items. 368.Sh ENVIRONMENT 369The following environment variables are referenced by 370.Nm : 371.Bl -tag -width ".Ev RC_DEFAULTS" 372.It Ev RC_CONFS 373Override default 374.Ql rc_conf_files 375.Pq even if set to NULL . 376.It Ev RC_DEFAULTS 377Location of 378.Ql /etc/defaults/rc.conf 379file. 380.El 381.Sh DEPENDENCIES 382The following standard commands are required by 383.Nm : 384.Pp 385.Xr awk 1 , 386.Xr cat 1 , 387.Xr chmod 1 , 388.Xr env 1 , 389.Xr grep 1 , 390.Xr mktemp 1 , 391.Xr mv 1 , 392.Xr rm 1 , 393.Xr sh 1 , 394.Xr stat 1 , 395.Xr tail 1 , 396.Xr chown 8 , 397.Xr jls 8 , 398and 399.Xr jexec 8 . 400.Sh FILES 401.Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact 402.It Pa /etc/defaults/rc.conf 403.It Pa /etc/rc.conf 404.It Pa /etc/rc.conf.local 405.It Pa /etc/rc.conf.d/name 406.It Pa /etc/rc.conf.d/name/* 407.It Pa /usr/local/etc/rc.conf.d/name 408.It Pa /usr/local/etc/rc.conf.d/name/* 409.El 410.Sh EXAMPLES 411Below are some simple examples of how 412.Nm 413can be used to query certain values from the 414.Xr rc.conf 5 415collection of system configuration files: 416.Pp 417.Nm 418sshd_enable 419.Dl returns the value of $sshd_enable, usually YES or NO . 420.Pp 421.Nm 422defaultrouter 423.Dl returns IP address of default router Pq if configured . 424.Pp 425Working on other files, such as 426.Xr crontab 5 : 427.Pp 428.Nm 429-f /etc/crontab MAILTO 430.Dl returns the value of the MAILTO setting Pq if configured . 431.Pp 432Appending to existing values: 433.Pp 434.Nm 435\&cloned_interfaces+=gif0 436.Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES . 437.Pp 438.Nm 439\&cloned_interfaces-=gif0 440.Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES . 441.Pp 442In addition to the above syntax, 443.Nm 444also supports inline 445.Xr sh 1 446PARAMETER expansion for changing the way values are reported, shown below: 447.Pp 448.Nm 449\&'hostname%%.*' 450.Dl returns $hostname up to (but not including) first `.' . 451.Pp 452.Nm 453\&'network_interfaces%%[$IFS]*' 454.Dl returns first word of $network_interfaces . 455.Pp 456.Nm 457\&'ntpdate_flags##*[$IFS]' 458.Dl returns last word of $ntpdate_flags (time server address) . 459.Pp 460.Nm 461usbd_flags-"default" 462.Dl returns $usbd_flags or "default" if unset or NULL . 463.Pp 464.Nm 465cloned_interfaces+"alternate" 466.Dl returns "alternate" if $cloned_interfaces is set . 467.Sh SEE ALSO 468.Xr rc.conf 5 , 469.Xr rc.subr 8 , 470.Xr jail 8 , 471.Xr jexec 8 , 472.Xr jls 8 , 473.Xr rc 8 , 474.Xr sysctl 8 475.Sh HISTORY 476A 477.Nm 478utility first appeared in 479.Fx 9.2 . 480.Sh AUTHORS 481.An Devin Teske Aq Mt dteske@FreeBSD.org 482.Sh THANKS TO 483Brandon Gooch, Ngie Cooper, Julian Elischer, Pawel Jakub Dawidek, 484Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker, 485Allan Jude, and Lars Engels for suggestions, help, and testing. 486