From 5eb383a10ec92c65eed525bc174785a6852e997f Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 14:40:59 +0300 Subject: Add incremental RST-to-MyST swap mechanism (circinus) (#1867) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(swap-circinus): add incremental RST-to-MyST swap mechanism Backport of the swap mechanism from feat/incremental-myst-swap onto the circinus release branch. Built directly on top of origin/circinus, so the underlying RST tree is circinus's (not current's). Mechanism: - scripts/import_myst.py — import md from myst/* with md- prefix - scripts/swap_sources.py — rename md-{name}.md → {name}.md before Sphinx builds, restore after; writes _build/_swap_state.json and _build/_swap_exclude.txt - docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build → trap restore; explicit `swap` and `restore` targets too - docs/conf.py — MyST extensions enabled; swap exclude_patterns loader; _prefer_webp builder hook so html prefers webp over png Content (all from origin/myst/circinus): - 253 md-prefixed pages alongside each {name}.rst counterpart - 1 plain MyST-only page kept at canonical name (docs/copyright.md, no .rst counterpart) - 182 .webp images added (circinus release previously had only PNG/JPG; this PR brings webp into circinus alongside the originals) - docs/_swap.txt populated with all 253 stems → MyST is served by default; revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) * fix(ext): handle RST fallback in CmdInclude when _renderer absent `cmdincludemd` is in `myst_fence_as_directive`, so MyST routes fence blocks through `render_fence → render_restructuredtext → MockRSTParser`. In that path `self.state` is a plain docutils Body with no `_renderer`, crashing the RTD build. Fall back to `nested_parse` when `_renderer` is unavailable so the directive works in both MyST and RST/MockRSTParser contexts. 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback (backport from PR #1857) 🤖 Generated by [robots](https://vyos.io) * docs: port .readthedocs.yml jobs and swap-script tests from PR #1857 Parity backport from PR #1857 (current) — was missing on circinus. - .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run scripts/swap_sources.py --swap before the Sphinx build and --restore after. Without this, the swap mechanism ships but never runs on RTD builds for this branch — the swap is a silent no-op. - tests/test_import_myst.py, tests/test_swap_sources.py: tests for the swap scripts. The scripts are identical to current's, so the same tests apply. Travels with the branch so CI catches per-branch regressions if the scripts ever drift. 🤖 Generated by [robots](https://vyos.io) * fix(review): add conftest, filter md- from copy, fix _prefer_webp builder list, trailing newline Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/64b17346-8739-4346-b619-84438cddef21 Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --- docs/configuration/service/md-https.md | 138 +++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/configuration/service/md-https.md (limited to 'docs/configuration/service/md-https.md') diff --git a/docs/configuration/service/md-https.md b/docs/configuration/service/md-https.md new file mode 100644 index 00000000..184fd088 --- /dev/null +++ b/docs/configuration/service/md-https.md @@ -0,0 +1,138 @@ +(http-api)= + +# HTTP API + +VyOS provide an HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. + +Please take a look at the {ref}`vyosapi` page for an detailed how-to. + +## Configuration + +```{cfgcmd} set service https allow-client address \ + +Only allow certain IP addresses or prefixes to access the https +webserver. +``` + +```{cfgcmd} set service https certificates ca-certificate \ + +Use CA certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates certificate \ + +Use certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates dh-params \ + +Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem. +Must be at least 2048 bits in length. +``` + +```{cfgcmd} set service https listen-address \ + +Webserver should only listen on specified IP address +``` + +```{cfgcmd} set service https port \ + +Webserver should listen on specified port. + +Default: 443 +``` + +```{cfgcmd} set service https enable-http-redirect + +Enable automatic redirect from http to https. +``` + +```{cfgcmd} set service https tls-version \<1.2 | 1.3\> + +Select TLS version used. + +This defaults to both 1.2 and 1.3. +``` + +```{cfgcmd} set service https vrf \ + +Start Webserver in given VRF. +``` + +```{cfgcmd} set service https request-body-size-limit \ + +Set the maximum request body size in megabytes. Default is 1MB. +``` + + +### API + +```{cfgcmd} set service https api keys id \ key \ + +Set a named api key. Every key has the same, full permissions +on the system. +``` + + +### REST + +```{cfgcmd} set service https api rest + +Enable REST API +``` + +```{cfgcmd} set service https api rest debug + +To enable debug messages. Available via {opcmd}`show log` or +{opcmd}`monitor log` +``` + +```{cfgcmd} set service https api rest strict + +Enforce strict path checking. +``` + + +### GraphQL + +```{cfgcmd} set service https api graphql introspection + +Enable GraphQL Schema introspection. +``` + +:::{note} +Do not leave introspection enabled in production, it is a security risk. +::: + +```{cfgcmd} set service https api graphql authentication type \ + +Set the authentication type for GraphQL, default option is key. Available options are: +* ``key`` use API keys configured in ``service https api keys`` +* ``token`` use JWT tokens. +``` + +```{cfgcmd} set service https api graphql authentication expiration + +Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. +``` + +```{cfgcmd} set service https api graphql authentication secret-length + +Set the byte length of the JWT secret. Default is 32. +``` + +```{cfgcmd} set service https api graphql cors allow-origin \ + +Allow cross-origin requests from \. +``` + + +## Example Configuration + +Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint. + +```none +set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY +set service https api rest +``` -- cgit v1.2.3