1=head1 NAME 2 3xl - Xen management tool, based on LibXenlight 4 5=head1 SYNOPSIS 6 7B<xl> I<subcommand> [I<args>] 8 9=head1 DESCRIPTION 10 11The B<xl> program is the new tool for managing Xen guest 12domains. The program can be used to create, pause, and shutdown 13domains. It can also be used to list current domains, enable or pin 14VCPUs, and attach or detach virtual block devices. 15 16The basic structure of every B<xl> command is almost always: 17 18=over 2 19 20B<xl> I<subcommand> [I<OPTIONS>] I<domain-id> 21 22=back 23 24Where I<subcommand> is one of the subcommands listed below, I<domain-id> 25is the numeric domain id, or the domain name (which will be internally 26translated to domain id), and I<OPTIONS> are subcommand specific 27options. There are a few exceptions to this rule in the cases where 28the subcommand in question acts on all domains, the entire machine, 29or directly on the Xen hypervisor. Those exceptions will be clear for 30each of those subcommands. 31 32=head1 NOTES 33 34=over 4 35 36=item start the script B</etc/init.d/xencommons> at boot time 37 38Most B<xl> operations rely upon B<xenstored> and B<xenconsoled>: make 39sure you start the script B</etc/init.d/xencommons> at boot time to 40initialize all the daemons needed by B<xl>. 41 42=item setup a B<xenbr0> bridge in dom0 43 44In the most common network configuration, you need to setup a bridge in dom0 45named B<xenbr0> in order to have a working network in the guest domains. 46Please refer to the documentation of your Linux distribution to know how to 47setup the bridge. 48 49=item B<autoballoon> 50 51If you specify the amount of memory dom0 has, passing B<dom0_mem> to 52Xen, it is highly recommended to disable B<autoballoon>. Edit 53B</etc/xen/xl.conf> and set it to 0. 54 55=item run xl as B<root> 56 57Most B<xl> commands require root privileges to run due to the 58communications channels used to talk to the hypervisor. Running as 59non root will return an error. 60 61=back 62 63=head1 GLOBAL OPTIONS 64 65Some global options are always available: 66 67=over 4 68 69=item B<-v> 70 71Verbose. 72 73=item B<-N> 74 75Dry run: do not actually execute the command. 76 77=item B<-f> 78 79Force execution: xl will refuse to run some commands if it detects that xend is 80also running, this option will force the execution of those commands, even 81though it is unsafe. 82 83=item B<-t> 84 85Always use carriage-return-based overwriting for displaying progress 86messages without scrolling the screen. Without -t, this is done only 87if stderr is a tty. 88 89=back 90 91=head1 DOMAIN SUBCOMMANDS 92 93The following subcommands manipulate domains directly. As stated 94previously, most commands take I<domain-id> as the first parameter. 95 96=over 4 97 98=item B<button-press> I<domain-id> I<button> 99 100I<This command is deprecated. Please use C<xl trigger> instead.> 101 102Indicate an ACPI button press to the domain, where I<button> can be 'power' or 103'sleep'. This command is only available for HVM domains. 104 105=item B<create> [I<configfile>] [I<OPTIONS>] 106 107The create subcommand takes a config file as its first argument: see 108L<xl.cfg(5)> for full details of the file format and possible options. 109If I<configfile> is missing B<xl> creates the domain assuming the default 110values for every option. 111 112I<configfile> has to be an absolute path to a file. 113 114Create will return B<as soon> as the domain is started. This B<does 115not> mean the guest OS in the domain has actually booted, or is 116available for input. 117 118If the I<-F> option is specified, create will start the domain and not 119return until its death. 120 121B<OPTIONS> 122 123=over 4 124 125=item B<-q>, B<--quiet> 126 127No console output. 128 129=item B<-f=FILE>, B<--defconfig=FILE> 130 131Use the given configuration file. 132 133=item B<-p> 134 135Leave the domain paused after it is created. 136 137=item B<-F> 138 139Run in foreground until death of the domain. 140 141=item B<-V>, B<--vncviewer> 142 143Attach to domain's VNC server, forking a vncviewer process. 144 145=item B<-A>, B<--vncviewer-autopass> 146 147Pass the VNC password to vncviewer via stdin. 148 149=item B<-c> 150 151Attach console to the domain as soon as it has started. This is 152useful for determining issues with crashing domains and just as a 153general convenience since you often want to watch the 154domain boot. 155 156=item B<key=value> 157 158It is possible to pass I<key=value> pairs on the command line to provide 159options as if they were written in the configuration file; these override 160whatever is in the I<configfile>. 161 162NB: Many config options require characters such as quotes or brackets 163which are interpreted by the shell (and often discarded) before being 164passed to xl, resulting in xl being unable to parse the value 165correctly. A simple work-around is to put all extra options within a 166single set of quotes, separated by semicolons. (See below for an example.) 167 168=back 169 170B<EXAMPLES> 171 172=over 4 173 174=item I<with config file> 175 176 xl create DebianLenny 177 178This creates a domain with the file /etc/xen/DebianLenny, and returns as 179soon as it is run. 180 181=item I<with extra parameters> 182 183 xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]' 184 185This creates a domain with the file hvm.cfg, but additionally pins it to 186cpus 0-3, and passes through two PCI devices. 187 188=back 189 190=item B<config-update> I<domain-id> [I<configfile>] [I<OPTIONS>] 191 192Update the saved configuration for a running domain. This has no 193immediate effect but will be applied when the guest is next 194restarted. This command is useful to ensure that runtime modifications 195made to the guest will be preserved when the guest is restarted. 196 197Since Xen 4.5 xl has improved capabilities to handle dynamic domain 198configuration changes and will preserve any changes made at runtime 199when necessary. Therefore it should not normally be necessary to use 200this command any more. 201 202I<configfile> has to be an absolute path to a file. 203 204B<OPTIONS> 205 206=over 4 207 208=item B<-f=FILE>, B<--defconfig=FILE> 209 210Use the given configuration file. 211 212=item B<key=value> 213 214It is possible to pass I<key=value> pairs on the command line to 215provide options as if they were written in the configuration file; 216these override whatever is in the I<configfile>. Please see the note 217under I<create> on handling special characters when passing 218I<key=value> pairs on the command line. 219 220=back 221 222=item B<console> [I<OPTIONS>] I<domain-id> 223 224Attach to the console of a domain specified by I<domain-id>. If you've set up 225your domains to have a traditional login console this will look much like a 226normal text login screen. 227 228Use the key combination Ctrl+] to detach from the domain console. 229 230B<OPTIONS> 231 232=over 4 233 234=item I<-t [pv|serial]> 235 236Connect to a PV console or connect to an emulated serial console. 237PV consoles are the only consoles available for PV domains while HVM 238domains can have both. If this option is not specified it defaults to 239emulated serial for HVM guests and PV console for PV guests. 240 241=item I<-n NUM> 242 243Connect to console number I<NUM>. Console numbers start from 0. 244 245=back 246 247=item B<destroy> [I<OPTIONS>] I<domain-id> 248 249Immediately terminate the domain specified by I<domain-id>. This doesn't give 250the domain OS any chance to react, and is the equivalent of ripping the power 251cord out on a physical machine. In most cases you will want to use the 252B<shutdown> command instead. 253 254B<OPTIONS> 255 256=over 4 257 258=item I<-f> 259 260Allow domain 0 to be destroyed. Because a domain cannot destroy itself, this 261is only possible when using a disaggregated toolstack, and is most useful when 262using a hardware domain separated from domain 0. 263 264=back 265 266=item B<domid> I<domain-name> 267 268Converts a domain name to a domain id. 269 270=item B<domname> I<domain-id> 271 272Converts a domain id to a domain name. 273 274=item B<rename> I<domain-id> I<new-name> 275 276Change the domain name of a domain specified by I<domain-id> to I<new-name>. 277 278=item B<dump-core> I<domain-id> [I<filename>] 279 280Dumps the virtual machine's memory for the specified domain to the 281I<filename> specified, without pausing the domain. The dump file will 282be written to a distribution specific directory for dump files, for example: 283@XEN_DUMP_DIR@/dump. 284 285=item B<help> [I<--long>] 286 287Displays the short help message (i.e. common commands) by default. 288 289If the I<--long> option is specified, it displays the complete set of B<xl> 290subcommands, grouped by function. 291 292=item B<list> [I<OPTIONS>] [I<domain-id> ...] 293 294Displays information about one or more domains. If no domains are 295specified it displays information about all domains. 296 297 298B<OPTIONS> 299 300=over 4 301 302=item B<-l>, B<--long> 303 304The output for B<xl list> is not the table view shown below, but 305instead presents the data as a JSON data structure. 306 307=item B<-Z>, B<--context> 308 309Also displays the security labels. 310 311=item B<-v>, B<--verbose> 312 313Also displays the domain UUIDs, the shutdown reason and security labels. 314 315=item B<-c>, B<--cpupool> 316 317Also displays the cpupool the domain belongs to. 318 319=item B<-n>, B<--numa> 320 321Also displays the domain NUMA node affinity. 322 323=back 324 325B<EXAMPLE> 326 327An example format for the list is as follows: 328 329 Name ID Mem VCPUs State Time(s) 330 Domain-0 0 750 4 r----- 11794.3 331 win 1 1019 1 r----- 0.3 332 linux 2 2048 2 r----- 5624.2 333 334Name is the name of the domain. ID the numeric domain id. Mem is the 335desired amount of memory to allocate to the domain (although it may 336not be the currently allocated amount). VCPUs is the number of 337virtual CPUs allocated to the domain. State is the run state (see 338below). Time is the total run time of the domain as accounted for by 339Xen. 340 341B<STATES> 342 343The State field lists 6 states for a Xen domain, and which ones the 344current domain is in. 345 346=over 4 347 348=item B<r - running> 349 350The domain is currently running on a CPU. 351 352=item B<b - blocked> 353 354The domain is blocked, and not running or runnable. This can be because the 355domain is waiting on IO (a traditional wait state) or has 356gone to sleep because there was nothing else for it to do. 357 358=item B<p - paused> 359 360The domain has been paused, usually occurring through the administrator 361running B<xl pause>. When in a paused state the domain will still 362consume allocated resources (like memory), but will not be eligible for 363scheduling by the Xen hypervisor. 364 365=item B<s - shutdown> 366 367The guest OS has shut down (SCHEDOP_shutdown has been called) but the 368domain is not dying yet. 369 370=item B<c - crashed> 371 372The domain has crashed, which is always a violent ending. Usually 373this state only occurs if the domain has been configured not to 374restart on a crash. See L<xl.cfg(5)> for more info. 375 376=item B<d - dying> 377 378The domain is in the process of dying, but hasn't completely shut down or 379crashed. 380 381=back 382 383B<NOTES> 384 385=over 4 386 387The Time column is deceptive. Virtual IO (network and block devices) 388used by the domains requires coordination by Domain0, which means that 389Domain0 is actually charged for much of the time that a DomainU is 390doing IO. Use of this time value to determine relative utilizations 391by domains is thus very unreliable, as a high IO workload may show as 392less utilized than a high CPU workload. Consider yourself warned. 393 394=back 395 396=item B<mem-max> I<domain-id> I<mem> 397 398Specify the maximum amount of memory the domain is able to use, appending 't' 399for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' 400for bytes. 401 402The mem-max value may not correspond to the actual memory used in the 403domain, as it may balloon down its memory to give more back to the OS. 404 405The value given just sets the memory amount the domain is allowed to allocate 406in the hypervisor. It can't be set lower than the current reservation, but 407it is allowed to be higher than the configured maximum memory size of the 408domain (B<maxmem> parameter in the domain's configuration). Using B<xl mem-max> 409to set the maximum memory above the initial B<maxmem> value will not allow the 410additional memory to be used via B<xl mem-set>. The initial B<maxmem> value is 411still used as an upper limit for B<xl mem-set>. 412 413The domain will not receive any signal regarding the changed memory limit. 414 415=item B<mem-set> I<domain-id> I<mem> 416 417Set the domain's used memory using the balloon driver; append 't' for 418terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for 419bytes. 420 421Because this operation requires cooperation from the domain operating 422system, there is no guarantee that it will succeed. This command will 423definitely not work unless the domain has the required paravirt 424driver. 425 426B<Warning:> There is no good way to know in advance how small of a 427mem-set will make a domain unstable and cause it to crash. Be very 428careful when using this command on running domains. 429 430=item B<migrate> [I<OPTIONS>] I<domain-id> I<host> 431 432Migrate a domain to another host machine. By default B<xl> relies on ssh as a 433transport mechanism between the two hosts. 434 435B<OPTIONS> 436 437=over 4 438 439=item B<-s> I<sshcommand> 440 441Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run 442<host> instead of ssh <host> xl migrate-receive [-d -e]. 443 444=item B<-e> 445 446On the new <host>, do not wait in the background for the death of the 447domain. See the corresponding option of the I<create> subcommand. 448 449=item B<-C> I<config> 450 451Send the specified <config> file instead of the file used on creation of the 452domain. 453 454=item B<--debug> 455 456Display huge (!) amount of debug information during the migration process. 457 458=item B<-p> 459 460Leave the domain on the receive side paused after migration. 461 462=back 463 464=item B<remus> [I<OPTIONS>] I<domain-id> I<host> 465 466Enable Remus HA or COLO HA for domain. By default B<xl> relies on ssh as a 467transport mechanism between the two hosts. 468 469B<NOTES> 470 471=over 4 472 473Remus support in xl is still in experimental (proof-of-concept) phase. 474Disk replication support is limited to DRBD disks. 475 476COLO support in xl is still in experimental (proof-of-concept) 477phase. All options are subject to change in the future. 478 479=back 480 481COLO disk configuration looks like: 482 483 disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...'] 484 485The supported options are: 486 487=over 4 488 489=item B<colo-host> : Secondary host's ip address. 490 491=item B<colo-port> : Secondary host's port, we will run a nbd server on the 492secondary host, and the nbd server will listen on this port. 493 494=item B<colo-export> : Nbd server's disk export name of the secondary host. 495 496=item B<active-disk> : Secondary's guest write will be buffered to this disk, 497and it's used by the secondary. 498 499=item B<hidden-disk> : Primary's modified contents will be buffered in this 500disk, and it's used by the secondary. 501 502=back 503 504COLO network configuration looks like: 505 506 vif = [ '...,forwarddev=xxx,...'] 507 508The supported options are: 509 510=over 4 511 512=item B<forwarddev> : Forward devices for the primary and the secondary, they 513are directly connected. 514 515 516=back 517 518B<OPTIONS> 519 520=over 4 521 522=item B<-i> I<MS> 523 524Checkpoint domain memory every MS milliseconds (default 200ms). 525 526=item B<-u> 527 528Disable memory checkpoint compression. 529 530=item B<-s> I<sshcommand> 531 532Use <sshcommand> instead of ssh. String will be passed to sh. 533If empty, run <host> instead of ssh <host> xl migrate-receive -r [-e]. 534 535=item B<-e> 536 537On the new <host>, do not wait in the background for the death of the domain. 538See the corresponding option of the I<create> subcommand. 539 540=item B<-N> I<netbufscript> 541 542Use <netbufscript> to setup network buffering instead of the 543default script (/etc/xen/scripts/remus-netbuf-setup). 544 545=item B<-F> 546 547Run Remus in unsafe mode. Use this option with caution as failover may 548not work as intended. 549 550=item B<-b> 551 552Replicate memory checkpoints to /dev/null (blackhole). 553Generally useful for debugging. Requires enabling unsafe mode. 554 555=item B<-n> 556 557Disable network output buffering. Requires enabling unsafe mode. 558 559=item B<-d> 560 561Disable disk replication. Requires enabling unsafe mode. 562 563=item B<-c> 564 565Enable COLO HA. This conflicts with B<-i> and B<-b>, and memory 566checkpoint compression must be disabled. 567 568=item B<-p> 569 570Use userspace COLO Proxy. This option must be used in conjunction 571with B<-c>. 572 573=back 574 575=item B<pause> I<domain-id> 576 577Pause a domain. When in a paused state the domain will still consume 578allocated resources (such as memory), but will not be eligible for 579scheduling by the Xen hypervisor. 580 581=item B<reboot> [I<OPTIONS>] I<domain-id> 582 583Reboot a domain. This acts just as if the domain had the B<reboot> 584command run from the console. The command returns as soon as it has 585executed the reboot action, which may be significantly earlier than when the 586domain actually reboots. 587 588For HVM domains this requires PV drivers to be installed in your guest 589OS. If PV drivers are not present but you have configured the guest OS 590to behave appropriately you may be able to use the I<-F> option to 591trigger a reset button press. 592 593The behavior of what happens to a domain when it reboots is set by the 594B<on_reboot> parameter of the domain configuration file when the 595domain was created. 596 597B<OPTIONS> 598 599=over 4 600 601=item B<-F> 602 603If the guest does not support PV reboot control then fallback to 604sending an ACPI power event (equivalent to the I<reset> option to 605I<trigger>). 606 607You should ensure that the guest is configured to behave as expected 608in response to this event. 609 610=back 611 612=item B<restore> [I<OPTIONS>] [I<configfile>] I<checkpointfile> 613 614Build a domain from an B<xl save> state file. See B<save> for more info. 615 616B<OPTIONS> 617 618=over 4 619 620=item B<-p> 621 622Do not unpause the domain after restoring it. 623 624=item B<-e> 625 626Do not wait in the background for the death of the domain on the new host. 627See the corresponding option of the I<create> subcommand. 628 629=item B<-d> 630 631Enable debug messages. 632 633=item B<-V>, B<--vncviewer> 634 635Attach to the domain's VNC server, forking a vncviewer process. 636 637=item B<-A>, B<--vncviewer-autopass> 638 639Pass the VNC password to vncviewer via stdin. 640 641 642 643=back 644 645=item B<save> [I<OPTIONS>] I<domain-id> I<checkpointfile> [I<configfile>] 646 647Saves a running domain to a state file so that it can be restored 648later. Once saved, the domain will no longer be running on the 649system, unless the -c or -p options are used. 650B<xl restore> restores from this checkpoint file. 651Passing a config file argument allows the user to manually select the VM config 652file used to create the domain. 653 654=over 4 655 656=item B<-c> 657 658Leave the domain running after creating the snapshot. 659 660=item B<-p> 661 662Leave the domain paused after creating the snapshot. 663 664=back 665 666=item B<sharing> [I<domain-id>] 667 668Display the number of shared pages for a specified domain. If no domain is 669specified it displays information about all domains. 670 671=item B<shutdown> [I<OPTIONS>] I<-a|domain-id> 672 673Gracefully shuts down a domain. This coordinates with the domain OS 674to perform graceful shutdown, so there is no guarantee that it will 675succeed, and may take a variable length of time depending on what 676services must be shut down in the domain. 677 678For HVM domains this requires PV drivers to be installed in your guest 679OS. If PV drivers are not present but you have configured the guest OS 680to behave appropriately you may be able to use the I<-F> option to 681trigger a power button press. 682 683The command returns immediately after signaling the domain unless the 684B<-w> flag is used. 685 686The behavior of what happens to a domain when it reboots is set by the 687B<on_shutdown> parameter of the domain configuration file when the 688domain was created. 689 690B<OPTIONS> 691 692=over 4 693 694=item B<-a>, B<--all> 695 696Shutdown all guest domains. Often used when doing a complete shutdown 697of a Xen system. 698 699=item B<-w>, B<--wait> 700 701Wait for the domain to complete shutdown before returning. 702 703=item B<-F> 704 705If the guest does not support PV shutdown control then fallback to 706sending an ACPI power event (equivalent to the I<power> option to 707I<trigger>). 708 709You should ensure that the guest is configured to behave as expected 710in response to this event. 711 712=back 713 714=item B<sysrq> I<domain-id> I<letter> 715 716Send a <Magic System Request> to the domain, each type of request is 717represented by a different letter. 718It can be used to send SysRq requests to Linux guests, see sysrq.txt in 719your Linux Kernel sources for more information. 720It requires PV drivers to be installed in your guest OS. 721 722=item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep|s3resume> [I<VCPU>] 723 724Send a trigger to a domain, where the trigger can be: nmi, reset, init, power 725or sleep. Optionally a specific vcpu number can be passed as an argument. 726This command is only available for HVM domains. 727 728=item B<unpause> I<domain-id> 729 730Moves a domain out of the paused state. This will allow a previously 731paused domain to now be eligible for scheduling by the Xen hypervisor. 732 733=item B<vcpu-set> I<domain-id> I<vcpu-count> 734 735Enables the I<vcpu-count> virtual CPUs for the domain in question. 736Like mem-set, this command can only allocate up to the maximum virtual 737CPU count configured at boot for the domain. 738 739If the I<vcpu-count> is smaller than the current number of active 740VCPUs, the highest number VCPUs will be hotplug removed. This may be 741important for pinning purposes. 742 743Attempting to set the VCPUs to a number larger than the initially 744configured VCPU count is an error. Trying to set VCPUs to < 1 will be 745quietly ignored. 746 747Some guests may need to actually bring the newly added CPU online 748after B<vcpu-set>, go to B<SEE ALSO> section for information. 749 750=item B<vcpu-list> [I<domain-id>] 751 752Lists VCPU information for a specific domain. If no domain is 753specified, VCPU information for all domains will be provided. 754 755=item B<vcpu-pin> [I<-f|--force>] I<domain-id> I<vcpu> I<cpus hard> I<cpus soft> 756 757Set hard and soft affinity for a I<vcpu> of <domain-id>. Normally VCPUs 758can float between available CPUs whenever Xen deems a different run state 759is appropriate. 760 761Hard affinity can be used to restrict this, by ensuring certain VCPUs 762can only run on certain physical CPUs. Soft affinity specifies a I<preferred> 763set of CPUs. Soft affinity needs special support in the scheduler, which is 764only provided in credit1. 765 766The keyword B<all> can be used to apply the hard and soft affinity masks to 767all the VCPUs in the domain. The symbol '-' can be used to leave either 768hard or soft affinity alone. 769 770For example: 771 772 xl vcpu-pin 0 3 - 6-9 773 774will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9, 775leaving its hard affinity untouched. On the other hand: 776 777 xl vcpu-pin 0 3 3,4 6-9 778 779will set both hard and soft affinity, the former to pCPUs 3 and 4, the 780latter to pCPUs 6,7,8, and 9. 781 782Specifying I<-f> or I<--force> will remove a temporary pinning done by the 783operating system (normally this should be done by the operating system). 784In case a temporary pinning is active for a vcpu the affinity of this vcpu 785can't be changed without this option. 786 787=item B<vm-list> 788 789Prints information about guests. This list excludes information about 790service or auxiliary domains such as dom0 and stubdoms. 791 792B<EXAMPLE> 793 794An example format for the list is as follows: 795 796 UUID ID name 797 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win 798 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux 799 800=item B<vncviewer> [I<OPTIONS>] I<domain-id> 801 802Attach to the domain's VNC server, forking a vncviewer process. 803 804B<OPTIONS> 805 806=over 4 807 808=item I<--autopass> 809 810Pass the VNC password to vncviewer via stdin. 811 812=back 813 814=back 815 816=head1 XEN HOST SUBCOMMANDS 817 818=over 4 819 820=item B<debug-keys> I<keys> 821 822Send debug I<keys> to Xen. It is the same as pressing the Xen 823"conswitch" (Ctrl-A by default) three times and then pressing "keys". 824 825=item B<set-parameters> I<params> 826 827Set hypervisor parameters as specified in I<params>. This allows for some 828boot parameters of the hypervisor to be modified in the running systems. 829 830=item B<dmesg> [I<OPTIONS>] 831 832Reads the Xen message buffer, similar to dmesg on a Linux system. The 833buffer contains informational, warning, and error messages created 834during Xen's boot process. If you are having problems with Xen, this 835is one of the first places to look as part of problem determination. 836 837B<OPTIONS> 838 839=over 4 840 841=item B<-c>, B<--clear> 842 843Clears Xen's message buffer. 844 845=back 846 847=item B<info> [I<OPTIONS>] 848 849Print information about the Xen host in I<name : value> format. When 850reporting a Xen bug, please provide this information as part of the 851bug report. See I<http://wiki.xen.org/xenwiki/ReportingBugs> on how to 852report Xen bugs. 853 854Sample output looks as follows: 855 856 host : scarlett 857 release : 3.1.0-rc4+ 858 version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011 859 machine : x86_64 860 nr_cpus : 4 861 nr_nodes : 1 862 cores_per_socket : 4 863 threads_per_core : 1 864 cpu_mhz : 2266 865 hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000 866 virt_caps : hvm hvm_directio 867 total_memory : 6141 868 free_memory : 4274 869 free_cpus : 0 870 outstanding_claims : 0 871 xen_major : 4 872 xen_minor : 2 873 xen_extra : -unstable 874 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 875 xen_scheduler : credit 876 xen_pagesize : 4096 877 platform_params : virt_start=0xffff800000000000 878 xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241 879 xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1 880 cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8) 881 cc_compile_by : sstabellini 882 cc_compile_domain : uk.xensource.com 883 cc_compile_date : Tue Nov 8 12:03:05 UTC 2011 884 xend_config_format : 4 885 886 887B<FIELDS> 888 889Not all fields will be explained here, but some of the less obvious 890ones deserve explanation: 891 892=over 4 893 894=item B<hw_caps> 895 896A vector showing what hardware capabilities are supported by your 897processor. This is equivalent to, though more cryptic, the flags 898field in /proc/cpuinfo on a normal Linux machine: they both derive from 899the feature bits returned by the cpuid command on x86 platforms. 900 901=item B<free_memory> 902 903Available memory (in MB) not allocated to Xen, or any other domains, or 904claimed for domains. 905 906=item B<outstanding_claims> 907 908When a claim call is done (see L<xl.conf>) a reservation for a specific 909amount of pages is set and also a global value is incremented. This 910global value (outstanding_claims) is then reduced as the domain's memory 911is populated and eventually reaches zero. Most of the time the value will 912be zero, but if you are launching multiple guests, and B<claim_mode> is 913enabled, this value can increase/decrease. Note that the value also 914affects the B<free_memory> - as it will reflect the free memory 915in the hypervisor minus the outstanding pages claimed for guests. 916See xl I<info> B<claims> parameter for detailed listing. 917 918=item B<xen_caps> 919 920The Xen version and architecture. Architecture values can be one of: 921x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64. 922 923=item B<xen_changeset> 924 925The Xen mercurial changeset id. Very useful for determining exactly 926what version of code your Xen system was built from. 927 928=back 929 930B<OPTIONS> 931 932=over 4 933 934=item B<-n>, B<--numa> 935 936List host NUMA topology information 937 938=back 939 940=item B<top> 941 942Executes the B<xentop(1)> command, which provides real time monitoring of 943domains. Xentop has a curses interface, and is reasonably self explanatory. 944 945=item B<uptime> 946 947Prints the current uptime of the domains running. 948 949=item B<claims> 950 951Prints information about outstanding claims by the guests. This provides 952the outstanding claims and currently populated memory count for the guests. 953These values added up reflect the global outstanding claim value, which 954is provided via the I<info> argument, B<outstanding_claims> value. 955The B<Mem> column has the cumulative value of outstanding claims and 956the total amount of memory that has been right now allocated to the guest. 957 958B<EXAMPLE> 959 960An example format for the list is as follows: 961 962 Name ID Mem VCPUs State Time(s) Claimed 963 Domain-0 0 2047 4 r----- 19.7 0 964 OL5 2 2048 1 --p--- 0.0 847 965 OL6 3 1024 4 r----- 5.9 0 966 Windows_XP 4 2047 1 --p--- 0.0 1989 967 968In which it can be seen that the OL5 guest still has 847MB of claimed 969memory (out of the total 2048MB where 1191MB has been allocated to 970the guest). 971 972=back 973 974=head1 SCHEDULER SUBCOMMANDS 975 976Xen ships with a number of domain schedulers, which can be set at boot 977time with the B<sched=> parameter on the Xen command line. By 978default B<credit> is used for scheduling. 979 980=over 4 981 982=item B<sched-credit> [I<OPTIONS>] 983 984Set or get credit (aka credit1) scheduler parameters. The credit scheduler is 985a proportional fair share CPU scheduler built from the ground up to be 986work conserving on SMP hosts. 987 988Each domain (including Domain0) is assigned a weight and a cap. 989 990B<OPTIONS> 991 992=over 4 993 994=item B<-d DOMAIN>, B<--domain=DOMAIN> 995 996Specify domain for which scheduler parameters are to be modified or retrieved. 997Mandatory for modifying scheduler parameters. 998 999=item B<-w WEIGHT>, B<--weight=WEIGHT> 1000 1001A domain with a weight of 512 will get twice as much CPU as a domain 1002with a weight of 256 on a contended host. Legal weights range from 1 1003to 65535 and the default is 256. 1004 1005=item B<-c CAP>, B<--cap=CAP> 1006 1007The cap optionally fixes the maximum amount of CPU a domain will be 1008able to consume, even if the host system has idle CPU cycles. The cap 1009is expressed in percentage of one physical CPU: 100 is 1 physical CPU, 101050 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is 1011no upper cap. 1012 1013NB: Many systems have features that will scale down the computing 1014power of a cpu that is not 100% utilized. This can be in the 1015operating system, but can also sometimes be below the operating system 1016in the BIOS. If you set a cap such that individual cores are running 1017at less than 100%, this may have an impact on the performance of your 1018workload over and above the impact of the cap. For example, if your 1019processor runs at 2GHz, and you cap a vm at 50%, the power management 1020system may also reduce the clock speed to 1GHz; the effect will be 1021that your VM gets 25% of the available power (50% of 1GHz) rather than 102250% (50% of 2GHz). If you are not getting the performance you expect, 1023look at performance and cpufreq options in your operating system and 1024your BIOS. 1025 1026=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL> 1027 1028Restrict output to domains in the specified cpupool. 1029 1030=item B<-s>, B<--schedparam> 1031 1032Specify to list or set pool-wide scheduler parameters. 1033 1034=item B<-t TSLICE>, B<--tslice_ms=TSLICE> 1035 1036Timeslice tells the scheduler how long to allow VMs to run before 1037pre-empting. The default is 30ms. Valid ranges are 1ms to 1000ms. 1038The length of the timeslice (in ms) must be higher than the length of 1039the ratelimit (see below). 1040 1041=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT> 1042 1043Ratelimit attempts to limit the number of schedules per second. It 1044sets a minimum amount of time (in microseconds) a VM must run before 1045we will allow a higher-priority VM to pre-empt it. The default value 1046is 1000 microseconds (1ms). Valid range is 100 to 500000 (500ms). 1047The ratelimit length must be lower than the timeslice length. 1048 1049=back 1050 1051B<COMBINATION> 1052 1053The following is the effect of combining the above options: 1054 1055=over 4 1056 1057=item B<E<lt>nothingE<gt>> : List all domain params and sched params from all pools 1058 1059=item B<-d [domid]> : List domain params for domain [domid] 1060 1061=item B<-d [domid] [params]> : Set domain params for domain [domid] 1062 1063=item B<-p [pool]> : list all domains and sched params for [pool] 1064 1065=item B<-s> : List sched params for poolid 0 1066 1067=item B<-s [params]> : Set sched params for poolid 0 1068 1069=item B<-p [pool] -s> : List sched params for [pool] 1070 1071=item B<-p [pool] -s [params]> : Set sched params for [pool] 1072 1073=item B<-p [pool] -d>... : Illegal 1074 1075=back 1076 1077=item B<sched-credit2> [I<OPTIONS>] 1078 1079Set or get credit2 scheduler parameters. The credit2 scheduler is a 1080proportional fair share CPU scheduler built from the ground up to be 1081work conserving on SMP hosts. 1082 1083Each domain (including Domain0) is assigned a weight. 1084 1085B<OPTIONS> 1086 1087=over 4 1088 1089=item B<-d DOMAIN>, B<--domain=DOMAIN> 1090 1091Specify domain for which scheduler parameters are to be modified or retrieved. 1092Mandatory for modifying scheduler parameters. 1093 1094=item B<-w WEIGHT>, B<--weight=WEIGHT> 1095 1096A domain with a weight of 512 will get twice as much CPU as a domain 1097with a weight of 256 on a contended host. Legal weights range from 1 1098to 65535 and the default is 256. 1099 1100=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL> 1101 1102Restrict output to domains in the specified cpupool. 1103 1104=item B<-s>, B<--schedparam> 1105 1106Specify to list or set pool-wide scheduler parameters. 1107 1108=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT> 1109 1110Attempts to limit the rate of context switching. It is basically the same 1111as B<--ratelimit_us> in B<sched-credit> 1112 1113=back 1114 1115=item B<sched-rtds> [I<OPTIONS>] 1116 1117Set or get rtds (Real Time Deferrable Server) scheduler parameters. 1118This rt scheduler applies Preemptive Global Earliest Deadline First 1119real-time scheduling algorithm to schedule VCPUs in the system. 1120Each VCPU has a dedicated period, budget and extratime. 1121While scheduled, a VCPU burns its budget. 1122A VCPU has its budget replenished at the beginning of each period; 1123Unused budget is discarded at the end of each period. 1124A VCPU with extratime set gets extra time from the unreserved system resource. 1125 1126B<OPTIONS> 1127 1128=over 4 1129 1130=item B<-d DOMAIN>, B<--domain=DOMAIN> 1131 1132Specify domain for which scheduler parameters are to be modified or retrieved. 1133Mandatory for modifying scheduler parameters. 1134 1135=item B<-v VCPUID/all>, B<--vcpuid=VCPUID/all> 1136 1137Specify vcpu for which scheduler parameters are to be modified or retrieved. 1138 1139=item B<-p PERIOD>, B<--period=PERIOD> 1140 1141Period of time, in microseconds, over which to replenish the budget. 1142 1143=item B<-b BUDGET>, B<--budget=BUDGET> 1144 1145Amount of time, in microseconds, that the VCPU will be allowed 1146to run every period. 1147 1148=item B<-e Extratime>, B<--extratime=Extratime> 1149 1150Binary flag to decide if the VCPU will be allowed to get extra time from 1151the unreserved system resource. 1152 1153=item B<-c CPUPOOL>, B<--cpupool=CPUPOOL> 1154 1155Restrict output to domains in the specified cpupool. 1156 1157=back 1158 1159B<EXAMPLE> 1160 1161=over 4 1162 11631) Use B<-v all> to see the budget and period of all the VCPUs of 1164all the domains: 1165 1166 xl sched-rtds -v all 1167 Cpupool Pool-0: sched=RTDS 1168 Name ID VCPU Period Budget Extratime 1169 Domain-0 0 0 10000 4000 yes 1170 vm1 2 0 300 150 yes 1171 vm1 2 1 400 200 yes 1172 vm1 2 2 10000 4000 yes 1173 vm1 2 3 1000 500 yes 1174 vm2 4 0 10000 4000 yes 1175 vm2 4 1 10000 4000 yes 1176 1177Without any arguments, it will output the default scheduling 1178parameters for each domain: 1179 1180 xl sched-rtds 1181 Cpupool Pool-0: sched=RTDS 1182 Name ID Period Budget Extratime 1183 Domain-0 0 10000 4000 yes 1184 vm1 2 10000 4000 yes 1185 vm2 4 10000 4000 yes 1186 1187 11882) Use, for instance, B<-d vm1, -v all> to see the budget and 1189period of all VCPUs of a specific domain (B<vm1>): 1190 1191 xl sched-rtds -d vm1 -v all 1192 Name ID VCPU Period Budget Extratime 1193 vm1 2 0 300 150 yes 1194 vm1 2 1 400 200 yes 1195 vm1 2 2 10000 4000 yes 1196 vm1 2 3 1000 500 yes 1197 1198To see the parameters of a subset of the VCPUs of a domain, use: 1199 1200 xl sched-rtds -d vm1 -v 0 -v 3 1201 Name ID VCPU Period Budget Extratime 1202 vm1 2 0 300 150 yes 1203 vm1 2 3 1000 500 yes 1204 1205If no B<-v> is specified, the default scheduling parameters for the 1206domain are shown: 1207 1208 xl sched-rtds -d vm1 1209 Name ID Period Budget Extratime 1210 vm1 2 10000 4000 yes 1211 1212 12133) Users can set the budget and period of multiple VCPUs of a 1214specific domain with only one command, 1215e.g., "xl sched-rtds -d vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0". 1216 1217To change the parameters of all the VCPUs of a domain, use B<-v all>, 1218e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1". 1219 1220=back 1221 1222=back 1223 1224=head1 CPUPOOLS COMMANDS 1225 1226Xen can group the physical cpus of a server in cpu-pools. Each physical CPU is 1227assigned at most to one cpu-pool. Domains are each restricted to a single 1228cpu-pool. Scheduling does not cross cpu-pool boundaries, so each cpu-pool has 1229its own scheduler. 1230Physical cpus and domains can be moved from one cpu-pool to another only by an 1231explicit command. 1232Cpu-pools can be specified either by name or by id. 1233 1234=over 4 1235 1236=item B<cpupool-create> [I<OPTIONS>] [I<configfile>] [I<variable=value> ...] 1237 1238Create a cpu pool based an config from a I<configfile> or command-line 1239parameters. Variable settings from the I<configfile> may be altered 1240by specifying new or additional assignments on the command line. 1241 1242See the L<xlcpupool.cfg(5)> manpage for more information. 1243 1244B<OPTIONS> 1245 1246=over 4 1247 1248=item B<-f=FILE>, B<--defconfig=FILE> 1249 1250Use the given configuration file. 1251 1252=back 1253 1254=item B<cpupool-list> [I<OPTIONS>] [I<cpu-pool>] 1255 1256List CPU pools on the host. 1257 1258B<OPTIONS> 1259 1260=over 4 1261 1262=item B<-c>, B<--cpus> 1263 1264If this option is specified, B<xl> prints a list of CPUs used by I<cpu-pool>. 1265 1266=back 1267 1268=item B<cpupool-destroy> I<cpu-pool> 1269 1270Deactivates a cpu pool. 1271This is possible only if no domain is active in the cpu-pool. 1272 1273=item B<cpupool-rename> I<cpu-pool> <newname> 1274 1275Renames a cpu-pool to I<newname>. 1276 1277=item B<cpupool-cpu-add> I<cpu-pool> I<cpus|node:nodes> 1278 1279Adds one or more CPUs or NUMA nodes to I<cpu-pool>. CPUs and NUMA 1280nodes can be specified as single CPU/node IDs or as ranges. 1281 1282For example: 1283 1284 (a) xl cpupool-cpu-add mypool 4 1285 (b) xl cpupool-cpu-add mypool 1,5,10-16,^13 1286 (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8 1287 1288means adding CPU 4 to mypool, in (a); adding CPUs 1,5,10,11,12,14,15 1289and 16, in (b); and adding all the CPUs of NUMA nodes 0, 2 and 3, 1290plus CPU 8, but keeping out CPUs 10,11,12, in (c). 1291 1292All the specified CPUs that can be added to the cpupool will be added 1293to it. If some CPU can't (e.g., because they're already part of another 1294cpupool), an error is reported about each one of them. 1295 1296=item B<cpupool-cpu-remove> I<cpus|node:nodes> 1297 1298Removes one or more CPUs or NUMA nodes from I<cpu-pool>. CPUs and NUMA 1299nodes can be specified as single CPU/node IDs or as ranges, using the 1300exact same syntax as in B<cpupool-cpu-add> above. 1301 1302=item B<cpupool-migrate> I<domain-id> I<cpu-pool> 1303 1304Moves a domain specified by domain-id or domain-name into a cpu-pool. 1305Domain-0 can't be moved to another cpu-pool. 1306 1307=item B<cpupool-numa-split> 1308 1309Splits up the machine into one cpu-pool per numa node. 1310 1311=back 1312 1313=head1 VIRTUAL DEVICE COMMANDS 1314 1315Most virtual devices can be added and removed while guests are 1316running, assuming that the necessary support exists in the guest OS. The 1317effect to the guest OS is much the same as any hotplug event. 1318 1319=head2 BLOCK DEVICES 1320 1321=over 4 1322 1323=item B<block-attach> I<domain-id> I<disc-spec-component(s)> ... 1324 1325Create a new virtual block device and attach it to the specified domain. 1326A disc specification is in the same format used for the B<disk> variable in 1327the domain config file. See L<xl-disk-configuration(5)>. This will trigger a 1328hotplug event for the guest. 1329 1330Note that only PV block devices are supported by block-attach. 1331Requests to attach emulated devices (eg, vdev=hdc) will result in only 1332the PV view being available to the guest. 1333 1334=item B<block-detach> I<domain-id> I<devid> [I<OPTIONS>] 1335 1336Detach a domain's virtual block device. I<devid> may be the symbolic 1337name or the numeric device id given to the device by domain 0. You 1338will need to run B<xl block-list> to determine that number. 1339 1340Detaching the device requires the cooperation of the domain. If the 1341domain fails to release the device (perhaps because the domain is hung 1342or is still using the device), the detach will fail. 1343 1344B<OPTIONS> 1345 1346=over 4 1347 1348=item B<--force> 1349 1350If this parameter is specified the device will be forcefully detached, which 1351may cause IO errors in the domain. 1352 1353=back 1354 1355 1356 1357=item B<block-list> I<domain-id> 1358 1359List virtual block devices for a domain. 1360 1361=item B<cd-insert> I<domain-id> I<virtualdevice> I<target> 1362 1363Insert a cdrom into a guest domain's existing virtual cd drive. The 1364virtual drive must already exist but can be empty. How the device should be 1365presented to the guest domain is specified by the I<virtualdevice> parameter; 1366for example "hdc". Parameter I<target> is the target path in the backend domain 1367(usually domain 0) to be exported; can be a block device or a file etc. 1368See B<target> in L<xl-disk-configuration(5)>. 1369 1370Only works with HVM domains. 1371 1372 1373=item B<cd-eject> I<domain-id> I<virtualdevice> 1374 1375Eject a cdrom from a guest domain's virtual cd drive, specified by 1376I<virtualdevice>. Only works with HVM domains. 1377 1378=back 1379 1380=head2 NETWORK DEVICES 1381 1382=over 4 1383 1384=item B<network-attach> I<domain-id> I<network-device> 1385 1386Creates a new network device in the domain specified by I<domain-id>. 1387I<network-device> describes the device to attach, using the same format as the 1388B<vif> string in the domain config file. See L<xl.cfg(5)> and 1389L<xl-network-configuration(5)> 1390for more informations. 1391 1392Note that only attaching PV network interfaces is supported. 1393 1394=item B<network-detach> I<domain-id> I<devid|mac> 1395 1396Removes the network device from the domain specified by I<domain-id>. 1397I<devid> is the virtual interface device number within the domain 1398(i.e. the 3 in vif22.3). Alternatively, the I<mac> address can be used to 1399select the virtual interface to detach. 1400 1401=item B<network-list> I<domain-id> 1402 1403List virtual network interfaces for a domain. 1404 1405=back 1406 1407=head2 CHANNEL DEVICES 1408 1409=over 4 1410 1411=item B<channel-list> I<domain-id> 1412 1413List virtual channel interfaces for a domain. 1414 1415=back 1416 1417=head2 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES 1418 1419=over 4 1420 1421=item B<vtpm-attach> I<domain-id> I<vtpm-device> 1422 1423Creates a new vtpm (virtual Trusted Platform Module) device in the domain 1424specified by I<domain-id>. I<vtpm-device> describes the device to attach, 1425using the same format as the B<vtpm> string in the domain config file. 1426See L<xl.cfg(5)> for more information. 1427 1428=item B<vtpm-detach> I<domain-id> I<devid|uuid> 1429 1430Removes the vtpm device from the domain specified by I<domain-id>. 1431I<devid> is the numeric device id given to the virtual Trusted 1432Platform Module device. You will need to run B<xl vtpm-list> to determine that 1433number. Alternatively, the I<uuid> of the vtpm can be used to 1434select the virtual device to detach. 1435 1436=item B<vtpm-list> I<domain-id> 1437 1438List virtual Trusted Platform Modules for a domain. 1439 1440=back 1441 1442=head2 VDISPL DEVICES 1443 1444=over 4 1445 1446=item B<vdispl-attach> I<domain-id> I<vdispl-device> 1447 1448Creates a new vdispl device in the domain specified by I<domain-id>. 1449I<vdispl-device> describes the device to attach, using the same format as the 1450B<vdispl> string in the domain config file. See L<xl.cfg> for 1451more information. 1452 1453B<NOTES> 1454 1455=over 4 1456 1457As in I<vdispl-device> string semicolon is used then put quotes or escaping 1458when using from the shell. 1459 1460B<EXAMPLE> 1461 1462=over 4 1463 1464xl vdispl-attach DomU connectors='id0:1920x1080;id1:800x600;id2:640x480' 1465 1466or 1467 1468xl vdispl-attach DomU connectors=id0:1920x1080\;id1:800x600\;id2:640x480 1469 1470=back 1471 1472=back 1473 1474=item B<vdispl-detach> I<domain-id> I<dev-id> 1475 1476Removes the vdispl device specified by I<dev-id> from the domain specified by I<domain-id>. 1477 1478=item B<vdispl-list> I<domain-id> 1479 1480List virtual displays for a domain. 1481 1482=back 1483 1484=head1 PCI PASS-THROUGH 1485 1486=over 4 1487 1488=item B<pci-assignable-list> 1489 1490List all the assignable PCI devices. 1491These are devices in the system which are configured to be 1492available for passthrough and are bound to a suitable PCI 1493backend driver in domain 0 rather than a real driver. 1494 1495=item B<pci-assignable-add> I<BDF> 1496 1497Make the device at PCI Bus/Device/Function BDF assignable to guests. 1498This will bind the device to the pciback driver. If it is already 1499bound to a driver, it will first be unbound, and the original driver 1500stored so that it can be re-bound to the same driver later if desired. 1501If the device is already bound, it will return success. 1502 1503CAUTION: This will make the device unusable by Domain 0 until it is 1504returned with pci-assignable-remove. Care should therefore be taken 1505not to do this on a device critical to domain 0's operation, such as 1506storage controllers, network interfaces, or GPUs that are currently 1507being used. 1508 1509=item B<pci-assignable-remove> [I<-r>] I<BDF> 1510 1511Make the device at PCI Bus/Device/Function BDF not assignable to guests. This 1512will at least unbind the device from pciback. If the -r option is specified, 1513it will also attempt to re-bind the device to its original driver, making it 1514usable by Domain 0 again. If the device is not bound to pciback, it will 1515return success. 1516 1517=item B<pci-attach> I<domain-id> I<BDF> 1518 1519Hot-plug a new pass-through pci device to the specified domain. 1520B<BDF> is the PCI Bus/Device/Function of the physical device to pass-through. 1521 1522=item B<pci-detach> [I<OPTIONS>] I<domain-id> I<BDF> 1523 1524Hot-unplug a previously assigned pci device from a domain. B<BDF> is the PCI 1525Bus/Device/Function of the physical device to be removed from the guest domain. 1526 1527B<OPTIONS> 1528 1529=over 4 1530 1531=item B<-f> 1532 1533If this parameter is specified, B<xl> is going to forcefully remove the device 1534even without guest domain's collaboration. 1535 1536=back 1537 1538=item B<pci-list> I<domain-id> 1539 1540List pass-through pci devices for a domain. 1541 1542=back 1543 1544=head1 USB PASS-THROUGH 1545 1546=over 4 1547 1548=item B<usbctrl-attach> I<domain-id> I<usbctrl-device> 1549 1550Create a new USB controller in the domain specified by I<domain-id>, 1551I<usbctrl-device> describes the device to attach, using form 1552C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same 1553meaning as the B<usbctrl> description in the domain config file. 1554See L<xl.cfg(5)> for more information. 1555 1556=item B<usbctrl-detach> I<domain-id> I<devid> 1557 1558Destroy a USB controller from the specified domain. 1559B<devid> is devid of the USB controller. 1560 1561=item B<usbdev-attach> I<domain-id> I<usbdev-device> 1562 1563Hot-plug a new pass-through USB device to the domain specified by 1564I<domain-id>, I<usbdev-device> describes the device to attach, using 1565form C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same 1566meaning as the B<usbdev> description in the domain config file. 1567See L<xl.cfg(5)> for more information. 1568 1569=item B<usbdev-detach> I<domain-id> I<controller=devid> I<port=number> 1570 1571Hot-unplug a previously assigned USB device from a domain. 1572B<controller=devid> and B<port=number> is USB controller:port in the guest 1573domain the USB device is attached to. 1574 1575=item B<usb-list> I<domain-id> 1576 1577List pass-through usb devices for a domain. 1578 1579=back 1580 1581=head1 DEVICE-MODEL CONTROL 1582 1583=over 4 1584 1585=item B<qemu-monitor-command> I<domain-id> I<command> 1586 1587Issue a monitor command to the device model of the domain specified by 1588I<domain-id>. I<command> can be any valid command qemu understands. This 1589can be e.g. used to add non-standard devices or devices with non-standard 1590parameters to a domain. The output of the command is printed to stdout. 1591 1592B<Warning:> This qemu monitor access is provided for convenience when 1593debugging, troubleshooting, and experimenting. Its use is not 1594supported by the Xen Project. 1595 1596Specifically, not all information displayed by the qemu monitor will 1597necessarily be accurate or complete, because in a Xen system qemu 1598does not have a complete view of the guest. 1599 1600Furthermore, modifying the guest's setup via the qemu monitor may 1601conflict with the Xen toolstack's assumptions. Resulting problems 1602may include, but are not limited to: guest crashes; toolstack error 1603messages; inability to migrate the guest; and security 1604vulnerabilities which are not covered by the Xen Project security 1605response policy. 1606 1607B<EXAMPLE> 1608 1609Obtain information of USB devices connected as such via the device model 1610(only!) to a domain: 1611 1612 xl qemu-monitor-command vm1 'info usb' 1613 Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage 1614 1615=back 1616 1617=head1 TRANSCENDENT MEMORY (TMEM) 1618 1619=over 4 1620 1621=item B<tmem-list> I<[OPTIONS]> I<domain-id> 1622 1623List tmem pools. 1624 1625B<OPTIONS> 1626 1627=over 4 1628 1629=item B<-l> 1630 1631If this parameter is specified, also list tmem stats. 1632 1633=back 1634 1635=item B<tmem-freeze> I<domain-id> 1636 1637Freeze tmem pools. 1638 1639=item B<tmem-thaw> I<domain-id> 1640 1641Thaw tmem pools. 1642 1643=item B<tmem-set> I<domain-id> [I<OPTIONS>] 1644 1645Change tmem settings. 1646 1647B<OPTIONS> 1648 1649=over 4 1650 1651=item B<-w> I<WEIGHT> 1652 1653Weight (int) 1654 1655=item B<-p> I<COMPRESS> 1656 1657Compress (int) 1658 1659=back 1660 1661=item B<tmem-shared-auth> I<domain-id> [I<OPTIONS>] 1662 1663De/authenticate shared tmem pool. 1664 1665B<OPTIONS> 1666 1667=over 4 1668 1669=item B<-u> I<UUID> 1670 1671Specify uuid (abcdef01-2345-6789-1234-567890abcdef) 1672 1673=item B<-a> I<AUTH> 1674 16750=auth,1=deauth 1676 1677=back 1678 1679=item B<tmem-freeable> 1680 1681Get information about how much freeable memory (MB) is in-use by tmem. 1682 1683=back 1684 1685=head1 FLASK 1686 1687B<FLASK> is a security framework that defines a mandatory access control policy 1688providing fine-grained controls over Xen domains, allowing the policy writer 1689to define what interactions between domains, devices, and the hypervisor are 1690permitted. Some example of what you can do using XSM/FLASK: 1691 - Prevent two domains from communicating via event channels or grants 1692 - Control which domains can use device passthrough (and which devices) 1693 - Restrict or audit operations performed by privileged domains 1694 - Prevent a privileged domain from arbitrarily mapping pages from other 1695 domains. 1696 1697You can find more details on how to use FLASK and an example security 1698policy here: L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt> 1699 1700=over 4 1701 1702=item B<getenforce> 1703 1704Determine if the FLASK security module is loaded and enforcing its policy. 1705 1706=item B<setenforce> I<1|0|Enforcing|Permissive> 1707 1708Enable or disable enforcing of the FLASK access controls. The default is 1709permissive, but this can be changed to enforcing by specifying "flask=enforcing" 1710or "flask=late" on the hypervisor's command line. 1711 1712=item B<loadpolicy> I<policy-file> 1713 1714Load FLASK policy from the given policy file. The initial policy is provided to 1715the hypervisor as a multiboot module; this command allows runtime updates to the 1716policy. Loading new security policy will reset runtime changes to device labels. 1717 1718=back 1719 1720=head1 PLATFORM SHARED RESOURCE MONITORING/CONTROL 1721 1722Intel Haswell and later server platforms offer shared resource monitoring 1723and control technologies. The availability of these technologies and the 1724hardware capabilities can be shown with B<psr-hwinfo>. 1725 1726See L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> for more 1727information. 1728 1729=over 4 1730 1731=item B<psr-hwinfo> [I<OPTIONS>] 1732 1733Show Platform Shared Resource (PSR) hardware information. 1734 1735B<OPTIONS> 1736 1737=over 4 1738 1739=item B<-m>, B<--cmt> 1740 1741Show Cache Monitoring Technology (CMT) hardware information. 1742 1743=item B<-a>, B<--cat> 1744 1745Show Cache Allocation Technology (CAT) hardware information. 1746 1747=back 1748 1749=back 1750 1751=head2 CACHE MONITORING TECHNOLOGY 1752 1753Intel Haswell and later server platforms offer monitoring capability in each 1754logical processor to measure specific platform shared resource metric, for 1755example, L3 cache occupancy. In the Xen implementation, the monitoring 1756granularity is domain level. To monitor a specific domain, just attach the 1757domain id with the monitoring service. When the domain doesn't need to be 1758monitored any more, detach the domain id from the monitoring service. 1759 1760Intel Broadwell and later server platforms also offer total/local memory 1761bandwidth monitoring. Xen supports per-domain monitoring for these two 1762additional monitoring types. Both memory bandwidth monitoring and L3 cache 1763occupancy monitoring share the same set of underlying monitoring service. Once 1764a domain is attached to the monitoring service, monitoring data can be shown 1765for any of these monitoring types. 1766 1767There is no cache monitoring and memory bandwidth monitoring on L2 cache so 1768far. 1769 1770=over 4 1771 1772=item B<psr-cmt-attach> I<domain-id> 1773 1774attach: Attach the platform shared resource monitoring service to a domain. 1775 1776=item B<psr-cmt-detach> I<domain-id> 1777 1778detach: Detach the platform shared resource monitoring service from a domain. 1779 1780=item B<psr-cmt-show> I<psr-monitor-type> [I<domain-id>] 1781 1782Show monitoring data for a certain domain or all domains. Current supported 1783monitor types are: 1784 - "cache-occupancy": showing the L3 cache occupancy(KB). 1785 - "total-mem-bandwidth": showing the total memory bandwidth(KB/s). 1786 - "local-mem-bandwidth": showing the local memory bandwidth(KB/s). 1787 1788=back 1789 1790=head2 CACHE ALLOCATION TECHNOLOGY 1791 1792Intel Broadwell and later server platforms offer capabilities to configure and 1793make use of the Cache Allocation Technology (CAT) mechanisms, which enable more 1794cache resources (i.e. L3/L2 cache) to be made available for high priority 1795applications. In the Xen implementation, CAT is used to control cache allocation 1796on VM basis. To enforce cache on a specific domain, just set capacity bitmasks 1797(CBM) for the domain. 1798 1799Intel Broadwell and later server platforms also offer Code/Data Prioritization 1800(CDP) for cache allocations, which support specifying code or data cache for 1801applications. CDP is used on a per VM basis in the Xen implementation. To 1802specify code or data CBM for the domain, CDP feature must be enabled and CBM 1803type options need to be specified when setting CBM, and the type options (code 1804and data) are mutually exclusive. There is no CDP support on L2 so far. 1805 1806=over 4 1807 1808=item B<psr-cat-set> [I<OPTIONS>] I<domain-id> I<cbm> 1809 1810Set cache capacity bitmasks(CBM) for a domain. For how to specify I<cbm> 1811please refer to L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>. 1812 1813B<OPTIONS> 1814 1815=over 4 1816 1817=item B<-s SOCKET>, B<--socket=SOCKET> 1818 1819Specify the socket to process, otherwise all sockets are processed. 1820 1821=item B<-l LEVEL>, B<--level=LEVEL> 1822 1823Specify the cache level to process, otherwise the last level cache (L3) is 1824processed. 1825 1826=item B<-c>, B<--code> 1827 1828Set code CBM when CDP is enabled. 1829 1830=item B<-d>, B<--data> 1831 1832Set data CBM when CDP is enabled. 1833 1834=back 1835 1836=item B<psr-cat-show> [I<OPTIONS>] [I<domain-id>] 1837 1838Show CAT settings for a certain domain or all domains. 1839 1840B<OPTIONS> 1841 1842=over 4 1843 1844=item B<-l LEVEL>, B<--level=LEVEL> 1845 1846Specify the cache level to process, otherwise the last level cache (L3) is 1847processed. 1848 1849=back 1850 1851=back 1852 1853=head1 IGNORED FOR COMPATIBILITY WITH XM 1854 1855xl is mostly command-line compatible with the old xm utility used with 1856the old Python xend. For compatibility, the following options are 1857ignored: 1858 1859=over 4 1860 1861=item B<xl migrate --live> 1862 1863=back 1864 1865=head1 TO BE DOCUMENTED 1866 1867We need better documentation for: 1868 1869=over 4 1870 1871=item B<tmem> 1872 1873Transcendent Memory. 1874 1875=back 1876 1877=head1 SEE ALSO 1878 1879The following man pages: 1880 1881L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)> 1882L<xl-network-configuration(5)> 1883 1884And the following documents on the xen.org website: 1885 1886L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt> 1887L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> 1888 1889For systems that don't automatically bring the CPU online: 1890 1891L<http://wiki.xen.org/wiki/Paravirt_Linux_CPU_Hotplug> 1892 1893=head1 BUGS 1894 1895Send bugs to xen-devel@lists.xen.org, see 1896http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports. 1897