usr.sbin/sysrc/sysrc.8

   1 .\" Copyright (c) 2011-2012 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 Aug 24, 2012
  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. Ignore previous
 102 .Fl v
 103 and/or
 104 .Ev SYSRC_VERBOSE .
 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. Print the pathname of the specific
 112 .Xr rc.conf 5
 113 file where the directive was found.
 114 .It Fl x
 115 Remove variable(s) from specified file(s).
 116 .El
 117 .Pp
 118 This utility works similar to
 119 .Xr sysctl 8 .
 120 It shares the `-e' and `-n' options
 121 .Pq detailed above
 122 and also has the same
 123 .Ql name[=value]
 124 syntax for querying/setting configuration options.
 125 .Pp
 126 However, while
 127 .Xr sysctl 8
 128 serves to query/modify MIBs in the entrant kernel,
 129 .Xr sysrc 8
 130 instead works on values in the system
 131 .Xr rc.conf 5
 132 configuration files.
 133 .Pp
 134 The list of system configuration files is configured in the file
 135 .Ql /etc/defaults/rc.conf
 136 within the variable
 137 .Ql rc_conf_files ,
 138 which by-default contains a space-separated list of pathnames. On all FreeBSD
 139 systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local". Each
 140 pathname is sourced in-order upon startup. It is in the same fashion that
 141 .Nm
 142 sources the configuration files before returning the value of the given
 143 variable.
 144 .Pp
 145 When supplied a variable name,
 146 .Nm
 147 will return the value of the variable. If the variable does not appear in any
 148 of the configured
 149 .Ql rc_conf_files ,
 150 an error is printed and error status is returned.
 151 .Pp
 152 When changing values of a given variable, it does not matter if the variable
 153 appears in any of the
 154 .Ql rc_conf_files
 155 or not. If the variable does not appear in any of the files, it is appended to
 156 the end of the first pathname in the
 157 .Ql rc_conf_files
 158 variable. Otherwise,
 159 .Nm
 160 will replace only the last-occurrence in the last-file found to contain the
 161 variable. This gets the value to take effect next boot without heavily
 162 modifying these integral files (yet taking care not to allow the file to
 163 grow unwieldy should
 164 .Nm
 165 be called repeatedly).
 166 .Sh ENVIRONMENT
 167 The following environment variables are referenced by
 168 .Nm :
 169 .Bl -tag -width ".Ev SYSRC_VERBOSE"
 170 .It Ev RC_CONFS
 171 Override default
 172 .Ql rc_conf_files
 173 .Pq even if set to NULL .
 174 .It Ev RC_DEFAULTS
 175 Location of
 176 .Ql /etc/defaults/rc.conf
 177 file.
 178 .It Ev SYSRC_VERBOSE
 179 Default verbosity. Set to non-NULL to enable.
 180 .El
 181 .Sh DEPENDENCIES
 182 The following standard commands are required by
 183 .Nm :
 184 .Pp
 185 .Xr awk 1 ,
 186 .Xr cat 1 ,
 187 .Xr chmod 1 ,
 188 .Xr chown 8 ,
 189 .Xr env 1 ,
 190 .Xr grep 1 ,
 191 .Xr jexec 8 ,
 192 .Xr jls 1 ,
 193 .Xr mktemp 1 ,
 194 .Xr mv 1 ,
 195 .Xr rm 1 ,
 196 .Xr sh 1 ,
 197 .Xr stat 1 ,
 198 .Xr tail 1
 199 .Sh FILES
 200 .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact
 201 .It Pa /etc/defaults/rc.conf
 202 .It Pa /etc/rc.conf
 203 .It Pa /etc/rc.conf.local
 204 .El
 205 .Sh EXAMPLES
 206 Below are some simple examples of how
 207 .Nm
 208 can be used to query certain values from the
 209 .Xr rc.conf 5
 210 collection of system configuration files:
 211 .Pp
 212 .Nm
 213 sshd_enable
 214 .Dl returns the value of $sshd_enable, usually YES or NO .
 215 .Pp
 216 .Nm
 217 defaultrouter
 218 .Dl returns IP address of default router Pq if configured .
 219 .Pp
 220 Working on other files, such as
 221 .Xr crontab 5 :
 222 .Pp
 223 .Nm
 224 -f /etc/crontab MAILTO
 225 .Dl returns the value of the MAILTO setting Pq if configured .
 226 .Pp
 227 In addition to the above syntax,
 228 .Nm
 229 also supports inline
 230 .Xr sh 1
 231 PARAMETER expansion for changing the way values are reported, shown below:
 232 .Pp
 233 .Nm
 234 \&'hostname%%.*'
 235 .Dl returns $hostname up to (but not including) first `.' .
 236 .Pp
 237 .Nm
 238 \&'network_interfaces%%[$IFS]*'
 239 .Dl returns first word of $network_interfaces .
 240 .Pp
 241 .Nm
 242 \&'ntpdate_flags##*[$IFS]'
 243 .Dl returns last word of $ntpdate_flags (time server address) .
 244 .Pp
 245 .Nm
 246 usbd_flags-"default"
 247 .Dl returns $usbd_flags or "default" if unset or NULL .
 248 .Pp
 249 .Nm
 250 cloned_interfaces+"alternate"
 251 .Dl returns "alternate" if $cloned_interfaces is set .
 252 .Pp
 253 .Nm
 254 \&'#kern_securelevel'
 255 .Dl returns length in characters of $kern_securelevel .
 256 .Pp
 257 .Nm
 258 \&'hostname?'
 259 .Dl returns NULL and error status 2 if $hostname is unset Pq or if set, returns the value of $hostname with no error status .
 260 .Pp
 261 .Nm
 262 \&'hostname:?'
 263 .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 .
 264 .Sh LIMITATIONS
 265 The
 266 .Nm
 267 utility presently does not support the
 268 .Ql rc.conf.d
 269 collection of system configuration files
 270 .Pq which requires a service name to be known during execution .
 271 .Pp
 272 This will be corrected by a future enhancement.
 273 .Sh SEE ALSO
 274 .Xr jail 8 ,
 275 .Xr jexec 8 ,
 276 .Xr jls 1 ,
 277 .Xr rc 8 ,
 278 .Xr rc.conf 5 ,
 279 .Xr sysctl 8
 280 .Sh HISTORY
 281 A
 282 .Nm
 283 utility first appeared in
 284 .Bx 10.0 .
 285 .Sh AUTHORS
 286 .An Devin Teske Aq dteske@FreeBSD.org
 287 .Sh THANKS TO
 288 Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek,
 289 Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, and Jilles Tjoelker
 290 for suggestions and help.