Signals

Signal handling and process management for NATS server

NATS server supports signal handling for graceful operations like reloading configuration, rotating logs, and shutting down.

Signal Command

Use the --signal flag to send signals to a running NATS server process:

nats-server --signal <signal>[=<pid>]

Signal Format

signal · string · required

The signal to send. Available signals: ldm, stop, quit, term, reopen, reload

pid · string

Process identifier. Can be either:

• A numeric PID (e.g., 1234)
• Path to a PID file (e.g., /var/run/nats-server.pid)

If not specified, signals are sent to all nats-server processes.

Available Signals

ldm - Log Debug and Memory

Dumps current goroutine stack traces and memory stats to the log.

Usage:

# Using PID file
nats-server --signal ldm=/var/run/nats-server.pid

# Using numeric PID
nats-server --signal ldm=12345

# To all nats-server processes
nats-server --signal ldm

Output Location:

• Written to the configured log file (if -l was used)
• Written to stdout if no log file configured

Use Cases:

• Debugging deadlocks
• Investigating high memory usage
• Troubleshooting performance issues

stop - Graceful Shutdown

Initiates graceful shutdown of the server. The server will:

1. Stop accepting new connections
2. Wait for existing clients to disconnect
3. Flush pending messages
4. Exit cleanly

Usage:

# Using PID file
nats-server --signal stop=/var/run/nats-server.pid

# Using numeric PID
nats-server --signal stop=12345

# To all nats-server processes
nats-server --signal stop

Equivalent System Signals:

• SIGINT (Ctrl+C)
• SIGTERM

quit - Immediate Shutdown

Immediately terminates the server without graceful cleanup.

Usage:

nats-server --signal quit=/var/run/nats-server.pid

Use quit only when stop fails or immediate termination is required. Prefer stop for graceful shutdown.

Equivalent System Signal:

• SIGQUIT

term - Terminate

Similar to stop, initiates graceful shutdown.

Usage:

nats-server --signal term=/var/run/nats-server.pid

Equivalent System Signal:

• SIGTERM

reopen - Rotate Log File

Reopens the log file. Used for log rotation with external tools like logrotate.

Usage:

nats-server --signal reopen=/var/run/nats-server.pid

Log Rotation Workflow:

1. External tool moves/renames the current log file
2. Send reopen signal to nats-server
3. Server closes old file handle and opens new log file

Example with logrotate:

# /etc/logrotate.d/nats-server
/var/log/nats-server.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        nats-server --signal reopen=/var/run/nats-server.pid
    endscript
}

Manual Rotation:

# Move current log
mv /var/log/nats-server.log /var/log/nats-server.log.1

# Signal server to reopen
nats-server --signal reopen=/var/run/nats-server.pid

# Server now writes to new /var/log/nats-server.log

reload - Reload Configuration

Reloads the server configuration from the config file without restarting.

Usage:

nats-server --signal reload=/var/run/nats-server.pid

What Gets Reloaded:

Authorization settings

• User credentials
• Permissions
• Account definitions

Logging settings

• Log level
• Debug/trace flags
• Log file path

Cluster settings

• Cluster permissions
• Authorization

Monitoring settings

• HTTP monitoring port settings

What Cannot Be Reloaded:

• Listen address and port
• Server name
• Cluster URL
• JetStream storage directory
• TLS certificates (requires restart)

Example:

# Edit configuration file
vim /etc/nats/nats-server.conf

# Reload configuration
nats-server --signal reload=/var/run/nats-server.pid

# Check logs for reload confirmation
tail -f /var/log/nats-server.log

Output:

[INF] Reloading server configuration
[INF] Reloaded server configuration

Using PID Files

For reliable signal delivery, start the server with a PID file:

# Start server with PID file
nats-server -c nats.conf -P /var/run/nats-server.pid

# Later, send signals using the PID file
nats-server --signal reload=/var/run/nats-server.pid

System Signal Equivalents

You can also send signals directly using standard Unix tools:

# Graceful shutdown
kill -SIGTERM $(cat /var/run/nats-server.pid)
kill -SIGINT $(cat /var/run/nats-server.pid)

# Immediate shutdown
kill -SIGQUIT $(cat /var/run/nats-server.pid)

# Reload configuration (SIGHUP)
kill -SIGHUP $(cat /var/run/nats-server.pid)

# Reopen log file (SIGUSR1)
kill -SIGUSR1 $(cat /var/run/nats-server.pid)

# Log debug and memory (SIGUSR2)
kill -SIGUSR2 $(cat /var/run/nats-server.pid)

Complete Examples

Production Server with Signal Support

# Start server with PID file
nats-server \
  -c /etc/nats/nats-server.conf \
  -P /var/run/nats-server.pid \
  -l /var/log/nats-server.log

# Reload configuration
nats-server --signal reload=/var/run/nats-server.pid

# Rotate logs
nats-server --signal reopen=/var/run/nats-server.pid

# Graceful shutdown
nats-server --signal stop=/var/run/nats-server.pid

Debug Running Server

# Dump goroutines and memory stats
nats-server --signal ldm=/var/run/nats-server.pid

# Check the log output
tail -100 /var/log/nats-server.log

Update Authorization

# Edit config to add new user
vim /etc/nats/nats-server.conf

# Reload without restart
nats-server --signal reload=/var/run/nats-server.pid

# New user can connect immediately

Emergency Shutdown

# Try graceful shutdown first
nats-server --signal stop=/var/run/nats-server.pid

# Wait 30 seconds
sleep 30

# If still running, force quit
if ps -p $(cat /var/run/nats-server.pid) > /dev/null; then
    nats-server --signal quit=/var/run/nats-server.pid
fi

Systemd Integration

For systemd-managed servers, signals are handled automatically:

# /etc/systemd/system/nats-server.service
[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nats-server -c /etc/nats/nats-server.conf -P /var/run/nats-server.pid
ExecReload=/usr/local/bin/nats-server --signal reload=/var/run/nats-server.pid
KillMode=mixed
KillSignal=SIGTERM
Restart=on-failure

[Install]
WantedBy=multi-user.target

Usage:

# Start service
sudo systemctl start nats-server

# Reload configuration
sudo systemctl reload nats-server

# Graceful stop
sudo systemctl stop nats-server

# Restart
sudo systemctl restart nats-server

Related Options

• Server Options - PID file configuration
• Logging Options - Log file and rotation settings