HEM(1)

NAME
hem - Persistent SSH connection and tunnel manager.

SYNOPSIS

    hem [-qv] [-c config_file] command [command_options] [profile...]
    hem init [-ef] [-d dir]
    hem manage [-Ae] profile...
    hem status [-cp] profile...
    hem up [-fp] profile...
    hem down [-s sig] profile...
    hem bounce profile...
    hem info [options] profile...

DESCRIPTION
Hem manages multiple background SSH connections using an ifconfig(8) / rc(8) style interface. The hem program is a front-end to multiple sub-commands: init, manage, status, up, down, bounce, and info. See the HEM COMMANDS section below for a description of each command.

When hem is invoked, it reads configuration information from ~/.hem/config, or the file specified by the --config argument, or the value of the HEM_CONFIG environment variable. See hem_config(5) for information on configuration values.

OPTIONS

-c, --config config_file
    Load configuration from config_file instead of the default configuration file location. The configuration file specifies the location of hem profiles and various other options that control its operation. See hem_config(5) for more information on configuration options and format.

-q, --quiet
    Do not write any non-critical output to stdout / stderr. Without the --quiet option, hem will write a small bit of informational output to stderr on what its doing.

-v, --verbose
    Write verbose messages typical reserved for the log to stderr in addition to normal informational output.

--help
    Show program usage and exit.

HEM COMMANDS
Each hem sub-command is fully documented under its own manual page:

hem-init(1)
    Initialize a new configuration directory (~/.hem by default) and check that ssh configuration is amenable to use with Hem.

hem-manage(1)
    Add a new connection profile and optionally authorize with the remote host. This command can also be used to edit existing profiles.

hem-info(1)
    Show configuration information for one or more profiles.

hem-status(1)
    Show connection status for one or more profiles.

hem-up(1)
    Bring connections up for one or more profiles.

hem-down(1)
    Take connections down for one or more profiles.

hem-bounce(1)
    Restart or reload the connection for one or more profiles.

CONNECTION PROFILES
All hem commands — with the exception of hem-init(1) — operate on one or more connection profiles. Each profile is represented by a file in the profiles directory: ~/.hem/profile (this can be overridden by setting the profile_dir variable in hem_config(5)).

A connection profile includes configuration for a single remote SSH connection. The profile filename is used to provide a minimal amount of connection information and is named similar to an SSH remote specifier: [user@]hostname[:port]. For example, you may have profiles named example.com, root@example.com, and toor@example.com:522.

EXAMPLES
Use the hem-init(1) command to initialize a new configuration directory:

    $ hem init
Add a connection profile for example.com with hem-manage(1) using your current username (USER environment variable), and another connection profile for legends.org with the username turing:

    $ hem manage example.com turing@legends.org
    writing ~/.hem/profile/example.com
    authorizing on example.com (~/.ssh/id_dsa.pub)
    Password: *************
    +++ public key added
    writing ~/.hem/profile/turing@legends.org
    authorizing on turing@legends.org (~/.ssh/id_dsa.pub)
    Password: *************
    +++ public key added
Note that, by default, hem-manage(1) will attempt to connect to the remote host and add authorize your public key for future sessions. You may be prompted for your remote password.

Use hem-status(1) to check connection state:

    $ hem status
    example.com                    down
    turing@legends.org             down
Bring up connection to legends.org only using hem-up(1):

    $ hem up turing@legends.org
    bringing up: turing@legends.org
Check connection status, again:

    $ hem status
    example.com                    down
    turing@legends.org             up            5432
Bring up all connections:

    $ hem up
    bringing up: example.com
    turing@legends.org is already up
Check connection status, again:

    $ hem status
    example.com                    up            5433
    turing@legends.org             up            5432
Take all connections down with hem-down(1):

    $ hem down
    taking down: example.com (pid: 5433)
    taking down: turing@legends.org (pid: 5432)

ENVIRONMENT VARIABLES

HEM_CONFIG
    If HEM_CONFIG is set, hem uses it as the location of the global configuration file. It overrides the default configuration file location (~/.hem/config), but is overridden by the -c invocation option.

HEM_EXEC
    The path to hem executables.

FILES

~/.hem/config
    This is the default per user configuration file. The settings in this file provide defaults for all connection profiles. Available configuration variables are described in the hem_config(5) manual page.

~/.hem/profile
    The default hem connection profile directory. Each file contains configuration for an individual remote SSH connection. Available configuration variables are described in the hem_profile(5) manual page.

~/.hem/run
    Hem stores .pid files for running connections in this directory by default. The location of this directory can be configured by setting the run_dir option. See hem_config(5) for more information.

~/.hem/log
    Hem logs messages here if no log_to option has been specified.

SEE ALSO
hem_config(5), ssh(1), ssh-agent(1), ssh_config(5).

AUTHOR
Written by Ryan Tomayko <r@tomayko.com>

RESOURCES
Web Site http://tomayko.com/src/hem/

Project Page http://github.com/rtomayko/hem/

COPYING
Copyright (C) 2008, Ryan Tomayko. Free use of this software is granted under the terms of the New and Simplified BSD License.

REFERENCES

1.  Ryan Tomayko
    http://tomayko.com/