.\" -*- nroff -*-
.TH STAPVIRT 1
.SH NAME
stapvirt \- prepare libvirt domains for systemtap probing

.\" macros
.de SAMPLE

.nr oldin \\n(.i
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
.in \\n[oldin]u

..

.SH SYNOPSIS
\fBstapvirt\fR
[\fB-c\fR \fIURI\fR]
[\fB-d\fR \fIPATH\fR]
[\fB-v\fR]
\fICOMMAND\fR
\fIARGUMENTS\fR

.SH DESCRIPTION
The \fIstapvirt\fR program can be used to add ports to domains managed by
libvirt (see
.nh
<http://libvirt.org/>).
.hy
These ports can then be used by \fIstap\fR to
run scripts inside the domains (see the '--remote' option in \fIstap\fR(1) for
more information).
.PP
Ports are added to the definition of the domain using the \fBport-add\fR
command.  These ports can later be removed using the \fBport-remove\fR command.
Note that there can only be as many simultaneous \fIstap\fR sessions as there
are ports.
.PP
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 using the \fBport-add\fR command.
However, you need to ensure that there is a virtio-serial controller in place so
that hotplugged ports can be connected. If creating a domain using virt-install,
you can do this by adding this option:
.SAMPLE
\fB$\fR virt-install [...] --controller=virtio-serial
.ESAMPLE
If the domain has already been created, you can simply do \fBport-add\fR
followed immediately by \fBport-remove\fR, and then power off and restart the
domain. The port will be removed, but the controller will remain.

.SH OPTIONS
The following options are supported. Any other option prints a short help
message.

.IP "\fB-c\fR \fIURI\fR"
Specify the libvirt driver URI to which to connect (e.g. 'qemu:///system'). The
default value is NULL, which indicates to libvirt to connect to the default
driver. See the page at <http://libvirt.org/uri.html> for supported values.

.IP "\fB-d\fR \fIPATH\fR"
Specify the directory in which UNIX sockets should be created when SystemTap
ports are added. The default directory is '/var/lib/libvirt/qemu'.

.IP "\fB-v\fR"
Increase verbosity. This option may be repeated for more verbosity.

.SH COMMANDS
The following commands are recognized by stapvirt. Any other command prints a
short help message.

.IP "\fBhelp\fR"
Display the help message.

.IP "\fBlist\fR"
List available domains.

.IP "\fBport-add\fR \fIDOMAIN\fR"
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.

.IP "\fBport-list\fR \fIDOMAIN\fR"
List the UNIX socket paths of the permanent SystemTap ports in the domain's
definition.

.IP "\fBport-remove\fR \fIDOMAIN\fR"
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.

.IP "\fBquery\fR \fIDOMAIN\fR"
Display the following information about the domain: its name, its UUID, its
state, the number of permanent SystemTap ports installed, and whether
hotplugging is supported.

.SH TUTORIAL
This tutorial will help you get started with stapvirt. Let's start by listing
all the privileged domains on the machine with the \fBlist\fR command:

.SAMPLE
\fB$\fR stapvirt -c 'qemu:///system' list
Available domains on URI 'qemu:///system':
ID      State     Type        Name
2       running   persistent  TestVM
.ESAMPLE

Note that we specified the libvirt URI using the -c switch. Otherwise libvirt
might have defaulted to e.g. 'qemu:///session'.
.PP
Rather than typing the URI everytime, it might be easier to instead set the
.nh
LIBVIRT_DEFAULT_URI
.ni
environment variable and omit the -c switch. Note that this is a libvirt
functionality (see
.nh
<libvirt.org/uri.html>
.hy
for more details).
.PP
The \fBlist\fR command indicates that we have a running domain named 'TestVM'
with ID 2. Let's use the \fBquery\fR command to retrieve more information:

.SAMPLE
\fB$\fR stapvirt query TestVM # by name
\fB$\fR 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
.ESAMPLE

The \fBquery\fR command gives us some basic information about the domain, such
as its name, UUID, and state. More importantly, it gives us two pieces of
information: 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.
.PP
If hotplugging were supported, we could stop here and run \fIstap\fR directly
(assuming we have a virtio-serial controller already in place, see
\fBDESCRIPTION\fR). Since in our case hotplugging is not supported, we need to
add SystemTap ports. To do this, we use the \fBport-add\fR command:

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

We can confirm that a port was added by running the \fBquery\fR command again:

.SAMPLE
\fB$\fR stapvirt query TestVM
\fB...\fR
   Permanent Ports:  1
       Hotplugging:  not supported
.ESAMPLE

It now indicates that there is 1 permanent port. We can also use the
\fBport-list\fR command to know exactly where the port will be created:

.SAMPLE
\fB$\fR stapvirt port-list TestVM
/var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock
.ESAMPLE

After powering off and restarting the domain, we are now ready to use the port
with \fIstap\fR:

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

Finally, if we'd like to remove the port, we can use the \fBport-remove\fR
command:

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

And that's all there is to it!

.SH SEE ALSO
.nh
.nf
.IR stap (1),
.IR virt-install (1)

.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR http://sourceware.org/systemtap/ , <systemtap@sourceware.org> .
.hy