Introduction

Prerequisits

The user is assumed to be familiar with the Java programming language, HTML, and recognize basic Roxen WebServer features, such as the administration interface, RXML, etc. The user also needs to be familiar with the operating system that Roxen WebServer is running on, to be able to install files in the Roxen WebServer filesystem.

Terminology

Roxen module

A component of a virtual server that fills some specific purpose, such as RXML parsing, providing a filesystem or similar. A Roxen module is a piece of code interfacing to the roxen module API, extending the server's features.

virtual filesystem

The virtual filesystem is the entire path namespace of your server, as seen in the URL's path segment. In a basic Roxen setup with just a common filesystem module mounted at / (the filesystem root), all files in the virtual filesystem map to this one filesystem, as is typically the case with other webservers where you have a single document root.

Roxen, however, has a slightly different approach to filesystems, that shares many characteristics with Unix filesystems. Several filesystems may be mounted on top of each other at different, or indeed the same, mountpoints in the virtual namespace of the server. If one filesystem is mounted at /, another at /I/live/ and a third at /I/live/here/, a request for the file /I/live/here/happily.html may deliver a file residing in either filesystem. Which one is decided first by the longest matching mountpoint, secondly the filesystem modules' priorities (as set by the administrator) and finally by which filesystem actually has a file to deliver.

Similarly, even entire other virtual servers may be mounted somewhere within your server's namespace, effectively blacking it out to your server. This also means that such a server's virtual filesystem does not map one-to-one to the path namespace as seen in the URL from the browser's point of view. What to the browser looks like a request of the file /my/secret/garden.jpg could quite possibly be the file /secret/garden.jpg from a virtual server mounted at /my/.

Due to the dynamic nature of Roxen, a file in the virtual filesystem need not exist as an actual file on disk (as it would in a real filesystem), but might be the result of some on-the-fly file-generation activity in a Roxen module of some sort. Indeed, even the error page received when roxen did not find a file, exists in the virtual filesystem (wherever anything else does not).

To find out what actually happens when requesting a given URL from your server; where the file has its origin, what modules touch it and so on, the "Resolve path..." option in the Maintenance menu under the Tasks tab in the administration interface does wonders.

real filesystem

The real filesystem, unlike the discussed above, refers to the filesystems provided by the operating system, where actual files reside, typically on a hard disk, network filesystem or similar. As the name hints, files on disk might be considered just the slightest bit more real than the figments of imagination that may be harvested from the virtual filesystem.

mountpoint

The term refers to where location modules are found in the virtual filesystem. A virtual file's path is considered to be below a certain mountpoint when the path begins with the the entire length of the mountpoint; for instance, /demo/4 is below both mountpoints / and /demo/ but not below /demo/module/ or /hello/world/. A mount point need not necessarily end in a slash, but it is a rather common convention.

virtual server

Back in the old days, a web server was one website serving files through one port at one host. Things change, and the world grows more complex. The widespread trend of abstracting a concept and tagging it "virtual" applies to virtual servers, as much as it does to the virtual filesystem; a virtual server in roxen is a collection of roxen modules working together under a common roof.

The criterion of being accessable on a single host:port combination does not apply in Roxen, nor the fact that the server uses the entire namespace of that domain. By using several server URL:s for a virtual server, it can respond to requests for several domains, on several ports possibly using several different protocols (eg HTTP, HTTPS and FTP, all to the same virtual filesystem). Or, just as possible, if given the sole server URL http://my.domain/just/here/, it will not see requests for any other part of the namespace of some other server handling http://my.domain/ than those below /just/here/. Equally possible, although not the most common of configurations, is not to mount any port at all.

Roxen WebServer start-up process

Roxen WebServer is a collection of scripts and modules. The start script sets up some essential environment variables to keep dynamic libraries and various other external stuff happy. After a rapid progression of start script argument parsing and setting up paths, it rotates the logs and launches the first Pike script: server/base_server/roxenloader.pike.

Next in turn, the Roxen loader bootstraps the server, making sure some dependencies are met, setting up some constants, and installs Roxen WebServer's own master program, server/etc/roxen_master.pike. This program is responsible for, among other things, the dumping and reloading of programs.

Then, the very core of Roxen WebServer, server/base_server/roxen.pike gets loaded. The configuration of all virtual servers are loaded next, their respective ports get registered and unless the flag --no-delayed-load was passed to the start script, not much more happens next until the first request arrives to a server. This means, of course, this code in a module of yours will not run until a server using the module is needed.

At this stage, the server process is up and will listen to incoming requests on all registered ports. When a request to an uninitialized server is received, Roxen will initialize that server, loading and strapping all of its modules. The request is then sent through the common processing sequence. Your applications will not be affected by the delayed loading. To the application, whether it be a module, a script, an rxml page or a servlet, the delayed loading is transparent and does not interfere with the programming environment.

For the rest of the lifespan of the Roxen process, it will go about its business listening and responding to requests, until terminated with a signal to the process, the start script or by the restart/shutdown administrator action. When the Roxen process receives a SIGHUP signal, it reloads its configuration files. A SIGINT/SIGTERM signal takes down the process and makes the start script spawn off a new one to replace the old one (sending a SIGINT/SIGTERM to the start script shuts down the server without respawning another one).