To install an image on a VotingWorks component, i.e., to image a machine, you need a vx-iso USB drive with one or more VotingWorks application images stored in the "Data" partition. There is also a "Keys" partition that can optionally contain VotingWorks Secure Boot public keys, necessary if a machine hasn't had these keys installed yet.
USB drives used as vx-iso drives must be zeroed out before first use. This step will also ensure the USB drive is empty and no longer contains any previous data prior to use as installation media. You can zero out a drive with the following command, substituting /dev/sdX with the appropriate path to the USB you are using, e.g. /dev/sda
sudo dd if=/dev/zero of=/dev/sdX bs=8M && sudo syncDrives provided by VotingWorks are already initialized with this process and contain the appropriate vx-iso release for installing an application image. You will only need to ensure the appropriate application image(s) are copied to the vx-iso USB drive. If you are creating your own vx-iso USB drive, please contact VotingWorks for assistance.
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:
/media/vx/DataAs the vx user, first verify the USB is mounted at the path above. An easy way to test is with the following command:
ls /media/vx/Data/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:
~root/vxadmin-signed.img.lz4To copy the image to the USB drive, run the following command as the vx user:
sudo cp ~root/vxadmin-signed.img.lz4 /media/vx/Data/ && sudo syncOnce 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 vx-iso USB drives and VotingWorks image files as required.
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 the vx-iso USB drive into the system. If this is a VxMarkScan 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.
By default, VotingWorks systems should boot from the USB. If not, you will need to select the USB drive from a BIOS or Boot Menu. For central system components, you can access the Boot Menu by pressing F9 during the boot sequence. For other components, please reach out to VotingWorks for assistance.
Select "Install Image". You can navigate vx-iso with the keyboard. This option will be auto-selected after 30 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 application image(s) on the vx-iso USB drive will be displayed. Select the number that identifies the correct image. In the event there is only one image, it will be automatically selected.
The imaging process will begin automatically after 10 seconds.
Once imaging completes, remove the USB drive as prompted. The system will then automatically reboot.
After rebooting, the system will perform an automatic encryption of the var filesystem. If Secure Boot was not enabled when the image was installed, you'll see a note about needing to enable Secure Boot. The machine will auto-boot you into the BIOS. Once Secure Boot has been enabled and the system reboots, the encryption process should complete successfully.
The /var partition should encrypt and expand, followed by a reboot. If this is the first time that a VotingWorks application has been installed to a machine, you should find yourself in the Basic Configuration Wizard. Proceed to that section. If the machine has been previously configured with a certified VotingWorks application of the same type, the Basic Configuration Wizard will be skipped.
Note: VotingWorks system software will be installed to the directory path: /vx/code/vxsuite
The underlying storage for /vx/code/vxsuite will depend on the hardware type. By default, NVMe storage is used. In the event an NVMe storage device is not available, an eMMC storage device will be used.
When installing VotingWorks applications that will be used in one or more elections, it is necessary to create a record of the software installation. There are multiple requirements, as described below.
3.1.4-I.1 a unique identifier (such as a serial number) for the record; 3.1.4-I.2 a list of unique identifiers of storage media associated with the record; 3.1.4-I.3 the time, date, and location of the software installation; 3.1.4-I.4 names, affiliations, and signatures of all people present; 3.1.4-I.5 copies of the procedures used to install the software on the programmed devices of the voting system; 3.1.4-I.6 the certification number of the voting system; 3.1.4-I.7 list of the software installed as well as associated digital signatures and mechanisms for installation and verification on programmed devices of the voting system; and 3.1.4-I.8 a unique identifier (such as a serial number) of the vote-capture device or election management system (EMS) which the software is installed.
To satisfy the above requirements, VotingWorks recommends following these best practices related to each requirement.
3.1.4-I.1 - We recommend using the machine ID for this record, e.g. SC-11-004 If necessary, appending the install date and time can further ensure uniqueness, e.g. SC-11-004-20250325-1300
3.1.4-I.2 - This should be the machine ID + the system drive the application was installed to. For example, a machine identified as SC-11-004 with the VotingWorks application installed to the /dev/nvme0n1 drive would use the record: SC-11-004-dev-nvme0n1
3.1.4-I.3 - As described.
3.1.4-I.4 - As described.
3.1.4-I.5 - Include physical copies of the TDP install instructions or a link to the TDP install instructions for this release.
3.1.4-I.6 - This is the EAC Certification Number, which can be found on the Certificate of Conformance for this VotingWorks application release.
3.1.4-I.7 - Include a physical copy of the COTS Report or a link to the COTS Report that can be found in the Hash/Checksum Verification of Dependenciesdocumentation, specific to each VotingWorks application release.
3.1.4-I.8 - We recommend using the serial number of the hardware device the VotingWorks application is being installed to. If that is not available, the same identifier used in 3.1.4-I.1 is recommended.
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: On older 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:
echo HASH | xxd -r -p | base64The system hash can also be computed from outside the application, using a vx-iso USB drive as described under Preparing USB Drives for Imaging. After booting from the drive, simply select the option to "Compute System Hash".
If this is the first time that a VotingWorks application has been installed to a machine, the machine will boot into a basic configuration wizard. If the machine has been previously configured with a certified VotingWorks application of the same type, this wizard will be skipped.
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:
Enter a jurisdiction ({state-2-letter-abbreviation}.{county-town-etc}, e.g., ca.los-angeles or vx.test for test/demo machines):Then, on all machines, you'll see this prompt:
Insert a USB drive into the machine. Press enter once you've done so.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:
Remove the USB drive, take it to VxCertifier, and bring it back to this machine when prompted. Press enter once you've re-inserted the USB drive.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-<machine-id>.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-<machine-id>.pem" file and send the certificate back to you, in the form of a "cert-<machine-id>.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-<machine-id>.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.
Note: If you are installing a VotingWorks application for use in an election, you are required to create a software installation record. The details of this software installation record can be found here: Software Installation Record Creation