share/man/man8/rc.subr.8

   1 .\"     $NetBSD: rc.subr.8,v 1.9 2002/07/08 16:14:55 atatat Exp $
   2 .\"     $FreeBSD: src/share/man/man8/rc.subr.8,v 1.3 2003/04/22 05:13:55 dougb Exp $
   3 .\"     $DragonFly: src/share/man/man8/rc.subr.8,v 1.1 2003/08/01 04:36:57 rob Exp $
   4 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to The NetBSD Foundation
   8 .\" by Luke Mewburn.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"     This product includes software developed by the NetBSD
  21 .\"     Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .Dd April 18, 2002
  39 .Dt RC.SUBR 8
  40 .Os
  41 .Sh NAME
  42 .Nm rc.subr
  43 .Nd functions used by system shell scripts
  44 .Sh SYNOPSIS
  45 .Bl -item
  46 .It
  47 .Li . /etc/rc.subr
  48 .It
  49 .Ic backup_file Ar action Ar file Ar current Ar backup
  50 .It
  51 .Ic checkyesno Ar var
  52 .It
  53 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
  54 .It
  55 .Ic check_process Ar procname Op Ar interpreter
  56 .It
  57 .Ic debug Ar message
  58 .It
  59 .Ic err Ar exitval Ar message
  60 .It
  61 .Ic force_depend Ar name
  62 .It
  63 .Ic info Ar message
  64 .It
  65 .Ic load_rc_config Ar command
  66 .It
  67 .Ic mount_critical_filesystems Ar type
  68 .It
  69 .Ic rc_usage Ar command Op Ar ...
  70 .It
  71 .Ic reverse_list Ar item Op Ar ...
  72 .It
  73 .Ic run_rc_command Ar argument
  74 .It
  75 .Ic run_rc_script Ar file Ar argument
  76 .It
  77 .Ic set_rcvar Op Ar base
  78 .It
  79 .Ic wait_for_pids Op Ar pid Op Ar ...
  80 .It
  81 .Ic warn Ar message
  82 .El
  83 .Sh DESCRIPTION
  84 .Nm
  85 contains commonly used shell script functions and variable
  86 definitions which are used by various scripts such as
  87 .Xr rc 8 .
  88 Scripts required by ports in
  89 .Pa /usr/local/etc/rc.d
  90 will also eventually
  91 be rewritten to make use of it.
  92 .Pp
  93 The
  94 .Nm
  95 functions were mostly imported from
  96 .Nx
  97 and it is intended that they remain synced between the
  98 two projects. With that in mind there are several variable
  99 definitions that can help in this regard. They are:
 100 .Bl -tag -width 4n
 101 .It Ic OSTYPE
 102 Its value will be either
 103 .Fx
 104 or
 105 .Nx ,
 106 depending on which OS it is running on.
 107 .It Ic SYSCTL
 108 The path to the
 109 .Xr sysctl 8
 110 command.
 111 .It Ic SYSCTL_N
 112 The path and argument list to display only the
 113 .Xr sysctl 8
 114 values instead of a name=value pair.
 115 .It Ic SYSCTL_W
 116 The path and argument to write or modify
 117 .Xr sysctl 8
 118 values.
 119 .El
 120 .Pp
 121 The
 122 .Nm
 123 functions are accessed by sourcing
 124 .Pa /etc/rc.subr
 125 into the current shell.
 126 .Pp
 127 The following shell functions are available:
 128 .Bl -tag -width 4n
 129 .It Xo
 130 .Ic backup_file Ar action Ar file Ar current Ar backup
 131 .Xc
 132 Make a backup copy of
 133 .Ar file
 134 into
 135 .Ar current .
 136 If the
 137 .Xr rc.conf 5
 138 variable
 139 .Sy backup_uses_rcs
 140 is
 141 .Sq YES ,
 142 use
 143 .Xr rcs 1
 144 to archive the previous version of
 145 .Ar current ,
 146 otherwise save the previous version of
 147 .Ar current
 148 as
 149 .Ar backup .
 150 .Pp
 151 .Ar action
 152 may be one of the following:
 153 .Bl -tag -width remove
 154 .It Sy add
 155 .Ar file
 156 is now being backed up by or possibly re-entered into this backup mechanism.
 157 .Ar current
 158 is created, and if necessary, the
 159 .Xr rcs 1
 160 files are created as well.
 161 .It Sy update
 162 .Ar file
 163 has changed and needs to be backed up.
 164 If
 165 .Ar current
 166 exists, it is copied to
 167 .Ar backup
 168 or checked into
 169 .Xr rcs 1
 170 (if the repository file is old),
 171 and then
 172 .Ar file
 173 is copied to
 174 .Ar current .
 175 .It Sy remove
 176 .Ar file
 177 is no longer being tracked by this backup mechanism.
 178 If
 179 .Xr rcs 1
 180 is being used, an empty file is checked in and
 181 .Ar current
 182 is removed,
 183 otherwise
 184 .Ar current
 185 is moved to
 186 .Ar backup .
 187 .El
 188 .It Ic checkyesno Ar var
 189 Return 0 if
 190 .Ar var
 191 is defined to
 192 .Sq YES ,
 193 .Sq TRUE ,
 194 .Sq ON ,
 195 or
 196 .Sq 1 .
 197 Return 1 if
 198 .Ar var
 199 is defined to
 200 .Sq NO ,
 201 .Sq FALSE ,
 202 .Sq OFF ,
 203 or
 204 .Sq 0 .
 205 Otherwise, warn that
 206 .Ar var
 207 is not set correctly.
 208 The values are case insensitive.
 209 .It Xo
 210 .Ic check_pidfile
 211 .Ar pidfile
 212 .Ar procname
 213 .Op Ar interpreter
 214 .Xc
 215 Parses the first word of the first line of
 216 .Ar pidfile
 217 for a PID, and ensures that the process with that PID
 218 is running and its first argument matches
 219 .Ar procname .
 220 Prints the matching PID if successfull, otherwise nothing.
 221 If
 222 .Ar interpreter
 223 is provided, parse the first line of
 224 .Ar procname ,
 225 ensure that the line is of the form
 226 .Dl #! interpreter [...]
 227 and use
 228 .Ar interpreter
 229 with its optional arguments and
 230 .Ar procname
 231 appended as the process string to search for.
 232 .It Ic check_process Ar procname Op Ar interpreter
 233 Prints the PIDs of any processes that are running with a first
 234 argument that matches
 235 .Ar procname .
 236 .Ar interpreter
 237 is handled as per
 238 .Ic check_pidfile .
 239 .It Ic debug Ar message
 240 Display a debugging message to
 241 .Em stderr ,
 242 log it to the system log using
 243 .Xr logger 1 ,
 244 and
 245 return to the caller.
 246 The error message consists of the script name
 247 (from
 248 .Sy $0 ) ,
 249 followed by
 250 .Dq ": DEBUG: " ,
 251 and then
 252 .Ar message .
 253 This function is intended to be used by developers
 254 as an aid to debugging scripts. It can be turned on or off
 255 by the
 256 .Xr rc.conf 5
 257 variable
 258 .Em rc_debug .
 259 .It Ic err Ar exitval Ar message
 260 Display an error message to
 261 .Em stderr ,
 262 log it to the system log
 263 using
 264 .Xr logger 1 ,
 265 and
 266 .Cm exit
 267 with an exit value of
 268 .Ar exitval .
 269 The error message consists of the script name
 270 (from
 271 .Sy $0 ) ,
 272 followed by
 273 .Dq ": ERROR: " ,
 274 and then
 275 .Ar message .
 276 .It Ic force_depend name
 277 Output an advisory message and force the
 278 .Ar name
 279 service to start. The
 280 .Ar name
 281 argument is the
 282 .Xr basename 1 ,
 283 component of the path to the script, usually
 284 .Em /etc/rc.d/name .
 285 If the script fails for any reason it will output a warning
 286 and return with a return value of 1. If it was successful
 287 it will return 0.
 288 .It Ic info Ar message
 289 Display an informational message to
 290 .Em stdout ,
 291 and log it to the system log using
 292 .Xr logger 1 .
 293 The message consists of the script name
 294 (from
 295 .Sy $0 ) ,
 296 followed by
 297 .Dq ": INFO: " ,
 298 and then
 299 .Ar message .
 300 The display of this informational output can be
 301 turned on or off by the
 302 .Xr rc.conf 5
 303 variable
 304 .Em rc_info .
 305 .It Ic load_rc_config Ar command
 306 Source in the configuration files for
 307 .Ar command .
 308 First,
 309 .Pa /etc/rc.conf
 310 is sourced if it has not yet been read in.
 311 Then,
 312 .Pa /etc/rc.conf.d/ Ns Ar command
 313 is sourced if it is an existing file.
 314 The latter may also contain other variable assignments to override
 315 .Ic run_rc_command
 316 arguments defined by the calling script, to provide an easy
 317 mechanism for an administrator to override the behaviour of a given
 318 .Xr rc.d 8
 319 script without requiring the editing of that script.
 320 .It Ic mount_critical_filesystems Ar type
 321 Go through a list of critical file systems,
 322 as found in the
 323 .Xr rc.conf 5
 324 variable
 325 .Sy critical_filesystems_ Ns Ar type ,
 326 mounting each one that
 327 is not currently mounted.
 328 .It Ic rc_usage Ar command Op Ar ...
 329 Print a usage message for
 330 .Sy $0 ,
 331 with
 332 .Ar commands
 333 being the list of valid arguments
 334 prefixed by
 335 .Dq "[fast|force]" .
 336 .It Ic reverse_list Ar item Op Ar ...
 337 Print the list of
 338 .Ar items
 339 in reverse order.
 340 .It Ic run_rc_command Ar argument
 341 Run the
 342 .Ar argument
 343 method for the current
 344 .Xr rc.d 8
 345 script, based on the settings of various shell variables.
 346 .Ic run_rc_command
 347 is extremely flexible, and allows fully functional
 348 .Xr rc.d 8
 349 scripts to be implemented in a small amount of shell code.
 350 .Pp
 351 .Ar argument
 352 is searched for in the list of supported commands, which may be one
 353 of:
 354 .Dl start stop restart rcvar
 355 as well as any word listed in the optional variable
 356 .Sy extra_commands .
 357 If
 358 .Sy pidfile
 359 or
 360 .Sy procname
 361 is set, also allow:
 362 .Dl status poll
 363 .Pp
 364 .Ar argument
 365 may have one of the following prefixes which alters its operation:
 366 .Bl -tag -width "Prefix" -offset indent -compact
 367 .It Sy Prefix
 368 .Sy Operation
 369 .It Li fast
 370 Skip the check for an existing running process,
 371 and sets
 372 .Sy rc_fast=YES .
 373 .It Li force
 374 Skip the checks for
 375 .Sy rcvar
 376 being set to yes,
 377 and sets
 378 .Sy rc_force=YES .
 379 This ignores
 380 .Ar argument Ns Sy _precmd
 381 returning non-zero, and ignores any of the
 382 .Sy required_*
 383 tests failing .
 384 .El
 385 .Pp
 386 .Ic run_rc_command
 387 uses the following shell variables to control its behaviour.
 388 Unless otherwise stated, these are optional.
 389 .Bl -tag -width procname -offset indent
 390 .It Sy name
 391 The name of this script.
 392 This is not optional.
 393 .It Sy rcvar
 394 The value of
 395 .Sy rcvar
 396 is checked with
 397 .Ic checkyesno
 398 to determine if this method should be run.
 399 .It Sy command
 400 Full path to the command.
 401 Not required if
 402 .Ar argument Ns Sy _cmd
 403 is defined for each supported keyword.
 404 .It Sy command_args
 405 Optional arguments and/or shell directives for
 406 .Sy command .
 407 .It Sy command_interpreter
 408 .Sy command
 409 is started with
 410 .Dl #! command_interpreter [...]
 411 which results in its
 412 .Xr ps 1
 413 command being
 414 .Dl command_interpreter [...] command
 415 so use that string to find the PID(s) of the running command
 416 rather than
 417 .Ql command .
 418 .It Sy extra_commands
 419 Extra commands/keywords/arguments supported.
 420 .It Sy pidfile
 421 Path to pid file.
 422 Used to determine the PID(s) of the running command.
 423 If
 424 .Sy pidfile
 425 is set, use
 426 .Dl check_pidfile $pidfile $procname
 427 to find the PID.
 428 Otherwise, if
 429 .Sy command
 430 is set, use
 431 .Dl check_process $procname
 432 to find the PID.
 433 .It Sy procname
 434 Process name to check for.
 435 Defaults to the value of
 436 .Sy command .
 437 .It Sy required_dirs
 438 Check for the existence of the listed directories
 439 before running the default start method.
 440 .It Sy required_files
 441 Check for the readability of the listed files
 442 before running the default start method.
 443 .It Sy required_vars
 444 Perform
 445 .Ic checkyesno
 446 on each of the list variables
 447 before running the default start method.
 448 .It Sy ${name}_chdir
 449 Directory to
 450 .Ic cd
 451 to before running
 452 .Sy command ,
 453 if
 454 .Sy ${name}_chroot
 455 is not provided.
 456 .It Sy ${name}_chroot
 457 Directory to
 458 .Xr chroot 8
 459 to before running
 460 .Sy command .
 461 Only supported after
 462 .Pa /usr
 463 is mounted.
 464 .It Sy ${name}_flags
 465 Arguments to call
 466 .Sy command
 467 with.
 468 This is usually set in
 469 .Xr rc.conf 5 ,
 470 and not in the
 471 .Xr rc.d 8
 472 script.
 473 The environment variable
 474 .Sq Ev flags
 475 can be used to override this.
 476 .It Sy ${name}_nice
 477 .Xr nice 1
 478 level to run
 479 .Sy command
 480 as.
 481 Only supported after
 482 .Pa /usr
 483 is mounted.
 484 .It Sy ${name}_user
 485 User to run
 486 .Sy command
 487 as, using
 488 .Xr chroot 8 .
 489 if
 490 .Sy ${name}_chroot
 491 is set, otherwise
 492 uses
 493 .Xr su 1 .
 494 Only supported after
 495 .Pa /usr
 496 is mounted.
 497 .It Sy ${name}_group
 498 Group to run the chrooted
 499 .Sy command
 500 as.
 501 .It Sy ${name}_groups
 502 Comma separated list of supplementary groups to run the chrooted
 503 .Sy command
 504 with.
 505 .It Ar argument Ns Sy _cmd
 506 Shell commands which override the default method for
 507 .Ar argument .
 508 .It Ar argument Ns Sy _precmd
 509 Shell commands to run just before running
 510 .Ar argument Ns Sy _cmd
 511 or the default method for
 512 .Ar argument .
 513 If this returns a non-zero exit code, the main method is not performed.
 514 If the default method is being executed, this check is performed after
 515 the
 516 .Sy required_*
 517 checks and process (non-)existence checks.
 518 .It Ar argument Ns Sy _postcmd
 519 Shell commands to run if running
 520 .Ar argument Ns Sy _cmd
 521 or the default method for
 522 .Ar argument
 523 returned a zero exit code.
 524 .It Sy sig_stop
 525 Signal to send the processes to stop in the default
 526 .Sy stop
 527 method.
 528 Defaults to
 529 .Dv SIGTERM .
 530 .It Sy sig_reload
 531 Signal to send the processes to reload in the default
 532 .Sy reload
 533 method.
 534 Defaults to
 535 .Dv SIGHUP .
 536 .El
 537 .Pp
 538 For a given method
 539 .Ar argument ,
 540 if
 541 .Ar argument Ns Sy _cmd
 542 is not defined, then a default method is provided by
 543 .Sy run_rc_command :
 544 .Bl -tag -width "argument" -offset indent
 545 .It Sy Argument
 546 .Sy Default method
 547 .It Sy start
 548 If
 549 .Sy command
 550 is not running and
 551 .Ic checkyesno Sy rcvar
 552 succeeds, start
 553 .Sy command .
 554 .It Sy stop
 555 Determine the PIDs of
 556 .Sy command
 557 with
 558 .Ic check_pidfile
 559 or
 560 .Ic check_process
 561 (as appropriate),
 562 .Ic kill Sy sig_stop
 563 those PIDs, and run
 564 .Ic wait_for_pids
 565 on those PIDs.
 566 .It Sy reload
 567 Similar to
 568 .Sy stop ,
 569 except that it uses
 570 .Sy sig_reload
 571 instead, and doesn't run
 572 .Ic wait_for_pids .
 573 .It Sy restart
 574 Runs the
 575 .Sy stop
 576 method, then the
 577 .Sy start
 578 method.
 579 .It Sy status
 580 Show the PID of
 581 .Sy command ,
 582 or some other script specific status operation.
 583 .It Sy poll
 584 Wait for
 585 .Sy command
 586 to exit.
 587 .It Sy rcvar
 588 Display which
 589 .Xr rc.conf 5
 590 variable is used (if any).
 591 This method always works, even if the appropriate
 592 .Xr rc.conf 5
 593 variable is set to
 594 .Sq NO .
 595 .El
 596 .Pp
 597 The following variables are available to the methods
 598 (such as
 599 .Ar argument Ns Sy _cmd )
 600 as well as after
 601 .Ic run_rc_command
 602 has completed:
 603 .Bl -tag -width "rc_flags" -offset indent
 604 .It Sy rc_arg
 605 Argument provided to
 606 .Sy run_rc_command ,
 607 after fast and force processing has been performed.
 608 .It Sy rc_flags
 609 Flags to start the default command with.
 610 Defaults to
 611 .Sy ${name}_flags ,
 612 unless overridden by the environment variable
 613 .Sq Ev flags .
 614 This variable may be changed by the
 615 .Ar argument Ns Sy _precmd
 616 method.
 617 .It Sy rc_pid
 618 PID of
 619 .Sy command
 620 (if appropriate).
 621 .It Sy rc_fast
 622 Not empty if
 623 .Dq fast
 624 prefix was used.
 625 .It Sy rc_force
 626 Not empty if
 627 .Dq force
 628 prefix was used.
 629 .El
 630 .It Ic run_rc_script Ar file Ar argument
 631 Start the script
 632 .Ar file
 633 with an argument of
 634 .Ar argument ,
 635 and handle the return value from the script.
 636 .Pp
 637 Various shell variables are unset before
 638 .Ar file
 639 is started:
 640 .Bd -ragged -offset indent
 641 .Sy name ,
 642 .Sy command ,
 643 .Sy command_args ,
 644 .Sy command_interpreter ,
 645 .Sy extra_commands ,
 646 .Sy pidfile ,
 647 .Sy rcvar ,
 648 .Sy required_dirs ,
 649 .Sy required_files ,
 650 .Sy required_vars ,
 651 .Ar argument Ns Sy _cmd ,
 652 .Ar argument Ns Sy _precmd .
 653 .Ar argument Ns Sy _postcmd .
 654 .Ed
 655 .Pp
 656 The startup behaviour of
 657 .Ar file
 658 depends upon the following checks:
 659 .Bl -enum
 660 .It
 661 If
 662 .Ar file
 663 ends in
 664 .Pa .sh ,
 665 it is sourced into the current shell.
 666 .It
 667 If
 668 .Ar file
 669 appears to be a backup or scratch file
 670 (e.g., with a suffix of
 671 .Sq ~ ,
 672 .Sq # ,
 673 .Sq .OLD ,
 674 or
 675 .Sq .orig ) ,
 676 ignore it.
 677 .It
 678 If
 679 .Ar file
 680 is not executable, ignore it.
 681 .It
 682 If the
 683 .Xr rc.conf 5
 684 variable
 685 .Sy rc_fast_and_loose
 686 is empty,
 687 source
 688 .Ar file
 689 in a sub shell,
 690 otherwise source
 691 .Ar file
 692 into the current shell.
 693 .El
 694 .It Ic set_rcvar Op Ar base
 695 Set the variable name required to start a service. In
 696 .Fx
 697 a daemon is usually controlled by an
 698 .Xr rc.conf 5
 699 variable consisting of a daemon's name postfixed by the string
 700 .Sy "_enable" .
 701 This is not the case in
 702 .Nx .
 703 When the following line is included in a script
 704 .Pp
 705 .Dl rcvar=`set_rcvar`
 706 .Pp
 707 This function will use the value of the
 708 .Sy $name
 709 variable, which should be defined by the calling script, to construct the appropriate
 710 .Xr rc.conf 5
 711 knob. If the
 712 .Ar base
 713 argument is set it will use
 714 .Ar base
 715 instead of
 716 .Sy $name .
 717 .It Ic wait_for_pids Op Ar pid Op Ar ...
 718 Wait until all of the provided
 719 .Ar pids
 720 don't exist any more, printing the list of outstanding
 721 .Ar pids
 722 every two seconds.
 723 .It Ic warn Ar message
 724 Display a warning message to
 725 .Em stderr
 726 and log it to the system log
 727 using
 728 .Xr logger 1 .
 729 The warning message consists of the script name
 730 (from
 731 .Sy $0 ) ,
 732 followed by
 733 .Dq ": WARNING: " ,
 734 and then
 735 .Ar message .
 736 .El
 737 .Sh FILES
 738 .Bl -tag -width /etc/rc.subr -compact
 739 .It Pa /etc/rc.subr
 740 The
 741 .Nm
 742 file resides in
 743 .Pa /etc .
 744 .El
 745 .Sh SEE ALSO
 746 .Xr rc.conf 5 ,
 747 .Xr rc 8
 748 .Sh HISTORY
 749 .Nm
 750 appeared in
 751 .Nx 1.3 .
 752 The
 753 .Xr rc.d 8
 754 support functions appeared in
 755 .Nx 1.5 .
 756 .Nm
 757 first appeared in
 758 .Fx 5.0 .