Table of Contents

Name

logiweb - start logiweb server

Synopsis

logiweb -- [chain=chain] [conf=filename] [demonize=Boolean] [help=Boolean] [httphost=internet-address] [localconf=filename] [log=filename] [logaccess=Boolean] [logdelta=duration] [loginit=Boolean] [logresponse=Boolean] [logschedule=Boolean] [option=Boolean] [pid=filename] [pntdist=duration] [pntfew=cardinal] [pntmany=cardinal] [pntmax=cardinal] [pntrisk=decadic] [pnttries=cardinal] [pntwait=duration] [relayurl=url] [reqbaud=decadic] [reqbyte=cardinal] [reqfate=cardnal-list] [reqheader=cardinal] [reqid=cardinal-list] [reqminfifo=decadic] [reqsource=cardinal-list] [reqtrust=cardinal-list] [reqwait=duration] [roots=association-list] [starters=server-address-list] [tcpchain=chain] [tcphost=internet-address] [tcpip=ip] [tcpport=port-number] [timeexp=exponent] [trustref=Boolean] [udpchain=chain] [udphost=internet-address] [udpip=ip] [udpport=port-number] [uninstall=Boolean] [user=username] [userconf=filename] [varconf=string] [varhome=string] [varhttp=string] [varinit=string] [varlgwping=string] [varlgwrelay=string] [varlib=string] [varlogiweb=string] [varman=string] [varpyk=string] [varrelay=string] [varscript=string] [version=Boolean]

Description

The Logiweb server translates Logiweb references into Uniform Resource Locators (URLs). It is designed to be run as a standalone demon process but may also be run as an ordinary user command in the foreground. The Logiweb server is typically started by an init-script.

When the Logiweb server starts, it scans the local file system for Logiweb pages, starting at the locations indicated by the roots parameter and stores the relationship between urls and Logiweb references in the 'state' of the server. After that, the Logiweb server cooperates with all other Logiweb servers in the world on indexing all Logiweb pages in the world.

Pyk is controlled by options. Pyk reads options from the following locations listed in order of priority: the commmand line, environment variables, a local configuration file, a user configuration file, a site configuration file, and compiled in defaults. Furthermore, if [post=CGI-string] is given then Pyk also reads options from the given CGI-string. To see the values of all options from all sources, including compiled in options, issue the command 'logiweb -option'.

The -- argument can be omitted if no options are given. Otherwise, -- must be present and must preceede all options.

On the command line, options can be given on the form 'option=value', '--option value' or '-option value'. Hence, 'udp=65535', '--udp 65535', and '-udp 65535' all set the 'udp' option to '65535'.

Options can be set to the empty string by the forms 'option=', '--nooption', and '-nooption'. As an example, 'logaccess=', '--nologaccess', and '-nologaccess' all set the 'logaccess' option to the empty string. The 'logaccess' option is a 'Boolean', and the empty string happens to be one of several strings that represent falsehood. For a description of Booleans and of other types see logiweb.conf(5) .

Options can be set to 'yes' by the forms 'option=yes', '--option', and '-option'. As an example, 'logaccess=yes', '--logaccess', and '-logaccess' (with no value after '--logaccess' and '-logaccess') all set the 'logaccess' option to 'yes'. 'yes' happens to be one of several strings that represent truth.

The Logiweb server listens on the udp port of the host machine given by the udp parameter. The server advertises itself as listening at the address and port number indicated by the server and udp parameters. The server parameter can be a domain name or a dotted ip but must be an address which allows computers on the Internet to contact the host machine of the Logiweb server.

The Logiweb server also listens on the tcp port given by the tcp parameter. At that port the server responds with human readable text in HTML format. When used in connection with the lgwrelay CGI program this allows a user to play with the Logiweb server.

Options

The Logiweb server is controlled by options. The server reads options from the following locations listed in order of priority: the command line, environment variables, a local configuration file, a user configuration file, a site configuration file, and compiled in defaults. To see the values of all options from all sources, including compiled in options, issue the command 'logiweb --option'.

conf=filename
Name of main configuration file, e.g. /etc/logiweb/logiweb.conf. See also the FILES section below.

demonize=Boolean
If true: run server as demon. If false: run server in foreground.

fifo...=size
Number of items that can wait in various fifo queues. fifotcp0 is the queue limit for incomming tcp connections (the 'backlog' parameter of listen(2) ). fifotcp1 is the queue limit for tcp requests waiting for processing. fifotcp2 is the queue limit for tcp requests waiting for rejection. fifoudp1 is the queue limit for udp requests waiting for processing. fifoudp2 is the queue limit for udp requests waiting for rejection.

help=Boolean
When true: Print short help message and exit.

httphost=internet-address
Internet address of http server to be used for fetching Logiweb pages. The address may be given as a domain name or a dotted ip. The value of httphost is the default for the tcphost and udphost parameters.

localconf=filename
Location of local configuration file. The local configuration file is relative to the current value of $PWD. See also the FILES section below.

log=dirname
Directory of log file. If dirname is non-empty then output from the Logiweb server is sent to a log file created in the given directory. The name of the log file is constructed from the current date and the current time of the day and looks like this: GRD-2006-03-21-UTC-08-05-41-374485. If the dirname is the empty string then output is sent to standard output. The log option has effect only if demonize=true; if demonize=false then output is always sent to standard output. If the user option is given and if the server is invoked by root, then the server opens the log file after the server drops its privileges so the log file directory must be writable by the user given by the user option.

logaccess=Boolean
If true: Log accesses to the Logiweb server.

logdelta=duration
Max number of seconds log output may be accumulated. If e.g. logaccess is true and if the Logiweb server is accesses several times from the same client within duration seconds, then the Logiweb server merely prints a single line which indicates how many times the server was accessed by the given client. As an example, 'logdelta=2minutes' sets logdelta to 180. See logiweb.conf(5) for the syntax of a duration.

loginit=Boolean
If true: Log all files visited during the initial scan of the local file system which leads to the initial state of the server.

logresponse=Boolean
If true:

Log responses from Logiweb server

logschedule=Boolean
If true: Log each time a top level process is invoked (produces a lot of output)

option=Boolean
When true: Do not start the server but instead print all options from all sources (i.e. command line options, environment variables, options from configuration files, and compiled in options).

pid=filename
Name of file to which the server writes its process identifier (pid). If the filename is the empty string then the server does not write its process identifier. Furthermore, the server only writes its process identifier if demonize=true. If the user option is given and if the server is invoked by root, then the server opens the pid file before the server drops its privileges so the pid file is written by root.

pntdist=duration
Time between two sibling maintenance scans through the state.

pntfew=cardinal
When a node has less than pntfew siblings, the server starts searching for new ones.

pntmany=cardinal
When a node has more than pntmany siblings, the server kicks out one sibling with probability pntrisk to keep the sibling graph fluid.

pntmax=cardinal
The max number of siblings a node can register.

pntrisk=decadic
When a node has more than pntmany siblings, the server kicks out one sibling with probability pntrisk to keep the sibling graph fluid.

pnttries=cardinal
Number of times the sibling maintenance asks the same question to a foreign server before it gives up.

pntwait=duration
Amount of time the server waits for a response to a query.

relayurl=url
Uniform resource locator of a CGI-program which provides a user interface to the Logiweb server.

reqbaud=decadic
Upper bound on outgoing udp messages measured in baud (bits per second).

reqbyte=card
Number of bits used for transmitting one 8 bit byte. Typically 10.

reqfate=cardlist
Share of outgoing bandwidth between processed and rejected requests. As an example, reqfate=,1,2 uses two third of the bandwidth for rejected requests.

reqheader=card
Number of header bytes expected to be added to each message. Typically 28 for udp/ip.

reqid=cardlist
Share of outgoing bandwidth between ping, get, and put requests (c.f. reqfate above).

reqminfifo=decadic
Messages of length at most reqminfifo are guaranteed to be transmittable. Longer messages may be discarded.

reqsource=cardlist
Share of outgoing bandwidth between protocol processing and upkeep processing.

reqtrust=cardlist
Share of outgoing bandwidth between trust 1, trust 2, and trust 3 requests.

reqwait=duration
Duration outgoing responses are allowed to wait in the operating system output buffers.

roots=association-list
The roots parameter indicates how external uniform resource locators (urls) map to local file names. The first character after 'roots=' is used as a list separator so that e.g.


roots=#http://my.domain/b/#/a/#http://another.domain/c/d/#/c/d/

indicates that http://my.domain/b/ maps to /a/ and that http://another.domain/c/d/ maps to /c/d/.

The roots option is typically given in a configuration file. In configuration files, the first non-space character after 'roots=' is used as list separator and spaces are allowed before and after any separation character. The server only indexes Logiweb pages reachable from roots. See also the SECURITY CONSIDERATIONS section below.

In configuration files,

the separator may be the newline character so that the association list

above may also be written


roots=
- http://my.domain/b/
- /a/
- http://another.domain/c/d/
- /c/d/

starters=server-address-list
Server addresses for connecting to Logiweb.

tcpchain=chain
Controls which machines can access the tcp port of the server. Only the machine running the Logiweb relay is supposed to access the tcp port. Connections that go via a Logiweb relay have two associated ip addresses: the ip of the caller of the relay and the ip of the machine running the relay. The ip of the caller is checked against udpchain whereas the ip of the machine running the relay is checked against tcpchain. See the udpchain option for further information. See logiweb.conf(5) for the format of chains.

tcphost=internet-address
Local address of server. The lgwrelay CGI program should send requests to the server using the tcp protocol, the tcphost address, and the tcpport port number. The tcphost name needs not be one accessible from the outside of firewalls, masquerading and so on. If lgwrelay runs on the same machine as the Logiweb server, then one may set the tcphost to 127.0.0.1. If empty (the default), the value for httphost is used for tcphost.

tcpip=ip
The Logiweb server listens on the interface with the given ip. The compiled in default is 0.0.0.0 (INADDR_ANY, c.f. ip(7) ) which instructs the server to listen on all interfaces. Only set this parameter on machines with more than one interface for which the server should only listen on one of the interfaces.

tcpport=port-number
The Logiweb server listens on the given tcp port number. The tcp port is supposed to be used by the lgwrelay CGI program. See also the 'tcphost=' option.

timeexp=exponent
The Logiweb server is multi-tasking and maintains a queue of scheduled processes. The granularity of that queue is 10^(-timeexp) seconds which indicates the shortest waiting time a server process can request.

trustref=Boolean
When false (the default): check the Ripemd code of Logiweb references against the Ripemd code of the associated contents. May be set to true during debugging to speed up the initial file scan.

udpchain=chain
Controls which machines can access the udp port of the server. A 'chain' defines a function from ip numbers to 'trust' levels. For the format of chains see logiweb.conf(5) . Machines with a trust level of zero are rejected. Machines with a trust level above zero are accepted. The server processes 'put' requests from machines with trust level 3 immediately and unconditionally. For machines with trust level 2, the server checks the correctness of a 'put' immediately. For machines with a trust level of 1 (the normal), the server places 'put' requests in a queue and verify them at the servers pace. Use trust level 2 for local, machines that run the pyk compiler. Trust level 3 is intended for distribution of the work of a Logiweb server over several computers and should not be used at the time of writing.

udphost=internet-address
Internet address of server. The address may be given as a domain name or a dotted ip. The Logiweb server uses this address when it refers to itself and when it advertises its services to other Logiweb servers. The udphost name must be a name under which the Logiweb server can be accessed from both outside and inside any firewalls and masquerading. The address is not necessarily identical to the host name. As an example, the domain name of host mymachine.my.domain could be www.my.domain when seen from the outside. See also the "udpport=" option. If empty (the default), the value for httphost is used for udphost.

udpip=ip
Analogous to tcpip=ip.

udpport=port-number
The Logiweb server listens on the given udp port number. The udp port is supposed to be used by Logiweb clients such as pyk, lgwping, and other Logiweb servers. See logiweb(7) for the protocol used for communication via the udp port. See also the 'udphost=' option.

uninstall=Boolean
When yes: Uninstall Logiweb installation using the values of log, varconf, varhome, varhttp, varinit, varlgwping, varlgwrelay, varlib, varlogiweb, varpyk, and varrelay which are typically defined in the site configuration file. In typical installations where Logiweb is installed by root, the uninstall also has to be done by root. Uninstallation is done stepwise with the option to skip each step.

user=username
Shortly after the server starts, it drops it privileges and sets its user and group id to the given user (equivalent to 'su username'). If the username is the empty string or if demonize=false then the Logiweb server does not change its user and group id. Changing user and group id is only useful and only possible if the Logiweb server is run by root. See also the log and pid options.

userconf=filename
Location of the user configuration file. The user configuration file is relative to the current value of $HOME. See also the FILES section below.

varconf=string
Compiled in default for the site configuration file. Only used during installation. Only has effect if set in logiweb.conf in the root of the source tree.

varhome=string
The directory which contains e.g. Logiweb web help pages.

varhttp=string
The location of the Logiweb Apache configuration file.

varinit=string
The location of the Logiweb server init script.

varlgwping=string
The location of the lgwping command.

varlgwrelay=string
The location of the lgwrelay command.

varlib=string
The location of the logiweb.so shared library.

varlogiweb=string
The location of logiweb command.

varman=string
The location of Logiweb man pages.

varpyk=string
The location of the pyk command.

varrelay=string
The location of the Logiweb relay CGI-script.

varscript=string
A ScriptAlias command which ends up in the Logiweb Apache configuration file.

version=Boolean
When true: Print version number and exit.

Files

The server reads up to three configuration files, namely a 'site', a 'user', and a 'local' configuration file. The server shares configuration files with the pyk compiler (pyk(1) ). The site configuration file is typically located in /etc/logiweb/logiweb.conf, the user configuration file is typically located in $HOME/.logiweb/logiweb.conf, and the local configuration file is typically located in $PWD/logiweb.conf.

The location of the site configuration file has a compiled in default but may be overridden by the conf command line argument or the LOGIWEB_CONF environment variable. Issue the command 'logiweb --option' to see the values of compiled in defaults.

The location of the user configuration file is typically set in the site configuration file but may be overridden by the userconf command line argument or the LOGIWEB_USERCONF environment variable. The location of the user configuration file is typically set to .logiweb/logiweb.conf which indicates that the user configuration file is the .logiweb/logiweb.conf file in the users home catalog. The server issues no warnings if the user configuration file does not exist so it is safe to set userconf to .logiweb/logiweb.conf in the site configuration file even if some users do not have a user configuration file.

The server reads no user configuration file if userconf is set to the empty string. The empty string happens to be the compiled in default for the userconf option.

The location of the local configuration file is typically set in the user configuration file but may be overridden by the localconf command line argument or the LOGIWEB_LOCALCONF environment variable. The location of the local configuration file is typically set to logiweb.conf which indicates that the local configuration file is ./logiweb.conf. The local configuration file allows to specify particular options to be in effect when the user cd's to a particular directory.

Environment

For each long option there is an associated environment variable. The name of the environment variable equals the name of the option prefixed by 'LOGIWEB_'. As an example, instead of writing 'userconf=xyzzy' on the command line or in a configuration file, one can set the environment variable LOGIWEB_USERCONF to xyzzy. Option names are case insensitive whereas option values are case sensitive. So one may instead set the environment variable Logiweb_UserConf to xyzzy and one may write UserConf=xyzzy on the command line or in a configuration file.

Security Considerations

Two issues should concern users of the server:

(1) The server is alpha test software implemented in CLISP and it listens on a udp-port accessible from the Internet. Hence, a cracker who manages to explore some security hole in the server may get access to CLISP which in turn can execute any program.

(2) The primary function of the server is to provide information to the outside world about the contents of the local file system.

To minimize the risks associated to (1) above, do as follows:

(1.1) Create a user named 'logiweb' and put 'user=logiweb' in the site configuration file (c.f. 'user' in the OPTIONS section). Use the 'logiweb' user for no other purpose. The server has root privileges when it is started from an init script, but if 'user=logiweb' is given then the server drops its root privileges as soon as it has read all options and written its pid file (c.f. 'pid' in the OPTIONS section) and before it scans the file system and before it starts listening to the Internet. Hence, with 'user=logiweb', the server has dropped its privileges before a cracker has a chance of attacking.

(1.2) Put 'userconf=' and 'localconf=' in the site configuration file. Those lines set userconf and localconf to the empty string so that the server reads no user and local configuration files. If these options are non-empty then, in all likelihood, the server will not find any user configuration file in /root and no local configuration file in /, but disabling the user and local configuration files limits control over the server to the command line arguments, the environment variables, the site configuration file, and the compiled in defaults. Do a 'logiweb --option' as root to see what options are in effect (c.f. 'option' in the OPTIONS section).

The risks associated to (2) are automatically minimized by the server as follows:

(2.1) The server only gives information about files reachable from 'roots' (c.f. 'roots' in the OPTIONS section). Beware, however, that the server follows symbolic links.

(2.2) The server only gives information about files that end with '.lgw'.

(2.3) The server only gives information about files that contain a correct 160 bit Logiweb checksum.

At present, the only tool that generates files with a correct Logiweb checksum is the pyk compiler. The pyk compiler can generate published as well as unpublished Logiweb pages, and the checksum is only placed in pages that the user explicitly asks to be published. In effect, the server only gives information about published Logiweb pages. That should not a concern since published Logiweb pages are supposed to be public. Users should be aware, however, that if they place a published Logiweb page within reach from 'roots' then crackers outside will be aware of the url of the published page and, hence, be aware of all directories above that url.

Author

Klaus Grue, http://logiweb.eu/

See Also

logiweb(7) , logiweb.conf(5) , lgwping(1) , lgwrelay(1) , pyk(1) , pyk(5)

The server is typically invoked from an init script. Concerning init scrips, see chkconfig(8) , init(8)


Table of Contents