FONEHOME(1)

📦 version 1.2.2, in opensuse-leap 16.0

💖 FONEHOME(1) — like, the manual page, bestie 💖

okay so picture this: it's General Commands Manual o'clock and you're about to meet fonehome, the icon herself. she's got a whole NAME section energy and honestly? she ate.

✨ NAME ✨

fonehome — establish connection to fonehome server 🫶

🌸 SYNOPSIS 🌸

fonehome [-f config-file]
fonehome -I

that's it. two moods. two vibes. pick one. 💅

🦋 DESCRIPTION 🦋

so fonehome is, like, a wrapper for the ssh(1) program — she's not trying to be ssh, she's ssh's hype woman. what she does is create a persistent no-pty ssh(1) connection to one or more fonehome servers, and she sets up normal and reverse port forwarding according to whatever's in the config over at /etc/fonehome/fonehome.conf. and like… what does that get you? private, bi-directional connections between the fonehome client and server, fully secured, and you never have to touch a firewall setup. not once. not ever. 🔥

she's genuinely that girl when you've got a bunch of machines deployed in the field and you want to keep secure access to them from a central operations server — no firewall hassles, no drama, no cap.

normally fonehome runs as a systemd(1) service, living her best low-key life. but — and this is the important part, listen up — upon first installation (or whenever a server's host key changes), there's a manual initialization step you must do: run fonehome yourself, by hand, with the -I flag. that's how the administrator gets to confirm and accept the server host key(s). it's giving ✨responsible adult supervision✨ and you can't skip it.

🎀 OPTIONS 🎀

  • -f config-file — use an alternate configuration file instead of the default /etc/fonehome/fonehome.conf. very "i have a different file and i'm not sorry" of you.
  • -I — perform first-time initialization when connecting to a new server. this is the one where you, a human, confirm the host key. iconic, necessary, do it. 🙈

💜 CONFIGURATION 💜

the config file is a bash(1) source file — yes, it's literally bash, she speaks shell natively — and it defines the following shell variables:

  • SERVER — defines the host to connect to. this is the only variable that is strictly required. everything else has a default, she's very self-sufficient. 👑
  • SSH_FLAGS — ssh(1) command line flags to use with the connection. typically this will contain reverse-forwarded ports so connections can come back from the server to the client. it's giving main character energy for your port forwards.
  • 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. both of those things, at the same time, no exceptions. 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.
lowkey memorise those defaults, they come up in conversation. 🍓

🌈 MULTIPLE SERVERS 🌈

bestie. she supports connecting to multiple servers. yes, plural. multiple. 🎀

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. one for you, one for you, one for you…

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. very "matching outfits for each server" of them.

and if these variables are not arrays, or are shorter than the SERVER array, then the last value will be used repeatedly (iykyk — bash array indexing, she recycles, it's sustainable 💅). therefore, setting a simple (non-array) value results in that value being used for all servers. easy. done. periodt.

🧚 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 ⭐

okay that's the whole page, you're officially educated. this was Debian, dated January 2, 2013 — shoutout to the OG release, she's been slaying since day one 💖✨🎀 go forth and forward some ports, bestie. 🦋

📦 where this page comes from