Skip to content

Latest commit

 

History

History
111 lines (76 loc) · 5.93 KB

INSTALL.md

File metadata and controls

111 lines (76 loc) · 5.93 KB
Raw

This file explains getting VxSuite up and running in Debian 11.2, along with setting up security features like Secure Boot, dm-verity, and TPM2-TOTP.

Preseed Installer

This repo provides a preseed file that can be used for an automated install of Debian that installs the software and partitions the disks in the manner necessary to create a production machine. In future we will also provide a development machine preseed, but for now we just provide a production one. To use the production preseed file to configure a machine, navigate to the automated install option in GRUB after booting the Debian iso: Screenshot_VxMarkProdBase_2022-03-21_21:10:57 Screenshot_VxMarkProdBase_2022-03-21_21:11:07

Then, type the URL for the preseed file into the box provided by the installer. The URL is

https://raw.githubusercontent.com/votingworks/vxsuite-complete-system/main/production-preseed.cfg

Screenshot_VxMarkProdBase_2022-03-23_13:13:34

Clicking "Continue" should result in a full install of the system, which automatically reboots into a login prompt. The login credentials are

login: vx
password: insecure

NOTE: These credentials are deleted as part of the production setup process and are not usable on deployed machines.

From there, clone this git repo and proceed with a normal installation.

Manual Installer

The manual install process can follow the usual path of the Debian installer. The only modification that needs to be made is as follows:

Set the machine's hostname to be "Vx": image

On the disk partitioning screen, select “Setup LVM”

image

Select the disk in question: image

Use separate partitions for /home, /var, and /tmp image

Make the changes: image

Use the whole disk for LVM: image

IMPORTANT: do not persist these changes, we're not done yet! image

On this screen, scroll to the top and click "Configure LVM": image image

Now it's okay to write the changes to disk: image

Start by deleting the swap partition: image image

Now add a hashes partition in its place: image image image image

Now we're done! image image

Note: there may be a screen asking if we want to install with a UEFI-based bootloader. Say yes. Afterwards, continue through the rest of the install as normal.

First boot

Since Debian does not have the same packages as Ubuntu (i.e. no PPAs), some modifications are needed from the usual VxSuite build process. First, you’ll have to add your user to the sudoers group using `usermod -a -G sudo ${USER}` 
sudo apt install git build-essential rsync cups cryptsetup efitools
usermod -a -G lpadmin $USER

Add export PATH=$PATH:/sbin/ to your .bashrc

reboot

Setting up VxSuite

Now we're ready to setup VxSuite. After rebooting into the OS,

git clone [email protected]:votingworks/vxsuite-complete-system
cd vxsuite-complete-system
make node
make checkout
make build
./setup-machine.sh

After this point, the machine will be locked down, and should automatically reboot. After reboot, ensure that your secure boot keys are on a USB drive connected to the machine and go into the vendor screen (TTY2). Select the lockdown option: image

This should setup everything for you, except TPM2-TOTP, and reboot the machine. On reboot, make sure you go back into the firmware interface and turn on Secure Boot. If that works, it should boot into the new dm-verity-backed lockdown. On the tty2, you should now see image

And if you ^C you should see the following when running lsblk: image