togs

A Terminal Emulation Manager with Session Toggling
using dvtm and dtach

Do Not Use! For historical reference only!
| Description | Installation | Usage | Configuration | Notes for Epic Users | Resources |

Description

Togs is a small shell script (sloccount<200) that combines dvtm, the console based tiling window manager, with the dtach utility to create an easy to use and powerful terminal emulation manager the ability to Toggle between Sessions.

Installation

In order for togs to work, you must also have dvtm and dtach installed. They may be available in your operating system's package manager, or you may choose to compile them yourself. Because of the configuration possibilities available in dvtm, I recommend that you compile that application yourself—it's very straightforward.

Togs versions (ChangeLog):

Download the script, rename to togs, copy to a bin directory in your path, and make it executable. For example:

    $ sudo cp togs-0.3 /usr/local/bin/togs
    $ sudo chmod 755 /usr/local/bin/togs

Development of togs is available on Gitorious.

    $ git clone git://gitorious.org/togs/togs.git

Copyright 2012, 2013 Ross Palmer Mohn <rpmohn@waxandwane.org>
Togs is licensed under an X11 style license.

Usage

 
    togs [-d rcdir] [sessionname [command]]
    togs [-d rcdir] -r oldname newname
    togs [-d rcdir] (-u | -l) sessionname

When you run togs for the first time it asks you for a session name and then opens the session.

    $ togs
    Session name: foo

You can also just put the session name you want to open as a command line parameter and it will open immediately.

    $ togs foo

The session name appears on the right hand side of the status bar as [SESSION: foo].

From within a togs session, you can press CTRL+\ to detach from the session and open a menu of options. From this menu you can easily switch to a different session, start a new session, or exit to the command line leaving all sessions detached and running in the background.

    Togs sessions running in /home/rpmohn/.togs:
        1) foo
        2) bar

    Session name or number:

At the menu's prompt, you can enter the name or number of the existing session you want to switch to. You can also start a new session by entering a different session name. If you want to detach from all sessions and return to the command line, just press Enter. Later, you can enter the command togs agein to open the same menu of options and continue using togs.

Sessions are private by default. You can share a session by unlocking it with the -u command line parameter.

    $ togs -u foo

When a session is unlocked, others can connect to it at the same time by specifying the appropriate shared resource directory after the -d command line parameter.

    $ togs -d /home/rpmohn/.togs/ foo

Later, you can make the session private again by locking it with the -l command line parameter.

    $ togs -l foo

If the original purpose of a session changes you can rename it to reflect its new purpose. When you do this, the name is changed and the session label in the status bar will update at the next status interval.

    $ togs -r foo baz

Sending commands to a session through togs is an optional feature. The default config.h file for dvtm includes a create command. and you can add more commands as desired. When you send the create command to a session it opens a new terminal in that session.

    $ togs foo create

There are many features available by keyboard shortcuts in your dvtm application. Please review the current dvtm and dtach manpages for their specific details. One example is the keyboard shortcut MOD+q which kills all clients and then the session. By default, MOD is mapped in dvtm to CTRL+g, so MOD+q is equivalent to pressing CTRL+g followed by q.

Configuration

Togs can be customized by editing the resource file. The default location of the resource file is ~/.togs/togsrc. Here are the default settings.

    # Status bar settings
    STATUS_COMMAND="date +%H:%M"
    STATUS_INTERVAL=60

    # dvtm path and options
    DVTM="dvtm"
    DVTM_OPTS=""
    DVTM_DBG="/dev/null"

    # dtach path and options
    DTACH="dtach"
    DTACH_OPTS="-r winch -z"

Here's an example of the customized status bar settings that I currently use. My status bar displays a warning for any filesystems over 95% full, average load statistics, and a custom date format.

    STATUS_COMMAND="df 2>/dev/null | grep -E '(9[5-9]|100)%' | sed 's/.* \([0-9]*%\) \(.*\)/\2:\1 - /'; \
        echo '['; uptime | sed 's/.*age: //'; echo '] '; \
        date +'%a %d-%b-%Y %R'"
    STATUS_INTERVAL=10

Besides customizing togs, there are many possibilites for customizing the dvtm application by making changes to its config.h file. For system administration work, I especially like the ability of dvtm to change foreground and background colors dynamically based on the value of a window's title. As an example, here is my current dvtm config.h file and below is a sample screenshot of a togs session named sysadmin. Among other automated visual queues, I have dvtm configured to switch to a yellowish background whenever I login to a production host and to switch my font to red whenever I su to root (see screenshot at the top of this page).

Notes for Epic Users

I currently work at Fletcher Allen Health Care as a Cache System Manager (among other roles :-) on their implementation of Epic's Electronic Health Record. Epic uses Intersystems Cache, which we run on IBM AIX.

My base script for quickly logging into Epic Cache Environments
I've written an Expect script called csess.exp, which I further shorten by aliasing it in my .bashrc to just the single letter 'c'. The top section of the script includes a proc macros {}, which has the basic framework for writing your own interactive Cache macros.

Note for working in an Intersystems Cache environment
In order to achieve the proper keyboard mappings in dvtm so that it works well work in Cache, you must add these escape sequence mappings at the end of your config.h file before compiling dvtm. This fixes the HOME and END keys and moves the four PF keys from the top row of the keypad (NumLock, /, *, -) to the first four function keys (F1, F2, F3, F4), which I think makes a lot more sense anyway.

    static char const * const keytable[] = {
        [KEY_HOME] = "\e[1~",
        [KEY_END]  = "\e[4~",
        [KEY_F(1)] = "\eOP",
        [KEY_F(2)] = "\eOQ",
        [KEY_F(3)] = "\eOR",
        [KEY_F(4)] = "\eOS",
    };

Note for compiling dvtm on AIX
You may need to patch your dvtm code before compiling on AIX in order to fix AIX's older implementation of the realpath() function. Try applying this patch to the dvtm.c file.

    diff --git a/dvtm.c b/dvtm.c
    index bff057b..656ca13 100644
    --- a/dvtm.c
    +++ b/dvtm.c
    @@ -1323,9 +1323,9 @@ parse_args(int argc, char *argv[]) {
                                    updatebarpos();
                                    break;
                            case 'c': {
    -                               const char *fifo;
    +                               char fifo[PATH_MAX];
                                    cmdfifo.fd = open_or_create_fifo(argv[++arg], &cmdfifo.fil
    -                               if (!(fifo = realpath(argv[arg], NULL)))
    +                               if (!realpath(argv[arg], fifo))
                                            error("%s\n", strerror(errno));
                                    setenv("DVTM_CMD_FIFO", fifo, 1);
                                    break;

In addition, you may need to modify the location of your ncurses header file at the top of source files dvtm.c and vt.h. For example:

    diff --git a/vt.h b/vt.h
    index 9ee9afe..91b2cd8 100644
    --- a/vt.h
    +++ b/vt.h
    @@ -19,7 +19,7 @@
     #ifndef VT_VT_H
     #define VT_VT_H

    -#include <curses.h>
    +#include <ncursesw/ncurses.h>
     #include <stdbool.h>
     #include <stdint.h>
     #include <stdlib.h>

And, of course, you'll need to modify the config.mk file to suit your system. Feel free to email me if you have any questions about getting dvtm to compile on AIX.

Note for compiling dtach on AIX
I submitted some patches to the dtach project so that it works on AIX. The patches were accepted and applied, but the project hasn't released a new version since January, 2008, so you'll have to grab a tarball from the dtach SCM repository. Click on the "Download GNU tarball" link at the bottom of that page and it should work fine.

Resources
Clipart is public domain