example.conf

# The master block sets global options and defaults for remotes.  The
# master node can be given an optional alias ("fred" here); in the
# topology block and hotkey focus actions, the master node can be
# referred to by either this alias (as a quoted string) or the
# (unquoted) keyword 'master'.
master "fred" {
	# log-file: if set to a quoted string, sets the path of a file
	# to which log messages are written.  Can alternately be set
	# to one of the keywords 'none' (disable logging), 'stderr'
	# (send log messages to stderr), or 'syslog' (send log
	# messages to the system log).
	#
	# log-file = "/home/me/enthrall.log"
	# log-file = syslog
	# log-file = stderr

	# log-level: sets the degree of verbosity in what messages are
	# sent to the log.  Must be one of the following keywords:
	# error, warn, info, verbose, debug, debug2.
	#
	# log-level = info

	# remote-shell: provides the path to the ssh binary to use.
	# If not provided, the default is simply "ssh" (whatever is
	# first in $PATH).
	#
	# remote-shell = "/alternate/path/to/ssh"

	# port: if provided, this sets the argument passed to ssh's
	# "-p" flag to set the default port to connect to on remotes.
	#
	# port = 2244

	# bind-address: if specified, the given string is passed as
	# the argument to ssh's "-b" flag.  May be useful if you have
	# multiple NICs, a v4 and a v6 address on the same interface,
	# etc.
	#
	# bind-address = "2607:f8b0:4009:803::1009"

	# identity-file: if provided, sets the argument passed to
	# ssh's "-i" flag to set the default key used to authenticate
	# to remotes.
	#
	# identity-file = "~/.ssh/enthrall-key"

	# user: if provided, this sets the default argument passed to
	# ssh's "-l" flag to set the username to connect as on the
	# remote system.
	#
	# user = "jschmoe"

	# remote-command: the default path at which to find the
	# enthrall binary on the remotes.  If not provided, the
	# default is simply whatever 'enthrall' is found first in
	# $PATH.
	#
	# remote-command = "/usr/local/bin/enthrall"

	# reconnect-max-tries: the maximum number of times to attempt
	# reconnecting to a failed remote before giving up.  Defaults
	# to 10.
	#
	# reconnect-max-tries = 5

	# reconnect-max-interval: the maximum number of seconds to
	# wait between reconnection attempts.  Default is 30.
	#
	# reconnect-max-interval = 10

	# use-private-ssh-agent: whether or not enthrall should run
	# under its own private ssh-agent (useful for maintaining
	# strict control over which ssh keys are managed by which
	# agent process).  Can be set to 'yes' or 'no'.  Note that
	# enthrall will use *an* ssh-agent unconditionally; even if
	# this is set to 'no', if enthrall is unable to contact a
	# running ssh-agent it will override this setting and re-start
	# itself under its own private agent anyway.  Default is 'no'.
	#
	# use-private-ssh-agent = yes

	# show-focus: selects one of the following modes of providing
	# a visual hint of which node is focused (default is none):
	#
	#   dim-inactive BRIGHTNESS [DURATION NUMSTEPS]: the screens
	#   of non-active nodes are dimmed to the given fraction of
	#   their default brightness (~0.7 is probably a good starting
	#   point).  If DURATION and NUMSTEPS are specified, fade
	#   brightness transitions in NUMSTEPS steps over DURATION
	#   seconds (defaulting to 0 and 1, i.e. no fade).
	#
	#   flash-active BRIGHTNESS DURATION [NUMSTEPS]: when
	#   switching focus to a node, momentarily set its screen
	#   brightness to the given level (where "normal" is 1.0) for
	#   the specified time (in seconds).  If NUMSTEPS is
	#   specified, fade the flash out in the given number of steps
	#   over DURATION (defaulting to 1, i.e. no fade).  Note that
	#   nothing stops you from setting BRIGHTNESS to be less than
	#   1.0, so flash-active could also effectively act as a sort
	#   of "blink-active".
	#
	#   none: no visual focus hint.
	#
	# show-focus = dim-inactive 0.8 0.3 8
	# show-focus = flash-active 1.2 0.3 8
	# show-focus = flash-active 0.6 0.3 8

	# mouse-switch: selects one of the following mechanisms for
	# switching the focused node via the mouse (default is none):
	#
	#   slide: simply slide the mouse pointer off the edge of one
	#   node's display to have it slide onto the next node.
	#
	#   multi-tap COUNT WINDOW: "tap" the mouse pointer against an
	#   edge of a screen COUNT times within WINDOW seconds to
	#   switch focus in the corresponding direction.  With a COUNT
	#   of 1, WINDOW is ignored (this is equivalent to the 'slide'
	#   setting).  The maximum value for COUNT is determined by
	#   the macro EDGESTATE_HISTLEN if you really want to have to
	#   tap a lot of times to switch.
	#
	#   none: switch-by-mouse disabled.
	#
	# mouse-switch = slide
	# mouse-switch = multi-tap 2 0.4

	# show-null-switch: selects one of the following settings for
	# determining whether or not to trigger the configured visual
	# focus-hint mechanism (see 'show-focus') when a "null" switch
	# is performed (e.g. switching left from a node that has no
	# left neighbor or switching to an already-focused node):
	#
	#   yes: do trigger visual focus hint.
	#
	#   no: do not trigger visual focus hint.
	#
	#   hotkey-only: trigger only if the null switch was performed
	#   via a hotkey, not if done via mouse-switch.
	#
	# show-null-switch: hotkey-only

	# hotkeys: hotkey[HOTKEY_STRING] = ACTION
	#
	# valid values for HOTKEY_STRING are system-dependent; some
	# possible examples on X11 might look like:
	#   "mod1+mod4+L"
	#   "mod1+mod4+control+Right"
	#
	# Similar things on OSX:
	#   "command+option+l"
	#   "command+option+control+RightArrow"
	#
	# ACTION can be one of the following:
	#
	#   focus DIRECTION (where DIRECTION is one of left, right,
	#   up, or down): switch focus to the given neighbor of the
	#   currently-focused node.
	#
	#   focus NODE: switch focus directly to the specified NODE,
	#   which can be either a string, naming a node by alias, or
	#   the keyword 'master' -- note that since master is a
	#   keyword (not a string) it should not be quoted.
	#
	#   focus previous: switch focus to the previously-focused
	#   node (toggle between the two most recently focused nodes).
	#
	#   clear-clipboard: clear the clipboard on the master and all
	#   connected remotes.  Useful after copying/pasting sensitive
	#   data (e.g. passwords) between nodes.
	#
	#   reconnect: reset permanently-failed remotes to allow
	#   auto-reconnection to attempt to re-establish a connection.
	#
	#   halt-reconnects: stop all ongoing (re)connection attempts.
	#   This can be useful if you use 'ssh-add -c' to have your
	#   ssh-agent prompt for confirmation and have a graphical
	#   ssh-askpass to prompt you for this confirmation -- if you
	#   initiate an attempt to connect to a node that isn't going
	#   to work for whatever reason (e.g. it's not on the
	#   network), this can be used to stop the repeated
	#   reconnection attempts from getting in the way with
	#   incessant askpass dialogs for each failed reconnection
	#   attempt.
	#
	#   step-log-level DELTA: Add integer DELTA to the current log
	#   level, from a minumum of 'error' to a maximum of 'debug2'
	#   (see 'log-level').
	#
	#   quit: disconnect all remotes and terminate enthrall.

	# arrow-key-based direction-switching
	hotkey["mod1+mod4+control+Left"] = focus left
	hotkey["mod1+mod4+control+Right"] = focus right
	hotkey["mod1+mod4+control+Up"] = focus up
	hotkey["mod1+mod4+control+Down"] = focus down

	# vi-style direction-switching
	hotkey["mod1+mod4+control+H"] = focus left
	hotkey["mod1+mod4+control+L"] = focus right
	hotkey["mod1+mod4+control+K"] = focus up
	hotkey["mod1+mod4+control+J"] = focus down

	# direct-switch keys
	hotkey["mod1+mod4+control+1"] = focus "foo"
	hotkey["mod1+mod4+control+2"] = focus master
	hotkey["mod1+mod4+control+3"] = focus "bar"
	hotkey["mod1+mod4+control+4"] = focus "baz"

	# focus toggle
	hotkey["mod1+mod4+control+grave"] = focus previous

	hotkey["mod1+mod4+control+X"] = clear-clipboard
	hotkey["mod1+mod4+control+R"] = reconnect
	hotkey["mod1+mod4+control+minus"] = halt-reconnects

	hotkey["mod1+mod4+control+plus"] = step-log-level 1
	hotkey["mod1+mod4+control+minus"] = step-log-level -1
}

# A remote block defines a remote node with a given alias.
remote "foo" {
	# hostname: if provided, sets the network hostname to connect
	# to for this remote.  If not provided, defaults to the
	# remote's alias (e.g. "foo" in this example remote block).
	#
	# hostname = "somehost"
	# hostname = "192.168.2.4"
	hostname = "foo.mydomain.tld"

	# scroll-multiplier: an integer scroll-speed multiplier.
	# Negative values can be used to invert scroll direction if
	# desired.  The default value is 1.
	#
	# scroll-multiplier = 4
	# scroll-multiplier = -2

	# Each remote can also specify remote-shell, user, port,
	# bind-address, identity-file, and remote-command to provide a
	# per-remote override of the global defaults.
	#
	# remote-shell = "/alternate/path/to/ssh"
	# port = 22
	# identity-file = "~/.ssh/alternate-enthrall-key"
	# bind-address = "192.168.2.2"
	# user = "joe"
	# remote-command = "/alternate/path/to/enthrall"

	# Platform-specific remote configuration parameters are
	# specified as strings in a special unstructured 'param' map.
	# Currently the only setting that's used for anything is
	# DISPLAY to set the environment variable of the same name on
	# X11 systems, so X11 remotes should probably have something
	# like:
	#
	# param["DISPLAY"] = ":0"
}

remote "bar" {
	hostname = "bar.someother.tld"
}

# If a remote needs no non-default configuration options, the empty
# braces can be omitted:
remote "baz"

# The topology block specifies how nodes are arranged relative to each
# other (i.e. who's on which side of whom).
topology {
	# Each link in the node topology is specified as:
	#
	#   NODE DIRECTION = NODE [DIRECTION]
	#
	# where NODEs are node aliases or the keyword master, as used
	# elsewhere, and DIRECTIONs are (again) one of left, right, up
	# and down.  For example:
	#
	#   master right = "foo" left
	#   "foo" right = "bar" left
	#   "fred" down = "baz" up
	#
	# This specifies a topology like this:
	#
	#    master <-> foo <-> bar
	#      ^
	#      |
	#      v
	#     baz
	#
	master right = "foo" left
	"foo" right = "bar" left
	"fred" down = "baz" up

	# Note, however, that the DIRECTION specifier on the right
	# side of the equal sign is optional; if omitted, this
	# specifies a one-directional link.  Example:
	#
	#   master up = "foo"
	#   "foo" down = "bar"
	#
	# If you so desire, you can use this to create exotic
	# topologies wherein (for example) a 'focus left' followed by
	# a 'focus right' does *not* leave you where you started.
	# Knock yourself out.
}