mirror of
https://github.com/kaboomserver/buildpack.git
synced 2024-09-29 19:53:13 +00:00
211 lines
9 KiB
Plaintext
211 lines
9 KiB
Plaintext
|
1. INTRODUCTION
|
||
|
|
||
|
dtach is a program written in C that emulates the detach feature of
|
||
|
screen, which allows a program to be executed in an environment that is
|
||
|
protected from the controlling terminal. For instance, the program under
|
||
|
the control of dtach would not be affected by the terminal being
|
||
|
disconnected for some reason.
|
||
|
|
||
|
dtach was written because screen did not adequately meet my needs; I did
|
||
|
not need screen's extra features, such as support for multiple
|
||
|
terminals or terminal emulation support. screen was also too big,
|
||
|
bulky, and had source code that was difficult to understand.
|
||
|
|
||
|
screen also interfered with my use of full-screen applications such as
|
||
|
emacs and ircII, due to its excessive interpretation of the stream between
|
||
|
the program and the attached terminals. dtach does not have a terminal
|
||
|
emulation layer, and passes the raw output stream of the program to the
|
||
|
attached terminals. The only input processing that dtach does perform is
|
||
|
scanning for the detach character (which signals dtach to detach from
|
||
|
the program) and processing the suspend key (which tells dtach to
|
||
|
temporarily suspend itself without affecting the running program), and both
|
||
|
of these can both be disabled if desired.
|
||
|
|
||
|
Contrary to screen, dtach has minimal features, and is extremely tiny.
|
||
|
This allows dtach to be more easily audited for bugs and security
|
||
|
holes, and makes it accessible in environments where space is limited,
|
||
|
such as on rescue disks.
|
||
|
|
||
|
dtach has only been tested on the Linux/x86 platform, however it should
|
||
|
be easily portable to other variants of Unix. It currently assumes that
|
||
|
the host system uses POSIX termios, and has a working forkpty function
|
||
|
available.
|
||
|
|
||
|
dtach may need access to various devices in the filesystem depending on what
|
||
|
forkpty does. For example, dtach on Linux usually needs access to /dev/ptmx
|
||
|
and /dev/pts.
|
||
|
|
||
|
2. QUICK START
|
||
|
|
||
|
Compiling dtach should be simple, as it uses autoconf:
|
||
|
|
||
|
$ ./configure
|
||
|
$ make
|
||
|
|
||
|
If all goes well, a dtach binary should be built for your system. You can
|
||
|
then copy it to the appropriate place on your system.
|
||
|
|
||
|
dtach uses Unix-domain sockets to represent sessions; these are network
|
||
|
sockets that are stored in the filesystem. You specify the name of the
|
||
|
socket that dtach should use when creating or attaching to dtach sessions.
|
||
|
|
||
|
For example, let's create a new session that is running ircII. We will use
|
||
|
/tmp/foozle as the session's socket:
|
||
|
|
||
|
$ dtach -A /tmp/foozle irc RuneB irc.freenode.net
|
||
|
|
||
|
Here, -A tells dtach to either create a new session or attach to the
|
||
|
existing session. If the session at /tmp/foozle does not exist yet, the
|
||
|
program will be executed. If it does exist, then dtach will attach to
|
||
|
the existing session.
|
||
|
|
||
|
dtach has another attach mode, which is specified by using -a. The -a
|
||
|
mode attaches to an already existing session, but will not create a new
|
||
|
session. Each attaching process can have a separate detach character,
|
||
|
suspend behavior, and redraw method, which are explained in the
|
||
|
following sections.
|
||
|
|
||
|
dtach is able to attach to the same session multiple times, though you
|
||
|
will likely encounter problems if your terminals have different window
|
||
|
sizes. Pressing ^L (Ctrl-L) will reset the window size of the program to
|
||
|
match the current terminal.
|
||
|
|
||
|
dtach also has a mode that copies the contents of standard input to a session.
|
||
|
For example:
|
||
|
|
||
|
$ echo -ne 'cd /var/log\nls -l\n' | dtach -p /tmp/foozle
|
||
|
|
||
|
The contents are sent verbatim including any embedded control characters (e.g.
|
||
|
the newline characters in the above example), and dtach will not scan the
|
||
|
input for a detach character.
|
||
|
|
||
|
3. DETACHING FROM THE SESSION
|
||
|
|
||
|
By default, dtach scans the keyboard input looking for the detach character.
|
||
|
When the detach character is pressed, dtach will detach from the current
|
||
|
session and exit, leaving the program running in the background. You can then
|
||
|
re-attach to the program by running dtach again with -A or -a.
|
||
|
|
||
|
The default detach character is ^\ (Ctrl-\). This can be changed by supplying
|
||
|
the -e option to dtach when attaching. For example:
|
||
|
|
||
|
$ dtach -a /tmp/foozle -e '^A'
|
||
|
|
||
|
That command would attach to the existing session at /tmp/foozle and use
|
||
|
^A (Ctrl-A) as the detach character, instead of the default ^\.
|
||
|
|
||
|
You can disable processing of the detach character by supplying the -E
|
||
|
option to dtach when attaching.
|
||
|
|
||
|
4. SUSPENDING DTACH
|
||
|
|
||
|
By default, dtach also processes the suspend key (^Z or Ctrl-Z) itself,
|
||
|
instead of passing it to the program. Thus, pressing suspend only suspends
|
||
|
the attaching process, instead of the running program. This can be very
|
||
|
useful for applications such as ircII, where you may not necessarily want
|
||
|
the program to be suspended.
|
||
|
|
||
|
Processing of the suspend key can be disabled by supplying the -z option
|
||
|
to dtach when attaching.
|
||
|
|
||
|
5. REDRAW METHOD
|
||
|
|
||
|
When attaching, dtach can use one of three methods to redraw the screen
|
||
|
(none, ctrl_l, or winch). By default, dtach uses the ctrl_l method,
|
||
|
which simply sends a ^L (Ctrl-L) character to the program if the
|
||
|
terminal is in character-at-a-time and no-echo mode. The winch method
|
||
|
forces a WINCH signal to be sent to the program, and the none method
|
||
|
disables redrawing completely.
|
||
|
|
||
|
For example, this command tells dtach to attach to a session at
|
||
|
/tmp/foozle and use the winch redraw method:
|
||
|
|
||
|
$ dtach -a /tmp/foozle -r winch
|
||
|
|
||
|
When creating a new session (with the -c or -A modes), the specified
|
||
|
method is used as the default redraw method for the session.
|
||
|
|
||
|
6. CHANGES
|
||
|
|
||
|
The changes in version 0.9 are:
|
||
|
- Added AIX support.
|
||
|
- Added dtach -N, a mode similar to dtach -n, except dtach will stay in the
|
||
|
foreground instead of daemonizing.
|
||
|
- Added dtach -p, which copies the contents of standard input to a session.
|
||
|
- dtach will no longer send 255 bytes of garbage to the program when read()
|
||
|
returns an error.
|
||
|
- The executable bit is now set on the socket if clients are attached, and
|
||
|
cleared when all clients have detached.
|
||
|
- The initial state of signals such as SIGPIPE are now preserved when
|
||
|
executing the program, instead of having the program start with some signals
|
||
|
ignored.
|
||
|
- A buffer overflow no longer occurs when a long socket path name is used, and
|
||
|
dtach will now try to use chdir to get around the length limitation if
|
||
|
necessary.
|
||
|
|
||
|
The changes in version 0.8 are:
|
||
|
- When using dtach -A or dtach -c, the master will now wait until the client
|
||
|
attaches before trying to read from the program being executed. This avoids
|
||
|
a race condition when the program prints something and exits before the
|
||
|
client can attach itself.
|
||
|
- Instead of exiting quietly, dtach will now report any errors that occur
|
||
|
while trying to execute the program.
|
||
|
- dtach -n can now be used without a terminal.
|
||
|
- dtach -A will now try to detect and remove stale sockets.
|
||
|
- Removed a Linux-specific escape sequence from the code that restores the
|
||
|
original terminal settings.
|
||
|
- Changed dtach.1 to use \- for the dashes in command line options, and
|
||
|
fix an ambiguous backslash.
|
||
|
- Use non-blocking mode in the master process, and avoid data loss by ensuring
|
||
|
that at least one attaching client succesfully completes a write.
|
||
|
- Fix -e ^<char> to work with lowercase characters.
|
||
|
|
||
|
The changes in version 0.7 are:
|
||
|
- The redraw method can now be explicitly specified on the command line
|
||
|
(either no redraw at all, the old ^L character method, and the new WINCH
|
||
|
signal method), since many programs only handle one or the other properly.
|
||
|
- Changed the default redraw method back to the old ^L character method.
|
||
|
- Changed the attach code to check the return value of select more carefully.
|
||
|
- Changed the SIGWINCH handler to reinstall itself, to handle systems that
|
||
|
always reset the handler.
|
||
|
- Added more proper process group handling.
|
||
|
|
||
|
The changes in version 0.6 are:
|
||
|
- Redraws are now handled by sending the child process a WINCH signal instead
|
||
|
of by sending a ^L character. This should help prevent line-oriented
|
||
|
programs (such as bash) from clearing the screen excessively.
|
||
|
- Flow control is now disabled when setting raw mode on the terminal.
|
||
|
- Switched to using select instead of poll.
|
||
|
- Changed some exits to exit succesfully instead of non-sucessfully.
|
||
|
- Updated my email address.
|
||
|
- Updated to Autoconf 2.59, renaming some files in the process.
|
||
|
|
||
|
The changes in version 0.5 are:
|
||
|
- Fix fd leakage.
|
||
|
- Prevent atexit from being called twice on dtach -A.
|
||
|
|
||
|
The changes in version 0.4 are:
|
||
|
- Slightly improved README and dtach.1
|
||
|
- Portability updates thanks to sourceforge's compile farm. dtach should now
|
||
|
work on: FreeBSD, Debian/alpha, Debian/sparc, Debian/PPC, and Solaris.
|
||
|
|
||
|
The changes in version 0.3 are:
|
||
|
- Fixed a typo in dtach.1
|
||
|
- Changed the attach code so that it tells the master when a suspend
|
||
|
occurs.
|
||
|
- Decreased the client <-> master packet size.
|
||
|
- Changed the master to send a stream of text to attaching clients
|
||
|
instead of sending a huge packet all the time.
|
||
|
- Use getrlimit and dynamically allocate the data structures, if
|
||
|
possible.
|
||
|
- Added some more autoconf checks.
|
||
|
- Initial sourceforge release.
|
||
|
|
||
|
7. AUTHOR
|
||
|
|
||
|
dtach is (C)Copyright 2004-2016 Ned T. Crigler, and is under the GNU General
|
||
|
Public License.
|
||
|
|
||
|
Comments and suggestions about dtach are welcome, and can be sent to
|
||
|
the author at: <crigler@users.sourceforge.net>.
|