Installing osquery on macOS and configuring Osqueryd schedule and logs for SAM total usage metrics. - Support and Troubleshooting

Installing osquery on macOS and configuring Osqueryd schedule and logs for SAM total usage metrics. Issue .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Installing osquery on macOS and configuring Osqueryd schedule and logs for SAM total usage metrics.

Release .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } All Releases

Resolution .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Overview This document provides comprehensive instructions for installing osquery on macOS and configuring it for ServiceNow SAM (Software Asset Management) integration.

Note: The osquery example configuration file contains JSON comments (lines starting with // ) which are not valid JSON and will cause the service to fail. These must be removed when copying the configuration.

Installation Process Step 1: Download osquery Package Visit the official osquery downloads page: https://osquery.io/downloads Download the latest macOS package (.pkg file) for your system Note the download location for the installation Step 2: Install the Package Navigate to the download location in Finder Double-click the downloaded .pkg file Follow the installation wizard: Click "Continue" on the introduction screen Review and accept the license agreement Select the installation destination (typically your main drive) Enter your administrator password when prompted Click "Install" to begin the installation Wait for the installation to complete Click "Close" when finished Step 3: Verify Installation Open Terminal and verify the installation:

# Check for osquery binaries which osqueryi which osqueryctl # Expected output: # /usr/local/bin/osqueryi # /usr/local/bin/osqueryctl # Verify app bundle installation ls -la /opt/osquery/lib/osquery.app # Check created directories and files ls -la /private/var/osquery/ Service Configuration Step 4: Create Configuration File from Example Critical Warning: The osquery.example.conf file contains JSON comments ( // ) which are invalid JSON syntax. These comments MUST be removed or the osquery service will fail to start.

Method 1: Automated Comment Removal (Recommended)

# Copy the example config while removing comment lines sudo grep -v '^\s*//' /var/osquery/osquery.example.conf > /var/osquery/osquery.conf Method 2: Manual Copy and Edit

# Copy the example configuration sudo cp /var/osquery/osquery.example.conf /var/osquery/osquery.conf # Edit the file sudo nano /var/osquery/osquery.conf # Manually delete all lines that start with // # These are JSON comments and will cause parsing errors Step 5: Add ServiceNow SAM Pack The SAM (Software Asset Management) pack enables osquery to work with ServiceNow's Agent Client Collector for enhanced discovery and software inventory.

For more details on this integration, see: https://www.servicenow.com/docs/bundle/zurich-it-operations-management/page/product/agent-client-collector/concept/using-enhanced-discovery-and-sam-together.html

Edit the configuration file to add the SAM metering pack:

sudo nano /var/osquery/osquery.conf Locate the "packs": section in the JSON structure and add the SAM metering entry:

"packs": { "sam-metering": "/Library/Application Support/servicenow/agent-client-collector/cache/acc-visibility-modules/bin/sam-metering.conf" } Important Notes:

If other packs already exist, add a comma after the last pack before adding sam-metering Ensure the path uses escaped spaces (or quote the entire path) Verify the ServiceNow agent is installed and this path exists Example with existing packs:

"packs": { "osquery-monitoring": "/var/osquery/packs/osquery-monitoring.conf", "sam-metering": "/Library/Application Support/servicenow/agent-client-collector/cache/acc-visibility-modules/bin/sam-metering.conf" } Step 6: Create and Configure osquery.flags Create the flags file with logging and rotation settings:

sudo nano /var/osquery/osquery.flags Add exactly these five flags:

--logger_rotate=true --logger_rotate_size=26214400 --logger_rotate_max_files=1 --watchdog_level=1 --logger_mode=0644 Flag Explanations:

Flag Description --logger_rotate=true Enables log rotation --logger_rotate_size=26214400 Sets max log size to 25MB (in bytes) --logger_rotate_max_files=1 Keeps only 1 rotated log file --watchdog_level=1 Sets watchdog monitoring level --logger_mode=0644 Sets log file permissions Save and exit (Press Ctrl+X, then Y, then Enter)

Step 7: Install LaunchDaemon Copy the service configuration to the system LaunchDaemons directory:

sudo cp /var/osquery/io.osquery.agent.plist /Library/LaunchDaemons/ Verify the file was copied:

ls -la /Library/LaunchDaemons/io.osquery.agent.plist Step 8: Start the Service Method A: Using osqueryctl (Recommended)

sudo osqueryctl start Method B: Manual LaunchDaemon Loading

sudo launchctl load -w /Library/LaunchDaemons/io.osquery.agent.plist Wait a few seconds for the service to fully initialize.

Service Verification Step 9: Verify Service is Running Run these commands to ensure the service started correctly:

# Check if service is loaded in launchctl sudo launchctl list | grep osquery # Expected output: [PID] 0 io.osquery.agent # Check if osqueryd process is running ps aux | grep osqueryd | grep -v grep # Expected output: root [PID] ... /opt/osquery/lib/osquery.app/Contents/MacOS/osqueryd # Check service status using osqueryctl sudo osqueryctl status # Expected output: osqueryd is running. pid: [PID] Step 10: Test osquery Interactive Shell Test the installation by running queries:

# Start interactive shell osqueryi # Once in the shell, run these test queries: SELECT * FROM system_info; SELECT * FROM os_version; SELECT name, path FROM processes WHERE name = 'osqueryd'; # Exit the shell .quit Step 11: Verify SAM Pack Configuration Confirm the SAM pack is loaded:

# Check configuration sudo grep -A2 "sam-metering" /var/osquery/osquery.conf # Check if pack file exists ls -la "/Library/Application Support/servicenow/agent-client-collector/cache/acc-visibility-modules/bin/sam-metering.conf" Troubleshooting 1. Service Fails to Start Symptoms: osqueryctl status shows "osqueryd is not running"

Solutions:

# Check logs sudo tail -50 /var/log/osquery/osqueryd.INFO # Verify JSON syntax osqueryi --config_check --config_path /var/osquery/osquery.conf # Ensure no JSON comments (//) remain in config 2. JSON Parsing Errors Error: "Cannot parse JSON: Unexpected character"

Solution:

# Remove all comment lines sudo grep -v '^\s*//' /var/osquery/osquery.conf > /tmp/osquery.conf sudo mv /tmp/osquery.conf /var/osquery/osquery.conf 3. Permission Issues Error: "Permission denied" errors in logs

Solution:

# Fix ownership sudo chown -R root:wheel /var/osquery/ sudo chmod 644 /var/osquery/osquery.conf sudo chmod 644 /var/osquery/osquery.flags 4. SAM Pack Not Found Error: "Error reading file" for sam-metering.conf

Solutions:

Verify ServiceNow agent is installed Check the exact path exists Use escaped spaces in the path or quote the entire path Useful Debugging Commands # View current configuration osqueryi --config_dump # Test configuration file osqueryi --config_check --config_path /var/osquery/osquery.conf # View recent logs sudo tail -f /var/log/osquery/osqueryd.INFO # Check all osquery processes ps aux | grep osquery # Restart service sudo osqueryctl restart

Related Links .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Reference File Locations File Path Configuration /var/osquery/osquery.conf Flags /var/osquery/osquery.flags Logs /var/log/osquery/ LaunchDaemon /Library/LaunchDaemons/io.osquery.agent.plist Binary /opt/osquery/lib/osquery.app/Contents/MacOS/osqueryd Official Documentation osquery Documentation: https://osquery.readthedocs.io/en/stable/installation/install-macos/ osquery Schema: https://osquery.io/schema/ ServiceNow Documentation - Agent Client Collector with Discovery and SAM: https://www.servicenow.com/docs/bundle/zurich-it-operations-management/page/product/agent-client-collector/concept/using-enhanced-discovery-and-sam-together.html