Installation

This article describes how to install the OpsDash server, as well as the OpsDash agent, on various supported platforms.

Quick Start

If you’re in a hurry, just follow the steps below, but we recommend coming back and reading through the rest of this document later so you can get the most out of OpsDash.

The quick start steps below show how to install from a downloaded .deb or .rpm package. If you’d rather install from an apt or yum repository, follow the steps here.

Server setup:

# for RHEL and similar distros
rpm -ihv opsdash-server-1.13.2-1.x86_64.rpm

# for Debian and similar distros
dpkg -i opsdash-server_1.13.2_amd64.deb

# review the configuration
vim /etc/opsdash/server.cfg

# copy the license file if you have one
cp /path/to/A1B2C-3D4E5-F6G7H-8I9J0-A1B2C.lic /etc/opsdash

# start the daemon
service opsdash-serverd start

Agent setup for Linux:

# for RHEL and similar distros
rpm -ihv opsdash-agent-1.13.2-1.x86_64.rpm

# for Debian and similar distros
dpkg -i opsdash-agent_1.13.2_amd64.deb

# review the configuration
# note: the server IP/hostname is *REQUIRED*
vim /etc/opsdash/agent.cfg

# start the daemon
service opsdash-agentd start

Agent setup for Windows:

Use the installer opsdash-agent-1.12.1-installer.exe to install the OpsDash Agent into the default location of C:\Program Files\OpsDash Agent.
Edit the agent.cfg file in the installation folder with an editor that understands Unix-style line endings. The server’s IP or hostname is required.
Start the service OpsDash Agent from the UI or using net start opsdashagent.

The dashboard for the server on which the agent is installed should start showing up on the OpsDash server web UI (http://your.server:8080/) in a couple of minutes. There are logs at /var/log/opsdash if you need to troubleshoot.

Quick Start with Repositories

OpsDash server and agent packages are also available in the RapidLoop yum (i686, x86_64) and apt (i386, amd64, armhf) repositories. The repositories contain only binary packages.

Using the RapidLoop yum repo

Create the file /etc/yum.repos.d/rapidloop.repo with the following contents:

[rapidloop]
name=RapidLoop Public YUM Repository
baseurl=https://packages.rapidloop.com/centos
gpgkey=https://packages.rapidloop.com/gpg-pubkey-rapidloop.asc

Import the RapidLoop signing key:

# download the key
wget https://packages.rapidloop.com/gpg-pubkey-rapidloop.asc

# import it
rpm --import gpg-pubkey-rapidloop.asc

Update the local metadata:

yum update

Install the OpsDash server:

# install the package
yum install opsdash-server

# review the configuration
vim /etc/opsdash/server.cfg

# copy the license file if you have one
cp /path/to/A1B2C-3D4E5-F6G7H-8I9J0-A1B2C.lic /etc/opsdash

# start the daemon
service opsdash-serverd start

Install the OpsDash agent:

# install the package
yum install opsdash-agent

# review the configuration
# note: the server IP/hostname is *REQUIRED*
vim /etc/opsdash/agent.cfg

# start the daemon
service opsdash-agentd start

Using the RapidLoop apt repo

Create the file /etc/apt/sources.list.d/rapidloop.list with the following contents:

deb http://packages.rapidloop.com/debian stable main

Import the RapidLoop signing key:

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1E1BACF5

Update the local metadata:

apt-get update

Install the OpsDash server:

# install the package
apt-get install opsdash-server

# review the configuration
vim /etc/opsdash/server.cfg

# copy the license file if you have one
cp /path/to/A1B2C-3D4E5-F6G7H-8I9J0-A1B2C.lic /etc/opsdash

# start the daemon
service opsdash-serverd start

Install the OpsDash agent:

# install the package
apt-get install opsdash-agent

# review the configuration
# note: the server IP/hostname is *REQUIRED*
vim /etc/opsdash/agent.cfg

# start the daemon
service opsdash-agentd start

Note: The RapidLoop apt repository is also accessible via https. If your distro supports it, we recommend that you install the apt-transport-https package and use the https form of the URL in /etc/apt/sources.list.d/rapidloop.list.

The RapidLoop Signing Key

The packages and metadata are signed by RapidLoop Packager <packager@rapidloop.com>. The GPG public key is available on the keyserver.ubuntu.com keyserver and has the following fingerprint:

c7b0 d569 65ee ba86 1263 afad c001 e068 1e1b acf5

The following sections cover the installation and configuration steps in detail.

Installing the Server

The OpsDash server (and agents) can be run on most popular Linux distros, running on the following hardware (bare-metal or virtualized):

x86_64 (aka amd64, 64-bit Intel architecture)
i386 (32-bit Intel architecture)
armv7 (ARM v7 LE with hardware FPU)
armv6 (ARM v6 LE with hardware FPU)

The server is available as an RPM package that can be installed on the following Linux distros:

It is also available as a deb package for the following distros:

Debian
Ubuntu
Raspbian
Other distros derived from Debian

There is also a .tar.gz tarball that can be used in other distros like Arch Linux.

We recommend installing the server first, although it is not mandatory.

To install the .rpm or the .deb, use the standard commands for the appropriate platform:

# for RHEL and similar distros
rpm -ihv opsdash-server-1.13.2-1.x86_64.rpm
yum install opsdash-server

# for Debian and similar distros
dpkg -i opsdash-server_1.13.2_amd64.deb
apt-get install opsdash-server

Configuring the Server

Before starting the OpsDash server, you should edit the configuration file at /etc/opsdash/server.cfg, at least to review that the default settings are acceptable. You’ll want to check:

Firewall Configuration

The OpsDash server uses 3 ports:

8080/tcp is used for the web-based user interface. This port should be reachable from wherever the web UI should be accessible. Ideally, this should be accessed only from inside your company VPN. If you need to, you can change this with the listen.web-ui entry in the configuration file.
6273/udp is used by the agents to report metric data. This port should be reachable from all the agents that report data into this OpsDash server. If you need to, you can change this with the listen.agent-metrics entry in the configuration file.
6273/tcp is used by the agents to report non-metric data. This port also should be reachable by all the agents. If you need to, you can change this with the listen.agent-data entry in the configuration file.

Before you start installing the agents, you should ensure that the firewall settings on the server allow traffic on these ports. Be sure to check your Amazon security groups, Google Cloud networks, iptables, ufw, firewall-cmd or any other firewalling measures that you use.

Email Settings

OpsDash can be configured to send alerts by email. To enable this, the email account details must be specified in the server configuration file. The following server.cfg snippet shows how to configure it with a gmail account:

email.smtpserver = smtp.gmail.com:587
email.username = your.gmail.username
email.password = your.gmail.password
email.from = opsdash@yourcompany.com

You can use any standard mail provider, including Yahoo, Outlook, Amazon SES etc. Most use port 587 with STARTTLS or port 465 with tlswrapper. If you’re using Gmail, you’ll need to enable the “less secure apps” setting for the account mentioned here.

If the email.smtpserver is set, then OpsDash assumes that you’re going to use the email feature. The from address (email.from) is mandatory if the email feature is enabled (the OpsDash server will log this situation and refuse to start up). Your email provider may place restrictions on what can be used as the value of email.from. For e.g., Amazon SES requires verification of the address and Gmail ignores it.

Note that the password is stored in this file in plain text. The package installation sets the owner of this file to user root, group opsdash and permissions to 0640 (-rw-r-----). This allows only root and OpsDash to read the password. If you do not trust root on this machine, you cannot securely store the password in server.cfg.

tlswrapper: OpsDash support end-to-end encrypted SMTP connections also (set the configuration value email.tlswrapper to yes), so that you can use it with smtp.gmail.com:465 or other systems, but this setting is not recommended.

maxfreq: You can configure OpsDash to send not more than one mail every X minutes. This prevents unintentional “alert-spam”. You can set the value with the configuration email.maxfreq = X where X is the number of minutes.

Data Retention

By default, time-series data and alert history is retained for 180 days (about 6 months). You can change this by setting the retention entry (the value is in number of days).

Restrict Modifications

You can specify an htpasswd file that contains usernames and encrypted passwords (htpasswd is a quasi-standard file format that can be modified with the htpasswd tool).

If configured, the OpsDash web UI will use this to authenticate whenever any modifications are to be made. That is, for read-only operations the web UI will function without requiring any password, but whenever any changes are needed (like configuring an alert), a password will be required.

Note that any user from the list of users in the htpasswd file will be granted access. The authentication is standard HTTP basic auth.

Also note that it possible to front the OpsDash web UI with a dedicated web server like nginx or Apache, and thereby setup a more restrictive authentication, or integrate with other authentication providers in your enterprise, like an LDAP server.

Using the License File

Before starting the server, copy the license file that you’ve received, into the directory /etc/opsdash. The OpsDash server looks for *.lic files in this directory at startup. If there is no valid license file in there at server startup, it proceeds in a trial mode.

The log file permissions have to such that the OpsDash server is able to read it. Please see the licensing section for more details.

You can view the licensing status in the Account Information page in the UI after the server starts up. The log files also contain indication of the licensing status.

Starting the Server

The OpsDash server runs as a daemon called opsdash-serverd, that can be managed by standard service managers like upstart and systemd.

After you are happy with the settings, and ensured that the firewalls will allow traffic to the necessary ports, you can start the server daemon with:

sudo service opsdash-serverd start

You should be able to browse to http://your.server:8080/ and see the OpsDash web UI.

The server log file at /var/log/opsdash/opsdash-server.log can help with troubleshooting common issues like incorrect configuration or port in use.

Installing the Agent

The OpsDash agent is available for the same set of architectures and plaforms for which the server is available, as listed above.

As for the server, you can use the standard commands for the appropriate platform:

# for RHEL and similar distros
rpm -ihv opsdash-agent-1.13.2-1.x86_64.rpm
yum install opsdash-agent

# for Debian and similar distros
dpkg -i opsdash-agent_1.13.2_amd64.deb
apt-get install opsdash-agent

Configuring the Agent

Before the agent can be started, the agent configuration file at /etc/opsdash/agent.cfg, needs to be edited. There is one mandatory entry that needs to be set.

Pointing to the OpsDash Server

The agent needs to be told which is the server, and this can be done by:

server = ip.or.hostname

You can specify an IPv4 address, a resolvable hostname, or an IPv6 address as the value.

If you’ve changed the default ports in the server’s configuration on the OpsDash server, then they need to be specified here also:

port.agent-metrics = from listen.agent-metrics in server.cfg
port.agent-data = from listen.agent-data in server.cfg

Other Settings

The filter.interfaces entry is a regular expression used to select the network interfaces (like eth0, en1 etc.) for reporting. The default setting will not match entries like lo, bridge0 etc. If you really need to include these interfaces in the agent’s report, you can tweak this value.

The reportinterval is the number of seconds that the agent will wait between sending in reports to the server. We recommend you leave this at the default setting of 30 seconds.

Starting the Agent

Similar to the server, the agent runs as a daemon, and can be started with:

sudo service opsdash-agentd start

The agent will start successfully only if the server entry is set in the configuration file /etc/opsdash/agent.cfg (see above).

After the agent is started successfully, you should be able to see the agent’s dashboard in the OpsDash web UI in about a minute or two. If it does not show up, check the connectivity (especially the firewall settings for the ports involved) between the agent and the server.

The agent log file at /var/log/opsdash/opsdash-agent.log can help with troubleshooting common issues.

Installation Using the Tarball

The tarball packages (*.tar.gz) contain the binaries of both the server and the agent, as well as all the necessary files needed to run them. It needs a bit of “assembly” to set these up as needed, but provides more flexibility which can be helpful for non-Debian/non-RHEL distros and as well as custom deployments.

Start by unpacking the tarball to a convenient location. Both the OpsDash server and the agent can be set up to run in-place at this location. The snippet below covers the steps:

# unpack the tarball
tar xvf opsdash-1.13.2.amd64.tar.gz

# cd to the sbin directory
cd opsdash-1.13.2-amd64/usr/sbin

# server can be run from here
# the -f forces the server to run in the foreground
# interrupt (^C) exits
./opsdash-server -f

Note that the server must be run in the foreground in this configuration, and will not work if daemonized. Running the agent is similar, remember to set a valid ‘server’ entry in the configuration file first:

# edit the agent configuration file, set "server"
vim /path/to/opsdash-1.13.2-amd64/etc/opsdash/agent.cfg

# cd to the sbin directory
cd opsdash-1.13.2-amd64/usr/sbin

# agent can be run from here
# the -f forces the agent to run in the foreground
# interrupt (^C) exits
./opsdash-agent -f

systemd Services

Using the tarball files, it is possible to set up systemd based services instead of the provided init-scripts (although the provided init-scripts will work with both systemd and non-systemd init environments.)

Below is an example of such a service file:

[Unit]
Description=OpsDash Server Daemon
After=network.target

[Service]
ExecStart=/path/to/opsdash-1.13.2-amd64/usr/sbin/opsdash-server -f
WorkingDirectory=/path/to/opsdash-1.13.2-amd64/usr/sbin
Restart=on-failure

[Install]
WantedBy=multi-user.target

Note that the -f argument and the WorkingDirectory are required for the service to launch successfully.