CentOS 7.0 - man page for stapvirt (centos section 1)

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


STAPVIRT(1)									      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 de-
	      fault  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  cur-
	      rently 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 defini-
	      tion.

       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 installed, and whether hotplugging is  sup-
	      ported.

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

       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!\n"); 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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:03 PM.

Unix & Linux Forums Content Copyright©1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?