READ THE COPYRIGHT FILE BEFORE INSTALLING
Installation
------------
Installation is mostly automated, but don't just jump right in. Read
the docs first, because there are some files you have to edit, and things
need to be done in a certain order. If the automation doesn't work,
just look at the makefiles and try to figure out what was supposed to
happen ;)
Also, it is important to read this document entirely as well as the
document on security, because failing to do that can jeopardize your
account's security. These are the files before installation:
Files (in the main directory)
-----
docs/ These documents
help/ The help documents (see installation steps below)
binsrc/ bin construction files. Should be taken care of by Makefile
there are also some scripts here that you might want
in particular, the fget set of scripts
etc/ security files for wsh
passwd password file - much like the unix /etc/passwd
write_access write access permissions file for wsh
read_access read access
exceptions for setting up special executables with exceptions
Makefile the main makefile
src/ wizshell source directory
makefile for wsh, help and mkpasswd
access.* catch.* login.* wizshell.* etc.. wsh source
help.c help source
mkpasswd.c mkpasswd source
tcp-s/ tcpserv source directory.
Configure sets up tcpserv for 'make'
README read this if you have any problems or questions about tcpserv
COPYRIGHT Sam Lantinga's copyright for tcpserv
(source) source for tcpserv
There are four main steps to installing the WizPort.
1) Make the wsh binary
This is the biggest step. Enter the src/ directory and edit the
'Makefile.' YOU MUST DO THIS or wsh will *not* work. The file
should (hopefully) be self-explanatory. You may also want to edit
config.h, this will give you some options of how you want wsh to run,
such as whether you want to use the password file or the player.o
files for login. Then type 'make' and hopefully the binary will be
created without errors ;). If so, move the file up one directory to
the main wsh directory. If it doesn't work, you may need to port
the code a little bit, though the code should be extremely portable
to any *nix platform.
You can test the wsh without telnet by 'wsh -l' (for a wsh login), but
you will need to change the passwd file first (see "Running the wsh" below)
2) Edit the binsrc/mkbin file
In this file you will see a few lines at the top like this:
set files="$files ls mv cp rm mkdir rmdir echo"
Simply uncomment the groups of files you wish to have in your wsh
bin directory. The mkbin script will then be able to build your
bin directory (when activated from the main makefile). The sets of
files listed were determined to be safe to the best of my knowledge,
feel free to add whatever files you like to this list, but first check
the security document. The script will create these files by linking
them to your actual machines binaries, so if you don't have the command,
then you can't use it with the wsh (unless you make a copy of the exec)
There are also some other binaries/scripts that you may wish to install
in bin/. Take a look in binsrc/ and in src/util.
3) Type make
In the main directory there is a makefile which should set up the
WizPort properly. It does this by doing the following:
o Makes sure 'wsh' exists. If not, you must do step 1
o Builds tcpserv and puts it in the main directory
tcpserv should build without a hitch (thanks Sam!)
o Create the bin/ directory
This is done by running the mkbin script in binsrc/ and also
building help and mkpasswd in src/ and moving them to bin/
4) Install the help files
There is a built in help program (bin/help after installation) that
lets the users look in the mud help directory easily. There are a few
help files for users of the wsh, these are in docs/help/ and they should
be moved to muds help directory (as specified by HELP_DIR in src/config.h)
You may also wish to edit these files (especially docs/help/bin)
Help will probably change when I get a better help system working.
There is also a semi-optional step:
5) Creating the new binaries
Since wsh *cannot* be used with such programs as 'vi' or 'emacs'
without serious security problems. I was able to run a usable
system with only two changed binaries - for 'vi' and 'more'
(emacs users will have to wait :). I used 'elvis' (a vi clone)
and 'less' (less is more :), both of which I was able to get
the source for, which I then edited to make secure. Both of these
are available (either in binsrc/ or as a separate archive), and
should be compiled and put into the bin/ directory. Once again,
you can strip the executables of debugging info to save disk space.
After mkbin runs, there should already be links of more and vi to
less and elvis, so normal unix users shouldn't notice the difference.
Another *very* useful binary to make is the splitvt and splitmud
executables. Many people cannot usually use the WizPort because
they are on a modem and have only one window - which they use to
mud. By using splitmud or splitvt, they can split the screen (like
a talk session) and mud in the bottom while still editing files in
the top. An edited version of these programs is available also.
(the original versions would start up /bin/sh instead of the wsh ;)
The split programs were also written by Sam Lantinga, the author
of tcpserv (thanks *again* Sam) through inspiration by yours truly.
You should now have a structure like this:
----------
| |
wsh/ root/ <- Mud ROOT_DIR is *outside* of wsh/
|
|
---------------------------------------------
| | | | | | |
*boot *wsh src/ bin/ etc/ *tcpserv Makefile
Files:
wsh/boot The bootup script for the WizPort
wsh/wsh The WizShell executable
wsh/tcpserv tcpserv executable
wsh/etc/ etc files
wsh/bin/ This is where the executables that the WizShell can use are
kept (such as ls, rm, etc...) Most of these will be links
to the machines actual files. This will be explained below.
wsh/src/ WizShell and tcpserv source if you wish to keep it
wsh/Makefile Was used to 'make'
Before logging into the wsh, you will need to edit the etc/ files.
Running the wsh
---------------
etc/passwd
----------
For the login, you have two options. One, the password, home and access type
(as well as other information which is currently mostly unused :) can
come from the file etc/passwd as described below. Often the WizPort is
used as a utility to support a mud, and in this case, you can also use the
player.o files to get the password and level. If you do this, you need to
look at login.c and change some functions to work with your mud. Also,
it is important to realize that this is MUCH less secure - although certainly
much easier. All someone needs to do is change a .o file on the mud and then
they can login unknown to the WizPort. If you want to use a password file
instead, you need to change src/config.h, and then make etc/passwd:
The fields of the etc/passwd field are labeled at the top of the file.
login: login name (usually same as the mud)
password: password (encrypted according to src/config.h)
You can either get this from the player.o file
or use the mkpasswd command (which will become installed in bin/)
things like change password and other utilities will be available
at a later date
access name: any string that matches an entry in the etc/*_access files
real name: Not currently used
home dir: Make sure this is set properly, because it is often used for
security reasons in *_access (through $HOME). It is best not
to use an empty home or a home of "/" because this can cause
problems with some executables.
etc/*_access
------------
These contain the read and write access for each access type. For each access
name you have in the password file, you need to have an associated entry in
both write_access and read_access. The format is simple (whitespace ignored):
<access name>: [<file> | <directory> | +<access name> | -<file | directory> ]*
For example,
WIZ: /open $HOME /log/$USER /players/*/open
The files can be actual files or directories. Having access to a directory
means having access to *all* files inside the directory (including inside
directories in the directory, etc..)
You can also use environment variables (such as $HOME) as tokens of a path.
Look at wizshell.c or type 'set' during a wsh session to see what environment
variables are available to you. To have an environment variable be a piece
of a token (such as "/log/$USER.rep") you can just add a putenv in wizshell.c
You can also use the * as a full token, but you cannot (yet) use tokens with
asterisks in them, such as /log/*.rep
Another thing you can add to the access list for a type is another access list,
for example, if you have an Immortal class, that has access to /obj, /room
and /doc as well as everything a normal wiz has, you can just do the following:
IMM: /obj /room /doc +WIZ
To create an access type that has FULL access, simply do:
GOD: /*
Finally, you can disallow files and directories:
IMM: /* -/room/post_dir
Will allow everything except files in /room/post_dir
etc/exceptions
--------------
There are exceptions that the wizshell uses for special cases. These
are put in the exceptions file so they can be changed without recompilation.
Only a basic understanding of these are necessary, unless you plan on
installing some binaries other than the standard set.
The format for exceptions is:
<exception type>: [<command> | <command>/<arg number> ]*
In other words, you name the type and then the exceptions of that type,
by command. If the exception is only for a certain argument number of
the command, for example, only the first argument to copy, you separate
by a slash, i.e: "cp/1"
Here are the exception types and some example exceptions:
1) WD_DEFAULT: ls lsf lsr lsx
For an explanation of this you need to look at the tech chapter, but
it is for commands that use the working directory as the default when
they have no arguments. For example, 'ls bob' will list bob, but
'ls' will list the current directory - it is the same as 'ls .'
Unfortunately, the wizshell never actually changes directory for
security reasons, it is always in the root directory. The WD_DEFAULT
exception are the commands that need to be given '.' as a default
argument when they have none.
These you shouldn't need to change.
2) CAN_READ: cat cp/1 tar/3
These are the file args that should be checked through 'read_access' and not
'write_access'. Examples here are all arguments to 'cat', the first arg
of cp (Usage: cp <src> <dest> - so the src only needs to be read) and the
third arg of tar - though you shouldn't have tar installed in bin/ anyways :)
I will have a workaround for tar just like ftp soon.
Without this, the users will need to have write access for all files they
work on, regardless of whether the command only reads the file.
3) NON_FILE_ARGS: echo banner tar/1 man stty help wsh/2 fget/1
These are arguments that shouldn't go through either access file, and more
importantly, shouldn't be converted into the full path form.
(i.e., the wsh converts "~jubal/moo/../cow.c" into "players/jubal/cow.c")
For example, "echo joe" shouldn't echo <current working directory>+"joe",
it should just echo "joe". Also, fget, for example, the first arg is not
a file on the wsh, and should not be expanded to full path form - we let
the remote filesystem take care of it - it will be a different path anyways,
and the security of the remote filesystem is not our business. To understand
why commands need to be put into this exception, you will need to read the
tech chapter.
Starting it
-----------
To start the WizPort up (so the wsh can be accessed by telnet) you can
do the following:
tcpserv -t <port#> wsh -l
The -l argument means do a login session. This argument is there so that
'wsh' can be invoked from inside the wsh without having to login again.
(for shell escapes, splitvt, etc..) I have found it easier to do all
this with a bootup file, so the src/Makefile will create one for you.
If you are using a mud, you can put this in your equivalent 'restart_mud'
script (just once though), or just type 'boot'.
There are two ways to start up the wsh from the unix command line (without
telnet)
To start up wizshell as a login session and ask for login and password:
1) wsh -l
To start up the wizshell without a password or login:
2) setenv WSHLOGIN=<name>
wsh
This way you can test other accounts without editing passwords. The
setting of WSHLOGIN can only be done outside wsh (for obvious reasons).
You only need to do the setenv once, then you can call wsh as many times
as desired (also useful for debugging)
Once logged into the wizshell, type help. This should outline some useful
features (such as the .wshrc and .login files) as well as some other help files.