xref: /freebsd/usr.sbin/sysrc/sysrc.8 (revision 0fca6ea1d4eea4c934cfff25ac9ee8ad6fe95583)
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.Dd April 3, 2022
26.Dt SYSRC 8
27.Os
28.Sh NAME
29.Nm sysrc
30.Nd safely edit system rc files
31.Sh SYNOPSIS
32.Nm
33.Op Fl cdDeEFhinNqvx
34.Op Fl s Ar name
35.Op Fl f Ar file
36.Op Fl j Ar jail | Fl R Ar dir
37.Ar name Ns Op Ns Oo +|- Oc Ns = Ns Ar value
38.Ar ...
39.Nm
40.Op Fl cdDeEFhinNqvx
41.Op Fl s Ar name
42.Op Fl f Ar file
43.Op Fl j Ar jail | Fl R Ar dir
44.Fl a | A
45.Nm
46.Op Fl E
47.Op Fl s Ar name
48.Op Fl f Ar file
49.Fl l
50.Nm
51.Op Fl eEqv
52.Fl L
53.Op Ar name ...
54.Sh DESCRIPTION
55The
56.Nm
57utility retrieves
58.Xr rc.conf 5
59variables from the collection of system rc files and allows processes with
60appropriate privilege to change values in a safe and effective manner.
61.Pp
62The following options are available:
63.Bl -tag -width indent+
64.It Fl a
65Dump a list of all non-default configuration variables.
66.It Fl A
67Dump a list of all configuration variables
68.Pq incl. defaults .
69.It Fl c
70Check only.
71For querying, return success if all requested variables are set
72.Pq even if NULL ,
73otherwise return error status.
74For assignments, return success if no changes are required, otherwise failure.
75If verbose
76.Pq see Dq Fl v
77prints a message stating whether variables are set and/or changes are required.
78.It Fl d
79Print a description of the given variable.
80.It Fl D
81Show default value(s) only (this is the same as setting RC_CONFS to NULL or
82passing `-f' with a NULL file-argument).
83.It Fl e
84Print query results as
85.Xr sh 1
86compatible syntax
87.Pq for example, Ql var=value .
88Ignored if either
89.Ql Fl n
90or
91.Ql Fl F
92is specified.
93.It Fl E
94When given
95.Sq Fl l
96or
97.Sq Fl L
98to list configuration files, only list those that exist.
99When changing a setting, prefer to modify existing files.
100.It Fl f Ar file
101Operate on the specified file(s) instead of the files obtained by reading the
102.Sq rc_conf_files
103entry in the
104.Ev RC_DEFAULTS
105file.
106This option can be specified multiple times for additional files.
107.It Fl F
108Show only the last
109.Xr rc.conf 5
110file each directive is in.
111.It Fl h
112Print a short usage message to stderr and exit.
113.It Fl -help
114Print a full usage statement to stderr and exit.
115.It Fl i
116Ignore unknown variables.
117.It Fl j Ar jail
118The
119.Ar jid
120or name of the
121.Ar jail
122to operate within
123.Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 .
124.It Fl l
125List configuration files used at startup on stdout and exit.
126.It Fl L
127List all configuration files including rc.conf.d entries on stdout and exit.
128Can be combined with
129.Sq Fl v
130or
131.Sq Fl e
132to show service names.
133.Nm
134exits with success if all named services are installed, failure otherwise.
135.It Fl n
136Show only variable values, not their names.
137.It Fl N
138Show only variable names, not their values.
139.It Fl q
140Quiet.
141Disable verbose and hide certain errors.
142When combined with
143.Sq Fl L
144and one or more
145.Ar name
146arguments, provide only exit status and no output.
147.It Fl R Ar dir
148Operate within the root directory
149.Sq Ar dir
150rather than
151.Sq / .
152.It Fl s Ar name
153If an
154.Li rc.d
155script of
156.Ar name
157exists
158.Po
159in
160.Dq /etc/rc.d
161or
162.Li local_startup
163directories
164.Pc ,
165process its
166.Dq rc.conf.d
167entries as potential overrides to
168.Sq rc_conf_files .
169See
170.Xr rc.subr 8
171for additional information on
172.Dq rc.conf.d .
173Can be combined with
174.Sq Fl l
175to list configuration files used by service at startup.
176.It Fl v
177Verbose.
178Print the pathname of the specific
179.Xr rc.conf 5
180file where the directive was found.
181.It Fl -version
182Print version information to stdout and exit.
183.It Fl x
184Remove variable(s) from specified file(s).
185.El
186.Pp
187This utility has a similar syntax to
188.Xr sysctl 8 .
189It shares the `-e' and `-n' options
190.Pq detailed above
191and also has the same
192.Ql name[=value]
193syntax for making queries/assignments.
194In addition
195.Pq but unlike Xr sysctl 8 ,
196.Ql name+=value
197is supported for adding items to values
198.Pq see APPENDING VALUES
199and
200.Ql name-=value
201is supported for removing items from values
202.Pq see SUBTRACTING VALUES .
203.Pp
204However, while
205.Xr sysctl 8
206serves to query/modify MIBs in the entrant kernel,
207.Nm
208instead works on values in the system
209.Xr rc.conf 5
210configuration files.
211.Pp
212The list of system configuration files is configured in the file
213.Ql /etc/defaults/rc.conf
214within the variable
215.Ql rc_conf_files ,
216which by-default contains a space-separated list of pathnames.
217On all
218.Fx
219systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local".
220Each
221pathname is sourced in-order upon startup.
222It is in the same fashion that
223.Nm
224sources the configuration files before returning the value of the given
225variable.
226.Pp
227When supplied a variable name,
228.Nm
229will return the value of the variable.
230If the variable does not appear in any
231of the configured
232.Ql rc_conf_files ,
233an error is printed and error status is returned.
234.Pp
235When changing values of a given variable, it does not matter if the variable
236appears in any of the
237.Ql rc_conf_files
238or not.
239If the variable does not appear in any of the files, it is appended to
240the end of the first pathname in the
241.Ql rc_conf_files
242variable.
243Otherwise,
244.Nm
245will replace only the last-occurrence in the last-file found to contain the
246variable.
247This gets the value to take effect next boot without heavily
248modifying these integral files (yet taking care not to allow the file to
249grow unwieldy should
250.Nm
251be called repeatedly).
252.Sh APPENDING VALUES
253When using the
254.Ql key+=value
255syntax to add items to 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.Bl -item -offset indent
260.It
261.Nm
262cloned_interfaces+=" gif0"
263.El
264.Pp
265the first character is a space, informing
266.Nm
267that existing values are to be considered separated by whitespace.
268If
269.Ql gif0
270is not found in the existing value for
271.Va cloned_interfaces ,
272it is added
273.Pq with delimiter only if existing value is non-NULL .
274.Pp
275For convenience, if the first character is alpha-numeric
276.Pq letters A-Z, a-z, or numbers 0-9 ,
277dot
278.Pq Li \&. ,
279or slash
280.Pq Li / ,
281.Nm
282uses the default setting of whitespace as separator.
283For example, the above and below statements are equivalent since
284.Dq gif0
285starts with an alpha-numeric character
286.Pq the letter Li g :
287.Bl -item -offset indent
288.It
289.Nm
290cloned_interfaces+=gif0
291.El
292.Pp
293Take the following sequence for example:
294.Bl -item -offset indent
295.It
296.Nm
297cloned_interfaces= # start with NULL
298.It
299.Nm
300cloned_interfaces+=gif0
301.Dl # NULL -> `gif0' Pq NB: no preceding delimiter
302.It
303.Nm
304cloned_interfaces+=gif0 # no change
305.It
306.Nm
307cloned_interfaces+="tun0 gif0"
308.Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
309.El
310.Pp
311.Nm
312prevents the same value from being added if already there.
313.Sh SUBTRACTING VALUES
314When using the
315.Ql key-=value
316syntax to remove items from existing values,
317the first character of the value is taken as the delimiter separating items
318.Pq usually Qo " " Qc or Qo , Qc .
319For example, in the following statement:
320.Pp
321.Dl Nm cloned_interfaces-=" gif0"
322.Pp
323the first character is a space, informing
324.Nm
325that existing values are to be considered separated by whitespace.
326If
327.Ql gif0
328is found in the existing value for
329.Va cloned_interfaces ,
330it is removed
331.Pq extra delimiters removed .
332.Pp
333For convenience, if the first character is alpha-numeric
334.Pq letters A-Z, a-z, or numbers 0-9 ,
335dot
336.Pq Li \&. ,
337or slash
338.Pq Li / ,
339.Nm
340uses the default setting of whitespace as separator.
341For example, the above and below statements are equivalent since
342.Dq gif0
343starts with an alpha-numeric character
344.Pq the letter Li g :
345.Bl -item -offset indent
346.It
347.Nm
348cloned_interfaces-=gif0
349.El
350.Pp
351Take the following sequence for example:
352.Bl -item -offset indent
353.It
354.Nm
355foo="bar baz" # start
356.It
357.Nm
358foo-=bar # `bar baz' -> `baz'
359.It
360.Nm
361foo-=baz # `baz' -> NULL
362.El
363.Pp
364.Nm
365removes all occurrences of all items provided
366and collapses extra delimiters between items.
367.Sh ENVIRONMENT
368The following environment variables are referenced by
369.Nm :
370.Bl -tag -width ".Ev RC_DEFAULTS"
371.It Ev RC_CONFS
372Override default
373.Ql rc_conf_files
374.Pq even if set to NULL .
375.It Ev RC_DEFAULTS
376Location of
377.Ql /etc/defaults/rc.conf
378file.
379.El
380.Sh DEPENDENCIES
381The following standard commands are required by
382.Nm :
383.Pp
384.Xr awk 1 ,
385.Xr cat 1 ,
386.Xr chmod 1 ,
387.Xr env 1 ,
388.Xr grep 1 ,
389.Xr mktemp 1 ,
390.Xr mv 1 ,
391.Xr rm 1 ,
392.Xr sh 1 ,
393.Xr stat 1 ,
394.Xr tail 1 ,
395.Xr chown 8 ,
396.Xr chroot 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 jail 8 ,
470.Xr jexec 8 ,
471.Xr jls 8 ,
472.Xr rc 8 ,
473.Xr rc.subr 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, Enji 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