diff options
Diffstat (limited to 'docs/configuration/service')
| -rw-r--r-- | docs/configuration/service/https.rst | 186 | ||||
| -rw-r--r-- | docs/configuration/service/index.rst | 1 | ||||
| -rw-r--r-- | docs/configuration/service/ipoe-server.rst | 16 | ||||
| -rw-r--r-- | docs/configuration/service/salt-minion.disable | 2 | ||||
| -rw-r--r-- | docs/configuration/service/salt-minion.rst | 53 | ||||
| -rw-r--r-- | docs/configuration/service/snmp.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 7 | ||||
| -rw-r--r-- | docs/configuration/service/tftp-server.rst | 6 |
8 files changed, 120 insertions, 156 deletions
diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index b9c691da..1f1e2aa9 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -4,178 +4,88 @@ HTTP-API ######## -Enabling HTTP-API ------------------ +VyOS provide a HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. -VyOS HTTP API can be enabled through the ``set service https api`` command. - -.. code-block:: none - - set service https api debug - set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY - -The local API process listens on localhost:8080, and nginx exposes it on all -virtual servers, by default. For the purpose of illustration below, we will -assume nginx is running at https://192.168.122.127. - -One can limit proxying to specific listen addresses/ports/server-names by -defining a ``service https virtual-host <id>``, and setting ``service https -api-restrict virtual-host <id>``. - -.. code-block:: none - - set service https virtual-host example listen-address 192.168.122.127 - set service https virtual-host example listen-port 44302 - set service https virtual-host example server-name example.net - - set service https api-restrict virtual-host example - -In this example, nginx will proxy only those requests to -192.168.122.127:44302 or example.net:44302 (assuming the DNS record is -viable). Omitting any of listen-address, listen-port, or server-name, will -leave appropriate defaults in the nginx directive. Multiple instances of -``service https api-restrict virtual-host`` may be set. - -Configuration mode requests ---------------------------- - -In our example, we are creating a dummy interface and assigning an address to -it: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP -method it uses is POST. Request data is passed in the ``data=`` field and the -API key is passed in the ``key=`` field. Key identifiers from the config are -purely informational and the application doesn't need to know them, they only -appear in the server logs to avoid exposing keys in log files, you only need -the key itself. - -Since internally there is no distinction between a path and a value, you can -omit the value field and include the value in the path like it's done in the -shell commands: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -Separate value field make the semantics more clear though, and also makes it -easier to create a command template once and update it with different values -as needed. - -You can pass the ``set``, ``delete`` or ``comment`` command to it. -The API will push the command to the session and commit. - -To retrieve a value: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -Use ``returnValues`` for multi-valued nodes. +Please take a look at the :ref:`vyosapi` page for an detailed how-to. +************* +Configuration +************* -Show config -""""""""""" +.. cfgcmd:: set service https api keys id <name> key <apikey> -To retrieve the full config under a path: + Set an named api key, every key have the same, full permissions + on the system. -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve +.. cfgcmd:: set service https api debug -It will return: - -.. code-block:: none + To enable debug messages. Available via :opcmd:`show log` or + :opcmd:`monitor log` - {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} - -Passing an empty path will return the full config: - -.. code-block:: none +.. cfgcmd:: set service https api port - # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + Set the listen port of the local API, this have non effect of the + webserver. The default is port 8080 +.. cfgcmd:: set service https api strict -Configuration management requests ---------------------------------- + Enforce strict path checking -When saving or loading a configuration, the endpoint is ``/config-file`` and -you can pass the ``save`` or ``load`` command. +.. cfgcmd:: set service https virtual-host <vhost> listen-address -If you don't specify the file when saving, it saves to ``/config/config.boot``. -Here's an example: + Address to listen for HTTPS requests -.. code-block:: none +.. cfgcmd:: set service https virtual-host <vhost> listen-port <1-65535> - # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file + Port to listen for HTTPS requests; default 443 -Image management requests -------------------------- +.. cfgcmd:: set service https virtual-host <vhost> server-name <text> -One may ``add`` or ``delete`` a system image using the endpoint ``/image``. -Here are the respective examples: + Server names for virtual hosts it ca be exact, wildcard or regex. -``add`` from ``url``. Here we use the URL of the latest rolling release: +.. cfgcmd:: set service https api-restrict virtual-host <vhost> -.. code-block:: none + Nginx exposes the local API on all virtual servers, by default + Use this to restrict nginx to one or more virtual hosts. - # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image +.. cfgcmd:: set service https certificates certbot domain-name <text> -``delete`` by image ``name``. For example: + Domain name(s) for which to obtain certificate -.. code-block:: none +.. cfgcmd:: set service https certificates certbot email - # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + Email address to associate with certificate -To list the available system images by name, one may use the operational mode -request ``show`` discussed in the next section; in this setting it would be: +.. cfgcmd:: set service https certificates system-generated-certificate -.. code-block:: none + Use an automatically generated self-signed certificate - # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show +.. cfgcmd:: set service https certificates system-generated-certificate + lifetime <days> -Operational mode requests -------------------------- + Lifetime in days; default is 365 -It is possible to run ``show`` and ``generate`` commands: +********************* +Example Configuration +********************* -Request: +Set an API-KEY is the minimal configuration to get a working API Endpoint. .. code-block:: none - curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate - -Response: - -.. code-block:: none + set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY - {"success": true, "data": "", "error": null} -Request: +To use this full configuration we asume a publice accessable hostname. .. code-block:: none - curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "<some pubkey>=\n", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} - + set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY + set service https certificates certbot domain-name rtr01.example.com + set service https certificates certbot email mail@example.com + set service https virtual-host rtr01 listen-address 198.51.100.2 + set service https virtual-host rtr01 listen-port 11443 + set service https virtual-host rtr01 server-name rtr01.example.com + set service https api-restrict virtual-host rtr01.example.com
\ No newline at end of file diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index fb194239..96660e91 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -19,6 +19,7 @@ Service mdns pppoe-server router-advert + salt-minion snmp ssh tftp-server diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 7858ff19..eea9517d 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -72,11 +72,11 @@ IPv6 DNS addresses are optional. set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 set service ipoe-server authentication mode 'local' - set service ipoe-server client-ipv6-pool delegate-prefix '2001:db8:1::/48,56' - set service ipoe-server client-ipv6-pool prefix '2001:db8::/48,64' - set service ipoe-server dnsv6-server server-1 '2001:db8::' - set service ipoe-server dnsv6-server server-2 '2001:db8:aaa::' - set service ipoe-server dnsv6-server server-3 '2001:db8:bbb::' + set service ipoe-server client-ipv6-pool delegate '2001:db8:1::/48' delegation-prefix '56' + set service ipoe-server client-ipv6-pool prefix '2001:db8::/48' mask '64' + set service ipoe-server name-server '2001:db8::' + set service ipoe-server name-server '2001:db8:aaa::' + set service ipoe-server name-server '2001:db8:bbb::' set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' .. code-block:: none @@ -116,7 +116,7 @@ example configuration can be used. .. code-block:: none set service ipoe-server authentication mode 'radius' - set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' + set service ipoe-server authentication radius server 10.100.100.1 key 'password' Bandwidth Shaping ================= @@ -134,8 +134,8 @@ The rate-limit is set in kbit/sec. set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '10.10.1.1' - set service ipoe-server dns-server server-2 '10.10.1.2' + set service ipoe-server name-server '10.10.1.1' + set service ipoe-server name-server '10.10.1.2' set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' .. code-block:: none diff --git a/docs/configuration/service/salt-minion.disable b/docs/configuration/service/salt-minion.disable deleted file mode 100644 index 63df57a4..00000000 --- a/docs/configuration/service/salt-minion.disable +++ /dev/null @@ -1,2 +0,0 @@ -salt-minion -###########
\ No newline at end of file diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/salt-minion.rst new file mode 100644 index 00000000..aa747c36 --- /dev/null +++ b/docs/configuration/service/salt-minion.rst @@ -0,0 +1,53 @@ +.. _saltminion: + +########### +Salt-Minion +########### + +SaltStack_ is Python-based, open-source +software for event-driven IT automation, remote task execution, and +configuration management. Supporting the "infrastructure as code" +approach to data center system and network deployment and management, +configuration automation, SecOps orchestration, vulnerability remediation, +and hybrid cloud control. + + +************ +Requirements +************ + +To use the Salt-Minion, a running Salt-Master is required. You can find more +in the `Salt Poject Documentaion +<https://docs.saltproject.io/en/latest/contents.html>`_ + +************* +Configuration +************* + +.. cfgcmd:: set service salt-minion hash <type> + + The hash type used when discovering file on master server (default: sha256) + +.. cfgcmd:: set service salt-minion id <id> + + Explicitly declare ID for this minion to use (default: hostname) + +.. cfgcmd:: set service salt-minion interval <1-1440> + + Interval in minutes between updates (default: 60) + +.. cfgcmd:: set service salt-minion master <hostname | IP> + + The hostname or IP address of the master + +.. cfgcmd:: set service salt-minion master-key <key> + + URL with signature of master for auth reply verification + + +Please take a look in the Automation section to find some usefull +Examples. + + + +.. _SaltStack: https://saltproject.io/
\ No newline at end of file diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index e962c1c5..4a5a2780 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -201,7 +201,8 @@ VyOS MIBs All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/`` -you are be able to download the files with the a activate ssh service like this +You are be able to download the files using SCP, once the SSH service +has been activated like so .. code-block:: none @@ -270,4 +271,4 @@ following content: .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 .. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 -.. start_vyoslinter
\ No newline at end of file +.. start_vyoslinter diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 94249766..6b09d40d 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -127,8 +127,8 @@ Operation .. opcmd:: generate ssh client-key /path/to/private_key - Re-generated a known pub/private keyfile which can e.g. used to connect to - other services (RPKI cache). + Re-generated a known pub/private keyfile which can be used to connect to + other services (e.g. RPKI cache). Example: @@ -153,5 +153,6 @@ Operation | =.. o=.oo| +----[SHA256]-----+ - Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub`` + Two new files ``/config/auth/id_rsa_rpki`` and + ``/config/auth/id_rsa_rpki.pub`` will be created. diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst index 276ce5fb..d220d789 100644 --- a/docs/configuration/service/tftp-server.rst +++ b/docs/configuration/service/tftp-server.rst @@ -32,15 +32,15 @@ on each IP address. .. cfgcmd:: set service tftp-server allow-upload -Optional, if you want to enable uploads, else TFTP server will act as read-only -server. +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. Example ------- Provide TFTP server listening on both IPv4 and IPv6 addresses ``192.0.2.1`` and ``2001:db8::1`` serving the content from ``/config/tftpboot``. Uploading via -TFTP to this server is not allowed! +TFTP to this server is disabled. The resulting configuration will look like: |