Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/martanne/abduco

abduco provides session management i.e. it allows programs to be run independently from its controlling terminal. That is programs can be detached - run in the background - and then later reattached. Together with dvtm it provides a simpler and cleaner alternative to tmux or screen.
https://github.com/martanne/abduco

Last synced: 1 day ago
JSON representation

abduco provides session management i.e. it allows programs to be run independently from its controlling terminal. That is programs can be detached - run in the background - and then later reattached. Together with dvtm it provides a simpler and cleaner alternative to tmux or screen.

Awesome Lists containing this project

README 

        
# abduco a tool for session {at,de}tach support



[abduco](https://www.brain-dump.org/projects/abduco) provides

session management i.e. it allows programs to be run independently

from their controlling terminal. That is programs can be detached -

run in the background - and then later reattached. Together with

[dvtm](https://www.brain-dump.org/projects/dvtm) it provides a

simpler and cleaner alternative to tmux or screen.



![abduco+dvtm demo](https://raw.githubusercontent.com/martanne/abduco/gh-pages/screencast.gif#center)



abduco is in many ways very similar to [dtach](http://dtach.sf.net)

but is a completely independent implementation which is actively maintained,

contains no legacy code, provides a few additional features, has a

cleaner, more robust implementation and is distributed under the

[ISC license](https://raw.githubusercontent.com/martanne/abduco/master/LICENSE)



## News



 * [abduco-0.6](https://www.brain-dump.org/projects/abduco/abduco-0.6.tar.gz)

   [released](https://lists.suckless.org/dev/1603/28589.html) (24.03.2016)

 * [abduco-0.5](https://www.brain-dump.org/projects/abduco/abduco-0.5.tar.gz)

   [released](https://lists.suckless.org/dev/1601/28094.html) (09.01.2016)

 * [abduco-0.4](https://www.brain-dump.org/projects/abduco/abduco-0.4.tar.gz)

   [released](https://lists.suckless.org/dev/1503/26027.html) (18.03.2015)

 * [abduco-0.3](https://www.brain-dump.org/projects/abduco/abduco-0.3.tar.gz)

   [released](https://lists.suckless.org/dev/1502/25557.html) (19.02.2015)

 * [abduco-0.2](https://www.brain-dump.org/projects/abduco/abduco-0.2.tar.gz)

   [released](https://lists.suckless.org/dev/1411/24447.html) (15.11.2014)

 * [abduco-0.1](https://www.brain-dump.org/projects/abduco/abduco-0.1.tar.gz)

   [released](https://lists.suckless.org/dev/1407/22703.html) (05.07.2014)

 * [Initial announcement](https://lists.suckless.org/dev/1403/20372.html)

   on the suckless development mailing list (08.03.2014)



## Download



Either download the latest [source tarball](https://github.com/martanne/abduco/releases),

compile and install it



    ./configure && make && sudo make install



or use one of the distribution provided

[binary packages](https://repology.org/project/abduco/packages).



## Quickstart



In order to create a new session `abduco` requires a session name

as well as an command which will be run. If no command is given

the environment variable `$ABDUCO_CMD` is examined and if not set

`dvtm` is executed. Therefore assuming `dvtm` is located somewhere

in `$PATH` a new session named *demo* is created with:



    $ abduco -c demo



An arbitrary application can be started as follows:



    $ abduco -c session-name your-application



`CTRL-\` detaches from the active session. This detach key can be

changed by means of the `-e` command line option, `-e ^q` would

for example set it to `CTRL-q`.



To get an overview of existing session run `abduco` without any

arguments.



    $ abduco

    Active sessions (on host debbook)

    * Thu    2015-03-12 12:05:20    demo-active

    + Thu    2015-03-12 12:04:50    demo-finished

      Thu    2015-03-12 12:03:30    demo



A leading asterisk `*` indicates that at least one client is

connected. A leading plus `+` denotes that the session terminated,

attaching to it will print its exit status.



A session can be reattached by using the `-a` command line option

in combination with the session name which was used during session

creation.



    $ abduco -a demo



If you encounter problems with incomplete redraws or other

incompatibilities it is recommended to run your applications

within [dvtm](https://github.com/martanne/dvtm) under abduco:



    $ abduco -c demo dvtm your-application



Check out the manual page for further information and all available

command line options.



## Improvements over dtach



 * **session list**, available by executing `abduco` without any arguments,

   indicating whether clients are connected or the command has already

   terminated.



 * the **session exit status** of the command being run is always kept and

   reported either upon command termination or on reconnection

   e.g. the following works:



        $ abduco -n demo true && abduco -a demo

        abduco: demo: session terminated with exit status 0



 * **read only sessions** if the `-r` command line argument is used when

   attaching to a session, then all keyboard input is ignored and the

   client is a passive observer only.



   Note that this is not a security feature, but only a convenient way to

   avoid accidental keyboard input.



   If you want to make your abduco session available to another user

   in a read only fashion, use [socat](http://www.dest-unreach.org/socat/)

   to proxy the abduco socket in a unidirectional (from the abduco server

   to the client, but not vice versa) way.



   Start your to be shared session, make sure only you have access to

   the `private` directory:



        $ abduco -c /tmp/abduco/private/session



   Then proxy the socket in unidirectional mode `-u` to a directory

   where the desired observers have sufficient access rights:



        $ socat -u unix-connect:/tmp/abduco/private/session unix-listen:/tmp/abduco/public/read-only &



   Now the observers can connect to the read-only side of the socket:



        $ abduco -a /tmp/abduco/public/read-only



   communication in the other direction will not be possible and keyboard

   input will hence be discarded.



 * **better resize handling** on shared sessions, resize request are only

   processed if they are initiated by the most recently connected, non

   read only client.



 * **socket recreation** by sending the `SIGUSR1` signal to the server

   process. In case the unix domain socket was removed by accident it

   can be recreated. The simplest way to find out the server process

   id is to look for abduco processes which are reparented to the init

   process.



        $ pgrep -P 1 abduco



   After finding the correct PID the socket can be recreated with



        $ kill -USR1 $PID



   If the abduco binary itself has also been deleted, but a session is

   still running, use the following command to bring back the session:



        $ /proc/$PID/exe



 * **improved socket permissions** the session sockets are by default either

   stored in `$HOME/.abduco` or `/tmp/abduco/$USER` in both cases it is

   made sure that only the owner has access to the respective directory.



## Development



You can always fetch the current code base from the git repository

located at [Github](https://github.com/martanne/abduco/) or

[Sourcehut](https://git.sr.ht/~martanne/abduco).



If you have comments, suggestions, ideas, a bug report, a patch or something

else related to abduco then write to the

[suckless developer mailing list](https://suckless.org/community)

or contact me directly.



### Debugging



The protocol content exchanged between client and server can be dumped

to temporary files as follows:



    $ make debug

    $ ./abduco -n debug [command-to-debug] 2> server-log

    $ ./abduco -a debug 2> client-log



If you want to run client and server with one command (e.g. using the `-c`

option) then within `gdb` the option `set follow-fork-mode {child,parent}`

might be useful. Similarly to get a syscall trace `strace -o abduco -ff

[abduco-cmd]` proved to be handy.



## License



abduco is licensed under the [ISC license](https://raw.githubusercontent.com/martanne/abduco/master/LICENSE)