In a Nutshell (🌰)
- Diagnose connection issues with Ansible, Docker, and system information
- Run comprehensive tests to validate device connectivity
- Troubleshoot authentication and configuration problems
- Verify that your device meets all requirements for SSM
Overview
The diagnostic tools in SSM allow you to verify the connectivity and configuration of your devices. When you encounter issues with device management, container operations, or playbook execution, the diagnostic tab provides valuable tools to identify and resolve problems.
Device Diagnostic Interface
Available Diagnostic Tests
SSM offers several diagnostic tests to validate different aspects of device connectivity:
Basic Connection Tests
| Test | Purpose | Requirements |
|---|---|---|
| Ansible Connection | Validates SSH connectivity for Ansible operations | Valid SSH credentials, Python on remote device |
| System Information | Tests ability to retrieve basic system data | SSH connectivity in agentless mode |
| Docker Connection | Verifies Docker engine connectivity | Docker installed and running on device |
Running Diagnostic Tests
Navigate to the device configuration page
↓
Select the Diagnostic tab
↓
Choose the test you want to run
↓
Click the Run Test button
↓
Wait for the test to complete
↓
Review the results
Test results will display with a success indicator (green/red) and detailed information about any issues encountered.
Interpreting Test Results
Success Indicators
- ✅ Green: Test passed successfully
- ❌ Red: Test failed
Common Issues and Solutions
Ansible Connection Issues
| Issue | Solution |
|---|---|
| SSH Authentication Failure | Verify your SSH credentials in the SSH configuration tab |
| Python Missing | Install Python on the remote device |
| Permission Denied | Ensure the SSH user has sufficient privileges |
System Information Issues
| Issue | Solution |
|---|---|
| Connection Timeout | Check network connectivity and firewall settings |
| Command Not Found | Verify system commands are available on the remote device |
Docker Connection Issues
| Issue | Solution |
|---|---|
| Docker Not Running | Start the Docker service on the remote device |
| Permission Denied | Add the SSH user to the docker group |
| API Version Mismatch | Update Docker to a compatible version |
Advanced Diagnostic Workflow
For comprehensive troubleshooting, follow this workflow:
- Start with Basic Tests: Run the basic connection tests first
- Review Logs: Check the detailed logs for specific error messages
- Verify Configuration: Review your device configuration for errors
- Run Advanced Tests: If basic tests fail, run advanced diagnostic tests
- Apply Fixes: Make the necessary changes based on test results
- Retest: Run the tests again to verify your fixes worked
Using Diagnostic Tools Effectively
When to Run Diagnostics
Purpose: Situations where running diagnostics is recommended.
Situations:
- After adding a new device
- When changing device configuration
- If container operations fail
- When playbook execution encounters errors
- After system updates on the device
Troubleshooting With Multiple Issues
Purpose: Approaching and resolving multiple diagnostic failures.
Proceed, in order:
- Start with the most fundamental issue (usually SSH connectivity)
- Resolve issues one at a time
- Rerun tests after each fix
- Document successful configurations for future reference