VyOps

Deploy native VyOS configuration files over SSH and synchronize confirmed router state back to Git.

Features

• SSH-key authentication via the shared @eliware/ssh-client library, 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.boot changes to the current Git repository.

Requirements

• 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.

Installation

npm install

The package provides:

vyops   Preflight or release a configuration bundle.

Configuration

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.
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.boot

Password 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.

Usage

Preflight a bundle without connecting:

vyops preflight /path/to/config.boot

Release a bundle:

vyops release /path/to/config.boot

Console switches:

vyops --help
vyops --version
vyops --debug preflight /path/to/config.boot
vyops release --force --debug /path/to/config.boot
vyops backup vyos@core1 /path/to/backup

backup 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.

The deployment workflow:

1. Connects using SSH keys.
2. Uploads the config to /home/vyos.
3. Loads it into the candidate configuration.
4. Prints compare output.
5. Runs commit-confirm.
6. Confirms and saves only after confirmation.
7. Installs local post-commit hooks, when present.
8. Downloads /config/config.boot back to the supplied config path.
9. Removes temporary remote files and closes SSH sessions.

Exit code 0 means success. Non-zero means validation or deployment failure.

Git pushback behavior

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.

Security

• 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.
• compare output is logged during deployment; review logs and diffs through the normal change-control process.
• Use LOG_LEVEL=debug only when troubleshooting; debug output includes connection, path, and command progress.

Development and validation

npm install
npm test
npm run lint
npm run audit
npm run validate:package

Coverage is generated by the test command. Focused tests should be added with behavior changes. Never deploy to a router during tests unless explicitly requested.

Operational notes

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.

Support

Repository: git@github.com:eliware/vyops.git

Open an issue or provide a focused patch with tests and validation results.

License

MIT License; see LICENSE.