You have just unpacked a release of the ausadmin software for USENET News hierarchy maintenance. If you are not a USENET hierarchy maintainer, this software may not be much use to you.

This software is (C)opyright 1998-2002 by Nick Andrew <nick@nick-andrew.net> and is released under the terms of the GNU General Public License (GPL).

To install and configure this software, follow these instructions in the order they appear.

Setting up

These instructions are minimal, because this software is alpha quality only!

Setup the environment

1. Install necessary software: apache-ssl, cronolog, ssh, rsync, pgp, gnupg
2. Create an 'ausadmin' userid and group, and su to ausadmin
3. Edit .profile or .bashrc to add $HOME/bin to your PATH
4. Unpack the ausadmin software release under ausadmin's home directory
5. Setup your apache webserver to serve the website. See doc/apache.conf
6. Unpack the ausadmin website release under your website DocumentRoot

Import your hierarchy data

1. su to ausadmin
2. mkdir -p data/Newsgroups
3. mkdir -p vote
4. copy your raw "newsgroups" type file to data/ausgroups (yes, that's the name it has to be at this time)
5. do "bin/gen-initial-newsgroups.pl data/ausgroups" to create and populate the data/Newsgroups directories. Just ignore the RCS messages.
6. You have now completed 1% of the setting up!
7. Next, find your charter files (one charter per newsgroup). Make sure the charter files are "clean" (i.e. no email headers or leftover rationale from group proposal time).
8. For each charter file:
   1. Do "bin/set-charter.pl newsgroup.name charter.file". Just ignore the RCS messages.
9. You have now completed 90% of the setting up!

Create templates

The "data" directory contains the definitive list of newsgroups in the data/Newsgroups directory, the definitive group descriptions (at least at the moment) in data/ausgroups, some generated files, and some templates for generating messages.

Samples for all templates are available in the samples/ directory.

1. Copy samples/* into data/
2. Edit each template for your situation and/or language. See below for the list of templates and what they are for.

The templates are:

Filename	Description
booster.template	This is a perl string expression which is eval()ed by the code, so it must start with " and end with " on a line by itself. See bin/Newsgroup.pm to find out what variable substitutions are allowed.
checkgroups.footer	This is a text file which is prepended to the generated checkgroups message, default is empty.
checkgroups.header	This is a text file which is appended to the generated checkgroups message, default is empty.
faq.header	This is a text file containing an article header to be used when posting the regular FAQ.
grouplist.footer	This is a text file which is appended to the human-readable group list message.
grouplist.header	This is a text file which is prepended to the human-readable group list message.
vote-check.msg	This is a text file containing an email header and body which is sent by the vote checker program, to look for invalid email addresses on votes received.

Setup PGP and GnuPG private and public keys

The software uses PGP 2.6.3(i) to sign control messages, and GnuPG to sign ordinary text files, such as RFDs, vote results, etc.

You will therefore need to have your public and private keys inserted into

• $HOME/.pgp/pubring.pgp and $HOME/.pgp/secring.pgp
• $HOME/.gnupg/pubring.gpg and $HOME/.gnupg/secring.gpg

Generate checkgroups and grouplist messages

1. Do "bin/gencheckgroups.pl > data/checkgroups.msg". The generated checkgroups is derived from the contents of your data/Newsgroups directory.
2. Do "bin/gen-grouplist". Ironically, the generated grouplist is derived from your original "data/ausgroups" file. So make sure it is up-to-date!

Setup vote-taker

The ausadmin software uses the email address: <vote@aus.news-admin.org> to accept email votes on proposals. You will need to use a different address. Set up your system so that emailed votes to your chosen address are piped to "bin/incoming" (not "bin/incoming.pl").

Jump and pray

The above may get you started with the ausadmin software. There is more work to do before you can start running votes however.

Firstly, there are many ausadmin-specific assumptions hardcoded into the source code. Things like email addresses, hostnames, home directories and domain names. You will need to search and modify these references. If you can remove these assumptions, for example by moving them out to a config file in the data/ directory, then ausadmin will greatly appreciate receiving a patch.

Secondly, you will need to learn the names of files in the vote directories and the meaning of their contents. Each proposal or vote has its own directory under vote/ and the files in that directory are created and modified as the vote proceeds.

The source code is starting to use the word "proposal" rather than vote. A proposal starts out as an RFD, (Request For Discussion), which is constructed from a source file which is received by ausadmin or created by ausadmin. See "Faq/RFD-template.txt" on the website for the file structure. This file is parsed by "bin/parse-rfd.pl" to create a new Proposal in the vote/ subdirectory. See, for example, "bin/make-rfd.pl" and "bin/setup-vote".

An RFD is posted, and discussed, and may become a proper vote after some time. In that case a CFV (Call For Votes) is created from the proposal information and posted. As soon as a CFV is created, the system is ready to receive votes. See, for example, "bin/mkcfv.pl".

Accepted votes are appended to a tally file until the vote completes. After the voting time limit is reached, there are various tools for analysing the messages to detect forgeries and multiple voting. Look for example at "bin/analyse-messages.pl".

Once the vote tally is confirmed, there are tools for counting the vote and creating control messages. See, for example, "bin/genresult.pl"

Bugs

There's one thing which the software doesn't do well at the moment and that is updating its control files (data/ausgroups and data/Newsgroups/*) when votes pass. This can lead to sending out obsolete checkgroups messages, for example.

There is also an issue with PGP-signing checkgroups and control messages. If there is a passphrase on the PGP keys, then automatic signing of these messages is not possible. This is not good for regular automated posting. I haven't found a way around this security/convenience trade-off yet.

The Easy Way (yes, you want this)

Now that I have scared you with a lot of scripts which you need to know how to use to do things, I can tell you that it is actually a lot easier. There are two tools which you will use all the time. They are "todo.pl" and "action".

"bin/todo.pl" examines every proposal under the vote/ directory and determines if you need to do something to advance the proposal. Recall that proposals start empty, then become RFDs, then CFV, then get voted upon and finally produce a result. There are necessary time delays in all parts of this process, and it is the hardest thing to remember which proposals are ready for which next stage of the process. "todo.pl" helps with this by printing a list of the proposals which are ready for you to make some change. For example:

ausadmin@slim:~$ bin/todo.pl
aus.sport.touch ... In discussion, wait until 2002-06-06 (rfd/posted)
aus.music.regurgitator ... In discussion, wait until 2002-05-26 (rfd/posted)
aus.business ... In discussion, wait until 2002-06-02 (rfd/posted)

This output says that the current state of each of the three proposals is "rfd/posted" (i.e. it's being discussed and the RFD has been posted) and the minimum timeframe for the discussion ends on the listed date.

The other very useful tool is "action". Action goes through each of the proposals in the vote/ directory and determines the proposal's current state. Depending on the current state, "action" knows what the next state in the process should be, and it knows what commands to issue to move the proposal forward. So "action" runs "setup-vote", "mkcfv.pl" and the other scary commands mentioned in the previous section.

"action" prompts you before doing each action. I usually only allow "action" to make one change at a time, and in the middle of each action I check the files in the vote/proposal_name directory to make sure that they are correct (correctly signed, correctly generated, etc...).

Big TODO list for the ausadmin software

• Generate messages (e.g. RFD and CFV) from templates as much as possible. This will help others to translate the software into other languages.
• Provide increased web-based functionality. For example, show all information about past completed proposals, whether they passed or failed, what revisions the proposals went through.
• Maintain more data about the newsgroups, for example the date of creation and who did the creation (maybe the control message itself). This is especially useful for "grandfathered" groups, i.e. groups which were created by somebody else before you started in this role.
• Provide web-based submission of proposals. Proposers should be able to type in and edit their proposal online.
• Move to a "reviewer panel" management structure rather than a single person. Having multiple people review submissions will provide some checks to keep the reviewers honest, and may reduce delays in getting proposals posted. It may be possible to have several reviewers and assign different privilege levels such that newbie reviewers are able to assist with proposal grammar and justification but are not able to officially accept proposals for discussion or voting.
• Provide web-based voting rather than email voting. In some ways, it is harder to submit multiple web votes than it is to submit multiple email votes. A "registered user" arrangement with an SSL web server voting site should be able to discourage all but the most persistent attempts at stuffing the ballot box.
• Cleanup the code, remove obsolete source files, move to a consistent naming standard for commands
• Reduce the number of commands which need to be executed from the command line. This may be accomplished by providing more web-based control functions.
• Remove all the "aus" and ausadmin specific assumptions from the code.

The End

This is the end of the setup instructions. There is some documentation under the doc/ directory also.

Please provide feedback to <nick@nick-andrew.net> if you start to use this software and if you make changes.