Security log
Problem and purpose
The security log is a separate stream of records about who signed in to the cluster, who changed roles and settings, and what happened to virtual machines. It resides in its own table in the vStack Center database, separately from component diagnostic logs, and opens on a dedicated screen — Security Event Log.
Its requirements differ from those of a diagnostic log. A security log record must not be replaced or removed without detection: incident investigations and regulatory audits rely on it. Each record therefore carries a SHA-256 hash that links it to the others, and the cluster can traverse the entire chain and report where it is broken.
This raises questions that administrators need answered. Which events require action, and which are background activity? What does the "chain broken" status mean? Where does the log go when the table grows, and how does an archive differ from an export?
This page explains the model. For reading and filtering events, see How to read the log and filter events; for exporting the log, downloading an archive, and starting an integrity check, see How to export the log, download an archive, and verify integrity.
Model and entities
Event record
A record is a flat set of fields. It has three parts: what happened and when, who the actor was, and which object was affected.
| Field | What it shows |
|---|---|
id | numeric record ID; used for sorting and addressing |
event_uuid | event UUID |
ts | event time, a Unix timestamp in seconds |
event_type | event type code, such as auth.login.success |
user_id | ID of the user who performed the action |
username | name of the user who performed the action |
object_type | type of the object on which the action was performed |
object_id | object ID |
object_name | object name |
result | result: success or failure |
details | additional information |
remote_ip | client address |
request_id | UUID of the cluster request that generated the record |
record_hash | SHA-256 record hash — a link in the chain |
acknowledged | the current user's mark indicating that the event has been read |
Actor and object fields are empty when the event has none: signing in to the
cluster has no object, and a system event has no user. The request_id field
links the event to the cluster request that generated it — a useful starting
point for an investigation when one action produced several records.
These same fields become file columns when the log is exported to CSV or JSON. The on-screen table shows only some of them; the rest appear in the individual record's card.
Type catalog
An event type is a string code with dots: auth.login.success,
auth.login.failure. The cluster maintains the list of types: each code has a
category, a severity level, and a human-readable name. This catalog supplies the
event type filter and table labels, so the cluster version determines the set
of types, rather than the client.
Events from the nodes themselves
Before 3.0.5, the log captured only events in the management plane. In 3.0.5, node operating system events and virtualization software events were added — they arrive from node agents and enter the same hash chain.
| Event type | What the record describes | Category | Severity |
|---|---|---|---|
os.ssh_login_success | successful SSH sign-in on a node | auth | info |
os.ssh_login_failure | failed SSH sign-in on a node | auth | warning |
os.user_local_created | creation of a local account on a node | auth | notice |
os.user_local_deleted | deletion of a local account on a node | auth | notice |
os.sysctl_changed | change to a node kernel parameter (sysctl) | config | warning |
os.boot | node startup | system | notice |
os.shutdown | normal node shutdown | system | notice |
os.shutdown_unclean | abnormal node shutdown | system | error |
os.kernel_panic | node kernel panic | system | critical |
system.service_stopped_unclean | abnormal termination of the virtualization software: process termination, a crash, or a power failure on the management machine | system | error |
vm.console_connected | connection to a VM console over WSS | vm | info |
vm.console_connect_failed | failed connection to a VM console | vm | warning |
Of these events, only os.kernel_panic contributes to the critical event count:
its severity is critical, and the counter counts the top three levels.
Abnormal shutdowns of both a node and the virtualization software have severity
error: they do not contribute to the counter, but do trigger email
notifications when the threshold is error or lower.
The os.shutdown_unclean and system.service_stopped_unclean records appear
at the next startup, rather than at the time of the failure: until then, nothing
can report it. On a clean installation, the first startup does not create a
false record.
Categories and severity
A category groups types by area. Records and exports use a short code, while the filter panel shows the interface label — three of the six differ:
| Code in the record | Label in the filter panel | Area |
|---|---|---|
auth | authentication | authentication and access management |
vm | virtual machines | virtual machines |
config | configuration | infrastructure configuration |
role | role | role management |
system | system | system events |
integrity | integrity | integrity monitoring |
Severity has seven levels, from highest to lowest: emergency,
alert, critical, error, warning, notice, info. The cluster considers
the top three levels — emergency, alert, critical — critical. These are
the levels used for the unread counter and email notification settings.
How it works
Hash chain
Each record stores its own SHA-256 hash in the record_hash field, linking it
to neighboring log records. Removing or replacing a record in the middle breaks
the link: the hashes of subsequent records no longer match, and verification
reports the ID of the record where the chain broke.
This design gives the log its main property: it is append-only. The log can be read, marked as read, exported, and archived — individual records cannot be edited or deleted. Archiving is the only way to reduce the table's size.
Integrity verification
Chain verification runs in the background. At startup, the cluster immediately distributes the work: it splits the log into equal parts and assigns them to workers that process their parts concurrently. While verification is running, the start button shows the completion percentage; when it finishes, a report appears beside it with the time, result, and number of records checked.
The result is one of five statuses. The cluster maintains the set of statuses and their labels.
| Status | Meaning |
|---|---|
| Never Started | no verification has been started in the cluster yet |
| Running | verification is running; the report shows the completion percentage |
| Completed | verification finished; the chain is intact |
| Failed | verification did not finish |
| Chain Broken | the chain is broken; the report shows the ID of the record where it broke |
Individual workers have their own statuses: Running, Completed, Failed, Chain Broken, Stopped, Pending. These help investigate a verification that has stalled: they show whether one worker or all workers failed.
Only one verification runs in the cluster at a time. Until it finishes, another start request is rejected.
Critical events and responses
The read mark is personal. It answers "has the current user reviewed this event?" rather than "has the team investigated it?": two administrators see different values for the same event.
Two mechanisms rely on this mark. The header indicator shows the current user's number of unread critical events, and the rows for these events are highlighted in the log table. Marking events as read clears both — either for selected events or for all unread critical events at once. Marking the same event again does not cause an error.
The third mechanism is email. The cluster sends notifications to a list of
addresses, with a severity threshold: events below the threshold do not generate
emails. The default threshold is alert, which covers only integrity
violations. Emails are sent by the vStack Center dispatcher through an SMTP
server set on the management VM. Without it, notifications do not work even
when enabled in the interface. Setup is described in
How to set up security log email notifications.
Table growth and archiving
The log is append-only, so its table grows, and that growth must be limited. Autoarchiving moves old records into a compressed CSV file when the table exceeds the size threshold.
| Setting | What it controls | Limits |
|---|---|---|
security_log_archive_enabled | whether autoarchiving is enabled | — |
security_log_archive_target_size | log table size threshold, in bytes | from 10 MB to 16 GB |
security_log_archive_path | archive storage directory | name length 1–256 |
security_log_disk_alert_threshold | free space threshold below which the cluster issues a warning, in bytes | at least 100 MB |
A toggle above the log table enables and disables autoarchiving. The other three settings are in the archive settings form; both sizes in that form are specified in megabytes.
An archive is a .csv.gz file with a name such as
security_log_a3f1b2c4_03_01_2025.csv.gz. For a completed archive, the list shows
the period, size, record count, archiving time, and SHA-256 checksum. An archive
still being created also appears in the list, but without these fields — it is
too early to download it.
An archive and an export serve different purposes. An export is a one-time selection based on filters: the file is created in a temporary directory on the management node, sent to the browser, and deleted. An archive permanently stores records removed from the table: the file resides in the archive directory and remains there after download.
Who can see what
The security log is a cluster-level object. It is available to two global
roles: Cluster master (role 1) and Security Admin (role 6). VDC
roles cannot see the log: its events span the entire cluster.
Access is granted by privileges, rather than by role number, so check the privilege.
| id | Name in the role card | Granted to | What it permits |
|---|---|---|---|
| 10000 | View Security Log | Cluster master, Security Admin | reading events, the type catalog, the critical event count, and verification status |
| 10001 | Export Security Log | Cluster master, Security Admin | exporting events to CSV and JSON |
| 10002 | Verify Security Log | Cluster master, Security Admin | starting hash chain verification |
| 10003 | View Security Archive | Cluster master, Security Admin | listing archives |
| 10004 | Export Security Archive | Cluster master, Security Admin | downloading an archive |
| 10005 | View Security Archive Settings | Cluster master, Security Admin | reading archive settings |
| 10006 | Edit Security Archive Settings | Cluster master only | editing archive settings |
| 10007 | Acknowledge Security Event | Cluster master, Security Admin | marking an event as read |
| 10008 | View Security Notify Settings | Cluster master, Security Admin | reading email settings |
| 10009 | Edit Security Notify Settings | Cluster master only | editing email settings |
There are also two security settings privileges: View Security Settings
(9000) and Edit Security Settings (9001). In addition to editing, the latter
permits reading lockout settings — see
Sessions and sign-in settings.
The distinction between reading and editing has practical consequences. Security Admin can see the log, archives, and both groups of settings, but only Cluster master can change archive thresholds and the email recipient list. The privilege and scope model is described in the roles and privileges reference.
Limitations
An export is limited to 100 000 records. A single export cannot return more: the file is created on the management node's disk, and the limit applies to the size of this operation. Workaround — narrow the selection with filters and a time range, or retrieve the log in parts; historical records are stored in archives.
Exports are not stored in the cluster. The file is created in a temporary directory, sent to the browser, and deleted. Workaround — use an archive for long-term storage rather than an export; to obtain the same selection again, repeat the export.
Only one chain verification runs at a time. A second start request is rejected until the first verification finishes. Workaround — wait for the current verification: its progress appears as a percentage on the button, and the ID of the record where the chain broke appears in the last verification report.
An incomplete archive cannot be downloaded. A file still being created appears in the list, but requests to download it are rejected. Workaround — wait until the entry shows a checksum, a record count, and an archiving time.
The read mark is personal. It cannot be used to assess a shift's work: it reflects only the current user. The workaround is an agreed process rather than a technical solution: track whether an event has been investigated through an external process, and use the mark as a personal filter.
API methods
API operations covered on this page: security-event-list, security-event-get,
security-event-types, security-event-critical-count,
security-event-acknowledge, security-event-notify-settings-get,
security-event-notify-settings-set, security-event-export,
security-event-archive-list, security-event-archive-export,
security-event-archive-settings-get, security-event-archive-settings-set,
security-event-log-verify, security-event-log-status,
security-verification-statuses — see the
API reference.
Further reading
- How to read the log and filter events — the log screen, list filters, an individual record, and the read mark.
- How to export the log, download an archive, and verify integrity — exporting to CSV and JSON, archives, archive settings, and starting chain verification.
- How to set up security log email notifications — the SMTP server, recipients, severity threshold, and email contents.
- Roles and privileges — how access is determined by privilege and scope.
- The downloaded security log archive cannot be opened —
troubleshooting a corrupted
.csv.gzfile.