Integrating GoAhead WebServer & eCos

Security is always a concern, especially since SNMP does not offer much security with all transactions being in plain text. Web servers used for web-based management offer security such as encrypted password authentication for users trying to access the server.

Devices using web-based management can also leverage existing RTOS features that are standard in most operating systems, such as networking stacks and filesystems. This eliminates the need to incorporate additional functionality to support embedded web servers, taking up valuable system resources.

On the downside, a disadvantage to web-based management is the handling of dynamic data—once a page is served from the embedded web server to the browser, the content is static and does not change, unless the user requests the data again. However, any number of solutions eliminate this problem without requiring user intervention. One solution is to use the HTTP REFRESH tag, which forces the browser to rerequest the data at a specified interval. Another is to use Java and JavaScript to run applets in the browser for a continuous data stream.

GoAhead WebServer

The GoAhead WebServer from GoAhead Software (http://www.goahead.com/) is a portable, open-source, small-footprint web server specifically designed for use in embedded systems. Unlike most web servers, The GoAhead WebServer is designed to meet embedded constraints—small memory footprint, configurable security model, dynamic web-page content support, support for devices that do not have a filesystem, and integration of the source code into custom devices.

The GoAhead WebServer supports a range of Internet technologies and protocols, including Active Server Pages (ASP), in-process Common Gateway Interface (CGI), embedded JavaScript, HTTP 1.0 with persistent connections found in HTTP 1.1, 65 connections per second, Secure Sockets Layer (SSL) 3.0, Digest Access Authentication (DAA), user management via login access, and storage of web pages in ROM.

The GoAhead WebServer is written in C and has been ported to operating systems such as Windows 95/98/NT/CE, Linux, eCos, Embedded Linux, ChorusOS, pSOS, MicroC/OS, VxWorks, QNX, Lynx, IRIX, HP-UX, RTEMS, and Novell Netware. GoAhead WebServer requires a TCP/IP stack, event timer, and approximately 60 KB of RAM.

The GoAhead WebServer source code can be downloaded free of charge in exchange for any enhancements to the source-code base. The license for using the GoAhead WebServer is based on three basic requirements:

• GoAhead must be notified prior to shipping the product using the WebServer.
• The GoAhead mark must be displayed on the initial page.

• GoAhead can identify companies using the WebServer for marketing efforts.

The entire GoAhead WebServer license can be found on the GoAhead web site.

The eCos RTOS

In this article, I integrate the GoAhead WebServer into the eCos RTOS. Although this discussion uses eCos, the techniques can be applied to any of the RTOSs supported by the GoAhead WebServer.

eCos, short for "Embedded Configurable Operating System," is an open- source, royalty-free RTOS. (For more information on eCos, see "eCos: An Operating System for Embedded Systems," by Gary Thomas, DDJ, January 2000.) eCos is ideal for embedded applications and is supported by the GNU open-source development tools, which include the GNU compiler (GCC) and the GNU debugger (gdb). Because eCos is open source, you can download and test eCos for free (see http://sources.redhat.com/ecos/).

eCos is designed for use in real-time applications and provides features such as preemptable tasks with multiple priority levels, low-latency interrupt handling, multiple scheduling policies, and multiple synchronization methods. Its core functionality also includes exception handling, timers, counters, device drivers, memory management, and ISO C and math libraries. A complete development and debug environment is provided—GNU-based compilers, assemblers, linkers, debuggers, and simulators. Configuration and build tools are available to run on either Linux or Windows host environments.

eCos supports a number of 16-, 32-, and 64-bit processor architectures including ARM, Intel x86, Matsushita AM3x, MIPS, NEC V8xx, PowerPC, SPARC, and SuperH. Here, I use Windows NT as the host development platform, eCos as the target RTOS, and the GNU development tools built for the PowerPC. Again, the steps can be applied using any host development platform and any supported OS.

Integrating the GoAhead WebServer

The first step in installing the GoAhead WebServer on the eCos platform is to download the GoAhead WebServer source code. The source code is contained in either a Windows zip file (816 KB), tar format (1.96 MB), or compressed tar format (640 KB).

The source files are extracted under the root directory ws211-011120. Table 1 lists the other directories extracted under the root directory. After extracting the Windows zip file, the source code uses approximately 1.8 MB of disk space.

The eCos directory includes the files main.c and makefile. main.c contains the code that gets implemented along with your application. makefile includes the build information for generating an archive or library file from the GoAhead WebServer source code.

GoAhead provides source code for webcomp, a program that lets web pages be built into the WebServer image. The webcomp.c program (located in the root directory) takes the files under the web subdirectory and compiles them into a format for storage in webrom.c, also located in the root directory.

For eCos, the webcomp program must be built using Windows or Linux native tools. The complete development project space for the Windows host platform is provided in the win subdirectory.

After building webcomp, webcomp.exe is generated. You want to copy this file into the eCos subdirectory. The webcomp program is called from the makefile to generate the webrom.c file with the appropriate web pages.

The DOS find command is used in Listing One to generate a list of files under the web subdirectory. This list is stored in the file web_files. Then, webcomp is called to generate the file webrom.c, which contains the compiled web pages. You can then compile webrom.c into the GoAhead WebServer archive image.

The makefiles for the supported operating systems compile the GoAhead WebServer code into a library or archive file. The next step is to verify that the makefile is configured properly.

The makefile in the eCos subdirectory contains definitions for building the WebServer for two specific development boards—the Cirrus Logic EDB72xxx and the Motorola PowerPC MBX860 (see Listing Two). For other development boards, you need to make the appropriate changes for the COMMAND_PREFIX and CFLAG definitions. You also need to ensure the PKG_INSTALL_DIR points to the location of the working directory for the built eCos image. (A good source to understand the changes that need to be made to the makefile is included with the eCos examples.) You also want to comment out the line to build webcomp in the makefile since you have built webcomp independently; see Listing Three.

Next, set the compiler definitions for the build. Since you are storing the web pages in ROM, you want to ensure the compiler definitions are set appropriately. In the makefile, include the option DWEBS_PAGE_ROM in the CFLAGS definition. The default configuration of the GoAhead WebServer uses a filesystem for web pages. Table 2 lists other possible compiler definitions.

At this point, you are ready to build the GoAhead WebServer using the GNU development tools and make utility, which is run from the ecos subdirectory. After the build completes, the GoAhead WebServer archive file libwebs.a, which is located in the ecos subdirectory, needs to be linked into the eCos image file.

To start building the eCos operating system and including the GoAhead WebServer archive image, you first need to increase the memory pool size for the malloc function. This is done by increasing the CYGNUM_MEMALLOC_FALLBACK_MALLOC_POOL_SIZE configuration option to 1638400. You can then build the eCos operating-system image. The eCos operating system is built into an archive library file that is included in the link with the user application.

You must then edit the eCos linker file to include the GoAhead WebServer image in the link process. The linker script file, target.ld, is located under the install/lib subdirectory within the eCos build working directory structure work/mbx. To include the GoAhead WebServer archive file, add libwebs.a to the GROUP command. Listing Four is a portion of the target.ld linker script file detailing this modification. Also copy the WebServer archive file to the install/lib subdirectory. Detailed information about building the eCos operating system can be found on the eCos web site.

Next, modify the application source code to run GoAhead WebServer. Each operating system supported by the GoAhead WebServer includes the file main.c, which gives example code on how to initialize and run the WebServer. Listing Five shows the task setup to initialize and run GoAhead WebServer. The first function, bopen, initializes the memory allocator with 60 KB. Approximately 8 KB is allocated for each page request. This value should be set based on the number of concurrent page requests expected for the system. If more memory is needed to handle additional page requests, this value can easily be increased based on the target resources available.

Next, initWebs is called to initialize the GoAhead WebServer. This function initializes the target's network by calling the eCos function init_all_network_interfaces. Calling socketOpen initializes the socket subsystem. The default web page and password are also set in initWebs. The WebServer is opened on port 80 (the default) using websOpenServer.

Finally, you enter into an endless loop to process the client requests. socketReady returns True when there is a socket with an event ready to process. Passing in -1 causes the function to go through all available sockets. The function socketSelect blocks until an event occurs on a socket, the parameter -1 causes the function to go through all sockets, and 2000 is the timeout in milliseconds. socketProcess services the events on each socket. The function emfSchedProcess manages the processing of the tasks queued by the WebServer. The last three function calls—websCloseServer, socketClose, and bclose—clean up the WebServer resources if an error occurs and you exit the endless loop. In normal operation, this should not occur.

There are two functions to remove—send and recv, both located at the end of the file main.c. These functions are placeholders for the actual routines, which are provided by the network stack code included with the eCos operating system.

Accessing the GoAhead WebServer

Finally, you can run the application. After downloading and starting the application, launch a browser to access the GoAhead WebServer. This assumes that there is some network connection between the target hardware and the host system, which runs the browser.

To access the GoAhead WebServer homepage, enter "http://<Target_IP_Address>" in the browser address field. This launches home.asp, the default homepage. It may be helpful to use either the Linux or Windows (depending on your host development platform) source code to build the GoAhead WebServer for your host platform. This lets you test the GoAhead WebServer on your host before integrating it into your RTOS. Host development platforms typically have a wider range of debugging tools available that let you step through and understand the GoAhead WebServer code before moving to your embedded platform.

Additional Modifications

There are a few modifications you can make to customize the GoAhead WebServer for your specific application:

• Port number. The default port number for the WebServer is set to 80. To change the default port number, modify the line port = 80; located in the file main.c. If this default is changed, when accessing the home page as just described, you will need to use "http://xxx.xxx.xxx .xxx:yy", where yy is the port number.
• Retries. By default, the GoAhead WebServer retries five times to find an alternative port to use if the default port is not available. This default can be modified in main.c by changing the line retries = 5;.

• Password. To password-protect server accesses, the default password needs to be entered in main.c. The line to modify is *password = T("");, where the new password is entered between the quotes "". The default password is blank, which allows access to the server without a password.

• Default homepage. Eventually, you will need to modify the web pages under the web subdirectory. The current web pages offer a great starting point for new web- page designs. If the name of the default homepage is changed, the code must also be changed to reflect the new homepage. This is located in main.c on the line websRedirect(wp, T("home.asp"));, where the new homepage is entered in place of home.asp.

Other Concerns

Other issues you may need to address involve dynamic page refreshing and storage of cookie files. There have been some recent posts to the GoAhead WebServer newsgroup (news://news.goahead .com/goahead.public.webserver) that offer suggestions and code samples that detail different methods for handling these issues.

It may also be necessary to dynamically change the content of the web pages stored on the target hardware. If this is the case, a filesystem needs to be implemented as well as a method for updating the contents of the web pages.

DDJ

Listing One

# Build a set of ROMable pages
webrom.c: 
    find ../web -name "*.*" >web_files
    ./webcomp ../web web_files >webrom.c

Back to Article

Listing Two

# For Cirrus Logic EDB72xx board
#PKG_INSTALL_DIR := /work/net_test/install
#COMMAND_PREFIX := arm-elf-
#CFLAGS := -mcpu=arm7tdmi -D__EDB7209 -D__EDB7212 -g -Wall -O2

# For Motorola PowerPC MBX/860
PKG_INSTALL_DIR := /work/mbx/install
COMMAND_PREFIX := powerpc-eabi-
CFLAGS := -mcpu=860 -msoft-float -g -Wall -O2

Back to Article

Listing Three

#webcomp:
# cc -o webcomp -O2 -DWEBS -DUEMF -DOS="Linux" -DLINUX -I.. ../webcomp.c

Back to Article

Listing Four

STARTUP(vectors.o)
ENTRY(__exception_reset)
INPUT(extras.o)
GROUP(libtarget.a libwebs.a libgcc.a)

Back to Article

Listing Five

void WebserverTask( cyg_addrword_t data )
{
   /* Initialize the memory allocator. */
   bopen(NULL, (60 * 1024), B_USE_MALLOC);

   /* Initialize the web server */
   if (initWebs() < 0)
   {
      diag_printf( "Error: webserverInitialize Failed!!!\n" );
      return;
   }

   /* Basic event loop. */
   while (!finished)
   {
      if (socketReady(-1) || socketSelect(-1, 2000))
      {
         socketProcess(-1);
      }

      emfSchedProcess();
   }

   /* Close the socket module, report memory leaks, and close the memory        allocator. */
   websCloseServer();
   socketClose();
   bclose();
   return;
}

Back to Article