Expand description
Named domain constants (XDG file names, env keys, network/timing defaults). Named domain constants (Rules Rust — proibição de hardcode).
Compile-time values with semantic names live here. Runtime host credentials,
per-VPS timeouts, and primary-key material are never hardcoded: they are
loaded once from CLI / OS keyring / XDG files under
[APP_NAME] (directories::ProjectDirs + optional --config-dir).
§12-Factor alignment (this product)
| Factor | How ssh-cli applies it |
|---|---|
| III Config | Hosts in XDG config.toml; secrets via CLI flags / keyring / secrets.key (not SSH_CLI_* env stores) |
| Build/Release/Run | Version from CARGO_PKG_VERSION; commit via build.rs; no prod URL in binary |
| Backing services | SSH endpoints are user registry data, not compile-time constants |
Modules keep local constants when the name is only meaningful in that module (e.g. concurrency RAM budget). Cross-cutting identity, storage file names, env var names, network defaults, and process timing are centralized.
Constants§
- ACTIVE_
VPS_ FILE_ NAME - Active-VPS marker file name (sibling of
CONFIG_FILE_NAME). - AEAD_
NONCE_ LEN_ BYTES - ChaCha20-Poly1305 nonce length in bytes.
- AEAD_
TAG_ LEN_ BYTES - Poly1305 authentication tag length in bytes.
- AGENT_
RETRY_ BASE_ MS - Base backoff delay (ms) for agent full-jitter formula.
- AGENT_
RETRY_ MAX_ DELAY_ MS - Ceiling for a single agent backoff sleep (ms).
- AGENT_
RETRY_ MAX_ RETRIES - Max retries after the first failure for agents re-invoking on exit 74.
- APP_
NAME - Binary and project name (
clap, keyring service, XDG directory leaf). - CONFIG_
FILE_ NAME - Registry file name under the config directory.
- DEFAULT_
SSH_ PORT - Default SSH port when the user omits
--portonvps add. - DEFAULT_
TUNNEL_ BIND_ ADDR - Default local bind for
tunnel --bind(loopback-only for safety). - ENV_
FORCE_ TEXT - Historical name only — not read as product store.
Use
--json/--output-format text. - ENV_
HOME - Historical name only — not read as product config store.
Use CLI
--config-dirfor isolated config roots. - ENV_
LANG - Historical name only — not read as product store.
Use CLI
--langorlocale set(XDGlang). - ENV_
SECRETS_ KEY - Hex primary-key material. Fail-closed: presence is rejected (not a store).
Use XDG
secrets.key,--secrets-key-file, or--use-keyring. - ENV_
SECRETS_ KEY_ FILE - Path to a primary-key file (hex). Fail-closed: presence is rejected (not a store).
Use CLI
--secrets-key-fileor XDGsecrets.key. - ENV_
USE_ KEYRING - Historical name only — prefer CLI
--use-keyring(not an env store). - FAN_
OUT_ SIGNAL_ POLL_ INTERVAL_ MS - Multi-host fan-out signal poll interval inside
map_bounded. - HAPPY_
EYEBALLS_ ATTEMPT_ DELAY_ MS - Delay before starting the next Happy Eyeballs dial candidate (RFC 8305-inspired).
- HARD_
CAP - Alias used by the concurrency budget module (same as
MAX_CONCURRENCY). - HARD_
RETRY_ MAX_ DELAY_ MS - Hard ceiling for a single delay (ms).
- HARD_
RETRY_ MAX_ RETRIES - Hard cap on configured retries (prevents accidental retry storms).
- IO_
OVERSUBSCRIBE - I/O oversubscribe factor vs CPU count for multi-host fan-out.
- KEYRING_
SERVICE - Keyring service name (must match historical installs).
- KEYRING_
USER_ LEGACY - Legacy keyring user (read-only migration alias).
- KEYRING_
USER_ PRIMARY - Canonical keyring user for the primary key.
- KNOWN_
HOSTS_ FILE_ NAME - TOFU host-key store file name (sibling of
CONFIG_FILE_NAME). - LANG_
PREFERENCE_ FILE_ NAME - Persisted UI language preference file name (sibling of
CONFIG_FILE_NAME). - MAX_
CONCURRENCY - Hard upper bound on concurrent multi-host sessions and SCP file channels.
- MIN_
CONCURRENCY - Minimum concurrent multi-host / fan-out units (always ≥ 1).
- NON_
LINUX_ CPU_ CAP - Conservative CPU×IO cap when free RAM cannot be read (non-Linux).
- PRIMARY_
KEY_ HEX_ LEN - Primary-key hex encoding length (
2 * PRIMARY_KEY_LEN_BYTES). - PRIMARY_
KEY_ LEN_ BYTES - Primary-key length in bytes.
- PROJECT_
ORGANIZATION directories::ProjectDirs::fromorganization (empty = app-only path).- PROJECT_
QUALIFIER directories::ProjectDirs::fromqualifier (empty = no reverse-DNS prefix).- RAM_
PER_ TASK_ BYTES - Documented per multi-host session RAM budget (bytes) for auto concurrency formula.
- RUNTIME_
SHUTDOWN_ TIMEOUT_ SECS - Tokio runtime graceful shutdown budget after the one-shot command returns.
- SECRETS_
KEY_ FILE_ NAME - Primary-key file name (next to
CONFIG_FILE_NAME; mode 0o600). - SECRET_
DIR_ MODE_ UNIX - Unix permission mode for secret directories (TLS identity dirs, etc.).
- SECRET_
FILE_ MODE_ UNIX - Unix permission mode for secret files (
config.toml,secrets.key,lang). - SFTP_
FALLBACK_ BASENAME - Basename used only when a multi-file source has no file name component. Prefer rejecting empty names; this is a last-resort label (G-SFTP-R13).
- SFTP_
IO_ CHUNK - Stream chunk size for SFTP file I/O (bytes). Never load whole files into RAM.
- SFTP_
LIST_ MAX_ ENTRIES - Fail-closed cap on directory listing entries (
sftp ls/ recursive walk). - SFTP_
MAX_ RECURSION_ DEPTH - Max recursion depth for
sftp upload|download --recursive. - SFTP_
SUBSYSTEM - SSH subsystem name for SFTP v3 (
request_subsystem). - SSH_
CLIENT_ ID - SSH identification string sent to the server (G-SSH-02).
- SSH_
KEEPALIVE_ INTERVAL_ SECS - SSH-level keepalive interval (seconds between keepalives when idle).
- SSH_
KEEPALIVE_ MAX - Max unanswered SSH keepalives before russh closes the session.
- SSH_
MAX_ PACKET_ SIZE - Maximum SSH packet size (32 KiB — RFC 4253 common default).
- SSH_
REKEY_ BYTE_ LIMIT - Rekey after this many bytes read or written (1 GiB — RFC 4253 §9).
- SSH_
REKEY_ TIME_ SECS - Rekey after this many seconds of session lifetime (RFC 4253 §9).
- SSH_
RSA_ MIN_ BITS - Minimum RSA private-key size accepted for publickey auth (bits).
- SSH_
RSA_ PREFERRED_ BITS - Preferred RSA size; smaller (but ≥ min) keys log a warning (bits).
- SSH_
WINDOW_ SIZE - Initial SSH channel window size (2 MiB — OpenSSH-class throughput).
- TCP_
KEEPALIVE_ ENABLED - Enable TCP-level
SO_KEEPALIVEon the SSH dial socket (complements SSH KA). - TLS_
ACME_ ACCOUNT_ FILE_ NAME - ACME account credentials file name (JSON, 0o600).
- TLS_
ACME_ DIR_ NAME - Subdirectory of
TLS_DIR_NAMEfor ACME account + issued certificates. - TLS_
ACME_ ORDER_ FILE_ NAME - Pending ACME order state file name (agent two-step DNS-01 flow).
- TLS_
CERT_ FILE_ NAME - Certificate chain PEM file name under an ACME/mTLS identity directory.
- TLS_
DIR_ NAME - XDG subdirectory for TLS material (mTLS client certs, ACME account/certs).
- TLS_
KEY_ FILE_ NAME - Private key PEM file name under an ACME/mTLS identity directory.
- TLS_
MTLS_ DIR_ NAME - Subdirectory of
TLS_DIR_NAMEfor imported mTLS client identities. - TUNNEL_
CHANNEL_ ORIGIN_ ADDR - Origin address advertised on SSH direct-tcpip channels for local forwards.
- TUNNEL_
CHANNEL_ ORIGIN_ PORT - Origin port advertised on SSH direct-tcpip channels (
0= ephemeral/unspecified). - TUNNEL_
FORWARD_ DRAIN_ TIMEOUT_ SECS - Grace period to drain in-flight tunnel forwards after stop.
- TUNNEL_
SIGNAL_ POLL_ INTERVAL_ MS - Tunnel accept-loop cooperative signal poll interval.
- WINDOWS_
SSH_ AGENT_ PIPE - Windows OpenSSH agent named pipe (platform default when
--use-agenthas no path).