Install NetQ Agents
After installing the NetQ software, you should install the NetQ Agents on each switch you want to monitor. You can install NetQ Agents on switches and servers running:
- Cumulus Linux 5.0.0 or later (Spectrum switches)
- Ubuntu 22.04, 20.04
Prepare for NetQ Agent Installation
For switches running Cumulus Linux, you need to:
- Install and configure NTP or PTP, if needed
- Obtain NetQ software packages
For servers running Ubuntu, you need to:
- Verify you installed the minimum package versions
- Verify the server is running
lldpd
- Install and configure NTP or PTP, if needed
- Obtain NetQ software packages
If your network uses a proxy server for external connections, you should first
configure a global proxy so apt-get
can access the software package in the NVIDIA networking repository.
Verify NTP Is Installed and Configured
Verify that NTP is running on the switch as outlined in the steps below. The switch system clock must be synchronized with the NetQ appliance to enable useful statistical analysis. Alternatively, you can configure PTP for time synchronization.
cumulus@switch:~$ sudo systemctl status ntp
[sudo] password for cumulus:
● ntp.service - LSB: Start NTP daemon
Loaded: loaded (/etc/init.d/ntp; bad; vendor preset: enabled)
Active: active (running) since Fri 2018-06-01 13:49:11 EDT; 2 weeks 6 days ago
Docs: man:systemd-sysv-generator(8)
CGroup: /system.slice/ntp.service
└─2873 /usr/sbin/ntpd -p /var/run/ntpd.pid -g -c /var/lib/ntp/ntp.conf.dhcp -u 109:114
If NTP is not installed, install and configure it before continuing.
If NTP is not running:
- Verify the IP address or hostname of the NTP server in the
/etc/ntp.conf
file, and then - Reenable and start the NTP service using the
systemctl [enable|start] ntp
commands
If you are running NTP in your out-of-band management network with VRF, specify the VRF (ntp@<vrf-name>
versus just ntp
) in the above commands.
Obtain NetQ Agent Software Package
Cumulus Linux 4.4 and later includes the netq-agent
package by default. To upgrade the NetQ Agent to the latest version:
- Add the repository by uncommenting or adding the following line in
/etc/apt/sources.list
:
cumulus@switch:~$ sudo nano /etc/apt/sources.list
...
deb https://apps3.cumulusnetworks.com/repos/deb CumulusLinux-4 netq-latest
...
You can specify a NetQ Agent version in the repository configuration. The following example shows the repository configuration to retrieve NetQ Agent 4.12:
deb https://apps3.cumulusnetworks.com/repos/deb CumulusLinux-4 netq-4.12
- Add the
apps3.cumulusnetworks.com
authentication key to Cumulus Linux:
cumulus@switch:~$ wget -qO - https://apps3.cumulusnetworks.com/setup/cumulus-apps-deb.pubkey | sudo apt-key add -
Verify Service Package Versions
Before you install the NetQ Agent on an Ubuntu server, make sure you install and run at least the minimum versions of the following packages:
- 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
Verify the Server is Running lldpd
Make sure you are running lldpd, not lldpad. Ubuntu does not include lldpd
by default; however, the installation requires it.
To install this package, run the following commands:
root@ubuntu:~# sudo apt-get update
root@ubuntu:~# sudo apt-get install lldpd
root@ubuntu:~# sudo systemctl enable lldpd.service
root@ubuntu:~# sudo systemctl start lldpd.service
Install and Configure Network Time Server
If NTP is not already installed and configured, follow the steps below. Alternatively, you can configure PTP for time synchronization.
Install NTP on the server, if not already installed. Servers must be synchronized with the NetQ appliance to enable useful statistical analysis.
root@ubuntu:~# sudo apt-get install ntp
Configure the network time server.
Open the
/etc/ntp.conf
file in your text editor of choice.Under the Server section, specify the NTP server IP address or hostname.
Enable and start the NTP service.
root@ubuntu:~# sudo systemctl enable ntp root@ubuntu:~# sudo systemctl start ntp
If you are running NTP in your out-of-band management network with VRF, specify the VRF (ntp@<vrf-name>
versus just ntp
) in the above commands.
Verify NTP is operating correctly. Look for an asterisk (*) or a plus sign (+) that indicates the clock synchronized with NTP.
root@ubuntu:~# ntpq -pn remote refid st t when poll reach delay offset jitter ============================================================================== +173.255.206.154 132.163.96.3 2 u 86 128 377 41.354 2.834 0.602 +12.167.151.2 198.148.79.209 3 u 103 128 377 13.395 -4.025 0.198 2a00:7600::41 .STEP. 16 u - 1024 0 0.000 0.000 0.000 \*129.250.35.250 249.224.99.213 2 u 101 128 377 14.588 -0.299 0.243
Obtain NetQ Agent Software Package
To install the NetQ Agent you need to install netq-agent
on each server. This is available from the NVIDIA networking repository.
To obtain the NetQ Agent package:
- Reference and update the local
apt
repository.
root@ubuntu:~# sudo wget -O- https://apps3.cumulusnetworks.com/setup/cumulus-apps-deb.pubkey | apt-key add -
- Add the Ubuntu repository:
Create the file /etc/apt/sources.list.d/cumulus-host-ubuntu-jammy.list
and add the following line:
root@ubuntu:~# vi /etc/apt/sources.list.d/cumulus-apps-deb-jammy.list
...
deb [arch=amd64] https://apps3.cumulusnetworks.com/repos/deb jammy netq-latest
...
The use of netq-latest
in these examples means that a get
to the repository always retrieves the latest version of NetQ, even for a major version update. If you want to keep the repository on a specific version — such as netq-4.4
— use that instead.
Create the file /etc/apt/sources.list.d/cumulus-host-ubuntu-focal.list
and add the following line:
root@ubuntu:~# vi /etc/apt/sources.list.d/cumulus-apps-deb-focal.list
...
deb [arch=amd64] https://apps3.cumulusnetworks.com/repos/deb focal netq-latest
...
The use of netq-latest
in these examples means that a get
to the repository always retrieves the latest version of NetQ, even for a major version update. If you want to keep the repository on a specific version — such as netq-4.4
— use that instead.
Install NetQ Agent
After completing the preparation steps, install the agent on your switch or host.
Cumulus Linux 4.4 and later includes the netq-agent
package by default. To install the NetQ Agent on earlier versions of Cumulus Linux:
Update the local
apt
repository, then install the NetQ software on the switch.cumulus@switch:~$ sudo apt-get update cumulus@switch:~$ sudo apt-get install netq-agent
Verify you have the correct version of the Agent.
cumulus@switch:~$ dpkg-query -W -f '${Package}\t${Version}\n' netq-agent
You should see version 4.12.0 and update 49 in the results.
- Cumulus Linux 5.9.0 or later: netq-agent_4.12.0-cld12u49~1731404238.ffa541ea6_amd64.deb
- Cumulus Linux 5.8.0 or earlier, ARM platforms: netq-agent_4.12.0-cl4u49~1731403923.ffa541ea6_armel.deb
- Cumulus Linux 5.8.0 or earlier, amd64 platforms: netq-agent_4.12.0-cl4u49~1731404368.ffa541ea6_amd64.deb
Restart
rsyslog
so it sends log files to the correct destination.cumulus@switch:~$ sudo systemctl restart rsyslog.service
Configure the NetQ Agent, as described in the next section.
To install the NetQ Agent:
Install the software packages on the server.
root@ubuntu:~# sudo apt-get update root@ubuntu:~# sudo apt-get install netq-agent
Verify that you have the correct agent version.
root@ubuntu:~# dpkg-query -W -f '${Package}\t${Version}\n' netq-agent
You should see version 4.12.0 and update 49 in the results.
- Ubuntu 20.04: netq-agent_4.12.0-ub20.04u49~1731404061.ffa541ea6_amd64.deb
- Ubuntu 22.04: netq-agent_4.12.0-ub22.04u49~1731404070.ffa541ea6_amd64.deb
- Restart
rsyslog
so it sends log files to the correct destination.
root@ubuntu:~# sudo systemctl restart rsyslog.service
- Configure the NetQ Agent, as described in the next section.
Configure NetQ Agent
After you install the NetQ Agents on the switches you want to monitor, you must configure them to obtain useful and relevant data.
The NetQ Agent is aware of and communicates through the designated VRF. If you do not specify one, it uses the default VRF (named default). If you later change the VRF configured for the NetQ Agent (using a lifecycle management configuration profile, for example), you might cause the NetQ Agent to lose communication.
If you configure the NetQ Agent to communicate in a VRF that is not default or mgmt, the following line must be added to /etc/netq/netq.yml
in the netq-agent
section:
netq-agent:
netq_stream_address: 0.0.0.0
Two methods are available for configuring a NetQ Agent:
- Edit the configuration file on the switch, or
- Use the NetQ CLI
Configure NetQ Agents Using a Configuration File
You can configure the NetQ Agent in the netq.yml
configuration file contained in the /etc/netq/
directory.
Open the
netq.yml
file using your text editor of choice. For example:sudo nano /etc/netq/netq.yml
Locate the netq-agent section, or add it.
Set the parameters for the agent as follows:
- port: 31980 (default configuration)
- server: IP address of the NetQ server where the agent should send its collected data
- vrf: default (or one that you specify)
- inband-interface: the interface used to reach your NetQ server and used by lifecycle management to connect to the switch (for deployments where switches are managed through an in-band interface)
Your configuration should be similar to this:
netq-agent: port: 31980 server: 192.168.1.254 vrf: mgmt
For in-band deployments:
netq-agent: inband-interface: swp1 port: 31980 server: 192.168.1.254 vrf: default
Configure NetQ Agents Using the NetQ CLI
If you configured the NetQ CLI, you can use it to configure the NetQ Agent to send telemetry data to the NetQ appliance or VM. To configure the NetQ CLI, refer to Install NetQ CLI.
If you intend to use a VRF for agent communication (recommended), refer to Configure the Agent to Use VRF. If you intend to specify a port for communication, refer to Configure the Agent to Communicate over a Specific Port.
Use the following command to configure the NetQ Agent:
sudo netq config add agent server <text-opta-ip> [port <text-opta-port>] [ssl true | ssl false] [ssl-cert <text-ssl-cert-file> | ssl-cert download] [vrf <text-vrf-name>] [inband-interface <interface-name>]
This example uses a NetQ server IP address of 192.168.1.254, the default port, and the mgmt
VRF for a switch managed through an out-of-band connection:
sudo netq config add agent server 192.168.1.254 vrf mgmt
Updated agent server 192.168.1.254 vrf mgmt. Please restart netq-agent (netq config restart agent).
sudo netq config restart agent
This example uses a NetQ server IP address of 192.168.1.254, the default port, and the default
VRF for a switch managed through an in-band connection on interface swp1
:
sudo netq config add agent server 192.168.1.254 vrf default inband-interface swp1
Updated agent server 192.168.1.254 vrf default. Please restart netq-agent (netq config restart agent).
sudo netq config restart agent
Configure Advanced NetQ Agent Settings
A couple of additional options are available for configuring the NetQ Agent. If you are using VRFs, you can configure the agent to communicate over a specific VRF. You can also configure the agent to use a particular port.
Configure the Agent to Use a VRF
By default, NetQ uses the default VRF for communication between the NetQ appliance or VM and NetQ Agents. While optional, NVIDIA strongly recommends that you configure NetQ Agents to communicate with the NetQ appliance or VM 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 you configured the management VRF and you want the agent to communicate with the NetQ appliance or VM over it, configure the agent like this:
sudo netq config add agent server 192.168.1.254 vrf mgmt
sudo netq config restart agent
If you later change the VRF configured for the NetQ Agent (using a lifecycle management configuration profile, for example), you might cause the NetQ Agent to lose communication.
Configure the Agent to Communicate over a Specific Port
By default, NetQ uses port 31980 for communication between the NetQ server and NetQ Agents for on-premises deployments and port 443 for cloud deployments. If you want the NetQ Agent to communicate with the NetQ sever via a different port, you need to specify the port number when configuring the NetQ Agent, like this:
sudo netq config add agent server 192.168.1.254 port 7379
sudo netq config restart agent