🔧 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 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] -->
			<!-- [compatibility: Minimum required version is 1.1.2] -->
			<key>IncludeHostname</key>
			<true/>
			<!-- [/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>
			<!-- [compatibility: Minimum required version is 1.1.2] -->
			<key>UnifiedLogEnabled</key>
			<true/>
			<key>UnifiedLogFrequency</key>
			<integer>15</integer>
			<key>UnifiedLogSubsystems</key>
			<array></array>
			<!-- [/compatibility] -->
			<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.

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

# [compatibility: minimum required version is 1.1.1]
compressArchives: false
# [/compatibility]
# [compatibility: minimum required version is 1.1.2]
includeHostname: true
# [/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
# [compatibility: minimum required version is 1.1.2]
unifiedLogger:
  enabled: false
  frequency: 1
  subsystems: ["com.apple.runningboard"]
# [/compatibility]

---

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.

Minimum required version: 1.1.2

From 1.1.2, logga will compress audit and access logs into an archive (lzfse) file on rotation. The rotation rules will take effect over compressed files as well. The file format is compatible with Apple's built in aa binary.

To extract an archieve, run: sudo aa extract -i audit.log.archive

includeHostname - bool

Minimum required version: 1.1.2

default: true

When enabled, logga will enrich logs with the machine's hostname.

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:

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

Example command:

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:

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.

---

unifiedLogger

Configuration for the unified logging capability

enabled - bool

Default: false

Enable or disable the unified logging capability. Unified logger is disabled by default due to the vast amount of logs it produces. Due to performance reasons, logga queries the Unified Logs API periodically (set by the frequency parameter). We suggest to limit the number of collected log entries by specifying subsystem filters.

frequency - Int

Default: 15

The periodicity (in minutes) of logga querying the Unified Logs API for new entries in order to persist logs.

subsystems - array

Default: []

Example: ["com.apple.runningboard"]

Limit the number of log entries returned by the Unified Logs API by listing subsystem IDs.