How to set up security log email notifications

When to use this

When the security administrator needs to learn about an integrity violation or an account lockout by email, without opening the log. The critical event indicator in the header is visible only to someone currently in the interface. An email arrives regardless.

Notifications are configured in two places. The mail server is set in the vStack Center dispatcher environment file on the management VM. Enabling, recipients, and the severity threshold are set in the log interface. Without the server, the interface form saves without errors, but no emails go out. This is the most common reason for "we set it up and nothing arrives".

Prerequisites

• an SMTP server that accepts mail from the management VM without authentication. The dispatcher has no settings for login, password, or encryption mode;
• SSH access to the management VM as root;
• the Cluster master role to save the notification settings. Security Admin can view the settings but cannot save them;
• vStack Center 3.0.3 or later.

Steps

Step 1. Set the mail server on the management VM

Add the parameters to the dispatcher environment file /usr/local/etc/vstack_center_dispatcher.env:

SMTP_HOST=192.0.2.25
SMTP_PORT=25
SMTP_SEND_FROM=vstack-security@example.com
SMTP_TIMEOUT=15000

Parameter	Value
SMTP_HOST	SMTP server address. An empty value or a missing line disables sending
SMTP_PORT	Port, 25 by default
SMTP_SEND_FROM	Sender address. Without it, emails are sent from no-reply@vstack.com, and your organization's mail server may reject mail from a foreign domain
SMTP_TIMEOUT	Connection timeout in milliseconds, 15000 by default

Outbound connections from the management VM are not restricted by default. If you have restricted them, open the SMTP server port.

Step 2. Restart the dispatcher and check the log

service vstack_center_dispatcher restart

The dispatcher reads the parameters only at startup. In the log under /var/log/vstack-center-dispatcher/, find one of these lines:

Line	Meaning
SMTP initialized: host=…, port=…	The mail transport is created; go on to the interface
SMTP_HOST not set — email notifications disabled	The dispatcher did not read the parameter: check the file name and the SMTP_HOST line

SMTP initialized does not mean the server is reachable. The dispatcher connects to it only when sending an email.

Step 3. Enable notifications in the log

1. Open Sites → the cluster → Security Event Log.
2. Click Actions above the table and select Notification settings.
3. Turn on Enable email notifications.
4. In Recipients, type an address and press Enter. The address is added to the list below the field. Add several addresses the same way; remove one with the cross.
5. In Minimum severity for email, select the threshold.
6. Click Save. The message "Notification settings updated" appears.

A settings change is written to the log as config.security_settings_changed. Editing the environment file in step 1 bypasses the API and is not logged.

Step 4. Choose the severity threshold

An email is sent for an event whose severity is at or above the threshold. The default threshold is alert. The event type dictionary has no emergency events, so with alert emails arrive only for five integrity violations.

Threshold	Emails arrive for
alert (default)	integrity.file_violation, integrity.config_violation, integrity.vm_config_violation, integrity.manifest_invalid, integrity.log_chain_broken
critical	all of the above, plus auth.account_locked, system.disk_space_exhausted, os.kernel_panic, and other critical events
error and lower	all of the above, plus unclean shutdowns of the node and the virtualization service (os.shutdown_unclean, system.service_stopped_unclean) and other events of the selected level

The critical event indicator counts the top three levels. To get emails for the same events that light up the indicator, set the threshold to critical. With the default threshold, an account lockout and exhausted disk space show up in the interface but generate no email.

An image checksum mismatch on import (integrity.image_sha256_mismatch) has warning severity, even though it belongs to the integrity category. It produces an email only with a threshold of warning or lower.

A threshold below error produces a stream of emails about routine events: a failed login is warning, a successful one is info.

What the email contains

The subject is [vStack Security] <event name> — <severity code>, for example [vStack Security] Блокировка учётной записи — critical. The event name comes from the event type dictionary and is always in Russian.

The body is plain text, also in Russian:

Событие безопасности
Наименование: Блокировка учётной записи
Уровень: Критическое состояние (critical)
Дата/время: 2026-10-09T08:15:42.118305+00:00
Субъект: operator (uid=17)
Объект: user/17 (operator)
Результат: success
IP: 198.51.100.40

The lines are: event name, severity, date and time, subject (user name and ID), object (type, ID, name), result, and source IP address. A missing field is replaced with a dash. Each recipient gets a separate email.

Keep three things in mind when reading an email:

• the time in the email is when the email was generated, in UTC, not the time of the log record. The difference is usually a fraction of a second, but you cannot match records to the millisecond by it;
• the email has no record number or event UUID. Find the record in the log by filtering on event type and time — see How to read the log and filter events;
• the email is sent after the record is saved. If the record is rolled back, there is no email. A slow or unreachable server does not delay the log record.

Verify the result

There is no test email button, so check delivery on a real event. An account lockout is the easiest:

1. Set the threshold to critical.
2. Create a test account and use up its failed login attempt limit. The log gets auth.account_locked.
3. The dispatcher log shows email notify: sent to <address> or email notify: failed to send to <address> with the reason, one line per recipient.
4. Check the recipient's mailbox.
5. Unlock or delete the test account, and restore the threshold if you need a different one.

sent to means the SMTP server accepted the email, not that it reached the mailbox. If the log says sent to and there is no email, look in spam and in the mail server log.

Troubleshooting

Settings are saved, but no emails arrive. Find the entry for the latest dispatcher start in its log. If it says SMTP_HOST not set — email notifications disabled or there is no SMTP initialized line, the mail server is not set. In that case events above the threshold produce email notify: SMTP not available in the log. Go through steps 1 and 2.

No emails, and nothing in the log for the event. The event is below the threshold, notifications are off, or the recipient list is empty. In these cases the dispatcher skips the email silently. Check the Notification settings form and the event severity in the record card.

The log says failed to send to <address>. The SMTP server is unreachable or rejected the email. The reason is on the same line. Common ones: the server requires authentication or TLS, the sender is from a foreign domain (set SMTP_SEND_FROM), the port is closed. There is no retry: the email for that event is lost, the log record stays.

Emails stopped after a vStack Center upgrade. The dispatcher environment file is regenerated on every management VM configuration deployment, including upgrades, and the SMTP_* lines disappear. After every upgrade, check for the SMTP initialized line in the log and repeat steps 1 and 2 if needed.

Settings are not saved (-24007). A recipient address has a typo, or Enter was not pressed and the address is not in the list.

There is no Notification settings item in the Actions menu. The role lacks the View Security Notify Settings privilege. Only Cluster master can save the settings.

Limitations

• The dispatcher does not support SMTP login, password, or TLS. If your mail server requires authentication, you need an intermediate relay that accepts mail from the management VM without it.
• There is no retry. A delivery failure is visible only in the dispatcher log; it does not appear in the security log or the interface.
• The mail server is set only in the environment file. It cannot be configured through the interface or the API, and an upgrade erases it.

API methods

Operations on this page in the API: security-event-notify-settings-get, security-event-notify-settings-set — see the API reference.

See also

• Security log — severity levels and critical events.
• How to read the log and filter events — the critical event indicator and the read mark.