Slinger Webserver

Topics of this chapter include:

• What is Slinger?
• Running Slinger
• Configuration
  • Security precautions
  • Configuration examples
• How dynamic HTML works
  • SSI tokens
  • SSI commands
• Ways to achieve dynamic HTML
  • The data server

What is Slinger?

Welcome to Slinger, a WWW server for resource-constrained environments. Slinger is compliant with the CGI 1.1 and HTTP 1.1 standards, and provides support for dynamic HTML via Server Side Includes (SSI).

Running Slinger

When you install the Slinger software, the install program puts the Slinger executables in the /usr/ucb/slinger directory. To run Slinger, just type:

slinger &

You need to run Slinger as root since Slinger communicates on a privileged port by default. As soon as Slinger has attached to the HTTP port, it drops itself down to user -2 (setuid(-2)).

For information about Slinger options, see the slinger utility page.

Configuration

Much of Slinger's configuration is done with environment variables. Slinger provides Server Side Include (SSI) commands to support dynamic HTML. For example, Slinger uses the PATH and CMD_INT environment variables to provide information to the SSI command, exec.

See the "Security precautions" section for configuration issues.

PATH

Configure dynamic HTML. It contains the pathname of the command interpreter and shell executable command used in the SSI command, exec. For more information, see the exec cmd description in the slinger utility page.

CMD_INT

Configure dynamic HTML. It contains the pathname or name of the shell program used to interpret the string passed to the SSI command, exec (e.g. /bin/sh). For more information, see the exec cmd description in the slinger utility page.

HTTPD_ROOT_DIR

Configure data files. It contains the name of the directory where Slinger looks for data files. Default is /usr/local/httpd.

HTTPD_ROOT_DOC

Configure the root document. It contains the name of the root document (e.g. index.html). When a web client requests the root document, HTTPD_ROOT_DOC is appended to HTTPD_ROOT_DIR to build the full pathname of the root document. Default is index.html.

HTTPD_SCRIPTALIAS

Configure CGI scripts. It contains the directory name where Slinger looks for the CGI executables. Note that if you define HTTPD_SCRIPTALIAS, anybody can run scripts or processes that reside in this directory on your machine. Not defining HTTPD_SCRIPTALIAS turns CGI off, causing all CGI requests to fail.

Don't use /bin or /usr/bin as your CGI directory.

Security precautions

• When you choose the directory for your data files, we recommend that:
  • You don't place any sensitive files in the document directory.
  • You isolate your data files directory from the system files directory. For example, /usr/www is much safer than the root directory /. The root directory / opens up your whole system to be served by Slinger.
• If you configure Slinger to support CGI:
  • Place the CGI scripts in a directory isolated from your normal system binaries. Don't use /bin or /usr/bin as your CGI directory.
  • Avoid setting your CGI script file permissions to "set user ID when executing" when the file is owned by a privileged user (e.g. root).
  • Keep your CGI scripts and documents in separate directories. This will prevent people from accessing your scripts.
• Don't expose your machine to undue risk. Make sure that:
  • The permissions on all the files and directories are read-only.
  • No files are owned by userid (-2) because Slinger runs at userid (-2) and you don't want Slinger to own the files.

  These precautions will prevent somebody from giving your machine a new password file or tampering with your web pages.

Configuration examples

The right way

We recommend that you put your documents and scripts in separate directories. In this example, the documents are in the /usr/webdoc directory, the root document is foo.html, and the CGI scripts are in /usr/web/cgi.

export HTTPD_ROOT_DIR=/usr/webdoc
export HTTPD_ROOT_DOC=foo.html
export HTTPD_SCRIPTALIAS=/usr/web/cgi
slinger &

The "wrong" way

In this example, anyone can download the scripts because the documents and scripts are in the same directory.

export HTTPD_ROOT_DIR=/usr/web
export HTTPD_ROOT_DOC=foo.html
export HTTPD_SCRIPTALIAS=/usr/web
slinger &

How dynamic HTML works

Slinger supports Server Side Include (SSI) commands to provide dynamic HTML. For example, Slinger uses the PATH and CMD_INT environment variables to provide information to the SSI command, exec. Using dynamic HTML, clients can offer interactive realtime features on their web pages.

Clients code dynamic HTML by placing SSI tokens in the HTML code of their web pages. The SSI token contains an SSI command that is handled by Slinger. While transmitting the HTML code, Slinger replaces a token with HTML data based on the tag contained in the SSI token.

The HTML file must have the file extension .shtml

SSI tokens

The syntax of an SSI token is as follows:

<!--#tag [[variable set[="value"]] ...] -->

where:

<!--

Starting delimiter of an SGML/HTML comment.

#

Tells Slinger the comment contains a command.

tag

SSI command.

variable set

One or more arguments to the SSI command.

value

One or more values for the variable set.

-->

Ending delimiter of SGML/HTML comment.

There must be a space before the ending comment delimiter.

There's no limit to the token size (other than memory).

SSI commands

Here's a brief summary of the SSI commands Slinger provides:

break

Terminate an HTML document at any point.

config

Set certain HTML output options.

echo

Insert data from certain variables onto an HTML page.

exec

Spawn an external program and insert its output onto an HTML page.

if

Conditionally execute SSI operations and conditionally print HTML text.

goto

Jump to a labeled token (without printing skipped text or applying skipped tokens).

include

Insert the contents of a file onto an HTML page.

label

Jump to a label using the goto command.

qnxvar

Get data or change data on the data server process. For more information, see the data server utility.

Detailed information about each token is available in the slinger utility page.

Ways to achieve dynamic HTML

HTML can be dynamically generated in order to support changing systems. The main components in such a system are:

• the changing element
• external applications that activate and read change
• the data server process
• Slinger
• the remote clients.

There are three ways to provide dynamic HTML:

1. CGI interface. This is described in many commonly available books.
2. Write an I/O manager to provide changing HTML each time the prefix is opened/read.
3. Use Server Side Includes with the data server. The rest of this section describes this method.

The data server

The data server process stores global data. External applications can modify or read this global state through the use of the data server API. Slinger can modify or read the global state via the qnxvar SSI command.

Here's a conceptual view of a device monitored and controlled by both an external application and a remote client of Slinger:

Using the data server.

To use dynamic HTML:

1. Use the SSI tokens to manipulate the HTML page.
2. Use the qnxvar tokens to query and manipulate the global data.
3. Write an application to manipulate the global state using the data server library functions. See the examples in the Writing Data Server Applications chapter in the TCP/IP Programmer's Guide.