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 mem can't be set lower than the current memory target for domain-
337 id. It is allowed to be higher than the configured maximum memory
338 size of the domain (maxmem parameter in the domain's
339 configuration).
340 Setting the maximum memory size above the configured maximum memory
342 size will require special guest support (memory hotplug) in order
343 to be usable by the guest.
344 The domain will not receive any signal regarding the changed memory
346 limit.
347 migrate [OPTIONS] domain-id host
349 Migrate a domain to another host machine. By default xl relies on
350 ssh as a transport mechanism between the two hosts.
351 OPTIONS
353 -s sshcommand
355 Use <sshcommand> instead of ssh. String will be passed to sh.
356 If empty, run <host> instead of ssh <host> xl migrate-receive
357 [-d -e].
358 -e On the new <host>, do not wait in the background for the death
360 of the domain. See the corresponding option of the create
361 subcommand.
362 -C config
364 Send the specified <config> file instead of the file used on
365 creation of the domain.
366 --debug
368 Display huge (!) amount of debug information during the
369 migration process.
370 -p Leave the domain on the receive side paused after migration.
372 -D Preserve the domain-id in the domain coniguration that is
374 transferred such that it will be identical on the destination
375 host, unless that configuration is overridden using the -C
376 option. Note that it is not possible to use this option for a
377 'localhost' migration.
378 remus [OPTIONS] domain-id host
380 Enable Remus HA or COLO HA for domain. By default xl relies on ssh
381 as a transport mechanism between the two hosts.
382 NOTES
384 Remus support in xl is still in experimental (proof-of-concept)
386 phase. Disk replication support is limited to DRBD disks.
387 COLO support in xl is still in experimental (proof-of-concept)
389 phase. All options are subject to change in the future.
390 COLO disk configuration looks like:
392 disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
394 The supported options are:
396 colo-host : Secondary host's ip address.
398 colo-port : Secondary host's port, we will run a nbd server on
399 the secondary host, and the nbd server will listen on this port.
400 colo-export : Nbd server's disk export name of the secondary host.
401 active-disk : Secondary's guest write will be buffered to this
402 disk, and it's used by the secondary.
403 hidden-disk : Primary's modified contents will be buffered in this
404 disk, and it's used by the secondary.
405 COLO network configuration looks like:
407 vif = [ '...,forwarddev=xxx,...']
409 The supported options are:
411 forwarddev : Forward devices for the primary and the secondary,
413 they are directly connected.
414 OPTIONS
416 -i MS
418 Checkpoint domain memory every MS milliseconds (default 200ms).
419 -u Disable memory checkpoint compression.
421 -s sshcommand
423 Use <sshcommand> instead of ssh. String will be passed to sh.
424 If empty, run <host> instead of ssh <host> xl migrate-receive
425 -r [-e].
426 -e On the new <host>, do not wait in the background for the death
428 of the domain. See the corresponding option of the create
429 subcommand.
430 -N netbufscript
432 Use <netbufscript> to setup network buffering instead of the
433 default script (/etc/xen/scripts/remus-netbuf-setup).
434 -F Run Remus in unsafe mode. Use this option with caution as
436 failover may not work as intended.
437 -b Replicate memory checkpoints to /dev/null (blackhole).
439 Generally useful for debugging. Requires enabling unsafe mode.
440 -n Disable network output buffering. Requires enabling unsafe
442 mode.
443 -d Disable disk replication. Requires enabling unsafe mode.
445 -c Enable COLO HA. This conflicts with -i and -b, and memory
447 checkpoint compression must be disabled.
448 -p Use userspace COLO Proxy. This option must be used in
450 conjunction with -c.
451 pause domain-id
453 Pause a domain. When in a paused state the domain will still
454 consume allocated resources (such as memory), but will not be
455 eligible for scheduling by the Xen hypervisor.
456 reboot [OPTIONS] domain-id
458 Reboot a domain. This acts just as if the domain had the reboot
459 command run from the console. The command returns as soon as it
460 has executed the reboot action, which may be significantly earlier
461 than when the domain actually reboots.
462 For HVM domains this requires PV drivers to be installed in your
464 guest OS. If PV drivers are not present but you have configured the
465 guest OS to behave appropriately you may be able to use the -F
466 option to trigger a reset button press.
467 The behavior of what happens to a domain when it reboots is set by
469 the on_reboot parameter of the domain configuration file when the
470 domain was created.
471 OPTIONS
473 -F If the guest does not support PV reboot control then fallback
475 to sending an ACPI power event (equivalent to the reset option
476 to trigger).
477 You should ensure that the guest is configured to behave as
479 expected in response to this event.
480 restore [OPTIONS] [configfile] checkpointfile
482 Build a domain from an xl save state file. See save for more info.
483 OPTIONS
485 -p Do not unpause the domain after restoring it.
487 -e Do not wait in the background for the death of the domain on
489 the new host. See the corresponding option of the create
490 subcommand.
491 -d Enable debug messages.
493 -V, --vncviewer
495 Attach to the domain's VNC server, forking a vncviewer process.
496 -A, --vncviewer-autopass
498 Pass the VNC password to vncviewer via stdin.
499 save [OPTIONS] domain-id checkpointfile [configfile]
501 Saves a running domain to a state file so that it can be restored
502 later. Once saved, the domain will no longer be running on the
503 system, unless the -c or -p options are used. xl restore restores
504 from this checkpoint file. Passing a config file argument allows
505 the user to manually select the VM config file used to create the
506 domain.
507 -c Leave the domain running after creating the snapshot.
509 -p Leave the domain paused after creating the snapshot.
511 -D Preserve the domain-id in the domain coniguration that is
513 embedded in the state file such that it will be identical when
514 the domain is restored, unless that configuration is
515 overridden. (See the restore operation above).
516 sharing [domain-id]
518 Display the number of shared pages for a specified domain. If no
519 domain is specified it displays information about all domains.
520 shutdown [OPTIONS] -a|domain-id
522 Gracefully shuts down a domain. This coordinates with the domain
523 OS to perform graceful shutdown, so there is no guarantee that it
524 will succeed, and may take a variable length of time depending on
525 what services must be shut down in the domain.
526 For HVM domains this requires PV drivers to be installed in your
528 guest OS. If PV drivers are not present but you have configured the
529 guest OS to behave appropriately you may be able to use the -F
530 option to trigger a power button press.
531 The command returns immediately after signaling the domain unless
533 the -w flag is used.
534 The behavior of what happens to a domain when it reboots is set by
536 the on_shutdown parameter of the domain configuration file when the
537 domain was created.
538 OPTIONS
540 -a, --all
542 Shutdown all guest domains. Often used when doing a complete
543 shutdown of a Xen system.
544 -w, --wait
546 Wait for the domain to complete shutdown before returning. If
547 given once, the wait is for domain shutdown or domain death.
548 If given multiple times, the wait is for domain death only.
549 -F If the guest does not support PV shutdown control then fallback
551 to sending an ACPI power event (equivalent to the power option
552 to trigger).
553 You should ensure that the guest is configured to behave as
555 expected in response to this event.
556 sysrq domain-id letter
558 Send a <Magic System Request> to the domain, each type of request
559 is represented by a different letter. It can be used to send SysRq
560 requests to Linux guests, see sysrq.txt in your Linux Kernel
561 sources for more information. It requires PV drivers to be
562 installed in your guest OS.
563 trigger domain-id nmi|reset|init|power|sleep|s3resume [VCPU]
565 Send a trigger to a domain, where the trigger can be: nmi, reset,
566 init, power or sleep. Optionally a specific vcpu number can be
567 passed as an argument. This command is only available for HVM
568 domains.
569 unpause domain-id
571 Moves a domain out of the paused state. This will allow a
572 previously paused domain to now be eligible for scheduling by the
573 Xen hypervisor.
574 vcpu-set domain-id vcpu-count
576 Enables the vcpu-count virtual CPUs for the domain in question.
577 Like mem-set, this command can only allocate up to the maximum
578 virtual CPU count configured at boot for the domain.
579 If the vcpu-count is smaller than the current number of active
581 VCPUs, the highest number VCPUs will be hotplug removed. This may
582 be important for pinning purposes.
583 Attempting to set the VCPUs to a number larger than the initially
585 configured VCPU count is an error. Trying to set VCPUs to < 1 will
586 be quietly ignored.
587 Some guests may need to actually bring the newly added CPU online
589 after vcpu-set, go to SEE ALSO section for information.
590 vcpu-list [domain-id]
592 Lists VCPU information for a specific domain. If no domain is
593 specified, VCPU information for all domains will be provided.
594 vcpu-pin [-f|--force] domain-id vcpu cpus hard cpus soft
596 Set hard and soft affinity for a vcpu of <domain-id>. Normally
597 VCPUs can float between available CPUs whenever Xen deems a
598 different run state is appropriate.
599 Hard affinity can be used to restrict this, by ensuring certain
601 VCPUs can only run on certain physical CPUs. Soft affinity
602 specifies a preferred set of CPUs. Soft affinity needs special
603 support in the scheduler, which is only provided in credit1.
604 The keyword all can be used to apply the hard and soft affinity
606 masks to all the VCPUs in the domain. The symbol '-' can be used to
607 leave either hard or soft affinity alone.
608 For example:
610 xl vcpu-pin 0 3 - 6-9
612 will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9,
614 leaving its hard affinity untouched. On the other hand:
615 xl vcpu-pin 0 3 3,4 6-9
617 will set both hard and soft affinity, the former to pCPUs 3 and 4,
619 the latter to pCPUs 6,7,8, and 9.
620 Specifying -f or --force will remove a temporary pinning done by
622 the operating system (normally this should be done by the operating
623 system). In case a temporary pinning is active for a vcpu the
624 affinity of this vcpu can't be changed without this option.
625 vm-list
627 Prints information about guests. This list excludes information
628 about service or auxiliary domains such as dom0 and stubdoms.
629 EXAMPLE
631 An example format for the list is as follows:
633 UUID ID name
635 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win
636 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux
637 vncviewer [OPTIONS] domain-id
639 Attach to the domain's VNC server, forking a vncviewer process.
640 OPTIONS
642 --autopass
644 Pass the VNC password to vncviewer via stdin.
645
647 debug-keys keys
648 Send debug keys to Xen. It is the same as pressing the Xen
649 "conswitch" (Ctrl-A by default) three times and then pressing
650 "keys".
651 set-parameters params
653 Set hypervisor parameters as specified in params. This allows for
654 some boot parameters of the hypervisor to be modified in the
655 running systems.
656 dmesg [OPTIONS]
658 Reads the Xen message buffer, similar to dmesg on a Linux system.
659 The buffer contains informational, warning, and error messages
660 created during Xen's boot process. If you are having problems with
661 Xen, this is one of the first places to look as part of problem
662 determination.
663 OPTIONS
665 -c, --clear
667 Clears Xen's message buffer.
668 info [OPTIONS]
670 Print information about the Xen host in name : value format. When
671 reporting a Xen bug, please provide this information as part of the
672 bug report. See
673 https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project
674 on how to report Xen bugs.
675 Sample output looks as follows:
677 host : scarlett
679 release : 3.1.0-rc4+
680 version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011
681 machine : x86_64
682 nr_cpus : 4
683 nr_nodes : 1
684 cores_per_socket : 4
685 threads_per_core : 1
686 cpu_mhz : 2266
687 hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000
688 virt_caps : hvm hvm_directio
689 total_memory : 6141
690 free_memory : 4274
691 free_cpus : 0
692 outstanding_claims : 0
693 xen_major : 4
694 xen_minor : 2
695 xen_extra : -unstable
696 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
697 xen_scheduler : credit
698 xen_pagesize : 4096
699 platform_params : virt_start=0xffff800000000000
700 xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241
701 xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1
702 cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8)
703 cc_compile_by : sstabellini
704 cc_compile_domain : uk.xensource.com
705 cc_compile_date : Tue Nov 8 12:03:05 UTC 2011
706 xend_config_format : 4
707 FIELDS
709 Not all fields will be explained here, but some of the less obvious
711 ones deserve explanation:
712 hw_caps
714 A vector showing what hardware capabilities are supported by
715 your processor. This is equivalent to, though more cryptic,
716 the flags field in /proc/cpuinfo on a normal Linux machine:
717 they both derive from the feature bits returned by the cpuid
718 command on x86 platforms.
719 free_memory
721 Available memory (in MB) not allocated to Xen, or any other
722 domains, or claimed for domains.
723 outstanding_claims
725 When a claim call is done (see xl.conf(5)) a reservation for a
726 specific amount of pages is set and also a global value is
727 incremented. This global value (outstanding_claims) is then
728 reduced as the domain's memory is populated and eventually
729 reaches zero. Most of the time the value will be zero, but if
730 you are launching multiple guests, and claim_mode is enabled,
731 this value can increase/decrease. Note that the value also
732 affects the free_memory - as it will reflect the free memory in
733 the hypervisor minus the outstanding pages claimed for guests.
734 See xl info claims parameter for detailed listing.
735 xen_caps
737 The Xen version and architecture. Architecture values can be
738 one of: x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
739 xen_changeset
741 The Xen mercurial changeset id. Very useful for determining
742 exactly what version of code your Xen system was built from.
743 OPTIONS
745 -n, --numa
747 List host NUMA topology information
748 top Executes the xentop(1) command, which provides real time monitoring
750 of domains. Xentop has a curses interface, and is reasonably self
751 explanatory.
752 uptime
754 Prints the current uptime of the domains running.
755 claims
757 Prints information about outstanding claims by the guests. This
758 provides the outstanding claims and currently populated memory
759 count for the guests. These values added up reflect the global
760 outstanding claim value, which is provided via the info argument,
761 outstanding_claims value. The Mem column has the cumulative value
762 of outstanding claims and the total amount of memory that has been
763 right now allocated to the guest.
764 EXAMPLE
766 An example format for the list is as follows:
768 Name ID Mem VCPUs State Time(s) Claimed
770 Domain-0 0 2047 4 r----- 19.7 0
771 OL5 2 2048 1 --p--- 0.0 847
772 OL6 3 1024 4 r----- 5.9 0
773 Windows_XP 4 2047 1 --p--- 0.0 1989
774 In which it can be seen that the OL5 guest still has 847MB of
776 claimed memory (out of the total 2048MB where 1191MB has been
777 allocated to the guest).
778
780 Xen ships with a number of domain schedulers, which can be set at boot
781 time with the sched= parameter on the Xen command line. By default
782 credit is used for scheduling.
783 sched-credit [OPTIONS]
785 Set or get credit (aka credit1) scheduler parameters. The credit
786 scheduler is a proportional fair share CPU scheduler built from the
787 ground up to be work conserving on SMP hosts.
788 Each domain (including Domain0) is assigned a weight and a cap.
790 OPTIONS
792 -d DOMAIN, --domain=DOMAIN
794 Specify domain for which scheduler parameters are to be
795 modified or retrieved. Mandatory for modifying scheduler
796 parameters.
797 -w WEIGHT, --weight=WEIGHT
799 A domain with a weight of 512 will get twice as much CPU as a
800 domain with a weight of 256 on a contended host. Legal weights
801 range from 1 to 65535 and the default is 256.
802 -c CAP, --cap=CAP
804 The cap optionally fixes the maximum amount of CPU a domain
805 will be able to consume, even if the host system has idle CPU
806 cycles. The cap is expressed in percentage of one physical CPU:
807 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
808 The default, 0, means there is no upper cap.
809 NB: Many systems have features that will scale down the
811 computing power of a cpu that is not 100% utilized. This can
812 be in the operating system, but can also sometimes be below the
813 operating system in the BIOS. If you set a cap such that
814 individual cores are running at less than 100%, this may have
815 an impact on the performance of your workload over and above
816 the impact of the cap. For example, if your processor runs at
817 2GHz, and you cap a vm at 50%, the power management system may
818 also reduce the clock speed to 1GHz; the effect will be that
819 your VM gets 25% of the available power (50% of 1GHz) rather
820 than 50% (50% of 2GHz). If you are not getting the performance
821 you expect, look at performance and cpufreq options in your
822 operating system and your BIOS.
823 -p CPUPOOL, --cpupool=CPUPOOL
825 Restrict output to domains in the specified cpupool.
826 -s, --schedparam
828 Specify to list or set pool-wide scheduler parameters.
829 -t TSLICE, --tslice_ms=TSLICE
831 Timeslice tells the scheduler how long to allow VMs to run
832 before pre-empting. The default is 30ms. Valid ranges are 1ms
833 to 1000ms. The length of the timeslice (in ms) must be higher
834 than the length of the ratelimit (see below).
835 -r RLIMIT, --ratelimit_us=RLIMIT
837 Ratelimit attempts to limit the number of schedules per second.
838 It sets a minimum amount of time (in microseconds) a VM must
839 run before we will allow a higher-priority VM to pre-empt it.
840 The default value is 1000 microseconds (1ms). Valid range is
841 100 to 500000 (500ms). The ratelimit length must be lower than
842 the timeslice length.
843 -m DELAY, --migration_delay_us=DELAY
845 Migration delay specifies for how long a vCPU, after it stopped
846 running should be considered "cache-hot". Basically, if less
847 than DELAY us passed since when the vCPU was executing on a
848 CPU, it is likely that most of the vCPU's working set is still
849 in the CPU's cache, and therefore the vCPU is not migrated.
850 Default is 0. Maximum is 100 ms. This can be effective at
852 preventing vCPUs to bounce among CPUs too quickly, but, at the
853 same time, the scheduler stops being fully work-conserving.
854 COMBINATION
856 The following is the effect of combining the above options:
858 <nothing> : List all domain params and sched params
860 from all pools
861 -d [domid] : List domain params for domain [domid]
862 -d [domid] [params] : Set domain params for domain [domid]
863 -p [pool] : list all domains and sched params for
864 [pool]
865 -s : List sched params for poolid 0
866 -s [params] : Set sched params for poolid 0
867 -p [pool] -s : List sched params for [pool]
868 -p [pool] -s [params] : Set sched params for [pool]
869 -p [pool] -d... : Illegal
870 sched-credit2 [OPTIONS]
871 Set or get credit2 scheduler parameters. The credit2 scheduler is
872 a proportional fair share CPU scheduler built from the ground up to
873 be work conserving on SMP hosts.
874 Each domain (including Domain0) is assigned a weight.
876 OPTIONS
878 -d DOMAIN, --domain=DOMAIN
880 Specify domain for which scheduler parameters are to be
881 modified or retrieved. Mandatory for modifying scheduler
882 parameters.
883 -w WEIGHT, --weight=WEIGHT
885 A domain with a weight of 512 will get twice as much CPU as a
886 domain with a weight of 256 on a contended host. Legal weights
887 range from 1 to 65535 and the default is 256.
888 -p CPUPOOL, --cpupool=CPUPOOL
890 Restrict output to domains in the specified cpupool.
891 -s, --schedparam
893 Specify to list or set pool-wide scheduler parameters.
894 -r RLIMIT, --ratelimit_us=RLIMIT
896 Attempts to limit the rate of context switching. It is
897 basically the same as --ratelimit_us in sched-credit
898 sched-rtds [OPTIONS]
900 Set or get rtds (Real Time Deferrable Server) scheduler parameters.
901 This rt scheduler applies Preemptive Global Earliest Deadline First
902 real-time scheduling algorithm to schedule VCPUs in the system.
903 Each VCPU has a dedicated period, budget and extratime. While
904 scheduled, a VCPU burns its budget. A VCPU has its budget
905 replenished at the beginning of each period; Unused budget is
906 discarded at the end of each period. A VCPU with extratime set
907 gets extra time from the unreserved system resource.
908 OPTIONS
910 -d DOMAIN, --domain=DOMAIN
912 Specify domain for which scheduler parameters are to be
913 modified or retrieved. Mandatory for modifying scheduler
914 parameters.
915 -v VCPUID/all, --vcpuid=VCPUID/all
917 Specify vcpu for which scheduler parameters are to be modified
918 or retrieved.
919 -p PERIOD, --period=PERIOD
921 Period of time, in microseconds, over which to replenish the
922 budget.
923 -b BUDGET, --budget=BUDGET
925 Amount of time, in microseconds, that the VCPU will be allowed
926 to run every period.
927 -e Extratime, --extratime=Extratime
929 Binary flag to decide if the VCPU will be allowed to get extra
930 time from the unreserved system resource.
931 -c CPUPOOL, --cpupool=CPUPOOL
933 Restrict output to domains in the specified cpupool.
934 EXAMPLE
936 1) Use -v all to see the budget and period of all the VCPUs of
938 all the domains:
939 xl sched-rtds -v all
941 Cpupool Pool-0: sched=RTDS
942 Name ID VCPU Period Budget Extratime
943 Domain-0 0 0 10000 4000 yes
944 vm1 2 0 300 150 yes
945 vm1 2 1 400 200 yes
946 vm1 2 2 10000 4000 yes
947 vm1 2 3 1000 500 yes
948 vm2 4 0 10000 4000 yes
949 vm2 4 1 10000 4000 yes
950 Without any arguments, it will output the default scheduling
952 parameters for each domain:
953 xl sched-rtds
955 Cpupool Pool-0: sched=RTDS
956 Name ID Period Budget Extratime
957 Domain-0 0 10000 4000 yes
958 vm1 2 10000 4000 yes
959 vm2 4 10000 4000 yes
960 2) Use, for instance, -d vm1, -v all to see the budget and
962 period of all VCPUs of a specific domain (vm1):
963 xl sched-rtds -d vm1 -v all
965 Name ID VCPU Period Budget Extratime
966 vm1 2 0 300 150 yes
967 vm1 2 1 400 200 yes
968 vm1 2 2 10000 4000 yes
969 vm1 2 3 1000 500 yes
970 To see the parameters of a subset of the VCPUs of a domain,
972 use:
973 xl sched-rtds -d vm1 -v 0 -v 3
975 Name ID VCPU Period Budget Extratime
976 vm1 2 0 300 150 yes
977 vm1 2 3 1000 500 yes
978 If no -v is specified, the default scheduling parameters for
980 the domain are shown:
981 xl sched-rtds -d vm1
983 Name ID Period Budget Extratime
984 vm1 2 10000 4000 yes
985 3) Users can set the budget and period of multiple VCPUs of a
987 specific domain with only one command, e.g., "xl sched-rtds -d
988 vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0".
989 To change the parameters of all the VCPUs of a domain, use -v
991 all, e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1".
992
994 Xen can group the physical cpus of a server in cpu-pools. Each physical
995 CPU is assigned at most to one cpu-pool. Domains are each restricted to
996 a single cpu-pool. Scheduling does not cross cpu-pool boundaries, so
997 each cpu-pool has its own scheduler. Physical cpus and domains can be
998 moved from one cpu-pool to another only by an explicit command. Cpu-
999 pools can be specified either by name or by id.
1000 cpupool-create [OPTIONS] [configfile] [variable=value ...]
1002 Create a cpu pool based an config from a configfile or command-line
1003 parameters. Variable settings from the configfile may be altered
1004 by specifying new or additional assignments on the command line.
1005 See the xlcpupool.cfg(5) manpage for more information.
1007 OPTIONS
1009 -f=FILE, --defconfig=FILE
1011 Use the given configuration file.
1012 cpupool-list [OPTIONS] [cpu-pool]
1014 List CPU pools on the host.
1015 OPTIONS
1017 -c, --cpus
1019 If this option is specified, xl prints a list of CPUs used by
1020 cpu-pool.
1021 cpupool-destroy cpu-pool
1023 Deactivates a cpu pool. This is possible only if no domain is
1024 active in the cpu-pool.
1025 cpupool-rename cpu-pool <newname>
1027 Renames a cpu-pool to newname.
1028 cpupool-cpu-add cpu-pool cpus|node:nodes
1030 Adds one or more CPUs or NUMA nodes to cpu-pool. CPUs and NUMA
1031 nodes can be specified as single CPU/node IDs or as ranges.
1032 For example:
1034 (a) xl cpupool-cpu-add mypool 4
1036 (b) xl cpupool-cpu-add mypool 1,5,10-16,^13
1037 (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8
1038 means adding CPU 4 to mypool, in (a); adding CPUs
1040 1,5,10,11,12,14,15 and 16, in (b); and adding all the CPUs of NUMA
1041 nodes 0, 2 and 3, plus CPU 8, but keeping out CPUs 10,11,12, in
1042 (c).
1043 All the specified CPUs that can be added to the cpupool will be
1045 added to it. If some CPU can't (e.g., because they're already part
1046 of another cpupool), an error is reported about each one of them.
1047 cpupool-cpu-remove cpu-pool cpus|node:nodes
1049 Removes one or more CPUs or NUMA nodes from cpu-pool. CPUs and NUMA
1050 nodes can be specified as single CPU/node IDs or as ranges, using
1051 the exact same syntax as in cpupool-cpu-add above.
1052 cpupool-migrate domain-id cpu-pool
1054 Moves a domain specified by domain-id or domain-name into a cpu-
1055 pool. Domain-0 can't be moved to another cpu-pool.
1056 cpupool-numa-split
1058 Splits up the machine into one cpu-pool per numa node.
1059
1061 Most virtual devices can be added and removed while guests are running,
1062 assuming that the necessary support exists in the guest OS. The effect
1063 to the guest OS is much the same as any hotplug event.
1064 BLOCK DEVICES
1066 block-attach domain-id disc-spec-component(s) ...
1067 Create a new virtual block device and attach it to the specified
1068 domain. A disc specification is in the same format used for the
1069 disk variable in the domain config file. See
1070 xl-disk-configuration(5). This will trigger a hotplug event for the
1071 guest.
1072 Note that only PV block devices are supported by block-attach.
1074 Requests to attach emulated devices (eg, vdev=hdc) will result in
1075 only the PV view being available to the guest.
1076 block-detach [OPTIONS] domain-id devid
1078 Detach a domain's virtual block device. devid may be the symbolic
1079 name or the numeric device id given to the device by domain 0. You
1080 will need to run xl block-list to determine that number.
1081 Detaching the device requires the cooperation of the domain. If
1083 the domain fails to release the device (perhaps because the domain
1084 is hung or is still using the device), the detach will fail.
1085 OPTIONS
1087 --force
1089 If this parameter is specified the device will be forcefully
1090 detached, which may cause IO errors in the domain and possibly
1091 a guest crash
1092 block-list domain-id
1094 List virtual block devices for a domain.
1095 cd-insert domain-id virtualdevice target
1097 Insert a cdrom into a guest domain's existing virtual cd drive. The
1098 virtual drive must already exist but can be empty. How the device
1099 should be presented to the guest domain is specified by the
1100 virtualdevice parameter; for example "hdc". Parameter target is the
1101 target path in the backend domain (usually domain 0) to be
1102 exported; can be a block device or a file etc. See target in
1103 xl-disk-configuration(5).
1104 Only works with HVM domains.
1106 cd-eject domain-id virtualdevice
1108 Eject a cdrom from a guest domain's virtual cd drive, specified by
1109 virtualdevice. Only works with HVM domains.
1110 NETWORK DEVICES
1112 network-attach domain-id network-device
1113 Creates a new network device in the domain specified by domain-id.
1114 network-device describes the device to attach, using the same
1115 format as the vif string in the domain config file. See xl.cfg(5)
1116 and xl-network-configuration(5) for more information.
1117 Note that only attaching PV network interfaces is supported.
1119 network-detach domain-id devid|mac
1121 Removes the network device from the domain specified by domain-id.
1122 devid is the virtual interface device number within the domain
1123 (i.e. the 3 in vif22.3). Alternatively, the mac address can be used
1124 to select the virtual interface to detach.
1125 network-list domain-id
1127 List virtual network interfaces for a domain.
1128 CHANNEL DEVICES
1130 channel-list domain-id
1131 List virtual channel interfaces for a domain.
1132 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES
1134 vtpm-attach domain-id vtpm-device
1135 Creates a new vtpm (virtual Trusted Platform Module) device in the
1136 domain specified by domain-id. vtpm-device describes the device to
1137 attach, using the same format as the vtpm string in the domain
1138 config file. See xl.cfg(5) for more information.
1139 vtpm-detach domain-id devid|uuid
1141 Removes the vtpm device from the domain specified by domain-id.
1142 devid is the numeric device id given to the virtual Trusted
1143 Platform Module device. You will need to run xl vtpm-list to
1144 determine that number. Alternatively, the uuid of the vtpm can be
1145 used to select the virtual device to detach.
1146 vtpm-list domain-id
1148 List virtual Trusted Platform Modules for a domain.
1149 VDISPL DEVICES
1151 vdispl-attach domain-id vdispl-device
1152 Creates a new vdispl device in the domain specified by domain-id.
1153 vdispl-device describes the device to attach, using the same format
1154 as the vdispl string in the domain config file. See xl.cfg(5) for
1155 more information.
1156 NOTES
1158 As in vdispl-device string semicolon is used then put quotes or
1160 escaping when using from the shell.
1161 EXAMPLE
1163 xl vdispl-attach DomU
1165 connectors='id0:1920x1080;id1:800x600;id2:640x480'
1166 or
1168 xl vdispl-attach DomU
1170 connectors=id0:1920x1080\;id1:800x600\;id2:640x480
1171 vdispl-detach domain-id dev-id
1173 Removes the vdispl device specified by dev-id from the domain
1174 specified by domain-id.
1175 vdispl-list domain-id
1177 List virtual displays for a domain.
1178 VSND DEVICES
1180 vsnd-attach domain-id vsnd-item vsnd-item ...
1181 Creates a new vsnd device in the domain specified by domain-id.
1182 vsnd-item's describe the vsnd device to attach, using the same
1183 format as the VSND_ITEM_SPEC string in the domain config file. See
1184 xl.cfg(5) for more information.
1185 EXAMPLE
1187 xl vsnd-attach DomU 'CARD, short-name=Main,
1189 sample-formats=s16_le;s8;u32_be' 'PCM, name=Main' 'STREAM,
1190 id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
1191 vsnd-detach domain-id dev-id
1193 Removes the vsnd device specified by dev-id from the domain
1194 specified by domain-id.
1195 vsnd-list domain-id
1197 List vsnd devices for a domain.
1198 KEYBOARD DEVICES
1200 vkb-attach domain-id vkb-device
1201 Creates a new keyboard device in the domain specified by domain-id.
1202 vkb-device describes the device to attach, using the same format as
1203 the VKB_SPEC_STRING string in the domain config file. See xl.cfg(5)
1204 for more information.
1205 vkb-detach domain-id devid
1207 Removes the keyboard device from the domain specified by domain-id.
1208 devid is the virtual interface device number within the domain
1209 vkb-list domain-id
1211 List virtual network interfaces for a domain.
1212
1214 pci-assignable-list [-n]
1215 List all the BDF of assignable PCI devices. See
1216 xl-pci-configuration(5) for more information. If the -n option is
1217 specified then any name supplied when the device was made
1218 assignable will also be displayed.
1219 These are devices in the system which are configured to be
1221 available for passthrough and are bound to a suitable PCI backend
1222 driver in domain 0 rather than a real driver.
1223 pci-assignable-add [-n NAME] BDF
1225 Make the device at BDF assignable to guests. See
1226 xl-pci-configuration(5) for more information. If the -n option is
1227 supplied then the assignable device entry will the named with the
1228 given NAME.
1229 This will bind the device to the pciback driver and assign it to
1231 the "quarantine domain". If it is already bound to a driver, it
1232 will first be unbound, and the original driver stored so that it
1233 can be re-bound to the same driver later if desired. If the device
1234 is already bound, it will assign it to the quarantine domain and
1235 return success.
1236 CAUTION: This will make the device unusable by Domain 0 until it is
1238 returned with pci-assignable-remove. Care should therefore be
1239 taken not to do this on a device critical to domain 0's operation,
1240 such as storage controllers, network interfaces, or GPUs that are
1241 currently being used.
1242 pci-assignable-remove [-r] BDF|NAME
1244 Make a device non-assignable to guests. The device may be
1245 identified either by its BDF or the NAME supplied when the device
1246 was made assignable. See xl-pci-configuration(5) for more
1247 information.
1248 This will at least unbind the device from pciback, and re-assign it
1250 from the "quarantine domain" back to domain 0. If the -r option is
1251 specified, it will also attempt to re-bind the device to its
1252 original driver, making it usable by Domain 0 again. If the device
1253 is not bound to pciback, it will return success.
1254 Note that this functionality will work even for devices which were
1256 not made assignable by pci-assignable-add. This can be used to
1257 allow dom0 to access devices which were automatically quarantined
1258 by Xen after domain destruction as a result of Xen's
1259 iommu=quarantine command-line default.
1260 As always, this should only be done if you trust the guest, or are
1262 confident that the particular device you're re-assigning to dom0
1263 will cancel all in-flight DMA on FLR.
1264 pci-attach domain-id PCI_SPEC_STRING
1266 Hot-plug a new pass-through pci device to the specified domain. See
1267 xl-pci-configuration(5) for more information.
1268 pci-detach [OPTIONS] domain-id PCI_SPEC_STRING
1270 Hot-unplug a pci device that was previously passed through to a
1271 domain. See xl-pci-configuration(5) for more information.
1272 OPTIONS
1274 -f If this parameter is specified, xl is going to forcefully
1276 remove the device even without guest domain's collaboration.
1277 pci-list domain-id
1279 List the BDF of pci devices passed through to a domain.
1280
1282 usbctrl-attach domain-id usbctrl-device
1283 Create a new USB controller in the domain specified by domain-id,
1284 usbctrl-device describes the device to attach, using form
1285 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1286 the usbctrl description in the domain config file. See xl.cfg(5)
1287 for more information.
1288 usbctrl-detach domain-id devid
1290 Destroy a USB controller from the specified domain. devid is devid
1291 of the USB controller.
1292 usbdev-attach domain-id usbdev-device
1294 Hot-plug a new pass-through USB device to the domain specified by
1295 domain-id, usbdev-device describes the device to attach, using form
1296 "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1297 the usbdev description in the domain config file. See xl.cfg(5)
1298 for more information.
1299 usbdev-detach domain-id controller=devid port=number
1301 Hot-unplug a previously assigned USB device from a domain.
1302 controller=devid and port=number is USB controller:port in the
1303 guest domain the USB device is attached to.
1304 usb-list domain-id
1306 List pass-through usb devices for a domain.
1307
1309 qemu-monitor-command domain-id command
1310 Issue a monitor command to the device model of the domain specified
1311 by domain-id. command can be any valid command qemu understands.
1312 This can be e.g. used to add non-standard devices or devices with
1313 non-standard parameters to a domain. The output of the command is
1314 printed to stdout.
1315 Warning: This qemu monitor access is provided for convenience when
1317 debugging, troubleshooting, and experimenting. Its use is not
1318 supported by the Xen Project.
1319 Specifically, not all information displayed by the qemu monitor
1321 will necessarily be accurate or complete, because in a Xen system
1322 qemu does not have a complete view of the guest.
1323 Furthermore, modifying the guest's setup via the qemu monitor may
1325 conflict with the Xen toolstack's assumptions. Resulting problems
1326 may include, but are not limited to: guest crashes; toolstack error
1327 messages; inability to migrate the guest; and security
1328 vulnerabilities which are not covered by the Xen Project security
1329 response policy.
1330 EXAMPLE
1332 Obtain information of USB devices connected as such via the device
1334 model (only!) to a domain:
1335 xl qemu-monitor-command vm1 'info usb'
1337 Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
1338
1340 FLASK is a security framework that defines a mandatory access control
1341 policy providing fine-grained controls over Xen domains, allowing the
1342 policy writer to define what interactions between domains, devices, and
1343 the hypervisor are permitted. Some example of what you can do using
1344 XSM/FLASK:
1345 - Prevent two domains from communicating via event channels or grants
1346 - Control which domains can use device passthrough (and which devices)
1347 - Restrict or audit operations performed by privileged domains
1348 - Prevent a privileged domain from arbitrarily mapping pages from
1349 other
1350 domains.
1351 You can find more details on how to use FLASK and an example security
1353 policy here:
1354 <https://xenbits.xenproject.org/docs/unstable/misc/xsm-flask.txt>
1355 getenforce
1357 Determine if the FLASK security module is loaded and enforcing its
1358 policy.
1359 setenforce 1|0|Enforcing|Permissive
1361 Enable or disable enforcing of the FLASK access controls. The
1362 default is permissive, but this can be changed to enforcing by
1363 specifying "flask=enforcing" or "flask=late" on the hypervisor's
1364 command line.
1365 loadpolicy policy-file
1367 Load FLASK policy from the given policy file. The initial policy is
1368 provided to the hypervisor as a multiboot module; this command
1369 allows runtime updates to the policy. Loading new security policy
1370 will reset runtime changes to device labels.
1371
1373 Intel Haswell and later server platforms offer shared resource
1374 monitoring and control technologies. The availability of these
1375 technologies and the hardware capabilities can be shown with psr-
1376 hwinfo.
1377 See <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html> for
1379 more information.
1380 psr-hwinfo [OPTIONS]
1382 Show Platform Shared Resource (PSR) hardware information.
1383 OPTIONS
1385 -m, --cmt
1387 Show Cache Monitoring Technology (CMT) hardware information.
1388 -a, --cat
1390 Show Cache Allocation Technology (CAT) hardware information.
1391 CACHE MONITORING TECHNOLOGY
1393 Intel Haswell and later server platforms offer monitoring capability in
1394 each logical processor to measure specific platform shared resource
1395 metric, for example, L3 cache occupancy. In the Xen implementation, the
1396 monitoring granularity is domain level. To monitor a specific domain,
1397 just attach the domain id with the monitoring service. When the domain
1398 doesn't need to be monitored any more, detach the domain id from the
1399 monitoring service.
1400 Intel Broadwell and later server platforms also offer total/local
1402 memory bandwidth monitoring. Xen supports per-domain monitoring for
1403 these two additional monitoring types. Both memory bandwidth monitoring
1404 and L3 cache occupancy monitoring share the same set of underlying
1405 monitoring service. Once a domain is attached to the monitoring
1406 service, monitoring data can be shown for any of these monitoring
1407 types.
1408 There is no cache monitoring and memory bandwidth monitoring on L2
1410 cache so far.
1411 psr-cmt-attach domain-id
1413 attach: Attach the platform shared resource monitoring service to a
1414 domain.
1415 psr-cmt-detach domain-id
1417 detach: Detach the platform shared resource monitoring service from
1418 a domain.
1419 psr-cmt-show psr-monitor-type [domain-id]
1421 Show monitoring data for a certain domain or all domains. Current
1422 supported monitor types are:
1423 - "cache-occupancy": showing the L3 cache occupancy(KB).
1424 - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
1425 - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
1426 CACHE ALLOCATION TECHNOLOGY
1428 Intel Broadwell and later server platforms offer capabilities to
1429 configure and make use of the Cache Allocation Technology (CAT)
1430 mechanisms, which enable more cache resources (i.e. L3/L2 cache) to be
1431 made available for high priority applications. In the Xen
1432 implementation, CAT is used to control cache allocation on VM basis. To
1433 enforce cache on a specific domain, just set capacity bitmasks (CBM)
1434 for the domain.
1435 Intel Broadwell and later server platforms also offer Code/Data
1437 Prioritization (CDP) for cache allocations, which support specifying
1438 code or data cache for applications. CDP is used on a per VM basis in
1439 the Xen implementation. To specify code or data CBM for the domain, CDP
1440 feature must be enabled and CBM type options need to be specified when
1441 setting CBM, and the type options (code and data) are mutually
1442 exclusive. There is no CDP support on L2 so far.
1443 psr-cat-set [OPTIONS] domain-id cbm
1445 Set cache capacity bitmasks(CBM) for a domain. For how to specify
1446 cbm please refer to
1447 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>.
1448 OPTIONS
1450 -s SOCKET, --socket=SOCKET
1452 Specify the socket to process, otherwise all sockets are
1453 processed.
1454 -l LEVEL, --level=LEVEL
1456 Specify the cache level to process, otherwise the last level
1457 cache (L3) is processed.
1458 -c, --code
1460 Set code CBM when CDP is enabled.
1461 -d, --data
1463 Set data CBM when CDP is enabled.
1464 psr-cat-show [OPTIONS] [domain-id]
1466 Show CAT settings for a certain domain or all domains.
1467 OPTIONS
1469 -l LEVEL, --level=LEVEL
1471 Specify the cache level to process, otherwise the last level
1472 cache (L3) is processed.
1473 Memory Bandwidth Allocation
1475 Intel Skylake and later server platforms offer capabilities to
1476 configure and make use of the Memory Bandwidth Allocation (MBA)
1477 mechanisms, which provides OS/VMMs the ability to slow misbehaving
1478 apps/VMs by using a credit-based throttling mechanism. In the Xen
1479 implementation, MBA is used to control memory bandwidth on VM basis. To
1480 enforce bandwidth on a specific domain, just set throttling value
1481 (THRTL) for the domain.
1482 psr-mba-set [OPTIONS] domain-id thrtl
1484 Set throttling value (THRTL) for a domain. For how to specify thrtl
1485 please refer to
1486 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>.
1487 OPTIONS
1489 -s SOCKET, --socket=SOCKET
1491 Specify the socket to process, otherwise all sockets are
1492 processed.
1493 psr-mba-show [domain-id]
1495 Show MBA settings for a certain domain or all domains. For linear
1496 mode, it shows the decimal value. For non-linear mode, it shows
1497 hexadecimal value.
1498
1500 xl is mostly command-line compatible with the old xm utility used with
1501 the old Python xend. For compatibility, the following options are
1502 ignored:
1503 xl migrate --live
1505
1507 The following environment variables shall affect the execution of xl:
1508 LIBXL_BOOTLOADER_RESTRICT
1510 Attempt to restrict the bootloader after startup, to limit the
1511 consequences of security vulnerabilities due to parsing guest owned
1512 image files.
1513 See docs/features/qemu-deprivilege.pandoc for more information on
1515 how to setup the unprivileged users.
1516 Note that running the bootloader in restricted mode also implies
1518 using non-interactive mode, and the disk image must be readable by
1519 the restricted user.
1520 Having this variable set is equivalent to enabling the option, even
1522 if the value is 0.
1523 LIBXL_BOOTLOADER_USER
1525 When using bootloader_restrict, run the bootloader as this user.
1526 If not set the default QEMU restrict users will be used.
1527 NOTE: Each domain MUST have a SEPARATE username.
1529 See docs/features/qemu-deprivilege.pandoc for more information.
1531 LIBXL_BOOTLOADER_TIMEOUT
1533 Timeout in seconds for bootloader execution when running in
1534 restricted mode. Otherwise the build time default in
1535 LIBXL_BOOTLOADER_TIMEOUT will be used.
1536 If defined the value must be an unsigned integer between 0 and
1538 INT_MAX, otherwise behavior is undefined. Setting to 0 disables
1539 the timeout.
1540
1542 The following man pages:
1543 xl.cfg(5), xlcpupool.cfg(5), xentop(1), xl-disk-configuration(5)
1545 xl-network-configuration(5)
1546 And the following documents on the xenproject.org website:
1548 <https://xenbits.xenproject.org/docs/unstable/misc/xsm-flask.txt>
1550 <https://xenbits.xenproject.org/docs/unstable/misc/xl-psr.html>
1551 For systems that don't automatically bring the CPU online:
1553 <https://wiki.xenproject.org/wiki/Paravirt_Linux_CPU_Hotplug>
1555
1557 Send bugs to xen-devel@lists.xenproject.org, see
1558 https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project on
1559 how to send bug reports.
15604.17.2 2023-11-14 xl(1)