
WebRSH 1.0.1b (beta) A Remote-Computing CGI Script for Windows 95/NT.
Copyright (C) 1997-1998  Yoram Last

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The author of this program can be contacted by e-mail at ylast@mindless.com.

WARNING: This program has an above-average potential for causing damage!
In particular, it may allow unauthorized remote access to your computer and
to network resources available to your computer. It may also cause your
computer to "crash" while you are away from it and thus unable to restart it.
It is strongly recommended that you read all accompanying documentation (in
particular, the security related parts) prior to using this program. It is
further recommended that you avoid using this program unless "you know what
you are doing."

                                 CONTENTS:
                               =============
     A. WHAT IS THIS?
     B. WHAT CAN IT DO?
     C. EXTERNAL PROGRAMS
     D. COMPATIBILITY
     E. SYSTEM REQUIREMENTS
     F. PRE-INSTALLATION
     G. INSTALLATION
     H. POST-INSTALLATION
     I. STATUS OF THIS PROGRAM
     J. TECHNICAL SUPPORT


A. WHAT IS THIS?
=================
WebRSH is small program that was written to obtain certain functionality which
I could not find elsewhere. Its main purpose is to provide remote-control 
capabilities to Windows 95/NT boxes from any (internet-connected) platform,
and without the need for a special client. This is implemented through an
HTTP-CGI interface, such that it can be operated from any machine that has a
(decent) web-browser. WebRSH is mostly a CGI Perl script. You must have a
CGI-compliant web server and a Perl interpreter in order to use it (see
'COMPATIBILITY' and 'PRE-INSTALLATION' below for more information).


B. WHAT CAN IT DO?
===================
1. Provides access to the DOS/console shell: Execute any DOS command remotely.
2. Provides complete (upload/download) remote access to all files.
3. An HTML based 'GUI' shell provides:
  a) A file manager.
  b) A text editor.
  c) A fast "point and click" interface to various common operations, such
     as: Launching and terminating programs (applications), executing
     (DOS/console) programs and obtaining their (text) output, file
     upload/download, listing running processes (programs), etc.
4. Modular, highly configurable design: Easy to customize in various ways.
   Supports seamless integration of other CGI programs as plugins.
5. Supports a (relatively) high level of security due to the following:
  a) No special server (other then a regular web server) is active, so
     its existence is not easily exposed. The main script can be renamed
     and "hidden" with an arbitrary URL.
  b) Implements an independent access control mechanism, which integrates
     with (and enhances) the server's access-control mechanism.
  c) Can be used over completely encrypted connections (by using an SSL
     capable server).
  d) Can be used behind a firewall through a standard HTTP proxy server.

Remark: Almost everything that WebRSH does can also be done by running both
 an ftp server and a telnet server. Moreover, such an ftp/telnet combo provides
 some functionality that WebRSH does not. Specifically, WebRSH does not support
 upload/download of entire directory trees, nor does it support running
 interactive character mode programs. The main advantages of WebRSH over an
 ftp/telnet combo are:
 a) It provides a fast and easy interface to do many things (e.g., commands to
   the remote host can be embedded as URLs in a bookmark file or an HTML page
   and be executed by simply clicking appropriate links).
 b) It does not require any client other than a web browser.
 c) When used appropriately, it can be much more secure.


C. EXTERNAL PROGRAMS:
======================
The WebRSH distribution archive includes several external programs. They are
used by WebRSH, but are not part of it. All of them are free programs available
on the internet and are useful in their own right. The following external
programs are included:

1. cgi-lib.pl by Steven E. Brenner: "The de facto standard library for creating
  Common Gateway Interface (CGI) scripts in the Perl language." It is located in
  WebRSH's 'lib' directory. Details concerning usage and distribution of this
  library can be found in the body of the cgi-lib.pl file itself. More
  information concerning it can be found at the cgi-lib.pl homepage at
  http://www.bio.cam.ac.uk/cgi-lib.
  
2. Services.pl by Aldo Calpini (dada): A CGI Perl service manager for WinNT.
  It is integrated here as a WebRSH plugin, and the included file is a slightly
  modified version of the original. The Services.pl file is located in WebRSH's
  'lib' directory, and the modifications are documented in the body of the file
  itself. Services.pl can be used and redistributed under (more or less?) the
  same terms as Perl itself. The original file and more information concerning
  it can be found at http://www.divinf.it/dada/perl.

3. The "littles" archive by Nicholas J. Leon: Includes an implementation
  of 'ps', 'kill', and 'nice' for Windows 95/NT on x86 machines. The binaries
  are in WebRSH's 'bin' directory, and the original documentation file is
  included as "littles.read.me" (it has been renamed from 'read.me') in the
  'docs' directory. I have been informed by the author of "littles" that these
  utilities can be freely used and distributed as long as:
  a) Their author is being appropriately credited.
  b) The original documentation file is included with the distribution.

4. spnh by myself (Yoram Last): Spawns programs in a hidden window. This
  program is required in order for WebRSH to work properly with Microsoft's
  Personal Web Server for Windows 95. The spnh.exe binary is in WebRSH's
  'bin' directory, and a documenting 'spnh.readme.txt' file is in the 'docs'
  directory. The (tiny) source code is in 'docs/src'. It is included here
  under the terms of the GNU General Public License.

Remark: When using WebRSH on Windows NT, it can be very beneficial to have the
 NT resource kit utilities installed. In particular, utilities such as tlist.exe,
 pulist.exe, kill.exe, pstat.exe, shutdown.exe, addusers.exe, etc., provide
 administrative functionality from the command line that is otherwise only
 available from NT's graphical shell. Moreover, tlist.exe and kill.exe are
 used by some (optional) parts of WebRSH, so these two utilities are actually
 necessary in order to obtain its full functionality. The current (NT 4.0)
 resource kit utilities are only available along with the resource kit book
 from Microsoft Press. However, the older NT 3.5 resource kit utilities can
 (still) be freely downloaded from
 ftp://ftp.microsoft.com/bussys/winnt/winnt-public/reskit/nt35, and most of
 them should work well also with newer versions of NT. In particular, tlist.exe
 and kill.exe from this source work fine. Note that it is not necessary to
 install the entire package. It is possible to uncompress individual utilities
 from the distribution archive (e.g., Tlist.ex_) using a program such as WinZip.
 Another way to get tlist.exe and kill.exe is to download their source code,
 which is available from Microsoft as part of the "Microsoft Source Code
 Samples," (search for 'tlist' on Microsoft's site at http://www.microsoft.com),
 and compile it. (Actually, if you have VC++, you might already have it on the
 CD-ROM.) The resulting executables seem identical to the ones from the NT 3.5
 resource kit.


D. COMPATIBILITY:
==================
1. General:
  WebRSH exploits both Perl and the (standard) CGI interface quite a bit. As a
  result, it requires a good Perl interpreter and a server that has a robust CGI
  implementation. Moreover, the WebRSH process must be spawned with a full
  console. This is done anyway by most CGI-compliant servers, but may require
  special settings in some cases (such as with Microsoft's servers). 

2. Perl interpreters: 
  For full functionality of WebRSH you will probably need the Perl 5 interpreter
  from ActiveState ("Perl for Win32"), which can be downloaded from
  http://www.activestate.com. WebRSH had been tested with builds 109, 110, and
  306. It should work well with any later build. Builds earlier than 105 are
  likely to be very problematic on Windows 95. We recommend that you get the
  latest release build.

3. Servers:
  WebRSH had been tested and found to work well with the following servers:
  O'reilly's WebSite (1.1e), Netscape FastTrack (2.0/2.01 for Windows 95/NT),
  Microsoft's IIS/PWS for Windows NT (requires the (binary or dword) registry
  value 'CreateProcessWithNewConsole' to exist in the registry key
  HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3Svc\Parameters and
  be set to 1), and Microsoft's Personal Web Server for Windows 95 (1.0a)
  (requires use of spnh.exe for proper spawning of WebRSH. See spnh.readme.txt
  for more information). Some of the freeware servers around tend to have
  buggy CGI implementations, which might work well for many purposes--but not
  for WebRSH. For security reasons, it is strongly recommended to use WebRSH
  only with web servers that support user-based access control (namely, the
  server should implement a username+password authentication check, and should
  be able to restrict access to certain resources to specified, properly
  authenticated, users). WebRSH implements its own location-based access control
  mechanism, so it is not crucial to have location-based access control
  implemented by the server.

Remark: Under Windows NT, WebRSH's functionality depends, in part, on the
 security context in which the process runs. The default setting for Microsoft's
 servers is to run CGI processes in the security context of the (authenticated)
 user executing the script. Most other servers, however, run CGI processes in
 the same security (user) context in which the server itself is running. This
 may be the system context or some user context, and can usually be configured
 as desired. The preferable way for WebRSH to run depends on the way your system
 is configured and on what you want to do with it. There isn't any particular
 universally preferred option here. However, if you find that some parts of
 WebRSH are not functional, this may be a result of running WebRSH in an
 inappropriate security context.


E. SYSTEM REQUIREMENTS:
========================
WebRSH should work on any system that can run Windows 95/NT.
For reasonable performance (namely, convenient response time), a minimum
of 90 Mhz pentium with 16 MB RAM (32 MB RAM for NT) is recommended. If the
system is simultaneously running other programs (e.g., a number of servers)
larger memory might be needed to obtain reasonable performance.


F. PRE-INSTALLATION:
=====================
1. If you do not already have a web server, get and install one. For example,
  you can download the (no time limits) evaluation version of O'Reilly's WebSite
  from http://software.ora.com. If you do not meet their criteria for continued
  free use of this server, you can later switch to another server (after you
  mastered things).

2. If you do not already have a perl interpreter (or that you have an old
  interpreter), get and install one. We recommend that you get the latest release
  build of "Perl for Win32" from http://www.activestate.com. It is further
  recommended that perl.exe will be in your 'PATH' (such that "perl somescript.pl"
  would execute somescript.pl from the DOS prompt; this is often being
  automatically setup by Perl's installation), and that you will have a Windows
  association of the .pl extension with 'perl.exe' (such that double clicking
  somescript.pl's icon in explorer would run the script).

3. Set up your web server such that you can run CGI perl scripts. At the
  minimum, you should be able to run the following simple "Hello World" script:

  print "Content-type: text/plain\n\n";
  print "Hello World\!\n\n";

  The way to enable execution of Perl scripts depends on the server. In some cases,
  the Windows association of the .pl extension with 'perl.exe' is the main thing.
  You should reads your server's documentation for details.


G. INSTALLATION:
=================
For the simplest installation, do the following:

1. Unpack the wrsh*.zip archive into C:\WebRSH. You must unpack in a way
  that would preserve the directory structure. C:\WebRSH should have the
  following subdirectories: bin, cfg, docs, home, htm, lib, scripts, sfdir,
  and temp.

2. Map C:\WebRSH\scripts as a CGI enabled directory (e.g., as '/webrsh')
  of your web server. Restrict access to this directory to appropriate
  users.

3. Map C:\WebRSH\sfdir as '/sfdir' (it should be mapped as an ordinary server
  directory from which files can be retrieved). Restrict access to this
  directory to appropriate users.

Remarks:
a) If you need (or prefer) to install in a directory other than C:\WebRSH, you
  will need to edit (with a text editor such as 'Notepad') the script file
  webrsh.pl in the scripts subdirectory. (This is the main WebRSH script.)
  Look for the line
  $ProgDir = 'C:\WebRSH';
  and change C:\WebRSH to the appropriate path.

b) If you can't (or prefer not to) map C:\WebRSH\scripts as a CGI directory,
  simply copy the C:\WebRSH\scripts\webrsh.pl script to any CGI enabled directory.
  However, it is strongly recommended that access to this directory will be
  restricted to appropriate users.
  
c) If you can't (or prefer not to) map C:\WebRSH\sfdir as /sfdir, you should
  copy its content to some other directory that is mapped as '/sfdir'. It is also
  possible to use a URL other than '/sfdir'. However, if you intend to use either
  a different location or a different URL mapping for this directory you will later
  need to modify WebRSH's option settings accordingly (see below).

d) If you install on an NTFS partition, you should make sure that the webrsh.pl
  script (when it is run through the server) will have write permission to the
  following subdirectories of C:\WebRSH (and to the files in them): cfg, scripts,
  sfdir, and temp. It is also recommended to have write permission to the home 
  subdirectory. If you install in a non-standard way (e.g., if you run webrsh.pl
  from another directory) you will need to set write permissions accordingly.

e) If you deviate from the recommended default directory structure, it is
  strongly recommended that you avoid using any directories that have spaces
  in their names (so don't install WebRSH, or any part of it, in a subdirectory
  of 'Program Files').
  

H. POST-INSTALLATION:
======================
1. Once installation is complete, access the webrsh.pl script with a web browser.
  If you mapped C:\WebRSH\scripts as '/webrsh', the appropriate URL would be:
  http://127.0.0.1/webrsh/webrsh.pl
  Note that you must access the script through the 127.0.0.1 (localhost) IP address.
  For security reasons, the script is initially set to allow access only from the
  computer on which it is installed--through the 127.0.0.1 IP address. If you
  find that you can't access the script (namely, if you get the "You are not
  allowed to access this program!" message), you can disable location based
  access control by editing the webrsh.pl script: Look for the line
  $LocSecurity = 1;
  and change it to
  $LocSecurity = 0;

2. Once you have accessed the script, you should complete the installation as
  follows:
  a) If you are using a location and/or a URL mapping for the 'sfdir' directory
    which is different from the default, you need to set up the appropriate
    directory paths.
  b) You need to set up access control according to how you intend to use WebRSH.
  c) You may wish to modify other options.

  Note that the main (webrsh.pl) script also doubles as a configuration file.
  Namely, option settings are stored in webrsh.pl, and it is being overwritten
  whenever options are modified. When this happens, WebRSH stores a backup copy
  of the old script as webrsh-.pl (unless you disable this behavior). It is 
  stored in the same directory where webrsh.pl is. If webrsh.pl somehow becomes
  unfunctional due to bad option settings, you should be able to recover by
  overwriting webrsh.pl with webrsh-.pl.

3. If you need to set non-default paths for 'sfdir', do the following:
  Click '[OPTIONS]' from WebRSH's main menu, and then click 'Directories'.
  Set the 'File Sending Directory' to the full path of where you copied the
  appropriate files, and the 'File Sending URL' to the appropriate URL path
  by which this directory is accessible through the web server. Then click
  'Apply' or 'OK' in order for the change to take effect.

4. At this point WebRSH should be fully functional. You should feel free to
  explore it. In particular, you should click '[HELP]' from WebRSH's main menu
  to learn more about it.

5. Setting Access Control:

  WebRSH implements an independent access control mechanism, which is intended
  to integrate with the server's access control. It includes:
  a) The ability to restrict access by location (IP address of the accessing
    client).
  b) The ability to check that some user authorization transaction took place,
    by checking for the existence of the environment variable 'AUTH_TYPE'.
  c) The ability to restrict access only to some specified users. (However,
    WebRSH does not authenticate users by itself. It counts on the server to
    authenticate users and supply properly authenticated usernames.)

  These built-in security features of WebRSH can be used to:
  a) Enhance the server's access control mechanism (e.g., some servers do not
   implement location-based access control).
  b) Double-check the server, to protect from bugs and/or configuration errors.

  Before setting access control, it is recommended that you check for the
  existence of certain environment variables. To do that enter the command 'set'
  in the command field, and click 'Execute' (or click '[MORE]' from the main menu
  and then click 'SET'). You should look for the following variables:
  REMOTE_ADDR: The IP address of the computer from which WebRSH had been accessed.
  AUTH_TYPE: The authentication method used. The existence of this variable
    indicates that authentication information had been submitted by the client
    when WebRSH had been accessed.
  REMOTE_USER (or AUTH_USER if the server is WebSite): The name of the user
    accessing WebRSH.

  To set access control, click '[OPTIONS]' from WebRSH's main menu, and then
  click 'Access Control'. Note the following:
  a) Location-based access control is completely disabled unless the "Restrict
    Access by Location" box is checked. Once checked, WebRSH will be accessible
    only to hosts that match one of the masks in the "Allowed Hosts" list and
    do NOT match any of the masks in the "Denied Hosts" list. Masks are IP
    addresses (of the form x.x.x.x) which may contain the following wild card
    symbols: '*' stands for zero or more digits. '?' stands for one digit.
    In order for all this to work properly, the accessing host's IP address
    must be supplied by the server in the environment variable 'REMOTE_ADDR'.
  b) If the "Check for User Authentication" box is checked, WebRSH will be
    accessible only if the environment variable 'AUTH_TYPE' exists and has
    a non-null value. If your server properly supplies this variable, it is
    recommended that you check this box. Otherwise, you should leave it unchecked.
    Note that this check doesn't provide much protection by itself, and a
    malicious client should be able to fool most servers into creating this
    variable. The main purpose of this check is to verify that the server indeed
    requires user authentication (under normal operation) and to alert you
    in case it does not.
  c) If the "Allow Access Only to these Users" box is checked, then only users
    with usernames that appear in the proceeding list will be able to access
    WebRSH. You should check that your server properly supplies the username in
    the environment variable 'REMOTE_USER' (or 'AUTH_USER' if the server is
    WebSite) before checking this box.

  Once the access control options are set up satisfactorily, you should click
  'Apply' or 'OK' in order for the change to take effect.

6. Process listing:

  WebRSH provides process listing and "killable links" through the 'rshps' and
  'rshkill' commands (equivalently, by clicking '[PS]' or '[KILL]' from the main
  menu). However, there are two different options of how to implement these
  commands, each of which uses different utilities. The default (shipping)
  setting is to use the 'pslib.pl' library, which uses the 'ps' and 'kill'
  commands from the "littles" archive. These utilities work on both NT and
  Windows 95, but 'ps' actually lists titled windows--not processes, such that
  some processes might not be listed while others may be listed several times.
  Moreover, under NT only a subset of the system's processes will be shown--
  depending on the precise way WebRSH is being run. Using this library can
  be convenient sometimes, but not if you need to list ALL running processes.
  On Windows NT, there is an alternative: you can use 'rkpslib.pl' which uses
  the resource kit utilities 'tlist.exe' and 'kill.exe' (see the remark in
  'EXTERNAL PROGRAMS' above on how to obtain them). These utilities need to be
  in your PATH in order for 'rkpslib.pl' to work.

  To change the "Process Handling" library, click '[OPTIONS]' from WebRSH's main
  menu, and then click 'General Preferences'. Look for 'PS Library:' and change
  it to the one you want to use. (Note that you have a choice only under Windows
  NT. Under Windows 95 only 'pslib.pl' will work.) Then click 'Apply' or 'OK' in
  order for the change to take effect.

Remark: If you installed WebRSH on a computer with a non-x86 processor (e.g.,
 on an Alpha machine), then you can delete the entire C:\WebRSH\bin directory
 (all of the binaries there are x86 binaries). You must have the 'tlist.exe'
 and 'kill.exe' utilities and to use 'rkpslib.pl' in order to have process
 listing/killing functionality, but other than that WebRSH should be fully
 functional (in theory).


I. STATUS OF THIS PROGRAM
==========================
WebRSH is currently in beta status. It should be fully functional, but some
bugs may be present. Using it in any "working environment" must be done with
caution. The on-line help is only partially implemented. Hopefully, the
existing part along with this readme file should suffice for most purposes.


J. TECHNICAL SUPPORT
=====================
No support of any kind is provided for this program, and the author
does not promise to answer e-mail messages related to it. Bug reports
and feedback (of any kind) to ylast@mindless.com would be appreciated.

