This article describes how to install the OpsDash server, as well as the OpsDash agent, on various supported platforms.
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.
# for RHEL and similar distros rpm -ihv opsdash-server-1.5-1.x86_64.rpm # for Debian and similar distros dpkg -i opsdash-server_1.5_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.5-1.x86_64.rpm # for Debian and similar distros dpkg -i opsdash-agent_1.5_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-installer.exeto install the OpsDash Agent into the default location of
C:\Program Files\OpsDash Agent.
- Edit the
agent.cfgfile 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:
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 pgp.mit.edu --recv-keys 1E1BACF5
Update the local metadata:
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
and use the https form of the URL in
The RapidLoop Signing Key¶
The packages and metadata are signed by RapidLoop Packager <firstname.lastname@example.org>. The GPG public key is available on the pgp.mit.edu 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:
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.5-1.x86_64.rpm yum install opsdash-server # for Debian and similar distros dpkg -i opsdash-server_1.5_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:
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.
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 = email@example.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.
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
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
yes), so that you can use
smtp.gmail.com:465 or other systems, but this setting is not
maxfreq: You can configure OpsDash to send not more than one mail every
minutes. This prevents unintentional “alert-spam”. You can set the value with
email.maxfreq = X where
X is the number of minutes.
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).
You can specify an
htpasswd file that contains usernames and encrypted
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
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.5-1.x86_64.rpm yum install opsdash-agent # for Debian and similar distros dpkg -i opsdash-agent_1.5_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
filter.interfaces entry is a regular expression used to select
the network interfaces (like
en1 etc.) for reporting. The default
setting will not match entries like
bridge0 etc. If you really
need to include these interfaces in the agent’s report, you can tweak
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.5.amd64.tar.gz # cd to the sbin directory cd opsdash-1.5-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.5-amd64/etc/opsdash/agent.cfg # cd to the sbin directory cd opsdash-1.5-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
Using the tarball files, it is possible to set up
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.5-amd64/usr/sbin/opsdash-server -f WorkingDirectory=/path/to/opsdash-1.5-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.