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