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
67 The following subcommands manipulate domains directly. As stated
68 previously, most commands take domain-id as the first parameter.
69 button-press domain-id button
71 This command is deprecated. Please use "xl trigger" instead.
72 Indicate an ACPI button press to the domain, where button can be
74 'power' or 'sleep'. This command is only available for HVM domains.
75 create [configfile] [OPTIONS]
77 The create subcommand takes a config file as its first argument:
78 see xl.cfg(5) for full details of the file format and possible
79 options. If configfile is missing xl creates the domain assuming
80 the default values for every option.
81 configfile has to be an absolute path to a file.
83 Create will return as soon as the domain is started. This does not
85 mean the guest OS in the domain has actually booted, or is
86 available for input.
87 If the -F option is specified, create will start the domain and not
89 return until its death.
90 OPTIONS
92 -q, --quiet
94 No console output.
95 -f=FILE, --defconfig=FILE
97 Use the given configuration file.
98 -p Leave the domain paused after it is created.
100 -F Run in foreground until death of the domain.
102 -V, --vncviewer
104 Attach to domain's VNC server, forking a vncviewer process.
105 -A, --vncviewer-autopass
107 Pass the VNC password to vncviewer via stdin.
108 -c Attach console to the domain as soon as it has started. This
110 is useful for determining issues with crashing domains and just
111 as a general convenience since you often want to watch the
112 domain boot.
113 key=value
115 It is possible to pass key=value pairs on the command line to
116 provide options as if they were written in the configuration
117 file; these override whatever is in the configfile.
118 NB: Many config options require characters such as quotes or
120 brackets which are interpreted by the shell (and often
121 discarded) before being passed to xl, resulting in xl being
122 unable to parse the value correctly. A simple work-around is
123 to put all extra options within a single set of quotes,
124 separated by semicolons. (See below for an example.)
125 EXAMPLES
127 with config file
129 xl create DebianLenny
130 This creates a domain with the file /etc/xen/DebianLenny, and
132 returns as soon as it is run.
133 with extra parameters
135 xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
136 This creates a domain with the file hvm.cfg, but additionally
138 pins it to cpus 0-3, and passes through two PCI devices.
139 config-update domain-id [configfile] [OPTIONS]
141 Update the saved configuration for a running domain. This has no
142 immediate effect but will be applied when the guest is next
143 restarted. This command is useful to ensure that runtime
144 modifications made to the guest will be preserved when the guest is
145 restarted.
146 Since Xen 4.5 xl has improved capabilities to handle dynamic domain
148 configuration changes and will preserve any changes made at runtime
149 when necessary. Therefore it should not normally be necessary to
150 use this command any more.
151 configfile has to be an absolute path to a file.
153 OPTIONS
155 -f=FILE, --defconfig=FILE
157 Use the given configuration file.
158 key=value
160 It is possible to pass key=value pairs on the command line to
161 provide options as if they were written in the configuration
162 file; these override whatever is in the configfile. Please see
163 the note under create on handling special characters when
164 passing key=value pairs on the command line.
165 console [OPTIONS] domain-id
167 Attach to the console of a domain specified by domain-id. If
168 you've set up your domains to have a traditional login console this
169 will look much like a normal text login screen.
170 Use the key combination Ctrl+] to detach from the domain console.
172 OPTIONS
174 -t [pv|serial]
176 Connect to a PV console or connect to an emulated serial
177 console. PV consoles are the only consoles available for PV
178 domains while HVM domains can have both. If this option is not
179 specified it defaults to emulated serial for HVM guests and PV
180 console for PV guests.
181 -n NUM
183 Connect to console number NUM. Console numbers start from 0.
184 destroy [OPTIONS] domain-id
186 Immediately terminate the domain specified by domain-id. This
187 doesn't give the domain OS any chance to react, and is the
188 equivalent of ripping the power cord out on a physical machine. In
189 most cases you will want to use the shutdown command instead.
190 OPTIONS
192 -f Allow domain 0 to be destroyed. Because a domain cannot
194 destroy itself, this is only possible when using a
195 disaggregated toolstack, and is most useful when using a
196 hardware domain separated from domain 0.
197 domid domain-name
199 Converts a domain name to a domain id.
200 domname domain-id
202 Converts a domain id to a domain name.
203 rename domain-id new-name
205 Change the domain name of a domain specified by domain-id to new-
206 name.
207 dump-core domain-id [filename]
209 Dumps the virtual machine's memory for the specified domain to the
210 filename specified, without pausing the domain. The dump file will
211 be written to a distribution specific directory for dump files, for
212 example: /var/lib/xen/dump/dump.
213 help [--long]
215 Displays the short help message (i.e. common commands) by default.
216 If the --long option is specified, it displays the complete set of
218 xl subcommands, grouped by function.
219 list [OPTIONS] [domain-id ...]
221 Displays information about one or more domains. If no domains are
222 specified it displays information about all domains.
223 OPTIONS
225 -l, --long
227 The output for xl list is not the table view shown below, but
228 instead presents the data as a JSON data structure.
229 -Z, --context
231 Also displays the security labels.
232 -v, --verbose
234 Also displays the domain UUIDs, the shutdown reason and
235 security labels.
236 -c, --cpupool
238 Also displays the cpupool the domain belongs to.
239 -n, --numa
241 Also displays the domain NUMA node affinity.
242 EXAMPLE
244 An example format for the list is as follows:
246 Name ID Mem VCPUs State Time(s)
248 Domain-0 0 750 4 r----- 11794.3
249 win 1 1019 1 r----- 0.3
250 linux 2 2048 2 r----- 5624.2
251 Name is the name of the domain. ID the numeric domain id. Mem is
253 the desired amount of memory to allocate to the domain (although it
254 may not be the currently allocated amount). VCPUs is the number of
255 virtual CPUs allocated to the domain. State is the run state (see
256 below). Time is the total run time of the domain as accounted for
257 by Xen.
258 STATES
260 The State field lists 6 states for a Xen domain, and which ones the
262 current domain is in.
263 r - running
265 The domain is currently running on a CPU.
266 b - blocked
268 The domain is blocked, and not running or runnable. This can
269 be because the domain is waiting on IO (a traditional wait
270 state) or has gone to sleep because there was nothing else for
271 it to do.
272 p - paused
274 The domain has been paused, usually occurring through the
275 administrator running xl pause. When in a paused state the
276 domain will still consume allocated resources (like memory),
277 but will not be eligible for scheduling by the Xen hypervisor.
278 s - shutdown
280 The guest OS has shut down (SCHEDOP_shutdown has been called)
281 but the domain is not dying yet.
282 c - crashed
284 The domain has crashed, which is always a violent ending.
285 Usually this state only occurs if the domain has been
286 configured not to restart on a crash. See xl.cfg(5) for more
287 info.
288 d - dying
290 The domain is in the process of dying, but hasn't completely
291 shut down or crashed.
292 NOTES
294 The Time column is deceptive. Virtual IO (network and block
296 devices) used by the domains requires coordination by Domain0,
297 which means that Domain0 is actually charged for much of the
298 time that a DomainU is doing IO. Use of this time value to
299 determine relative utilizations by domains is thus very
300 unreliable, as a high IO workload may show as less utilized
301 than a high CPU workload. Consider yourself warned.
302 mem-max domain-id mem
304 Specify the maximum amount of memory the domain is able to use,
305 appending 't' for terabytes, 'g' for gigabytes, 'm' for megabytes,
306 'k' for kilobytes and 'b' for bytes.
307 The mem-max value may not correspond to the actual memory used in
309 the domain, as it may balloon down its memory to give more back to
310 the OS.
311 The value given just sets the memory amount the domain is allowed
313 to allocate in the hypervisor. It can't be set lower than the
314 current reservation, but it is allowed to be higher than the
315 configured maximum memory size of the domain (maxmem parameter in
316 the domain's configuration). Using xl mem-max to set the maximum
317 memory above the initial maxmem value will not allow the additional
318 memory to be used via xl mem-set. The initial maxmem value is still
319 used as an upper limit for xl mem-set.
320 The domain will not receive any signal regarding the changed memory
322 limit.
323 mem-set domain-id mem
325 Set the domain's used memory using the balloon driver; append 't'
326 for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for
327 kilobytes and 'b' for bytes.
328 Because this operation requires cooperation from the domain
330 operating system, there is no guarantee that it will succeed. This
331 command will definitely not work unless the domain has the required
332 paravirt driver.
333 Warning: There is no good way to know in advance how small of a
335 mem-set will make a domain unstable and cause it to crash. Be very
336 careful when using this command on running domains.
337 migrate [OPTIONS] domain-id host
339 Migrate a domain to another host machine. By default xl relies on
340 ssh as a transport mechanism between the two hosts.
341 OPTIONS
343 -s sshcommand
345 Use <sshcommand> instead of ssh. String will be passed to sh.
346 If empty, run <host> instead of ssh <host> xl migrate-receive
347 [-d -e].
348 -e On the new <host>, do not wait in the background for the death
350 of the domain. See the corresponding option of the create
351 subcommand.
352 -C config
354 Send the specified <config> file instead of the file used on
355 creation of the domain.
356 --debug
358 Display huge (!) amount of debug information during the
359 migration process.
360 -p Leave the domain on the receive side paused after migration.
362 remus [OPTIONS] domain-id host
364 Enable Remus HA or COLO HA for domain. By default xl relies on ssh
365 as a transport mechanism between the two hosts.
366 NOTES
368 Remus support in xl is still in experimental (proof-of-concept)
370 phase. Disk replication support is limited to DRBD disks.
371 COLO support in xl is still in experimental (proof-of-concept)
373 phase. All options are subject to change in the future.
374 COLO disk configuration looks like:
376 disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
378 The supported options are:
380 colo-host : Secondary host's ip address.
382 colo-port : Secondary host's port, we will run a nbd server on
383 the secondary host, and the nbd server will listen on this port.
384 colo-export : Nbd server's disk export name of the secondary host.
385 active-disk : Secondary's guest write will be buffered to this
386 disk, and it's used by the secondary.
387 hidden-disk : Primary's modified contents will be buffered in this
388 disk, and it's used by the secondary.
389 COLO network configuration looks like:
391 vif = [ '...,forwarddev=xxx,...']
393 The supported options are:
395 forwarddev : Forward devices for the primary and the secondary,
397 they are directly connected.
398 OPTIONS
400 -i MS
402 Checkpoint domain memory every MS milliseconds (default 200ms).
403 -u Disable memory checkpoint compression.
405 -s sshcommand
407 Use <sshcommand> instead of ssh. String will be passed to sh.
408 If empty, run <host> instead of ssh <host> xl migrate-receive
409 -r [-e].
410 -e On the new <host>, do not wait in the background for the death
412 of the domain. See the corresponding option of the create
413 subcommand.
414 -N netbufscript
416 Use <netbufscript> to setup network buffering instead of the
417 default script (/etc/xen/scripts/remus-netbuf-setup).
418 -F Run Remus in unsafe mode. Use this option with caution as
420 failover may not work as intended.
421 -b Replicate memory checkpoints to /dev/null (blackhole).
423 Generally useful for debugging. Requires enabling unsafe mode.
424 -n Disable network output buffering. Requires enabling unsafe
426 mode.
427 -d Disable disk replication. Requires enabling unsafe mode.
429 -c Enable COLO HA. This conflicts with -i and -b, and memory
431 checkpoint compression must be disabled.
432 -p Use userspace COLO Proxy. This option must be used in
434 conjunction with -c.
435 pause domain-id
437 Pause a domain. When in a paused state the domain will still
438 consume allocated resources (such as memory), but will not be
439 eligible for scheduling by the Xen hypervisor.
440 reboot [OPTIONS] domain-id
442 Reboot a domain. This acts just as if the domain had the reboot
443 command run from the console. The command returns as soon as it
444 has executed the reboot action, which may be significantly earlier
445 than when the domain actually reboots.
446 For HVM domains this requires PV drivers to be installed in your
448 guest OS. If PV drivers are not present but you have configured the
449 guest OS to behave appropriately you may be able to use the -F
450 option to trigger a reset button press.
451 The behavior of what happens to a domain when it reboots is set by
453 the on_reboot parameter of the domain configuration file when the
454 domain was created.
455 OPTIONS
457 -F If the guest does not support PV reboot control then fallback
459 to sending an ACPI power event (equivalent to the reset option
460 to trigger).
461 You should ensure that the guest is configured to behave as
463 expected in response to this event.
464 restore [OPTIONS] [configfile] checkpointfile
466 Build a domain from an xl save state file. See save for more info.
467 OPTIONS
469 -p Do not unpause the domain after restoring it.
471 -e Do not wait in the background for the death of the domain on
473 the new host. See the corresponding option of the create
474 subcommand.
475 -d Enable debug messages.
477 -V, --vncviewer
479 Attach to the domain's VNC server, forking a vncviewer process.
480 -A, --vncviewer-autopass
482 Pass the VNC password to vncviewer via stdin.
483 save [OPTIONS] domain-id checkpointfile [configfile]
485 Saves a running domain to a state file so that it can be restored
486 later. Once saved, the domain will no longer be running on the
487 system, unless the -c or -p options are used. xl restore restores
488 from this checkpoint file. Passing a config file argument allows
489 the user to manually select the VM config file used to create the
490 domain.
491 -c Leave the domain running after creating the snapshot.
493 -p Leave the domain paused after creating the snapshot.
495 sharing [domain-id]
497 Display the number of shared pages for a specified domain. If no
498 domain is specified it displays information about all domains.
499 shutdown [OPTIONS] -a|domain-id
501 Gracefully shuts down a domain. This coordinates with the domain
502 OS to perform graceful shutdown, so there is no guarantee that it
503 will succeed, and may take a variable length of time depending on
504 what services must be shut down in the domain.
505 For HVM domains this requires PV drivers to be installed in your
507 guest OS. If PV drivers are not present but you have configured the
508 guest OS to behave appropriately you may be able to use the -F
509 option to trigger a power button press.
510 The command returns immediately after signaling the domain unless
512 the -w flag is used.
513 The behavior of what happens to a domain when it reboots is set by
515 the on_shutdown parameter of the domain configuration file when the
516 domain was created.
517 OPTIONS
519 -a, --all
521 Shutdown all guest domains. Often used when doing a complete
522 shutdown of a Xen system.
523 -w, --wait
525 Wait for the domain to complete shutdown before returning.
526 -F If the guest does not support PV shutdown control then fallback
528 to sending an ACPI power event (equivalent to the power option
529 to trigger).
530 You should ensure that the guest is configured to behave as
532 expected in response to this event.
533 sysrq domain-id letter
535 Send a <Magic System Request> to the domain, each type of request
536 is represented by a different letter. It can be used to send SysRq
537 requests to Linux guests, see sysrq.txt in your Linux Kernel
538 sources for more information. It requires PV drivers to be
539 installed in your guest OS.
540 trigger domain-id nmi|reset|init|power|sleep|s3resume [VCPU]
542 Send a trigger to a domain, where the trigger can be: nmi, reset,
543 init, power or sleep. Optionally a specific vcpu number can be
544 passed as an argument. This command is only available for HVM
545 domains.
546 unpause domain-id
548 Moves a domain out of the paused state. This will allow a
549 previously paused domain to now be eligible for scheduling by the
550 Xen hypervisor.
551 vcpu-set domain-id vcpu-count
553 Enables the vcpu-count virtual CPUs for the domain in question.
554 Like mem-set, this command can only allocate up to the maximum
555 virtual CPU count configured at boot for the domain.
556 If the vcpu-count is smaller than the current number of active
558 VCPUs, the highest number VCPUs will be hotplug removed. This may
559 be important for pinning purposes.
560 Attempting to set the VCPUs to a number larger than the initially
562 configured VCPU count is an error. Trying to set VCPUs to < 1 will
563 be quietly ignored.
564 Some guests may need to actually bring the newly added CPU online
566 after vcpu-set, go to SEE ALSO section for information.
567 vcpu-list [domain-id]
569 Lists VCPU information for a specific domain. If no domain is
570 specified, VCPU information for all domains will be provided.
571 vcpu-pin [-f|--force] domain-id vcpu cpus hard cpus soft
573 Set hard and soft affinity for a vcpu of <domain-id>. Normally
574 VCPUs can float between available CPUs whenever Xen deems a
575 different run state is appropriate.
576 Hard affinity can be used to restrict this, by ensuring certain
578 VCPUs can only run on certain physical CPUs. Soft affinity
579 specifies a preferred set of CPUs. Soft affinity needs special
580 support in the scheduler, which is only provided in credit1.
581 The keyword all can be used to apply the hard and soft affinity
583 masks to all the VCPUs in the domain. The symbol '-' can be used to
584 leave either hard or soft affinity alone.
585 For example:
587 xl vcpu-pin 0 3 - 6-9
589 will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9,
591 leaving its hard affinity untouched. On the other hand:
592 xl vcpu-pin 0 3 3,4 6-9
594 will set both hard and soft affinity, the former to pCPUs 3 and 4,
596 the latter to pCPUs 6,7,8, and 9.
597 Specifying -f or --force will remove a temporary pinning done by
599 the operating system (normally this should be done by the operating
600 system). In case a temporary pinning is active for a vcpu the
601 affinity of this vcpu can't be changed without this option.
602 vm-list
604 Prints information about guests. This list excludes information
605 about service or auxiliary domains such as dom0 and stubdoms.
606 EXAMPLE
608 An example format for the list is as follows:
610 UUID ID name
612 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win
613 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux
614 vncviewer [OPTIONS] domain-id
616 Attach to the domain's VNC server, forking a vncviewer process.
617 OPTIONS
619 --autopass
621 Pass the VNC password to vncviewer via stdin.
622
624 debug-keys keys
625 Send debug keys to Xen. It is the same as pressing the Xen
626 "conswitch" (Ctrl-A by default) three times and then pressing
627 "keys".
628 set-parameters params
630 Set hypervisor parameters as specified in params. This allows for
631 some boot parameters of the hypervisor to be modified in the
632 running systems.
633 dmesg [OPTIONS]
635 Reads the Xen message buffer, similar to dmesg on a Linux system.
636 The buffer contains informational, warning, and error messages
637 created during Xen's boot process. If you are having problems with
638 Xen, this is one of the first places to look as part of problem
639 determination.
640 OPTIONS
642 -c, --clear
644 Clears Xen's message buffer.
645 info [OPTIONS]
647 Print information about the Xen host in name : value format. When
648 reporting a Xen bug, please provide this information as part of the
649 bug report. See http://wiki.xen.org/xenwiki/ReportingBugs on how to
650 report Xen bugs.
651 Sample output looks as follows:
653 host : scarlett
655 release : 3.1.0-rc4+
656 version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011
657 machine : x86_64
658 nr_cpus : 4
659 nr_nodes : 1
660 cores_per_socket : 4
661 threads_per_core : 1
662 cpu_mhz : 2266
663 hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000
664 virt_caps : hvm hvm_directio
665 total_memory : 6141
666 free_memory : 4274
667 free_cpus : 0
668 outstanding_claims : 0
669 xen_major : 4
670 xen_minor : 2
671 xen_extra : -unstable
672 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
673 xen_scheduler : credit
674 xen_pagesize : 4096
675 platform_params : virt_start=0xffff800000000000
676 xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241
677 xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1
678 cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8)
679 cc_compile_by : sstabellini
680 cc_compile_domain : uk.xensource.com
681 cc_compile_date : Tue Nov 8 12:03:05 UTC 2011
682 xend_config_format : 4
683 FIELDS
685 Not all fields will be explained here, but some of the less obvious
687 ones deserve explanation:
688 hw_caps
690 A vector showing what hardware capabilities are supported by
691 your processor. This is equivalent to, though more cryptic,
692 the flags field in /proc/cpuinfo on a normal Linux machine:
693 they both derive from the feature bits returned by the cpuid
694 command on x86 platforms.
695 free_memory
697 Available memory (in MB) not allocated to Xen, or any other
698 domains, or claimed for domains.
699 outstanding_claims
701 When a claim call is done (see xl.conf(5)) a reservation for a
702 specific amount of pages is set and also a global value is
703 incremented. This global value (outstanding_claims) is then
704 reduced as the domain's memory is populated and eventually
705 reaches zero. Most of the time the value will be zero, but if
706 you are launching multiple guests, and claim_mode is enabled,
707 this value can increase/decrease. Note that the value also
708 affects the free_memory - as it will reflect the free memory in
709 the hypervisor minus the outstanding pages claimed for guests.
710 See xl info claims parameter for detailed listing.
711 xen_caps
713 The Xen version and architecture. Architecture values can be
714 one of: x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
715 xen_changeset
717 The Xen mercurial changeset id. Very useful for determining
718 exactly what version of code your Xen system was built from.
719 OPTIONS
721 -n, --numa
723 List host NUMA topology information
724 top Executes the xentop(1) command, which provides real time monitoring
726 of domains. Xentop has a curses interface, and is reasonably self
727 explanatory.
728 uptime
730 Prints the current uptime of the domains running.
731 claims
733 Prints information about outstanding claims by the guests. This
734 provides the outstanding claims and currently populated memory
735 count for the guests. These values added up reflect the global
736 outstanding claim value, which is provided via the info argument,
737 outstanding_claims value. The Mem column has the cumulative value
738 of outstanding claims and the total amount of memory that has been
739 right now allocated to the guest.
740 EXAMPLE
742 An example format for the list is as follows:
744 Name ID Mem VCPUs State Time(s) Claimed
746 Domain-0 0 2047 4 r----- 19.7 0
747 OL5 2 2048 1 --p--- 0.0 847
748 OL6 3 1024 4 r----- 5.9 0
749 Windows_XP 4 2047 1 --p--- 0.0 1989
750 In which it can be seen that the OL5 guest still has 847MB of
752 claimed memory (out of the total 2048MB where 1191MB has been
753 allocated to the guest).
754
756 Xen ships with a number of domain schedulers, which can be set at boot
757 time with the sched= parameter on the Xen command line. By default
758 credit is used for scheduling.
759 sched-credit [OPTIONS]
761 Set or get credit (aka credit1) scheduler parameters. The credit
762 scheduler is a proportional fair share CPU scheduler built from the
763 ground up to be work conserving on SMP hosts.
764 Each domain (including Domain0) is assigned a weight and a cap.
766 OPTIONS
768 -d DOMAIN, --domain=DOMAIN
770 Specify domain for which scheduler parameters are to be
771 modified or retrieved. Mandatory for modifying scheduler
772 parameters.
773 -w WEIGHT, --weight=WEIGHT
775 A domain with a weight of 512 will get twice as much CPU as a
776 domain with a weight of 256 on a contended host. Legal weights
777 range from 1 to 65535 and the default is 256.
778 -c CAP, --cap=CAP
780 The cap optionally fixes the maximum amount of CPU a domain
781 will be able to consume, even if the host system has idle CPU
782 cycles. The cap is expressed in percentage of one physical CPU:
783 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
784 The default, 0, means there is no upper cap.
785 NB: Many systems have features that will scale down the
787 computing power of a cpu that is not 100% utilized. This can
788 be in the operating system, but can also sometimes be below the
789 operating system in the BIOS. If you set a cap such that
790 individual cores are running at less than 100%, this may have
791 an impact on the performance of your workload over and above
792 the impact of the cap. For example, if your processor runs at
793 2GHz, and you cap a vm at 50%, the power management system may
794 also reduce the clock speed to 1GHz; the effect will be that
795 your VM gets 25% of the available power (50% of 1GHz) rather
796 than 50% (50% of 2GHz). If you are not getting the performance
797 you expect, look at performance and cpufreq options in your
798 operating system and your BIOS.
799 -p CPUPOOL, --cpupool=CPUPOOL
801 Restrict output to domains in the specified cpupool.
802 -s, --schedparam
804 Specify to list or set pool-wide scheduler parameters.
805 -t TSLICE, --tslice_ms=TSLICE
807 Timeslice tells the scheduler how long to allow VMs to run
808 before pre-empting. The default is 30ms. Valid ranges are 1ms
809 to 1000ms. The length of the timeslice (in ms) must be higher
810 than the length of the ratelimit (see below).
811 -r RLIMIT, --ratelimit_us=RLIMIT
813 Ratelimit attempts to limit the number of schedules per second.
814 It sets a minimum amount of time (in microseconds) a VM must
815 run before we will allow a higher-priority VM to pre-empt it.
816 The default value is 1000 microseconds (1ms). Valid range is
817 100 to 500000 (500ms). The ratelimit length must be lower than
818 the timeslice length.
819 -m DELAY, --migration_delay_us=DELAY
821 Migration delay specifies for how long a vCPU, after it stopped
822 running should be considered "cache-hot". Basically, if less
823 than DELAY us passed since when the vCPU was executing on a
824 CPU, it is likely that most of the vCPU's working set is still
825 in the CPU's cache, and therefore the vCPU is not migrated.
826 Default is 0. Maximum is 100 ms. This can be effective at
828 preventing vCPUs to bounce among CPUs too quickly, but, at the
829 same time, the scheduler stops being fully work-conserving.
830 COMBINATION
832 The following is the effect of combining the above options:
834 <nothing> : List all domain params and sched params
836 from all pools
837 -d [domid] : List domain params for domain [domid]
838 -d [domid] [params] : Set domain params for domain [domid]
839 -p [pool] : list all domains and sched params for
840 [pool]
841 -s : List sched params for poolid 0
842 -s [params] : Set sched params for poolid 0
843 -p [pool] -s : List sched params for [pool]
844 -p [pool] -s [params] : Set sched params for [pool]
845 -p [pool] -d... : Illegal
846 sched-credit2 [OPTIONS]
847 Set or get credit2 scheduler parameters. The credit2 scheduler is
848 a proportional fair share CPU scheduler built from the ground up to
849 be work conserving on SMP hosts.
850 Each domain (including Domain0) is assigned a weight.
852 OPTIONS
854 -d DOMAIN, --domain=DOMAIN
856 Specify domain for which scheduler parameters are to be
857 modified or retrieved. Mandatory for modifying scheduler
858 parameters.
859 -w WEIGHT, --weight=WEIGHT
861 A domain with a weight of 512 will get twice as much CPU as a
862 domain with a weight of 256 on a contended host. Legal weights
863 range from 1 to 65535 and the default is 256.
864 -p CPUPOOL, --cpupool=CPUPOOL
866 Restrict output to domains in the specified cpupool.
867 -s, --schedparam
869 Specify to list or set pool-wide scheduler parameters.
870 -r RLIMIT, --ratelimit_us=RLIMIT
872 Attempts to limit the rate of context switching. It is
873 basically the same as --ratelimit_us in sched-credit
874 sched-rtds [OPTIONS]
876 Set or get rtds (Real Time Deferrable Server) scheduler parameters.
877 This rt scheduler applies Preemptive Global Earliest Deadline First
878 real-time scheduling algorithm to schedule VCPUs in the system.
879 Each VCPU has a dedicated period, budget and extratime. While
880 scheduled, a VCPU burns its budget. A VCPU has its budget
881 replenished at the beginning of each period; Unused budget is
882 discarded at the end of each period. A VCPU with extratime set
883 gets extra time from the unreserved system resource.
884 OPTIONS
886 -d DOMAIN, --domain=DOMAIN
888 Specify domain for which scheduler parameters are to be
889 modified or retrieved. Mandatory for modifying scheduler
890 parameters.
891 -v VCPUID/all, --vcpuid=VCPUID/all
893 Specify vcpu for which scheduler parameters are to be modified
894 or retrieved.
895 -p PERIOD, --period=PERIOD
897 Period of time, in microseconds, over which to replenish the
898 budget.
899 -b BUDGET, --budget=BUDGET
901 Amount of time, in microseconds, that the VCPU will be allowed
902 to run every period.
903 -e Extratime, --extratime=Extratime
905 Binary flag to decide if the VCPU will be allowed to get extra
906 time from the unreserved system resource.
907 -c CPUPOOL, --cpupool=CPUPOOL
909 Restrict output to domains in the specified cpupool.
910 EXAMPLE
912 1) Use -v all to see the budget and period of all the VCPUs of
914 all the domains:
915 xl sched-rtds -v all
917 Cpupool Pool-0: sched=RTDS
918 Name ID VCPU Period Budget Extratime
919 Domain-0 0 0 10000 4000 yes
920 vm1 2 0 300 150 yes
921 vm1 2 1 400 200 yes
922 vm1 2 2 10000 4000 yes
923 vm1 2 3 1000 500 yes
924 vm2 4 0 10000 4000 yes
925 vm2 4 1 10000 4000 yes
926 Without any arguments, it will output the default scheduling
928 parameters for each domain:
929 xl sched-rtds
931 Cpupool Pool-0: sched=RTDS
932 Name ID Period Budget Extratime
933 Domain-0 0 10000 4000 yes
934 vm1 2 10000 4000 yes
935 vm2 4 10000 4000 yes
936 2) Use, for instance, -d vm1, -v all to see the budget and
938 period of all VCPUs of a specific domain (vm1):
939 xl sched-rtds -d vm1 -v all
941 Name ID VCPU Period Budget Extratime
942 vm1 2 0 300 150 yes
943 vm1 2 1 400 200 yes
944 vm1 2 2 10000 4000 yes
945 vm1 2 3 1000 500 yes
946 To see the parameters of a subset of the VCPUs of a domain,
948 use:
949 xl sched-rtds -d vm1 -v 0 -v 3
951 Name ID VCPU Period Budget Extratime
952 vm1 2 0 300 150 yes
953 vm1 2 3 1000 500 yes
954 If no -v is specified, the default scheduling parameters for
956 the domain are shown:
957 xl sched-rtds -d vm1
959 Name ID Period Budget Extratime
960 vm1 2 10000 4000 yes
961 3) Users can set the budget and period of multiple VCPUs of a
963 specific domain with only one command, e.g., "xl sched-rtds -d
964 vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0".
965 To change the parameters of all the VCPUs of a domain, use -v
967 all, e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1".
968
970 Xen can group the physical cpus of a server in cpu-pools. Each physical
971 CPU is assigned at most to one cpu-pool. Domains are each restricted to
972 a single cpu-pool. Scheduling does not cross cpu-pool boundaries, so
973 each cpu-pool has its own scheduler. Physical cpus and domains can be
974 moved from one cpu-pool to another only by an explicit command. Cpu-
975 pools can be specified either by name or by id.
976 cpupool-create [OPTIONS] [configfile] [variable=value ...]
978 Create a cpu pool based an config from a configfile or command-line
979 parameters. Variable settings from the configfile may be altered
980 by specifying new or additional assignments on the command line.
981 See the xlcpupool.cfg(5) manpage for more information.
983 OPTIONS
985 -f=FILE, --defconfig=FILE
987 Use the given configuration file.
988 cpupool-list [OPTIONS] [cpu-pool]
990 List CPU pools on the host.
991 OPTIONS
993 -c, --cpus
995 If this option is specified, xl prints a list of CPUs used by
996 cpu-pool.
997 cpupool-destroy cpu-pool
999 Deactivates a cpu pool. This is possible only if no domain is
1000 active in the cpu-pool.
1001 cpupool-rename cpu-pool <newname>
1003 Renames a cpu-pool to newname.
1004 cpupool-cpu-add cpu-pool cpus|node:nodes
1006 Adds one or more CPUs or NUMA nodes to cpu-pool. CPUs and NUMA
1007 nodes can be specified as single CPU/node IDs or as ranges.
1008 For example:
1010 (a) xl cpupool-cpu-add mypool 4
1012 (b) xl cpupool-cpu-add mypool 1,5,10-16,^13
1013 (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8
1014 means adding CPU 4 to mypool, in (a); adding CPUs
1016 1,5,10,11,12,14,15 and 16, in (b); and adding all the CPUs of NUMA
1017 nodes 0, 2 and 3, plus CPU 8, but keeping out CPUs 10,11,12, in
1018 (c).
1019 All the specified CPUs that can be added to the cpupool will be
1021 added to it. If some CPU can't (e.g., because they're already part
1022 of another cpupool), an error is reported about each one of them.
1023 cpupool-cpu-remove cpus|node:nodes
1025 Removes one or more CPUs or NUMA nodes from cpu-pool. CPUs and NUMA
1026 nodes can be specified as single CPU/node IDs or as ranges, using
1027 the exact same syntax as in cpupool-cpu-add above.
1028 cpupool-migrate domain-id cpu-pool
1030 Moves a domain specified by domain-id or domain-name into a cpu-
1031 pool. Domain-0 can't be moved to another cpu-pool.
1032 cpupool-numa-split
1034 Splits up the machine into one cpu-pool per numa node.
1035
1037 Most virtual devices can be added and removed while guests are running,
1038 assuming that the necessary support exists in the guest OS. The effect
1039 to the guest OS is much the same as any hotplug event.
1040 BLOCK DEVICES
1042 block-attach domain-id disc-spec-component(s) ...
1043 Create a new virtual block device and attach it to the specified
1044 domain. A disc specification is in the same format used for the
1045 disk variable in the domain config file. See
1046 xl-disk-configuration(5). This will trigger a hotplug event for the
1047 guest.
1048 Note that only PV block devices are supported by block-attach.
1050 Requests to attach emulated devices (eg, vdev=hdc) will result in
1051 only the PV view being available to the guest.
1052 block-detach domain-id devid [OPTIONS]
1054 Detach a domain's virtual block device. devid may be the symbolic
1055 name or the numeric device id given to the device by domain 0. You
1056 will need to run xl block-list to determine that number.
1057 Detaching the device requires the cooperation of the domain. If
1059 the domain fails to release the device (perhaps because the domain
1060 is hung or is still using the device), the detach will fail.
1061 OPTIONS
1063 --force
1065 If this parameter is specified the device will be forcefully
1066 detached, which may cause IO errors in the domain.
1067 block-list domain-id
1069 List virtual block devices for a domain.
1070 cd-insert domain-id virtualdevice target
1072 Insert a cdrom into a guest domain's existing virtual cd drive. The
1073 virtual drive must already exist but can be empty. How the device
1074 should be presented to the guest domain is specified by the
1075 virtualdevice parameter; for example "hdc". Parameter target is the
1076 target path in the backend domain (usually domain 0) to be
1077 exported; can be a block device or a file etc. See target in
1078 xl-disk-configuration(5).
1079 Only works with HVM domains.
1081 cd-eject domain-id virtualdevice
1083 Eject a cdrom from a guest domain's virtual cd drive, specified by
1084 virtualdevice. Only works with HVM domains.
1085 NETWORK DEVICES
1087 network-attach domain-id network-device
1088 Creates a new network device in the domain specified by domain-id.
1089 network-device describes the device to attach, using the same
1090 format as the vif string in the domain config file. See xl.cfg(5)
1091 and xl-network-configuration(5) for more information.
1092 Note that only attaching PV network interfaces is supported.
1094 network-detach domain-id devid|mac
1096 Removes the network device from the domain specified by domain-id.
1097 devid is the virtual interface device number within the domain
1098 (i.e. the 3 in vif22.3). Alternatively, the mac address can be used
1099 to select the virtual interface to detach.
1100 network-list domain-id
1102 List virtual network interfaces for a domain.
1103 CHANNEL DEVICES
1105 channel-list domain-id
1106 List virtual channel interfaces for a domain.
1107 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES
1109 vtpm-attach domain-id vtpm-device
1110 Creates a new vtpm (virtual Trusted Platform Module) device in the
1111 domain specified by domain-id. vtpm-device describes the device to
1112 attach, using the same format as the vtpm string in the domain
1113 config file. See xl.cfg(5) for more information.
1114 vtpm-detach domain-id devid|uuid
1116 Removes the vtpm device from the domain specified by domain-id.
1117 devid is the numeric device id given to the virtual Trusted
1118 Platform Module device. You will need to run xl vtpm-list to
1119 determine that number. Alternatively, the uuid of the vtpm can be
1120 used to select the virtual device to detach.
1121 vtpm-list domain-id
1123 List virtual Trusted Platform Modules for a domain.
1124 VDISPL DEVICES
1126 vdispl-attach domain-id vdispl-device
1127 Creates a new vdispl device in the domain specified by domain-id.
1128 vdispl-device describes the device to attach, using the same format
1129 as the vdispl string in the domain config file. See xl.cfg(5) for
1130 more information.
1131 NOTES
1133 As in vdispl-device string semicolon is used then put quotes or
1135 escaping when using from the shell.
1136 EXAMPLE
1138 xl vdispl-attach DomU
1140 connectors='id0:1920x1080;id1:800x600;id2:640x480'
1141 or
1143 xl vdispl-attach DomU
1145 connectors=id0:1920x1080\;id1:800x600\;id2:640x480
1146 vdispl-detach domain-id dev-id
1148 Removes the vdispl device specified by dev-id from the domain
1149 specified by domain-id.
1150 vdispl-list domain-id
1152 List virtual displays for a domain.
1153 VSND DEVICES
1155 vsnd-attach domain-id vsnd-item vsnd-item ...
1156 Creates a new vsnd device in the domain specified by domain-id.
1157 vsnd-item's describe the vsnd device to attach, using the same
1158 format as the VSND_ITEM_SPEC string in the domain config file. See
1159 xl.cfg(5) for more information.
1160 EXAMPLE
1162 xl vsnd-attach DomU 'CARD, short-name=Main,
1164 sample-formats=s16_le;s8;u32_be' 'PCM, name=Main' 'STREAM,
1165 id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
1166 vsnd-detach domain-id dev-id
1168 Removes the vsnd device specified by dev-id from the domain
1169 specified by domain-id.
1170 vsnd-list domain-id
1172 List vsnd devices for a domain.
1173 KEYBOARD DEVICES
1175 vkb-attach domain-id vkb-device
1176 Creates a new keyboard device in the domain specified by domain-id.
1177 vkb-device describes the device to attach, using the same format as
1178 the VKB_SPEC_STRING string in the domain config file. See xl.cfg(5)
1179 for more informations.
1180 vkb-detach domain-id devid
1182 Removes the keyboard device from the domain specified by domain-id.
1183 devid is the virtual interface device number within the domain
1184 vkb-list domain-id
1186 List virtual network interfaces for a domain.
1187
1189 pci-assignable-list
1190 List all the assignable PCI devices. These are devices in the
1191 system which are configured to be available for passthrough and are
1192 bound to a suitable PCI backend driver in domain 0 rather than a
1193 real driver.
1194 pci-assignable-add BDF
1196 Make the device at PCI Bus/Device/Function BDF assignable to
1197 guests. This will bind the device to the pciback driver. If it is
1198 already bound to a driver, it will first be unbound, and the
1199 original driver stored so that it can be re-bound to the same
1200 driver later if desired. If the device is already bound, it will
1201 return success.
1202 CAUTION: This will make the device unusable by Domain 0 until it is
1204 returned with pci-assignable-remove. Care should therefore be
1205 taken not to do this on a device critical to domain 0's operation,
1206 such as storage controllers, network interfaces, or GPUs that are
1207 currently being used.
1208 pci-assignable-remove [-r] BDF
1210 Make the device at PCI Bus/Device/Function BDF not assignable to
1211 guests. This will at least unbind the device from pciback. If the
1212 -r option is specified, it will also attempt to re-bind the device
1213 to its original driver, making it usable by Domain 0 again. If the
1214 device is not bound to pciback, it will return success.
1215 pci-attach domain-id BDF
1217 Hot-plug a new pass-through pci device to the specified domain.
1218 BDF is the PCI Bus/Device/Function of the physical device to pass-
1219 through.
1220 pci-detach [OPTIONS] domain-id BDF
1222 Hot-unplug a previously assigned pci device from a domain. BDF is
1223 the PCI Bus/Device/Function of the physical device to be removed
1224 from the guest domain.
1225 OPTIONS
1227 -f If this parameter is specified, xl is going to forcefully
1229 remove the device even without guest domain's collaboration.
1230 pci-list domain-id
1232 List pass-through pci devices for a domain.
1233
1235 usbctrl-attach domain-id usbctrl-device
1236 Create a new USB controller in the domain specified by domain-id,
1237 usbctrl-device describes the device to attach, using form
1238 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1239 the usbctrl description in the domain config file. See xl.cfg(5)
1240 for more information.
1241 usbctrl-detach domain-id devid
1243 Destroy a USB controller from the specified domain. devid is devid
1244 of the USB controller.
1245 usbdev-attach domain-id usbdev-device
1247 Hot-plug a new pass-through USB device to the domain specified by
1248 domain-id, usbdev-device describes the device to attach, using form
1249 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1250 the usbdev description in the domain config file. See xl.cfg(5)
1251 for more information.
1252 usbdev-detach domain-id controller=devid port=number
1254 Hot-unplug a previously assigned USB device from a domain.
1255 controller=devid and port=number is USB controller:port in the
1256 guest domain the USB device is attached to.
1257 usb-list domain-id
1259 List pass-through usb devices for a domain.
1260
1262 qemu-monitor-command domain-id command
1263 Issue a monitor command to the device model of the domain specified
1264 by domain-id. command can be any valid command qemu understands.
1265 This can be e.g. used to add non-standard devices or devices with
1266 non-standard parameters to a domain. The output of the command is
1267 printed to stdout.
1268 Warning: This qemu monitor access is provided for convenience when
1270 debugging, troubleshooting, and experimenting. Its use is not
1271 supported by the Xen Project.
1272 Specifically, not all information displayed by the qemu monitor
1274 will necessarily be accurate or complete, because in a Xen system
1275 qemu does not have a complete view of the guest.
1276 Furthermore, modifying the guest's setup via the qemu monitor may
1278 conflict with the Xen toolstack's assumptions. Resulting problems
1279 may include, but are not limited to: guest crashes; toolstack error
1280 messages; inability to migrate the guest; and security
1281 vulnerabilities which are not covered by the Xen Project security
1282 response policy.
1283 EXAMPLE
1285 Obtain information of USB devices connected as such via the device
1287 model (only!) to a domain:
1288 xl qemu-monitor-command vm1 'info usb'
1290 Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
1291
1293 tmem-list [OPTIONS] domain-id
1294 List tmem pools.
1295 OPTIONS
1297 -l If this parameter is specified, also list tmem stats.
1299 tmem-freeze domain-id
1301 Freeze tmem pools.
1302 tmem-thaw domain-id
1304 Thaw tmem pools.
1305 tmem-set domain-id [OPTIONS]
1307 Change tmem settings.
1308 OPTIONS
1310 -w WEIGHT
1312 Weight (int)
1313 -p COMPRESS
1315 Compress (int)
1316 tmem-shared-auth domain-id [OPTIONS]
1318 De/authenticate shared tmem pool.
1319 OPTIONS
1321 -u UUID
1323 Specify uuid (abcdef01-2345-6789-1234-567890abcdef)
1324 -a AUTH
1326 0=auth,1=deauth
1327 tmem-freeable
1329 Get information about how much freeable memory (MB) is in-use by
1330 tmem.
1331
1333 FLASK is a security framework that defines a mandatory access control
1334 policy providing fine-grained controls over Xen domains, allowing the
1335 policy writer to define what interactions between domains, devices, and
1336 the hypervisor are permitted. Some example of what you can do using
1337 XSM/FLASK:
1338 - Prevent two domains from communicating via event channels or grants
1339 - Control which domains can use device passthrough (and which devices)
1340 - Restrict or audit operations performed by privileged domains
1341 - Prevent a privileged domain from arbitrarily mapping pages from
1342 other
1343 domains.
1344 You can find more details on how to use FLASK and an example security
1346 policy here: <http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
1347 getenforce
1349 Determine if the FLASK security module is loaded and enforcing its
1350 policy.
1351 setenforce 1|0|Enforcing|Permissive
1353 Enable or disable enforcing of the FLASK access controls. The
1354 default is permissive, but this can be changed to enforcing by
1355 specifying "flask=enforcing" or "flask=late" on the hypervisor's
1356 command line.
1357 loadpolicy policy-file
1359 Load FLASK policy from the given policy file. The initial policy is
1360 provided to the hypervisor as a multiboot module; this command
1361 allows runtime updates to the policy. Loading new security policy
1362 will reset runtime changes to device labels.
1363
1365 Intel Haswell and later server platforms offer shared resource
1366 monitoring and control technologies. The availability of these
1367 technologies and the hardware capabilities can be shown with psr-
1368 hwinfo.
1369 See <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> for more
1371 information.
1372 psr-hwinfo [OPTIONS]
1374 Show Platform Shared Resource (PSR) hardware information.
1375 OPTIONS
1377 -m, --cmt
1379 Show Cache Monitoring Technology (CMT) hardware information.
1380 -a, --cat
1382 Show Cache Allocation Technology (CAT) hardware information.
1383 CACHE MONITORING TECHNOLOGY
1385 Intel Haswell and later server platforms offer monitoring capability in
1386 each logical processor to measure specific platform shared resource
1387 metric, for example, L3 cache occupancy. In the Xen implementation, the
1388 monitoring granularity is domain level. To monitor a specific domain,
1389 just attach the domain id with the monitoring service. When the domain
1390 doesn't need to be monitored any more, detach the domain id from the
1391 monitoring service.
1392 Intel Broadwell and later server platforms also offer total/local
1394 memory bandwidth monitoring. Xen supports per-domain monitoring for
1395 these two additional monitoring types. Both memory bandwidth monitoring
1396 and L3 cache occupancy monitoring share the same set of underlying
1397 monitoring service. Once a domain is attached to the monitoring
1398 service, monitoring data can be shown for any of these monitoring
1399 types.
1400 There is no cache monitoring and memory bandwidth monitoring on L2
1402 cache so far.
1403 psr-cmt-attach domain-id
1405 attach: Attach the platform shared resource monitoring service to a
1406 domain.
1407 psr-cmt-detach domain-id
1409 detach: Detach the platform shared resource monitoring service from
1410 a domain.
1411 psr-cmt-show psr-monitor-type [domain-id]
1413 Show monitoring data for a certain domain or all domains. Current
1414 supported monitor types are:
1415 - "cache-occupancy": showing the L3 cache occupancy(KB).
1416 - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
1417 - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
1418 CACHE ALLOCATION TECHNOLOGY
1420 Intel Broadwell and later server platforms offer capabilities to
1421 configure and make use of the Cache Allocation Technology (CAT)
1422 mechanisms, which enable more cache resources (i.e. L3/L2 cache) to be
1423 made available for high priority applications. In the Xen
1424 implementation, CAT is used to control cache allocation on VM basis. To
1425 enforce cache on a specific domain, just set capacity bitmasks (CBM)
1426 for the domain.
1427 Intel Broadwell and later server platforms also offer Code/Data
1429 Prioritization (CDP) for cache allocations, which support specifying
1430 code or data cache for applications. CDP is used on a per VM basis in
1431 the Xen implementation. To specify code or data CBM for the domain, CDP
1432 feature must be enabled and CBM type options need to be specified when
1433 setting CBM, and the type options (code and data) are mutually
1434 exclusive. There is no CDP support on L2 so far.
1435 psr-cat-set [OPTIONS] domain-id cbm
1437 Set cache capacity bitmasks(CBM) for a domain. For how to specify
1438 cbm please refer to
1439 <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
1440 OPTIONS
1442 -s SOCKET, --socket=SOCKET
1444 Specify the socket to process, otherwise all sockets are
1445 processed.
1446 -l LEVEL, --level=LEVEL
1448 Specify the cache level to process, otherwise the last level
1449 cache (L3) is processed.
1450 -c, --code
1452 Set code CBM when CDP is enabled.
1453 -d, --data
1455 Set data CBM when CDP is enabled.
1456 psr-cat-show [OPTIONS] [domain-id]
1458 Show CAT settings for a certain domain or all domains.
1459 OPTIONS
1461 -l LEVEL, --level=LEVEL
1463 Specify the cache level to process, otherwise the last level
1464 cache (L3) is processed.
1465 Memory Bandwidth Allocation
1467 Intel Skylake and later server platforms offer capabilities to
1468 configure and make use of the Memory Bandwidth Allocation (MBA)
1469 mechanisms, which provides OS/VMMs the ability to slow misbehaving
1470 apps/VMs by using a credit-based throttling mechanism. In the Xen
1471 implementation, MBA is used to control memory bandwidth on VM basis. To
1472 enforce bandwidth on a specific domain, just set throttling value
1473 (THRTL) for the domain.
1474 psr-mba-set [OPTIONS] domain-id thrtl
1476 Set throttling value (THRTL) for a domain. For how to specify thrtl
1477 please refer to
1478 <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
1479 OPTIONS
1481 -s SOCKET, --socket=SOCKET
1483 Specify the socket to process, otherwise all sockets are
1484 processed.
1485 psr-mba-show [domain-id]
1487 Show MBA settings for a certain domain or all domains. For linear
1488 mode, it shows the decimal value. For non-linear mode, it shows
1489 hexadecimal value.
1490
1492 xl is mostly command-line compatible with the old xm utility used with
1493 the old Python xend. For compatibility, the following options are
1494 ignored:
1495 xl migrate --live
1497
1499 We need better documentation for:
1500 tmem
1502 Transcendent Memory.
1503
1505 The following man pages:
1506 xl.cfg(5), xlcpupool.cfg(5), xentop(1), xl-disk-configuration(5)
1508 xl-network-configuration(5)
1509 And the following documents on the xen.org website:
1511 <http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
1513 <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
1514 For systems that don't automatically bring the CPU online:
1516 <http://wiki.xen.org/wiki/Paravirt_Linux_CPU_Hotplug>
1518
1520 Send bugs to xen-devel@lists.xen.org, see
1521 http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
15224.12.1 2019-12-11 xl(1)