Using KVM on Peplink with a Mac

This guide explains how to manage a KVM/QEMU virtualization host on your Peplink network from a Mac, using virt-manager over a TCP connection with SASL authentication.

Homebrew's build of libvirt (which virt-manager relies on) ships without SASL support, so a standard install cannot connect to a SASL-protected host over TCP. The steps below add that support and complete the connection.

Prerequisites

• A KVM/QEMU host (e.g. a Peplink KVM-capable router) with libvirt configured for TCP + SASL authentication, and a SASL user created for you. Confirm this works locally on the host with:

  sudo virsh -c qemu+tcp://127.0.0.1/system list --all

  It should prompt for a username and password and return the VM list.

  Important: TCP + SASL is the default connection mechanism when using the Peplink KVM environment. You can configure TLS as an option, but there are no configuration items to complete on the Peplink device to enable TCP + SASL.
   

• A Mac with Homebrew and virt-manager installed (brew install virt-manager).
• Network access from the Mac to the host on TCP port 16509. If you reach the host across a site-to-site link, routing that traffic through a SpeedFusion tunnel is recommended — the tunnel encrypts it in transit, which offsets the lack of encryption at the libvirt layer.

Step 1 — Check whether your Mac's libvirt has SASL

otool -L /opt/homebrew/opt/libvirt/lib/libvirt.dylib | grep -i sasl

• No output → SASL is missing. Continue to Step 2.
• Shows libsasl2 → SASL is already present. Skip to Step 4.

Step 2 — Install cyrus-sasl

brew install cyrus-sasl

This package is "keg-only" (not linked into your PATH), which is why libvirt does not find it on its own. That is corrected in the next step.

Step 3 — Rebuild libvirt with SASL support

Add cyrus-sasl as a dependency of the libvirt formula and rebuild from source:

export HOMEBREW_NO_INSTALL_FROM_API=1
brew edit libvirt

In the editor that opens:

1. Find the depends_on list (it already contains gnutls, libssh2, and others) and add a line:

   depends_on "cyrus-sasl"

2. Find the meson arguments list inside def install (the %w[...] block of -D flags) and add:

   "-Dsasl=enabled",

Save and close the editor, then rebuild (this compiles from source and takes several minutes):

brew reinstall --build-from-source libvirt

When it finishes, verify SASL is now linked in:

otool -L /opt/homebrew/opt/libvirt/lib/libvirt.dylib | grep -i sasl

You should see a line referencing libsasl2. If so, the client can now use SASL.

Step 4 — Create the client SASL configuration

Tell the libvirt client which authentication mechanism to use:

mkdir -p /opt/homebrew/etc/sasl2
cat > /opt/homebrew/etc/sasl2/libvirt.conf <<'EOF'
mech_list: scram-sha-256
EOF

This mechanism must match one offered by the host.

Step 5 — Connect

Test from the command line first (it gives the clearest error messages). Replace the IP with your host's address:

virsh -c qemu+tcp://your-username@192.168.50.1/system list --all

You will be prompted:

Please enter your authentication name: your-username
Please enter your password:

Enter your username without any @hostname suffix — SASL adds the realm automatically. A successful connection returns the list of virtual machines (an empty list is fine).

Once the command-line test works, open virt-manager and add the connection:

• File → Add Connection
• Hypervisor: Custom URL
• Enter the host's hostname or IP address
  Format: qemu+tcp://[webadminusername]@[peplinkadminIP]/system
  qemu+tcp://192.168.50.1/system
• Click Connect

• When prompted, enter your SASL username and password

virt-manager will now connect and display the host's virtual machines. The connection URI is .

When to use TLS instead

Because TCP + SASL does not encrypt the management stream, switch to TLS (qemu+tls://, port 16514) whenever the connection leaves a trusted network — for example, managing a host at a remote site over the internet or a cellular WAN. Homebrew's libvirt already includes TLS support, so no rebuild is needed on the Mac; the additional work is generating and installing certificates on the host and client. TLS provides the stream encryption that this method does not.

Troubleshooting

Note: the edited libvirt formula is a local change. A future brew update may flag it as modified; you may need to re-apply the edit if an upgrade reverts SASL support.