nodetool enablebinary¶

Enables the CQL native transport, allowing client connections.

Synopsis¶

nodetool [connection_options] enablebinary

Description¶

nodetool enablebinary enables the CQL native transport protocol, which handles all CQL client connections. When enabled, the node accepts connections on the native transport port (default: 9042) from CQL drivers and tools like cqlsh.

The native transport is Cassandra's primary client interface, supporting:

CQL queries - SELECT, INSERT, UPDATE, DELETE operations
Prepared statements - Pre-compiled queries for performance
Batch operations - Atomic multi-statement execution
Streaming results - Pagination for large result sets
Event notifications - Schema change and topology events

Behavior¶

When the native transport is enabled:

Cassandra begins listening on the configured native transport port
New client connections are accepted
The node can serve as a coordinator for CQL requests
Event listeners receive topology and schema notifications

Connection Handling

Existing connections established before a disable/enable cycle may need to reconnect. Most CQL drivers handle this automatically through their connection pooling logic.

Examples¶

Basic Usage¶

nodetool enablebinary

Verify Enabled¶

nodetool enablebinary
nodetool statusbinary
# Expected output: running

Test Client Connectivity¶

# Enable binary
nodetool enablebinary

# Verify with cqlsh
cqlsh localhost 9042 -e "SELECT now() FROM system.local"

When to Use¶

After Maintenance¶

Re-enable client connections after maintenance:

# Maintenance complete
nodetool enablebinary

# Verify
nodetool statusbinary

Recovery from Accidental Disable¶

If binary was accidentally disabled:

# Check status
nodetool statusbinary
# Output: not running

# Enable immediately
nodetool enablebinary

# Verify clients can connect
cqlsh localhost

After Node Restart Issues¶

If binary transport failed to start automatically:

# Check current state
nodetool statusbinary

# Enable if not running
nodetool enablebinary

# Check logs if it fails
tail -100 /var/log/cassandra/system.log | grep -i native

Controlled Traffic Restoration¶

Restore client traffic after a controlled outage:

# Verify cluster state first
nodetool status

# Enable binary to accept traffic
nodetool enablebinary

# Monitor for issues
watch nodetool tpstats

Workflow: Complete Node Recovery¶

After full node isolation, restore in the correct order:

# 1. Check current state
nodetool statusgossip  # Verify gossip is running
nodetool statusbinary  # Verify binary is not running

# 2. Ensure gossip is running first
if [ "$(nodetool statusgossip)" != "running" ]; then
    nodetool enablegossip
    sleep 5  # Wait for cluster sync
fi

# 3. Verify node is seen as UP by cluster
nodetool status | grep $(hostname -i)
# Should show "UN" (Up/Normal)

# 4. Enable binary transport
nodetool enablebinary

# 5. Verify operational
nodetool statusbinary  # running

# 6. Test client connectivity
cqlsh localhost -e "SELECT * FROM system.local"

Order of Operations¶

Restoring a Node¶

Always follow this order when restoring from isolation:

Step	Command	Reason
1	`enablegossip`	Node must be in cluster first
2	Wait 5-10 seconds	Allow cluster state sync
3	`enablebinary`	Now safe to accept clients

Enable Gossip First

Never enable binary while gossip is disabled. The node would accept requests but cannot coordinate properly with other nodes, leading to potential consistency issues.

Isolating a Node¶

The reverse order for isolation:

Step	Command	Reason
1	`disablebinary`	Stop new client connections
2	Wait for operations	Allow in-flight requests to complete
3	`disablegossip`	Then isolate from cluster

Port and Configuration¶

Default Configuration¶

Setting	Default	Description
`native_transport_port`	9042	Standard CQL port
`native_transport_port_ssl`	9142	SSL-enabled CQL port
`start_native_transport`	true	Auto-start on boot
`native_transport_max_threads`	128	Max client handler threads
`native_transport_max_frame_size_in_mb`	256	Max request size

Verifying Port Binding¶

# Check if port is listening
netstat -tlnp | grep 9042

# Or with ss
ss -tlnp | grep 9042

Verification¶

Command Verification¶

nodetool statusbinary
# Expected: running

Port Verification¶

# Verify port is listening
netstat -tlnp | grep 9042
# tcp  0  0 0.0.0.0:9042  0.0.0.0:*  LISTEN  <pid>/java

Client Connection Test¶

# Test with cqlsh
cqlsh localhost 9042 -e "DESCRIBE KEYSPACES"

# Test with simple query
cqlsh localhost -e "SELECT cluster_name FROM system.local"

Driver Connection Test¶

# Python driver test
python3 -c "
from cassandra.cluster import Cluster
cluster = Cluster(['localhost'])
session = cluster.connect()
print('Connected:', session.execute('SELECT now() FROM system.local').one())
cluster.shutdown()
"

Troubleshooting¶

Binary Won't Enable¶

If enablebinary doesn't work:

# Check JMX connectivity
nodetool info

# Check logs for errors
tail -100 /var/log/cassandra/system.log | grep -i "native\|binary"

# Check for port conflicts
netstat -tlnp | grep 9042

Port Already in Use¶

# Find process using port
lsof -i :9042

# Check if another Cassandra process is running
pgrep -f CassandraDaemon

Connection Refused After Enable¶

If clients get connection refused:

# Verify status
nodetool statusbinary

# Check listening address
grep native_transport /etc/cassandra/cassandra.yaml

# Verify firewall allows connections
iptables -L -n | grep 9042

SSL Configuration Issues¶

If using SSL and connections fail:

# Check SSL configuration in cassandra.yaml
grep -A20 client_encryption /etc/cassandra/cassandra.yaml

# Verify certificate files exist and are readable
ls -la /path/to/keystore.jks

# Check SSL port
netstat -tlnp | grep 9142

Monitoring After Enable¶

Watch Thread Pools¶

# Monitor for request handling
watch -n 2 'nodetool tpstats | head -20'

Check Client Connections¶

# Count active connections
netstat -an | grep 9042 | grep ESTABLISHED | wc -l

Monitor Latency¶

# Watch coordinator latencies
nodetool proxyhistograms

Client Behavior¶

Connection Pooling¶

Most CQL drivers maintain connection pools. After enabling binary:

Existing pooled connections may be stale
Drivers typically detect this and reconnect
Some drivers may need explicit reconnection

Retry Policies¶

Client retry policies determine behavior when binary is toggled:

Policy	Behavior
Default	Retry on same/next coordinator
Fallthrough	Fail immediately
DowngradingConsistency	Retry with lower CL

Driver Reconnection¶

Most drivers handle reconnection automatically:

# Python driver example - automatic reconnection
from cassandra.cluster import Cluster
from cassandra.policies import ConstantReconnectionPolicy

cluster = Cluster(
    ['node1', 'node2'],
    reconnection_policy=ConstantReconnectionPolicy(delay=5.0)
)

Automation Script¶

#!/bin/bash
# enable_client_access.sh - Safely enable client access

echo "=== Pre-checks ==="

# Verify gossip is running
if [ "$(nodetool statusgossip)" != "running" ]; then
    echo "ERROR: Gossip not running. Enable gossip first."
    echo "Run: nodetool enablegossip"
    exit 1
fi

# Check node status in cluster
status=$(nodetool status | grep "$(hostname -i)" | awk '{print $1}')
if [ "$status" != "UN" ]; then
    echo "WARNING: Node status is '$status', expected 'UN'"
    echo "Wait for node to be fully recognized before enabling binary"
fi

echo ""
echo "=== Enabling Binary Transport ==="

# Enable binary
nodetool enablebinary

# Verify
sleep 2
if [ "$(nodetool statusbinary)" = "running" ]; then
    echo "Binary transport enabled successfully"
else
    echo "ERROR: Failed to enable binary transport"
    exit 1
fi

# Test connectivity
echo ""
echo "=== Testing Connectivity ==="
if cqlsh localhost -e "SELECT now() FROM system.local" 2>/dev/null; then
    echo "CQL connection test: PASSED"
else
    echo "CQL connection test: FAILED"
    echo "Check logs: tail /var/log/cassandra/system.log"
fi

echo ""
echo "=== Current State ==="
echo "Gossip: $(nodetool statusgossip)"
echo "Binary: $(nodetool statusbinary)"
echo "Port 9042: $(netstat -tlnp 2>/dev/null | grep 9042 | awk '{print $4}')"

Best Practices¶

Binary Transport Guidelines

Enable gossip first - Always ensure cluster communication before client access
Verify before enabling - Check node is healthy and in cluster
Test after enabling - Verify clients can actually connect
Monitor thread pools - Watch for request handling issues
Gradual traffic restoration - Use load balancer to slowly add node back
Document in runbooks - Include enable/disable in maintenance procedures

Command	Relationship
disablebinary	Disable CQL transport
statusbinary	Check transport status
enablegossip	Enable gossip (do first)
statusgossip	Check gossip status
tpstats	Monitor thread pools
status	Check cluster status