SSL Configuration

Reference documentation

How does Sensu use SSL?

All communication between Sensu services happens via the Sensu transport. As such, to secure a Sensu installation means to secure communication between all of the Sensu services and the Sensu transport via SSL encryption. Sensu can operate without the use of SSL encryption, however, this practice is heavily discouraged.

SSL-secured Transports

Although the Sensu transport library makes it possible for Sensu to leverage transport alternatives to RabbitMQ (e.g. Redis), not all transports offer SSL support (e.g. Redis does not support SSL). For this reason, this reference document will focus on SSL security for Sensu with the RabbitMQ transport.

Configuring Sensu + RabbitMQ for SSL encryption

Generate self-signed OpenSSL certificates and CA

The following instructions will generate an OpenSSL certificate authority and self-signed certificates. Alternatively, please refer to the official RabbitMQ SSL documentation for a detailed guide on configuring RabbitMQ with SSL.

  1. OpenSSL is required on the machine that will generate the SSL certificates. Install OpenSSL on your platform: 

    sudo apt-get update
sudo apt-get install openssl
openssl version
    sudo yum install openssl
openssl version

  2. Download the Sensu SSL tool 

    wget http://docs.sensu.io/sensu-core/1.9/files/sensu_ssl_tool.tar
tar -xvf sensu_ssl_tool.tar

  3. Generate an OpenSSL certificate authority and self-signed certificates using the Sensu SSL tool: 

    cd sensu_ssl_tool
./ssl_certs.sh generate
ls -l
    NOTE: the generated certificates will be valid for 5 years. The Sensu SSL tool will generate a certificate authority, SSL certificates for the RabbitMQ server, and a shared SSL certificate for all of the Sensu services. 
    ├── client
│   ├── cert.pem
│   ├── keycert.p12
│   ├── key.pem
│   └── req.pem
├── sensu_ca
│   ├── cacert.cer
│   ├── cacert.pem
│   ├── certs
│   │   ├── 01.pem
│   │   └── 02.pem
│   ├── index.txt
│   ├── index.txt.attr
│   ├── index.txt.attr.old
│   ├── index.txt.old
│   ├── openssl.cnf
│   ├── private
│   │   └── cakey.pem
│   ├── serial
│   └── serial.old
├── server
│   ├── cert.pem
│   ├── keycert.p12
│   ├── key.pem
│   └── req.pem
└── ssl_certs.sh

Enable RabbitMQ SSL support

  1. Stop RabbitMQ NOTE: The service command will not work on CentOS 5, the sysvinit script must be used, e.g. sudo /etc/init.d/rabbitmq-server stop 

    sudo service rabbitmq-server stop

  2. Please refer to the official RabbitMQ documentation for enabling SSL support for instructions on installing the certificate authority and SSL certificates, and configuring the RabbitMQ ssl_listeners and ssl_options directives. NOTE: the RabbitMQ documentation will direct you to provide the location of three certificate files: cacertfile, certfile, and keyfile. These files correspond to the sensu_ca/cacert.pem, server/cert.pem, and server/key.pem files generated by the Sensu SSL tool (above). We recommend copying these files to the RabbitMQ server in a new /etc/rabbitmq/ssl/ directory. When complete, your /etc/rabbitmq/rabbitmq.config file should contain the following configuration block: 

    [
 {rabbit, [
    {ssl_listeners, [5671]},
    {ssl_options, [{cacertfile,"/etc/rabbitmq/ssl/cacert.pem"},
                   {certfile,"/etc/rabbitmq/ssl/cert.pem"},
                   {keyfile,"/etc/rabbitmq/ssl/key.pem"},
                   {versions, ['tlsv1.2']},
                   {ciphers,  [{rsa,aes_256_cbc,sha256}]},
                   {verify,verify_peer},
                   {fail_if_no_peer_cert,true}]}
  ]}
].
    NOTE: If using multiple CAs, it may be necessary to include the {depth, 2}, parameter under ssl_options. For more information about this attribute, see the RabbitMQ SSL Reference documentation.

  3. Start RabbitMQ NOTE: The service command will not work on CentOS 5, the sysvinit script must be used, e.g. sudo /etc/init.d/rabbitmq-server start 

    sudo service rabbitmq-server start

Configure Sensu

  1. Install the self-signed SSL certificates generated above by copying the client/cert.pem and client/key.pem files to the /etc/sensu/ssl/ directory on all systems running Sensu processes (e.g. the Sensu server, API, and client(s)).

  2. Add ssl definition attributes to your Sensu RabbitMQ configuration. Please note the following standalone configuration example, a JSON configuration file located at /etc/sensu/conf.d/rabbitmq.json. Please see the ssl attributes section of the RabbitMQ reference documentation for more information. 

    {
  "rabbitmq": {
    "host": "127.0.0.1",
    "port": 5671,
    "vhost": "/sensu",
    "user": "sensu",
    "password": "secret",
    "heartbeat": 30,
    "prefetch": 50,
    "ssl": {
      "cert_chain_file": "/etc/sensu/ssl/cert.pem",
      "private_key_file": "/etc/sensu/ssl/key.pem"
    }
  }
}
    WARNING: please note that by default, RabbitMQ will listen for SSL connections on port 5671 instead of 5672, so if you are upgrading an existing configuration, please ensure that all Sensu services are attempting to connect to RabbitMQ on "port": 5671.

  3. Restart the Sensu services.

Known limitations

You may have noticed that the instructions above only generated a single client certificate. Ideally, every SSL connection would use a different certificate, allowing them to be individually revoked. There is currently no way to tell RabbitMQ to reject a certificate. If the integrity of a certificate is compromised, it is common practice to regenerate and redistribute the certificate authority and certificates. This process is greatly simplified with the use of configuration management tools. In the future, the Sensu project hopes to be able to provide a better mechanism for distributing individual certificates and providing fast/simple revocation facilities.