Commit 53e05ccf authored by Paul John King's avatar Paul John King

Redocumented script and used it to build README --

parent 97d60e3b
`kvm_tool` is a Bourne shell script that provides several commands to create
and destroy KVM resources. The only external command the script uses is
`virsh`.
Pool Commands
-------------
The command call
kvm_tool create pool «name» «path»
creates a directory-type storage pool with the name `«name»` under the path
`«path»`.
The command call
kvm_tool destroy pool «name»
destroys the storage pool with the name `«name»`.
Volume Commands
---------------
The command call
kvm_tool create volume «name» «pool» «path»
creates a qcow2 storage volume with the name `«name»` in the storage pool
`«pool»` with the qcow2 file-system image at the path `«path»` as its backing
storage volume.
The command call
kvm_tool destroy volume «name» «pool»
destroys the storage volume with the name `«name»` in the storage pool
`«pool»`.
Domain Commands
---------------
The command call
kvm_tool create domain [-m «mac_address»] «name» «cpu_count» «ram» «path» «bridge»
creates a KVM domain with the name `«name»`, `«cpu_count»` CPUs, `«ram»` MiB of
RAM, the file-system image at the path `«path»`, and a connection to the bridge
device `«bridge»`. If the `-m` option is used then the domain has the MAC
address `«mac_address»`.
The command call
kvm_tool examine domain «name»
outputs the CPU count, the RAM, the RAM units, a path to the file-system image,
the bridge device and the MAC address of the KVM domain with the name `«name»`
as Bourne-shell variable assignments (suitable for shell evaluation) and
returns
* 0 if the domain exists, and
* 1 otherwise.
The command call
kvm_tool verify domain [-m «mac_address»] «name» «cpu_count» «ram» «path» «bridge»
returns
* 0 if a KVM domain with the name `«name»`, `«cpu_count»` CPUs, `«ram»` MiB of
RAM, the file-system image at the path `«path»`, and a connection to the
bridge device `«bridge»` (with MAC address `«mac_address»` if the `-m` option
is used) exists,
* 1 if a KVM domain with the name `«name»` but other parameters exists, and
* 2 if no KVM domain with the name `«name»` exists.
The command call
kvm_tool destroy domain «name»
destroys the domain with the name `«name»`, as well as any managed save image
and snapshots. If the domain is running then it continues to run but will be
destroyed when stopped.
Machine Commands
----------------
The command call
kvm_tool create machine [-i «ipv4_address»] «name» «cpu_count» «ram» «path» «bridge»
creates a KVM domain with the name `«name»`, `«cpu_count»` CPUs, `«ram»` MiB of
RAM, a qcow2 storage volume with the name `«name»` in the `default` storage
pool with the qcow2 file-system image at the path `«path»` as its backing
storage volume, and a connection to the bridge device `«bridge»`. If the `-i`
option is used then the domain has the MAC address output by `kvm_tool get mac
address «ipv4_address»` - run `kvm_tool help utility` for details of this MAC
address.
The command call
kvm_tool examine machine «name»
outputs the CPU count, the RAM, the RAM units, a path to the file-system image,
a path to the backing file-sytem image, the bridge device and the MAC address
of the KVM domain with the name `«name»` as Bourne-shell variable assignments
(suitable for shell evaluation) and returns
* 0 if the domain exists, and
* 1 otherwise.
The command call
kvm_tool verify machine [-i «ipv4_address»] «name» «cpu_count» «ram» «path» «bridge»
returns
* 0 if a KVM domain with the name `«name»`, `«cpu_count»` CPUs, `«ram»` MiB of
RAM, a qcow2 storage volume with the name `«name»` in the `default` storage
pool with the qcow2 file-system image at the path `«path»` as its backing
storage volume, and a connection to the bridge device `«bridge»` (with the
MAC address output by `kvm_tool get mac address «ipv4_address»` if the `-i`
option is used - run `kvm_tool help utility` for details of this MAC address)
exists,
* 1 is a KVM domain with name `«name»` but other parameters exists, and
* 2 if no KVM domain with name `«name»` exists.
The command call
kvm_tool destroy machine «name»
destroys the domain with name `«name»` and the storage volume with the name
`«name»` in the `default` storage pool.
Utility Commands
----------------
The command call
kvm_tool get image path «volume» «pool»
outputs a path to the file-system image of the storage volume with the name
`«name»` in the storage pool `«pool»`.
The command call
kvm_tool get mac address «ipv4_address»
outputs a locally administered unicast MAC address that encodes the IPv4
address `«ipv4_address»` in its last four octets. If `«ipv4_address»` is
w.x.y.z
then the MAC address is
e2:9f:W:X:Y:Z
where
e2:9f [MAC octets]
┌──────────────┐
= e 2 9 f [hexadecimal]
┌──┐┌──┐┌──┐┌──┐
= 1110001010011111 [binary]
└────┘ └──────┘
= 56 lu 159 [decimal]
└────┘ └──────┘
= LVI CLIX [Roman numerals]
and
* `W` is the hexadecimal representation of `w`,
* `X` is the hexadecimal representation of `x`,
* `Y` is the hexadecimal representation of `y`, and
* `Z` is the hexadecimal representation of `z`.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment