Votorola Software Manual 0.2.3.1

Deployment Areas and Vote-Servers

Setting up a Deployment Area
Pollwiki
1. Setting Up the Pollwiki
Vote-Servers
File Server
Database Server
1. Setting Up Database Access for a Vote-Server

A deployment area. A deployment area is an administrative scope within which a set of voting facilities are independently installed, maintained and operated.

Setting Up a Deployment Area

This section outlines the minimal procedure for setting up a deployment area. It will include a pollwiki and two vote-servers: an offline server (voff) for test purposes, and an online server (v) for public use.

Setting Up the Offline Vote-Server

Set up the pollwiki (1.2.1).
Install Votorola (1.3.1).
Set up database access for vote-server voff (1.5.1).
Create vote-server voff (1.3.2).
Set up the web servlet interface (5.1).
Set up the server side of Crossforum Theatre. (gwt/scene/theatre.xht#server-setup)

Testing the Vote-Server

This procedure tests the vote-server by running a voter simulation with the script vosim-alex. It also tests the difference bridge.

Ensure the database server (postgres), pollwiki (apache) and web interface (tomcat) are all running. Ensure you are logged into a terminal as user voff.

The script vosim-alex should be on your path. Do a dry run with a small group of simulated test voters:

$ vosim-alex ab 1-3 # voters a1, a2, a3, b1, b2 and b3

test-a1@zelea.com Sys/p/sandbox vote test-a@zelea.com
test-a2@zelea.com Sys/p/sandbox vote test-a@zelea.com
test-a3@zelea.com Sys/p/sandbox vote test-a@zelea.com
test-b1@zelea.com Sys/p/sandbox vote test-b@zelea.com
test-b2@zelea.com Sys/p/sandbox vote test-b@zelea.com
test-b3@zelea.com Sys/p/sandbox vote test-b@zelea.com

It ouputs a list of commands for the voter shell.

Execute these commands by piping them to the voter shell:

$ vosim-alex ab 1-3 | voter

Old value:  none
Sys/p/sandbox

You were voting for:     nobody
You are now voting for:  test-a@zelea.com

No results are available for this poll.  They have yet to be reported.
(Administrator see 'vocount report'.)
 . . . and so on

Compile the voter list by tracing the trust network.
```
$ votrace
```
You ought to see 1 or more voter registers (XML files) under ~/votorola/out/votrace/_readyTrace_report/_mounted_trace/. The content of the registers is unimportant for this test, because we are using a minimal configuration that counts the votes of registered and unregistered users alike. Nonetheless the trace must be mounted.
Count the votes.
```
$ vocount
```
You should see a tie between two leading candidates (a and b), at 3 votes apiece:

http://localhost:8080/voff/w/Votespace/?p=Sys!p!sandbox

Cast a vote for a new candidate.

$ voter test-v@zelea.com Sys/p/sandbox vote test-c@zelea.com

Sys/p/sandbox

You were voting for:     nobody
You are now voting for:  test-c@zelea.com

    test-v@zelea.com
        |
        | 1
        |
        V
    test-c@zelea.com  --->  1 removed from flow

The final recipient of the vote is test-c@zelea.com.  . . .

Recount the votes.
```
$ vocount
```
Now hit refresh in your browser. You should see a new candidate (c) with a single vote.

Import some test pages to the pollwiki.

% cd /WIKI-INSTALL-PATH/mediawiki/maintenance

% php importDump.php /home/voff/votorola/_/test/minimalPollwikiPages.xml

Done!
You might want to run rebuildrecentchanges.php to regenerate
the recentchanges page.

% php rebuildrecentchanges.php

Loading from page and revision tables...
$wgRCMaxAge=604800 (7 days)
Updating links and size differences...
Loading from user, page, and logging tables...
Flagging bot account edits...
Flagging auto-patrolled edits...
Done.

BUG: if this rebuild fails with database errors (seen on Mediawiki 1.18.2 and PostgreSQL 9.1.4), then ignore them. These are not critical errors.

Test the difference bridge. Start in the votespace browser where it shows the new voter (Test-v-ZeleaCom):

http://localhost:8080/voff/w/Votespace?p=Sys!p!sandbox&u=Test-v-ZeleaCom

To the left of that voter's name, click on the small [wiki/chaos symbol] link.

That should take you to the voter's position page in the pollwiki. At the top of that page, click on the link “Diff vs. candidate's”.

That should take you to a diff page, the text of which looks something like this:

Tv. Test-v-ZeleaCom
Tc. Test-c-ZeleaCom
    [ Patch ]
[ ] -----------------------------------------------------------------------------------------------------
frag 1
    but perhaps there are more paragraphs yet to come?

    This is sentence 30 of our position draft. ↩
Tv. It is followed by sentence 31, ↩
    which introduces this important amendment. ↩
Tc. It is followed by sentence 31. ↩
    Sentence 31 is followed by sentence 32, ↩
    which consists of two phrases. ↩
    Next comes the third sentence of this paragraph which is numbered 33 in the overall position draft. ↩
[ ] -----------------------------------------------------------------------------------------------------
frag 2
    here is sentence 97. ↩
    Eighth place in this paragraph belongs to sentence 98. ↩
    Sentence 99 appears last in the paragraph, ↩
Tv. but perhaps there are more paragraphs yet to come? ↩
    No, ↩
    I am afraid that's the end of it.
Tc. but perhaps there are more paragraphs yet to come?
    [ Patch ]

Test the patch facility. Press the login link at the top right of the diff page, and login under alias ‘c’.

The controls on the diff page are now enabled as though you were the candidate. Select frag 1 to accept the “important amendment” from the voter. Then press the Patch button.

That effects the patch and takes you to the revision history of your (the candidate's) position draft. If the login handshake fails with result "NeedToken", then ensure the wiki script URI is specified with a fully qualified domain name.

[BUG: it will fail with "WrongPass". You must create an account in the wiki for "Vobot", and set the password to the default.]

In the revision history, ensure that the two most recent revisions are selected, then press the Compare selected revisions button. A comparison page is shown. In that page, you should see that the voter's proposed change “which introduces this important amendment” was incorporated into sentence 31.

That ends the test. When you are finished, you may want to run vox-clean to erase everything from the vote-server. First, stop any running services such as the web interface:

% /etc/init.d/tomcat-6 stop

Then inspect the script in your editor.

$ emacs `which vox-clean`

Ensure that each line of the clean() subroutine is uncommented so that all test data is erased. Then run it:

$ vox-clean

removing directory: /home/voff/votorola/out/votrace
removing database schema: out_trace
NOTICE:  drop cascades to 3 other objects
DETAIL:  drop cascades to table out_trace."2012-9m-1-membership-1"
drop cascades to table out_trace."2012-9m-1-trace_node-1"
drop cascades to table out_trace."2012-9m-1-trust_edge-1"
DROP SCHEMA
removing database table: in_vote
DROP TABLE
removing directory: /home/voff/votorola/out/vocount
removing database schema: out_count
NOTICE:  drop cascades to table out_count."2012-9m-2-count_node-1"
DROP SCHEMA

  List of schemas
  Name  |  Owner   
--------+----------
 public | postgres
(1 row)

         List of relations
 Schema |   Name    | Type  | Owner 
--------+-----------+-------+-------
 public | geocode   | table | voff
 public | store_wap | table | voff
 public | user      | table | voff
(3 rows)

Finally, restart the web interface:

% /etc/init.d/tomcat-6 start

You should no longer see the registry's output directory ~/votorola/out/votrace/, nor any poll results in the web interface (hit refresh here):

http://localhost:8080/voff/w/Votespace/?p=Sys!p!sandbox

Setting Up the Online Vote-Server

After voff is properly configured and tested, you can easily set up the online vote-server v. This is the general pattern to follow for all software and configuration upgrades: first test them offline, then transfer them online.

Simply repeat the setup procedure above, but this time for vote-server v. Copy its initial configuration from voff and amend all references to the vote-server name. To find all references:

$ find ~/votorola  -name code -prune  -o -name out -prune \
-o -type f -exec grep voff {} +

Pollwiki

The pollwiki provides 1) a shared database among separate facilities of the voting network; 2) a default UI layer of views and controls onto the shared database; and 3) a default drafting medium for poll positions.

Setting Up the Pollwiki

This is optional. We provide a multi-area reference pollwiki and it is recommended that you start with that. You may migrate to your own pollwiki later. However there is a BUG: your users won't be able to patch their differences, because the username Vobot is hard coded into the difference bridge and we cannot share the password. But just ask, and we'll fix this ASAP.

Follow the usual instructions in order to install the MediaWiki software, and get a basic wiki running. Do not create any pages until after you install Semantic MediaWiki (below).

During configuration, you are prompted for a “Wiki name”. This gives you a special namespace in the wiki for site-specific pages. The reference pollwiki simply uses the name ‘Site’. Choose any name, you can always change it later.

You are also prompted for a database password. If you are using PostgreSQL “trust” authentication then there is no password. Leaving the field blank seems to work in that case, despite the warning “must not be blank”.
Once the basic wiki is running and before creating any pages, install Semantic MediaWiki. Install whatever version is recommended, but it must be at least 1.7.1.

Note the special instructions for PostgreSQL.
Install extension MailishUsername.

That should be sufficient to start. Later you can refine the configuration by copying from other pollwikis. See also the working example in the appendix.

votorola/a/
votorola.a

Vote-Servers

A vote-server is a server that provides polls and other voter services. A deployment area typically has a pair of vote-servers, one for online public use, and one for offline testing. Each vote-server has a separate account on the local host computer, under which its data is stored and its processes are run. The login name of this account is also known as the vote-server name. Conventional vote-server names are v and voff.

File structure for vote-servers. Shows the structure for a typical deployment area with two vote-servers: an online server `v`, and an offline server `voff`. In this example, `v` is linked to an older version of Votorola, and `voff` to a newer version. (Complete examples in `/home/voff` and `/home/vdev`.)
home v votorola code -> ../../../opt/votorola-0.1.11 ··· as below voff votorola code -> ../../../opt/votorola-0.2.3 in out register web poll-service.js vote-server.js opt votorola-0.1.11 votorola-0.2.3

The vote-server is configured by its configuration script, located in the votorola directory (shown above). The internal structure of the script is outlined in the figure below.

Startup configuration for a vote-server. Shows the hook function that is defined by the script `~/votorola/vote-server.js`. (Complete examples in `/home/voff/votorola` and `/home/vdev/votorola`.)
vote-server.js function constructingVoteServer( vsCC )

Each vote-server maintains a store of relational data, as shown in the figure below.

Database structure for vote-servers. Shows the structure for a typical deployment area with two vote-servers. Each vote-server has a namesake database wherein it maintains 2 general-purpose tables. (Not shown are the various special-purpose tables of the voter services.)
v as below voff geocode user

Installing Votorola

Unix is required. Although testing is currently limited to Linux, it should also work with other versions of Unix.

Java version 1.7 is required.

$ java -version

Procedure

Create the votorola group. This will be the default group for all vote-server accounts.
```
% groupadd votorola
```
Add yourself to the group.
```
% usermod --append --groups votorola MYLOGIN
```
This is a convenience for editing the vote-server's files without having to login as such.
Download votorola-0.2.3.tar.gz.
Unpack it.
```
% tar --extract --gzip --file votorola-0.2.3.tar.gz --dir /opt
```
You may actually unpack it anywhere. This manual assumes the /opt directory.
If you happen to have unpacked a version other than 0.2.3, then follow its instructions from this point on.
Test one of Votorola's executables. This one lists the Java runtime properties. Test it the long way, first:
```
$ java -jar /opt/votorola-0.2.3/votorola/s/_/bin/voqproperties | sort
```
```
awt.toolkit=sun.awt.X11.XToolkit
file.encoding.pkg=sun.io
file.encoding=UTF-8
file.separator=/
  . . .
```
Do not place these executables on the path yet. You'll do that later when you create a vote-server.
If Linux kernel option binfmt_misc is enabled, and if PK-Zip is already bound to execute Java JAR archives, then you needn't type java -jar in front of each Votorola command. You may execute it directly, like this:
```
$ /opt/votorola-0.2.3/votorola/s/_/bin/voqproperties | sort
```
For instructions on enabling this, see the example script jar-wrapper.¹³

That is all. Votorola is now installed.

Creating a Vote-Server

Create the vote-server's user account.

% useradd voff --gid votorola --create-home

% passwd voff

Set the file creation mask so that new files are writeable by the votorola group.⁴ For example, add this line to the vote-server's ~/.bashrc:
```
umask 0002 # creation mask (0002), files writeable by login group (votorola)
```
While you are there, also add the following line. This places the example scripts and the standard Votorola commands on the vote-server's path:¹³
```
PATH=$HOME/votorola/bin:$HOME/votorola/code/votorola/s/_/bin:$PATH
```
You may want to add the vote-server to the database group.
```
% usermod --append --groups postgres voff
```
Whether or not this is necessary depends on how the database engine is configured. It will be necessary, for example, if access to the engine's socket file is restricted to members of the postgres group. The typical location of the socket file is /var/run/postgresql/.s.PGSQL.5432.
Login as the vote-server.
```
$ whoami
```
```
voff
```
In the vote-server's home directory, create the votorola directory.
```
$ mkdir ~/votorola
```
In that directory, create a symbolic link to the code that was previously installed.
```
$ ln --force --no-deref --sym /opt/votorola-0.2.3/ ~/votorola/code
```
Copy over the minimal configuration from the examples that were bundled with the release.
```
$ cp -R ~/votorola/code/votorola/s/_/example/minimal/home/voff/votorola/*  ~/votorola/
```
Ensure the I/O directories are writeable by the votorola group.⁴
```
$ chmod g+w ~/votorola/in ~/votorola/out
```
Test that Votorola's executables are accessible. For example:
```
$ voqproperties | sort
```
```
awt.toolkit=sun.awt.X11.XToolkit
file.encoding.pkg=sun.io
file.encoding=UTF-8
file.separator=/
  . . .
```
If not, then look at the PATH environment variable. Also look at binfmt_misc.
Test the logging configuration, with the help of volog.
```
$ volog
```
In a default Java installation, the log is usually output to the console. Wherever it is output, you should see volog's test messages:
```
Sep 22, 2012 8:59:36 PM votorola.s.line.VOLog main
INFO: volog is running with arguments []
Sep 22, 2012 8:59:36 PM votorola.g.logging.LoggerX test
OFF: testing SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST and ALL...
Sep 22, 2012 8:59:36 PM votorola.g.logging.LoggerX test
SEVERE: this is SEVERE
Sep 22, 2012 8:59:36 PM votorola.g.logging.LoggerX test
WARNING: this is a WARNING
Sep 22, 2012 8:59:36 PM votorola.g.logging.LoggerX test
INFO: this is INFO
```
You may want to increase the verbosity level for the offline vote-server from INFO to at least CONFIG. And you may want to log the messages to files, and not just the console. Refer to the discussion of logging configuration in the examples appendix.
Ensure the database server (postgres) is running.

Run a smoke test on a poll.

$ voter Sys/p/sandbox hello

hello

$ voter test-a@zelea.com Sys/p/sandbox vote test-b@zelea.com

 . . .
You were voting for:     nobody
You are now voting for:  test-b@zelea.com

No results are available for this poll.  They have yet to be reported.
(Administrator see 'vocount report'.)

$ voter test-a@zelea.com Sys/p/sandbox unvote

 . . .
You were voting for:     test-b@zelea.com
You are now voting for:  nobody
 . . .

That is all. The vote-server is now created.

Upgrading Votorola

Download the new version of Votorola.

Unpack it.

% tar --extract --gzip --file votorola-VERSION.tar.gz --dir /opt

Stop any processes that are running for the offline vote-server.

Unreport and unmount any mounted counts and lists.²

$ vocount ureport && vocount umount --verbose

$ votrace ureport && votrace umount --verbose

At this point, ensure you are reading from the new version of the software manual.
If you are deploying the web interface, then ensure no user sessions are persisted from the old version of Votorola:
```
% (save=/tmp/var_run_tomcat-6_Catalina/; \
rm --force --recursive $save && mv /var/run/tomcat-6/Catalina/ $save)
```
(Here's the script of that.) Otherwise Tomcat may experience serialization errors at next startup as it tries to recover sessions from the previous run.³

Link to the newly installed code.

$ ln --force --no-deref --sym  /opt/votorola-VERSION/  /home/voff/votorola/code

Read the top entry in /home/voff/votorola/code/votorola/changes.xht. Update your configuration, if necessary.
Remount any lists and counts that were unmounted, above.
Restart any voter interface processes that were stopped, above.

File Server

The file server provides the file storage and communication interface of a vote-server's public archives. The main purpose of the public archives is to support the verification of poll results. A secondary purpose is to store backup data, as insurance against a database loss.⁹

Database Server

The database server provides one or more databases for each vote-server. Databases contain administrative data, voter input, and mounted traces and counts. Votorola requires the PostgreSQL database management system (DBMS), version 9.1 or later.

The database cluster must be installed with a UTF-8 character encoding. According to Semantic MediaWiki's installation instructions, it is not enough to install a non-UTF-8 cluster with UTF-8 databases. Note also the additional configuration step for PostgreSQL 9.

Setting Up Database Access for a Vote-Server

This assumes that a PostgreSQL DBMS is already installed on the database server, as described above.

Start the DBMS process (postmaster) on the database server.
From the server, ensure you are logged into Linux as a DBMS superuser. If root has not been made a DBMS superuser, then login as postgres.
```
% su - postgres   # if necessary
```
Create a DBMS account for the vote-server, under the same user name.
```
% createuser voff
```
When prompted, answer ‘no’ to special user permissions for creating databases, other users, and so forth. None of these are needed by the vote-server.
Create a vote-server database, with the same name as the vote-server.
```
% createdb --owner=voff  voff
```

votorola/s/line/
votorola.s.line

Command Line

vocount — count the votes
vodeliver — deliver an email test message
voface-mail — respond to voter messages
voharvest — gather diff messages
volist — compile a voter list
volog — log test messages
vomir — pull remote votes for mirroring
vonop — do nothing
voqproperties — print the runtime properties
voscript — compile a configuration script
voter — issue a service command on behalf of a voter
votrace — trace a neighbourhood trust network

This section concerns the command-line administrative interface. Following are the details for each command provided by the interface.

vocount — count the votes

synopsis

vocount [--verbose] [--etc[=ready|mount|report|umount]]

vocount snap [--verbose] [--etc[=ready|mount|report|umount]] [--churn]
vocount ready [--verbose] [--etc[=mount|report|umount]]
   [~/votorola/out/vocount/snap-YYYY-MD-S]
vocount mount [--verbose] [--etc[=report|umount]] [--churn]
   [~/votorola/out/vocount/snap-YYYY-MD-S/readyCount-S]
vocount report [--verbose] [--etc]
   [~/votorola/out/vocount/snap-YYYY-MD-S/readyCount-S]
vocount umount [--verbose]
   [~/votorola/out/vocount/snap-OLD-YYYY-MD-S/readyCount-OLD-S]

vocount ureport [--verbose]

vocount status

vocount --help

description

Tool vocount counts the votes and makes the results available for other tools and processes. It does this in separate, staged invocations, with these action arguments:

snap — to capture a snapshot of the voter input and archive it in the output store
ready — to capture the parameters for the count and archive them in the output store
mount — to cascade the votes, sum the results, and record them in the output store
report — to mark the mounted results as current for reporting in all user interfaces
umount — to undo a prior mount and clear its results from the output store

If no action is specified, the default is to carry out all actions from snap through umount. The following commands are therefore equivalent:

$ vocount

$ vocount snap --etc=umount

Repeated invocations of mount/umount will always generate the same results. The results depend only on the archival snap/readyCount record that was created by the previous invocation of snap/ready. Thus the snap/readyCount record alone is sufficient to do a recount, and anyone obtaining a copy may use it to verify the reported results.

File structure for vocount. Shows an example of typical file output, with daily snapshots. The latest of these is mounted. The various `SERVICE-NAME` are the names of the individual polls.
/home/voff/votorola/out/vocount _readyCount_report -> snap-2011-bl-1/readyCount-1 _snap_report -> snap-2011-bl-1 snap-2011-bj-1 ··· snap-2011-bk-1 ··· snap-2011-bl-1 _in_vote `SERVICE-NAME`.txt `SERVICE-NAME`.txt ··· readyCount-1 _in_config `SERVICE-NAME` `SERVICE-NAME` ··· _mountedCount `SERVICE-NAME`.serial `SERVICE-NAME`.serial ··· readyTrace -> ../../../ trace/snap-2011-bl-1/readyTrace-3

Database structure for vocount. Shows the typical output structure for a vote-server with a single mounted count. Also shown is the voter input table, from which each snapshot is taken.
out_count 2011-bl-1-count_node-1 in_vote

actions

snap

Take a snapshot of voter input. This action reads the input from the input store, and writes it to the output store. In the process it creates a new snap directory, the path of which it prints to standard out. For example:

~/votorola/out/vocount/snap-YYYY-MD-S

ready

Capture and record the parameters for the count. This action takes for an argument a snap directory containing a snapshot of voter input, as created by a previous snap action. It stores within that directory any administrative input that may be needed by subsequent mount actions, such as special configuration for the count compiler. In the process it creates a new ready directory, the path of which it prints to standard out:

~/votorola/out/vocount/snap-YYYY-MD-S/readyCount-S

In this directory, a symbolic link named readyTrace is also created. It points to the snap/readyTrace record of the currently reported trace of the trust network. It is created as a copy of the symbolic link _readyTrace_report, which must already exist.

~/votorola/out/vocount/snap-YYYY-MD-S/readyCount-S/readyTrace

If no snap directory is specified, then it defaults to the most recently modified directory. This is usually the directory of the previous snap or ready action.

mount

Count the votes and make the results available for reporting. This action takes for an argument a ready directory created by a previous ready action. It reads the stored voter and administrative input. It dereferences the symbolic link to the snap/readyTrace record (which must already be mounted as a compiled trace), and uses it to check the eligibility of voters. It cascades and sums the votes, and finally writes the results to the database and filebase for other tools and processes to read.

If no snap/readyCount record is specified, then it defaults to the most recently modified record, as determined by the modification time of its directory. This is usually the most recently created, mounted, or unmounted record.

report

Mark the results as current, for reporting in all user interfaces. This action creates a symbolic links to a particular mounted snap/readyCount record.

~/votorola/out/vocount/_readyCount_report ->
   snap-YYYY-MD-S/readyCount-S
~/votorola/out/vocount/_snap_report -> snap-YYYY-MD-S

If no snap/readyCount record is specified, then it defaults to the most recently mounted record.

umount

Unmount the results of the count. This action reverses a previous mount action, erasing the results from the database and filebase. The snap/readyCount record is not deleted, but remains available for remounting.

If no snap/readyCount record is specified, then all counts are unmounted, except for the currently reported count. While it is being reported, a count cannot be unmounted.

ureport

Unreport the currently reported results. This action reverses a previous report action, unlinking the _readyCount_report and _snap_report links, so that no results are reported.

status

Print the status of all snap/readyCount records. For example:

$ vocount status

M  /home/voff/votorola/out/vocount/snap-2011-bj-1/readyCount-1
   /home/voff/votorola/out/vocount/snap-2011-bk-1/readyCount-1
MR /home/voff/votorola/out/vocount/snap-2011-bl-1/readyCount-1

The status flags are:

`M`	mounted
`R`	reported

options

--etc --etc=ready|mount|report|umount

Carry out all actions through to the specified end-action. For example:

$ vocount snap --etc=mount

The single command above is equivalent to these three commands, in order:

$ vocount snap

$ vocount ready

$ vocount mount

The end-action must be logically subsequent to the start action, otherwise it is ignored. If --etc is specified without an end-action, then it defaults to umount.

Output printing is suppressed for intermediate actions; the end-action alone prints its output. However, if --verbose is in effect, then all actions print their output as usual.

--churn

Churn the wiki cache. Replaces any stale pages with fresh copies from the pollwiki, prior to taking a snapshot of voter input.

--verbose

Print additional information to standard output, as the actions are carried out.

caveats

Unlike a mounted file system, a mounted count persists across system re-starts until explictly unmounted. So ‘mount’ is something of a misnomer.

vodeliver — deliver an email test message

synopsis

cat MESSAGE-FILE | vodeliver [maildir:INBOX-PATH | INBOX-URL]

cat MESSAGE-FILE | vodeliver # to voface-mail inbox

vodeliver --help

description

Test tool vodeliver delivers an email test message to an inbox. It reads the message from standard input, and writes it to the inbox.

If no INBOX-URL is specified, the default is the inbox specified by the configuration of voface-mail. Note that this bypasses voface-mail's authentication layer.

voface-mail — respond to voter messages

synopsis

voface-mail [--help]

description

Process voface-mail is the primary process of the mail-based voter interface. It implements the response layer of the interface; waiting for email messages to arrive from voters, and responding to them. For each message delivered to the inbox, it parses it into separate commands; relays each command to the voter service; and transmits the reply back to the voter.

voharvest — harvesting off-site messages

synopsis

voharvest [--verbose]
                remove PAGE_NAME_OF_ARCHIVE_IN_POLLWIKI remove all messages of an archive
                update PAGE_NAME_OF_ARCHIVE_IN_POLLWIKI* update a particular forum

voharvest [--help]

synopsis

voscript SCRIPT-FILE

voscript --help

description

Interpreter voscript tests the compilation of a configuration script using the JavaScript engine. The SCRIPT-FILE must be encoded in UTF-8 (or equivalently US-ASCII).

Voscript provides the same include facility as the Votorola runtime. A script may load other JavaScript files, pulling them into the compilation, using a function call such as this:

vo.inc( '/home/voff/my-module.jsm' );

The filepath may be absolute, or relative to the including file. Shell variables in the filepath ($NAME) or expressions such as tildes (~) are not expanded.

voter — issue a voter command

synopsis

voter [--id=ID|VOTER-EMAIL] SERVICE-NAME COMMAND [OPTION...] [ARGUMENT...]

voter < ARGUMENT-FILE

cat ARGUMENT-FILE | voter

voter SERVICE-NAME help

voter --help

description

Command shell voter issues a service command on behalf of a voter. The SERVICE-NAME identifies the service. It may be an ordinary service (registry or poll), or the meta-service of the mail-based voter interface (if any is configured). The command is dispatched directly to the service's command/resonse interface, bypassing the usual voter interface (mail or Web). The reply is printed to standard output.

The personal identifier (--id or VOTER-EMAIL) is taken as the authentic issuer when carrying out the COMMAND. The --id may be in the form of either an email address or a mailish username. Neither is required if the command happens to allow for anonymous issue. Here's an example of a help command issued anonymously to a poll named ‘mayor’:

voter mayor help

Any OPTIONS or ARGUMENTS following the COMMAND are passed to the service's command responder. The --help option below, for example, does not request help regarding the voter shell, but regarding the poll's vote command:

voter --id=test-a@zelea.com mayor vote --help

With neither SERVICE-NAME, COMMAND nor other arguments, voter reads multiple lines from standard input and executes them in sequence. The input must be encoded in UTF-8, or equivalently US-ASCII. For example:

vosim-alex ab 1-3 | voter

votrace — trace a neighbourhood trust network

synopsis

votrace [--verbose] [--etc[=ready|mount|report|umount]]

votrace snap [--verbose] [--etc[=ready|mount|report|umount]] [--churn]
votrace ready [--verbose] [--etc[=mount|report|umount]] [--churn]
   [~/votorola/out/votrace/snap-YYYY-MD-S]
votrace mount [--verbose] [--etc[=report|umount]]
   [~/votorola/out/votrace/snap-YYYY-MD-S/readyTrace-S]
votrace report [--verbose] [--etc]
   [~/votorola/out/votrace/snap-YYYY-MD-S/readyTrace-S]
votrace umount [--verbose]
   [~/votorola/out/votrace/snap-YYYY-MD-S/readyTrace-S]

votrace ureport [--verbose]

votrace status

votrace --help

description

Tool votrace traces a neighbourhood trust network, calculates trust levels, compiles a residential register, and makes these available for other tools and processes. It does this in separate, staged invocations, with these action arguments:

snap — to capture a snapshot of the registrant input and archive it in the output store
ready — to capture the parameters for the trace and archive them in the output store
mount — to trace the trust network, compile the list, and record them in the output store
report — to mark the mounted trace as current for reporting in all user interfaces
umount — to undo a prior mount and clear its trace from the output store

If no action is specified, the default is to carry out all actions from snap through umount. The following commands are therefore equivalent:

$ votrace

$ votrace snap --etc=umount

Repeated invocations of mount/umount will always generate the same trace. The content of the trace depends only on the archival snap/readyTrace record that was created by the previous invocation of snap/ready. Thus the snap/readyTrace record alone is sufficient to do a re-compilation, and anyone obtaining a copy may use it to verify the reported trace.

File structure for votrace. Shows an example of typical file output, with daily snapshots. The latest snapshot shows several snap/readyTrace records that have been captured for it, though normally there is only one. The latest of these is mounted.
/home/voff/votorola/out/votrace _readyTrace_report -> snap-2011-bl-1/readyTrace-3 _snap_report -> snap-2011-bl-1 snap-2011-bj-1 ··· snap-2011-bk-1 ··· snap-2011-bl-1 _in_registration.xml readyTrace-1 readyTrace-2 readyTrace-3 _mountedTrace _default.xml _trace.serial

Database structure for votrace. Shows the typical output structure for a vote-server with a single mounted trace.
out_trace 2011-bl-1-membership-3 2011-bl-1-trace_node-3 2011-bl-1-trust_edge-3

actions

snap

Take a snapshot of registrant input. This action reads the input from the streetwiki(s), and writes it to the output store. In the process it creates a new snap directory, the path of which it prints to standard out. For example:

~/votorola/out/votrace/snap-YYYY-MD-S

ready

Capture and record the parameters for the compilation. This action takes for an argument a snap directory containing a snapshot of registrant input, as created by a previous snap action. It stores within that directory any administrative input that may be needed by subsequent mount actions, such as special configuration for the network tracer and list compiler. In the process it creates a new ready directory, the path of which it prints to standard out:

~/votorola/out/votrace/snap-YYYY-MD-S/readyTrace-S

If no snap directory is specified, then it defaults to the most recently modified directory. This is usually the directory of the previous snap or ready action.

mount

Trace the network, compile the list, and make them available for reporting. This action takes for an argument a ready directory created by a previous ready action. It reads the stored registrant and administrative input, traces the neighbourhood trust network, and writes the results to the database and filebase for other tools and processes to read.

If no snap/readyTrace record is specified, it mounts the most recently modified record. Records are considered modified by creation, mounting, unmounting, or anything else that alters the modification time of the record directory.

If no snap/readyTrace record is specified, then it defaults to the most recently modified record, as determined by the modification time of its directory. This is usually the most recently created, mounted, or unmounted record.

report

Mark the trace as current, for reporting in all user interfaces. This action creates a symbolic link to a particular mounted snap/readyTrace record.

~/votorola/out/votrace/_readyTrace_report ->
   snap-YYYY-MD-S/readyTrace-S
~/votorola/out/votrace/_snap_report -> snap-YYYY-MD-S

If no snap/readyTrace record is specified, then it defaults to the most recently mounted record.

umount

Unmount the trace. This action reverses a previous mount action, erasing the trace from the database and filebase. The snap/readyTrace record is not deleted, but remains available for remounting.

If no snap/readyTrace record is specified, then all lists are unmounted, except for the currently reported trace. While it is being reported, a trace cannot be unmounted.

ureport

Unreport the currently reported results. This action reverses a previous report action, unlinking the _readyTrace_report and _snap_report links, so that no trace is reported.

status

Print the status of all snap/readyTrace records. For example:

$ votrace status

M  /home/voff/votorola/out/votrace/snap-2011-bj-1/readyTrace-1
   /home/voff/votorola/out/votrace/snap-2011-bk-1
   /home/voff/votorola/out/votrace/snap-2011-bl-1/readyTrace-1
   /home/voff/votorola/out/votrace/snap-2011-bl-1/readyTrace-2
MR /home/voff/votorola/out/votrace/snap-2011-bl-1/readyTrace-3

The status flags are:

`M`	mounted
`R`	reported

options

--etc --etc=ready|mount|report|umount

Carry out all actions through to the specified end-action. For example:

$ votrace snap --etc=mount

The single command above is equivalent to these three commands, in order:

$ votrace snap

$ votrace ready

$ votrace mount

The end-action must be logically subsequent to the start action, otherwise it is ignored. If --etc is specified without an end-action, then it defaults to umount.

Output printing is suppressed for intermediate actions; the end-action alone prints its output. However, if --verbose is in effect, then all actions print their output as usual.

--churn

Churn the wiki cache. Replaces any stale pages with fresh copies from the streetwiki, prior to taking a snapshot of registrant input.

--verbose

Print additional information to standard output, as the actions are carried out.

caveats

Unlike a mounted file system, a mounted trace persists across system re-starts until explictly unmounted. So ‘mount’ is something of a misnomer.

votorola/a/register/
votorola.a.register

This section is obsolete. The design has shifted over to streetwikis and trustservers, and the admin manual has yet to be updated.

Each deployment area provides a voter registry, from which its voter lists are compiled. The voter registry is a public repository of user-specific attributes and inter-user trust edges. The user-specific attributes serve to record the eligibility credentials that are claimed by each user, while the inter-user trust edges serve to authenticate the claims. The collection of all attributes for a particular user comprises that user's registration. Each registration is keyed by email address, which serves as the primary user identifier.¹⁰

Registry synchronization. Shows a network of two jusrisdictional levels, with registration data passing from voters to registries. Data passes first to local registries, thence to higher jusrisdictional registries via the synchronization interface.

Voter input to a registry is synchronized throughout. The purpose of synchronization is single registration. Voters register at their local areas, as shown in the figure above. The registration data is then streamed from the local areas to higher juridictional areas, and thence throughout. So voters may register once and be eligible for polls at all jurisdictional levels.

File structure for a voter registry. Shows the structure for a typical offline vote-server. (Complete examples in `/home/voff/votorola/register` and `/home/vdev/votorola/register`.)
/home/voff/votorola/register register-run.js register.js

Configuration is specified by startup and runtime scripts located in the registry's service directory (shown above). The internal structure of the scripts is outlined in the figures below.

Startup configuration for a voter registry. Shows the hook function that is defined by the script `~/votorola/register/register.js`.
register.js function constructingRegister( regCC )

Runtime configuration for a voter registry. Shows the hook functions that are defined by the script `~/votorola/register/register-run.js`.
register-run.js - Compiling a Voter List ----------------------------- function indexingListEntry( listIC ) - Trust Network -------------------------------------- function extendingTrust( trustEC ) function trustBarUnregistered( destinationEmail, registerUID )

register-run.js

- Compiling a Voter List -----------------------------
    function indexingListEntry( listIC )

- Trust Network --------------------------------------
    function extendingTrust( trustEC )
    function trustBarUnregistered( destinationEmail, registerUID )

The registry also maintains a store of relational data, as shown in the figure below.

Database structure for a voter registry. Each registry has a table for doubt signals, and a table for registration input, from which the voter lists are compiled. Tables for the compiled voter lists (not shown here) are stored under the `out_list` schema.
out_list doubt in_registration

Setting Up the Registry

The minimal configuration already includes a registry. It will suffice for a minimal setup. Test it first, using the voter command shell.

$ voter register  hello

hello

$ voter test-a@zelea.com  register  set residence 170 Main Street, M1M 1A1

Old value:  none
New value:  170 Main Street, M1M 1A1

$ voter test-a@zelea.com  register  unset residence

Old value:  170 Main Street, M1M 1A1
New value:  none

It should respond as shown above.

Compiling a Voter List

A voter list is a snapshot copy of the register in which the network of trust edges is traced, and each voter's registration is evaluated at a particular level of trust. The compilation of the lists is configured by the runtime script register-run.js.

Runtime configuration for list compilation. Shows the hook function that is defined for this purpose by the script `~/votorola/register/register-run.js`.
register-run.js - Compiling a Voter List ----------------------------- function indexingListEntry( listIC )

To compile a voter list, use the tool volist:

$ nice volist

Lists may be compiled either one at a time, or repeatedly at scheduled intervals.⁶ Each newly compiled list creates a new snap/readyList record in the output filestore. For a quick overview of the records in the filestore, use volist status:

$ volist status

   /home/voff/votorola/out/volist/snap-2011-bh-1/readyList-1
   /home/voff/votorola/out/volist/snap-2011-bi-1/readyList-1
MR /home/voff/votorola/out/volist/snap-2011-bj-1/readyList-1

The newly compiled list is automatically mounted (M) and reported (R), making it immediately visible in all voter interfaces. At the same time, all previous lists are unmounted. To revert to one of the previous lists, simply remount it and re-report it. For example:

$ nice volist mount --etc \
~/votorola/out/volist/snap-2011-bi-1/readyList-1

$ volist status

   /home/voff/votorola/out/volist/snap-2011-bh-1/readyList-1
MR /home/voff/votorola/out/volist/snap-2011-bi-1/readyList-1
   /home/voff/votorola/out/volist/snap-2011-bj-1/readyList-1

Much like count records, list records will require occasional cleaning or archiving. It is best to clean the count records first, because you must be careful afterwards not to break the readyList links of those that remain. When cleaning the list records, you must avoid deleting the referents of those links. (It is usually safe to delete all records in a particular date range, unless you know that counts were tallied against older lists.)

votorola/a/register/trust/
votorola.a.register.trust

Trust Network

The trust network is a directed graph of user-to-user trust edges that are extended by the users for the purpose of cross-authenticating the voter registry. Individual trust edges are stored as public input to the registry. During compilation of a voter list, the edges are traced to determine the level of trust for each particular registration. These levels are then incorporated into the resulting voter list.¹¹

A trust edge extends from one registrant (source node) to another (destination node). It pertains to the following attributes of the latter's registration (D):

D.voterEmail
D.residence

The trust edge asserts, “Yes. That's the email address of my neighbour across the street, and she really does live there.” More formally:

D.voterEmail is the email address of a person (P) living at D.residence. It is not the email address of an imposter, posing as P.
D.residence is the primary residence of P.
P is registered exactly once at D.residence. For each other registration (E), where E.residence equals D.residence, E.voterEmail is the email address of a person other than P.

A given source node may extend trust to any number of destination nodes (subject to any bars imposed by the configuration), but may extend at most one edge to each. The extension of trust is configured and controlled by the runtime script register-run.js.

Runtime configuration for trust extension. Shows the hook functions that are defined for this purpose by the script `~/votorola/register/register-run.js`.
register-run.js - Trust Network -------------------------------------- function extendingTrust( trustEC ) function trustBarUnregistered( destinationEmail, registerUID )

In a fully elaborated network, each destination node is evaluated at a particular level of trust, which is recorded in its entry in the voter list. The recorded level (t) depends exclusively on the levels among the source nodes, where it is calculated as the highest level that does not exceed the count n(t) of sources at that level or higher. In other words, to have a trust level of 3, a voter must have 3 or more immediate trust sources, each itself having a trust level of 3 or higher.

t ≤ n(t)

where:: (t) is the trust level; n(t) is the count of immediate source nodes at level (t) or higher

The ultimate trust source is the root node, which is the registrar. All trust edges must be traceable to the root, otherwise they are discounted in the elaborated network. Unlike an ordinary node, the root has a high (effectively infinite) trust level, and it may extend any number of edges (primary trust edges) to the same destination.

The maximum trust level in the network, max(t), is limited both by the redundancy of primary edges, and by the number and distribution of primary destinations. As a rule, to attain a network with a max(t) of 3 requires a minimum of 3 destinations, with a minimum of 3 edges to each. Furthermore, in order for the primary destinations to propagate max(t) to other voters, at least max(t) of them must cooperate as a group in extending their edges to further destinations. In practice therefore, the primary destinations must be grouped such that:

group size n ≥ max(t);
members cooperate with each other; and
members are located closely enough such that common destination nodes do not exceed the range limitations imposed by register-run.js.

A typical register-run.js will impose range limits on trust extension. Network activity is thus localized to neighbourhood scales, where it may be moderated by everyday social constraints. Rogue sources may not inject trust from afar, and be shielded by distance from the fallout. All trust is locally traceable and locally accountable. (The range limits imposed on individual edges must nevertheless allow for sufficient overlap, so the overall network is not limited in extent. Trust extension ought not to be limited to a single postal code area, for example; but rather to multiple, contiguous areas.)

Doubt Signaling

Doubt signaling is an adjunct facility in the trust network. It serves to formally indicate suspicious voter registrations. A doubt signal extends from one voter (source) to another (destination). The source may extend signals to any number of destinations, but may extend at most one to each.

The negative messages of doubt signaling are complementary to the positive messages of the trust network. However, doubt signals propagate in a separate network of their own. The two polarities of message are kept apart, and never cancel each other in combination. This separation prevents instability that might arise if, for example, contention among sources and destinations were to lead to a tit-for-tat escalation of messages. This is prevented because the formal authenticity of the register depends only on the positive messages of the trust network. The negative doubt signals serve only to indicate that particular destinations in the network (particular voter registrations) are suspicious, and that the trust sources and registrars ought to consider withdrawing their trust from them. But the actual withdrawal does not follow automatically. Rather it is conditional on the understanding and agreement of the trust sources. Social inter-mediation of the opposing networks thus dampens any tendency to systematic instability. (The response time for withdrawal is nevertheless likely to be faster than any subsequent re-extension of trust to the untrustworthy destinations, so the asymettry between the two should be sufficient to deter abuse of the registry.)

Being the target of doubt signals does not formally affect a voter's inclusion in the voter list, nor her eligibility to vote in polls. Doubt signals are not needed therefore in order to compile a voter list, especially outside of the local area. Consequently they are not considered as part of the core voter input, and are not synchronized up to the super-areas.

votorola/a/count/
votorola.a.count

Polls and Vote Counts

Poll Commands for Voters
1. unvote
2. vote
Counting the Votes

A deployment area may provide any number of polls. A poll is a collection of votes that are stored in a public repository from which vote counts are generated. The poll is provided by the lowest sub-area that is able to compile a complete list of eligible voters from its own registry. For example, a poll on the issue of electing a member to a national assembly would be provided by a local area (regional or municipal), because the constituencies for such a non-proportional assembly are local. On the other hand, a poll to propose a legislative bill for the same assembly would be provided by a national super-area, because such bills are national issues, on which everyone is entitled to vote. (A super-area would also host any local poll for which the voter list happened, somehow, to straddle the boundary between two local sub-areas.)

Multiple polls in a subnet. Shows a network of two jusrisdictional levels, with data passing from the voters to the polls. Each poll is hosted at a deployment area that receives input directly from the voters.

File structure for polls. Shows the structure for a minimal, offline vote-server. (Complete examples in `/home/voff/votorola` and `/home/vdev/votorola`.)
/home/voff/votorola/ ··· poll-service.js

The vote-server is configured by its configuration script, located in the votorola directory (shown above). The internal structure of the script is outlined in the figure below.

Startup configuration for a poll. Shows the hook functions that are defined by the script `~/votorola/poll-service.js`. (Complete examples in `/home/voff/votorola` and `/home/vdev/votorola`.)
poll-service.js function castingVote( vCC ) function constructingPoll( pollCC ) function pollConstructed( poll ) function voterBarUnknown( voterEmail ) function voterBarUnregistered( voterEmail, registerUID )

poll-service.js

    function castingVote( vCC )
    function constructingPoll( pollCC )
    function pollConstructed( poll )
    function voterBarUnknown( voterEmail )
    function voterBarUnregistered( voterEmail, registerUID )

Polls also store relational data, as shown in the figure below.

Database structure for polls. All polls share a single table to store votes and other voter input. Tables for counts (not shown here) are stored under the `out_count` schema.
out_count in_vote

Poll Commands for Voters

This section documents the command/response interface of a poll. The command/response interface is responsible for servicing the command oriented clients of the poll, such as the mail-based voter interface, and the voter command shell. The following general-purpose commands are provided:

hello
help
version

In addition, the poll provides a couple of special-purpose poll configuration and voting commands. These are documented below.

reconstruct

Reconstruct a count from scratch.

    reconstruct

The service constucts the poll from scratch by ignoring any configuration
items that were cached in previous constructions.  It replies with detailed
progress reports that are generated during the reconstruction process.

unvote

Withdraw a vote from a count.

    unvote

The service replies, confirming the withdrawal:

    Sys/p/sandbox

    You were voting for:     mychoice@somewhere.net
    You are now voting for:  nobody

If you change your mind later, and wish to vote again, use the 'vote' command.

vote

Cast a vote in a count.

    vote CANDIDATE-EMAIL

    vote [--alter VOTER-EMAIL]

You can vote for anyone you choose.  All you need is a person's email address.
For example:

    vote myChoice@somewhere.net

To recall who you last voted for, simply send:

    vote

The service replies, identifying the recipient of your vote:

    Sys/p/sandbox

    You are voting for:  myChoice@somewhere.net

If that person also casts a vote, then your vote is carried with it.  Whoever
gets that person's vote also get yours.  And so on.  Your vote is carried
until it reaches someone who does not vote.  This is called a 'delegate
cascade'.  At the end of the cascade, votes accumulate to reveal the favoured
candidates.

A trace of the cascade is included in the reply, so you can follow the path of
your vote, and see who ultimately receives it.  Or you can mark the vote as
non-cascading, so it stays put until you change it:

    vote --cascade no  (however, this option is not yet implemented)

To see how another voter is voting, send:

    vote --alter VOTER-EMAIL

To change your vote, send another 'vote' command.  Or withdraw it altogether
using 'unvote'. 

[There is currently no easy way to see who is voting for you, or to view the
overall results.  This will be corrected in the beta release.]

Counting the Votes

A vote count is a snapshot copy of the results of a poll in which the flow of votes is traced, and the total received by each candidate is recorded. The count is configured by the runtime script poll-run.js.

Runtime configuration for a vote count. Shows the hook functions that are defined for this purpose by the script `~/votorola/poll/services/SERVICE-NAME/poll-run.js`.
poll-run.js - Counting the Votes --------------------------------- function castingVote( vCC ) function voterBarUnknown( voterEmail ) function voterBarUnregistered( voterEmail, registerUID )

poll-run.js

- Counting the Votes ---------------------------------
    function castingVote( vCC )
    function voterBarUnknown( voterEmail )
    function voterBarUnregistered( voterEmail, registerUID )

To count the votes, use the tool vocount. A voter list must already be mounted and reported.

$ nice volist  # if a new list is need

$ nice vocount

Counts may be conducted either one at a time, or repeatedly at scheduled intervals.⁶ Each separate count creates a new snap/readyCount record in the output filestore. For a quick overview of the records in the filestore, use vocount status:

$ vocount status

   /home/voff/votorola/out/vocount/snap-2011-bh-1/readyCount-1
   /home/voff/votorola/out/vocount/snap-2011-bi-1/readyCount-1
MR /home/voff/votorola/out/vocount/snap-2011-bj-1/readyCount-1

The new count is automatically mounted (M) and reported (R), making the results immediately visible in all voter interfaces. At the same time, all previous counts are unmounted. To revert to one of the previous counts, simply remount it and re-report it. For example:

$ nice vocount mount --etc \
~/votorola/out/vocount/snap-2011-bi-1/readyCount-1

$ vocount status

   /home/voff/votorola/out/vocount/snap-2011-bh-1/readyCount-1
MR /home/voff/votorola/out/vocount/snap-2011-bi-1/readyCount-1
   /home/voff/votorola/out/vocount/snap-2011-bj-1/readyCount-1

Snap/readyList records will accumulate in the filestore over time, as new lists are compiled. For the offline vote-server, the records may be cleaned away by simply erasing the entire filestore, using the script vox-clean.

The online vote-server ought to be cleaned more carefully. Provided a particular list is not currently mounted (M), and no poll readyList links are pointing to it then its snap/readyList subdirectory may be deleted from the output store. Deletion will cleanly remove all traces of it from the vote-server. Any snap directory that is left childless (without a snap/readyList subdirectory) may likewise be deleted.

It is also possible to move snap/readyList records. You may wish to archive them, for example. When moving any particular record, be sure to include the parent snap directory and its immediate files. (There is no need to include sister snap/readyList records that happen to share the same parent, you may move them independently.) In addition, when a count record is moved, its linked readyList record must also be moved.⁸

File structure the web interface. Shows the structure for a minimal deployment area with two vote-servers: an online server `v`, and an offline server `voff`. In this example, the servlet container Tomcat is set up to run the web interface of vote-server `voff`. (Complete examples in `/home/voff/votorola/web` and `/home/vdev/votorola/web`.)
`CATALINA_BASE` (Tomcat) conf Catalina localhost voff.xml -> /home/voff/votorola/web/voff.xml server.xml web.xml ··· home v votorola ··· out ··· web v.xml ··· voff votorola ··· out ··· login-persistence.serial web-activity-list.serial web voff.xml vowicket.js

Startup configuration for the web interface. Shows the hook functions that are defined by the script `~/votorola/web/vowicket.js`.
vowicket.js function constructingVOWicket( wicCC ) function initializingVOWicket( web )

votorola/s/mail/
votorola.s.mail
rough draft

Mail User Interface

Setting Up the Mail Interface
Mail Commands for Voters
1. hello
2. help
3. version
Challenge-Response Authentication

This section concerns the mail-based voter interface (mail interface). The mail interface is currently only documented in rough draft. It is not required for a minimal installation.

File structure for the mail interface. Shows the structure for a typical offline vote-server. (See also the working examples.)
/home/voff .tmda ··· Maildir ··· votorola ··· mail mail-meta-service-run.js mail-meta-service.js voface-mail.js

Startup configuration for the mail meta-service. Shows the hook function that is defined by the script `~/votorola/mail/mail-meta-service.js`. (Complete example in `/home/vdev/votorola/mail`.)
mail-meta-service.js function constructingMailMetaService( metaCC )

Runtime configuration for the mail meta-service. Shows the hook function that is defined by the script `~/votorola/mail/mail-meta-service-run.js`. (Complete example in `/home/vdev/votorola/mail`.)
mail-meta-service-run.js function serviceEmail( service )

Startup configuration for the mail-based voter interface. Shows the hook function that is defined by the script `~/votorola/mail/voface-mail.js`. (Complete example in `/home/vdev/votorola/mail`.)
voface-mail.js function constructingVOFaceMail( mailCC )

# # # # # # # # # #

- inner response layer, to respond to (act on) authenticated messages
- structure and function
    - MessageResponder.java feeds commands to voter services; gathers their responses;
      and transmits them back to sender
- in exceptional cases, the responder may act repeatedly on the same message
    a) if processing of a message is interrupted by a server failure,
       the message will be reprocessed on a subsequent run
        - it is therefore possible that users will see multiple replies to a single message
            / but most re-processed messages will generate only a single reply
    b) a user might re-send a message
    - in any case, no critical anomalies will occur from partial processing of messages,
      or from repeated response to some/all of the commands they contain
- localization
    - respond with language, date formats, etc. according to sender's MIME header
      Content-Language, per RFC 3282 
        - http://www.ietf.org/rfc/rfc3282.txt
        - some canned messages will not be localized:
            - error messages
                - expected to be rare
                - typically in English, or programmer's language
            - bar descriptions from runtime configuration scripts
                - difficult to localize, so this is postponed
                - will be in primary language(s) of the deployment area's internet domain
    - respond in UTF-8
        - 7-bit characters (ASCII) will pass cleanly
        - 8-bit will be over-encoded for email (in whatever standard it uses)
            / presumeably the user's client can decode it,
              if they are used to receiving non-ASCII messages

Setting Up the Mail Interface

Ensure you have s mail transfer agent (MTA) that is configured to receive mail for your vote-server account. Votorola has been tested with qmail, but it should work with any MTA that is supported by TMDA.
Set up an inbox for the mail interface. The default (which you can change in your configuration script, farther below) is:
```
~/Maildir
```
Messages for all voter services (service-name@HOST.DOMAIN.DOM) will be delivered to this inbox.
[Create configuration scripts for the mail interface.]
Test the meta-service from the command-line.
```
$ voter mail hello
```
```
hello
```
Run the mail interface, voface-mail.
```
$ voface-mail &
```
It is running in the background, so use fg if you ever need to foreground it.

Deliver an email message for the meta-service, using vodeliver.

$ echo 'Return-Path: <me@domain.dom>
Delivered-To: voff@HOST.DOMAIN.DOM
Date: Thu, 19 Nov 2009 12:24:37 -0400
Content-Language: en-US
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
To: voff@HOST.DOMAIN.DOM
From: me@domain.dom
Subject: this is a test message...

hello there

help me please' | vodeliver

That should put a message in the inbox. Vomailrd should pick it up, and send a reply to me@domain.dom, within about 20 seconds.

Use your ordinary mail client to send a message to the vote-server at the same address, voff@HOST.DOMAIN.DOM. If your MTA receives the message and delivers it to the vote-server inbox, then you should get a reply momentarilly.
Configure the MTA to deliver messages for all voter services (registry and polls) to the vote-server inbox. (For qmail, see the example /var/qmail/alias directory in the appendix.)
Send a message to the voter registry (register@HOST.DOMAIN.DOM), consisting of the single line:
```
help
```
You should get a reply momentarilly.

Test a poll too, by sending a help command to SERVICE-NAME@HOST.DOMAIN.DOM.

The interface will not support voter-input commands (such as 'vote'), until the authentication layer (below) is in place. If a voter-input command is received, then voface-mail will terminate with an error message.

Mail Commands for Voters

This section documents the command/response interface of the mail meta-service. The meta-service provides bootstrap instructions on accessing the voter services, as well as general information about the vote-server. Its commands are accessible by mail clients, and through the voter command shell. For access from the shell, the service name is “mail”. For example:

$ voter mail version

Votorola 0.2.3

hello

Ping the service, say hello to it.

    hello

    hello TEXT

The service replies 'hello'.  Any TEXT arguments are ignored.

help

Request general information on the service, and instructions on using it.

    help

The service replies with information and instructions.

To request help for a specific command, try 'COMMAND --help';  for instance
'vote --help'.

version

Ask what version of software the vote-server is running.

    version

The service replies with the version.

Challenge-Response Authentication

The mail interface authenticates messages in order to verify sender identity. The only authentication method currently supported is a handshake across a challenge filter. The apparent sender must reply to a specific challenge (Did you send this message?) before the message is accepted.

# # # # # # # # # #
- this section concerns the basic authentication layer of the mail interface
- outer authentication layer, to authenticate address of sender
    - bypassed if message contains no command that requires authentication
        / some messages, such as read-only queries, do not require authentication
    - different methods of authentication will eventually be available,
      according to voter choice
        / e.g. challenge filter, or signed email
        - but challenge filter is the only one implemented at present

    - structure:
        1. mail/tmda-filter-wrapper
        2. Tagged Message Delivery Agent (TMDA)
        3. spam filter, to suppress challenge of obvious spam
    - usage #TMDA
    - function
        - nominal senders are challenged in order to authenticate them as actual senders
        - once authenticated, messages pass to the response layer
    - localization
        - challenge message (TMDA template) will be in language(s)
          of sender's internet domain
        - otherwise:
            / global area might be the only one that needs this
            - use the top-level domain (country code) of the sender's address
              to select an appropriate template (which may itself be multilingual)
            - see TMDA configuration variable TEMPLATE_DIR_MATCH_SENDER
                / this is the best TMDA can do, at present;
                  (it cannot read standard MIME headers, as the response layer does, below)

Ensure you have Tagged Message Delivery Agent (TMDA) — any recent version.
Ensure you have Perl 5:
```
$ perl --version
```

# # # # # # # # # #
- basic TMDA
- not forgetting to gen. a crypt_key
= test TMDA

# # # # # # # # # #
= ensure you have libraries needed by tmda-filter-wrapper,
  by test running it, without arguments

# # # # # # # # # #
= set up MTA and TMDA for voter authentication
    - e.g., by following the example configuration
- note the CAVEATS in tmda-filter-wrapper
    - it may need tweaking for your MTA

1.	It is not yet clear that synchronization of raw voter input data will be sufficient for registrations. Super-areas may find it difficult to compile their voter lists from scratch, because compiler configuration may vary depending on the sub-area of origin.
2.	Mounts may become inaccessible owing to structural changes in the database tables, files or code. Unmounting prior to each upgrade will avoid exceptions such as `java.io.InvalidClassException ... serialVersionUID`, and orphaned tables and files. In any case, you may recover normal operations by remounting.
3.	If you make frequent code changes (developer) you may want to disable session persistence entirely. See example/full/home/vdev/votorola/web/vdev.xml.
4.	Write permission for the `votorola` group need not actually be set for all vote-server files. This is mostly a convenience for human members of the group such as administrators; process members such as the servlet container (`tomcat`) only need write access to certain directories, including `~/votorola/in/` and `~/votorola/out/`.
6.	Runs of `votrace`, `vocount` and other results compilers may be scheduled using a `crontab` utility. Here is an example of a `crontab` configuration file for an online vote-server: MAILTO=mike@zelea.com CBIN=/home/v/votorola/code/votorola/s/_/bin # Min Hour Etc Command 25 0-23/4 * * * nice $CBIN/votrace --churn; sleep 30s; nice $CBIN/vomir; sleep 30s; nice $CBIN/vocount This configuration recompiles the results every 4 hours, at 25 minutes past the hour. In order to guard against timed exploits, however, it might be better to add a degree of randomness to this schedule.
7.	For a script to simplify switching between on and offline web interfaces, see: http://reluk.ca/system/host/obsidian/usr/local/bin/vox-tomcat-context.
8.	Symbolic links created in the output filestore are not currently relative. They must therefore be recreated in archival copies, to point internally. Alteratively, the links may be replaced with copies of the entire referent (not yet tested).
9.	For an example backup script, see: http://reluk.ca/system/host/obsidian/usr/local/bin/vox-backup.
10.	The method of user identification is constrained by the following requirements. Each identifier must be: Globally unique. No two registrants may have the same identifier, even if they are registering on different vote-servers. Machine readable and stable. The combination of name and street address that suffices for traditional voter registries will not work. The identifier must remain constant despite name changes (addition of titles, marriage) and despite relocation of residence. Known in advance of registration. Voters must be able to nominate and vote for a candidate who is not yet registered. The nominee's identifier must therefore be known in advance of registration. Verifiable against actual identity. In the trust network, each trust edge is an assertion that a particular identifier corresponds to a particular person. The extender of trust must be able to verify this correspondence, at least when challenged. The method that most easily meets all requirements is an email address. The requirement of nomination (3), in particular, is satisfied by the fact that an email address identifies not only a person, but also a communication channel. It is therefore likely to be known by others, so they can start voting for the addressee right away, and post relevant information in the pollwiki. Prior knowledge of the identifier also simplifies verification (4). Any identifier can be verified by a formal handshake between two parties (doubter and doubted), but a typical user would have to be guided through the process. A familiar email address that is recognized in advance, however, requires no handshake at all. Even if it is not recognized, the handshake can be informal, because an imposter would eventually be exposed through everyday communication. On the other hand, using email addresses as identifiers is likely to expose users to additional spam in their mail boxes. The usual remedies will not work here. Naive obsfuscations ("at" for "@" etc.) do not work at all, because the harvesting bots can see through them. Captcha guards cannot be used, because all registration and voting data is ultimately made public. The votes in particular must be published in machine-readable format for purposes of verification, and each vote is a couplet of email addresses. Closing this data to spammers would also close it to public verification. The whole verification process would then be suspect and the legitimacy of the polls questioned. So the possibility of increased spam will be a concern for some participants who lack adequate protections, at least until we have a fix for the general problem of spam. (That in itself may be something to vote for.)
11.	The design of the neighbourhood trust network was intially sketched by Michael Allan.¹²
12.	Open electoral system (strawman plan). APSA_ITP, mailing list of the American Political Science Association, Information Technology and Politics Section, August 2007. http://lists.hmdc.harvard.edu/lists/apsa_itp_at_lists_hmdc_harvard_edu/2007_08/threads.html#00037
13.	In the event that `binfmt_misc` cannot be enabled, you may want use scripted launchers for the Votorola commands. Here are some examples (somewhat out of date): /home/vdev/votorola/bin/volaunchers.

`~`	vote-server home directory
`$`	BASH command prompt
`ITEM`	variable, subtitute your own value for `'ITEM'`
`[item]`	optional item in a command, type 'item' or nothing
`a \| b`	choice of items in a command, type either 'a' or 'b'

Votorola Software Manual

Deployment Areas and Vote-Servers

Setting Up a Deployment Area

Setting Up the Offline Vote-Server

Testing the Vote-Server

Setting Up the Online Vote-Server

Pollwiki

Setting Up the Pollwiki

Vote-Servers

Installing Votorola

Procedure

Creating a Vote-Server

Upgrading Votorola

File Server

Database Server

Setting Up Database Access for a Vote-Server

Command Line

vocount — count the votes

synopsis

description

actions

options

caveats

vodeliver — deliver an email test message

synopsis

description

voface-mail — respond to voter messages

synopsis

description

voharvest — harvesting off-site messages

synopsis

description

volist — compile a voter list

volog — log test messages

synopsis

description

vomir — pull remote votes for mirroring

synopsis

description

vonop — do nothing

synopsis

description

voqproperties — print the runtime properties

synopsis

description

voscript — compile a configuration script

synopsis

description

voter — issue a voter command

synopsis

description

see also

votrace — trace a neighbourhood trust network

synopsis

description

actions

options

caveats

Registry and Lists

Setting Up the Registry

Compiling a Voter List

Trust Network

Doubt Signaling

Polls and Vote Counts

Poll Commands for Voters

reconstruct

unvote

vote

Counting the Votes

Web Servlet Interface

Setting Up the Web Servlet Interface

Web API

Mail User Interface

Setting Up the Mail Interface

Mail Commands for Voters

hello

help

version

Challenge-Response Authentication

Examples of Vote-Server Configuration