From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/md-quick-start.md | 381 ------------------------------------------------- 1 file changed, 381 deletions(-) delete mode 100644 docs/md-quick-start.md (limited to 'docs/md-quick-start.md') diff --git a/docs/md-quick-start.md b/docs/md-quick-start.md deleted file mode 100644 index 9d1a6eee..00000000 --- a/docs/md-quick-start.md +++ /dev/null @@ -1,381 +0,0 @@ -(quick-start)= - -# Quick Start - -This chapter will guide you on how to get up to speed quickly using your new -VyOS system. It will show you a very basic configuration example that will -provide a {ref}`nat` gateway for a device with two network interfaces -(`eth0` and `eth1`). - -(quick-start-configuration-mode)= - -## Configuration Mode - -By default, VyOS is in operational mode, and the command prompt displays -a `$`. To configure VyOS, you will need to enter configuration mode, resulting -in the command prompt displaying a `#`, as demonstrated below: - -```none -vyos@vyos$ configure -vyos@vyos# -``` - - -## Commit and Save - -After every configuration change, you need to apply the changes by using the -following command: - -```none -commit -``` - -Once your configuration works as expected, you can save it permanently by using -the following command: - -```none -save -``` - - -## Interface Configuration - -- Your outside/WAN interface will be `eth0`. It will receive its interface - address via DHCP. -- Your internal/LAN interface will be `eth1`. It will use a static IP address - of `192.168.0.1/24`. - -After switching to {ref}`quick-start-configuration-mode` issue the following -commands: - -```none -set interfaces ethernet eth0 address dhcp -set interfaces ethernet eth0 description 'OUTSIDE' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth1 description 'LAN' -``` - - -## SSH Management - -After switching to {ref}`quick-start-configuration-mode` issue the following -commands, and your system will listen on every interface for incoming SSH -connections. You might want to check the {ref}`ssh` chapter on how to listen -on specific addresses only. - -```none -set service ssh port '22' -``` - -(dhcp-dns-quick-start)= - -## DHCP/DNS quick-start - -The following settings will configure DHCP and DNS services on -your internal/LAN network, where VyOS will act as the default gateway and -DNS server. - -- The default gateway and DNS recursor address will be `192.168.0.1/24` -- The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for - static assignments -- DHCP clients will be assigned IP addresses within the range of - `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` -- DHCP leases will hold for one day (86400 seconds) -- VyOS will serve as a full DNS recursor, replacing the need to utilize Google, - Cloudflare, or other public DNS servers (which is good for privacy) -- Only hosts from your internal/LAN network can use the DNS recursor - -```none -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option default-router '192.168.0.1' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option name-server '192.168.0.1' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option domain-name 'vyos.net' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 subnet-id '1' - -set service dns forwarding cache-size '0' -set service dns forwarding listen-address '192.168.0.1' -set service dns forwarding allow-from '192.168.0.0/24' -``` - - -## NAT - -The following settings will configure {ref}`source-nat` rules for our -internal/LAN network, allowing hosts to communicate through the outside/WAN -network via IP masquerade. - -```none -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.168.0.0/24' -set nat source rule 100 translation address masquerade -``` - - -## Firewall - -A new firewall structure—which uses the `nftables` backend, rather -than `iptables`—is available on all installations starting from -VyOS `1.4-rolling-202308040557`. The firewall supports creation of distinct, -interlinked chains for each [Netfilter hook]() -and allows for more granular control over the packet filtering process. - -The firewall begins with the base `filter` tables you define for each of the -`forward`, `input`, and `output` Netfiter hooks. Each of these tables is -populated with rules that are processed in order and can jump to other chains -for more granular filtering. - -### Configure Firewall Groups - -To make firewall configuration easier, we can create groups of interfaces, -networks, addresses, ports, and domains that describe different parts of -our network. We can then use them for filtering within our firewall rulesets, -allowing for more concise and readable configuration. - -In this case, we will create two interface groups — a `WAN` group for our -interfaces connected to the public internet and a `LAN` group for the -interfaces connected to our internal network. Additionally, we will create a -network group, `NET-INSIDE-v4`, that contains our internal subnet. - -```none -set firewall group interface-group WAN interface eth0 -set firewall group interface-group LAN interface eth1 -set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24' -``` - - -### Configure Stateful Packet Filtering - -With the new firewall structure, we have have a lot of flexibility in how we -group and order our rules, as shown by the three alternative approaches below. - -#### Option 1: Global State Policies - -Using options defined in `set firewall global-options state-policy`, state -policy rules that applies for both IPv4 and IPv6 are created. These global -state policies also applies for all traffic that passes through the router -(transit) and for traffic originated/destinated to/from the router itself, and -will be evaluated before any other rule defined in the firewall. - -Most installations would choose this option, and will contain: - -```none -set firewall global-options state-policy established action accept -set firewall global-options state-policy related action accept -set firewall global-options state-policy invalid action drop -``` - - -#### Option 2: Common/Custom Chain - -We can create a common chain for stateful connection filtering of multiple -interfaces (or multiple netfilter hooks on one interface). Those individual -chains can then jump to the common chain for stateful connection filtering, -returning to the original chain for further rule processing if no action is -taken on the packet. - -The chain we will create is called `CONN_FILTER` and has three rules: - -- A default action of `return`, which returns the packet back to the original - chain if no action is taken. -- A rule to `accept` packets from established and related connections. -- A rule to `drop` packets from invalid connections. - -```none -set firewall ipv4 name CONN_FILTER default-action 'return' - -set firewall ipv4 name CONN_FILTER rule 10 action 'accept' -set firewall ipv4 name CONN_FILTER rule 10 state established -set firewall ipv4 name CONN_FILTER rule 10 state related - -set firewall ipv4 name CONN_FILTER rule 20 action 'drop' -set firewall ipv4 name CONN_FILTER rule 20 state invalid -``` - -Then, we can jump to the common chain from both the `forward` and `input` -hooks as the first filtering rule in the respective chains: - -```none -set firewall ipv4 forward filter rule 10 action 'jump' -set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER - -set firewall ipv4 input filter rule 10 action 'jump' -set firewall ipv4 input filter rule 10 jump-target CONN_FILTER -``` - - -#### Option 3: Per-Hook Chain - -Alternatively, you can take the more traditional stateful connection -filtering approach by creating rules on each base hook's chain: - -```none -set firewall ipv4 forward filter rule 5 action 'accept' -set firewall ipv4 forward filter rule 5 state established -set firewall ipv4 forward filter rule 5 state related -set firewall ipv4 forward filter rule 10 action 'drop' -set firewall ipv4 forward filter rule 10 state invalid - -set firewall ipv4 input filter rule 5 action 'accept' -set firewall ipv4 input filter rule 5 state established -set firewall ipv4 input filter rule 5 state related -set firewall ipv4 input filter rule 10 action 'drop' -set firewall ipv4 input filter rule 10 state invalid -``` - - -### Block Incoming Traffic - -Now that we have configured stateful connection filtering to allow traffic from -established and related connections, we can block all other incoming traffic -addressed to our local network. - -Create a new chain (`OUTSIDE-IN`) which will drop all traffic that is not -explicitly allowed at some point in the chain. Then, we can jump to that chain -from the `forward` hook when traffic is coming from the `WAN` interface -group and is addressed to our local network. - -```none -set firewall ipv4 name OUTSIDE-IN default-action 'drop' - -set firewall ipv4 forward filter rule 100 action jump -set firewall ipv4 forward filter rule 100 jump-target OUTSIDE-IN -set firewall ipv4 forward filter rule 100 inbound-interface group WAN -set firewall ipv4 forward filter rule 100 destination group network-group NET-INSIDE-v4 -``` - -We should also block all traffic destinated to the router itself that isn't -explicitly allowed at some point in the chain for the `input` hook. As -we've already configured stateful packet filtering above, we only need to -set the default action to `drop`: - -```none -set firewall ipv4 input filter default-action 'drop' -``` - - -### Allow Management Access - -We can now configure access to the router itself, allowing SSH -access from the inside/LAN network and rate limiting SSH access from the -outside/WAN network. - -First, create a new dedicated chain (`VyOS_MANAGEMENT`) for management -access, which returns to the parent chain if no action is taken. Add a rule -to accept traffic from the `LAN` interface group: - -```none -set firewall ipv4 name VyOS_MANAGEMENT default-action 'return' -``` - -Configure a rule on the `input` hook filter to jump to the `VyOS_MANAGEMENT` -chain when new connections are addressed to port 22 (SSH) on the router itself: - -```none -set firewall ipv4 input filter rule 20 action jump -set firewall ipv4 input filter rule 20 jump-target VyOS_MANAGEMENT -set firewall ipv4 input filter rule 20 destination port 22 -set firewall ipv4 input filter rule 20 protocol tcp -``` - -Finally, configure the `VyOS_MANAGEMENT` chain to accept connection from the -`LAN` interface group while limiting requests coming from the `WAN` -interface group to 4 per minute: - -```none -set firewall ipv4 name VyOS_MANAGEMENT rule 15 action 'accept' -set firewall ipv4 name VyOS_MANAGEMENT rule 15 inbound-interface group 'LAN' - -set firewall ipv4 name VyOS_MANAGEMENT rule 20 action 'drop' -set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent count 4 -set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent time minute -set firewall ipv4 name VyOS_MANAGEMENT rule 20 state new -set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface group 'WAN' - -set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept' -set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new -set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface group 'WAN' -``` - - -### Allow Access to Services - -Here we're allowing the router to respond to pings. Then, we can allow access to -the DNS recursor we configured earlier, accepting traffic bound for port 53 from -all hosts on the `NET-INSIDE-v4` network: - -```none -set firewall ipv4 input filter rule 30 action 'accept' -set firewall ipv4 input filter rule 30 icmp type-name 'echo-request' -set firewall ipv4 input filter rule 30 protocol 'icmp' -set firewall ipv4 input filter rule 30 state new - -set firewall ipv4 input filter rule 40 action 'accept' -set firewall ipv4 input filter rule 40 destination port '53' -set firewall ipv4 input filter rule 40 protocol 'tcp_udp' -set firewall ipv4 input filter rule 40 source group network-group NET-INSIDE-v4 -``` - -Finally, we can now configure access to the services running on this router, -allowing all connections coming from localhost: - -```none -set firewall ipv4 input filter rule 50 action 'accept' -set firewall ipv4 input filter rule 50 source address 127.0.0.0/8 -``` - -Commit changes, save the configuration, and exit configuration mode: - -```none -vyos@vyos# commit -vyos@vyos# save -Saving configuration to '/config/config.boot'... -Done -vyos@vyos# exit -vyos@vyos$ -``` - - -## Hardening - -Especially if you are allowing SSH remote access from the outside/WAN -interface, there are a few additional configuration steps that should be taken. - -Replace the default `vyos` system user: - -```none -set system login user myvyosuser authentication plaintext-password mysecurepassword -``` - -Set up {ref}`ssh_key_based_authentication`: - -```none -set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa -set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub -``` - -Finally, try and SSH into the VyOS install as your new user. Once you have -confirmed that your new user can access your router without a password, delete -the original `vyos` user and completely disable password authentication for -{ref}`ssh`: - -```none -delete system login user vyos -set service ssh disable-password-authentication -``` - -As above, commit your changes, save the configuration, and exit -configuration mode: - -```none -vyos@vyos# commit -vyos@vyos# save -Saving configuration to '/config/config.boot'... -Done -vyos@vyos# exit -vyos@vyos$ -``` - -You now should have a simple yet secure and functioning router to experiment -with further. Enjoy! -- cgit v1.2.3