README.md (7391B)
1 # abduco a tool for session {at,de}tach support 2 3 [abduco](https://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](https://www.brain-dump.org/projects/dvtm) it provides a 8 simpler and cleaner alternative to tmux or screen. 9 10  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](https://www.brain-dump.org/projects/abduco/abduco-0.6.tar.gz) 21 [released](https://lists.suckless.org/dev/1603/28589.html) (24.03.2016) 22 * [abduco-0.5](https://www.brain-dump.org/projects/abduco/abduco-0.5.tar.gz) 23 [released](https://lists.suckless.org/dev/1601/28094.html) (09.01.2016) 24 * [abduco-0.4](https://www.brain-dump.org/projects/abduco/abduco-0.4.tar.gz) 25 [released](https://lists.suckless.org/dev/1503/26027.html) (18.03.2015) 26 * [abduco-0.3](https://www.brain-dump.org/projects/abduco/abduco-0.3.tar.gz) 27 [released](https://lists.suckless.org/dev/1502/25557.html) (19.02.2015) 28 * [abduco-0.2](https://www.brain-dump.org/projects/abduco/abduco-0.2.tar.gz) 29 [released](https://lists.suckless.org/dev/1411/24447.html) (15.11.2014) 30 * [abduco-0.1](https://www.brain-dump.org/projects/abduco/abduco-0.1.tar.gz) 31 [released](https://lists.suckless.org/dev/1407/22703.html) (05.07.2014) 32 * [Initial announcement](https://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 something 165 else related to abduco then write to the 166 [suckless developer mailing list](https://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)