aboutsummaryrefslogtreecommitdiff
path: root/docs/tpc.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tpc.md')
-rw-r--r--docs/tpc.md85
1 files changed, 43 insertions, 42 deletions
diff --git a/docs/tpc.md b/docs/tpc.md
index d3e7e06..c2a6954 100644
--- a/docs/tpc.md
+++ b/docs/tpc.md
@@ -6,7 +6,10 @@ The Hydra Suite was made with the [Trusted Personal Computer (TPC)][]
This guide documents the lifecycle of a TPC storage device, or a "TPS
Cartridge":
- Cartridge = TPS = Trusted Personal Storage (like and SSD, microSD or M.2)
+ Cartridge = TPS = Trusted Personal Storage
+
+A TPS can usually be whatever removable block device like an SSD, microSD, M.2
+etc.
The idea is that a number of TPCs can have interchangeable cartridges, as long
as each cartridge has an unique name.
@@ -19,12 +22,12 @@ as each cartridge has an unique name.
Start by running the following commands in your terminal, adjusting to your
case:
- export HYDRA="nome-da-hydra"
- export VOLNAME="nome-do-disco"
- export DOMAIN="dominio.example.org"
+ export HYDRA="hydra-name"
+ export DISK="disk-name"
export DEVICE="/dev/sdb"
- export USER=`whoami`
- export DEST=/media/$VOLNAME
+ export DOMAIN="`facter domain`"
+ export USER="`whoami`"
+ export DEST="/media/$DISK"
export CONFIG_FOLDER="`hydra $HYDRA folder`"
if [ "$USER" != "root" ]; then
@@ -46,52 +49,52 @@ procedures from this document can be done from another TPC.
If non-existing, create entries and keys:
- hydra $HYDRA newnode $VOLNAME tpc
+ hydra $HYDRA newnode $DISK tpc
Customize:
- vim $CONFIG_FOLDER/config/provision/$VOLNAME.conf
- vim $CONFIG_FOLDER/puppet/config/node/$VOLNAME.$DOMAIN.yaml
- vim $CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN.yaml
+ vim $CONFIG_FOLDER/config/provision/$DISK.conf
+ vim $CONFIG_FOLDER/puppet/config/node/$DISK.$DOMAIN.yaml
+ vim $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml
### Secrets
Proceed adding other passwords and secrets at
-`$CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN`, make sure to
+`$CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN`, make sure to
encode them with [hiera-yaml][]:
- hydra $HYDRA eyaml $VOLNAME encrypt -q -o block -p -l some::password
+ hydra $HYDRA eyaml $DISK encrypt -q -o block -p -l some::password
If you already have the secret somewhere, you can use a construction like this
which already adds the eyaml block into the hiera config file:
keyringer $HYDA decrypt /path/to/some/secret | \
tr -d '\n' | \
- hydra $HYDRA eyaml $VOLNAME encrypt -q -o block --stdin -l some::password >> \
- $CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN.yaml
+ hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::password >> \
+ $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml
You can also ensure a fresh random passphrase is used, using your favourite
generator like this:
head -c ${1:-20} /dev/urandom | base64 | \
tr -d '\n' | \
- hydra $HYDRA eyaml $VOLNAME encrypt -q -o block --stdin -l some::random:password >> \
- $CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN.yaml
+ hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
+ $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml
For `passwd(5)` and `shadow(5)` hashed passphrases, use something like this:
mkpasswd -m sha-512 | \
tr -d '\n' | \
- hydra $HYDRA eyaml $VOLNAME encrypt -q -o block --stdin -l some::random:password >> \
- $CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN.yaml
+ hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
+ $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml
Or this, for a random passphrase:
head -c ${1:-20} /dev/urandom | base64 | \
mkpasswd -m sha-512 --stdin | \
tr -d '\n' | \
- hydra $HYDRA eyaml $VOLNAME encrypt -q -o block --stdin -l some::random:password >> \
- $CONFIG_FOLDER/puppet/config/secrets/node/$VOLNAME.$DOMAIN.yaml
+ hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
+ $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml
[hiera-yaml]: https://github.com/voxpupuli/hiera-eyaml
@@ -100,7 +103,7 @@ Or this, for a random passphrase:
The proceed with the system installation, which should create all volumes in
the TPS and setup the base Operating System:
- hydra $HYDRA provision $VOLNAME
+ hydra $HYDRA provision $DISK
### Metadata
@@ -112,23 +115,23 @@ can be useful during recovery procedures.
1. Write down UUIDS, models and serials from the new disk. Examples:
- lsblk $DEVICE -n -o +UUID | keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/lsblk
- udevadm info --query=all --name=$DEVICE | keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/udevadm
+ lsblk $DEVICE -n -o +UUID | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/lsblk
+ udevadm info --query=all --name=$DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/udevadm
# For non-USB and non-microSD disks only
- $SUDO hdparm -I $DEVICE | keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/hdparm
- $SUDO smartctl -i $DEVICE | keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/smartctl
+ $SUDO hdparm -I $DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/hdparm
+ $SUDO smartctl -i $DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/smartctl
2. Save partition tables, the LUKS header and other relevant information:
- $SUDO LC_ALL=C sfdisk -d $DEVICE | keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/sfdisk
+ $SUDO LC_ALL=C sfdisk -d $DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/sfdisk
- $SUDO cryptsetup luksDump /dev/mapper/$VOLNAME-root | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-root
- $SUDO cryptsetup luksDump /dev/mapper/$VOLNAME-swap | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-swap
+ $SUDO cryptsetup luksDump /dev/mapper/$DISK-root | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-root
+ $SUDO cryptsetup luksDump /dev/mapper/$DISK-swap | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-swap
- $SUDO cryptsetup luksHeaderBackup /dev/mapper/$VOLNAME-root --header-backup-file luksHeaderBackup-root
+ $SUDO cryptsetup luksHeaderBackup /dev/mapper/$DISK-root --header-backup-file luksHeaderBackup-root
$SUDO chown $(whoami) luksHeaderBackup-root
- keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/luksHeaderBackup-root luksHeaderBackup-root
+ keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/luksHeaderBackup-root luksHeaderBackup-root
chmod +w luksHeaderBackup-root
wipe luksHeaderBackup-root
@@ -137,15 +140,15 @@ can be useful during recovery procedures.
* Optionally, configure ATA passphrases for the new disk. If so, make sure to
save the passphrase in the keyring:
- keyringer $HYDRA encrypt nodes/$VOLNAME.$DOMAIN/ata
+ keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/ata
## Mounting
Use the following whenever you need to mount the cartridge in another system:
- hydractl mount-media $VOLNAME
+ hydractl mount-media $DISK
-This will make the volume available at `/media/$VOLNAME`.
+This will make the volume available at `/media/$DISK`.
## Initial user
@@ -161,7 +164,7 @@ home folder encrypted, backup your data and then proceed running
### Syncing the user and encrypted home in the new cartridge
-Then, with the new TPS cartridge mounted (`hydractl mount-media $VOLNAME`), do
+Then, with the new TPS cartridge mounted (`hydractl mount-media $DISK`), do
the following to replicate your user and homedir there:
$SUDO chroot $DEST adduser $USER
@@ -183,7 +186,7 @@ and is logged in there as `root`.
From another system, and with the cartridge mounted:
- hydractl sync-tpc $VOLNAME
+ hydractl sync-tpc $DISK
This might involve a lot of data being transmitted. If you want `sync-tpc` to
ignore all your QEMU virtual machine images hosted at `/var/cache/quemu`, setup
@@ -201,7 +204,7 @@ Now that basic provisioning is completed, you can unmount the cartridge.
From another system, and with the cartridge mounted:
- hydractl umount-media $VOLNAME
+ hydractl umount-media $DISK
## Booting
@@ -209,20 +212,18 @@ The current provisioning procedure (as of 2024-02) may yield into
a partially bootable system, and may need some additional manual
steps right after installation:
- hydractl mount-media $VOLNAME
+ hydractl mount-media $DISK
sudo chroot $DEST
update-initramfs -v -u
- hydractl umount-media $VOLNAME
+ hydractl umount-media $DISK
During boot, at the `(initramfs)` prompt, type this to successfully
unlock the encrypted volumes:
- cryptsetup luksOpen /dev/mapper/volumename-root root
- cryptsetup luksOpen /dev/mapper/volumename-swap swap
+ cryptsetup luksOpen /dev/mapper/${DISK}-root root
+ cryptsetup luksOpen /dev/mapper/${DISK}-swap swap
^Ctrl-D
-Where `volumename` is `$VOLNAME`.
-
Then, in the running system, do:
sudo update-initramfs -v -u
generated by cgit v1.2.3 (git 2.39.1) at 2024-09-13 11:01:51 +0000