Fork me on GitHub

Graceful Restarts


You can send signals to a Teleport daemon to get diagnostic or gracefully shut it down:

SignalTeleport Daemon Behavior
USR1Dumps diagnostics/debugging information into syslog.
QUITGraceful shutdown. The daemon will wait until connections are dropped.
TERM , INT or KILLImmediate non-graceful shutdown. All existing connections will be dropped.
USR2Forks a new Teleport daemon to serve new connections.
HUPForks a new Teleport daemon to serve new connections and initiates the graceful shutdown of the existing process when there are no more clients connected to it.

Graceful upgrades

In this guide we will try a manual graceful upgrade of a binary and a rollback using signals.

Locate a running teleport daemon PID:

Locate teleport process PID

pidof teleport


Unpack a new binary and replace a binary without stopping a server. Preserve the old binary, just in case if the upgrade goes wrong.

mv /usr/bin/teleport /usr/bin/teleport.bak
cp /new/binary/teleport /usr/bin/teleport

Fork a new teleport process:

kill -USR2 $(pidof teleport)

The original teleport process forked a new child process and passed existing file descriptors to the child. You now have two processes handling requests on the same socket:

pidof teleport

235276 235119

In our example, 235276 is a PID of the child process, and 235119 is a PID of the parent.

In the logs you will see that the parent process reports that it has forked a new child process, and the child accepts file descriptors from it's parent.

2021-08-19T10:16:51-07:00 [PROC:1]  INFO Forked new child process. path:/usr/local/teleport service/signals.go:457
2021-08-19T10:16:51-07:00 [PROC:1]  INFO Using file descriptor diag passed by the parent process. service/signals.go:207

Examine the logs and use the system. You have two options:

If the new binary behaves with errors, shut down the child process:

kill -TERM 235276

Do not forget to restore the original binary

mv /usr/bin/teleport.bak /usr/bin/teleport

You can retry the process again later.

Have a suggestion or can’t find something?