1xl(1)                                 Xen                                xl(1)
2
3
4

NAME

6       xl - Xen management tool, based on LibXenlight
7

SYNOPSIS

9       xl subcommand [args]
10

DESCRIPTION

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
17       The basic structure of every xl command is almost always:
18
19         xl subcommand [OPTIONS] domain-id
20
21       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

NOTES

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
35       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
41       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
46       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

GLOBAL OPTIONS

52       Some global options are always available:
53
54       -v  Verbose.
55
56       -N  Dry run: do not actually execute the command.
57
58       -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
62       -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

DOMAIN SUBCOMMANDS

67       The following subcommands manipulate domains directly.  As stated
68       previously, most commands take domain-id as the first parameter.
69
70       button-press domain-id button
71           This command is deprecated. Please use "xl trigger" instead.
72
73           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
76       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
82           configfile has to be an absolute path to a file.
83
84           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
88           If the -F option is specified, create will start the domain and not
89           return until its death.
90
91           OPTIONS
92
93           -q, --quiet
94               No console output.
95
96           -f=FILE, --defconfig=FILE
97               Use the given configuration file.
98
99           -p  Leave the domain paused after it is created.
100
101           -F  Run in foreground until death of the domain.
102
103           -V, --vncviewer
104               Attach to domain's VNC server, forking a vncviewer process.
105
106           -A, --vncviewer-autopass
107               Pass the VNC password to vncviewer via stdin.
108
109           -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
114           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
119               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
126           EXAMPLES
127
128           with config file
129                 xl create DebianLenny
130
131               This creates a domain with the file /etc/xen/DebianLenny, and
132               returns as soon as it is run.
133
134           with extra parameters
135                 xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
136
137               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
140       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
147           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
152           configfile has to be an absolute path to a file.
153
154           OPTIONS
155
156           -f=FILE, --defconfig=FILE
157               Use the given configuration file.
158
159           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
166       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
171           Use the key combination Ctrl+] to detach from the domain console.
172
173           OPTIONS
174
175           -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
182           -n NUM
183               Connect to console number NUM. Console numbers start from 0.
184
185       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
191           OPTIONS
192
193           -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
198       domid domain-name
199           Converts a domain name to a domain id.
200
201       domname domain-id
202           Converts a domain id to a domain name.
203
204       rename domain-id new-name
205           Change the domain name of a domain specified by domain-id to new-
206           name.
207
208       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
214       help [--long]
215           Displays the short help message (i.e. common commands) by default.
216
217           If the --long option is specified, it displays the complete set of
218           xl subcommands, grouped by function.
219
220       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
224           OPTIONS
225
226           -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
230           -Z, --context
231               Also displays the security labels.
232
233           -v, --verbose
234               Also displays the domain UUIDs, the shutdown reason and
235               security labels.
236
237           -c, --cpupool
238               Also displays the cpupool the domain belongs to.
239
240           -n, --numa
241               Also displays the domain NUMA node affinity.
242
243           EXAMPLE
244
245           An example format for the list is as follows:
246
247               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
252           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
259           STATES
260
261           The State field lists 6 states for a Xen domain, and which ones the
262           current domain is in.
263
264           r - running
265               The domain is currently running on a CPU.
266
267           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
273           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
279           s - shutdown
280               The guest OS has shut down (SCHEDOP_shutdown has been called)
281               but the domain is not dying yet.
282
283           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
289           d - dying
290               The domain is in the process of dying, but hasn't completely
291               shut down or crashed.
292
293           NOTES
294
295               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
303       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
308           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
312           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
321           The domain will not receive any signal regarding the changed memory
322           limit.
323
324       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
329           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
334           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
338       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
342           OPTIONS
343
344           -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
349           -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
353           -C config
354               Send the specified <config> file instead of the file used on
355               creation of the domain.
356
357           --debug
358               Display huge (!) amount of debug information during the
359               migration process.
360
361           -p  Leave the domain on the receive side paused after migration.
362
363       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
367           NOTES
368
369               Remus support in xl is still in experimental (proof-of-concept)
370               phase.  Disk replication support is limited to DRBD disks.
371
372               COLO support in xl is still in experimental (proof-of-concept)
373               phase. All options are subject to change in the future.
374
375           COLO disk configuration looks like:
376
377             disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
378
379           The supported options are:
380
381           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
390           COLO network configuration looks like:
391
392             vif = [ '...,forwarddev=xxx,...']
393
394           The supported options are:
395
396           forwarddev : Forward devices for the primary and the secondary,
397           they are directly connected.
398
399           OPTIONS
400
401           -i MS
402               Checkpoint domain memory every MS milliseconds (default 200ms).
403
404           -u  Disable memory checkpoint compression.
405
406           -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
411           -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
415           -N netbufscript
416               Use <netbufscript> to setup network buffering instead of the
417               default script (/etc/xen/scripts/remus-netbuf-setup).
418
419           -F  Run Remus in unsafe mode. Use this option with caution as
420               failover may not work as intended.
421
422           -b  Replicate memory checkpoints to /dev/null (blackhole).
423               Generally useful for debugging. Requires enabling unsafe mode.
424
425           -n  Disable network output buffering. Requires enabling unsafe
426               mode.
427
428           -d  Disable disk replication. Requires enabling unsafe mode.
429
430           -c  Enable COLO HA. This conflicts with -i and -b, and memory
431               checkpoint compression must be disabled.
432
433           -p  Use userspace COLO Proxy. This option must be used in
434               conjunction with -c.
435
436       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
441       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
447           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
452           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
456           OPTIONS
457
458           -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
462               You should ensure that the guest is configured to behave as
463               expected in response to this event.
464
465       restore [OPTIONS] [configfile] checkpointfile
466           Build a domain from an xl save state file.  See save for more info.
467
468           OPTIONS
469
470           -p  Do not unpause the domain after restoring it.
471
472           -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
476           -d  Enable debug messages.
477
478           -V, --vncviewer
479               Attach to the domain's VNC server, forking a vncviewer process.
480
481           -A, --vncviewer-autopass
482               Pass the VNC password to vncviewer via stdin.
483
484       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
492           -c  Leave the domain running after creating the snapshot.
493
494           -p  Leave the domain paused after creating the snapshot.
495
496       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
500       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
506           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
511           The command returns immediately after signaling the domain unless
512           the -w flag is used.
513
514           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
518           OPTIONS
519
520           -a, --all
521               Shutdown all guest domains.  Often used when doing a complete
522               shutdown of a Xen system.
523
524           -w, --wait
525               Wait for the domain to complete shutdown before returning.
526
527           -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
531               You should ensure that the guest is configured to behave as
532               expected in response to this event.
533
534       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
541       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
547       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
552       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
557           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
561           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
565           Some guests may need to actually bring the newly added CPU online
566           after vcpu-set, go to SEE ALSO section for information.
567
568       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
572       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
577           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
582           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
586           For example:
587
588            xl vcpu-pin 0 3 - 6-9
589
590           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
593            xl vcpu-pin 0 3 3,4 6-9
594
595           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
598           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
603       vm-list
604           Prints information about guests. This list excludes information
605           about service or auxiliary domains such as dom0 and stubdoms.
606
607           EXAMPLE
608
609           An example format for the list is as follows:
610
611               UUID                                  ID    name
612               59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5  2    win
613               50bc8f75-81d0-4d53-b2e6-95cb44e2682e  3    linux
614
615       vncviewer [OPTIONS] domain-id
616           Attach to the domain's VNC server, forking a vncviewer process.
617
618           OPTIONS
619
620           --autopass
621               Pass the VNC password to vncviewer via stdin.
622

XEN HOST SUBCOMMANDS

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
629       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
634       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
641           OPTIONS
642
643           -c, --clear
644               Clears Xen's message buffer.
645
646       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
652           Sample output looks as follows:
653
654            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
684           FIELDS
685
686           Not all fields will be explained here, but some of the less obvious
687           ones deserve explanation:
688
689           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
696           free_memory
697               Available memory (in MB) not allocated to Xen, or any other
698               domains, or claimed for domains.
699
700           outstanding_claims
701               When a claim call is done (see xl.conf) 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
712           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
716           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
720           OPTIONS
721
722           -n, --numa
723               List host NUMA topology information
724
725       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
729       uptime
730           Prints the current uptime of the domains running.
731
732       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
741           EXAMPLE
742
743           An example format for the list is as follows:
744
745            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
751           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

SCHEDULER SUBCOMMANDS

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
760       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
765           Each domain (including Domain0) is assigned a weight and a cap.
766
767           OPTIONS
768
769           -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
774           -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
779           -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
786               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
800           -p CPUPOOL, --cpupool=CPUPOOL
801               Restrict output to domains in the specified cpupool.
802
803           -s, --schedparam
804               Specify to list or set pool-wide scheduler parameters.
805
806           -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
812           -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
820           -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
827               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
831           COMBINATION
832
833           The following is the effect of combining the above options:
834
835           <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
851           Each domain (including Domain0) is assigned a weight.
852
853           OPTIONS
854
855           -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
860           -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
865           -p CPUPOOL, --cpupool=CPUPOOL
866               Restrict output to domains in the specified cpupool.
867
868           -s, --schedparam
869               Specify to list or set pool-wide scheduler parameters.
870
871           -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
875       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
885           OPTIONS
886
887           -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
892           -v VCPUID/all, --vcpuid=VCPUID/all
893               Specify vcpu for which scheduler parameters are to be modified
894               or retrieved.
895
896           -p PERIOD, --period=PERIOD
897               Period of time, in microseconds, over which to replenish the
898               budget.
899
900           -b BUDGET, --budget=BUDGET
901               Amount of time, in microseconds, that the VCPU will be allowed
902               to run every period.
903
904           -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
908           -c CPUPOOL, --cpupool=CPUPOOL
909               Restrict output to domains in the specified cpupool.
910
911           EXAMPLE
912
913               1) Use -v all to see the budget and period of all the VCPUs of
914               all the domains:
915
916                   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
927               Without any arguments, it will output the default scheduling
928               parameters for each domain:
929
930                   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
937               2) Use, for instance, -d vm1, -v all to see the budget and
938               period of all VCPUs of a specific domain (vm1):
939
940                   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
947               To see the parameters of a subset of the VCPUs of a domain,
948               use:
949
950                   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
955               If no -v is specified, the default scheduling parameters for
956               the domain are shown:
957
958                   xl sched-rtds -d vm1
959                   Name                        ID    Period    Budget  Extratime
960                   vm1                          2     10000      4000        yes
961
962               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
966               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

CPUPOOLS COMMANDS

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
977       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
982           See the xlcpupool.cfg(5) manpage for more information.
983
984           OPTIONS
985
986           -f=FILE, --defconfig=FILE
987               Use the given configuration file.
988
989       cpupool-list [OPTIONS] [cpu-pool]
990           List CPU pools on the host.
991
992           OPTIONS
993
994           -c, --cpus
995               If this option is specified, xl prints a list of CPUs used by
996               cpu-pool.
997
998       cpupool-destroy cpu-pool
999           Deactivates a cpu pool.  This is possible only if no domain is
1000           active in the cpu-pool.
1001
1002       cpupool-rename cpu-pool <newname>
1003           Renames a cpu-pool to newname.
1004
1005       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
1009           For example:
1010
1011            (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
1015           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
1020           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
1024       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
1029       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
1033       cpupool-numa-split
1034           Splits up the machine into one cpu-pool per numa node.
1035

VIRTUAL DEVICE COMMANDS

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
1041   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
1049           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
1053       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
1058           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
1062           OPTIONS
1063
1064           --force
1065               If this parameter is specified the device will be forcefully
1066               detached, which may cause IO errors in the domain.
1067
1068       block-list domain-id
1069           List virtual block devices for a domain.
1070
1071       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
1080           Only works with HVM domains.
1081
1082       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
1086   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 informations.
1092
1093           Note that only attaching PV network interfaces is supported.
1094
1095       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
1101       network-list domain-id
1102           List virtual network interfaces for a domain.
1103
1104   CHANNEL DEVICES
1105       channel-list domain-id
1106           List virtual channel interfaces for a domain.
1107
1108   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
1115       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
1122       vtpm-list domain-id
1123           List virtual Trusted Platform Modules for a domain.
1124
1125   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 for more
1130           information.
1131
1132           NOTES
1133
1134               As in vdispl-device string semicolon is used then put quotes or
1135               escaping when using from the shell.
1136
1137               EXAMPLE
1138
1139                   xl vdispl-attach DomU
1140                   connectors='id0:1920x1080;id1:800x600;id2:640x480'
1141
1142                   or
1143
1144                   xl vdispl-attach DomU
1145                   connectors=id0:1920x1080\;id1:800x600\;id2:640x480
1146
1147       vdispl-detach domain-id dev-id
1148           Removes the vdispl device specified by dev-id from the domain
1149           specified by domain-id.
1150
1151       vdispl-list domain-id
1152           List virtual displays for a domain.
1153

PCI PASS-THROUGH

1155       pci-assignable-list
1156           List all the assignable PCI devices.  These are devices in the
1157           system which are configured to be available for passthrough and are
1158           bound to a suitable PCI backend driver in domain 0 rather than a
1159           real driver.
1160
1161       pci-assignable-add BDF
1162           Make the device at PCI Bus/Device/Function BDF assignable to
1163           guests.  This will bind the device to the pciback driver.  If it is
1164           already bound to a driver, it will first be unbound, and the
1165           original driver stored so that it can be re-bound to the same
1166           driver later if desired.  If the device is already bound, it will
1167           return success.
1168
1169           CAUTION: This will make the device unusable by Domain 0 until it is
1170           returned with pci-assignable-remove.  Care should therefore be
1171           taken not to do this on a device critical to domain 0's operation,
1172           such as storage controllers, network interfaces, or GPUs that are
1173           currently being used.
1174
1175       pci-assignable-remove [-r] BDF
1176           Make the device at PCI Bus/Device/Function BDF not assignable to
1177           guests.  This will at least unbind the device from pciback.  If the
1178           -r option is specified, it will also attempt to re-bind the device
1179           to its original driver, making it usable by Domain 0 again.  If the
1180           device is not bound to pciback, it will return success.
1181
1182       pci-attach domain-id BDF
1183           Hot-plug a new pass-through pci device to the specified domain.
1184           BDF is the PCI Bus/Device/Function of the physical device to pass-
1185           through.
1186
1187       pci-detach [OPTIONS] domain-id BDF
1188           Hot-unplug a previously assigned pci device from a domain. BDF is
1189           the PCI Bus/Device/Function of the physical device to be removed
1190           from the guest domain.
1191
1192           OPTIONS
1193
1194           -f  If this parameter is specified, xl is going to forcefully
1195               remove the device even without guest domain's collaboration.
1196
1197       pci-list domain-id
1198           List pass-through pci devices for a domain.
1199

USB PASS-THROUGH

1201       usbctrl-attach domain-id usbctrl-device
1202           Create a new USB controller in the domain specified by domain-id,
1203           usbctrl-device describes the device to attach, using form
1204           "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1205           the usbctrl description in the domain config file.  See xl.cfg(5)
1206           for more information.
1207
1208       usbctrl-detach domain-id devid
1209           Destroy a USB controller from the specified domain.  devid is devid
1210           of the USB controller.
1211
1212       usbdev-attach domain-id usbdev-device
1213           Hot-plug a new pass-through USB device to the domain specified by
1214           domain-id, usbdev-device describes the device to attach, using form
1215           "KEY=VALUE KEY=VALUE ..." where KEY=VALUE has the same meaning as
1216           the usbdev description in the domain config file.  See xl.cfg(5)
1217           for more information.
1218
1219       usbdev-detach domain-id controller=devid port=number
1220           Hot-unplug a previously assigned USB device from a domain.
1221           controller=devid and port=number is USB controller:port in the
1222           guest domain the USB device is attached to.
1223
1224       usb-list domain-id
1225           List pass-through usb devices for a domain.
1226

DEVICE-MODEL CONTROL

1228       qemu-monitor-command domain-id command
1229           Issue a monitor command to the device model of the domain specified
1230           by domain-id. command can be any valid command qemu understands.
1231           This can be e.g. used to add non-standard devices or devices with
1232           non-standard parameters to a domain. The output of the command is
1233           printed to stdout.
1234
1235           Warning: This qemu monitor access is provided for convenience when
1236           debugging, troubleshooting, and experimenting.  Its use is not
1237           supported by the Xen Project.
1238
1239           Specifically, not all information displayed by the qemu monitor
1240           will necessarily be accurate or complete, because in a Xen system
1241           qemu does not have a complete view of the guest.
1242
1243           Furthermore, modifying the guest's setup via the qemu monitor may
1244           conflict with the Xen toolstack's assumptions.  Resulting problems
1245           may include, but are not limited to: guest crashes; toolstack error
1246           messages; inability to migrate the guest; and security
1247           vulnerabilities which are not covered by the Xen Project security
1248           response policy.
1249
1250           EXAMPLE
1251
1252           Obtain information of USB devices connected as such via the device
1253           model (only!) to a domain:
1254
1255            xl qemu-monitor-command vm1 'info usb'
1256             Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
1257

TRANSCENDENT MEMORY (TMEM)

1259       tmem-list [OPTIONS] domain-id
1260           List tmem pools.
1261
1262           OPTIONS
1263
1264           -l  If this parameter is specified, also list tmem stats.
1265
1266       tmem-freeze domain-id
1267           Freeze tmem pools.
1268
1269       tmem-thaw domain-id
1270           Thaw tmem pools.
1271
1272       tmem-set domain-id [OPTIONS]
1273           Change tmem settings.
1274
1275           OPTIONS
1276
1277           -w WEIGHT
1278               Weight (int)
1279
1280           -p COMPRESS
1281               Compress (int)
1282
1283       tmem-shared-auth domain-id [OPTIONS]
1284           De/authenticate shared tmem pool.
1285
1286           OPTIONS
1287
1288           -u UUID
1289               Specify uuid (abcdef01-2345-6789-1234-567890abcdef)
1290
1291           -a AUTH
1292               0=auth,1=deauth
1293
1294       tmem-freeable
1295           Get information about how much freeable memory (MB) is in-use by
1296           tmem.
1297

FLASK

1299       FLASK is a security framework that defines a mandatory access control
1300       policy providing fine-grained controls over Xen domains, allowing the
1301       policy writer to define what interactions between domains, devices, and
1302       the hypervisor are permitted. Some example of what you can do using
1303       XSM/FLASK:
1304        - Prevent two domains from communicating via event channels or grants
1305        - Control which domains can use device passthrough (and which devices)
1306        - Restrict or audit operations performed by privileged domains
1307        - Prevent a privileged domain from arbitrarily mapping pages from
1308       other
1309          domains.
1310
1311       You can find more details on how to use FLASK and an example security
1312       policy here: <http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
1313
1314       getenforce
1315           Determine if the FLASK security module is loaded and enforcing its
1316           policy.
1317
1318       setenforce 1|0|Enforcing|Permissive
1319           Enable or disable enforcing of the FLASK access controls. The
1320           default is permissive, but this can be changed to enforcing by
1321           specifying "flask=enforcing" or "flask=late" on the hypervisor's
1322           command line.
1323
1324       loadpolicy policy-file
1325           Load FLASK policy from the given policy file. The initial policy is
1326           provided to the hypervisor as a multiboot module; this command
1327           allows runtime updates to the policy. Loading new security policy
1328           will reset runtime changes to device labels.
1329

PLATFORM SHARED RESOURCE MONITORING/CONTROL

1331       Intel Haswell and later server platforms offer shared resource
1332       monitoring and control technologies. The availability of these
1333       technologies and the hardware capabilities can be shown with psr-
1334       hwinfo.
1335
1336       See <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> for more
1337       information.
1338
1339       psr-hwinfo [OPTIONS]
1340           Show Platform Shared Resource (PSR) hardware information.
1341
1342           OPTIONS
1343
1344           -m, --cmt
1345               Show Cache Monitoring Technology (CMT) hardware information.
1346
1347           -a, --cat
1348               Show Cache Allocation Technology (CAT) hardware information.
1349
1350   CACHE MONITORING TECHNOLOGY
1351       Intel Haswell and later server platforms offer monitoring capability in
1352       each logical processor to measure specific platform shared resource
1353       metric, for example, L3 cache occupancy. In the Xen implementation, the
1354       monitoring granularity is domain level. To monitor a specific domain,
1355       just attach the domain id with the monitoring service. When the domain
1356       doesn't need to be monitored any more, detach the domain id from the
1357       monitoring service.
1358
1359       Intel Broadwell and later server platforms also offer total/local
1360       memory bandwidth monitoring. Xen supports per-domain monitoring for
1361       these two additional monitoring types. Both memory bandwidth monitoring
1362       and L3 cache occupancy monitoring share the same set of underlying
1363       monitoring service. Once a domain is attached to the monitoring
1364       service, monitoring data can be shown for any of these monitoring
1365       types.
1366
1367       There is no cache monitoring and memory bandwidth monitoring on L2
1368       cache so far.
1369
1370       psr-cmt-attach domain-id
1371           attach: Attach the platform shared resource monitoring service to a
1372           domain.
1373
1374       psr-cmt-detach domain-id
1375           detach: Detach the platform shared resource monitoring service from
1376           a domain.
1377
1378       psr-cmt-show psr-monitor-type [domain-id]
1379           Show monitoring data for a certain domain or all domains. Current
1380           supported monitor types are:
1381            - "cache-occupancy": showing the L3 cache occupancy(KB).
1382            - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
1383            - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
1384
1385   CACHE ALLOCATION TECHNOLOGY
1386       Intel Broadwell and later server platforms offer capabilities to
1387       configure and make use of the Cache Allocation Technology (CAT)
1388       mechanisms, which enable more cache resources (i.e. L3/L2 cache) to be
1389       made available for high priority applications. In the Xen
1390       implementation, CAT is used to control cache allocation on VM basis. To
1391       enforce cache on a specific domain, just set capacity bitmasks (CBM)
1392       for the domain.
1393
1394       Intel Broadwell and later server platforms also offer Code/Data
1395       Prioritization (CDP) for cache allocations, which support specifying
1396       code or data cache for applications. CDP is used on a per VM basis in
1397       the Xen implementation. To specify code or data CBM for the domain, CDP
1398       feature must be enabled and CBM type options need to be specified when
1399       setting CBM, and the type options (code and data) are mutually
1400       exclusive. There is no CDP support on L2 so far.
1401
1402       psr-cat-set [OPTIONS] domain-id cbm
1403           Set cache capacity bitmasks(CBM) for a domain. For how to specify
1404           cbm please refer to
1405           <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
1406
1407           OPTIONS
1408
1409           -s SOCKET, --socket=SOCKET
1410               Specify the socket to process, otherwise all sockets are
1411               processed.
1412
1413           -l LEVEL, --level=LEVEL
1414               Specify the cache level to process, otherwise the last level
1415               cache (L3) is processed.
1416
1417           -c, --code
1418               Set code CBM when CDP is enabled.
1419
1420           -d, --data
1421               Set data CBM when CDP is enabled.
1422
1423       psr-cat-show [OPTIONS] [domain-id]
1424           Show CAT settings for a certain domain or all domains.
1425
1426           OPTIONS
1427
1428           -l LEVEL, --level=LEVEL
1429               Specify the cache level to process, otherwise the last level
1430               cache (L3) is processed.
1431
1432   Memory Bandwidth Allocation
1433       Intel Skylake and later server platforms offer capabilities to
1434       configure and make use of the Memory Bandwidth Allocation (MBA)
1435       mechanisms, which provides OS/VMMs the ability to slow misbehaving
1436       apps/VMs by using a credit-based throttling mechanism. In the Xen
1437       implementation, MBA is used to control memory bandwidth on VM basis. To
1438       enforce bandwidth on a specific domain, just set throttling value
1439       (THRTL) for the domain.
1440
1441       psr-mba-set [OPTIONS] domain-id thrtl
1442           Set throttling value (THRTL) for a domain. For how to specify thrtl
1443           please refer to
1444           <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
1445
1446           OPTIONS
1447
1448           -s SOCKET, --socket=SOCKET
1449               Specify the socket to process, otherwise all sockets are
1450               processed.
1451
1452       psr-mba-show [domain-id]
1453           Show MBA settings for a certain domain or all domains. For linear
1454           mode, it shows the decimal value. For non-linear mode, it shows
1455           hexadecimal value.
1456

IGNORED FOR COMPATIBILITY WITH XM

1458       xl is mostly command-line compatible with the old xm utility used with
1459       the old Python xend.  For compatibility, the following options are
1460       ignored:
1461
1462       xl migrate --live
1463

TO BE DOCUMENTED

1465       We need better documentation for:
1466
1467       tmem
1468           Transcendent Memory.
1469

SEE ALSO

1471       The following man pages:
1472
1473       xl.cfg(5), xlcpupool.cfg(5), xentop(1), xl-disk-configuration(5)
1474       xl-network-configuration(5)
1475
1476       And the following documents on the xen.org website:
1477
1478       <http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
1479       <http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
1480
1481       For systems that don't automatically bring the CPU online:
1482
1483       <http://wiki.xen.org/wiki/Paravirt_Linux_CPU_Hotplug>
1484

BUGS

1486       Send bugs to xen-devel@lists.xen.org, see
1487       http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
1488
1489
1490
14914.11.1                            2019-05-14                             xl(1)
Impressum