|
Check-in Number:
|
1618 | |
| Date: |
2002-Jan-23 17:39:53 (local)
2002-Jan-23 16:39:53 (UTC) |
| User: | ms |
| Branch: | |
| Comment: |
add first cut of sample manual page |
| Tickets: |
|
| Inspections: |
|
| Files: |
|
ossp-pkg/rc/rc-sample.pod -> 1.1
*** /dev/null Fri Apr 26 14:45:33 2024
--- - Fri Apr 26 14:45:53 2024
***************
*** 0 ****
--- 1,169 ----
+
+ =pod
+
+ =head1 NAME
+
+ rc-sample -- B<OSSP rc> Example Use Cases
+
+ =head1 DESCRIPTION
+
+ This documents typical use cases for B<OSSP rc>.
+
+ =head1 USE CASE: OpenPKG Run-Command Facility
+
+ This describes how B<OSSP rc> is used as the B<OpenPKG>
+ (http://www.openpkg.org/) run-command facility. First, the involved files:
+
+ =over 4
+
+ =item F</cw/etc/rc>
+
+ This is just the location of the B<OSSP rc> program.
+
+ =item F</cw/etc/rc.cf>
+
+ This is the B<OSSP rc> configuration file, hard-coded into
+ F</cw/etc/rc> at configure/build time with the Autoconf option
+ C<--with-config=/cw/etc/rc.cf>. It is installed at B<OpenPKG>
+ bootstrap time and used read-only.
+
+ Dirs /cw/etc/rc.d:/cw/local/etc/rc.d
+ Name rc.%s/rc.*
+ ConfigDef (?<=^\s*)([a-zA-Z_][a-zA-Z_0-9]*)=("[^"]*"|'[^']*'|\S+)
+ SectionDef (?<=^|\n)%([a-zA-Z][a-zA-Z0-9]*)(\s+-[a-zA-Z]\s*\S+)\s*\n(.+?)(?=\n%%\S+|$)
+ ParamDef (?<=^|\s)-([a-zA-Z])\s*(\S+)
+ SectionRef (?<=^\s*|;\s*)%([a-zA-Z][a-zA-Z0-9]*)(\s+[^\n]+)?
+ ParamRef \$([0-9])
+ NameConfig config
+ NameCommon common
+ Execute root %s
+ Execute !root sudo %s
+ LineControl yes
+
+ =item F</cw/etc/rc.func> (C<%common> extensions)
+
+ This is the B<OpenPKG> Bourne-Shell script providing a set of reusable
+ functions. It is installed at B<OpenPKG> bootstrap time and used
+ read-only.
+
+ opVarIsYes () {
+ _var="${1}"
+ eval "_val=\"\$${_var}\""
+ case "${_val}" in
+ [Yy][Ee][Ss] | [Tt][Rr][Uu][Ee] | [Oo][Nn] | 1 )
+ unset _var _val
+ return 0
+ ;;
+ [Nn][Oo] | [Ff][Aa][Ll][Ss][Ee] | [Oo][Ff][Ff] | 0 )
+ unset _var _val
+ return 1
+ ;;
+ *)
+ opWarn "variable \$${_var} is not set properly."
+ unset _var _val
+ return 1
+ ;;
+ esac
+ }
+ opServiceEnabled () {
+ opVarIsYes ${1}_enable
+ }
+
+ =item F</cw/etc/rc.conf>
+
+ This is the B<OpenPKG> configuration script where the administrator
+ overrides the variables from the script's C<%config> sections. It it
+ generated (as an empty file) on B<OpenPKG> bootstrap time and manually
+ edited later to influence the behaviours of the package's run-command
+ scripts (here F</cw/etc/rc.d/rc.foo>).
+
+ foo_enable=yes
+ foo_flags="--sample"
+
+ =item F</cw/etc/rc.d/rc.foo>
+
+ This is the example run-command script of an B<OpenPKG> package C<foo>.
+ It is installed by package C<foo> and used read-only.
+
+ #!/cw/etc/rc
+ %config
+ foo_enable=yes
+ foo_flags=""
+ %common
+ foo_pidfile=/cw/var/foo/foo.pid
+ %start -u root -p 100
+ if opServiceEnabled foo; then
+ /cw/sbin/foo -p $foo_pidfile -S $foo_flags
+ fi
+ %stop -u root -p 100
+ if opServiceEnabled foo; then
+ /cw/sbin/foo -p $foo_pidfile -K
+ fi
+ %restart -u root -p 100
+ if opServiceEnabled foo; then
+ %stop
+ sleep 1
+ %start
+ fi
+ %env
+ if opServiceEnabled foo; then
+ FOO=/cw/sbin/foo
+ export FOO
+ fi
+
+ =back
+
+ With this setup, the following use cases are possible:
+
+ $ /cw/etc/rc --query "foo enabled: %{foo_enable}"
+ foo enabled: yes
+ $ _
+
+ $ /cw/etc/rc --config
+ Configuration Variable Effective Value Default Value
+ ------------------------ ------------------------- -- -------------------------
+ foo_enable "yes" == "yes"
+ foo_flags "--sample" != ""
+ $ _
+
+ $ /cw/etc/rc -v foo start
+ start: foo
+ $ _
+
+ $ /cw/etc/rc --print foo env
+ # /cw/etc/rc.d/rc.foo 3
+ foo_enable=yes
+ foo_flags=""
+ # /cw/etc/rc.conf 1
+ foo_enable=yes
+ foo_flags="--sample"
+ # internal 0
+ . /cw/etc/rc.func
+ # /cw/etc/rc.d/rc.foo 6
+ foo_pidfile=/cw/var/foo/foo.pid
+ # /cw/etc/rc.d/rc.foo 22
+ if opServiceEnabled foo; then
+ FOO="The Foo"
+ export FOO
+ fi
+ $ _
+
+ $ eval `/cw/etc/rc --eval foo env`
+ $ print $FOO
+ The Foo
+ $ _
+
+ =head1 USE CASE: Dynamic User Environment (DUE)
+
+ ....
+
+ # rc configuration for Dynamic User Environment (DUE)
+ Dirs .:..//
+ Name .duerc
+ RequireUmask 022
+ RequireOwner $USER
+ RequireGroup %{GROUP}
+
+ ....
+
+ =cut
|
|
