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.