Top: PTypes demo program -- wshare

Overview

Wshare is a simple multithreaded web server (HTTP daemon) that uses almost all functional parts of the library and serves as an example of using PTypes. Wshare supports protocol versions up to HTTP/1.1. It provides simple means of sharing files over the web, but it lacks server-side scripting and authentication functionality.

The program is covered by the same license as PTypes. The authors can not be responsible for any data loss or accidental disclosure of confidential information caused by this software. It is provided `as is' with the hope that it can be useful both as a library demo program and a simple web server.

The sources are in ./wshare. On UNIX, this application is built along with the library and is copied to ./bin. For MSVC, a separate project is provided as a part of the PTypes workspace. For BCC on Windows, the makefile is wshare/wshare.mak.

Wshare does not require any special installation or configuration procedures and can be easily run from the command line with at least one parameter: the directory you wish to share over the web. Note that wshare does not understand .htaccess or any other configuration files in your directories, so the web site you might previously have will run with wshare's default configuration and access rights.

Wshare is scalable: you can write your own handlers for new HTTP methods, virtual paths and for specific file extensions. Currently custom modules can be incorporated into wshare only at compile-time. Please, see wshare/modules.h and wshare/request.h for details. Also take a look at the sample compile-time module wshare/mod_about.cxx.

Please, run the program to see the summary of the command-line options.

usage: wshare [options] document-root

  -D              daemonize, UNIX only
  -d              allow directory indexes
  -g group        group ID to run as, UNIX only
  -n num          maximum number of simultaneous connections (default: 30)
  -o file-name    write HTTP access log to file-name
  -p port-num     port number to listen to
  -u user         user ID to run as, UNIX only
  -x              always show directory indexes (ignore default index files)

Running on UNIX

By default the daemon is trying to bind to port 80, which is a privileged port on UNIX. You will have to either run it as root, or to specify a port number higher than 1024 with the option -p port-number, e.g. -p 8080.

Wshare uses UNIX's syslog to log error messages. The HTTP access log goes to stderr, which can be overridden with -o logfile.

Wshare can also daemonize itself, i.e. detach from the console and remain active after the user logs out. Use option -D to daemonize the program. After that, the only way to stop the server is to send a SIGKILL signal, i.e. determine the process ID with ps and then invoke kill -KILL PID. On some systems you will need to use ps with the option that specifies your user ID.

For better security, wshare can downgrade process privileges to the user/group specified through -u user and -g group command-line options. This is done after binding to the socket and opening the log file. If -g is omitted and only -u is specified, wshare downgrades the process to the primary group of that user. For example, if you specify -u nobody, the group will be automatically assigned to a group nobody.

Running on Windows

On Windows wshare runs as a simple console application. All you can do with wshare on Windows is to specify a different port to bind to with option -p port-number and to redirect the HTTP access log to some file with option -o logfile. Redirecting the access log to a file instead of writing it to the console window can speed up the server.

Common features

By default wshare does not generate directory indexes (analogue of `Option Indexes' in Apache's configuration), which means the directory must have a default index file named as either of: index.html, Index.html or default.htm. Directory indexes can be allowed by specifying option -d. In this case, if the directory does not have any of the default index files listed above, wshare will generate a page with the list of files the directory contains.

If you don't want default index files at all, use option -x in the command line: the server will then show the directory indexes, like if you specified an empty "DirectoryIndex" directive with Apache.

You can limit the number of simultaneous connections with option -n num, which is 30 by default. When the number of connections reaches num/2 , the server stops supporting persistent connections. When it reaches num, the server sends "503 Service unavailable" to the client. And finally, when the number of connection requests reaches num * 2, wshare simply aborts the connection by closing the socket.

You can get the current status of the server by requesting http://localhost/.wstat in your browser. Wshare responds to this request only if the client is on the same host as the server, i.e. localhost or 127.0.0.1.

Some other features are hardcoded into wshare and can be changed only by recompiling it. The list of default index files can be found in wshare/config.cxx, and the file extension-to-MIME translation table is in wshare/mimetable.cxx. An awk script wshare/mimetable.awk is provided to translate an apache-style mime.conf file into C++ code that can be linked with wshare.

Examples (UNIX)

The simplest usage:

wshare ./

Quickly share your files through port 8080 and ignore any index.html files in the directories:

wshare -x -p 8080 ~/mydocs

Run a real server for real users (must be root on UNIX):

wshare -D -n 100 -u nobody -o /var/log/wshare-access.log /usr/local/www

BE CAREFUL and double check the directory you are opening to the world.