Skip to content

AGENTS.md

Latest commit

 

History

History
112 lines (93 loc) · 4.95 KB

AGENTS.md

File metadata and controls

112 lines (93 loc) · 4.95 KB
Raw

AGENTS.md

Project purpose

The user-visible VyOS package: command definitions (XML), conf-mode and op-mode scripts, Jinja2 templates, validators, migration scripts, and the Python vyos.* library imported by all of the above.

This is the largest single VyOS package and the primary surface for new feature work in 1.4+.

Tech stack

  • Python 3 (>=3.11) with the vyos.* library under python/vyos/.
  • XML interface definitions for configure mode (conf-mode) are located in interface-definitions/. XML CLI building blocks can be split into include files to reduce duplication. Include files are in interface-definitions/include/.
  • XML definitions for operational mode (op-mode) CLI commands are stored in op-mode-definitions/. They use the same include pattern as conf-mode. Include files are in op-mode-definitions/include/.
  • Both conf-mode and op-mode make heavy use of Jinja2 as a templating engine. Jinja2 templates are either inline Python strings or stored as discrete files under data/templates/. Storing templates as files is preferred.
  • C wrapper libvyosconfig (vendored at libvyosconfig/) builds libvyosconfig.so.0 (shared library) using OCaml ctypes bindings against vyos/vyos1x-config.
  • Build: Debian packaging via debhelper + dh-python. Build dependencies are in debian/control (for example: protobuf-compiler, libpcre2-dev, libffi-dev, python3-vici, python3-fastapi,...).
  • Tests: nose2 (nose2.cfg), Python pylint, and ruff (ruff.toml).
  • Runtime smoketests are located under smoketest/. These tests are used by vyos-build when assembling and testing ISO images.

Build instructions

# Debian package build (produces 6 binary packages)
dpkg-buildpackage -uc -us -tc -b
# or
make deb

# In-tree build (XML preprocessing + shim compilation)
make all  # see Makefile targets

Produces: vyos-1x, libvyosconfig0, vyos-1x-aws, vyos-1x-smoketest, vyos-1x-vmware, vyos-user-utils.

Testing instructions

Smoketests (smoketest/) run inside the QEMU harness invoked by vyos-build's scripts/check-qemu-install --smoketest.

Repository layout

  • python/vyos/ - importable Python library (config.py, configtree.py ctypes wrapper, configsession.py, firewall.py, frrender.py, ifconfig drivers).
  • src/conf_mode/ - set-mode entry-point scripts named after CLI components.
  • src/op_mode/ - show/op-mode scripts.
  • src/validators/ - value validators (Python; OCaml validators come from src/ocaml/).
  • src/migration-scripts/ - config-format migrations between releases.
  • src/services/ - runtime services, including the HTTP API implementation.
  • interface-definitions/ - XML CLI declarations (preprocessed via scripts/build-command-templates, scripts/override-default, scripts/transclude-template).
  • op-mode-definitions/ - op-mode XML.
  • data/templates/ - Jinja2 input templates for third-party services consumed by VyOS (FRR, strongSwan, nftables, dnsmasq,...).
  • libvyosconfig/ - C wrapper; source of the libvyosconfig0 Debian package.
  • smoketest/ - nose2 CLI smoketests.
  • schema/, mibs/, debian/, scripts/.

Cross-repo context

  • Imports libvyosconfig0 (built from in-tree libvyosconfig/, which wraps vyos/vyos1x-config).
  • Calls OCaml validators from src/ocaml/ via <validator name='...'/> XML directives. OCaml validators reduce Python interpreter startup overhead and make configuration commits faster.
  • vyos/vyos-documentation carries docs/_include/vyos-1x as a submodule pinned to sagitta — do not bump the doc submodule branch without a coordinated change.
  • HTTP API runtime dependencies come from vyos/vyos-http-api-tools; the FastAPI implementation lives in src/services/.

Conventions

  • Commit/PR titles must follow: component: T1234: description. Phorge IDs are at https://vyos.dev. This is enforced by the check-pr-message.yml reusable workflow.
  • See CONTRIBUTING.md for additional commit message guidance.
  • Branch model: rolling (default), circinus (1.5 LTS), sagitta (1.4 LTS), equuleus (1.3 LTS). Backports via @Mergifyio backport <branch>.
  • Default-branch protection: 2 required approvals; required status checks.
  • Linting (vyos/.github reusables): ruff 0.6.4, darker, pylint W0611, Jinja2 lint. ruff.toml and nose2.cfg are at repository root.
  • No mergify.yml - vyos-1x is one of the few mirror-pipeline consumers without it.

Notes for future contributors

  • The vendored libvyosconfig/ is not just a wrapper - it produces the libvyosconfig0 Debian package. Edits there affect every consumer of the config-tree API.
  • New features go here, not in the legacy vyatta-cfg* repositories.
  • 2 repository-level Actions secrets, 2 environments, 2 outbound webhooks. Do not enumerate secret names or infrastructure endpoints in code or docs.
  • License: GPL/LGPL dual; see LICENSE, LICENSE.GPL, LICENSE.LGPL.