1xm(1M) System Administration Commands xm(1M)
2
6 xm - xVM management user interface
7
9 xm subcommand [options] domain
10
13 The main interface for command and control of both xVM and guest
14 domains is virsh(1M). Users should use virsh wherever possible, as it
15 provides a generic and stable interface to controlling virtualized
16 operating systems. Some xVM operations are not yet implemented by
17 virsh. In those cases, the legacy utility xm can be used for detailed
18 control.
19 With minor variations, the basic structure of an xm command is:
22 xm subcommand [options] domain
24 ...where subcommand is one of the subcommands listed below, domain is
29 the domain name (which is internally translated to a numeric domain
30 id), and options are subcommand-specific options. The exceptions to
31 this structure occur where a subcommand acts on all domains, on the
32 entire machine, or directly on the xVM hypervisor. These exceptions are
33 obvious in the descriptions of the subcommands.
34 All xm operations rely upon the xVM control daemon, xend(1M). xend must
37 be running before any xm commands can run. As described in the man
38 page, xend runs under the service management facility (smf(5)), which
39 enables the daemon to start when a system is booted.
40 Most xm subcommands require either root privileges or that you assume
43 the Primary Administrator role.
44 Most xm commands act asynchronously, so the fact that an xm command
47 returns immediately does not mean that the requested action is com‐
48 plete. Many operations on domains, such as create and shutdown, can
49 take considerable time (30 seconds or more) to complete.
50
52 The xm program supports the subcommands listed below. The parameters
53 and options for a given subcommand are described in the description for
54 that subcommand.
55 block-attach domain be-dev fe-dev mode [bedomain]
57 Create a new virtual block device. This will notify the guest
59 domain of the new virtual block device..
60 The block-attach subcommand has the following arguments and
62 options:
63 domain
65 The guest domain name to which the device will be attached.
67 be-dev
70 The device in the backend domain (domain 0) to be exported.
72 This can be specified as a physical partition (for example,
73 phy:/dev/md/dsk/mydisk, a ZFS volume or a normal file
74 ('file:/export/disk-image').
75 fe-dev
78 The form, either a symbolic name or a numeric id, by which a
80 device should be identified to the guest domain. In Linux, an
81 example of a symbolic name is /dev/hdc. For Solaris guest
82 domains, a single number should be used. The specified number
83 will correspond to a Solaris disk ID. For example, disk ID 3
84 will have a slice 0 name of /dev/dsk/c0d3s0.
85 mode
88 The access mode for the device from the guest domain. Supported
90 modes are w (read/write) and r (read-only).
91 bedomain
94 The backend domain hosting the device. This defaults to domain
96 0. Currently, no other ID is supported.
97 See EXAMPLES for an example of the use of this subcommand.
99 block-configure domain back_dev front_dev mode [back_domain]
102 Change block device configuration. Used for changing CDs in an HVM
104 (hardware-based virtual machine) domain; in particular, changing
105 the backend device to refer to a different ISO file. See block-
106 attach for parameter descriptions.
107 block-detach domain dev-id
110 Destroy a domain's virtual block device. devid must be the device
112 id given to the device by domain 0. You must run xm block-list to
113 determine that number.
114 block-list [-l|--long] domain
117 List virtual block devices for a domain. The block-list subcommand
119 has a single option:
120 -l, --long
122 Display output in long format.
124 console domain
128 Attach to domain domain's console. If you have set up your domains
130 to have a text-based login console, you receive a normal login
131 screen.
132 The console supports only paravirtualized domains. The attached
134 console performs similarly to a serial console.
135 control-] exits the virtual console.
137 create [option] -f=config-file [name=value]...
140 The create subcommand creates a domain, according to the specifica‐
142 tions in the mandatory config-file argument. create optionally
143 accepts a set of name-value pairs that can override or add to the
144 variables defined in config-file.
145 config-file can be an absolute pathname.
147 The create subcommand returns immediately upon domain startup. How‐
149 ever, the starting of a domain is independent of the booting of the
150 guest operating system in that domain and independent of that OS's
151 availability for input.
152 The create and new subcommands are legacy features. These subcom‐
154 mands are used for existing domains that use the old configuration
155 file format. New domains should be created with virt-install(1M).
156 The create subcommand has the following options:
158 -c
160 --console_autoconnect
161 Attach to the console of the domain as soon as it has started.
163 -f=file, --defconfig=file
166 Use the given Python configuration script, file.The configura‐
168 tion script is loaded after arguments have been processed. Each
169 command-line option sets a configuration variable named after
170 its long option name, and these variables are placed in the
171 environment of the script before it is loaded. Variables for
172 options that can be repeated have list values. Other variables
173 can be set using var=value on the command line. After the
174 script is loaded, option values that were not set on the com‐
175 mand line are replaced by the values set in the script.
176 -F=file, --config=file
179 Use the given SXP-format configuration file. This is an inter‐
181 nal format; this option is useful only for debugging purposes.
182 -h, --help
185 Display list of options for create subcommand.
187 --help_config
190 Display the available configuration variables (vars) from the
192 configuration script.
193 -n, --dryrun
196 Dry run. Displays the resulting configuration in SXP but does
198 not create the domain.
199 -p, --paused
202 Leave the domain paused after it is created.
204 -q, --quiet
207 Display no messages over the course of domain creation.
209 debug-keys keys
213 Send commands to the hypervisor debugger. The keys are as follows:
215 % (ASCII 25)
217 Trap to xendbg.
219 C (ASCII 43)
222 Trigger a crash dump.
224 H (ASCII 48)
227 Dump heap info.
229 N (ASCII 4e)
232 NMI statistics.
234 O (ASCII 4f)
237 Toggle shadow audits.
239 R (ASCII 52)
242 Reboot machine.
244 S (ASCII 53)
247 Reset shadow page tables.
249 a (ASCII 61)
252 Dump timer queues.
254 d (ASCII 64)
257 Dump registers.
259 h (ASCII 68)
262 Display list of debug keys.
264 i (ASCII 69)
267 Dump interrupt bindings.
269 m (ASCII 6d)
272 Memory info.
274 n (ASCII 6e)
277 Trigger an NMI.
279 q (ASCII 71)
282 Dump domain (and guest debug) info.
284 r (ASCII 72)
287 Dump run queues.
289 t (ASCII 74)
292 Display multi-CPU clock info.
294 u (ASCII 75)
297 Dump Non-Uniform Memory Access (NUMA) info.
299 v (ASCII 76)
302 Dump Intel's VMCS.
304 z (ASCII 7a)
307 Print ioapic info.
309 delete domain
313 Removes the domain domain from xVM domain management. This is the
315 same as the virsh(1M) undefine, which should be used in place of
316 this subcommand.
317 destroy domain
320 Immediately terminate the domain domain. For the domain OS, this is
322 the equivalent of abruptly removing the power from a physical
323 machine. In most cases, you will want to use the shutdown command
324 instead.
325 dmesg [-c]
328 Displays recent messages in the xVM message buffer; analogous to
330 dmesg(1M). The message buffer contains informational, warning, and
331 error messages created during xVM's operation.
332 The dmesg subcommand supports the following option:
334 -c, --clear
336 Clears xVM's message buffer.
338 domid domain
342 Converts a domain name to a domain ID.
344 Domain IDs change on each boot, whereas names are permanent. See
346 xVM(5) for an explanation of the differences among a domain ID,
347 UUID, and name.
348 domname domain
351 Converts a domain ID to a domain name.
353 dump-core domain [output-file]
356 Dumps core for the domain domain. By default, the domain continues
358 to run after a dump is collected. If output-file is not specified,
359 the domain core dump is generated in /var/xen/dump/. Core dump
360 files can be large. Solaris guest domain cores can be debugged
361 using mdb(1).
362 The dump-core domain has the following options:
364 -C, --crash
366 Crash domain after dumping core.
368 -L, --live
371 Dump core without pausing the domain.
373 help [-l, --long]
377 Displays a list of common xm subcommands. xm help supports the fol‐
379 lowing option:
380 -l, --long Display a complete list of xm subcommands, grouped by
382 function.
383 info
387 Display information about the xVM host in name : value format. The
389 information reported by info is useful for inclusion in a bug
390 report.
391 list [-l, --long] [domain, ...]
394 Displays information about one or more domains. If no domains are
396 specified, displays information about all domains.
397 An example of list output:
399 Name ID Mem VCPUs State Time(s)
401 Domain-0 0 3456 2 r----- 244.7
402 solaris 1 511 30 -b---- 353.8
403 The fields in this output are as follows:
406 Name
408 Domain name
410 ID
413 Numeric domain ID.
415 Mem
418 Amount of memory, in MB, currently allocated to a domain.
420 VCPUS
423 Number of virtual CPUs assigned to a domain.
425 State
428 Run state (described below).
430 Time
433 Total run time of the domain as accounted for by xVM.
435 The State field in xm list output can, for a given domain, display
437 one of the following letters.
438 r
440 Running. The domain is currently running on a CPU.
442 b
445 Blocked. The domain is not currently running. It is either idle
447 or waiting on I/O.
448 p
451 Paused. The domain has been paused, occurring usually as a
453 result of an administrator running xm pause. When in a paused
454 state the domain still consumes allocated resources, such as
455 memory, but will not be eligible for scheduling by the xVM
456 hypervisor. See also the virsh suspend subcommand.
457 s
460 Shutdown. The domain is in the state it was in prior to
462 startup. This state will, most likely, never be visible.
463 c
466 Crashed. The domain has crashed, which means that it terminated
468 in an abrupt, unexpected manner. Usually this state can occur
469 only if the domain has been configured not to restart on crash.
470 d
473 Dying. The domain is in process of moving to a shutdown or
475 crashed state.
476 The list subcommand supports the following option:
478 -l, --long
480 Displays more detailed information about each domain than is
482 shown in the standard list output table.
483 log
487 Display the xend(1M) log. The log file is /var/log/xen/xend.log.
489 mem-max domain mem
492 Specify the maximum amount of memory a domain is able to use. mem
494 is specified in megabytes.
495 The mem-max value might not correspond to the actual memory used in
497 a domain, because a domain might scale down its memory usage to
498 return memory to the OS.
499 mem-set domain mem
502 Set the amount of memory used by the running domain domain. Because
504 this operation requires cooperation from the domain operating sys‐
505 tem, there is no guarantee that it will succeed.
506 Warning: There is no good way to know in advance how small of a
508 mem-set value will make a domain unstable and cause it to crash. Be
509 very careful when using this command on running domains. Solaris
510 guest domains attempt to refuse potentially dangerous settings.
511 migrate [options] domain host
514 Migrate a domain to another host machine. On the target host
516 machine, the following conditions must obtain for this subcommand
517 to be successful:
518 o The other host must be running the same version of xVM.
520 o The migration TCP port must be open and accepting con‐
522 nections from the source host.
523 o There must be sufficient resources—memory, disk, and so
525 forth—for the domain to run.
526 See xend(1M) for an explanation of how to set up a machine to
527 receive a remote migration.
528 The domain's accessible disks must reside on some form of shared
530 storage, such as NFS files or iSCSI volumes, and this storage must
531 be accessible to both hosts
532 The migrate subcommand supports the following option:
534 -l, --live
536 Use live migration. This option migrates the domain between
538 hosts without shutting down the domain.
539 network-attach domain [script=scriptname] [ip=ipaddr] [mac=macaddr]
543 [bridge=link] [backend=bedomain] [rate=bandwidth] [vlan=vid]
544 Creates a new network device in the domain specified by domain. The
546 subcommand has the following arguments:
547 domain
549 Domain in which the network device is to be created.
551 script=scriptname
554 Use the specified script name to bring up the network.
556 ip=ipaddr
559 Passes the specified IP address to the adapter upon creation.
561 This address might be ignored by the specified domain.
562 mac=macaddr
565 The MAC address that the domain will see on its Ethernet
567 device. If the MAC address is not specified, it will be ran‐
568 domly generated with the 00:16:3e vendor id prefix.
569 bridge=link
572 The name of the network link to which to attach a virtual
574 interface, in case you have more than one.
575 backend=bedomain
578 The backend domain id. By default, this is domain 0. Note that
580 backend != 0 is not currently operational.
581 rate=bandwidth
584 Sets the bandwidth limit for this interface. The bandwidth
586 should be expressed in a regular expression defined as follows:
587 ^([0-9]+)([GMK]?)([Bb])/s(@([0-9]+)([mu]?)s)?$
589 Note that bandwidth will be rounded up to 1.2M if the figure
592 you input is below that value.
593 vlan=vid
596 Sets the VLAN ID for this interface.
598 network-detach domain dev-id
602 Removes the network device from the domain specified bydomain. dev-
604 id is the virtual interface device number within the domain.
605 network-list [-l|--long] domain
608 List virtual network interfaces for a domain.
610 -l, --long
612 Display output in long format.
614 new domain
618 The new subcommand creates (but does not start) the domain defined
620 by the given configuration file.
621 The new and create subcommands are legacy features. These subcom‐
623 mands are used for existing domains that use the old configuration
624 file format. New domains should use virt-install(1M).
625 -f=file, --defconfig=file
627 Use the given Python configuration script, file.The configura‐
629 tion script is loaded after arguments have been processed. Each
630 command-line option sets a configuration variable named after
631 its long option name, and these variables are placed in the
632 environment of the script before it is loaded. Variables for
633 options that can be repeated have list values. Other variables
634 can be set using var=value on the command line. After the
635 script is loaded, option values that were not set on the com‐
636 mand line are replaced by the values set in the script.
637 -F=file, --config=file
640 Use the given SXP-format configuration file. This is an inter‐
642 nal format; this option is useful only for debugging purposes.
643 --help_config
646 Display the available configuration variables (vars) from the
648 configuration script.
649 -n, --dryrun
652 Dry run. Displays the resulting configuration in SXP but does
654 not create the domain.
655 npiv-add domid [-p virtual_port_WWN] [-n virtual_node_WWN] physi‐
659 cal_port_WWN[, physical_port_WWN...]
660 Add a configuration entry for the virtual_port_WWN and associated
662 virtual_node_WWN to the domain specified by domid, along with can‐
663 didate physical ports on which the virtual port could be created.
664 If virtual port/node WWNs are not specified, they will be gener‐
665 ated.
666 npiv-disable domid -p virtual_port_WWN
669 Delete the specified virtual port and associated storage devices
671 from the domain. The virtual_port_WWN will be marked as disabled,
672 regardless of whether the deletion succeeds.
673 npiv-enable domid -p virtual_port_WWN
676 Create the specified virtual port on the first available physical
678 port. The virtual_port_WWN will be marked as enabled, regardless of
679 whether the creation succeeds.
680 npiv-list domid
683 List all the virtual port WWNs in the domain along with:
685 o virtual node WWN
687 o list of candidate physical ports (see npiv-add)
689 o storage over the virtual port, if any
691 npiv-mod domid -p virtual_port_WWN -n virtual_node_WWN physi‐
694 cal_port_WWN[, physical_port_WWN...]
695 Modify the configuration entry of the virtual_node_WWN and the
697 physical_port_WWN list with the specified virtual_port_WWN.
698 npiv-rm domid -p virtual_port_WWN
701 Remove the configuration entry of the virtual_port_WWN from the
703 domain specified by domid.
704 pause domain
707 Pause a domain. When in a paused state the domain still consumes
709 allocated resources, such as memory, but will not be eligible for
710 scheduling by the xVM hypervisor.
711 reboot [options] domain
714 Reboot a domain. The effect of this subcommand is the same as if
716 the domain had the init 6 command (see init(1M)) run from the con‐
717 sole. Unless -w is specified, reboot returns as soon as it has ini‐
718 tiated the reboot process, which can be significantly before the
719 domain actually reboots.
720 The reboot subcommand supports the following options:
722 -a, --all
724 Reboot all domains.
726 -w, --wait
729 Wait for reboot to complete before returning. This might take
731 an extended period, as all services in the domain will have to
732 be shutdown cleanly.
733 rename oldname newname
737 Renames the domain oldname to newname.
739 restore state-file
742 Build a domain from an xm save state file. See the save subcommand.
744 resume domain
747 Resume the activities of the domain domain, which is in a suspended
749 state as a result of the suspend subcommand.
750 save domain state-file
753 Saves a running domain to a file state-file, so that it can later
755 be restored, using the restore subcommand. Once saved, the domain
756 will no longer be running on the system, thus the memory allocated
757 for the domain will be free for the use of other domains.
758 Note that network connections present before the save operation
760 might be severed, as TCP timeouts might have expired.
761 sched-credit -d domain [-w weight|-ccap]
764 Get and set credit scheduler parameters for the specified domain.
766 See xVM(5) for a description of the credit scheduler. Without the
767 -w or -c options, the current settings for the given domain are
768 shown. Otherwise, the relevant parameter is set.
769 The parameters to the sched-credit subcommand are as follows:
771 -c cap, --cap=cap
773 Set the maximum amount of CPU a domain can consume. A value of
775 zero (the default) means no maximum is set. This value is
776 expressed in percentage points of a physical CPU. For example,
777 a value of 50 specifies a cap of half a physical CPU.
778 -d domain, --domain=domain
781 Domain for which to set scheduling parameters.
783 -w weight, --weight=weight
786 Set the relative weight of the domain. A domain with twice the
788 weight will receive twice the CPU time as another domain, if
789 CPU use is in contention. Valid weights are in the range
790 1-65536 and the default is 256.
791 sched-sedf domain period slice latency-hint extratime weight
795 Set Simple EDF scheduler parameters. This scheduler provides
797 weighted CPU sharing in an intuitive way and uses realtime algo‐
798 rithms to ensure time guarantees. The Simple EDF scheduler is not
799 the default scheduler used in xVM.
800 The parameters to the sched-sedf subcommand are as follows:
802 domain
804 The domain for which scheduling parameters applies.
806 period
809 The normal EDF scheduling usage, in nanoseconds.
811 slice
814 The normal EDF scheduling usage, in nanoseconds.
816 latency-hint
819 Scaled period if domain is performing heavy I/O.
821 extratime
824 Flag for allowing domain to run in extra time.
826 weight
829 Another way of setting CPU slice.
831 shell
835 Launches an interactive shell.
837 shutdown [options] domain
840 Gracefully shuts down a domain. The effect of this subcommand is
842 the same as if the domain had the init 5 command (see init(1M))
843 run from the console. This subcommand coordinates with the domain
844 OS to perform graceful shutdown. The duration of the entire shut‐
845 down will vary, depending on what services must be shutdown in the
846 domain. The shutdown subcommand returns immediately after sig‐
847 nalling the domain, unless the -w option is used.
848 The shutdown subcommand supports the following options:
850 -a
852 Shutdown all domains.
854 -w
857 Wait for the domain to complete shutdown before returning.
859 start domain
863 Start the domain specified by domain.
865 suspend domain
868 Suspend the activities of all services in the domain specified by
870 domain.
871 sysrq domain letter
874 For the accepted signals in a Linux domain, refer to the Linux doc‐
876 umentation. For Solaris signalling the letter b causes the domain
877 to enter kmdb(1), the Solaris kernel debugger, if that debugger is
878 loaded. Any other letter has no effect.
879 top domain...
882 Invokes the xentop(1M) command. Monitor a host and one or more
884 domains in real time.
885 unpause domain
888 Moves the domain domain out of the paused state. This will allow a
890 previously paused domain to now be eligible for scheduling by the
891 xVM hypervisor. See the pause subcommand.
892 uptime domain
895 Provides information on resource usage for domain domain. Analogous
897 to the uptime(1) command.
898 vcpu-list domain
901 Lists VCPU information for the domain domain. If no domain is spec‐
903 ified, the subcommand provides VCPU information for all domains.
904 vcpu-pin domain vcpu cpus
907 Pins the VCPU to only run on the specified CPUs. The keyword all
909 can be used to apply the cpus list to all VCPUs in the domain.
910 Normally VCPUs can float between available CPUs whenever xVM deems
912 a different run state is appropriate. Pinning can be used to
913 restrict this, by ensuring certain VCPUs can run only on certain
914 physical CPUs.
915 vcpu-set domain vcpu-count
918 Enables the number vcpu-count of virtual CPUs for the domain in
920 question. Like the mem-setsubcommand, vcpu-set can allocate only up
921 to the maximum virtual CPU count configured at boot time for a
922 domain.
923 If vcpu-count is smaller than the current number of active VCPUs,
925 the highest numbered VCPUs will be hotplug removed. This might have
926 consequences for pinned VCPUs.
927 Attempting to set the VCPUs to a number larger than the initially
929 configured VCPU count is an error. Trying to set VCPUs to less than
930 one will be silently ignored.
931
934 Example 1 Attach a File as a Read-only Block Device
935 The following example attaches a file as a read-only block device to a
938 Solaris guest domain, as /dev/dsk/c0d3.
939 xm block-attach solaris1 file:/data/disk.img 3 r
942 Example 2 Live Migration of a domU to a Different Host
946 xm migrate --live solaris1 solaris-host2
948 Example 3 Pin a Domain's vcpus to Corresponding CPUs
952 xm vcpu-pin solaris1 0 5
954 xm vcpu-pin solaris1 1 6
955 Example 4 Balloon Down a Domain to Use Less Memory
959 xm mem-set solaris1 512
961
965 o Sean Dague, sean at dague dot net
966 o Daniel Stekloff, dsteklof at us dot ibm dot com
968 o Reiner Sailer, sailer at us dot ibm dot com
970
972 See attributes(5) for descriptions of the following attributes:
973 ┌─────────────────────────────┬─────────────────────────────┐
978 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
979 ├─────────────────────────────┼─────────────────────────────┤
980 │Availability │SUNWxvmu │
981 ├─────────────────────────────┼─────────────────────────────┤
982 │Interface Stability │Volatile │
983 └─────────────────────────────┴─────────────────────────────┘
984
986 kmdb(1), uptime(1), dmesg(1M), init(1M), virsh(1M), virt-install(1M),
987 xend(1M), xentop(1M), xenstored(1M), attributes(5), smf(5), xVM(5)
988SunOS 5.11 12 Mar 2009 xm(1M)