WebRSH 1.1b (beta) - A Remote-Computing CGI Program.
Copyright (C) 1997,1998 Yoram Last (ylast@mindless.com)
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.
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."
ABOUT THIS FILE:
==================
This is the readme file for WebRSH 1.1b, released July 12, 1998. This file
contains general information concerning WebRSH along with what most people
would need in order to install it successfully. It is recommended that anyone
installing WebRSH would read this file. The WebRSH distribution archive also
includes the two platform-specific files 'install-win32.txt' and
'install-unix.txt', which contain some very detailed installation information.
These files are aimed at people without prior CGI experience, at anyone that
runs into problems, or at anyone attempting a complicated installation of
WebRSH such as a system-wide multi-user installation. More information can
also be obtained by looking at the main WebRSH script in WebRSH's 'scripts'
directory. Further documentation is included in WebRSH's online help manual.
WebRSH needs to first be installed before this manual can be properly accessed.
Also, for the latest information on WebRSH, you should check its homepage at
http://www.geocities.com/SiliconValley/Horizon/7772/webrsh.html.
Note that while we provide a great deal of information here, installation of
WebRSH is quite simple and should not take more than a few minutes (as long
as you already have a CGI-Perl enabled web server). There is also a recommended
post-installation procedure intended to verify that access control to WebRSH
and a few other things are properly set up.
CONTENTS:
=============
A. WHAT IS THIS?
B. WHAT DOES IT DO?
C. EXTERNAL PROGRAMS
D. COMPATIBILITY
E. SYSTEM REQUIREMENTS
F. INSTALLATION
G. POST-INSTALLATION
H. STATUS OF THIS PROGRAM
I. TODOS
J. TECHNICAL SUPPORT
K. HOW CAN I HELP?
A. WHAT IS THIS?
=================
WebRSH is a flexible and extensible general purpose web-based computing shell,
designed to run as a CGI program and to provide a command line interface, file
manager, text editor, and a few other basic things, while being highly
configurable and adaptable to various tasks. WebRSH is implemented in Perl,
and requires, on the server side, a CGI-compliant web server and a Perl
interpreter in order to work. On the client side, it works with almost any
web browser. WebRSH is multi-platform and currently supports both Win32 and
UNIX. It is distributed as a single archive containing everything needed to
install it on any of its supported platforms (except for Perl and a web server,
that is).
B. WHAT DOES IT DO?
===================
1. Provides access to the (character mode) shell: Execute any shell command remotely.
2. Provides complete (upload/download) remote access to 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, executing commands and
obtaining their (text) output, file upload/download, listing running
processes, 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 using 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 provides command line capability along with file transfer capability
from a single interface.
c) It does not require any client other than a web browser.
d) 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 that
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. getcwd.pl by Brandon S. Allbery: Gets the current working directory on
UNIX platforms, and used by WebRSH precisely for this purpose. This is
simply the getcwd script from the standard Perl library, which is included
with the standard Perl distribution. We include it here (in WebRSH's own
'lib' directory) to release WebRSH from needing anything other than a Perl
binary in order to work (on UNIX platforms, that is).
3. 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.
4. ps by myself (Yoram Last), partially based on code by Amol Deshpande: Lists
running processes on Win32 platforms and used by WebRSH for that purpose. The
ps.exe binary is in WebRSH's 'bin' directory and the source code is in
'docs/src'. This program is included here under the terms of the GNU General
Public License.
5. 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.
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.
2. Perl interpreters:
UNIX: WebRSH should work with Perl 5.001m or later, although it was only
tested with Perl 5.004. Only a Perl binary is required. No modules are used.
Win32: 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 306 and
316, and should work well with any stable build from 306 and on. WebRSH also
works well with earlier 1xx builds (tested with 109,110) except for one
thing: The process killing capability (namely, the 'rshkill' command), as
implemented by the 'pslib-win32.pl' library, uses Perl's built in 'kill'
command which is not implemented in those earlier builds. You can still
use such a build with full functionality on NT, if you have the NT resource
kit installed and you change your PS Library to 'pslib-ntrk.pl' (see more on
this below). The newer 'ActivePerl' from ActiveState (currently in beta) had
not been tested. Win32 Perl ports based on the standard Perl 5.004_x
distribution might work, but had not been tested. CygWin based ports are
NOT likely to work.
3. Servers:
WebRSH requires a robust and complete CGI implementation. It had been tested
and found to work well with Apache (on both Linux and NT), and with the main
commercial servers for Win32 (Microsoft's native IIS/PWS servers, Netscape's
FastTrack/Enterprise, and O'reilly's WebSite). Note, however, that there are
quite a few servers floating around (particularly for Win32) that have broken
CGI implementations, and that might therefore not work properly with 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.
4. Browsers:
Most of WebRSH is HTML 2.0 compliant, at least in the sense that it should
work properly with any HTML 2.0 compliant web browser. One exception to this
rule is support for form-based file uploading which is either provided by a
browser or is not. Other than that, however, all that is needed is support for
basic HTML, forms, and tables. The optional 'Frames Interface' only works with
browsers that support both frames and JavaScript. Overall, WebRSH is at its
best with Netscape Navigator version 3.0 or higher.
Here is a rough compatibility status report for some specific browsers:
Netscape Navigator 2.0 and above: 100% of WebRSH's functionality is available
with these browsers. Some purely cosmetical features (table colors and some
dynamical features of the Frames Interface) do not work in Navigator 2.0x
and require Navigator 3.0 or above.
MSIE 4.0x: Roughly speaking, everything works. In particular, the Frames
Interface works nicely. However, The 'GET as TEXT' and 'GET as BIN'
file downloading methods are not effective (they behave the same as
'GET') since MSIE ignores the server-reported MIME type of files and
decides by itself what is the type of the file and what it should do
with it.
MSIE 3.0x: Neither file uploading nor the Frames Interface work and the
same 'GET as *' limitation of MSIE 4.0x applies. Other than that it
works fine.
HotJava 1.x, Lynx 2.x, MSIE 2.0, NCSA Mosaic 3.0 (for Windows), Opera 3.x,
and probably most other usable web browsers: Neither file uploading nor the
Frames Interface work with these browsers, but the rest of WebRSH is
fully functional.
Remark: WebRSH's functionality depends, in part, on the security context in which
the process runs. This is not an issue on Win95, and it is fairly straight
forward on UNIX platform. However, it can get quite tricky on WinNT due to its
complex security model. NT users should check their security settings in the
event of WebRSH exhibiting potentially related unexpected behavior.
E. SYSTEM REQUIREMENTS:
========================
WebRSH should work on any system that runs an appropriate operating
system, Perl interpreter, and web server. For reasonable performance
(namely, convenient response time), the following minimal system
configurations (or equivalents) are recommended (faster is always better):
Linux: 486DX2 (66 Mhz) with 16 MB RAM.
Windows 95: 100 Mhz Pentium with 16 MB RAM.
Windows NT: 90 Mhz Pentium with 32 MB RAM.
If the system is simultaneously running other programs (e.g., a number
of servers) larger memory might be needed to obtain reasonable performance.
F. INSTALLATION:
=================
We provide here a fairly brief description of how to install WebRSH. It should
suffice for most people with working CGI-Perl setups and prior CGI experience.
Much more detailed descriptions are given in the two OS-specific files
'install-unix.txt' and 'install-win32.txt'. If you do not already have a
working CGI-Perl setup, or that you do not have any prior CGI experience, or
you are interested in making a system-wide multi-user installation, or you
find the explanation here to be unclear, or if you run into problems, or...
Then you should read one of these files, according to your operating system.
Before actually installing WebRSH, it may be useful to know some basic things
about its design, which can be thought of as having the following three parts:
a) A 'Main Program Directory', where most of the program actually resides. In
general, it can be located anywhere. However, WebRSH needs to have read permission
to everything in it and write permission to some parts of it. Some portions
of it can be later on moved elsewhere if desired, but there is no reason to be
concerned about it in a single-user installation. A multi-user installation is
more complicated since those files that get written by WebRSH need to be copied
to private locations for each user.
b) A 'File Sending Directory', which contains several images and HTML files that
are used as part of WebRSH's output. This directory needs to be mapped as part
of your web space, such that the files in it can be retrieved directly through
the web server.
c) The 'main WebRSH script' which is the one and only file that needs to be
enabled as a CGI script. It can be moved anywhere and renamed as desired, as long
as it is made accessible as a CGI script. In order for WebRSH to work there are two
pieces of information that must be entered in the body of this file as part of the
installation: The location of the 'Main Program Directory' (so that WebRSH can
find the rest of itself) and the URI which corresponds to the 'File Sending Directory'
(so that WebRSH can create links to the files in it). The 'main WebRSH script' also
doubles as being the main configuration file for WebRSH, and the script overwrites
itself when options are modified from the web-based interface. For this reason, this
script should be writable by the user context in which it runs. In a multi-user
installation, each user needs to run his own copy of this script and there are a few
more location parameters that need to be entered in its body as part of enabling it
for each user's usage.
We can now proceed to install WebRSH. (We only describe here a single-user
installation.) Do the following:
a) Extract the distribution archive to its final destination. You must extract
it in a way that preserves directory structure, such that you get a top-level
'WebRSH' directory (this is your 'Main Program Directory') with a number of
of subdirectories (we refer to those as WebRSH's directories).
b) WebRSH's 'sfdir' directory is your 'File Sending Directory'. Map it as part
of your web space as an ordinary directory. If you can't simply map it, then
either copy it or move it to where it needs to reside in order to be
accessible through your web server. It is recommended that you restrict access
to this directory only to users that will be running WebRSH.
c) One of the files in WebRSH's 'scripts' directory is your 'main WebRSH script'
(the 'webrsh.cgi' is for UNIX and the 'webrsh-win32.pl' is for Win32). Copy
it to where you want to run it from, and enable it as a CGI script. Restrict
access to it such that it is only accessible to whoever is supposed to access
it. It is recommended that you use a username + password authentication scheme.
d) Open your CGI-enabled 'main WebRSH script' with a text editor. Look for
the line starting with '$ProgDir = ', and set the value of $ProgDir to be
the full path to your 'Main Program Directory'. Then look for the line
starting with '$SendFilesUrl = ', and set the value of $SendFilesUrl to
be the URI which corresponds to your 'sfdir'. Save your changes.
WebRSH should now be properly installed, and you can proceed to the
'POST-INSTALLATION' section. UNIX users may want to delete a few Win32
specific files that aren't doing anything useful on their system. These
are the 'webrsh-win32.pl' file in WebRSH's 'scripts' directory, the two .exe
files in WebRSH's 'bin' directory, and the two files in the 'src' subdirectory
of WebRSH's 'docs' directory. Win32 users can delete the file 'webrsh.cgi' in
WebRSH's 'scripts' directory. There are a few more platform-specific files
scattered around, but we recommend that you leave these alone.
G. POST-INSTALLATION:
======================
1. Once installation is complete, access the 'main WebRSH script' with a web
browser. By default (unless you changed the '$LocSecurity' variable earlier),
it should only be accessible from the local machine on which it is installed
through the 127.0.0.1 (localhost) IP address. This means that the relevant
URL should be something like http://127.0.0.1/webrsh/webrsh.cgi. If you can't
access it in this way or you are getting the 'You are not allowed to access
this program!' message, you may need to disable location based access control.
To do this open your relevant copy of the 'main WebRSH script' with a text
editor, and look for the line:
$LocSecurity = 1;
Change it to
$LocSecurity = 0;
and save the modified script. You should now be able to access it from anywhere.
2. Once you have accessed the script, you should complete the installation as
follows:
a) You need to set up access control according to how you intend to use WebRSH.
b) Process listing and killing might not yet work at this stage. You may need
to setup WebRSH to use an appropriate 'PS Library' (see below).
c) You may wish to modify other options, so it's a good idea to spend some time
exploring WebRSH to see what is available.
Note that the 'main WebRSH script' also doubles as a configuration file. That is,
option settings are stored in it, and it is being overwritten whenever options
are modified. When this happens, WebRSH stores a backup copy of the old script
as a file with the same name except for a '-' added before the extension (unless
you disable this behavior). It is stored in the same directory where the 'main
WebRSH script' is. If WebRSH somehow becomes unfunctional due to bad option
settings, you should be able to recover by overwriting your 'main WebRSH script'
with this backup copy.
3. 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 authorization 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.
4. Process Listing and Killing:
WebRSH provides process listing and "killable links" through the 'rshps' and
'rshkilllist' commands (equivalently, by clicking '[PS]' or '[KILL]' in the
Main Menu). It also lets you kill processes with the 'rshkill' command. The
way to obtain process listing is very much system dependent: On Win32 there
is no built-in command that does that ('tlist' from the NT resource kit is
probably the closest to being such a thing). On UNIX platforms, a 'ps' command
is always available, but its precise syntax (namely, available switches) and
output depend on the platform. Moreover, there is no universal choice of what
should be the output of WebRSH-provided process listing: In some cases it may
be desirable to have it list ALL processes running on the system, while in
other cases it would be better to only list processes owned by (or accessible
to) the WebRSH user.
The way WebRSH tackles these issues is by having the actual implementations of
its relevant commands be contained in an easy to replace 'PS Library'. A
'PS Library' is simply a Perl script that should reside in WebRSH's 'lib'
directory and contain the three subroutines: 'RshPs', 'RshKill' and 'PrintKill'.
They should correspondingly implement: 'rshps', 'rshkill', and 'rshkilllist'.
You choose your preferable 'PS Library' by specifying its name in an appropriate
field in the 'General Preferences' options setting form. We recommend that such
libraries have names of the form pslib-*.pl, where * is replaced by some
descriptive string. One should never really need to write such a 'PS Library'
from scratch. The idea of using this mechanism is the following: By starting
from an existing library that works on your platform (or on a similar platform),
it should be easy create new libraries that work as you want them to. In most
cases all you need to modify is the command line switches given to the 'ps'
command. There is no limit on how many such libraries you can have, and you
can easily switch between them by changing the 'PS Library' name in your
'General Preferences'.
The current version of WebRSH ships with three such pslib-*.pl libraries:
'pslib-linux.pl', 'pslib-win32.pl', and 'pslib-ntrk.pl'. The first of those
is the default for UNIX platforms. It works (as its name suggests) on Linux,
and might also work on some other unices, but, in general, you would need
to modify this library in order to get a version that works on another UNIX
platform. (Hopefully, future versions of WebRSH will include more ready
to go pslib-*.pl files for other systems. This mostly depends on users
supplying them though.) The 'pslib-win32.pl' library is the default for Win32
platforms. It depends on the supplied 'ps.exe' to reside in WebRSH's 'bin'
directory. Note that if you want it to list ALL processes on the system,
you should edit it and add the '-a' switch to be given to 'ps.exe'. Otherwise,
it would only list processes that are accessible by the WebRSH user. The
'pslib-ntrk.pl' library only works on WinNT with the resource kit utilities
'tlist' and 'kill' installed (they must be in WebRSH's PATH). In most cases
there is no reason to use it. It is included here mainly to support using WebRSH
with older (1xx) builds of "Perl for Win32" ('pslib-win32.pl' doesn't work with
those), and also to support running WebRSH on non-x86 NT boxes (the supplied
'ps.exe' is an x86 binary) in the event that you don't have a compiler to
compile the source of 'ps.exe'.
H. 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.
WebRSH should be quite stable on Win32 platforms, and to a slightly lesser
extent on Linux. It was not yet tested on any other operating system, and while
it should work on any UNIX variant it should be considered an alpha status
program on platforms where it was not yet tested.
I. TODOS
=========
The following are on the "todo" list for the release of version 1.1:
1. Complete the online help manual.
2. Implement a decent property sheet for the file manager, including
a graphical interface to setting UNIX ownership and permissions.
(The currently provided listing is just a temporary hack.) Support
for NTFS and SMB sharing permissions on Win32 is NOT planned at
this time, unless someone else would volunteer to do it.
3. Text Editor improvements (maybe).
In the longer run, various wonderful things may or may not be done.
J. TECHNICAL SUPPORT
=====================
No support of any kind is promised for this program, and the author does not
promise to answer all e-mail messages related to it. Bug reports and feedback
(of any kind) to ylast@mindless.com would be greatly appreciated. The author
may assist users of this program who run into problems if his time allows
it. However, absolutely no commitment to doing that is being given. Users
should attempt to read the documentation that comes with WebRSH and to check
the WebRSH homepage at
http://www.geocities.com/SiliconValley/Horizon/7772/webrsh.html
for the latest information prior to seeking the author's help. Note that
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.
K. HOW CAN I HELP?
===================
WebRSH's further development and stabilization depends greatly on aid from
the user/developer community that has interest in it. Particularly, due to
the high level of system interaction of this program along with the author's
limited access to operating systems and their various potential setups.
Help can include general feedback, bug reports, fixes, feature requests,
reports on success or failure of using WebRSH in settings where its usability
status is not yet known, etc. It can also be more substantial and include
implementing portions of WebRSH that are still missing, improving the existing
documentation, writing CGI plugins that add to WebRSH's functionality, and
porting WebRSH to operating systems on which it does not yet work (or providing
"missing pieces" like pslib-*.pl scripts for operating systems where some of
WebRSH's functionality is absent). More generally, if you think something is
missing, please drop me a note. If you are also willing to do something about
it, that's even better.
Note that while WebRSH is in beta status, it is important to report success
of its installation/operation as well as problems. Without that it would be
difficult to asses its stability/usability status and the final release will
be delayed. So, if you are using it, please drop a short note to
ylast@mindless.com saying how it goes.
(
geocities.com/siliconvalley/horizon) (
geocities.com/siliconvalley)