abduco

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README | LICENSE

README.md (8017B)


      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)