.\" @(#)$Revision: 1.3 $
.ds OK [\|
.ds CK \|]
.TH OSH 8 "16 November 1994"
.SH NAME
osh \- operator shell, a privileged restricted shell
.SH SYNOPSIS
.BI osh " \*(OK command \*(CK "
.SH DESCRIPTION
.LP
.BR 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.
.SS Invocation
Osh can be invoked with no arguments to start a subshell, or a single
command can be specified on the command line.
.SH USAGE

.SS Commands
.LP
A
.I command
is a sequence of nonblank
.I words
separated by
.IR blanks .
The first word specifies the name of the command to
be executed. The remaining words are passed as arguments 
to the invoked command.
.LP
A
.I pipeline
is a sequence of one or more
.I commands
separated by
.RB ` | '.
The standard output of each command but the last
is connected by a
.B pipe
(see
.BR 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.
.br
.ne 11
.LP
A
.I list
is a sequence of one or more
.IR "command" s
or pipelines, separated by
.RB ` ; ',
and optionally terminated by
.RB ` ; '
or
.RB ` & '.
A semicolon
.RB ( ; )
sequentially executes the preceding pipeline; an ampersand
.RB ( & )
asynchronously executes the preceding pipeline (the shell does
.I not
wait for that pipeline to finish).
An arbitrary number of 
.SM NEWLINE
characters may appear in a
.IR list ,
instead of semicolons, to delimit commands.
.LP
.SS Comments
A word beginning with
.B #
and all the following characters up to a 
.SM NEWLINE
are ignored.
.SS Environment Substitution
The character
.B $
may be used to reference environment variables.
Environment variables may NOT be assigned values inside
.BR osh .
.SS Input/Output
.LP
A command's input and output
may be redirected using a special notation interpreted by the shell.
The following may follow a
.I command
and are
.I not
passed on to the invoked command.
Note: environment substitution occurs before
.I word
is used.
.LP
.TP 14
.BI < word
Use file
.I word
as standard input (file descriptor 0).
.TP
.BI > word
Use file
.I word
as standard output (file descriptor 1).
If the file does not exist it is created;
otherwise, it is truncated to zero length.
.TP
.BI >\|> word
Use file
.I word
as standard output.
If the file exists output is appended to it (by first seeking to the
.SM EOF\s0);
otherwise, the file is created.
.LP
Redirection will be evaluated for the entire
.I command.
.LP
If a command is followed by
.B &
the default standard input
for the command
is the empty file
.BR /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.
.SS Filename Generation
.LP
Before a command is executed,
each command
.I word
is scanned for the characters
.RB ` \(** ',
.RB ` ? ',
.RB ` { ',
and
.RB ` \*(OK '.
If one of these characters appears
the word is regarded as a
.IR 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.
.RB ` . '
at the start of a filename
or immediately following a
.RB ` / ',
as well as the character
.RB ` / '
itself,
must be matched explicitly.
.LP
.PD 0
.RS
.TP
.B \(**
Matches any string, including the null string.
.TP
.B ?
Matches any single character.
.br
.ne 4
.TP
.BR \*(OK .\|.\|. \*(CK
Matches any one of the enclosed characters.
.PD
.RE
.SS Quoting
The following characters have a special meaning to the shell
and cause termination of a word unless quoted:
.RS
.LP
.B ";  &  |  <  >  "
.SM NEWLINE\S*\ \ 
.SM SPACE\S*\ \ 
.SM TAB\S*\ \ 
.RE
.LP
A character may be
.I quoted
(made to stand for itself)
by preceding
it with a
backslash (\fB\e\fP) or inserting it between a pair of quote marks
(\fB""\fP).
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.
.br
.ne 20
.SS Prompting
When used interactively,
the shell prompts the user for commands. If a command is
given on the command line, no prompting is performed.
.SS Signals
The
.SM INTERRUPT
and
.SM QUIT
signals for an invoked
command are ignored if the command is followed by
.BR & ;
otherwise signals have the values
inherited by the shell from its parent
(but see also
the
.B trap
command below).
.SM INTERRUPT
is handled asynchronously.
.br
.ne 18
.SS 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.
.LP
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.
.TP 16
.BI help
Help will usually give the user the list of commands allowed to be
executed by him.
.TP 16
.BI logout
Logout or ^D <eof> will always exit the user from Osh.
.TP 16
.BI cd " directory "
Change the current directory.
.TP 16
.BI more " \*(OK filename \*(CK "
Read a file using an internal, secure, version of more.
.TP 16
.BI alias " \*(OK name command \*(CK "
Specify an alias called
.I name
to perform
.I command.
If alias is called without arguments, print out a list of known
aliases.
.LP
The following commands are
.I only
available to noninteractive users.
.TP 16
.BI test " \fR\*(OK " -r|-w " \*(CK filename "
Test the file against the Operator Shell's access control lists for
readability or writeability. Exit's 1 on readable/writeable, 0 otherwise.
.SH EXIT STATUS
.LP
If the shell is being used noninteractively, the
exit status is meaningless
.I except
in the case of the 'test' command, whereby 
.B osh
will exit with 1 if the file access is allowed, 0 if it is
not allowed.
.SH SEE ALSO
.BR sh (1),
.BR csh (1)
.LP
.br
Neuman, Michael;
.I "The Operator Shell: A Means for Privilege Distribution Under \s-1Unix\s0".
(Usenix/SANS III) 
.SH WARNINGS
.LP
Words used for filenames in input/output redirection
are not interpreted for filename generation
(see
.BR "File Name Generation" ,
above).
For example,
.RB ` "cat file1 > a\(**" '
will create a file named
.RB ` a\(** '.
.LP
Because commands in pipelines are run as separate processes,
variables set in a pipeline have no effect on the parent shell.
.SH EXAMPLES
.LP
The following shows a sample interactive osh session:
.LP
.RS
.ft B
.nf
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) #>
.fi
.ft R
.RE
.LP
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).
.LP
.RS
.ft B
.nf
example% \ /usr/local/bin/osh cat /etc/shadow
root:passwordhere:::::::
daemon:NP:6445:::::::
bin:NP:6445:::::::
.fi
.ft R
.RE
.LP
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.
.LP
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.
.LP
.RS
.ft B
.nf
#!/bin/sh -f

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

if (test -z "$1")
	then
\ \ \ \ \ \ \ \ \ \ echo "Test what file? Give me a file to test."
\ \ \ \ \ \ \ \ \ \ exit
	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
.fi
.ft R
.RE
.SH BUGS
.LP
None. (suuure...)