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