This topic provides step-by-step instructions for installing Cumulus NetQ 1.4 with Cumulus Linux 3.3.2 or later. It provides setup instructions for the Telemetry Server, for the Cumulus Linux switches, and for the Linux-based hosts.
Cumulus NetQ core telemetry and analytics capabilities require two components to be installed to gain access to the network connectivity and actionable insights NetQ provides:
- NetQ Telemetry application installed on the Telemetry Server
cumulus-netqmeta package installed on Cumulus® Linux® switches
Optionally, you can:
- Add greater fabric visibility by installing Net Q,
cumulus-netqmeta package, on host servers running CentOS, Red Hat Enterprise, or Ubuntu Linux Operating Systems
- Add local storage and distribution services for the Cumulus Linux network operating system (NOS) and provisioning scripts used to deploy and upgrade Cumulus Linux and NetQ. See Cumulus NetQ Image and Provisioning Management User Guide for details.
- Add Free Range (FR) Routing capabilities on your hosts.
NetQ is supported on a variety of hardware. Refer to the Cumulus Hardware Compatibility List for the hardware supported and descriptions of the available options.
Operating System Support
NetQ 1.4 is supported on the following operating systems:
- Cumulus Linux 3.3.2 and later
- Ubuntu 16.04
- Red Hat® Enterprise Linux (RHEL) 7.1
- CentOS 7
NetQ Application Support
- The NetQ Telemetry application is supported on NetQ 1.0 and later.
- The NetQ Service Console is supported on NetQ 1.0 and later.
- The NetQ Telemetry, Image and Provisioning Management Server (IPM) application (an early access feature) is available with NetQ 1.4 and later.
Installation of NetQ involves installing the Telemetry Server, and installing and configuring the NetQ Agents. Additional steps are needed to install NetQ in a High Availability configuration or to Integrate NetQ with Event Notification Applications. This flow chart shows the three required steps (the numbered items) and the optional steps to install and setup NetQ to start validating your network.
Install the NetQ Telemetry Server
The NetQ Telemetry Server is comprised of the following components:
- NetQ Telemetry application: network monitoring and analytics functionality
- NetQ Telemetry CLI: command line user interface for monitoring network and administering NetQ through a terminal session
- NetQ Service Console: web console user interface for monitoring and administering NetQ with the NetQ Shell
- Redis: primary data base storage for collected data
- InfluxDB: secondary data base storage for network snapshots
- Authorization: secure access functionality
The server is available in one of two formats, as a:
- VMware ESXi™ 6.5 virtual machine (VM)
- KVM/QCOW (QEMU Copy on Write) image for use on CentOS, Ubuntu and RHEL hosts
To install the Telemetry Server VM:
- Download the NetQ Telemetry Server (TS) VM.
- On the Cumulus Downloads page, select NetQ from the Product list box.
- Optionally, select the latest available version from the Version list box.
- Optionally, select the hypervisor you wish to use from the Hypervisor list box.
- Scroll down to review the images that match your selection criteria, and click Download for the VM you want.
Open Virtual Machine Manager.
Import the image.
Select File > New Virtual Machine, or click the New VM icon.
Select Import existing disk image.
Place the image in the
Select the Cumulus image you just downloaded.
Click Choose Volume.
- Type, or browse for, the location where you want to store the volume. The directory must already exist.
- Select Generic for the OS type and Version.
- Click Forward.
Allocate the amount of memory and number of CPUs you want available to this VM.The amount of RAM recommended for the NetQ TS is dependent on your configuration and a number of other criteria; refer to the Methods for Diagnosing Network Issues topic for more information.
- Increase or decrease the amount of Memory and number of CPUs using the + and - symbols to best meet your environment needs.
- Click Forward.
- Prepare for installation.
- Provide a unique and useful name for the VM.
- Select Customize configuration before install.
- Click Finish to open the configuration options.
- Configure custom CPU parameters.
- Click CPUs.
- Increase or decrease the Current and Maximum allocation of CPUs using the + and - symbols to best meet your environment needs.
- Select Copy host CPU configuration.
- Click Apply.
- Configure custom network interface card (NIC) parameters.
- Click NIC.
- Select the Network source.
- Select or type the Device model.
- Verify the MAC address for the NIC.
Verify NetQ TS VM has started.
If the VM did not start automatically, click Begin Installation.
There are two default user accounts you can use to log in:
- The primary username is admin, and its associated password is CumulusNetQ!.
- An alternate username is cumulus, and its associated password is CumulusLinux!.
Note the external IP address of the switch where the TS is running. It is needed to configure the NetQ Agents on each node you want to monitor.
The TS obtains its IP address from DHCP. To determine the assigned IP address, log in to the TS and run
ifconfig eth0. Use the
int6 addrfor the TS IP address based on whether you are running IPv4 or IPv6.
For HA mode, you need to note the IP addresses of all three instances of the TS.
If you need the TS to have a static IP address, manually assign one:
gatewaylines to the eth0 configuration, specifying the TS's IP address and the IP address of the gateway.
- Save the file and exit.
Two options are available when installing NetQ that require additional configuration:
- High Availability mode
- Integration with third-party notification applications
Once the NetQ Telemetry Server is installed, if you are interested in using the Telemetry Server in high availability (HA) mode, follow the instructions in Configure High Availability Mode.
In either standard or HA mode, if you want to proactively monitor events in your network, you can integrate NetQ with PagerDuty, Slack, Elastic, or Splunk. To do so you need to configure both the notification application itself to receive the messages, and the NetQ Notifier with what messages to send and where to send them, after installing the NetQ Agents. See Integrate NetQ with Event Notification Applications.
Install the NetQ Agent
The NetQ Agent must be installed on each node you want to monitor. The node can be a:
- Switch running Cumulus Linux version 3.3.2 or later
- Server running Red Hat RHEL 7.1, Ubuntu 16.04 or CentOS 7
- Linux virtual machine running any of the above Linux operating systems
To install the NetQ Agent you need to install an OS-specific meta package,
cumulus-netq, on each switch. Optionally, you can install it on hosts. The meta package contains the NetQ Agent, the NetQ command line interface (CLI), and the NetQ library. The library contains modules used by both the NetQ Agent and the CLI.
Instructions for installing the meta package on each node type are included here:
- Install NetQ Agent on a Cumulus Linux Switch
- Install NetQ Agent on an Ubuntu Server
- Install NetQ Agent on a Red Hat or CentOS Server
apt-getcan access the meta package on the Cumulus Networks repository.
Install NetQ Agent on a Cumulus Linux Switch
A simple two-step process installs the NetQ Agent on a Cumulus switch.
On a switch, edit
/etc/apt/sources.listto add the repository for Cumulus NetQ. Note that NetQ has a separate repository from Cumulus Linux.The repository
debcan be used if you want to always retrieve the latest posted version of NetQ. CumulusLinux-3 netq-latest
Update the local
aptrepository, then install the NetQ meta package on the switch.
Repeat these steps for each node, or use an automation tool to install NetQ Agent on multiple nodes. Refer to Deployment Appendices for an example Ansible playbook.
Install NetQ Agent on an Ubuntu Server (Optional)
Before you install the NetQ Agent on an Ubuntu server, make sure the following packages are installed and running these minimum versions:
- iproute 1:4.3.0-1ubuntu3.16.04.1 all
- iproute2 4.3.0-1ubuntu3 amd64
lldpd 0.7.19-1 amd64
- ntp 1:4.2.8p4+dfsg-3ubuntu5.6 amd64
docker-ce 17.06.1~ce-0~ubuntu amd64This package is required only if you plan to monitor Docker instances on the host; otherwise do not install it.
Make sure you are running lldpd, not lldpad. Ubuntu does not include
lldpdby default, which is required for the installation. To install this package, run the following commands:
To install the NetQ Agent on an Ubuntu server:
Reference and update the local
Create the file
/etc/apt/sources.list.d/cumulus-host-ubuntu-xenial.listand add the following lines:
The use of
netq-latestin this example means that a get to the repository always retrieves the last version of NetQ, even in the case where a major version update has been made. If you want to keep the repository on a specific version — such as
netq-1.4— use that instead.
Install NTP on the server.
Install the meta package on the server.
Restart the NetQ daemon.
Install NetQ Agent on a Red Hat or CentOS Server (Optional)
Before you install the NetQ Agent on a Red Hat or CentOS server, make sure the following packages are installed and running these minimum versions:
Make sure you are running lldpd, not lldpad.
CentOS does not include
lldpdby default, nor does it include
wget, which is required for the installation. To install this package, run the following commands:
To install the NetQ Agent on a Red Hat or CentOS server:
Reference and update the local
/etc/yum.repos.d/cumulus-host-el.repoto set the
enabled=1flag for the two NetQ repositories.
Install NTP on the server.
Install the Bash completion and NetQ meta packages on the server.
Restart the NetQ daemon.
Set Up the NetQ Agents
Once the NetQ Agents have been installed on the network nodes you want to monitor, the NetQ Agents must be configured to obtain useful and relevant data. The code examples shown in this section illustrate how to configure the NetQ Agent on a Cumulus switch acting as a host, but it is exactly the same for the other type of nodes. Depending on your deployment, follow the relevant additional instructions after the basic configuration steps:
- Basic Configuration
- Configuring the Agent to Use a VRF
- Configuring the Agent to Communicate over a Specific Port
- Enabling Docker for Container Environments
This is the minimum configuration required to properly monitor your nodes.
Verify that NTP is running on the host node. Nodes must be in time synchronization with the Telemetry Server to enable useful statistical analysis.
rsyslogso log files are sent to the correct destination.
Link the host node to the TS you configured above.
In this code example, the IP address for the TS is 22.214.171.124. Note: Run
ifconfig eth0on the TS if you forgot to write down the address.
This command updates the configuration in the
/etc/netq/netq.ymlfile and enables the NetQ CLI.
Restart NetQ Agent.
If you see the following error, it means you haven't added the telemetry server or the server wasn't configured:
Verify NetQ Agent can reach the TS.
Configure the Agent to Use a VRF (Optional)
While optional, Cumulus strongly recommends that you configure NetQ Agents to communicate with the telemetry server only via a VRF, including a management VRF. To do so, you need to specify the VRF name when configuring the NetQ Agent. For example, if the management VRF is configured and you want the agent to communicate with the telemetry server over it, configure the agent like this:
You then restart the agent as described in the previous section:
Configure the Agent to Communicate over a Specific Port (Optional)
By default, NetQ uses port 6379 for communication between the telemetry server and NetQ Agents. If you want the NetQ Agent to communicate with the telemetry server via a different port, you need to specify the port number when configuring the NetQ Agent like this:
If you are using NetQ in high availability mode, you can only configure it on port 6379 or 26379.
Enabling Docker for Container Environments
Before enabling Docker, you must first install Docker. The code examples used here were created on an Ubuntu 16.04 host.
To install and enable Docker:
Add the Docker repository key.
Install the Docker repository.
Update the package lists.
Install Docker on the Ubuntu host.
Check that the Docker service is running on the Ubuntu 16.04 host.
Optional: Add the docker group to your user account to be able to run docker commands without using
Adding groups to different users requires a logout and login to take effect.
Enable Docker by adding the following three lines to the
netq.ymlfile on the container host. This command also sets how often to pull data from the container to every 15 seconds.
Set Up Security
When you set up and configured your Cumulus Linux switches, you likely configured a number of the security features available. Cumulus recommends the same security measures be followed for the Telemetry Server in the out-of-band-network. Refer to the Securing Cumulus Linux white paper for details.
Your Cumulus Linux switches have a number of ports open (refer to Default Open Ports in Cumulus Linux article).