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