.\" 	%NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp %
.\"
.\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Luke Mewburn.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the NetBSD
.\"	Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" %FreeBSD: src/share/man/man8/rc.subr.8,v 1.6 2004/07/09 10:08:03 ru Exp %
.\"
.\" $FreeBSD$
.Dd January 6, 2004
.Dt RC.SUBR 8
.Os
.Sh 名称
.Nm rc.subr
.Nd システムシェルスクリプトで使用する関数群
.Sh 書式
.Bl -item -compact
.It
.Ic .\& Pa /etc/rc.subr
.Pp
.It
.Ic backup_file Ar action Ar file Ar current Ar backup
.It
.Ic checkyesno Ar var
.It
.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
.It
.Ic check_process Ar procname Op Ar interpreter
.It
.Ic debug Ar message
.It
.Ic err Ar exitval Ar message
.It
.Ic force_depend Ar name
.It
.Ic info Ar message
.It
.Ic load_rc_config Ar command
.It
.Ic mount_critical_filesystems Ar type
.It
.Ic rc_usage Ar command ...
.It
.Ic reverse_list Ar item ...
.It
.Ic run_rc_command Ar argument
.It
.Ic run_rc_script Ar file Ar argument
.It
.Ic wait_for_pids Op Ar pid ...
.It
.Ic warn Ar message
.El
.Sh 解説
.Nm
スクリプトは、
.Xr rc 8
のような様々なスクリプトから共通に利用される
シェルスクリプト関数や変数定義を含んでいます。
また ports が要求する
.Pa /usr/local/etc/rc.d
内のスクリプトも、やがては本スクリプトを使用するように
書き換えられるでしょう。
.Pp
.Nm
の関数群は大部分が
.Nx
から取り込まれたものであり、またそれらは二つのプロジェクト間で同期を
とり続けられるように
考えられています。
これを念頭において、この点に関して助けとなる変数定義がいくつかあります:
.Bl -tag -width 4n
.It Va OSTYPE
この値は
.Qq Li FreeBSD
か
.Qq Li NetBSD
のどちらかで、実行されている OS によります。
.It Va SYSCTL
.Xr sysctl 8
コマンドのパス。
.It Va SYSCTL_N
.Ar name Ns = Ns Ar value
のペアとしてではなく、
.Xr sysctl 8
値のみを表示する際の、パスと引数のリスト。
.It Va SYSCTL_W
.Xr sysctl 8
値を設定または変更する際の、パスと引数。
.El
.Pp
.Nm
関数群は、カレントシェルで
.Pa /etc/rc.subr
を読み込むことで利用できるようになります。
.Pp
以下のシェル関数が利用可能です:
.Bl -tag -width 4n
.It Ic backup_file Ar action file current backup
.Ar file
のバックアップコピーを
.Ar current
として作成します。
.Xr rc.conf 5
変数の
.Va backup_uses_rcs
が
.Dq Li YES
である場合、以前のバージョンの
.Ar current
は
.Xr rcs 1
を使ってアーカイブします。
そうでない場合の、以前のバージョンの
.Ar current
を
.Ar backup
として保存します。
.Pp
引数
.Ar action
は次のうちのどれかです:
.Bl -tag -width ".Cm remove"
.It Cm add
.Ar file
はこのバックアップ機構により今後バックアップされるようになるか、
あるいは再度追加されます。
.Ar current
が作成され、必要なら、
.Xr rcs 1
ファイルが同様に作成されます。
.It Cm update
.Ar file
は変更されており、バックアップを取る必要があります。
.Ar current
が存在するなら、
.Ar backup
にコピーされるか、もしくは
.Xr rcs 1
にチェックインされます (リポジトリファイルが古い場合)。
その後に、
.Ar file
が
.Ar current
にコピーされます。
.It Cm remove
.Ar file
はこのバックアップ機構で管理されなくなります。
.Xr rcs 1
が使われている場合は、空のファイルがチェックインされて
.Ar current
は削除されます。
そうでない場合は、
.Ar current
は
.Ar backup
に移動します。
.El
.It Ic checkyesno Ar var
.Ar var
の値が
.Dq Li YES ,
.Dq Li TRUE ,
.Dq Li ON ,
.Ql 1
ならば、0 を返します。
.Ar var
の値が
.Dq Li NO ,
.Dq Li FALSE ,
.Dq Li OFF ,
.Ql 0
ならば、1 を返します。
これら以外の値ならば、
.Ar var
が正しく設定されていないという警告を出します。
値は大文字 / 小文字を問いません。
.It Ic check_pidfile Ar pidfile procname Op Ar interpreter
.Ar pidfile
の最初の行の最初の語を解析して PID とし、この PID を持つプロセスが
実行されていて、最初の引数が
.Ar procname
にマッチすることを確認します。
成功すればマッチした PID を出力し、そうでない場合は何もしません。
.Ar interpreter
が与えられた場合、
.Ar procname
の最初の行を解析して、
.Pp
.Dl "#! interpreter [...]"
.Pp
という形式であることを確かめます。
そして
.Ar interpreter
とオプション引数に
.Ar procname
を追加したものを、検索するプロセス文字列として使用します。
.It Ic check_process Ar procname Op Ar interpreter
最初の引数が
.Ar procname
にマッチする、実行されているすべてのプロセスの PID を出力します。
.Ar interpreter
は
.Ic check_pidfile
と同様に扱われます。
.It Ic debug Ar message
デバッグメッセージを
.Va stderr
に表示し、
.Xr logger 1
を使用してシステムログに記録をして、呼び出し元に戻ります。
このエラーメッセージは、スクリプト名
.Va ( $0
より),
.Dq Li ": DEBUG: " ,
およびこれに続く
.Ar message
で構成されます。
この関数はスクリプトのデバッグの手助けとして、開発者が使用することを
目的にしています。
これは
.Xr rc.conf 5
変数の
.Va rc_debug
により、有効あるいは無効にすることができます。
.It Ic err Ar exitval message
エラーメッセージを
.Va stderr
に表示し、
.Xr logger 1
を使用してシステムログに記録をして、終了値
.Ar exitval
で
.Ic 終了
します。
このエラーメッセージは、スクリプト名
.Va ( $0
より),
.Dq Li ": ERROR: " ,
およびこれに続く
.Ar message
で構成されます。
.It Ic force_depend name
勧告メッセージを出力し、
.Ar name
サービスを強制的に起動します。
引数
.Ar name
は、通常
.Pa /etc/rc.d/name
といったスクリプトのパスの
.Xr basename 1
要素です。
スクリプトが何らかの原因で失敗した場合、警告を出力して戻り値 1 を返します。
成功した場合は、戻り値 0 を返します。
.It Ic info Ar message
情報メッセージを
.Va stdout
に表示し、
.Xr logger 1
を使用してシステムログに記録をします。
このメッセージは、スクリプト名
.Va ( $0
より),
.Dq Li ": INFO: " ,
およびこれに続く
.Ar message
で構成されます。
この情報出力の表示は
.Xr rc.conf 5
変数の
.Va rc_info
により、有効あるいは無効にすることができます。
.It Ic load_rc_config Ar command
.Ar command
の設定ファイルを読み込みます。
最初に、
.Pa /etc/rc.conf
がまだ読み込まれていなければ、読み込みます。
その後に、ファイル
.Pa /etc/rc.conf.d/ Ns Ar command
が存在すれば、これを読み込みます。
後者は呼び出しスクリプト側で指定した
.Ic run_rc_command
引数を上書きする変数定義を含めることもできます。
これは管理者が任意の
.Xr rc.d 8
スクリプトを編集することなく、その動作を上書きできる簡易な仕組みを提供します。
.It Ic mount_critical_filesystems Ar type
.Xr rc.conf 5
変数の
.Va critical_filesystems_ Ns Ar type
で定義された重要なファイルシステムの一覧のうち、この時点でマウントされて
いないものがあれば、マウントします。
.It Ic rc_usage Ar command ...
.Va $0
の使用方法を、有効な引数の一覧である
.Ar command
に
.Sm off
.Dq Bq Li fast | force | one
.Sm on
のプレフィックスをつけて出力します。
.It Ic reverse_list Ar item ...
.Ar item
のリストを逆順で出力します。
.It Ic run_rc_command Ar argument
各種のシェル変数の設定に基づいて、現在の
.Xr rc.d 8
スクリプトの、
.Ar argument
処理を実行します。
.Ic run_rc_command
はきわめて柔軟性があり、完全に機能する
.Xr rc.d 8
スクリプトを小量のシェルコードで記述することができます。
.Pp
.Ar argument
はサポートされているコマンドから検索され、それは以下のうちのどれかです:
.Bl -tag -width ".Cm restart" -offset indent
.It Cm start
サービスを起動します。
本コマンドは、
.Xr rc.conf 5
の指定によりサービスを起動するべきかをチェックします。
またサービスが既に実行中であるかをチェックし、その場合は起動を拒否します。
標準の
.Fx
スクリプトにおいて、システムが直接マルチユーザモードで起動する場合は、
起動プロセスの高速化のために、後者のチェックは行われません。
.It Cm stop
.Xr rc.conf 5
の指定によりサービスが起動していれば、サービスを停止します。
本コマンドはサービスが実行中かどうかをチェックし、そうでない場合、
その旨を表示します。
.It Cm restart
.Cm stop
の後に、
.Cm start
を実行します。
デフォルトでは、 (もし実行中なら) プログラムのプロセス ID を表示します。
.It Cm rcvar
どの
.Xr rc.conf 5
変数がサービスの起動を制御しているか、(もしあれば) 表示します。
.El
.Pp
.Va pidfile
または
.Va procname
が設定されていれば、以下もサポートされています:
.Bl -tag -width ".Cm restart" -offset indent
.It Cm poll
コマンドが終了するのを待ちます。
.It Cm status
プロセスの状態を表示します。
.El
.Pp
他にサポートされているコマンドは、オプション変数の
.Va extra_commands
に列挙されています。
.Pp
.Ar argument
はそれ自身の動作を変更する、以下のプレフィックスをつけることができます:
.Bl -tag -width ".Li force" -offset indent
.It Li fast
実行中のプロセスの有無をチェックしません。
.Va rc_fast Ns = Ns Li YES
をセットします。
.It Li force
.Va rcvar
が
.Dq Li YES
にセットされているかどうかをチェックしません。
.Va rc_force Ns = Ns Li YES
をセットします。
.Ar argument Ns Va _precmd
が非 0 を返したり、
.Va required_*
テストのどれかが失敗したりしても無視します。
また終了ステータスとして常に 0 を返します。
.It Li one
.Va rcvar
が
.Dq Li YES
にセットされているかどうかをチェックしません。
しかし他の全ての前提チェックは行います。
.El
.Pp
.Ic run_rc_command
はその動作を制御するために、以下のシェル変数を使用します。
特に明記が無いものは、オプションです。
.Bl -tag -width ".Va procname" -offset indent
.It Va name
このスクリプトの名称。
これはオプションではありません。
.It Va rcvar
.Va rcvar
の値は
.Ic checkyesno
によりチェックされ、この処理を実行するかどうかを判定します。
.It Va command
コマンドのフルパス。
サポートされている各キーワードに対して
.Ar argument Ns Va _cmd
が設定されている場合は、必要ありません。
.It Va command_args
オプション引数、および / または
.Va command
に対するシェルディレクティブ。
.It Va command_interpreter
.Va command
は
.Pp
.Dl "#! command_interpreter [...]"
という形式で起動されるので、
.Xr ps 1
コマンドの出力は
.Pp
.Dl "command_interpreter [...] command"
.Pp
のようになります。
ですので、実行中のコマンドの PID を検索するのに、
.Va command
ではなくこの文字列を使用します。
.It Va extra_commands
特別にサポートするコマンド / キーワード / 引数。
.It Va pidfile
PID ファイルのパス。
実行中のコマンドの PID を特定するのに使用します。
.Va pidfile
が設定された場合、 PID を検索するには
.Pp
.Dl "check_pidfile $pidfile $procname"
.Pp
を使用します。
そうでなければ、
.Va command
が設定されている場合、 PID を検索するには
.Pp
.Dl "check_process $procname"
.Pp
を使用します。
.It Va procname
チェックする対象プロセス名。
デフォルトでは
.Va command
の値です。
.It Va required_dirs
デフォルトの start 処理を実行する前に、これに列挙された各ディレクトリの
存在をチェックします。
.It Va required_files
デフォルトの start 処理を実行する前に、これに列挙された各ファイルが
読み取り可能かどうかをチェックします。
.It Va required_vars
デフォルトの start 処理を実行する前に、これに列挙された各変数に対して
.Ic checkyesno
を適用します。
.It Va ${name}_chdir
.Va ${name}_chroot
が提供されない場合、
.Va command
を実行する前に
.Ic cd
するディレクトリ。
.It Va ${name}_chroot
.Va command
を実行する前に
.Xr chroot 8
するディレクトリ。
.Pa /usr
がマウントされた後にのみサポートされています。
.It Va ${name}_flags
.Va command
の呼び出し時に適用する引数。
これは通常
.Xr rc.conf 5
で設定され、
.Xr rc.d 8
スクリプトで設定されるものではありません。
これを上書きするのに、環境変数の
.Sq Ev flags
を使うことができます。
.It Va ${name}_nice
.Va command
を実行する際の
.Xr nice 1
レベル。
.Pa /usr
がマウントされた後にのみサポートされています。
.It Va ${name}_user
.Va command
を実行する際のユーザ。
.Va ${name}_chroot
が設定されている場合は
.Xr chroot 8
を使用し、そうでなければ
.Xr su 1
を使用します。
.Pa /usr
がマウントされた後にのみサポートされています。
.It Va ${name}_group
chroot 後に
.Va command
を実行する際のグループ。
.It Va ${name}_groups
コンマで区切られたリストで、 chroot 後に
.Va command
を実行する際の補助グループ。
.It Ar argument Ns Va _cmd
.Ar argument
のデフォルト処理を上書きするシェルコマンド。
.It Ar argument Ns Va _precmd
.Ar argument Ns Va _cmd
を実行する直前、もしくは
.Ar argument
のデフォルト処理の直前に実行するシェルコマンド。
もしこれが非 0 の終了コードを返した場合、メイン処理は行われません。
デフォルト処理が実行されるならば、このチェックは
.Va required_*
チェックとプロセスの (非) 存在チェックの後に行われます。
.It Ar argument Ns Va _postcmd
実行された
.Ar argument Ns Va _cmd
、もしくは
.Ar argument
のデフォルト処理が終了コード 0 を返した時に実行されるシェルコマンド。
.It Va sig_stop
デフォルトの
.Cm stop
処理において、プロセスを停止するのに送られるシグナル。
デフォルトは
.Dv SIGTERM
です。
.It Va sig_reload
デフォルトの
.Cm reload
処理において、プロセスに再読み込みさせるのに送られるシグナル。
デフォルトは
.Dv SIGHUP
です。
.El
.Pp
.Ar argument
で与えられた処理に対して、
.Ar argument Ns Va _cmd
が定義されていなければ、デフォルト処理が
.Ic run_rc_command
によって与えられます:
.Bl -tag -width ".Sy Argument" -offset indent
.It Sy argument
.Sy デフォルト処理
.It Cm start
.Va command
が実行されておらず、
.Ic checkyesno Va rcvar
が成功すれば、
.Va command
を起動します。
.It Cm stop
.Ic check_pidfile
または
.Ic check_process
(適切なほう) により
.Va command
の PID を特定し、それらの PID に対して
.Ic kill Va sig_stop
を実行し、そしてそれらの PID に対して
.Ic wait_for_pids
を実行します。
.It Cm reload
.Cm stop
と似ていますが、違うのは代わりに
.Va sig_reload
を使い、
.Ic wait_for_pids
を実行しないことです。
.It Cm restart
.Cm stop
処理を実行後に、
.Cm start
処理を実行します。
.It Cm status
.Va command
の PID を表示するか、もしくはスクリプト固有のステータス情報を表示します。
.It Cm poll
.Va command
が終了するのを待ちます。
.It Cm rcvar
使用される
.Xr rc.conf 5
変数を (もしあれば) 表示します。
この処理は、対応する
.Xr rc.conf 5
変数が
.Dq Li NO
に設定されていても動作します。
.El
.Pp
以下の変数は、
.Ic run_rc_command
が完了した後だけでなく、
.Ar ( argument Ns Va _cmd
のような) 処理でも同様に参照できます:
.Bl -tag -width ".Va rc_flags" -offset indent
.It Va rc_arg
fast 及び force 処理が済んだ後の、
.Ic run_rc_command
に与えられた引数。
.It Va rc_flags
デフォルトのコマンド実行時のフラグ。
環境変数の
.Sq Ev flags
で上書きされない限り、デフォルトは
.Va ${name}_flags
です。
この変数は
.Ar argument Ns Va _precmd
処理で変更することができます。
.It Va rc_pid
.Va command
の PID (もしあるならば)。
.It Va rc_fast
.Dq Li fast
プレフィックスが使われた場合、空ではありません。
.It Va rc_force
.Dq Li force
プレフィックスが使われた場合、空ではありません。
.El
.It Ic run_rc_script Ar file argument
スクリプト
.Ar file
を引数
.Ar argument
で実行し、スクリプトからの戻り値を処理します。
.Pp
.Ar file
が実行される前に、多くのシェル変数が消去されます:
.Bd -ragged -offset indent
.Va name ,
.Va command ,
.Va command_args ,
.Va command_interpreter ,
.Va extra_commands ,
.Va pidfile ,
.Va rcvar ,
.Va required_dirs ,
.Va required_files ,
.Va required_vars ,
.Ar argument Ns Va _cmd ,
.Ar argument Ns Va _precmd .
.Ar argument Ns Va _postcmd .
.Ed
.Pp
.Ar file
起動時の動作は、以下のチェックに依るものになります:
.Bl -enum
.It
.Ar file
の名前が
.Pa .sh
で終わっていれば、カレントシェルに読み込まれます。
.It
.Ar file
がバックアップもしくは一時ファイルのようならば
(例. サフィックスが
.Pa ~ , # , .OLD , .orig
である)、無視します。
.It
.Ar file
が実行可能でなければ、無視します。
.It
.Xr rc.conf 5
変数の
.Va rc_fast_and_loose
が空ならば、
.Ar file
をサブシェルで読み込みます。
そうでなければ、カレントシェルで
.Ar file
を読み込みます。
.El
.It Ic wait_for_pids Op Ar pid ...
指定された全ての
.Ar pid
が消失するまで待ち、 2 秒ごとに残存している
.Ar pid
を出力します。
.It Ic warn Ar message
警告メッセージを
.Va stderr
に表示し、
.Xr logger 1
を使用してシステムログに記録をします。
この警告メッセージは、スクリプト名
.Va ( $0
より),
.Dq Li ": WARNING: " ,
およびこれに続く
.Ar message
で構成されます。
.El
.Sh 関連ファイル
.Bl -tag -width ".Pa /etc/rc.subr" -compact
.It Pa /etc/rc.subr
.Nm
ファイルは
.Pa /etc
に存在します。
.El
.Sh 関連項目
.Xr rc.conf 5 ,
.Xr rc 8
.Sh 歴史
.Nm
スクリプトは
.Nx 1.3
で登場しました。
.Xr rc.d 8
をサポートする関数は
.Nx 1.5
で登場しました。
.Nm
スクリプトは
.Fx 5.0
ではじめて登場しました。