Site Network
A site network is a wide-area network
of sites that run Votorola, and share common streams of voter input.
The sites are of two types: core sites that provide essential voter services,
and peripheral sites that provide extended services.
All sites are interconnected by synchronization interfaces,
through which they share common streams of voter input data.
(The site network needs a redesign,
as does the register.)
Core Subnets
Core subnets
form the administrative backbone of the system.
A core subnet is composed of one or more core sites
that are interconnected to form a proper tree,
the structure of which mirrors the formal hierarchy of a sovereign jurisdiction,
in whole or part.
Subnet communications consist primarily of voter registration data
that streams from sub-site to super-site.
This enables a single registration facility,
wherein the voters register once, and are eligible for all polls throughout the subnet.
Other than this, the nodes of the subnet are expected
to be largely independent of each other; no administrative hierarchy is intended.
The purpose of having more-or-less independent sites,
as opposed to a centrally administered system, is two-fold:
i) to broadly distribute the costs and incentives of administration; and
ii) to narrowly root the provision of services within the communities that are served.
The role of the sub-sites in this arrangement is to divide the administrative burden
horizontally across multiple jurisdictions,
while the role of the super-sites is to divide it vertically across multiple levels.
Local representatives, mayors and bylaws are voted at local sub-sites,
while heads of state and national laws are voted at super-sites.
How this is done, exactly, is a site decision.
Peripheral Subnets
Peripheral subnets
are composed of one or more nodes
(peripheral sites) that are interconnected
to receive a common stream of voter input data from a core site,
either directly or indirectly.
Peripheral subnets may be relatively unstructured.
They may attach ad hoc to the core subnet. They need not form proper trees,
nor need their nodes always correspond to proper jurisdictions.
Peripheral sites are expected to offer extended services,
such as additional polls, voter interfaces, analyses, and system oversight.
In the figure above, for example, the peripheral sites include
a pair of global sites that provide international polls (top);
a local site that provides regional, cross-border polls (middle);
and a local site that provides extended services for a single core site (right).
Synchronization Interface
The synchronization interface
is the primary connector in the site network.
It transmits unidirectional streams of voter input
upward to core super-sites, and outward to perpipheral sites.
The design of the synchronization interface is still undecided.
It is expected to be based on a database synchronization protocol,
such as Postgresql Slony-I or Oracle streams.
In anticipation of this, all raw, public voter input
is currently being stored in separate
voter input tables.
Each table has a fixed columnar structure, comprising the primary keys,
and a single XML column for data.1
Core Sites and Pollservers
A core site
provides essential voter services to the population of a single sovereign jurisdiction
such as a state, or a sovereign-designated sub-jurisdiction such as a municipality.
The provision of basic voter services depends on three types of server:
pollserver, file server and database server.
Setting Up a Core Site
This section outlines the minimal procedure for setting up a core site.
The site will serve the population of a single local jurisdiction,
such as city or region. It will provide basic registration services,
polling services, and a Web interface. It will include two pollservers:
an off-line server (voff) for test purposes,
and an on-line server (v) for public use.
Setting Up the Off-Line Pollserver
-
Install Votorola
(2.3.1).
-
Set up database access for the pollserver voff
(2.5.1).
-
Create the pollserver voff
(2.3.2).
-
Set up the voter register
(4.1).
-
Set up an initial test poll
(5.1).
-
Set up the pollwiki
(2.2.1).
-
Set up the Web voter interface
(6.1).
Testing the Pollserver
-
Test voff by running a voter simulation,
using the example script
vosim-alex.
This script should already be on the pollserver's path.
Ensure you are logged in as voff,
then run the script with a small group of simulated voters.
For example, run it for the group (a1, a2, a3, b1, b2, b3):
$ vosim-alex ab 1-3
sim-a1@zelea.com register set residence 146 A Street, M5N N5N
sim-a1@zelea.com test-p vote sim-a@zelea.com
sim-a2@zelea.com register set residence 147 A Street, M5N N5N
sim-a2@zelea.com test-p vote sim-a@zelea.com
sim-a3@zelea.com register set residence 148 A Street, M5N N5N
sim-a3@zelea.com test-p vote sim-a@zelea.com
sim-b1@zelea.com register set residence 147 B Street, M6O O6O
sim-b1@zelea.com test-p vote sim-b@zelea.com
sim-b2@zelea.com register set residence 148 B Street, M6O O6O
sim-b2@zelea.com test-p vote sim-b@zelea.com
sim-b3@zelea.com register set residence 149 B Street, M6O O6O
sim-b3@zelea.com test-p vote sim-b@zelea.com
It ouputs a list of voter commands.
-
Now run the commands by piping them to the voter shell:
$ vosim-alex ab 1-3 | voter
Old value: none
New value: A1
Old value: none
New value: 146 A Street, M5N 5N5
Old value: none
New value: http://www.onefreeminute.net/#a1
Old value: none
New value: Simulated voter, registered by vosim-alex.
test-p
You were voting for: nobody
You are now voting for: sim-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.
$ nice volist
If the Web interface is running,
you should see six registrations in the voter list at:
http://localhost:8080/voff/w/Register/
-
Count the votes.
$ nice vocount
You should see a tie between two leading candidates (a and b),
at 3 votes apiece:
http://localhost:8080/voff/w/Pollspace/?p=test
-
Test the interface to the pollwiki by clicking on a candidate's
![[wiki/chaos symbol]](../a/web/base/chaos-12.png)
link.
It should take you to the candidate's position page.
The page will have no text, however, until the candidate creates it.
-
When you are finished, you may wish to erase everything
from the pollserver using the script vox-clean.
First inspect the script in your editor.
$ emacs `which vox-clean`
Ensure the contents of subroutine clean() are uncommented,
in order to erase registrations, list, votes, counts and everything.
Then run it:
$ vox-clean
removing database table: in_registration
DROP TABLE
removing directory: /home/voff/votorola/out/volist
removing database schema: out_list
NOTICE: drop cascades to table out_list."2009-bj-1-neighbourhood-1"
NOTICE: drop cascades to table out_list."2009-bj-1-trust_edge-1"
NOTICE: drop cascades to table out_list."2009-bj-1-list_node-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."2009-bj-1-count_node-1"
DROP SCHEMA
List of schemas
Name | Owner
--------------------+----------
information_schema | postgres
pg_catalog | postgres
pg_toast | postgres
public | postgres
(4 rows)
List of relations
Schema | Name | Type | Owner
--------+---------+-------+-------
public | doubt | table | voff
public | geocode | table | voff
public | user | table | voff
(3 rows)
You should no longer see any voter list, nor any poll results:
http://localhost:8080/voff/w/Register/
http://localhost:8080/voff/w/Pollspace/?p=test
Setting Up the On-Line Pollserver
After working with voff, and configuring it as required,
you will be in a position to set up the on-line pollserver v.
This is the general pattern to follow for all software and configuration upgrades:
first test them off-line, then transfer them on-line.
Simply repeat the setup procedure above,
but this time for pollserver v.
Copy its initial configuration from voff,
and amend all references to the pollserver name. To find all references:
$ find ~/votorola -name code -prune -o -name out -prune \
-o -type f -exec grep voff {} +
Pollwiki
The pollwiki provides users
with knowledge-base services and drafting facilities.
The drafting facilities are for the purpose of editing candidate proposals
and other position drafts. They are provided only as a convenient default.
Candidates are free to use their own drafting facilities,
and may store their documents at any location.
Knowledge-base services include distributed analyses such as classification,
and distributed data input. Future releases of Votorola
will be able to communicate with multiple knowledge bases.
Again, the pollwiki is provided as a convenient default for this purpose.
Votorola works with any version of MediaWiki
that is compatible with the Semantic MediaWiki extension.
A single wiki may be shared between the on-line and off-line pollservers.
The likelihood of collisions between the two is probably minimal.
Setting Up the Pollwiki
-
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”.
Consider using the
short title
of your pollserver, as set in ~/votorola/pollserver.js.
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.
Note the special
instructions for PostgreSQL.
Despite what the instructions say,
the MediaWiki tables need not be
“accessible without explicit schema qualification”.
The SQL commands to run before creating any pages
must therefore be schema qualified. The corrected commands are:
$ select max(smw_id) from mediawiki.smw_ids;
max
-----
50
(1 row)
$ alter sequence mediawiki.smw_ids_smw_id_seq restart with 50;
When Semantic MediaWiki is fully installed,
create a test page in some unimportant place.
Wehn you save the page, you may see an error like this:
PHP Warning: pg_query() [function.pg-query]: Query failed: ERROR: duplicate key value violates unique constraint "smw_ids_pkey" in /var/www/localhost/htdocs/mediawiki/includes/db/DatabasePostgres.php on line 576
It should then recover. You should not see this error again.
Probably it can be avoided by restarting the sequence (above)
from 51 (one higher than max). But this has not been tested.
-
Reconfigure the wiki to use
pretty URLs
like those on Wikipedia. Votorola expects to find
each user's page at an address that looks like this:
http://localhost/wiki/User:USERNAME
and not like this:
http://localhost/wiki/index.php5?title=User:USERNAME
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
Pollservers
A pollserver is
a server that provides polls and other voter services.
A core site typically has a pair of pollservers,
one for on-line public use, and one for off-line testing.
Each pollserver 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 pollserver name.
Conventional pollserver names are v and voff.
The configuration of each pollserver is specified by its startup script,
located in the votorola directory (shown above).
The internal structure of the script is outlined in the figure below.
Each pollserver maintains a store of relational data, as shown in the figure below.
Installing Votorola
Unix is required. Although testing is currently limited to Linux,
it should also work with other versions of Unix.
Java 6 is required.
$ java -version
Procedure
-
Create the votorola group.
This will be the default group for all pollserver accounts.
$ groupadd votorola
-
Add yourself to the group.
$ usermod --append --groups votorola MYLOGIN
This is a convenience, enabling you to edit a pollserver's files
without having to login in under the pollserver account.
-
Download votorola-0.1.12.tar.gz.
-
Unpack it.
$ tar --extract --gzip --file votorola-0.2.2.tar.gz --dir /opt
You may actually unpack it anywhere.
This manual assumes the /opt directory.
-
Test one of Votorola's executables. Test it the long way, first:
$ java -jar /opt/votorola-0.2.2/votorola/s/bin/voqproperties | sort
file.encoding=ISO-8859-1
file.encoding.pkg=sun.io
file.separator=/
. . .
Do not place these executables on the path yet.
We'll do that later, when we create a pollserver.
-
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:13
$ /opt/votorola-0.2.2/votorola/s/bin/voqproperties | sort
For instructions on enabling this, see the example script
jar-wrapper.
Creating a Pollserver
-
Create the pollserver's user account.
$ useradd voff --gid votorola --create-home
$ passwd voff
-
Set the file creation mask so that all new files
are writeable by the votorola group.4, 5
For example, add this line to the pollserver'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 pollserver's path:13
PATH=$HOME/votorola/bin:$HOME/votorola/code/votorola/s/bin:$PATH
-
If necessary, add the pollserver 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 the engine's socket file is restricted
to the postgres group.
The typical location of the socket file
is /var/run/postgresql/.s.PGSQL.5432.
-
Login as the pollserver.
-
In the pollserver'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.2/ ~/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/
Confirm that the output directory is writeable
by the votorola group.4
$ stat ~/votorola/out/
File: `/home/voff/votorola/out/'
Size: 4096 Blocks: 8 IO Block: 4096 directory
Device: 803h/2051d Inode: 16199 Links: 2
Access: (0775/drwxrwxr-x) Uid: ( 1006/voff) Gid: ( 1008/votorola)
. . .
-
Test that Votorola's executables are accessible.
For example:
$ voqproperties | sort
file.encoding=ISO-8859-1
file.encoding.pkg=sun.io
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:
5-May-2008 2:47:59 PM votorola.a.line.VOLog main
INFO: volog is running with arguments []
5-May-2008 2:47:59 PM votorola.g.logging.LoggerX test
OFF: testing SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST and ALL...
5-May-2008 2:47:59 PM votorola.g.logging.LoggerX test
SEVERE: this is SEVERE
5-May-2008 2:47:59 PM votorola.g.logging.LoggerX test
WARNING: this is a WARNING
5-May-2008 2:47:59 PM votorola.g.logging.LoggerX test
INFO: this is INFO
You may want to increase the verbosity level for the off-line pollserver
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.
Upgrading Votorola
-
Download the new version of Votorola.
-
Unpack it.
$ tar --extract --gzip --file votorola-VERSION.tar.gz --dir /opt
At this point, you should be reading from the newly installed system manual.
-
Stop any processes that are running for the off-line pollserver.
-
Unreport and unmount any mounted counts and lists.2
$ vocount ureport && vocount umount
$ volist ureport && volist umount
-
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)
Otherwise, Tomcat may experience serialization errors at next startup,
as it tries to recover sessions from the previous run.3
-
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 pollserver's public archives.
The main purpose of the public archives
is to support results verification.
Results are always based on discrete snapshots of voter input and administrative data.
Whenever results are reported, a copy of the results
together with the snapshot of the data on which it is based
are combined into a single archive, and published through the file server.
One may independently download the archive and recount the votes.
When this is combined with tests of the accuracy of input data
(e.g. by random spot checks) it provides complete verification of reported results.
The verification facility is not implemented, however,
in the current version of Votorola;
so a public file server is not actually required yet.
A secondary purpose of the file server is to store backup data,
as insurance against a database loss.9
Database Server
The database server
provides one or more databases for each pollserver.
Databases contain administrative data; raw voter input;
streamed synchronization of voter input from site to site;
and mounted voter lists and poll counts.
Votorola requires the PostgreSQL database management system (DBMS),
version 8.3 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.
Setting Up Database Access for a Pollserver
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 pollserver,
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 pollserver.
-
Create a pollserver database, with the same name as the pollserver.
$ createdb --owner=voff voff
votorola/a/register/
votorola.a.register
Register and Lists
Each core site provides a voter register,
from which its voter lists are compiled.
The voter register 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.10
(The register needs a redesign,
to meet the requirements of a common
registration framework.)
Voter input to a register is synchronized throughout the core subnet.
The purpose of synchronization is single registration.
Voters register at their local sites, as shown in the figure above.
The registration data is then streamed from the local sites to higher juridictional sites,
and thence throughout the subnet. So voters may register once
and be eligible for polls at all jurisdictional levels.
Configuration is specified by startup and runtime scripts
located in the register's service directory (shown above).
The internal structure of the scripts is outlined in the figures below.
The register also maintains a store of relational data,
as shown in the figure below.
Setting Up the Register
The minimal configuration
already includes a register. 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.
Register Commands for Voters
This section documents the command/response interface of the voter register.
The command/response interface is responsible for servicing
the command oriented clients of the register, such as the mail-based voter interface,
and the voter command shell.
The following general-purpose commands are provided:
In addition, the register provides a number of special-purpose commands.
These are documented below.
doubt
Cast doubt on another voter.
doubt VOTER-EMAIL [REASON]
doubt [--alter VOTER-EMAIL]
If an entry in the voter list appears to contain false information, then you
may mark it as such by casting doubt on the voter. For example:
doubt falseVoter@domain.dom nobody lives at 7 Turncott, the building
is empty
You must be in the voter list yourself before your doubt will reach the other
voter. When it does reach her, it will not affect her own inclusion in the
list, nor her eligibility to vote in the polls. It will only serve to
indicate your suspicion that her entry in the register is false. Other voters
may then consider whether or not to withdraw their trust from her.
To recall who you are doubting, simply send:
doubt
The service replies, identifying the doubted voters:
You are casting doubt on 1 voter(s).
falseVoter@domain.dom
nobody lives at 7 Turncott, the building is empty
Or, to see where another voter has cast doubt, send:
doubt --alter VOTER-EMAIL
To cast doubt on additional voters, use the 'doubt' command repeatedly. To
withdraw it, use 'undoubt'.
If your registration comes to be doubted by several voters, then you may wish
to attach a note of explanation to it, as a defence. See the command "set
note". [There is currently no easy way to discover who is doubting you, or to
view registration details, except through the Web interface. This will be
corrected in the beta-two release.]
set
Set the value of a register attribute.
set [--alter VOTER-EMAIL] name|residence|link|note VALUE
The attributes that may be set are:
name
set name James Madison
Your proper name. This attribute is optional, and may be left unset.
residence
set residence 11407 Constitution Highway, 22957
Your primary residential address. This attribute is required to
establish your eligibility to vote in the various electoral districts.
Avoid abbreviations, and always place the postal code last.
link
set link http://~jim/emontpelier.net
A Web link in standard URI format, pointing to further information
about you. This attribute is optional, and may be left unset.
note
set note My Internet connection may be down, but I'm still here.
A short note explaining or commenting on your registration. This
attribute is optional, and may be left unset.
Under certain conditions, you may be able to set the attributes of a
registrant other than yourself, by using the --alter option. You may set the
attributes of another registrant, in this way, only if none were previously
set by the registrant. (Once a registrant sets or resets a single attribute
in the register, she assumes exclusive control of all attributes.)
set --alter muller@wintermere.nz link http://~muller@wintermere.nz
All attributes in the register are in public view. Once set, you may alter an
attribute's value with another 'set' command, or erase it with 'unset'.
[There is currently no easy way to view your register settings. This will be
corrected in the beta release.]
trust
Extend trust to another voter.
trust VOTER-EMAIL
trust [--alter VOTER-EMAIL]
To be eligible to vote, you must have the trust of other voters in your
neighbourhood. A sufficient number of them (themselves trusted) must extend
their trust to you. Only then will your registration be included in the voter
list, and your votes included in the poll counts. The exact amount of trust
you require will usually be specified in the voter list. [The list is
currently posted only in the Web interface.] The list is also a helpful
resource for locating suitable neighbours prior to requesting their trust (by
email, telephone, and so forth).
Trust usually has a limited range, restricting it to the local neighbourhood.
The range is usually symmetric (the direction does not matter). So, before
requesting trust *from* a neighbour, you may wish to test your range by
extending your own trust *to* that neighbour. To extend your trust, use the
'trust' command. For example:
trust myNeighbour@somewhere.net
If you cannot obtain trust because too few voters are registered in your
neighbourhood, then you must contact your local registrar. [Instructions will
be provided in a future release.]
To recall who you are trusting, simply send:
trust
The service replies, identifying the recipients of your trust:
You are trusting 1 voter(s).
myNeighbour@somewhere.net
Or, to see the recipients of another voter's trust, send:
trust --alter VOTER-EMAIL
To extend trust to additional voters, use the 'trust' command repeatedly. To
withdraw it, use 'untrust'.
[There is currently no easy way to discover your own trust level, or to see
who is extending trust to you, except through the Web interface. This will be
corrected in the beta-two release.]
undoubt
Withdraw doubt that was previously cast on another voter
undoubt VOTER-EMAIL
The service replies, confirming the withdrawal:
You were casting doubt on 1 voter(s).
You are now casting doubt on 0 voter(s).
If you change your mind later, and wish to re-cast your doubt, use the 'doubt'
command.
unset
Unset the value of a register attribute, erasing it.
unset [--alter VOTER-EMAIL] name|residence|link|note
For example:
unset link
The service replies, confirming the erasure:
Old value: http://~muller@wintermere.nz
New value: none
If you change your mind later, and wish to set a value once again, use the
'set' command.
Under certain conditions, you may be able to erase the attributes of a
registrant other than yourself by using the --alter option. See the 'set'
command for details.
untrust
Withdraw trust that was previously extended to another voter
untrust VOTER-EMAIL
The service replies, confirming the withdrawal:
You were trusting 1 voter(s).
You are now trusting 0 voter(s).
If you change your mind later, and wish to re-extend your trust, use the
'trust' command.
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.
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.6
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-2009-bh-1/readyList-1
/home/voff/votorola/out/volist/snap-2009-bi-1/readyList-1
MR /home/voff/votorola/out/volist/snap-2009-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-2009-bi-1/readyList-1
$ volist status
/home/voff/votorola/out/volist/snap-2009-bh-1/readyList-1
MR /home/voff/votorola/out/volist/snap-2009-bi-1/readyList-1
/home/voff/votorola/out/volist/snap-2009-bj-1/readyList-1
Much like count records, list records will require
occaisional 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 register.
Individual trust edges are stored as public input to the register.
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.11
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):
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.
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 core site.
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 register.)
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 site. Consequently they are not considered as part
of the core voter input, and are not synchronized up to the super-sites.
votorola/a/poll/
votorola.a.poll
Polls and Vote Counts
A core site 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-site that is able to compile
a complete list of eligible voters from its own register.
For example, a poll on the issue of electing a member to a national assembly
would be provided by a local site (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-site,
because such bills are national issues, on which everyone is entitled to vote.
(A super-site would also host any local poll for which the voter list happened, somehow,
to straddle the boundary between two local sub-sites.)
Configuration is specified by scripts and other files that are
located in the poll's service directory (shown above).
The internal structure of the scripts (startup and runtime)
is outlined in the figures below.
Every poll is associated with a district.
A district is any one of a number of geographical subdivisions
that divide the overall area of a core site, according to a particular divisional scheme.
If the configuration of a poll does not explicitly assign a district,
then the poll is automatically assigned to the default district,
for which a configuration file is expected
to be found at ~/votorola/poll/district.js.
Every district is associated with
a divisional scheme.
A divisional scheme is a method of dividing the area of a core site into separate districts.
For example, a Canadian city might have two schemes:
a municipal “Wards” scheme that divides the area
according the jursidictions of City Councillors;
and a federal “Ridings” scheme that divides it
according the jursidictions of Members of Parliament.
If a particular district were not explicitly assigned to one of these two schemes,
nor to any other, then it would be assigned automatically to the default scheme.
In that case, the configuration of the default scheme is expected
to be found in the file ~/votorola/poll/divisional-scheme.js.
Polls also store of relational data, as shown in the figure below.
Setting Up a Poll
-
The minimal configuration already defines a poll
with a service name of “test-p”.
To create another, simply copy it to another service directory
with a different name.
$ (s=~/votorola/poll/services; cp -R $s/test-p/ $s/SERVICE-NAME)
-
Test the new poll.
$ voter SERVICE-NAME hello
hello
$ voter test-a@zelea.com SERVICE-NAME 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 SERVICE-NAME unvote
. . .
You were voting for: test-b@zelea.com
You are now voting for: nobody
. . .
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:
In addition, the poll provides a couple of special-purpose voting commands.
These are documented below.
unvote
Withdraw a vote from a poll.
unvote
The service replies, confirming the withdrawal:
null
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 poll.
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:
null
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.
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 done either one at a time, or repeatedly at scheduled intervals.6
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-2009-bh-1/readyCount-1
/home/voff/votorola/out/vocount/snap-2009-bi-1/readyCount-1
MR /home/voff/votorola/out/vocount/snap-2009-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-2009-bi-1/readyCount-1
$ vocount status
/home/voff/votorola/out/vocount/snap-2009-bh-1/readyCount-1
MR /home/voff/votorola/out/vocount/snap-2009-bi-1/readyCount-1
/home/voff/votorola/out/vocount/snap-2009-bj-1/readyCount-1
Snap/readyList records will accumulate in the filestore over time,
as new lists are compiled. For the off-line pollserver,
the records may be cleaned away by simply erasing the entire filestore,
using the script vox-clean.
The on-line pollserver 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 pollserver.
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.8
under revision
Leader Configuration
Leader configuration
is the portion of a poll's configuration
that is distributed out to the leading candidates of the poll.
Most of a poll's configuration is centrally defined at the pollserver,
but a part of it may be distributed out to the leading candidates.
This part includes items that are expected to fluctuate as the poll proceeds,
such as its description and categorization. These items are periodically pulled
from the candidate who is currently leading the poll,
hence the term “leader configuration”.
Note:
The design of leader configuration is undergoing revision. In an upcoming release,
all distributed data will be pulled from the voters (and admin)
via media such as pollwiki pages.
Distributed leader configuration is gathered in the file leader.rdf,
which is located in the poll's service directory.
The structure and semantics of this file are defined
in votorola/poll/Leader.xsd
and Poll.rdf.
The file is automatically overwritten by configuration
that is pulled from the candidates.
Administrative override of leader configuration is controlled by the file
leader-override.rdf. As long as the override file is present,
any ordinary leader.rdf is ignored.
The administrator then has complete control of the configuration,
while the candidates have none.
Initializing the Leader Configuration
When the poll is first created, the leader configuration is undefined.
If you wish, you may provide initial defaults, or define an administrative override.
-
Copy the initial leader configuration from the provided example.
You have two choices: either provide initial defaults,
or define an administrative override. To provide initial defaults
(subsequently to be overwritten by whatever is pulled from the candidates):
$ cp ~/votorola/code/votorola/a/poll/leader.rdf \
~/votorola/poll/services/SERVICE-NAME/
Alternatively, you may define an administrative override:
$ cp ~/votorola/code/votorola/a/poll/leader.rdf \
~/votorola/poll/services/SERVICE-NAME/leader-override.rdf
-
Edit the file to customize the configuration.
The contents are largely self-explanatory.
For the complete structural schema,
see Leader.xsd.
The most important item is Poll/@rdf:about,
which must exactly match the
service UID
of the poll.
Modifying the Leader Configuration
After editing the configuration file, the changes will take effect immediately
in the command-line interface (script voter).
For other interfaces, the changes will take effect
at the next mounting or unmounting of the poll's count.
You may speed up this process by touching the serial file
of an already-mounted count:
$ touch ~/votorola/out/vocount/_readyCount_report/_mountedCount/SERVICE-NAME.serial
The configuration changes then take effect
after the next fetch of count data in the voter interface.
In the Web interface, for example,
this occurs when any user visits a page that shows count data.
Thereafter, the configuration changes will be visible to all users,
on all pages that are fetched.
votorola/a/web/
votorola.a.web
Web Voting
This section concerns the Web-based voter interface (Web interface).
The configuration of the Web interface is specified by its startup script,
located in the pollserver's votorola/web directory (shown above).
The internal structure of the script is outlined in the figure below.
The file votorola/out/login-persistance.serial
contains hash salts (random numbers) for use by the login persistance facility
(“keep me logged in”).
The security of persisted logins depends on keeping this file private.
You may delete this file in order to invalidate all persisted logins.
A new file containing new salts will automatically be generated.
The file votorola/out/web-activity-list.serial
contains the activity list (http://localhost:8080/voff/w/Activity/).
It is periodically rewritten at runtime.
To clear it, first shut down the Web interface, then delete the file.
Setting Up the Web Interface
A Java servlet container is required. Only Tomcat has been tested.
The minimal configuration
already includes a startup configuration file voface-web.js,
and a Tomcat Context file voff.xml.
-
Ensure that the servlet container is a member
of the votorola group. For example,
assuming the container runs under the name tomcat:
$ groups tomcat
votorola tomcat
If it is not a member of votorola, then add it:
$ usermod --append --groups votorola tomcat
-
Define the Web interface as a servlet Web application,
by linking to its Context file from Tomcat. Do this as root:
$ ln --force --symbolic /home/voff/votorola/web/voff.xml \
CATALINA_BASE/conf/Catalina/localhost/
Alternatively you can simply copy the Context file to that directory.7
You may need to create the destination directory first.
The Context directories (Catalina/localhost)
are not pre-created in a clean installation of Tomcat.
For more information, see Tomcat's documentation regarding the directories
CATALINA_BASE/conf/[enginename]/[hostname].
-
Restart the servlet container. The Web interface will be accessible at:
http://localhost:8080/voff/w/
If you shut down the interface and restart it,
then also remember to clear any old pages from the browser history.
Their links may behave incorrectly after a restart. To clear them,
go back to the first page, press refresh, and continue from there.
Web Services
In addition to its interactive services for users,
the Web interface also provides non-interactive services (just one at present)
for the use of Web developers and page authors.
Candidate Referral
http://SERVER-NAME/v/w/Pollspace/?p=POLL-NAME&u=CANDIDATE-USERNAME
http://SERVER-NAME/v/w/Pollspace/?p=POLL-NAME&v=CANDIDATE-EMAIL
The server name is that of the pollserver that hosts the poll.
It replies with a vote confirmation page
in which the user may accept or reject the suggested vote shift,
or browse for other candidates. For more information, see the API
of WP_Pollspace.
votorola/a/mail/
votorola.a.mail
rough draft
Mail Voting
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.
# # # # # # # # # #
- 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 core site'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 a mail transfer agent (MTA) that is configured
to receive mail for your pollserver 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, further 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.
-
Run the mail interface, voface-mail.
$ voface-mail &
(It's 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 pollserver
at the same address, voff@HOST.DOMAIN.DOM.
If your MTA receives the message and delivers it to the pollserver inbox,
then you should get a reply momentarilly.
-
Configure the MTA to deliver messages for all voter services
(register and polls) to the pollserver inbox.
(For qmail, see the example
/var/qmail/alias directory
in the appendix.)
-
Send a message to the voter register
(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 pollserver.
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.2
hello
Say hello to the service.
hello
hello TEXT
The service replies 'hello'. Any TEXT arguments are ignored. This command is
used for testing.
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'.
version
Ask what version of software the pollserver 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 site 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
Copyright 2007-2009, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.
