Best Practices and Precautions for Running radiusdebug on Cloudpath Production Servers

Summary

This article outlines the recommended procedures, precautions, and recovery actions for using the radiusdebug utility command in Cloudpath environments. The radiusdebug utility in Cloudpath provides detailed RADIUS server debugging information and is commonly used to troubleshoot authentication failures, RADIUS service issues, and configuration corruption. Because radiusdebug runs the entire RADIUS server in a highly verbose debug mode, it can impact system performance and should be used with caution, particularly in production environments. Following the guidance in this article helps ensure safe troubleshooting while minimizing service disruption.

Question

What precautions and best practices should be followed when using the Cloudpath radiusdebug tool?

Customer Environment

Cloudpath Production Environment High-volume authentication deployments Replicated Cloudpath nodes Environments requiring RADIUS authentication troubleshooting and debugging

Resolution

Overview

The radiusdebug CLI command runs the entire RADIUS server (all ports) in the most verbose debugging mode as a standalone Linux process. This temporarily suspends the normal cloudpath-radiusd service; therefore, the klish system status check will not show RADIUS as running. The debug instance will continue to service all RADIUS requests. As a result, requests will still be processed, but system performance may be degraded due to the additional logging overhead. Use this command with caution in established production environments.

Best Practices

1. Use Only When Necessary

radiusdebug should primarily be used for:

RADIUS service startup failures
RADIUS service crash investigations
Corrupt or invalid configuration troubleshooting
Detailed authentication troubleshooting

Important: Do not run radiusdebug on RUCKUS-hosted systems unless a member of the Engineering team is actively involved in the troubleshooting session.

For high-volume production environments, consider limiting troubleshooting to specific clients whenever possible and perform debugging during off-peak hours.

2. Properly Exit the Debug Session

Always terminate the debug session using CTRL+C.

Do not simply close the terminal window.

After pressing CTRL+C, verify that the standard RADIUS service has resumed operation by monitoring the RADIUS log:

tail -F /var/log/radius/radius-port1812.log

3. Minimize Debug Duration

Due to the performance impact, keep the debug session active only for the minimum amount of time required to capture the issue, especially on high-volume sites.

The debug output should be logged to:

/var/log/radius/radiusdebug_output.log

4. Replicated Environments

In environments with replication enabled:

Run radiusdebug on only one node at a time.
Avoid running debug sessions simultaneously across multiple nodes.

Recovery Procedure

If the radiusdebug process becomes unresponsive and does not respond to CTRL+C, perform the following recovery steps:

Stop the debug process:

kill -9 radiusd

Restart the standard RADIUS service:

systemctl restart cloudpath-radiusd

After the service restart, verify normal operation by monitoring:

tail -F /var/log/radius/radius-port1812.log

Article Number:
000015563

Updated:
September 03, 2026 05:11 PM (20 days ago)

Tags:
Troubleshooting, Cloudpath

Votes:
0

This article is:
helpful
not helpful