= DWiki's configuration file DWiki's configuration file has a simple format. Blank lines and comments (any line that has a '_#_' as the first non-whitespace character) are just skipped, and everything else is interpreted as a configuration directive to set. Directives can be continued with additional lines by starting the continued lines with whitespace (as in email headers). The continuation whitespace will be turned into a single space in the final, un-continued version of the line. Configuration directives have optional values, which are separated from the configuration item by whitespace. (Whitespace within the value is not interpreted, although trailing whitespace is removed from lines.) So an example set of configuration file lines might be: root /web/data/dwiki pagedir pages tmpldir templates wikiname TestWiki wikititle Testing Wiki DWiki requires and uses some configuration directives. Unused configuration directives are not errors; all configuration directives (and their values) become part of the context variables available for template _${...}_ expansion. To simplify life, configuration directives are put through a canonicalization process. This operates like so: * if ~~root~~ is specified, it must be an absolute path to a directory. * if something ending in ~~dir~~ or ~~file~~ is not an absolute path and ~~root~~ is defined, DWiki sees if tacking on ~~root~~ results in the right sort of thing. * any directive ending in ~~dir~~ or ~~file~~ must wind up (possibly after the ~~root~~ prefixing above) being an absolute path to a directory or a file respectively. * if ~~root~~ is defined and ~~pagedir~~, ~~tmpldir~~, or ~~rcsdir~~ are not defined, DWiki sees if directories called _pages_, _templates_, or _rcsroot_ exist under ~~root~~ and if so sets up the configuration directives appropriately. Required configuration directives are: _pagedir_, _tmpldir_, _wikiname_, and _rooturl_. This means that with defaulting, the minimal DWiki configuration file is: > root /some/where > rooturl /some/thing > wikiname SomeThing == Configuration directives and their meanings: === Core where-to-find-things configuration: - _root_: If present, this is taken as the root directory that further configuration directives can specify paths relative to. - _pagedir_: The root directory of the page hierarchy. (Required.) - _tmpldir_: The root directory of the template hierarchy. (Required; cannot be the same as _pagedir_.) - _usercs_: Support checking RCS files for things like page history, page locker, and so on. Whether or not _usercs_ is set, DWiki refuses to serve files ending with _,v_ or in RCS directories; see InvalidPageNames. As a result, setting _usercs_ is only necessary if you want page history et al to be visible to people visiting the DWiki; you can use RCS yourself on page files without setting it. - _rcsroot_: The root directory of the separate RCS file storage hierarchy; used only if _usercs_ is on. \\ Normally, RCS files are expected to be in _RCS_ directories under _pagedir_, where basic RCS commands put them (if you make those directories; DWiki requires you to work this way). With this directive on, the RCS _,v_ files for files under _pagedir_ are instead found under here, in a mirror of the directory structure in _pagedir_, so you have *pagedir*_/foo/bar_ and *rcsdir*_/foo/bar,v_. This keeps _pagedir_ neater at the expense of requiring some scripting support. === Web configuration - _wikiname_: The short, one-word name of this DWiki. You probably want to have a CamelCased name. This shows up as the name of the breadcrumbs, among other places. (Required.) - _wikititle_: The full, multi-word title of this DWiki. - _wikiroot_: The front page of the DWiki; the page you get redirected to when you request the DWiki's root. If this isn't set or doesn't exist, DWiki tries _wikiname_'s value as a page name; if that doesn't work, people see the DWiki's root directory in a directory view. - _rooturl_: The URL of the directory that is the root of the DWiki instance; use '/' to mean 'the root of the web server'. - _publicurl_: If set, DWiki puts this directory's URL on the front of DWiki URLs instead of _rooturl_. - _staticdir_: The directory to serve static files from. DWiki *only serves files* from this hierarchy; requests for a directory will fail. - _staticurl_: The URL of the directory that is the root of static files. If _staticurl_ doesn't start with a slash, it's taken as a subdirectory of _rooturl_. (Requires _staticdir_ to be set.) - _charset_: If set, DWiki claims that all text/html and text/plain content it generates is in this character set in HTTP replies. Normally 'UTF-8' these days. If unset, DWiki does not label text/html and text/plain HTTP replies with character set information. ~~You should set this to 'UTF-8'~~. Really. It shouldn't even be optional. - _cssurlprefix_: This is technically not a DWiki configuration directive as such because it isn't interpreted by the program. Instead it's used by the standard _html/css_ template as one option for where to find DWiki's standard CSS file, _dwiki.css_. If this is set it's the URL of a directory (without a trailing slash). If this is not set, the _html/css_ template assumes that _dwiki.css_ can be found at _${staticurl}/dwiki.css_. It's more efficient to serve _dwiki.css_ outside of DWiki itself, since it's a static file. Note that various parts of DWikiText rendering do not look right if the CSS is missing (in particular, all sorts of tables are likely to look bad). ==== DWiki URL to file mapping When DWiki gets a request for a URL, it tries to turn it into a request for something under either _staticurl_ (if defined) or _rooturl_; whatever is left after subtracting the appropriate thing is the path being served relative to _staticdir_ or _pagedir_. _staticurl_ is checked first, so it can be a subset of the URL space available under _rooturl_. For safety reasons, DWiki only tries to process a request if the request's URL falls under either _staticurl_ or _rooturl_. If DWiki receives a request for anything outside those two, something is clearly wrong and it generates a terse error page. When it generates URLs for DWiki pages DWiki normally puts _rooturl_ on front (as a directory). However, if you set _publicurl_ DWiki puts that on the front instead. This is useful if for internal reasons you receive requests with their URLs rewritten to something users shouldn't (or can't) use. The case ChrisSiebenmann knows is Apache with URL aliases and the DWiki CGI-BIN being run via suexec. === Authentication See [[Authentication]] for more information on the authentication system. - _authfile_: Where DWiki can find user / password / group information for the DWiki's users. If this is set, the DWiki has authentication. - _defaultuser_: If set, all otherwise not authenticated connections get to be this user, *if* the user is in _authfile_. This should be used carefully, as it makes *all* requests to the DWiki be authenticated (since they all have a user, if even only the default user). If this is set, the username it is set to is said to be the 'guest user'. - _global-authseed_: This is a special magic token to make it harder to brute-force people's DWiki passwords in some situations. It can be any value and should be kept secret. - _global-authseed-file_: This is the file to read _global-authseed_ from, if it is set. The file has no special format, but should contain some randomness and its contents should be kept secret. - _authcookie-path_: This controls the 'path=' value for the authentication cookies generated by DWiki. If not set to a value, we use the root URL; otherwise we use the value straight. If it is not set, authentication cookes have no explicit 'path=' setting. ChrisSiebenmann has come to believe that you don't want to set this, and it remains as a vestigial remnant. - _logins-report-bad_: If present in the configuration file, DWiki will log the username (or at least the first 50 characters of it) for bad logins with unknown usernames. This is not necessarily a good idea but at one point was interesting to track what form-stuffing spammers were doing. === Comments - _commentsdir_: The root directory for storing comments in. The only place DWiki writes permanent data to. - _comments-on_: Enable commenting in this DWiki. This requires that _commentsdir_ be defined and that authentication be enabled. - _comments-in-normal_: Your standard templates display comments on the normal view of the page instead of the 'showcomments' view. - _remap-normal-to-showcomments_: DWiki will remap the 'normal' view for pages to the 'showcomments' view, thereby implementing _comments-in-normal_ without you needing to change the standard templates. If you want to enable anonymous comments you should create a _guest_ user in the DWiki _authfile_ and then set _guest_ as the _defaultuser_. (Well, you can use the username of your choice, but _guest_ is conventional.) === Caching DWiki can optionally cache the results of page generation to speed up response time. See [[Caching]] for a longer discussion. - _cachedir_: The root directory for storing the caches. It should not be used for anything else (ie, not it should not also be _pagedir_, _tmpldir_, or _commentsdir_). DWiki will write scratch files to here. - _cache-warn-errors_: Log warnings about cache store errors. (These are non-fatal but indicate that your cache isn't caching.) - _render-cache_: Enable caching the results of selected renderers and renderer components. (Requires _cachedir_ to be set.) - _render-heuristic-ttl_: The TTL of renderer cache entries with heuristic validators, in seconds. The default value is an hour. - _render-anonymous-only_: Use the renderer cache only for the guest user or for connections that are not authenticated. - _render-heuristic-flagged-ttl_: The TTL of renderer cache entries that have explicit invalidation (aka 'flagged' cache entries), in seconds. The default value is 48 hours, as explicit invalidation is considered safer than heuristic invalidation. - _render-heuristic-flagged-delta_: In order to lessen the chance of races between renderer cache invalidation and renderer cache regeneration, flagged cache entries must be at least this many seconds more recent than the invalidation marker (if it exists). Defaults to 30 seconds. - _bfc-cache-ttl_: Enable a brute force page cache of complete pages with a TTL of this many seconds. (Requires _cachedir_ to be set.) - _bfc-time-min_: A complete page will be cached if it took at least this much of a second to be generated. Defaults to 0.75 of a second. - _bfc-load-min_: A complete page will be cached if the load average is at least this high. No default; the BFC normally doesn't look at the load average at all. - _bfc-time-triv_: Regardless of the setting of _bfc-load-min_, don't bother looking at the load average if the page took at most this long to generate. Defaults to 0.09 of a second. - _bfc-atom-ttl_: Use this TTL for Atom syndication requests, instead of the normal one. - _bfc-atom-nocond-ttl_: Use this TTL for Atom syndication requests that are not using conditional GET, and also force the caching of the results of these requests regardless of the load. - _bfc-skip-robots_: If set, this is a list of User-Agent substrings (formatted as for _bad-robots_, see later) for robots that should not cause entries to be put into the BFC. - _imc-cache-entries_: Enable an in-memory cache of complete pages with this many entries. The IMC skips all pages that the BFC skips. The IMC is only meaningful if the same process handles more than one request, so by default it is only enabled if DWiki knows that it is running using _dwiki-scgi.py_ as a preforking SCGI server. - _imc-force-on_: Force the IMC on even if DWiki would not enable it. You probably only want to use this if you are running DWiki as a WSGI application inside a preforking WSGI server such as uWSGI. - _imc-cache-ttl_: The TTL, in seconds, of entries in the in-memory cache; must be provided if _imc-cache-entries_ is. - _imc-resp-max-size_: The maximum size (in kilobytes) of pages that will be cached in the in-memory cache. The default value is 256 KB. - _slow-requests-by_: Delay all requests by this much, in fractional seconds. Normally used only for testing BFC. In practice some degree of caching is mandatory for decent performance once your DWiki gets big enough and so it's recommended that you turn on _render-cache_ and _bfc-cache-ttl_ unless you have a good reason to do otherwise. Turn on _imc-cache-entries_ and _imc-cache-ttl_ if you're using SCGI. === Syndication feed controls - _atomfeed-display-howmany_: How many items at most an Atom feed should display. If set, it must be a positive integer; if not set, _atom::pages_ and _atom::comments_ use a default of 100 items. - _feed-max-size_: How many kilobytes _atom::pages_ or _atom::comments_ should try to limit their output to. If set, either stops adding new entries (regardless of how many entries have been processed already) once they have generated that many kilobytes or more of output. Because of the 'or more' clause, you should allow for a safety margin. If unset, syndication feeds are not size-limited. - _feed-max-size-ips_: If set, this is a whitespace separated list of IPv4 addresses, tcpwrappers style IPv4 address prefixes (eg '_66.150.15._'), or IPv4 CIDRs (eg '_66.150.15.0/25_') that _feed-max-size_ applies to. Syndication requests from any other addresses are not size-limited. If unset, _feed-max-size_ applies to all syndication requests, regardless of what IP address makes the request. This option can be specified multiple times; if so, all the addresses are merged together. - _feed-start-time_: If set, pages older than this time will not appear in Atom feeds, which is handy if you want to move a DWiki, redirect the old URLs, and not flood people's Atom feeds (because the Atom for pages is the page's full URL unless you've set _atomfeed-tag_). The value can be specified either as an integer Unix timestamp, as 'YEAR-MO-DA [HH:MM[:SS]]', 'YEAR/MO/DA', or an Atom format time string, and is always in *local* time (even when specified as an Atom format time string; sorry). - _atomfeed-tag_: If set, the _atom::pagetag_ renderer will use it to generate Atom s for pages in the format :/. This should normally be set to a _tag:_-based URI; see [[here http://web.archive.org/web/20110902122124/http://diveintomark.org/archives/2004/05/28/howto-atom-id]] for a discussion. - _atomfeed-tag-time_: If set, the _atom::pagetag_ renderer will only generate tag-formatted Atom s for pages more recent than this time. This can be used to make a graceful transition into tag-based Atom s for an existing DWiki (and then, with _feed-start-time_, to graceful move it). This has the same time format as _feed-start-time_. - _atomfeed-virt-only-adv_: If set, restrict what Atom page feeds are advertised for [[virtual directories VirtualDirectory]]. If we are displaying a vdir and it is not a listed type, we advertise the Atom feed for the real directory instead (eg, for 'blog/2007/10/' the Atom feed advertised would be for 'blog/'). This is a space-separated list of vdir types; the allowed types are _latest_, _oldest_, _range_, _calendar_, and the _calendar_ subtypes _year_, _month_, and _day_. - _atomfeed-virt-only-in_: If set, restrict what virtual directories allow Atom page feed requests. A disallowed _latest_ or _range_ feed request is (permanently) redirected to the real directory's feed; other disallowed feeds get 404 responses. The format and list of vdir types is the same as for _atomfeed-virt-only-adv_. If this is set, it becomes _atomfeed-virt-only-in_'s default value. If both are set, this should be a superset of _atomfeed-virt-only-adv_'s value; otherwise DWiki will advertise feeds that it will refuse requests for. You should normally allow feeds for _latest_ because this gives people a way of controlling how large a feed they pull from you; they can use, eg, 'blog/latest/10/?atom' to pull only a ten-entry feed instead of your full-sized feed. These two directives don't change or affect what Atom comment feeds are advertised or allowed; they affect only Atom feeds for pages. === Other features: - _alias-path_: This sets the DWiki path for the third place to try to find CamelCase links in (see [[Formatting]]). This allows a DWiki to have a collection of CamelCase names for things that are globally usable but that don't clutter up the DWiki root directory. \\ This is a *DWiki* path, not a filesystem path (and is implicitly always an absolute DWiki path). The conventional value is _Aliases_. - _search-on_: enables searching. If it has the value 'authenticated', only authenticated users can search. Note that if you have a guest user set, all users are authenticated. - _blog-display-howmany_: How many items the _blog::blog_ renderer should try to restrict most pages it displays to. If set, it must be a positive integer; if not set, _blog::blog_ uses a default. - _canon-hosts_: If set, this is a space-separated list of canonical hostnames for this DWiki. If a request has a _Host:_ header that is not in this list, DWiki immediately serves up a redirection to the first hostname in the list (or _canon-host-url_, if that is set), which is assumed to be the preferred hostname. - _canon-host-url_: If set, this is the canonical URL for the host of this DWiki (*without* the ending _/_, but including http or https and the port if necessary). DWiki will generate redirects and absolute URLs that use this URL. If _canon-hosts_ is also set, this should be the full version of the first entry in _canon-hosts_. (This is primarily useful in some hopefully unusual situations involving HTTP-to-HTTPS transitions.) - _literal-words_: If set, this is a list of strings, separated by '_ | _' (space, |, space), that will be rendered literally and not considered to contain markup, as if each of them had been specified in '_.pn lit _' processing note directives. === Special oddities - _dump-req-times_: Report the amount of time that requests took to standard error. This is set by the standard _-T_ option. - _dump-atom-reqs_: Report on Atom requests to standard error. This is set by the standard _-A_ option. - _stamp-messages_: Add timestamp and client IP address to messages reported by the above two options. This is set by the standard _--stamp_ option. These are documented because you might want to set them directly if you're running DWiki as a WSGI application inside some standard WSGI server (such as uWSGI, Apache's ``mod_wsgi'', or gUnicorn). === Dealing with bad clients: - _bad-robots_: If set, this is a list of User-Agent substrings, separated by '_ | _' (space, |, space), for robots that should get permission denied responses when they try to fetch pages in various views that no robot should be fetching. Currently the list of bad views is atom, atomcomments, source, and writecomment, all of which are typically fetched by robots that don't respect _rel="nofollow"_ on links. - _no-ua-is-bad-robot_: If set, any request with a missing User-Agent header is considered to be from a bad robot. - _banned-robots_: If set, this is a list of User-Agent substrings (formatted as for _bad-robots_) for robots that should get permission denied responses on *all* requests. - _banned-ips_: If set, this is a list of IPv4 addresses, tcpwrapper style IP prefixes, or CIDRs (as for _feed-max-size-ips_) for addresses that will get access denied responses for all requests. It can be specified multiple times. - _banned-comment-ips_: If set, this is like _banned-ips_ but only applies to attempts to write comments. - _bad-robot-ips_: If set, this is like _banned-ips_ but only applies to requests that try to fetch pages in various views that no robot should be fetching (as in _bad-robots_). Under normal circumstances it's more efficient to use your web server's access controls to totally ban IP addresses and bad user-agents; your web server usually has faster code for this and you don't have to get DWiki involved in the process. _banned-robots_ and _banned-ips_ exist because this is not always possible.