4 The Wt configuration file manages, for every Wt application, settings
5 for session management, debugging, directory for runtime information
6 such as session sockets, and some security settings.
8 Settings may be specified globally, or for a single application path.
10 The path should be as configured in the Wt build process, where it
11 defaults to /etc/wt/wt_config.xml. It can be overridden in the environment
12 variable WT_CONFIG_XML, or with the -c startup option of wthttp.
14 The values listed here are the default values, which are used when the
15 declaration is missing or no configuration file is used.
20 <!-- Default application settings
22 The special location "*" always matches. See below for an example
23 of settings specific to a single application.
25 <application-settings location="*">
27 <!-- Session management. -->
29 <!-- Every session runs within a dedicated process.
31 This mode guarantees kernel-level session privacy, but as every
32 session requires a seperate process, it is also an easy target
33 for DoS attacks if not shielded by access control.
35 Note: currently only supported by the wtfcgi and wthttp
41 <max-num-sessions>100</max-num-sessions>
45 <!-- Multiple sessions within one process.
47 This mode spawns a number of processes, and sessions are
48 allocated randomly to one of these processes (you should not
49 use this for dynamic FCGI servers, but only in conjunction
50 with a fixed number of static FCGI servers.
52 This requires careful programming, as memory corruption in one
53 session will kill all of the sessions in the same process. You
54 should debug extensively using valgrind. Also, it is your
55 responsibility to keep session state not interfering and
58 On the other hand, sessions are inexpensive, and this mode
59 suffers far less from DoS attacks than dedicated-process mode.
60 Use it for non-critical and well-debugged web applications.
62 Note: the wthttp connector will ignore the num-processes
63 setting and use only process.
66 <num-processes>1</num-processes>
69 <!-- Session tracking strategy.
72 Auto: cookies is available, otherwise URL rewriting
73 URL: only URL rewriting
75 It is recommended to stick to URL rewriting for session
76 tracking as this is more secure (it avoids the risk of attacks
77 like CSRF or BREACH), and also provides proper support for
78 concurrent sessions in a single browser.
80 <tracking>URL</tracking>
82 <!-- How reload should be handled.
84 When reload should (or rather, may) spawn a new session, then
85 even in the case cookies are not used for session management,
86 the URL will not be cluttered with a sessionid.
87 However, WApplication::refresh() will never be called.
89 <reload-is-new-session>true</reload-is-new-session>
91 <!-- Session timeout (seconds).
93 When a session remains inactive for this amount of time, it is
96 <timeout>600</timeout>
98 <!-- Server push timeout (seconds).
100 When using server-initiated updates, the client uses
101 long-polling requests. Proxies (including reverse
102 proxies) are notorious for silently closing idle
103 requests; the client therefore cancels the request
104 periodically and issues a new one. This timeout sets
107 <server-push-timeout>50</server-push-timeout>
108 </session-management>
110 <!-- Settings that apply only to the FastCGI connector.
112 To configure the wthttp connector, use command line options, or
113 configure default options in /etc/wt/wthttpd
118 If debugging is enabled and this path is not empty, then valgrind
119 will be started for every shared process, or for every session
120 which has ?debug appended to the command line.
122 The variable is slighly misnamed. Not only a path can be set,
123 but also options, like for example:
125 /usr/bin/valgrind - -leak-check=full
127 <valgrind-path></valgrind-path>
131 Path used by Wt to do session management.
133 <run-directory>/var/run/wt</run-directory>
135 <!-- Number of threads per process
137 This configures the size of the thread pool. You may
138 want to change this value if you would like to support
139 reentrant event loops, where you block one event loop
140 using WDialog::exec() or related static
141 methods. Everytime you enter such an event loop, one
142 thread is blocked, and therefore the total number of
143 sessions that reliably can do this is limited to the
144 number of thread you have (minus one to unblock).
146 For the built-in http connector, there is a similar
147 config option that is specified in the whttpd config
148 file or on the command line (-t).
150 The default value is 1.
152 <num-threads>1</num-threads>
156 <!-- Settings that apply only to the MS IIS ISAPI connector.
158 To configure the wthttp connector, use command line options, or
159 configure default options in /etc/wt/wthttpd
162 <!-- Number of threads per process
164 This configures the number of threads that will be used
165 to handle Wt requests. The IIS internal threads are never
166 used to do any processing; all requests are forwarded to
167 be handled in this threadpool. Rather than to configure a
168 so-called 'web-garden' in IIS, increase this number. The
169 ISAPI connector will not work correctly when a web-garden
172 You may want to change this value if you would like to
173 support more reentrant event loops, where you block one
174 event loop using WDialog::exec() or related static
175 methods. Everytime you enter such an event loop, one
176 thread is blocked, and therefore the total number of
177 sessions that reliably can do this is limited to the
178 number of thread you have (minus one to unblock).
180 You may also want to increase this number if your Wt
181 application is regularly waiting for IO (databases, network,
182 files, ...). If this number is too low, all threads could
183 be waiting for IO operations to complete while your CPU
184 is idle. Increasing the number of threads may help.
186 Computing intensive applications may also increase this number,
187 even though it is better to offload computations to a helper
188 thread and user server push or a WTimer to check for
189 completion of the task in order to keep your GUI responsive
190 during the computations.
192 The default value is 10.
194 <num-threads>10</num-threads>
196 <!-- Maximum Request Size spooled in memory (Kb)
198 Normally, Wt keeps incoming requests (POST data) in memory.
199 However, malicious users could send a big POST and as such
200 use up all memory of your HTTP server. With this parameter,
201 you tune how big a request can be before Wt spools it in a
202 file before processing it. Legitimate big POST messages may
203 occur when users are expected to upload files.
205 See also max-request-size.
207 The default value is 128K, which is more than enough for
208 any interactive Wt event.
210 <max-memory-request-size>128</max-memory-request-size>
213 <!-- Javascript debug options
216 - naked: JavaScript errors are not caught at all
217 - false: JavaScript errors are caught and a simple error message
218 is printed to indicate that something is terribly wrong
219 - stack: equivalent to 'false'
220 - true: JavaScript errors are rethrown after server-side logging
222 Unless the value is 'naked',
223 WApplication::handleJavaScriptError() is called which by
224 default logs the error and terminates the session.
230 When the log file is empty, or omitted, logging is done to
231 stderr. This may end up in the web server error log file
232 (e.g. for apache + fastcgi module), or on stderr (e.g. for
235 <log-file></log-file>
237 <!-- Logger configuration
239 This configures the logger. With the default configuration,
240 everything except for debugging messages are logged.
242 The configuration is a string that defines rules for
243 enabling or disabling certain logging. It is a white-space
244 delimited list of rules, and each rule is of the form:
246 [-]level : enables (or disables) logging of messages of
247 the given level; '*' is a wild-card that matches all
250 [-]level:scope : enables (or disables) logging of
251 messages of the given level and scope; '*' is a wild-card
252 that matches all levels or scopes. The default
253 configuration is "* -debug", i.e. by default everything
254 is logged, except for "debug" messages.
258 "* -debug debug:wthttp": logs everything, including
259 debugging messages of scope "wthttp", but no other
262 "* -info -debug": disables logging of info messages
263 in addition to debugging messages.
265 Note debugging messages are only emitted when debugging
266 has been enabled while building Wt.
268 <log-config>* -debug</log-config>
270 <!-- Maximum HTTP request size (Kb)
272 Maximum size of an incoming POST request. This value must be
273 increased when the user is allowed to upload files.
275 <max-request-size>128</max-request-size>
277 <!-- Session id length (number of characters) -->
278 <session-id-length>16</session-id-length>
280 <!-- DoS prevention: limit plain HTML sessions
282 This is a simple measure which avoids Denial-of-Service
283 attacks on plain HTML sessions, which are easy to mount in
284 particular in the case of progressive bootstrap mode.
286 This setting may be used to keep the ratio of plain HTML
287 versus Ajax sessions under a certain ratio. Typically, most
288 of your sessions will be Ajax sessions, and only a tiny
289 fraction (e.g. less than 5%) will be plain HTML
290 sessions. This ratio is only enforced when more than 20 sessions
293 <plain-ajax-sessions-ratio-limit>1</plain-ajax-sessions-ratio-limit>
295 <!-- DoS prevention: adds a puzzle to validate Ajax sessions
297 This is a simple measure which avoids Denial-of-Service
298 attacks on Ajax sessions.
300 When enabled, a puzzle needs to be solved in the first Ajax
301 request which eliminates agents that do not build a proper
304 <ajax-puzzle>false</ajax-puzzle>
306 <!-- Do strict serialization of events.
308 By default events are queued at the client-side, and
309 transmitted to the server so that at any time only one
310 request/response is pending. This scheme has a quality that
311 resembles TCP: on a low-latency link you allow the
312 transmission of many smaller requests, while on a high
313 latency link, events will be propagated less often, but in
316 In any case, this scheme does not drop events, no matter
317 how quickly they are generated.
319 In rare cases, the scheme may result in unwanted behaviour,
320 because the client-side is allowed to be slighly out of
321 sync at the time an event is recorded with the server-side
322 (and more so on high-latency links). The drastic
323 alternative is to discard events while a response is
324 pending, and can be configured by setting this option to
327 <strict-event-serialization>false</strict-event-serialization>
329 <!-- Enables web socket.
331 By default Ajax and long polling are used to communicate
332 between server and browser.
334 By enabling web socket support, if the browser supports
335 WebSockets, then WebSocket is the protocol used for
336 communication between client and server. WebSockets are
337 currently only supported by the built-in httpd Connector,
338 which acts as both an HTTP and WebSocket server. The WebSocket
339 protocol is intentionally not compatible with HTTP, through
340 a special hand-shake mechanism, and requires
341 that all (reverse) proxy servers also have explicit support
344 This feature is still experimental: the Web Sockets RFC is
345 still a draft. Wt implements up to version 17 of the draft
346 (latest as of November 2011).
348 <web-sockets>false</web-sockets>
350 <!-- Enables the detection of webgl-capabilites.
352 When this is enabled, the browser will try to create a
353 webgl-context when loading to verify that it is possible. This
354 is neccesary when using WGLWidget.
356 This can take up some load time. When your application does not
357 use WGLWidget, this option can be set to false. It will improve
358 the initial loading time of the web-application.
360 <webgl-detection>true</webgl-detection>
362 <!-- Redirect message shown for browsers without JavaScript support
364 By default, Wt will use an automatic redirect to start the
365 application when the browser does not support
366 JavaScript. However, browsers are not required to follow
367 the redirection, and in some situations (when using XHTML),
368 such automatic redirection is not supported.
370 This configures the text that is shown in the anchor which
371 the user may click to be redirected to a basic HTML version
374 <redirect-message>Load basic HTML</redirect-message>
376 <!-- Whether we are sitting behind a reverse proxy
378 When deployed behind a reverse proxy (such as Apache or Squid),
379 the server location is not read from the "Host" header,
380 but from the X-Forwarded-For header, if present.
382 This option is required to make e.g. clientAddress() return the
385 <behind-reverse-proxy>false</behind-reverse-proxy>
387 <!-- Whether inline CSS is allowed.
389 Some Wt widgets will insert CSS rules in the the inline
390 stylesheet when first used. This can be disabled using this
391 configuration option.
393 Note: some widgets, such as WTreeView and WTableView,
394 dynamically manipulate rules in this stylesheet, and will
395 no longer work properly when inline-css is disabled.
397 <inline-css>true</inline-css>
399 <!-- The timeout before showing the loading indicator.
401 The value is specified in ms.
403 <indicator-timeout>500</indicator-timeout>
405 <!-- The timeout for processing a double click event.
407 The value is specified in ms.
409 <double-click-timeout>200</double-click-timeout>
411 <!-- Ajax user agent list
413 Wt considers three types of sessions:
414 - Ajax sessions: use Ajax and JavaScript
415 - plain HTML sessions: use plain old server GETs and POSTs
416 - bots: have clean internal paths and no persistent sessions
418 By default, Wt does a browser detection to distinguish between
419 the first two: if a browser supports JavaScript (and has it
420 enabled), and has an Ajax DOM API, then Ajax sessions are chosen,
421 otherwise plain HTML sessions.
423 Here, you may indicate which user agents should or should
424 not receive an Ajax session regardless of what they report as
427 Possible values for 'mode' or "white-list" or "black-list". A
428 white-list will only treat the listed agents as supporting Ajax,
429 all other agents will be served plain HTML sessions. A black-list
430 will always server plain HTML sessions to listed agents and
431 otherwise rely on browser capability detection.
433 Each <user-agent> is a regular expression.
435 <user-agents type="ajax" mode="black-list">
436 <!-- <user-agent>.*Crappy browser.*</user-agent> -->
439 <!-- Bot user agent list
441 Here, you can specify user agents that should be should be
444 Each <user-agent> is a regular expression.
446 <user-agents type="bot">
447 <user-agent>.*Googlebot.*</user-agent>
448 <user-agent>.*msnbot.*</user-agent>
449 <user-agent>.*Slurp.*</user-agent>
450 <user-agent>.*Crawler.*</user-agent>
451 <user-agent>.*Bot.*</user-agent>
452 <user-agent>.*ia_archiver.*</user-agent>
453 <user-agent>.*Twiceler.*</user-agent>
456 <!-- Configures different rendering engines for certain browsers.
458 Currently this is only used to select IE7 compatible rendering
459 engine for IE8, which solves problems of unreliable and slow
460 rendering performance for VML which Microsoft broke in IE8.
462 Before 3.3.0, the default value was IE8=IE7, but since 3.3.0
463 this has been changed to an empty string (i.e. let IE8 use the
464 standard IE8 rendering engine) to take advantage of IE8's
465 improved CSS support. If you make heavy use of VML, you may need
466 to revert to IE8=IE7.
468 <UA-Compatible></UA-Compatible>
470 <!-- Configures whether the progressive bootstrap method is used.
472 The default bootstrap method first senses whether there is Ajax
473 support, and only then creates the application.
475 The progressive bootstrap method first renders a plain HTML
476 version and later upgrades to an Ajax version.
478 (Not to be confused with the Twitter Bootstrap theme)
480 <progressive-bootstrap>false</progressive-bootstrap>
482 <!-- Set session-ID cookie
484 In its default (and recommended) configuration, Wt does not
485 rely on cookies for session tracking.
487 Wt has several mechanisms in place to prevent session ID stealing:
488 - for an Ajax session, the session ID is not shown in the URL,
489 avoiding session ID stealing through a referer attack.
490 - in case the session ID is present in the URL (e.g. for a plain
491 HTML session), Wt will redirect links to images or external
492 anchors through an intermediate page that censors the session ID
494 In case of the loss of a session ID, the impact is minimized:
495 - a full page refresh is not supported if the client IP address
496 changes or the user-agent changes
497 - an Ajax update is protected by other state which is not exposed
500 To still enable a full page refresh when the client IP address
501 changes, an additional cookie may be set which is used only
502 for this purpose, and can be enabled using this setting.
504 <session-id-cookie>false</session-id-cookie>
506 <!-- Configure cookie checks
508 By default, Wt will test for cookie support using JavaScript.
509 Because cookie manipulation from JavaScript is a common security
510 risk vector, some prefer to disable these checks.
513 <cookie-checks>true</cookie-checks>
515 <!-- Configure meta headers
517 The user-agent allows optional filtering based on the
518 user-agent, using a regular expression. You can have multiple
519 set-meta-headers definitions.
522 <meta-headers user-agent=".*MSIE.*">
523 <meta name="robots" content="noindex" />
526 <!-- Runtime Properties
528 These properties may be used to adapt applications to their
529 deployment environment. Typical use is for paths to resources
530 that may or may not be shared between several applications.
533 <!-- baseURL property
535 The absolute URL at which the application is deployed
536 (known to the user). This is needed only in two scenarios.
538 a) use of relative URLs in included XHTML
540 When you use relative URLs for images, etc... in
541 literal XHTML fragments (e.g. in WTemplate), which need
542 to resolve against the deployment path of the
543 application. This will not work as expected in the
544 presence of an internal application path. This URL is
545 set as base URL in the HTML, against which relative
546 URLs are resolved so that these work correctly
547 regardless of the internal path. It is also used
548 explicitly in any URL generated by the library.
550 b) widgetset mode deployments
552 Another situation in which you need to define the baseURL is
553 when deploying a widgetset mode application behind a reverse
554 proxy. A widgetset mode application uses only absolute URLs
555 because it may be hosted in a web page from an entirely
558 By default, no baseURL is specified, in which case Wt will
559 avoid using absolute URLs. Relative URLs passed in API calls
560 will be "fixed" so that they resolve against the location of the
561 application deploy path, even in the presence of an
564 <!-- <property name="baseURL">"http://mysite.com/app</property> -->
566 <!-- resourcesURL property
568 The URL at which the resources/ folder is deployed that
569 comes distributed with Wt and contains auxiliary files
570 used to primarily for styles and themes.
572 The default value is 'resources/'
574 <property name="resourcesURL">resources/</property>
576 <!-- extBaseURL property
578 Used in conjunction with Ext:: widgets, and points to the
579 URL of Ext JavaScript and resource files (css, images).
580 See the documentation for the Ext namespace for details.
582 The default value is 'ext/'
584 <property name="extBaseURL">ext/</property>
586 <!-- favicon property
588 By default, a browser will try to fetch a /favicon.ico icon
589 from the root of your web server which is used as an icon
590 for your application. You can specify an alternative location
591 by setting this property, or for an individual application
592 entry point by passing a location to WServer::addEntryPoint().
594 <!-- <property name="favicon">images/favicon.ico</property> -->
597 </application-settings>
600 <!-- Override settings for specific applications.
602 Location refers to physical filesystem location of the
603 application. The application prints this location (which
604 corresponds to argv[0]) to the log file on startup, and this
605 should match exactly.
608 <application-settings
609 location="/var/www/localhost/wt-examples/hello.wt">
610 </application-settings>