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 26, 2019
  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 .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
 220 .Fx
 221 systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local".
 222 Each
 223 pathname is sourced in-order upon startup.
 224 It is in the same fashion that
 225 .Nm
 226 sources the configuration files before returning the value of the given
 227 variable.
 228 .Pp
 229 When supplied a variable name,
 230 .Nm
 231 will return the value of the variable.
 232 If the variable does not appear in any
 233 of the configured
 234 .Ql rc_conf_files ,
 235 an error is printed and error status is returned.
 236 .Pp
 237 When changing values of a given variable, it does not matter if the variable
 238 appears in any of the
 239 .Ql rc_conf_files
 240 or not.
 241 If the variable does not appear in any of the files, it is appended to
 242 the end of the first pathname in the
 243 .Ql rc_conf_files
 244 variable.
 245 Otherwise,
 246 .Nm
 247 will replace only the last-occurrence in the last-file found to contain the
 248 variable.
 249 This gets the value to take effect next boot without heavily
 250 modifying these integral files (yet taking care not to allow the file to
 251 grow unwieldy should
 252 .Nm
 253 be called repeatedly).
 254 .Sh APPENDING VALUES
 255 When using the
 256 .Ql key+=value
 257 syntax to add items to existing values,
 258 the first character of the value is taken as the delimiter separating items
 259 .Pq usually Qo " " Qc or Qo , Qc .
 260 For example, in the following statement:
 261 .Bl -item -offset indent
 262 .It
 263 .Nm
 264 cloned_interfaces+=" gif0"
 265 .El
 266 .Pp
 267 the first character is a space, informing
 268 .Nm
 269 that existing values are to be considered separated by whitespace.
 270 If
 271 .Ql gif0
 272 is not found in the existing value for
 273 .Va cloned_interfaces ,
 274 it is added
 275 .Pq with delimiter only if existing value is non-NULL .
 276 .Pp
 277 For convenience, if the first character is alpha-numeric
 278 .Pq letters A-Z, a-z, or numbers 0-9 ,
 279 dot
 280 .Pq Li \&. ,
 281 or slash
 282 .Pq Li / ,
 283 .Nm
 284 uses the default setting of whitespace as separator.
 285 For example, the above and below statements are equivalent since
 286 .Dq gif0
 287 starts with an alpha-numeric character
 288 .Pq the letter Li g :
 289 .Bl -item -offset indent
 290 .It
 291 .Nm
 292 cloned_interfaces+=gif0
 293 .El
 294 .Pp
 295 Take the following sequence for example:
 296 .Bl -item -offset indent
 297 .It
 298 .Nm
 299 cloned_interfaces= # start with NULL
 300 .It
 301 .Nm
 302 cloned_interfaces+=gif0
 303 .Dl # NULL -> `gif0' Pq NB: no preceding delimiter
 304 .It
 305 .Nm
 306 cloned_interfaces+=gif0 # no change
 307 .It
 308 .Nm
 309 cloned_interfaces+="tun0 gif0"
 310 .Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
 311 .El
 312 .Pp
 313 .Nm
 314 prevents the same value from being added if already there.
 315 .Sh SUBTRACTING VALUES
 316 When using the
 317 .Ql key-=value
 318 syntax to remove items from existing values,
 319 the first character of the value is taken as the delimiter separating items
 320 .Pq usually Qo " " Qc or Qo , Qc .
 321 For example, in the following statement:
 322 .Pp
 323 .Dl Nm cloned_interfaces-=" gif0"
 324 .Pp
 325 the first character is a space, informing
 326 .Nm
 327 that existing values are to be considered separated by whitespace.
 328 If
 329 .Ql gif0
 330 is found in the existing value for
 331 .Va cloned_interfaces ,
 332 it is removed
 333 .Pq extra delimiters removed .
 334 .Pp
 335 For convenience, if the first character is alpha-numeric
 336 .Pq letters A-Z, a-z, or numbers 0-9 ,
 337 dot
 338 .Pq Li \&. ,
 339 or slash
 340 .Pq Li / ,
 341 .Nm
 342 uses the default setting of whitespace as separator.
 343 For example, the above and below statements are equivalent since
 344 .Dq gif0
 345 starts with an alpha-numeric character
 346 .Pq the letter Li g :
 347 .Bl -item -offset indent
 348 .It
 349 .Nm
 350 cloned_interfaces-=gif0
 351 .El
 352 .Pp
 353 Take the following sequence for example:
 354 .Bl -item -offset indent
 355 .It
 356 .Nm
 357 foo="bar baz" # start
 358 .It
 359 .Nm
 360 foo-=bar # `bar baz' -> `baz'
 361 .It
 362 .Nm
 363 foo-=baz # `baz' -> NULL
 364 .El
 365 .Pp
 366 .Nm
 367 removes all occurrences of all items provided
 368 and collapses extra delimiters between items.
 369 .Sh ENVIRONMENT
 370 The following environment variables are referenced by
 371 .Nm :
 372 .Bl -tag -width ".Ev RC_DEFAULTS"
 373 .It Ev RC_CONFS
 374 Override default
 375 .Ql rc_conf_files
 376 .Pq even if set to NULL .
 377 .It Ev RC_DEFAULTS
 378 Location of
 379 .Ql /etc/defaults/rc.conf
 380 file.
 381 .El
 382 .Sh DEPENDENCIES
 383 The following standard commands are required by
 384 .Nm :
 385 .Pp
 386 .Xr awk 1 ,
 387 .Xr cat 1 ,
 388 .Xr chmod 1 ,
 389 .Xr env 1 ,
 390 .Xr grep 1 ,
 391 .Xr mktemp 1 ,
 392 .Xr mv 1 ,
 393 .Xr rm 1 ,
 394 .Xr sh 1 ,
 395 .Xr stat 1 ,
 396 .Xr tail 1 ,
 397 .Xr chown 8 ,
 398 .Xr jls 8 ,
 399 and
 400 .Xr jexec 8 .
 401 .Sh FILES
 402 .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact
 403 .It Pa /etc/defaults/rc.conf
 404 .It Pa /etc/rc.conf
 405 .It Pa /etc/rc.conf.local
 406 .It Pa /etc/rc.conf.d/name
 407 .It Pa /etc/rc.conf.d/name/*
 408 .It Pa /usr/local/etc/rc.conf.d/name
 409 .It Pa /usr/local/etc/rc.conf.d/name/*
 410 .El
 411 .Sh EXAMPLES
 412 Below are some simple examples of how
 413 .Nm
 414 can be used to query certain values from the
 415 .Xr rc.conf 5
 416 collection of system configuration files:
 417 .Pp
 418 .Nm
 419 sshd_enable
 420 .Dl returns the value of $sshd_enable, usually YES or NO .
 421 .Pp
 422 .Nm
 423 defaultrouter
 424 .Dl returns IP address of default router Pq if configured .
 425 .Pp
 426 Working on other files, such as
 427 .Xr crontab 5 :
 428 .Pp
 429 .Nm
 430 -f /etc/crontab MAILTO
 431 .Dl returns the value of the MAILTO setting Pq if configured .
 432 .Pp
 433 Appending to existing values:
 434 .Pp
 435 .Nm
 436 \&cloned_interfaces+=gif0
 437 .Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES .
 438 .Pp
 439 .Nm
 440 \&cloned_interfaces-=gif0
 441 .Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES .
 442 .Pp
 443 In addition to the above syntax,
 444 .Nm
 445 also supports inline
 446 .Xr sh 1
 447 PARAMETER expansion for changing the way values are reported, shown below:
 448 .Pp
 449 .Nm
 450 \&'hostname%%.*'
 451 .Dl returns $hostname up to (but not including) first `.' .
 452 .Pp
 453 .Nm
 454 \&'network_interfaces%%[$IFS]*'
 455 .Dl returns first word of $network_interfaces .
 456 .Pp
 457 .Nm
 458 \&'ntpdate_flags##*[$IFS]'
 459 .Dl returns last word of $ntpdate_flags (time server address) .
 460 .Pp
 461 .Nm
 462 usbd_flags-"default"
 463 .Dl returns $usbd_flags or "default" if unset or NULL .
 464 .Pp
 465 .Nm
 466 cloned_interfaces+"alternate"
 467 .Dl returns "alternate" if $cloned_interfaces is set .
 468 .Sh SEE ALSO
 469 .Xr rc.conf 5 ,
 470 .Xr jail 8 ,
 471 .Xr jexec 8 ,
 472 .Xr jls 8 ,
 473 .Xr rc 8 ,
 474 .Xr rc.subr 8 ,
 475 .Xr sysctl 8
 476 .Sh HISTORY
 477 A
 478 .Nm
 479 utility first appeared in
 480 .Fx 9.2 .
 481 .Sh AUTHORS
 482 .An Devin Teske Aq Mt dteske@FreeBSD.org
 483 .Sh THANKS TO
 484 Brandon Gooch, Enji Cooper, Julian Elischer, Pawel Jakub Dawidek,
 485 Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker,
 486 Allan Jude, and Lars Engels for suggestions, help, and testing.