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 .Dd April 3, 2022
  26 .Dt SYSRC 8
  27 .Os
  28 .Sh NAME
  29 .Nm sysrc
  30 .Nd safely edit system rc files
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl cdDeEFhinNqvx
  34 .Op Fl s Ar name
  35 .Op Fl f Ar file
  36 .Op Fl j Ar jail | Fl R Ar dir
  37 .Ar name Ns Op Ns Oo +|- Oc Ns = Ns Ar value
  38 .Ar ...
  39 .Nm
  40 .Op Fl cdDeEFhinNqvx
  41 .Op Fl s Ar name
  42 .Op Fl f Ar file
  43 .Op Fl j Ar jail | Fl R Ar dir
  44 .Fl a | A
  45 .Nm
  46 .Op Fl E
  47 .Op Fl s Ar name
  48 .Op Fl f Ar file
  49 .Fl l
  50 .Nm
  51 .Op Fl eEqv
  52 .Fl L
  53 .Op Ar name ...
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 utility retrieves
  58 .Xr rc.conf 5
  59 variables from the collection of system rc files and allows processes with
  60 appropriate privilege to change values in a safe and effective manner.
  61 .Pp
  62 The following options are available:
  63 .Bl -tag -width indent+
  64 .It Fl a
  65 Dump a list of all non-default configuration variables.
  66 .It Fl A
  67 Dump a list of all configuration variables
  68 .Pq incl. defaults .
  69 .It Fl c
  70 Check only.
  71 For querying, return success if all requested variables are set
  72 .Pq even if NULL ,
  73 otherwise return error status.
  74 For assignments, return success if no changes are required, otherwise failure.
  75 If verbose
  76 .Pq see Dq Fl v
  77 prints a message stating whether variables are set and/or changes are required.
  78 .It Fl d
  79 Print a description of the given variable.
  80 .It Fl D
  81 Show default value(s) only (this is the same as setting RC_CONFS to NULL or
  82 passing `-f' with a NULL file-argument).
  83 .It Fl e
  84 Print query results as
  85 .Xr sh 1
  86 compatible syntax
  87 .Pq for example, Ql var=value .
  88 Ignored if either
  89 .Ql Fl n
  90 or
  91 .Ql Fl F
  92 is specified.
  93 .It Fl E
  94 When given
  95 .Sq Fl l
  96 or
  97 .Sq Fl L
  98 to list configuration files, only list those that exist.
  99 When changing a setting, prefer to modify existing files.
 100 .It Fl f Ar file
 101 Operate on the specified file(s) instead of the files obtained by reading the
 102 .Sq rc_conf_files
 103 entry in the
 104 .Ev RC_DEFAULTS
 105 file.
 106 This option can be specified multiple times for additional files.
 107 .It Fl F
 108 Show only the last
 109 .Xr rc.conf 5
 110 file each directive is in.
 111 .It Fl h
 112 Print a short usage message to stderr and exit.
 113 .It Fl -help
 114 Print a full usage statement to stderr and exit.
 115 .It Fl i
 116 Ignore unknown variables.
 117 .It Fl j Ar jail
 118 The
 119 .Ar jid
 120 or name of the
 121 .Ar jail
 122 to operate within
 123 .Pq overrides So Fl R Ar dir Sc ; requires Xr jexec 8 .
 124 .It Fl l
 125 List configuration files used at startup on stdout and exit.
 126 .It Fl L
 127 List all configuration files including rc.conf.d entries on stdout and exit.
 128 Can be combined with
 129 .Sq Fl v
 130 or
 131 .Sq Fl e
 132 to show service names.
 133 .Nm
 134 exits with success if all named services are installed, failure otherwise.
 135 .It Fl n
 136 Show only variable values, not their names.
 137 .It Fl N
 138 Show only variable names, not their values.
 139 .It Fl q
 140 Quiet.
 141 Disable verbose and hide certain errors.
 142 When combined with
 143 .Sq Fl L
 144 and one or more
 145 .Ar name
 146 arguments, provide only exit status and no output.
 147 .It Fl R Ar dir
 148 Operate within the root directory
 149 .Sq Ar dir
 150 rather than
 151 .Sq / .
 152 .It Fl s Ar name
 153 If an
 154 .Li rc.d
 155 script of
 156 .Ar name
 157 exists
 158 .Po
 159 in
 160 .Dq /etc/rc.d
 161 or
 162 .Li local_startup
 163 directories
 164 .Pc ,
 165 process its
 166 .Dq rc.conf.d
 167 entries as potential overrides to
 168 .Sq rc_conf_files .
 169 See
 170 .Xr rc.subr 8
 171 for additional information on
 172 .Dq rc.conf.d .
 173 Can be combined with
 174 .Sq Fl l
 175 to list configuration files used by service at startup.
 176 .It Fl v
 177 Verbose.
 178 Print the pathname of the specific
 179 .Xr rc.conf 5
 180 file where the directive was found.
 181 .It Fl -version
 182 Print version information to stdout and exit.
 183 .It Fl x
 184 Remove variable(s) from specified file(s).
 185 .El
 186 .Pp
 187 This utility has a similar syntax to
 188 .Xr sysctl 8 .
 189 It shares the `-e' and `-n' options
 190 .Pq detailed above
 191 and also has the same
 192 .Ql name[=value]
 193 syntax for making queries/assignments.
 194 In addition
 195 .Pq but unlike Xr sysctl 8 ,
 196 .Ql name+=value
 197 is supported for adding items to values
 198 .Pq see APPENDING VALUES
 199 and
 200 .Ql name-=value
 201 is supported for removing items from values
 202 .Pq see SUBTRACTING VALUES .
 203 .Pp
 204 However, while
 205 .Xr sysctl 8
 206 serves to query/modify MIBs in the entrant kernel,
 207 .Nm
 208 instead works on values in the system
 209 .Xr rc.conf 5
 210 configuration files.
 211 .Pp
 212 The list of system configuration files is configured in the file
 213 .Ql /etc/defaults/rc.conf
 214 within the variable
 215 .Ql rc_conf_files ,
 216 which by-default contains a space-separated list of pathnames.
 217 On all
 218 .Fx
 219 systems, this defaults to the value "/etc/rc.conf /etc/rc.conf.local".
 220 Each
 221 pathname is sourced in-order upon startup.
 222 It is in the same fashion that
 223 .Nm
 224 sources the configuration files before returning the value of the given
 225 variable.
 226 .Pp
 227 When supplied a variable name,
 228 .Nm
 229 will return the value of the variable.
 230 If the variable does not appear in any
 231 of the configured
 232 .Ql rc_conf_files ,
 233 an error is printed and error status is returned.
 234 .Pp
 235 When changing values of a given variable, it does not matter if the variable
 236 appears in any of the
 237 .Ql rc_conf_files
 238 or not.
 239 If the variable does not appear in any of the files, it is appended to
 240 the end of the first pathname in the
 241 .Ql rc_conf_files
 242 variable.
 243 Otherwise,
 244 .Nm
 245 will replace only the last-occurrence in the last-file found to contain the
 246 variable.
 247 This gets the value to take effect next boot without heavily
 248 modifying these integral files (yet taking care not to allow the file to
 249 grow unwieldy should
 250 .Nm
 251 be called repeatedly).
 252 .Sh APPENDING VALUES
 253 When using the
 254 .Ql key+=value
 255 syntax to add items to 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 .Bl -item -offset indent
 260 .It
 261 .Nm
 262 cloned_interfaces+=" gif0"
 263 .El
 264 .Pp
 265 the first character is a space, informing
 266 .Nm
 267 that existing values are to be considered separated by whitespace.
 268 If
 269 .Ql gif0
 270 is not found in the existing value for
 271 .Va cloned_interfaces ,
 272 it is added
 273 .Pq with delimiter only if existing value is non-NULL .
 274 .Pp
 275 For convenience, if the first character is alpha-numeric
 276 .Pq letters A-Z, a-z, or numbers 0-9 ,
 277 dot
 278 .Pq Li \&. ,
 279 or slash
 280 .Pq Li / ,
 281 .Nm
 282 uses the default setting of whitespace as separator.
 283 For example, the above and below statements are equivalent since
 284 .Dq gif0
 285 starts with an alpha-numeric character
 286 .Pq the letter Li g :
 287 .Bl -item -offset indent
 288 .It
 289 .Nm
 290 cloned_interfaces+=gif0
 291 .El
 292 .Pp
 293 Take the following sequence for example:
 294 .Bl -item -offset indent
 295 .It
 296 .Nm
 297 cloned_interfaces= # start with NULL
 298 .It
 299 .Nm
 300 cloned_interfaces+=gif0
 301 .Dl # NULL -> `gif0' Pq NB: no preceding delimiter
 302 .It
 303 .Nm
 304 cloned_interfaces+=gif0 # no change
 305 .It
 306 .Nm
 307 cloned_interfaces+="tun0 gif0"
 308 .Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
 309 .El
 310 .Pp
 311 .Nm
 312 prevents the same value from being added if already there.
 313 .Sh SUBTRACTING VALUES
 314 When using the
 315 .Ql key-=value
 316 syntax to remove items from existing values,
 317 the first character of the value is taken as the delimiter separating items
 318 .Pq usually Qo " " Qc or Qo , Qc .
 319 For example, in the following statement:
 320 .Pp
 321 .Dl Nm cloned_interfaces-=" gif0"
 322 .Pp
 323 the first character is a space, informing
 324 .Nm
 325 that existing values are to be considered separated by whitespace.
 326 If
 327 .Ql gif0
 328 is found in the existing value for
 329 .Va cloned_interfaces ,
 330 it is removed
 331 .Pq extra delimiters removed .
 332 .Pp
 333 For convenience, if the first character is alpha-numeric
 334 .Pq letters A-Z, a-z, or numbers 0-9 ,
 335 dot
 336 .Pq Li \&. ,
 337 or slash
 338 .Pq Li / ,
 339 .Nm
 340 uses the default setting of whitespace as separator.
 341 For example, the above and below statements are equivalent since
 342 .Dq gif0
 343 starts with an alpha-numeric character
 344 .Pq the letter Li g :
 345 .Bl -item -offset indent
 346 .It
 347 .Nm
 348 cloned_interfaces-=gif0
 349 .El
 350 .Pp
 351 Take the following sequence for example:
 352 .Bl -item -offset indent
 353 .It
 354 .Nm
 355 foo="bar baz" # start
 356 .It
 357 .Nm
 358 foo-=bar # `bar baz' -> `baz'
 359 .It
 360 .Nm
 361 foo-=baz # `baz' -> NULL
 362 .El
 363 .Pp
 364 .Nm
 365 removes all occurrences of all items provided
 366 and collapses extra delimiters between items.
 367 .Sh ENVIRONMENT
 368 The following environment variables are referenced by
 369 .Nm :
 370 .Bl -tag -width ".Ev RC_DEFAULTS"
 371 .It Ev RC_CONFS
 372 Override default
 373 .Ql rc_conf_files
 374 .Pq even if set to NULL .
 375 .It Ev RC_DEFAULTS
 376 Location of
 377 .Ql /etc/defaults/rc.conf
 378 file.
 379 .El
 380 .Sh DEPENDENCIES
 381 The following standard commands are required by
 382 .Nm :
 383 .Pp
 384 .Xr awk 1 ,
 385 .Xr cat 1 ,
 386 .Xr chmod 1 ,
 387 .Xr env 1 ,
 388 .Xr grep 1 ,
 389 .Xr mktemp 1 ,
 390 .Xr mv 1 ,
 391 .Xr rm 1 ,
 392 .Xr sh 1 ,
 393 .Xr stat 1 ,
 394 .Xr tail 1 ,
 395 .Xr chown 8 ,
 396 .Xr chroot 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 jail 8 ,
 470 .Xr jexec 8 ,
 471 .Xr jls 8 ,
 472 .Xr rc 8 ,
 473 .Xr rc.subr 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.