diff --git a/docs/api.html.in b/docs/api.html.in index 0b9ffd3608..4b6a529b1c 100644 --- a/docs/api.html.in +++ b/docs/api.html.in @@ -84,7 +84,7 @@ which is garanteed to be unique for long term usage and across a set of nodes. - +

Functions and naming conventions

The naming of the functions present in the library is usually @@ -93,7 +93,7 @@

For each first class object you will find apis for the following actions:

For more in-depth details of the storage related APIs see - the storage management page, + the storage management page,

The libvirt drivers

diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in index 2cbd2bd2b3..59d3414a5b 100644 --- a/docs/api_extension.html.in +++ b/docs/api_extension.html.in @@ -145,20 +145,20 @@

  1. SHOULD log a message with VIR_DEBUG() indicating that it is - being called and its parameters;
    2. + being called and its parameters;
  2. MUST call virResetLastError();
  3. SHOULD confirm that the connection is valid with - VIR_IS_CONNECT(conn);
    4. + VIR_IS_CONNECT(conn);
  4. SECURITY: If the API requires a connection with write - privileges, MUST confirm that the connection flags do not - indicate that the connection is read-only;
    5. + privileges, MUST confirm that the connection flags do not + indicate that the connection is read-only;
  5. SHOULD do basic validation of the parameters that are being - passed in;
    6. + passed in;
  6. MUST confirm that the driver for this connection exists and that - it implements this function;
    7. + it implements this function;
  7. MUST call the internal API;
  8. SHOULD log a message with VIR_DEBUG() indicating that it is - returning, its return value, and status.
    9. + returning, its return value, and status.
  9. MUST return status to the caller.
diff --git a/docs/apps.html.in b/docs/apps.html.in index 48e0bb5115..215c9b25ac 100644 --- a/docs/apps.html.in +++ b/docs/apps.html.in @@ -21,42 +21,42 @@
virsh
- An interactive shell, and batch scriptable tool for performing - management tasks on all libvirt managed domains, networks and - storage. This is part of the libvirt core distribution. + An interactive shell, and batch scriptable tool for performing + management tasks on all libvirt managed domains, networks and + storage. This is part of the libvirt core distribution.
virt-install
- Provides a way to provision new virtual machines from a - OS distribution install tree. It supports provisioning from - local CD images, and the network over NFS, HTTP and FTP. + Provides a way to provision new virtual machines from a + OS distribution install tree. It supports provisioning from + local CD images, and the network over NFS, HTTP and FTP.
virt-clone
- Allows the disk image(s) and configuration for an existing - virtual machine to be cloned to form a new virtual machine. - It automates copying of data across to new disk images, and - updates the UUID, Mac address and name in the configuration + Allows the disk image(s) and configuration for an existing + virtual machine to be cloned to form a new virtual machine. + It automates copying of data across to new disk images, and + updates the UUID, Mac address and name in the configuration
virt-image
- Provides a way to deploy virtual appliances. It defines a - simplified portable XML format describing the pre-requisites - of a virtual machine. At time of deployment this is translated - into the domain XML format for execution under any libvirt - hypervisor meeting the pre-requisites. + Provides a way to deploy virtual appliances. It defines a + simplified portable XML format describing the pre-requisites + of a virtual machine. At time of deployment this is translated + into the domain XML format for execution under any libvirt + hypervisor meeting the pre-requisites.
virt-df
- Examine the utilization of each filesystem in a virtual machine - from the comfort of the host machine. This tool peeks into the - guest disks and determines how much space is used. It can cope - with common Linux filesystems and LVM volumes. + Examine the utilization of each filesystem in a virtual machine + from the comfort of the host machine. This tool peeks into the + guest disks and determines how much space is used. It can cope + with common Linux filesystems and LVM volumes.
virt-top
- Watch the CPU, memory, network and disk utilization of all - virtual machines running on a host. + Watch the CPU, memory, network and disk utilization of all + virtual machines running on a host.
@@ -65,17 +65,17 @@
virt-manager
- A general purpose desktop management tool, able to manage - virtual machines across both local and remotely accessed - hypervisors. It is targeted at home and small office usage - upto managing 10-20 hosts and their VMs. + A general purpose desktop management tool, able to manage + virtual machines across both local and remotely accessed + hypervisors. It is targeted at home and small office usage + upto managing 10-20 hosts and their VMs.
virt-viewer
- A lightweight tool for accessing the graphical console - associated with a virtual machine. It can securely connect - to remote consoles supporting the VNC protocol. Also provides - an optional mozilla browser plugin. + A lightweight tool for accessing the graphical console + associated with a virtual machine. It can securely connect + to remote consoles supporting the VNC protocol. Also provides + an optional mozilla browser plugin.
@@ -84,18 +84,18 @@
oVirt
- oVirt provides the ability to manage large numbers of virtual - machines across an entire data center of hosts. It integrates - with FreeIPA for Kerberos authentication, and in the future, - certificate management. + oVirt provides the ability to manage large numbers of virtual + machines across an entire data center of hosts. It integrates + with FreeIPA for Kerberos authentication, and in the future, + certificate management.
AbiCloud
- AbiCloud is an open source cloud platform manager which allows to - easily deploy a private cloud in your datacenter. One of the key - differences of AbiCloud is the web rich interface for managing the - infrastructure. You can deploy a new service just dragging and - dropping a VM. + AbiCloud is an open source cloud platform manager which allows to + easily deploy a private cloud in your datacenter. One of the key + differences of AbiCloud is the web rich interface for managing the + infrastructure. You can deploy a new service just dragging and + dropping a VM.
@@ -104,10 +104,10 @@
virt-p2v
- A tool for converting a physical machine into a virtual machine. It - is a LiveCD which is booted on the machine to be converted. It collects - a little information from the user and then copies the disks over to - a remote machine and defines the XML for a domain to run the guest. + A tool for converting a physical machine into a virtual machine. It + is a LiveCD which is booted on the machine to be converted. It collects + a little information from the user and then copies the disks over to + a remote machine and defines the XML for a domain to run the guest.
@@ -115,13 +115,13 @@
for munin
- The plugins provided by Guido Günther allow to monitor various things + The plugins provided by Guido Günther allow to monitor various things like network and block I/O with Munin.
for collectd
- The libvirt-plugin is part of collectd + The libvirt-plugin is part of collectd and gather statistics about virtualized guests on a system. This way, you can collect CPU, network interface and block device usage for each guest without installing collectd on the guest systems. @@ -130,8 +130,8 @@
nagios-virt
- Nagios-virt is a configuration tool for adding monitoring of your - virtualised domains to Nagios. + Nagios-virt is a configuration tool for adding monitoring of your + virtualised domains to Nagios. You can use this tool to either set up a new Nagios installation for your Xen or QEMU/KVM guests, or to integrate with your existing Nagios installation. diff --git a/docs/archnetwork.html.in b/docs/archnetwork.html.in index ab019dbe02..22e8697bc7 100644 --- a/docs/archnetwork.html.in +++ b/docs/archnetwork.html.in @@ -11,26 +11,26 @@ diff --git a/docs/archstorage.html.in b/docs/archstorage.html.in index 9bdbe53e3b..059f0b7921 100644 --- a/docs/archstorage.html.in +++ b/docs/archstorage.html.in @@ -7,16 +7,16 @@

  1. - Volume - a single storage volume which can - be assigned to a guest, or used for creating further pools. A - volume is either a block device, a raw file, or a special format - file. + Volume - a single storage volume which can + be assigned to a guest, or used for creating further pools. A + volume is either a block device, a raw file, or a special format + file.
  2. - Pool - provides a means for taking a chunk - of storage and carving it up into volumes. A pool can be used to - manage things such as a physical disk, a NFS server, a iSCSI target, - a host adapter, an LVM group. + Pool - provides a means for taking a chunk + of storage and carving it up into volumes. A pool can be used to + manage things such as a physical disk, a NFS server, a iSCSI target, + a host adapter, an LVM group.
diff --git a/docs/bugs.html.in b/docs/bugs.html.in index 62e3864b0f..380bcff908 100644 --- a/docs/bugs.html.in +++ b/docs/bugs.html.in @@ -30,26 +30,26 @@

Linux Distribution specific bug reports

@@ -65,7 +65,7 @@
uuid
The content of the uuid element provides - a globally unique identifier for the virtual machine. - The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. - If omitted when defining/creating a new machine, a random - UUID is generated. Since 0.0.1
+ a globally unique identifier for the virtual machine. + The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. + If omitted when defining/creating a new machine, a random + UUID is generated. Since 0.0.1

Operating system booting

@@ -78,24 +78,24 @@
type
The content of the type element specifies the - type of operating system to be booted in the virtual machine. - hvm indicates that the OS is one designed to run - on bare metal, so requires full virtualization. linux - (badly named!) refers to an OS that supports the Xen 3 hypervisor - guest ABI. There are also two optional attributes, arch - specifying the CPU architecture to virtualization, and machine - referring to the machine type. The Capabilities XML - provides details on allowed values for these. Since 0.0.1
+ type of operating system to be booted in the virtual machine. + hvm indicates that the OS is one designed to run + on bare metal, so requires full virtualization. linux + (badly named!) refers to an OS that supports the Xen 3 hypervisor + guest ABI. There are also two optional attributes, arch + specifying the CPU architecture to virtualization, and machine + referring to the machine type. The Capabilities XML + provides details on allowed values for these. Since 0.0.1
loader
The optional loader tag refers to a firmware blob - used to assist the domain creation process. At this time, it is - only needed by Xen fully virtualized domains. Since 0.1.0
+ used to assist the domain creation process. At this time, it is + only needed by Xen fully virtualized domains. Since 0.1.0
boot
The dev attribute takes one of the values "fd", "hd", - "cdrom" or "network" and is used to specify the next boot device - to consider. The boot element can be repeated multiple - times to setup a priority list of boot devices to try in turn. - Since 0.1.3 + "cdrom" or "network" and is used to specify the next boot device + to consider. The boot element can be repeated multiple + times to setup a priority list of boot devices to try in turn. + Since 0.1.3
@@ -111,22 +111,22 @@ 
         ...
-	<bootloader>/usr/bin/pygrub</bootloader>
-	<bootloader_args>--append single</bootloader_args>
+        <bootloader>/usr/bin/pygrub</bootloader>
+        <bootloader_args>--append single</bootloader_args>
         ...
bootloader
The content of the bootloader element provides - a fully qualified path to the bootloader executable in the - host OS. This bootloader will be run to choose which kernel - to boot. The required output of the bootloader is dependent - on the hypervisor in use. Since 0.1.0
+ a fully qualified path to the bootloader executable in the + host OS. This bootloader will be run to choose which kernel + to boot. The required output of the bootloader is dependent + on the hypervisor in use. Since 0.1.0
bootloader_args
The optional bootloader_args element allows - command line arguments to be passed to the bootloader. - Since 0.2.3 -
+ command line arguments to be passed to the bootloader. + Since 0.2.3 +
@@ -141,64 +141,64 @@ 
         ...
-	<os>
+        <os>
           <type>hvm</type>
           <loader>/usr/lib/xen/boot/hvmloader</loader>
           <kernel>/root/f8-i386-vmlinuz</kernel>
           <initrd>/root/f8-i386-initrd</initrd>
           <cmdline>console=ttyS0 ks=http://example.com/f8-i386/os/</cmdline>
-	</os>
-	...
+ </os> + ...
type
This element has the same semantics as described earlier in the - BIOS boot section
+ BIOS boot section
loader
This element has the same semantics as described earlier in the - BIOS boot section
+ BIOS boot section
kernel
The contents of this element specify the fully-qualified path - to the kernel image in the host OS.
+ to the kernel image in the host OS.
initrd
The contents of this element specify the fully-qualified path - to the (optional) ramdisk image in the host OS.
+ to the (optional) ramdisk image in the host OS.
cmdline
The contents of this element specify arguments to be passed to - the kernel (or installer) at boottime. This is often used to - specify an alternate primary console (eg serial port), or the - installation media source / kickstart file
+ the kernel (or installer) at boottime. This is often used to + specify an alternate primary console (eg serial port), or the + installation media source / kickstart file

Basic resources

         ...
-	<memory>524288</memory>
-	<currentMemory>524288</currentMemory>
-	<memoryBacking>
-	  <hugepages/>
+        <memory>524288</memory>
+        <currentMemory>524288</currentMemory>
+        <memoryBacking>
+          <hugepages/>
         </memoryBacking>
-	<vcpu>1</vcpu>
-	...
+ <vcpu>1</vcpu> + ...
memory
The maximum allocation of memory for the guest at boot time. - The units for this value are kilobytes (i.e. blocks of 1024 bytes)
+ The units for this value are kilobytes (i.e. blocks of 1024 bytes)
currentMemory
The actual allocation of memory for the guest. This value - be less than the maximum allocation, to allow for ballooning - up the guests memory on the fly. If this is omitted, it defaults - to the same value as the memory element
+ be less than the maximum allocation, to allow for ballooning + up the guests memory on the fly. If this is omitted, it defaults + to the same value as the memory element
memoryBacking
The optional memoryBacking element, may have an - hugepages element set within it. This tells the - hypervisor that the guest should have its memory allocated using - hugepages instead of the normal native page size.
+ hugepages element set within it. This tells the + hypervisor that the guest should have its memory allocated using + hugepages instead of the normal native page size.
vcpu
The content of this element defines the number of virtual - CPUs allocated for the guest OS.
+ CPUs allocated for the guest OS.

Lifecycle control

@@ -214,21 +214,21 @@ 
         ...
-	<on_poweroff>destroy</on_poweroff>
-	<on_reboot>restart</on_reboot>
-	<on_crash>restart</on_crash>
-	...
+ <on_poweroff>destroy</on_poweroff> + <on_reboot>restart</on_reboot> + <on_crash>restart</on_crash> + ...
on_poweroff
The content of this element specifies the action to take when - the guest requests a poweroff.
+ the guest requests a poweroff.
on_reboot
The content of this element specifies the action to take when - the guest requests a reboot.
+ the guest requests a reboot.
on_crash
The content of this element specifies the action to take when - the guest crashes.
+ the guest crashes.

@@ -238,16 +238,16 @@

destroy
The domain will be terminated completely and all resources - released
+ released
restart
The domain will be terminated, and then restarted with - the same configuration
+ the same configuration
preserve
The domain will be terminated, and its resource preserved - to allow analysis.
+ to allow analysis.
rename-restart
The domain will be terminated, and then restarted with - a new name
+ a new name

Hypervisor features

@@ -259,12 +259,12 @@ 
         ...
-	<features>
-	  <pae/>
-	  <acpi/>
-	  <apic/>
-	</features>
-	...
+ <features> + <pae/> + <acpi/> + <apic/> + </features> + ...

All features are listed within the features @@ -277,10 +277,10 @@

pae
Physical address extension mode allows 32-bit guests - to address more than 4 GB of memory.
+ to address more than 4 GB of memory.
acpi
ACPI is useful for power management, for example, with - KVM guests it is required for graceful shutdown to work. + KVM guests it is required for graceful shutdown to work.
@@ -296,13 +296,13 @@ 
         ...
         <clock offset="localtime"/>
-	...
+ ...
clock
The offset attribute takes either "utc" or - "localtime" to specify how the guest clock is initialized - in relation to the host OS. + "localtime" to specify how the guest clock is initialized + in relation to the host OS.
@@ -318,17 +318,17 @@ 
         ...
         <devices>
-	  <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+          <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
           ...
emulator
- The contents of the emulator element specify - the fully qualified path to the device model emulator binary. - The capabilities XML specifies - the recommended default emulator to use for each particular - domain type / architecture combination. + The contents of the emulator element specify + the fully qualified path to the device model emulator binary. + The capabilities XML specifies + the recommended default emulator to use for each particular + domain type / architecture combination.
@@ -342,47 +342,47 @@ 
           ...
-	  <disk type='file'>
-	    <driver name="tap" type="aio">
-	    <source file='/var/lib/xen/images/fv0'/>
-	    <target dev='hda' bus='ide'/>
+          <disk type='file'>
+            <driver name="tap" type="aio">
+            <source file='/var/lib/xen/images/fv0'/>
+            <target dev='hda' bus='ide'/>
             <encryption type='...'>
               ...
             </encryption>
-	  </disk>
-	  ...
+ </disk> + ...
disk
The disk element is the main container for describing - disks. The type attribute is either "file" or "block" - and refers to the underlying source for the disk. The optional - device attribute indicates how the disk is to be exposed - to the guest OS. Possible values for this attribute are "floppy", "disk" - and "cdrom", defaulting to "disk". - Since 0.0.3; "device" attribute since 0.1.4
+ disks. The type attribute is either "file" or "block" + and refers to the underlying source for the disk. The optional + device attribute indicates how the disk is to be exposed + to the guest OS. Possible values for this attribute are "floppy", "disk" + and "cdrom", defaulting to "disk". + Since 0.0.3; "device" attribute since 0.1.4
source
If the disk type is "file", then the file attribute - specifies the fully-qualified path to the file holding the disk. If the disk - type is "block", then the dev attribute specifies - the path to the host device to serve as the disk. Since 0.0.3
+ specifies the fully-qualified path to the file holding the disk. If the disk + type is "block", then the dev attribute specifies + the path to the host device to serve as the disk. Since 0.0.3
target
The target element controls the bus / device under which the - disk is exposed to the guest OS. The dev attribute indicates - the "logical" device name. The actual device name specified is not guaranteed to map to - the device name in the guest OS. Treat it as a device ordering hint. - The optional bus attribute specifies the type of disk device - to emulate; possible values are driver specific, with typical values being - "ide", "scsi", "virtio", "xen" or "usb". If omitted, the bus type is - inferred from the style of the device name. eg, a device named 'sda' - will typically be exported using a SCSI bus. - Since 0.0.3; bus attribute since 0.4.3; + disk is exposed to the guest OS. The dev attribute indicates + the "logical" device name. The actual device name specified is not guaranteed to map to + the device name in the guest OS. Treat it as a device ordering hint. + The optional bus attribute specifies the type of disk device + to emulate; possible values are driver specific, with typical values being + "ide", "scsi", "virtio", "xen" or "usb". If omitted, the bus type is + inferred from the style of the device name. eg, a device named 'sda' + will typically be exported using a SCSI bus. + Since 0.0.3; bus attribute since 0.4.3; "usb" attribute value since after 0.4.4
driver
If the hypervisor supports multiple backend drivers, then the optional - driver element allows them to be selected. The name - attribute is the primary backend driver name, while the optional type - attribute provides the sub-type. Since 0.1.8 + driver element allows them to be selected. The name + attribute is the primary backend driver name, while the optional type + attribute provides the sub-type. Since 0.1.8
encryption
If present, specifies how the volume is encrypted. See @@ -401,22 +401,22 @@ 
           ...
-	  <hostdev mode='subsystem' type='usb'>
-	    <source>
-	      <vendor id='0x1234'/>
-	      <product id='0xbeef'/>
-	    </source>
-	  </hostdev>
-	  ...
+ <hostdev mode='subsystem' type='usb'> + <source> + <vendor id='0x1234'/> + <product id='0xbeef'/> + </source> + </hostdev> + ...

or:

           ...
-	  <hostdev mode='subsystem' type='pci'>
-	    <source>
-	      <address bus='0x06' slot='0x02' function='0x0'/>
-	    </source>
-	  </hostdev>
-	  ...
+ <hostdev mode='subsystem' type='pci'> + <source> + <address bus='0x06' slot='0x02' function='0x0'/> + </source> + </hostdev> + ...
hostdev
@@ -457,12 +457,12 @@ 
           ...
-	  <interface type='bridge'>
-	    <source bridge='xenbr0'/>
-	    <mac address='00:16:3e:5d:c7:9e'/>
-	    <script path='vif-bridge'/>
-	  </interface>
-	  ...
+ <interface type='bridge'> + <source bridge='xenbr0'/> + <mac address='00:16:3e:5d:c7:9e'/> + <script path='vif-bridge'/> + </interface> + ...
Virtual network
@@ -663,16 +663,16 @@ qemu-kvm -net nic,model=? /dev/null 
           ...
-	  <input type='mouse' bus='usb'/>
-	  ...
+ <input type='mouse' bus='usb'/> + ...
input
The input element has one mandatory attribute, the type - whose value can be either 'mouse' or 'tablet'. The latter provides absolute - cursor movement, while the former uses relative movement. The optional - bus attribute can be used to refine the exact device type. - It takes values "xen" (paravirtualized), "ps2" and "usb".
+ whose value can be either 'mouse' or 'tablet'. The latter provides absolute + cursor movement, while the former uses relative movement. The optional + bus attribute can be used to refine the exact device type. + It takes values "xen" (paravirtualized), "ps2" and "usb".
@@ -687,11 +687,11 @@ qemu-kvm -net nic,model=? /dev/null 
           ...
-	  <graphics type='sdl' display=':0.0'/>
-	  <graphics type='vnc' port='5904'/>
-	  <graphics type='rdp' autoport='yes' multiUser='yes' />
-	  <graphics type='desktop' fullscreen='yes'/>
-	  ...
+ <graphics type='sdl' display=':0.0'/> + <graphics type='vnc' port='5904'/> + <graphics type='rdp' autoport='yes' multiUser='yes' /> + <graphics type='desktop' fullscreen='yes'/> + ...
graphics
@@ -775,16 +775,16 @@ qemu-kvm -net nic,model=? /dev/null 
         ...
         <parallel type='pty'>
-	  <source path='/dev/pts/2'/>
-	  <target port='0'/>
+          <source path='/dev/pts/2'/>
+          <target port='0'/>
         </parallel>
         <serial type='pty'>
-	  <source path='/dev/pts/3'/>
-	  <target port='0'/>
+          <source path='/dev/pts/3'/>
+          <target port='0'/>
         </serial>
         <console type='pty'>
-	  <source path='/dev/pts/4'/>
-	  <target port='0'/>
+          <source path='/dev/pts/4'/>
+          <target port='0'/>
         </console>
         </devices>
       </domain>
@@ -797,17 +797,17 @@ qemu-kvm -net nic,model=? /dev/null
Represents a serial port
console
Represents the primary console. This can be the paravirtualized - console with Xen guests, or duplicates the primary serial port - for fully virtualized guests without a paravirtualized console.
+ console with Xen guests, or duplicates the primary serial port + for fully virtualized guests without a paravirtualized console.
source
The attributes available for the source element - vary according to the type attribute on the parent - tag. Allowed variations will be described below
+ vary according to the type attribute on the parent + tag. Allowed variations will be described below
target
The port number of the character device is specified via the - port attribute, numbered starting from 1. There is - usually only one console device, and 0, 1 or 2 serial devices - or parallel devices. + port attribute, numbered starting from 1. There is + usually only one console device, and 0, 1 or 2 serial devices + or parallel devices.
Domain logfile
@@ -1061,45 +1061,45 @@ qemu-kvm -net nic,model=? /dev/null
model
-

+

The required model attribute specifies what real - watchdog device is emulated. Valid values are specific to the - underlying hypervisor. -

-

- QEMU and KVM support: -

-
    -
  • 'i6300esb' — the recommended device, - emulating a PCI Intel 6300ESB
    • -
  • 'ib700' — emulating an ISA iBase IB700
    • -
+ watchdog device is emulated. Valid values are specific to the + underlying hypervisor. +

+

+ QEMU and KVM support: +

+
    +
  • 'i6300esb' — the recommended device, + emulating a PCI Intel 6300ESB
    • +
  • 'ib700' — emulating an ISA iBase IB700
    • +
action
-

+

The optional action attribute describes what - action to take when the watchdog expires. Valid values are - specific to the underlying hypervisor. -

-

- QEMU and KVM support: -

-
    -
  • 'reset' — default, forcefully reset the guest
    • -
  • 'shutdown' — gracefully shutdown the guest - (not recommended)
    • -
  • 'poweroff' — forcefully power off the guest
    • -
  • 'pause' — pause the guest
    • -
  • 'none' — do nothing
    • -
-

- Note that the 'shutdown' action requires that the guest - is responsive to ACPI signals. In the sort of situations - where the watchdog has expired, guests are usually unable - to respond to ACPI signals. Therefore using 'shutdown' - is not recommended. -

+ action to take when the watchdog expires. Valid values are + specific to the underlying hypervisor. +

+

+ QEMU and KVM support: +

+
    +
  • 'reset' — default, forcefully reset the guest
    • +
  • 'shutdown' — gracefully shutdown the guest + (not recommended)
    • +
  • 'poweroff' — forcefully power off the guest
    • +
  • 'pause' — pause the guest
    • +
  • 'none' — do nothing
    • +
+

+ Note that the 'shutdown' action requires that the guest + is responsive to ACPI signals. In the sort of situations + where the watchdog has expired, guests are usually unable + to respond to ACPI signals. Therefore using 'shutdown' + is not recommended. +

diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in index eb61f15894..b39f3534f8 100644 --- a/docs/formatnetwork.html.in +++ b/docs/formatnetwork.html.in @@ -35,17 +35,17 @@
name
The content of the name element provides - a short name for the virtual network. This name should - consist only of alpha-numeric characters and is required - to be unique within the scope of a single host. It is - used to form the filename for storing the persistent - configuration file. Since 0.3.0
+ a short name for the virtual network. This name should + consist only of alpha-numeric characters and is required + to be unique within the scope of a single host. It is + used to form the filename for storing the persistent + configuration file. Since 0.3.0
uuid
The content of the uuid element provides - a globally unique identifier for the virtual network. - The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. - If omitted when defining/creating a new network, a random - UUID is generated. Since 0.3.0
+ a globally unique identifier for the virtual network. + The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. + If omitted when defining/creating a new network, a random + UUID is generated. Since 0.3.0

Connectivity

@@ -58,32 +58,32 @@ 
         ...
         <bridge name="virbr0" />
-	<forward mode="nat" dev="eth0"/>
-	...
+ <forward mode="nat" dev="eth0"/> + ...
bridge
The name attribute on the bridge element - defines the name of a bridge device which will be used to construct - the virtual network. The virtual machines will be connected to this - bridge device allowing them to talk to each other. The bridge device - may also be connected to the LAN. It is recommended that bridge - device names started with the prefix vir, but the name - virbr0 is reserved for the "default" virtual network. - This element should always be provided when defining a new network. - Since 0.3.0 + defines the name of a bridge device which will be used to construct + the virtual network. The virtual machines will be connected to this + bridge device allowing them to talk to each other. The bridge device + may also be connected to the LAN. It is recommended that bridge + device names started with the prefix vir, but the name + virbr0 is reserved for the "default" virtual network. + This element should always be provided when defining a new network. + Since 0.3.0
forward
Inclusion of the forward element indicates that - the virtual network is to be connected to the physical LAN. If - no attributes are set, NAT forwarding will be used for connectivity. - Firewall rules will allow forwarding to any other network device whether - ethernet, wireless, dialup, or VPN. If the dev attribute - is set, the firewall rules will restrict forwarding to the named - device only. If the mode attribute is set to route - then the traffic will not have NAT applied. This presumes that the - local LAN router has suitable routing table entries to return traffic - to this host. Since 0.3.0; 'mode' attribute since + the virtual network is to be connected to the physical LAN. If + no attributes are set, NAT forwarding will be used for connectivity. + Firewall rules will allow forwarding to any other network device whether + ethernet, wireless, dialup, or VPN. If the dev attribute + is set, the firewall rules will restrict forwarding to the named + device only. If the mode attribute is set to route + then the traffic will not have NAT applied. This presumes that the + local LAN router has suitable routing table entries to return traffic + to this host. Since 0.3.0; 'mode' attribute since 0.4.2
@@ -96,50 +96,50 @@ 
         ...
-	<ip address="192.168.122.1" netmask="255.255.255.0">
-	  <dhcp>
-	    <range start="192.168.122.100" end="192.168.122.254" />
-	    <host mac="00:16:3e:77:e2:ed" name="foo.example.com" ip="192.168.122.10" />
-	    <host mac="00:16:3e:3e:a9:1a" name="bar.example.com" ip="192.168.122.11" />
-	  </dhcp>
-	</ip>
+        <ip address="192.168.122.1" netmask="255.255.255.0">
+          <dhcp>
+            <range start="192.168.122.100" end="192.168.122.254" />
+            <host mac="00:16:3e:77:e2:ed" name="foo.example.com" ip="192.168.122.10" />
+            <host mac="00:16:3e:3e:a9:1a" name="bar.example.com" ip="192.168.122.11" />
+          </dhcp>
+        </ip>
       </network>
ip
The address attribute defines an IPv4 address in - dotted-decimal format, that will be configured on the bridge - device associated with the virtual network. To the guests this - address will be their default route. The netmask - attribute defines the significant bits of the network address, - again specified in dotted-decimal format. Since 0.3.0 + dotted-decimal format, that will be configured on the bridge + device associated with the virtual network. To the guests this + address will be their default route. The netmask + attribute defines the significant bits of the network address, + again specified in dotted-decimal format. Since 0.3.0
tftp
Immediately within - the ip element there is an optional tftp - element. The presence of this element and of its attribute - root enables TFTP services. The attribute specifies - the path to the root directory served via TFTP. - Since 0.7.1 + the ip element there is an optional tftp + element. The presence of this element and of its attribute + root enables TFTP services. The attribute specifies + the path to the root directory served via TFTP. + Since 0.7.1
dhcp
Also within the ip element there is an - optional dhcp element. The presence of this element - enables DHCP services on the virtual network. It will further - contain one or more range elements. - Since 0.3.0 + optional dhcp element. The presence of this element + enables DHCP services on the virtual network. It will further + contain one or more range elements. + Since 0.3.0
range
The start and end attributes on the - range element specify the boundaries of a pool of - IPv4 addresses to be provided to DHCP clients. These two addresses - must lie within the scope of the network defined on the parent - ip element. Since 0.3.0 + range element specify the boundaries of a pool of + IPv4 addresses to be provided to DHCP clients. These two addresses + must lie within the scope of the network defined on the parent + ip element. Since 0.3.0
host
Within the dhcp element there may be zero or more - host elements; these specify hosts which will be given + host elements; these specify hosts which will be given names and predefined IP addresses by the built-in DHCP server. Any such element must specify the MAC address of the host to be assigned - a given name (via the mac attribute), the IP to be + a given name (via the mac attribute), the IP to be assigned to that host (via the ip attribute), and the - name to be given that host by the DHCP server (via the + name to be given that host by the DHCP server (via the name attribute). Since 0.4.5
bootp
The optional bootp element specifies BOOTP options to be provided by the DHCP server. @@ -170,14 +170,14 @@ 
       <network>
-	<name>default</name>
-	<bridge name="virbr0" />
-	<forward mode="nat"/>
-	<ip address="192.168.122.1" netmask="255.255.255.0">
-	  <dhcp>
-	    <range start="192.168.122.2" end="192.168.122.254" />
-	  </dhcp>
-	</ip>
+        <name>default</name>
+        <bridge name="virbr0" />
+        <forward mode="nat"/>
+        <ip address="192.168.122.1" netmask="255.255.255.0">
+          <dhcp>
+            <range start="192.168.122.2" end="192.168.122.254" />
+          </dhcp>
+        </ip>
       </network>

Routed network config

@@ -193,14 +193,14 @@ 
       <network>
-	<name>local</name>
-	<bridge name="virbr1" />
-	<forward mode="route" dev="eth1"/>
-	<ip address="192.168.122.1" netmask="255.255.255.0">
-	  <dhcp>
-	    <range start="192.168.122.2" end="192.168.122.254" />
-	  </dhcp>
-	</ip>
+        <name>local</name>
+        <bridge name="virbr1" />
+        <forward mode="route" dev="eth1"/>
+        <ip address="192.168.122.1" netmask="255.255.255.0">
+          <dhcp>
+            <range start="192.168.122.2" end="192.168.122.254" />
+          </dhcp>
+        </ip>
       </network>

Isolated network config

@@ -215,13 +215,13 @@ 
       <network>
-	<name>private</name>
-	<bridge name="virbr2" />
-	<ip address="192.168.152.1" netmask="255.255.255.0">
-	  <dhcp>
-	    <range start="192.168.152.2" end="192.168.152.254" />
-	  </dhcp>
-	</ip>
+        <name>private</name>
+        <bridge name="virbr2" />
+        <ip address="192.168.152.1" netmask="255.255.255.0">
+          <dhcp>
+            <range start="192.168.152.2" end="192.168.152.254" />
+          </dhcp>
+        </ip>
       </network>
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 72022cb643..63a1f2a853 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -37,10 +37,10 @@
usage
- Specifies what this secret is used for. A mandatory - type attribute specifies the usage category, currently - only volume is defined. Specific usage categories are - described below. + Specifies what this secret is used for. A mandatory + type attribute specifies the usage category, currently + only volume is defined. Specific usage categories are + described below.
diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in index 3ed88a2914..ccf5a91f0c 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -34,27 +34,27 @@
name
Providing a name for the pool which is unique to the host. - This is mandatory when defining a pool. Since 0.4.1
+ This is mandatory when defining a pool. Since 0.4.1
uuid
Providing an identifier for the pool which is globally unique. - This is optional when defining a pool, a UUID will be generated if - omitted. Since 0.4.1
+ This is optional when defining a pool, a UUID will be generated if + omitted. Since 0.4.1
allocation
Providing the total storage allocation for the pool. This may - be larger than the sum of the allocation of all volumes due to - metadata overhead. This value is in bytes. This is not applicable - when creating a pool. Since 0.4.1
+ be larger than the sum of the allocation of all volumes due to + metadata overhead. This value is in bytes. This is not applicable + when creating a pool. Since 0.4.1
capacity
Providing the total storage capacity for the pool. Due to - underlying device constraints it may not be possible to use the - full capacity for storage volumes. This value is in bytes. This - is not applicable when creating a pool. Since 0.4.1
+ underlying device constraints it may not be possible to use the + full capacity for storage volumes. This value is in bytes. This + is not applicable when creating a pool. Since 0.4.1
available
Providing the free space available for allocating new volumes - in the pool. Due to underlying device constraints it may not be - possible to allocate the entire free space to a single volume. - This value is in bytes. This is not applicable when creating a - pool. Since 0.4.1
+ in the pool. Due to underlying device constraints it may not be + possible to allocate the entire free space to a single volume. + This value is in bytes. This is not applicable when creating a + pool. Since 0.4.1

Source elements

@@ -71,38 +71,38 @@ <host name="iscsi.example.com"/> <device path="demo-target"/> </source> - ... + ...
device
Provides the source for pools backed by physical devices. - May be repeated multiple times depending on backend driver. Contains - a single attribute path which is the fully qualified - path to the block device node. Since 0.4.1
+ May be repeated multiple times depending on backend driver. Contains + a single attribute path which is the fully qualified + path to the block device node. Since 0.4.1
directory
Provides the source for pools backed by directories. May - only occur once. Contains a single attribute path - which is the fully qualified path to the block device node. - Since 0.4.1
+ only occur once. Contains a single attribute path + which is the fully qualified path to the block device node. + Since 0.4.1
host
Provides the source for pools backed by storage from a - remote server. Will be used in combination with a directory - or device element. Contains an attribute name - which is the hostname or IP address of the server. May optionally - contain a port attribute for the protocol specific - port number. Since 0.4.1
+ remote server. Will be used in combination with a directory + or device element. Contains an attribute name + which is the hostname or IP address of the server. May optionally + contain a port attribute for the protocol specific + port number. Since 0.4.1
name
Provides the source for pools backed by storage from a - named element (e.g., a logical volume group name). - remote server. Contains a string identifier. - Since 0.4.5
+ named element (e.g., a logical volume group name). + remote server. Contains a string identifier. + Since 0.4.5
format
Provides information about the format of the pool. This - contains a single attribute type whose value is - backend specific. This is typically used to indicate filesystem - type, or network filesystem type, or partition table type, or - LVM metadata type. All drivers are required to have a default - value for this, so it is optional. Since 0.4.1
+ contains a single attribute type whose value is + backend specific. This is typically used to indicate filesystem + type, or network filesystem type, or partition table type, or + LVM metadata type. All drivers are required to have a default + value for this, so it is optional. Since 0.4.1

Target elements

@@ -133,27 +133,27 @@
path
Provides the location at which the pool will be mapped into - the local filesystem namespace. For a filesystem/directory based - pool it will be the name of the directory in which volumes will - be created. For device based pools it will be the name of the directory in which - devices nodes exist. For the latter /dev/ may seem - like the logical choice, however, devices nodes there are not - guaranteed stable across reboots, since they are allocated on - demand. It is preferable to use a stable location such as one - of the /dev/disk/by-{path,id,uuid,label locations. - Since 0.4.1 + the local filesystem namespace. For a filesystem/directory based + pool it will be the name of the directory in which volumes will + be created. For device based pools it will be the name of the directory in which + devices nodes exist. For the latter /dev/ may seem + like the logical choice, however, devices nodes there are not + guaranteed stable across reboots, since they are allocated on + demand. It is preferable to use a stable location such as one + of the /dev/disk/by-{path,id,uuid,label locations. + Since 0.4.1
permissions
Provides information about the default permissions to use - when creating volumes. This is currently only useful for directory - or filesystem based pools, where the volumes allocated are simple - files. For pools where the volumes are device nodes, the hotplug - scripts determine permissions. It contains 4 child elements. The - mode element contains the octal permission set. The - owner element contains the numeric user ID. The group - element contains the numeric group ID. The label element - contains the MAC (eg SELinux) label string. - Since 0.4.1 + when creating volumes. This is currently only useful for directory + or filesystem based pools, where the volumes allocated are simple + files. For pools where the volumes are device nodes, the hotplug + scripts determine permissions. It contains 4 child elements. The + mode element contains the octal permission set. The + owner element contains the numeric user ID. The group + element contains the numeric group ID. The label element + contains the MAC (eg SELinux) label string. + Since 0.4.1
encryption
If present, specifies how the volume is encrypted. See @@ -192,41 +192,41 @@ 
       <volume>
-	<name>sparse.img</name>
-	<key>/var/lib/xen/images/sparse.img</key>
+        <name>sparse.img</name>
+        <key>/var/lib/xen/images/sparse.img</key>
         <allocation>0</allocation>
-	<capacity unit="T">1</capacity>
+        <capacity unit="T">1</capacity>
         ...
name
Providing a name for the volume which is unique to the pool. - This is mandatory when defining a volume. Since 0.4.1
+ This is mandatory when defining a volume. Since 0.4.1
key
Providing an identifier for the volume which is globally unique. - This is optional when defining a volume, a key will be generated if - omitted. Since 0.4.1
+ This is optional when defining a volume, a key will be generated if + omitted. Since 0.4.1
allocation
Providing the total storage allocation for the volume. This - may be smaller than the logical capacity if the volume is sparsely - allocated. It may also be larger than the logical capacity if the - volume has substantial metadata overhead. This value is in bytes. - If omitted when creating a volume, the volume will be fully - allocated at time of creation. If set to a value smaller than the - capacity, the pool has the option of deciding - to sparsely allocate a volume. It does not have to honour requests - for sparse allocation though. Since 0.4.1
+ may be smaller than the logical capacity if the volume is sparsely + allocated. It may also be larger than the logical capacity if the + volume has substantial metadata overhead. This value is in bytes. + If omitted when creating a volume, the volume will be fully + allocated at time of creation. If set to a value smaller than the + capacity, the pool has the option of deciding + to sparsely allocate a volume. It does not have to honour requests + for sparse allocation though. Since 0.4.1
capacity
Providing the logical capacity for the volume. This value is - in bytes. This is compulsory when creating a volume. - Since 0.4.1
+ in bytes. This is compulsory when creating a volume. + Since 0.4.1
source
Provides information about the underlying storage allocation - of the volume. This may not be available for some pool types. - Since 0.4.1
+ of the volume. This may not be available for some pool types. + Since 0.4.1
target
Provides information about the representation of the volume - on the local host. Since 0.4.1
+ on the local host. Since 0.4.1

Target elements

@@ -240,7 +240,7 @@ 
         ...
-	<target>
+        <target>
           <path>/var/lib/virt/images/sparse.img</path>
           <format type='qcow2'/>
           <permissions>
@@ -249,33 +249,33 @@
             <mode>0744</mode>
             <label>virt_image_t</label>
           </permissions>
-	</target>
+ </target>
path
Provides the location at which the volume can be accessed on - the local filesystem, as an absolute path. This is a readonly - attribute, so shouldn't be specified when creating a volume. - Since 0.4.1
+ the local filesystem, as an absolute path. This is a readonly + attribute, so shouldn't be specified when creating a volume. + Since 0.4.1
format
Provides information about the pool specific volume format. - For disk pools it will provide the partition type. For filesystem - or directory pools it will provide the file format type, eg cow, - qcow, vmdk, raw. If omitted when creating a volume, the pool's - default format will be used. The actual format is specified via - the type attribute. Consult the pool-specific docs for + For disk pools it will provide the partition type. For filesystem + or directory pools it will provide the file format type, eg cow, + qcow, vmdk, raw. If omitted when creating a volume, the pool's + default format will be used. The actual format is specified via + the type attribute. Consult the pool-specific docs for the list of valid values. Since 0.4.1
permissions
Provides information about the default permissions to use - when creating volumes. This is currently only useful for directory - or filesystem based pools, where the volumes allocated are simple - files. For pools where the volumes are device nodes, the hotplug - scripts determine permissions. It contains 4 child elements. The - mode element contains the octal permission set. The - owner element contains the numeric user ID. The group - element contains the numeric group ID. The label element - contains the MAC (eg SELinux) label string. - Since 0.4.1 + when creating volumes. This is currently only useful for directory + or filesystem based pools, where the volumes allocated are simple + files. For pools where the volumes are device nodes, the hotplug + scripts determine permissions. It contains 4 child elements. The + mode element contains the octal permission set. The + owner element contains the numeric user ID. The group + element contains the numeric group ID. The label element + contains the MAC (eg SELinux) label string. + Since 0.4.1
@@ -305,25 +305,25 @@
path
Provides the location at which the backing store can be accessed on - the local filesystem, as an absolute path. If omitted, there is no + the local filesystem, as an absolute path. If omitted, there is no backing store for this volume. - Since 0.6.0
+ Since 0.6.0
format
Provides information about the pool specific backing store format. - For disk pools it will provide the partition type. For filesystem - or directory pools it will provide the file format type, eg cow, - qcow, vmdk, raw. Consult the pool-specific docs for the list of valid + For disk pools it will provide the partition type. For filesystem + or directory pools it will provide the file format type, eg cow, + qcow, vmdk, raw. Consult the pool-specific docs for the list of valid values. Most file formats require a backing store of the same format, however, the qcow2 format allows a different backing store format. Since 0.6.0
permissions
Provides information about the permissions of the backing file. It contains 4 child elements. The - mode element contains the octal permission set. The - owner element contains the numeric user ID. The group - element contains the numeric group ID. The label element - contains the MAC (eg SELinux) label string. - Since 0.6.0 + mode element contains the octal permission set. The + owner element contains the numeric user ID. The group + element contains the numeric group ID. The label element + contains the MAC (eg SELinux) label string. + Since 0.6.0
@@ -362,10 +362,10 @@ 
       <volume>
-	<name>sparse.img</name>
-	<allocation>0</allocation>
-	<capacity unit="T">1</capacity>
-	<target>
+        <name>sparse.img</name>
+        <allocation>0</allocation>
+        <capacity unit="T">1</capacity>
+        <target>
           <path>/var/lib/virt/images/sparse.img</path>
           <permissions>
             <owner>0744</owner>
@@ -373,7 +373,7 @@
             <mode>0744</mode>
             <label>virt_image_t</label>
           </permissions>
-	</target>
+        </target>
       </volume>
diff --git a/docs/hacking.html.in b/docs/hacking.html.in index bc2f8f0a40..94b7238e76 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -8,50 +8,50 @@
  1. Discuss any large changes on the mailing list first. Post patches - early and listen to feedback.
    2. + early and listen to feedback.

  2. Post patches in unified diff format. A command similar to this - should work:

    - 
    +          should work:
    
+        
       diff -urp libvirt.orig/ libvirt.modified/ > libvirt-myfeature.patch
 
    
-	
    
-	  or:
-	
    
-	
    +        
    
+          or:
+        
    
+        
       cvs diff -up > libvirt-myfeature.patch
  3. Split large changes into a series of smaller patches, self-contained - if possible, with an explanation of each patch and an explanation of how - the sequence of patches fits together.
    4. + if possible, with an explanation of each patch and an explanation of how + the sequence of patches fits together.
  4. Make sure your patches apply against libvirt CVS. Developers - only follow CVS and don't care much about released versions.
    5. + only follow CVS and don't care much about released versions.

  5. Run the automated tests on your code before submitting any changes. - In particular, configure with compile warnings set to -Werror:

    - 
    +          In particular, configure with compile warnings set to -Werror:
    
+        
       ./configure --enable-compile-warnings=error
 
    
-	
    
-	  and run the tests:
-	
    
-	
    +        
    
+          and run the tests:
+        
    
+        
       make check
   make syntax-check
   make -C tests valgrind
 
    
-	
    
-	  The latter test checks for memory leaks.
-	
    
+        
    
+          The latter test checks for memory leaks.
+        
    
 
       
  6. Update tests and/or documentation, particularly if you are adding
-	a new feature or changing the output of a program.
    7. 
+        a new feature or changing the output of a program.

There is more on this subject, including lots of links to background reading on the subject, on - Richard Jones' guide to working with open source projects + Richard Jones' guide to working with open source projects

@@ -77,8 +77,8 @@ (setq c-indent-level 4) (setq c-basic-offset 4)) (add-hook 'c-mode-hook - '(lambda () (if (string-match "/libvirt" (buffer-file-name)) - (libvirt-c-mode)))) + '(lambda () (if (string-match "/libvirt" (buffer-file-name)) + (libvirt-c-mode))))

Code formatting (especially for new code)

@@ -118,30 +118,30 @@ @@ -250,14 +250,14 @@