mail

Disabled by default; see https://mnestor.github.io/ssoossh/operations/email-notifications/. Disabled is the default. A server that has never been told about a relay should not try to reach one, and notifications are an addition to the certificate flows rather than a part of them — every path that emits one works identically when this is off.

Key	Type	Default
mail.enabled	bool	false
mail.from	string	empty
mail.reply_to	string	empty
mail.subject_prefix	string	empty
mail.template_dir	string	empty
mail.expiry_reminder_lead	duration	168h
mail.expired_attempt_window	duration	24h
mail.rotation_quiet_period	duration	168h
mail.smtp.host	string	localhost
mail.smtp.port	int	25
mail.smtp.tls	string	opportunistic
mail.smtp.server_name	string	empty
mail.smtp.ca_file	string	empty
mail.smtp.insecure_skip_verify	bool	false
mail.smtp.auth	string	none
mail.smtp.username	string	empty
mail.smtp.password	string	empty
mail.smtp.password_file	string	empty
mail.smtp.helo	string	empty
mail.smtp.timeout	duration	15s
mail.logging.*
mail.logging.level	string	info
mail.logging.add_source	bool	false
mail.logging.log_json	bool	false

enabled

bool, default false

Turns outbound mail on. With it false the notification handler is not registered at all, so no event is queued and nothing is rendered.

mail:
  enabled: false

from

string, default empty

The envelope and header sender, e.g. “ssoossh@example.com” or “ssoossh <noreply@example.com>”. Required when Enabled.

mail:
  from: ""

reply_to

string, default empty

An optional Reply-To header. Worth setting to a monitored address: these messages report credential activity, and the first thing a recipient does with an unexpected one is try to reply.

mail:
  reply_to: "ssh-admins@example.com"

subject_prefix

string, default empty

Prepended to every rendered subject, e.g. “[ssoossh] “. Empty adds nothing. Templates can also write their own subject in full; this exists so an operator can tag every message without editing any template.

mail:
  subject_prefix: ""

template_dir

string, default empty

An optional directory of local template overrides. A file there replaces the embedded template of the same name; anything absent falls back to the embedded one, so overriding a single message does not mean vendoring the whole set. See https://mnestor.github.io/ssoossh/operations/email-notifications/.

mail:
  template_dir: "/etc/ssoossh/mail-templates"

expiry_reminder_lead

duration, default 168h

How far ahead of an enrollment code’s expiry the service_enrollment_expiring reminders start. Zero disables the sweep that sends them, and the job is not registered at all.

Inside the window the reminder repeats weekly until the code is within its final week, then daily until it expires. A 30-day lead therefore sends at 30, 23, 16 and 9 days out and then every day from 7 days out; the default week sends the daily ones alone.

A week by default: long enough that someone can schedule the re-enrollment rather than drop what they are doing, short enough that the first message still describes a real deadline.

Each send is claimed in the database so every instance can run the sweep without any of them duplicating it. Shortening this means an enrollment past the new window gets no reminder until it re-enters it; lengthening it picks enrollments up at the next sweep.

The web UI’s service codes page marks an account “Expires soon” over the same window, so the page and the first reminder agree. Zero turns the reminder off but not that warning, which then uses a week.

mail:
  expiry_reminder_lead: 168h

expired_attempt_window

duration, default 24h

Rate-limits the service_enrollment_expired_attempt notification to at most one per enrollment per window. Zero disables that notification entirely.

A window rather than a one-shot because the thing it reports is a retry loop: a cron job holding an expired code fails on its own schedule indefinitely, and the recipient needs to keep hearing that it is still happening without hearing it every five minutes. A day by default, so the useful message is “this is still happening today”.

mail:
  expired_attempt_window: 24h

rotation_quiet_period

duration, default 168h

How long after an NSS fleet key is rotated the nss_key_rotation_cleanup digest stays silent, giving hosts time to pick up the new secret on their own. After it, the digest goes out daily while any address still presents the previous secret, and stops when none does or the rotation grace (nss.key_rotation_grace) ends. Zero disables the digest entirely.

A week by default: a fleet that redeploys its configuration weekly has switched by then, and what is left is worth a message.

mail:
  rotation_quiet_period: 168h