reptyr(1)

1reptyr(1)                   General Commands Manual                  reptyr(1)
2
3
4

NAME

6       reptyr - Reparent a running program to a new terminal
7

SYNOPSIS

9       reptyr PID
10
11       reptyr -l|-L [COMMAND [ARGS]]
12
13

DESCRIPTION

15       reptyr  is a utility for taking an existing running program and attach‐
16       ing it to a new terminal. Started a long-running process over ssh,  but
17       have  to leave and don't want to interrupt it? Just start a screen, use
18       reptyr to grab it, and then kill the ssh session and head on home.
19
20       reptyr works by attaching to the target program using ptrace(2),  redi‐
21       recting  relevant file descriptors, and changing the program's control‐
22       ling terminal (See tty(4)) It is this last  detail  that  makes  reptyr
23       work much better than alternatives such as retty(1).
24
25
26       After  attaching  a program, the program will appear to be either back‐
27       grounded or suspended to the shell it was launched from  (depending  on
28       the shell). For maximal safety you can run
29
30              bg; disown
31
32       in the old shell to remove the association with the program, but reptyr
33       will attempt to ensure that the target program remains running even  if
34       you close the shell without doing so.
35
36

OPTIONS

38       -T
39
40              Use  an  alternate  mode  of  attaching, "TTY-stealing". In this
41              mode, reptyr will not ptrace(2) the  target  process,  but  will
42              attempt to discover the terminal emulator for that process' pty,
43              and steal the master end of the pty. This mode is more  reliable
44              and  flexible in many circumstances (for instance, it can attach
45              all processes on a tty, rather than just a single process). How‐
46              ever,  as a downside, children of sshd(8) cannot be attached via
47              -T unless reptyr is run as root. See ⟨https://blog.nelhage.com/
48              2014/08/new-reptyr-feature-tty-stealing/⟩  for  more information
49              about tty-stealing.
50
51       -l, -L [COMMAND [ARGS]]
52
53              Instead of attaching to a new process, create a  new  pty  pair,
54              proxy the master end to the current terminal, and then print the
55              name of the slave pty. This can be passed  to  e.g.   gdb´s  set
56              inferior-tty option.
57
58              If  an  optional COMMAND and ARGS are passed in conjunction with
59              -l, that command will be executed as a child of reptyr with  the
60              REPTYR_PTY  environment  variable  set  to the name of the slave
61              pty. If -L is used instead of -l, then fds 0-2 of the child will
62              also  be redirected to point to the slave, and the child will be
63              run in a fresh session with the slave as its controlling  termi‐
64              nal.
65
66       -s
67
68              By  default, reptyr will move any file descriptors in the target
69              that were connected to  the  target's  controlling  terminal  to
70              point  to  the  new terminal. The -s option will cause reptyr to
71              unconditionally attach file descriptors 0, 1, and 2 in the  tar‐
72              get,  even if the target has no controlling terminal or they are
73              not connected to a terminal.
74
75       -v
76
77              Print the version of reptyr and exit.
78
79       -h
80
81              Print a usage message and exit.
82
83       -V
84
85              Print verbose debug output while running.
86

NOTES

88       reptyr depends on the ptrace(2) system call to  attach  to  the  remote
89       program.  On  Ubuntu  Maverick  and higher, this ability is disabled by
90       default for security reasons. You can enable it temporarily by doing
91
92               # echo 0 > /proc/sys/kernel/yama/ptrace_scope
93
94       as     root,     or     permanently     by     editing     the     file
95       /etc/sysctl.d/10-ptrace.conf,  which  also  contains  more  information
96       about this setting.
97
98

BUGS

100       When attaching to some curses programs, they will not redraw the screen
101       right away, and a ^L or similar will be needed to force a redraw.
102
103       Similarly,  after  attaching to certain programs, the old terminal will
104       be left in an odd state, and a clear or  even  reset  may  be  required
105       before the old terminal is usable again.
106
107       Attaching to rtorrent (and probably some other apps) doesn't work right
108       (rtorrent stops accepting input) (The problem is that rtorrent is using
109       epoll  to  poll  stdin, and we don't update the internal reference that
110       the epoll fd has to the old tty).
111
112       Attaching to a process with children doesn't work right. This should be
113       possible to fix -- I just need to ptrace each child individually and do
114       the same games to it.
115
116       Attaching a less(1) process doesn't work  if  you  have  a  .lessfilter
117       file,  as less leaves around a zombie child in this case. This could be
118       worked around.
119
120       Bugs should be reported to the author (see  below)  or  via  the  issue
121       tracker on GitHub.
122
123

AUTHORS

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

HOMEPAGE

129       ⟨https://github.com/nelhage/reptyr⟩
130
131