Debian Codegraph @

man/stapvirt.1

raw
1 .\" -*- nroff -*-
2 .TH STAPVIRT 1
3 .SH NAME
4 stapvirt \- prepare libvirt domains for systemtap probing
5
6 .\" macros
7 .de SAMPLE
8
9 .nr oldin \\n(.i
10 .br
11 .RS
12 .nf
13 .nh
14 ..
15 .de ESAMPLE
16 .hy
17 .fi
18 .RE
19 .in \\n[oldin]u
20
21 ..
22
23 .SH SYNOPSIS
24 \fBstapvirt\fR
25 [\fB-c\fR \fIURI\fR]
26 [\fB-d\fR \fIPATH\fR]
27 [\fB-v\fR]
28 \fICOMMAND\fR
29 \fIARGUMENTS\fR
30
31 .SH DESCRIPTION
32 The \fIstapvirt\fR program can be used to add ports to domains managed by
33 libvirt (see
34 .nh
35 <http://libvirt.org/>).
36 .hy
37 These ports can then be used by \fIstap\fR to
38 run scripts inside the domains (see the '--remote' option in \fIstap\fR(1) for
39 more information).
40 .PP
41 Ports are added to the definition of the domain using the \fBport-add\fR
42 command. These ports can later be removed using the \fBport-remove\fR command.
43 Note that there can only be as many simultaneous \fIstap\fR sessions as there
44 are ports.
45 .PP
46 Starting from libvirt v1.1.1 and QEMU v0.10.0, SystemTap ports can be hotplugged
47 and thus do not need to be added first using the \fBport-add\fR command.
48 However, you need to ensure that there is a virtio-serial controller in place so
49 that hotplugged ports can be connected. If creating a domain using virt-install,
50 you can do this by adding this option:
51 .SAMPLE
52 \fB$\fR virt-install [...] --controller=virtio-serial
53 .ESAMPLE
54 If the domain has already been created, you can simply do \fBport-add\fR
55 followed immediately by \fBport-remove\fR, and then power off and restart the
56 domain. The port will be removed, but the controller will remain.
57
58 .SH OPTIONS
59 The following options are supported. Any other option prints a short help
60 message.
61
62 .IP "\fB-c\fR \fIURI\fR"
63 Specify the libvirt driver URI to which to connect (e.g. 'qemu:///system'). The
64 default value is NULL, which indicates to libvirt to connect to the default
65 driver. See the page at <http://libvirt.org/uri.html> for supported values.
66
67 .IP "\fB-d\fR \fIPATH\fR"
68 Specify the directory in which UNIX sockets should be created when SystemTap
69 ports are added. The default directory is '/var/lib/libvirt/qemu'.
70
71 .IP "\fB-v\fR"
72 Increase verbosity. This option may be repeated for more verbosity.
73
74 .SH COMMANDS
75 The following commands are recognized by stapvirt. Any other command prints a
76 short help message.
77
78 .IP "\fBhelp\fR"
79 Display the help message.
80
81 .IP "\fBlist\fR"
82 List available domains.
83
84 .IP "\fBport-add\fR \fIDOMAIN\fR"
85 Add a permanent SystemTap port to the domain's definition. If the domain is
86 currently running, it must be powered off before changes take effect.
87
88 .IP "\fBport-list\fR \fIDOMAIN\fR"
89 List the UNIX socket paths of the permanent SystemTap ports in the domain's
90 definition.
91
92 .IP "\fBport-remove\fR \fIDOMAIN\fR"
93 Remove a permanent SystemTap port from the domain's definition. If the domain is
94 currently running, it must be powered off before changes take effect.
95
96 .IP "\fBquery\fR \fIDOMAIN\fR"
97 Display the following information about the domain: its name, its UUID, its
98 state, the number of permanent SystemTap ports installed, and whether
99 hotplugging is supported.
100
101 .SH TUTORIAL
102 This tutorial will help you get started with stapvirt. Let's start by listing
103 all the privileged domains on the machine with the \fBlist\fR command:
104
105 .SAMPLE
106 \fB$\fR stapvirt -c 'qemu:///system' list
107 Available domains on URI 'qemu:///system':
108 ID State Type Name
109 2 running persistent TestVM
110 .ESAMPLE
111
112 Note that we specified the libvirt URI using the -c switch. Otherwise libvirt
113 might have defaulted to e.g. 'qemu:///session'.
114 .PP
115 Rather than typing the URI everytime, it might be easier to instead set the
116 .nh
117 LIBVIRT_DEFAULT_URI
118 .ni
119 environment variable and omit the -c switch. Note that this is a libvirt
120 functionality (see
121 .nh
122 <libvirt.org/uri.html>
123 .hy
124 for more details).
125 .PP
126 The \fBlist\fR command indicates that we have a running domain named 'TestVM'
127 with ID 2. Let's use the \fBquery\fR command to retrieve more information:
128
129 .SAMPLE
130 \fB$\fR stapvirt query TestVM # by name
131 \fB$\fR stapvirt query 2 # by ID
132
133 Name: TestVM
134 UUID: 905951c0-fa4f-409b-079c-c91ddda27028
135 State: running
136 ID: 2
137 Type: persistent
138 Permanent Ports: 0
139 Hotplugging: not supported
140 .ESAMPLE
141
142 The \fBquery\fR command gives us some basic information about the domain, such
143 as its name, UUID, and state. More importantly, it gives us two pieces of
144 information: the number of permanent ports installed, and whether hotplugging is
145 supported. Technically, hotplugging support depends on libvirt and qemu, and is
146 not related to the domain in itself.
147 .PP
148 If hotplugging were supported, we could stop here and run \fIstap\fR directly
149 (assuming we have a virtio-serial controller already in place, see
150 \fBDESCRIPTION\fR). Since in our case hotplugging is not supported, we need to
151 add SystemTap ports. To do this, we use the \fBport-add\fR command:
152
153 .SAMPLE
154 \fB$\fR stapvirt port-add TestVM
155 Added new port org.systemtap.stapsh.0
156 The domain must be powered off before changes take effect.
157 .ESAMPLE
158
159 We can confirm that a port was added by running the \fBquery\fR command again:
160
161 .SAMPLE
162 \fB$\fR stapvirt query TestVM
163 \fB...\fR
164 Permanent Ports: 1
165 Hotplugging: not supported
166 .ESAMPLE
167
168 It now indicates that there is 1 permanent port. We can also use the
169 \fBport-list\fR command to know exactly where the port will be created:
170
171 .SAMPLE
172 \fB$\fR stapvirt port-list TestVM
173 /var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock
174 .ESAMPLE
175
176 After powering off and restarting the domain, we are now ready to use the port
177 with \fIstap\fR:
178
179 .SAMPLE
180 \fB$\fR stap -e 'probe begin { printf("Hello from TestVM!\\n"); exit() }' \\
181 --remote=libvirt://TestVM
182 Hello from TestVM!
183 .ESAMPLE
184
185 Finally, if we'd like to remove the port, we can use the \fBport-remove\fR
186 command:
187
188 .SAMPLE
189 \fB$\fR stapvirt port-remove TestVM
190 Removed port org.systemtap.stapsh.0
191 The domain must be powered off before changes take effect.
192 .ESAMPLE
193
194 And that's all there is to it!
195
196 .SH SEE ALSO
197 .nh
198 .nf
199 .IR stap (1),
200 .IR virt-install (1)
201
202 .SH BUGS
203 Use the Bugzilla link of the project web page or our mailing list.
204 .nh
205 .BR http://sourceware.org/systemtap/ , <[email protected]> .
206 .hy