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 12, 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 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 .Nm
 279 uses the default setting of whitespace as separator.
 280 For example, the above and below statements are equivalent since
 281 .Dq gif0
 282 starts with an alpha-numeric character
 283 .Pq the letter Li g :
 284 .Bl -item -offset indent
 285 .It
 286 .Nm
 287 cloned_interfaces+=gif0
 288 .El
 289 .Pp
 290 Take the following sequence for example:
 291 .Bl -item -offset indent
 292 .It
 293 .Nm
 294 cloned_interfaces= # start with NULL
 295 .It
 296 .Nm
 297 cloned_interfaces+=gif0
 298 .Dl # NULL -> `gif0' Pq NB: no preceding delimiter
 299 .It
 300 .Nm
 301 cloned_interfaces+=gif0 # no change
 302 .It
 303 .Nm
 304 cloned_interfaces+="tun0 gif0"
 305 .Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
 306 .El
 307 .Pp
 308 .Nm
 309 prevents the same value from being added if already there.
 310 .Sh SUBTRACTING VALUES
 311 When using the
 312 .Ql key-=value
 313 syntax to remove items from existing values,
 314 the first character of the value is taken as the delimiter separating items
 315 .Pq usually Qo \  Qc or Qo , Qc .
 316 For example, in the following statement:
 317 .Pp
 318 .Dl Nm cloned_interfaces-=" gif0"
 319 .Pp
 320 the first character is a space, informing
 321 .Nm
 322 that existing values are to be considered separated by whitespace.
 323 If
 324 .Ql gif0
 325 is found in the existing value for
 326 .Va cloned_interfaces ,
 327 it is removed
 328 .Pq extra delimiters removed .
 329 .Pp
 330 For convenience, if the first character is alpha-numeric
 331 .Pq letters A-Z, a-z, or numbers 0-9 ,
 332 .Nm
 333 uses the default setting of whitespace as separator.
 334 For example, the above and below statements are equivalent since
 335 .Dq gif0
 336 starts with an alpha-numeric character
 337 .Pq the letter Li g :
 338 .Bl -item -offset indent
 339 .It
 340 .Nm
 341 cloned_interfaces-=gif0
 342 .El
 343 .Pp
 344 Take the following sequence for example:
 345 .Bl -item -offset indent
 346 .It
 347 .Nm
 348 foo="bar baz" # start
 349 .It
 350 .Nm
 351 foo-=bar # `bar baz' -> `baz'
 352 .It
 353 .Nm
 354 foo-=baz # `baz' -> NULL
 355 .El
 356 .Pp
 357 .Nm
 358 removes all occurrences of all items provided
 359 and collapses extra delimiters between items.
 360 .Sh ENVIRONMENT
 361 The following environment variables are referenced by
 362 .Nm :
 363 .Bl -tag -width ".Ev RC_DEFAULTS"
 364 .It Ev RC_CONFS
 365 Override default
 366 .Ql rc_conf_files
 367 .Pq even if set to NULL .
 368 .It Ev RC_DEFAULTS
 369 Location of
 370 .Ql /etc/defaults/rc.conf
 371 file.
 372 .El
 373 .Sh DEPENDENCIES
 374 The following standard commands are required by
 375 .Nm :
 376 .Pp
 377 .Xr awk 1 ,
 378 .Xr cat 1 ,
 379 .Xr chmod 1 ,
 380 .Xr env 1 ,
 381 .Xr grep 1 ,
 382 .Xr jls 1 ,
 383 .Xr mktemp 1 ,
 384 .Xr mv 1 ,
 385 .Xr rm 1 ,
 386 .Xr sh 1 ,
 387 .Xr stat 1 ,
 388 .Xr tail 1 ,
 389 .Xr chown 8
 390 and
 391 .Xr jexec 8 .
 392 .Sh FILES
 393 .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact
 394 .It Pa /etc/defaults/rc.conf
 395 .It Pa /etc/rc.conf
 396 .It Pa /etc/rc.conf.local
 397 .It Pa /etc/rc.conf.d/name
 398 .It Pa /etc/rc.conf.d/name/*
 399 .It Pa /usr/local/etc/rc.conf.d/name
 400 .It Pa /usr/local/etc/rc.conf.d/name/*
 401 .El
 402 .Sh EXAMPLES
 403 Below are some simple examples of how
 404 .Nm
 405 can be used to query certain values from the
 406 .Xr rc.conf 5
 407 collection of system configuration files:
 408 .Pp
 409 .Nm
 410 sshd_enable
 411 .Dl returns the value of $sshd_enable, usually YES or NO .
 412 .Pp
 413 .Nm
 414 defaultrouter
 415 .Dl returns IP address of default router Pq if configured .
 416 .Pp
 417 Working on other files, such as
 418 .Xr crontab 5 :
 419 .Pp
 420 .Nm
 421 -f /etc/crontab MAILTO
 422 .Dl returns the value of the MAILTO setting Pq if configured .
 423 .Pp
 424 Appending to existing values:
 425 .Pp
 426 .Nm
 427 \&cloned_interfaces+=gif0
 428 .Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES .
 429 .Pp
 430 .Nm
 431 \&cloned_interfaces-=gif0
 432 .Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES .
 433 .Pp
 434 In addition to the above syntax,
 435 .Nm
 436 also supports inline
 437 .Xr sh 1
 438 PARAMETER expansion for changing the way values are reported, shown below:
 439 .Pp
 440 .Nm
 441 \&'hostname%%.*'
 442 .Dl returns $hostname up to (but not including) first `.' .
 443 .Pp
 444 .Nm
 445 \&'network_interfaces%%[$IFS]*'
 446 .Dl returns first word of $network_interfaces .
 447 .Pp
 448 .Nm
 449 \&'ntpdate_flags##*[$IFS]'
 450 .Dl returns last word of $ntpdate_flags (time server address) .
 451 .Pp
 452 .Nm
 453 usbd_flags-"default"
 454 .Dl returns $usbd_flags or "default" if unset or NULL .
 455 .Pp
 456 .Nm
 457 cloned_interfaces+"alternate"
 458 .Dl returns "alternate" if $cloned_interfaces is set .
 459 .Sh SEE ALSO
 460 .Xr jls 1 ,
 461 .Xr rc.conf 5 ,
 462 .Xr rc.subr 8 ,
 463 .Xr jail 8 ,
 464 .Xr jexec 8 ,
 465 .Xr rc 8 ,
 466 .Xr sysctl 8
 467 .Sh HISTORY
 468 A
 469 .Nm
 470 utility first appeared in
 471 .Fx 9.2 .
 472 .Sh AUTHORS
 473 .An Devin Teske Aq dteske@FreeBSD.org
 474 .Sh THANKS TO
 475 Brandon Gooch, Garrett Cooper, Julian Elischer, Pawel Jakub Dawidek,
 476 Cyrille Lefevre, Ross West, Stefan Esser, Marco Steinbach, Jilles Tjoelker,
 477 Allan Jude, and Lars Engels for suggestions, help, and testing.