1xl(1) Xen xl(1)
2
6 xl - Xen management tool, based on libxenlight
7
9 xl subcommand [args]
10
12 The xl program is the new tool for managing Xen guest domains. The
13 program can be used to create, pause, and shutdown domains. It can also
14 be used to list current domains, enable or pin VCPUs, and attach or
15 detach virtual block devices.
16 The basic structure of every xl command is almost always:
18 xl subcommand [OPTIONS] domain-id
20 Where subcommand is one of the subcommands listed below, domain-id is
22 the numeric domain id, or the domain name (which will be internally
23 translated to domain id), and OPTIONS are subcommand specific options.
24 There are a few exceptions to this rule in the cases where the
25 subcommand in question acts on all domains, the entire machine, or
26 directly on the Xen hypervisor. Those exceptions will be clear for
27 each of those subcommands.
28
30 start the script /etc/init.d/xencommons at boot time
31 Most xl operations rely upon xenstored and xenconsoled: make sure
32 you start the script /etc/init.d/xencommons at boot time to
33 initialize all the daemons needed by xl.
34 setup a xenbr0 bridge in dom0
36 In the most common network configuration, you need to setup a
37 bridge in dom0 named xenbr0 in order to have a working network in
38 the guest domains. Please refer to the documentation of your Linux
39 distribution to know how to setup the bridge.
40 autoballoon
42 If you specify the amount of memory dom0 has, passing dom0_mem to
43 Xen, it is highly recommended to disable autoballoon. Edit
44 /etc/xen/xl.conf and set it to 0.
45 run xl as root
47 Most xl commands require root privileges to run due to the
48 communications channels used to talk to the hypervisor. Running as
49 non root will return an error.
50
52 Some global options are always available:
53 -v Verbose.
55 -N Dry run: do not actually execute the command.
57 -f Force execution: xl will refuse to run some commands if it detects
59 that xend is also running, this option will force the execution of
60 those commands, even though it is unsafe.
61 -t Always use carriage-return-based overwriting for displaying
63 progress messages without scrolling the screen. Without -t, this
64 is done only if stderr is a tty.
65 -T Include timestamps and pid of the xl process in output.
67
69 The following subcommands manipulate domains directly. As stated
70 previously, most commands take domain-id as the first parameter.
71 button-press domain-id button
73 This command is deprecated. Please use "xl trigger" instead.
74 Indicate an ACPI button press to the domain, where button can be
76 'power' or 'sleep'. This command is only available for HVM domains.
77 create [configfile] [OPTIONS]
79 The create subcommand takes a config file as its first argument:
80 see xl.cfg(5) for full details of the file format and possible
81 options. If configfile is missing xl creates the domain assuming
82 the default values for every option.
83 configfile has to be an absolute path to a file.
85 Create will return as soon as the domain is started. This does not
87 mean the guest OS in the domain has actually booted, or is
88 available for input.
89 If the -F option is specified, create will start the domain and not
91 return until its death.
92 OPTIONS
94 -q, --quiet
96 No console output.
97 -f=FILE, --defconfig=FILE
99 Use the given configuration file.
100 -p Leave the domain paused after it is created.
102 -F Run in foreground until death of the domain.
104 -V, --vncviewer
106 Attach to domain's VNC server, forking a vncviewer process.
107 -A, --vncviewer-autopass
109 Pass the VNC password to vncviewer via stdin.
110 -c Attach console to the domain as soon as it has started. This
112 is useful for determining issues with crashing domains and just
113 as a general convenience since you often want to watch the
114 domain boot.
115 key=value
117 It is possible to pass key=value pairs on the command line to
118 provide options as if they were written in the configuration
119 file; these override whatever is in the configfile.
120 NB: Many config options require characters such as quotes or
122 brackets which are interpreted by the shell (and often
123 discarded) before being passed to xl, resulting in xl being
124 unable to parse the value correctly. A simple work-around is
125 to put all extra options within a single set of quotes,
126 separated by semicolons. (See below for an example.)
127 EXAMPLES
129 with extra parameters
131 xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
132 This creates a domain with the file hvm.cfg, but additionally
134 pins it to cpus 0-3, and passes through two PCI devices.
135 config-update domain-id [configfile] [OPTIONS]
137 Update the saved configuration for a running domain. This has no
138 immediate effect but will be applied when the guest is next
139 restarted. This command is useful to ensure that runtime
140 modifications made to the guest will be preserved when the guest is
141 restarted.
142 Since Xen 4.5 xl has improved capabilities to handle dynamic domain
144 configuration changes and will preserve any changes made at runtime
145 when necessary. Therefore it should not normally be necessary to
146 use this command any more.
147 configfile has to be an absolute path to a file.
149 OPTIONS
151 -f=FILE, --defconfig=FILE
153 Use the given configuration file.
154 key=value
156 It is possible to pass key=value pairs on the command line to
157 provide options as if they were written in the configuration
158 file; these override whatever is in the configfile. Please see
159 the note under create on handling special characters when
160 passing key=value pairs on the command line.
161 console [OPTIONS] domain-id
163 Attach to the console of a domain specified by domain-id. If
164 you've set up your domains to have a traditional login console this
165 will look much like a normal text login screen.
166 Use the key combination Ctrl+] to detach from the domain console.
168 OPTIONS
170 -t [pv|serial]
172 Connect to a PV console or connect to an emulated serial
173 console. PV consoles are the only consoles available for PV
174 domains while HVM domains can have both. If this option is not
175 specified it defaults to emulated serial for HVM guests and PV
176 console for PV guests.
177 -n NUM
179 Connect to console number NUM. Console numbers start from 0.
180 destroy [OPTIONS] domain-id
182 Immediately terminate the domain specified by domain-id. This
183 doesn't give the domain OS any chance to react, and is the
184 equivalent of ripping the power cord out on a physical machine. In
185 most cases you will want to use the shutdown command instead.
186 OPTIONS
188 -f Allow domain 0 to be destroyed. Because a domain cannot
190 destroy itself, this is only possible when using a
191 disaggregated toolstack, and is most useful when using a
192 hardware domain separated from domain 0.
193 domid domain-name
195 Converts a domain name to a domain id.
196 domname domain-id
198 Converts a domain id to a domain name.
199 rename domain-id new-name
201 Change the domain name of a domain specified by domain-id to new-
202 name.
203 dump-core domain-id [filename]
205 Dumps the virtual machine's memory for the specified domain to the
206 filename specified, without pausing the domain. The dump file will
207 be written to a distribution specific directory for dump files, for
208 example: /var/lib/xen/dump/dump.
209 help [--long]
211 Displays the short help message (i.e. common commands) by default.
212 If the --long option is specified, it displays the complete set of
214 xl subcommands, grouped by function.
215 list [OPTIONS] [domain-id ...]
217 Displays information about one or more domains. If no domains are
218 specified it displays information about all domains.
219 OPTIONS
221 -l, --long
223 The output for xl list is not the table view shown below, but
224 instead presents the data as a JSON data structure.
225 -Z, --context
227 Also displays the security labels.
228 -v, --verbose
230 Also displays the domain UUIDs, the shutdown reason and
231 security labels.
232 -c, --cpupool
234 Also displays the cpupool the domain belongs to.
235 -n, --numa
237 Also displays the domain NUMA node affinity.
238 EXAMPLE
240 An example format for the list is as follows:
242 Name ID Mem VCPUs State Time(s)
244 Domain-0 0 750 4 r----- 11794.3
245 win 1 1019 1 r----- 0.3
246 linux 2 2048 2 r----- 5624.2
247 Name is the name of the domain. ID the numeric domain id. Mem is
249 the desired amount of memory to allocate to the domain (although it
250 may not be the currently allocated amount). VCPUs is the number of
251 virtual CPUs allocated to the domain. State is the run state (see
252 below). Time is the total run time of the domain as accounted for
253 by Xen.
254 STATES
256 The State field lists 6 states for a Xen domain, and which ones the
258 current domain is in.
259 r - running
261 The domain is currently running on a CPU.
262 b - blocked
264 The domain is blocked, and not running or runnable. This can
265 be because the domain is waiting on IO (a traditional wait
266 state) or has gone to sleep because there was nothing else for
267 it to do.
268 p - paused
270 The domain has been paused, usually occurring through the
271 administrator running xl pause. When in a paused state the
272 domain will still consume allocated resources (like memory),
273 but will not be eligible for scheduling by the Xen hypervisor.
274 s - shutdown
276 The guest OS has shut down (SCHEDOP_shutdown has been called)
277 but the domain is not dying yet.
278 c - crashed
280 The domain has crashed, which is always a violent ending.
281 Usually this state only occurs if the domain has been
282 configured not to restart on a crash. See xl.cfg(5) for more
283 info.
284 d - dying
286 The domain is in the process of dying, but hasn't completely
287 shut down or crashed.
288 NOTES
290 The Time column is deceptive. Virtual IO (network and block
292 devices) used by the domains requires coordination by Domain0,
293 which means that Domain0 is actually charged for much of the
294 time that a DomainU is doing IO. Use of this time value to
295 determine relative utilizations by domains is thus very
296 unreliable, as a high IO workload may show as less utilized
297 than a high CPU workload. Consider yourself warned.
298 mem-set domain-id mem
300 Set the target for the domain's balloon driver.
301 The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for
303 MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB).
304 This must be less than the initial maxmem parameter in the domain's
306 configuration.
307 Note that this operation requests the guest operating system's
309 balloon driver to reach the target amount of memory. The guest may
310 fail to reach that amount of memory for any number of reasons,
311 including:
312 • The guest doesn't have a balloon driver installed
314 • The guest's balloon driver is buggy
316 • The guest's balloon driver cannot create free guest memory due
318 to guest memory pressure
319 • The guest's balloon driver cannot allocate memory from Xen
321 because of hypervisor memory pressure
322 • The guest administrator has disabled the balloon driver
324 Warning: There is no good way to know in advance how small of a
326 mem-set will make a domain unstable and cause it to crash. Be very
327 careful when using this command on running domains.
328 mem-max domain-id mem
330 Specify the limit Xen will place on the amount of memory a guest
331 may allocate.
332 The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for
334 MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB).
335 NB that users normally shouldn't need this command; xl mem-set will
337 set this as appropriate automatically.
338 mem can't be set lower than the current memory target for domain-
340 id. It is allowed to be higher than the configured maximum memory
341 size of the domain (maxmem parameter in the domain's
342 configuration). Note however that the initial maxmem value is still
343 used as an upper limit for xl mem-set. Also note that calling xl
344 mem-set will reset this value.
345 The domain will not receive any signal regarding the changed memory
347 limit.
348 migrate [OPTIONS] domain-id host
350 Migrate a domain to another host machine. By default xl relies on
351 ssh as a transport mechanism between the two hosts.
352 OPTIONS
354 -s sshcommand
356 Use <sshcommand> instead of ssh. String will be passed to sh.
357 If empty, run <host> instead of ssh <host> xl migrate-receive
358 [-d -e].
359 -e On the new <host>, do not wait in the background for the death
361 of the domain. See the corresponding option of the create
362 subcommand.
363 -C config
365 Send the specified <config> file instead of the file used on
366 creation of the domain.
367 --debug
369 Display huge (!) amount of debug information during the
370 migration process.
371 -p Leave the domain on the receive side paused after migration.
373 -D Preserve the domain-id in the domain coniguration that is
375 transferred such that it will be identical on the destination
376 host, unless that configuration is overridden using the -C
377 option. Note that it is not possible to use this option for a
378 'localhost' migration.
379 remus [OPTIONS] domain-id host
381 Enable Remus HA or COLO HA for domain. By default xl relies on ssh
382 as a transport mechanism between the two hosts.
383 NOTES
385 Remus support in xl is still in experimental (proof-of-concept)
387 phase. Disk replication support is limited to DRBD disks.
388 COLO support in xl is still in experimental (proof-of-concept)
390 phase. All options are subject to change in the future.
391 COLO disk configuration looks like:
393 disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
395 The supported options are:
397 colo-host : Secondary host's ip address.
399 colo-port : Secondary host's port, we will run a nbd server on
400 the secondary host, and the nbd server will listen on this port.
401 colo-export : Nbd server's disk export name of the secondary host.
402 active-disk : Secondary's guest write will be buffered to this
403 disk, and it's used by the secondary.
404 hidden-disk : Primary's modified contents will be buffered in this
405 disk, and it's used by the secondary.
406 COLO network configuration looks like:
408 vif = [ '...,forwarddev=xxx,...']
410 The supported options are:
412 forwarddev : Forward devices for the primary and the secondary,
414 they are directly connected.
415 OPTIONS
417 -i MS
419 Checkpoint domain memory every MS milliseconds (default 200ms).
420 -u Disable memory checkpoint compression.
422 -s sshcommand
424 Use <sshcommand> instead of ssh. String will be passed to sh.
425 If empty, run <host> instead of ssh <host> xl migrate-receive
426 -r [-e].
427 -e On the new <host>, do not wait in the background for the death
429 of the domain. See the corresponding option of the create
430 subcommand.
431 -N netbufscript
433 Use <netbufscript> to setup network buffering instead of the
434 default script (/etc/xen/scripts/remus-netbuf-setup).
435 -F Run Remus in unsafe mode. Use this option with caution as
437 failover may not work as intended.
438 -b Replicate memory checkpoints to /dev/null (blackhole).
440 Generally useful for debugging. Requires enabling unsafe mode.
441 -n Disable network output buffering. Requires enabling unsafe
443 mode.
444 -d Disable disk replication. Requires enabling unsafe mode.
446 -c Enable COLO HA. This conflicts with -i and -b, and memory
448 checkpoint compression must be disabled.
449 -p Use userspace COLO Proxy. This option must be used in
451 conjunction with -c.
452 pause domain-id
454 Pause a domain. When in a paused state the domain will still
455 consume allocated resources (such as memory), but will not be
456 eligible for scheduling by the Xen hypervisor.
457 reboot [OPTIONS] domain-id
459 Reboot a domain. This acts just as if the domain had the reboot
460 command run from the console. The command returns as soon as it
461 has executed the reboot action, which may be significantly earlier
462 than when the domain actually reboots.
463 For HVM domains this requires PV drivers to be installed in your
465 guest OS. If PV drivers are not present but you have configured the
466 guest OS to behave appropriately you may be able to use the -F
467 option to trigger a reset button press.
468 The behavior of what happens to a domain when it reboots is set by
470 the on_reboot parameter of the domain configuration file when the
471 domain was created.
472 OPTIONS
474 -F If the guest does not support PV reboot control then fallback
476 to sending an ACPI power event (equivalent to the reset option
477 to trigger).
478 You should ensure that the guest is configured to behave as
480 expected in response to this event.
481 restore [OPTIONS] [configfile] checkpointfile
483 Build a domain from an xl save state file. See save for more info.
484 OPTIONS
486 -p Do not unpause the domain after restoring it.
488 -e Do not wait in the background for the death of the domain on
490 the new host. See the corresponding option of the create
491 subcommand.
492 -d Enable debug messages.
494 -V, --vncviewer
496 Attach to the domain's VNC server, forking a vncviewer process.
497 -A, --vncviewer-autopass
499 Pass the VNC password to vncviewer via stdin.
500 save [OPTIONS] domain-id checkpointfile [configfile]
502 Saves a running domain to a state file so that it can be restored
503 later. Once saved, the domain will no longer be running on the
504 system, unless the -c or -p options are used. xl restore restores
505 from this checkpoint file. Passing a config file argument allows
506 the user to manually select the VM config file used to create the
507 domain.
508 -c Leave the domain running after creating the snapshot.
510 -p Leave the domain paused after creating the snapshot.
512 -D Preserve the domain-id in the domain coniguration that is
514 embedded in the state file such that it will be identical when
515 the domain is restored, unless that configuration is
516 overridden. (See the restore operation above).
517 sharing [domain-id]
519 Display the number of shared pages for a specified domain. If no
520 domain is specified it displays information about all domains.
521 shutdown [OPTIONS] -a|domain-id
523 Gracefully shuts down a domain. This coordinates with the domain
524 OS to perform graceful shutdown, so there is no guarantee that it
525 will succeed, and may take a variable length of time depending on
526 what services must be shut down in the domain.
527 For HVM domains this requires PV drivers to be installed in your
529 guest OS. If PV drivers are not present but you have configured the
530 guest OS to behave appropriately you may be able to use the -F
531 option to trigger a power button press.
532 The command returns immediately after signaling the domain unless
534 the -w flag is used.
535 The behavior of what happens to a domain when it reboots is set by
537 the on_shutdown parameter of the domain configuration file when the
538 domain was created.
539 OPTIONS
541 -a, --all
543 Shutdown all guest domains. Often used when doing a complete
544 shutdown of a Xen system.
545 -w, --wait
547 Wait for the domain to complete shutdown before returning. If
548 given once, the wait is for domain shutdown or domain death.
549 If given multiple times, the wait is for domain death only.
550 -F If the guest does not support PV shutdown control then fallback
552 to sending an ACPI power event (equivalent to the power option
553 to trigger).
554 You should ensure that the guest is configured to behave as
556 expected in response to this event.
557 sysrq domain-id letter
559 Send a <Magic System Request> to the domain, each type of request
560 is represented by a different letter. It can be used to send SysRq
561 requests to Linux guests, see sysrq.txt in your Linux Kernel
562 sources for more information. It requires PV drivers to be
563 installed in your guest OS.
564 trigger domain-id nmi|reset|init|power|sleep|s3resume [VCPU]
566 Send a trigger to a domain, where the trigger can be: nmi, reset,
567 init, power or sleep. Optionally a specific vcpu number can be
568 passed as an argument. This command is only available for HVM
569 domains.
570 unpause domain-id
572 Moves a domain out of the paused state. This will allow a
573 previously paused domain to now be eligible for scheduling by the
574 Xen hypervisor.
575 vcpu-set domain-id vcpu-count
577 Enables the vcpu-count virtual CPUs for the domain in question.
578 Like mem-set, this command can only allocate up to the maximum
579 virtual CPU count configured at boot for the domain.
580 If the vcpu-count is smaller than the current number of active
582 VCPUs, the highest number VCPUs will be hotplug removed. This may
583 be important for pinning purposes.
584 Attempting to set the VCPUs to a number larger than the initially
586 configured VCPU count is an error. Trying to set VCPUs to < 1 will
587 be quietly ignored.
588 Some guests may need to actually bring the newly added CPU online
590 after vcpu-set, go to SEE ALSO section for information.
591 vcpu-list [domain-id]
593 Lists VCPU information for a specific domain. If no domain is
594 specified, VCPU information for all domains will be provided.
595 vcpu-pin [-f|--force] domain-id vcpu cpus hard cpus soft
597 Set hard and soft affinity for a vcpu of <domain-id>. Normally
598 VCPUs can float between available CPUs whenever Xen deems a
599 different run state is appropriate.
600 Hard affinity can be used to restrict this, by ensuring certain
602 VCPUs can only run on certain physical CPUs. Soft affinity
603 specifies a preferred set of CPUs. Soft affinity needs special
604 support in the scheduler, which is only provided in credit1.
605 The keyword all can be used to apply the hard and soft affinity
607 masks to all the VCPUs in the domain. The symbol '-' can be used to
608 leave either hard or soft affinity alone.
609 For example:
611 xl vcpu-pin 0 3 - 6-9
613 will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9,
615 leaving its hard affinity untouched. On the other hand:
616 xl vcpu-pin 0 3 3,4 6-9
618 will set both hard and soft affinity, the former to pCPUs 3 and 4,
620 the latter to pCPUs 6,7,8, and 9.
621 Specifying -f or --force will remove a temporary pinning done by
623 the operating system (normally this should be done by the operating
624 system). In case a temporary pinning is active for a vcpu the
625 affinity of this vcpu can't be changed without this option.
626 vm-list
628 Prints information about guests. This list excludes information
629 about service or auxiliary domains such as dom0 and stubdoms.
630 EXAMPLE
632 An example format for the list is as follows:
634 UUID ID name
636 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win
637 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux
638 vncviewer [OPTIONS] domain-id
640 Attach to the domain's VNC server, forking a vncviewer process.
641 OPTIONS
643 --autopass
645 Pass the VNC password to vncviewer via stdin.
646
648 debug-keys keys
649 Send debug keys to Xen. It is the same as pressing the Xen
650 "conswitch" (Ctrl-A by default) three times and then pressing
651 "keys".
652 set-parameters params
654 Set hypervisor parameters as specified in params. This allows for
655 some boot parameters of the hypervisor to be modified in the
656 running systems.
657 dmesg [OPTIONS]
659 Reads the Xen message buffer, similar to dmesg on a Linux system.
660 The buffer contains informational, warning, and error messages
661 created during Xen's boot process. If you are having problems with
662 Xen, this is one of the first places to look as part of problem
663 determination.
664 OPTIONS
666 -c, --clear
668 Clears Xen's message buffer.
669 info [OPTIONS]
671 Print information about the Xen host in name : value format. When
672 reporting a Xen bug, please provide this information as part of the
673 bug report. See
674 https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project
675 on how to report Xen bugs.
676 Sample output looks as follows:
678 host : scarlett
680 release : 3.1.0-rc4+
681 version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011
682 machine : x86_64
683 nr_cpus : 4
684 nr_nodes : 1
685 cores_per_socket : 4
686 threads_per_core : 1
687 cpu_mhz : 2266
688 hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000
689 virt_caps : hvm hvm_directio
690 total_memory : 6141
691 free_memory : 4274
692 free_cpus : 0
693 outstanding_claims : 0
694 xen_major : 4
695 xen_minor : 2
696 xen_extra : -unstable
697 xen_caps : xen-3.0-x86_64 xen-3.0-x86_32p hvm-3.0-x86_32 hvm-3.0-x86_32p hvm-3.0-x86_64
698 xen_scheduler : credit
699 xen_pagesize : 4096
700 platform_params : virt_start=0xffff800000000000
701 xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241
702 xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1
703 cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8)
704 cc_compile_by : sstabellini
705 cc_compile_domain : uk.xensource.com
706 cc_compile_date : Tue Nov 8 12:03:05 UTC 2011
707 xend_config_format : 4
708 FIELDS
710 Not all fields will be explained here, but some of the less obvious
712 ones deserve explanation:
713 hw_caps
715 A vector showing what hardware capabilities are supported by
716 your processor. This is equivalent to, though more cryptic,
717 the flags field in /proc/cpuinfo on a normal Linux machine:
718 they both derive from the feature bits returned by the cpuid
719 command on x86 platforms.
720 free_memory
722 Available memory (in MB) not allocated to Xen, or any other
723 domains, or claimed for domains.
724 outstanding_claims
726 When a claim call is done (see xl.conf(5)) a reservation for a
727 specific amount of pages is set and also a global value is
728 incremented. This global value (outstanding_claims) is then
729 reduced as the domain's memory is populated and eventually
730 reaches zero. Most of the time the value will be zero, but if
731 you are launching multiple guests, and claim_mode is enabled,
732 this value can increase/decrease. Note that the value also
733 affects the free_memory - as it will reflect the free memory in
734 the hypervisor minus the outstanding pages claimed for guests.
735 See xl info claims parameter for detailed listing.
736 xen_caps
738 The Xen version and architecture. Architecture values can be
739 one of: x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
740 xen_changeset
742 The Xen mercurial changeset id. Very useful for determining
743 exactly what version of code your Xen system was built from.
744 OPTIONS
746 -n, --numa
748 List host NUMA topology information
749 top Executes the xentop(1) command, which provides real time monitoring
751 of domains. Xentop has a curses interface, and is reasonably self
752 explanatory.
753 uptime
755 Prints the current uptime of the domains running.
756 claims
758 Prints information about outstanding claims by the guests. This
759 provides the outstanding claims and currently populated memory
760 count for the guests. These values added up reflect the global
761 outstanding claim value, which is provided via the info argument,
762 outstanding_claims value. The Mem column has the cumulative value
763 of outstanding claims and the total amount of memory that has been
764 right now allocated to the guest.
765 EXAMPLE
767 An example format for the list is as follows:
769 Name ID Mem VCPUs State Time(s) Claimed
771 Domain-0 0 2047 4 r----- 19.7 0
772 OL5 2 2048 1 --p--- 0.0 847
773 OL6 3 1024 4 r----- 5.9 0
774 Windows_XP 4 2047 1 --p--- 0.0 1989
775 In which it can be seen that the OL5 guest still has 847MB of
777 claimed memory (out of the total 2048MB where 1191MB has been
778 allocated to the guest).
779
781 Xen ships with a number of domain schedulers, which can be set at boot
782 time with the sched= parameter on the Xen command line. By default
783 credit is used for scheduling.
784 sched-credit [OPTIONS]
786 Set or get credit (aka credit1) scheduler parameters. The credit
787 scheduler is a proportional fair share CPU scheduler built from the
788 ground up to be work conserving on SMP hosts.
789 Each domain (including Domain0) is assigned a weight and a cap.
791 OPTIONS
793 -d DOMAIN, --domain=DOMAIN
795 Specify domain for which scheduler parameters are to be
796 modified or retrieved. Mandatory for modifying scheduler
797 parameters.
798 -w WEIGHT, --weight=WEIGHT
800 A domain with a weight of 512 will get twice as much CPU as a
801 domain with a weight of 256 on a contended host. Legal weights
802 range from 1 to 65535 and the default is 256.
803 -c CAP, --cap=CAP
805 The cap optionally fixes the maximum amount of CPU a domain
806 will be able to consume, even if the host system has idle CPU
807 cycles. The cap is expressed in percentage of one physical CPU:
808 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
809 The default, 0, means there is no upper cap.
810 NB: Many systems have features that will scale down the
812 computing power of a cpu that is not 100% utilized. This can
813 be in the operating system, but can also sometimes be below the
814 operating system in the BIOS. If you set a cap such that
815 individual cores are running at less than 100%, this may have
816 an impact on the performance of your workload over and above
817 the impact of the cap. For example, if your processor runs at
818 2GHz, and you cap a vm at 50%, the power management system may
819 also reduce the clock speed to 1GHz; the effect will be that
820 your VM gets 25% of the available power (50% of 1GHz) rather
821 than 50% (50% of 2GHz). If you are not getting the performance
822 you expect, look at performance and cpufreq options in your
823 operating system and your BIOS.
824 -p CPUPOOL, --cpupool=CPUPOOL
826 Restrict output to domains in the specified cpupool.
827 -s, --schedparam
829 Specify to list or set pool-wide scheduler parameters.
830 -t TSLICE, --tslice_ms=TSLICE
832 Timeslice tells the scheduler how long to allow VMs to run
833 before pre-empting. The default is 30ms. Valid ranges are 1ms
834 to 1000ms. The length of the timeslice (in ms) must be higher
835 than the length of the ratelimit (see below).
836 -r RLIMIT, --ratelimit_us=RLIMIT
838 Ratelimit attempts to limit the number of schedules per second.
839 It sets a minimum amount of time (in microseconds) a VM must
840 run before we will allow a higher-priority VM to pre-empt it.
841 The default value is 1000 microseconds (1ms). Valid range is
842 100 to 500000 (500ms). The ratelimit length must be lower than
843 the timeslice length.
844 -m DELAY, --migration_delay_us=DELAY
846 Migration delay specifies for how long a vCPU, after it stopped
847 running should be considered "cache-hot". Basically, if less
848 than DELAY us passed since when the vCPU was executing on a
849 CPU, it is likely that most of the vCPU's working set is still
850 in the CPU's cache, and therefore the vCPU is not migrated.
851 Default is 0. Maximum is 100 ms. This can be effective at
853 preventing vCPUs to bounce among CPUs too quickly, but, at the
854 same time, the scheduler stops being fully work-conserving.
855 COMBINATION
857 The following is the effect of combining the above options:
859 <nothing> : List all domain params and sched params
861 from all pools
862 -d [domid] : List domain params for domain [domid]
863 -d [domid] [params] : Set domain params for domain [domid]
864 -p [pool] : list all domains and sched params for
865 [pool]
866 -s : List sched params for poolid 0
867 -s [params] : Set sched params for poolid 0
868 -p [pool] -s : List sched params for [pool]
869 -p [pool] -s [params] : Set sched params for [pool]
870 -p [pool] -d... : Illegal
871 sched-credit2 [OPTIONS]
872 Set or get credit2 scheduler parameters. The credit2 scheduler is
873 a proportional fair share CPU scheduler built from the ground up to
874 be work conserving on SMP hosts.
875 Each domain (including Domain0) is assigned a weight.
877 OPTIONS
879 -d DOMAIN, --domain=DOMAIN
881 Specify domain for which scheduler parameters are to be
882 modified or retrieved. Mandatory for modifying scheduler
883 parameters.
884 -w WEIGHT, --weight=WEIGHT
886 A domain with a weight of 512 will get twice as much CPU as a
887 domain with a weight of 256 on a contended host. Legal weights
888 range from 1 to 65535 and the default is 256.
889 -p CPUPOOL, --cpupool=CPUPOOL
891 Restrict output to domains in the specified cpupool.
892 -s, --schedparam
894 Specify to list or set pool-wide scheduler parameters.
895 -r RLIMIT, --ratelimit_us=RLIMIT
897 Attempts to limit the rate of context switching. It is
898 basically the same as --ratelimit_us in sched-credit
899 sched-rtds [OPTIONS]
901 Set or get rtds (Real Time Deferrable Server) scheduler parameters.
902 This rt scheduler applies Preemptive Global Earliest Deadline First
903 real-time scheduling algorithm to schedule VCPUs in the system.
904 Each VCPU has a dedicated period, budget and extratime. While
905 scheduled, a VCPU burns its budget. A VCPU has its budget
906 replenished at the beginning of each period; Unused budget is
907 discarded at the end of each period. A VCPU with extratime set
908 gets extra time from the unreserved system resource.
909 OPTIONS
911 -d DOMAIN, --domain=DOMAIN
913 Specify domain for which scheduler parameters are to be
914 modified or retrieved. Mandatory for modifying scheduler
915 parameters.
916 -v VCPUID/all, --vcpuid=VCPUID/all
918 Specify vcpu for which scheduler parameters are to be modified
919 or retrieved.
920 -p PERIOD, --period=PERIOD
922 Period of time, in microseconds, over which to replenish the
923 budget.
924 -b BUDGET, --budget=BUDGET
926 Amount of time, in microseconds, that the VCPU will be allowed
927 to run every period.
928 -e Extratime, --extratime=Extratime
930 Binary flag to decide if the VCPU will be allowed to get extra
931 time from the unreserved system resource.
932 -c CPUPOOL, --cpupool=CPUPOOL
934 Restrict output to domains in the specified cpupool.
935 EXAMPLE
937 1) Use -v all to see the budget and period of all the VCPUs of
939 all the domains:
940 xl sched-rtds -v all
942 Cpupool Pool-0: sched=RTDS
943 Name ID VCPU Period Budget Extratime
944 Domain-0 0 0 10000 4000 yes
945 vm1 2 0 300 150 yes
946 vm1 2 1 400 200 yes
947 vm1 2 2 10000 4000 yes
948 vm1 2 3 1000 500 yes
949 vm2 4 0 10000 4000 yes
950 vm2 4 1 10000 4000 yes
951 Without any arguments, it will output the default scheduling
953 parameters for each domain:
954 xl sched-rtds
956 Cpupool Pool-0: sched=RTDS
957 Name ID Period Budget Extratime
958 Domain-0 0 10000 4000 yes
959 vm1 2 10000 4000 yes
960 vm2 4 10000 4000 yes
961 2) Use, for instance, -d vm1, -v all to see the budget and
963 period of all VCPUs of a specific domain (vm1):
964 xl sched-rtds -d vm1 -v all
966 Name ID VCPU Period Budget Extratime
967 vm1 2 0 300 150 yes
968 vm1 2 1 400 200 yes
969 vm1 2 2 10000 4000 yes
970 vm1 2 3 1000 500 yes
971 To see the parameters of a subset of the VCPUs of a domain,
973 use:
974 xl sched-rtds -d vm1 -v 0 -v 3
976 Name ID VCPU Period Budget Extratime
977 vm1 2 0 300 150 yes
978 vm1 2 3 1000 500 yes
979 If no -v is specified, the default scheduling parameters for
981 the domain are shown:
982 xl sched-rtds -d vm1
984 Name ID Period Budget Extratime
985 vm1 2 10000 4000 yes
986 3) Users can set the budget and period of multiple VCPUs of a
988 specific domain with only one command, e.g., "xl sched-rtds -d
989 vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0".
990 To change the parameters of all the VCPUs of a domain, use -v
992 all, e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1".
993
995 Xen can group the physical cpus of a server in cpu-pools. Each physical
996 CPU is assigned at most to one cpu-pool. Domains are each restricted to
997 a single cpu-pool. Scheduling does not cross cpu-pool boundaries, so
998 each cpu-pool has its own scheduler. Physical cpus and domains can be
999 moved from one cpu-pool to another only by an explicit command. Cpu-
1000 pools can be specified either by name or by id.
1001 cpupool-create [OPTIONS] [configfile] [variable=value ...]
1003 Create a cpu pool based an config from a configfile or command-line
1004 parameters. Variable settings from the configfile may be altered
1005 by specifying new or additional assignments on the command line.
1006 See the xlcpupool.cfg(5) manpage for more information.
1008 OPTIONS
1010 -f=FILE, --defconfig=FILE
1012 Use the given configuration file.
1013 cpupool-list [OPTIONS] [cpu-pool]
1015 List CPU pools on the host.
1016 OPTIONS
1018 -c, --cpus
1020 If this option is specified, xl prints a list of CPUs used by
1021 cpu-pool.
1022 cpupool-destroy cpu-pool
1024 Deactivates a cpu pool. This is possible only if no domain is
1025 active in the cpu-pool.
1026 cpupool-rename cpu-pool <newname>
1028 Renames a cpu-pool to newname.
1029 cpupool-cpu-add cpu-pool cpus|node:nodes
1031 Adds one or more CPUs or NUMA nodes to cpu-pool. CPUs and NUMA
1032 nodes can be specified as single CPU/node IDs or as ranges.
1033 For example:
1035 (a) xl cpupool-cpu-add mypool 4
1037 (b) xl cpupool-cpu-add mypool 1,5,10-16,^13
1038 (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8
1039 means adding CPU 4 to mypool, in (a); adding CPUs
1041 1,5,10,11,12,14,15 and 16, in (b); and adding all the CPUs of NUMA
1042 nodes 0, 2 and 3, plus CPU 8, but keeping out CPUs 10,11,12, in
1043 (c).
1044 All the specified CPUs that can be added to the cpupool will be
1046 added to it. If some CPU can't (e.g., because they're already part
1047 of another cpupool), an error is reported about each one of them.
1048 cpupool-cpu-remove cpu-pool cpus|node:nodes
1050 Removes one or more CPUs or NUMA nodes from cpu-pool. CPUs and NUMA
1051 nodes can be specified as single CPU/node IDs or as ranges, using
1052 the exact same syntax as in cpupool-cpu-add above.
1053 cpupool-migrate domain-id cpu-pool
1055 Moves a domain specified by domain-id or domain-name into a cpu-
1056 pool. Domain-0 can't be moved to another cpu-pool.
1057 cpupool-numa-split
1059 Splits up the machine into one cpu-pool per numa node.
1060
1062 Most virtual devices can be added and removed while guests are running,
1063 assuming that the necessary support exists in the guest OS. The effect
1064 to the guest OS is much the same as any hotplug event.
1065 BLOCK DEVICES
1067 block-attach domain-id disc-spec-component(s) ...
1068 Create a new virtual block device and attach it to the specified
1069 domain. A disc specification is in the same format used for the
1070 disk variable in the domain config file. See
1071 xl-disk-configuration(5). This will trigger a hotplug event for the
1072 guest.
1073 Note that only PV block devices are supported by block-attach.
1075 Requests to attach emulated devices (eg, vdev=hdc) will result in
1076 only the PV view being available to the guest.
1077 block-detach [OPTIONS] domain-id devid
1079 Detach a domain's virtual block device. devid may be the symbolic
1080 name or the numeric device id given to the device by domain 0. You
1081 will need to run xl block-list to determine that number.
1082 Detaching the device requires the cooperation of the domain. If
1084 the domain fails to release the device (perhaps because the domain
1085 is hung or is still using the device), the detach will fail.
1086 OPTIONS
1088 --force
1090 If this parameter is specified the device will be forcefully
1091 detached, which may cause IO errors in the domain and possibly
1092 a guest crash
1093 block-list domain-id
1095 List virtual block devices for a domain.
1096 cd-insert domain-id virtualdevice target
1098 Insert a cdrom into a guest domain's existing virtual cd drive. The
1099 virtual drive must already exist but can be empty. How the device
1100 should be presented to the guest domain is specified by the
1101 virtualdevice parameter; for example "hdc". Parameter target is the
1102 target path in the backend domain (usually domain 0) to be
1103 exported; can be a block device or a file etc. See target in
1104 xl-disk-configuration(5).
1105 Only works with HVM domains.
1107 cd-eject domain-id virtualdevice
1109 Eject a cdrom from a guest domain's virtual cd drive, specified by
1110 virtualdevice. Only works with HVM domains.
1111 NETWORK DEVICES
1113 network-attach domain-id network-device
1114 Creates a new network device in the domain specified by domain-id.
1115 network-device describes the device to attach, using the same
1116 format as the vif string in the domain config file. See xl.cfg(5)
1117 and xl-network-configuration(5) for more information.
1118 Note that only attaching PV network interfaces is supported.
1120 network-detach domain-id devid|mac
1122 Removes the network device from the domain specified by domain-id.
1123 devid is the virtual interface device number within the domain
1124 (i.e. the 3 in vif22.3). Alternatively, the mac address can be used
1125 to select the virtual interface to detach.
1126 network-list domain-id
1128 List virtual network interfaces for a domain.
1129 CHANNEL DEVICES
1131 channel-list domain-id
1132 List virtual channel interfaces for a domain.
1133 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES
1135 vtpm-attach domain-id vtpm-device
1136 Creates a new vtpm (virtual Trusted Platform Module) device in the
1137 domain specified by domain-id. vtpm-device describes the device to
1138 attach, using the same format as the vtpm string in the domain
1139 config file. See xl.cfg(5) for more information.
1140 vtpm-detach domain-id devid|uuid
1142 Removes the vtpm device from the domain specified by domain-id.
1143 devid is the numeric device id given to the virtual Trusted
1144 Platform Module device. You will need to run xl vtpm-list to
1145 determine that number. Alternatively, the uuid of the vtpm can be
1146 used to select the virtual device to detach.
1147 vtpm-list domain-id
1149 List virtual Trusted Platform Modules for a domain.
1150 VDISPL DEVICES
1152 vdispl-attach domain-id vdispl-device
1153 Creates a new vdispl device in the domain specified by domain-id.
1154 vdispl-device describes the device to attach, using the same format
1155 as the vdispl string in the domain config file. See xl.cfg(5) for
1156 more information.
1157 NOTES
1159 As in vdispl-device string semicolon is used then put quotes or
1161 escaping when using from the shell.
1162 EXAMPLE
1164 xl vdispl-attach DomU
1166 connectors='id0:1920x1080;id1:800x600;id2:640x480'
1167 or
1169 xl vdispl-attach DomU
1171 connectors=id0:1920x1080\;id1:800x600\;id2:640x480
1172 vdispl-detach domain-id dev-id
1174 Removes the vdispl device specified by dev-id from the domain
1175 specified by domain-id.
1176 vdispl-list domain-id
1178 List virtual displays for a domain.
1179 VSND DEVICES
1181 vsnd-attach domain-id vsnd-item vsnd-item ...
1182 Creates a new vsnd device in the domain specified by domain-id.
1183 vsnd-item's describe the vsnd device to attach, using the same
1184 format as the VSND_ITEM_SPEC string in the domain config file. See
1185 xl.cfg(5) for more information.
1186 EXAMPLE
1188 xl vsnd-attach DomU 'CARD, short-name=Main,
1190 sample-formats=s16_le;s8;u32_be' 'PCM, name=Main' 'STREAM,
1191 id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
1192 vsnd-detach domain-id dev-id
1194 Removes the vsnd device specified by dev-id from the domain
1195 specified by domain-id.
1196 vsnd-list domain-id
1198 List vsnd devices for a domain.
1199 KEYBOARD DEVICES
1201 vkb-attach domain-id vkb-device
1202 Creates a new keyboard device in the domain specified by domain-id.
1203 vkb-device describes the device to attach, using the same format as
1204 the VKB_SPEC_STRING string in the domain config file. See xl.cfg(5)
1205 for more information.
1206 vkb-detach domain-id devid
1208 Removes the keyboard device from the domain specified by domain-id.
1209 devid is the virtual interface device number within the domain
1210 vkb-list domain-id
1212 List virtual network interfaces for a domain.
1213
1215 pci-assignable-list [-n]
1216 List all the BDF of assignable PCI devices. See
1217 xl-pci-configuration(5) for more information. If the -n option is
1218 specified then any name supplied when the device was made
1219 assignable will also be displayed.
1220 These are devices in the system which are configured to be
1222 available for passthrough and are bound to a suitable PCI backend
1223 driver in domain 0 rather than a real driver.
1224 pci-assignable-add [-n NAME] BDF
1226 Make the device at BDF assignable to guests. See
1227 xl-pci-configuration(5) for more information. If the -n option is
1228 supplied then the assignable device entry will the named with the
1229 given NAME.
1230 This will bind the device to the pciback driver and assign it to
1232 the "quarantine domain". If it is already bound to a driver, it
1233 will first be unbound, and the original driver stored so that it
1234 can be re-bound to the same driver later if desired. If the device
1235 is already bound, it will assign it to the quarantine domain and
1236 return success.
1237 CAUTION: This will make the device unusable by Domain 0 until it is
1239 returned with pci-assignable-remove. Care should therefore be
1240 taken not to do this on a device critical to domain 0's operation,
1241 such as storage controllers, network interfaces, or GPUs that are
1242 currently being used.
1243 pci-assignable-remove [-r] BDF|NAME
1245 Make a device non-assignable to guests. The device may be
1246 identified either by its BDF or the NAME supplied when the device
1247 was made assignable. See xl-pci-configuration(5) for more
1248 information.
1249 This will at least unbind the device from pciback, and re-assign it
1251 from the "quarantine domain" back to domain 0. If the -r option is
1252 specified, it will also attempt to re-bind the device to its
1253 original driver, making it usable by Domain 0 again. If the device
1254 is not bound to pciback, it will return success.
1255 Note that this functionality will work even for devices which were
1257 not made assignable by pci-assignable-add. This can be used to
1258 allow dom0 to access devices which were automatically quarantined
1259 by Xen after domain destruction as a result of Xen's
1260 iommu=quarantine command-line default.
1261 As always, this should only be done if you trust the guest, or are
1263 confident that the particular device you're re-assigning to dom0
1264 will cancel all in-flight DMA on FLR.
1265 pci-attach domain-id PCI_SPEC_STRING
1267 Hot-plug a new pass-through pci device to the specified domain. See
1268 xl-pci-configuration(5) for more information.
1269 pci-detach [OPTIONS] domain-id PCI_SPEC_STRING
1271 Hot-unplug a pci device that was previously passed through to a
1272 domain. See xl-pci-configuration(5) for more information.
1273 OPTIONS
1275 -f If this parameter is specified, xl is going to forcefully
1277 remove the device even without guest domain's collaboration.
1278 pci-list domain-id
1280 List the BDF of pci devices passed through to a domain.
1281
1283 usbctrl-attach domain-id usbctrl-device
1284 Create a new USB controller in the domain specified by domain-id,
1285 usbctrl-device describes the device to attach, using form
1286 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1287 the usbctrl description in the domain config file. See xl.cfg(5)
1288 for more information.
1289 usbctrl-detach domain-id devid
1291 Destroy a USB controller from the specified domain. devid is devid
1292 of the USB controller.
1293 usbdev-attach domain-id usbdev-device
1295 Hot-plug a new pass-through USB device to the domain specified by
1296 domain-id, usbdev-device describes the device to attach, using form
1297 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1298 the usbdev description in the domain config file. See xl.cfg(5)
1299 for more information.
1300 usbdev-detach domain-id controller=devid port=number
1302 Hot-unplug a previously assigned USB device from a domain.
1303 controller=devid and port=number is USB controller:port in the
1304 guest domain the USB device is attached to.
1305 usb-list domain-id
1307 List pass-through usb devices for a domain.
1308
1310 qemu-monitor-command domain-id command
1311 Issue a monitor command to the device model of the domain specified
1312 by domain-id. command can be any valid command qemu understands.
1313 This can be e.g. used to add non-standard devices or devices with
1314 non-standard parameters to a domain. The output of the command is
1315 printed to stdout.
1316 Warning: This qemu monitor access is provided for convenience when
1318 debugging, troubleshooting, and experimenting. Its use is not
1319 supported by the Xen Project.
1320 Specifically, not all information displayed by the qemu monitor
1322 will necessarily be accurate or complete, because in a Xen system
1323 qemu does not have a complete view of the guest.
1324 Furthermore, modifying the guest's setup via the qemu monitor may
1326 conflict with the Xen toolstack's assumptions. Resulting problems
1327 may include, but are not limited to: guest crashes; toolstack error
1328 messages; inability to migrate the guest; and security
1329 vulnerabilities which are not covered by the Xen Project security
1330 response policy.
1331 EXAMPLE
1333 Obtain information of USB devices connected as such via the device
1335 model (only!) to a domain:
1336 xl qemu-monitor-command vm1 'info usb'
1338 Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
1339
1341 FLASK is a security framework that defines a mandatory access control
1342 policy providing fine-grained controls over Xen domains, allowing the
1343 policy writer to define what interactions between domains, devices, and
1344 the hypervisor are permitted. Some example of what you can do using
1345 XSM/FLASK:
1346 - Prevent two domains from communicating via event channels or grants
1347 - Control which domains can use device passthrough (and which devices)
1348 - Restrict or audit operations performed by privileged domains
1349 - Prevent a privileged domain from arbitrarily mapping pages from
1350 other
1351 domains.
1352 You can find more details on how to use FLASK and an example security
1354 policy here:
1355 <https://xenbits.xenproject.org/docs/unstable/misc/xsm-flask.txt>
1356 getenforce
1358 Determine if the FLASK security module is loaded and enforcing its
1359 policy.
1360 setenforce 1|0|Enforcing|Permissive
1362 Enable or disable enforcing of the FLASK access controls. The
1363 default is permissive, but this can be changed to enforcing by
1364 specifying "flask=enforcing" or "flask=late" on the hypervisor's
1365 command line.
1366 loadpolicy policy-file
1368 Load FLASK policy from the given policy file. The initial policy is
1369 provided to the hypervisor as a multiboot module; this command
1370 allows runtime updates to the policy. Loading new security policy
1371 will reset runtime changes to device labels.
1372
1374 Intel Haswell and later server platforms offer shared resource
1375 monitoring and control technologies. The availability of these
1376 technologies and the hardware capabilities can be shown with psr-
1377 hwinfo.
1378 See <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html> for
1380 more information.
1381 psr-hwinfo [OPTIONS]
1383 Show Platform Shared Resource (PSR) hardware information.
1384 OPTIONS
1386 -m, --cmt
1388 Show Cache Monitoring Technology (CMT) hardware information.
1389 -a, --cat
1391 Show Cache Allocation Technology (CAT) hardware information.
1392 CACHE MONITORING TECHNOLOGY
1394 Intel Haswell and later server platforms offer monitoring capability in
1395 each logical processor to measure specific platform shared resource
1396 metric, for example, L3 cache occupancy. In the Xen implementation, the
1397 monitoring granularity is domain level. To monitor a specific domain,
1398 just attach the domain id with the monitoring service. When the domain
1399 doesn't need to be monitored any more, detach the domain id from the
1400 monitoring service.
1401 Intel Broadwell and later server platforms also offer total/local
1403 memory bandwidth monitoring. Xen supports per-domain monitoring for
1404 these two additional monitoring types. Both memory bandwidth monitoring
1405 and L3 cache occupancy monitoring share the same set of underlying
1406 monitoring service. Once a domain is attached to the monitoring
1407 service, monitoring data can be shown for any of these monitoring
1408 types.
1409 There is no cache monitoring and memory bandwidth monitoring on L2
1411 cache so far.
1412 psr-cmt-attach domain-id
1414 attach: Attach the platform shared resource monitoring service to a
1415 domain.
1416 psr-cmt-detach domain-id
1418 detach: Detach the platform shared resource monitoring service from
1419 a domain.
1420 psr-cmt-show psr-monitor-type [domain-id]
1422 Show monitoring data for a certain domain or all domains. Current
1423 supported monitor types are:
1424 - "cache-occupancy": showing the L3 cache occupancy(KB).
1425 - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
1426 - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
1427 CACHE ALLOCATION TECHNOLOGY
1429 Intel Broadwell and later server platforms offer capabilities to
1430 configure and make use of the Cache Allocation Technology (CAT)
1431 mechanisms, which enable more cache resources (i.e. L3/L2 cache) to be
1432 made available for high priority applications. In the Xen
1433 implementation, CAT is used to control cache allocation on VM basis. To
1434 enforce cache on a specific domain, just set capacity bitmasks (CBM)
1435 for the domain.
1436 Intel Broadwell and later server platforms also offer Code/Data
1438 Prioritization (CDP) for cache allocations, which support specifying
1439 code or data cache for applications. CDP is used on a per VM basis in
1440 the Xen implementation. To specify code or data CBM for the domain, CDP
1441 feature must be enabled and CBM type options need to be specified when
1442 setting CBM, and the type options (code and data) are mutually
1443 exclusive. There is no CDP support on L2 so far.
1444 psr-cat-set [OPTIONS] domain-id cbm
1446 Set cache capacity bitmasks(CBM) for a domain. For how to specify
1447 cbm please refer to
1448 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>.
1449 OPTIONS
1451 -s SOCKET, --socket=SOCKET
1453 Specify the socket to process, otherwise all sockets are
1454 processed.
1455 -l LEVEL, --level=LEVEL
1457 Specify the cache level to process, otherwise the last level
1458 cache (L3) is processed.
1459 -c, --code
1461 Set code CBM when CDP is enabled.
1462 -d, --data
1464 Set data CBM when CDP is enabled.
1465 psr-cat-show [OPTIONS] [domain-id]
1467 Show CAT settings for a certain domain or all domains.
1468 OPTIONS
1470 -l LEVEL, --level=LEVEL
1472 Specify the cache level to process, otherwise the last level
1473 cache (L3) is processed.
1474 Memory Bandwidth Allocation
1476 Intel Skylake and later server platforms offer capabilities to
1477 configure and make use of the Memory Bandwidth Allocation (MBA)
1478 mechanisms, which provides OS/VMMs the ability to slow misbehaving
1479 apps/VMs by using a credit-based throttling mechanism. In the Xen
1480 implementation, MBA is used to control memory bandwidth on VM basis. To
1481 enforce bandwidth on a specific domain, just set throttling value
1482 (THRTL) for the domain.
1483 psr-mba-set [OPTIONS] domain-id thrtl
1485 Set throttling value (THRTL) for a domain. For how to specify thrtl
1486 please refer to
1487 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>.
1488 OPTIONS
1490 -s SOCKET, --socket=SOCKET
1492 Specify the socket to process, otherwise all sockets are
1493 processed.
1494 psr-mba-show [domain-id]
1496 Show MBA settings for a certain domain or all domains. For linear
1497 mode, it shows the decimal value. For non-linear mode, it shows
1498 hexadecimal value.
1499
1501 xl is mostly command-line compatible with the old xm utility used with
1502 the old Python xend. For compatibility, the following options are
1503 ignored:
1504 xl migrate --live
1506
1508 The following man pages:
1509 xl.cfg(5), xlcpupool.cfg(5), xentop(1), xl-disk-configuration(5)
1511 xl-network-configuration(5)
1512 And the following documents on the xenproject.org website:
1514 <https://xenbits.xenproject.org/docs/unstable/misc/xsm-flask.txt>
1516 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>
1517 For systems that don't automatically bring the CPU online:
1519 <https://wiki.xenproject.org/wiki/Paravirt_Linux_CPU_Hotplug>
1521
1523 Send bugs to xen-devel@lists.xenproject.org, see
1524 https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project on
1525 how to send bug reports.
15264.15.1 2021-11-23 xl(1)