# stapvirt

## NAME



           stapvirt - prepare libvirt domains for systemtap probing
    


## SYNOPSIS



           **stapvirt**[**-c** _URI_] [**-d** _PATH_] [**-v**] _COMMAND ARGUMENTS_
    


## DESCRIPTION



           The _stapvirt_ program can be used to add ports to domains managed
           by libvirt (see <http://libvirt.org/>).  These ports can then be
           used by _stap_ to run scripts inside the domains (see the '--remote'
           option in stap(1) for more information).
    
           Ports are added to the definition of the domain using the **port-add**
           command.  These ports can later be removed using the **port-remove**
           command.  Note that there can only be as many simultaneous _stap_
           sessions as there are ports.
    
           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
           **port-add** 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:
    
                  **$** virt-install [...] --controller=virtio-serial
    
           If the domain has already been created, you can simply 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.
    


## OPTIONS



           The following options are supported. Any other option prints a
           short help message.
    
           **-c** _URI_ Specify the libvirt driver URI to which to connect (e.g.
                  'qemu:///system'). The default value is NULL, which indi‐
                  cates to libvirt to connect to the default driver. See the
                  page at <http://libvirt.org/uri.html> for supported values.
    
           **-d** _PATH_
                  Specify the directory in which UNIX sockets should be cre‐
                  ated when SystemTap ports are added. The default directory
                  is '/var/lib/libvirt/qemu'.
    
           **-v** Increase verbosity. This option may be repeated for more
                  verbosity.
    


## COMMANDS



           The following commands are recognized by stapvirt. Any other com‐
           mand 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 defini‐
                  tion. If the domain is currently running, it must be pow‐
                  ered off before changes take effect.
    
           **query** _DOMAIN_
                  Display the following information about the domain: its
                  name, its UUID, its state, the number of permanent System‐
                  Tap ports installed, and whether hotplugging is supported.
    


## TUTORIAL



           This tutorial will help you get started with stapvirt. Let's start
           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
    
           Note that we specified the libvirt URI using the -c switch. Other‐
           wise libvirt might have defaulted to e.g. 'qemu:///session'.
    
           Rather than typing the URI everytime, it might be easier to in‐
           stead set the LIBVIRT_DEFAULT_URI environment variable and omit
           the -c switch. Note that this is a libvirt functionality (see
           <libvirt.org/uri.html> for more details).
    
           The **list** command indicates that we have a running domain named
           'TestVM' with ID 2. Let's use the **query** command to retrieve more
           information:
    
                  **$** 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
    
           The **query** command gives us some basic information about the do‐
           main, 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 relat‐
           ed to the domain in itself.
    
           If hotplugging were supported, we could stop here and run _stap_ di‐
           rectly (assuming we have a virtio-serial controller already in
           place, see **DESCRIPTION**). Since in our case hotplugging is not sup‐
           ported, we need to add SystemTap ports. To do this, 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 that a port was added by running the **query** command
           again:
    
                  **$** stapvirt query TestVM
                  **...**
                     Permanent Ports:  1
                         Hotplugging:  not supported
    
           It now indicates that there is 1 permanent port. We can also use
           the **port-list** command to know exactly where the port will be cre‐
           ated:
    
                  **$** 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!
    
           Finally, if we'd like to remove the port, we can use the **port-re‐**
           **move** 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!
    


## BUGS



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


* * *