macOS

Agentless

Synopsis

Director logs in to one Mac over SSH and runs read-only commands on it. Nothing is installed on the Mac and no agent is sent to it. What the device reads is decided by the datasets and profiles assigned to it: the host's inventory, its metrics, its log files, and scripts run on it — see Solaris, AIX, and macOS Datasets.

A standard user, not an administrator, reads everything the device reads: nothing runs under sudo, and the device's own collection writes nothing on the Mac but a script's temporary file. A script you assign runs as the login and can do whatever the login may. macOS 12 and later are supported, on Intel and Apple silicon Macs alike.

One device reads one host, and one Director owns it.

Before adding a Mac

• A Mac answers SSH once Remote Login is on (System Settings > General > Sharing; on macOS 12, System Preferences > Sharing), for the users it allows.
• A log file in a folder macOS protects (a user's Library, Desktop, or Documents) is refused to an SSH login unless Remote Login's Allow full disk access for remote users is on too. The system's logs in /var/log are not protected.
• The macOS device needs Director 2.2.3 or later. The wizard refuses an older Director.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: macos
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    username: <string>
    port: <numeric>
    password: <string>
    key_based: <boolean>
    private_key: <string>
    passphrase: <string>
    timeout: <numeric>
    host_key: <string>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be macos
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	Y	-	The host, an IP address or a name. A wildcard address (0.0.0.0, ::) is refused.
port	N	22	The host's SSH port
username	Y	-	The login (resolvable via ${ENV_VAR} or $secret{...})
password	N*	-	Its password (resolvable via ${ENV_VAR} or $secret{...})
key_based	N	false	Log in with private_key instead of password
private_key	N*	-	The private key, in PEM or OpenSSH format (resolvable via ${ENV_VAR} or $secret{...})
passphrase	N	-	The key's passphrase, when it has one
timeout	N	30	Seconds for the connection and its login, from 1 to 300
host_key	N	-	The host's SSH key: a SHA256: fingerprint as ssh-keygen -lf prints it, or the public key itself. See Host Keys.

* password is required unless key_based is true, in which case private_key is required.

A device that fails these checks does not start, and its state is Configuration error.

Datasets

The device's definitions are its datasets, each named after its type: macos_inventory_collector, macos_metrics_collector, macos_file_log_collector, and macos_script_collector. In the console they are the datasets and profiles assigned to the device. For their properties, see Solaris, AIX, and macOS Datasets.

Host Keys

The host's SSH key is checked before any credential is sent.

Trusted on first use

Without host_key, the key the host presents the first time is trusted. A later login that meets a different key stops the device with Authentication error, naming the trusted key and every key the host presented. If the key changed on purpose, for example because the Mac was reinstalled, set host_key to the new one.

With host_key set, the host must present that key. Any of the host's keys may be pinned: the Director asks for ECDSA, RSA, then Ed25519, logging in again for each before any credential is sent, so an Ed25519 fingerprint works. The connection check reports the key the host presented, ready to pin; with no pin, it reports the ECDSA key.

Console

In the console, go to Devices → Operating systems → macOS and click Add new device. The wizard is the one Windows and Linux devices use. With Agentless chosen, its steps are:

1. General settings: Device name, Director, Deployment type: Agentless, Description (Optional), Tags (Optional)
2. Install and connect: Address, Port, Timeout (Optional), Host key (Optional), Username, and either Password or, with SSH key authentication ticked, Private key and Passphrase (Optional). Check access has the Director log in and confirm the host runs this system; Create device waits for it to pass. A Self-Managed Director skips the check.
3. Data collection: the datasets or profiles the device reads
4. Update management: not offered for an agentless device
5. Review and complete setup

The wizard does not ask for a status or a pre-processing pipeline: the device is created enabled, with no pipeline. Enable device and Disable device are in the device page's Actions menu. Cloning a device opens the same five steps with its settings filled in, and asks again for a password, private key or passphrase typed by hand. A Vault or environment reference is kept.

The device's page is the one a Windows or Linux device has: Device overview, Access settings, Data collection, Health, Live data and Activity logs. Access settings shows the Host key beside the Timeout (Trusted on first use when none is pinned), and Check access in its editor logs in with the stored password or key.

Agent

The sections above describe the Mac read over SSH. The wizard's other Deployment type is Agent: an Agent installed on the Mac reads it, and the Director needs no login there. The Agent needs a Director or cluster on version 2.3.1 or later; the wizard says so when an older one is chosen. Install and connect shows the command that installs the Agent on the Mac.

Updates

The Agent is updated through its Director, as a Windows or Linux Agent is. The wizard goes through the Update management step, and the device page has an Update management tab, after Data collection. The organization's update settings apply unless Custom update policy is turned on; see Updates.

An update stops the Agent's launchd service, replaces the Agent and starts the service again.

Examples

Password Authentication

Reading a Mac's inventory hourly and its metrics every minute, with a password login...

- id: 471209403 name: mbp-dev-01 type: macos status: true properties: address: "192.0.2.40" username: "vmetric" password: "$secret{unix/mbp-dev-01}" definitions: - name: macos_inventory_collector status: true - name: macos_metrics_collector status: true

Key Authentication with a Pinned Host Key

Logging in with an SSH key and pinning the host's key, so no key is trusted on first use...

- id: 471209405 name: mac-build-01 type: macos status: true properties: address: "mac-build-01.example.com" username: "vmetric" key_based: true private_key: "$secret{unix/collector-key}" host_key: "SHA256:<fingerprint>" definitions: - name: macos_metrics_collector status: true