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.
- 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
- 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
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
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
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.
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:
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).