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.

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.)
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.

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

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).
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.

Comments

commentsdir: The root directory for storing comments in. The only place DWiki writes 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.

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.
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.
render-anonymous-only: Use the render cache only for the guest user or for connections that are not authenticated.
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.
slow-requests-by: Delay all requests by this much, in fractional seconds. Normally used only for testing BFC.

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.
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.
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.
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 IP addresses or tcpwrappers style IP address prefixes (eg, '66.150.15.') 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.
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, which is assumed to be the preferred hostname.
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.