     OSH(8)                                                               OSH(8)
                                  16 November 1994

     NAME
          osh - operator shell, a privileged restricted shell

     SYNOPSIS
          osh [ command ]

     DESCRIPTION
          osh, the Operator Shell, is a setuid root, security enhanced,
          restricted shell.  It allows the administrator to carefully limit the
          access of special commands and files to the users whose duties require
          their use, while at the same time automatically maintaining audit
          records.

        Invocation
          Osh can be invoked with no arguments to start a subshell, or a single
          command can be specified on the command line.

     USAGE
        Commands
          A command is a sequence of nonblank words separated by blanks.  The
          first word specifies the name of the command to be executed. The
          remaining words are passed as arguments to the invoked command.  A
          pipeline is a sequence of one or more commands separated by `|'.  The
          standard output of each command but the last is connected by a pipe
          (see pipe(2V)) to the standard input of the next command.  Each
          command is run as a separate process; the shell normally waits for the
          last command to terminate before prompting for or accepting the next
          input line.
          A list is a sequence of one or more commands or pipelines, separated
          by `;', and optionally terminated by `;' or `&'.  A semicolon (;)
          sequentially executes the preceding pipeline; an ampersand (&)
          asynchronously executes the preceding pipeline (the shell does not
          wait for that pipeline to finish).  An arbitrary number of NEWLINE
          characters may appear in a list, instead of semicolons, to delimit
          commands.

        Comments
          A word beginning with # and all the following characters up to a
          NEWLINE are ignored.

        Environment Substitution
          The character $ may be used to reference environment variables.
          Environment variables may NOT be assigned values inside osh.

        Input/Output
          A command's input and output may be redirected using a special
          notation interpreted by the shell.  The following may follow a command
          and are not passed on to the invoked command.  Note: environment
          substitution occurs before word is used.

                                        - 1 -         Formatted:  March 15, 2000

     OSH(8)                                                               OSH(8)
                                  16 November 1994

          <word         Use file word as standard input (file descriptor 0).

          >word         Use file word as standard output (file descriptor 1).
                        If the file does not exist it is created; otherwise, it
                        is truncated to zero length.

          >>word        Use file word as standard output.  If the file exists
                        output is appended to it (by first seeking to the EOF);
                        otherwise, the file is created.  Redirection will be
                        evaluated for the entire command. If a command is
                        followed by & the default standard input for the command
                        is the empty file /dev/null.  Otherwise, the environment
                        for the execution of a command contains the file
                        descriptors of the invoking shell as modified by
                        input/output specifications.

        Filename Generation
          Before a command is executed, each command word is scanned for the
          characters `*', `?', `{', and `['.  If one of these characters appears
          the word is regarded as a pattern.  The word is replaced with
          alphabetically sorted filenames that match the pattern.  If no
          filename is found that matches the pattern, the error `No Match' will
          be returned, and the command will not be executed.  `.' at the start
          of a filename or immediately following a `/', as well as the character
          `/' itself, must be matched explicitly.
               *    Matches any string, including the null string.
               ?    Matches any single character.
               [...]
                    Matches any one of the enclosed characters.

        Quoting
          The following characters have a special meaning to the shell and cause
          termination of a word unless quoted:
               ;  &  |  <  > NEWLINES*   SPACES*   TABS*
          A character may be quoted (made to stand for itself) by preceding it
          with a backslash (\) or inserting it between a pair of quote marks
          ("").  During processing, the shell may quote certain characters to
          prevent them from taking on a special meaning.  Backslashes used to
          quote a single character are removed from the word before the command
          is executed.

                                        - 2 -         Formatted:  March 15, 2000

     OSH(8)                                                               OSH(8)
                                  16 November 1994

        Prompting
          When used interactively, the shell prompts the user for commands. If a
          command is given on the command line, no prompting is performed.

        Signals
          The INTERRUPT and QUIT signals for an invoked command are ignored if
          the command is followed by &; otherwise signals have the values
          inherited by the shell from its parent (but see also the trap command
          below).  INTERRUPT is handled asynchronously.

        Execution
          Each time a command is entered, the above substitutions are carried
          out. If the user invoking the shell is allowed by the administrator to
          execute the command, and the parameters do not violate the file access
          control lists specified by the administrator, the command is executed.
          The following commands are usually available to the user. Of course,
          the system administrator can turn any of them off, but there's little
          reason to.

          help            Help will usually give the user the list of commands
                          allowed to be executed by him.

          logout          Logout or ^D <eof> will always exit the user from Osh.

          cd directory    Change the current directory.

          more [ filename ]
                          Read a file using an internal, secure, version of
                          more.

          alias [ name command ]
                          Specify an alias called name to perform command. If
                          alias is called without arguments, print out a list of
                          known aliases.  The following commands are only
                          available to noninteractive users.

          test [ -r|-w ] filename
                          Test the file against the Operator Shell's access
                          control lists for readability or writeability. Exit's
                          1 on readable/writeable, 0 otherwise.

     EXIT STATUS
          If the shell is being used noninteractively, the exit status is
          meaningless except in the case of the 'test' command, whereby osh will
          exit with 1 if the file access is allowed, 0 if it is not allowed.

     SEE ALSO
          sh(1), csh(1)
          Neuman, Michael; The Operator Shell: A Means for Privilege
          Distribution Under Unix . (Usenix/SANS III)

                                        - 3 -         Formatted:  March 15, 2000

     OSH(8)                                                               OSH(8)
                                  16 November 1994

     WARNINGS
          Words used for filenames in input/output redirection are not
          interpreted for filename generation (see File Name Generation, above).
          For example, `cat file1 > a*' will create a file named `a*'.  Because
          commands in pipelines are run as separate processes, variables set in
          a pipeline have no effect on the parent shell.

     EXAMPLES
          The following shows a sample interactive osh session:
               example%  /usr/local/bin/osh
               Mike Neuman (mcn)
               Operator Shell version 1.5alpha1
               example.mcn (/sec/opshell/osh/osh) #> help
               Operator Shell (osh) Version 1.5alpha1
                    by Michael Neuman <mcn@lanl.gov>

               Defines:
               NO_COMPILE_TABLE
               LOGGING to FILE
               CHECK_ACESS
               OPER_OVERRIDE

               Commands accessible:
               help     cd     more    alias
               example.mcn (/sec/opshell/osh/osh) #>
          The following is an example of how to run an osh command from the
          command line (assuming the user has permission to read the file
          /etc/shadow in the osh access control list).
               example%  /usr/local/bin/osh cat /etc/shadow
               root:passwordhere:::::::
               daemon:NP:6445:::::::
               bin:NP:6445:::::::
          The following is an example of a shell script calling Osh to test the
          accessibility of a file. This is a simple way to write a handler. You
          could, for example, write the following shell script, make it
          executable only by root, and add it to the Osh command table. The
          script, when executed, will correctly call osh to test the
          readability/writeability of certain arguments.  For example, if you
          wanted to write a simple `ln' handler, you would use a script similar
          to the one below to test the writeability of the last argument (the
          destination). By default, Osh automatically checks the readability of
          every argument, so it's not necessary to test them separately.
               #!/bin/sh -f

               OSHPATH="/usr/local/bin/osh"

               if (test -z "$1")
                    then
                         echo "Test what file? Give me a file to test."
                         exit

                                        - 4 -         Formatted:  March 15, 2000

     OSH(8)                                                               OSH(8)
                                  16 November 1994

                    fi
               if ($OSHPATH test -w $1)
                    then
                         echo "$1 writeable"
               #         Do something with this fact.
                    else
                         if ($OSHPATH test -r $1)
                              then
                                   echo "$1 readable"
               #                    Do something with this fact
                              else
                                   echo "No permission."
                         fi
               fi
               exit

     BUGS
          None. (suuure...)

                                        - 5 -         Formatted:  March 15, 2000