GoAhead® WebServer 2.1 Release Notes

Release Date: 5/23/00
File: release.htm

These notes provides release-specific information for the May, 2000 release of GoAhead WebServer 2.1. Please see the License Agreement as well as the online documentation included with this WebServer release.

Table of Contents

1. What's New in This Release?
2. Operating System Support
3. Feature Support
4. Compiling and Running GoAhead WebServer 2.1
5. Accessing the GoAhead WebServer Home Page
6. The GoAhead WebCompiler
7. The WebServer Extensions
8. Known Issues in WebServer 2.1
9. Resolved Issues in WebServer 2.1
10. Resolved Issues from WebServer 2.0
11. Copyright Information

1. What's New in This Release?

WebServer 2.1 differs as follows from release 2.0:

• Windows 2000 Port
• eCos port
• Secure Socket Layer (SSL)
• Digest Access Authentication (DAA)
• User Management
• New APIs
• Standard CGI Implementation

Secure Socket Layer

WebServer 2.1 supports Secure Socket Layering (SSL), a protocol created by Netscape Communications Corporation for authentication and encryption over TCP/IP networks. SSL is, for the most part, invisible to the end user. The web browser may notify the user that they are about to enter a secure web page, and perhaps use a visual cue to indicate the duration that SSL is active. The HTTPS prefix on the URL (https://www.goahead.com) indicates that the SSL protocol will be used.

SSL uses two layers: the SSL Message Layer and the SSL Record Layer. The Message Layer constructs and sends user data, handshake messages, alert messages, and change cipher specification messages. Its primary task is to set up the mutual understanding required by both client and server for the SSL Record Layer, which is responsible for sending SSL data records.

Digest Access Authentication

WebServer 2.1 supports digest access authentication (DAA), which is an authentication scheme for HTTP that is more secure than the basic access authentication scheme. The primary advantage of DAA is that , unlike basic access authentication, passwords are never transmitted across the Internet in an unencrypted form.

The web browser presentation for DAA is essentially the same as for basic access authentication. The user typically is prompted for a user ID and password before being allowed access to a URL. In basic access, passwords are sent as clear text. In digest access, the user ID and password are encrypted using the RSA Data Security, Inc. MD5 Message-Digest Algorithm before being sent.

User Management

In password protected sites, multiple user IDs with multiple levels of security may be necessary. In WebServer 2.1, these include:

• User IDs
• User Groups
• URL Access Limits

A User ID contains these data elements:

1. User Name
2. User Password
3. User Group (determines access rights of user)
4. Protect
5. Enabled

User Groups contain these data elements:

1. Group Name (i.e., administrator, user, guest)
2. Privileges (none, read files, administrate users)
3. Protect
4. Enabled

URL Access Limits are used when certain directories or URL pages on the web site have exceptionally secure access limits. If a directory has an access limit associated with it, its contents default to the directories access limit.

URL Access Limits have the following data elements:

1. URL name (name of the web page or directory)
2. Access Method (one of NONE, FULL, BASIC, or DIGEST)
3. Encryption Required
4. User Group (currently limited to one user group for simplicity)

By default, there are no user functions that require administrator privilege; however, the following functions could be configured to require administrator privileges if that level of security is necessary in your application:

1. Add User
2. Delete User
3. Change Password
4. Change User Class
5. Add User Group
6. Delete User Group
7. Change Privileges
8. Add Access Limit
9. Delete Access Limit
10. Change Privilege
11. Change User Group

User Management Page Access

Whenever a browser requests a page, WebServer checks to see if there is an AccessLimit assigned to the requested page. Access Limits are stored in the umconfig.txt file located in the operating system directory where WebServer 2.1 was installed. If no user group is assigned to the access limit, then the default privilege takes effect with WebServer taking the following actions:

• If the default Privilege is "none", WebServer responds with the "File not Found" header.
• If the default Privilege is not "none", WebServer returns the page.

If a user group is assigned to the access limit, then WebServer:

1. sends an Authenticate response header (DAA if enabled),
2. waits for the receipt of Authorization Request Header from the client,
3. compares the user ID and password with those stored in the registered context, and
4. sends the page to the client if the user is authorized.

New User Management APIs

These APIs are new to WebServer 2.1:

Standard CGI Implementation

Note: CGI is not supported in Windows CE.

The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or Web servers. A plain HTML document retrieved by a Web daemon is a static text file that doesn't change. A CGI program, on the other hand, is executed in real-time and able to output dynamic content.

CGI scripts are written in any language that can read STDIN, write to STDOUT, and read environment variables. This means that virtually any programming language can be used, including C, Perl, or even shell scripting.

Note: this WebServer documentation does not provide instructions on how to write CGI scripts for processing Web forms; however, numerous books and Websites are readily available that do an excellent job in covering this basic information.

In WebServer 2.0, GoForms CGI processing was accomplished by instructing the webs module to treat all URLs beginning with "/goform" as GoForms. Using a similar mechanism, WebServer 2.1 has a new "handler" that is called when URL requests are received for URLs beginning with "/cgi-bin". CGI executable processes must be located in the WebServer's cgi-bin subdirectory. Separate processes will be created for each CGI request.

Environment Variables

Input to Standard CGIs is accomplished mainly through these environment variables:

SERVER_SOFTWARE
The name and version of the information server software answering the request (and running the gateway).
Format: name/version

SERVER_NAME
The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.

GATEWAY_INTERFACE
The revision of the CGI specification used by this server.
Format: CGI/revision

SERVER_PROTOCOL
The name and revision of the information protocol used by this request.
Format: protocol/revision

SERVER_PORT
The port number receiving the request.

REQUEST_METHOD
The method used to make the request. For HTTP, this is "GET", "HEAD", "POST", etc.

PATH_INFO
The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. The server decodes this information before it is passed to the CGI script.

PATH_TRANSLATED
The server provides a translated version of PATH_INFO, which completes a virtual-to-physical mapping of the path as required.

SCRIPT_NAME
A virtual path to the script being executed for self-referencing URLs.

QUERY_STRING
The information which follows the "?" in the URL which referenced this script. This is the query information. It is not decoded in any fashion. This variable is always set when there is query information, regardless of command line decoding.

REMOTE_HOST
The hostname making the request. If the server does not have this information, it will set REMOTE_ADDR and leave this unset.

REMOTE_ADDR
The IP address of the remote host making the request.

AUTH_TYPE
If the script is protected, this is the protocol-specific authentication method used to validate the user.

REMOTE_USER
If the script is protected, this is the authenticated username.

REMOTE_IDENT
This variable is set to the remote user name retrieved from the server. Use of this variable should be limited to logging only.

CONTENT_TYPE
For queries having attached information, such as HTTP POST and PUT, this identifies the content type of the data.

CONTENT_LENGTH
The length of the said content as given by the client.

HTTP_ACCEPT
The MIME types accepted by the client, as given by HTTP headers. Other protocols may need to receive this information from elsewhere. Each item in this list should be separated by commas as specified by HTTP.
Format: type/subtype, type/subtype.

HTTP_USER_AGENT
The browser being used by the client to send the request. General format: software/version library/version.

Standard CGI Implementation Data Structures

The data structures provided for GoForms function for standard CGI implementation.

2. Operating System Support

• Windows 2000
• Windows 98
• Windows 95
• Windows NT
• Windows CE
• VxWorks 5.3.1
• VxWorks 5.4
• LynxOS
• LINUX
• eCos
• QNX

3. Feature Support

* Need to follow special CGI instructions for VxWorks.
** Not tested by GoAhead.

4. Compiling and Running GoAhead WebServer 2.1

This release supports compiling and running the GoAhead WebServer under WindRiver VxWorks, Windows 95, 98, 2000, NT, and CE, LynxOS, LINUX, and eCos.

Before trying to build the GoAhead WebServer, ensure that you have the latest version from GoAhead by checking http://www.goahead.com/webserver. Each supported platform has an operating system subdirectory, which includes a Makefile for building, and a main program for invoking and initializing the GoAhead WebServer.

To build and run WebServer, change to the relevant operating system directory and use "make" or the instructions below to initiate the build. Some of the make or batch files may need to be modified for the configuration of your system or the target system. See Configuring the GoAhead WebServer below.

Installation Notes

User Management
The user management and access limit configuration is stored in a file called umconfig.txt. This file is created when the user management configuration is saved through the web interface. It is not provided in this distribution.

Standard CGI Implementation
The cgitest.c file is a sample CGI program that creates an HTML page that displays the CGI environment variables. This source code module is stand-alone, meaning that no other source files are required to generate an executable (with the exception of "stdio.h"). For VxWorks, a similar sample CGI program can be found in vxcgitst.c.

Operating Systems

For VxWorks:

  cd VXWORKS
  setpath 
  make

The above commands build for an x86 platform. If you are building for a Power PC 604 platform, use "ppcpath" and "make -f Makefile.ppc" instead. For other platforms, modify setpath.bat to set the PATH environment variable for your development environment and target device. Modify the compiler flags and options in Makefile to build for your specific target device.

Load webs.o onto the target system and use standard VxWorks procedures to load the program into memory and execute it (load module and task spawn).

To terminate WebServer so that it can be restarted without being reloaded, send a SIGTERM or SIGKILL signal to the WebServer task by using the "kill" API with signal numbers 15 or 9 respectively. Never use the taskDelete or td APIs when you plan on restarting WebServer.

For Windows NT:

 cd WIN
 nmake /f webs.mak
 webs

To stop WebServer, right click on the taskbar icon for the GoAhead WebServer and select "Close".

For Windows 95, 98, 2000:

 cd WIN
 setpath (NOTE: Users of Visual Studio 6.0 may 
          not need to use this command to set their environment path.) 
 nmake /f webs.mak
 webs

Modify setpath.bat to set PATH environment variable for your development environment.

To stop WebServer, right click on the taskbar icon for the GoAhead WebServer and select "Close".

If using Microsoft Visual Studio:

1. Open MS C++.
2. Open the provided workspace and select File|Open Workspace.
3. Navigate to the directory where you unzipped the WebServer files (i.e., E:\webserver\win\webs.dsw).
4. Click Open.
5. Select 'build webs.exe' from the Build Menu.
6. The following should appear in the bottom window:
   
   

   --------------------Configuration: webs - Win32
   Debug-------------------------------
   webs.exe - 0 errors(s), 0 warning(s)

7. From the Build Menu, select 'Execute webs.exe' . The 'GoAhead WebServer' button should now appear on the taskbar.
8. Follow the instructions provided in "Accessing the WebServer Home Page".
9. If SSL support is required, these additional steps are necessary:
   1. Add the webSSL.c file to the list of program files.
   2. Add WEBS.SSL_SUPPORT to the preprocessor definitions of the project settings.
   3. Add the include path of the RSA package to the additional include directories.
   4. Add the library path of the RSA package to the additional library paths.
   5. Add the RSA library file name to the library modules.

Note for users of Microsoft Visual C++:

If you see the following Setup Environment Variables message after installing Visual C++, use the Visual C++ instructions provided below BEFORE building and running GoAhead WebServer.

Setup Environment Variables message:

"For your convenience, the environment variables required to run build tools from a command prompt are saved in the VCVARS32.BAT file in your BIN directory."

Visual C++ Instructions:

1. Copy the VCVARS32.BAT file to your root directory (usually C:\).
2. Add the file's path name to your AUTOEXEC.BAT file.
3. Reboot your System.

For Windows CE:

Either of two different methods may be used to build the Windows CE WebServer:

Using build.bat:

1. In the WebServer build.bat file (CE/build.bat), ensure that the "set PATH" statement is correct, and that both the include and library files paths are correct.
2. Ensure that all compiler flags are set correctly.
   
   Note: You can get the correct flag settings for each processor from within Visual C++. Set your project to build against the target SDK. Access the compiler settings from the menu bar. Choose Project, Settings, and the C/C++ tab. The textbox labeled "Preprocessor definitions" lists the compiler settings.
3. Run the build.bat file.
4. Load webs.exe and your web pages on to your CE device using your normal procedures to transfer files to the device. The default location for the web pages is in the \web directory. This can be modified in main.c. Using precompiled and linked pages (see WEBS_PAGE_ROM and WebCompiler below) make it easy to load the application and its pages to the system in one step.

Using Microsoft's C++ Visual Studio:

1. In Microsoft Visual C++, Visual Studio, open the workspace webs.dsw in the CE subdirectory.
2. Set the include and library paths properly for your device.
   Be sure the symbolic constants CE, UEMF, WEBS, and UNICODE are defined.
3. Use the build facilities of Visual Studio to generate webs.exe.
4. Load webs.exe and your web pages on to your CE device using your normal procedures to transfer files to the device. The default location for the web pages is in the \web directory. This can be modified in main.c. Using precompiled and linked pages (see WEBS_PAGE_ROM and WebCompiler below) make it easy to load the application and its pages to the system in one step.

Note: By default, user management and digest access are not added when WebServer compiles. If these features are desired, set the proper flags in the build.bat file.

For LINUX:

cd LINUX
make
su;# As super user
./webs

For LYNX:

cd LYNX
make
su;# As super user
./webs

For eCos:

cd ECOS
make
su;# As super user
webs

For QNX:

CD QNX4
make
su ;# As super user
webs

5. Accessing the WebServer Home Page (Windows)

1. Launch your browser on the same system as WebServer.

2. Launch GoAhead WebServer using web.exe (located in the folder for your OS, e.g., WIN).
Note: WebServer icon should now appear in the task menu.

3. In the browser's Address field enter "http://[YOURHOSTNAME]" or "http://[YOURIPADDRESS]
Note: defaults to port 80. Otherwise use "http://xxxxxxx:yy" where "yy" is the correct port number.

To determine your system's host name or IP address, at the command prompt type either "hostname" <enter> or "ipconfig" <enter> (for Win95, instead use "winipcfg" to see the IP address).

4. The server's default home page is home.asp.

Configuring the GoAhead WebServer

You can customize the configuration of the GoAhead WebServer by changing the compiler defines in the per-operating system Makefile. The following defines are relevant:

WEBS_PAGE_ROM
Define this to retrieve pages from ROM vs file system.

WEBS_LOG_SUPPORT
Define this to enable loging of web accesses to a file.

WEBS_KEEP_ALIVE_SUPPORT
Define this to enable HTTP/1.0 keep alive support.
(untested in WeServer 2.1)

WEBS_IF_MODIFIED_SUPPORT
Define this to enable if-modified-since support.
(untested in WeServer 2.1)

B_STATS
Define this to enable memory and stack statistics.

DIGEST_ACCESS_SUPPORT
Define this to enable Digest Access Authentication.

USER_MANAGEMENT_SUPPORT
Define this to enable the use and configure-ability of User Management.

WEBS_SSL_SUPPORT
Define this to enable SSL support.

In all cases, the symbolic constants UEMF and WEBS must be defined in the command line arguments to the compiler. The symbolic constant UNICODE needs to be defined for Windows CE compilations or any other builds that need to use unicoded character strings. Please see the WebServer online documentation for more detailed configuration instructions.

You should also customize the per-operating system main.c startup program. For example, the Windows main program is under WIN/main.c. This main program defines the HTTP port, password, web page directory, default error handling, and default trace message handling, among other things. It is expected that you will use this program as the basis for integrating the source into your real-time operating environment. For VXWORKS, you may need to change the CC, LD definitions in VXWORKS/Makefile if you are using a different BSP. Also you will need to change the variable ROOT_DIR in main.c to reflect the name of the root directory for your file system. When editing source files, set your tab stop setting to 4.

6. GoAhead WebCompiler

The WebCompiler creates ROMable C source code for a set of Web pages. The WebCompiler takes as input a list of files and a prefix to strip off the web page filenames. It writes to its standard output a C source file representing the web pages. For example:

webcomp /mydir file.list >webrom.c 

The first parameter is the prefix to remove from all the files in the file.list. The standard Makefiles are already setup to compile webrom.c. Please see Configuring GoAhead WebServer above for instructions on enabling ROM access.

7. GoAhead WebServer Extensions

If you create some great extensions and applications based upon the GoAhead WebServer and want to make them freely available to the WebServer community, you can add them to an archive of user contributions that is maintained on the GoAhead web site. Please submit postings to webservercode@goahead.com for posting to the archive.

8. Known Issues in WebServer 2.1

Refer to GoAhead's on-line support for WebServer at http://goahead.custhelp.com/cgi-bin/goahead for current WebServer issues.

9. Resolved Issues in WebServer 2.1

10. Resolved Issues from WebServer 2.0

11. Copyright Information

Trademarks

GoAhead and GoAhead WebServer are registered trademarks of GoAhead Software. All other brand or product names are the trademarks or registered trademarks of their respective holders.

Copyright

Copyright © 1999, 2000 GoAhead Software, Inc. All rights reserved.

Product and technical information in this document is subject to change without notice and does not represent a commitment on the part of GoAhead Software, Inc.

Copy Restrictions

The software described in this document may be used and copied only in accordance with the terms of the accompanying license agreement.

GoAhead Software, Inc.
10900 NE 8th Street
Suite 750
Bellevue, WA 98004
+1 ( 425) 453-1900
www.goahead.com
info@goahead.com