NAME¶

fonehome — establish connection to fonehome server

SYNOPSIS¶

DESCRIPTION¶

fonehome is a wrapper for the ssh(1) program. It creates a persistent no-pty ssh(1) connection to one or more fonehome servers, with normal and reverse port forwarding setup according to the configuration in /etc/fonehome/fonehome.conf. This allows private, bi-directional connections between the fonehome client and server, while keeping those connections fully secured, without requiring any firewall setup.

fonehome is useful in situations where you have several machines deployed in the field and want to maintain secure access to them from a central operations server without any firewall hassles.

Normally fonehome is run as a systemd(1) service. However, upon first installation (or whenever a server's host key changes), a manual initialization step must be performed by running fonehome manually with the -I flag. This allows the administrator to confirm and accept the server host key(s).

OPTIONS¶

-f config-file

Use and alternate configuration file other than the default /etc/fonehome/fonehome.conf.

-I

Perform first-time initialization when connecting to a new server.

CONFIGURATION¶

The configuration file is a bash(1) source file that defines the following shell variables:

SERVER

Defines the host to connect to. This is the only variable that is strictly required.

SSH_FLAGS

ssh(1) command line flags to use with the connection. Typically this will contain reverse-forwarded ports to allow connections back from the server to the client.

USERNAME

SSH username. Default is fonehome.

KEY_FILE

File containing the SSH private key. This file must be unencrypted to allow for unattended operation; however, it should be readable only by root. Default is /etc/fonehome/fonehome.key.

RETRY_DELAY

How long (in seconds) to pause between connection attempts. Default is 30 seconds.

SYSLOG_TAG

Identifier to use when logging to syslog(3). Default is fonehome.

SYSLOG_FACILITY

Facility to use when logging to syslog(3). Default is daemon.

KNOWN_HOSTS_FILE

SSH known hosts file used to store recognized server public keys. Default is /etc/fonehome/fonehome.hosts.

MULTIPLE SERVERS¶

fonehome suports connecting to multiple servers. To enable multi-server support, simply declare SERVER as a bash(1) array variable. Then a separate connection will be maintained to each server in the array.

When multiple servers are configured, the USERNAME, SSH_FLAGS, KEY_FILE, and RETRY_DELAY variables may also be declared as arrays, in which case the corresponding array elements will be used for each server. If these variables are not arrays, or are shorter than the SERVER array, the last value will be used repeatedly. Therefore, setting a simple (non-array) value results in that value being used for all servers.

FILES¶

/etc/fonehome/fonehome.conf

Default configuration file.

/etc/fonehome/fonehome.key

Default private SSH key file used to authenticate to the server.

/etc/fonehome/fonehome.hosts

Default SSH known hosts file used to store and verify the server's public key.

SEE ALSO¶

ssh(1).

fonehome: Remote access to machines behind firewalls, https://github.com/archiecobbs/fonehome/.