CLI Troubleshooting

This guide covers common issues you may encounter with the OpsSquad CLI and how to resolve them.

Diagnostic Commands

Before troubleshooting, run these commands to gather information:

# Validate installation
opssquad node validate

# Check node status
opssquad node status

# View recent logs
opssquad node logs --lines=50

Common Issues

Node Won't Start

Symptoms:

• opssquad node start completes but node shows as stopped
• Status shows "Inactive" or "Failed"

Solutions:

1. Run validation:

   opssquad node validate

   This identifies configuration or permission issues.

2. Check logs for errors:

   opssquad node logs

   Look for error messages indicating the root cause.

3. Verify configuration exists:

   # System installation
   cat /etc/opssquad/node.yaml
   
   # User installation
   cat ~/.config/opssquad/node.yaml

4. Check binary exists:

   # System installation
   ls -la /usr/local/lib/opssquad/
   
   # User installation
   ls -la ~/.local/lib/opssquad/

Connectivity Problems

Symptoms:

• Node starts but shows "Disconnected"
• "Connection refused" or "timeout" errors in logs
• Node repeatedly reconnecting

Solutions:

1. Test network connectivity:

   # Check if you can reach the platform
   nc -zv socket.opssquad.ai 9000
   
   # Alternative test
   curl -v telnet://socket.opssquad.ai:9000

   If this fails, you have a network/firewall issue.

2. Check firewall rules:

   Ensure outbound TCP connections on port 9000 are allowed:

   # UFW (Ubuntu)
   sudo ufw status
   
   # iptables
   sudo iptables -L -n | grep 9000
   
   # firewalld (CentOS/RHEL)
   sudo firewall-cmd --list-all

3. Check DNS resolution:

   nslookup socket.opssquad.ai
   dig socket.opssquad.ai

4. Check for proxy interference:

   The node's TCP connection may not work through HTTP proxies. Try disabling proxy settings:

   unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
   opssquad node restart

Permission Errors

Symptoms:

• "Permission denied" errors
• Cannot read/write configuration files
• Service fails to start

Solutions:

System Installation (Root)

If you installed with sudo, always use sudo for management commands:

sudo opssquad node status
sudo opssquad node start
sudo opssquad node logs

Check file permissions:

# Configuration should be readable by root
sudo ls -la /etc/opssquad/

# Logs directory should be writable
sudo ls -la /var/log/opssquad/

Fix permissions if needed:

sudo chown -R root:root /etc/opssquad/
sudo chmod 600 /etc/opssquad/node.yaml
sudo chmod 755 /var/log/opssquad/

User Installation (Non-Root)

If you installed as a regular user, do not use sudo:

# Correct - no sudo
opssquad node status

# Incorrect - will cause permission conflicts
sudo opssquad node status  # Don't do this!

Check file permissions:

ls -la ~/.config/opssquad/
ls -la ~/.local/lib/opssquad/
ls -la ~/.local/log/opssquad/

Configuration Invalid

Symptoms:

• Validation fails with "invalid configuration"
• Node won't start due to config errors

Solutions:

1. Check YAML syntax:

   # Install yamllint
   pip install yamllint
   
   # Validate config
   yamllint /etc/opssquad/node.yaml

2. Verify required fields:

   The configuration must have node_id and token:

   app:
     node_id: "your-node-id"  # Required
     token: "your-token"      # Required

3. Check for special characters:

   If your token contains special characters, wrap it in quotes:

   app:
     token: "tok_live_key+with/special=chars"

4. Regenerate configuration:

   If config is corrupted, reinstall:

   opssquad node uninstall --force
   opssquad node install --node-id="your-id" --token="your-token"

macOS Security Warnings

Symptoms:

• "opssquad cannot be opened because the developer cannot be verified"
• Binary blocked by Gatekeeper

Solutions:

Using System Preferences

1. Open System Preferences (or System Settings on macOS Ventura+)
2. Go to Security & Privacy (or Privacy & Security)
3. Under the General tab, you should see a message about opssquad being blocked
4. Click Open Anyway or Allow Anyway
5. Try running the command again

Using Command Line

Remove the quarantine attribute:

sudo xattr -d com.apple.quarantine /usr/local/bin/opssquad
sudo xattr -d com.apple.quarantine /usr/local/lib/opssquad/*

Service Not Starting on Boot

Symptoms:

• Node runs when started manually but doesn't start on boot
• Systemd service not enabled

Solutions:

Check if the service is enabled:

sudo systemctl is-enabled opssquad-connectivity-layer

Enable it:

sudo systemctl enable opssquad-connectivity-layer

Check service status:

sudo systemctl status opssquad-connectivity-layer

View service logs:

sudo journalctl -u opssquad-connectivity-layer -f

Node Keeps Disconnecting

Symptoms:

• Frequent "reconnecting" messages in logs
• Node status fluctuates between Connected/Disconnected

Possible Causes:

1. Unstable network connection - Check network stability
2. Firewall timeout - Some firewalls close idle connections
3. Resource exhaustion - Check CPU/memory usage

Solutions:

# Check for network issues
ping -c 10 socket.opssquad.ai

# Check system resources
top -bn1 | head -20

# Check for connection resets in logs
opssquad node logs | grep -i "disconnect\|reconnect\|error"

Getting Help

If you cannot resolve the issue:

• Email Support: Contact [email protected] with output of opssquad node validate and opssquad node logs, plus your operating system and version.
• Community Discord: Join discord.gg/opssquad for real-time help from the community.
• GitHub Issues: Report bugs at github.com/opssquad/opssquad-cli-tool/issues.

Next Steps

• Commands Reference - Review all available CLI commands.
• Configuration - Learn about configuration options.