##(see the SpecSpec for an explanation)

 * '''Launchpad Entry''': UbuntuSpec:foundations-lucid-cryptsetup
 * '''Created''': SteveLangasek
 * '''Contributors''': ScottJamesRemnant 
 * '''Packages affected''': cryptsetup, plymouth, usplash

== Summary ==

To correct race conditions seen in Ubuntu 9.10 between X startup and unlocking of encrypted volumes, the `cryptsetup` package must be integrated with `udev` and `plymouth`.

== Release Note ==

The `cryptsetup` package now integrates with `udev` and `plymouth` to handle prompting for passphrases asynchronously when using whole-disk encryption, solving various problems with boot-time hangs reported in Ubuntu 9.10.  Users who worked around this issue in 9.10 by adding `bootwait` to `/etc/fstab` or `noauto` to `/etc/crypttab` can safely remove these options again.

== Rationale ==

Users who have configured their systems to use encrypted volumes in the past expect these volumes to continue to be usable when upgrading to newer Ubuntu releases.  This has not been the case for Ubuntu 9.10, where late-appearing disks have caused boot-time hangs for users.  This should be addressed for Ubuntu 10.04 LTS, and a best effort made to backport any suitable fixes to 9.10.

== User stories ==

 * Carl has an external USB drive which is encrypted with LUKS, and is configured to be mounted as `/home/carl/data` via `/etc/fstab` and `/etc/crypttab`.  Carl doesn't care if the device is mounted before he logs in, but when it's connected and becomes available, he wants to be automatically prompted for the passphrase to decrypt it.

 * Oliver encrypts his entire `/home` and `/var` partitions using LUKS, each on a different volume.  He wants to be prompted at boot time for the password to decrypt each volume.

== Design ==

 * the existing init script and upstart job should both be replaced by a single upstart job which triggers on the addition of a new block device.
 * the new init script should use plymouth exclusively, to provide an abstraction that guarantees correct VT handling and serialization of prompts

== Implementation ==

=== upstart job for lucid ===
{{{
  start on block-device-added ID_FS_USAGE=crypto
  instance $DEVICE
  task
  script
    grep -q "$DEVICE" /etc/crypttab || { stop; exit 0; }
    exec plymouth ask-for-password --prompt="Please to be telling me secrets for $DEVICE" --command="cryptsetup $DEVICE"
  end script
}}}

 * Needs to exec an external script which checks for the device in crypttab and checks for `noauto` being set, before calling plymouth

=== fixes for karmic ===
 * neuter the init script `start` action
 * implement an upstart job that uses watershed to serialize prompts, since we can't use plymouth
 * release note about the `bootwait` mount option will continue to apply

== Test/Demo Plan ==

It's important that we are able to test new features, and demonstrate them to users.  Use this section to describe a short plan that anybody can follow that demonstrates the feature is working.  This can then be used during testing, and to show off after release. Please add an entry to http://testcases.qa.ubuntu.com/Coverage/NewFeatures for tracking test coverage.

This need not be added or completed until the specification is nearing beta.

----
CategorySpec