Constructing CGI Environment

1.0.0 Directories in /usr/web
2.0.0 /lib/namespace.httpd
3.0.0 $web
4.0.0 $web/etc/handler
5.0.0 $web/etc/namespace_80
6.0.0 CGI and security

2003/01/03

If you want to use CGI, then you should consider the environment to support CGI. Because Pegasus can configure and must explicitly configure namespace that is required for CGI.

Many names will be required. For example, a CGI program may be waiting a message that will never come. Then pegasus must kill the process. To enable it, /proc must be provided.

Directories in `/usr/web`

You will find the following directories in example/usr/web of Pegasus distribution.

	d-rwxrwxr-x M 8 arisawa arisawa	bin/386
	d-rwxrwxr-x M 8 arisawa arisawa	bin/rc
	d-rwxrwxr-x M 8 arisawa arisawa	dev
	d-rwxrwxr-x M 8 arisawa arisawa	doc
	d-rwxrwxr-x M 8 arisawa arisawa	env
	d-rwxrwxr-x M 8 arisawa arisawa	etc
	d-rwxrwxr-x M 8 arisawa arisawa	lib
	d-rwxrwxr-x M 8 arisawa arisawa	mnt
	d-rwxrwxr-x M 8 arisawa arisawa	proc
	d-rwxrwxr-x M 8 arisawa arisawa	rc/lib
	d-rwxrwxr-x M 8 arisawa arisawa	sys/log
	d-rwxrwxr-x M 8 arisawa arisawa	sys/lib
	d-rwxrwxr-x M 8 arisawa arisawa	sys/man
	d-rwxrwxr-x M 8 arisawa arisawa	tmp
	--r-------- M 8 arisawa arisawa	unreadable

Don't give permission for writing to user none or web. The last unreadable in the list is used to detect whether the server is running in allow mode or not. (If the server is running in allow mode, CGI service will be stopped.)
These directories is empty except bin/386 and bin/rc. My preference is to place CGI in /usr/web/bin. /lib/namespace.httpd below stands on my preference.

You can copy

	example/usr/web

to /usr/web as it is. My cpdir will help you.

	cpdir -mv example/usr/web /usr/web

`/lib/namespace.httpd`

Service space is constructed using /usr/web as it's base. Entity must be given using bind command in

	/lib/namespace.httpd

You will find the example in Pegasus distribution:

	example/lib/namespace.httpd

The content is (stripping comments)

bind -a /usr/web/bin/$cputype /bin
bind -a /usr/web/bin/rc /bin
bind /sys/log/http /usr/web/sys/log/http
bind /sys/lib /usr/web/sys/lib
bind /sys/man /usr/web/sys/man
bind /lib /usr/web/lib
bind /bin /usr/web/bin
bind /rc/lib /usr/web/rc/lib
bind -c #e /usr/web/env
bind #c /usr/web/dev
bind /proc /usr/web/proc

Not all will be required. And note that the line:

	bind /sys/lib /usr/web/sys/lib

will make all files under /sys/lib accessible via CGI. Especially you should note that some secret files such as /sys/lib/ssh and /sys/lib/tls may be there.

CGI environment configured in /lib/namespace.httpd will be inherited to all hosts and users. Therefore you should be careful enough.

`$web`

Web root is denoted by $web in the followin explanation. $web for user alice is (if not specified in /sys/lib/httpd.rewrite):

	/usr/alice/web

On the other hand, $web for real host and virtual hosts are specified in /sys/lib/httpd.rewrite. For example $web for real host will be /usr/bob/www if we specify

	/	*/usr/bob/www

in /sys/lib/httpd.rewrite.

Each $web have directories:

	doc
	etc
	bin/386
	bin/rc

where

doc is a directory to place web document. Home page will be doc/index.html
etc is a directory to place access control files such as passwd, allow, handler, rewrite and namespace_80
bin/386 and bin/rc are directories to place executable files for CGI. Pegasus will bind them to /bin in append mode.

`$web/etc/handler`

$web/etc/handler is a file to define execution handler and are managed by the person who owns web document. The file is

	/etc/handler

in service space.
The role of this file is to pass the request from client to the specified program.
Typical contents of handler is:

# suffix             mimetype  unused   execpath arg ...
/netlib/*/index.html text/html 	0 	/bin/ftp2html
*.http                  -       0       $target
*.html               text/html	1       $target
*.dx_html            text/html  0       /bin/dx $target

This is what I am using. The first line is a comment. The first field is path pattern of requested path and $target that may appear after fourth field is the path name. A line that contains *.html defines files so called CGI. This line says that if a file with extension .html and with executable bit for others is requested then execute the file. The output format is text/html and ramfs is provided. This means the file extension of CGI is determined not by Pegasus but by user.
Table of $web/etc/handler determines action against requested path. Requested file need not be present. See execution handler for more more information.

`$web/etc/namespace_80`

Those who manage web pages can configure his namespace. The configured namespace cannot go beyond namespace that is configured in /lib/namespace.httpd as long as -m option is not given to httpd.
The configuration file is

	$web/etc/namespace_80

in service space. If you are bob, the real place will be

	/usr/bob/www/etc/namespace_80

Note:

The number 80 in $web/etc/namespace_80 is a port number. If you are using other port, say 443, then use namespace_443.
Pegasus is already in service space. Therefore the path in this file must be a path from $web.
Not all configuration is allowed for security reason. Only bind command is allowed unless -m option is given in running httpd. A bind that brings system file to document space is not allowed.
If you want to hide a directory, then create empty directory (/doc/nil for example) and bind it.
bind /doc/nil /doc/private

CGI and security

Pegasus allows all users to have CGI environment if host administrator configure /lib/namespace.httpd for CGI. Pegasus thinks that CGI should not be served only to administrator. Therefore this feature should be in mined in configuring /lib/namespace.httpd.
Pegasus is designed in considering that it should be attack proof against malicious system user. However Pegasus has not been examined in the system with malicious users.

If httpd is invoked by listen, then httpd runs as user none.
If you want httpd to write a file, it is safe to set access mode

	alrw-rw-rw-		# if reading is required
	alrw--w--w-		# if you don't want the file to be read by others

It is most important not to be lost or modified by others.

If you want not to be accessed by other system users, run httpd in server mode.

Constructing CGI Environment

Directories in /usr/web

/lib/namespace.httpd

$web