diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_html_extra/robots.txt | 7 | ||||
| -rw-r--r-- | docs/automation/vyos-api.rst | 117 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/configuration/container/index.rst | 9 | ||||
| -rw-r--r-- | docs/configuration/firewall/ipv4.rst | 8 | ||||
| -rw-r--r-- | docs/configuration/firewall/ipv6.rst | 8 | ||||
| -rw-r--r-- | docs/configuration/interfaces/geneve.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/loadbalancing/haproxy.rst | 46 | ||||
| -rw-r--r-- | docs/configuration/policy/community-list.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/policy/route-map.rst | 1 | ||||
| -rw-r--r-- | docs/configuration/policy/route.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/service/lldp.rst | 12 | ||||
| -rw-r--r-- | docs/configuration/system/login.rst | 12 | ||||
| -rw-r--r-- | docs/configuration/system/syslog.rst | 4 | ||||
| -rw-r--r-- | docs/installation/install.rst | 2 |
15 files changed, 218 insertions, 22 deletions
diff --git a/docs/_html_extra/robots.txt b/docs/_html_extra/robots.txt new file mode 100644 index 00000000..627cb18e --- /dev/null +++ b/docs/_html_extra/robots.txt @@ -0,0 +1,7 @@ +User-agent: atlassian-bot +Disallow: + +User-agent: * +Disallow: # Allow everything + +Sitemap: https://docs.vyos.io/sitemap.xml
\ No newline at end of file diff --git a/docs/automation/vyos-api.rst b/docs/automation/vyos-api.rst index 60247fae..a9518a00 100644 --- a/docs/automation/vyos-api.rst +++ b/docs/automation/vyos-api.rst @@ -12,8 +12,9 @@ For configuration and enabling the API see :ref:`http-api` Authentication ************** -All endpoints only listen on HTTP POST requests and the API KEY must set as -``key`` in the formdata. +All endpoints except one listen on HTTP POST requests and the API KEY must set +as ``key`` in the formdata. The only public endpoint listens to HTTP GET request +and takes optional query parameters. Below see one example for curl and one for python. The rest of the documentation is reduced to curl. @@ -39,6 +40,118 @@ The rest of the documentation is reduced to curl. ************* API Endpoints ************* +/info +========= + +This is the only endpoint provided by the API service that does not require +authentication and can be queried by anonymous users. Requesting the ``info`` +endpoint you obtain general information about the system, namely the VyOS +version, the system host name and a welcome banner for anonymous users. + +This endpoint responds **only** to HTTP GET requests. + +.. code-block:: none + + curl --location --request GET 'https://vyos/info' + + response + { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname: "vyos" + "banner": "Welcome to VyOS" + }, + "error": null + } + +This endpoint can take two optional query parameters - ``version`` and +``hostname``. These parameters accept all values that can be converted to +Boolean - e.g. ``yes/no``, ``1/0``, ``true/false`` etc, and they dictate whether +to include the respective values into the response. + +If request is sent without any query parameters, the endpoints treats them as +if they are set to ``true`` by default: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?version=1&hostname=1' + + response { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname": "vyos", + "banner": "Welcome to VyOS" + }, + "error": null + } + +If any of the parameters is set to a value that corresponds to ``false``, the +response object will have an empty string instead of the respective value: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?version=0&hostname=1' + + response { + "success": true, + "data": { + "version": "", + "hostname": "vyos", + "banner": "Welcome to VyOS" + }, + "error": null + } + +Please note, that there is no need to specify both parameters if you want to +hide just one of the fields - a missing query parameter is treated as ``true``: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?hostname=no' + + response { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname": "", + "banner": "Welcome to VyOS" + }, + "error": null + } + +Please note, that while you can disable output for both ``hostname`` and +``version``, the ``banner`` is included into the response in any case. + +**Important:** The endpoint accepts **ONLY** ``hostname`` and ``version`` query +parameters. Including any other besides them, or instead of them, will respond +with HTTP 400 Bad Request: + +.. code-block:: none + + curl --location --request GET \ + 'https://192.168.56.119/info?hostname=1&url=https://evilsite.com' + + response { + "success": false, + "error": "{'type': 'extra_forbidden', 'loc': ('query', 'url'), 'msg': 'Extra inputs are not permitted', 'input': 'https://evilsite.com'}", + "data": null + } + +As well as the values passed to the query string are validated to ensure they +are strictly Boolean and won't accept any other data type: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?hostname=1; eval"sudo rm -rf /" + + response + { + "success": false, + "error": "{'type': 'bool_parsing', 'loc': ('query', 'hostname'), 'msg': 'Input should be a valid boolean, unable to interpret input', 'input': '1; eval \"sudo rm -rf /\"'}", + "data": null + } /retrieve ========= diff --git a/docs/conf.py b/docs/conf.py index f05832fe..95f0c31a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -109,6 +109,8 @@ html_theme = "sphinx_rtd_theme" # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_extra_path = ['_html_extra'] + # Custom sidebar templates, must be a dictionary that maps document names # to template names. # diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 8327f169..5882f6db 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -124,6 +124,15 @@ Configuration Volume is either mounted as rw (read-write - default) or ro (read-only) +.. cfgcmd:: set container name <name> tmpfs <tmpfsname> destination <path> + + Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. + +.. cfgcmd:: set container name <name> tmpfs <tmpfsname> size <MB> + + Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the + systems total available memory. + .. cfgcmd:: set container name <name> uid <number> .. cfgcmd:: set container name <name> gid <number> diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index 5fc9bd4c..a9435fa8 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-03 +:lastproofread: 2025-02-14 .. _firewall-ipv4-configuration: @@ -188,7 +188,7 @@ The action can be : distribute packets between several queues. Also, **default-action** is an action that takes place whenever a packet does -not match any rule in it's chain. For base chains, possible options for +not match any rule in its chain. For base chains, possible options for **default-action** are **accept** or **drop**. .. cfgcmd:: set firewall ipv4 forward filter default-action @@ -219,7 +219,7 @@ not match any rule in it's chain. For base chains, possible options for Firewall Logs ============= -Logging can be enable for every single firewall rule. If enabled, other +Logging can be enabled for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log @@ -1236,7 +1236,7 @@ Rule-set overview .. opcmd:: show firewall statistics - This will show you a statistic of all rule-sets since the last boot. + This will show you statistics of all rule-sets since the last boot. Show Firewall log ================= diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index c579b6d1..95502f4a 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-03 +:lastproofread: 2025-02-14 .. _firewall-ipv6-configuration: @@ -188,7 +188,7 @@ The action can be : distribute packets between several queues. Also, **default-action** is an action that takes place whenever a packet does -not match any rule in it's chain. For base chains, possible options for +not match any rule in its chain. For base chains, possible options for **default-action** are **accept** or **drop**. .. cfgcmd:: set firewall ipv6 forward filter default-action @@ -219,7 +219,7 @@ not match any rule in it's chain. For base chains, possible options for Firewall Logs ============= -Logging can be enable for every single firewall rule. If enabled, other +Logging can be enabled for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log @@ -1242,7 +1242,7 @@ Rule-set overview .. opcmd:: show firewall statistics - This will show you a statistic of all rule-sets since the last boot. + This will show you statistics of all rule-sets since the last boot. Show Firewall log ================= diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index a0a46a95..e9d2d52b 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -85,3 +85,8 @@ GENEVE options decisions or MAY be used as a mechanism to distinguish between overlapping address spaces contained in the encapsulated packet when load balancing across CPUs. + +.. cfgcmd:: set interfaces gnv0 <interface> port <port> + + Configure port number of remote GENEVE endpoint. + diff --git a/docs/configuration/loadbalancing/haproxy.rst b/docs/configuration/loadbalancing/haproxy.rst index c7c25783..e62740ce 100644 --- a/docs/configuration/loadbalancing/haproxy.rst +++ b/docs/configuration/loadbalancing/haproxy.rst @@ -57,6 +57,12 @@ Service For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` see tables in syslog configuration section. +.. cfgcmd:: set load-balancing haproxy service <name> timeout client + <seconds> + + Set the maximum inactivity time on the client side for this service. + Value range 1-3600 seconds. + .. cfgcmd:: set load-balancing haproxy service <name> http-compression algorithm <gzip | deflate | identity | raw-deflate> @@ -184,6 +190,26 @@ Backend For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` see tables in syslog configuration section. +.. cfgcmd:: set load-balancing haproxy backend <name> timeout check + <seconds> + + Set the timeout in seconds for established connections. + Value range 1-3600 seconds. + + +.. cfgcmd:: set load-balancing haproxy backend <name> timeout connect + <seconds> + + Set the maximum time to wait for a connection attempt to a server to succeed. + Value range 1-3600 seconds. + +.. cfgcmd:: set load-balancing haproxy backend <name> timeout server + <seconds> + + Set the maximum inactivity time on the server side. + Value range 1-3600 seconds. + + Global ------- @@ -212,6 +238,26 @@ Global parameters For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` see tables in syslog configuration section. +.. cfgcmd:: set load-balancing haproxy timeout check <seconds> + + Set the timeout in seconds for established connections. + Value range 1-3600 seconds. Default is 5 seconds. + +.. cfgcmd:: set load-balancing haproxy timeout client <seconds> + + Set the maximum inactivity time on the client side. + Value range 1-3600 seconds. Default is 50 seconds. + +.. cfgcmd:: set load-balancing haproxy timeout connect <seconds> + + Set the maximum time to wait for a connection attempt to a server to succeed. + Value range 1-3600 seconds. Default is 10 seconds. + +.. cfgcmd:: set load-balancing haproxy timeout server <seconds> + + Set the maximum inactivity time on the server side. + Value range 1-3600 seconds. Default is 50 seconds. + Health checks ============= diff --git a/docs/configuration/policy/community-list.rst b/docs/configuration/policy/community-list.rst index e53abeb3..ee2da03c 100644 --- a/docs/configuration/policy/community-list.rst +++ b/docs/configuration/policy/community-list.rst @@ -30,6 +30,6 @@ policy community-list Set description for rule. .. cfgcmd:: set policy community-list <text> rule <1-65535> regex - <aa:nn|local-AS|no-advertise|no-export|internet|additive> + <aa:nn|local-AS|no-advertise|no-export|additive> Regular expression to match against a community-list.
\ No newline at end of file diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/route-map.rst index ccc4cef0..03cdb99b 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/route-map.rst @@ -366,7 +366,6 @@ List of well-known communities * ``local-as`` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 * ``no-advertise`` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 * ``no-export`` - Well-known communities value NO_EXPORT 0xFFFFFF01 - * ``internet`` - Well-known communities value 0 * ``graceful-shutdown`` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 * ``accept-own`` - Well-known communities value ACCEPT_OWN 0xFFFF0001 * ``route-filter-translated-v4`` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/route.rst index 45975774..b818d238 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/route.rst @@ -24,6 +24,11 @@ from 1 - 999999, at the first match the action of the rule will be executed. Option to log packets hitting default-action. +.. cfgcmd:: set policy route <name> interface <interface> +.. cfgcmd:: set policy route6 <name> interface <interface> + + Apply routing policy to interface + .. cfgcmd:: set policy route <name> rule <n> description <text> .. cfgcmd:: set policy route6 <name> rule <n> description <text> diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst index 12a9e0b6..8aee6183 100644 --- a/docs/configuration/service/lldp.rst +++ b/docs/configuration/service/lldp.rst @@ -49,10 +49,16 @@ Configuration Enable transmission of LLDP information on given `<interface>`. You can also say ``all`` here so LLDP is turned on on every interface. -.. cfgcmd:: set service lldp interface <interface> disable +.. cfgcmd:: set service lldp interface <interface> mode [disable|rx-tx|rx|tx] - Disable transmit of LLDP frames on given `<interface>`. Useful to exclude - certain interfaces from LLDP when ``all`` have been enabled. + Configure the administrative status of the given port. + + By default, all ports are configured to be in rx-tx mode. This means they + can receive and transmit LLDP frames. + + In rx mode, they won't emit any frames. In tx mode, they won't receive + any frames. In disabled mode, no frame will be sent and any incoming frame + will be discarded. .. cfgcmd:: set service lldp snmp diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 452981a9..3a7481eb 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -319,28 +319,28 @@ TACACS is defined in :rfc:`8907`. Configuration ------------- -.. cfgcmd:: set system login tacas server <address> key <secret> +.. cfgcmd:: set system login tacacs server <address> key <secret> Specify the IP `<address>` of the TACACS server user with the pre-shared-secret given in `<secret>`. Multiple servers can be specified. -.. cfgcmd:: set system login tacas server <address> port <port> +.. cfgcmd:: set system login tacacs server <address> port <port> Configure the discrete port under which the TACACS server can be reached. This defaults to 49. -.. cfgcmd:: set system login tacas server <address> disable +.. cfgcmd:: set system login tacacs server <address> disable Temporary disable this TACACS server. It won't be queried. -.. cfgcmd:: set system login tacas server <address> timeout <timeout> +.. cfgcmd:: set system login tacacs server <address> timeout <timeout> Setup the `<timeout>` in seconds when querying the TACACS server. -.. cfgcmd:: set system login tacas source-address <address> +.. cfgcmd:: set system login tacacs source-address <address> TACACS servers could be hardened by only allowing certain IP addresses to connect. As of this the source address of each TACACS query can be @@ -350,7 +350,7 @@ Configuration interface address pointing towards the server - making it error prone on e.g. OSPF networks when a link fails and a backup route is taken. -.. cfgcmd:: set system login tacas vrf <name> +.. cfgcmd:: set system login tacacs vrf <name> Source all connections to the TACACS servers from given VRF `<name>`. diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 73baaa5e..41a65934 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -27,6 +27,10 @@ Global Settings This defaults to 1200 seconds. +.. cfgcmd:: system syslog marker disable + + Disable periodic injection of mark messages. + .. cfgcmd:: system syslog preserve-fqdn If set, the domain part of the hostname is always sent, even within the same diff --git a/docs/installation/install.rst b/docs/installation/install.rst index 13c2e9a5..9ba310fe 100644 --- a/docs/installation/install.rst +++ b/docs/installation/install.rst @@ -44,7 +44,7 @@ any other type of storage. Hardware requirements ===================== -The minimum system requirements are 1024 MiB RAM and 2 GiB storage. +The minimum system requirements are 4 GB RAM and 10 GB storage. Depending on your use, you might need additional RAM and CPU resources e.g. when having multiple BGP full tables in your system. |