XS-activation: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Software]]
[[Category:Software]]
[[Category:SchoolServer]]
[[Category:SchoolServer]]
[[Category:Security, activation and deployability]]


The XS Activation service runs on the school server, and provides antitheft services. It can serve 'standard' leases, or delegated leases, depending on how it is set up.
The XS Activation service runs on the school server. It listens on port 191 serving un-activated XO laptops with activation leases. If it doesn't know a laptop's activation lease, it does nothing. The leases are automatically imported when a USB drive with a valid lease.sig file is attached (see [[Firmware Key and Signature Formats]]). The USB stick can also be used to activate XOs directly: this package is a short cut in that process and has an identical effect.


'''This page describes xs-activation as shipped in xs-0.6. For earlier versions, see the README file included in the package.'''
The activation service uses xinetd, which means it does not run as a daemon but is started up whenever necessary.


== Likely use case ==
= Use cases =


XS-activation is useful in a number of scenarios. The main ones are:
This service is primarily used by brand new laptops, at boot time. Once the laptops have activation leases they renew them via other means. A laptop will only need this service again if its lease expires.


* Activating just-shipped XOs in large numbers via Wireless, using 'standard' leases.
Often the laptops will be activated in batches in a warehouse situation. Early laptops depolyments have being given very long leases and are unlikely to need re-activation in the hardware's lifetime.
* Running in a school, generating short-lived leases for the XOs in the school. For this, delegated leases are needed. In this role, an XO can be marked as stolen on the XS. Next time the laptop is seen, it will cause the laptop to shut down.


For more detail on the usage scenarios, see [[XS Blueprints:Lease and update server]].
== Releases ==


= Configuration, setup =
* [http://dev.laptop.org/git?p=users/dbagnall/xs-activation.git;a=tags Latest tagged releases]
* for Fedora 7 based releases (up to XS 0.4): [http://xs-dev.laptop.org/xsrepos/testing/olpc/7/i386/xs-activation-0.2-1.xs7.noarch.rpm xs-activation-0.2]


XS-activation starts up automatically with the XS. For xs-activation to do useful work, it must have either 'standard' act01 leases, or a combination of keys and delegations.
== README in the latest development version ==


== Loading activation data ==
<gitembed>users/dbagnall/xs-activation.git||README||660||700</gitembed>

To load data for xs-activation, the procedure is as follows:

* On a FAT formatted USB disk, create a directory called "xs-activation"
** If you want to use the same USB disk for many servers, you can instead create a directory called <code>xs-activation/SERVERNAME</code> where servername is the output of <code>hostname -d | cut -f1 -d. </code>. For example, on a server <code>schoolserver.'''foo'''.bar.edu.pr</code>, the directory will be <code>xs-activation/foo</code>.
* Place in the directory the files you intend to load
* Create a manifest for the set of files.
cd /path/to/directory
TMP=$(mktemp)
sha1sum * > $TMP
mv $TMP manifest.sha1
* If the XS server has "xs-security-on" as described here http://dev.laptop.org/git/users/martin/xs-tools/tree/README , then you will need to provide the signature for the manifest file.

With this, you have a USB disk that you can plug on the XS, and the XS will automatically read and import the data from it. For debugging, see /var/log/user.log

== Standard leases ==

Follow the general loading procedure above, only listing 'leases.sig' in the directory. Leases are split up per-machine so you can later load a different leases.sig file, which will add to the leases the XS can serve.

== Delegated leases ==

To use delegated leases you first need to use the [http://dev.laptop.org/git/bios-crypto bios-crypto package] to

# Create OATS and ACT keys for your deployment, and get them installed on the XOs
# Create server keys
# Create delegations of the OATS and ACT keys from the OATS and ACT keys to the server, ''for each XO that will be managed by the XS''.

The [http://dev.laptop.org/git/bios-crypto bios-crypto package] includes tools to the keys and delegations described above. To load them on a XS, follow the loading procedure described above.

You can supply the following files:

* 'server.pri' and 'server.pub': keys for the XS.
* 'd-lease.sig': lease delegations
* 'd-oats.sig': OATS delegations

Note that not all the files are needed. The keys files are only needed the first time (and will be rejected subsequent times).

If after the initial load of data, a new USB disk is prepared with new d-leases.sis and d-oats.sig files (plus the updated manifest), the new delegations will be added to the data already in the XS.

=== Limiting lease length ===

To set the length of the delegated leases served, create a file /library/xs-activation/leasetimelimit with the number of days the leases should be valid for. Example:

# 10 day leases
echo 10 > /library/xs-activation/leasetimelimit

The maximum value accepted is 300. xs-activation will not serve delegated leases longer than 300 days.

= Usage =

In normal use, xs-activation does its job transparently and does not require any user intervention.

== Monitoring and marking stolen XOs ==

Moodle offers a status page and tools. The school teacher must use an XO that has registered and has 'coursecreator' privileges in the XS. With that XO, the Moodle interface offers an 'Antitheft' page, under 'Admin -> Users -> Antitheft'.

In that page, a table shows

* The XOs that have been served leases
* What account in Moodle they are associated with (if the XO is registered)
* When the XO last used Moodle, and when it got its last lease.
* An option to mark the XO as stolen
* If an XO request a new lease after being marked as stolen, xs-activation will serve a "kill" signal, and this will be noted in the report.

== Preparing a 'rescue' lease.sig ==

In some situations, XOs may be unable to get their activation leases directly from the XS via wireless, and will need a rescue disk. Some of the cases where this is true are

* XOs where the lease has run out, and cannot connect directly to Access Points (for example: 8.2.x)
* XOs with faulty wireless
* In schools with saturated wireless spectrum

The procedure is as follows:

# The school teacher must use an XO that has registered and has 'coursecreator' privileges in the XS. With that XO...
# Open Browse.xo, visit the 'Local schoolserver' (Moodle)
# Go to "Admin -> Users -> Antitheft
# Click on the ''Get a "rescue" leases.sig file'' option. This will download a file to the Journal.
# Switch to the Journal, rename the file from "File leases.sig downloaded from ..." to "leases.sig"
# Plug a USB disk, when the USB disk icon appears at the bottom of the screen
# Copy the leases.sig file to the disk
# Unmount the USB disk

Now the USB disk can be used to recover any of the laptops in that school. Note that the rescue leases is valid for only 2 days.

Latest revision as of 19:53, 14 February 2011


The XS Activation service runs on the school server, and provides antitheft services. It can serve 'standard' leases, or delegated leases, depending on how it is set up.

This page describes xs-activation as shipped in xs-0.6. For earlier versions, see the README file included in the package.

Use cases

XS-activation is useful in a number of scenarios. The main ones are:

  • Activating just-shipped XOs in large numbers via Wireless, using 'standard' leases.
  • Running in a school, generating short-lived leases for the XOs in the school. For this, delegated leases are needed. In this role, an XO can be marked as stolen on the XS. Next time the laptop is seen, it will cause the laptop to shut down.

For more detail on the usage scenarios, see XS Blueprints:Lease and update server.

Configuration, setup

XS-activation starts up automatically with the XS. For xs-activation to do useful work, it must have either 'standard' act01 leases, or a combination of keys and delegations.

Loading activation data

To load data for xs-activation, the procedure is as follows:

  • On a FAT formatted USB disk, create a directory called "xs-activation"
    • If you want to use the same USB disk for many servers, you can instead create a directory called xs-activation/SERVERNAME where servername is the output of hostname -d | cut -f1 -d. . For example, on a server schoolserver.foo.bar.edu.pr, the directory will be xs-activation/foo.
  • Place in the directory the files you intend to load
  • Create a manifest for the set of files.
    cd /path/to/directory
    TMP=$(mktemp)
    sha1sum * > $TMP
    mv $TMP manifest.sha1

With this, you have a USB disk that you can plug on the XS, and the XS will automatically read and import the data from it. For debugging, see /var/log/user.log

Standard leases

Follow the general loading procedure above, only listing 'leases.sig' in the directory. Leases are split up per-machine so you can later load a different leases.sig file, which will add to the leases the XS can serve.

Delegated leases

To use delegated leases you first need to use the bios-crypto package to

  1. Create OATS and ACT keys for your deployment, and get them installed on the XOs
  2. Create server keys
  3. Create delegations of the OATS and ACT keys from the OATS and ACT keys to the server, for each XO that will be managed by the XS.

The bios-crypto package includes tools to the keys and delegations described above. To load them on a XS, follow the loading procedure described above.

You can supply the following files:

  • 'server.pri' and 'server.pub': keys for the XS.
  • 'd-lease.sig': lease delegations
  • 'd-oats.sig': OATS delegations

Note that not all the files are needed. The keys files are only needed the first time (and will be rejected subsequent times).

If after the initial load of data, a new USB disk is prepared with new d-leases.sis and d-oats.sig files (plus the updated manifest), the new delegations will be added to the data already in the XS.

Limiting lease length

To set the length of the delegated leases served, create a file /library/xs-activation/leasetimelimit with the number of days the leases should be valid for. Example:

   # 10 day leases
   echo 10 > /library/xs-activation/leasetimelimit 

The maximum value accepted is 300. xs-activation will not serve delegated leases longer than 300 days.

Usage

In normal use, xs-activation does its job transparently and does not require any user intervention.

Monitoring and marking stolen XOs

Moodle offers a status page and tools. The school teacher must use an XO that has registered and has 'coursecreator' privileges in the XS. With that XO, the Moodle interface offers an 'Antitheft' page, under 'Admin -> Users -> Antitheft'.

In that page, a table shows

  • The XOs that have been served leases
  • What account in Moodle they are associated with (if the XO is registered)
  • When the XO last used Moodle, and when it got its last lease.
  • An option to mark the XO as stolen
  • If an XO request a new lease after being marked as stolen, xs-activation will serve a "kill" signal, and this will be noted in the report.

Preparing a 'rescue' lease.sig

In some situations, XOs may be unable to get their activation leases directly from the XS via wireless, and will need a rescue disk. Some of the cases where this is true are

  • XOs where the lease has run out, and cannot connect directly to Access Points (for example: 8.2.x)
  • XOs with faulty wireless
  • In schools with saturated wireless spectrum

The procedure is as follows:

  1. The school teacher must use an XO that has registered and has 'coursecreator' privileges in the XS. With that XO...
  2. Open Browse.xo, visit the 'Local schoolserver' (Moodle)
  3. Go to "Admin -> Users -> Antitheft
  4. Click on the Get a "rescue" leases.sig file option. This will download a file to the Journal.
  5. Switch to the Journal, rename the file from "File leases.sig downloaded from ..." to "leases.sig"
  6. Plug a USB disk, when the USB disk icon appears at the bottom of the screen
  7. Copy the leases.sig file to the disk
  8. Unmount the USB disk

Now the USB disk can be used to recover any of the laptops in that school. Note that the rescue leases is valid for only 2 days.