VIRTPROXYD(8)

📦
version 12.8.0 · 8 versions
, in centos-stream 10

💅 VIRTPROXYD(8) — the libvirt proxy daemon, explained bestie to bestie

okay so welcome to section 8 of the manual, the daemon zone ✨ this whole page is about virtproxyd, and yes she's from the Virtualization Support fam. buckle up 🎀

✨ NAME ✨

virtproxyd — the libvirt proxy daemon, aka the friend who forwards your messages 💌

🌸 SYNOPSIS 🌸

virtproxyd [OPTION]...

that's it, that's the whole vibe check 🦋

💖 DESCRIPTION 💖

So virtproxyd is a server side daemon component of the libvirt virtualization management system, literally the backbone energy 👑

She's one of a whole collection of modular daemons — like a friend group that replaced the functionality previously provided by the monolithic libvirtd daemon. glow-up, no cap 💅

This daemon runs on virtualization hosts and:

  • Listens on a UNIX socket to provide backwards compatibility for clients that previously connected to the libvirtd socket 🔌
  • Optionally listens on TCP ports for connections from off-node clients 🌐

Upon receiving RPC messages from a client, virtproxyd will transparently forward them on to the appropriate modular daemon, and similarly relay back any asynchronous events. she's literally just the messenger and she's slaying at it 🫶

By default, the virtproxyd daemon listens for requests on a local Unix domain socket with the same path previously used by libvirtd. The configuration file can be used to instruct it to also listen on TCP socket(s). Systemd socket activation is also supported to allow it to receive pre-opened listener sockets on startup ✨

And here's the iconic part: since virtproxyd merely forwards RPC messages, it has no important state, and can be restarted at any time. Clients should expect to reconnect after the restart — that's just the relationship, ngl 😭

🦋 DAEMON STARTUP MODES 🦋

The virtproxyd daemon is capable of starting in two modes. two modes, two moods 💫

🎀 Socket activation mode

On hosts with systemd, it is started in socket activation mode and it will rely on systemd to create and listen on the UNIX, and optionally TCP/IP, sockets and pass them as pre-opened file descriptors. In this mode, most of the socket related config options in /etc/libvirt/virtproxyd.conf will no longer have any effect 👀 (she's not ignoring you, systemd is just handling it).

To enable TCP or TLS sockets use either

$ systemctl start virtproxyd-tls.socket

or

$ systemctl start virtproxyd-tcp.socket
⚠️ Note: The TCP socket uses plain unencrypted TCP connection and thus is insecure and should not be used. like fr fr do not, that's giving "leaving your diary open in the cafeteria" 💀

🧚 Traditional service mode

On hosts without systemd, it will create and listen on UNIX sockets itself. It will also listen on TCP/IP socket(s), according to the listen_tcp and listen_tls options in /etc/libvirt/virtproxyd.conf. self-sufficient queen energy 👑

💜 OPTIONS 💜

  • -h, --help — Display command line help usage then exit. the "wait what does this do again" button 🙈
  • -d, --daemon — Run as a daemon & write PID file. she goes off to do her own thing in the background ✨
  • -f, --config FILE — Use this configuration file, overriding the default value 🗂️
  • -p, --pid-file FILE — Use this name for the PID file, overriding the default value 📌
  • -t, --timeout SECONDS — Exit after timeout period (in seconds), provided there are no client connections. nobody's texting? she's leaving 👋
  • -v, --verbose — Enable output of verbose messages. she will tell you EVERYTHING 🗣️
  • --version — Display version information then exit 🏷️

🌈 SIGNALS 🌈

On receipt of SIGHUP, virtproxyd will reload its configuration. that's her little refresh button, iconic behavior 🔄

🍓 FILES 🍓

👑 When run as root

  • /etc/libvirt/virtproxyd.conf

The default configuration file used by virtproxyd, unless overridden on the command line using the -f | --config option.

  • /run/libvirt/libvirt-sock
  • /run/libvirt/libvirt-sock-ro

The sockets virtproxyd will use. two sockets, double the slay 🔌

  • /etc/pki/CA/cacert.pem

The TLS Certificate Authority certificate virtproxyd will use. 🏛️

  • /etc/pki/libvirt/servercert.pem

The TLS Server certificate virtproxyd will use. 📜

  • /etc/pki/libvirt/private/serverkey.pem

The TLS Server private key virtproxyd will use. 🤫 do not share, that's the whole point

  • /run/virtproxyd.pid

The PID file to use, unless overridden by the -p | --pid-file option.

🌸 When run as non-root

  • $XDG_CONFIG_HOME/libvirt/virtproxyd.conf

The default configuration file used by virtproxyd, unless overridden on the command line using the -f | --config option.

  • $XDG_RUNTIME_DIR/libvirt/libvirt-sock

The socket virtproxyd will use.

  • $HOME/.pki/libvirt/cacert.pem

The TLS Certificate Authority certificate virtproxyd will use. 🏛️

  • $HOME/.pki/libvirt/servercert.pem

The TLS Server certificate virtproxyd will use. 📜

  • $HOME/.pki/libvirt/serverkey.pem

The TLS Server private key virtproxyd will use. 🤫

  • $XDG_RUNTIME_DIR/libvirt/virtproxyd.pid

The PID file to use, unless overridden by the -p | --pid-file option.

If $XDG_CONFIG_HOME is not set in your environment, virtproxyd will use $HOME/.config 🏠

If $XDG_RUNTIME_DIR is not set in your environment, virtproxyd will use $HOME/.cache 🗄️

⭐ EXAMPLES ⭐

To retrieve the version of virtproxyd:

# virtproxyd --version
virtproxyd (libvirt) 12.8.0

To start virtproxyd, instructing it to daemonize and create a PID file:

# virtproxyd -d
# ls -la /run/virtproxyd.pid
-rw-r--r-- 1 root root 6 Jul  9 02:40 /run/virtproxyd.pid

look at that PID file living her best life in /run 🥹

💀 BUGS 💀

Please report all bugs you discover. This should be done via either:

  1. the mailing list

https://libvirt.org/contact.html

  1. the bug tracker

https://libvirt.org/bugs.html

Alternatively, you may report bugs to your software distributor / vendor. we love a flexible reporting pipeline 🫶

🧚 AUTHORS 🧚

Please refer to the AUTHORS file distributed with libvirt. the whole squad is listed there 👯‍♀️

Copyright (C) 2006-2020 Red Hat, Inc., and the authors listed in the libvirt AUTHORS file.

💅 LICENSE 💅

virtproxyd is distributed under the terms of the GNU LGPL v2.1+. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. read that again bestie, no warranty, she said what she said 😌

🔥 SEE ALSO 🔥

virsh(1), libvirtd(8), https://libvirt.org/daemons.html

mwah, that's the whole page 💖 brought to you by the Virtualization Support girlies and libvirt 12.8.0 — catch you in the next manpage, bye bestie 🦋✨🎀

📦 where this page comes from