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#center)
  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](https://github.com/martanne/abduco/releases),
  38 compile and install it
  39
  40     ./configure && make && sudo make install
  41
  42 or use one of the distribution provided
  43 [binary packages](https://repology.org/project/abduco/packages).
  44
  45 ## Quickstart
  46
  47 In order to create a new session `abduco` requires a session name
  48 as well as an command which will be run. If no command is given
  49 the environment variable `$ABDUCO_CMD` is examined and if not set
  50 `dvtm` is executed. Therefore assuming `dvtm` is located somewhere
  51 in `$PATH` a new session named *demo* is created with:
  52
  53     $ abduco -c demo
  54
  55 An arbitrary application can be started as follows:
  56
  57     $ abduco -c session-name your-application
  58
  59 `CTRL-\` detaches from the active session. This detach key can be
  60 changed by means of the `-e` command line option, `-e ^q` would
  61 for example set it to `CTRL-q`.
  62
  63 To get an overview of existing session run `abduco` without any
  64 arguments.
  65
  66     $ abduco
  67     Active sessions (on host debbook)
  68     * Thu    2015-03-12 12:05:20    demo-active
  69     + Thu    2015-03-12 12:04:50    demo-finished
  70       Thu    2015-03-12 12:03:30    demo
  71
  72 A leading asterisk `*` indicates that at least one client is
  73 connected. A leading plus `+` denotes that the session terminated,
  74 attaching to it will print its exit status.
  75
  76 A session can be reattached by using the `-a` command line option
  77 in combination with the session name which was used during session
  78 creation.
  79
  80     $ abduco -a demo
  81
  82 If you encounter problems with incomplete redraws or other
  83 incompatibilities it is recommended to run your applications
  84 within [dvtm](https://github.com/martanne/dvtm) under abduco:
  85
  86     $ abduco -c demo dvtm your-application
  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 located at [Github](https://github.com/martanne/abduco/) or
 162 [Sourcehut](https://git.sr.ht/~martanne/abduco).
 163
 164 If you have comments, suggestions, ideas, a bug report, a patch or
 165 something else related to abduco then write to the
 166 [suckless developer mailing list](http://suckless.org/community)
 167 or contact me directly.
 168
 169 ### Debugging
 170
 171 The protocol content exchanged between client and server can be dumped
 172 to temporary files as follows:
 173
 174     $ make debug
 175     $ ./abduco -n debug [command-to-debug] 2> server-log
 176     $ ./abduco -a debug 2> client-log
 177
 178 If you want to run client and server with one command (e.g. using the `-c`
 179 option) then within `gdb` the option `set follow-fork-mode {child,parent}`
 180 might be useful. Similarly to get a syscall trace `strace -o abduco -ff
 181 [abduco-cmd]` proved to be handy.
 182
 183 ## License
 184
 185 abduco is licensed under the [ISC license](https://raw.githubusercontent.com/martanne/abduco/master/LICENSE)