install-unix.txt - Detailed installation guide for UNIX
This file is part of WebRSH 1.1b (beta)
Copyright (C) 1997,1998  Yoram Last (ylast@mindless.com)

A. PRE-INSTALLATION:
=====================
1. If you are installing WebRSH as a user on a UNIX system, you should check to
  insure that the following 4 conditions hold for you:
  a) That you can publish web content by placing it in an appropriate directory
    (typically this would be the 'public_html' subdirectory of your home 
     directory).
  b) That you can run CGI scripts in general and Perl scripts in particular.
    This requires appropriate permissions from the server as well as knowledge
    of how to enable files as CGI scripts. It is often enough for the file to
    be executable and to have a .cgi extension, but in some cases you may need
    place it in a special directory. Also, you should know the path to Perl 5
    on your system. This is often '/usr/bin/perl', but it might also be
    '/bin/perl', '/usr/local/bin/perl', or something else. Moreover, on some
    systems 'perl' might still be version 4, so you might need to replace 'perl'
    with 'perl5' in the above. (If you don't know the Perl setup on your system,
    try the following: Type 'perl -v' to get the version of 'perl'. If it isn't
    5.00x, try 'perl5 -v'. Once you have located the appropriate perl try 'which
    perl' or 'which perl5' to get the path.)
  c) That your CGI scripts get executed in your own user context (namely, they
    should get executed with your uid).
  d) That you have the ability to restrict access to your web content
    (particularly, to CGI scripts) with a user authentication mechanism. This
    is often done by setting up an appropriate '.htaccess' file.

  If you run into problems with any of the above, and if the web server on
  your system is Apache, you can try to locate the apache configuration files
  and look up the Apache documentation at http://www.apache.org. In principle,
  you should be able to tell from this how things are configured on your system.
  Otherwise, contact your system administrators. It is also possible for a UNIX
  user to run WebRSH using a private web server (which would need to use a port
  number above 1024), but running WebRSH in this way is not recommended.

2. If you are installing WebRSH as a UNIX administrator (which you probably are
  if you are installing it on a personal system), and if you would like to enable
  its usage by users of the system, you should insure that the above required
  setup is enabled for the appropriate users. The most natural way of achieving
  that is to run an Apache server with the 'suexec' supplement. You should look
  at the Apache documentation to see how this is done. If you would like to use
  WebRSH as an aid in remote system/server administration, you would probably
  need to set it up such that it gets executed as a root process (uid 0). The
  best way of doing that is to run a separate web server that runs as root. Note
  that running WebRSH in this way may be a significant security hazard. Consider
  using an SSL enabled server for such a purpose.

3. Once you verified the web server and Perl setups on your system, you should,
  at the minimum, be able to run the following simple "Hello World" script:

  #!/usr/bin/perl
  print "Content-type: text/plain\n\n";
  print "Hello World\!\n\n";

  The '/usr/bin/perl' might need to be replaced by the appropriate path to the Perl
  executable on your system. You should not attempt to install WebRSH unless you are
  first able to run a simple script of this type.


B. INSTALLATION:
=================
We first describe in detail how to perform a private user installation. After
that we give some remarks indicating how to do a system-wide install. For
the purpose of this description, we assume that your user name is 'joe',
your home directory is '/home/joe', and the root directory of your web space
is '/home/joe/public_html'. You would probably need to modify some of the
paths described below to match your true setup.

1. Extract the distribution archive to its final destination. Your home
  directory should be a good place to do it, such that WebRSH's top level
  directory will be '/home/joe/WebRSH'. When we refer below to WebRSH
  directories, we mean subdiretories of this top level one.

2. Map WebRSH's 'sfdir' directory as part of your web space. If your server
  configuration supports symbolic links you can simply make a symbolic link
  to it in 'public_html' (from your home directory type 'cd public_html' and
  then 'ln -s ../WebRSH/sfdir sfdir'). Otherwise, you can also copy it as a
  subdirectory of your 'public_html' directory.

3. The main WebRSH script (which is the one and only script you actually
  need to run as a CGI script in order for WebRSH to work) is the file
  'webrsh.cgi' in WebRSH's 'scripts' directory. You should make a copy of
  this file executable as a CGI script. Copy it to somewhere in your web
  space where it can be used as such, and make sure it has the appropriate
  permissions for your server setup (in most cases it should be world
  readable and executable, but writable only by yourself, and it should
  further reside in a directory that has those precise permissions).
  Unless you must place CGI scripts in a special directory, we recommend
  that you create a 'webrsh' subdirectory of your 'public_html' directory
  and place this copy of 'webrsh.cgi' there.

4. Restrict access to the 'webrsh.cgi' script, such that username + password
  authentication is required in order to access it through the web server.
  It is recommended that you also restrict access to the 'sfdir' directory,
  but this is not crucial.

5. Open your "active" copy of 'webrsh.cgi' with a text editor. You should
  now modify two variables to correspond to your setup:

  look for the line
  $ProgDir = '~/WebRSH';
  and change the value to match the full path to your top level WebRSH
  directory. Something like
  $ProgDir = '/home/joe/WebRSH';

  next, look for the line
  $SendFilesUrl = '/sfdir';
  and change the value to match the proper URI of your 'sfdir' directory.
  Something like
  $SendFilesUrl = '/~joe/sfdir';

  Next, you might also need to modify an access control variable. By
  default, the WebRSH script will only work if accessed from the host on
  which it is installed through the 127.0.0.1 (localhost) IP address. If
  you will be initially accessing it from another host, you should look
  for the line
  $LocSecurity = 1;
  and change it to
  $LocSecurity = 0;
  Make sure, however, that your server's access control protection is
  properly set, or else others may be now able to access your WebRSH.

  Finally, if the path to the Perl 5 executable on your system is different
  from '/usr/bin/perl', you should make the appropriate modification at the
  top of the script.

  Don't forget to save your modifications.

WebRSH should now be properly installed, and you should proceed to the
'POST-INSTALLATION' section of the 'readme.txt' file.


SYSTEM-WIDE INSTALLATION:

If you would like to make a multi-user system-wide installation of WebRSH,
you should first read the private user installation description above, and
then note the following: Most of WebRSH can reside in a central directory,
but there are some things each user that will be running WebRSH needs to
have for himself. These are:
1. A private 'Configuration Directory' containing the appropriate files.
2. A private copy of the main WebRSH script.
3. A 'Temporary Directory' that he can write to. It and can be either a global
  'tmp' directory or a private user directory.

To proceed with the installation, do the following:

1. Extract the distribution archive to its final destination.
  '/usr/local/lib' should be a good place, such that the top level
  WebRSH directory will be '/usr/local/lib/WebRSH'.
2. Map WebRSH's 'sfdir' directory to your web space (see above).
3. Edit the 'webrsh.cgi' script in WebRSH's 'scripts' directory (see above):
  You should change '$ProgDir' to point to the top level WebRSH directory,
  and '$SendFilesUrl' to point to the proper URI of 'sfdir'.

The system-wide portion of the installation is now basically complete. For
each user that will be running WebRSH you should do the following (if you need
to enable many users, you should probably automate it with a script):

1. Create a 'Configuration Directory' in the user's home directory. A good
  name for it is '.webrsh'. Put in this directory copies of the two files
  'mimetable.txt' and 'rshinidat.txt' that are in WebRSH's 'cfg' directory.
  The user should have read and write permissions to this directory and to
  the files in it (best if he owns them all).

2. Put a copy of the 'webrsh.cgi' script (the one you edited before)
  somewhere in your web space where it can be web-accessed by the user
  and executed with his uid. The most natural place is somewhere in
  his 'public_html' directory. This copy and the directory where it
  resides should be owned by the user and writable by him. You should
  restrict web-access to this script, such that only the user can access
  it (with his normal login name). You should also further edit it to
  properly set the following variables:
  set 'CfgDir' to point to the above 'Configuration Directory'.
  set '$HomeDir' to point to his home directory.
  set '$TempDir' to what he should use as a temporary directory. This
    can simply be the above 'Configuration Directory' if you like.
  You should probably also set $LocSecurity = 0 (to enable access from
  remote machines), $CheckForUser = 1 ,and @AllowUsers = ('username')
  where username should be replaced by the user's login name.

WebRSH installation for this user should now be complete.

