1 .\" Copyright (c) 2011-2015 Devin Teske
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
27 .Dd September 12, 2015
32 .Nd safely edit system rc files
38 .Op Fl j Ar jail | Fl R Ar dir
39 .Ar name Ns Op Ns Oo +|- Oc Ns = Ns Ar value
45 .Op Fl j Ar jail | Fl R Ar dir
61 variables from the collection of system rc files and allows processes with
62 appropriate privilege to change values in a safe and effective manner.
64 The following options are available:
65 .Bl -tag -width indent+
67 Dump a list of all non-default configuration variables.
69 Dump a list of all configuration variables
73 For querying, return success if all requested variables are set
75 otherwise return error status.
76 For assignments, return success if no changes are required, otherwise failure.
79 prints a message stating whether variables are set and/or changes are required.
81 Print a description of the given variable.
83 Show default value(s) only (this is the same as setting RC_CONFS to NULL or
84 passing `-f' with a NULL file-argument).
86 Print query results as
89 .Pq for example, Ql var=value .
100 to list configuration files, only list those that exist.
101 When changing a setting, prefer to modify existing files.
103 Operate on the specified file(s) instead of the files obtained by reading the
108 This option can be specified multiple times for additional files.
112 file each directive is in.
114 Print a short usage message to stderr and exit.
116 Print a full usage statement to stderr and exit.
118 Ignore unknown variables.
125 .Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 .
127 List configuration files used at startup on stdout and exit.
129 List all configuration files including rc.conf.d entries on stdout and exit.
134 to show service names.
136 exits with success if all named services are installed, failure otherwise.
138 Show only variable values, not their names.
140 Show only variable names, not their values.
143 Disable verbose and hide certain errors.
148 arguments, provide only exit status and no output.
150 Operate within the root directory
169 entries as potential overrides to
173 for additional information on
177 to list configuration files used by service at startup.
180 Print the pathname of the specific
182 file where the directive was found.
184 Print version information to stdout and exit.
186 Remove variable(s) from specified file(s).
189 This utility has a similar syntax to
191 It shares the `-e' and `-n' options
193 and also has the same
195 syntax for making queries/assignments.
197 .Pq but unlike Xr sysctl 8 ,
199 is supported for adding items to values
200 .Pq see APPENDING VALUES
203 is supported for removing items from values
204 .Pq see SUBTRACTING VALUES .
208 serves to query/modify MIBs in the entrant kernel,
210 instead works on values in the system
214 The list of system configuration files is configured in the file
215 .Ql /etc/defaults/rc.conf
218 which by-default contains a space-separated list of pathnames.
220 systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local".
222 pathname is sourced in-order upon startup.
223 It is in the same fashion that
225 sources the configuration files before returning the value of the given
228 When supplied a variable name,
230 will return the value of the variable.
231 If the variable does not appear in any
234 an error is printed and error status is returned.
236 When changing values of a given variable, it does not matter if the variable
237 appears in any of the
240 If the variable does not appear in any of the files, it is appended to
241 the end of the first pathname in the
246 will replace only the last-occurrence in the last-file found to contain the
248 This gets the value to take effect next boot without heavily
249 modifying these integral files (yet taking care not to allow the file to
252 be called repeatedly).
256 syntax to add items to existing values,
257 the first character of the value is taken as the delimiter separating items
258 .Pq usually Qo \ Qc or Qo , Qc .
259 For example, in the following statement:
260 .Bl -item -offset indent
263 cloned_interfaces+=" gif0"
266 the first character is a space, informing
268 that existing values are to be considered separated by whitespace.
271 is not found in the existing value for
272 .Va cloned_interfaces ,
274 .Pq with delimiter only if existing value is non-NULL .
276 For convenience, if the first character is alpha-numeric
277 .Pq letters A-Z, a-z, or numbers 0-9 ,
279 uses the default setting of whitespace as separator.
280 For example, the above and below statements are equivalent since
282 starts with an alpha-numeric character
283 .Pq the letter Li g :
284 .Bl -item -offset indent
287 cloned_interfaces+=gif0
290 Take the following sequence for example:
291 .Bl -item -offset indent
294 cloned_interfaces= # start with NULL
297 cloned_interfaces+=gif0
298 .Dl # NULL -> `gif0' Pq NB: no preceding delimiter
301 cloned_interfaces+=gif0 # no change
304 cloned_interfaces+="tun0 gif0"
305 .Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
309 prevents the same value from being added if already there.
310 .Sh SUBTRACTING VALUES
313 syntax to remove items from existing values,
314 the first character of the value is taken as the delimiter separating items
315 .Pq usually Qo \ Qc or Qo , Qc .
316 For example, in the following statement:
318 .Dl Nm cloned_interfaces-=" gif0"
320 the first character is a space, informing
322 that existing values are to be considered separated by whitespace.
325 is found in the existing value for
326 .Va cloned_interfaces ,
328 .Pq extra delimiters removed .
330 For convenience, if the first character is alpha-numeric
331 .Pq letters A-Z, a-z, or numbers 0-9 ,
333 uses the default setting of whitespace as separator.
334 For example, the above and below statements are equivalent since
336 starts with an alpha-numeric character
337 .Pq the letter Li g :
338 .Bl -item -offset indent
341 cloned_interfaces-=gif0
344 Take the following sequence for example:
345 .Bl -item -offset indent
348 foo="bar baz" # start
351 foo-=bar # `bar baz' -> `baz'
354 foo-=baz # `baz' -> NULL
358 removes all occurrences of all items provided
359 and collapses extra delimiters between items.
361 The following environment variables are referenced by
363 .Bl -tag -width ".Ev RC_DEFAULTS"
367 .Pq even if set to NULL .
370 .Ql /etc/defaults/rc.conf
374 The following standard commands are required by
393 .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact
394 .It Pa /etc/defaults/rc.conf
396 .It Pa /etc/rc.conf.local
397 .It Pa /etc/rc.conf.d/name
398 .It Pa /etc/rc.conf.d/name/*
399 .It Pa /usr/local/etc/rc.conf.d/name
400 .It Pa /usr/local/etc/rc.conf.d/name/*
403 Below are some simple examples of how
405 can be used to query certain values from the
407 collection of system configuration files:
411 .Dl returns the value of $sshd_enable, usually YES or NO .
415 .Dl returns IP address of default router Pq if configured .
417 Working on other files, such as
421 -f /etc/crontab MAILTO
422 .Dl returns the value of the MAILTO setting Pq if configured .
424 Appending to existing values:
427 \&cloned_interfaces+=gif0
428 .Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES .
431 \&cloned_interfaces-=gif0
432 .Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES .
434 In addition to the above syntax,
438 PARAMETER expansion for changing the way values are reported, shown below:
442 .Dl returns $hostname up to (but not including) first `.' .
445 \&'network_interfaces%%[$IFS]*'
446 .Dl returns first word of $network_interfaces .
449 \&'ntpdate_flags##*[$IFS]'
450 .Dl returns last word of $ntpdate_flags (time server address) .
454 .Dl returns $usbd_flags or "default" if unset or NULL .
457 cloned_interfaces+"alternate"
458 .Dl returns "alternate" if $cloned_interfaces is set .
470 utility first appeared in
473 .An Devin Teske Aq dteske@FreeBSD.org
475 Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek,
476 Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker,
477 Allan Jude, and Lars Engels for suggestions, help, and testing.