usr.sbin/sysrc/sysrc.8

   1 .\" Copyright (c) 2011-2013 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 Jul 5, 2013
  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 dDeFhinNqvx
  36 .Op Fl f Ar file
  37 .Op Fl j Ar jail | Fl R Ar dir
  38 .Ar name Ns Op = Ns Ar value
  39 .Ar ...
  40 .Nm
  41 .Op Fl dDeFhinNqvx
  42 .Op Fl f Ar file
  43 .Op Fl j Ar jail | Fl R Ar dir
  44 .Fl a | A
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility retrieves
  49 .Xr rc.conf 5
  50 variables from the collection of system rc files and allows processes with
  51 appropriate privilege to change values in a safe and effective manner.
  52 .Pp
  53 The following options are available:
  54 .Bl -tag -width indent+
  55 .It Fl a
  56 Dump a list of all non-default configuration variables.
  57 .It Fl A
  58 Dump a list of all configuration variables
  59 .Pq incl. defaults .
  60 .It Fl d
  61 Print a description of the given variable.
  62 .It Fl D
  63 Show default value(s) only (this is the same as setting RC_CONFS to NULL or
  64 passing `-f' with a NULL file-argument).
  65 .It Fl e
  66 Print query results as
  67 .Ql var=value
  68 .Pq useful for producing output to be fed back in .
  69 Ignored if
  70 .Fl n
  71 is specified.
  72 .It Fl f Ar file
  73 Operate on the specified file(s) instead of the files obtained by reading the
  74 .Sq rc_conf_files
  75 entry in the
  76 .Ev RC_DEFAULTS
  77 file.
  78 This option can be specified multiple times for additional files.
  79 .It Fl F
  80 Show only the last
  81 .Xr rc.conf 5
  82 file each directive is in.
  83 .It Fl h
  84 Print a short usage message to stderr and exit.
  85 .It Fl -help
  86 Print a full usage statement to stderr and exit.
  87 .It Fl i
  88 Ignore unknown variables.
  89 .It Fl j Ar jail
  90 The
  91 .Ar jid
  92 or name of the
  93 .Ar jail
  94 to operate within
  95 .Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 .
  96 .It Fl n
  97 Show only variable values, not their names.
  98 .It Fl N
  99 Show only variable names, not their values.
 100 .It Fl q
 101 Quiet.
 102 Ignore previous occurrences of
 103 .Fl v
 104 flag.
 105 .It Fl R Ar dir
 106 Operate within the root directory
 107 .Pq Sq Ar dir
 108 rather than
 109 .Pq Sq / .
 110 .It Fl v
 111 Verbose.
 112 Print the pathname of the specific
 113 .Xr rc.conf 5
 114 file where the directive was found.
 115 .It Fl x
 116 Remove variable(s) from specified file(s).
 117 .El
 118 .Pp
 119 This utility works similar to
 120 .Xr sysctl 8 .
 121 It shares the `-e' and `-n' options
 122 .Pq detailed above
 123 and also has the same
 124 .Ql name[=value]
 125 syntax for querying/setting configuration options.
 126 .Pp
 127 However, while
 128 .Xr sysctl 8
 129 serves to query/modify MIBs in the entrant kernel,
 130 .Nm
 131 instead works on values in the system
 132 .Xr rc.conf 5
 133 configuration files.
 134 .Pp
 135 The list of system configuration files is configured in the file
 136 .Ql /etc/defaults/rc.conf
 137 within the variable
 138 .Ql rc_conf_files ,
 139 which by-default contains a space-separated list of pathnames.
 140 On all FreeBSD
 141 systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local".
 142 Each
 143 pathname is sourced in-order upon startup.
 144 It is in the same fashion that
 145 .Nm
 146 sources the configuration files before returning the value of the given
 147 variable.
 148 .Pp
 149 When supplied a variable name,
 150 .Nm
 151 will return the value of the variable.
 152 If the variable does not appear in any
 153 of the configured
 154 .Ql rc_conf_files ,
 155 an error is printed and error status is returned.
 156 .Pp
 157 When changing values of a given variable, it does not matter if the variable
 158 appears in any of the
 159 .Ql rc_conf_files
 160 or not.
 161 If the variable does not appear in any of the files, it is appended to
 162 the end of the first pathname in the
 163 .Ql rc_conf_files
 164 variable.
 165 Otherwise,
 166 .Nm
 167 will replace only the last-occurrence in the last-file found to contain the
 168 variable.
 169 This gets the value to take effect next boot without heavily
 170 modifying these integral files (yet taking care not to allow the file to
 171 grow unwieldy should
 172 .Nm
 173 be called repeatedly).
 174 .Sh ENVIRONMENT
 175 The following environment variables are referenced by
 176 .Nm :
 177 .Bl -tag -width ".Ev RC_DEFAULTS"
 178 .It Ev RC_CONFS
 179 Override default
 180 .Ql rc_conf_files
 181 .Pq even if set to NULL .
 182 .It Ev RC_DEFAULTS
 183 Location of
 184 .Ql /etc/defaults/rc.conf
 185 file.
 186 .El
 187 .Sh DEPENDENCIES
 188 The following standard commands are required by
 189 .Nm :
 190 .Pp
 191 .Xr awk 1 ,
 192 .Xr cat 1 ,
 193 .Xr chmod 1 ,
 194 .Xr env 1 ,
 195 .Xr grep 1 ,
 196 .Xr jls 1 ,
 197 .Xr mktemp 1 ,
 198 .Xr mv 1 ,
 199 .Xr rm 1 ,
 200 .Xr sh 1 ,
 201 .Xr stat 1 ,
 202 .Xr tail 1 ,
 203 .Xr chown 8
 204 and
 205 .Xr jexec 8 .
 206 .Sh FILES
 207 .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact
 208 .It Pa /etc/defaults/rc.conf
 209 .It Pa /etc/rc.conf
 210 .It Pa /etc/rc.conf.local
 211 .El
 212 .Sh EXAMPLES
 213 Below are some simple examples of how
 214 .Nm
 215 can be used to query certain values from the
 216 .Xr rc.conf 5
 217 collection of system configuration files:
 218 .Pp
 219 .Nm
 220 sshd_enable
 221 .Dl returns the value of $sshd_enable, usually YES or NO .
 222 .Pp
 223 .Nm
 224 defaultrouter
 225 .Dl returns IP address of default router Pq if configured .
 226 .Pp
 227 Working on other files, such as
 228 .Xr crontab 5 :
 229 .Pp
 230 .Nm
 231 -f /etc/crontab MAILTO
 232 .Dl returns the value of the MAILTO setting Pq if configured .
 233 .Pp
 234 In addition to the above syntax,
 235 .Nm
 236 also supports inline
 237 .Xr sh 1
 238 PARAMETER expansion for changing the way values are reported, shown below:
 239 .Pp
 240 .Nm
 241 \&'hostname%%.*'
 242 .Dl returns $hostname up to (but not including) first `.' .
 243 .Pp
 244 .Nm
 245 \&'network_interfaces%%[$IFS]*'
 246 .Dl returns first word of $network_interfaces .
 247 .Pp
 248 .Nm
 249 \&'ntpdate_flags##*[$IFS]'
 250 .Dl returns last word of $ntpdate_flags (time server address) .
 251 .Pp
 252 .Nm
 253 usbd_flags-"default"
 254 .Dl returns $usbd_flags or "default" if unset or NULL .
 255 .Pp
 256 .Nm
 257 cloned_interfaces+"alternate"
 258 .Dl returns "alternate" if $cloned_interfaces is set .
 259 .Pp
 260 .Nm
 261 \&'#kern_securelevel'
 262 .Dl returns length in characters of $kern_securelevel .
 263 .Pp
 264 .Nm
 265 \&'hostname?'
 266 .Dl returns NULL and error status 2 if $hostname is unset Pq or if set, returns the value of $hostname with no error status .
 267 .Pp
 268 .Nm
 269 \&'hostname:?'
 270 .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 .
 271 .Sh LIMITATIONS
 272 The
 273 .Nm
 274 utility presently does not support the
 275 .Ql rc.conf.d
 276 collection of system configuration files
 277 .Pq which requires a service name to be known during execution .
 278 .Pp
 279 This will be corrected by a future enhancement.
 280 .Sh SEE ALSO
 281 .Xr jls 1 ,
 282 .Xr rc.conf 5 ,
 283 .Xr jail 8 ,
 284 .Xr jexec 8 ,
 285 .Xr rc 8 ,
 286 .Xr sysctl 8
 287 .Sh HISTORY
 288 A
 289 .Nm
 290 utility first appeared in
 291 .Fx 9.2 .
 292 .Sh AUTHORS
 293 .An Devin Teske Aq dteske@FreeBSD.org
 294 .Sh THANKS TO
 295 Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek,
 296 Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, and Jilles Tjoelker
 297 for suggestions and help.