root/README

                               Overview

Alue will be a discussion forum system providing a web-based forum
interface, a NNTP (Netnews) interface and an email interface, all with
equal status. What will be unusual compared to most of the competition
is that all these interfaces will be coequal views to the same
abstract discussion, instead of being primarily one of these things
and providing the others as bolted-on gateways.

Currently NNTP access is implemented and essentially fully functional.
HTTPS access provides basic functionality.  HTTPS administration is
lacking, and is under development.


                               Warnings

In general - Alue is under construction.  This has several
consequences:

 - Alue currently requires an expert operator.

 - Alue is security sensitive but has not been inspected or audited
   for security issues.

 - No stability of file formats or other interfaces is promised, and
   no upgrade support is provided.


                             Requirements

Alue is intended to be installed by the system administrator.  While
installing it in one's own home directory is technically possible, it
is not recommended and may be a violation of a relevant acceptable
usage policy (since Alue opens ports to the Internet).

Alue requires a standards-compliant C++ compiler, a recent Boost
release (0.38 has been tested; 0.35 is only grudgingly supported[1]),
and the GnuTLS library.

A SSL/TLS key and a certificate (whether self-signed or CA-issued) are
needed.  It is not possible to run Alue without SSL/TLS support.

Alue has been developed on Debian GNU/Linux, but is likely to work on
any POSIX system with no or minimal changes.  A port to Windows is
expected to be relatively simple but needs a competent volunteer.

[1] Alue can be run on Boost 0.35 but in that case requires a copy of
boost/asio/buffers_iterator.hpp from 0.36 or later (and trivial
changes to the source to use that file).


                            Configuration

The ports used can be specified on the command line: 

  --nntp-port for NNTP (default 119)
  --nntps-port for NNTP over SSL/TLS (default 563)
  --https-port for HTTP over SSL/TLS (default 443)

Each takes as an argument a port specification: either a number or a
name listed in /etc/services.  If a well-known port (<1024) is used,
then Alue must usually be started as root.

Alue does not support cleartext HTTP without changes to the source.
Since most HTTP clients also support HTTPS, there seems to be no
justification to enable the less secure cleartext protocol.  (The same
argument unfortunately does not apply to NNTP, since NNTP with
STARTTLS and NNTPS are not supported by many widely used clients.)

If Alue is started as root, pass --user USER on the command line to
tell Alue to drop root privileges and switch to USER after
initialization.

Alue logs into the file alue.log in the current directory, unless
overridden with the --logfile option.  The log buffer is flushed each
time Alue becomes idle.  There is currently no way to instruct Alue to
close and reopen the log.

Alue uses the uname nodename as the system's name (for Xref and Path),
unless overridden with the --canonical-name option.  This should be a
globally unique name.

Put the SSL/TLS private key (in PEM format) in the file key.pem (or
give another file name on the command line using the option
--key-file).

Put the SSL/TLS X.509 certificate (in PEM format) in the file cert.pem
(or give another file name on the command line using the option
--cert-file).  If you need intermediate certificates (for example if
such are provided to you by your Certificate Authority), concatenate
them in the same file, in the order of certification (that is, each
certificate is certified by the certification immediately after it).

The options --log-http, --log-nntp and --log-smtp take one argument
each (a boolean), and all default to false.  If true, then the
corresponding protocol is extensively logged.  Do note the privacy
implications.

The option --vm-limit allows you to specify a virtual memory ulimit
for the Alue process, in order to protect the host system from runaway
allocation bugs in Alue (none currently known, but they have
occasionally manifested during development testing).

The option --include-dir specifies the directory where the HTML and
email template files reside.  The option --files-dir specifies the
directory where files like CSS stylesheets and images (to be served
verbatim by the HTTPS system) are located.  The template language is
currently undocumented; a sample set of templates (used to run the
test installation) is available at
  http://git.verbosify.org/?p=verbosify-templates/.git;a=summary
  git://git.verbosify.org/git/verbosify-templates.git/

The option --operator-email specifies an email address through which
the operator is reachable.  This address will be used in
Alue-generated emails.

                           Central database

The central database is located in the file alue.db2 in the current
directory.  Its format is described in the file db/FORMAT.txt. It
stores messages as well as information about groups and users.


                           Creating a group

NOTE: There is currently no way to create groups without shutting down
the server.  (A web-based method is planned.)

Step One.  Stop the server.  (This is important, since editing the
message database while the server is running can cause data
corruption.)

Step Two.  Append to the message database a block having the following
format:

  .BEGIN <timestamp>
  NEWGROUP <groupname>
  DESCRIPTION <short description>
  READING <reading_policy>
  .END

Note that the file is line-oriented; each line in the above schema
must correspond to a single line in the file.  The lines in the file
must not be indented.  Case is significant.

Timestamp should have the ISO format (yyyymmddThhmmss) and should
indicate the time when the group is created.  It should be later than
any other timestamp in the file, and earlier than any timestamp that
will be added later (by Alue, for example).

Groupname should follow USEFOR syntax.

Description is free-form text.  It must be a single line and should be
short.

Reading_policy is either PERMITTED (allowing unidentified users to
read the group) or RESTRICTED (requiring authentication before the
group can be read).  Crossposting between restricted and other groups
is not possible.

Step Three.  Start the server again.


                               Contact

For access to the source and updates, see
  http://git.verbosify.org/?p=alue.git;a=summary
  git://git.verbosify.org/git/alue.git/

There is an installation running on verbosify.org.  Accounts are not
currently publicly available, but there are serveral groups that are
available (read-only) to unidentified users.

Bug reports, patches and other comments should be sent to
antti-juhani@kaijanaho.fi