Sensu on Mac OS X

Install Sensu Core

Sensu Core is installed on Mac OS X systems via a native system installer package (i.e. a .pkg file), which is available for download from the Sensu Downloads page, and from this repository.

WARNING: Mac OS X packages are currently as a “beta” release. Support for running Sensu on Mac OS X will be provided on a best-effort basis until further notice.

Download and install Sensu using the Sensu Universal .pkg file

  1. Download Sensu from the Sensu Downloads page, or via the curl utility

    curl -LO

    NOTE: the Universal .pkg file supports OS X “Mavericks” (10.9) and newer. Mountain Lion users: please use this installer.

  2. Install the package using the installer utility

    sudo installer -pkg sensu-0.26.1-1.pkg -target /
  3. Configure the Sensu client. No “default” configuration is provided with Sensu, so the Sensu Client will not start without the corresponding configuration. Please refer to the “Configure Sensu” section (below) for more information on configuring Sensu. At minimum, the Sensu client will need a working transport definition and client definition.

Configure Sensu

By default, all of the Sensu services on Mac OS X systems will load configuration from the following locations:

  • /etc/sensu/config.json
  • /etc/sensu/conf.d/

NOTE: additional or alternative configuration file and directory locations may be used by modifying Sensu’s launchd daemon configuration XML and/or by starting the Sensu services with the corresponding CLI arguments. For more information, please see the configure the Sensu client launchd daemon section, below.

The following Sensu configuration files are provided as examples. Please review the Sensu configuration reference documentation for additional information on how Sensu is configured.

Create the Sensu configuration directory

In some cases, the default Sensu configuration directory (i.e. /etc/sensu/conf.d/) is not created by the Sensu installer, in which case it is necessary to create this directory manually.

mkdir /etc/sensu/conf.d

Example client configuration

  1. Copy the following contents to a configuration file located at /etc/sensu/conf.d/client.json:

      "client": {
        "name": "macosx",
        "address": "",
        "environment": "development",
        "subscriptions": [
        "socket": {
          "bind": "",
          "port": 3030

Example Transport Configuration

At minimum, the Sensu client process requires configuration to tell it how to connect to the configured Sensu Transport.

  1. Copy the following contents to a configuration file located at /etc/sensu/conf.d/transport.json:

      "transport": {
        "name": "rabbitmq",
        "reconnect_on_error": true

    NOTE: if you are using Redis as your transport, please use "name": "redis" for your transport configuration. For more information, please visit the transport definition specification.

  2. Please refer to the configuration instructions for the corresponding transport for configuration file examples (see Redis, or RabbitMQ reference documentation).

Configure the Sensu client launchd daemon

The Sensu Core .pkg package includes a Sensu client daemon configuration, allowing Sensu to be run as a launchd job, or daemon. The OS X launchd service and launchctl utility use a “plist” file (an XML-based configuration file) to configure the sensu-client daemon run arguments (e.g. --log /var/log/sensu/sensu-client.log).

  1. To configure the Sensu client service wrapper, copy the default service definition file entitled org.sensuapp.sensu-client.plist to /Library/LaunchDaemons/org.sensuapp.sensu-client.plist and edit it with your favorite text editor.

    sudo cp /opt/sensu/embedded/Cellar/sensu/0.26.0/Library/LaunchDaemons/org.sensuapp.sensu-client.plist /Library/LaunchDaemons/org.sensuapp.sensu-client.plist
  2. This XML configuration file allows you to set Sensu client CLI arguments. The following example configuration file sets the Sensu client primary configuration file path to /etc/sensu/config.json, the Sensu configuration directory to /etc/sensu/conf.d, and the log file path to /etc/sensu/sensu-client.log.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN>
    <plist version="1.0">

Operating Sensu

Managing the Sensu client process with launchctl

Start or stop the Sensu client using the launchctl utility:

sudo launchctl load -w /Library/LaunchDaemons/org.sensuapp.sensu-client.plist
sudo launchctl unload -w /Library/LaunchDaemons/org.sensuapp.sensu-client.plist

Interacting with Sensu via CLI

Interacting with the any of the installed Sensu processes (e.g. sensu-client) via CLI on Mac OS X requires running the processes as the _sensu user, which is installed by the Sensu OS X installer package.


$ sudo -u _sensu /opt/sensu/bin/sensu-client -V

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.