Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt

Use this file to discover all available pages before exploring further.

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:
  • User credentials
  • Permissions
  • Account definitions
  • Log level
  • Debug/trace flags
  • Log file path
  • Cluster permissions
  • Authorization
  • 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