Skip to content

Latest commit

 

History

History
136 lines (106 loc) · 4.85 KB

SoftwareUpdaterSetup.md

File metadata and controls

136 lines (106 loc) · 4.85 KB

NOTE: This document is not fully operational currently. The second half of this document, starting with "Setting up the Update Directory" needs to be updated to reflect the updated installer packaging mechanism etc.

Softwareupdater Setup

The softwareupdater is a continuously running program that is bundled alongside Seattle installations to allow nodes to update to new versions of Seattle. The softwareupdater client queries updates from a softwareupdater server site URL that is embedded in the client code. If updates are available, their signature is checked using a public key also embedded in the client.

This document describes how to set up the server side of things so that the softwareupdater client works correctly.

Dependencies

A softwareupdater site serves files via the Web using software like Apache.

Setting up the site for the first time

We will assume here that you want to set up a softwareupdater site from scratch. If you already have a key pair you wish to use to sign your metainfo file, skip to Telling Clients How to Update.

Generating Key Pairs

Build the softwareupdater repository (see the Build Instructions for details):

git clone https://github.com/SeattleTestbed/softwareupdater/
cd softwareupdater/scripts
python initialize.py
python build.py

In the generated ../RUNNABLE directory, generate a new pair of cryptographic keys for the softwareupdater, supplying an arbitrary key name and an optional key length in bits (default 1024):

cd ../RUNNABLE
python generatekeys.py new_update_signing_key 4096

Keep the two generated keys in a safe location. (You may remove the rest of the build directory however.)

Telling Clients How to Update

Now we have to configure the software updater client (which will be included in every future install from your deployment) to inform it how to acquire updates from us. For this, first clone and initialize the installer-packaging repo, https://github.com/SeattleTestbed/installer-packaging

In the DEPENDENCIES/softwareupdater subfolder, edit softwareupdater.py as follows: Find softwareurl and change it to reflect your web server setup. Then, set softwareupdatepublickey to the public key generated by generatekeys.py. The first number in the public key file corresponds to the 'e' value, and the second number corresponds to the 'n' value.

For example,

softwareurl = "http://seattlesoftwareupdater.poly.edu/updatesite/"
# ...
softwareupdatepublickey = {'e':82832..., 'n':31962...}

Every computer installing your installer will have this same public key, and will trust files signed by this key.

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.)