docs.roxen.comView this page in a printer friendly mode
DocsRoxenWebServer 3.4System Developer ManualIntroduction
Copyright  2006, Roxen Internet Software
Suggestions, comments & compliments

The Inner Workings of Roxen


Some important terms to grasp to fully understand the manual.

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. Roxen modules may be implemented in pike or Java.

Pike module

A Pike module is, unlike Roxen modules, not something seen by the common roxen user or administrator. A pike module extends the Pike language environment, providing the programmer alone with some features, abstraction or similar, such as the SQL and Image modules.

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 refers, unlike the discussed above, 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.


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.