Understanding the cl-support Output File
The cl-support script generates a compressed archive file of useful information for troubleshooting. The system creates the file automatically or you can create the file manually.
Automatic cl-support File Generation
The switch generates the cl-support file automatically:
- When there is a core dump file in the
/var/support/coredirectory for any application that Linux distributions support. - When one of the monitored services fails for the first time after you reboot or power cycle the switch.
cl-support files can generate in quick succession due to a chain of faults, which burdens system resources and causes system instability. When this occurs, the switch deactivates automatic cl-support file generation and preserves the first cl-support file (which contains relevant diagnostic information) for troubleshooting.
You can reactivate automatic cl-support file generation with the nv action activate system tech-support auto-generation command:
cumulus@switch:~$ nv action activate system tech-support auto-generation
You can also configure the number of seconds during which failures are counted and the maximum number of failures allowed during that time before automatic cl-support file generation deactivates.
The following example sets number of seconds during which failures are counted to 120 and the maximum number of failures allowed to 5.
cumulus@switch:~$ nv set system tech-support auto-generation burst-duration 120
cumulus@switch:~$ nv set system tech-support auto-generation burst-size 5
cumulus@switch:~$ nv config apply
When Cumulus Linux deactivates automatic cl-support file generation:
- The
cl-supportfile includes the reason for the failure, the state ofcl-supportfile generation (auto-generation (deactivated)), and indicates that thecl-supportfile is due to the first fault in a chain of faults. - The switch generates a
syslogmessage indicating that automatic generation is deactivated. - When you log into the switch, you see a banner indicating that automatic generation is deactivated due to detection of a chain of faults. The banner includes the name and location of the
cl-supportfile, the reason for deactivation, and the recommended actions.
Disable Automatic cl-support File Generation
To disable automatic cl-support file generation, run the nv set system tech-support auto-generation state disabled command:
cumulus@switch:~$ nv set system tech-support auto-generation state disabled
To reenable automatic cl-support file generation, run the nv set system tech-support auto-generation state enabled command.
cumulus@switch:~$ nv set system tech-support auto-generation state enabled
Show Automatic cl-support File Generation
To show if automatic cl-support file generation is active or inactive, and the reason for deactivation, run the nv show system tech-support auto-generation command.
cumulus@switch:~$ nv show system tech-support auto-generation
operational applied
-------------- ----------------------------------------------------------------------------- -------
state disabled enabled
burst-duration 7200 7200
burst-size 5 5
reason found core file(s): lldpd.346499.1768799305.core lldpd.346502.1768799305.core
support-file /var/support/cl_support_cumulus_20260119_050826.txz
Recovery Steps
=================
Step Action
---- -------------------------------------------------------------------------------------------------------------
1 Verify system health (CPU, memory, storage)
2 Collect the support files
3 Re-activate tech support generation service manually "nv action activate system tech-support auto-generation”
Manual cl-support File Generation
To create the cl-support file manually, run the nv action generate system tech-support command:
cumulus@switch:~$ nv action generate system tech-support
Action executing ...
Generating system tech-support file, it might take a few minutes...
Action executing ...
Generated tech-support
Action succeeded
Cumulus Linux saves the cl-support file in the /var/support directory. The file name starts with cl_support and ends with the date and time of creation.
The Linux command to generate the cl-support file includes more options; for example, you can include security sensitive information, include debugging information, only run certain modules, and provide a reason for running the script in the file.
To create the cl-support file manually, run the cl-support command:
cumulus@switch:~$ sudo cl-support
If the Cumulus Linux support team requests that you submit the output from cl-support to investigate issues you experience, and you need to include security-sensitive information, such as the sudoers file, use the -s option:
cumulus@switch:~$ sudo cl-support -s
cl-support Script Options
| Option | Description |
|---|---|
-h: |
Displays the available cl-support script options with a description. |
-c: |
Runs only modules matching core files (if no -e modules). |
-D: |
Displays debugging information. |
-d: |
Does not run modules in the provided comma separated list. |
-e: |
Only runs modules in the provided comma separated list. -e all runs all modules and submodules, including all optional modules. |
-j: |
Creates json output files for modules, where supported. |
-l: |
Lists the available modules, then exits. |
-M: |
Does not set a timeout for modules. Use this option with -T. |
-m: |
Runs modules serially and sets the module memory limit in MB; -m 0 runs serially without limits. |
-p: |
Adds a prefix to the cl-support archive file name. |
-r: |
Provides the reason for running the cl-support script. You must enclose the reason in quotes. |
-S: |
Uses a different output directory than the default /var/support. |
-s: |
Includes security sensitive information, such as the sudoers file. |
-T: |
Sets the timeout in seconds for creating the cl-support file. 0 disables the timeout. |
-t: |
Provides a tag string as part of the cl-support file name. |
-v: |
Runs in verbose mode to display status messages. |
cl-support Examples
The following example does not run the cl-support script on the ptp4l.ptp4l and what-just-happened.wjh modules.
cumulus@switch:~$ sudo cl-support -d ptp4l.ptp4l,what-just-happened.wjh
cl-support: cl-support is running without memory limits
Please send /var/support/cl_support_leaf01_20240214_183635.txz to Cumulus support.
The following example runs the cl-support script and displays debugging information:
cumulus@switch:~$ sudo cl-support -D
DEBUG: Memory headroom set as 256MB
DEBUG: Available memory 576MB
DEBUG: Allowed memory consumption calculated at 320MB
DEBUG: Using calculated memory limit
DEBUG: Last parallel mode archive creation used 4MB
DEBUG: /usr/bin/systemd-run -q -P -G -p MemoryMax=320M /usr/bin/time -v -o /tmp/tmp.f8L5l6odWn /usr/lib/cumulus/cl-support -D
DEBUG: run_timeout 90 synced
...
The following example runs the cl-support script, lists available modules, then exits.
cumulus@switch:~$ sudo cl-support -l
Default modules: synced.synced ptp4l.ptp4l what-just-happened.wjh
gdb.coreinfo openvswitch.dump ptmd.ptm switchd.mlx switchd.stack
switchd.fuse clag.clag network.kernel network.ifquery network.sfp
network.sfphex network.net_use network.ifupdown2_policy dot1x.config
system.versions system.logs system.systemd system.dmesg system.hwinfo
system.memory_use system.configs system.pkg system.misc system.uefi
system.time frr.frr neighmgr.neighmgr nvue.config lldp.lldp
Optional modules: switchd.verbose clag.clagkerneldB system.pkgverify
frr.ospftable frr.ospf6table frr.evpntable frr.bgptable nclu.config
The following example adds a prefix to the generated cl-support file name:
cumulus@switch:~$ sudo cl-support -p myprefix
Please send /var/support/myprefix_support_leaf01_20240214_184135.txz to Cumulus support.
The following example provides the reason for running the cl-support script:
cumulus@switch:~$ sudo cl-support -r "switchd crash"
Please send /var/support/cl_support_leaf01_20240214_184806.txz to Cumulus support.
Collect the NVMe NAND Debug Log
On an NVIDIA platform with a Virtium NVMe SSD, every cl-support run (automatic or manual) also collects the SSD’s internal NAND debug log, which Virtium uses to root-cause SSD failures. Collection requires no user action or configuration.
cl-support runs NAND log collection read-only and only after the existing SSD health collection finishes, so the two never access the NVMe controller at the same time. Collection does not change the SSD firmware, configuration, or data, and it leaves nothing on the switch afterward. cl-support bounds collection with a timeout and an output size limit, so a malfunctioning collection utility cannot exhaust system resources or fail the rest of the cl-support run.
The log appears in the archive as Support/nandlog_<ssd-serial>.bin, named after the SSD serial number. A summary of the collection, including the SSD model, serial number, resulting file name, and any error, appears in Support/nandlog.show.
Cumulus Linux only collects the NAND debug log from a Virtium NVMe SSD. On a switch without an NVMe SSD, or with a non-Virtium NVMe SSD, cl-support skips NAND log collection and records the reason; the rest of the cl-support run is unaffected. The utility that collects the log ships as part of the Cumulus Linux image, so a switch that reaches Cumulus Linux 5.19 only through an APT upgrade might not have it yet; if so, collection is skipped cleanly and the reason is recorded.
Delete cl-support Files
To delete a cl-support file from the switch, run the NVUE nv action delete system tech-support files <file-name> command. You can also use the Linux sudo rm /var/support/<file-name> command.
cumulus@switch:~$ nv action delete system tech-support files /var/support/cl_support_leaf01_20240725_221237.txz
Action executing ...
File Delete Succeeded
Action succeeded
Show cl-support Files
To show the cl-support files on the switch, run the nv show system tech-support files command. You can also run the Linux ls command on the /var/support directory (ls /var/support).
cumulus@switch:~$ nv show system tech-support files
File name File path
------------------------------------- --------------------------------------------------
cl_support_leaf01_20240725_225811.txz /var/support/cl_support_leaf01_20240725_225811.txz
Upload cl-support Files
To upload a cl-support file off the switch to an external location, run the nv action upload system tech-support files <file-name> <remote-url> command.
Related Information
For information on the directories included in the cl-support archive, see:
- Troubleshooting the etc Directory. The
/etcdirectory contains the largest number of files. - Troubleshooting Log Files. This guide highlights the most important log files to inspect. Keep in mind,
cl-supportincludes all log files.