<!-- Wt Configuration File. The Wt configuration file manages, for every Wt application, settings for session management, debugging, directory for runtime information such as session sockets, and some security settings. Settings may be specified globally, or for a single application path. The path should be as configured in the Wt build process, where it defaults to /etc/wt/wt_config.xml. It can be overridden in the environment variable WT_CONFIG_XML, or with the -c startup option of wthttpd. The values listed here are the default values, which are used when the declaration is missing or no configuration file is used. --> <server> <!-- Default application settings The special location "*" always matches. See below for an example of settings specific to a single application. --> <application-settings location="*"> <!-- Session management. --> <session-management> <!-- Every session runs within a dedicated process. This mode guarantees kernel-level session privacy, but as every session requires a seperate process, it is also an easy target for DoS attacks if not shielded by access control. It is also a convenient mode during development, as it is easy to enable disable debugging using valgrind, and it always starts the latest deployed executable for a new session. Note: currently only supported using the FastCGI connector --> <!-- <dedicated-process> <max-num-sessions>100</max-num-sessions> </dedicated-process> --> <!-- Multiple sessions within one process. This mode spawns a number of processes, and sessions are allocated randomly to one of these processes (you should not use this for dynamic FCGI servers, but only in conjunction with a fixed number of static FCGI servers. This requires careful programming, as memory corruption in one session will kill all of the sessions in the same process. You should debug extensively using valgrind. Also, it is your responsibility to keep session state not interfering and seperated. On the other hand, sessions are inexpensive, and this mode suffers far less from DoS attacks than dedicated-process mode. Use it for non-critical and well-debugged web applications. Note: wthttpd always uses exactly one process --> <shared-process> <num-processes>1</num-processes> </shared-process> <!-- Session tracking strategy. Possible values: Auto: cookies is available, otherwise URL rewriting URL: only URL rewriting --> <tracking>URL</tracking> <!-- How reload should be handled. When reload should (or rather, may) spawn a new session, then even in the case cookies are not used for session management, the URL will not be cluttered with a sessionid. However, WApplication::refresh() will never be called. --> <reload-is-new-session>true</reload-is-new-session> <!-- Session timeout (seconds). When a session remains inactive for this amount of time, it is cleaned up. --> <timeout>600</timeout> <!-- Server push timeout (seconds). When using server-initiated updates, the client uses long-polling requests. Proxies (including reverse proxies) are notorious for silently closing idle requests; the client therefore cancels the request periodically and issues a new one. This timeout sets the frequency. --> <server-push-timeout>50</server-push-timeout> </session-management> <!-- Settings that apply only to the FastCGI connector. To configure the wthttpd connector, use command line options, or configure default options in /etc/wt/wthttpd --> <connector-fcgi> <!-- Valgrind path If debugging is enabled and this path is not empty, then valgrind will be started for every shared process, or for every session which has ?debug appended to the command line. The variable is slighly misnamed. Not only a path can be set, but also options, like for example: /usr/bin/valgrind - -leak-check=full --> <valgrind-path></valgrind-path> <!-- Run directory Path used by Wt to do session management. --> <run-directory>/var/spool/wt/run</run-directory> <!-- Number of threads per process This configures the size of the thread pool. You may want to change this value if you would like to support reentrant event loops, where you block one event loop using WDialog::exec() or related static methods. Everytime you enter such an event loop, one thread is blocked, and therefore the total number of sessions that reliably can do this is limited to the number of thread you have (minus one to unblock). For the built-in http connector, there is a similar config option that is specified in the whttpd config file or on the command line (-t). The default value is 1. --> <num-threads>1</num-threads> </connector-fcgi> <!-- Settings that apply only to the MS IIS ISAPI connector. To configure the wthttpd connector, use command line options, or configure default options in /etc/wt/wthttpd --> <connector-isapi> <!-- Number of threads per process This configures the number of threads that will be used to handle Wt requests. The IIS internal threads are never used to do any processing; all requests are forwarded to be handled in this threadpool. Rather than to configure a so-called 'web-garden' in IIS, increase this number. The ISAPI connector will not work correctly when a web-garden is configured. You may want to change this value if you would like to support more reentrant event loops, where you block one event loop using WDialog::exec() or related static methods. Everytime you enter such an event loop, one thread is blocked, and therefore the total number of sessions that reliably can do this is limited to the number of thread you have (minus one to unblock). You may also want to increase this number if your Wt application is regularly waiting for IO (databases, network, files, ...). If this number is too low, all threads could be waiting for IO operations to complete while your CPU is idle. Increasing the number of threads may help. Computing intensive applications may also increase this number, even though it is better to offload computations to a helper thread and user server push or a WTimer to check for completion of the task in order to keep your GUI responsive during the computations. The default value is 10. --> <num-threads>10</num-threads> <!-- Maximum Request Size spooled in memory (Kb) Normally, Wt keeps incoming requests (POST data) in memory. However, malicious users could send a big POST and as such use up all memory of your HTTP server. With this parameter, you tune how big a request can be before Wt spools it in a file before processing it. Legitimate big POST messages may occur when users are expected to upload files. See also max-request-size. The default value is 128K, which is more than enough for any interactive Wt event. --> <max-memory-request-size>128</max-memory-request-size> </connector-isapi> <!-- Javascript debug options Values: - true: JavaScript errors are not caught but the browser built-in debug options are used - stack: JavaScript errors are caught but also a stack trace is printed, useful for diagnosing a problem in production - false: JavaScript errors are caught and a simple error message is printed to indicate that something is terribly wrong --> <debug>false</debug> <!-- Log file When the log file is empty, or omitted, logging is done to stderr. This may end up in the web server error log file (e.g. for apache + fastcgi module), or on stderr (e.g. for the built-in httpd). --> <log-file></log-file> <!-- Logger configuration This configures the logger. With the default configuration, everything except for debugging messages are logged. The configuration is a string that defines rules for enabling or disabling certain logging. It is a white-space delimited list of rules, and each rule is of the form: [-]level : enables (or disables) logging of messages of the given level; '*' is a wild-card that matches all levels [-]level:scope : enables (or disables) logging of messages of the given level and scope; '*' is a wild-card that matches all levels or scopes. The default configuration is "* -debug", i.e. by default everything is logged, except for "debug" messages. Some other examples: "* -debug debug:wthttp": logs everything, including debugging messages of scope "wthttp", but no other debugging messages. "* -info -debug": disables logging of info messages in addition to debugging messages. Note debugging messages are only emitted when debugging has been enabled while building Wt. --> <log-config>* -debug</log-config> <!-- Maximum HTTP request size (Kb) Maximum size of an incoming POST request. This value must be increased when the user is allowed to upload files. --> <max-request-size>128</max-request-size> <!-- Session id length (number of characters) --> <session-id-length>16</session-id-length> <!-- DoS prevention: limit plain HTML sessions This is a simple measure which avoids Denial-of-Service attacks on plain HTML sessions, which are easy to mount in particular in the case of progressive bootstrap mode. This setting may be used to keep the ratio of plain HTML versus Ajax sessions under a certain ratio. Typically, most of your sessions will be Ajax sessions, and only a tiny fraction (e.g. less than 5%) will be plain HTML sessions. This ratio is only enforced when more than 20 sessions have been created. --> <plain-ajax-sessions-ratio-limit>1</plain-ajax-sessions-ratio-limit> <!-- DoS prevention: adds a puzzle to validate Ajax sessions This is a simple measure which avoids Denial-of-Service attacks on Ajax sessions. When enabled, a puzzle needs to be solved in the first Ajax request which eliminates agents that do not build a proper DOM tree. --> <ajax-puzzle>false</ajax-puzzle> <!-- Send the XHTML mime type when appropriate Wt renders XHTML1 (XML variant of HTML) that is backward-compatible with HTML. Using XHTML, Wt is capable of supporting XHTML-only features such as embedded SVG or MathML. When enabled, JWt sets an XHTML mime-type (application/xhtml+xml) when the browser reports support for it. Most notably, Internet Explorer does not support it. Because XHTML and HTML are slightly different with respect to default CSS rules, you may want to disable sending the XHTML mime-type alltogether, at least if you are not using SVG (used by the WPaintedWidget). --> <send-xhtml-mime-type>false</send-xhtml-mime-type> <!-- Do strict serialization of events. By default events are queued at the client-side, and transmitted to the server so that at any time only one request/response is pending. This scheme has a quality that resembles TCP: on a low-latency link you allow the transmission of many smaller requests, while on a high latency link, events will be propagated less often, but in batches. In any case, this scheme does not drop events, no matter how quickly they are generated. In rare cases, the scheme may result in unwanted behaviour, because the client-side is allowed to be slighly out of sync at the time an event is recorded with the server-side (and more so on high-latency links). The drastic alternative is to discard events while a response is pending, and can be configured by setting this option to true. --> <strict-event-serialization>false</strict-event-serialization> <!-- Enables web socket. By default Ajax and long polling are used to communicate between server and browser. By enabling web socket support, if the browser supports WebSockets, then WebSocket is the protocol used for communication between client and server. WebSockets are currently only supported by the built-in httpd Connector, which acts as both an HTTP and WebSocket server. The WebSocket protocol is intentionally not compatible with HTTP, through a special hand-shake mechanism, and requires that all (reverse) proxy servers also have explicit support for this protocol. This feature is still experimental: the Web Sockets RFC is still a draft. Wt implements up to version 17 of the draft (latest as of November 2011). --> <web-sockets>false</web-sockets> <!-- Redirect message shown for browsers without JavaScript support By default, Wt will use an automatic redirect to start the application when the browser does not support JavaScript. However, browsers are not required to follow the redirection, and in some situations (when using XHTML), such automatic redirection is not supported. This configures the text that is shown in the anchor which the user may click to be redirected to a basic HTML version of your application. --> <redirect-message>Load basic HTML</redirect-message> <!-- Whether we are sitting behind a reverse proxy When deployed behind a reverse proxy (such as Apache or Squid), the server location is not read from the "Host" header, but from the X-Forwarded-For header, if present. --> <behind-reverse-proxy>false</behind-reverse-proxy> <!-- Whether inline CSS is allowed. Some Wt widgets will insert CSS rules in the the inline stylesheet when first used. This can be disabled using this configuration option. Note: some widgets, such as WTreeView and WTableView, dynamically manipulate rules in this stylesheet, and will no longer work properly when inline-css is disabled. --> <inline-css>true</inline-css> <!-- The timeout before showing the loading indicator. The value is specified in ms. --> <indicator-timeout>500</indicator-timeout> <!-- Ajax user agent list Wt considers three types of sessions: - Ajax sessions: use Ajax and JavaScript - plain HTML sessions: use plain old server GETs and POSTs - bots: have clean internal paths and no persistent sessions By default, Wt does a browser detection to distinguish between the first two: if a browser supports JavaScript (and has it enabled), and has an Ajax DOM API, then Ajax sessions are chosen, otherwise plain HTML sessions. Here, you may indicate which user agents should or should not receive an Ajax session regardless of what they report as capabilities. Possible values for 'mode' or "white-list" or "black-list". A white-list will only treat the listed agents as supporting Ajax, all other agents will be served plain HTML sessions. A black-list will always server plain HTML sessions to listed agents and otherwise rely on browser capability detection. Each <user-agent> is a regular expression. --> <user-agents type="ajax" mode="black-list"> <!-- <user-agent>.*Crappy browser.*</user-agent> --> </user-agents> <!-- Bot user agent list Here, you can specify user agents that should be should be treated as bots. Each <user-agent> is a regular expression. --> <user-agents type="bot"> <user-agent>.*Googlebot.*</user-agent> <user-agent>.*msnbot.*</user-agent> <user-agent>.*Slurp.*</user-agent> <user-agent>.*Crawler.*</user-agent> <user-agent>.*Bot.*</user-agent> <user-agent>.*ia_archiver.*</user-agent> <user-agent>.*Twiceler.*</user-agent> </user-agents> <!-- Whether the progressive bootstrap is used. The default bootstrap method first senses whether there is Ajax support, and only then creates the application. The progressive bootstrap method first renders a plain HTML version and later upgrades to an Ajax version. --> <progressive-bootstrap>false</progressive-bootstrap> <!-- Set session-ID cookie In its default (and recommended) configuration, Wt does not rely on cookies for session tracking. Wt has several mechanisms in place to prevent session ID stealing: - for an Ajax session, the session ID is not shown in the URL, avoiding session ID stealing through a referer attack. - in case the session ID is present in the URL (e.g. for a plain HTML session), Wt will redirect links to images or external anchors through an intermediate page that censors the session ID In case of the loss of a session ID, the impact is minimized: - a full page refresh is not supported if the client IP address changes or the user-agent changes - an Ajax update is protected by other state which is not exposed in the URL To still enable a full page refresh when the client IP address changes, an additional cookie may be set which is used only for this purpose, and can be enabled using this setting. --> <session-id-cookie>false</session-id-cookie> <!-- Runtime Properties These properties may be used to adapt applications to their deployment environment. Typical use is for paths to resources that may or may not be shared between several applications. --> <properties> <!-- baseURL property The absolute URL at which the application is deployed (known to the user). This is needed only in two scenarios. a) use of relative URLs in included XHTML When you use relative URLs for images, etc... in literal XHTML fragments (e.g. in WTemplate), which need to resolve against the deployment path of the application. This will not work as expected in the presence of an internal application path. This URL is set as base URL in the HTML, against which relative URLs are resolved so that these work correctly regardless of the internal path. It is also used explicitly in any URL generated by the library. b) widgetset mode deployments Another situation in which you need to define the baseURL is when deploying a widgetset mode application behind a reverse proxy. A widgetset mode application uses only absolute URLs because it may be hosted in a web page from an entirely different domain. By default, no baseURL is specified, in which case Wt will avoid using absolute URLs. Relative URLs passed in API calls will be "fixed" so that they resolve against the location of the application deploy path, even in the presence of an internal path. --> <!-- <property name="baseURL">"http://mysite.com/app</property> --> <!-- resourcesURL property The URL at which the resources/ folder is deployed that comes distributed with Wt and contains auxiliary files used to primarily for styles and themes. The default value is 'resources/' --> <property name="resourcesURL">resources/</property> <!-- extBaseURL property Used in conjunction with Ext:: widgets, and points to the URL of Ext JavaScript and resource files (css, images). See the documentation for the Ext namespace for details. The default value is 'ext/' --> <property name="extBaseURL">ext/</property> <!-- favicon property By default, a browser will try to fetch a /favicon.ico icon from the root of your web server which is used as an icon for your application. You can specify an alternative location by setting this property, or for an individual application entry point by passing a location to WServer::addEntryPoint(). --> <!-- <property name="favicon">images/favicon.ico</property> --> </properties> </application-settings> <!-- Override settings for specific applications. Location refers to physical filesystem location of the application. The application prints this location (which corresponds to argv[0]) to the log file on startup, and this should match exactly. --> <!-- <application-settings location="/var/www/localhost/wt-examples/hello.wt"> </application-settings> --> </server>