NATS is an open source high performance messaging system, often described as “a central nervous system for the cloud”. It is capable of routing millions of messages per second, which makes it ideal for connecting microservices and IoT (Internet of Things) devices.
NATS is a PubSub messaging system. In this kind of system, one or more publishers send messages with a certain subject to a message broker and the message broker delivers these messages to any clients, or subscribers of the given subject. Publishers don’t know or even care about subscribers and vice versa. This architecture makes it easy to scale the system and add new capabilities since we can add publishers and subscribers without affecting the rest of the system. This type of system is perfect for monitoring servers and devices; devices can send messages and we can subscribe to those messages to send notifications through email or other means.
In this tutorial, we will install gnatsd
, the official NATS server, as a service and make it accessible in a secure way. We will also create a basic server overload warning system that sends out emails when server load gets too high, using gnatsd
as its message broker.
To complete this tutorial, you will need:
sudo
privileges. You can set up a standard account by following the Initial Server Setup with Ubuntu 16.04.Let’s start by downloading the gnatsd
server and making sure it runs on our system without any issues.
The latest stable gnatsd
release is version 0.9.4 at the time this tutorial was written. You can check the NATS download page for a later version and adapt the commands below as necessary if you’d like to use a newer version.
First, log into your server with your non-root account:
Then, make sure you are in your user’s home directory:
Next, use wget
to download gnatsd
to your server:
The archive you just downloaded is a compressed archive, so you’ll need to install unzip
to extract the files. You can install it with apt
:
Then use unzip
to extract gnatsd
:
Then make gnatsd
executable so you can run it:
Let’s test that we can run gnatsd
by running it from the current directory. Use the following command to start gnatsd
:
The output you see will be similar to this example:
Output[1851] 2016/09/23 05:20:02.247420 [INF] Starting nats-server version 0.9.4
[1851] 2016/09/23 05:20:02.248182 [INF] Listening for client connections on 127.0.0.1:4222
[1851] 2016/09/23 05:20:02.248626 [INF] Server is ready
By default, gnatsd
listens on port 4222
on address 0.0.0.0
which corresponds to all interfaces. Using the --port
argument, you can change the port, and with --addr
you can change the address it listens on. We ran gnatsd
with --addr 127.0.0.1
, so that it is available only within our server and cannot be accessed by external clients. Later in the tutorial, we will secure gnatsd
and open it up to the world.
Press CTRL+C
to shut down gnatsd
.
Now that you know things work, let’s set things up in a more formal way.
On Linux, third party, service-related software is frequently kept under the /srv
directory. We are going to follow that convention and keep NATS-related files under /srv/nats
. We’ll place the gnatsd
executable file in /srv/nats/bin
.
First, create the /srv/nats/bin
folder:
Then move gnatsd
to the /srv/nats/bin
folder:
The server can load its configuration from a file, which will come in handy when we need to modify server settings later in the tutorial. Create the file /srv/nats/gnatsd.config
:
And add the following contents to the file:
port: 4222
net: '127.0.0.1'
This configuration file tells the gnatsd
server to listen on port 4222
on address 127.0.0.1
, just like before, but this time we won’t have to specify those options on the command line.
Let’s run the server again to make sure that we have configured things correctly. Execute the following command to launch gnatsd
using the new configuration file:
The output is similar to what you have seen before:
Output[1869] 2016/06/18 05:30:55.988856 [INF] Starting nats-server version 0.9.4
[1869] 2016/06/18 05:30:55.989190 [INF] Listening for client connections on 127.0.0.1:4222
[1869] 2016/06/18 05:30:55.989562 [INF] Server is ready
Once again, press CTRL+C
to shut down gnatsd
and return to your prompt. Now let’s create a user that will run this service.
It is a good security practice to run each service with its own user account to limit the damage in case a service is compromised. Let’s create a user and group that will own the NATS service and NATS-related files.
First, let’s create a system user and group called nats
:
OutputAdding system user `nats' (UID 106) ...
Adding new group `nats' (GID 114) ...
Adding new user `nats' (UID 106) with group `nats' ...
Not creating home directory `/home/nats'.
We assigned /bin/false
shell to the nats
system user to disable logins for this user and suppressed home directory creation. We also created a nats
group.
Let’s change the owner of the /srv
directory to the nats
user and group:
Now that we have created the nats
user and group, let’s continue with creating the NATS service.
We would like gnatsd
to start when the system boots and restart if it crashes. We’ll use systemd to handle this.
systemd is a service manager for Linux systems. It is responsible for starting services on boot, restarting them as necessary and stopping them in a controlled fashion on system shutdown.
We need to create a service configuration in order to define how and when the NATS service should be started. User-created service files live in /etc/systemd/system
, so create the file /etc/systemd/system/nats.service
:
And in the file, place this script to define how gnatsd
should start up:
[Unit]
Description=NATS messaging server
[Service]
ExecStart=/srv/nats/bin/gnatsd -c /srv/nats/gnatsd.config
User=nats
Restart=on-failure
[Install]
WantedBy=multi-user.target
[Unit]
section contains generic information about the service, such as Description
which describes the service.[Service]
section contains service-related configuration. ExecStart
is the command to run the server. We use the absolute path of the gnatsd
executable here. Restart=on-failure
means that the service must be restarted if it crashes or terminates with a failure. It will not be restarted if it was stopped by systemd.[Install]
section contains installation information about the service. WantedBy=multi-user.target
tells systemd to start the service when starting multi-user.target
. This is a generic way of starting services on system boot.Once the service description is in place, we can start it with the following command:
Let’s confirm that gnatsd
is running by sending a PING
message:
We have just used nc
to communicate with gnatsd
. nc
is a command line utility to communicate with TCP or UDP servers. The command we used prints an output similar to the following:
OutputINFO {"server_id":"Os7xI5uGlYFJfLlfo1vHox","version":"0.9.4","go":"go1.6.3","host":"127.0.0.1","port":4222,"auth_required":false,"ssl_required":false,"tls_required":false,"tls_verify":false,"max_payload":1048576}
PONG
The response PONG
lets us know the server is listening and working as expected. We need to run one last command to make our NATS server start on boot:
You will see the following output which confirms that the service was installed:
OutputCreated symlink from /etc/systemd/system/multi-user.target.wants/nats.service to /etc/systemd/system/nats.service.
We successfully configured gnatsd
to run as a service. Now let’s secure it and make it accessible to external clients.
If all publishers and subscribers we would like to use with gnatsd
ran on the same server, we could call it done and move on but that’s rarely the case these days. We’ll need to let external clients connect and publish messages to gnatsd
in a secure way.
gnatsd
supports TLS transport, so we will use that to secure the communication between gnatsd
and NATS clients.
First, we need a certificate. You can buy a commercial certificate, retrieve one from Let’s Encrypt or generate a self-signed certificate. We will use the latter approach, since acquiring a certificate is out of the scope of this article.
Create a directory to hold the certificate temporarily:
Then create a self-signed certificate with the following command:
This command creates an RSA certificate with 2048 bits and 10 years of validity. Note that we have used an arbitrary domain name since we won’t enable TLS verification for the gnatsd
server in this article.
You should now have the files gnatsd.key
and gnatsd.crt
in the ~/priv
directory. Let’s move those files under our /srv/nats/
directory structure so everything is in one place. Execute the following command:
Now, make /srv/nats/priv
accessible to only to the nats
user and group:
Now we update /srv/nats/gnatsd.config
to contain the certificate and key we just created. Open the configuration file again:
And add the following section to tell gnatsd
to use your certificate and key:
. . .
tls {
cert_file: "/srv/nats/priv/gnatsd.crt"
key_file: "/srv/nats/priv/gnatsd.key"
timeout: 1
}
Save the file and exit the editor. Then restart the service so it can pick up the changes.
Let’s test that our certificates work. Run this command:
This time, the command outputs this message:
OutputINFO {"server_id":"npkIPrCE5Kp8O3v1EfV8dz","version":"0.9.4","go":"go1.6.3","host":"127.0.0.1","port":4222,"auth_required":false,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
-ERR 'Secure Connection - TLS Required'
The server returned the message -ERR 'Secure Connection - TLS Required'
which confirms that the new configuration was picked up and a secure connection is required, which nc
doesn’t know how to do.
In order to be able to communicate with our NATS service without installing a full blown NATS client, we will be using a tool called catnats. Let’s download it first:
And make it executable:
Finally, move catnats.py
to the /srv/nats/bin
folder and rename it to catnats
:
Let’s check that we can communicate with our NATS service using catnats
, by sending the same PING
message we have sent before:
You’ll see this output indicating our connection is secure:
OutputINFO {"server_id":"npkIPrCE5Kp8O3v1EfV8dz","version":"0.9.4","go":"go1.6.3","host":"127.0.0.1","port":4222,"auth_required":false,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
PONG
Now that we have secured the communication, let’s enable authentication so that a username and password is required to connect to NATS.
Our NATS service does not require authentication by default. This is fine when the service is only accessible on a private network, but we want our NATS service accessible on the internet so we should enable authentication. gnatsd
supports username and password authentication, and it is easy to enable.
Open the /srv/nats/gnatsd.config
file:
Add a new authorization
section that specifies the credentials. We will use user1
as the username and pass1
as the password for this tutorial. You should use a longer, more complex password in a production environment:
. . .
authorization {
user: user1
password: pass1
}
Save the file, and then change the owner of /srv/nats/gnatsd.config
to nats
and make it readable by that user in order to protect the username and password from other users on the system:
Then restart the service for the changes to take effect:
Let’s send a PING
message to gnatsd
to check whether everything is OK. Once again, use catnats
to send the message:
You’ll see the following output:
OutputNFO {"server_id":"sY0SSJBNbEw53HxzS9mH1t","version":"0.9.4","go":"go1.6.3","host":"127.0.0.1","port":4222,"auth_required":true,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
-ERR 'Authorization Violation'
This tells us that the changes were successfully applied and we now need to send the correct username and password in order to connect to the service. Let’s try again, this time providing the username user1
and password pass1
:
This time it worked, as you can see from the following output:
OutputINFO {"server_id":"sY0SSJBNbEw53HxzS9mH1t","version":"0.9.4","go":"go1.6.3","host":"127.0.0.1","port":4222,"auth_required":true,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
+OK
PONG
Now that we’ve restricted this service to clients that know the username and password, we can reconfigure the service so outside clients can connect.
We’ve configured our NATS server to listen on 127.0.0.1
, which is the local interface. If we make it listen on 0.0.0.0
, then it will be available to the world. Let’s update /srv/nats/gnatsd.config
one last time:
Then change the IP address associated with the net
setting:
. . .
net: '0.0.0.0'
. . .
Save the file and restart the service:
And now our NATS service is ready for external client connections. To learn how to use it, let’s create a simple monitoring service that uses our NATS server as a message broker.
In this section, you will create a simple overload monitoring system that makes use of your NATS service. The system will receive load averages of servers and send an email to an administrator if any of the servers are overloaded.
The sample project will consist of the following components:
stats.loadaverage
subject every 60 seconds. You need to run this component on any server you would like to monitor for load.stats.loadaverage
subject and receives the host name, load average and processor count of a server. If the load average of a host is above a certain threshold, the notifier sends an email to a predefined address through an SMTP server.We will run all of these components on the same server for simplicity, but you can try running each component in a different server when you’ve completed this tutorial.
You can read the average load on a Linux system from /proc/loadavg
. For this project, we are interested only in the load average of the last minute, which is the first field of the output. Use this command to get that value:
You’ll see the following output:
Output0.11
The load average you get by reading /proc/loadavg
depends on the number of processors, so you have to normalize it by dividing the load average by the number of processors. You can use the following command to get the processor count of your server:
You’ll see the result displayed in your terminal:
Output1
Since the default shell of our server cannot deal with floating number arithmetic, we will send both the load average and number of processors together with the host name as the payload of our message and do the division in the notifier later. Here’s the command we’ll use to construct the payload:
The command displays the hostname, the load average, and the number of processors, respectively:
Outputyour_hostname 0.28 1
Let’s create a shell script which publishes the host name, load average and processor count to our NATS server with the subject stats.loadaverage
. We’ll configure our system to run this script periodically. Create a new file called ~/publish_load_average.sh
:
In the file, add this script:
NATS_ADDR=127.0.0.1:4222
LOADAVG=$(cat /proc/loadavg | cut -f1 -d" ")
NPROC=$(getconf _NPROCESSORS_ONLN)
SUBJECT="stats.loadaverage"
PAYLOAD=$(echo $(hostname) $LOADAVG $NPROC)
MESSAGE="PUB $SUBJECT ${#PAYLOAD}\r\n${PAYLOAD}\r\n"
printf "$MESSAGE" | /srv/nats/bin/catnats -q --raw --addr $NATS_ADDR --user user1 --pass pass1
This script creates the message and then pipes it to catnats
, which publishes the message to the NATS service. We run catnats
with the -q
switch to suppress any output, and we use the --raw
switch so catnats
doesn’t try to interpret the contents of the input. You can change the $NATS_ADDR
variable’s value if the NATS service are on different servers.
Let’s test that the script sends load averages to NATS.
The following command runs ~/publish_load_average.sh
every 5 seconds. Note that we use the &
character at the end of line to run the command in the background:
You’ll see output showing that the command is running in the background with a process ID:
Output[1] 14123
Note: Jot down the process ID somewhere, since you will need to use the ID to stop the command later.
Now connect to NATS and subscribe to the subject stats.loadaverage
to retrieve load averages:
We use the --no-exit
flag to disable auto-exit, and --pong
to keep our connection to NATS alive. If everything is correct, you should get an output similar to the following which will update every 5 seconds:
OutputINFO {"server_id":"A8qJc7mdTy8AWBRhPWACzW","version":"0.8.1","go":"go1.6.2","host":"0.0.0.0","port":4222,"auth_required":true,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
+OK
+OK
MSG stats.loadaverage 0 27
your_hostname 0.08 1
Press CTRL+C
to exit from catnats
. Let’s stop the loop that called publish_load_average.sh
too since we are going to have a better way of running publish_load_average.sh
:
The approach we just took works great for testing, but it’s not something we want to use permanently. We would like the system to run publish_load_average.sh
to run every minute. In order to accomplish that, we can add a crontab entry. Linux systems use cron
, a system that can run commands, or “jobs”, on a schedule we specify. The crontab
command lets us manage these jobs. You can learn all about Cron in the tutorial How To Use Cron To Automate Tasks On a VPS.
To create a new entry, execute the command:
If you have never run the command above, you may see the following prompt which will ask you to choose a text editor to manage entries:
Outputno crontab for demo - using an empty one
Select an editor. To change later, run 'select-editor'.
1. /bin/ed
2. /bin/nano <---- easiest
3. /usr/bin/vim.basic
4. /usr/bin/vim.tiny
Choose 1-4 [2]:
Type the number corresponding to the editor you are most comfortable with and press ENTER
. A file will be displayed in the editor you’ve chosen.
At the end of the opened file, add the following line, but substitute your username if you’ve used something other than sammy
:
*/1 * * * * bash /home/sammy/publish_load_average.sh
The entry above tells cron
to run our publish_load_average.sh
script every minute. Save the file and close the editor.
Now let’s test that periodic publishing of the load average is working:
Wait for a few minutes, and the output you see will be similar to the following:
OutputINFO {"server_id":"A8qJc7mdTy8AWBRhPWACzW","version":"0.8.1","go":"go1.6.2","host":"0.0.0.0","port":4222,"auth_required":true,"ssl_required":true,"tls_required":true,"tls_verify":false,"max_payload":1048576}
+OK
+OK
MSG stats.loadaverage 0 27
your_hostname 0.01 1
MSG stats.loadaverage 0 27
your_hostname 0.00 1
Press CTRL+C
to exit catnats
.
We have successfully set up the monitor, and it’s sending messages to our NATS server. Next, we’ll set up the notifier that makes use of this data.
Let’s create the notifier which connects to our NATS service and listens for stats.loadaverage
messages. Whenever our program receives a message, it calculates the load average per processor. If it is higher than 0.6, or 60% CPU utilization per processor, it sets a warning flag for the host that published the message and sends an email to a predefined address. If the load average per processor is less than 0.4, the warning flag for the host is cleared. To prevent flooding the inbox, we send a single email when the warning flag is set.
We will use Node.JS to create the notifier, as there’s a great NATS client for Node.js. So, install Node.js first:
Next, create the directory for the notifier and switch to it:
Node.js projects use a file called package.json
which contains information about the project and its dependencies. Execute the following command to create that file:
Then install the NATS client for Node.js, as well as the nodemailer
module which we’ll use in this project to send warning emails:
Now we can create the notifier. Create the file notifier.js
:
Then add the following code to the file:
Be sure you change these options to match your username and password for the NATS service, as well as your email address.
Next, add this code to import the Node.js NATS client and connect to the gnatsd
service:
Then add this code to set up the mailer and connect to the SMTP server which will send the emails. We’ll set this server up shortly:
Then add the rest of the code to calculate the load average and determine whether or not we need to send a notification email:
We subscribe to the message, and every time we receive a message we execute the processMessage
function, which parses the payload we sent and determines the load average. If it’s too high, we send the message, and we track if we’ve previously sent one by setting a flag based on the hostname. This way we can track notifications on a per-host basis. If the load average is below our threshold, we clear that flag.
With the monitor and notifier in place, it’s time to test our sample project.
Let’s take this for a test drive. We are going to generate some artificial load and check whether the notifier will send the warning email when the load gets too high.
Let’s install the stress
tool to generate CPU load on our server:
Next we need to set up an SMTP server to mail out the messages from our notifier. Installing and configuring a full-blown SMTP server would be overkill for this test, so we are going to use a simple SMTP server which just displays the emails handed to it instead of actually sending them. The Python programming language has a DebuggingServer
module we can load that discards emails it receives, but displays them to the screen so we can ensure things work. Python is already installed on our Ubuntu server, so this is a perfect solution.
Let’s start the debugging SMTP server in the background. We’ll make it listen on localhost
port 2525
, which matches the SMTP address we configured in our notifier.js
code. Execute this command to start the SMTP server:
Then start the notifier in the background with this command:
And lastly, let’s generate some load on all processors of our server. Execute the stress
command with the following options:
After a few minutes, you’ll see output similar to the following, as the SMTP server starts displaying the messages sent by the notifier:
Output---------- MESSAGE FOLLOWS ----------
Content-Type: text/plain
To: admin@example.com
Subject: Warning! Server is Overloaded: your_hostname
Message-Id: <1466354822129-04c5d944-0d19670b-780eee12@localhost>
X-Mailer: nodemailer (2.4.2; +http://nodemailer.com/;
SMTP/2.5.0[client:2.5.0])
Content-Transfer-Encoding: 7bit
Date: Sun, 19 Jun 2016 16:47:02 +0000
MIME-Version: 1.0
X-Peer: 127.0.0.1
Load average: 0.88
------------ END MESSAGE ------------
This lets you know you’ve successfully sent emails when the load gets too high on the server.
Press CTRL+C
to stop generating load. You’ve completed the sample project and should now have a good idea how to make this work for you in your own environment.
In this article, you learned about the NATS PubSub messaging system, installed it in a secure way as a service, and tested it in a sample project. The sample project used the Node.JS client, but NATS has clients for more languages and frameworks which you can find listed on the NATS download page. You can learn more about NATS in its official documentation.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!