Skip to content

Networking

Setting any forwarded ports in the ports section, or using the (default) ssh-portfwd option, will add a usermode network connection to the VM.

If you explicitly do not want a usermode connection in your VM, you will need to:

  • ensure you have no ports section
  • change the SSH mode to either 'vsock' or 'direct' (see below)
  • define your own network configuration as per virt-install's documentation for the --network option (i.e. in the machine section).

With no network configuration set, a usermode network will be added by default, so if you explicitly want no network interfaces at all, you'll need to set network: none in the machine section.

Port forwarding

The syntax for the ports section is very similar to that of Podman or Docker. These lines are used to generate passt port-forwarding rules, passed to virt-install. Per the virt-install manual for the network option (see portForward=), the syntax is:

  • [ADDRESS:]HOSTPORT[:GUESTPORT][/PROTO]

Example port forwarding rules

ports:
  - 127.0.0.1:8080:80  # forward local-only port 8080 to the guest's port 80
  - 9000-9100/tcp      # forward all ports in the range 7000 through 8000 to the guest

SSH Communication Options

By default, SSH communications works by adding a local-only port forwarding rule, similar to above. A random local-only IP is chosen in the 127.21.x.x loopback range, and port 2222 is forwarded from that IP to port 22 in the guest.

This was chosen as the default because it works with usermode networking and has broad compatibility for guests, but other options are available using an ssh section in the virtfile:

Example

ssh:
  type: portfwd
  1. portfwd - This is the default (as above), available as a flag if you want to define it explicitly.
  2. vsock - SSH over VSOCK, works well if systemd v256+ is on the guest, but otherwise may require a bit of configuration (see libvirt documentation)
  3. direct - SSH over routed network link - use this if neither of the above suit your needs. In this case, the guest IP is determined from ARP. You will need to configure the machine with a non-usermode network for this to work.

SSH as a non-root user

Example

ssh:
  user: fred

If you want to use SSH as a non-root user, you can define the user as above. The user must be created before or within the customize step, as an SSH key will be injected for this user.

Assigning the desired privileges for this user (administrative groups, passwords etc) is left as an exercise for the reader.

Getting SSH Details

If you want to script your own SSH commands, or run scp or rsync etc, you can get the connection info by running nvirt sshinfo:

Output from running nvirt sshinfo
{
  "dest": "ssh://alice@127.21.221.26:2222",
  "identity": "/home/user/my-project/.nvirt/ssh/default"
}