Installation

Set up Monitoring macOS end to end in under 10 minutes: the indexes and HTTP Event Collector token in Splunk, then the app, then Collectord on each Mac as a LaunchDaemon. Install Collectord by hand, with Homebrew, or through your MDM.

If you don’t have a license key yet, request one first: see Before you begin.

Before you begin

• Splunk. Splunk Enterprise 9.2 or later, or Splunk Cloud Platform, for the Monitoring macOS app.
• A Mac. An Apple Silicon Mac with macOS 14 Sonoma or later. The installer refuses an Intel Mac or an older macOS.
• A license key. Request a 30-day evaluation key to try Collectord before production, or a free developer key for a homelab, learning or a personal project (180 days, renewable). Both forms email the key within a few minutes. For a longer evaluation, an offline key or more capacity, contact us.

Set up Splunk

Create the indexes

Collectord for macOS sends two kinds of data, and each goes to its own kind of index:

• The stats go to a Splunk metrics index (see Metrics index): CPU, memory, power, temperatures, disks, network, processes, batteries, security posture and the rest.
• The events go to an events index: unified log entries, crash reports, launchd service transitions, host events (boots, sleep, logins, account and security setting changes), connections, the application inventory, the install log and Collectord’s own log.

Create both in Settings › Indexes › New Index: for example, macos as an events index, and macos_metrics with Index Data Type: Metrics. The shipped configuration sends the stats to macos_metrics, so if you use that name, you don’t have to change anything on the Macs.

Create an HTTP Event Collector token

Collectord forwards data to Splunk over the HTTP Event Collector (HEC). If HEC isn’t enabled yet, follow Splunk’s Set up and use HTTP Event Collector in Splunk Web.

Create a token for the Macs, with both indexes:

• Default index: the events index, macos. Collectord sends its events to the token’s default index unless you name another.
• Allowed Indexes: the metrics index, macos_metrics, beside the events index. Collectord sends its stats to the metrics index.

Set both. A stats record that ends up in an events index is indexed as an event whose text is the word metric, and every measurement in it is lost.

Don’t set a source type on the token: Collectord assigns its own source types, and the app expects them.

The rest of this guide needs two values: the HEC endpoint URL and the token. Check both with curl from one of the Macs: a check from elsewhere only proves that that machine reaches HEC. Splunk answers Success, and the test event stays in the token’s default index:

1$ curl -k https://hec.example.com:8088/services/collector/event/1.0 -H "Authorization: Splunk B5A79AAD-D822-46CC-80D1-819F80D7BFB0" -d '{"event": "hello world"}'
2{"text": "Success", "code": 0}

-k skips certificate validation; use it only for self-signed certificates.

On Splunk Cloud, HEC has a URL of its own: https://http-inputs-<stack>.splunkcloud.com:443 on a paid stack, https://<stack>.splunkcloud.com:8088 on a trial stack.

Install the Monitoring macOS app

Install Monitoring macOS (monitoringmacos) from Splunkbase, on your search heads only.

Every search in the app reads its data through two macros:

• macro_macos_base reads the events index. If your events index isn’t searchable by default for your users, point the macro at it.
• macro_macos_metrics_base reads every metrics index the role can search, (index=*), so any name works. Narrow it to yours to keep other metrics out of the app’s searches.

With the example indexes, the two macros read:

1macro_macos_base = (index=macos)
2macro_macos_metrics_base = (index=macos_metrics)

To edit them, open the Macros panel on the app’s Setup › Configuration page. It links each macro to its editor in Settings › Advanced search › Search macros, where editing needs write access to the app (the admin, power or sc_admin role). Your change is kept across upgrades.

Once the first Mac reports, check the setup on the same page. It counts what reached each index in the last 15 minutes: Macs sending stats, Macs sending events, and stats that landed in an events index.

With field filters turned on ([search] field_filters in limits.conf), a field filter can make the dashboards fail (“Your search is restricted by a field filter”). That happens when the filter is on any metrics index macro_macos_metrics_base reaches, for a role the filter applies to that lacks the run_commands_ignoring_field_filter capability.

Limit the macro to unfiltered indexes: (index=macos_metrics), or (index=* NOT index=<filtered>). When your data’s index is the filtered one, grant those roles the capability or exempt them from the filter instead.

Install Collectord

Collectord for macOS (collectorformacos) runs as a LaunchDaemon, as root. It needs no Full Disk Access or other privacy permission: see Privacy for what it reads.

Install the package

Download the package and install it with installer:

1curl -fsSL -o /tmp/collectorformacos.pkg https://packages.outcold.solutions/downloads/collectorformacos/26.10.1/collectorformacos-26.10.1.pkg
2sudo installer -pkg /tmp/collectorformacos.pkg -target /

The package installs:

The package starts the LaunchDaemon right away. Collectord cannot start until you accept the license and give it the HEC URL and token. Until then, launchd tries again every 10 seconds, and each attempt writes why to Collectord’s log.

Or install with Homebrew

The cask installs the same package:

1brew install --cask outcoldsolutions/tap/collectorformacos

Configure Collectord

Open /opt/collectorformacos/etc/002-user.conf in your editor:

1sudo -e /opt/collectorformacos/etc/002-user.conf

This file holds your overrides for the defaults in /opt/collectorformacos/etc/001-general.conf. In it, set:

• Splunk HEC. The URL and the token.
• Your license key (see Before you begin), once you review and accept the license agreement.
• A fleet label, optionally. The dashboards and the Alert Catalog filter by it, so give each group of Macs its own: ci, build-farm, laptops.

Configuration covers what else you can set. A filled-in example:

 1[general]
 2acceptLicense = true
 3license = ...
 4fields.macos_cluster = ci
 5
 6[output.splunk]
 7url = https://hec.example.com:8088/services/collector/event/1.0
 8token = B5A79AAD-D822-46CC-80D1-819F80D7BFB0
 9insecure = false
10# Every stat goes to this metrics index: create it (datatype = metric) and let the token write to
11# it. Without one, the stats go to the token's default index; an events index keeps each record as
12# an event reading "metric", and its measurements are lost.
13defaultMetricsIndex = macos_metrics

Collectord picks the file up at its next start, within 10 seconds. To restart it now:

1sudo launchctl kickstart -k system/com.outcoldsolutions.collectord

Verify the installation

Let Collectord check its own setup: the configuration, the license, the HEC endpoint and token, a test record in each events and metrics index it sends to, and what it reads on the Mac.

1sudo /opt/collectorformacos/bin/collectord verify

Tail its log to watch it run:

1tail -f /Library/Logs/collectorformacos/collectord.log

In Splunk, the Mac shows up on the app’s Fleet Overview once its first stats arrive. See troubleshooting for what each check means.

Control the service

Collectord runs as the LaunchDaemon com.outcoldsolutions.collectord:

• Status. sudo launchctl print system/com.outcoldsolutions.collectord
• Log. tail -f /Library/Logs/collectorformacos/collectord.log
• Check the setup. sudo /opt/collectorformacos/bin/collectord verify
• Restart. sudo launchctl kickstart -k system/com.outcoldsolutions.collectord. A changed log level or license applies within ten seconds without one; every other setting takes a restart.
• Start it again after someone switched it off. sudo launchctl enable system/com.outcoldsolutions.collectord, then sudo launchctl bootstrap system /Library/LaunchDaemons/com.outcoldsolutions.collectord.plist. See Troubleshooting.
• Diagnostic bundle for support. sudo /opt/collectorformacos/bin/collectord diag --stream > diag.tar.gz

Deploy with MDM

For a fleet, deploy Collectord the way you deploy other software: its settings as a configuration profile, and the package through your MDM. An MDM that deploys a package from a URL can take the download link from Install the package as it is.

Three profiles go with the package, and these pages have the XML of each:

• Settings. The managed preferences for the com.outcoldsolutions.collectord domain: the Splunk URL and token, the indexes, the fleet label, the license and the rest. Collectord overlays them on its configuration files, so the Macs need no 002-user.conf.
• Managed Login Items. It keeps users from switching the LaunchDaemon off in System Settings › General › Login Items. It also keeps macOS from notifying them that it was added. macOS accepts it only from a user-approved MDM.
• Unified log private data. Optional: see Log forwarding.

Deploy the settings and Managed Login Items profiles first, then the package. Collectord then starts with its settings, and the LaunchDaemon is never offered to the user to switch off.

Without an MDM, install the settings and unified log private data profiles by hand: open the .mobileconfig on the Mac, then install it in System Settings › General › Device Management. The Managed Login Items profile cannot be installed that way. macOS refuses it with “The profile must originate from a user approved MDM server”.

Create the settings profile

Every key is optional: set the ones you need and leave out the rest. Configuration lists every key and what it sets. Most MDMs also let you build the same payload as custom settings for the com.outcoldsolutions.collectord preference domain.

 1<?xml version="1.0" encoding="UTF-8"?>
 2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 3<!--
 4  The collector's settings for a fleet, every key optional: they override its configuration files
 5  and environment (collectord verify lists what each key set); the licence and the log level apply
 6  without a restart, the rest at the next restart. macOS writes them to a file every user of the Mac
 7  can read: give a SplunkToken here the macOS indexes only, or deliver it in 002-user.conf (600).
 8-->
 9<plist version="1.0">
10<dict>
11	<key>PayloadContent</key>
12	<array>
13		<dict>
14			<key>PayloadDisplayName</key>
15			<string>Monitoring macOS - Settings</string>
16			<key>PayloadIdentifier</key>
17			<string>com.outcoldsolutions.collectorformacos.settings.collectord</string>
18			<key>PayloadType</key>
19			<string>com.outcoldsolutions.collectord</string>
20			<key>PayloadUUID</key>
21			<string>6E2C0A3F-3B1B-4F5B-9D55-8A0B3C2D1E21</string>
22			<key>PayloadVersion</key>
23			<integer>1</integer>
24			<key>AcceptLicense</key>
25			<true/>
26			<key>License</key>
27			<string>LICENSE-KEY</string>
28			<key>SplunkURL</key>
29			<string>https://splunk.example.com:8088/services/collector/event/1.0</string>
30			<key>SplunkToken</key>
31			<string>00000000-0000-0000-0000-000000000000</string>
32			<key>EventsIndex</key>
33			<string>macos</string>
34			<key>MetricsIndex</key>
35			<string>macos_metrics</string>
36			<key>FleetLabel</key>
37			<string>ci-fleet</string>
38			<key>LogPacks</key>
39			<array>
40				<string>workloads</string>
41				<string>fleet_health</string>
42			</array>
43			<key>LogCountsOnly</key>
44			<false/>
45			<key>ProcessStats</key>
46			<true/>
47		</dict>
48	</array>
49	<key>PayloadDisplayName</key>
50	<string>Monitoring macOS - Settings</string>
51	<key>PayloadIdentifier</key>
52	<string>com.outcoldsolutions.collectorformacos.settings</string>
53	<key>PayloadOrganization</key>
54	<string>Outcold Solutions</string>
55	<key>PayloadScope</key>
56	<string>System</string>
57	<key>PayloadType</key>
58	<string>Configuration</string>
59	<key>PayloadUUID</key>
60	<string>6E2C0A3F-3B1B-4F5B-9D55-8A0B3C2D1E20</string>
61	<key>PayloadVersion</key>
62	<integer>1</integer>
63</dict>
64</plist>

LogPacks names the log packs to turn on, and turns off every pack it doesn’t name, so the example above leaves the security pack off. To keep the defaults, name the three packs on by default: workloads, fleet_health and security.

macOS writes the profile’s settings to /Library/Managed Preferences/com.outcoldsolutions.collectord.plist, which every user of the Mac can read, unlike 002-user.conf (mode 600). So any local user can read a SplunkToken delivered this way. Give that token the macOS indexes only, or leave SplunkToken out of the profile and deliver the token in 002-user.conf.

Create the Managed Login Items profile

This profile keeps users from switching the LaunchDaemon off, and macOS from telling them it was added. Deploy it through your MDM:

 1<?xml version="1.0" encoding="UTF-8"?>
 2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 3<!--
 4  Managed Login Items: users cannot turn the collector's LaunchDaemon off in System Settings, and
 5  are not told it was added.
 6-->
 7<plist version="1.0">
 8<dict>
 9	<key>PayloadContent</key>
10	<array>
11		<dict>
12			<key>PayloadDisplayName</key>
13			<string>Monitoring macOS - Managed Login Items</string>
14			<key>PayloadIdentifier</key>
15			<string>com.outcoldsolutions.collectorformacos.loginitems.rules</string>
16			<key>PayloadType</key>
17			<string>com.apple.servicemanagement</string>
18			<key>PayloadUUID</key>
19			<string>6E2C0A3F-3B1B-4F5B-9D55-8A0B3C2D1E11</string>
20			<key>PayloadVersion</key>
21			<integer>1</integer>
22			<key>Rules</key>
23			<array>
24				<dict>
25					<key>RuleType</key>
26					<string>Label</string>
27					<key>RuleValue</key>
28					<string>com.outcoldsolutions.collectord</string>
29					<key>Comment</key>
30					<string>collectorformacos</string>
31				</dict>
32			</array>
33		</dict>
34	</array>
35	<key>PayloadDisplayName</key>
36	<string>Monitoring macOS - Managed Login Items</string>
37	<key>PayloadIdentifier</key>
38	<string>com.outcoldsolutions.collectorformacos.loginitems</string>
39	<key>PayloadOrganization</key>
40	<string>Outcold Solutions</string>
41	<key>PayloadScope</key>
42	<string>System</string>
43	<key>PayloadType</key>
44	<string>Configuration</string>
45	<key>PayloadUUID</key>
46	<string>6E2C0A3F-3B1B-4F5B-9D55-8A0B3C2D1E10</string>
47	<key>PayloadVersion</key>
48	<integer>1</integer>
49</dict>
50</plist>

Change the profile later

Collectord checks its configuration files and the profile for a change every 10 seconds. A new license or log level applies right away. Everything else applies at Collectord’s next start: the Splunk URL and token, the indexes, the log packs, the inputs. So push the new profile, then restart Collectord from your MDM with a script:

1launchctl kickstart -k system/com.outcoldsolutions.collectord

To check what the profile set, run sudo /opt/collectorformacos/bin/collectord verify on a Mac. It lists every key the profile set and what it set, never its value. It marks FAILED a key of the wrong type or a profile it cannot read.

Upgrade Collectord

If you get stuck, or want a hand planning an upgrade, contact support - we’ll help and guide you through it.

Upgrade the Monitoring macOS app in Splunk first, then the Macs. Install the new package the way you installed the first: with sudo installer, your MDM, or Homebrew.

1sudo installer -pkg /tmp/collectorformacos.pkg -target /
2brew upgrade --cask collectorformacos   # with Homebrew

The package stops the running Collectord, and waits up to 90 seconds for it to save what Splunk acknowledged. It replaces Collectord’s files (the binary, 001-general.conf, the LaunchDaemon and the log rotation), and starts it again. It keeps your 002-user.conf and the state database in /opt/collectorformacos/var/collectord, so the new version continues where the old one stopped.

A LaunchDaemon someone switched off in Login Items, or with launchctl disable, stays off. The install succeeds and says so, and Troubleshooting shows how to turn it back on.

Uninstall

The uninstaller stops Collectord and removes everything the package installed, your configuration, the state database and the logs included:

1sudo /opt/collectorformacos/bin/uninstall.sh

With --keep-data it keeps /opt/collectorformacos/etc and /opt/collectorformacos/var, so a reinstall continues where Collectord stopped:

1sudo /opt/collectorformacos/bin/uninstall.sh --keep-data

With Homebrew:

• brew uninstall --cask collectorformacos stops and removes Collectord, and keeps your configuration and the state database.
• brew uninstall --zap --cask collectorformacos removes those and the logs too.

Remove the MDM profiles from the Macs you uninstall Collectord from.

Next steps

• Take the tour of the dashboards.
• Pick alerts on the Alert Catalog page and create the ones relevant to your fleet.
• Choose which unified log entries to forward, and add your own log files.
• Read what Collectord collects on a Mac, and the switches for each source.
• Work through the troubleshooting checks if something looks off.