Moving Running Processes Between Terminals With Reptyr

What is reptyr and When To Use It

reptyr is a utility program that allows attaching running Linux processes to a new terminal (TTY). It works by sending a SIGSTOP signal to the process to pause it, reassigning it to a new TTY device, and sending a SIGCONT signal to resume the process on the new terminal. Some scenarios where reptyr can be useful include:

• Reattaching background processes to the foreground terminal
• Moving screen/tmux sessions between terminals
• Changing the TTY of processes over SSH without interrupting the process
• Migrating processes between servers by reassigning TTYs

In essence, reptyr allows seamlessly moving processes between terminals without restarting them. This enables restoring sessions even when the original terminal is no longer available.

How reptyr Works

Under the hood, reptyr uses the native ptrace system call in Linux to attach to a running process and manipulate it. The key steps it follows are:

1. Use ptrace to attach to the process matched by the PID or TTY given
2. Stop the process using SIGSTOP so state can be manipulated
3. Open the new TTY device to reassign the process
4. Use pread and pwrite to transfer repl_tty data to new TTY
5. Set process controlling terminal to new TTY
6. Detach ptrace from process
7. Send SIGCONT to resume process on new TTY

By directly manipulating the process state via ptrace, reptyr is able to seamlessly transition even sophisticated programs like vim or ssh between terminals without ill effects.

Installing reptyr

reptyr is available as a package on most common Linux distributions like Debian, Ubuntu, Fedora, Arch, etc. To install:

Debian/Ubuntu

$ apt install reptyr

Fedora

 
$ dnf install reptyr

Arch Linux

$ pacman -S reptyr

Alternatively, the latest version can always be compiled from source code on GitHub:

$ git clone https://github.com/nelhage/reptyr
$ cd reptyr
$ make && sudo make install

Using reptyr Step-by-Step

Using reptyr is quite straightforward for basic reattachment of processes. The generic syntax is:

$ reptyr {PID|TTY} {NEW_TTY} 

For example, to reattach process with PID 1234 to the current TTY:

$ reptyr 1234 /dev/pts/1

Some useful flags include:

• -T

  – Specify target TTY instead of auto-creating a new one

• -d

  – Detach reptyr from process after reattach

• -p

  – Interpret matching identifier as PID instead of TTY

For reattaching processes that were background or originated over SSH, the user generally needs read + write access to the /dev/tty devices. Scripts run as root can reattach any process owned by same root user.

Reattaching Screen and tmux Sessions

reptyr can reattach detached screen and tmux sessions using the TTY identifier. For example, for a screen session attached to /dev/pts/2:

$ screen -rd session1
[detached]
$ ps aux | grep screen
user 1234 pts/2    screen
$ reptyr pts/2 /dev/pts/1

The session is now reattached onto current TTY while retaining its state. However, the old screens/tmux sessions may still remain as zombie processes. Be sure to kill these unneeded relics:

  
$ ps aux | grep zombie  
$ kill {old_session_pid}

Advanced Usage Examples

In production environments, verify normal user permissions work before relying on reptyr for recovering processes. Test key workflows by purposefully detaching terminals.

Some creative examples include:

• Migrating an SSH session from one server to another by reassigning the PTY device
• Transferring processes between Docker containers or VM TTYs
• Live process migration without containers using reptyr + SSH

Care should be taken with any advanced usage: suspend processes before TCP connections are severed to avoid data corruption.

Troubleshooting Common Issues

Some errors seen when reattaching processes with reptyr:

reptyr: can't initialize pty for target
reptyr: permission denied opening TTY
reptyr: opening new pts: Function not implemented

Ensure your user has read/write permissions for the target and source /dev/tty/ devices. Processes with elevated privileges may prevent reattaching under a normal user.

Stale repl_tty data in process state can also lead to permission errors. Try clearing stale TTY data:

$ echo 0 > /proc/{pid}/repl_tty
$ reptyr {pid} {new_tty}

Summary

reptyr is a powerful tool for moving Linux processes between terminals and restoring sessions. Key takeaways include:

• reptyr works by pausing processes, reassigning TTYs, and resuming
• Useful for reattaching background jobs and screen/tmux sessions
• Can help migrate sessions across servers with careful usage
• Requires read/write access to relevant TTY devices

With robust permission settings and testing, reptyr enables restoring critical sessions across various failure scenarios safely.