DeScribe Copyright DeScribe, Inc., 1988, 1989 Letter HPDeskJe HPDeskJe HP DeskJet 680C HP DeskJet 680C Info 1 Info 2 Info 3 Info 4 Courier onospaced StickyNote Helvetica portional rev1.10,081997 PlanetWide OS/2 Web Server (c)copyright 1997 Payne-Mennie Computing Services It is assumed that you are the Webmaster administrating the server and are already familiar with the HTML language tags and their uses. Also, that you understand the operation of the OS/2 Warp environment and can perform the described tasks in our documentation. COPYRIGHT/LEGAL: This software is provided on an "as-is" basis. We offer no warranty on this software whatsoever, and you use it at your own risk. The files contained in this package may not be modified or reverse- engineered or decompiled in any form; for any reason. Problems with the binaries or documentation should be brought to the attention of Payne-Mennie Computing Services for correction. You are granted use of this "shareware" version of PlanetWide v1.10 OS/2 Web Server for a reasonable period of time allowing you to evaluate the suitability and operation of the software. After the evaluation period you should consider registering your copy with Payne-Mennie Computing Services.(see: how to register) OVERVIEW: Welcome! PlanetWide v1.10 is a powerful, multithreaded, 32-bit OS/2 HTTP Web Server. It was developed to serve high volumes of data from the OS/2 Warp platform, and do it efficiently! As the webmaster, you require an HTTP server that is lean on the system resources, and still performs. PlanetWide was written with a text-based interface, preserving precious memory and virtual swap space. There is also a lot of important information available to you in the log file,and in the text window. Further explanation is available; (see: log file ). The server configuration is very simple, and you should be up and running in just a few minutes. Enjoy. FEATURES IN THIS RELEASE: Configurable maximum number of connections Configurable maximum packet size (BLOCKSIZE). Support for a large number of simultaneous connections. Full reverse DNS lookup per connection. Complete logging of all incoming connections including - Number of threads in use at the time. - Peak threads. - Client IP address or domain name (DNS lookup). - File delivered. - File requested even if file is nonexistent or the user does not have permission to receive it. Built-in NCSA imagemap support (RECT, CIRCLE, POLY, and DEFAULT). CGI interfrace for running external EXE and CMD files (GET,POST). Allow/disallow any IP number, range, or subnet on a per directory basis. Directory and file security on a per directory basis. Configurable remote server kill from your web browser. Do you know of a feature that should be included in PlanetWide? Contact us and let us know. If we think it's a suitable idea, we'll include it in a future release. SYSTEM REQUIREMENTS: - OS/2 Warp Connect, or Warp v4.0. - HPFS formatted partition. - TCPIP v2.0 (or IAK). - Recommend 12MB of RAM if your machine is more than just a web server. - Internet service with a static IP address. UPGRADING FROM A PREVIOUS VERSION: If you have a previous version of PlanetWide installed and running, then you only need to follow five(5) simple steps. 1. Unzip the PlanetWide ZIP archive into a temporary directory. 2. Copy the new WEBSERV.EXE into your existing server directory. OPTIONAL: create a subdirectory of your c:\webserv\ called x:\webserv\doc\ and unzip PWDOCS.ZIP into it. These online documents and tutorials are available to you through your web client such as Netscape Navigator(tm) for OS/2. Included: Frames/HTML Standard/HTML ASCII TEXT Optional: create a subdirectory of your x:\webserv\ called x:\webserv\cgi-bin\ and unzip the CGI-BIN.ZIP into it. The files contained within the zip archive are POST and GET Method CGI's and their sources which will add functionality to your web server software. Included: Guestbook (POST METHOD) Guestbook (GET METHOD) See the online documentation for more information and easy tutorials. 3. Edit your WEBSERV.CNF and add the following line: (configure the reverse DNS lookup support: Enable=YES Disable=NO) LOOKUP YES 4. Edit the PlanetWide WPS ICON properties to reflect the new version number of the software (v1.10). 5. Run WEBSERV.EXE from the command line, or use the PlanetWide WPS icon. You are back in business. NEW INSTALLATION PROCEDURE: If this is your first time installing PlanetWide OS/2 Web Server, carefully follow these steps. In a few minutes you will have a fully functional server. - Create a new directory to contain your web server files.(eg: x:\WEBSERV). (Place your web pages in subdirectories of the newly created x:\WEBSERV). - Unzip PWWS110.zip into your new directory. (Unzipping will produce many files, including:) - WEBSERV.EXE - server executible. - WEBSERV.CNF - server configuration file(ascii text). - WEBSERV.DOC - server documentation file(ascii text). - EXCLUDE.CNF - file-exclusions data file(ascii text). - DATATYPE.CNF - file-type configuration file(ascii text). - ERR404.HTM - default ERROR 404 html page. - FILTER - server security filter file(ascii text). - MAKEICON.CMD - WPS installation command file. - PW.ICO - server WPS Icon. - CGI-BIN.ZIP - POST/GET CGI programs and their sources. - PWDOC.ZIP - Online documentation including many tutorials. - REGISTER.TXT - Registration Form. Don t forget to register! - OPTIONAL: create a subdirectory of your c:\webserv\ called x:\webserv\doc\ and unzip PWDOCS.ZIP into it. These online documents and tutorials are available to you through your web client such as Netscape Navigator(tm) for OS/2. Included: Frames/HTML Standard/HTML ASCII TEXT - Optional: create a subdirectory of your x:\webserv\ called x:\webserv\cgi-bin\ and unzip the CGI-BIN.ZIP into it. The files contained within the zip archive are POST and GET Method CGI's and their sources which will add functionality to your web server software. Included: Guestbook (POST METHOD) Guestbook (GET METHOD) See the online documentation for more information and easy tutorials. - Run MAKEICON.CMD to create the WorkPlace Shell folder and Icons on your desktop. - Edit WEBSERV.CNF to suit your installation - If you are unsure of what values to use, (see: configuring the server). - Place your INDEX.HTM, INDEX.HTML, DEFAULT.HTM, or DEFAULT.HTML in the same directory you installed to. Don't be alarmed about having your configuration files in the server default directory, the EXCLUDE.CNF can be configured to refuse transmission of these files. (see: exclude.cnf file). - Run WEBSERV.EXE from the command line, or use the WPS Icon on your desktop. SPECIFYING THE PORT#: WEBSERV.EXE can be configured to start on any tcp/ip port number. If no port has been specified, the server defaults to PORT:80. (eg: to start the server on PORT:8888) - from the OS/2 command line: x:\webserv\WEBSERV 8888 - from the WPS Icon: (edit the WPS Icon properties) Path and File name: webserv.exe Parameters: 8888 Working Directory: x:\webserv Note: Multiple web servers can co-exist on the system with each session serving a different port. RUNNING PLANETWIDE LOCALLY: PlanetWide may function as a fully operational web server on a local machine without an ISP connection. Running locally is a great way to build your web pages. Follow the instructions below to create your local web server: - Initiate the installation of MPTS networking support from your OS/2 Warp CDROM. - Choose to configure your MPTS LAN Adapter. - Select the IBM NULL MAC DRIVER as your lan adapter. - Add the TCP/IP protocol. - Exit and SAVE the new configuration. - Shutdown and restart your system. - Enter the TCP/IP Configuration utility. - Select the Loopback Interface from the interface list. - Enable the interface. - Enable MANUALLY SELECT IP ADDRESS. - The interface defaults to 127.0.0.1 (you may alter this address) - Exit and Save your configuration. - Shutdown and restart your system. - Edit the WEBSERV.CNF to reflect your manually configured IP address. - Start PlanetWide from command line, or from the WPS Icon. - Access your web server by entering the IP address on the URL line of your web browser. ( eg: http://127.0.0.1/mypage/index.htm ) Congratulations, you are now a one system Internet! Enjoy PlanetWide! CONFIGURING THE SERVER (WEBSERV.CNF): Here is an example of a typical WEBSERV.CNF file: SERVERNAME www.myserver.ca KILLSTRING SHUT_DOWN_NOW MAXCONN 200 BLOCKSIZE 600 SERVERNAME - The IP address of your machine (eg:10.10.10.10) or the domain name associated with your server (eg: www.myserver.ca). KILLSTRING - This is the string which you can use to kill your server from a remote location. You should change this string to avoid others shutting down your server. If you never want to be able to shut down your server remotely, change this string to something like: "kfjhglqi3976t4uc#$Tgf8g7345uvdf" To shut down PlanetWide from your browser, simply enter the URL like this: http://www.myserver.ca/SHUT_DOWN_NOW MAXCONN - Depending on your available bandwidth, the power of your machine, the volume of traffic to your server, etc. you may wish to limit the number of connections to PlanteWide. By specifying a value of 40 here you make it so that anyone trying to connect to the server will have to wait if there are already 40 outstanding requests. PlanetWide is capable of handling as many connections as there is available system resources. Busy sites built on larger Pentium(tm) computers with a lot of memory may service thousands of simultaneous connections. BLOCKSIZE - This is the maximum packet size for the server. If this number is high, you will be able to service less connections, but the ones that you are servicing will receive more data at a time. If this number is low, you will be able to service more connections, but the efficiency will be a bit lower due to packet header overhead, etc. The default blocksize is 600 bytes. We recommend leaving it there unless you wish to experiment with your particular configuration. Note: This number is only a packet size. Your web pages are NOT limited in size and can be any size you like. CONFIGURING FILE EXCLUSIONS (EXCLUDE.CNF): This file is where you list the files that you don't want people to have access to, even if they reference them directly. Such files include: the server executable, configuration files, security files, and maybe even log files. The EXCLUDE.CNF file is only read when the server is started, so if you change it, you must restart the server for the changes to take effect. Files are listed one file per line. For each file you wish to exclude, place the /path/filename into your EXCLUDE.CNF file: - One file entry per line. - Use forward slashes only in your filename entries. - PlanetWide assumes the root directory to be where webserv.exe is located. The contents of a new EXCLUDE.CNF is as follows: webserv.exe exclude.cnf webserv.cnf datatype.cnf webserv.log A sample entry into the EXCLUDE.CNF file: /users/bob/bobspage.html Note: Filter files in any directory are automatically excluded and do not require an entry in the exclude.cnf. (see: filtering ip addresses). PROGRAM DIRECTORIES - (/CGI-BIN): PlanetWide has built-in support for handling the POST-METHOD and GET-METHOD CGI(common gateway interface). This interface allows the server to host various external programs such as digit-counters, guest-books and interfaces to databases across the web. During the installation process, a subdirectory of the server directory must be created to store your EXE and CMD files. The directory is x:\WEBSERV\CGI-BIN\. Note: if your web server directory is named other than x:\webserv, create the \cgi-bin\ directory in the correct location. For example: if a user accesses a guest-book from a web page, PlanetWide searches the \CGI-BIN directory for the program specified. If the specified program is found, it is then initiated. If no matching file is found, the request is ignored. PlanetWide assumes the file extension of a CGI, so there is no need to fully qualify the CGI filename. If you wish to execute GUESTBOOK.EXE, simply use this command: