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.
curl -fsSL https://github.com/michel-onstein/acs/releases/latest/download/install.sh | shThe 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/acsinstalls 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 scpReleases 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 machinecargo 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).
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 oneacs 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").
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 < SHA256SUMSacs 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.
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.
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.
-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.
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.
-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.lanThe 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.
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.
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.
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.
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.
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 oneAn 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.
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).
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:
-i(or-o IdentityFile=) on the command line;- the chosen host entry's
identity_file; - 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}).
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.
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 readsThese 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.
| 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) |
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 releasescripts/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.