Installation

Stable release

To install K2hR3 OpenStack Notification Listener, run this command in your terminal:

$ sudo pip install k2hr3_osnl

This is the preferred method to install K2hR3 OpenStack Notification Listener, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

Configuration

There are two primary configurations in k2hr3_onsl.conf:

• transport_url

  The message queue server location with an username and a password.

• api_url

  The k2hr3 WebApi server location.

The following figure can help you to understand the transport_url and api_url:

The k2hr3_osnl.conf path depends on the pip command shipped in your OS. You can get the path by two commands.

$ sudo pip3 show -f k2hr3_osnl
Name: k2hr3-osnl
...
Location: /usr/local/lib/python3.5/dist-packages
Requires: oslo.messaging, oslo.config
Files:
  ../../../bin/k2hr3_osnl
  ../../../etc/k2hr3/k2hr3_osnl.conf
...
$ python -c "
> import os;
> print(
>   os.path.abspath(
>     '/usr/local/lib/python3.5/dist-packages/../../../etc/k2hr3/k2hr3_osnl.conf'
>   )
> );
> "
/usr/local/etc/k2hr3/k2hr3_osnl.conf

/usr/local/etc/k2hr3/k2hr3_osnl.conf is it. You should change the transport_url and the api_url setting for your environment.

[DEFAULT]
debug_level = error

[oslo_messaging_notifications]
event_type = ^port\.delete\.end$
publisher_id = ^network.*$
transport_url = rabbit://user:pass@127.0.0.1:5672/
topic = notifications
exchange = neutron

[k2hr3]
api_url = https://localhost/v1/role
allow_self_signed_cert = False

FYI: The Usage page describes every setting parameters.

Start

This chapter instructs how to install the listener.

$ sudo k2hr3_osnl -c /path/to/k2hr3_osnl.conf

No error means the listener successfully starts to listen to the next notification message.

Service Management

While you have already successfully started the listener, you would like to prepare for following troubles.

• The listener process is dead after the OS rebooted.
• The listener is dead when you have stopped the terminal which started the listener.

Most of modern OSs provide the way to register a process as a service to the service management system which launches them at boot time and stops them at shutdown. systemd is one of such a service which is installed in Debian 9, Fedora 28, CentOS 7 and other recent Linux distributions.

An example of what systemd config file might look like is:

[Unit]
Description=k2hr3_osnl
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/tmp
Environment=HOME=/tmp
User=nobody
Group=nobody
ExecStart=/usr/local/bin/k2hr3_osnl -c /usr/local/etc/k2hr3/k2hr3_osnl.conf
Restart=on-failure
PIDFile=/var/run/k2hr3_osnl.pid

[Install]
WantedBy=multi-user.target

FYI: systemd.unit and systemd.service page describe meaning of parameters.

The syntax is the “.INI” style. ExecStart specifies the absolute k2hr3_osnl path. The path depends on your OS. I found it in /usr/local/bin/k2hr3_osnl in my environment.

$ which k2hr3_osnl
/usr/local/bin/k2hr3_osnl

After update the ExecStart, save the configuration to the /lib/systemd/system/k2hr3_osnl.service and register it to systemd. Please note the systemd configuration path depends on you OS.

$ sudo systemctl daemon-reload
$ sudo systemctl enable k2hr3_osnl.service

After that, you tell systemd to look for your service at the first command and you tell systemd to enable it at the second command, so that it will start every time the system boots.

Then, you start the k2hr3_osnl as a service.

$ sudo systemctl start k2hr3_osnl.service

You can see the service status:

$ sudo systemctl status k2hr3_osnl.service

If you have got some errors, you should check logs put on stderr at first. Then please send a issue with it from issue.