First make sure that you've prepared USB drives for imaging, following the instructions under Preparing USB Drives for Imaging. Then follow these steps:
Power off the machine.
Insert both the vx-iso and image USB drives into the system. If this is a VxMark or a VxScan, connect a keyboard as well. If there aren't enough ports available, use a USB hub as provided by VotingWorks.
Power on the machine to begin booting vx-iso.
The precinct system components (VxMark and VxScan) are to auto-boot from a bootable USB drive when connected and should auto-boot to vx-iso.
The central system components (VxAdmin and VxCentralScan) require entering f9 after powering on to boot to USB. Select the USB drive corresponding to the vx-iso drive.
Select "Write an image". You can navigate vx-iso with the keyboard. This option will be auto-selected in 10 seconds.
If the machine already has Secure Boot keys installed, it should not prompt you to install keys. If it does for some reason, you should reach out to VotingWorks for assistance. Only if you know the keys need to be installed should you opt to install them.
The images on the image USB drive will be displayed. Select the number that identifies the correct image.
Enter 27 for the final expected size of the image in GB.
Confirm your selections and wait for imaging to complete.
Once imaging completes, remove the USB drives and press "Enter" to reboot.
On reboot, you should see a prompt for a passphrase. This passphrase is used to decrypt the machine's /var partition so that it can be re-encrypted via the TPM. Enter "insecure" — this passphrase is not relevant to our security architecture. If Secure Boot is not enabled, you'll instead see a note about needing to enable Secure Boot. The machine will auto-boot you into the BIOS. On reboot after that, you should see the passphrase prompt.
The /var partition should encrypt and expand, and you should then find yourself in Basic Configuration Wizard. Proceed to that section.
On VxMark, if you find yourself on an unexpected screen after the above steps, e.g., a Secure Boot error screen or booting straight into a previously installed image, you may need to manually edit the VxMark boot order. You can follow these instructions to do so:
Power off the machine.
Insert the vx-iso USB drive.
Power on the machine and auto-boot to vx-iso.
Use "Ctrl+C" to leave the main vx-iso interface and access a terminal.
Type efibootmgr to list out the boot entries. The output will look something like this:
Identify the boot entry for the recently installed image. Let's say in this case we want vxadmin-signed, Boot0002.
Run the following command, replacing the index, to make that entry the first in the boot order after the USB drive:
Once a machine has been imaged with a signed image, you can verify the system hash against the hash of what was built and signed during the Trusted Build process. To perform this verification, VotingWorks provides Signed Hash Validation.
See Signed Hash Validation for details.
Note: In some releases (v4.0.1 and earlier), the Secure Boot signing process only output a SHA256 hash value. That hash value needs to be converted to a base64 encoded value to match what is provided by Signed Hash Validation. That can be accomplished with the following command:
To install an image on a VotingWorks component, i.e., to image a machine, you need two USB drives:
A vx-iso USB drive — vx-iso is our VotingWorks-specific ISO installer program.
An image USB drive — This is an empty USB drive with two partitions, a "Data" partition that can contain as many VotingWorks images as space allows and a "Keys" partition that can optionally contain the VotingWorks Secure Boot public keys, necessary if a machine hasn't had these keys installed yet.
Note: If you have existing drives that are properly partitioned, you can skip these steps and simply copy a VotingWorks image file directly to the USB. Those instructions can be found at the bottom of this page in the Copying an image file to a previously configured USB drive section.
Clone the vx-iso repo for the tooling necessary to prepare the above:
Follow these instructions to create a vx-iso and/or image USB drive.
If this is SLI, we have provided you with vx-iso USB drives so that you don't need to prepare them from scratch.
You'll need access to the relevant images and optionally the VotingWorks Secure Boot public keys. Both of these are stored on a private S3 bucket, though they're not sensitive, and VotingWorks can prepare temporary links to grant access to them.
If this is SLI, you do not need to create data drives with the VotingWorks Secure Boot public keys. Secure Boot has already been configured on all your machines.
For this example, we will assume that you have a signed vxadmin image on the build machine. It will be located in the root user's home directory and be named vxadmin-signed.img.lz4
We will also assume the USB drive is automatically mounted by the vx user, with the Data partition located at:
As the vx user, first verify the USB is mounted at the path above. An easy way to test is with the following command:
That command should return without an error. It may list one or more images if they were already on the USB drive. That's ok. (You can delete any existing images from the USB drive if you like, but it is not necessary.)
Since the signed image file is located in the root user's home directory by default, we'll use that path. As mentioned earlier, we will use a vxadmin image for this example. That path would be:
To copy the image to the USB drive, run the following command as the vx user:
Once the copy and sync completes, you can eject the USB drive and remove it. It is now ready to image a machine. Repeat this process with any other USB drives and VotingWorks image files as required.
After you've imaged a machine, the machine will boot into a basic configuration wizard. The majority of the steps are self-explanatory, but "Step 1: Set Machine ID" and "Step 4: Create Machine Cert" require some extra clarification.
It is important that the machine ID be unique for each machine. Many machines have a physical placard on them indicating the machine ID. That is the ID that should be used here.
On VxAdmin, you'll first see a prompt to enter a jurisdiction:
SLI should use co.sli
Then, on all machines, you'll see this prompt:
Insert a USB drive that you designate for this purpose. From here on out, we'll refer to this USB drive as the VxCertifier USB drive.
After selecting the VxCertifier USB drive, a certificate signing request will be written to it. You'll then be prompted to:
Because you'll be certifying your machine at your own facility as opposed to a VotingWorks facility, you won't be able to take the USB drive to VxCertifier, our VotingWorks certification terminal. We'll need to use a remote certification process instead.
You'll need to remove the VxCertifier USB drive, find the "csr.pem" file inside the "certs/" directory on it, and share that file with VotingWorks. This file does not contain any private information so can be shared over the internet, e.g., via email. VotingWorks will prepare a certificate given this "csr.pem" file and send the certificate back to you, in the form of a "cert.pem" file. This file, too, does not contain any private information so can be shared over the internet. You'll need to copy this "cert.pem" file back onto the VxCertifier USB drive, placing it in the same "certs/" directory that we pulled the "csr.pem" from. Re-inserting the USB drive into the machine and pressing enter should allow you to proceed successfully.
On VxAdmin, you'll be prompted to program your first system administrator card as a last step. Remember to record the displayed PIN. On other machines, no steps remain. You'll reboot into the app after this.
This section walks through the steps to install a Trusted Build image on a VotingWorks component using vx-iso.