Documentation: docs · specifications · examples
Deploy native VyOS configuration files over SSH and synchronize confirmed router state back to Git.
- SSH-key authentication via the shared
@eliware/ssh-clientlibrary, with optional password bootstrap via stdin. - Native VyOS curly-brace configuration validation.
- Candidate load,
compare,commit-confirm, confirmation, and save. - Complete
scripts/tree synchronization, including post-commit hooks, boot scripts, binaries, and nested support files. - Pushback of confirmed
/config/config.bootchanges to the current Git repository.
- Node.js 26 or newer.
- npm.
- SSH access to the target VyOS router using an existing key.
- A Git working tree when pushback behavior is enabled by the deployment workflow.
npm installThe package provides:
vyops Back up, preflight, or release a configuration bundle.
| Variable | Required | Default | Purpose |
|---|---|---|---|
VYOPS_SSH_KEY |
No | $HOME/.ssh/id_rsa |
Private SSH key path. |
SSH_AUTH_SOCK |
No | unset | SSH agent socket passed to the shared SSH client. |
SSH_KNOWN_HOSTS |
No | ~/.ssh/known_hosts |
Known-hosts file used for host verification. |
SSH_HOST_CA |
No | unset | Trusted SSH host-CA public key for certificate verification. |
VYOPS_CONNECT_TIMEOUT |
No | 30000 |
SSH connection timeout in milliseconds. |
VYOPS_OPERATION_TIMEOUT |
No | 60000 |
SSH exec/SFTP operation timeout in milliseconds. |
VYOPS_INTERACTIVE_TIMEOUT |
No | 60000 |
Interactive VyOS sequence timeout in milliseconds. |
LOG_LEVEL |
No | info |
Winston log level (error, warn, info, http, verbose, debug, or silly). |
The config must use native VyOS curly-brace syntax. The bundle's system host-name
and single system login user entry provide the release target automatically.
For a router that has not received its SSH key yet, provide the SSH password through stdin:
printf '%s\n' "$VYOS_PASSWORD" | vyops release --password-stdin /path/to/config.bootPassword mode still requires the target host key to be present in known_hosts; it does not disable host verification. Passwords are not accepted as command-line arguments or written to logs.
Preflight a bundle without connecting:
vyops preflight /path/to/config.bootRelease a bundle:
vyops release --yes /path/to/config.boot--yes is required to acknowledge the printed target summary. Add --verify to run
post-release checks for VRRP, WireGuard, BGP, routes, and HAProxy. Use
--verify-binaries to require staged .exe files to be recognized as
architecture-matching ELF binaries and to match their local SHA-256 hashes. Use
--no-pushback to leave Git unchanged, or --no-hooks only for emergency
troubleshooting; the latter prints a prominent warning.
Console switches:
vyops --help
vyops --version
vyops --debug preflight /path/to/config.boot
vyops release --yes --force --debug /path/to/config.boot
vyops backup vyos@core1 /path/to/backupbackup downloads the active /config/config.boot and the complete
/config/scripts tree into the destination directory. It does not enter
configuration mode or modify the router.
preflight validates the config and recursively checks the scripts/ tree before
any SSH connection. Executable scripts must use LF line endings, a supported
shell shebang, and valid executable intent. release runs the same checks before
uploading or changing the router.
Before upload, release also checks /config availability and writability,
free space, sudo, and systemd; HAProxy is required when the bundle contains
HAProxy hooks. Uploaded scripts are rechecked remotely for executable mode and
CR bytes. Releases retain config.boot.manifest.tsv beside the synchronized
config; it records hashes, modes, and pre-existing state and drives rollback.
With --debug, release logs include operation IDs and deployment phases so an
individual SSH command, upload, download, timeout, or cleanup event can be
correlated. Timeout failures discard the affected channel and SSH client and
report the target operation without logging credentials.
The opt-in live backup integration test can be run with
VYOPS_LIVE_TARGET=vyos@router VYOPS_LIVE_BACKUP_DEST=/path/to/destination.
It is skipped unless both variables are explicitly set.
The deployment workflow:
- Connects using SSH keys.
- Uploads the config to
/home/vyos. - Loads it into the candidate configuration.
- Prints
compareoutput. - Runs
commit-confirm. - Confirms and saves only after confirmation.
- Downloads
/config/config.bootback to the supplied config path (and the deployment manifest when scripts are managed). - Runs the deployed remote post-commit hooks, when present;
--verifyruns the optional operational checks before the hooks. - Removes temporary remote files and closes SSH sessions.
Exit code 0 means success. Non-zero means validation or deployment failure.
After a successful deployment, VyOps commits and pushes changes to the current Git repository with a Pushback <timestamp> commit. A later run skips deployment when the config is unchanged and the latest commit is a pushback commit.
Review repository status and remotes before deployment. Do not run deployments concurrently against core1 and core2.
- Config files may contain secrets; do not print, publish, or commit deployment logs containing config contents.
- Use least-privilege SSH accounts and keys dedicated to the target routers.
- Keep private keys outside the repository and restrict their filesystem permissions.
compareoutput is logged during deployment; review logs and diffs through the normal change-control process.- Use
LOG_LEVEL=debugonly when troubleshooting; debug output includes connection, path, and command progress.
npm install
npm test
npm run lint
npm run audit
npm run validate:packageCoverage is generated by the test command. Focused tests should be added with behavior changes. Never deploy to a router during tests unless explicitly requested.
Deployments require existing SSH keys and a reachable VyOS target. The workflow uses confirmed commits and saves only after confirmation. Temporary remote files are cleaned up in the deployment cleanup path. SIGINT, SIGTERM, and SIGHUP trigger SSH cleanup through the shared signal handlers.
Repository: git@github.com:eliware/vyops.git
Open an issue or provide a focused patch with tests and validation results.
MIT License; see LICENSE.