Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

The software updater is a continuously running program that is bundled alongside Seattle installations to allow our nodes to update to new versions of Seattle. This document describes how to set up the server side of things, so that the software updater can be used correctly.

Setting up the server involves modifying softwareupdater.py itself! Be sure to do this before handing out installers from your Clearinghouse!

Dependencies

  • A web server. (Apache works well for this)



Instructions

Generating Key Pairs

If you already have a key pair you wish to use to sign your metainfo file, you can skip to Telling Clients How to Update.

Create an empty directory called keygen/, and from trunk/, run preparetest.py to that directory:

$ python preparetest.py ./keygen/

From the keygen/ directory, run generatekeys.py. It takes an output filename and a key length. The key length defaults to 1024 if not specified. The following code snippet will generate two files: myupdatekeys.privatekey and myupdatekeys.publickey.

$ python generatekeys.py myupdatekeys 2048

Keep the two generated keys in a safe location. You no longer need this directory, and it is safe to delete it.



Telling Clients How to Update

Now we have to update the software updater client to inform it to acquire updates from us. Find softwareurl and softwareupdatepublickey in softwareupdater.py and change them to reflect your setup. For public keys generated by generatekeys.py, the first number corresponds to the 'e' value, and the second number corresponds to the 'n' value.

softwareurl = "http://seattlesoftwareupdater.poly.edu/updatesite/"

# embedded this because it seems easier to update it along with this file
# Every computer running Seattle will have this same public key, and will trust
# files signed by this key.
softwareupdatepublickey = {'e':82832270266597330072676409661763231354244983360850404742185516224735762244569727906889368190381098316859532462559839005559035695542121011189767114678746829532642015227757061325811995458461556243183965254348908097559976740460038862499279411461302045605434778587281242796895759723616079286531587479712074947611, 'n':319621204384190529645831372818389656614287850643207619926347176392517761801427609535545760457027184668587674034177692977122041230031985031724339016854308623931563908276376263003735701277100364224187045110833742749159504168429702766032353498688487937836208653017735915837622736764430341063733201947629404712911592942893299407289815035924224344585640141382996031910529762480483482480840200108190644743566141062967857181966489101744929170144756204101501136046697030104623523067263295405505628760205318871212056879946829241448986763757070565574197490565540710448548232847380638562809965308287901471553677400477022039092783245720343246522144179191881098268618863594564939975401607436281396130900640289859459360314214324155479461961863933551434423773320970748327521097336640702078449006530782991443968680573263568609595969967079764427272827202433035192418494908184888678872217792993640959292902948045622147093326912328933981365394795535990933982037636876825043938697362285277475661382202880481400699819441979130858152032120174957606455858082332914545153781708896942610940094268714863253465554125515897189179557899347310399568254877069082016414203023408461051519104976942275899720740657969311479534442473551582563833145735116565451064388421}



Setting up the Update Directory

Now, create a new folder called updatesite/. This is where our update files will be stored. Run preparetest.py to this directory. You should also copy over other files that you want the software updater to download.

$ mkdir updatesite
$ python preparetest.py updatesite

From within updatesite/, we want to now generate the metainfo file. Run writemetainfo.py, pointing to the private key you wish to use. The -n argument indicates that we are generating a new metainfo file.

MAKE SURE THE KEY YOU USE TO SIGN THE METAINFO FILE IS NOT IN THIS DIRECTORY. IT WILL BE PROPAGATED TO CLIENTS.

$ python writemetainfo.py ../myupdatekeys.privatekey ../myupdatekeys.publickey -n



Setting up the Web Server

You must now make sure your web server can serve the all the files in your update directory. For Apache, you can simply move the update directory to /var/www/, or create a symlink to updatesite/. Once this is complete, you are done!



Propagating New Updates

Deploying a new update is extremely easy. For safety reasons, we will create a new directory instead of using the existing one. Create a new directory called new_updatesite/, and put the files that you want new clients to update to there. Make sure to copy the metainfo file from the existing updatesite/ directory so writemetainfo.py can do a few sanity checks on what was updated etc. Now regenerate the metainfo file in the new directory. Note that the -n is missing, as we already have a metainfo file. Also, be SURE to use the same key that you used to initially sign the metainfo file.

$ python writemetainfo.py ../myupdatekeys.privatekey ../myupdatekeys.publickey

You may want to test the new directory by changing an existing client's softwareupdater to point to the new directory, and then let it perform a software update. If there are no problems, then back up the old update directory, and rename the new update directory so that it is served by your web server. The update will propagate to clients within an hour. (Clients wait up to an hour before checking the designated URL for updates.)