#
#	quickie - a small fast C++ Wiki Wiki
#	Copyright (C) 2005 Peter Miller
#
#	This program is free software; you can redistribute it and/or modify
#	it under the terms of the GNU General Public License as published by
#	the Free Software Foundation; either version 2 of the License, or
#	(at your option) any later version.
#
#	This program is distributed in the hope that it will be useful,
#	but WITHOUT ANY WARRANTY; without even the implied warranty of
#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#	GNU General Public License for more details.
#
#	You should have received a copy of the GNU General Public License
#	along with this program; if not, write to the Free Software
#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
#
# MANIFEST: var/manual/configuration.wiki
#
! Configuration Guide
The configuration file is used to control various aspects of wiki pages,
including their location and their appearance.

!! The configuration file
The Quickie configuration file is called "{{quickie.conf}}", but which
directory the configuration file is located in is controlled by
two factors.

If the {{QUICKIE_SYSCONFDIR}} environment variable is set, the
{{quickie.conf}} file is looked for in this directory.

Otherwise, the compiled-in default is used.  This default is
set by using the {{./configure --sysconfdir=}}''path'' command
line option when the program was built.  This often defaults
to {{${prefix}/etc}}, and given that {{$prefix}} defaults to
{{/usr/local}}, if you changed nothing, the file you are looking
for is called {{/usr/local/etc/quickie.conf}}, but most Linux
distributions (and many sites) override this using the {{./configure
--sysconfdir=/etc}} option, making the path {{/etc/quickie.conf}} quite
likely, as well.

!! Viewing Current Settings
You can see the current values of all the configuration settings via the
[admin/settings|Settings] page.  Unlike regular wiki pages, this page
is generated on-the-fly each time, and represents the current state of
the wiki engine.

!! The configuration fields
The {{quickie.conf}} file is composed of a number of fields.  The field
name is on the left, then a colon and white space, and then the value.
The field name ares __not__ case sensitive, but the values may be.

Comments are whole lines which start with a hash ({{#}}) character.
Blank lines are ignored.

In general, numeric fields can have K or M suffixes to indicate 2**10 and
2**20 multipliers.

Each configuration field is described below.

!!! Anonymous User Edit
The ''anonymous-user-edit'' field is used to control whether or non
anonymous users (users who are not logged in) may edit wiki pages.
Defaults to false if not set, ''i.e.'' users must be logged in.

!!! Chroot
The ''chroot'' field is a boolean, and is used to control whether or not
the server changes it's root path into the ''localstatedir'' directory
before processing requests.  This offers a small measure of protection against
wily hackers who exploit bugs in Quickie (no security bugs are known,
at this time).  This field defaults to __false__ if not set.

Unfortunately, modern systems now make ''chroot''(2) a privileged
operation (because it can lead to root escalation) and thus not
universally available, which is a what a default of ''true'' assumes.

Please not that, as a result of the ''chroot''(2) system call the
''localstatedir'' will be displayed on the [admin/settings|Current
Settings] page as {{"/"}}.

You will also need to duplicate the ''file''(1) magic number database
inside the chroot jail, otherwise it's going to give useless
__Content-Type__ headers for all non-wiki pages.

!!! Default User Edit
The ''default-user-edit'' field is used to populate the user permission
to edit wiki pages when a new user is created.  Defaults to true if not
set.

!!! Local State Dir
The ''localstatedir'' field can be set from three places,
whichever is found first:
the {{QUICKIE_LOCALSTATEDIR}} environment variable, or
the ''localstatedir'' field of the {{quickie.conf}} file, or
the {{./configure --localstatedir=}}''path'' command line option at build time.

The line in the {{quickie.conf}} file could look like this:
{{{localstatedir: /var/quickie}}}
The usual place is {{/var/quickie}} by convention, but suit yourself.

!!! Post-Limit
The ''post-limit'' field can be used to limit the amount of data fed
through POST requests to the Quickie server.  This can be used to
prevent your server from becoming a free file server.
Defaults to 100K if not set.
A value of zero means ''unlimited''.

!!! Recent-Limit
The ''recent-limit'' field is used to control the number of pages shown
in the [admin/recent|Recent Changes] page.  It defaults to 100 if not set.

!!! Show Mod Times
The ''show-mod-times'' field is use to control the addition of
descriptive text showing the time-last-modified (when the wiki text of
the page was last modified) and time-last-updated (when the HMTL text
of the wiki page was last cached) at the bottom of each page, after the
Edit link.
{{{Show-Mod-Times: true}}}
Defaults to {{true}} if not set.

!!! Sidebar-Layout
See the [manual/sidebar|Sidebar Guide] page for more information.

!!! Style Sheet File
The ''style-sheet-name'' field controls the name of the file in
the {{/admin/}} directory which contains the CSS (Cascading Style
Sheet) for this wiki. defaults to {{default.css}} if not set.  See the
[manual/markup|Text Formatting Guide] for more information.

!!! Umask
The ''umask'' field controls the file creation mask.
It defaults to 022.
See ''umask''(2) for more information.