logga docs

Appearance

🔧 Configuration ​

good to know

For any configuration changes to take effect, the extension needs to be reloaded.

Configuration with Custom MDM Configuration Profile
Configuration with file

Configuration with Custom MDM Configuration Profile ​

Minimum required version: 1.1.0

In order to enable MDM administrators to manage logga from a single location, logga can be configured via deployed Custom Configuration Profiles.

Deploy Configuration Profile on macOS hosts ​

Save and deploy the below Configuration Profile with your preferred MDM tool. See the detailed list of configuration parameters below.

warning

The PayloadType key must not be modified (com.logga.client) so that logga can find and apply the Profile.

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<!-- [compatibility: Minimum required version is 1.1.1] -->
			<key>CompressArchives</key>
			<false/>
			<!-- [/compatibility] -->
			<key>AccessLoggerEnabled</key>
			<true/>
			<key>AccessLoggerLogFilePath</key>
			<string>/Library/Application Support/Logga/access.log</string>
			<key>AccessLoggerMaxFileCount</key>
			<integer>10</integer>
			<key>AccessLoggerMaxFileSize</key>
			<integer>5242880</integer>
			<key>AccessLoggerOutputFormat</key>
			<string>json</string>
			<key>AuditLoggerCustomLogFormat</key>
			<string>${timestamp} ${username} ${group} ${command} ${args}</string>
			<key>AuditLoggerEnabled</key>
			<true/>
			<key>AuditLoggerLogFilePath</key>
			<string>/Library/Application Support/Logga/audit.log</string>
			<key>AuditLoggerMaxFileCount</key>
			<integer>10</integer>
			<key>AuditLoggerMaxFileSize</key>
			<integer>5242880</integer>
			<key>AuditLoggerMutingInverted</key>
			<false/>
			<key>AuditLoggerMutingTargets</key>
			<array>
				<dict>
					<key>Path</key>
					<string>/usr/bin/xcodebuild</string>
					<key>Type</key>
					<string>Prefix</string>
				</dict>
			</array>
			<key>AuditLoggerOutputFormat</key>
			<string>json</string>
			<key>PayloadDescription</key>
			<string>logga configuration profile</string>
			<key>PayloadDisplayName</key>
			<string>logga Configuration Profile</string>
			<key>PayloadIdentifier</key>
			<string>com.logga.client.2e03f882-4744-40c4-88e1-47e38d9337cd</string>
			<key>PayloadOrganization</key>
			<string>logga</string>
			<key>PayloadType</key>
			<string>com.logga.client</string>
			<key>PayloadUUID</key>
			<string>2e03f882-4744-40c4-88e1-47e38d9337cd</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string>logga configuration profile</string>
	<key>PayloadDisplayName</key>
	<string>logga Configuration Profile</string>
	<key>PayloadIdentifier</key>
	<string>com.logga.client.configuration</string>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>59174207-CD91-40FF-9DCA-4C6F2EE0441A</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

Verify the Custom Profile on macOS ​

Open System Settings > Privacy & Security > Profiles and see if logga Configuration Profile is present under the Devices section.

logga Configuration Profile

Precedence ​

The Profile based configuration takes precedence over the file based configuration.

  1. If logga Configuration Profile is present on the machine, logga defaults to it
  2. If logga Configuration Profile is missing, logga falls back to the configuration file at /Library/Application\ Support/Logga/config.yaml (the installer creates it)
  3. If the configuration file at /Library/Application\ Support/Logga/config.yaml is missing as well, logga creates one with default values

logga is fault tolerant. If any configuration keys are missing or invalid, then defaults will be used instead.

Configuration with file ​

logga expects to find a valid configuration file at /Library/Application\ Support/Logga/config.yaml.
logga creates a default configuration file on two occasions:

  • At installation
  • On system extension load, when there isn't any valid configuration found at the expected location
    • it means that if the configuration file contains errors, logga will overwrite it

Default configuration ​

yaml
# [compatibility: minimum required version is 1.1.1]
compressArchives: false
# [/compatibility]
auditLogger:
  customLogFormat: ${timestamp} ${username} ${group} ${command} ${args}
  muting:
    inverted: false
    targets: []
  enabled: true
  logFilePath: /Library/Application Support/Logga/audit.log
  outputFormat: json
  maxLogFileCount: 5
  maxLogFileSize: 5242880
accessLogger:
  enabled: true
  logFilePath: /Library/Application Support/Logga/access.log
  outputFormat: json
  maxLogFileCount: 5
  maxLogFileSize: 5242880

compressArchives - bool ​

Minimum required version: 1.1.1

default: false

When enabled, logga will compress audit and access logs into a gzip file on rotation. The rotation rules will take effect over compressed files as well.

auditLogger ​

Configuration for the audit logging capability

customLogFormat - string ​

default: ${timestamp} ${username} ${group} ${command} ${args}

The audit logger supports custom log formatting. The field names are fixed, but other than that, you can go crazy with your own format.
Available fields:

  • timestamp
  • username
  • group
  • uid
  • guid
  • auid
  • euid
  • egid
  • pid
  • ppid
  • tty
  • exec_path
  • script
  • cwd
  • command
  • env
  • args

Example configuration:

yaml
auditLogger:
  customLogFormat: "[${timestamp}]: (${username}, ${group}) |example text| ${command} % ${args}"
# Rest of the configuration file is omitted

Example command:

bash
ls -la

would result in the following log line:

[2023-10-03T20:03:03.696Z]: (administrator, staff) |example text| /bin/ls % ["ls", "-G", "-la"]

See more examples

muting - object ​

Sometimes there is just too much noise, which is true for audit logs as well. logga supports muting some paths to reduce noise in the audit log stream.

Example configuration:

yaml
auditLogger:
  muting:
    inverted: false
    targets:
      - path: /usr/bin/xcodebuild
        type: prefix
      - path: /usr/sbin/ioreg
        type: literal
inverted - bool ​

Default: false

See more details in the log inversion page.

targets - array ​

Lists the muting rules.

path - string ​

If the process execution path matches the given path, it will be excluded from the log stream.

type - string ​

Type can take up two values: prefix and literal. As the names imply, prefix will look for prefix based matches, while literal will look for exact matches.

enabled - bool ​

Default: true

Enable or disable the audit logging capability

logFilePath - string ​

Default: /Library/Application\ Support/Logga/audit.log

Defines the file path where logga writes audit logs into. If logga cannot parse the provided path, it will fallback to /Library/Application\ Support/Logga/audit.log

outputFormat - string ​

Default: json

Represents the selected log output format.
Currently supported audit log formats: custom, json, auditd

maxLogFileCount - int ​

Default: 5

logga does log rotation by default. By this parameter you can overwrite the numbers of log files to keep at the same time.

maxLogFileSize - int ​

Default: 10485760

TIP

For performance reasons, logga won't rotate exactly at "maxLogFileSize" bytes

logga doesn't let the currently active log file grow (much) beyond this limit (in bytes). When a file reaches maxLogFileSize, it gets rotated.

accessLogger ​

Configuration for the access logging capability

enabled - bool ​

Default: true

Enable or disable the access logging capability

logFilePath - string ​

Default: /Library/Application\ Support/Logga/access.log

Defines the file path where logga writes access logs into. If logga cannot parse the provided path, it will fallback to /Library/Application\ Support/Logga/access.log

outputFormat - string ​

Default: json

Represents the selected log output format.
Currently supported access log formats: json

maxLogFileCount - Int ​

Default: 5

logga does log rotation by default. By this parameter you can overwrite the numbers of log files to keep at the same time.

maxLogFileSize - Int ​

Default: 10485760

TIP

For performance reasons, logga won't rotate exactly at "maxLogFileSize" bytes

logga doesn't let the currently active log file grow (much) beyond this limit (in bytes). When a file reaches maxLogFileSize, it gets rotated.