Chapter V
- eVote for Site Administrators -

Architecture/Overview

eVote is a user interface and a database server especially crafted to stimulate, accept and report on vote data generated by the online community.

eVote is five executables that work together. 

                       _______________
                      |               |
                      |  eVote_Clerk  |
                      |    -------    |
                      |      The      |
                      |     Clerk     |
                      |_______________|
                      /|\ /|\  /|\  /|\
                       |   |    |    |
                       |   |    |    |
                   STARTS  |    |   COMMUNICATES WITH
                   /       |    |                |
                 /         |    |                |
               /           |    |               \|/
 _______________           |    |             _________________
|               |          |    |            |                 |
|     eVote     |          |    |            |  eVote_insert   |----> Runs
|   ---------   |          |    |            |     -------     |  "resend"
|    Command    |          |    |            |  The email list |   or your
|     Center    |          |    |            |    Interface    |   mailer,
|_______________|          |    |            |_________________|        as
                     COMMUNICATES WITH            /|\          appropriate.
                           |     \                 |              /|\
                           |       \            "wrapper", part    |    
                           |         \          of Majordomo, runs |
                          \|/          \        eVote_insert &     |
               _______________________   \      eVote_petition     |
              |                       |    \       |               |
              |       eVote_mail      |      \|   \|/              |
              |  -------------------  |       _______________________
              |  Mail Administrator's |      |                       |
              |  Utility Interface    |      |     eVote_petition    |
              |_______________________|      |  -------------------  |
                                             |  Accepts signatures   |
                                             |  for petitions only.  |
                                             |  Also an email        |
                                             |  interface.           |
                                             |_______________________|

eVote's Executables

eVote is five programs that work together: eVote_Clerk, usually called "The Clerk"; eVote_insert, the email list user interface; eVote_mail, the mail administrator's utility interface; eVote_petition, the interface for signers of petitions, and eVote, the command center for controlling The Clerk.

eVote_insert, eVote_petition and eVote_mail reside in the same directory as the listserver's program, "resend" or "post". This happens automatically during installation. They are owned and run by your listserver's login.

When running Majordomo, eVote_mail is in the same directory with eVote_insert and eVote_petition. With Mailman, it is in the bin directory with Mailman's utility scripts.

The two executables, eVote_Clerk and eVote, reside, by default, in the directory, /usr/local/bin. A different directory can be specified during installation.

After installation, executing ls -l eV* in the directory you specified displays the two executables and one text file, "eVote.cf": 

-r-x--x--x   1 clerk    users      535081 May 11 15:46 eVote
-r--r--r--   1 clerk    users         246 May 11 15:46 eVote.cf
-r-x------   1 clerk    users      246213 May 11 15:46 eVote_Clerk

The third eVote file, eVote.cf, is a text file containing eVote's run-time parameters. It is described in the section titled "Defaults".

eVote_queries.py for Mailman Only

eVote_queries.py is an extra executable that integrates itself with Mailman so that eVote can query and manipulate Mailman's data. During installation, it is placed in mailman/bin where eVote expects it.

Other eVote Files

Interprocess Communication

The Clerk communicates with the eVote_insert by using two of UNIX's interprocess communication facilities: shared memory and message queues.

The Clerk has one incoming message queue. All requests to The Clerk go in on that same queue. Each user interface process has one return message queue. The Clerk sends messages back to the user interface process through that process' return queue. These messages acknowledge the completion of instructions and communicate the fast-moving personalized statistics that the user sees.

A shared memory segment is established for each currently active conference or email list. The shared memory contains slow-moving data regarding the polls for the list. In particular, the shared memory holds details about the characteristics of each poll. It does not contain statistics.




Installation

Installation involves two main steps:

  1. Install eVote.

  2. Link eVote to your already-running listserver, probably Mailman or Majordomo.

This assumes that you already have a listserver running on your Linux-run computer. If not, then installing Mailman or Majordomo is your first step.

To install Mailman, collect version 2.0.13 from http://sourceforge.net/projects/mailman.

To install Majordomo, collect version 2.94.5 from http://www.greatcircle.com/majordomo.

Installing eVote

When installing eVote, care must be taken about permissions and security. Some particular login must calculate statistics and own eVote's data files, i.e., the ballots for your users. For vote security, choose this login carefully. A good security trick is to make a special login, "clerk", for this purpose. If you place an '*' in the encrypted password field of the password entry for your clerk login, then only root can access this login and only by using "su clerk".

The entry in our /etc/passwd file is:

clerk:*:401:100::/usr/local/eVote/data:/bin/tcsh

The '*' in the password field means that, to be the clerk login, you login as root and then issue the "su clerk" command.

The clerk login can have its own group. It doesn't matter.

Note also that recent Unix systems maintain a /etc/shadow file which is only readable by root and which contains the passwords. In this case the "*" is to be written in this file while the /etc/passwd file should have an 'x' in the field corresponding to the password.

Don't make an "eVote" login, save that name for your petitions. "The Clerk" is the vote-server that maintains eVote's data so "clerk" is a good choice for this login.

Doing The Install

Do the installation as your listserver login, probably "mailman" or "majordom". Then:

  1. Be in the same directory where the compressed tar file resides:

    eVote2.5x.tgz

  2. Unload the file:

    tar -zxvf eVote2.5x.tgz

  3. Move to the src directory:

    cd eVote-2.5x/src

  4. Edit the makefile in the src directory. The makefile has instructions for this.

  5. Do the installation in the src directory:

    make install

Linking To Mailman

Mailman List Requirements

Your eVoted Mailman lists requires two option settings:

  1. In "General Options", for the question, "Where are replies to list messages directed?", please click "This list".

  2. If, in "Privacy Options", you have restricted posting privileges to list members only, you must do an extra fanagle to allow eVote to post to your list. Each eVoted list has a special address associated with mail from eVote. The address for the "sample" list at the eVoted-site.net domain is sample-eVote@eVoted-site.net. Add this address to "Addresses of members accepted for posting to this list without implicit approval".

Performing the Link with Mailman

Linking eVote to Mailman involves altering your exim or sendmail (or other MTA) aliases file, usually /etc/aliases.

  1. Add the following aliases:

        eVote-owner:      mailman-owner
    eVote-notify:     "|/home/mailman/mail/wrapper eVote_insert"

  2. For each allready-established list that requires eVote, add the following aliases. In this example, the list name is "sample".

        sample-eVote: sample-admin
    owner-sample: sample-admin

  3. Also, for each list that requires eVoting, edit the following aliases as indicated:

        sample:         "|/home/mailman/mail/wrapper eVote_insert post sample"

    sample-request: "|/home/mailman/mail/wrapper mailcmd eVote sample"

    Note that the alias for "sample:" has the word "eVote_insert"
    inserted between " ...  /wrapper" and "post ... ".  Don't change
    the line in any other way.

    Also note that the alias for "sample-request" has the word "eVote"
    inserted between " ... mailcmd " and "sample ... ".  Don't change
    the line in any other way.

    Don't forget to mkaliases, or newaliases, as your system requires.

  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
  | Note: Don't make an eVoted list whose name starts with "petition" |
  | unless you are using it for the petition facility; and don't make |
  | a list whose name is "eVote", you'll want that address for your   |
  | petition address.                                                 |
  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *

When you create a new email list with Mailman's "newlist" utility, it will ask if this list is to be eVoted. If so, it will supply the correct alias entries for the list.

Linking To Majordomo

Majordomo List Requirements

Your eVoted Majordomo lists require two things in the configuration, for example, in the sample.config file:

  1. The reply_to parameter must be the list address:

    reply_to = sample@eVoted-site.net

  2. If your list uses Majordomo's restrict_post feature, you must do an extra fanagle to allow eVote to post to your list. Each eVoted list has a special address associated with mail from eVote. The address for the "sample" list at the eVoted-site.net domain is eVote-sample@eVoted-site.net. Make a file in your $lists directory called "sample.posters" and put the line in it: sample-eVote@eVoted-site.net. Then, in the Majordomo configuration file for the list, include sample.poster in the list of files in the restrict_post parameter in the configuration file: 

    restrict_post = sample.posters and-any-other-files-listed

  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
  | Note: Don't make an eVoted list whose name starts with "petition" |
  | unless you are using it for the petition facility; and don't make |
  | a list whose name is "eVote", you'll want that address for your   |
  | petition address.                                                 |
  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *

Performing the Link with Majordomo

Linking eVote to Majordomo involves altering your exim or sendmail (or other MTA) aliases file, usually /etc/aliases.

  1. Add the following alias:

    eVote-owner: owner-majordomo

  2. For each list, add the following alias. In this example, the list name is "sample".

    sample-eVote: owner-sample

  3. For each list that requires eVoting, edit the following aliases as indicated:

    sample: "|/usr/local/majordomo/wrapper eVote_insert resend -l sample -h your-domain.net sample-outgoing"

    

sample-approval: owner-sample, "|/usr/local/majordomo/wrapper eVote_insert"

    Note that the alias for "sample:" has the word "eVote_insert" inserted between " ... /wrapper" and "resend ... ". Don't change the line in any other way.

    Also note that the alias for "sample-approval" has `,"|/usr/local/majordomo/wrapper eVote_insert"' added at the end. Use the same path to the "wrapper" program as you use in the sample alias.

      * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
  | Note: Don't make an eVoted list whose name starts with "petition" |
  | unless you are using it for the petition facility; and don't make |
  | a list whose name is "eVote", you'll want that address for your   |
  | petition address.                                                 |
  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *

Getting Started

These instructions are for sites running any listserver.

  1. Don't forget to mkaliases, or newaliases, as your system requires.

  2. Start eVote's vote-keeper, "The Clerk", running.

    1. Be sure you are logged in as the "clerk" user.

    2. Give the command:

      eVote

    An "eVote_Clerk" process will start and should stay running all the time that your computer is up and running.

    If you have trouble at this point, there may be an incapatibility with your linux's "ipcs" command which eVote issues and parses. You can configure this in the EVOTE_BIN/eVote.cf file:

    IPCS = ipcs -c

    is a good one to try. The ipcs command needs to have the interprocess communication id's as the first fields:

    ------ Shared Memory Segment Creators/Owners --------
shmid     perms     cuid      cgid      uid       gid       

------ Semaphore Arrays Creators/Owners --------
semid     perms     cuid      cgid      uid       gid       

------ Message Queues: Creators/Owners --------
msqid     perms     cuid      cgid      uid       gid       
1114752   666       clerk     users     clerk     users

    To verify that eVote is installed and running, give the command:

    eVote check

    If The Clerk is running, and it should be, you'll see something like:

    The Clerk's in_queue is alive. In-queue id is 0
    eVote_Clerk is up and running; pid = 121.
    Last receive at Mon May 2 10:28:52 1994
    Last send at Mon May 2 10:28:52 1994
    Currently 0 messages on the in-queue.

    Before you stop your computer, issue the command:

    eVote quit

    When you start again, be sure to start The Clerk again. If you fail to stop The Clerk before you bring down your system, probably everything will be OK anyway. If not, you'll be able to recover all but the most recent transactions. See "The Vote Data" below.

  3. The first "subscribe" or "unsubscribe" command to the "sample" list will start eVote working for the "sample" list. Or you can use

    eVote_mail sync sample

    to immediately initialize eVote for the list. The "eVote_mail" program is in the $config/mailman/bin directory for Mailman installations; and for Majordomo installations it is in the same directory with "resend".

  4. Alert your list owners that their lists are now eVoted. If you are running Majordomo, your list owners may want to use Majordomo's "newinfo" command to modify their list's info file to alert list members that eVote is now up and running for the list. A sample info file, "eVote_sample.info", is in the same directory as your mail lists.

    If you are running Mailman, the welcome message will automatically include eVote information when the list is eVoted.

    Also, list owners have a new set of commands available to them. These are described in "eVote.list-owner-info" in the same directory as your mail lists. If you are running Mailman, these commands will be described in the "newlist" information sent to new list administrators.

Verifying The Installation

To verify the installation, perform these tests:

  1. Send a message to an eVoted list that says:

    eVote help

    You should receive a help file and no mail should go to other list members.

  2. Send a message to an eVoted list that says:

    test.

    It should be sent to all list members as usual.

  3. Send a message to an eVoted list that says:

    eVote poll [y/n] public visible
    message:
    Is eVote working?

    Instructions for voting should be generated and sent to all members.

  4. Unsubscribe and subscribe to an eVoted list. If there is trouble, you'll get an error message.

If these things work properly, your installation is correct.

If you experience some trouble it might be helpful to capture any error messages to stderr. You can do this by placing "eVote_script" in your alias entry instead of "eVote_insert". See "Other Helpful Tools" below.

Preparing For Total Automation

That's enough to get started. But soon, you'll want to set up a few other things to make all your work go away.

You may want to set up cron tasks to regularly:

In "Preparing for Mailer Errors" below (for Majordomo installations only):

  1. Run majordomo's "bounce-remind" script.

  2. Clean the "bounces" list of old entries.

In "Automated backup" below:

  1. Run an automatic backup script nightly.

In "Synchronicity Checks" below:

  1. Run Synchronicity checks.

In "Stale Messages Awaiting Confirmation" below:

  1. Delete old, unanswered, confirm messages.

Also, you may want to add a command to your startup script so that eVote_Clerk starts automatically at boot time, and you might want to establish a "crash command" so that, if the Clerk falls down, something intelligent happens.

Automatic Startup

At deliberate.com, we start the Clerk automatically when the system boots with a command in the start-up script:

su clerk -c /usr/bin/eVote

For more insight into this command, see "Starting The Clerk" below.

Crash Command

If you wish you can instruct The Clerk to run any command just before it crashes, if it crashes. Add this entry to your EVOTE_BIN/eVote.cf file:

CRASH_COMMAND = /usr/bin/stop_modem

You may stipulate any command and if The Clerk receives any kind of signal or comes down for any reason, except for an "eVote quit", it will try to run that command before it dies.

If you change your CRASH_COMMAND, you must restart The Clerk for it to see the new command.

In EVOTE_HOME_DIR/eVote/src/tools/utils is a tryagain.c program that makes a good CRASH_COMMAND. It keeps a tiny data file that notes the last time The Clerk came down unexpectedly. If it wasn't within the last 20 minutes, The Clerk is started again automatically. If it was within the last 20 minutes, it calls a program to turn off the modem. In any case, it sends mail to owner-eVote.

Preparing for Mailer Errors - Majordomo Installations Only

When your list owners send in an "eVote approve <password> bounce <address>" command, the address is removed from majordomo's list, it is marked as "on vacation" in eVote, and it is added to the "bounces" email list. You need to alter majordomo's "bounce-remind" script so that it asks the users to use eVote's command for reinstating their subscription. At deliberate.com our bounce-remind script ends with the following text. Replace "eVote-site.net" with your domain:


---- cut ----
print MSG <<EOF;

if the problem has been fixed, please send a message directly
to the list, not to majordomo: 

   <list-name>@evoted-site.net

where you replace <list-name> with the real name of the list.

have your message say:

   evote back

you'll need to access the mailing list archives if you want to catch
up on whatever you missed while your address was on vacation.

if your address has changed, please notify your list's owner by
writing to:

owner-<list-name>@evoted-site.net

replace <list-name> with the real name of the list. Your list's
owner can change your address so that your ballot follows you to
your new address.

if you don't want to keep getting these reminders every day, but
don't want to resubscribe to the list, please send the "eVote back"
message and then unsubscribe in the usual way: write to
majordomo@evoted-site.net and say:

  unsubscribe <list-name>

where you replace <list-name> with the real name of the list.

EOF

close(MSG);
exit(0);
---- cut ----

Deleting Bad Addresses From Your System - Majordomo Installations Only

when you want to remove names from the "bounces" list, please use the evote_mail program:

evote_mail bounce 30

will remove all addresses that are at least 30 days old. It removes them from the evote data in an intelligent way. Majordomo can't.

Automated Backup

When keeping vote data, it is especially important to make frequent backups, and to check occasionally that the backups can be fed back into the working computer system.

Just after our cron-run backup procedure, we remove all the automatic backups that eVote_Clerk made with:

rm EVOTE_HOME_DIR/eVote/data/~*

Synchronicity Checks

If you modify your listserver's subscriber data, eVote won't see your changes unless you synchronize the list.

To force this synchronization, give the command:

eVote_mail sync <list_name>

The sync command will initialize eVoting for a list. You can say

eVote_mail sync all

to synchronize all your eVoted lists

A first subscribe or unsubscribe to a list will automatically initialize eVote for the list, as long as the alias file indicates that this is an eVoted list.

If the "-r" option is used on the sync command, any new addresses in the listserver's data will be added as non-voters/read-only subscribers and won't be considered in the statistics:

eVote_mail -r sync <list_name>

To change an existing member of a list to a non-voter/read-only subscriber, an external archive address, for example, give the command:

eVote_mail no_vote <list_name> <email_address>

You can change the status of an address in several ways if you know the list's password by sending email with the appropriate command directly to the list's address. See Chapter IV "eVote for List Owners" above.

eVote keeps a "who.list" data file where each participant in any list has a unique id. To verify the correctness of this list, use the command:

eVote_mail sync_who

At deliberate.com, we have a cron task do:

eVote_mail sync all
eVote_mail sync_who

every night just after we have made backups.

Stale Messages Awaiting Confirmation

For security, several classes of messages are not processed unless the user sends a confirmation reply. There are two types, certain administration requests, and signatures for petitions.

unsubscribe

When eVote gets notice that a user has unsubscribed, if that user has any votes in on open polls, then the user's ballot is put "on vacation". A confirmation request is sent, which, when replied-to, causes the ballot to be deleted.

eVote back

The "eVote members" command displays which members are "on vacation". This is an opportunity to forge an "eVote back" message and then a vote message for the member on vacation. These false messages might not be discovered until after the poll is closed. For this reason, the "eVote back" command demands confirmation.

eVote close

This powerful command closes a poll and it cannot be reopened. Forging this message would wreck havoc with the online community so this command demands confirmation.

eVote drop

This command deletes the poll data and so demands a confirmation.

(When the "eVote close" or "eVote drop" command is given with the approve keyword and the list's password, no confirmation message is sent.)

Also, if a petition was initiated with the keyword "confirm", then a confirmation request is sent to each signer before the signature is accepted into the data.

eVote_mail provides commands to delete the stale messages that have been awaiting confirmation:

To delete stale messages waiting for confirmation on all lists and for all reasons, give the command:

eVote_mail confirm 5

this will delete messages at least 5 days old.

To delete stale signature confirmations only from one particular petition list, use:

eVote_mail confirm 2 petitiona

This will delete signature messages awaiting confirmation from the petitiona list only that are at least 2 days old.




The Petition Facility

eVote's petition facility allows a global vote in which the participants don't subscribe to an email list. However, there must be an eVoted list whose name starts with "petition" for administering the petition.

The petition facility has complete multi-language support so that the same petition can be processed in several languages. Deliberate.com has a translation tool that can help to translate the interface to other languages as well. See EVOTE_HOME_DIR/eVote/src/tools/trans/README.

The petition facility allows signatures and, optionally, votes to be collected under the same subject line. Also optionally, you can specify that certain fields be given.

Administration of petitions is totally handled by the members of your petition lists. However, as site administrator, you can provide a facility for the automatic update of a remote url, i.e. the running count of signatures can appear on any web page. Also, there is support for collecting signatures from a web page using Javascript, or CGI scripting or a mixture of both. If you use Javascript by itself, it will be necessary to use "mailto" as the action of the web form, and you will need to include the"unhex" filter in your alias file: see "Coordinating With The WWW" below. While Javascript alone is simple, be aware that the "mailto" action is not supported correctly by all browsers (in particular, MS Internet Explorer).

Implementing Petition Lists

To implement petitions, you must:

  1. Make an eVote mail alias for collecting signatures:

    For Mailman, the alias should be:

    eVote: "|/home/mailman/mail/wrapper eVote_petition post petition"

    For Majordomo, the alias should be:

    eVote: "|/usr/local/majordomo/wrapper eVote_petition resend -l petition -h your-domain.net petition-outgoing"

  2. Make a "petition" list.

You do this the same way you set up any eVoted list. eVote notices that the name of the list is "petition" and gives this list special characteristics. You can make a list name like "petitiona" or any name that starts with "petition", but you must have one list whose name matches the "petition" name in your eVote alias.

Do not use a "subject-prefix" feature on petition lists:

For Mailman, on the "General Options" page, there is a field for "Prefix for subject line of list postings". Make that a blank field.

For Majordomo, the "subject-prefix" option should be blank in the list's configuration file.

It may be more space-efficient to create a list for each petition if you expect your signers to have only that one interaction with your system.

Reports

eVote will use ftp to send updates of files to remote computers every time someone signs a petition or removes a signature. This process can only be set up by the administrator of eVote, remote users cannot do it.

To send file updates for a particular poll, perhaps "Fix The Roof", assume the listserver login as you:

  1. Make a directory, LISTDIR/polls/petition-list/FixThe/reports, where LISTDIR is Majordomo's "listdir", or the LISTDIR you established at install time for Mailman installations. The directory, LISTDIR/polls/petition-list/FixThe should already exist. The petition file key, "FixThe", is the concatenation of the words in the title -- until the words add to 5 characters or more. The petition file key gets truncated at 10 characters.

    Place the files you want updated and shipped to remote sites, say "update1.html", "update2.html", etc., in this directory.

  2. Make a copy of each, but name them, "update1.html.var", "update2.html.var", in the same directory.

  3. Edit the *.var files so that the number to be updated by the signature count looks like "{SIGS==0}" where you want it to give the count. It probably says just "0" at that point in the original html report file. The variable name, SIGS in this case, can be any name. If the same report file should be updated by several petitions, use a different variable name for each petition's count.

    The number to the right of the double-equals sign in the {SIGS==0} should match the number currently in the report file.

  4. Make a third file for each file to be updated, "update1.html.ftp", "update2.html.ftp", etc. This file should contain the commands that ftp needs to perform when it connects to the remote site in order to update the report file, for example,

    cd public_html/eVote
    put report1.html

  5. In listserver's login's home directory, make a file named ".netrc". For each remote site that will receive an updated file, there should be three lines in the file:

    machine ftp.ozemail.com.au
    login jjjacq
    password whoknows

    Be sure that this file is readable by your majordomo login.

  6. Make a file, LISTDIR/polls/petition-list/FixThe/report_instructions. At the very beginning of the file, insert your version of the following:

    ------  cut here  ------
Reports: 3
update1.html SIGS ftp.ozemail.com.au
update2.html TOTAL nanospace.com
aztec.html xx best.com
------  cut here  ------

    Don't add anything else!

    Note that the first line contains the string "Reports: " and then the number of reports to update when the signature count changes.

    For each report there should be one line containing three words: the name of the file to update, the variable to update, and the machine that receives the update. The machine name can be "x" and the file will be updated but not sent anywhere. Use this feature if you have several files to update that will all be sent to the same site:

    ------  cut here  ------
Reports: 3
update_en.html SIGS x
update_es.html SIGS x
update_fr.html SIGS ftp.ozemail.com.au
------  cut here  ------

    Your update_fr.html.ftp file might then say:

    ------  cut here  ------
cd public_html/issue/en
put update_en.html
cd ../es
put update_es.html
cd ../fr
put update_fr.html
------  cut here  ------

If your ".var" file says {$DATE} the current date, unix style, will be inserted into the updated html file.

That should do it!

Coordinating With The WWW

If the petition is promoted on a web page, it is possible to use Javascript or CGI scripting to make a button that sends email requests to service the signing of petitions, the unsigning of petitions, even subscribing and unsubscribing to lists, and all email commands.

If Javascript alone is used, the form submission is by "mailto" action. Then the critical piece of software to make this work is the "unhex" program. Javascript and the html form generate the email message using the x-www-form-urlencoded format so that it has hex codes for all non-alphanumeric characters. This can be translated to clear text for majordomo and for eVote by placing "unhex" in the mail alias as shown below.

For the signature address:

eVote: "|/usr/local/majordomo/wrapper unhex eVote_petition resend \
    -l petition -h your-domain.net petition-outgoing"

The unhex program is described in some detail in "Other Helpful Tools" below.

For a sample of a mixture of Javascript and CGI script for a web-enabled petition, see:

http://www.deliberate.com/food

These pages are available for you to copy and modify for petitions run on your site. Of course, your users can do this without your help or permission, as long as you have the "unhex" program in your alias.

The CGI script is also available, the source consist of two files, formmail.c and cgi.h, it also requires a small database to be set up to use keywords to provide the destination address and/or the subject of the email.

If CGI scripting or a mixture of CGI scripting and Javascript is used, then obviously the CGI script can take care of formatting the email fully and the "unhex" program is not needed. CGI scripting is preferable whenever possible as it always works with most, if not all, browsers. Javascript is simpler to implement, but unfortunately the "mailto" action it uses does not work reliably with MS Internet Explorer.

Bad Signatures

If you wish to remove someone's signature from the petition, you can do so if you know the password for the list:

  1. Send a message to:

    petition@eVoted-site.net

  2. The subject must be the subject of the petition:

    Save The World

  3. The message should be

    eVote approve <password> unsign <address> <address> <...>

This will remove the signature from the signature file as well as the email address from eVote's data.

Also, there are two programs "eVote_errors.c" and "eVote_domain.c" in the EVOTE_HOME_DIR/src/mail directory that were written in a hurry and used to process errors generated because we were under attack at deliberate.com.

Language Support

There is considerable language support in the petition facility. It speaks three languages and new languages are fairly easy to add. See EVOTE_HOME_DIR/eVote/src/tools/trans/README.

Accents, umlauts, etc., will be ignored in the subject line. Quoted-printables are decoded. These facilities were donated by Laurent Chemla.

Multi-Language Petitions

eVote's petition facility will parse the subject line of any message coming into eVote_petition from the eVote@eVoted-site.net address and determine if the subject exists as a petition title in any language for any petition on any petition list at your facility.

Translations for subjects and petition texts can be supplied remotely by the petition's author at the time of initialization, or they can be added later by you, the site administrator.

Alterations On the Fly

Three classes of alterations can be made on the fly. The users and list owners cannot do them, only you, the site administrator can. The three types are:

  1. Adding a language to a petition.

  2. Adding or changing a form.

  3. Toggling the confirm feature.

Adding A Language

Three languages, English, Spanish, and French, are supported in eVote 2.5x. If you need another language, deliberate.com can help you translate the code. We have a tool so that the human translator does not need to be a computer programmer. See EVOTE_HOME_DIR/eVote/src/tools/trans/README.

If you are running a petition in one or two of the supported languages, and wish to add support for the petition in another supported language, these are your instructions.

When a user initializes a petition, the information is parsed by eVote and the subjects land in two or three different places. If you wish to add a language, you must add it in two places; and in three if there is a form for the petition:

  1. The petition text for each language has its own file:

    The petition's text, in English, is stored in LISTDIR/polls/petitiona/Governments/text/English and the Spanish is in LISTDIR/polls/petitiona/Governments/text/Espanol. where "petitiona" is the name of the list. If the list is "petition-fred", use that directory name after "polls". The petition file key, "Governments", is the concatenation of the words in the title -- until the words add to 5 characters or more. The petition file key gets truncated at 10 characters. Add a new file for the new text and give it the appropriate language name

  2. Add the translation of the subject to the "Subject Translation Table."

    There is only one such table for your site:

    LISTDIR/../polls/translation.data

    This editable file has the following format:

          LIST: petition 
        SUBJECT: PUB: NO_CONFIRM: Fix The Roof -En
          -es Regla El Techo
          -en Fix The Roof
        SUBJECT: PRI: DO_CONFIRM: Fire The Boss -En
          -en Fire The Boss
      LIST: petitiona
        SUBJECT: PUB: DO_CONFIRM: Salve El Mundo -Es
          -es Salve El Mundo
          -fr Sauvez Le Monde
          -en Save The World

    The "PRI:" or "PUB:" in the "SUBJECT:" line indicates if it's a private or public petition. *Don't* change that. If you do, it won't change the privacy type of the actual petition, it will only cause eVote to lie about it.

    The "NO_CONFIRM:" or "DO_CONFIRM" indicates that a confirmation request should or should not be sent to signers of this petition. See "Toggling the Confirm Feature" below.

    The "-En" at the end of the "SUBJECT:" line means that the default language for the petition is English.

    The indented lines following the SUBJECT: line are the title translations.

    Add the subject translation you need. Be careful to follow the formatting -- make the right number of spaces.

  3. If the petition has a form to check, the multi-language form phrases and requirements are stored in the form template for the petition:

    LISTDIR/../polls/petitiona/Government/form_template

    The form_template file for 4 fields in 3 languages looks like:

    Fields: 3
* country: -Fr pays: -Es pais: 
  name: -Fr nom: -Es nombre: 
  email: -Fr email: -Es email: 
  id: -Fr id: -Es id: 99999

    The asterisk indicates that it is a required field.

    If you want to specify a required format for a field, do that after all the translations for that field.

    Again, be sure to follow the format given. Get the right number of spaces.

    Notes

    You can add new translations of an existing petition to the table,and matching new petition text in the directory structure, but you cannot create a new petition text by putting data into these places. Doing so will create havoc.

    These files are easy to read and modify. No reinitializations are necessary after these files are changed.

    If the subject of the petition is "Save the World", a signer or web page can use "Save the World -es" to indicate that Spanish is desired. Or, if the translation has been provided, they can use "Salve El Mundo". The language flag takes precedence over the language of subject line.

Adding Or Changing A Form

Also, you can change the form template so that fields become required, or not, after the petition is initialized. The changes will take effect immediately. The file to modify is LISTDIR/../polls/petitiona/Government/form_template

This one checks the format of the zip and state field:

Fields: 4
* name: 
  address:
  zip: 99999
  state: XX

The asterisk indicates that it is a required field.

If you want to specify a required format for a field, do that after the colon for the field. Be sure to follow the format given. Get the right number of spaces.

If you are altering a multi-lingual petition, see "Adding A Language", list item 3, above.

Toggling The Confirm Feature

The confirm feature is controlled by a keyword in the Subject Translation Table. There is only one such table for all the petitions at your site:

LISTDIR/../polls/translation.data

This editable file has the following format:

      LIST: petition 
        SUBJECT: PUB: NO_CONFIRM: Fix The Roof -En
          -es Regla El Techo
          -en Fix The Roof
        SUBJECT: PRI: DO_CONFIRM: Fire The Boss -En
          -en Fire The Boss
      LIST: petitiona
        SUBJECT: PUB: DO_CONFIRM: Save The World -Es
          -es Salve El Mundo
          -fr Sauvez Le Monde
          -en Save The World

The "DO_CONFIRM:" or "NO_CONFIRM" indicates that a confirmation request should or should not be sent to signers of this petition.

Simply change that keyword. Be careful not to mess up the layout of the file.




Administration - A Deeper Look

Taking care of eVote is a matter of starting and (maybe) stopping The Clerk, keeping an eye on EVOTE_HOME_DIR/eVote/data/Clerk.log and, *please*, backing up the data files, all these things can be done automatically. See "Preparing For Total Automation" above.

This section provides a deeper look at eVote's facilities.

Starting The Clerk

To use eVote, The Clerk must be running in your computer's background. To start The Clerk, you must be logged in as clerk, then enter:

eVote

or:

eVote start

eVote puts The Clerk into the background automatically.

You can override the "EVOTE_HOME_DIR" in the eVote.cf file at start-up time by saying:

eVote -h /u1

Also, you can override the message queue key for the Clerk:

eVote -k 101

If the Clerk is already running on your machine, saying "eVote" will start the "eVote demo", a telnet interface into your Clerk and your vote data.

Stopping The Clerk

If you are going to bring down your computer, it is a good idea to stop The Clerk first. To do this, enter:

eVote quit

"eVote stop" works too.

If you bring down your machine without stopping The Clerk first, all the vote data will almost certainly be OK anyway. The Clerk, unless it is very busy at the moment, keeps it's data files up-to-date.

The Clerk's Log

The Clerk logs interesting events to EVOTE_HOME_DIR/eVote/data/Clerk.log. eVote offers two commands for manipulating this log:

eVote flush

flushes EVOTE_HOME_DIR/eVote/data/Clerk.log so that you can see the latest entries.

eVote new_log

flushes EVOTE_HOME_DIR/eVote/data/Clerk.log and moves it to EVOTE_HOME_DIR/eVote/data/Clerk_log.back. Clerk.log is then empty and ready for new entries.

If EVOTE_HOME_DIR/eVote/data/Clerk_log.back already exists, its contents are appended to EVOTE_HOME_DIR/eVote/data/Clerk_log.old before the current Clerk.log is written into Clerk_log.back. Therefore, Clerk_log.back always contains the most recently backed-up Clerk log.

Other Possibilities

eVote offers a few other commands to the system administrator:

eVote check

reports if The Clerk is running now or not.

eVote check list-name

prods The Clerk to recalculate all statistics for the named list and report the results to standard output. If anything ever does not add up right, please contact Deliberate.Com.

eVote dropc list-name

removes the named list from the system. This call makes backup data files so the data can be retrieved. "dropc" is for "drop conference".

eVote ipc

prints a report to stdout about the currently active message queues and shared memory segments.

eVote new_exe

instructs The Clerk executable to prepare for a new executable and quit. Use this command when you receive a new version of The Clerk's executable file, eVote_Clerk, or when you want to change the BLOCK_SIZE.

eVote priority up

asks The Clerk to raise its process priority with respect to the other processes. That is, "eVote priority up" instructs The Clerk to run faster. The Clerk adjusts its own priority as it perceives a need so you'll probably never need this command. Similarly,

eVote priority down

instructs The Clerk to slow down. In order to use these commands, The Clerk must be running under root's id, which many sysadmins are loathed to do.

eVote stop_ipc

brings down eVote's message queues and shared memory segments. Only use this command when The Clerk is not running.

The Vote Data

All vote data are kept in one directory, EVOTE_HOME_DIR/eVote/data, or /usr/local/eVote/data, by default. The default can be changed during installation, or by editing the value of EVOTE_HOME_DIR in the EVOTE_BIN/eVote.cf file, or even by giving an optional argument to the "eVote start" command.

If you change the data directory and you already have some eVote data in the old data directory, be sure to move the data files to the new directory so that The Clerk can find them.

There are three active data files for each currently active eVoted list:

list-name.bnf

a tiny file that keeps the current values of various ballot parameters.

list-name.dat

contains the ballots for the list.

list-name.inf

contains information about the polls in the list.

There is also one file for the whole system:

who.list

contains the email addresses and keys into the list-name.dat files.

The Clerk makes a backup of each data file whenever the data files undergo a transformation: reordering or growing.

Backup files appear in the same directory with the active data files. However, the names of backup files start with ~00. If, when a backup is being generated, there already is a backup starting with ~00, the new backup will start with ~01, then ~02 and so on, up to ~99 when it starts with ~00 again.

All data files are backed up using the same scheme:

~00list-name.bnf
~00list-name.inf
~00list-name.dat
~00who.list

You may want to remove old redundant backup files periodically. Set a cron task to do this just after you do your regular back up to tape.

If you need to use a set of backup files as the current data, simply remove the `~nn' from the file name. The first few text characters of the list-name.inf file contain the list name. Check to be sure that the data file name matches the name in the list-name.inf file. If not, probably the name of the data file was truncated in the backup process. Rename the data files so that the file names match the name in the list-name.inf file. Do not change the information in the list-name.inf file. Altering the data files even slightly is likely to render the data useless.

Help For Subscribers

The files, eVote.petition, eVote.poll and eVote.help, are used by eVote to generate documentation that is emailed to users. These reside in LISTDIR. The eVote.poll file contains directions for initiating a new poll; eVote.petition for initiating a new petition. The eVote.help file contains general information about eVote. You can ignore these files but please don't move or remove them.

Defaults

eVote and The Clerk read various run-time parameters from the EVOTE_BIN/eVote.cf file. This file is automatically constructed during installation.

The EVOTE_BIN/eVote.cf file can be edited to change most of the parameters. Altering some of the parameters also involves rebuilding the kernel. This is discussed below in "Interprocess Communication".

Other Helpful Tools

A few small programs can be found in EVOTE_HOME_DIR/src/tools.

Utilities

In EVOTE_HOME_DIR/src/tools/utils are a few utility programs. They can be used as-is with Majordomo's wrapper. To use them with Mailman's wrapper, you would have to add the executable names to the list of allowed executables in $prefix/src/mail-wrapper.c and recompile the wrapper. They are:

unhex.c

If you want majordomo to respond to email that was sent from a web page mail-to, pipe messages through this program. Your alias for majordomo should be:
majordomo: "|/usr/local/majordomo/wrapper unhex majordomo"

The unhex executable needs to reside in the same directory with the majordomo perl script.

This program is also useful for accepting petition signatures and eVote commands from Javascript-generated mailto's.

sample: "|/usr/local/majordomo/wrapper unhex eVote_insert \
   resend -l sample -h eVoted-site.net sample-outgoing"

The unhex.c program reads the message and if it starts with "hex=", it reads the whole message, translating the hex code into regular ascii and passing the message along to eVote_insert, or whatever program is next in the alias line.

Hex code in the subject line is always translated to regular ascii by unhex.

"hex=" is generated as the first word of a message when the messages is issued from a hidden field in a html form if the hidden field's name is "hex".

(John Jacq, eVote's web page engineer, says: Yep! that's almost all I did, indeed some of the forms I use don't have any javascript at all, just a hidden field named "hex" to which I have assigned a value.

The forms where lots of fields are involved are in fact 2 consecutive forms on the same page, one has all the fields, the second has first the hidden field "hex", then an unnamed "submit" button which has a mailto action and an onClick event handler. onClick occurs first and passes control to a javascript routine, the routine extracts all the information from the first form, perhaps adds some of its own, perhaps checks that certain fields have been filled in, or that a value is in the correct range, then it concatenates everything into one big long string and shoves it into the value property of the "hex" field on the 2nd form, and finally returns true. Then the mailto executes and the email automatically starts with "hex=....". jjjacq@axs.com.au)

eVote_script

Use this little script to take control of where the error stream from majordomo lands. Make your alias for an eVoted list say "eVote_script" instead of "eVote_insert":

sample: "|/usr/local/majordomo/wrapper eVote_script resend \
   -l sample -h eVoted-site.net sample-outgoing"

You'll need to edit eVote_script. Mine looks like:

#!/bin/bash
/usr/local/majordomo/unhex eVote_insert $* 2>> /tmp/eVote_debug

because I run unhex and I want my errors in land in /tmp/eVote_debug.

Mail Filters

The EVOTE_HOME_DIR/eVote/src/tools/filters directory has 3 security tools for email: shelter, angel and fence. These were developed in response to attacks on Zapatista's mailing lists and personal addresses.

The Zapatistas were attacked by forging their email addresses on messages that subscribed them to hundreds of email lists around the world. Suddenly the email addresses became recipients of thousands of unwanted messages, rendering them useless.

There is also a "forward" program that will accept mail, fiddle with the from_address and the subject line and then mail it onto another address.

And there is a "pick" program that will sort the mail by language and send each language to a different address.

Finally, there is the "puppet" program that allows a user on this local machine to send mail from a trusted external address that will be sent out looking like it comes from the local address. That way, it appears that you are working at your desk when you are really at your boyfriend's house.

See EVOTE_HOME_DIR/eVote/src/tools/filters/README for details.

The EVOTE_HOME_DIR/eVote/src/tools/utils directory has a few more filters:

unhex.c

Reads stdin and looks for hex code that comes from a mailto. It replaces the hex code with ascii characters and puts the result on stdout and executes its command line. Useful in the alias file.

unhtml.c

This feature is courtesy of Zapatistas. If you make an alias entry:

unhtml: "|/usr/local/majordomo/wrapper unequal unhtml deaccent sorter\
    -er return -en return -es return -it return -o return sendmail -t"

people can send html files to the address:

unhtml@your_site.net

and a copy of the message will be sent back, but with much of the html code removed.

unequal.c

converts an email with quoted printables to 8 bit text.

deaccent.c

converts email with accented letters to 7 bit.

sorter.c

sorts mail by language and mails it to the address indicated for the language. It is in this chain of programs because it sends the results to the "return" address.

Qmail Compliant

Note that eVote is qmail compatible. When an address starts with an '&', the '&' is ignored. This feature was donated by Dustin Marquess.

Dustin also provided code so that if an address starts with one of the following characters, the address is ignored:

~ - Pathname (using sh homedir expansion)
# - Comment
+ - List separator (Used in "+list" to mark the start of addresses)
. - Pathname (relative to current directory)
/ - Pathname (absolute)
| - Program pipe




If There's Trouble

If you have trouble, and this section does not help, please contact Deliberate.Com. The best form of communication is email: eVote-users@deliberate.com. If you call and reach the answering machine, please identify yourself. Deliberate.Com does not return long distance calls from unknown callers.

These symptoms of trouble can occur:

* Trouble getting started.
* The Clerk coming down unexpectedly.
* Warning messages in the Clerk.log.
* eVote_insert timing out.

Each is discussed here.

Trouble Getting Started

If you have trouble getting The Clerk or eVote_insert to work, check these things:

If these things are as they should be, and you still have trouble, please write eVote-users@deliberate.com. Better yet join the "eVote-users" list at Deliberate.com and discuss your problem there.

If The Clerk Stops Unexpectedly

If The Clerk comes down on its own, it has run into some trouble(!). Check the last entries in EVOTE_HOME_DIR/eVote/data/Clerk.log. It should tell you what has happened and advise you how to proceed.

Hopefully the next section, "Trouble in Clerk.log" will also help. If not, please contact Deliberate.Com through eVote-users@deliberate.com.

Trouble in Clerk.log

Most of the messages in the Clerk.log are for information only, they do not indicate trouble.

However, it is possible to see:

No system resources. Coming down.

or

Too many open files? Coming down.

In either case, work with your system administrator or system vendor to correct these problems.

Other problems can arise that are fixable by altering the values in the EVOTE_BIN/eVote.cf file. Note however, that altering the values pertaining to interprocess communication also requires rebuilding the UNIX kernel.

Fixing The BLOCK_SIZE

You may get warnings in your Clerk.log that:

The current BLOCK_SIZE of 2048 is small for the ED list.
Please increase it.

This means that the number of polls for the named list has grown so that only 8 ballots can be contained in one block. If you expect the list to grow further, you should increase the BLOCK_SIZE:

  1. While The Clerk is running, log in as clerk and enter the command:

    eVote new_exe

  2. Edit the EVOTE_BIN/eVote.cf file so that the desired BLOCK_SIZE is listed. Doubling the old BLOCK_SIZE is a good solution.

  3. Restart The Clerk:

    eVote

Timing Out In eVote_insert

If, when eVote_insert is running, you see this message on stderr:

Timed out after 5 seconds of waiting for a response from The Clerk.

be sure that The Clerk is running in the background. Use:

ps -ef | grep eVote

"eVote check" may also time out.

If it is running, and your computer is very busy, 5 seconds may not be long enough to wait for a response from The Clerk.

The solution may be to alter the value of TIME_OUT in the EVOTE_BIN/eVote.cf file. You can do this while The Clerk is running and the change will take effect immediately.

Emergency Messages

There is another timeout of 250 seconds over eVote_petition and eVote_insert. If either program takes longer than that, or if either gets an unexpected signal that causes it to quit, an emergency message is sent to EVOTE_MAIL_TO and eVote-owner@eVoted-site.net detailing the problem and showing a copy of the email message that surfaced the problem. EVOTE_MAIL_TO can be specified in your EVOTE_BIN/eVote.cf file. The default value is eVote-owner@eVoted-site.net.

Interprocess Communication

eVote relies heavily on two of UNIX's interprocess communication facilities: message queues and shared memory. On a very busy system, the message queues and shared memory segments could get worked to their limits. If so, some action may be necessary on your part.

To learn the current limits on your machine, you can compile and run EVOTE_HOME_DIR/eVote/src/tools/utils/ipctest.c

If eVote/The Clerk is not the only application using the message queue facility, or if you are running two Clerks, you need to have a different "EVOTE_MSG_KEY" in the EVOTE_BIN/eVote.cf file. Simply change the value and restart The Clerk.

Shared Memory

eVote is sensitive to various parameters that are hard-coded in the kernel. The first of these relates to the shared memory facility: SHMMNI. This is the number of shared memory segments allowed by the system.

eVote requires one shared memory segment, and occasionally two, for each active eVoted list. If The Clerk detects that the number of available memory segments is dwindling dangerously, it adjourns all lists that don't currently have users online. In this case, a message will appear in your Clerk.log:

The number of available shared memory segments is only 2.

If such messages are rare, you may be able to ignore them without repercussions. However, if The Clerk does run out of memory segments and is unable to adjourn any lists, it stores everything and exits! In this case, near the end of the Clerk.log file, you'll see:

The system tunable parameter SHMMNI needs to be higher.

Increasing the SHMMNI parameter is the remedy. See "Altering System Tunable Parameters" below.

Message Queues

eVote is dependent on three system parameters that pertain to message queues: MSGMNI, MSGTQL and MSGMAX. Another parameter, STARTING_NICE, doesn't directly pertain to message queues but if STARTING_NICE isn't right, the symptoms will show up in the message queues.

MSGMAX is the maximum size, in bytes, that a message can be. eVote adjusts to this value, as long as it isn't something silly. Be sure it's more than than 512 bytes. Other than that, it needs no attention.

MAXMNI is the maximum number of message queues allowed in the system. eVote needs one message queue for each user that is currently participating in an eVoted list -- plus one queue for The Clerk.

If the number of available queues gets dangerously low, the Clerk.log will contain the message:

The number of available message queues is only 3.

If this happens, The Clerk will look for any queues to dead processes and drop those queues. If this message is rare, it may be OK to ignore it.

However, if The Clerk can't find any queues to drop, and there is no room for a new queue, it exits! In this case, near the bottom of the Clerk.log file will be the entry:

The system tunable parameter MSGMNI needs to be higher.

Increasing the MSGMNI parameter is the remedy.

MSGTQL is the maximum number of messages that can be waiting to be received at one time. This is a system-wide parameter. If the number of messages waiting in all the queues exceeds MSGTQL, the results are disastrous.

Before sending a message to The Clerk, the number of waiting messages is checked. This is quite expensive (resource-wise) but necessary. If the callers to The Clerk fill up all the message slots, The Clerk will be unable to send a return message and will get stuck.

You will have warnings before this happens. However, because the check against MSGTQL is performed on the user interface side, no messages concerning MSGTQL appear in Clerk.log. When the MSGTQL limit is approached the user will experience a slow-down in response time. If, after 5 seconds of waiting, the user still can't get a message to The Clerk, an error message will be printed to the user's standard error:

eVote: Too many messages on the queue.

If this happens, there are three things to try. But, to try 1 or 2, eVote_Clerk must be running under root.

  1. You can send a "priority up" command to eVote:

    eVote priority up

  2. You can lower STARTING_NICE value in the EVOTE_BIN/eVote.cf file.

  3. You can increase MSGTQL.

Altering STARTING_NICE

If you wish to change the starting priority of The Clerk, bring The Clerk down and add an entry to the EVOTE_BIN/eVote.cf file:

STARTING_NICE = 20

The default nice value for UNIX is 20. A smaller number makes The Clerk run faster relative to the other processes in the system.

Altering System Tunable Parameters

To alter system tunable parameters you must rebuild the UNIX kernel! The system tunable parameters that The Clerk depends on are SHMMNI, MSGMNI, MSGTQL, and MSGMAX.

These parameters are sometimes #defined in the system headers, msg.h and shm.h. This is not dealt with consistently across the various flavors of Unix. In any case, changing these these values requires a rebuild of the kernel.




Back to Table of Contents Chapter VI
Last modified: Fri Apr 4 19:19:47 EST 2003