NAME
rtwebserver - Embedded web-server for Antelope real-time systems
SYNOPSIS
rtwebserver [-v] [-p pfname] [-P port] [-s sitename] [pfplainref value [pfplainref value] ... ]
DESCRIPTION
The
rtwebserver application runs an embedded web-server inside an Antelope real-time system
(usually managed by
rtexec(1)).
The
rtwebserver.pf parameter-file describes all contents
of the web-site. Each element of the served
Uniform Resource Locator (URL) hierarchy is mapped
by the
rtwebserver.pf parameter-file to the content to deliver. That content may be an external
file, a sub-section of the
rtwebserver.pf parameter file, or the output of a python
rpy
script. The python
rpy script format is documented in the man-page
rtwebserver_rpy(3y).
The
rtwebserver command-line may contain additional key-value pairs after all option arguments are given. These key-value pairs
are inserted into the
rtwebserver.pf parameter-file before that parameter-file is interpreted. These keys may then be used
as parameter-file plain references (see
pf(5) for an explanation of plain references). Most commonly this may be used to specify additional
orbservers on the
rtwebserver command-line, with which the configured web resources may interact.
OPTIONS
-
-v
Issue verbose messages
-
-p pfname
Override the default parameter-file of rtwebserver.pf
-
-P port
Override the port specified in the parameter file
-
-s sitename
This specifies the top-level parameter-file array containing specifications for the
web-site in rtwebserver.pf. If not specified, the default is site.
FILES
The
rtwebserver program serves static and dynamic web files from locations specified in the
rtwebserver parameter file, as described below.
ENVIRONMENT
The
rtwebserver program assumes the ANTELOPE environment variable is properly set.
PARAMETER FILE
Parameters
-
port
This parameter sets the Trasmission Control Protocol (TCP) port on which the
rtwebserver program listens for connections. The port number
may be overridden with the command-line -P option.
-
trackingdb
If this parameter is not blank, requests served are entered into the named tracking database
-
valid_ip_addresses
This table lists IP addresses and their netmasks that may connect to the rtwebserver instance.
For further information, see the man page legit_ip(3).
-
reject_ip_addresses
This table lists IP addresses that are disallowed from connecting to the rtwebserver instance.
For further information, see the man page legit_ip(3).
-
profile
If this boolean parameter is present and set to a true value, rtwebserver conducts some simple profiling
of the time taken to render web requests.
-
<site>
A site array describes all the configuration and structural details for a single web-site.
The name site is the default; other names may be used for the top-level
array describing a web-site, with the -s command-line option to rtwebserver
used to create the described web-site.
-
<site>{pages}
The pages sub-array is a hierarchical nested structure that assigns each path element of the
Uniform Resource Locator (URL) to its own resource. The keys of the pages array are URL elements. The values
of the pages array are resources to serve when the URL element is requested. Simple values (URL leaves, i.e.
terminal elements of the URL string) may be given by a string specification to be described below. Compound values
(URL branches, i.e. intermediate pathname elements in the URL) may be given by nested parameter-file arrays. For each
simple value (URL leaf), the string specifying the resource to serve consists of a resource type, followed by a
semicolon, followed by a string giving the particulars for that resource.
Several page types are allowed, depending on what the value of each entry starts with. These are (note that when invoking these,
the colon character must be explicitly included):
file: with this page type, rtwebserver
assumes that what follows is the pathname of a file on the filesystem, which it serves directly to the requesting web
client. If the pathname is a directory, rtwebserver will serve all files in the directory.
pf: with this page type, rtwebserver assumes that what follows is the name of a key into the site
parameter-file array, containing a string or string-literal value with the contents to serve to the web client.
rpy: with this page type, rtwebserver assumes that what follows is the pathname of a python rpy script. The
rpy python script must contain a variable named resource which holds an instance of a
twisted.web.resource.Resource object able to render the URL in question, as documented further in the man-page
rtwebserver_rpy(3y).
rtcache: with this page type, rtwebserver assumes that what follows is the name of a key into the site,
containing a parameter-file sub-array to be given as initialization to an object of type RtcacheResource(3y) which manages
the page. For further detail see the man page for RtcacheResource(3y).
revproxy: with this page type, rtwebserver assumes that what follows is the address of a web-address
to reverse-proxy to the given resource name (i.e. making the named web-site appear as if it were a sub-page of the
web-site being served by rtwebserver).
Resource strings of type pf or file may be followed by whitespace, then a text string identifying the MIME
type for the resource. If no MIME type is given, text/plain is assumed.
If a resource is followed by the word index (separated by whitespace characters), the given resource is also
served as the root page for the given URL directory. If this index keyword is used, it must be the last
entity on the resource line. (e.g. if the MIME type is specified for an index page of type pf or
type file, the index keyword must come after the MIME type specification).
-
<site>{siteconfig}
The siteconfig sub-array provides parameter-file values to be given to any dynamic rpy scripts supporting the
website. The rpy scripts may access these parameters by importing the Python dictionary rtserver.config.sitedict,
which will have a dictionary entry named siteconfig containing these entries from rtwebserver.pf.
-
<site>{pythonpaths}
The pythonpaths table lists system paths which should be appended to the Python path (using the Python command sys.path.append())
prior to building the web-site.
-
<site>{phrases}
This sub-array is optional and could actually have any name that doesn't already conflict with a previous name in the
<site> array. This sub-array may be used to keep named snippets of HTML content that can be referred to by various rpy
files used to build the web-site.
Sample parameter file
port 8008
trackingdb rtsys/rtwebtrack
valid_ip_addresses &Tbl{
127.0.0.1 255.255.255.255
10.10.10.0 255.255.255.0
}
reject_ip_addresses &Tbl{
}
site &Arr{
pythonpaths &Tbl{
}
siteconfig &Arr{
databases &Arr{
antelope_demo /opt/antelope/data/db/demo/demo
}
}
pages &Arr{
index pf:demoindex text/html index
css &Arr{
style.css pf:stylesheet text/css
}
}
demoindex &Literal{
<html>
<head>
<link rel="stylesheet" href="/css/style.css" type="text/css" media="screen" />
</head>
<body>
<h1>It works!</h1>
</body>
</html>
}
stylesheet &Literal{
h1 {
color: #000 ;
font-family: arial, helvetica, geneva, sans-serif ;
font-size: 1.3em ;
margin: 2px ;
margin-top: 20px ;
font-variant: small-caps ;
letter-spacing: 1px ;
text-align: center;
}
}
}
EXAMPLE
% rtwebserver -v
SEE ALSO
rtwebserver_rpy(3y), rtexec(1), pf(5), legit_ip(3), RtcacheResource(3y), rtcache(1)
BUGS AND CAVEATS
If a hierarchy describing a web-page itself contains both a resource named
pages and a resource named
siteconfig, the
rtwebserver program will get very confused.
The
rtwebserver program must be restarted after changes to its parameter file.
As always under Unix, access to privileged ports require root execution privileges.
The pathnames for files listed in the parameter file are relative to the current working directory in which
rtwebserver is running, which may not be the same as the directory in which the parameter-file resides.
The
revproxy capability currently works only with top-level pages.
AUTHOR
Kent Lindquist