usr.sbin/sysrc/sysrc.8

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