stem

A Session oriented Terminal Emulation Manager
using dvtm and dtach

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

Description

Stem 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 Session oriented Terminal Emulation Manager.

Installation

In order for stem 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.

Stem versions (ChangeLog):

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

    $ sudo cp stem-0.2 /usr/local/bin/stem
    $ sudo chmod 755 /usr/local/bin/stem

Development of stem is available on Gitorious.

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

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

Usage

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

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

    $ stem
    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.

    $ stem foo

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

From within a stem 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.

    Stem sessions running in /home/rpmohn/.stem:
        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 stem agein to open the same menu of options and continue using stem.

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

    $ stem -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.

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

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

    $ stem -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.

    $ stem -r foo baz

Sending commands to a session through stem 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.

    $ stem 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

Stem can be customized by editing the resource file. The default location of the resource file is ~/.stem/stemrc. 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 %G-%b-%d %R'"
    STATUS_INTERVAL=10

Besides customizing stem, 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 stem session named sysadmin. Among other automated visual queues, I have dvtm configured to switch to a red background whenever I login to a production host and to switch my font to red whenever I su to root.

Notes

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 runs on IBM AIX and Intersystems Cache.

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;

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 courtesy Clipart ETC