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 < signa l > [= < pi d > ]
The signal to send. Available signals: ldm, stop, quit, term, reopen, reload
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:
Stop accepting new connections
Wait for existing clients to disconnect
Flush pending messages
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: 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: term - Terminate Similar to stop, initiates graceful shutdown.
Usage: nats-server --signal term=/var/run/nats-server.pid
Equivalent System Signal: 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:
External tool moves/renames the current log file
Send reopen signal to nats-server
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