From dcceeb9868245a792622c7fb4157bf676677c497 Mon Sep 17 00:00:00 2001 From: Niklas Hambüchen Date: Fri, 10 Nov 2023 18:46:54 +0100 Subject: manual: tests: Describe how to port-forward into test VMs --- .../running-nixos-tests-interactively.section.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'nixos/doc/manual/development/running-nixos-tests-interactively.section.md') diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md index 54002941d63..a816213f37d 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -57,6 +57,22 @@ using: Once the connection is established, you can enter commands in the socat terminal where socat is running. +## Port forwarding to NixOS test VMs {#sec-nixos-test-port-forwarding} + +If your test has only a single VM, you may use e.g. + +```ShellSession +$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-127.0.0.1:22" ./result/bin/nixos-test-driver +``` + +to port-forward a port in the VM (here `22`) to the host machine (here port `2222`). + +This naturally does not work when multiple machines are involved, +since a single port on the host cannot forward to multiple VMs. + +If the test defines multiple machines, you may opt to _temporarily_ set +`virtualisation.forwardPorts` in the test definition for debugging. + ## Reuse VM state {#sec-nixos-test-reuse-vm-state} You can re-use the VM states coming from a previous run by setting the -- cgit 1.4.1 From f9611764c699fe98ad45996f3c87b9bdd14db716 Mon Sep 17 00:00:00 2001 From: Niklas Hambüchen Date: Sat, 11 Nov 2023 01:22:13 +0100 Subject: manual: Fix QEMU_NET_OPTS VM-side address. In my earlier commit manual: Don't suggest exposing VM port to local network. I made a side change titled Use `127.0.0.1` also on the VM side, otherwise connections to services that, in the VM, bind to `127.0.0.1` only (doing the safe approach) do not work. Unfortunately, that was wrong: QEMU inside the VM always communicates via the virtualised Ethernet interface, not via the VM's loopback interface. So trying to connect to `127.0.0.1` on the VM's side cannot work. --- .../development/running-nixos-tests-interactively.section.md | 7 ++++++- nixos/doc/manual/installation/changing-config.chapter.md | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) (limited to 'nixos/doc/manual/development/running-nixos-tests-interactively.section.md') diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md index a816213f37d..4b8385d7e0d 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -62,7 +62,7 @@ where socat is running. If your test has only a single VM, you may use e.g. ```ShellSession -$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-127.0.0.1:22" ./result/bin/nixos-test-driver +$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-:22" ./result/bin/nixos-test-driver ``` to port-forward a port in the VM (here `22`) to the host machine (here port `2222`). @@ -73,6 +73,11 @@ since a single port on the host cannot forward to multiple VMs. If the test defines multiple machines, you may opt to _temporarily_ set `virtualisation.forwardPorts` in the test definition for debugging. +Such port forwardings connect via the VM's virtual network interface. +Thus they cannot connect to ports that are only bound to the VM's +loopback interface (`127.0.0.1`), and the VM's NixOS firewall +must be configured to allow these connections. + ## Reuse VM state {#sec-nixos-test-reuse-vm-state} You can re-use the VM states coming from a previous run by setting the diff --git a/nixos/doc/manual/installation/changing-config.chapter.md b/nixos/doc/manual/installation/changing-config.chapter.md index f2ffea9088a..12abf90b718 100644 --- a/nixos/doc/manual/installation/changing-config.chapter.md +++ b/nixos/doc/manual/installation/changing-config.chapter.md @@ -89,7 +89,7 @@ guest. For instance, the following will forward host port 2222 to guest port 22 (SSH): ```ShellSession -$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-127.0.0.1:22" ./result/bin/run-*-vm +$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-:22" ./result/bin/run-*-vm ``` allowing you to log in via SSH (assuming you have set the appropriate @@ -98,3 +98,8 @@ passwords or SSH authorized keys): ```ShellSession $ ssh -p 2222 localhost ``` + +Such port forwardings connect via the VM's virtual network interface. +Thus they cannot connect to ports that are only bound to the VM's +loopback interface (`127.0.0.1`), and the VM's NixOS firewall +must be configured to allow these connections. -- cgit 1.4.1