nyuuzyou/wikis huggingface dataset:
XAPI Developer Guide

__NOTOC__
== XAPI Developer Guide ==
This guide is a constantly evolving documentation effort to support developers learning about or working with XAPI.
== OCaml Language ==
The XAPI toolstack is written entirely in OCaml. General information on the language is available at http://www.ocaml-tutorial.org/, which is mirrored at http://mirror.ocamlcore.org/ocaml-tutorial.org/. 
* XAPI Source Documentation - OCamlDoc source-code documentation for XAPI
* OCaml Best Practices - Coding standards and guidelines for OCaml source code in XAPI.
* OCaml Editing - Various editor configurations
* OCaml Coding Considerations - Common issues in OCaml
* OCaml Errors - Code examples for various compiler errors
* OCaml Advice - Installation and configuration of OCaml
* OCaml Resources - Helpful Links for more information
* OCaml Cyclical Build Dependencies - Suggestions for cyclical build dependencies
* OCaml Doc - Techniques specific to the XAPI use of OCamlDoc
== XAPI Tutorials ==
A collection of tutorials to better understand how to make changes to XAPI. 
* XAPI Adding Field - Adding a field to an API in XAPI
* XAPI Adding Function - Adding an API function to XAPI
== XAPI Projects ==
Projects currently being worked on and suggestions for future projects.
* XAPI project suggestions - Suggestions for new xapi projects
== XAPI Internals ==
How XAPI Works...
* XAPI Startup - Startup process for XAPI 
* VM Startup - VM startup process within XAPI
* XAPI VM Migration - How XAPI migrates VM
* XAPI Dispatch - Service dispatch and message forwarding mechanism 
* XAPI Pool Join - Internal mechanism behind the pool join process
Category:XAPI Devel
Category:Design Document
Category:Index
XAPI HVM Platform Keys

== HVM Platform Keys ==
Xapi currently has certain defaults in terms of what hardware to emulate for HVM guests. Some of these are configurable through the VM record while others are not. They can be translated into command line options for qemu-dm. In other cases no option is added (falling back to qemu-dm defaults).
This page lists which platform keys are currently considered and they state.
Feature 	Current Status 	Desired Status 	Observations
Parallel Ports	Ignored 	Configurable (in "platform:parallel")	Xapi doesn't instruct qemu-dm at all, leaving it to the default (emulate LPT1). Using "-parallel none" causes qemu-dm not to emulate any parallel ports.
Serial Ports 	Configurable (in "other-config:hvm_serial")	Configurable (in "platform:serial") 	Xapi passes "-serial pty" by default.
Category:XAPI
Category:Users
XAPI Host Plugins

==XAPI Host Plugins==
"The XenAPI has an extension mechanism that allows one to install a Python script (usually, but it can be any executable) on the host side, and then call that through the XenAPI." - http://wiki.openstack.org/XenAPI
Writing a XenAPI plugin in Python is simplified by using the XenAPIPlugin module, which is by default installed in dom0 in XCP. Below is a simple XenAPI plugin which reverses a string passed to it:
#!/usr/bin/python
import XenAPIPlugin
def main(session, args):
 try:
 data = args["data"]
 return data[::-1]
 except KeyError:
 raise RuntimeError("No argument found with key 'data'.")
if __name__ == "__main__":
 XenAPIPlugin.dispatch({"main": main})
Save this code to /etc/xapi.d/plugins/reverse and make it executable. The plugin can then be run from the CLI like so:
# xe host-call-plugin host-uuid=<host-uuid> plugin=reverse fn=main args:data="hello, world"
dlrow ,olleh
Category:XAPI Devel
Category:OpenStack
XAPI Management Tools

= XAPI Management Tools =
This page lists various 3rd party management tools and interfaces for XCP (Xen Cloud Platform). For Xen, please see the list of Xen Management Tools. If you want your project listed here please edit the page or send an email to xen-devel or xen-users mailinglist and we'll update the page.
=Cloud frontends=
* OpenStack: http://www.openstack.org/
* CloudStack: http://cloudstack.org/
= Command Line =
XCP does not come with the 'xm' CLI you may have used for managing traditional Xen. Instead, XCP comes with several CLI management clients built into dom0 (the thin hypervisor host), including:
* xe (/usr/bin/xe)
* xl (/opt/xensource/bin/xl)
* For further documentation, see Command Line Interface - Running the Xen Cloud Platform Command Line Interface
* For installing the 'xe' CLI on another Linux box, see XCP Install CLI
= GUIs on Linux host =
The project which is most active and which is being actively developed is 
*Xen Orchestra
* OpenXenManager: http://sourceforge.net/apps/trac/openxenmanager/wiki/WikiStart
The following projects have been inactive recently:
* XVP (Xen VNC Proxy): http://www.xvpsource.org/
* XCCS (Xen Cloud Control System): http://www.xencloudcontrol.com
= GUIs on Windows host =
Citrix XenCenter is the most popular choice for managing XCP hosts, however, there are a couple minor compatibility issues that can be worked around to improve usage, as described on the XenCenter and XCP compatibility page. These have been resolved for XCP 1.6 and XenCenter will work with open source XenServer
* Citrix XenCenter: http://community.citrix.com/display/xs/XenCenter
= Application Programming Interfaces (APIs)=
* XenAPI (XAPI): XAPI Developer Guide
= Other = 
* Other technologies related to XAPI can be found here
Category:XAPI
Category:Overview
Category:Users
Category:Beginners
XAPI Pool Join

== XAPI Pool Join ==
This page partly describes the internal mechanism behind the pool join process.
The ultimate source of truth is in the [source code]: this page simply gives a flavour of the kind of thing that goes on.
The term "candidate host" is used to refer to the host which is attempting to join the pool.
=== Preliminaries ===
# Check that the candidate host does not have HA enabled. 
# Read the non-shared SRs from the local database. 
# Log in to the pool's master. 
# Check that HA isn't enabled in the pool. 
=== Pre-join assertions ===
# Check that the candidate host is not attempting to join itself (assert_not_joining_myself). 
# Check that there are no other hosts in the local database (assert_i_know_of_no_other_hosts). 
# Check that there are no running or suspended VMs on the candidate host (assert_no_running_or_suspended_vms_on_me). 
# Check that there are no VMs with current operations (assert_no_vms_with_current_ops). 
# Check that hosts are homogeneous in terms of software version and CPU (unless the "force" option is used on the pool join operation) (assert_hosts_homogeneous). 
# Check that the candidate host has no shared SRs (assert_no_shared_srs_on_me). 
# Check that the management interface is (or contains) a physical NIC (assert_management_interface_is_physical). 
# Check that the external authentication type and service name matches the master (assert_external_auth_matches). 
=== Set up ===
# Obtain the pool's "cluster secret" (Client.Pool.initial_auth). 
# Fetch a backup of the master's database (Pool_db_backup.fetch_database_backup). 
=== Synchronise state with the master ===
This is done in a best-effort fashion; errors are suppressed. As much state as possible is synchronised.
# Get the record for the candidate host (or create one none already exists) (create_or_get_host_on_master). 
# Create records for SR and PBD on master (SR.introduce; copy other-config over; PBD.create) (create_sr_and_pbd_on_master). 
# Create records for VMs on master (create_vm_on_master). 
# Remap VDIs to have SR fields matching the newly created SR records (remap_vdi). 
# Create records for VDIs on master (create_vdi_on_master). 
# Remap VBDs to have VDI/VM fields matching the newly created VDI records (remap_vbd). 
# Create records for VBDs on master (create_vbd_on_master). 
# Create physical PIFs (create_pif_and_maybe_network). Re-use the corresponding network if the master has a corresponding PIF. Otherwise create a new network. 
# Remap VIFs to have network fields matching the newly created Network records (remap_vif). 
# Create records for VIFs on master (create_vif_on_master). 
# Set the default crashdump SR and default suspend-image SR on the candidate host's host record. 
=== Finish-up ===
# Write the cluster secret to the Xapi_globs.pool_secret_path file. 
# Set the candidate host's pool role to be a slave (Pool_role.set_role). 
# Restart xapi (Xapi_fuse.light_fuse_and_run). 
Category:XAPI Devel
Category:Design Document
XAPI Ubuntu Install

Ubuntu is supported both as a PV or HVM guest on XAPI-based orchestrators like XenServer. Ubuntu 10.04 LTS works out-of-the-box as a PV guest.
There's some helpful information on the Ubuntu wiki, but bear in mind this information is oriented towards a local Xen Project configuration, not specifically XAPI:
*https://help.ubuntu.com/community/Xen
*https://help.ubuntu.com/community/XenProposed (a better version of the docs)
== Considerations for XenServer Users ==
On XenServer, the easiest way to install a new Ubuntu guest is to use XenCenter and one of the built-in Ubuntu templates.
If using the Ubuntu template in XenCenter to create a new VM, enter this URL as the InstallURL to setup a new copy of Ubuntu: http://archive.ubuntu.net/ubuntu. This will allow you to easily do a network install with 10.04.
If you have boot problems, please read XAPI_Ubuntu_PV for more information about configuring the Ubuntu kernel to boot correctly from XenServer.
== XAPI packages in Ubuntu Server 12.04 LTS ==
Ubuntu Server 12.04 LTS now supports the Xen Project Hypervisor, the XAPI packages (called XCP-XAPI) and XAPI-based OpenStack plug-ins. The inclusion of the XAPI packages into Ubuntu Server 12.04 LTS makes the Xen Project Hypervisor more easily accessible to Ubuntu users and adds a wealth of enterprise virtualization functionality.
== Access via XAPI protocol on Ubuntu Server 12.04 ==
This post suggests that an adjustment to the PAM rules is needed for remote XAPI nodes to access the server. This affects XenServer's XenCenter and third-party XAPI-based orchestrators.
Edit the /etc/pam.d/xapi file as follows. If you change the file to look like this, you should be able to log in with a XAPI-based orchestrator:
#%PAM-1.0
auth include common-auth
account include common-auth
password include common-auth
== Documentation ==
* XAPI package on Ubuntu
* XAPI documentation on Ubuntu
* OpenStack documentation
Category:Users
Category:Ubuntu
Category:Guest Install
Category:XAPI
Category:XCP
XAPI Ubuntu PV

=Ubuntu PV Guest Support=
These instructions are specific to PV (paravirtual) guests running on XAPI. PV means that the guest's kernel is launched directly from XAPI and that the kernel has built-in support for Xen Project Hypervisor. This page is not applicable to HVM guests.
The reason why Ubuntu 10.04 works as a PV guest without changing the kernel is because 10.04 (not sure about the other Ubuntu releases) shipped with a kernel that has pvops built-in, which means it was pre-compiled to support being run as a Xen Project PV guest natively.
For more information specific to Xen Project on Ubuntu, read here: https://help.ubuntu.com/community/Xen
All of that said, the below is mostly generic to any Linux PV guest.
If you're having trouble booting your Linux (Ubuntu in this case) guest due to complaints about XAPI being unable to locate the kernel, the below may help.
=Update PV Grub Configuration=
First, if you want to live edit the guest's grub configuration, you can do so:
export UUID=MYUUID
#list the VM disks
xe vm-disk-list uuid=$UUID
#edit system's live grub
xe-edit-bootloader -n "MYHOSTNAME" -p 1 -f /grub/grub.cfg
=Set the Boot Kernel=
Now, assuming you know exactly what the kernel and ramdisk file names are called (e.g. look through the grub config as above), you can tell XAPI exactly which image to use to boot your system.
Replace the examples below with your actual kernel/ramdisk:
export UUID=MYUUID
#just in case, save the current values
xe vm-param-get uuid=$UUID param-name=PV-bootloader-args
xe vm-param-get uuid=$UUID param-name=PV-args
# set the correct kernel image, init image, and root device per your specific machine
xe vm-param-set uuid=$UUID PV-bootloader-args="--kernel=/vmlinuz-MYKERNEL --ramdisk=/initrd.img-MYKERNEL"
xe vm-param-set uuid=$UUID PV-args="root=/dev/MYROOTDISK-root ro quiet"
XAPI VM Migration

Note: this description has been out of date for a while. To see how migration works, it is best to read the code starting from here: https://github.com/xapi-project/xen-api/blob/a232a3db5e51bf21eed2680386e4de79dcf4c70e/ocaml/xapi/message_forwarding.ml#L1638
== XAPI VM Migration ==
Here's an overview of how xapi does migration of VMs. The code can be found in api.hg/ocaml/xapi/xapi_vm_migrate.ml.
Receiver
attach the VDIs
create the domain
restore the devices (unless we must delay until after VDI activation)
send handshake to transmitter
Synchronisation point 1
restore the domain, deserialising it from the transmitter
Synchronisation point 2
receive handshake from transmitter
Synchronisation point 3
activate VDIs (unless it's a localhost migrate)
restore the devices (unless done already)
unpause the domain
plug PCI devices
send handshake to transmitter
Synchronisation point 4
You may be interested in a proposal for CrossPoolMigration
Category:XAPI Devel
Category:Design Document
XAPI fake presence of PV drivers

= Faking the presence of the PV drivers =
xapi currently insists that PV drivers are present before allowing the operations:
* suspend/resume
* migrate
* clean reboot/shutdown
* disk, nic hotplug/unplug
The vast majority of testing is performed with PV drivers and it is recommended that PV drivers are always installed.
However, at the xen-level, plain HVM guests without PV drivers can usually still be suspend/resumed and migrated, although with reduced performance (e.g. in the case of migrate: longer VM downtime). It is convenient to "fake" the presence of PV drivers in order to test these features during development, without having to always install PV tools in VMs.
The following script takes the VM's uuid and writes the magic xenstore keys to fake the presence of up-to-date PV drivers. It must be run on the same host as the VM.
#!/bin/sh
set -e
usage() {
 echo "$0 <VM uuid>"
 echo " -- fakes the presence of PV tools in <VM uuid>"
 echo " -- NB the VM must be either paused or running on localhost"
}
 
fake(){
 local uuid=$1
 domid=$(xe vm-list uuid=${uuid} params=dom-id --minimal)
 xenstore-write /local/domain/${domid}/attr/PVAddons/MajorVersion ${major} \
	 /local/domain/${domid}/attr/PVAddons/MinorVersion ${minor} \
 /local/domain/${domid}/attr/PVAddons/MicroVersion ${micro} \
 /local/domain/${domid}/data/updated 1
}
uuid=$(xe vm-list uuid=$1 params=uuid --minimal)
if [ $? -ne 0 ]; then
 echo "Argument should be a VM uuid"
 usage
 exit 1
fi
# use the PRODUCT_VERSION from here:
. /etc/xensource-inventory
major=$(echo ${PRODUCT_VERSION} | cut -f 1 -d .)
minor=$(echo ${PRODUCT_VERSION} | cut -f 2 -d .)
micro=$(echo ${PRODUCT_VERSION} | cut -f 3 -d .)
# Check the VM is running on this host
resident_on=$(xe vm-list uuid=${uuid} params=resident-on --minimal)
if [ "${resident_on}" != "${INSTALLATION_UUID}" ]; then
 echo "VM must be resident on this host"
 exit 2
fi
power_state=$(xe vm-list uuid=${uuid} params=power-state --minimal)
case "${power_state}" in
 running)
 fake $uuid
 ;;
 paused)
 fake $uuid
 ;;
 *)
 echo "VM must be either running or paused"
 exit 3
 ;;
esac
Category:XAPI Devel
Category:Design Document
XCP Design and Architecture Docs

This page contains links to features and designs that have been implemented or are currently being in XAPI and XCP. These documents can help you understand how XAPI works. For XCP, see the XenServer Wiki.
== The following features/proposals have been completed ==
Tunnelling
Emergency Network Reset
Cross-host VDI.copy
Compressing VM Exports
== The following features/proposals are currently being implemented ==
NIC Bonding Improvements
domain tasklets
GPU pass-through API support
XAPI on Debian
XAPI on Ubuntu
== Design Documents ==
XAPI Dispatch
XAPI fake presence of PV drivers
XAPI Pool Join
XAPI RRDs
XAPI Startup
XAPI VM Migration
XAPI Adding Field
XAPI Adding Function
Category:XAPI Devel
Category:Index
Category:Design Document
XCP NIC Bonding

NIC bonding can improve server resiliency by using two physical NICs as if they were one. Two NICs may be bonded to create a single, high-performing channel that provides connectivity between VMs and your external network. [1]
You can create a NIC bond in XenCenter by using "Add Network" in the Networking tab and choosing Bonded network.
=Active/Active=
This is the default mode with traffic balanced between NICs using Source Level Balancing (SLB). This mode will only work properly on a single logical switch (e.g. a single physical switch, or multiple switches that are stacked with proprietary backplanes such that they appear as a single switch). The advantage of this mode is it will use both interfaces for increased capacity, and also will fail-over between ports if one fails.
=Active/Backup=
If you're trying to setup simple fail-over redundancy with 2 separate switches, you probably want active/backup, which you can only configure from the CLI.
The recommended method is setup the bond first in XenCenter, then change the type to active/backup as below:
xe bond-list
Pick out the bond's master UUID like master ( RO): 4b9c2fa4-daa0-f9e8-4313-90cfa57019f3
xe pif-param-set uuid=4b9c2fa4-daa0-f9e8-4313-90cfa57019f3 other-config:bond-mode=active-backup
=References=
# http://support.citrix.com/article/CTX124421
# http://support.citrix.com/article/CTX124421
Category:Users
Category:Example
Category:XCP
XEND

== Man Pages ==
These pages point to the Xen Project 4.4 tree, the last release to include XEND.
== Xen Project Man Pages ==
Man page 	Description
xm(1) 	Xen Project management user interface (deprecated, also see Xen 4.1+ Upgrade Notes)
xend-config.sxp(5) 	Xen Project daemon configuration file (deprecated, also see Xen 4.1+ Upgrade Notes)
xmdomain.cfg(5) 	XM domain config file format (deprecated, also see Xen 4.1+ Upgrade Notes)
xm.cfg(5), sEDF scheduler	The sEDF scheduler provides weighted CPU sharing in an intuitive way and uses realtime-algorithms to ensure time guarantees.
== Also See ==
* XL vs Xend Feature Comparison
* Learn about migrating from XEND to libxenlight in the video XM to XL: A Short, But Necessary, Journey
Category:Beginners
Category:Users
Category:Developers
XL vs Xend Feature Comparison

The following compares the featureset of the xend toolstack vs the xl toolstack as of Xen 4.4 and 4.5.
 	xm / xend 	xl
Guest Types 	Guest Types 	Guest Types
PV guests 	 	
HVM guests 	 	
PVHVM guests 	 	
PVH guests 	 	
Guest lifecycle operations 	Guest lifecycle operations 	Guest lifecycle operations
Create, shutdown, reboot 	 	
Pause, unpause 	 	
List, rename 	 	
Live migration and save/restore 	 	
Remus Integration 	[ 4 ] 	
Guest device support 	Guest device support 	Guest device support
Network devices (both para-virtualised and emulated) 	 	
Block devices (both para-virtualised and emulated) 	 	
Sharing storage across DomU's via w! in virtual machines configuration files in disk settings	 	[ 1 ]
Virtual framebuffer, keyboard and mouse (both para-virtualised and emulated) 	[ 6 ] 	[ 6 ][ 7 ]
SPICE framebuffer/console support 	 	
QXL graphics device support for SPICE 	 	[ 2 ]
PV console devices 	 	
PCI device passthrough 	 	
VGA graphics device (GPU) passthrough 	 	
SCSI LUN/Host passthrough (PVSCSI) 	 	[ 2 ]
Qemu USB device passthrough via config file (using qemu xen traditional) 	 	
Qemu USB device passthrough via config file (using qemu upstream) 	 	
Qemu USB device passthrough via hotplug (using qemu xen traditional) 	 	[ 3 ]
Qemu USB device passthrough via hotplug (using qemu upstream) 	 	[ 3 ]
Qemu USB device passthrough support for USB 1.1 	 	
Qemu USB device passthrough support for USB 2.0 (qemu upstream) 	 	
Qemu USB device passthrough support for USB 3.0 (qemu upstream) 	 	
PVUSB USB 2.0 device passthrough for both PV and HVM guests 	 	[ 3 ]
Device Model Support 	Device Model Support 	Device Model Support
Qemu Xen Traditional Device Model 	 	
Upstream Qemu Device Model 	 	
Stub domain Qemu Xen Traditional Device Model 	 	
Stub domain Upstream Qemu Device Model 	 	[ 2 ]
Misc Features 	Misc Features 	Misc Features
CPU pools 	[ 5 ] 	
Cpupool-per-NUMA node. 	 	
Control of CPU scheduler parameters 	 	
TMEM 	 	
XSM/Flash policy control 	 	
Control of CPUID features exposed to guests. 	 	(syntax greatly improved)
Features that are explicitly not supported in XL 	Features that are explicitly not supported in XL	Features that are explicitly not supported in XL
Managed Domains 	 	[ 1 ]
Python code in configuration files 	 	[ 1 ]
[ 1 ] Feature is explicitly not supported by xl, see XL Anti-Features 
[ 2 ] Feature will be exposed in a future release 
[ 3 ] Feature development has started in the Xen 4.5 release cycle, but did not get completed 
[ 4 ] See Remus Toolkit Differences 
[ 5 ] Undocumented in XEND man pages 
[ 6 ] Includes SDL & VNC support
[ 7 ] Includes SPICE support 
Also See:
* XL
* XEND
* Choice of Toolstacks
* Short video overview: XM to XL: A Short, But Necessary, Journey
* Remus Toolkit Differences 
Category:Xen Category:Xen 4.2 Category:Users
Category:Xen 4.3
Category:Xen 4.4
Category:Xen 4.5
Category:Compatibility
XM

== Documentation ==
These pages link to the Xen Project 4.4 documentation, the last version to support xm.
 
Document related to xm and xmdomain.cfg	Description
xm(1) 	Xen Project management user interface
xmdomain.cfg(5) 	XM domain config file format
xm.cfg(5), sEDF scheduler 	The sEDF scheduler provides weighted CPU sharing in an intuitive way and uses realtime-algorithms to ensure time guarantees.
Category:Beginners
Category:Users
Category:Developers
XSMAsDefault TODO List

== What do we want to achieve ==
XSM with default policy will have:
* Same functionality exposed to guests without regressions
* Have at minimum the same security as we have without XSM enabled.
* Have set of policies for device driver domains vs control domains.
== Known Issues ==
* Cannot re-apply a new policy after guests have been running.
== TODO List ==
Category:Security
* Could initial build of Xen hypervisor include a built-in (inside .init.data) policy file?
* Can we make policies modularized? A core (perhaps built-in?) with amendments loaded later?
Xapi on debian user experience improvements

This page lists a number of things we could do to make the default experience of xapi on debian more smooth
# "xe" could detect when it's talking to another webserver (e.g. apache) and print something more helpful than "Server internal error."
# the NFS SR could detect when "nfs-common" hasn't been installed and prompt to install it (or it could depend on it)
# the regenerate templates md5 stamp shouldn't be written if the regenerate templates fails (eg due to a dead xapi)
# xapi startup should print a more useful message if libXc doesn't work because the "xen" init.d script hasn't done the necessary setup
Category:XAPI Devel
Xcp-xapi Release History

= xcp-xapi Package Release History =
We hope to have xapi as widely available as possible. It is currently explicitly up-streamed into Debian and Ubuntu. Hopefully work will soon staring on Fedora.
== Source ==
You can see the source here: https://github.com/xen-org
== Debian ==
=== 7.0 (Wheezy) ===
First release with package included.
For more info see: http://packages.debian.org/wheezy/xcp-xapi
== Ubuntu ==
=== 12.04 (Precise) ===
First release with packages included.
For more info see: http://packages.ubuntu.com/precise/xcp-xapi