1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# 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`](https://github.com/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
```bash
# 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`.
|
