Debian Codegraph @

README

raw
1 -*- Text -*- is good.
2
3 detachtty
4
5 detachtty lets you run interactive programs non-interactively, and
6 connect to them over the network when you do need to interact with them.
7
8 If you've used screen, it's a similar concept. Compared to screen,
9 detachtty has
10
11 * no capability to swap between different screens (it doesn't co-opt C-a)
12 * no tty emulation (you can sanely use it in emacs comint modes)
13 * no features (less to go wrong)
14 * no configuration file
15 * ability to spawn ssh to securely connect across the network
16
17 * What it's for - a likely usage scenario
18
19 I have a persistent server implemented in Lisp. Usually it sits there
20 serving things, but sometimes (for example when a new version is
21 available and it needs to be upgraded) I need to connect to it and
22 type Lisp at it.
23
24 Why don't I use screen? I could - I used to do exactly that - but
25 then I have to talk directly to the CMUCL repl, which means no command
26 line editing. I want to use ILISP, but (1) screen's terminal handling
27 is likely to confuse Emacs, (2) screen isn't network-enabled and the
28 server machine doesn't have Emacs installed anyway.
29
30 * How it works:
31
32 detachtty has two parts:
33
34 ** detachtty - the server
35
36 opens a pseudoterminal and starts your program on the slave end. It
37 then copies between that tty and a unix-domain socket whose location
38 you specify when you start it
39
40 detachtty has options to fork into the background, to specify the
41 socket location, and to govern the placement of its log file and of
42 the dribble file from the application underneath it
43
44 ** attachtty - the client
45
46 When you want to connect to the process, attachtty attaches to the
47 unix-domain socket and copies input/output to and from you.
48
49 If you have ssh installed and set up, you can also use attachtty
50 across the network. This requires
51
52 - that you also have attachtty installed on the machine that you are
53 running detachtty on, and that it's somewhere on the path
54
55 It's often nice to be able to interrupt a process, especially when
56 it's stuck in some kind of loop. attachtty catches SIGINT and sends
57 the character \003 into the pty master, which causes the controlled
58 process to get a SIGINT of its own. This works at least for using
59 with ILISP and CMUCL.
60
61 To terminate attachtty, sending it SIGQUIT (usually from the
62 keyboard with CONTROL+\): it will detach from the unix-domain socket,
63 leaving the server process running. Sometimes you need to press it twice.
64
65 You can also suspend and resume attachtty as a regular Unix process
66 (usually from the keyboard with CONTROL+Z). The server process
67 will keep running while attachtty is suspended.
68
69 * Using it - an example
70
71 server$ detachtty --help
72 detachtty: unrecognized option `--help'
73 usage:
74 detachtty [--no-detach] [--dribble-file name] [--log-file name] \
75 [--pid-file name] socket-path command [arg] [arg] [arg] ...
76
77 server$ detachtty --dribble-file /var/log/cliki-dribble --log-file \
78 /var/log/detachtty.log --pid-file /var/run/cliki.pid \
79 /var/run/cliki-socket /usr/bin/lisp -eval '(load-system :telentweb)' \
80 -eval '(progn (telentweb::init) (telentweb::start))' \
81
82 client$ attachtty dan@server:/var/run/cliki-socket
83
84 ** Signals and log files
85
86 When detachtty receives a SIGHUP, it closes and reopens its log and dribble
87 files, so it should play nice with whatever log rotation tools you already
88 use. Note that the dribble file especially can grow large quite quickly
89
90 The SIGHUP should be sent to detachtty, not to the child. What the child
91 does with signals depends entirely on what the child is ...
92
93
94 * Security considerations
95
96 - detachtty performs no authentication of who's attached. You choose
97 where the socket is created in the filesystem, so choose somewhere
98 that other people can't get to.
99
100 (detachtty creates its socket with mode 0700. Some Unix systems -
101 Linux among them - honour file permissions on sockets, so only the
102 original user or root will be able to connect to it. However, "many
103 BSD derived systems [...] ignore permissions for Unix sockets" so you
104 need to check if this will help you or not.)
105
106 - communication across the net is done using ssh. If there is a
107 program on your computer called "ssh", then whatever level of security
108 it provides is available here
109
110 - no serious effort has been made to examine the attachtty and
111 detachtty code for buffer overruns etc. If you are planning on using
112 these setuid or in some other untrusted-user situation, now is the
113 time to think of an alternative plan.
114
115
116 * Where to get it
117
118 detachtty development is hosted at <URL:https://github.com/cosmos72/detachtty>
119
120 Also, your distribution may (or may not) already contain it.
121 If it does, you will find that:
122
123 - on Debian, Ubuntu and other GNU/Linux systems that use ".deb" packages,
124 "apt-get install detachtty" will download and install it
125 - on RedHat, Fedora, CentOS and other GNU/Linux systems that use ".rpm" packages,
126 "yum install detachtty" will download and install it
127
128 Users of platforms that do not contain detachtty can download it from
129 <URL:https://github.com/cosmos72/detachtty/archive/master.tar.gz>
130 and compile and install it manually - see the INSTALL file inside the
131 downloaded package.
132
133
134 * Feedback, feature requests, patches
135
136 Use github issues at <URL:https://github.com/cosmos72/detachtty/issues>