1STAPVIRT(1) General Commands Manual STAPVIRT(1)
2
6 stapvirt - prepare libvirt domains for systemtap probing
7
11 stapvirt [-c URI] [-d PATH] [-v] COMMAND ARGUMENTS
12
15 The stapvirt program can be used to add ports to domains managed by
16 libvirt (see <http://libvirt.org/>). These ports can then be used by
17 stap to run scripts inside the domains (see the '--remote' option in
18 stap(1) for more information).
19 Ports are added to the definition of the domain using the port-add com‐
21 mand. These ports can later be removed using the port-remove command.
22 Note that there can only be as many simultaneous stap sessions as there
23 are ports.
24 Starting from libvirt v1.1.1 and QEMU v0.10.0, SystemTap ports can be
26 hotplugged and thus do not need to be added first using the port-add
27 command. However, you need to ensure that there is a virtio-serial
28 controller in place so that hotplugged ports can be connected. If cre‐
29 ating a domain using virt-install, you can do this by adding this op‐
30 tion:
31 $ virt-install [...] --controller=virtio-serial
33 If the domain has already been created, you can simply do port-add fol‐
35 lowed immediately by port-remove, and then power off and restart the
36 domain. The port will be removed, but the controller will remain.
37
40 The following options are supported. Any other option prints a short
41 help message.
42 -c URI Specify the libvirt driver URI to which to connect (e.g. 'qe‐
45 mu:///system'). The default value is NULL, which indicates to
46 libvirt to connect to the default driver. See the page at
47 <http://libvirt.org/uri.html> for supported values.
48 -d PATH
51 Specify the directory in which UNIX sockets should be created
52 when SystemTap ports are added. The default directory is
53 '/var/lib/libvirt/qemu'.
54 -v Increase verbosity. This option may be repeated for more ver‐
57 bosity.
58
61 The following commands are recognized by stapvirt. Any other command
62 prints a short help message.
63 help Display the help message.
66 list List available domains.
69 port-add DOMAIN
72 Add a permanent SystemTap port to the domain's definition. If
73 the domain is currently running, it must be powered off before
74 changes take effect.
75 port-list DOMAIN
78 List the UNIX socket paths of the permanent SystemTap ports in
79 the domain's definition.
80 port-remove DOMAIN
83 Remove a permanent SystemTap port from the domain's definition.
84 If the domain is currently running, it must be powered off be‐
85 fore changes take effect.
86 query DOMAIN
89 Display the following information about the domain: its name,
90 its UUID, its state, the number of permanent SystemTap ports in‐
91 stalled, and whether hotplugging is supported.
92
95 This tutorial will help you get started with stapvirt. Let's start by
96 listing all the privileged domains on the machine with the list com‐
97 mand:
98 $ stapvirt -c 'qemu:///system' list
101 Available domains on URI 'qemu:///system':
102 ID State Type Name
103 2 running persistent TestVM
104 Note that we specified the libvirt URI using the -c switch. Otherwise
107 libvirt might have defaulted to e.g. 'qemu:///session'.
108 Rather than typing the URI everytime, it might be easier to instead set
110 the LIBVIRT_DEFAULT_URI environment variable and omit the -c switch.
111 Note that this is a libvirt functionality (see <libvirt.org/uri.html>
112 for more details).
113 The list command indicates that we have a running domain named 'TestVM'
115 with ID 2. Let's use the query command to retrieve more information:
116 $ stapvirt query TestVM # by name
119 $ stapvirt query 2 # by ID
120 Name: TestVM
122 UUID: 905951c0-fa4f-409b-079c-c91ddda27028
123 State: running
124 ID: 2
125 Type: persistent
126 Permanent Ports: 0
127 Hotplugging: not supported
128 The query command gives us some basic information about the domain,
131 such as its name, UUID, and state. More importantly, it gives us two
132 pieces of information: the number of permanent ports installed, and
133 whether hotplugging is supported. Technically, hotplugging support de‐
134 pends on libvirt and qemu, and is not related to the domain in itself.
135 If hotplugging were supported, we could stop here and run stap directly
137 (assuming we have a virtio-serial controller already in place, see DE‐
138 SCRIPTION). Since in our case hotplugging is not supported, we need to
139 add SystemTap ports. To do this, we use the port-add command:
140 $ stapvirt port-add TestVM
143 Added new port org.systemtap.stapsh.0
144 The domain must be powered off before changes take effect.
145 We can confirm that a port was added by running the query command
148 again:
149 $ stapvirt query TestVM
152 ...
153 Permanent Ports: 1
154 Hotplugging: not supported
155 It now indicates that there is 1 permanent port. We can also use the
158 port-list command to know exactly where the port will be created:
159 $ stapvirt port-list TestVM
162 /var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock
163 After powering off and restarting the domain, we are now ready to use
166 the port with stap:
167 $ stap -e 'probe begin { printf("Hello from TestVM!\n"); exit() }' \
170 --remote=libvirt://TestVM
171 Hello from TestVM!
172 Finally, if we'd like to remove the port, we can use the port-remove
175 command:
176 $ stapvirt port-remove TestVM
179 Removed port org.systemtap.stapsh.0
180 The domain must be powered off before changes take effect.
181 And that's all there is to it!
184
187 stap(1),
188 virt-install(1)
189
192 Use the Bugzilla link of the project web page or our mailing list.
193 http://sourceware.org/systemtap/,<systemtap@sourceware.org>.
194 STAPVIRT(1)