Configuration reference

Yxorp reads its configuration from an XML file at startup, and sets up it's internal representation of the configuration statements. While Yxorp is running, a new configuration file can be inserted into the running configuration; this may extend the configuration, but also replace parts of the original configuration. It is also possible to read the actual configuration from the running daemon.

Overview of the configuration file

The configuration statements are grouped; each group deals with a set of configuration items. These groups are:

configlistener; this group deals with the TCP interface that is used to read or update the configuration in an active yxorp daemon;
log; this group contains the statements that configure logging;
listener; this group, that may occur more than once in a configuration, controls the proxy processing and sets the TCP ports that the yxorp daemon will listen to;
rule; may occur multiple times and contains the rule programming language statements;
threads; controls the settings that the yxorp daemon will use for worker threads;
security; controls security settings;
server; controls which (virtual or real) servers yxorp can send requests to;
virtualserver; controls the groupings of servers that are used as loadbalancing or failover pools;
realserver; controls the settings of real servers that are mapped from a server definition or a virtualserver pool;
globalconfiguration; controls which settings the yxorp daemon uses for things like timers, retry limits to connect to servers, headers to process, etc;
basicauth; sets which userid/password combinations are recognized for local basic authentication processing;
debug; controls filtering of debug output messages. If yxorp is built with debugging support enabled, these filters may be used to selectively show some message types.

Syntax of the configuration file

The configuration file should be formatted as follows:

<?xml version="1.0"?>
<yxorpconfig>
<log>
... logging settings
</log>
<configlistener>
... config listener settings
</configlistener>
<rule id=”name” type=”request”>
... rule code
</rule
</yxorpconfig>

Configuration file contents

The configuration file must start as follows:

<?xml version="1.0"?>
<yxorpconfig>

and end as follows:

</yxorpconfig>

The other contents of the configuration file depend on what Yxorp functions you want to use. These are described in the next sections.

Configuring listeners

Listeners are the end point for sessions between a client and Yxorp. For Yxorp to do any useful work, at least one listener must be created.

There are two types of listener, corresponding to the two types of proxy: dissecting and tunneling. The dissecting proxy completely takes a request apart, may run all kinds of scripts on each part of the request, and then reassembles it and forwards it to a server. In contrast, a tunnel proxy does not do any processing on a request, but just forwards it as-is to a server. Which type of proxy is chosen depends on the definition in the listener; a listener may invoke either type of proxy, but not both.

A listener is created by setting a <listener> tag in the configuration. The <listener> tag takes the following attributes for a dissecting proxy:

Attribute	Format
id	string	Must be set on each listener, and sets the listener identifier. The id must be unique. It is used in logging and tracking, and in the reconfiguration process.
type	number	4 means IPv4, 6 means IPv6. Default is IPv4.
mode	string	“tunnel” creates a tunnel proxy; “dissect” creates a dissecting proxy. “dissect” is default.
port	number	TCP port number the listener will bind to.
ipaddress	ipaddress	IP address the listener will bind to. If type=4, then a normal dotted IP address must be set; if type=6, an IPv6 address notation must be set. The IPv4 address 0.0.0.0 has a special meaning and will bind to all local addresses of the system.
rule	string	The name of the rule that will be executed for requests.
resprule	string	The name of the rule that will be executed for responses. This setting can be changed by using rule functions in the request rule.
rejrule	string	The name of the rule that will be executed if a request is rejected. This setting can be changed by using rule functions.
inboundentityrule	string	The name of the rule that is run after an inbound entity (ie. client-to-server) has been received. Setting this causes inbound entities to be buffered, and the request to be processed store-and-forward. This setting can be changed by using rule functions.
outboundentityrule	string	The name of the rule that is run after an outbound entity (ie. server-to-client) has been received. Setting this causes outbound entities to be buffered, and the request to be processed store-and-forward. This setting can be changed by using rule functions.
cachearea	string	The name of the cache area that is applicable for requests coming in on this listener. This setting can be changed by using rule functions.
ssl	string	“yes” to enable SSL, “no” to disable. If Yxorp is built without SSL support, presence of this attribute will cause an error message.
certfile	string	Name of a file containing the certificate to be used. The certificate must be in PEM format. The file must also contain the private key associated with the certificate, or the pvtkeyfile attribute must be used.
pvtkeyfile	string	Name of a file containing the private key associated with the certificate set by the certfile attribute. If the pvtkeyfile attribute is not used, Yxorp expects to find the private key in the file set by the certfile tag.
certpasswd	string	Optional password to decrypt the certificate with
cafile	string	Name of a file containing the certificate authority information that is used to verify certificates. The file must be in PEM format.
requestclientcertificate	number	If nonzero, Yxorp will request a client to send a client certificate during the setup phase of a SSL connection between a client and this listener.
verifyclientcertificate	number	If nonzero, Yxorp will verify client certificates it receives from sessions from clients to this listener. If the certificates do not verify, the session setup will be aborted.

For a tunneling proxy, the following attributes are applicable:

Attribute	Format
id	string	Must be set on each listener, and sets the listener identifier. The id must be unique. It is used in logging and tracking, and in the reconfiguration process.
type	number	4 means IPv4, 6 means IPv6. Default is IPv4.
mode	string	“tunnel” creates a tunnel proxy; “dissect” creates a dissecting proxy. “dissect” is default.
port	number	TCP port number the listener will bind to.
ipaddress	ipaddress	IP address the listener will bind to. If type=4, then a normal dotted IP address must be set; if type=6, an IPv6 address notation must be set. The IPv4 address 0.0.0.0 has a special meaning and will bind to all local addresses of the system.
tunneldest	ipaddress	If mode=”tunnel”, IPv4 address of the tunnel destination host; if mode=”dissect”, this attribute has no meaning.
tunnelport	ipaddress	If mode=”tunnel”, TCP port number on the tunnel destination host; if mode=”dissect”, this attribute has no meaning.

Reconfiguring

All attributes on a listener can be reconfigured on-line. If the socket attributes (port and ipaddress) are changed, Yxorp will close the current socket and bind to a new socket with the new settings. If the new socket is in use on the operating system level, this might take an extended period of time; if sessions or programs are active on the new socket, the socket may not become available at all, causing Yxorp to keep retrying to bind to the socket.

In case a certificate file modification time stamp has changed, the certificate file will be reloaded.

Example

The following example creates a dissect listener for IPv4 on the HTTP port, that will bind to the localhost interface (and thus only accept requests sent to the localhost address):

<listener 
	id=”www” 
	type=”4” 
	mode=”dissect”
	ipaddress=”127.0.0.1” 
	port=”80” 
	rule=”wwwreq” 
	resprule=”wwwresp” 
	rejrule=”wwwrej”
/>

The next example will create a tunnel listener using IPv6 on the HTTPS port, and connect to an IPv4 server on address 1.2.3.4:

<listener 
	id=”www” 
	type=”6” 
	mode=”tunnel”
	ipaddress=”fe80::210:1100:0123:4567” 
	port=”443” 
	tunneldest=”1.2.3.4” 
	tunnelport=”443” 
/>

Configuring TLS extension Server Name Indication

When built with OpenSSL version 0.9.8g or later, Yxorp can support the TLS extension Server Name Indication. This means that one of several server certificates may be presented to the client, according to the server name that the client includes in the TLS handshake (assuming, of course, that the client also supports SNI).

The certificate, CA file etc. configured on the <listener> tag is the default certificate in the SNI context; that is, the certificate on the <listener> tag is presented to the client if no server name is included in the TLS handshake. If the server name is present, this name is used to map into a list of <certlist> items that can be configured inside the <listener> tag. If a match is found, the certificate defined by the <certlist> is used for the TLS/SSL handshake; if no match is found, the default defined on the <listener> tag is used.

The <certlist> tag takes the following arguments:

Attribute	Format
hostname	string	The host name, or server name in the TLS context, that will be used to map to this certificate list entry.
certfile	string	Name of a file containing the certificate to be used. The certificate must be in PEM format. The file must also contain the private key associated with the certificate, or the pvtkeyfile attribute must be used.
pvtkeyfile	string	Name of a file containing the private key associated with the certificate set by the certfile attribute. If the pvtkeyfile attribute is not used, Yxorp expects to find the private key in the file set by the certfile tag.
certpasswd	string	Optional password to decrypt the certificate with
cafile	string	Name of a file containing the certificate authority information that is used to verify certificates. The file must be in PEM format.

Reconfiguring

All attributes on a <certlist> item can be reconfigured. In case a certificate file modification time stamp has changed, the certificate file will be reloaded.

Example

The following example shows how <certlist> items are configured:

<listener 
	id=”tlslistener” 
	ipaddress=”127.0.0.1” 
	port=”443” 
	certfile=”test.pem” 
>
	<certlist hostname=”www.example.com” certfile=”examplecert.pem” />
	<certlist hostname=”secure.example.com” certfile=”secureexamplecert.pem” />
</listener>

Configuring servers

Yxorp uses the servers listed in the configuration as an abstraction layer for servers. A server can either directly map to a real server, or map to a virtual server for load balancing. If no servers are available, a special rule type called the 'sorry rule' is executed.

A server is identified by the name taken from the Host: header, and thus, normally the same as the domain part of the URL that was requested. If rule code is used to modify the Host: header value, the changed value is used. If the value in the Host: header does not correspond to any server, the request is rejected (by executing a reject rule, if one is specified; or by the default reject actions).

A server is created by setting a <server> tag in the configuration. The <server> tag takes the following attributes:

Attribute	Format
id	string	Must be set on each server. The id must be unique. The id is used to select a server based on the contents of the Host: header.
virtualserver	string	Identifies the virtual server that will process the request. Mutually exclusive with the realserver attribute.
realserver	string	Sets a direct mapping from server to real server. Mutually exclusive with the virtualserver attribute.
sorry	string	Name of the rule to be executed if no real servers are available for processing the request.
stickyloss	string	Name of the rule to be executed if the real server a sticky session was mapped to is no longer available.
track	string	“yes” or “no” to indicate if requests to this server cause tracking to be invoked for this client.

Reconfiguring

All attributes on a server can be reconfigured on-line.

Example

The following example creates a server that will map requests for a domain name (Host: header value) of yxorp.sourceforge.net to a virtual server named “servergroup1”. If none of the servers in the group is available, the sorry rule “sorryrule-yxorp” is invoked.

<server 
	id=”yxorp.sourceforge.net” 
	virtualserver=”servergroup1”
	sorry=”sorryrule-yxorp”
/>

The following example creates a server that will map requests for a domain name (Host: header value) of yxorp.sourceforge.net to a real server named “bigserver”:

<server 
	id=”yxorp.sourceforge.net” 
	realserver=”bigserver”
	sorry=”sorryrule-yxorp”
/>

Configuring virtual servers

The configuration settings for a virtual server list which real servers may be used to process a request. The virtualserver configuration also determines the scheduling algorithm to be used for load balancing.

Real servers will be excluded from the load balancing if they are out-of-service. If one of the real servers has been set out-of-service automatically, is is possible to have the virtualserver schedule a request to it occasionally, to determine whether it has become available again. This mechanism is called “real server wakeup”. This should work without disruption; if Yxorp is not able to connect to a server, another server will be connected after a short timeout.

A virtual server is created by setting a <virtualserver> tag in the configuration. Inside the virtualserver tag , the <real> tags are used to list the real servers. The <virtualserver> tag takes the following attributes:

Attribute	Format
id	string	Must be set on each server. The id must be unique.
schedule	string	Identifies the scheduling algorithm the virtual server will use. Currently defined are “roundrobin”, “randomrobin”, “lru”, and “weightedrandom”.
wakeup	string	Enables or disables waking up of mapped real serves that have been automatically set out-of-service. Valid values are “auto” for automatic wakeup and “manual” for disabling the mechanism.
wakeupfrequency	number	Average number of requests scheduled to in-service real servers in between attempts to wakeup a real server. Do not set to a value less than 100.
sticky	string	“yes” or “no” to set sticky load balancing for this client on this server group.
clearrealservers	number	If non-zero, all <real> tags within this virtualserver will be cleared.

The <real> tag takes the following attributes:

Attribute	Format
id	string	Must be set on each server. The id must be unique.
weight	number	If weightedrandom scheduling is used, this attribute is used to define the weight of this real server mapping. A weight of zero defines a “server of last resort”, that will be scheduled only if no servers with a higher weight are in service and available.
add	number	(default non-zero) If non-zero, this <real> tag will be added.
remove	number	If non-zero, this <real> tag will be removed.

Reconfiguring

All attributes on a virtualserver can be reconfigured on-line. The list of real servers will by default be replaced.

Example

The following example creates a virtual server that will load balance requests over a group of three real servers, using the roundrobin scheduling algorithm, and automatically retrying to inservice servers that may have become unavailable:

<virtualserver
	id=”servergroup1”
	schedule=”roundrobin”
	wakeup=”auto”
	wakeupfrequency=”100”
 >
	<real id=”server1” />
	<real id=”server2” />
	<real id=”server3” />
</virtualserver>

Configuring real servers

The configuration settings for a real server define the attributes of actual servers.

A real server may be set out-of-service automatically if it fails to respond to requests.

A real server is created by setting a <realserver> tag in the configuration. The <realserver> tag takes the following attributes:

Attribute	Format
id	string	Must be set on each server. The id must be unique.
ipaddress	IPv4 address	Numerical IPv4 address of this server. It is possible to set “dns” instead of the numerical IP address here; this will cause the value of the Host: header to be used to lookup the IP address and connect to it. This is useful for debugging and testing, but do not use this in production situations, as it might be a security risk, and it will also decrease performance. Note also that “dns” only works for requests associated with a dissecting listener, not with a tunnel.
port	number	TCP port on the server . If not set, 80 is the default.
sslport	number	SSL-capable TCP port on the server.
verifyservercertificate	number	If non-zero, SSL connections to this real server will verify the server certificate. If the certificate does not verify, the connection setup will be aborted.
cafile	string	File containing the certificate authority information against which the server certificates will be checked.
available	string	“yes” or “no” to set the intended availability state. If unavailable, Yxorp will not send requests to this server, except requests from sticky-loadbalancing sessions that have a sticky state mapping to this server.
inservice	string	Possible values are “yes” or “no”; automatically changed by server wakeup mechanisms (see virtualserver). If out-of-service, Yxorp will not send requests to this server.
reason	string	(display only) The source of the information in the inservice attribute; “config” if the setting was derived from configuration file or command; “auto” if the setting was caused by an automatic process.

Reconfiguring

All attributes on a real server can be reconfigured on-line.

Example

The following example creates a real server. The initial state of the real server is available, that is, the server is presumed to be able to process requests; the server is also set inservice, which means that new requests can be scheduled to this server.

<realserver
	id=”bigserver”
	port=”80”
	ipaddress=”10.1.0.117” 
	inservice=”yes”
	available=”yes”
/>

Configuring rules

Rules are small programs written in a special programming language. Each rule contains exactly one such program, which can deal with a request or response. The rule language itself is described in a separate chapter.

A rule begins with a <rule> tag, and ends with a </rule> tag. The text space in between these tags are assumed to be the program source. The rule program source is compiled when the configuration file is read; syntax errors will be reported. The configuration process will abort if serious errors are detected.

Since the configuration file uses XML, and the rule language uses text constructs that may not be valid in “plain” XML, it is sensible to enclose all rules in <![CDATA[ ... ]]> tags.

The <rule> tag takes the following attributes:

Attribute	Format
id	string	Required; must be unique across a configuration. The listener rule and resprule attributes refer to this id.
type	string	Value can be “request”, “response”, “reject”, “inboundentity”, “outboundentity”, “stickyloss” or “sorry”. The value is currently used for configuration file documentation only; defaults to “request”.

Reconfiguring

All parts of a rule may be reconfigured.

Example

<rule id=”example” type=”request”>
<![CDATA[
// rule source
   host: = “yxorp.sourceforge.net”;
]]>
</rule>

Configuring logging

Yxorp logs to files. Normal requests are logged to the access log; requests denied (either by a rule or by Yxorp code) are logged to the error log; and rule programs may log information to another log file, called the trace log. There are also files for debugging output, and for request details.

The log file names are set as attributes on the <log> tag in the configuration file.

The <log> tag takes the following attributes:

Attribute	Format
accesslog	string	File name for the access log
debuglog	string	File name for the debug log. Note that you only need this if Yxorp has been built with debugging enabled, and if debug settings in the configuration actually cause debugging output. If no file name has been set, and debug output is generated, it will be sent to stdout.
requestdetaillog	string	File name for the request detail log. This log file can be used to capture detail information about each request, or alternatively about failed requests only. The amount of information logged is much larger than with the accesslog or debuglog. The <requestdetaillog> tag can be used to tailor what information is logged; also, function calls in the rule language allow to make specific exceptions for specific requests.
errorlog	string	File name for the error log
tracelog	string	File name for the trace log. You will only need this if you have rule programs containing the trace function.

Log entries in the access and error logs are formatted from a printf-like format string. Any normal text in the format string is simply copied to the log; tokens starting with '%' are interpreted as field names, and substituted with the field value. The format strings are set as subtags enclosed in the log tag; the format strings are set in the text space. The format for the access log is set using the <access-fmt> subtag; the format of the error log is set using the <error-fmt> subtag.

The default access log format is as follows:

%clientip %clientport %nsstart %realserver \"%method %protocol%host%uri\" %statuscode %fromclient %toclient %toserver %fromserver %clientreqhdr %clientrsphdr %serverreqhdr %serverrsphdr %elapsed

The default error log format:

%requestnumber %clientip  %clientport %nsstart %realserver \"%method http://%host%uri\" %statuscode %fromclient %toclient %toserver %fromserver %clientreqhdr %clientrsphdr %serverreqhdr %serverrsphdr %elapsed %rejectreason

The following tokens are available for formatting:

Token	Field value
%clientip	Client IP number
%clientiplookup	Resolved name of client IP number
%clientport	TCP port number on client
%method	Method name
%uri	Uri (after translation by rule programs)
%host	Host name of server, taken from the Host: header (optionally modified by rule programs by assigning the Host: variable)
%targetserver	Host name of server, taken from the Host: header (optionally modified by rule programs by using the settargetserver() function call)
%nsstart	Time stamp at start of request
%nsend	Time stamp at end of request
%logi	Ordinal number of log entry as counted by request logging module
%requestnumber	Ordinal number of request, as counted by listener at start of the request
%protocol	Returns “http://” or “https://” according to the current protocol. Same as %clientprotocol.
%statuscode	HTTP status code
%fromclient	Total bytes received from client
%toclient	Total bytes sent to client
%fromserver	Total bytes received from server
%toserver	Total bytes sent to server
%clientreqhdr	Number of bytes in headers received from client
%clientrsphdr	Number of bytes in headers sent to client
%serverreqhdr	Number of bytes in headers sent to server
%serverrsphdr	Number of bytes in headers received from server
%elapsed	Wall clock time it took to process the request, in milliseconds
%rejectreason	Text string containing the reason why a request was rejected
%realserver	The real server that the request was forwarded to. If the request was served from a cache area, the name of the area is set instead.
%clientprotocol	Returns “http://” or “https://” according to the current protocol used between yxorp and the client
%serverprotocol	Returns “http://” or “https://” according to the current protocol used between yxorp and the server

Reconfiguring

All of the log settings may be reconfigured. If the log file names are changed in the new configuration, the active log file will be closed, and a new file with the changed name will be created (as yxorp tries to log a message, so using this mechanism to rotate logfiles must be used with caution since yxorp may not have closed the logfiles immediately upon reconfiguring).

Example

The following example will create three log files, and set the formatting for the access log and the error log:

<log accesslog=”/var/log/yxorpaccess” errorlog=”/var/log/yxorperror” tracelog=”/var/log/yxorptrace”>
	<access-fmt>%clientip %nsend %method %host %uri %statuscode 	</access-fmt>
	<error-fmt>%clientip %rejectreason”</error-fmt>
</log>

The following example, assuming a config snippet generated by a script running from cron, will “rotate” the access log file to a new, daily log file:

<log accesslog=”/var/log/yxorpaccess.2004-Feb-29” />

Configuring request detail logging

The requestdetaillog is a log file, defined in the <log> tag described above. It can be used to log details about each request, or only about requests that ended in error. The request or status line (the first line in an HTTP message) and the headers can be logged in each stage of Yxorp's processing.

The <requestdetaillog> tag takes the following attributes:

Attribute	Format
log	number	Master flag; if set to 0, no requestdetaillog actions are taken.
logerror	number	If set to 0, all requests are logged to the requestdetaillog. If set to non-zero, only requests for which the end status is in error are logged to the requestdetaillog.
logreceivedrequest	number	If set to non-zero, received request data (request line and message headers) is added to the requestdetaillog. The hex dump may also contain the first part of the request entity, depending on what is in the buffer at the time. The following bitmasks apply: 0x01 : Text dump 0x02 : Hex dump 0x04 : State of the internal data structures at time of dump
logtransmittedrequest	number	If set to non-zero, transmitted request data (request line and message headers) is added to the requestdetaillog. The hex dump may also contain the first part of the request entity, depending on what is in the buffer at the time. The following bitmasks apply: 0x01 : Text dump 0x02 : Hex dump 0x04 : State of the internal data structures at time of dump
logreceivedresponse	number	If set to non-zero, received response data (status line and message headers) is added to the requestdetaillog. The hex dump may also contain the first part of the response entity, depending on what is in the buffer at the time. The following bitmasks apply: 0x01 : Text dump 0x02 : Hex dump 0x04 : State of the internal data structures at time of dump
logtransmittedresponse	number	If set to non-zero, transmitted response data (status line and message headers) is added to the requestdetaillog. The hex dump may also contain the first part of the response entity, depending on what is in the buffer at the time. The following bitmasks apply: 0x01 : Text dump 0x02 : Hex dump 0x04 : State of the internal data structures at time of dump
logfinalinternaldata	number	If set to non-zero, a formatted copy of some of Yxorp's internal data structures are addedd to the requestdetaillog.

Reconfiguring

All flags in the requestdetaillog tag may be reconfigured.

Example

The following example shows how to configure the request detail log to log the data received for requests that ended in error:

<requestdetaillog log=”1” logerror=”1” logreceivedrequests=”1” />

Configuring a configuration listener

The configuration listener is a special interface into an active Yxorp daemon. It allows the configuration of Yxorp to be changed while Yxorp is active.

Normally, the configuration listener should be bound to IP address 127.0.0.1 and port 7780. This is done by setting the <configlistener> tag in the configuration file. Setting the IP address to 127.0.0.1 is recommended, because of security reasons; only change this if you are sure you know all the consequences.

You can also choose not to run a configuration listener; this is inherently more secure, but also less flexible. If no configuration listener is active, the yxorpconfig command can not be used to reconfigure Yxorp, or to read the current configuration; also, all other commands like yxorpclientstate and yxorprealserver will not work without a configuration listener.

Disable the configuration listener by omitting the <configlistener> tag, or by explicitly setting the port number to zero.

There can only be one configlistener in an Yxorp daemon; any attempt to define more than one configlistener will overwrite the previous configuration attributes.

The <configlistener> tag takes the following attributes:

Attribute	Format
port	number	port to bind to; default is 0. Setting the port number to 0 disables the configuration listener.
ipaddress	ipaddress	IPv4 address to listen on; default is 127.0.0.1

Reconfiguring

It is not possible to reconfigure the configlistener.

Example

The following example shows how to configure the configuration listener to use IP address 127.0.0.1 and port number 7780:

<configlistener ipaddress=”127.0.0.1” port=”7780” />

Configuring threads

Yxorp uses a thread pool for processing the requests. The behaviour and size of the thread pool can be configured by the <thread> tag.

The <thread> tag takes the following attributes:

Attribute	Format
initial	number	The number of threads that Yxorp will create at start
minfree	number	If less than this number of threads are free to process a request, Yxorp attempts to create a new thread.
max	number	Upper limit to the size of the thread pool.
startatoverrun	number	If the minfree threshold is reached, this amount of new threads will be started. The default and minimum is 1; the maximum is 10.
actual	number	(display only) Actual number of active threads.
actualfree	number	(display only) Actual number of free (waiting) threads.

Not all threads in an Yxorp process are counted for the thread pool size: the debug/log system, and each listener have their own dedicated thread that is not part of the thread pool. Because of this, the number of threads or LWPs reported by operating system commands may be higher than the value of max or actual.

In general, and assuming that clients ie. browsers behave according to RFC2616, each client can use two parallel sessions to retrieve content. During the handling of requests, and for some time after that according to the session timeout settings, this translates into two active threads for each client. The number of actual threads you need depends very much on the 'think time' of your users, that is, how long users will stay on the same web page. If this is shorter than the session timeout settings, each user will use up to two threads. If the 'think time' is longer than the session timeout settings, the actually needed number of threads will be lower. The timer settings that influence this are readfromclienttimeout, sslclientreadtimeout, and completerequesttimeout.

The defaults should suffice for normal web sites. If you run a heavily loaded site (ie. serving hundreds of concurrent sessions) you may have to increase the max attribute or lower the timer settings. Be careful about changing these settings though.

Reconfiguring

It is possible to reconfigure threads; however, reducing 'max' will not lower the number of active threads. Threads do however stop after having been idle for a configurable time.

Example

<threads initial=”20” minfree=”2” max=”100” />

Configuring security

Yxorp runs with reduced privileges on Solaris and Linux. Normally, binding to a port number lower than 1024 requires the process to run as root. Yxorp can release the root privileges and set parts of the process to run as a lower-privileged user. The way this works has significantly changed since version 0.19, it is now implemented using capabilities (Linux) and privileges (Solaris). For other platforms, you will either have to run Yxorp as root, or use non-privileged ports only.

For both Linux and Solaris, all privileges except the ones necessary for Yxorp are released. For Linux, the only remaining privilege is “cap_net_bind_service”; for Solaris, it is “PRIV_NET_PRIVADDR”. In this way, Yxorp does not need to run as root to be able to open low sockets (ie. <1024).

Besides this, it is also possible to change the userid and group that Yxorp will run as; this has the added effect of securing access to the file system. Because of privileges dropped on Solaris and Linux, Yxorp will not have omnipotent file system access even when it runs as root.

Other operating systems (like FreeBSD, NetBSD, MacOS etc) currently have no working privilege model. On those operating systems Yxorp needs to run as root to be able to bind to ports lower than 1024. It is still possible to have Yxorp run as non-root on those operating systems, but all listeners will need to bind to high ports.

Another security setting is “chroot”; if this is set, yxorp will change root to the specified directory. Within the jail, you will need the following:

File name or description
/dev/random /dev/urandom	A source of entropy for SSL. If your build includes SSL support, Yxorp needs read access to at least one of these.
/dev/null	Yxorp needs /dev/null to run as a daemon.
<ssl certificates>	The certificates for your SSL-enabled listeners. Yxorp needs read access to these files. Make sure that you do not allow world access to these files! Normally, yxorp tries to find this file within the <$sysconfdir> directory that was set during configure (ie. /usr/local/etc).
<log files>	Any of yxorp's log files you specified in your configuration. Yxorp needs permission to create and write these files.

You do not have to copy any dynamic or static libraries into the jail (as yxorp will already have the handles open before changing to the jail), but for OpenSSL you will need to make a source of entropy available within the jail (usually /dev/urandom or /dev/random). Also, the certificate must be accessible within the jail.

Many people insist on statically linking applications that will run inside a chroot jail. This is not in our view preferable, because you will need to relink the executables any time a bug fix is applied to any of the libraries, and you will need to do this by hand. Chances are very big you will forget this, and thus remain vulnerable for longer than needed. Besides, dynamic libraries were invented for a reason.

The <security> tag takes the following attributes:

Attribute	Format
user	number/string	The numerical userid or userid from /etc/passwd that will be set
group	number/string	The numerical group or group name from /etc/group that will be set
chroot	string	chroot to the specified directory just after reading the configuration file. The path must be complete (i.e. start in the root of the file system).

Reconfiguring

It is not possible to reconfigure security settings.

Example

<security user=”65535” group=”65535” />

<security user=”nobody” group=”nobody” />

Configuring basic authentication

Yxorp can store a table of basic authentication credentials in its configuration. Basic authentication credentials can also be retrieved from LDAP, see the configuration sections on <ldapserver> and <ldapsource> for more information.

Note that basic authentication is not very secure. To recover userid and password from the encoded form is trivial. Generally, it is a good idea to enforce SSL in combination with basic authentication; however, you should be aware that browsers cache or store the userid and password, and some browsers even show the password in clear text in a configuration window.

The <basicauth> tag takes the following attributes:

Attribute	Format
realm	string	The realm. See also the first parameter on the basic_auth_check function.
userid	string	The user name
passwd	string	The password
base64	string	The encrypted form of userid and password (set either base64 or userid/passwd). Generated configurations from yxorp will always contain the base64 form.
remove	number	If nonzero, remove this base64 credential from the table.

Reconfiguring

It is possible to reconfigure all basic authentication settings.

Example

<basicauth realm=”mystuff” userid=”baas” passwd=”notsosecure” />

Configuring digest authentication

Yxorp can store a table of digest authentication credentials in its configuration. Digest authentication credentials can also be retrieved from LDAP, see the configuration sections on <ldapserver> and <ldapsource> for more information.

Yxorp must be built with OpenSSL to support digest authentication.

Digest authentication is in theory much stronger than basic authentication. However, client applications are known that do not correctly implement digest authentication. For this reason, Yxorp currently does not currently enforce the nc parameter to be ever-increasing. This severly limits the cryptographic strength of the algorithm.

The <digestauth> tag takes the following attributes:

Attribute	Format
realm	string	The realm. See also the first parameter on the digest_auth_check function.
userid	string	The user name
passwd	string	The password
ha1	string	The encrypted form of userid, realm, and password (set either realm and ha1 or realm, userid and passwd). Generated configurations from yxorp will always contain the ha1 form.
remove	number	If nonzero, remove this digest authentication credential from the table.

Reconfiguring

It is possible to reconfigure all digest authentication settings.

Example

<digestauth realm=”mystuff” userid=”baas” passwd=”moresecure” />

Configuring ldap servers

Yxorp can access LDAP servers for retrieving information, for example to support the basic_auth_check() and digest_auth_check() functions. Yxorp must be built with ldap to support this.

LDAP support associated with basic authentication is considered stable functionality as of Yxorp version 2.33 and later. Support of digest authenticate with LDAP however is not; the way Yxorp implements that will change in later versions.

The <ldapserver> tag takes the following attributes:

Attribute	Format
id	string	The name by which this ldapserver is referred to (usually from an ldapsource definition).
hostname	string	The name of the host that the ldap server runs on
port	string	The port on which the ldap server listens
binddn*	string	The dn (distinguished name) to use in binding to the ldap server. Only required for digest authentication support, not relevant for basic authentication support.
password*	string	The password to use in the bind operation. Only required for digest authentication support, not relevant for basic authentication support.
maxsessions*	number	The maximum number of sessions that can be concurrently open to this ldap. This should be equal to the maximum number of threads you are running. Only required for digest authentication support, not relevant for basic authentication support.

* in the table above signifies attributes that are part of the experimental support of digest authentication.

Reconfiguring

It is possible to reconfigure all ldapserver settings; however, existing sessions to an ldap server are not taken down on reconfiguration.

Example

// for basic authentication support
<ldapserver
  id=”ldapserver1”
  hostname=”localhost”
  port=”389”
/>

// for digest authentication support
<ldapserver 
   id=”ldapserver2” 
   hostname=”localhost” 
   port=”389” 
   binddn=”cn=root,dc=example,dc=com” 
   password=”secret” 
   maxsessions=”100” 
/>

Configuring ldap sources

An ldapsource is an abstraction layer on top of ldapservers to set retrieval parameters with. Yxorp must be built with ldap support to enable the <ldapsource> tag; otherwise, the <ldapsource> tag will be rejected from the configuration.

The ldapsource tag can be used with the basic_auth_check function; in this case, the settings on the ldapsource tag will be used to perform a simple bind to the ldap server. If however a digest_auth_check function is used, an administrative bind will be done to the ldap server using the DN set on the <ldapserver> tag. This administrative connection will then be used to retrieve the password for the userid retrieved from the digest_auth_check from the ldap server. For this to work, the ldap server needs to store the user passwords as clear text.

The <ldapsource> tag takes the following attributes:

Attribute	Format
id	string	The name by which this ldapsource is referred to.
serverid	string	The serverid maps to a ldapserver definition to be used for this ldapsource
bindfmt	string	A string containing exactly one occurrence of “%s”. The username as passed from a basic authentication dialog will be substituted into this “%s”; the resulting string will be used to perform a simple bind to the ldap server mapped by the serverid attribute. The result of this simple bind will be passed back to the basic_auth_check function; also, the result will be cached according to the cachetime setting.
cachetime	number	Number of seconds that the result of a simple bind to the ldap is cached by Yxorp. The minimum setting is 10 seconds.
base*	string	The base DN to be used for search operations
scope*	string	The scope to be used for search operations. Defined values are “base”, “onelevel”, and “subtree”.

* in the table above signifies attributes that are part of the experimental support of digest authentication.

Reconfiguring

It is possible to reconfigure all ldapsource settings.

Example

// for basic authentication
<ldapsource
   id=”ldapsource1”
   serverid=”ldapserver1”
   bindfmt=”cn=%s,ou=People,dc=example,dc=com”
   cachetime=”60”
/>

// for digest authentication

<ldapsource 
   id=”ldapsource1” 
   serverid=”ldapserver1”
   base=”ou=People,dc=example,dc=com”
   scope=”subtree”
/>

Configuring cache areas

To control the caching processes, Yxorp uses the concept of areas. A request that is eligible for caching is mapped to a “cache area”, which can be defined as a set of attributes to control how that request is cached. Cache areas are configured through the <cachearea> tag.

The <cachearea> tag takes the following attributes:

Attribute	Format
area	string	The name of the cache area
maxage	number	The maximum time in seconds that an entity is cached. After this time, it will not be used for generating cached responses, and it will be removed from the cache.
maxobjectsize	number	The maximum size of an object that is accepted into this cache area. Larger objects will not be stored, and thus, no caching will be done for these.
refreshage	number	If an object is older than this time in seconds, the first reference will not be served from the cache but directed to the real server. The entity returned from the real server will be stored in the cache, thus effectively refreshing the cache. This mechanism is intended to keep the cache consistenly fresh, but limit the maximum load on the real servers.

Reconfiguring

It is possible to reconfigure all cachearea settings.

Example

<cachearea area=”area51” maxage=”120” maxobjectsize=”128000” />

Configuring global settings

Global configuration settings are (as the name implies) global within a daemon (and thus govern all processing for all listeners).

The default values for the settings are set to reasonable defaults that should work well in almost all circumstances. In general, you should probably not make any changes to the defaults, with a few exceptions that are documented elsewhere in this document. If you do decide to make changes, make sure you understand what it is you are changing, and test what the effects are before deploying to production systems.

The <globalconfiguration> tag takes the following attributes:

Attribute	Format
maxchunksize	number	In chunked content processing, the maximum size of a chunk that will be accepted. A larger chunk will lead to the request being rejected.
maxchunkheaderlength	number	In chunked content processing, the maximum chunk header length that will be accepted. If a header is longer than this, the request will be rejected.
maxchunkheaderreadretries	number	The maximum number of retries that will be done in trying to read a complete chunk header, in chunked header processing. If this amount of retries does not produce a valid chunk header, the request will be rejected.
maxserverconnectionattempts	number	The maximum number of times connection to a server will be retried. If applicable, load balancing is applied, so the first connection attempt may be to server A, the next attempt to server B. Setting this to a higher number may lead to high response times if servers are unavailable. Also see connectservertimeout.
writetoclienttimeout	number	The time (in milliseconds) yxorp will wait for a write to a client to succeed. Note that normally a write will succeed almost instantaneously, since Unix processes the writes asynchronously; the actual meaning of this timer is more along the lines of “wait this long for buffer space to become available”. If this timer expires, the request will be rejected.
readfromclienttimeout	number	The time (in milliseconds) yxorp will wait for data to arrive from a client. If the timer expires, the request will be rejected.
sslclientaccepttimeout	number	The time (in milliseconds) that the SSL exchanges may take in total for the SSL connection between a client and yxorp to be accepted. This includes handshaking, selecting a cypher algorithm, and exchanging keys. If this timer expires, the request will be rejected.
sslclientreadtimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to read data from the SSL connection between a client and yxorp. This may include a key renegotiation. If this timer expires, the request will be rejected.
sslclientwritetimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to write data to the SSL connection between a client and yxorp. This may include a key renegotiation. If this timer expires, the request will be rejected.
sslclientclosetimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to close the SSL connection between a client and yxorp. If this timer expires, the request will be rejected.
sslserverconnecttimeout	number	The time (in milliseconds) that the SSL exchanges may take in total for the SSL connection between yxorp and a server to be accepted. This includes handshaking, selecting a cypher algorithm, and exchanging keys. If this timer expires, the request will be rejected.
sslserverreadtimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to read data from the SSL connection between yxorp and a server. This may include a key renegotiation. If this timer expires, the request will be rejected.
sslserverwritetimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to write data from the SSL connection between yxorp and the server. This may include a key renegotiation. If this timer expires, the request will be rejected.
sslserverclosetimeout	number	The time (in milliseconds) that the SSL exchanges may take in total to close the SSL connection between yxorp and a server. If this timer expires, the request will be rejected.
maxrealserverconnectfailuresbeforeoutservice	number	When this many subsequent failures occurred connecting a server, it is set out of service. If part of a virtualserver load balancing group, it will thereafter be considered out of service (and only be scheduled if the wakeup algorithm is active). For servers that are directly mapped to real servers, the out of service attribute is ignored.
connectservertimeout	number	(milliseconds) Wait this long for a connection to a server to complete. Setting this to a longer time also has the effect of causing longer response times if one or more servers in a virtualserver load balancing group becomes unavailable. See also maxserverconnectionattempts.
writetoservertimeout	number	(milliseconds) Wait this long for a write to a server connection to succeed. See writetoclienttimeout above. If this timer expires, the request will be rejected.
readfromservertimeout	number	(milliseconds) Wait this long for data to arrive from a server connection. If this timer expires, the request will be rejected.
completerequesttimeout	number	(milliseconds) Wait this long before a request must be completely received. A request is considered completely received in this context when both the start-line and message-headers have been read, or, less formally, when the <CR><LF><CR><LF> after the last request header has been read. If this timer expires, the request will be rejected.
tunnelwritetoservertimeout	number	(milliseconds) Wait this long for a tunnel buffer to be written to the server connection.
tunnelwritetoclienttimeout	number	(milliseconds) Wait this long for a tunnel buffer to be written to the client connection.
tunnelconnecttimeout	number	(milliseconds) Wait this long for a tunnel connection to be established.
clientstatecleanupinterval	number	(seconds) Time between runs of the client state cleanup process. Don't set too short, because the cleanup process locks the client state table, and frequent locking decreases throughput. Also don't set too long, because then the amount of work increases and the table is locked longer.
clientstatecleanupmaxage	number	(seconds) Time a client state is maintained, counting from the last request referencing this state. If you are using sticky load balancing, you may need to increase this time to the maximum time you want the sticky mapping to be remembered for idle sessions.
requestdvarvectorsize	number	The size of the dvar vector that is allocated for each request. This number should be set carefully, since the dvar table will not expand. The number should be large enough to accommodate all rule programs, built-in variables, and headers (both from client and from server), but it should also be small enough not to waste memory. Also consider that due to the way the dvar table works, a certain amount of free space increases the likelyhood that a dvar entry will be found quickly, whereas setting the vector size small will increase the likelyhood that a partial table scan will be necessary to locate a dvar entry. To improve efficiency, the number you set here will be rounded up to the next higher prime number. Note that if this number is set too small Yxorp will not be able to store information about the request; this may cause the request to be rejected. A suggested minimum is 97; when tuning, set to at least 2 times the actual dvars you need (counting built-ins, headers, and variables you use in rule programs, including results from capturing regexpses).
clientstatedvarvectorsize	number	The size of the dvar vector associated with a client state. In this dvar vector, the mapping between virtual and real servers is kept for sticky load balancing. The dvar vector can also be accessed from rule programs. To improve efficiency, the number you set here will be rounded up to the next higher prime number. Note that if this number is set too small Yxorp will not be able to store information in the client state; this may cause Yxorp to be unable to do sticky load balancing or other functionality that uses clientstate dvars. A suggested minimum is 1; when tuning, set to at least 2 times the actual dvars you need (counting sticky-enabled virtualservers in the same cookie domain, and clientstate variables you use in rule programs).
maxdvarchunksize	number	The maximum size of one memory allocation “chunk” in a dvar vector. In practice, this is the maximum size that the value of a variable can ever have; requests for storage over this size are rejected and cause the process requiring the variable to fail. The default is set to 16M, which should be adequate for normal use. If you need to tune this, you are probably doing something that Yxorp was not meant to do. See also maxrcmpchunksize.
maxrcmpchunksize	number	The maximum size of one memory allocation “chunk” used for the rule vm. In practice, this is the maximum size that the value of a variable can ever have; requests for storage over this size are rejected and cause the process requiring the variable to fail. The default is set to 16M, which should be adequate for normal use. If you need to tune this, you are probably doing something that Yxorp was not meant to do. See also maxdvarchunksize.
entitybuffertotalsizelimit	number	The total amount of memory that Yxorp can use for entity buffers. Yxorp uses these buffers to temporarily store HTTP entities that are subject to rule processing (ie. inboundentity and outboundentity rules) and caching. If you don't use these rule types, and don't use caching, you do no need entity buffers. To determine the number you need if the default is insufficient, consider the average size of entities that need to be buffered, and the maximum number of threads you are using. Multiply these, and set the limit to twice that amount to be on the safe side. If yxorp runs out of entity buffer space, requests subject to rule processing will be rejected, and requests that would be eligible for caching will not be cached. As a rule of thumb, do not define more than a quarter of the physical memory that is available in your system and not used in any other processes. If you exceed this, paging may occur to the point of greatly reducing system throughput. If you don't need entity buffers, leave this setting at it's default.
entitybufferinitial	number	The initial size of an entitybuffer if the required size can not be determined from the request or response. This occurs if no Content-Length header is present in a request or response, which is generally the case with dynamically generated content. See also entitybuffertotalsizelimit and entitybufferextend.
entitybufferextend	number	The number of bytes added to an entitybuffer if it is allocated without knowledge of the required size, and if the initial allocation (ie. entitybufferinitial) is not sufficient. Since the reallocation this causes is an expensive operation, set entitybufferinitial to a value that is sufficient for something like 80-90% of all requests. Setting to 0 prevents reallocation (and causes requests that require a larger amount to fail). See also entitybuffertotalsizelimit and entitybufferinitial.
entitybuffermaxobjectsize	number	The maximum size of one entitybuffer, both for fixed-length requests and variable length requests (that are allocated through entitybufferinitial and entitybufferextend). Requests that require a larger buffer are rejected (for inboundentity and outboundentity rules) or not cached.
cachemaxobjectsize	number	The maximum size of an HTTP entity that can be cached.
cachetotalsizelimit	number	The maximum size that the cache can use. If this is exceeded, no new entries will be added to the cache. As a rule of thumb, don't set this to more than half the physical memory that is available in your system and not used in any other processes. If you exceed this, paging may occur to the point of greatly reducing system throughput.
cachemaintenanceinterval	number	The time (in seconds) between runs of the maintenance processes for the cache.
basicauthmaintenanceinterval	number	The time (in seconds) between runs of the maintenance processes for the basic authentication cache.
enabledheadergroups	string	The header groups that are enabled. Available groups are “std” which is always enabled, “dav” for WebDAV related headers, and “msext” for Microsoft extensions to WebDAV. To enable these groups, comma-separate the groups you require.
enabledmethodgroups	string	The method groups that are enabled. Available groups are “std” which is always enabled, “rfc2616” for additional less-used methods defined in rfc2616, “dav” for WebDAV related headers, and “msext” for Microsoft extensions to WebDAV. To enable these groups, comma-separate the groups you require.
pidfilename	string	The filename for the pid file, as a complete path starting in the root of the filesystem. Yxorp needs to have its own directory to put the pid file in, and the name of that directory must end in “yxorp”, otherwise, Yxorp will refuse to start. Default is “/var/run/yxorp/yxorp.pid”. Yxorp will attempt to create the last directory in the path if it does not exist. Also, Yxorp takes care of setting file ownerships to the user and group configured in the <security> tags.
clearthreadpoolgracetime	number	(milliseconds) Time that Yxorp waits for threads to finish after a stop command has been given. After this time expires, threads will be forcibly stopped to ensure orderly shutdown.
closelogdaemongracetime	number	(milliseconds) Time that Yxorp waits for it's internal log daemon to finish after a stop command has been given. This allows the log daemon to flush its buffers and ensure that logging is complete.
starterwaitforsignaltime	number	(milliseconds) Time that the command starting Yxorp waits for its daemonized child to become active.
threadinactivitylimit	number	(seconds) Time a thread waits for work before exiting. Thread resources are released after being inactive for this length of time. Currently, this comprises LDAP sessions maintained per thread.
doclientheaderenabledchecks	number	(default non-zero) If zero, Yxorp will not check if headers are enabled for client. All headers that are defined in Yxorp's table will be accepted from a client. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doclientheaderlengthchecks	number	(default non-zero) If zero, Yxorp will not check the length of headers received from a client. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doclientheaderbufchecks	number	(default non-zero) If zero, Yxorp will not check the contents of headers received from the client against a table of allowed characters. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doclientheaderduplicatechecks	number	(default non-zero) If zero, Yxorp will not check headers received from the client for duplicates. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doclientheaderunknownchecks	number	(default non-zero) If zero, Yxorp will accept from clients any unknown header (ie. headers that are not defined in Yxorp's header table). The unknown headers will be passed through without any checking (regardless of other settings). However, all known headers will be checked as defined by the header table or by other do[client\|server]header settings. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doserverheaderenabledchecks	number	(default non-zero) If zero, Yxorp will not check if headers are enabled for server. All headers that are defined in Yxorp's table will be accepted from a server. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doserverheaderlengthchecks	number	(default non-zero) If zero, Yxorp will not check the length of headers received from a server. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doserverheaderbufchecks	number	(default non-zero) If zero, Yxorp will not check the contents of headers received from the server against a table of allowed characters. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doserverheaderduplicatechecks	number	(default non-zero) If zero, Yxorp will not check headers received from the server for duplicates. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
doserverheaderunknownchecks	number	(default non-zero) If zero, Yxorp will accept from servers any unknown header (ie. headers that are not defined in Yxorp's header table). The unknown headers will be passed through without any checking (regardless of other settings). However, all known headers will be checked as defined by the header table or by other do[client\|server]header settings. Do not set this to zero if you run Yxorp as a security device; instead, change individual header definitions to accommodate your needs.
workdatadissectbufsize	number	(default 8192) The buffer size used to receive requests in. A complete request (excluding entity) must fit into this buffer; if not, Yxorp will reject the request. The part of the request that this applies to is made up by the request line (method name, uri, http version) and all headers, including the terminating CRLF after each line and the CRLF terminating the request. The entity (the data retrieved by a request, or the data sent in by for example a POST request) is not limited by this buffer size. Do not change this unless you really have requests this big, and can not change them to become smaller. Also note workdatadissectwbufsize, which must be defined larger than workdatadissectbufsize.
workdatadissectwbufsize	number	(default 10240) Internal work buffer. Must be set bigger than workdatadissectbufsize (normally at least 2K over this size). Do not change this unless you have changed workdatadissectbufsize.
maxlenrequesturi	number	(default 2048) The maximum size of the URI that is received by Yxorp. This size includes any parameter fields sent by clients (ie. http://www.example.com/some.cgi?parameter1=value1). Requests with longer URI's will be rejected by Yxorp.
maxlenheaderline	number	(default 2048) The maximum length of any header that Yxorp can process. Note that some headers (eg. Authorization:, Referer:, Location: may include URI's, and thus may become quite long. Requests with longer headers will be rejected by Yxorp.
rewritelocationheader	number	If nonzero (default), yxorp will rewrite Location: headers coming from the server that contain an absolute form URI to the domain name that the request associated with the response originally contained.
renameonrotate	number	(default zero). If nonzero, yxorp will rename its log files when rotating them. If zero, the files will just be closed and then reopened.
basicauthmaintenanceinterval	number	(default 30) Number of seconds between runs of the basic authentication maintenance process.
basicauthcachetime	number	(default 60) Number of seconds that credentials added by use of the basicauth_add function are accepted as valid. After this time, the entry may still be present in the basicauth table; the credentials will be removed on first reference after the time elapsed, or by the next basic authentication maintenance process.
generatexcache	number	(default nonzero) If nonzero, Yxorp will generate X-Cache headers if serving from a cache was applicable to this request. If serving from a cache was not possible, no header will be generated irrespective of this setting.
viareportversionstringtoclient	number	If zero, do not report the version string in Via: headers sent to the client.
viareportpackagenametoclient	number	If zero, do not report the package name in Via: headers sent to the client. Irrelevant if viareportversionstringtoclient is nonzero.
viareporthosttoclient	number	If zero, do not generate a Via: header to send to the client. Irrelevant if viareportversionstringtoclient or viareportpackagenametoclient are nonzero.
viareportversionstringtoserver	number	If zero, do not report the version string in Via: headers sent to the server.
viareportpackagenametoserver	number	If zero, do not report the package name in Via: headers sent to the server. Irrelevant if viareportversionstringtoserver is nonzero.
viareporthosttoserver	number	If zero, do not generate a Via: header to send to the server. Irrelevant if viareportversionstringtoserver or viareportpackagenametoserver are nonzero.
workerthreadstacksize	number	(default zero) If nonzero, the value defined here will be used to override the platform's default for the stack size of a worker thread. The stack size should not be defined smaller that 128000. This setting should only be used if no alternatives exist, and the number of threads required consume all available virtual memory. Normally, either the available virtual memory should be increased (ie. ulimit -v) or the defined stack space should be lowered (ie. ulimit -s). Note that the ulimit command only applies within the shell in which the command was issued; for ulimit to have effect, it must either be included in the script used to start yxorp, or be issued manually before yxorp is started.
statecookiename	string	This string will be prepended to the name of the cookie variable that Yxorp will set if it needs to track clients. The special value of “(auto)” derives a unique name from the hostname that Yxorp runs on.
localhostname	string	The string defined here will be used in reporting the host name of the system that Yxorp runs on; for instance in X-Cache: and Via: headers. The default special value of “(auto)” can be used to derive the name from the host name as reported by the operating system; or any other name can be configured.

The method table

In the globalconfiguration section is the table of accepted methods. The header table can be changed by including “<method>” tags in the globalconfiguration section.

By default, only a restrictive set of methods consisting of “GET”, “HEAD”, and “POST” is active; but many more methods are defined. These can be enabled with the “enabledmethodgroups” setting in the global configuration.

The <method> tag takes the following attributes:

Attribute	Format
id	string	The name of the method, as it would appear in a request. Yxorp processes this value case-insensitively.
enable	number	Whether or not this method is enabled. Remember that a method must also be in an enabled method group to be active.
inboundentity	number	If non-zero, Yxorp expects an entity to be sent client-to-server with this method.
outboundentity	number	If non-zero, Yxorp expects an entity to be sent server-to-client with this method.
cacheable	number	If non-zero, cache processing is enabled for this method. This should only be set to 1 for GET and HEAD; caching is not defined by rfc2616 for other methods. Changing this attribute from the provided defaults may cause undesired effects.
methodgroups	string	Defines to which method groups this method belongs. Recognized values are “all”, “rfc2616”, “dav”, and “msext”. Refer to enabledmethodgroups in globalconfig.

The header table

Also in the globalconfiguration section is the table of accepted headers. Only headers that appear in this table are processed by yxorp, or made available in the rule language. The standard headers in RFC2616 are included by default. The header table can be changed by including “<header>” tags in the globalconfiguration section.

The <header> tag takes the following attributes:

Attribute	Format
id	string	The name of the header, as it would appear in a request. Yxorp processes this value case-insensitively. The name must include a colon (':') as the last character.
xlateid	string	The name of the header as it would appear in the rule language. Normally, the only difference between the id and xlateid are that '-' is changed to '_'; this is usually required because the minus sign has a specific meaning in the rule language.
client	number, (“reject” \| ”ignore”)	If non-zero, this header is accepted from a client connection. If 0, the request is rejected if “reject” is set, or the header is discarded if “ignore” is set. Reject is default.
server	number, (“reject” \| ”ignore”)	If non-zero, this header is accepted from a server connection. If 0, the request is rejected if “reject” is set, or the header is discarded if “ignore” is set. Reject is default.
maxlen	number [“, ignore”]	The maximum length of this header line (so including the header name itself). If this length is exceeded the request is rejected, unless “ignore” is set, in which case the header is discarded.
check	string, (“reject” \| ”ignore”)	Takes the values “none”, “numeric”, “rfc2616-text”, and “reduced”; this sets the character set that the header will be checked against. If characters exist in the header that are not in the character set, the header will either be discarded or the request will be rejected, according to the reject setting for the header. “none” means no checking will be performed; “rfc2616-text” sets the character set to the set described in RFC2616 (i.e. 7-bit ASCII without the control characters); “reduced” is a subset of rfc2616-text, in which most non-alphanumerical characters have been removed; “numeric” is the set of characters between 0 and 9.
allowduplicates	number, (“reject” \| ”ignore”)	Whether or not multiple occurrences of this header are allowed within a single request or response. If 0, the request is rejected if “reject” is set, or the header is discarded if “ignore” is set. Reject is default.
hop-by-hop	numeric	As defined in rfc2616, some headers have meaning only on one session. Yxorp base code controls the values of these headers. This attribute should not be changed.
folding	numeric	As defined in rfc2616, a gateway may decide to combine headers with the same name into one, if the header value is composed of a comma-separated list. Setting the folding attribute to “1” enables this.
hdrgroups	string	Defines to which header groups this header belongs. Recognized values are “all”, “dav”, and “msext”. Refer to enabledheadergroups in globalconfig.

The status code table

In the globalconfiguration section is the table of status codes. The table can be changed by including “<statuscode>” tags in the globalconfiguration section.

By default, all status codes in rfc2616 and rfc2518 (WebDAV) are defined. You can add to these, or change the standard reason texts with the codes for your amusement.

The <method> tag takes the following attributes:

Attribute	Format
id	number	The numeric status code.
reason	string	The textual explanation of the status code

Reconfiguring

All global settings can be reconfigured. However, header, method, and status code entries, once they are created, may be modified but not completely removed.

Example

The example below sets the global configuration values for clientstatecleanupmaxage to 900 seconds. The header table is updated with the (custom) header “Example:”, which will be called “bad_example:” in the scripting language, is accepted from a client but not from a server; the maximum length is 1 byte, and the entire request will be rejected if this request is overlength, has any characters in it outside of the reduced set, or appears multiple times in the request.

The status code of “200” is changed from it's default “OK” to say “Yo”.

<globalconfiguration
                    clientstatecleanupmaxage="900"
                    >
<header id=”Example”
        xlateid=”bad_example”
        maxlen=”1, reject”
        client=”1”
        server=”0, ignore”
        check=”reduced, reject”
        allowduplicates=”0, reject”
/>
<statuscode id=”200” reason=”Yo”>
</globalconfiguration>