NetQ Command Line Overview
The NetQ CLI provides access to all network state and event information collected by NetQ Agents. It behaves similarly to typical CLIs, with groups of commands that display related information, and help commands that provide additional information. See the command line reference for a comprehensive list of NetQ commands, including examples, options, and definitions.
The NetQ command line interface only runs on switches and server hosts implemented with Intel x86 or ARM-based architectures.
CLI Access
When you install or upgrade NetQ, you can also install and enable the CLI on your NetQ server or appliance and hosts.
To access the CLI from a switch or server:
-
Log in to the device. The following example uses the default username of cumulus and a hostname of switch:
<computer>:~<username>$ ssh cumulus@switch -
Enter your password to reach the command prompt. The default password is CumulusLinux!
-
You can now run commands:
cumulus@switch:~$ netq show agents
Command Line Basics
This section describes the core structure and behavior of the NetQ CLI.
Command Line Structure
The NetQ command line has a flat structure as opposed to a modal structure: you can run all commands from the standard command prompt instead of only in a specific mode, at the same level.
Command Syntax
All NetQ CLI commands begin with netq. The commands you use to monitor your network fall into one of four syntax categories: validation (check), monitoring (show), configuration, and trace.
netq check <network-protocol-or-service> [options]
netq show <network-protocol-or-service> [options]
netq config <action> <object> [options]
netq trace <destination> from <source> [options]
| Symbols | Meaning |
|---|---|
| Parentheses ( ) | Grouping of required parameters. Choose one. |
| Square brackets [ ] | Single or group of optional parameters. If more than one object or keyword is available, choose one. |
| Angle brackets < > | Required variable. Value for a keyword or option; enter according to your deployment nomenclature. |
| Pipe | | Separates object and keyword options, also separates value options; enter one object or keyword and zero or one value. |
Command Output
The command output presents results in color for many commands. Results with errors appear in red, and warnings appear in yellow. Results without errors or warnings appear in either black or green. VTEPs appear in blue. A node in the pretty output appears in bold, and angle brackets (< >) wrap around a router interface. To view the output with only black text, run the netq config del color command. You can view output with colors again by running netq config add color.
All check and show commands have a default timeframe of now to one hour ago, unless you specify an approximate time using the around keyword or a range using the between keyword. For example, running netq check bgp shows the status of BGP over the last hour. Running netq show bgp around 3h shows the status of BGP three hours ago.
When entering a time value, you must include a numeric value and the unit of measure:
- w: weeks
- d: days
- h: hours
- m: minutes
- s: seconds
- now
When using the between option, you can enter the start time (text-time) and end time (text-endtime) values as most recent first and least recent second, or vice versa. The values do not have to have the same unit of measure. Use the around option to view information for a particular time.
Command Prompts
NetQ code examples use the following prompts:
cumulus@switch:~$indicates the user cumulus is logged in to a switch to run the example commandcumulus@host:~$indicates the user cumulus is logged in to a host to run the example commandcumulus@netq-appliance:~$indicates the user cumulus is logged in to the NetQ appliance to run the commandcumulus@hostname:~$indicates the user cumulus is logged in to a switch, host or appliance to run the example command
To use the NetQ CLI, the switches must be running the Cumulus Linux or SONiC operating system, the NetQ software, the NetQ Agent, and the NetQ CLI. The hosts must be running the Ubuntu OS, the NetQ Agent, and the NetQ CLI. Refer to Install NetQ for additional information.
Command Completion
As you enter commands, you can get help with the valid keywords or options using the tab key. For example, using tab completion with netq check displays the possible objects for the command, and returns you to the command prompt to complete the command:
cumulus@switch:~$ netq check <<press Tab>>
addresses : IPv4/v6 addresses
agents : Netq agent
bgp : BGP info
cl-version : Cumulus Linux version
evpn : EVPN
interfaces : network interface port
mlag : Multi-chassis LAG (alias of clag)
mtu : Link MTU
ntp : NTP
ospf : OSPF info
roce : RoCE
sensors : Temperature/Fan/PSU sensors
topology : Topology
vlan : VLAN
vxlan : VxLAN
cumulus@switch:~$ netq check
Command Help
As you enter commands, you can get help with command syntax by entering help as part of the command. For example, to find out which options are available for an IP addresses check, enter the netq check addresses command followed by help:
cumulus@switch:~$ netq check addresses help
Commands:
netq check addresses [label <text-label-name> | hostnames <text-list-hostnames>] [check_filter_id <text-check-filter-id>] [include <addr-number-range-list> | exclude <addr-number-range-list>] [around <text-time>] [json | summary]
To see an exhaustive list of commands and their definitions, run:
cumulus@switch:~$ netq help list
To display NetQ command formatting rules, run:
cumulus@switch:~$ netq help verbose
Command History
The CLI stores commands issued within a session, which lets you review and rerun commands that you already ran. At the command prompt, press the Up Arrow and Down Arrow keys to move back and forth through the list of commands previously entered. When you have found a given command, you can run the command by pressing Enter, just as you would if you had entered it manually. You can also modify the command before you run it.
Command Categories
While the CLI has a flat structure, NetQ commands are conceptually grouped into the following functional categories:
Validation Commands
The netq check commands validate the current or historical state of the network by looking for errors and misconfigurations in the network. The commands run fabric-wide validations against various configured protocols and services to determine how well the network is operating. You can perform validation checks for the following:
- addresses: IPv4 and IPv6 addresses duplicates across devices
- agents: NetQ Agents operation on all switches and hosts
- bgp: BGP (Border Gateway Protocol) operation across the network fabric
- clag: Cumulus Linux MLAG (multi-chassis LAG/link aggregation) operation
- cl-version: Cumulus Linux version
- evpn: EVPN (Ethernet Virtual Private Network) operation
- interfaces: network interface port operation
- mlag: Cumulus MLAG (multi-chassis LAG/link aggregation) operation
- mtu: Link MTU (maximum transmission unit) consistency across paths
- ntp: NTP (Network Time Protocol) operation
- ospf: OSPF (Open Shortest Path First) operation
- roce: RoCE (RDMA over Converged Ethernet) configurations
- sensors: Temperature/Fan/PSU sensor operation
- topology: Topology configuration
- vlan: VLAN (Virtual Local Area Network) operation
- vxlan: VXLAN (Virtual Extensible LAN) data path operation
The commands take the form of netq check <network-protocol-or-service> [options], where the options vary according to the protocol or service.
Monitoring Commands
The netq show commands let you view details about the current or historical configuration and status of various protocols and services.
The commands take the form of netq [<hostname>] show <network-protocol-or-service> [options], where the options vary according to the protocol or service. You can restrict the commands from showing the information for all devices to showing information only for a selected device using the hostname option.
Configuration Commands
Various commands—netq config, netq lcm, netq add, and netq del—allow you to manage NetQ Agent and CLI server configurations, configure lifecycle management, set up container monitoring, and manage notifications.
NetQ Agent Configuration
The agent commands configure individual NetQ Agents.
The agent configuration commands can add and remove agents from switches and hosts, start and stop agent operations, debug the agent, specify default commands, and enable or disable a variety of monitoring features (including sensors, FRR (FRRouting), CPU usage limit, and What Just Happened).
Commands apply to one agent at a time. Run them from the switch or host where the NetQ Agent resides. You must run the netq config commands with sudo privileges.
The agent configuration commands include:
netq config (add|del|show) agent
netq config (start|stop|status|restart) agent
The following example shows how to view the NetQ Agent configuration:
cumulus@switch:~$ sudo netq config show agent
netq-agent value default
--------------------- --------- ---------
exhibitport
exhibiturl
server 127.0.0.1 127.0.0.1
cpu-limit 100 100
agenturl
wjh Enabled
enable-opta-discovery False False
agentport 8981 8981
port 31980 31980
vrf default default
is-gnmi-enabled False False
netq_stream_port 7680 7680
netq_stream_address 127.0.0.1 127.0.0.1
is-ssl-enabled False False
ssl-cert
generate-unique-hostname False False
()
After making configuration changes to your agents, you must restart the agent for the changes to take effect. Use the netq config restart agent command.
Refer to Manage NetQ Agents and Install NetQ Agents for additional examples.
CLI Configuration
The netq config cli configures and manages the CLI component. You can add or remove the CLI (essentially enabling/disabling the service), start and restart it, and view the configuration of the service.
Commands apply to one device at a time, and you run them from the switch or host where you run the CLI.
The CLI configuration commands include:
netq config add cli server
netq config del cli server
netq config show cli premises [json]
netq config show (cli|all) [json]
netq config (status|restart) cli
netq config select cli premise
The following example shows how to restart the CLI instance:
cumulus@switch~:$ netq config restart cli
The following example shows how to enable the CLI on a NetQ on-premises appliance or virtual machine:
cumulus@switch~:$ netq config add cli server 10.1.3.101
NetQ System Configuration Commands
Use the following commands to manage the NetQ system itself:
- bootstrap: Loads the installation program onto the network switches and hosts in either a single server or server cluster arrangement.
- decommission: Decommissions a switch or host.
- install: Installs NetQ in standalone or cluster deployments; also used to install patch software.
- upgrade bundle: Upgrades NetQ on NetQ on-premises appliances or VMs.
The following example shows how to decommission a switch named leaf01:
cumulus@netq-appliance:~$ netq decommission leaf01
For information and examples on installing and upgrading the NetQ system, see Install NetQ and Upgrade NetQ.
Event Notification Commands
The notification configuration commands can add, remove, and show notification via third-party integrations. These commands create the channels, filters, and rules that display event messages. Refer to Configure System Event Notifications for step-by-step instructions and examples.
Threshold-based Event Notification Commands
NetQ supports TCA events, a set of events that are triggered by crossing a user-defined threshold. Configure and manage TCA events using the following commands:
netq add tca
netq del tca tca_id <text-tca-id-anchor>
netq show tca
Lifecycle Management Commands
The lifecycle management commands help you efficiently manage the deployment of NVIDIA product software onto your network devices (servers, appliances, and switches).
LCM commands allow you to:
- Manage network OS and NetQ images in a local repository
- Configure switch access credentials for installations and upgrades
- Manage switch inventory and roles
- Install or upgrade NetQ Agents and CLI on switches
- Upgrade the network OS on switches with NetQ Agents
- View a result history of upgrade attempts
- Add or delete NetQ configuration profiles
The following example shows the NetQ configuration profiles:
cumulus@switch:~$ netq lcm show netq-config
ID Name Default Profile VRF WJH CPU Limit Log Level Last Changed
------------------------- --------------- ------------------------------ --------------- --------- --------- --------- -------------------------
config_profile_3289efda36 NetQ default co Yes mgmt Disable Disable info Tue Apr 27 22:42:05 2021
db4065d56f91ebbd34a523b45 nfig
944fbfd10c5d75f9134d42023
eb2b
The following example shows how to add a Cumulus Linux installation image to the NetQ repository on the switch:
netq lcm add cl-image /path/to/download/cumulus-linux-4.3.0-mlnx-amd64.bin
Trace Commands
The netq trace commands let you view the available paths between two nodes on the network. You can perform a layer 2 or layer 3 trace, and view the output in one of three formats: JSON, pretty, and detail. JSON output provides the output in a JSON file format for ease of importing to other applications or software. Pretty output lines up the paths in a pseudo-graphical manner to help visualize multiple paths. Detail output is useful for traces with higher hop counts where the pretty output wraps lines, making it harder to interpret the results. The detail output displays a table with a row for each path.
The trace command syntax is:
netq trace (<mac> vlan <1-4096>) from (<src-hostname>|<ip-src>) [vrf <vrf>] [around <text-time>] [json|detail|pretty] [debug]
netq trace <ip> from (<src-hostname>|<ip-src>) [vrf <vrf>] [around <text-time>] [json|detail|pretty] [debug]
netq trace (<mac> vlan <1-4096>) from <mac-src> [around <text-time>] [json|detail|pretty] [debug]