STAPVIRT(1)						      General Commands Manual						       STAPVIRT(1)

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).

       Starting from libvirt v1.1.1 and QEMU v0.10.0, SystemTap ports can be hotplugged and thus domains do  not  require  any	preparation  using
       stapvirt. The 'query' command can be used to determine whether hotplugging is supported.

       If  hotplugging	is  not  supported, then ports must be 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.

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 indicates 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  created  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 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 restarted  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 restarted before
	      changes take effect.

       query DOMAIN
	      Display the following information about the domain: its name, its UUID, its state, the  number  of  permanent  SystemTap	ports  in-
	      stalled, 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 com-
       mand:

	      $ 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. Otherwise libvirt might have defaulted to e.g. 'qemu:///session'.

       Rather than typing the URI everytime, it might be easier to instead 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 informa-
       tion:

	      $ 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 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 de-
       pends on libvirt and qemu, and is not related to the domain in itself.

       If hotplugging were supported, we could stop here and run stap directly.  Since in our case hotplugging is not supported, 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 restarted 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 created:

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

       After stopping and restarting the domain, we are now ready to use the port with stap:

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

       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 restarted before changes take effect.

       And that's all there is to it!

SEE ALSO

       stap(1)

BUGS

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

																       STAPVIRT(1)