diff options
Diffstat (limited to 'docs')
| m--------- | docs/_include/vyos-1x | 0 | ||||
| -rw-r--r-- | docs/automation/cloud-init.rst | 81 | ||||
| -rw-r--r-- | docs/automation/vyos-api.rst | 2 | ||||
| -rw-r--r-- | docs/changelog/1.3.rst | 97 | ||||
| -rw-r--r-- | docs/changelog/1.4.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/service/https.rst | 14 | ||||
| -rw-r--r-- | docs/configuration/service/snmp.rst | 4 | ||||
| -rw-r--r-- | docs/debugging.rst | 5 | ||||
| -rw-r--r-- | docs/installation/install.rst | 55 |
9 files changed, 222 insertions, 58 deletions
diff --git a/docs/_include/vyos-1x b/docs/_include/vyos-1x -Subproject c2dfb24a0672ea93a4262feeddd6929275eb08c +Subproject 147f655a69cd9526cd23f51ab18027cb5abc95b diff --git a/docs/automation/cloud-init.rst b/docs/automation/cloud-init.rst index 2be66f7f..10bab72c 100644 --- a/docs/automation/cloud-init.rst +++ b/docs/automation/cloud-init.rst @@ -58,9 +58,19 @@ cloud-config file format ************************ A cloud-config document is written in YAML. The file must begin -with ``#cloud-config`` line. The key used to designate a VyOS configuration -is ``vyos_config_commands``. What follows is VyOS configuration using -the "set-style" syntax. Both "set" and "delete" commands are supported. +with ``#cloud-config`` line. The only supported top-level keys are +``vyos_config_commands`` and ``write_files``. The use of these keys is described +in the following two sections. + + +************************ +Initial Configuration +************************ + + +The key used to designate a VyOS configuration is ``vyos_config_commands``. What +follows is VyOS configuration using the "set-style" syntax. Both "set" and "delete" +commands are supported. Commands requirements: @@ -75,7 +85,7 @@ proper commands list by copying it from another router. The configuration specified in the cloud-config document overwrites default configuration values and values configured via Metadata. -Here is an example cloud-config. +Here is an example cloud-config that appends configuration at the time of first boot. .. code-block:: yaml @@ -88,9 +98,9 @@ Here is an example cloud-config. - set interfaces ethernet eth1 address '192.0.2.247/24' - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' -************************* +------------------------- System Defaults/Fallbacks -************************* +------------------------- These are the VyOS defaults and fallbacks. @@ -100,6 +110,65 @@ These are the VyOS defaults and fallbacks. All of these can be overridden using the configuration in user-data. + +********************************* +Command Execution at Initial Boot +********************************* + +VyOS supports the execution of operational commands and linux commands at +initial boot. This is accomplished using ``write_files`` to certain +files in the /opt/vyatta/etc/config/scripts directory. Commands specified +in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed +prior to configuration. The +/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains +commands to be executed after configuration. In both cases, commands are +executed as the root user. + +Note that the /opt/vyatta/etc/config is used instead of the /config/scripts +directory referenced in the :ref:`command-scripting` section of the +documentation because the /config/script directory isn't mounted when the +``write_files`` module executes. + +The following example shows how to execute commands after the initial +configuration. + +.. code-block:: yaml + + #cloud-config + write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log + run show ip bgp summary >> $filename + + +If you need to gather information from linux commands to configure VyOS, you can +execute commands and then configure VyOS in the same script. + +The following example sets the hostname based on the instance identifier +obtained from the EC2 metadata service. + +.. code-block:: yaml + + + #cloud-config + write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` + configure + set system host-name $hostname + commit + exit + *************** Troubleshooting *************** diff --git a/docs/automation/vyos-api.rst b/docs/automation/vyos-api.rst index 27655483..8bc33d53 100644 --- a/docs/automation/vyos-api.rst +++ b/docs/automation/vyos-api.rst @@ -190,7 +190,7 @@ For example, show which images are installed. /generate ========= -THe ``generate`` endpoint run a ``generate`` command. +The ``generate`` endpoint run a ``generate`` command. .. code-block:: none diff --git a/docs/changelog/1.3.rst b/docs/changelog/1.3.rst index cf04e5a9..e790813b 100644 --- a/docs/changelog/1.3.rst +++ b/docs/changelog/1.3.rst @@ -8,10 +8,25 @@ _ext/releasenotes.py +2021-08-30 +========== + +* :vytask:`T2558` (feature): Add some CPU information to `show version` + fix broken hypervisor detection + + +2021-08-29 +========== + +* :vytask:`T3708` (bug): isisd and gre-bridge commit error +* :vytask:`T3783` (bug): "set protocols isis spf-delay-ietf" is not working +* :vytask:`T2750` (default): Use m4 as a template processor + + 2021-08-27 ========== * :vytask:`T3182` (bug): Main blocker Task for FRR 7.4/7.5 series update +* :vytask:`T2108` (default): Use minisign/signify instead of GPG for release signing 2021-08-26 @@ -326,7 +341,7 @@ * :vytask:`T3250` (bug): PPPoE server: wrong local usernames * :vytask:`T3138` (bug): ddclient improperly updated when apply rfc2136 config * :vytask:`T2620` (feature): Add ipsec peer-name to log to simplifies grepping and troubleshooting -* :vytask:`T2645` (default): Editing route-map Action Requires New Rule +* :vytask:`T2645` (default): Editing route-map action requires adding a new rule 2021-06-09 @@ -383,7 +398,7 @@ * :vytask:`T3103` (default): Rewrite parts of vyos\frr.py for readability, logging and to fix mulitiline regex "bugs" * :vytask:`T2739` (default): vyos-utils is not compiled with a Jenkins pipeline. * :vytask:`T2451` (bug): Cannot use !tcp or !tcp_udp while adding firewall rule -* :vytask:`T2436` (default): equuleus: Testing: vyos-1x: syntax checking python scripts in PR +* :vytask:`T2436` (default): equuleus: Testing: vyos-1x: syntax checking Python scripts in PR * :vytask:`T2184` (bug): OpenVPN op_mode tools broken * :vytask:`T1944` (bug): FRR: Invalid route in BGP causes update storm, memory leak, and failure of Zebra. * :vytask:`T1995` (bug): "show vpn ike sa" command always show child-sas as down @@ -564,7 +579,7 @@ ========== * :vytask:`T3458` (default): vyos docs missing gretap from tunnel section -* :vytask:`T2946` (bug): call to commandd 'stty_size' cause show interfaces API to fail. +* :vytask:`T2946` (bug): Calling 'stty_size' causes show interfaces API to fail 2021-04-26 @@ -603,7 +618,7 @@ 2021-04-14 ========== -* :vytask:`T3055` (bug): op-mode incorrect naming fo ipsec policy-based tunnels +* :vytask:`T3055` (bug): op-mode incorrect naming for ipsec policy-based tunnels 2021-04-12 @@ -1069,7 +1084,7 @@ 2021-01-09 ========== -* :vytask:`T2467` (bug): Restarting Flow Accounting Fails +* :vytask:`T2467` (bug): Restarting flow accounting fails with systemd error * :vytask:`T3199` (feature): Update Linux Kernel to v5.4.88 / 5.10.6 @@ -1093,7 +1108,7 @@ * :vytask:`T3185` (bug): [conf-mode] Wrong CompletionHelp for Tunnel local-ip * :vytask:`T3152` (bug): wan-load-balance does not show connections -* :vytask:`T2601` (bug): pppoe-server: does not possible to disable ccp +* :vytask:`T2601` (bug): pppoe-server: Cannot disable CCP 2021-01-03 @@ -1119,8 +1134,8 @@ 2020-12-31 ========== -* :vytask:`T3162` (bug): PPPoE server pado-delay issue -* :vytask:`T3160` (bug): PPPoE server called-sid option does not work +* :vytask:`T3162` (bug): Wrong PPPoE server pado-delay parameter added to config +* :vytask:`T3160` (bug): PPPoE server called-sid option defined in wrong section * :vytask:`T3168` (feature): Update Linux Kernel to v5.4.86 @@ -1149,7 +1164,7 @@ 2020-12-23 ========== -* :vytask:`T3143` (bug): OpenVPN server: Push route does not work +* :vytask:`T3143` (bug): OpenVPN server: Push route config format is wrong * :vytask:`T3146` (feature): Upgrade FRR from 7.4 -> 7.5 version incl. new libyang * :vytask:`T3145` (feature): Update Linux Kernel to v5.4.85 * :vytask:`T3147` (feature): Upgrade to SaltStack version 3002.2 @@ -1158,13 +1173,19 @@ 2020-12-22 ========== -* :vytask:`T3142` (bug): OpenVPN op-command completion issue +* :vytask:`T3142` (bug): OpenVPN op-command completion fails due to missing status file * :vytask:`T2940` (feature): Update FRR to 7.4 -* :vytask:`T2573` (bug): BFD opmode Commands are broken +* :vytask:`T2573` (bug): BFD op-mode commands are broken * :vytask:`T2495` (feature): Add xml for ISIS [conf_mode] * :vytask:`T1316` (feature): Support for IS-IS +2020-12-21 +========== + +* :vytask:`T2619` (bug): Bug: Changes in NAT or ZONES from 1.2 to 1.3 + + 2020-12-20 ========== @@ -1224,7 +1245,7 @@ 2020-12-07 ========== -* :vytask:`T3120` (bug): 1.3-rolling-202012070217 python error when deleting nat rule +* :vytask:`T3120` (bug): Python error when deleting nat rule * :vytask:`T3119` (feature): migrate "system ip" to get_config_dict() and provide smoketest @@ -1237,7 +1258,7 @@ 2020-12-04 ========== -* :vytask:`T3108` (bug): Section Config overlapped match with FRRConfig +* :vytask:`T3108` (bug): Section config overlapped match with FRRConfig * :vytask:`T3112` (feature): PPPoE IPv6: remove "enable" node * :vytask:`T3100` (feature): Migrate DHCP/DHCPv6 server to get_config_dict() @@ -1309,7 +1330,7 @@ * :vytask:`T2153` (bug): traceroute circular reference * :vytask:`T3081` (bug): get_config_dict() does not honor whitespaces in the CLI values field * :vytask:`T3080` (bug): OpenVPN failing silently for a number of reasons in rolling post Nov/02 -* :vytask:`T3074` (bug): openvpn site-to-site dosn't work +* :vytask:`T3074` (bug): OpenVPN site-to-site creates wrong peer address * :vytask:`T2542` (bug): OpenVPN client tap interfaces not coming up * :vytask:`T3084` (bug): wifi: TypeError on "show interfaces wireless info" @@ -1318,7 +1339,7 @@ ========== * :vytask:`T3079` (bug): Fix the problem that VLAN 1 will be deleted in VLAN-aware bridge -* :vytask:`T3060` (bug): OpenVPN not working in vyos-1.3-rolling-20201101 and after +* :vytask:`T3060` (bug): OpenVPN virtual interface not coming up after upgrade 2020-11-20 @@ -1349,7 +1370,7 @@ 2020-11-15 ========== -* :vytask:`T3069` (bug): openvpn - routed networks not available +* :vytask:`T3069` (bug): OpenVPN routed networks not available * :vytask:`T3038` (feature): Supporting AZERTY keyboards * :vytask:`T2993` (bug): op-mode: lldp: show lldp neighbors - AttributeError: 'str' object has no attribute 'items' * :vytask:`T2564` (enhancment): Extend VyOS to support appliance LCDs @@ -1415,7 +1436,7 @@ * :vytask:`T3043` (feature): Wireless: Refactor CLI * :vytask:`T3034` (feature): Add WiFi WPA 3 support -* :vytask:`T2967` (bug): Duplicate IPv6 BFD Peers Created +* :vytask:`T2967` (bug): Duplicate IPv6 BFD peers created * :vytask:`T2483` (bug): DHCP most likely not restarting pdns_recursor @@ -1485,7 +1506,7 @@ 2020-10-22 ========== -* :vytask:`T2978` (bug): IPoE service does not work on shared mode. +* :vytask:`T2978` (bug): IPoE service does not work on shared mode * :vytask:`T2906` (bug): OpenVPN: tls-auth missing key direction @@ -1493,14 +1514,14 @@ ========== * :vytask:`T2828` (bug): BGP conf_mode error enforce-first-as -* :vytask:`T2749` (bug): Setting ethx configuration issue. +* :vytask:`T2749` (bug): Setting ethx configuration takes a long time * :vytask:`T2138` (default): Can't load archived configs as they are gzipped 2020-10-20 ========== -* :vytask:`T2987` (bug): VxLAN not working properly after upgrading to latest October build (also with newinstallation) +* :vytask:`T2987` (bug): VxLAN not working properly after upgrading to latest October build and with a new installation * :vytask:`T2989` (default): MPLS documentation expansion @@ -1547,7 +1568,7 @@ 2020-10-12 ========== -* :vytask:`T2951` (bug): monitor nat not working +* :vytask:`T2951` (bug): Cannot enable logging for monitor nat * :vytask:`T2782` (bug): Changing timezone, does not restart rsyslog @@ -1566,7 +1587,7 @@ 2020-10-06 ========== -* :vytask:`T2957` (bug): show openvpn not returning anything +* :vytask:`T2957` (bug): show openvpn not printing anything 2020-10-05 @@ -1599,7 +1620,7 @@ 2020-10-01 ========== -* :vytask:`T2945` (bug): Interface removed from BRIDGE on setting changed +* :vytask:`T2945` (bug): Interface removed from bridge on setting change * :vytask:`T2948` (bug): NAT: OSError when configuring translation address range * :vytask:`T2936` (feature): Migrate PPPoE server to get_config_dict() do reduce boilerplate code @@ -1697,7 +1718,7 @@ 2020-09-14 ========== -* :vytask:`T2872` (bug): "Show log" for nat and openvpn got inter-mixed +* :vytask:`T2872` (bug): "Show log" for nat and openvpn got intermixed * :vytask:`T2301` (bug): Delete PBR vyatta_policy_ref * :vytask:`T2880` (feature): Update Linux Kernel to v4.19.145 * :vytask:`T2879` (feature): Cleanup 4.19.144 kernel configuration @@ -1749,7 +1770,7 @@ 2020-09-02 ========== -* :vytask:`T2833` (bug): vyos 1.3-rolling-202008200357 RIP outgoing update filter list no longer operational +* :vytask:`T2833` (bug): RIP outgoing update filter list no longer operational * :vytask:`T2849` (bug): vyos.xml.defaults should return a list on multi nodes, by default @@ -1811,7 +1832,7 @@ 2020-08-23 ========== -* :vytask:`T2811` (bug): Does not possible to delete vpn anyconnect +* :vytask:`T2811` (bug): Cannot delete vpn anyconnect * :vytask:`T2823` (bug): VXLAN has state A/D after configuration * :vytask:`T2812` (default): Add basic smoketest for anyconnect @@ -1961,7 +1982,7 @@ 2020-07-27 ========== -* :vytask:`T2729` (feature): Pseudo-ethernet replace fail message. +* :vytask:`T2729` (feature): Pseudo-ethernet replace fail message * :vytask:`T1249` (feature): multiply PBR rules can set to a single interface * :vytask:`T1956` (feature): PPPoE server: support PADO-delay * :vytask:`T1295` (feature): FRR: update documentation @@ -1977,7 +1998,7 @@ * :vytask:`T2734` (feature): WireGuard: fwmark CLI definition is inconsistent * :vytask:`T2733` (feature): Support MTU configuration on pseudo ethernet devices -* :vytask:`T2644` (default): Disabling Bonded Interfaces Broken +* :vytask:`T2644` (default): Bonding interfaces cannot be disabled * :vytask:`T2476` (bug): Bond member description change leads to network outage * :vytask:`T2443` (feature): NHRP: Add debugging information to syslog * :vytask:`T2021` (bug): OSPFv3 doesn't support decimal area syntax @@ -2027,10 +2048,10 @@ 2020-07-22 ========== -* :vytask:`T2718` (bug): ntp.conf updated incorrectly. +* :vytask:`T2718` (bug): ntp.conf updated incorrectly * :vytask:`T2658` (bug): Interface description comment display error -* :vytask:`T2643` (bug): Show Interface Command Issues -* :vytask:`T2725` (bug): Recent 1.3 rolling (since May) fail to load config if user has no password - KeyError: 'password_encrypted' +* :vytask:`T2643` (bug): show interfaces does not scale with terminal width +* :vytask:`T2725` (bug): Config fails to load if user has no password * :vytask:`T2707` (default): Allow alternative initialization data for Config @@ -2098,7 +2119,7 @@ 2020-07-06 ========== -* :vytask:`T2680` (bug): Dhcp6c service can not recover when it fails. +* :vytask:`T2680` (bug): dhcp6c service cannot recover when it fails 2020-07-05 @@ -2150,9 +2171,9 @@ 2020-06-26 ========== -* :vytask:`T2642` (bug): sshd Broken on Latest Rolling Release +* :vytask:`T2642` (bug): sshd fails to start due to configuration error * :vytask:`T2588` (default): Add support for default values to the interface-definition format -* :vytask:`T2622` (bug): An issue with config migration (interface pseudo ethernet) +* :vytask:`T2622` (bug): Pseudo-ethernet interface config disappears across versions * :vytask:`T2057` (feature): Generalised Interface configuration * :vytask:`T2625` (feature): Provide generic Library for package builds @@ -2184,7 +2205,7 @@ 2020-06-23 ========== -* :vytask:`T2632` (bug): WireGuard: Can not use only one preshared-key for one peer +* :vytask:`T2632` (bug): WireGuard: Cannot use only one preshared-key for one peer * :vytask:`T1829` (bug): Install Image script does not respect size of partition greater than 2G but less than disk size * :vytask:`T2635` (feature): SSH: migrate to get_config_dict() @@ -2281,8 +2302,8 @@ ========== * :vytask:`T2575` (bug): pppoe-server: does not possibly assign IP address -* :vytask:`T2565` (bug): Does not possible connect to l2tp server with radius auth -* :vytask:`T2553` (bug): Regression: set interface ethN vif-s nnnn does not commit on 1.3-rolling-202006050621 +* :vytask:`T2565` (bug): Cannot connect to l2tp server with radius auth +* :vytask:`T2553` (bug): set interface ethN vif-s nnnn does not commit 2020-06-08 @@ -2368,7 +2389,7 @@ 2020-05-26 ========== -* :vytask:`T2520` (bug): Show conntrack fail +* :vytask:`T2520` (bug): show conntrack fails with Perl error * :vytask:`T2502` (bug): PPPoE default route not installed for IPv6 when "default-route auto" * :vytask:`T2458` (feature): Update FRR to 7.3.1 * :vytask:`T2506` (feature): DHCPv6-PD add prefix hint CLI option diff --git a/docs/changelog/1.4.rst b/docs/changelog/1.4.rst index 87e6de41..57ca2fdb 100644 --- a/docs/changelog/1.4.rst +++ b/docs/changelog/1.4.rst @@ -8,10 +8,26 @@ _ext/releasenotes.py +2021-08-29 +========== + +* :vytask:`T3708` (bug): isisd and gre-bridge commit error +* :vytask:`T3783` (bug): "set protocols isis spf-delay-ietf" is not working +* :vytask:`T2750` (default): Use m4 as a template processor + + +2021-08-28 +========== + +* :vytask:`T3743` (bug): l2tp doesn't work after reboot if outside-address not 0.0.0.0 + + 2021-08-27 ========== * :vytask:`T3182` (bug): Main blocker Task for FRR 7.4/7.5 series update +* :vytask:`T3568` (feature): Add XML for firewall conf-mode +* :vytask:`T2108` (default): Use minisign/signify instead of GPG for release signing 2021-08-26 @@ -325,7 +341,7 @@ * :vytask:`T3250` (bug): PPPoE server: wrong local usernames * :vytask:`T3138` (bug): ddclient improperly updated when apply rfc2136 config * :vytask:`T2620` (feature): Add ipsec peer-name to log to simplifies grepping and troubleshooting -* :vytask:`T2645` (default): Editing route-map Action Requires New Rule +* :vytask:`T2645` (default): Editing route-map action requires adding a new rule 2021-06-08 @@ -576,7 +592,7 @@ ========== * :vytask:`T3458` (default): vyos docs missing gretap from tunnel section -* :vytask:`T2946` (bug): call to commandd 'stty_size' cause show interfaces API to fail. +* :vytask:`T2946` (bug): Calling 'stty_size' causes show interfaces API to fail 2021-04-26 @@ -639,7 +655,7 @@ ========== * :vytask:`T3398` (bug): Can't commit -* :vytask:`T3055` (bug): op-mode incorrect naming fo ipsec policy-based tunnels +* :vytask:`T3055` (bug): op-mode incorrect naming for ipsec policy-based tunnels 2021-04-13 diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 1f1e2aa9..c44fffd9 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -4,7 +4,7 @@ HTTP-API ######## -VyOS provide a HTTP API. You can use it to execute op-mode commands, +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. @@ -15,7 +15,7 @@ Configuration .. cfgcmd:: set service https api keys id <name> key <apikey> - Set an named api key, every key have the same, full permissions + Set a named api key. Every key has the same, full permissions on the system. .. cfgcmd:: set service https api debug @@ -25,7 +25,7 @@ Configuration .. cfgcmd:: set service https api port - Set the listen port of the local API, this have non effect of the + Set the listen port of the local API, this has no effect on the webserver. The default is port 8080 .. cfgcmd:: set service https api strict @@ -42,11 +42,11 @@ Configuration .. cfgcmd:: set service https virtual-host <vhost> server-name <text> - Server names for virtual hosts it ca be exact, wildcard or regex. + Server names for virtual hosts it can be exact, wildcard or regex. .. cfgcmd:: set service https api-restrict virtual-host <vhost> - Nginx exposes the local API on all virtual servers, by default + By default, nginx exposes the local API on all virtual servers. Use this to restrict nginx to one or more virtual hosts. .. cfgcmd:: set service https certificates certbot domain-name <text> @@ -78,7 +78,7 @@ Set an API-KEY is the minimal configuration to get a working API Endpoint. set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY -To use this full configuration we asume a publice accessable hostname. +To use this full configuration we asume a public accessible hostname. .. code-block:: none @@ -88,4 +88,4 @@ To use this full configuration we asume a publice accessable hostname. 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 + set service https api-restrict virtual-host rtr01.example.com diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index 36dc1787..d4b340c1 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -129,7 +129,7 @@ sent in clear text between a manager and agent. Each SNMPv3 message contains security parameters which are encoded as an octet string. The meaning of these security parameters depends on the security model being used. -The securityapproach in v3 targets: +The security approach in SNMPv3 targets: * Confidentiality – Encryption of packets to prevent snooping by an unauthorized source. @@ -163,7 +163,7 @@ Example set service snmp v3 view default oid 1 After commit the plaintext passwords will be hashed and stored in your -configuration. The resulting LCI config will look like: +configuration. The resulting CLI config will look like: .. code-block:: none diff --git a/docs/debugging.rst b/docs/debugging.rst index fec73257..5a25639d 100644 --- a/docs/debugging.rst +++ b/docs/debugging.rst @@ -29,6 +29,11 @@ Kernel an unexpected delay during manual or boot commit, this may be useful in identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``. + + In addition this setting creates the runtime debug files for some Live system + components (see below). Those files are: ``/tmp/vyos-config-status``, + ``/tmp/vyos.container.debug``, ``/tmp/vyos.frr.debug``, + ``/tmp/vyos.ifconfig.debug``. * ``vyos-config-debug`` - During development, coding errors can lead to a commit failure on boot, possibly resulting in a failed initialization of the diff --git a/docs/installation/install.rst b/docs/installation/install.rst index 7b96511a..7cd582f4 100644 --- a/docs/installation/install.rst +++ b/docs/installation/install.rst @@ -177,6 +177,59 @@ Finally, verify the authenticity of the downloaded image: gpg: Good signature from "VyOS Maintainers (VyOS Release) <maintainers@vyos.net>" [unknown] Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E +.. _minisign-verification: + +Minisign verification +^^^^^^^^^^^^^^^^^^^^^ + +Currently we are using GPG for release signing (pretty much like everyone else). + +Popularity of GPG for release signing comes from the fact that many people +already had it installed for email encryption/signing. Inside a VyOS image, +signature checking is the only reason to have it installed. However, it still +comes with all the features no one needs, such as support for multiple outdated +cipher suits and ability to embed a photo in the key file. More importantly, +web of trust, the basic premise of PGP, is never used in release signing +context. Once you have a knowingly authentic image, authenticity of upgrades is +checked using a key that comes in the image, and to get their first image people +never rely on keyservers either. + +Another point is that we are using RSA now, which requires absurdly large keys +to be secure. + +In 2015, OpenBSD introduced signify. An alternative implementation of the same +protocol is minisign, which is also available for Windows and macOS, and in most +GNU/Linux distros it's in the repositories now. + +Its installed size (complete with libsodium) is less than that of GPG binary +alone (not including libgcrypt and some other libs, which I think we only use +for GPG). Since it uses elliptic curves, it gets away with much smaller keys, +and it doesn't include as much metadata to begin with. + +Another issue of GPG is that it creates a /root/.gnupg directory just for +release checking. The dir is small so the fact that it's never used again is +an aesthetic problem, but we've had that process fail in the past. But, small +key size of the Ed25519 algorithm allows passing public keys in command line +arguments, so verification process can be completely stateless: + +:vytask:`T2180` switched the validation system to prefer minisign over GPG keys. + +To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: + +.. code-block:: none + + $ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig + Signature and comment signature verified + Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso + +During an image upgrade VyOS performas the following command: + +.. code-block:: none + + $ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig + Signature and comment signature verified + Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso + .. _live_installation: Live installation @@ -460,7 +513,7 @@ extracted contents of the ISO file. so that it shows the correct URL at ``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. -.. note:: Do not change the name of the *filesystem.squashfs* file. If +.. note:: Do not change the name of the *filesystem.squashfs* file. If you are working with different versions, you can create different directories instead. |