usr.sbin/sysrc/sysrc.8

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