/*
 * GNU.FREE 2002
 *
 * Copyright (c) 1999, 2000, 2001, 2002
 * The Free Software Foundation (www.fsf.org)
 *
 * GNU.FREE Co-ordinator: Jason Kitcat <jeep@free-project.org>
 *
 * GNU site: http://www.gnu.org/software/free/
 * 
 * FREE e-democracy site: http://www.free-project.org
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program (COPYING); if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 */

INSTALL

=========================
- CONTENTS
=========================

+ Installing GNU.FREE
	- Writing config files
	- The Installer
+ Building the Software
	- JNLP Note
	- Internationalisation Note
+ Running GNU.FREE

=========================
- Installing GNU.FREE 1.9
=========================

Before you can run GNU.FREE you will need to edit or create a configuration file.
The configuration is written in XML and is read by the installer to setup GNU.FREE
There is a sample file in the FREE-1.9 directory called gnufree-edl-sample.xml

Currently most of the fields aren't used by the Installer or won't impact the running of
the software. Key ones which are used:

gnufree:vote_system
	- valid identifiers:
	'fptp'	First Past the Post (simple majority vote)
	'borda' Ranking system where each candidate is allocated points according to how the vote ranked them.
Keep the modifier as 'default'.

gnufree:choice
	- code:
	This is what the system sends to servers, so it must be unique for each candidate.
	- other:
	Ignored.
	- Main text:
	Used in the graphical display.
	
Other fields such as gnufree:write_in and gnufree:jnlp will be used in the next version.

When you have created a valid file, run the installation:

-MacOS Users:
Double-click the FreeInstall.app icon

-Other OS Users:
Run FreeInstall.Install from FreeInstall.jar in the FREE-1.9 directory

On a typical Solaris setup with Java SDK 1.2 you would do it with a command like
this (change the paths according to your system):

"/usr/java1.2/bin/java -cp .:FreeInstall.jar:log4j.jar:freeawt.jar:cryptix32.jar:xerces.jar FreeInstall.Install"

Other command-line systems will use the same or nearly the same syntax.

On a Win32 system it would be:

"java -cp .;FreeInstall.jar;log4j.jar;freeawt.jar;cryptix32.jar;xerces.jar FreeInstall.Install"


+ Install Advice: What the fields in Free Install mean +

[] General notes

When entering passwords avoid using plain English. Passwords ideally should be long and a
combination of letters and numbers. The following punction is also allowed ;()*=-_+@,.<>?

If any problems occur all file changes are recorded in the FreeInstall.log file.

(Note that you'll need a Java 1.1.x compiler and Virtual Machine to do
all actions mentioned in this file, there's a GNU page of help at 
http://www.gnu.org/software/java/java.html or see http://java.sun.com for more info)

[] Picking the file

Enter the full filename of your configuration file (see above for more on config files) including
the file extension. 

Example:

this_is_a_test.xml  would open the file of that name in the FREE-1.9 directory.


[] Screen One

This screen allows you to set which servers will be used for the vote.
NB: Server names can be either DNS style (sterling.swingdigital.com) or numeric IP addresses
 (142.42.36.21).

Regional Server name: The server where RTServer will be running in regional mode e.g. test.vote.com
Electoral Roll Server name: The server where ERServer will be running e.g. roll.foo.com
Totaller Server name: The server where RTServer will be running in totaller mode e.g. total.bn.com
ERServer port number: The port on which GNU.FREE services will communicate, it must be a number >1024
RTServer port number: The port on which GNU.FREE services will communicate, it must be a number >1024
[These last two options are provided if you want to run ERServer and RTServer on the SAME machine,
 this should only be for test purposes. Otherwise leave them as the same value.]
 
[] Screen Two: DEPRECATED - Set your choices in the XML file.

This screen lets you set what the choices to vote for will be. Currently up to 4 choices are possible.

Party 1-4: An alphanumeric choice to vote for.

[] Screen Three

Here you set a single password.

Authorisation password: This plain-text password is used to create the Message Authentication Codes
(MACs) that provide tamper protection. This password prevents crackers from generating new MACs 
so that tampered packets no longer appear tampered to the system.

[] Screen Four

The key installer screen is for providing the keys for AuthKey. This creates unique, single use
authorisation keys that allow the system to verify that a voter is allowed to vote without knowing
who the voter is. These keys are also used to encrypt database information.

Password to seed key 1: A string that is combined with a secure random number to create key one.
Password to seed key 2: A string that is combined with a secure random number to create key two.
MAC key password: Key to make the Message Authentication Code which data is passed through before it
 encrypted with one of the keys.
 
[] Screen Five
 
The Databases screen allows you to choose what kind of database the servers will store their
information in. The default is Hypersonic-SQL (a pure Java system), which is built in and
ready to go. So unless you have a MySQL or PostgreSQL (>v7) system setup or plan to, we recommend
staying with the default.

[] Screen Five(b)

These supplementary screens will only appear if you choose a database which isn't the default.

You won't be able to provide the information for these fields unless you have already setup a
database server for use by GNU.FREE

[] Screen Six

Installation progress. Depending on which version of Java, which operating system and your hardware
specifications this could take a while. On some machines it may appear as though nothing is happening
or even that the system has crashed - BE PATIENT! The system is creating secure random numbers to
seed some keys. These take time... however the remaining portion will be quick and you will see the
files being changed. Creating keys is hard work so on systems this may take a significant length of
time, so make some coffee!

Examples:

Pentium 120Mhz with 90Mb RAM running GNU/Linux and JDK1.3:
	FreeInstall takes over 10 minutes to complete.
PowerComputing PowerPC 604e 250Mhz with 128Mb RAM running MacOS 8.6 and MRJ2.2:
	FreeInstall takes approx 2 minutes to complete.


======================
- Building the Software
======================

By using the installation program, FreeInstall, a key security file in
the util directory will have changed. This encodes some important security info
which is unique to your implementation. It is stored, along with other common
GNU.FREE files in freeutil.jar - a copy is included if you want to quickly run GNU.FREE for
demo purposes. For secure implementation you MUST create your own copy of freeutil.jar
and here's how:

1) Rename the existing freeutil.jar to freeutil.old.jar

2) Move from the FREE-1.9 directory to FREE-1.9/Free/util/

3) Compile the files, in our typical Solaris implementation this would be with:

	"/usr/java1.2/bin/javac -classpath .:cryptix32.jar *.java"
	
	(which would be run when you are in FREE-1.9/Free/util/ directory)
	
	On Win32 that would be:
	
	"javac -classpath .;cryptix32.jar *.java"
	
4) Create a jar file, in our typical Solaris setup we would type:

	"/usr/java1.2/bin/jar -cf freeutil.jar *.class"

	(which would be run when you are in FREE-1.9/Free/util/ directory)
	
	On a Win32 system we have been informed that you need to run it as:
	
	"jar -cf freeutil.jar Free\util\*.class"
	
5) Finish off by copying the new freeutil.jar found in FREE-1.9/Free/util/
   to the FREE-1.9 directory.


>>>>>>>>>>>>>>>> JNLP NOTE <<<<<<<<<<<<<<<<<<<<

If you plan on using JNLP to distribute the GNU.FREE client then you need to do
one minor code change until we alter the install system.

Open FreeClient/FClient.java and remove line 94:

	"FreePanel.showSplash(4000);"
	
(or comment it out!)

Now carry on... when done read JNLP-INSTALL for more.

>>>>>>>>>>>>>>>> EOF JNLP NOTE <<<<<<<<<<<<<<<<<<<<


>>>>>>>>>>>>>>>> INTERNATIONALISATION NOTE <<<<<<<<<<<<<<<<<<<<

Since version 1.6 of GNU.FREE you can now provide the the FreeClient program
in different languages without any programming.

Currently we have 9 languages included with the package, they can be found in the
Lang directory. To use the files the need to be in the FreeClient's class path.

TO CHANGE LANGUAGE:

Open FClient.java and look for the constants on lines 45 + 47. These set the language
and country the program will use. Current valid string combinations are:

Language:			Country:
	nl					NL
	en					GB
	fr					FR
	de					DE
	el					GR
	pl					PL
	pt					BR
	ru					RU
	sv					SE
	
Having done this change then continue to compile as normal.

>>>>>>>>>>>>>>>> EOF INTERNATIONALISATION NOTE <<<<<<<<<<<<<<<<<<<<

Now you need to compile the main GNU.FREE programs which all depend on the freeutil.jar
file we've just made.

To compile & run GNU.FREE programs you need to make sure that you set a compile time
classpath which includes the FREE-1.9 directory as well as the following files
included with GNU.FREE:

-freeutil.jar
	A new copy of common GNU.FREE files
-freeawt.jar
	Support files for the GNU.FREE interface
-freedbpool.jar
	Database caching/optimisation files
-log4j.jar
	The log4j logging system
-cryptix32.jar
	Encryption & security algorithms
-xerces.jar
	XML parser package (used for install only)
-hsql.jar
	The Hypersonic SQL database system

NOTE: If you chose a database other than HSQL then you need to replace the references to
hsql.jar with the correct jar file:

- jdbc7.0-1.1.jar
	PostgreSQL 7.0.x JVM 1.1 database driver
	(for the latest versions http://jdbc.postgresql.org/)
	
- mm.mysql-2.0.4-jdbc.jar
	mySQL 3.x JVM 1.1 or 1.2 database driver
	(for the latest versions http://mmmysql.sourceforge.net/)
	
Make sure you are in the "FREE-1.9" directory before you compile the 4 GNU.FREE programs.

In our example Solaris system you would compile using the following commands:

	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:. Free/*.java"
	
On Win32:

	"javac -classpath freeutil.jar;freeawt.jar;freedbpool.jar;hsql.jar;log4j.jar;cryptix32.jar;. Free/*.java"
	
[Note: If you experience a compilation problem related to Free.DBPool files then move the DBPool directory from
 FREE-1.9/Free/DBPool to FREE-1.9/ and try again.]
	
Run the command again but:

	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:. ERServer/*.java"
	
On Win32:

	"javac -classpath freeutil.jar;freeawt.jar;freedbpool.jar;hsql.jar;log4j.jar;cryptix32.jar;. ERServer/*.java"
	
Again for PollManager:
	
	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:cryptix32.jar:. PollManager/*.java"

On Win32:

	"javac -classpath freeutil.jar;freeawt.jar;crytix32.jar;. PollManager/*.java"
	
And one more time for FreeClient:
	
	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:cryptix32.jar:. FreeClient/*.java"

On Win32:

	"javac -classpath freeutil.jar;freeawt.jar;cryptix32.jar;. FreeClient/*.java"
	
And that's it! You should be all done.... Read on if you want to learn how to run the
programs.

[ PERFORMANCE NOTE: While GNU.FREE has many performance optimizations there are often
  compiler facilities to further tune Java systems. For example Sun's (Solaris) compiler
  takes a -O command-line option to optimize code. However this may dramatically slow
  down compiltion time, crete larger class files and cause new bugs. We do not test
  GNU.FREE code with this option so proceed at your own risk.
  
  There also tools both commercial and Free which reduce class size, optimize code and
  obfuscate Java output (this can make reverse engineering harder but by no means impossible).
  For more information see sites such as http://www.meurrens.org/ip-Links/java/codeEngineering/
  which provide details and links to software. ]


======================
- Running GNU.FREE
======================

Running Java programs can be bit tricky to the uninitiated because you need to specify
the Package name and also the main class name. Now I'm the first to admit that the GNU.FREE
package names aren't all brilliant but I'm going to stick with them for the time being.
Anyway here are the names you need to invoke for the Java Virtual Machine:

Regional/Totaller Server		Free.RTServer
Electoral Roll Server			ERServer.ERServer
Voting Client program			FreeClient.FClient
Polling station client			PollManager.PollManager

MacOS X users should follow the Solaris instructions but remove ':$CLASSPATH'.
Also only type 'java' and not the full path to the java program.

So in our Solaris system that would be done (respectively):

	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:.:$CLASSPATH Free.RTServer"
	
	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:.:$CLASSPATH ERServer.ERServer"

	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:cryptix32.jar:.:$CLASSPATH PollManager.PollManager"
	
	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:cryptix32.jar:.:$CLASSPATH FreeClient.FClient"
	
Why all that "$CLASSPATH" stuff? Because specifying a runtime classpath overrides the 
system classpath settings, but we don't want that to happen. So what doess $CLASSPATH
say? In this example it contains:

	"./:/package/java/lib/:/local/share/arch/solaris2/package/warwick-a1/lib/classes"
	
On Win32 run the programs with:

	"java -cp freeutil.jar;freeawt.jar;freedbpool.jar;hsql.jar;log4j.jar;cryptix32.jar;.;%CLASSPATH% Free.RTServer"

	"java -cp freeutil.jar;freeawt.jar;freedbpool.jar;hsql.jar;log4j.jar;cryptix32.jar;.;%CLASSPATH% ERServer.ERServer"

	"java -cp freeutil.jar;freeawt.jar;cryptix32.jar;.;%CLASSPATH% PollManager.PollManager"

	"java -cp freeutil.jar;freeawt.jar;cryptix32.jar;.;%CLASSPATH% FreeClient.FClient"

Your programs should be up and running now!

You still need to populate databases and build keys. Check the "Getting Started" document in
the Docs directory of your installation or on the website (filename: gs1.html) for information
on how to do this.

Once that's been done make sure you read the hints 'n tips and advice in the "Running Elections"
file (filename: re1.html) - have a good election!

Visit http://www.free-project.org/ for more help and advice.
	
++++

Problems, bugs and updates for this file and GNU.FREE as a whole should go to jeep@free-project.org

EOF INSTALL