Tag Archives: Linux

Setup OpenZWave on Home Assistant under CentOS 8

Introduction

Home Assistant Legacy Z-Wave Integration
Home Assistant Legacy Z-Wave Integration
In an earlier blog I created on how to set up Home Assistant natively using CentOS 8. I explained how you can set Z-Wave using a platform that the Home Assistant team plan on eventually retiring. They’re making room for a new and improved way of doing things; that’s what this blog focuses on.

The new method of setting up Z-Wave with Home Assistant is still in Beta (at the time of writing this blog) and is called OpenZWave. It is more than stable enough to add to your environment if you want to try it out.

While OpenZWave’s integration into Home Assistant is a little more complicated to set up (more moving parts too), it is a completely separately maintained component; this is a good thing! Z-Wave integration becomes much easier to maintain as a separate system (with separate release schedules).

OpenZWave Home Assistant Integration
The New OpenZWave Home Assistant Integration

Requirements

Aeon Labs - Aeotec Z-Wave Z-Stick - Gen5 - ZW090It is presumed that you have a Z-Wave Hub that is plugged into the same server hosting Home Assistant.If everything is working as expected, you should see a device (visible as /dev/ttyXXXN) that you can interact with.

I personally own a Gen5 Aeon Labs Aeotec Z-Wave Z-Stick which shows up as /dev/ttyACM0 on my system.

The other requirements (which are explained further in the next sections):

  1. A MQTT Server (Mosquitto)
  2. The OpenZWave Daemon

The Setup

MQTT Server

A MQTT is lightweight messaging protocol for small sensors and mobile devices, optimized for high-latency or unreliable networks. This becomes the channel to which OpenZWave can report all of your devices back to Home Assistant with. You also use this medium to trigger, and update your devices as well. Home Assistant recommends we use Mosquitto which is a light weight free tool that works great. It’s installation and setup is as easy as:

# Install Mosquitto
sudo dnf install -y mosquitto
# Start it up
sudo systemctl start mosquitto
# Enable it
sudo systemctl enable mosquitto

To get this configured in Home Assistant, you just need to add the following line to your configuration.yaml file:

# Example configuration.yaml entry
# If you followed my earlier blog, this just has to go anywhere in
# /etc/homeassistant/configuration.yaml
mqtt:
  broker: localhost

The OpenZWave Daemon

The OpenZWave Daemon is the key component that communicates to and from all of your Z-Wave devices and relays their status through the MQTT server (for Home Assistant to interpret). We can install this easily through Snapcraft:

# First you need snap installed
sudo dnf install -y snapd
sudo systemctl enable --now snapd.socket
 
# You just need  log out and back in again
# to run the next few commands (because of new environment variables
# put in place)... but this is easier; log in a root with a fresh
# environment set up:
sudo su -
 
# Install Snap
snap install ozwdaemon
 
# Get our configuration
snap get ozwdaemon -d
 
# I had to set a few things myself.  This is not really my network key
# but it's what you may need to do if you're coming from the old z-wave
# configuration; you'll want to re-import your secure key so you can still
# talk to your secure devices:
snap set ozwdaemon ozw.network-key=0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01

# By default it is already set up to use an mqtt server installed on
# localhost.  So no changes are needed here.

# It is also by default looking for your Z-Wave Hub at /dev/ttyACM0
# While this works great for me (requiring no change at all), you can
# set yours to whatever path you need like so:
snap set ozwdaemon usb-path=/dev/ttyACM0

# Connect our device to our Z-Wave USB device we configured
snap connect ozwdaemon:raw-usb

# Set up our dameon to start and restart if we ever restart our pc
snap start --enable ozwdaemon.ozwdaemon

At this point you can add the OpenZWave Integration inside Home Assistant. It should detect everything if all of the instructions went well above. This is done by:

  1. Click on Configuration which is on the left hand side when logged into Home Assistant using an Administrator account
  2. Click on Add Integration
  3. Search for OpenZWave
  4. Choose to Add this Integration

Troubleshooting

You can follow the OpenZWave logs as follows if you run into any issues:

# Follow our logs:
snap logs ozwdaemon -f
# or snapd:
journalctl -u snapd -f

You can also increase the logs provided by Home Assistant for the 2 things in question to help isolate any issues; simply add the following to your Home Assistant’s configuration.yaml file:

# Extra Z-Wave/MQTT Logging configuration.yaml entry
# If you followed my earlier blog, this just has to go anywhere in
# /etc/homeassistant/configuration.yaml
logger:
  logs:
    homeassistant.components.ozw: debug
    homeassistant.components.mqtt: debug

Older versions of the Home Assistant OpenZWave front end do not handle secure nodes properly which was identified here.

Credit

If you like what you see and wish to copy and paste this HOWTO, please reference back to this blog post at the very least. It’s really all I ask. Alternatively, I certainly won’t turn down a coffee if you wish to buy me one! πŸ™‚

Sources

The Perfect Home Assistant CentOS 8 Installation

Introduction

If you have a dedicated server that you want to set up Home Assistant on and would like to run it natively (not in a container), then this is the tutorial for you. This tutorial focuses on using CentOS 8 because I am personally familiar with RedHat based products. But those who chose to use Ubuntu, Debian, Alpine, Arch, etc should be able to benefit from a good chunk of the information explained here too.

Minimum Requirements

While Home Assistant works awesome on a Raspberry Pi for simple things, it can start to get sluggish and feel under-powered over time as you get addicted like the rest of us and continue to add automations to it. It specifically takes a hard it once you start adding automations that involve video and get fancy with others.

nuc6i5syh
Intel Nuc Kit nuc6i5syh
Thus, if you’re a hobbyist who plans on continuing to evolve your homes automation over time, a Raspberry Pi is not good enough. A small PC (and this tutorial of course πŸ˜‰ ) is the best way to go.

I am personally using a very old (outdated) model of an Intel Nuc that works great. But even if you just have an old PC lying around in the corner, that would be a fantastic choice too! Despite the official requirements identified here, for the most optimal experience (in my opinion), your Home Assistant PC should have:

Type My Suggested Minimum Requirement
RAM 8GB
CPU >= Intel i5
Network >=100Mbit/s
It’s strongly recommended that the server you choose to set up Home Assistant utilize a physical network cable and not WiFi.
Storage >=32GB
Storage is only really important if you plan on installing home surveillance (specifically video cameras). If you do, then target your storage to be at least 512GB or more instead. This will allow you to record with them and save the content locally (should you choose to do this).

Here is the breakdown of where the storage all goes (with respect to this tutorial):

Path Size Details
/etc/homeassistant/ 1GB Your configuration files are small (less then 256KB), however Home Assistant maintains what is called a Recorder which tracks itself in an SQLite database. This SQLite database tends to grow over time in size (which you can control). This is also the location of your homeassistant.log file which can also grow in size as well. By giving yourself (at least) 1GB here, you just provide enough room for future growth that will never interrupt your setup over time. More on the contents of this directory is discussed near the end of this blog.
/opt/homeassistant/ 2GB The entire installation of Home Assistant will sit here once you’ve completed this tutorial. The actual installation (with most bells and whistles) is just under 1GB. 2GB is just a suggested size because it will leave you with plenty of room for future growth.
/ 6GB Your root filesystem and all the core directories that go with it such as /boot, /tmp, /home, /usr, /var, … etc.
6GB is more than enough to host the Linux operating system and all of it’s needs while still leaving you ample space for growth.
/opt/homeassistant/video/ >128GB I’m just throwing this in here… Those who don’t have video recording cameras at their home (inside and out) can ignore this. But consider at LEAST 32GB per camera depending on how much you want to record. You may also want to plan for an expansion down the road too; I said >=512GB earlier and I meant it. Storage is cheap these days, so plan properly at the start.

Download the latest copy of CentOS 8 and stick it on a spare USB Drive you have and/or burn it to a DVD so that you can install it onto your PC.

The Base Home Assistant Setup

It is assumed at this point that you’ve set up your server or already had one running. Let’s set up a working environment that Home Assistant can work in. It’s important to have root or sudo privileges prior to running the commands below in each section.

General Server Preparation

The safest way to run Home Assistant is with it’s own dedicated user and permissions. The following will set up a working environment for us to build further onto:

# Again.. our basic layout will be:
# User: homeassistant
# HA Config: /etc/homeassistant
# HA Core: /opt/homeassistant

# Prepare our user:
sudo useradd -rm homeassistant \
   --home-dir /opt/homeassistant

# The dialout group allows us to access our external USB
# devices such as the Aeotec Z-Stick Series 5 (which is
# what I use). We want to add our user to this group:
sudo usermod -aG dialout homeassistant

# Prepare our configuration directory
sudo mkdir /etc/homeassistant

# Adjust our permissions
sudo chown -R homeassistant:homeassistant \
   /opt/homeassistant /etc/homeassistant

# Some of the packages later installed with pip3
# require that they are compiled in your environment
# (or it will not work) so the following is also
# required:
sudo dnf install -y gcc make gcc-c++ systemd-devel \
    unzip tar

Python 3.8 Setup

We need to setup Python 3.8 into our CentOS environment because it is the minimum requirement for Home Assistant to work. So basically we have 2 options here: Take the most stable version of v3.8, or take the one manged by CentOS which is sometimes outdated. Either way, I’ve explained both below:

  1. Option 1: The CentOS Maintained Version:
    # Simply install the module
    sudo dnf module -y install python38 python38-devel
    
    # That's it... you're done :)
    
  2. Option 2: The Latest Stable Version:
    sudo dnf install -y bzip2-devel expat-devel gdbm-devel \
        libuuid-devel libffi-devel\
        ncurses-devel openssl-devel readline-devel \
        sqlite-devel tk-devel xz-devel zlib-devel wget \
        gcc make gcc-c++ tar
     
    # At the time this blog was written, the current
    # version was v3.8.5:
    VERSION=3.8.5
    
    #
    # Acquire
    #
    wget https://www.python.org/ftp/python/${VERSION}/Python-${VERSION}.tgz
    tar -xf Python-${VERSION}.tgz
     
    #
    # Configure
    #
    cd Python-${VERSION}
    ./configure --enable-optimizations
    
    #
    # Build
    #
    
    # This step can take a while - so be patient!
    make -j 4
    
    #
    # Install
    #
    
    # This is very safe and will not over-write
    # existing Python that ships with CentOS
    sudo make altinstall
    

Regardless of which route you chose to take, you can test the version out to see if you were successful:

# Test the version out:
python3.8 -V

Surveillance Video Camera Setup

Run the following commands if you have or plan on having surveillance cameras installed into your environment. Feel free to run this at a later time if you want. Basically you need a copy of ffmpeg available if you plan on accessing your camera stream in Home Assistant.

sudo dnf install -y epel-release dnf-utils
yum-config-manager --set-enabled PowerTools
sudo yum-config-manager \
   --add-repo=https://negativo17.org/repos/epel-multimedia.repo
sudo dnf install -y ffmpeg

Home Assistant Installation

Assuming you’ve followed the sections Python 3.8 Setup and General Server Preparation above, we can now install Home Assistant:

# First we switch to our new homeassistant user we created:
sudo -u homeassistant -H -s
 
# Optional SSH Keygen Setup
[ ! -f ~/.ssh/id_rsa.pub ] && \
   ssh-keygen -f ~/.ssh/id_rsa -C "Home Assistant" -q -N ""

# Change to our home directory (if we're not there already)
cd /opt/homeassistant

# Prepare our virtual environment
python3.8 -m venv .

# It's always VERY important you activate your
# environment before you start running pip3
# commands
. ./bin/activate

# Perform our installation:
pip3 install homeassistant home-assistant-frontend \
     homeassistant-pyozw colorlog flask-sqlalchemy

# Return back to our root user
exit

Finally we must create an System D Startup file to make it easy to start/stop our instance of Home Assistant:

# the following will drop us in a startup script we can use with our environment
sudo bash <<EOF
cat << _EOF > /usr/lib/systemd/system/home-assistant.service
[Unit]
Description=Home Assistant
After=network-online.target
 
[Service]
Type=simple
User=homeassistant
ExecStart=/opt/homeassistant/bin/hass -c "/etc/homeassistant"
WorkingDirectory=/opt/homeassistant
PrivateTmp=true
Restart=on-failure
 
[Install]
WantedBy=multi-user.target
_EOF
EOF

# Pick up our new configuration
sudo systemctl daemon-reload

# Make it so Home Assistant starts even after a
# server reboot
sudo systemctl enable home-assistant

# Let's start it up now
sudo systemctl start home-assistant

The final piece of the puzzle is to expose port 8123 to our network so that we can access our instance of Home Assistant:

sudo bash <<EOF
cat << _EOF > /usr/lib/firewalld/services/home-assistant.xml
<?xml version="1.0" encoding="utf-8"?>
<service>
  <short>Home Assistant</short>
  <description>Home Assistant Web Portal</description>
  <port protocol="tcp" port="8123"/>
</service>
_EOF
EOF

# Reload our firewall so it can find our recently
# created configuration file (defined above)
sudo firewall-cmd --reload
 
# Now we'll add our new firewall service
sudo firewall-cmd --zone=public \
   --add-service=home-assistant --permanent

# once again reload our firewall to open our newly
# declared port:
sudo firewall-cmd --reload

Finalizing Your Installation

Home Assistant Initial Login PageYou can now visit your new Home Assistant server at http://ip.to.your.server:8123 and start setting up your account for the first time.

When you first access the page you will be able to create the first system user (also the administrator account) that you can build automations with.

Home Assistant Upgrades

You’ll find that Home Assistant is rapidly expanding and always fixing issues and adding more cool features you can play with. Upgrading Home Assistant is as easy as this:

# Switch to our home assistant user:
sudo -u homeassistant -H -s

# Change to our home directory (if we're not there already)
cd /opt/homeassistant

# It's always VERY important you activate your
# environment before you start running pip3
# commands
. ./bin/activate
 
# Switch to our homeassistant user
pip3 install --upgrade homeassistant

# Return to our user with sudoer's permission
exit

# Restart Home Assistant
sudo systemctl restart home-assistant

A Quick Overview

At this point you should be all set up with a running copy of Home Assistant to play with. Here are some general files and directories that will begin appearing in your server’s filesystem in the /etc/homeassistant/ directory that you may want to know about:

homeassistant.log

All of the logs associated with Home Assistant will show up here. This is a fantastic location to begin your troubleshooting should you run into problems.

configuration.yaml

This is the core configuration that will drive your entire Home Assistant application from this point forward. Any changes to this file will require you to restart Home Assistant for the changes to take effect.

home-assistant_v2.db

This is the Home Assistant Recorder. From within your Home Assistant Dashboard, you can click on History button off of the dashboard to see the contents.

/etc/homeassistant/home-assistant_v2.db example

secrets.yaml

This is a simple file that allows you to map key/value pairs. The idea is to keep all of your passwords and/or tokens that you otherwise want to keep from prying eyes. This file should be given very strict permissions:

# protect this file if you intend to use it
chmod 600 /etc/homeassistant/secrets.yaml

For example, you might use Apprise to send you an email notification. In order to send an email Apprise needs your personal email information. As an example, in your configuration.yaml file you might do this:

# /etc/homeassistant/configuration.yaml
# ...
notify:
  name: apprise
  platform: apprise
  url: !secret apprise_url

Then in your secrets.yaml file you now need an entry for a new keyword you created called apprise_url. Your entry in the secrets.yaml file might look like this:

# /etc/homeassistant/secrets.yaml
# Define your Apprise details in a secure location:
apprise_url: mailto://myuser:mypassword@gmail.com

More details on how secrets work can be found here in the Home Assistant documentation. Also, check out the Apprise wiki to see all of the different services you can notify with it.

automations.yaml

This is where you can begin constructing your own Home Assistant automations once you’ve added a few integrations into Home Assistant.

An example of an automation you might have set up could send us an email using Apprise at sunset:

# /etc/homeassistant/automations.yaml
#
# Utilize Apprise to send a notification
#
alias: "[Interactive] - Sunset Apprise Notice"
trigger:
  platform: sun
  event: sunset

action:
  service: notify.apprise
  data:
    title: "Good evening"
    message: "This sun is setting."

Configuration Backup

No setup is complete without regular backups taking place. The following is just a basic configuration backup setup you can use to get you started:

# For Backups (run these commands as the homeassistant user):
sudo mkdir -p /opt/homeassistant/backups
sudo chown homeassistant.homeassistant /opt/homeassistant/backups

# This is a simple script to get you started:
sudo bash <<EOF
cat << _EOF > /opt/homeassistant/bin/backup.sh
#!/bin/sh
# Create a backup of Home Assistant
TARGET=/opt/homeassistant/backups
SOURCE=/etc/homeassistant
 
[ ! -d "\$TARGET" ] && /usr/bin/mkdir -p "\$TARGET"
[ ! -d "\$TARGET" ] && exit 1
 
tar cfz "\$TARGET/\$(date +'%Y.%m.%d')-config.tgz" -C \$SOURCE . 
RET=\$?
 
# Tidy; Keep X days worth
find -L \$TARGET/ -mindepth 1 -maxdepth 1 -name "*.config.tgz" -mtime +120 -delete
exit \$RET
_EOF
EOF

# Permissions to be executable
sudo chmod 775 /opt/homeassistant/bin/backup.sh

# Prepare ourselves a cron job that will run our backup every week
sudo bash <<EOF
cat << _EOF > /etc/cron.d/homeassistant_backup
0 0 * * 0 homeassistant /opt/homeassistant/bin/backup.sh &>/dev/null
_EOF
EOF

Credit

This blog took me a very (,very) long time to put together and test! If you like what you see and wish to copy and paste this HOWTO, please reference back to this blog post at the very least. It’s really all I ask. Alternatively, I certainly won’t turn down a coffee if you wish to buy me one! πŸ™‚

Sources

Integrate Apprise into Nagios for More Notification Support

Introduction

Apprise is an open source tool that allows you to send a notification through a wide range of messaging services out there (such as Discord, Slack, Telegram, Microsoft Teams, etc). Well when you combine this with Nagios, you open it up to a much larger scope then simply emailing on an alert.

With Apprise you can configure Nagios to text your mobile phone using Amazon’s Web Service, or notify your devops team on Slack and/or Microsoft Teams. You can even trigger an IFTTT event. But it doesn’t just stop there, Apprise already supports over 35+ notification services today (and is always expanding) which means Nagios could leverage all of this too. This blog will explain how you can set up your instance of Nagios to notify more end points then just email.

The Installation

I’m going to presume you have a copy of Nagios already installed. If you don’t you can check out my blog here on how to set up your own copy with CentOS 7. Those who are not using CentOS are certainly not out of luck though, there are lots of blogs out there to get you started.

This blog will assume you have root privileges or have sudoers privileges.

Apprise can be easily added to your system through pip:

# Install Apprise onto the system currently also hosting Nagios
sudo pip install apprise

Configure Nagios

The Nagios configuration files can vary in their location depending on what Linux distribution you’re using. I’m going to just refer to some standard paths used by the stuff I host here (for CentOS/RedHat).

Step 1: Nagios Import Directory

If you’re using the Nuxref RPMs, then you can skip this step and move to the next as you’ll already be configured for this. Those using another distribution will want to update their nagios.cfg to point to a directory we can use to drop in and remove configuration from. The file is presumably going to be located as: /etc/nagios/nagios.cfg):

# Place this anywhere in /etc/nagios/nagios.cfg
# preferably put it near the bottom of the file.

# Definitions for global configuration directory
cfg_dir=/etc/nagios/conf.d

Now make sure this directory exists because this is where we’ll place our new apprise configuration:

# Ensure our global include directory exists that we
# just defined in our nagios.cfg file:
mkdir -p /etc/nagios/conf.d

# Place a dummy file in here so that Nagios doesn't
# throw any errors (as it isn't a fan of include directories
# without configuration files in it).
touch /etc/nagios/conf.d/dummy.cfg

Step 2: Apprise/Nagios Integration

Now we need to let Nagios know about Apprise. We’ll do this by creating the following files called /etc/nagios/conf.d/apprise.cfg

#
# Apprise to Nagios Configuration File
# Place this file as /etc/nagios/conf.d/apprise.cfg
#
# 'notify-host-by-apprise' command definition
define command{
   command_name   notify-host-by-apprise
   command_line   /usr/bin/printf "%b" "- *Notification Type*: $NOTIFICATIONTYPE$\n- *Host*: $HOSTNAME$\n- *State*: \n- *Address*: $HOSTADDRESS$\n- *Info*: $HOSTOUTPUT$\n\n- *Date/Time*: $LONGDATETIME$\n" | /usr/bin/apprise -c /etc/nagios/apprise.yml -n "$HOSTSTATE$" -g "$NOTIFICATIONTYPE$" -t "** $NOTIFICATIONTYPE$ Host Alert: $HOSTNAME$ is $HOSTSTATE$ **"
}
 
# 'notify-service-by-apprise' command definition
define command{
   command_name   notify-service-by-apprise
   command_line   /usr/bin/printf "%b" "*Notification Type*: $NOTIFICATIONTYPE$\n- *Service*: $SERVICEDESC$\n- *Host*: $HOSTALIAS$\n- *Address*: $HOSTADDRESS$\n- *State*: $SERVICESTATE$\n- *Date/Time*: $LONGDATETIME$\n\n*Additional Info*:\n$SERVICEOUTPUT$\n" | /usr/bin/apprise -c /etc/nagios/apprise.yml -n "$HOSTSTATE$" -g "$NOTIFICATIONTYPE$" -t "** $NOTIFICATIONTYPE$ Service Alert: $HOSTALIAS$/$SERVICEDESC$ is $SERVICESTATE$ **"
}

# Register our contact template that we can reference
define contact{
  ; The name of this contact template
  name                             apprise-contact

  ; service notifications can be sent anytime
  service_notification_period      24x7

  ; host notifications can be sent anytime
  host_notification_period         24x7

  ; send notifications for all service states, flapping events,
  ; and scheduled downtime events
  service_notification_options     w,u,c,r,f,s

  ; send notifications for all host states, flapping events,
  ; and scheduled downtime events
  host_notification_options        d,u,r,f,s

  ; send service notifications via email
  service_notification_commands    notify-service-by-apprise

  ; send host notifications via email
  host_notification_commands       notify-host-by-apprise

  ; Don't register this as it is just a template for future
  ; references by contacts who wish to use the apprise plugin
  register                         0
}

Now for every contact we set up going forward, we can point it to use Apprise. By default Nagios usually provides us a contact.cfg file that contains the generic user nagiosadmin. For those using my packaging, you can find this file at /etc/nagios/objects/contacts.cfg; you’ll want to change it to looks like this:

define contact{
  ; Short name of (Nagios) user
  contact_name    nagiosadmin

  ; This next line used to read generic-contact; but we want to switch it
  ; over to our new Apprise based one:
  use             apprise-contact

  ; Full name of user
  alias           Nagios Admin

  ; not important if using apprise-contact (defined above)
  email           nagios@localhost
}

Before you advance to the next step, you’ll want to run a test flight check on your configuration and make sure it validates okay.

# Perform a flight check on our new configuration (as root)
sudo nagios -v /etc/nagios/nagios.cfg

If you get any errors, you should revisit the first part of this blog and try to iron them out before continuing. If everything is error free, then the next step is to reload our instance of Nagios (if it’s running) so it can re-read this configuration. This can be done with the command:

# You will need to be root to do this; send a SIGHUP
# to all instances of nagios running in memory:
sudo killall -HUP nagios

Step 3: Apprise Configuration

Now we need to prepare our Apprise configuration (/etc/nagios/apprise.yml) and fill it with the notification services we want listen for and who we want to pass it to.

We can associate with Nagios notifications types passed to us through tags. Nagios will pass these along one of the following $NOTIFICATIONTYPE$ when an event occurs; these are:

  • PROBLEM: There was an issue with one of the checks.
  • RECOVERY: The issue previously set has been cleared.
  • ACKNOWLEDGEMENT: An outstanding issue has been acknowledged.
  • FLAPPINGSTART: Flapping is a state where a service has a PROBLEM associated with it and then moments later has a RECOVERY. This is the state called FLAPPING. When this process occurs too many times in a row, this alert gets set.
  • FLAPPINGSTOP: The service that was previously FLAPPING is no longer doing so.
  • FLAPPINGDISABLED: Someone just disabled FLAPPING for this service/host.
  • DOWNTIMESTART: The scheduled downtime for this service/host has begun.
  • DOWNTIMEEND: The scheduled downtime is over.
  • DOWNTIMECANCELLED: Someone just cancelled the scheduled downtime for this service/host.

Knowing the above notification types that we’ll receive, here is what an Apprise configuration file located at /etc/nagios/apprise.yml might look like:

# This file should be placed in /etc/nagios/apprise.yml

# NOTE: THIS IS JUST AN EXAMPLE CONFIGURATION FILE. YOU WILL WANT
#       TO CUSTOMIZE YOUR OWN WITH THE SERVICE(S) OF YOUR CHOICE
#       VISIT https://github.com/caronc/apprise TO SEE WHAT IS
#       AVAILABLE AND HOW THEY WORK.

# Identify all of the global notification types we want to flag on.
tag:
  - PROBLEM
  - RECOVERY
  - FLAPPINGSTART
  - FLAPPINGSTOP

# Now we want to define our Apprise URLS; you'll want to visit
# https://github.com/caronc/apprise to see all of the supported
# services and how to build their URLs.
urls:

  # Maybe we want to notify a custom service we're hosting to
  # monitor and track Nagios status; Check out the following 
  # for more details https://github.com/caronc/apprise/wiki/Notify_json

  - json://localhost

  # Maybe we want to notify a Slack channel; more details on this
  # are here: https://github.com/caronc/apprise/wiki/Notify_slack
  - slack://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#nuxref

  # the Apprise YAML configuration is quite powerful, the
  # following prepares the email URL and sends an email to each
  # user identified below:
  - email://user:password@gmail.com
      - to: george@example.com
      - to: admin@example.com

  # More details on the emails can be found here:
  # https://github.com/caronc/apprise/wiki/Notify_email

  # We can also individually disperse the tags in the same config
  # file.  The below tags will override the globals defined above.
  # A use case for this would be that maybe we just want to
  # send certain notification types to say... the DevOps team:
  - email://user:password@gmail.com
      - to: devops@example.com
        tag: DOWNTIMESTART, DOWNTIMEEND, DOWNTIMECANCELLED

Once you’re file is all ready, be sure this file is readable by Nagios (to keep it away from prying eyes), but otherwise you’re all set and ready to go!

# Here is what one might do to protect this apprise configuration
chmod 640 /etc/nagios/apprise.yml
chown nagios.root /etc/nagios/apprise.yml

Verification

To be sure everything works, you may want to just test that you got all of your configuration right You can test this using manually as follows:

# Test our configuration with apprise using the PROBLEM tag
# -vvv for some verbose debugging in-case we need it.
apprise -c /etc/nagios/apprise.yml \
    -n CRITICAL -g PROBLEM \
    -vvv \
    -t "A Test Title" \
    -b "a Test Body"

Here is a screenshot of a test error displayed on gitter.im that was sent by Nagios using Apprise:
Gitter Example

Sources