README.md

   1 # abduco a tool for session {at,de}tach support
   2
   3 [abduco](http://www.brain-dump.org/projects/abduco) provides
   4 session management i.e. it allows programs to be run independently
   5 from their controlling terminal. That is programs can be detached -
   6 run in the background - and then later reattached. Together with
   7 [dvtm](http://www.brain-dump.org/projects/dvtm) it provides a
   8 simpler and cleaner alternative to tmux or screen.
   9
  10 ![abduco+dvtm demo](https://raw.githubusercontent.com/martanne/abduco/gh-pages/screencast.gif)
  11
  12 abduco is in many ways very similar to [dtach]("http://dtach.sf.net)
  13 but is a completely independent implementation which is actively maintained,
  14 contains no legacy code, provides a few additional features, has a
  15 cleaner, more robust implementation and is distributed under the
  16 [ISC license](https://raw.githubusercontent.com/martanne/abduco/master/LICENSE)
  17
  18 ## News
  19
  20  * [abduco-0.6](http://www.brain-dump.org/projects/abduco/abduco-0.6.tar.gz)
  21    [released](http://lists.suckless.org/dev/1603/28589.html) (24.03.2016)
  22  * [abduco-0.5](http://www.brain-dump.org/projects/abduco/abduco-0.5.tar.gz)
  23    [released](http://lists.suckless.org/dev/1601/28094.html) (09.01.2016)
  24  * [abduco-0.4](http://www.brain-dump.org/projects/abduco/abduco-0.4.tar.gz)
  25    [released](http://lists.suckless.org/dev/1503/26027.html) (18.03.2015)
  26  * [abduco-0.3](http://www.brain-dump.org/projects/abduco/abduco-0.3.tar.gz)
  27    [released](http://lists.suckless.org/dev/1502/25557.html) (19.02.2015)
  28  * [abduco-0.2](http://www.brain-dump.org/projects/abduco/abduco-0.2.tar.gz)
  29    [released](http://lists.suckless.org/dev/1411/24447.html) (15.11.2014)
  30  * [abduco-0.1](http://www.brain-dump.org/projects/abduco/abduco-0.1.tar.gz)
  31    [released](http://lists.suckless.org/dev/1407/22703.html) (05.07.2014)
  32  * [Initial announcement](http://lists.suckless.org/dev/1403/20372.html)
  33    on the suckless development mailing list (08.03.2014)
  34
  35 ## Download
  36
  37 Either download the latest source tarball
  38 [abduco-0.5.tar.gz](http://www.brain-dump.org/projects/abduco/abduco-0.5.tar.gz)
  39 with sha1sum
  40
  41     37c51a0d5c3dd216251d84d5c1b550f119ad53c9  abduco-0.5.tar.gz
  42
  43 compile and install it
  44
  45     ./configure && make && sudo make install
  46
  47 or use one of the distribution provided binary packages:
  48
  49  * [Debian](https://packages.debian.org/search?keywords=abduco)
  50  * [Fedora](https://admin.fedoraproject.org/pkgdb/package/abduco/)
  51  * [Gentoo](http://packages.gentoo.org/package/app-misc/abduco/)
  52  * [Ubuntu](http://packages.ubuntu.com/search?keywords=abduco)
  53  * [Mac OS X](http://www.braumeister.org/formula/abduco) via homebrew
  54
  55 ## Quickstart
  56
  57 In order to create a new session `abduco` requires a session name
  58 as well as an command which will be run. If no command is given
  59 the environment variable `$ABDUCO_CMD` is examined and if not set
  60 `dvtm` is executed. Therefore assuming `dvtm` is located somewhere
  61 in `$PATH` a new session named *demo* is created with:
  62
  63     $ abduco -c demo
  64
  65 An arbitrary application can be started as follows:
  66
  67     $ abduco -c session-name your-application
  68
  69 `CTRL-\` detaches from the active session. This detach key can be
  70 changed by means of the `-e` command line option, `-e ^q` would
  71 for example set it to `CTRL-q`.
  72
  73 To get an overview of existing session run `abduco` without any
  74 arguments.
  75
  76     $ abduco
  77     Active sessions (on host debbook)
  78     * Thu    2015-03-12 12:05:20    demo-active
  79     + Thu    2015-03-12 12:04:50    demo-finished
  80       Thu    2015-03-12 12:03:30    demo
  81
  82 A leading asterisk `*` indicates that at least one client is
  83 connected. A leading plus `+` denotes that the session terminated,
  84 attaching to it will print its exit status.
  85
  86 A session can be reattached by using the `-a` command line option
  87 in combination with the session name which was used during session
  88 creation.
  89
  90     $ abduco -a demo
  91
  92 If you encounter problems with incomplete redraws or other
  93 incompatibilities it is recommended to run your applications
  94 within [dvtm](https://github.com/martanne/dvtm) under abduco:
  95
  96     $ abduco -c demo dvtm your-application
  97
  98 Check out the manual page for further information and all available
  99 command line options.
 100
 101 ## Improvements over dtach
 102
 103  * **session list**, available by executing `abduco` without any arguments,
 104    indicating whether clients are connected or the command has already
 105    terminated.
 106
 107  * the **session exit status** of the command being run is always kept and
 108    reported either upon command termination or on reconnection
 109    e.g. the following works:
 110
 111         $ abduco -n demo true && abduco -a demo
 112         abduco: demo: session terminated with exit status 0
 113
 114  * **read only sessions** if the `-r` command line argument is used when
 115    attaching to a session, then all keyboard input is ignored and the
 116    client is a passive observer only.
 117
 118    Note that this is not a security feature, but only a convenient way to
 119    avoid accidental keyboard input.
 120
 121    If you want to make your abduco session available to another user
 122    in a read only fashion, use [socat](http://www.dest-unreach.org/socat/)
 123    to proxy the abduco socket in a unidirectional (from the abduco server
 124    to the client, but not vice versa) way.
 125
 126    Start your to be shared session, make sure only you have access to
 127    the `private` directory:
 128
 129         $ abduco -c /tmp/abduco/private/session
 130
 131    Then proxy the socket in unidirectional mode `-u` to a directory
 132    where the desired observers have sufficient access rights:
 133
 134         $ socat -u unix-connect:/tmp/abduco/private/session unix-listen:/tmp/abduco/public/read-only &
 135
 136    Now the observers can connect to the read-only side of the socket:
 137
 138         $ abduco -a /tmp/abduco/public/read-only
 139
 140    communication in the other direction will not be possible and keyboard
 141    input will hence be discarded.
 142
 143  * **better resize handling** on shared sessions, resize request are only
 144    processed if they are initiated by the most recently connected, non
 145    read only client.
 146
 147  * **socket recreation** by sending the `SIGUSR1` signal to the server
 148    process. In case the unix domain socket was removed by accident it
 149    can be recreated. The simplest way to find out the server process
 150    id is to look for abduco processes which are reparented to the init
 151    process.
 152
 153         $ pgrep -P 1 abduco
 154
 155    After finding the correct PID the socket can be recreated with
 156
 157         $ kill -USR1 $PID
 158
 159    If the abduco binary itself has also been deleted, but a session is
 160    still running, use the following command to bring back the session:
 161
 162         $ /proc/$PID/exe
 163
 164  * **improved socket permissions** the session sockets are by default either
 165    stored in `$HOME/.abduco` or `/tmp/abduco/$USER` in both cases it is
 166    made sure that only the owner has access to the respective directory.
 167
 168 ## Development
 169
 170 You can always fetch the current code base from the git repository.
 171
 172     git clone https://github.com/martanne/abduco.git
 173
 174 or
 175
 176     git clone git://repo.or.cz/abduco.git
 177
 178 If you have comments, suggestions, ideas, a bug report, a patch or something
 179 else related to abduco then write to the
 180 [suckless developer mailing list](http://suckless.org/community)
 181 or contact me directly mat[at]brain-dump.org.
 182
 183 [![Build Status](https://travis-ci.org/martanne/abduco.svg?branch=master)](https://travis-ci.org/martanne/abduco)
 184 [![Coverity Scan Build Status](https://scan.coverity.com/projects/4285/badge.svg)](https://scan.coverity.com/projects/4285)
 185
 186 ### Debugging
 187
 188 The protocol content exchanged between client and server can be dumped
 189 to temporary files as follows:
 190
 191     $ make debug
 192     $ ./abduco -n debug [command-to-debug] 2> server-log
 193     $ ./abduco -a debug 2> client-log
 194
 195 If you want to run client and server with one command (e.g. using the `-c`
 196 option) then within `gdb` the option `set follow-fork-mode {child,parent}`
 197 might be useful. Similarly to get a syscall trace `strace -o abduco -ff [abduco-cmd]`
 198 proved to be handy.
 199
 200 ## License
 201
 202 abduco is licensed under the [ISC license](https://raw.githubusercontent.com/martanne/abduco/master/LICENSE)