Ubuntu Manpage: reptyr - Reparent a running program to a new terminal

NAME

       reptyr - Reparent a running program to a new terminal

SYNOPSIS

       reptyr PID

       reptyr -l|-L [COMMAND [ARGS]]

DESCRIPTION

       reptyr  is a utility for taking an existing running program and attaching it to a new terminal. Started a
       long-running process over ssh, but have to leave and don't want to interrupt it? Just start a screen, use
       reptyr to grab it, and then kill the ssh session and head on home.

       reptyr  works  by attaching to the target program using ptrace(2), redirecting relevant file descriptors,
       and changing the program's controlling terminal (See tty(4)) It is this last  detail  that  makes  reptyr
       work much better than alternatives such as retty(1).

       After attaching a program, the program will appear to be either backgrounded or suspended to the shell it
       was launched from (depending on the shell). For maximal safety you can run

              bg; disown

       in the old shell to remove the association with the program, but reptyr will attempt to ensure  that  the
       target program remains running even if you close the shell without doing so.

OPTIONS

-T

Use an alternate mode of attaching, "TTY-stealing". In this mode, reptyr will not ptrace(2) the
target process, but will attempt to discover the terminal emulator for that process' pty, and
steal the master end of the pty. This mode is more reliable and flexible in many circumstances
(for instance, it can attach all processes on a tty, rather than just a single process). However,
as a downside, children of sshd(8) cannot be attached via -T unless reptyr is run as root. See
⟨https://blog.nelhage.com/2014/08/new-reptyr-feature-tty-stealing/⟩ for more information about
tty-stealing.

-l, -L [COMMAND [ARGS]]

Instead of attaching to a new process, create a new pty pair, proxy the master end to the current
terminal, and then print the name of the slave pty. This can be passed to e.g. gdb´s set
inferior-tty option.

If an optional COMMAND and ARGS are passed in conjunction with -l, that command will be executed
as a child of reptyr with the REPTYR_PTY environment variable set to the name of the slave pty. If
-L is used instead of -l, then fds 0-2 of the child will also be redirected to point to the slave,
and the child will be run in a fresh session with the slave as its controlling terminal.

-s

By default, reptyr will move any file descriptors in the target that were connected to the
target's controlling terminal to point to the new terminal. The -s option will cause reptyr to
unconditionally attach file descriptors 0, 1, and 2 in the target, even if the target has no
controlling terminal or they are not connected to a terminal.

-v

Print the version of reptyr and exit.

-h

Print a usage message and exit.

-V

Print verbose debug output while running.

NOTES

       reptyr  depends  on  the  ptrace(2)  system  call to attach to the remote program. On Ubuntu Maverick and
       higher, this ability is disabled by default for security reasons. You can enable it temporarily by doing

               # echo 0 > /proc/sys/kernel/yama/ptrace_scope

       as root, or permanently by editing  the  file  /etc/sysctl.d/10-ptrace.conf,  which  also  contains  more
       information about this setting.

BUGS

       When  attaching  to some curses programs, they will not redraw the screen right away, and a ^L or similar
       will be needed to force a redraw.

       Similarly, after attaching to certain programs, the old terminal will be left in  an  odd  state,  and  a
       clear or even reset may be required before the old terminal is usable again.

       Attaching  to rtorrent (and probably some other apps) doesn't work right (rtorrent stops accepting input)
       (The problem is that rtorrent is using epoll to poll stdin, and we don't update  the  internal  reference
       that the epoll fd has to the old tty).

       Attaching to a process with children doesn't work right. This should be possible to fix -- I just need to
       ptrace each child individually and do the same games to it.

       Attaching a less(1) process doesn't work if you have a .lessfilter file, as less leaves around  a  zombie
       child in this case. This could be worked around.

       Bugs should be reported to the author (see below) or via the issue tracker on GitHub.

AUTHORS

       reptyr was written by Nelson Elhage <nelhage@nelhage.com>.

HOMEPAGE

       ⟨https://github.com/nelhage/reptyr⟩