Deploying the universal forwarder to a macOS fleet

Deployment architecture

To follow deployment best practices, use the following components:

• A custom .pkg installer package containing:
  • The Universal Forwarder .tgz archive
  • Pre-configured deployment configuration files
  • A user-seed.conf file for admin credentials
• A postinstall script that extracts and configures the forwarder
• A LaunchDaemon for automatic startup at boot
• (Optional) A PPPC profile for Full Disk Access permissions

Step 1: Prepare configuration files

Prepare the following configuration files:

• deploymentclient.conf

  Create this file to configure the forwarder to connect to your agent management:

  CODECopy

  [deployment-client] clientName = $HOSTNAME [target-broker:deploymentServer] targetUri = your-deployment-server.company.com:8089

  [deployment-client]
  clientName = $HOSTNAME [target-broker:deploymentServer] targetUri = your-deployment-server.company.com:8089

• outputs.conf (Alternative to your agent management)

  If not using agent management, configure direct forwarding to indexers:

  CODECopy

  [tcpout] defaultGroup = splunk-indexers [tcpout:splunk-indexers] server = indexer1.company.com:9997,indexer2.company.com:9997 compressed = true

  [tcpout] defaultGroup = splunk-indexers [tcpout:splunk-indexers] server = indexer1.company.com:9997,indexer2.company.com:9997 compressed = true

• user-seed.conf

  Pre-configure admin credentials to bypass the interactive setup prompts that occur during the initial launch of the application (First Time Run sequence) by taking these steps:

  1. On a single reference machine where the universal forwarder is already installed, run the hash-passwd command to generate a SHA-512 crypt hash of your password:

     CODECopy

     /opt/splunkforwarder/bin/splunk hash-passwd <your-chosen-password>

     /opt/splunkforwarder/bin/splunk hash-passwd <your-chosen-password>

     It generates the password hash string.

     Note: You only need to perform this step once. You will reuse this same hash for all devices in your fleet.
  2. Copy the entire output of the password hash string, which begins with $6$.
     Note: Do not modify or manually construct the hash string. The Splunk platform manages this format internally.
  3. Configure the user-seed.conf file as follows, pasting the entire output of the password hash string as the HASHED_PASSWORD value:

     PYTHONCopy

     [user_info] USERNAME = admin HASHED_PASSWORD = <paste the entire output from splunk hash-passwd command>

     [user_info]
     USERNAME = admin
     HASHED_PASSWORD = <paste the entire output from splunk hash-passwd command>

  4. Distribute this user-seed.conf file to your target machines.

     Important: The universal forwarder only consumes the user-seed.conf file during its initial launch (the First Time Run sequence). Upon startup, the Splunk platform reads the file, creates the admin account in $SPLUNK_HOME/etc/passwd, and then ignores the seed file. This ensures all devices in your fleet receive the same initial admin credentials.

Step 2: Create the post-installation script

The post-installation script, run by the .pkg installer, automates the extraction, configuration, and service initialization of the universal forwarder.

The script includes the set -e shell setting to ensure the script stops immediately if any step fails. This is a safety measure to prevent the installer from continuing if a critical configuration step is unsuccessful.

#!/bin/bash 
# Splunk Universal Forwarder - macOS Silent Installation Script 
# This script is designed to run as a postinstall script in a .pkg installer.
# Specifies the shell setting to ensure the script stops immediately if any step fails:
set -e  

# Configures the installation paths:
SPLUNK_HOME="/opt/splunkforwarder" 
STAGING_DIR="/var/tmp/splunk_install"  

# Extracts the universal forwarder package to the /opt folder: 
echo "Extracting Splunk Universal Forwarder..." 
cd /opt 
tar xzf "${STAGING_DIR}/splunkforwarder-*.tgz"  

# Terminates any existing splunkd process: 
pkill splunkd 2>/dev/null || true sleep 2  

# Deploys the configuration files into the Splunk Enterprise /local folder:
echo "Deploying configuration files..." 
mkdir -p "${SPLUNK_HOME}/etc/system/local" cp "${STAGING_DIR}/deploymentclient.conf" "${SPLUNK_HOME}/etc/system/local/" 2>/dev/null || true cp "${STAGING_DIR}/outputs.conf" "${SPLUNK_HOME}/etc/system/local/" 2>/dev/null || true cp "${STAGING_DIR}/user-seed.conf" "${SPLUNK_HOME}/etc/system/local/" 2>/dev/null || true  

# Sets ownership (runs as root by default): 
chown -R root:wheel "${SPLUNK_HOME}"  

# Accepts the license and starts the universal forwarder:
echo "Starting Splunk Universal Forwarder..." 
"${SPLUNK_HOME}/bin/splunk" start --accept-license --no-prompt --answer-yes  

# Registers boot-start with the Launch Daemon system service: 
echo "Enabling boot-start..." 
"${SPLUNK_HOME}/bin/splunk" enable boot-start  

# Moves the Launch Daemon to the correct system location (the/LaunchDaemons folder) if needed:
if [ -f "/Library/LaunchAgents/com.splunk.splunkd.plist" ]; then    mv "/Library/LaunchAgents/com.splunk.splunkd.plist" "/Library/LaunchDaemons/" fi  

# Loads the Launch Daemon 
launchctl unload /Library/LaunchDaemons/com.splunk.plist 2>/dev/null || true sleep 1 launchctl load /Library/LaunchDaemons/com.splunk.plist  

# Remove the staging files to clean up the installation directory: 
rm -rf "${STAGING_DIR}"  
echo "Splunk Universal Forwarder installation complete." exit 0

Step 3: Build the Deployment Package

Use a package building tool such as Packages , JAMF Composer, or munkipkg to create a .pkg installer:

1. Create a new package project.
2. Add files to be installed to the /var/tmp/splunk_install/ folder:
   • splunkforwarder-<version>-darwin-universal2.tgz
   • deploymentclient.conf
   • outputs.conf (if applicable)
   • user-seed.conf
3. Add the postinstall script to the Scripts section.
4. Set the package identifier (for example, com.splunk.universalforwarder).
5. Build the package.

Step 4: Configure macOS Security Permissions (PPPC Profile)

On macOS version 10.14 and higher, the universal forwarder requires Full Disk Access to read protected log files, such as /var/log/system.log. Deploy a Privacy Preferences Policy Control (PPPC) profile through the MDM platform to grant this permission silently.

Use the following PPPC Profile configuration to grant Full Disk Access (FDA) (SystemPolicyAllFiles to the universal forwarder:

<?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>             <key>PayloadType</key>             <string>com.apple.TCC.configuration-profile-policy</string>             <key>Services</key>             <dict>                 <key>SystemPolicyAllFiles</key>                 <array>                     <dict>                         <key>Allowed</key>                         <true/>                         <key>CodeRequirement</key>                         <string>identifier "splunkd" and anchor apple generic</string>                         <key>Identifier</key>                         <string>/opt/splunkforwarder/bin/splunkd</string>                         <key>IdentifierType</key>                         <string>path</string>                     </dict>                 </array>             </dict>         </dict>     </array>     <key>PayloadIdentifier</key>     <string>com.company.splunk.pppc</string>     <key>PayloadType</key>     <string>Configuration</string> </dict> </plist>

Step 5: Deploy the universal forwarder using the MDM platform

Following these steps using the JAMF Pro MDM platform:

1. Upload the .pkg to JAMF Admin or directly to JAMF Pro.
2. Create a New Policy with the following settings:
   • For Trigger, set Recurring Check-in or Enrollment Complete.
   • For Execution Frequency, set Once per computer.
   • For Scope, set Target computers or Smart Groups.
3. Navigate to Configuration Profiles, create a new profile and add the PPPC profile configuration.
4. Set the Scope of the the Configuration Profile to the same target machines.

Configure an indexer

To configure the universal forwarder to send data to an indexer, run the following command:

/opt/splunkforwarder/bin/splunk add forward-server <indexer>:9997 -auth admin:<password>

Configure agent management

To configure the universal forwarder to connect to agent management, run the following command:

/opt/splunkforwarder/bin/splunk set deploy-poll <deployment-server>:8089 -auth admin:<password>

Add data inputs

# System logs:
/opt/splunkforwarder/bin/splunk add monitor /var/log -auth admin:<password>  

# Application logs:
/opt/splunkforwarder/bin/splunk add monitor /Library/Logs -auth admin:<password>  

# User logs (requires Full Disk Access):
/opt/splunkforwarder/bin/splunk add monitor ~/Library/Logs -auth admin:<password>

Restart the universal forwarder

To restart the universal forwarder, run the following command:

/opt/splunkforwarder/bin/splunk restart

Next steps: configuration and management

After successfully installing the universal forwarder, consult the following resources:

• To learn about configuring the universal forwarder, see Enable a receiver for Splunk Enterprise.
• To learn about macOS data sources, see the Get Data In manual.
• To learn about managing universal forwarders at scale, see Update Your Deployment manual.

GateKeeper warnings - macOS 13 and higher versions

Issue:

You receive GateKeeper security warnings about the downloaded software.

Cause:

The macOS 13 (Ventura) and higher versions of the operating system introduced stricter security requirements for background services.

Possible solutions:

• Ensure your .pkg installer is properly signed with a Developer ID Installer certificate.

• Install the universal forwarder using MDM which bypasses GateKeeper for managed software

Full Disk Access Denied

Issue:

The universal forwarder cannot read /var/log/system.log or other protected files.

Possible solutions:

• Ensure the PPPC profile is deployed and applied
• Manually grant access in System Preferences > Security & Privacy > Privacy > Full Disk Access.

Launch Daemon is not starting

Possible solution:

Verify whether the Launch Daemon is in the correct location and loaded:

CODECopy

ls -la /Library/LaunchDaemons/com.splunk.plist sudo launchctl list | grep splunk

ls -la /Library/LaunchDaemons/com.splunk.plist sudo launchctl list | grep splunk

Connection issues

Issue:

Network connectivity and firewall issues

Possible solutions:

• Test connectivity to the deployment server:
  CODECopy

  nc -zv <deployment-server> 8089

  nc -zv <deployment-server> 8089

• Test connectivity to the indexer:
  CODECopy

  nc -zv <indexer> 9997

  nc -zv <indexer> 9997

• Check universal forwarder logs:
  CODECopy

  tail -f /opt/splunkforwarder/var/log/splunk/splunkd.log

  tail -f /opt/splunkforwarder/var/log/splunk/splunkd.log