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