STAPVIRT(1)

✨ STAPVIRT(1) ✨

okay bestie, welcome to the stapvirt manual page, straight out of the General Commands Manual section 💅 she's a whole queen and she's here to prep your libvirt domains for systemtap probing. buckle up 🎀

---

🌸 NAME 🌸

stapvirt — prepare libvirt domains for systemtap probing ✨

---

🦋 SYNOPSIS 🦋

stapvirt [-c URI] [-d PATH] [-v] COMMAND ARGUMENTS

---

💖 DESCRIPTION 💖

So like, the stapvirt program is the girl you call when you wanna add ports to domains managed by libvirt (go look at <http://libvirt.org/> if you need the lore). once those ports exist, stap can use them to run scripts inside the domains — peep the --remote option in stap(1) if you want the deets 🫶

ports get added to the domain's definition with the port-add command. and later, when you're over them, you remove them with port-remove. lowkey important: you can only have as many simultaneous stap sessions as you have ports. no extra port, no extra session, that's just the math 💀

now here's the glow-up era: starting from libvirt v1.1.1 and QEMU v0.10.0, SystemTap ports can be hotplugged and thus do not need to be added first with port-add. iconic. BUT — and this is the catch bestie — you have to make sure there's a virtio-serial controller in place so the hotplugged ports can actually connect. if you're creating a domain with virt-install, you do that by adding this option:

$ virt-install [...] --controller=virtio-serial

and if the domain is already created, no worries — you can just do port-add followed immediately by port-remove, and then power off and restart the domain. the port will be removed, but the controller will remain. slay ✨

---

⭐ OPTIONS ⭐

these are the supported options. literally any other option prints a short help message. (not a full manual, just a little "hey" 😭)

• -c URI — specify the libvirt driver URI to connect to (e.g. 'qemu:///system'). the default value is NULL, which tells libvirt to connect to the default driver. supported values live over at <http://libvirt.org/uri.html> 👑
• -d PATH — specify the directory where UNIX sockets should be created when SystemTap ports are added. the default directory is '/var/lib/libvirt/qemu' 🎀
• -v — increase verbosity. and the way that this option may be repeated for even more verbosity? obsessed 💅

---

👑 COMMANDS 👑

these are the commands stapvirt recognizes. any other command prints a short help message 🙈

• help — display the help message.
• list — list available domains.
• port-add DOMAIN — add a permanent SystemTap port to the domain's definition. if the domain is currently running, it must be powered off before changes take effect ⚠️
• port-list DOMAIN — list the UNIX socket paths of the permanent SystemTap ports in the domain's definition.
• port-remove DOMAIN — remove a permanent SystemTap port from the domain's definition. if the domain is currently running, it must be powered off before changes take effect ⚠️
• query DOMAIN — display all of this about the domain: its name, its UUID, its state, the number of permanent SystemTap ports installed, and whether hotplugging is supported. she's nosy and we love her 💖

---

🌈 TUTORIAL 🌈

okay this is the part where we hold hands and get you started with stapvirt 🫶 let's begin by listing all the privileged domains on the machine with the list command:

$ stapvirt -c 'qemu:///system' list
Available domains on URI 'qemu:///system':
ID      State     Type        Name
2       running   persistent  TestVM

notice we specified the libvirt URI using the -c switch. otherwise libvirt might have defaulted to something like 'qemu:///session'. sneaky 😭

and rather than typing that URI every single time (so much effort), it might be easier to set the LIBVIRT_DEFAULT_URI environment variable instead and just omit the -c switch. fyi this is a libvirt functionality — see <libvirt.org/uri.html> for more details 💜

so the list command says we have a running domain named 'TestVM' with ID 2. let's use the query command to pull more info:

$ stapvirt query TestVM # by name
$ stapvirt query 2      # by ID

              Name:  TestVM
              UUID:  905951c0-fa4f-409b-079c-c91ddda27028
             State:  running
                ID:  2
              Type:  persistent
   Permanent Ports:  0
       Hotplugging:  not supported

query gives us the basics — name, UUID, state, all that. but more importantly, it gives us two lil pieces of info: the number of permanent ports installed, and whether hotplugging is supported. technically, hotplugging support depends on libvirt and qemu and is not related to the domain in itself. iykyk 🧚

if hotplugging were supported, we could stop right here and run stap directly (assuming we already have a virtio-serial controller in place, see DESCRIPTION). but since in our case hotplugging is not supported, we need to add SystemTap ports. to do that, we use the port-add command:

$ stapvirt port-add TestVM
Added new port org.systemtap.stapsh.0
The domain must be powered off before changes take effect.

we can confirm a port was added by running query again:

$ stapvirt query TestVM
...
   Permanent Ports:  1
       Hotplugging:  not supported

it now says there's 1 permanent port 💅 and we can also use the port-list command to know exactly where that port will be created:

$ stapvirt port-list TestVM
/var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock

after powering off and restarting the domain, we are now ready to use the port with stap:

$ stap -e 'probe begin { printf("Hello from TestVM!\n"); exit() }' \
       --remote=libvirt://TestVM
Hello from TestVM!

and finally, if we'd like to remove the port, we can use the port-remove command:

$ stapvirt port-remove TestVM
Removed port org.systemtap.stapsh.0
The domain must be powered off before changes take effect.

and that's all there is to it! periodt 🎀✨

---

🦋 SEE ALSO 🦋

• stap(1)
• virt-install(1)

---

💀 BUGS 💀

use the Bugzilla link of the project web page or our mailing list, bestie: <http://sourceware.org/systemtap/>, <systemtap@sourceware.org>.

---

and that's the whole page, angel — this was the STAPVIRT(1) page from the General Commands Manual, mwah 💋 go forth and probe responsibly 🫶