Connection Issues

TL;DR

CMDOP connection problems typically stem from DNS resolution failures, firewall rules blocking outbound port 443, proxy misconfiguration, or network instability. The agent only requires outbound HTTPS on port 443 with no inbound ports needed, and works behind NAT. Run cmdop doctor for automated diagnostics, or use cmdop connect --debug for verbose connection logging to pinpoint the issue.

Why won’t my agent connect?

What are the symptoms?


Error: connection failed


Error: dial tcp: connection refused

How do I diagnose the problem?

Check internet connectivity:
```
curl https://api.cmdop.com/v1/health
```
Check agent status:
```
cmdop status
```

Check firewall:


# Test outbound 443
nc -zv grpc.cmdop.com 443

How do I fix connection failures?

DNS Resolution


# Check DNS
nslookup grpc.cmdop.com
 
# Try Google DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Firewall

CMDOP only requires outbound HTTPS (443). No inbound ports needed.


# Allow outbound 443 (iptables)
sudo iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
 
# Allow outbound 443 (ufw)
sudo ufw allow out 443

Proxy Configuration


export HTTPS_PROXY=http://proxy.company.com:8080
cmdop connect

Corporate Proxy with Auth


export HTTPS_PROXY=http://user:[email protected]:8080
cmdop connect

Why does my connection drop frequently?

What are the symptoms?

Terminal disconnects randomly
Agent shows “reconnecting…”
Sessions close unexpectedly

How do I diagnose dropping connections?


# Check network stability
ping -c 100 grpc.cmdop.com
 
# Check for packet loss
mtr grpc.cmdop.com

How do I fix frequent disconnections?

Increase Keepalive

The agent sends keepalive pings every 25 seconds by default. If your network has aggressive timeouts:


# Set environment variable
export CMDOP_KEEPALIVE_INTERVAL=15
cmdop connect

Check MTU


# Test MTU
ping -M do -s 1472 grpc.cmdop.com
 
# If fails, reduce MTU
sudo ip link set dev eth0 mtu 1400

WiFi Power Saving

Disable WiFi power management:


# Temporarily
sudo iwconfig wlan0 power off
 
# Permanently (NetworkManager)
echo -e "[connection]\nwifi.powersave = 2" | \
  sudo tee /etc/NetworkManager/conf.d/no-powersave.conf

Why is my session stuck in GRACE_PERIOD?

What are the symptoms?

Session shows GRACE_PERIOD status
Cannot attach to session
Have to wait or create new session

What does GRACE_PERIOD mean?

When a client disconnects, the server waits 30 seconds before closing the session. This allows reconnection without losing state.


Client disconnects → GRACE_PERIOD (30s) → Session closes
                          ↓
                    Reconnect → Session continues

How do I fix a stuck GRACE_PERIOD session?

Wait and reconnect:
- Session will close after 30 seconds
- Create new session

Force close (if you’re sure):


# List sessions
cmdop sessions
 
# Close specific session
cmdop sessions close <session-id>

Check for zombie clients:
- Multiple clients attached to same session
- One disconnected, one blocking

How do I fix multiple agents running on the same machine?

What are the symptoms?


Error: address already in use


Error: port file exists

How do I diagnose duplicate agents?


# Check for running agents
pgrep -f "cmdop connect"
 
# Check discovery file
cat ~/.cmdop/agent.info

How do I resolve duplicate agent conflicts?


# Kill all agents
pkill -f "cmdop connect"
 
# Remove stale discovery
rm -f ~/.cmdop/agent.info
 
# Start fresh
cmdop connect

How do I fix firewall blocking issues?

What are the symptoms?

Agent connects but no data flows
Commands timeout
File transfers fail

How do I diagnose firewall issues?


# Test gRPC
grpcurl grpc.cmdop.com:443 grpc.health.v1.Health/Check
 
# Test with curl
curl -v https://api.cmdop.com/v1/health

How do I configure common firewalls for CMDOP?

AWS Security Group

Required outbound rule:


Type: HTTPS
Protocol: TCP
Port: 443
Destination: 0.0.0.0/0

GCP Firewall


gcloud compute firewall-rules create allow-cmdop-out \
  --direction=EGRESS \
  --priority=1000 \
  --network=default \
  --action=ALLOW \
  --rules=tcp:443 \
  --destination-ranges=0.0.0.0/0

Azure NSG


az network nsg rule create \
  --resource-group myRG \
  --nsg-name myNSG \
  --name allow-cmdop \
  --priority 100 \
  --direction Outbound \
  --destination-port-ranges 443 \
  --protocol Tcp \
  --access Allow

Does CMDOP work behind NAT?

How does CMDOP handle NAT?

CMDOP uses outbound-only connections. No port forwarding needed.

The agent:

Connects outbound to grpc.cmdop.com:443
Maintains persistent connection
Receives commands over same connection

What about double NAT issues?

If behind double NAT (common in corporate environments):

Check for MTU issues
Verify keepalive works
Use explicit proxy if available

How do I fix connection timeout errors?

What are the symptoms?


Error: connection timeout after 10s

How do I resolve timeout issues?

Increase Timeout


export CMDOP_CONNECT_TIMEOUT=30
cmdop connect

Check DNS


# Measure DNS time
time nslookup grpc.cmdop.com
 
# If slow, use explicit IP
# (Not recommended for production)

Check Server Status


# Check status page
curl https://status.cmdop.com/api/v1/status

How do I fix TLS/certificate errors?

What are the symptoms?


Error: certificate verify failed

How do I fix certificate verification failures?

Update CA Certificates


# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates
 
# CentOS/RHEL
sudo yum update ca-certificates
 
# Alpine
apk add ca-certificates

Sync System Time

TLS requires correct time:


# Check time
date
 
# Sync with NTP
sudo timedatectl set-ntp true
 
# Or manually
sudo ntpdate pool.ntp.org

Self-Hosted Custom CA


# Add your CA
sudo cp company-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
 
# Or set env
export CMDOP_CA_FILE=/path/to/ca.crt
cmdop connect

How do I use debug mode for connection troubleshooting?

For detailed connection troubleshooting:


# Maximum verbosity
CMDOP_LOG_LEVEL=DEBUG cmdop connect --debug 2>&1 | tee debug.log

Check log for:

DNS resolution
TLS handshake
gRPC stream establishment
Authentication flow