Adeona version 0.2.1 as of July 14, 2008

Adeona is the first privacy-preserving, decentralized, open source 
laptop tracking system that can help in the recovery of lost or 
stolen laptops.  Adeona does not rely on a proprietary, central 
service.  

Adeona is designed to use the open source distributed storage 
service OpenDHT, to store location updates. The software client 
component of the system uses strong cryptographic mechanisms to not 
only encrypt the location data, but also ensure that the ciphertexts 
stored within OpenDHT are *anonymous* and *unlinkable*. At the same 
time, retrieving the location information is easy.

For more information about Adeona, please visit our website at
http://adeona.cs.washington.edu


USAGE

For detailed instructions, please consult the Adeona website at
http://adeona.cs.washington.edu/documents.html

Linux
---------------------------------------------------------------------

-Installing and Initialization

Make sure your computer has the following installed
1. OpenSSL
2. traceroute
3. cron
4. iwconfig [optional]

Also, please note the default installation directory prefix the installer
script is set to use, "/usr/local". You can change it in
adeona/scripts/installadeona.sh

To install the Adeona system, execute the following commands
$ tar xzf adeona-0.2.1.tar.gz
$ cd adeona/
$ ./configure

If there are no errors from the configure script,
$ sudo make install

The install script will echo a crontab entry that you may copy+paste into,
$ sudo crontab -e

The crontab entry is of the form
INSTALLDIR=/usr/local/adeona
@reboot $INSTALLDIR/adeona-client.exe -s $INSTALLDIR/adeona-clientstate.cst -r $INSTALLDIR/resources/ -l $INSTALLDIR/logs/ &

Note the "&" at the end, which is necessary unless you want the parent /bin/sh
hanging around while the client is running.

After installation, you can go ahead and
$ rm -rf adeona/ && rm adeona-0.2.1.tar.gz

The install script included in the distribution does the following: 
1. Builds the Adeona programs.
2. Installs the programs under /usr/local/adeona by default.
3. Runs the Adeona initialization program which requests for a password
for encrypting your location-finding credentials. It then creates two
files, adeona-clientstate.cst and adeona-retrievecredentials.ost.
4. Starts the Adeona client.
5. Makes a copy of adeona-retrievecredentials.ost on your Desktop or
home directory as a reminder for making a backup.

IMPORTANT: The client program relies on cron to make sure it starts
up.  Please make sure you add the correct crontab entry. Otherwise,
the client will not run the next time you reboot.

-The Adeona client
The Adeona client program is scheduled to start everytime you reboot
your computer through a cron entry in /etc/crontab. If you'd like to
stop the client, the 'kill' command can be used.  
To restart it manually, do below
$ ADEONADIR=/usr/local/adeona
$ sudo $ADEONADIR/adeona-client.exe -r $ADEONADIR/resources/ -l $ADEONADIR/logs/ -s $ADEONADIR/adeona-clientstate.cst 

-Retrieval
To view the arguments and options for the Adeona retrieval program, run the
command below
$ ADEONADIR=/usr/local/adeona
$ $ADEONADIR/adeona-retrieve.exe -h

For example, the command below will retrieve the most recent location update,
given an encrypted /path/to/your/adeona-retrievecredentials.ost file.
$ $ADEONADIR/adeona-retrieve.exe -r $ADEONADIR/resources/ -l /path/to/results/ -s /path/to/your/adeona-retrievecredentials.ost -n 1

Mac OS
---------------------------------------------------------------------

-Installing and Initialization
To install the Adeona system,
1. Mount the disk image (.dmg) by double clicking on the adeona-osx.dmg icon.
2. Double click on the package icon. This will launch the installer
that will guide you through the rest of the installation and
initialization process.

The installer does the following:
1. Installs the Adeona programs and files under /usr/local/adeona. The
Adeona retrieve terminal is installed in /Applications/Adeona so you
can easily find it using Spotlight.
2. Runs the Adeona initialization program which requests for a
password with which your location-finding credentials are protected
with.
3. Installs a launchd job which will start the Adeona client and keep
it running onwards.
4. Makes a copy of adeona-retrievecredentials.ost on your Desktop so
you won't forget to make a backup.

-The Adeona client
The Adeona client is kept running by the OS X program, launchd. The
plist file for it is installed in
/Library/LaunchDaemons/edu.washington.cs.adeona.plist

If you'd like to stop the client, run the commands below in Terminal,
$ sudo launchctl stop edu.washington.cs.adeona
$ sudo launchctl unload /Library/LaunchDaemons/edu.washington.cs.adeona.plist
*launchd might automatically keep the client running if you don't unload

To run the client manually, run the commands below in Terminal
$ sudo launchctl load /Library/LaunchDaemons/edu.washington.cs.adeona.plist
$ sudo launchctl start edu.washington.cs.adeona

-Retrieval
To retrieve locations,
1. Browse to the Adeona folder located under Applications
2. Double click on the adeona-retrieve.term icon. This will run a
Terminal window that will guide you through the retrieval process.

Note: You can also follow the Linux instructions for retrieving if
you want to do it manually. Or, run the command below in Terminal,

$ /usr/local/adeona/scripts/adeona-retrieve.sh

Windows XP/Vista
---------------------------------------------------------------------

-Installing and Initialization
1. Double click on the AdeonaSetup.exe icon.
2. This will launch the Adeona installer that will guide you through
the rest of the installation and initialization process.

The installer does the following:
1. Installs the Adeona programs and files under C:\Programs Files\Adeona by default. 
2. Runs the Adeona initialization program which will request a password
with which your location-finding credentials are protected with.
3. Installs the Adeona client program as a Windows service which will
start the client program and keep it running onwards.
4. Creates a Start Menu entry called Adeona where you can select
actions from.
5. Makes a copy of adeona-retrievecredentials.ost on your Desktop so
you won't forget to make a backup.

-The Adeona client
The Adeona client is kept running as a Windows service called
AdeonaClientService.

If you'd like to stop the client, run the command below in the command
prompt, 
> net stop AdeonaClientService

If you'd like to run the client manually, run the command below in
the command prompt,
> net start AdeonaClientService

Or, if you don't like the command prompt, 
1. Navigate to Start -> Control Panel 
-> Administrative Tools -> Computer Management

2. In the Computer Management window, navigate to 
Services and Applications -> Services

3. You can use this interface to Start or Stop the Adeona client program

-Retrieval
To run the Adeona retrieval program,
1. Navigate to Start -> Programs -> Adeona -> Run Adeona Recovery.
The Adeona Recovery Wizard will guide you through the rest of the
retrieval process.


UNINSTALL

Hopefully you won't ever need to follow the instructions below but
here they are. The instructions lead to the complete removal of the
Adeona system your computer.

Linux
---------------------------------------------------------------------
1. Use the 'kill' command to kill the adeona-client.exe program
2. Delete the Adeona directory,
$ sudo rm -rf /usr/local/adeona

3. Remove the crontab entry for Adeona through
$ sudo crontab -e

Mac OS
---------------------------------------------------------------------
Run the commands below in Terminal,
1. Stop the adeona-client.exe program,
$ sudo launchctl stop edu.washington.cs.adeona
$ sudo launchctl unload /Library/LaunchDaemons/edu.washington.cs.adeona.plist

2. Delete the Adeona folder and files
$ sudo rm -rf /usr/local/adeona
$ sudo rm -rf /Applications/Adeona
$ sudo rm /Library/LaunchDaemons/edu.washington.cs.adeona.plist 
$ sudo rm -rf /Library/Receipts/adeona.pkg

Windows XP/Vista
---------------------------------------------------------------------
The Uninstall program will completely remove Adeona from your system.
1. Navigate to Start -> Programs -> Adeona -> Uninstall Adeona


ACKNOWLEDGEMENTS

OpenSSL
The OpenSSL crypto library provides the cryptographic primitives
needed by Adeona.

isightcapture
The isightcapture program by Axel Bauer is included in the Mac OS
packages used by Adeona to take snapshots. More information about the
isightcapture program can be found at
http://www.intergalactic.de/pages/iSight.html

Cygwin
The Cygwin project is used to build the Windows version of Adeona. The
cygwin1.dll, cygcrypto-0.9.8.dll and the cygrunsrv.exe program are
included in the Windows package 

NSIS
The Nullsoft Scriptable Install System is used to create the Windows
installer of Adeona.


LICENSE

The Adeona software package is licensed under the GNU GPLv2 license.
Please see the file License.txt included with this distribution for
additional information.


CONTACT

For questions, comments and suggestions, please visit our website at 
http://adeona.cs.washington.edu/contact.html 


