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 being built along with the library and is being 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, nonexistent (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.

Note: there is a known problem on Linux with GCC 2.96: wshare may crash under heavy load if compiled with this version of GCC. It is recommended to use GCC 2.95 instead.

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

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.

Note, that many Unix systems `lock' the port for some time even after the server exits. Normally this lasts few minutes, so if you repeatedly run wshare on the same port, most likely you will get an error message saying that the address is in use.

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 "504 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 -o /var/log/wshare-access.log /usr/local/www

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