All VxSuite applications use the same framework to log user actions, application processes, and errors. The logs are persisted to disk and can be exported by election managers or system administrators.
VxSuite applications use a shared logging library to capture required or otherwise important application log events. The core metadata for each application log event maps roughly to VVSG 2.0 standards, with some additional fields:
- Log Event ID - Internal identifier for each event. The full list of log event IDs with descriptions is included in the automatically generated log documentation.
- Log Event Type - Describes whether the event is a status update or an action, and whether it originated with the user, application, or larger system. The full list of log event types with descriptions is included in the automatically generated log documentation.
- User - If there was an authenticated user role at the time of a user action, describes the role as
system_administrator,election_manager,poll_workerorvendor. If no user was authenticated, thenunknown. If event does not originate from the user but rather automatically from the application or operating system, it will besystem. - Disposition - For actions that can fail or succeed,
successorfailure. Otherwisenafor not applicable. - Source - Indicates where in the system's architecture the log came from, whether it be the frontend renderer, the frontend server, the backend server, a hardware daemon, or the operating system.
- Message - The log message itself, which may not be present if the log event ID sufficiently describes the event.
- Other Metadata - Other metadata can be freely included. For example, if a user adds manual tallies on VxAdmin, the metadata of those manual tallies will be included in the logging.
- Time Written - Timestamp of when the log was created.
The shared logging library formats the log events as JSON and pushes them to application processes' stdout. All stdout output from the application processes - both the application log events and any process output - is sent to the system's logger utility and assigned the tag votingworksapp.
VxSuite uses rsyslog, an advanced implementation of the Syslog protocol, to centralize and manage logs from votingworksapp and other sources. rsyslog has advantages over the built-in Linux syslog implementation of the Syslog protocol, including JSON structured messages, advanced filtering, and increased performance. Using rsyslog, different types of logs are directed to different log files in /var/log/votingworks/:
| Log File | Contents |
|---|---|
vx-logs.log | Key logs required by VVSG 2.0 or otherwise critical for understanding the behavior of the application or device, including:
|
auth.log | All operating system authentication-related events. Note that this will not include voting system authentication events such as logging in with a smart card - these events are in vx-logs.log |
syslog | All other events emitted from the application or the operating system that do not fall into the other log files. |
vx-logs.log is the most important and informative file in most cases. The other files rarely need to be referenced. All logs required by VVSG certification will exist in vx-logs.log.
Because each log file can grow very large, the application will rotate logs if necessary with the logrotate utility on each startup. Previous log files will be compressed and suffixed with a timestamp.
Including the various log files and log rotation, below is an example of the list of log files that might appear on a device:
/var/log/votingworks/vx-logs.log
/var/log/votingworks/vx-logs.log-20241104.gz
/var/log/votingworks/vx-logs.log-20241105.gz
/var/log/votingworks/auth.log
/var/log/votingworks/syslog
/var/log/votingworks/syslog-20241105.gz
{
"timeLogWritten":"2024-11-05T15:51:51.246232-08:00",
"host":"VotingWorks",
"source":"vx-scan-backend",
"eventId":"auth-login",
"eventType":"user-action",
"user":"poll_worker",
"message":"User logged in.",
"disposition":"success",
}The default VotingWorks log format is how logs are formatted when emitted from the application and how they appear in vx-logs.log. It is a direct mapping of the#application-log-events fields.
Logs can be exported in CDF format, in which case the vx-logs.log file is replaced by a vx-logs.cdf.json file with the logging attributes mapped as follows:
| CDF Attribute | |
|---|---|
| ElectionEventLog.GeneratedTime | ISO formatted timestamp of when logs were exported |
| ElectionEventLog.Device | List containing only the current device |
| Device.Type | The CDF
|
| Device.Id | The serial number of the device |
| Device.Version | The software version e.g. "v3.1.2" |
| Device.Event | List of all events |
| Event.Id | A VotingWorks defined identifier for the type of event, such as "save-election-package-complete" |
| Event.Disposition | "success", "failure", "na", or "other" |
| Event.OtherDisposition | If the disposition is "other", the details appear here |
| Event.Sequence | The index of the log in the list of logs, zero-indexed |
| Event.TimeStamp | ISO formatted timestamp of when the event was logged |
| Event.Type | Log event type |
| Event.Description | Log message |
| Event.Details | JSON including the log source and any additional logging metadata |
| Event.UserId | The user at the time of the log |
The log export flow exposed in all VxSuite applications also allows for exporting an errors-only version of the logs. This will only export a log file for logs where the disposition is "failure" and covers all software and hardware errors that have occurred on the machine.
A full list of all logs made in the system with a description of each one can be found here. For convenience a table is provided below mapping Table 15-1 from VVSG 2.0 Requirement 15.1-D to the appropriate logs in the VotingWorks system. The details and descriptions provided in Table 15-1 have been simplified for brevity in this table. Some items have been expanded into multiple rows to more precisely specify linked logs.
| System Event | Detail | Logging Details |
|---|---|---|
| Device generated error and exception messages | Errors can be logged with any LogEventId but are indicated by a Disposition of scanner-state-machine-transition |
|
Critical system status messages |
diagnostic and status messages upon startup | machine-boot-init machine-boot-complete |
| Critical system status messages | "zero totals" check | polls-opened toggled-test-mode |
| Critical system status messages | the initiation or termination of scanner and communications equipment operation | |
| Critical system status messages | Printer errors | paper-handler-state-machine-transition |
| Critical system status messages | Detection or remediation of malware or other malicious software | The system will not boot if malicious software is detected. |
| Critical system status messages | Cryptographic boot validation success/failure | dmverity-boot |
| Non-critical status messages | device-attached scanner-state-machine-transition paper-handler-state-machine-transition |
|
| Events that require election official intervention | device-unattached scanner-state-machine-transition paper-handler-state-machine-transition |
|
| Device shutdown and restarts | machine-shutdown-init machine-shutdown-complete | |
| Changes to system configuration settings | It is not possible to change these configuration settings any attempt to do so will result in a sudo-action log. | |
| Integrity checks for executables, configuration files, data, and logs | election-configured and import-cast-vote-record-complete logs will have failures if there were errors authenticating the files. | |
| The addition and deletion of files | file-saved database-create-complete database-destroy-complete scanner-state-machine-event | |
| System readiness results | diagnostic-init diagnostic-complete |
|
| Removable media events | usb-device-change-detected | |
| Backup and restore | import-cast-vote-records-completeexport-cast-vote-records-complete file-saved |
| System Event | Detail | Logging Details |
|---|---|---|
| Authentication related events | Login/logoff events | sudo-action auth-login auth-logout auth-pin-entry |
| Account lockout events | ||
| Password changes | password-change smart-card-program-complete | |
| Access control related events | sudo-action password-change | |
| User account and role (or groups) management activity | Programming smart cards to create new user accounts: smart-card-program-complete. All other security changes can only be made through configuring a new election-package with those settings: election-configured. Attempts to bypass or make changes to roles or permissions outside of this will not be allowed and result in a sudo-action and/or password-change log. |
| System Event | Logging Details |
|---|---|
| Enabling or disabling networking functionality | It is not possible to enable wired or wireless networking. Any attempt to bypass protections in place blocking this will result in an error and a sudo-action log. |
| System Event | Logging Details |
|---|---|
| Installing, upgrading, patching, or modifying software or firmware | dmverity-boot |
| Changes to configuration settings | sudo-action password-change |
| Abnormal process exits | unknown-error |
| Successful and failed database connection attempts (if a database is uses) | |
| Changes to cryptographic keys | sudo-action |
| System Event | Detail | Logging Details |
|---|---|---|
| Ballot definition and modification | election-configured election-unconfigured | |
| Voting events | Opening and closing polls | polls-opened polls-closed voting-paused voting-resumed reset-polls-to-paused |
| Voting events | Casting a vote | VxMark: vote-cast VxScan: scanner-state-machine-event with the event "scanStart" to indicate the voter has started feeding a ballot. If the voter has to cast from adjudication there will be an "Accept" event. |
| Voting events | Canceling a vote during verification | VxMark: ballot-invalidated VxScan: scanner-state-machine-event with event "Reject" |
| Voting events | Success or failure of log and election results exportation | export-cast-vote-record-complete file-saved |