head	1.13;
access;
symbols
	OSSP_RC_0_7_3:1.13
	OSSP_RC_0_7_2:1.13
	OSSP_RC_0_7_1:1.13
	OSSP_RC_ALPHA_06:1.10
	OSSP_RC_EXBROKEN:1.10
	OSSP_RC_SPEC:1.7;
locks; strict;
comment	@# @;


1.13
date	2003.07.07.13.30.51;	author ms;	state Exp;
branches;
next	1.12;

1.12
date	2003.07.07.12.55.42;	author ms;	state Exp;
branches;
next	1.11;

1.11
date	2003.06.23.14.53.10;	author ms;	state Exp;
branches;
next	1.10;

1.10
date	2002.03.26.17.11.06;	author ms;	state Exp;
branches;
next	1.9;

1.9
date	2002.02.12.17.59.50;	author ms;	state Exp;
branches;
next	1.8;

1.8
date	2002.02.04.22.35.20;	author ms;	state Exp;
branches;
next	1.7;

1.7
date	2002.01.31.20.00.54;	author ms;	state Exp;
branches;
next	1.6;

1.6
date	2002.01.30.22.55.26;	author ms;	state Exp;
branches;
next	1.5;

1.5
date	2002.01.30.08.00.04;	author ms;	state Exp;
branches;
next	1.4;

1.4
date	2002.01.30.07.57.56;	author ms;	state Exp;
branches;
next	1.3;

1.3
date	2002.01.29.08.53.03;	author ms;	state Exp;
branches;
next	1.2;

1.2
date	2002.01.28.16.23.20;	author ms;	state Exp;
branches;
next	1.1;

1.1
date	2002.01.23.16.39.53;	author ms;	state Exp;
branches;
next	;


desc
@@


1.13
log
@More header corrections and improvements.
@
text
@##
##  OSSP rc -- Run-Command Processor samples (manual page)
##  Copyright (c) 2002-2003 Cable & Wireless Deutschland GmbH
##  Copyright (c) 2002-2003 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@@engelschall.com>
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  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.
##


=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, hardcoded 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.

 #   how to locate RC files
 Locate            /cw/etc/rc.d/rc.%{RCFILE:s/^all$/*/}
 Locate            /cw/local/etc/rc.d/rc.%{RCFILE:s/^all$/*/}

 #   requirements on RC files
 RequireUmask      022
 RequireOwner      cw
 RequireGroup      cw

 #   how to parse RC files
 ParseEnvAss       (?<=^\s*)([a-zA-Z_][a-zA-Z_0-9]*)=(?:"([^"]*)"|'([^']*)'|(\S+))
 ParseSectionDef   (?<=^|\n)%([a-zA-Z][a-zA-Z0-9]*)(\s+-[a-zA-Z]\s*\S+)*\s*\n(.+?)(?=\n%%\S+|$)
 ParseSectionRef   (?<=^\s*|;\s*)@@([a-zA-Z][a-zA-Z0-9]*)(\s+[^\n]+)?
 ParseSectionParam (?<=^|\s)-([a-zA-Z])\s*(\S+)
 NameConfig        config
 NameCommon        common
 NameDefault       default
 NameError         error

 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 transactions 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)

=over 4

=item F<$HOME/.bashrc>

 cd () {
     eval `$HOME/bin/rc --eval --conf=$HOME/.duecf $PWD leave`
     builtin cd ${1+"$@@"} 
     eval `$HOME/bin/rc --eval --conf=$HOME/.duecf $PWD enter`
 }

=item F<$HOME/.duecf>

 #   how to locate RC files
 Locate        %{RCFILE}/.duerc
 Locate        ${HOME}/.duerc:m/^<dir path="%{RCFILE}">(.*)<\/dir>/i
 Locate        ${HOME}/.duerc.%{RCFILE:s/^\///:s/[\/]/-/g}

 #   restrictions on RC files
 RequireUmask  022
 RequireOwner  ${USER}
 RequireGroup  ${USER:F<user2group>}

 #   how to parse RC files
 Functions     $HOME/.duefunc

=item F<$HOME/.duefunc>

 #   append (or optionally prepend) one or more directories (optionally
 #   have to be existing) to a colon-separated path variable. In case a
 #   directory already exists, it is first removed.
 #
 #   Usage:   duePathAdd [-p] [-e] <variable> <dir> [<dir> ...]
 #   Example: duePathAdd -e PATH /bin /sbin /usr/bin /usr/sbin /usr/ccs/bin
 #
 duePathAdd () {
    _prepend=0
    _exists=0
    while [ $# -gt 0 ]; do
        case $1 in
            -p ) _prepend=1; shift ;;
            -e ) _exists=1;  shift ;;
            *  ) break ;;
        esac
    done
    _var="$1"
    shift
    _edit_del=""
    _edit_add=""
    for _dir in "$@@"; do
        if [ ".${_exists}" = .1 ] && [ ! -d "${_dir}" ]; then
            continue
        fi
        _edit_del="${_edit_del} -e 's;^${_dir}\$;;' -e 's;^${_dir}:;;'"
        _edit_del="${_edit_del} -e 's;:${_dir}:;:;' -e 's;:${_dir}\$;;'"
        if [ ".${_prepend}" = .0 ]; then
            _edit_add="${_edit_add} -e 's;\$;:${_dir};'"
        else
            _edit_add="-e 's;^;${_dir}:;' ${_edit_add}"
        fi
    done
    if [ ".${_edit_del}${_edit_add}" != . ]; then
        eval "${_var}=\`echo \"\$${_var}\" | sed ${_edit_del} ${_edit_add}\`"
    fi
    unset _prepend _exists _var _edit_del _edit_add _dir
 }

 #
 #   remove one or more directories from a colon-separated path variable
 #
 #   Usage:   duePathDel <variable> <dir> [<dir> ...]
 #   Example: duePathDel PATH /bin /sbin /usr/bin /usr/sbin /usr/ccs/bin
 #
 duePathDel () {
    _var="$1"
    shift
    _edit=""
    for _dir in "$@@"; do
        _edit="${_edit} -e 's;^${_dir}\$;;' -e 's;^${_dir}:;;'"
        _edit="${_edit} -e 's;:${_dir}:;:;' -e 's;:${_dir}\$;;'"
    done
    eval "${_var}=\`echo \"\$${_var}\" | sed ${_edit}\`"
    unset _var _edit _dir
 }


=item F</cw/.duerc>

 <event name=enter>
     duePathAdd PATH            $CWD/bin $CWD/sbin
     duePathAdd MANPATH         $CWD/man
     duePathAdd INFOPATH        $CWD/info
     duePathAdd LD_LIBRARY_PATH $CWD/lib
 </event>
 <event name=leave>
     duePathDel PATH            $CWD/bin $CWD/sbin
     duePathDel MANPATH         $CWD/man
     duePathDel INFOPATH        $CWD/info
     duePathDel LD_LIBRARY_PATH $CWD/lib
 </event>

=item F<$HOME/.dueglobal>
  
 <dir path=/cw>
     <event name=enter>
         duePathAdd PATH            /cw/bin /cw/sbin
         duePathAdd MANPATH         /cw/man
         duePathAdd INFOPATH        /cw/info
         duePathAdd LD_LIBRARY_PATH /cw/lib
     </event>
     <event name=leave>
         duePathDel PATH            /cw/bin /cw/sbin
         duePathDel MANPATH         /cw/man
         duePathDel INFOPATH        /cw/info
         duePathDel LD_LIBRARY_PATH /cw/lib
     </event>
 </dir>
 <dir path=/usr/opkg>
     ...
 </dir>

=cut

@


1.12
log
@Correct and update copyrights and source headers.
@
text
@d2 1
a2 1
##  OSSP rc -- Run-command processor samples (manual page)
@


1.11
log
@Use term run-command consistently throughout docs.
@
text
@d3 3
a5 3
##  Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
##  Copyright (c) 2000-2002 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2000-2002 Ralf S. Engelschall <rse@@engelschall.com>
@


1.10
log
@Vacation flush, mostly build configuration details. Its not building very
clean right now.
@
text
@d37 1
a37 1
=head1 USE CASE: OpenPKG Runcommand Facility
d40 1
a40 1
(http://www.openpkg.org/) runcommand facility. 
d114 1
a114 1
edited later to influence the behaviours of the package's runcommand
d122 1
a122 1
This is the example runcommand script of an B<OpenPKG> package C<foo>.
@


1.9
log
@Cleanup.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d2 1
a2 1
##  rc-sample.pod -- OSSP Run-command processor samples (manual page)
@


1.8
log
@Fixed copyright.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d125 1
a125 1
 #!/cw/etc/rc
@


1.7
log
@General edits, added new %default and %error sections.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d1 25
@


1.6
log
@Add ASN.1 example, revise and correct manpages, update todo list.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d12 1
a12 1
=head1 USE CASE: OpenPKG Run-Command Facility
d15 1
a15 1
(http://www.openpkg.org/) run-command facility. 
d27 1
a27 1
This is the B<OSSP rc> configuration file, hard-coded into
d42 1
a42 1
 ParseEnvDef       (?<=^\s*)([a-zA-Z_][a-zA-Z_0-9]*)=(?:"([^"]*)"|'([^']*)'|(\S+))
d44 1
a45 2
 ParseSectionRef   (?<=^\s*|;\s*)%([a-zA-Z][a-zA-Z0-9]*)(\s+[^\n]+)?
 ParseParamRef     \$([0-9])
d48 2
d57 1
a57 1
This is the B<OpenPKG> Bourne-Shell script providing a set of reusable
d89 1
a89 1
edited later to influence the behaviours of the package's run-command
d97 1
a97 1
This is the example run-command script of an B<OpenPKG> package C<foo>.
@


1.5
log
@since --eval might change $PATH, ensure same rc is used afterwards
@
text
@d127 1
a127 1
With this setup, the following use cases are possible:
@


1.4
log
@consequently rename config to env
@
text
@d174 1
a174 1
     eval `rc --eval --conf=$HOME/.duecf $PWD leave`
d176 1
a176 1
     eval `rc --eval --conf=$HOME/.duecf $PWD enter`
@


1.3
log
@overhauling the location determination of rc files
@
text
@d42 1
a42 1
 ParseConfigDef    (?<=^\s*)([a-zA-Z_][a-zA-Z_0-9]*)=(?:"([^"]*)"|'([^']*)'|(\S+))
@


1.2
log
@still unfinished DUE example
@
text
@d15 3
a17 1
(http://www.openpkg.org/) run-command facility. First, the involved files:
d32 21
a52 12
 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
d173 5
a177 5
  cd () {
      eval `rc --eval --conf=$HOME/.duecf - leave`
      builtin cd ${1+"$@@"} 
      eval `rc --eval --conf=$HOME/.duecf - enter`
  }
d181 12
a192 7
  Dirs          .:..// # current and all parent dirs
  Name          .duerc
  NameGlobal    $HOME/.dueglobal:/etc/dueglobal
  RequireUmask  022      
  RequireOwner  %{USER}
  RequireGroup  %{GROUP}
  Functions     $HOME/.duefunc
d256 12
a267 12
  <event name=enter>
      duePathAdd PATH            $CWD/bin $CWD/sbin
      duePathAdd MANPATH         $CWD/man
      duePathAdd INFOPATH        $CWD/info
      duePathAdd LD_LIBRARY_PATH $CWD/lib
  </event>
  <event name=leave>
      duePathDel PATH            $CWD/bin $CWD/sbin
      duePathDel MANPATH         $CWD/man
      duePathDel INFOPATH        $CWD/info
      duePathDel LD_LIBRARY_PATH $CWD/lib
  </event>
d271 17
a287 17
  <directory path=/cw>
      <event name=enter>
          duePathAdd PATH            /cw/bin /cw/sbin
          duePathAdd MANPATH         /cw/man
          duePathAdd INFOPATH        /cw/info
          duePathAdd LD_LIBRARY_PATH /cw/lib
      </event>
      <event name=leave>
          duePathDel PATH            /cw/bin /cw/sbin
          duePathDel MANPATH         /cw/man
          duePathDel INFOPATH        /cw/info
          duePathDel LD_LIBRARY_PATH /cw/lib
      </event>
  </directory>
  <directory path=/usr/opkg>
      ...
  </directory>
@


1.1
log
@add first cut of sample manual page
@
text
@d158 1
a158 1
 ....
d160 1
a160 6
#   rc configuration for Dynamic User Environment (DUE)
Dirs          .:..//
Name          .duerc
RequireUmask  022      
RequireOwner  $USER           
RequireGroup  %{GROUP}
d162 110
a271 1
 ....
d274 1
@