Log records

This page describes what a log record looks like, which fields it carries, and how the numeric event IDs work. The IDs themselves are listed in Log event IDs.

Formats

The format depends on the destination chosen in the Logging settings.

• File, JSON encoding: one JSON object per line, in a .jsonl file. This is the format to feed a log collector or a SIEM. With a tamper evident passphrase every line also carries a chained signature.
• File, W3C encoding: the W3C Extended Log File Format, in a .log file. It is meant for protocol activity, it has a fixed set of columns, and it does not carry event IDs.
• Syslog: each record is sent as <PRI>timestamp host tag[pid]: marker followed by the same JSON object the JSON file holds. The facility in PRI is set by the Facility option, and is kern unless you change it.
• Standard output: one key=value line per record, for reading in a terminal.

Fields on every record

Field	Meaning
time	When the record was written.
level	The severity: trace, debug, info, warn or error.
service	The log the record belongs to: ss-webrest for the management service, ss-wrk-<virtual site> for a virtual site.
subsystem	The part of the software that wrote the record.
nodeId	The node that wrote the record.
comment	The text written for people.
error	The error, when there is one.

Event IDs

A record that describes an event a log collector should recognize carries a numeric eventId field. Records without one are diagnostics written for people; they never gain an ID unless the event table says so.

The IDs follow these rules:

• An ID names what happened, not where: a wrong password is the same event on SSH, FTP and HTTPS, and the protocol field tells them apart.
• IDs are grouped in blocks of a thousand by subject (service, connections, sign in, files, Shield, operators, audit, cluster, platform). Within a block, related outcomes share a range: 3100 to 3199 is every failed end user sign in, for example.
• An event is always written with the same level, and always at Info or above, so a default installation records it.
• The meaning of an ID never changes, and an ID that is withdrawn is never used again. New IDs and new fields can appear in any release; a field an event carries is never removed or renamed.

NOTE

Some events are sampled or throttled because the condition behind them can repeat thousands of times a minute, for example a connection refused at accept or a revoked token presented again by an open browser tab. The Notes column of the event table says which ones, and how.

Some actions produce two events on purpose: one says who did it, the other what happened. An operator adding a cluster node writes HANodeAdded (7050) and the cluster writes ClusterPeerAdded (8004); an operator setting another account's password writes ObjectUpdated (7002) and OperatorPasswordSetOnAccount (6202).

Event fields

An event carries the fields listed for it in the event table, from this set. Empty values are not written.

Field	Meaning
eventId	The event ID, as a number.
sessionId	The session. Every attempt, refusal and channel of one SSH connection shares one session ID.
channelId	For SSH, the channel, which is a session of its own inside the connection.
clientIp	The client's address.
username	The user name: the one the client typed for a failed sign in, otherwise the account.
protocol	See below.
vsite	The virtual site, on records written by the management service.
authMethod	How a sign in succeeded, for example password,otp; several methods are listed in order.
endReason	Why a session ended: client closed, logout, idle timeout, admin terminated, terminated by script, session expired, server shutdown or share login refused.
actor, actorRole	Who acted: the account, and sa, admin, setup, telegram or cli.
objectType, objectId	What an operator acted on, for example user and its ID.
method, route	The HTTP method and route of an audited request.
target, rule	The address or network a Shield ban is about, and the rule that fired.
node, peer	A node an action or cluster event is about.
event, script	The event handler and script of a script event.
vfs, listener, certificate, recipient	The virtual file system, the listening address, the certificate, or the email recipient involved.

The protocol field holds the session's subsystem on session and file records (ssh2_sftp, ssh2_scp, ssh2_shell, ssh2_command, ftp, ftps, ftpes, https, https_sharing, and SSH2 for an SSH connection before it opens a channel), the service on listener records (SSH2, FTP, FTPS, HTTPS, R2FS), and the Shield's protocol names on Shield records (ssh, ftp, ftps, ftpes, https, share, r2fs, webrest).

Older records keep the spelling they always had: the web access log writes sessID and clientIP, and a few library records write sessionID.

Command line tools

The management service's command line tools that change security state (password reset, two factor disable, node reset, database credential rotation, secret re-encryption, initialization from a backup, and backup export) write an audit record too, with the operating system account that ran them as actor. They never write into the service's own log file: with the File destination they append to ss-webrest-cli.jsonl in the same directory, which is not hash chained. With Syslog or Standard output they write where the service does.

Older text tags

Earlier releases marked some lines with a tag inside the comment. The comments are unchanged, so a search for these tags still works; the event ID is the reliable way to find the same events.

Tag	Event
/DRAIN	2010 ConnRefusedDraining
/MTC	2011 ConnRefusedTotalLimit or 2012 ConnRefusedLicenseLimit
/MCP, /MPC	2013 ConnRefusedAddressLimit
/UMC, /MPU	2014 ConnRefusedAccountLimit
/SCR	2015 ConnRefusedByScript
/NCA	2020 SSHNoCommonAlgorithms
/NSC	2021 SSHHandshakeFailed
/PV	3102 SignInWrongPassword
/UPC	3121 SignInProtocolNotAllowed
/UAL	3122 SignInAccountNotAllowed
/USCRAR, /USCRAP	3124 SignInDeniedByScript
/SCP, /EXEC, /SHELL (not allowed)	4104 SubsystemNotAllowed