1reptyr(1) General Commands Manual reptyr(1)
2
3
4
6 reptyr - Reparent a running program to a new terminal
7
9 reptyr PID
10
11 reptyr -l|-L [COMMAND [ARGS]]
12
13
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
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
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
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
125 reptyr was written by Nelson Elhage <nelhage@nelhage.com>.
126
127
129 ⟨https://github.com/nelhage/reptyr⟩
130
131
133 neercs(1), screen(1)
134
135
136
137 03 Feb 2011 reptyr(1)