wsh(1) wsh(1)
NAME
wsh - a restricted shell with unix-type security
SYNOPSIS
wsh [-il] [-c string]
DESCRIPTION
wsh is part of the WizPort package. The wsh offers a unix shell
with a different root and file securities than the account it runs
on. It has its own set of bin/ commands and its own set of
accounts that can login to it. The read and write access are
in a tree-path form, with excluded nodes.
Command Options
Command options are interpreted as follows:
-i Interactive mode. Will cause the wsh to source
the /.login.global and $HOME/.login, as well as
respond interactively to user requests.
-l Login. The wsh will start up with login and
password prompts. This is unnecessary if the user
is already logged into the wsh, or if the
administrator needs to login without a password
(set the WSHLOGIN environment variable first)
-c Read commands from the (single) following argument
which must be present. Usually for shell escapes.
If there is an argument left after processing the command options,
the argument will be used as the name of a file from which commands
will be executed.
COMMANDS
Each line of input is a command to the shell. The first word in
the line is taken to be the command to execute. If this word matches
one of the built-in commands, then the built-in command will be used.
Otherwise, if the command is the name of a file in the bin/ directory,
then that command will be executed. All following words are considered
to be either flags, arguments or filenames. If the word starts
with a dash (-) and is a legal flag, then it will be passed as a
normal argument to the executable. If the word is a legal non-filename
(determined by the 'etc/exceptions' file), then the word is passed
unaltered to the executable. Otherwise, the word is considered to
be a filename and is path-completed and access checked (see Security)
and then passed to the executable.
Parsing
The wsh parser initially tries to do substitutions. The following
substitions are possible and will be explained below:
history, alias, and environment
After substitutions, the line is broken up into 'tokens,' or words.
The wsh checks to see if the first word is a built-in command (see
below). If so, that command will be interpreted. If not, the
parser will take all the following tokens and convert them to full-path
form as explained above. The following rules apply to parsing:
Whitespace
Whitespace is ignored unless in a string.
Comments
Anything following a '#' (pound sign) will be ignored as a comment.
Quoting
If the ' (half-quote), " (double-quote) or '(' (left parenthesis) are
encountered in the input line following whitespace, the following text
will be considered a string and kept together as one argument, with
whitespace. The string will end when the parser encounters the
matching end, a half-quote, double-quote or right parenthesis.
History Substitutions
All commands that the user has previously entered are saved in the
history buffer (except for failed history and environment
substitutions). The buffer has an initial default size, but can
be changed with the 'history' command (see 'history' in Built-In
Commands). Using history substitution, the user is able to
repeat these commands without retyping them. The possible forms are:
!<num> Re-do the <num> line in history
!<str> Re-do the first line in history (moving up the
history list) that starts with the substring <str>.
!! Re-do the last command
Any time a '!' is followed by non-whitespace, a history expansion
will be attempted, and the command will fail if the expansion fails.
In order to use an '!' (exclamation point) in a command without doing
a history expansion, the user can use the '\' (backslash). If a
'\!' is found following whitespace, the parser will replace it with
just a '!' and then will not attempt the history expansion.
Also, the form '\\' following whitespace will be converted to '\'
Alias Substitution
The wsh keeps a list of aliases that can be used to refer to other
commands. The alias list can be modified and displayed (see the
'alias' and 'unalias' commands in Built-In Commands)
Before checking for built-in commands, the parser will check to
see if the first word of the line matches the name of an alias.
If so, then the alias name is replaced by the string that the alias
is set to. Then, the new line is run through the parser again,
to check for history expansion, aliases, etc... If the parser
gets the same alias as was expanded last time, then it will not
expand the alias again. This allows aliases of the form:
alias ls ls -sF
In this case, 'ls' will only be expanded once. To avoid more complex
alias loops, the parser will stop after a certain maximum number of
aliases have been expanded. On most systems the maximum is 40, and
this should be enough for even the most complex aliases. If you
need a higher maximum, contact your administrator and they might be
able to change it for you.
Environment Substitution
Environment variables can be accessed and changed by the 'setenv'
command. To use environment variables inside of commands, prepend
them with the '$' (dollar sign). The following characters will be
the variable name to use, until one of the following characters:
/ \ " [ ] : <whitespace or newline>
Special Variables:
The following variables have special meaning to the wsh:
debug You can set this variable to either 'on' or 'off'
If it is on, you will get lots of ugly debug messages
that won't mean anything to you.
EDITOR The default editor to use.
This variable cannot be altered for security reasons.
HOME You can set this to change your home directory.
You must supply it with an absolute path (it must
start with a '/')
LOGNAME This is your login name.
This variable cannot be altered for security reasons.
MAIL This isn't used by the 'wsh' but is changed at login
from the administrators mail path.
This variable cannot be altered for security reasons.
NETHOST This is set at login to your host name (or number if
the name can't be resolved)
This variable cannot be altered for security reasons.
PATH This is set at login to the wsh 'bin/' path
This variable cannot be altered for security reasons.
prompt This is the prompt that you see for each 'wsh' command.
If a %/ is found in the prompt, it will be expanded to
your current working directory. For example, the prompt
I use is:
set prompt "[$USER] %/ wsh> "
which becomes:
[jubal] /players/jubal wsh>
SHELL Default shell to use. Set to the 'wsh'
This variable cannot be altered for security reasons.
TERM This isn't actually a 'wsh' variable, but it is very
likely that you will need to change it if you have
any terminal problems.
Built-In Commands
The following are commands that the shell will interpret and evaluate
instead of running an executable.
acc
Prints out the access tree in a crude format (see Security)
alias
alias <name>
alias <name> string>
The first form will print out all available aliases
The second form will print out the string set to <name>
The third form will set <name> to <string>
See aliases
cd <path>
Change the current working directory to the path specified.
The path can be absolute or local, and can use normal
substition (environment variables and history)
chat <string>
Tell the <string> to everyone on the chat line.
Make sure to be careful with the string, because normal
evaluation of the line will take place (for example,
using "!!" will result in a history expansion)
exit
Exit this shell. If the shell is a login shell, then
$HOME/.logout will be executed.
history
history <num>
The first form will print out all the commands saved in
the history buffer. (see History)
The second form will resize the history buffer to <num>
logout
Same as exit
pwd
Print out the current working directory
It is important for programmers to realize that this is
not the same as the directory that is set by the chdir()
system call.
setenv
setenv <name>
setenv <name> <string>
The first form prints out all environment variables
The second form shows the value of the variable <name>
The third form sets the variable <name> to <string>
* As of version 1.45c, 'set' is no longer the same as setenv
See Environment Substitution
source <file>
Read commands from <file> until an end-of-file or an exit
These commands will be added to the history buffer
. <file>
The period is a shorthand for 'source'
tell <who> <string>
Tell <string> to the user <who> if logged in
unalias <name>
Remove <name> from alias list
version
Print out some version information
whoami
Show the name of the user logged in
who
Show all users logged in with some pertinent information
Non-Built-In Command Execution
When a command is not a built-in command, then the bin/ directory
is checked for an executable with the same name as the command.
If one is found, that executable will be spawned off as a new process,
and will return to the shell upon completion. Otherwise, a "Command
not found" error will be given.
Security
EXTERNAL INFLUENCES
Environment Variables
A number of environment variables are used by the wsh.
See Environment Substitution
Term settings
When the wsh is used with the tcpserv server, it will have whatever
term settings that the administrator has upon booting the server
Unix read-write permissions
The wsh does not get around normal unix file security. It is
assumed (for correct operation) that the files in the wsh root
are all readable and writable by the administrator.
WARNINGS
To administrators:
Please take note! The 'wsh' is a very complicated system, and can be
made unsecure by putting the wrong executables in the bin/ directory.
** PLEASE READ THE SECURITY FILE BEFORE INSTALLING **
KNOWN BUGS
Because links are resolved to their 'actual' path, if you try to
remove a link from inside the wsh, it will attempt to remove the
actual file itself, and if you have permission, then it will succeed.
Versions before 1.45 would source the .logout file of whatever
directory the user was in. This is not a security problem, however.
When you type the 'who' command, your idle time is not updated until
after the command is executed. I actually find this amusing, since
it lets you know how long you were idle for, so I don't plan to fix it.
It is possible for someone to login without ending up on the 'who'
list. This is a semaphore problem, and there is no easy way to fix this.
!! seems to be off by one if done right after the .login
Some machines don't fgets() properly. Consequently, you can't backspace
over a space. I haven't the slightest idea why, but hopefully readline()
will fix this.
AUTHOR
wsh was written by David Ljung (ljung@cae.wisc.edu)
FILES
The following files/directories are defined in the source
ROOT_DIR root of the wsh filesystem
WSH_DIR main directory for the wsh files
BIN_DIR directory where wsh executables are kept
PASSWD_FILE file of users and user info (including passwords)
It is possible to use mud files instead - see the docs
WRITE_ACC_FILE file of write access types
READ_ACC_FILE file of read access types
EXCEPTIONS_FILE file of defined exceptions
UTMP_FILE used by the 'who' command
WTMP_FILE log of all logins -- erase this file on occasion
WSH_FNAME actual path of the wsh executable
HELP_DIR where documents and helpfiles can be found
SEE ALSO
tcpserv(1), csh(1)