Skip to content
michel-onsteinPublic

About

acs (Ad-hoc Connectivity Shell): persistent, reconnecting remote shells over ssh with an unfiltered terminal stream

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

504 Commits

Folders and files

Repository files navigation

acs

acs — Ad-hoc Connectivity Shell. Persistent remote shells over ssh that survive network drops — with an unfiltered terminal stream, so the local terminal's scrollback, mouse reporting, OSC 52 copy, hyperlinks and keyboard protocols work exactly as over plain ssh -t. One binary is both the local client and the remote session holder; it installs itself on the remote the first time you connect.

The design is in docs/DESIGN.md.

Install

curl -fsSL https://github.com/michel-onstein/acs/releases/latest/download/install.sh | sh

The installer picks the build for your machine (macOS Apple silicon and Intel, Linux x86_64 and aarch64), checks it against the release's SHA256SUMS, and installs it the way acs installs itself on a remote:

Run as Binary On PATH as
you ~/.local/share/acs/<version>/acs ~/.local/bin/acs (a link), ~/.local/bin/acscp -> acs
root /usr/local/lib/acs/<version>/acs /usr/local/bin/acs (a link), /usr/local/bin/acscp -> acs

so a client of the same version finds acs already there when it connects to this machine. acscp is acs's second name, for copying files: a relative link to the acs beside it, so it follows every upgrade. It is made where nothing is, never over a file or link you put there, and not beside an acs that is yours. It says how to add the directory to your PATH if it is not on it, and running it again upgrades in place. The link only moves forward: an older ACS_VERSION is installed beside the newer one without taking the link, and a file or link at that name it did not make is left alone. Either way it says so, and where it put the version. It needs curl or wget, sha256sum, shasum or openssl, and ssh-keygen (which comes with the ssh acs needs anyway).

Variable Meaning
ACS_VERSION=0.2.0 install that release instead of the latest
ACS_INSTALL_DIR=~/bin put the binary itself in that directory (replacing any acs there), with acscp -> acs beside it

for example curl -fsSL …/install.sh | ACS_VERSION=0.2.0 sh.

With Homebrew (macOS, or Homebrew on Linux):

brew install michel-onstein/acs/acs

installs the same build from the tap michel-onstein/homebrew-acs, which every release updates, with acscp linked beside acs; upgrade it with brew upgrade acs.

By hand, the archives are on Releases:

v=0.19.0 t=aarch64-apple-darwin     # see the release page for the latest
curl -LO https://github.com/michel-onstein/acs/releases/download/$v/acs-$v-$t.tar.gz
tar xzf acs-$v-$t.tar.gz && install -m 755 acs-$v-$t/acs ~/.local/bin/acs
ln -s acs ~/.local/bin/acscp    # acs run as acscp copies files, like scp

Releases up to 0.18.0 are tagged with a v, so theirs are under download/v$v/ (VERSIONING.md, "Tags").

Or build it yourself:

cargo xtask dist                                  # every target, see below
cp dist/aarch64-apple-darwin/acs ~/.local/bin/    # or the build for your machine

cargo xtask dist needs cargo-zigbuild, zig and the Rust targets x86_64-unknown-linux-musl, aarch64-unknown-linux-musl (and on macOS x86_64-apple-darwin). The complete binaries in dist/ carry static Linux builds for x86_64 and aarch64, so any of them can install acs on any Linux host. A plain cargo build binary is slim: it can only install a copy of itself (same OS and CPU).

Upgrade

acs upgrade            # the latest release, checked against its signed SHA256SUMS
acs upgrade --check    # only say whether there is a newer one
acs upgrade --version 0.2.0   # that release, even an older one

acs 0.18.0 and older know only v-tagged releases: they upgrade to 0.19.0 (published under v0.19.0 as well) and on from there. Once 0.20.0 is out, one still on 0.18.0 or older runs acs upgrade --version 0.19.0 first, or re-runs the one-line installer (VERSIONING.md, "Tags").

Release signatures

A release's SHA256SUMS is signed, and both the installer and acs upgrade check the signature against a key they carry before they read a checksum out of it — a checksum served from the same place as the archive proves only that the two agree with each other. Signing is ssh-keygen -Y in the acs-release namespace, so no extra tool is needed. A missing signature, one that does not verify, or a missing ssh-keygen stops the install or upgrade; nothing is unpacked or run.

The public key is below and in the binary, and it is published in the Homebrew tap — a separate repository — so you can check one against the other rather than trusting only the copy that came with the download:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILbxQW5C9X7CdwcQ4bab0gsQi4Evk2xfgmI/972dlHCb acs release signing

To check a release by hand:

printf 'releases@acs namespaces="acs-release" %s\n' "$(cat acs-release.pub)" > allowed
ssh-keygen -Y verify -f allowed -I releases@acs -n acs-release \
    -s SHA256SUMS.sig < SHA256SUMS

How the upgrade replaces the binary

acs replaces itself in place (a link like ~/.local/bin/acs is pointed at the new version); if its directory is not yours, it says to use sudo acs upgrade. It uses curl (or wget). Remote hosts need nothing: the next connection installs the new version there. An acs installed with Homebrew is brew's to replace: acs upgrade says to run brew upgrade acs instead.

Once a week acs looks for a newer release in the background (it never delays connecting) and, if there is one, says so once when you next start it:

acs: acs 0.3.0 is available (you have 0.2.0) — run: acs upgrade

(with Homebrew, run: brew upgrade acs). Offline, it says nothing. Turn it off with ACS_NO_UPDATE_CHECK=1 or update_check: false in the configuration.

Nothing is needed on the remote beyond ssh, a POSIX sh and gzip: on first contact acs installs its own version under ~/.local/share/acs/<version>/ and links ~/.local/bin/acs to it.

Use

acs [ssh options] [user@]host            pick a detached session, or create one
acs [ssh options] [user@]host session    attach, or create
acs [ssh options] [user@]host --new      create a new numbered session (1, 2, …)
acs list [ssh options] [user@]host       list sessions on host
acs list [ssh options]                   list sessions on every host alias
acs host session -- command args…        run a command instead of the login shell

list, config, upgrade and cp are commands when they come first. A host with one of those names is reached as user@list, with an option before it (acs -p 22 list), or listed as acs list list.

A plain acs host looks at the host's sessions first. With none detached, it creates one — main, or the lowest free number if main is taken. With some detached, it shows them:

acs: detached sessions on devbox

     NAME  STATE     WHO           IDLE  AGE  COMMAND
> 1  main  detached  (michel@mbp)  4m    1d   /bin/zsh -l
  2  work  detached  (michel@mbp)  2h    3d   htop
  n  new session
     exit

1-9, or ↑↓ jk and Enter: attach   .: all   x: end   n: new   Esc: leave
Key Effect
1–9 attach that session (more than nine: the rest by cursor)
↑ ↓ or k j, then Enter attach the session under the cursor, or pick new session or exit
n create a new session (on a session row, or on new session)
. show attached sessions too; taking one over asks first (--force does not)
x end the session under the cursor, after a y (or a second x)
Esc leave the menu (Ctrl-C too)

The bar names only the keys that act on the row under the cursor, so x and n are not offered on new session or exit, and Enter is named for what it does there:

1-9: attach   ↑↓ jk: move   .: all   Enter or Esc: leave

The list, the menu's x and the attach share one ssh connection, so a plain acs host logs in once (one touch of a hardware key), and acs -v host shows a single running ssh …. -v also times each phase of a connection — ssh spawned, the greeting sent, acs ready on the remote, the session list, the attach, the first output — as acs: timing: … lines, for every redial too. HELLO sent is where the whole greeting has gone, so its place in the list is the answer to whether it went out with the dial: normally it is right after ssh spawned, and it comes later on the menu's connection, which greets after the list, or as HELLO partly sent then HELLO sent when the greeting was too big for one write. Without a terminal on stdout there is no menu: acs host attaches main, creating it if needed.

In a session, press Ctrl-] Ctrl-] quickly, then:

Key Effect
d detach — the session keeps running; reattach with acs host session
x exit — end the session on the remote

The terminal bell rings when Ctrl-] Ctrl-] has armed command mode, so you know the next key is a command (command mode waits 2 seconds for it, or as long as ACS_ESCAPE_TIMEOUT_MS if you have set that longer). acs writes the bell to your terminal only, never to the program, and never in the middle of a sequence the program is sending. Turn it off with command_bell: false in the configuration or ACS_COMMAND_BELL=0.

A single Ctrl-], or Ctrl-] followed by any other key, goes to the program as usual. The command key works in every keyboard encoding a terminal may use (including the kitty keyboard protocol) and never triggers inside a paste.

Copying files

acs cp copies files to and from a host, spelled like scp:

acs cp [-rpqvC46] [-P port] [-i identity] [-J jump] [-F config] [-o opt=value] source ... target
acs cp notes.txt devbox:                 upload into the home directory
acs cp -r project devbox:src/            a directory, recursively
acs cp devbox:/var/log/syslog devbox:a.txt .    download, several sources from one host
acs cp -r devbox:project nas:backup/     between two hosts, through this machine
acs cp 'devbox:logs/*.gz' .              a wildcard, expanded on the host
acs cp devbox:a nas:b notes out/         two hosts and a local file at once

The same binary run as acscp is acs cp, a drop-in for scp. install.sh, the remote install, acs upgrade and Homebrew each put a relative acscp -> acs link beside the acs they install, so it follows every upgrade; an install from before acscp gets it on its next upgrade. None of them touches a file or link already at that name. Where you placed acs yourself, make it in the same directory: ln -s acs <dir>/acscp. An argument is remote when it is [user@]host:[path] with no / before the first :; the host may be an acs alias, and ./a:b is a local file. -r copies directories (following symlinks), -p keeps the modification and access times and the exact mode, and the port is -P — as in scp, -p is preserve here. -q turns off the progress meter, -v shows the ssh commands, the connect timings and a summary.

A copy uses acs's own ssh connection, so it shares the master of a session already open to the host, and on a host that has never seen acs it installs it on that one connection first, as acs host does (unless install_on_remote is false).

A copy survives a lost link the way a session does: it redials at once, then backs off from 1 s to 30 s (sooner when this machine's network changes), and carries on from where the file had got to. A file is written to .<name>.acscp-part beside its final name and renamed into place when whole; a part found there is checked against the source by a hash of its bytes and resumed, or written again when it is not the file's start. That part is the only state, so a copy you stop with Ctrl-C — or one --no-reconnect ended — is finished from it by running the same acs cp again. A part no later run claims stays until you remove it.

A copy between two hosts goes through this machine, as scp -3 does: acs opens a connection to each, installing acs on either where it is missing, and passes the stream from one to the other without writing anything here. Sources on several hosts are copied one host after another, and the target's host may be one of them. Such a copy does not reconnect: a lost link ends it and says so, and running the same command again goes on from the part already on the target.

A remote path may hold wildcards — quote it, so your own shell leaves it alone. There is no shell on the far end either: acs expands *, ? and [...] there itself, in any component of the path, and a name beginning with . only for a pattern that does. The files that arrive must match the pattern, as scp checks; a pattern matching nothing is reported, and one into what is not a directory is refused. A remote name that holds one of those characters literally is written with a \ before it ('devbox:report\[1].pdf').

Local and remote sources may go in one copy (acs cp -r notes devbox:project .), and a download may take sources from several hosts: acs copies the sources on each host in turn, one host after another, then the local ones. Several sources, or a wildcard, need the target to be a directory; that is checked before anything is written, so a refused copy leaves the target as it was.

ssh options

-i <identity_file>, -p <port>, -J <jump>, -F <config> and -o <option=value> are passed to every ssh call acs makes, with ssh's meaning; -L (below) is the exception and goes to the session's connection alone. There is no -l, neither ssh's login option nor a list option: put a login name in user@host or -o User=, and list with acs list. Your ~/.ssh/config, agent and keys apply as usual; nothing needs configuring on either side. A key can also be set per host alias in the configuration (identity_file, below); -i on the command line wins.

Connecting again without another handshake

An ssh handshake is several round trips and, with a hardware key, a touch. acs keeps a connection of its own alive for a few minutes after you last used a host, so a reattach after a detach — or an acs list devbox followed by acs devbox — opens another channel on it instead of starting over, and acs list over every alias asks any host you have a session on through it (a listing never starts one). It is acs's own connection, in acs's own 0700 directory (/tmp/acs-mux-<uid>), never the one your ~/.ssh/config multiplexes; nothing is left behind more than ACS_CONTROL_PERSIST seconds (300 by default) after the last use, even if acs is killed.

A reconnect never reuses it: that is the one case where a shared connection could be the dead one, so a redial always dials its own. It also ends the shared one on its way, but only when what ended the link says the connection failed — an ssh that exited, or a host that went silent. A link that broke while bytes were still arriving on it took nothing else with it, and any other session sharing that connection keeps it rather than being dropped and losing what you had typed. A session that forwards a port (-L or local_forwards, below) does not use it either — a forward opened on a shared connection would outlive the session. ACS_CONTROL_PERSIST=0 turns the whole thing off, and -v says what acs decided and how long each phase took.

Forwarding a port

-L forwards a local port over the session's connection, spelled as ssh spells it and repeatable:

acs -L 8080:localhost:80 -L 5432:db.internal:5432 devbox

[bind_address:]port:host:hostport, with an IPv6 literal in brackets (-L '[::1]:8080:localhost:80') and an empty bind address or * for every interface. A spec acs cannot read is an error before any ssh runs, rather than a complaint from ssh on every dial.

The forward rides the session's ssh only — not the connections acs list, the remote install or the menu over every alias make, which run side by side and would each try to bind the same port. It follows the session across reconnects, but it is gone for as long as the link is: the listening socket belongs to the ssh process, so a drop closes it and the redial rebinds it, and anything connected through it at the time is cut. If the port cannot be rebound — a second acs took it, or it is still in TIME_WAIT — ssh says so and the session carries on without the forward; add -o ExitOnForwardFailure=yes if you would rather acs kept redialling until the port is free. There is no key for adding or removing a forward once a session is running.

-o LocalForward="8080 localhost:80" still works too, and is the way to forward a unix socket, but it goes to every ssh call acs makes (so several may fight over one port) and is passed to ssh unchecked.

A forward a host always needs belongs in the configuration rather than in a command line you retype: local_forwards takes the same specs, globally or on one alias.

local_forwards: [8080:localhost:80]   # every session
aliases:
  db:
    local_forwards: 5432:db.internal:5432   # this alias instead
    hosts:
      - host: db.lan
  quiet:
    local_forwards: none                    # this one forwards nothing
    hosts:
      - host: quiet.lan

The two add up: acs -L 9000:localhost:9000 db forwards 9000 as well as the configured 5432, the way repeated -L does. To say no forward there is one word, none: on an alias it replaces the global list with nothing, and acs -L none db drops the configured ones for that run (any other -L you give still applies). A bad spec in the file is an error the moment acs reads it, naming the line — not ssh complaining on every dial.

When the network drops

The client notices a dead link within 10 seconds, redials at once — most drops are a blip and the network is back by then — and then with backoff (1 s doubling to 30 s, or at once again when your machine's own addresses change — a new Wi-Fi network, a wake, a VPN) and resumes exactly where the output stopped — nothing is lost or repeated. While it is waiting a status line shows at the bottom of the screen, typed keys are dropped, and Ctrl-] Ctrl-] d still detaches. --no-reconnect exits instead.

When your addresses change while a session is connected — the Wi-Fi switch and the wake from sleep, where the old connection goes quiet rather than closing — acs does not drop the session on the strength of that. It asks the host straight away and gives it 2 seconds to be heard from: a link that came through the change answers and costs you nothing, and one that did not is replaced in a second or two instead of ten.

Both of those rest on your machine's addresses really moving when you roam, so -v says what each thing the kernel mentioned was worth: network changed: 192.168.1.5/24 → 10.0.0.5/24 for one that counted, network hint: still on 192.168.1.5/24 — not a change for one that did not. If you switch network and see no line at all, the watcher is not seeing your machine's network move — that is worth reporting.

Never giving up on a host

acs gives up (exit 255) where there is no session to keep: the host cannot be reached at the start, or the link drops before the session was attached. With --persist (or persist: true in the configuration, or ACS_PERSIST=1) it never gives up on a host: it pings it every second for the first 30 seconds, then every 5 (reachability_interval), and dials as soon as it answers — at the start as after a drop, where the ping replaces the backoff. It pings an alias's hosts as it does to choose one, and a plain host itself; an alias whose hosts all have reachability_check: false cannot be pinged and keeps the backoff. Before the session exists, Ctrl-C gives up; after, Ctrl-] Ctrl-] d detaches as usual. persist can be set globally, on an alias, or on one of its hosts (the host's wins over the alias's, which wins over the global one); --persist wins over all of them.

Ctrl-L after reconnecting

Whenever acs attaches to a session that was already running — resuming after a drop, acs host session again after a detach, or taking a session over — it sends the program one Ctrl-L first, so a shell or full-screen program repaints the screen. A session acs has just created gets none. The Ctrl-L comes after any keys the drop left unsent and before anything you type next, reaches the program once per reconnect, and is never sent into the middle of a paste.

Ctrl-L is a key, not a terminal command: a shell clears the screen, vim, less and htop redraw, but a program reading raw input receives a form feed, and vim in Insert mode inserts one. Turn it off with redraw_on_reconnect: false in the configuration, for everything or for one host alias (below), or with ACS_REDRAW_ON_RECONNECT=0. The screen is still cleared and the program still asked to redraw on a re-attach, as before.

Several people, one account

Each client has an identity (user@hostname, or ACS_IDENTITY). Attaching to a session someone else is attached to asks first:

acs: session 'main' on devbox is attached from alice@laptop since 10:02 — take over? [y/N]

--force skips the question, for that attach. Agreeing to take a session is about whoever holds it at the time, so it is not reused: if the link later drops and the redial finds somebody else attached, acs asks again. ACS_DEFAULT_SESSION gives each person their own name instead of main for the session a plain acs host creates.

Configuration

Settings live in YAML files: the global /etc/acs/config.yaml, then your own ~/.config/acs/config.yaml (or $XDG_CONFIG_HOME/acs/config.yaml). Both are optional. A setting in your file replaces the global one; mappings merge key by key and lists add up, global entries first.

# ~/.config/acs/config.yaml
install_on_remote: false   # never install acs on a host (default: true)
update_check: false        # never look for a newer release (default: true)
command_bell: false        # no bell when Ctrl-] Ctrl-] arms (default: true)
redraw_on_reconnect: true  # Ctrl-L after reconnecting (default: true)
reachability_timeout: 1s   # how long hosts have to answer a ping (default: 500ms)
aliases:
  devbox:                  # acs devbox
    - host: devbox.lan     # at home: used if it answers a ping
    - host: devbox.example.com
      user: michel         # from outside, as michel
  nas:
    - host: nas.lan
      reachability_check: false   # it drops pings: use it unchecked
  lab:                     # an alias with settings of its own
    identity_file: ~/.ssh/id_lab  # the key for every host below…
    redraw_on_reconnect: false    # no Ctrl-L after reconnecting to lab
    reachability_timeout: 2s      # a slow link: wait longer for its pings
    hosts:
      - host: lab.lan
      - host: lab.example.com
        identity_file: ~/.ssh/id_lab_outside   # …but this one

An alias has one of two shapes, and the example uses both. Usually it is just its list of hosts, as devbox and nas are. When it has settings of its own, as lab has, it is a mapping of those settings, with the list under hosts: — YAML cannot make one node both a list and a mapping. The mapping form is always allowed, even without settings, and acs config host set <alias> <setting> <value> rewrites a list-form alias into it (host unset of its last setting turns it back into a list).

Setting Meaning
install_on_remote install acs on a host that lacks it (default true); when false, acs says what is missing and exits with 254
update_check look for a newer acs release once a week (default true)
command_bell ring the terminal bell when Ctrl-] Ctrl-] arms command mode (default true; ACS_COMMAND_BELL overrides it)
redraw_on_reconnect send Ctrl-L after reconnecting to a session (default true); an alias's own value wins, and ACS_REDRAW_ON_RECONNECT over both
reachability_timeout how long an alias's hosts have to answer a ping: 500ms, 0.5s, 2s, up to 60s (default 500ms); an alias's own value wins
reachability_tcp check an alias's hosts by connecting to their ssh port (as ssh -G names it) instead of pinging them (default false); an alias's own value wins
persist never give up on a lost host: ping it and dial when it answers (default false); also on an alias or one of its hosts, the most specific winning; --persist and ACS_PERSIST over all
reachability_interval how often a lost host is pinged while persisting, after the first 30 pings a second apart: 100ms to 3600s (default 5s); an alias's own value wins
prefer_local_network try first an alias's hosts that are on a network this machine is on, IPv4 or IPv6 (default false); an alias's own value wins
local_forwards ports every session forwards, as -L spells them: a list, or one value with commas (8080:localhost:80,5432:db:5432); none for no forward (default). An alias's own list replaces the global one, and -L on the command line adds to it
aliases each alias name maps to a list of host entries, with an optional user, identity_file, reachability_check (default true), prefer, persist and local_networks — or to a mapping of the alias's own settings (identity_file, redraw_on_reconnect, reachability_timeout, reachability_tcp, persist, reachability_interval, prefer_local_network, local_forwards) and its hosts

A mistake in a file stops acs with the file and line, for example ~/.config/acs/config.yaml:2: install_on_remote: expected true or false.

Host aliases

acs devbox with the file above uses devbox.lan if it answers a ping, otherwise michel@devbox.example.com if that one does. An entry with reachability_check: false is used without a ping. An IPv6 host is pinged with ping6 where the system's ping cannot reach one (macOS). The hosts are pinged all at once, and the order in the file still decides: an earlier host that answers within reachability_timeout wins over a later one that answered first, so choosing takes at most that long however many hosts there are. prefer: true on an entry puts it ahead of the others: when it answers it is used even if an earlier host answered too (several preferred entries go by order among themselves), which also lets your own file name the primary host of an alias whose other hosts are in the global file. With prefer_local_network: true, a host whose address is on one of this machine's networks goes first of all: at home on 192.168.1.0/24, devbox.lan (192.168.1.20) is used before devbox.example.com wherever it is listed — as long as it answers its ping.

With reachability_tcp: true (globally or on an alias) a host is checked by connecting to its ssh port instead of a ping — the port ssh -G gives for it, so ~/.ssh/config and the command line's -p, -F, -J, -o and --ssh decide it — within the same reachability_timeout. That suits hosts and networks that drop pings, and a host whose sshd is down no longer counts as up. A host ssh reaches through a ProxyJump or a ProxyCommand has no port of its own to try, so it is still pinged.

acs remembers which host an alias used last on the networks you are on (~/.local/state/acs/aliases), so away from home, where devbox.lan is down, the next acs devbox takes devbox.example.com as soon as it answers instead of waiting out reachability_timeout for devbox.lan every time. Back home it is devbox.lan again: the place is the set of networks, and a host ranked higher that answers again is the one used from the next connection on.

An interface's own prefix is narrower than a site, so that match alone misses a host one subnet away: from 172.16.1.65/24 a host at 172.16.8.2 is on another network, although both are at the same site. local_networks on a host entry says where that entry is the one to use — when this machine is on one of these networks, try this host first:

aliases:
  devbox:
    - host: devbox.example.com
    - host: devbox.lan
      local_networks: [172.16.0.0/16, 2001:db8:1::/48]

The address tested is this machine's own, not the host's: at the site, on 172.16.1.65, devbox.lan goes first; from a café on 10.0.0.0/8 it does not, even though its own address is still inside 172.16.0.0/16. That is what makes the setting say something about where you are, and it is why it belongs to one entry rather than to the alias or the whole file — "prefer this host when I am on network X" does not parse without naming the host. It needs no prefer_local_network (it costs no name lookup, so there is nothing to switch off) and it does not exempt the host from its ping; it only ranks it. Several entries may carry the setting — among those that match, the order in the file decides — and an entry may be local both ways at once, in which case -v names the network the host itself is on. A network that is not in CIDR form, matches every address (/0), or is loopback or link-local is a configuration error naming the file and line.

Without a user, your ~/.ssh/config picks the login name. If no entry answers, acs lists the hosts it tried and exits with 255. -v accounts for every entry of the alias, one line each: which was chosen and why, which did not answer its ping, and — the entries the choice never reached — which host was chosen before them, or which reachability_check: false entry they are listed behind and so could never have been used:

acs: devbox: devbox.lan does not answer ping within 500ms
acs: devbox: devbox.vpn answers ping, using devbox.vpn
acs: devbox: devbox.backup not tried: devbox.vpn was chosen first
acs: devbox: devbox.old not tried: it is listed after devbox.backup, whose reachability_check is off

The untried entries come last, continuing the order the choice walked in.

The alias is resolved again on every reconnect, so when you move from home to outside, the redial goes to whichever address answers. List ways of reaching one machine under an alias: the session lives on that machine, so a fallback to a different one finds no session to resume.

acs root@devbox goes through the alias the same way, logging in as root on whichever host is chosen (instead of michel on the fallback), and keeps root on every redial. Any name that is not an alias, with or without a user@, is used as given. To reach a machine whose name is also an alias, use its full name or address (acs devbox.example.com).

Which ssh key

identity_file picks the key acs passes to ssh as -i, for one host entry or for a whole alias. The first of these wins, and only that one is passed:

  1. -i (or -o IdentityFile=) on the command line;
  2. the chosen host entry's identity_file;
  3. the alias's identity_file.

With none of them, ssh picks the key as usual (~/.ssh/config, the agent). A leading ~/ means your home directory. The key follows the entry: a reconnect that falls back to another host of the alias uses that host's key. ssh still offers its other keys after this one unless you set IdentitiesOnly yes. Your own file can set just the key of an alias whose hosts are in the global file (lab: {identity_file: ~/.ssh/mine}).

Sessions on every host

acs list without a host shows the sessions on every alias at once. In a terminal it is the session menu above, with a HOST column: pick a session on any host with its number or the cursor, x ends one on its host, n starts a new one on the host of the row under the cursor, and each host's rows appear as it answers. acs list <alias> is that one host's menu. Into a pipe (acs list | less) it is a table:

HOST    NAME  STATE     WHO           IDLE  AGE  COMMAND
devbox  main  attached  michel@mbp    3s    2h   /bin/zsh -l
devbox  work  detached  (michel@mbp)  4m    1d   htop
no sessions on nas
acs: pi: no host for 'pi' is reachable (tried pi.lan)

Each alias is resolved as above and all are asked in parallel, so a host that is down or slow only costs its own line — on stderr, after at most 30 s (ACS_DIAL_TIMEOUT_MS). The exit status is 0 when every host answered and 255 when any did not. Several ssh cannot ask for passwords on one terminal, so these calls run with ssh's BatchMode: list a host that needs a password on its own, with acs list <alias>. With no aliases configured, it says so — or, with no configuration file at all, that there is none and where it looked — and exits with 2.

Editing it from the command line

acs config host add devbox devbox.lan                 # the first host of devbox
acs config host add devbox devbox.example.com --user michel
acs config host add nas nas.lan --no-reachability-check
acs config host add lab lab.lan --identity-file ~/.ssh/id_lab_home
acs config host set lab identity_file ~/.ssh/id_lab   # the alias's key
acs config host unset lab identity_file
acs config host set lab redraw_on_reconnect false     # no Ctrl-L for lab
acs config host set lab reachability_timeout 2s       # lab's hosts may take 2 s
acs config host set lab persist true                  # never give up on lab
acs config host add nas nas.lan --persist             # nor on this host of nas
acs config host add devbox devbox.vpn --prefer        # devbox.vpn first when it answers
acs config host list                                  # aliases, hosts and keys
acs config host remove devbox devbox.lan              # one host, or the alias
acs config set install_on_remote false
acs config set update_check false                     # no weekly release check
acs config set command_bell false                     # no bell for command mode
acs config set redraw_on_reconnect false              # no Ctrl-L on reconnect
acs config set reachability_interval 10s              # ping a lost host every 10 s
acs config host set devbox prefer_local_network true  # devbox.lan first at home
acs config host add devbox devbox.site --local-networks 172.16.0.0/16
                                                      # first when I am on that
acs config set reachability_timeout 250ms             # pings must answer within 250 ms
acs config set local_forwards 8080:localhost:80       # every session forwards it
acs config host set db local_forwards 5432:db.internal:5432,8080:localhost:80
                                                      # db's own, over the global list
acs config host set quiet local_forwards none         # quiet forwards nothing
acs config get install_on_remote
acs config unset install_on_remote                    # back to the default
acs config show                                       # everything, and where it is from
acs config path                                       # the files acs reads

These edit ~/.config/acs/config.yaml; add --global for /etc/acs/config.yaml (with sudo). Comments and the order of the rest of the file are kept. Because config is a command, a host named config is reached as user@config.

Environment

Variable Meaning
ACS_DEFAULT_SESSION name of the session plain acs host creates, and attaches without a terminal (default main)
ACS_IDENTITY identity shown to others on a shared account
ACS_ESCAPE_KEY command key in ^X notation (default ^])
ACS_ESCAPE_TIMEOUT_MS window for the double press (default 400), and the window to then choose the command key — that one never shorter than 2 s
ACS_COMMAND_BELL 0: no bell when command mode arms; 1: a bell even if the configuration turns it off
ACS_REDRAW_ON_RECONNECT 0: no Ctrl-L after reconnecting; 1: a Ctrl-L even if the configuration (global or the alias's) turns it off
ACS_PERSIST 1: never give up on a lost host (as --persist); 0: give up as by default, whatever the configuration says
ACS_SSH ssh program (default ssh; also --ssh)
ACS_SOCKET_DIR remote socket directory (default /tmp/acs-<uid>); a relative path is taken from the remote login directory, normally home
ACS_CONTROL_DIR local directory for acs's own ssh control sockets (default /tmp/acs-mux-<uid>, made 0700)
ACS_CONTROL_PERSIST seconds an acs-owned ssh master outlives its last use (default 300); 0 turns the shared master off
ACS_CONTROL_FALLBACK_MS how long a connection that joins an existing master may take to answer before the master is ended and the connection made on its own (default 2000)
ACS_RING remote output history kept for resume, bytes (default 1 MiB)
ACS_CP_WINDOW how many file headers acs cp sends ahead of their data (default 64)
ACS_DIAL_TIMEOUT_MS how long a new connection may take to answer (default 120 s, time for a password or a key touch; 30 s for each host of acs list)
ACS_REDIAL_TIMEOUT_MS how long a reconnect may take to answer before acs goes back to waiting and tries again (default 30 s); it does not change ACS_DIAL_TIMEOUT_MS
XDG_CONFIG_HOME where your configuration file is (default ~/.config)
ACS_GLOBAL_CONFIG global configuration file (default /etc/acs/config.yaml)
ACS_PING ping program for alias reachability checks (default ping)
ACS_RELEASES_URL where acs upgrade and the update check look for releases (default GitHub). Must be https, since what is fetched is checked only against sums from the same place and is then run; acs upgrade --allow-insecure-url accepts another scheme. Ignored altogether when the real and effective user differ, so a sudo upgrade is not steered by the environment
ACS_NO_UPDATE_CHECK 1: never look for a newer release
XDG_STATE_HOME where the update check and the host each alias used last keep their state (default ~/.local/state)

Development

scripts/verify.sh       # fmt, clippy (macOS and Linux targets), tests, markdownlint
scripts/test_linux.sh   # the suite on Linux in a container, plus multi-user isolation
scripts/e2e_ssh.sh      # end to end over real ssh against a container host
scripts/test_install.sh # install.sh against the real releases, here and in containers
scripts/version-bump.sh # release the next version and publish its binaries
scripts/release-binaries.sh  # (re)publish a tag's binaries to GitHub Releases
scripts/update-tap.sh X.Y.Z  # point the Homebrew tap at a release

scripts/test_linux.sh --only NAME [-- ARGS...] runs one test target instead of the three steps — a file under tests/ without .rs, or lib for the unit tests — in the same container and with the same flags as the full run, so --only netns and --only multiuser still run as root with their ignored tests asked for. Anything after -- goes to the test harness, such as a name filter.

scripts/e2e_ssh.sh --no-build reuses the binaries already in dist/ (about 20 s instead of a minute), but only when dist/source.stamp says they were built from the tree as it is now — otherwise it refuses, since a failure from a stale binary looks exactly like a real one. A checkout with no dist/ at all, such as a fresh worktree, has nothing stale to reuse, so it is built once instead of refused. --allow-stale-dist reuses dist/ unchecked, and is a usage error without --no-build.

Results of the checks that need a real terminal are in docs/VERIFICATION.md.

About

acs (Ad-hoc Connectivity Shell): persistent, reconnecting remote shells over ssh with an unfiltered terminal stream

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages