Subdirectories: NewFeatures.
2013-09-12
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 WikiDWiki 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
, orrcsroot
exist under root and if so sets up the configuration directives appropriately.Required configuration directives are:
pagedir
,tmpldir
,wikiname
, androoturl
. This means that with defaulting, the minimal DWiki configuration file is:root /some/where rooturl /some/thing wikiname SomeThingConfiguration 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, settingusercs
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 inRCS
directories underpagedir
, 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 underpagedir
are instead found under here, in a mirror of the directory structure inpagedir
, so you have pagedir/foo/bar
and rcsdir/foo/bar,v
. This keepspagedir
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 ofrooturl
. (Requiresstaticdir
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, thehtml/css
template assumes thatdwiki.css
can be found at${staticurl}/dwiki.css
. It's more efficient to servedwiki.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) orrooturl
; whatever is left after subtracting the appropriate thing is the path being served relative tostaticdir
orpagedir
.staticurl
is checked first, so it can be a subset of the URL space available underrooturl
.For safety reasons, DWiki only tries to process a request if the request's URL falls under either
staticurl
orrooturl
. 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 setpublicurl
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 DWikiauthfile
and then setguest
as thedefaultuser
. (Well, you can use the username of your choice, butguest
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
, orcommentsdir
). 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
andbfc-cache-ttl
unless you have a good reason to do otherwise. Turn onimc-cache-entries
andimc-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
andatom::comments
use a default of 100 items.feed-max-size
- How many kilobytes
atom::pages
oratom::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
') thatfeed-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 <id> 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 <id>s for pages in the format <tag>:/<page path>. This should normally be set to atag:
-based URI; see here for a discussion.atomfeed-tag-time
- If set, the
atom::pagetag
renderer will only generate tag-formatted Atom <id>s for pages more recent than this time. This can be used to make a graceful transition into tag-based Atom <id>s for an existing DWiki (and then, withfeed-start-time
, to graceful move it). This has the same time format asfeed-start-time
.
atomfeed-virt-only-adv
- If set, restrict what Atom page feeds are advertised for virtual directories. 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 thecalendar
subtypesyear
,month
, andday
.atomfeed-virt-only-in
- If set, restrict what virtual directories allow Atom page feed requests. A disallowed
latest
orrange
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 foratomfeed-virt-only-adv
. If this is set, it becomesatomfeed-virt-only-in
's default value. If both are set, this should be a superset ofatomfeed-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 isAliases
.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 (orcanon-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. Ifcanon-hosts
is also set, this should be the full version of the first entry incanon-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 <whatever>
' 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 respectrel="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 inbad-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
andbanned-ips
exist because this is not always possible.