The virsh(1) man page wasn't saying anything about the 'migrateuri'
parameter other than it can be usually omitted. A patched version of
docs/migrate.html.in is taken in this patch to fix that up in the man
page.
The man page states that with --config the next boot is affected. This
can be understood as if _only_ the next boot was affected. This isn't
true if the machine is running.
This patch adds the full --live, --config, --current infrastructure and
tweaks stuff to correctly support the obsolete --persistent flag.
Note that this patch changes the the behavior of the --config flag to match the
use of this flag in rest of libvirt. This flag was mistakenly renamed from
--persistent that originaly had different semantics.
VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST to filter the FC HBA,
and VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS to filter the FC HBA
which supports vport.
The docs assumed the command works always for QEMU and other
hypervisors. As this is done using the balloon mechainism live increase
of the maximum memory limit isn't supported. Fix the docs to mention
this limitation.
Clarify that net-create deals with a transient virtual
network whereas net-define defines a persistent virtual
network definition and will create the network (xml)
definition file.
Clarify that net-destroy works with both transient and
persistent virtual networks.
Signed-off-by: Gene Czarcinski <gene@czarc.net>
Only nodedev-destroy and nodedev-dumpxml can benifit from the
new API, other commands like nodedev-detach only works for
PCI devices, WWN makes no sense for them.
When a disk-only snapshot is requested the domain is treated as if it
was offline. This forbids to mix memory checkpoints with the DISK_ONLY
flag.
This patch improves the error message and mentions the restriction in
the virsh man page.
Add a 'lxc-enter-namespace' command which accepts a domain name
and then a command + args to run, attached to the container
eg
virsh -c lxc:/// lxc-enter-namespace demo -- /bin/ps -auxf
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Offline migration transfers inactive definition of a domain (which may
or may not be active). After successful completion, the domain remains
in its current state on source host and is defined but inactive on
destination host. It's a bit more clever than virDomainGetXMLDesc() on
source host followed by virDomainDefineXML() on destination host, as
offline migration will run pre-migration hook to update the domain XML
on destination host. Currently, copying non-shared storage is not
supported during offline migration.
Offline migration can be requested with a new migration flag called
VIR_MIGRATE_OFFLINE (which has to be combined with
VIR_MIGRATE_PERSIST_DEST flag).
As we enable more modes of snapshot creation, it becomes more important
to be able to quickly filter based on snapshot properties. This patch
introduces new filter flags; subsequent patches will introduce virsh
back-compat filtering, as well as actual libvirt filtering.
* include/libvirt/libvirt.h.in (virDomainSnapshotListFlags): Add
five new flags in two new groups.
* src/libvirt.c (virDomainSnapshotNum, virDomainSnapshotListNames)
(virDomainListAllSnapshots, virDomainSnapshotNumChildren)
(virDomainSnapshotListChildrenNames)
(virDomainSnapshotListAllChildren): Document them.
* src/conf/snapshot_conf.h (VIR_DOMAIN_SNAPSHOT_FILTERS_STATUS)
(VIR_DOMAIN_SNAPSHOT_FILTERS_LOCATION): Add new convenience filter
collection macros.
* tools/virsh-snapshot.c (cmdSnapshotList): Add 5 new flags.
* tools/virsh.pod (snapshot-list): Document them.
This reverts commits 5f63a5cb42
and ff86b0c97b. After much list
discussion, consensus was that libvirt aliases should be reserved
to correct typos, otherwise it risks confusion. Rather, we
should implement a way for users to provide their own aliases
as part of their virsh configuration preferences.
External checkpoints could be created with snapshot-create, but
without libvirt supplying a default name for the memory file,
it is essential to add a new argument to snapshot-create-as to
allow the user to choose the memory file name. This adds the
option --memspec [file=]name[,snapshot=type], where type can
be none, internal, or external. For an example,
virsh snapshot-create-as $dom --memspec /path/to/file
is the shortest possible command line for creating an external
checkpoint, named after the current timestamp.
* tools/virsh-snapshot.c (vshParseSnapshotMemspec): New function.
(cmdSnapshotCreateAs): Use it.
* tests/virsh-optparse (test_url): Test it.
* tools/virsh.pod (snapshot-create-as): Document it.
Make it clear that the alternate terms have no difference except
for length of time they were supported.
* tools/virsh.pod (start, shutdown, reboot): More documentation.
https://bugzilla.redhat.com/show_bug.cgi?id=873344 suggested that
the grouping 'boot', 'shutdown', 'reboot'; as well as the grouping
'start', 'stop', 'restart'; might be easier to remember than the
current mix of 'start', 'shutdown', 'reboot'.
Also, touch up the wording of 'reboot' to be more accurate.
* tools/virsh-domain.c (domManagementCmds): Add other command names.
* tools/virsh.pod (start, shutdown, reboot): Document the aliases.
The default behavior while creating external checkpoints is to pause the
guest while the memory state is captured. We want the users to sacrifice
space saving for creating the memory save image while the guest is live
to minimize downtime.
This patch adds a flag that causes the guest not to be paused before
taking the snapshot.
*include/libvirt/libvirt.h.in:
- add new paused reason: VIR_DOMAIN_PAUSED_SNAPSHOT
- add new flag for taking snapshot: VIR_DOMAIN_SNAPSHOT_CREATE_LIVE
*tools/virsh-domain-monitor.c:
- add string representation for VIR_DOMAIN_PAUSED_SNAPSHOT
*tools/virsh-snapshot.c:
- add support for VIR_DOMAIN_SNAPSHOT_CREATE_LIVE
*tools/virsh.pod:
- add docs for --live option added to use
VIR_DOMAIN_SNAPSHOT_CREATE_LIVE flag
We always expose individual bits from flags as separate options rather
than exposing a raw flags options. Since virNodeSuspendForDuration does
not currently support any flags, the only way of using this --flags
options that would not fail is "--flags 0", which is equivalent to
omitting the option. Thus it is highly unlikely anyone would actually be
using it and removing it should be safe.
https://bugzilla.redhat.com/show_bug.cgi?id=869100 mentioned some
confusion about 'virsh snapshot-list' errors. Clean up a
misleading error message, and add some documentation.
* tools/virsh-snapshot.c (cmdSnapshotList): Mention --current
rather than --from when appropriate.
* tools/virsh.pod (snapshot-list): Mention that the named starting
point is NOT part of the list except under --tree.
Upstream kernel introduced new sysfs knob "merge_across_nodes" to
specify if pages from different numa nodes can be merged. When set
to 0, only pages which physically reside in the memory area of
same NUMA node can be merged. When set to 1, pages from all nodes
can be merged.
This patch supports the tuning by adding new param field
"shm_merge_across_nodes".
Using VIR_DOMAIN_XML_MIGRATABLE flag, one can request domain's XML
configuration that is suitable for migration or save/restore. Such XML
may contain extra run-time stuff internal to libvirt and some default
configuration may be removed for better compatibility of the XML with
older libvirt releases.
This flag may serve as an easy way to get the XML that can be passed
(after desired modifications) to APIs that accept custom XMLs, such as
virDomainMigrate{,ToURI}2 or virDomainSaveFlags.
I was using qemu-monitor-command during development, and found it quite
hard to use. Compare the results of this patch on ease of reading:
$ virsh qemu-monitor-command dom '{"execute":"query-version"}'
{"return":{"qemu":{"micro":1,"minor":12,"major":0},"package":"(qemu-kvm-0.12.1.2)"},"id":"libvirt-7683"}
$ virsh qemu-monitor-command --pretty dom '{"execute":"query-version"}'
{
"return": {
"qemu": {
"micro": 1,
"minor": 12,
"major": 0
},
"package": "(qemu-kvm-0.12.1.2)"
},
"id": "libvirt-7674"
}
* tools/virsh-host.c (cmdQemuMonitorCommand): New option.
* tools/virsh.pod (qemu-monitor-command): Document it.
This command uses the new virNetworkUpdate() API to modify an existing
network definition, and optionally have those modifications take
effect immediately without restarting the network.
An example usage:
virsh net-update mynet add-last ip-dhcp-host \
"<host mac='00:11:22:33:44:55' ip='192.168.122.45'/>" \
--live --config
If you like, you can instead put the xml into a file, and call like
this:
virsh net-update mynet add ip-dhcp-host /tmp/myxml.xml
--live --config
virsh will autodetect whether the argument is itself an xml element,
or if it's a file, by looking at the first character - the first
character of an xml element is always "<", and the first character of
a file is almost always *not* "<" (in the rare case that it is, the
user could specify "./<filename...").
A --parent-index option is also available (to give the index within a
list of parent objects, e.g. the index of the parent <ip> element when
updating ip-dhcp-host elements), but is optional and at least for now
will probably be used rarely.
--live, --config, and --current options - if you specify --live, only
the live state of the network will be updated. If you also specify
--config, then the persistent configuration will also be updated;
these two commands can be given separately, or both together. If you
don't specify either (you can optionally specify "--current" for the
same effect), then the "current" config will be updated (i.e. if the
network is active, then only its live config is affected, but if the
network is inactive, only the persistent config is affected).
The new command 'virsh blockcommit $dom $disk' requests the start
of an asynchronous commit operation across the entire chain of
$disk. Further arguments can fine-tune which portion of the
chain is committed. Existing 'virsh blockjob' commands can then
track the status, change the bandwidth, or abort the commit job.
With a bit more on the command line, 'virsh blockcommit $dom $disk
--wait --verbose' can be used for blocking behavior, with visual
feedback on the overall status, and can be canceled with Ctrl-C.
The overall design, including the wait loop logic, borrows heavily
from the existing blockpull command.
* tools/virsh-domain.c (cmdBlockCommit): New function.
* tools/virsh.pod (blockcommit): Document it.
New command node-memory-tune to get/set the node memory parameters,
only two parameters are allowed to set (pages_to_scan, and sleep_millisecs,
see documents in this patch for more details).
Example of node-memory-tune's output:
Shared memory:
pages_to_scan 100
sleep_millisecs 20
pages_shared 0
pages_sharing 0
pages_unshared 0
pages_volatile 0
full_scans 0
This introduces four new options for secret-list, to filter the
returned secrets by whether it's ephemeral or not, and/or by
whether it's private or not.
* tools/virsh-secret.c: (New helper vshSecretSorter,
vshSecretListFree, and vshCollectSecretList; Use the new
API for secret-list; error out if flags are specified,
because there is no way to filter the results when using
old APIs (no APIs to get the properties (ephemeral, private)
of a secret yet).
* tools/virsh.pod: Document the 4 new options.
tools/virsh-nodedev.c:
* vshNodeDeviceSorter to sort node devices by name
* vshNodeDeviceListFree to free the node device objects list.
* vshNodeDeviceListCollect to collect the node device objects, trying
to use new API first, fall back to older APIs if it's not supported.
* Change option --cap to accept multiple capability types.
tools/virsh.pod
* Update document for --cap
tools/virsh-network.c:
* vshNetworkSorter to sort networks by name
* vshNetworkListFree to free the network objects list.
* vshNetworkListCollect to collect the network objects, trying
to use new API first, fall back to older APIs if it's not supported.
* New options --persistent, --transient, --autostart, --no-autostart,
for net-list, and new field 'Persistent' for its output.
tools/virsh.pod:
* Add documents for the new options.
tools/virsh-pool.c:
* vshStoragePoolSorter to sort the pool list by pool name.
* struct vshStoragePoolList to present the pool list, pool info
is collected by list->poolinfo if 'details' is specified by
user.
* vshStoragePoolListFree to free the pool list
* vshStoragePoolListCollect to collect the pool list, new API
virStorageListAllPools is tried first, if it's not supported,
fall back to older APIs.
* New options --persistent, --transient, --autostart, --no-autostart
and --type for pool-list. --persistent or --transient is to filter
the returned pool list by whether the pool is persistent or not.
--autostart or --no-autostart is to filter the returned pool list
by whether the pool is autostarting or not. --type is to filter
the pools by pool types. E.g.
% virsh pool-list --all --persistent --type dir,disk
tools/virsh.pod:
* Add documentations for the new options.
The storage pool's management doesn't relate with a domain, it
probably was an intention, but not achieved yet. And the fact
is only active pools are listed by default.
The bandwidth units for blockpull and blockcopy are in Megabytes per
Second, not Megabits per Second.
Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
This patch adds two macros: VIR_DOMAIN_SCHEDULER_EMULATOR_PERIOD,
VIR_DOMAIN_SCHEDULER_EMULATOR_QUOTA for controlling cpu bandwidth
for emulator activities not tied to vcpus
Change the permissible minimum value of nodesuspend duration time
to 60 seconds. If option is less than the value, reports error.
Update virsh help and manpage the infomation.
When --direct is used when migrating a domain running on a hypervisor
that does not support direct migration (such as QEMU), the caller would
get the following error message:
this function is not supported by the connection driver:
virDomainMigrateToURI2
which is a complete nonsense since qemu driver implements
virDomainMigrateToURI2. This patch would emit a more sensible error in
this case:
Requested operation is not valid: direct migration is not supported
by the connection driver
v2:
- Refactored to use virBuffer
- Refactored to use virXPath wrappers
- Added support for tls-port and password for SPICE
- Added optional flag to disable SPICE password to the URI
- Added support for RDP
- Fixed code reviews
Add a new 'domdisplay' command that provides a URI for VNC, SPICE and
RDP connections. Presently the 'vncdisplay' command provides you with
the port info that QEMU is listening on but there is no counterpart for
SPICE and RDP. Additionally this provides you with the bind address as
specified in the XML, which the existing 'vncdisplay' lacks. For SPICE
connections it supports secure and unsecure channels and optionally
providing the password for the SPICE channel.
Signed-off-by: Doug Goldstein <cardoe@cardoe.com>
Storage is one of the last domains in libvirt where we don't fully
utilize inactive and live XML. Okay, it might be because we don't
have support for that. So implement such support. However, we need
to fallback when talking to old daemon which doesn't support this
new flag called VIR_STORAGE_XML_INACTIVE.
This patch makes use of the newly added api virConnectListAllDomains()
to list domains in virsh.
Virsh now represents lists of domains using an internal structure
vshDomainList. This structure contains the virDomainPtr list as provided
by virConnectListAllDomains() and the count of domains in the list.
For backwards compatibility, the function vshDomainListCollect was added
that tries to enumerate the domains using the new API and if the API is
not supported falls back to the older approach with the two list
functions. The helper function also simulates filtering by all
currently supported flags added with virConnectListAllDomains().
This patch also cleans up the "list" command handler to use the new
helpers and adds new command line flags to make use of filtering.
Previously, to get the name of all snapshots with children, it was
necessary to get the name of all snapshots and then remove the
name of leaf snapshots. This is racy, and somewhat inefficient
compared to planned API additions. We can emulate --no-metadata on
0.9.5-0.9.12, but for now, there is no emulation of --no-leaves.
* tools/virsh.c (cmdSnapshotList): Add new options --no-leaves and
--no-metadata.
(vshSnapshotList): Emulate where possible.
* tools/virsh.pod (snapshot-list): Document them.
as we are missing:
attach-disk: --type can accept 'lun' too, not just cdrom or floppy.
attach-disk: --target specify logical device name, not path
attach-interface: --target silently drops strings with vnet* prefix
commit 52d064f42d added
VIR_NETWORK_XML_INACTIVE in order to allow suppressing the
auto-generated list of VFs in network definitions, and a --inactive
flag to virsh net-dumpxml to take advantage of the flag. However, it
missed out on two opportunities:
1) Use INACTIVE to get the current config of the network as it
exists on disk, rather than the currently active config.
2) Add INACTIVE to the flags used for the virsh net-edit command, so
that it won't include the forward-pool interfaces that were
autogenerated, and so that a re-edit of the network prior to
restarting it will show any other edits made since the last restart
of the network. (prior to this patch, if you edited a network a 2nd
time without restarting, all of the previous edits would magically
disappear).
In order to fit with the new #define-based generic edit function in
virsh.c, a new function vshNetworkGetXMLDesc() was added. This
function first tries to call virNetworkGetXMLDesc with the INACTIVE
flag added, then retries without if the first attempt fails (in the
manner expected when the server doesn't support it).
Expose the recent API additions in virsh. Borrows ideas from 'dominfo'
for the general type of information to display.
Output looks like:
$ tools/virsh snapshot-info fedora-local tmp
Name: tmp
Domain: fedora-local
Current: no
State: disk-snapshot
Parent: -
Children: 1
Descendants: 2
Metadata: yes
possibly with fewer lines when talking to older servers.
* tools/virsh.c (cmdSnapshotInfo): New command.
* tools/virsh.pod (snapshot-info): Document it.
Rather than further overloading 'blockpull', I decided to create a
new virsh command to expose the new flags of virDomainBlockRebase.
Blocking until the command completes naturally is pointless, since
the block copy job is intended to run indefinitely. Instead, I
made the command support three --wait modes: by default, it runs until
mirroring is started; with --pivot, it pivots as soon as mirroring
is started; and with --finish, it aborts (for a clean copy) as
soon as mirroring is started.
* tools/virsh.c (VSH_CMD_BLOCK_JOB_COPY): New mode.
(blockJobImpl): Support new flags.
(cmdBlockCopy): New command.
(cmdBlockJob): Support new job info, new abort flag.
* tools/virsh.pod (blockcopy, blockjob): Document the new command
and flags.
I'm tired of shell-scripting to wait for completion of a block pull,
when virsh can be taught to do the same. I couldn't quite reuse
vshWatchJob, as this is not a case of a long-running command where
a second thread must be used to probe job status (at least, not unless
I make virsh start doing blocking waits for an event to fire), but it
served as inspiration for my simpler single-threaded loop. There is
up to a half-second delay between sending SIGINT and the job being
aborted, but I didn't think it worth the complexity of a second thread
and use of poll() just to minimize that delay.
* tools/virsh.c (cmdBlockPull): Add new options to wait for
completion.
(blockJobImpl): Add argument.
(cmdBlockJob): Adjust caller.
* tools/virsh.pod (blockjob): Document new mode.
Block job cancellation can take a while. Now that upstream qemu 1.1
has asynchronous block cancellation, we want to expose that to the user.
Therefore, the following updates are made to the virDomainBlockJob API:
A new block job event type VIR_DOMAIN_BLOCK_JOB_CANCELED is managed by
libvirt. Regardless of the flags used with virDomainBlockJobAbort, this
event will be raised: 1. when using synchronous block_job_cancel (the
event will be synthesized by libvirt), and 2. whenever it is received
from qemu (via asynchronous block-job-cancel). Note that the event
may be detected by libvirt even before the virDomainBlockJobAbort
completes (always true when it is synthesized, but also possible if
cancellation was fast).
A new extension flag VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC is added to the
virDomainBlockJobAbort API. When enabled, this function will allow
(but not require) asynchronous operation (ie, it returns as soon as
possible, which might be before the job has actually been canceled).
When the API is used in this mode, it is the responsibility of the
caller to wait for a VIR_DOMAIN_BLOCK_JOB_CANCELED event or poll via
the virDomainGetBlockJobInfo API to check the cancellation status.
This patch also exposes the new flag through virsh, and makes virsh
slightly easier to use (--async implies --abort, and lack of any options
implies --info), although it leaves the qemu implementation for later
patches.
Signed-off-by: Adam Litke <agl@us.ibm.com>
Cc: Stefan Hajnoczi <stefanha@gmail.com>
Signed-off-by: Eric Blake <eblake@redhat.com>
The documentation for the flag doesn't clearly state that the flag only
enhances the output and the user needs to specify other flags to list
inactive domains, that are enhanced by this flag.
Currently, we put no strains on escape sequence possibly leaving users
with console that cannot be terminated. However, not all ASCII
characters can be used as escape sequence. Only those falling in
@ - _ can be; implement and document this constraint.
Commit d42a2ff forgot to touch up virsh documentation, and commit
4e9953a mis-spelled the option name.
* tools/virsh.pod (snapshot-create, snapshot-create-as): Fix typo
and match recent change in flag meaning.
Right now, it is appallingly easy to cause qemu disk snapshots
to alter a domain then fail; for example, by requesting a two-disk
snapshot where the second disk name resides on read-only storage.
In this failure scenario, libvirt reports failure, but modifies
the live domain XML in-place to record that the first disk snapshot
was taken; and places a difficult burden on the management app
to grab the XML and reparse it to see which disks, if any, were
altered by the partial snapshot.
This patch adds a new flag where implementations can request that
the hypervisor make snapshots atomically; either no changes to
XML occur, or all disks were altered as a group. If you request
the flag, you either get outright failure up front, or you take
advantage of hypervisor abilities to make an atomic snapshot. Of
course, drivers should prefer the atomic means even without the
flag explicitly requested.
There's no way to make snapshots 100% bulletproof - even if the
hypervisor does it perfectly atomic, we could run out of memory
during the followup tasks of updating our in-memory XML, and report
a failure. However, these sorts of catastrophic failures are rare
and unlikely, and it is still nicer to know that either all
snapshots happened or none of them, as that is an easier state to
recover from.
* include/libvirt/libvirt.h.in
(VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC): New flag.
* src/libvirt.c (virDomainSnapshotCreateXML): Document it.
* tools/virsh.c (cmdSnapshotCreate, cmdSnapshotCreateAs): Expose it.
* tools/virsh.pod (snapshot-create, snapshot-create-as): Document
it.
This introduces a new domain state pmsuspended to represent
the domain which has been suspended by guest power management,
e.g. (entered itno s3 state). Because a "running" state could
be confused in this case, one will see the guest is paused
actually while playing. And state "paused" is for the domain
which was paused by virDomainSuspend.
virsh.pod had several instances in which it referred to "the
documentation" which was a little puzzling to me since it is
documentation. Reading the document from end to end makes it clear
that it means a specific URI which was noted previously in the text,
but I had never noticed those URIs in several years of referring to
the man page. This patch adds those URIs to several additional places
in the text.
Currently if the URI passed to virConnectOpen* is NULL, then we
- Look for LIBVIRT_DEFAULT_URI env var
- Probe for drivers
This changes it so that
- Look for LIBVIRT_DEFAULT_URI env var
- Look for 'uri_default' in $HOME/.libvirt/libvirt.conf
- Probe for drivers
Since VIR_DOMAIN_AFFECT_{LIVE,CONFIG,CURRENT} was created,
all new virsh commands use "--config" to represents the
persistent changing. This patch add "--config" option
for the old commands which still use "--persistent",
and "--persistent" is now alias of "--config".
tools/virsh.c: (use "--config", and "--persistent" is
alias of "--config" now).
cmdDomIfSetLink, cmdDomIfGetLink, cmdAttachDevice,
cmdDetachDevice, cmdUpdateDevice, cmdAttachInterface,
cmdDetachInterface, cmdAttachDisk, cmdDetachDisk
toos/virsh.pod: Update docs of the changed commands, and
add some missed docs for "--config" (detach-interface,
detach-disk, and detach-device).
The last vestige of the inaccurate 'kilobytes' when we meant 1024 is
now gone. And virsh is now useful for setting memory in units other
than KiB.
* tools/virsh.c (cmdSetmem, cmdSetmaxmem): Use new helper routine,
allow passing bogus arguments on to hypervisor to test driver
sanity checking, and fix leak on parse error.
(vshMemtuneGetSize): New helper.
(cmdMemtune): Use it.
* tools/virsh.pod (setmem, setmaxmem, memtune): Document this.
Now can now do:
virsh vol-resize $vol 10M
virsh blockresize $dom $vol 10M
to get both interfaces to resize to 10MiB. The remaining wart
is that vol-resize defaults to bytes, but blockresize defaults
to KiB, but we can't break existing scripts; oh well, it's no
worse than the same wart of the underlying virDomainBlockResize.
The API for virStorageVolResize states that capacity must always
be positive, and that the presence of shrink and delta flags is
what implies a negative change.
* tools/virsh.c (vshCommandOptScaledInt): New function.
(cmdVolResize): Don't pass negative size.
(cmdVolSize): Rename...
(vshVolSize): ...and use new helper routine.
(cmdBlockResize): Use new helper routine, and support new bytes
flag.
* tools/virsh.pod (NOTES): Document suffixes.
(blockresize, vol-create-as, vol-resize): Point to notes.
Just because our public API has a typo doesn't mean that virsh
has to keep the typo.
* tools/virsh.c (VSH_CMD_FLAG_ALIAS): New flag.
(nodedevCmds): Use it.
(cmdHelp): Omit alias commands.
(cmdNodeDeviceDettach): Rename...
(cmdNodeDeviceDetach): ...to this.
* tools/virsh.pod (nodedev-detach): Document it.
Command line interfaces should use dash, not underscore, as many
keyboard layouts allow that to be typed with fewer shift key presses.
Also, the US spelling of --tunneled gets more google hits than the
UK spelling of --tunnelled.
* tools/virsh.c (opts_migrate): Allow US variant.
(opts_blkdeviotune): Prefer - over _.
* tools/virsh.pod (blkdeviotune): Fix spelling.
In the past, we have created some virsh options with less-than-stellar
names. For back-compat reasons, those names must continue to parse,
but we don't want to document them in help output. This introduces
a new option type, an alias, which points to a canonical option name
later in the option list.
I'm actually quite impressed that our code has already been factored
to do all option parsing through common entry points, such that I
got this added in relatively few lines of code!
* tools/virsh.c (VSH_OT_ALIAS): New option type.
(opts_echo): Hook up an alias, for easy testing.
(vshCmddefOptParse, vshCmddefHelp, vshCmddefGetOption): Allow for
aliases.
* tools/virsh.pod (NOTES): Document promise of back-compat.
* tests/virshtest.c (mymain): Test new feature.
Now virsh can call virDomainBlockRebase.
* tools/virsh.c (cmdBlockPull): Add --base parameter.
(blockJobImpl): Use it to expose BlockRebase API.
* tools/virsh.pod (blockpull): Document it.
The current scrub version doesn't support pfitzner7, pfitzner33 and schneier
patterns on RHEL, we should comment it in virsh man page.
* tools/virsh.pod: update wiping algorithms docs.
Signed-off-by: Alex Jia <ajia@redhat.com>
This patch adds support for the newly introduced
VIR_DOMAIN_CONSOLE_FORCE and VIR_DOMAIN_CONSOLE_SAFE flags. The console
command now has an optional parameter --force that specifies that the
user wants to forcibly interrupt an ongoing console session and create
a new one. Flag --safe requests that the console should be opened only
if the hypervisor driver supports safe console handling.
The behaviour to this point was that the daemon opened two streams to
the console, that competed for data from the pipe, and the result was
that both of the consoles ended up scrambled.
This patch doesn't modify operation of other commands dealing with
console connections (start, create) as those open connections to newly
started domains making it virtually impossible for another client to race
for the console and steal it.
* tools/console.c:
- add support for flag passthrough
* tools/console.h:
- modify function prototypes to match impl.
* tools/virsh.c:
- add flag --force for the console command
This patch adds new options to the "virsh list" command enabling
filtering of persistent and transient domains along with the option to
print only UUIDs or names of domains instead of printing the table.
Option --name prints domain names (one per line) instead of the default
table. Similarly --uuid prints domain's UUID. The option --table is
an alias for the default behavior.
Aditionally --persistent and/or --transient may be specified to filter
the output of domains.
Commit fad5cd2108 introduced option to
display domain's title in the list command output. There was a mistake
in the virsh man page example for this command stating --note instead of
--title.
When blkdeviotune was first committed in 0.9.8, we had the limitation
that setting one value reset all others. But bytes and iops should
be relatively independent. Furthermore, setting tuning values on
a live domain followed by dumpxml did not output the new settings.
* src/qemu/qemu_driver.c (qemuDiskPathToAlias): Add parameter, and
update callers.
(qemuDomainSetBlockIoTune): Don't lose previous unrelated
settings. Make live changes reflect to dumpxml output.
* tools/virsh.pod (blkdeviotune): Update documentation.
This patch adds a new command "desc" to show and modify titles and
description for the domains using the new API.
This patch also adds a new flag for the "list" command to show titles in
the domain list, to allow easy identification of VMs by storing a short
description.
Example:
virsh # list --title
Id Name State Title
-----------------------------------------------
0 Domain-0 running Mailserver 1
2 fedora paused
Add a new function to allow changing of capacity of storage volumes.
Plan out several flags, even if not all of them will be implemented
up front.
Expose the new command via 'virsh vol-resize'.
Signed-off-by: Eric Blake <eblake@redhat.com>
Currently, we support only filling a volume with zeroes on wiping.
However, it is not enough as data might still be readable by
experienced and equipped attacker. Many technical papers have been
written, therefore we should support other wiping algorithms.
Extend the 'shutdown' and 'reboot' methods so that they both
accept a new argument
--mode acpi|agent
* tools/virsh.c: New args for shutdown/reboot
* tools/virsh.pod: Document new args
Other virsh domifXXX commands can accept target name
as a parameter to specify interface. From viewpoint of
consistency, virsh domif-getlink command should accept
target name as a parameter. This patch achieves this.
Signed-off-by: Taku Izumi <izumi.taku@jp.fujitsu.com>
Disk "type" and "device" are generally interesting stuff the
user may want to known, too. To not break any scripts which
parsed the output field, a new option "--details" is introduced
to output the two introduced fields.
Just like command "domblklist", the command extracts "type",
"source", "target", "model", and "MAC" of all virtual interfaces
from domain XML (live or persistent).
When disk snapshots were first implemented, libvirt blindly refused
to allow an external snapshot destination that already exists, since
qemu will blindly overwrite the contents of that file during the
snapshot_blkdev monitor command, and we don't like a default of
data loss by default. But VDSM has a scenario where NFS permissions
are intentionally set so that the destination file can only be
created by the management machine, and not the machine where the
guest is running, so that libvirt will necessarily see the destination
file already existing; adding a flag will allow VDSM to force the file
reuse without libvirt complaining of possible data loss.
https://bugzilla.redhat.com/show_bug.cgi?id=767104
* include/libvirt/libvirt.h.in (virDomainSnapshotCreateFlags): Add
VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT.
* src/libvirt.c (virDomainSnapshotCreateXML): Document it. Add
note about partial failure.
* tools/virsh.c (cmdSnapshotCreate, cmdSnapshotCreateAs): Add new
flag.
* tools/virsh.pod (snapshot-create, snapshot-create-as): Document
it.
* src/qemu/qemu_driver.c (qemuDomainSnapshotDiskPrepare)
(qemuDomainSnapshotCreateXML): Implement the new flag.
Add a new command domiftune to get/set interface parameters.
* tools/virsh.c: implement the new command
* tools/virsh.pod: documentation of the new command
Virsh's echo command looks not having any relations with domains and its
description should go into the generic commands section instead of the
domain commands section (current).
Virsh's send-key command manipulates domains and its description should
go into the domain commands section instead of generic commands section
(current).
Add an option for virsh undefine command, to remove associated storage
volumes while undefining a domain. This patch allows the user to remove
associated (libvirt managed ) storage volumes while undefining a domain.
The new option --storage for the undefine command takes a string
argument that consists of comma separated list of target or source path
of volumes to be undefined. Volumes are removed after the domain has
been successfully undefined,
If a volume is not part of a storage pool, the user is warned to remove
the volume in question himself.
Option --wipe-storage may be specified along with this, that ensures
the image is wiped before removing.
Option --remove-all-storage enables the user to remove all storage. The
name is chosen long as the users should be aware what they're about to
do.
I was wondering why 'virsh edit' didn't support the same
'--inactive' option as 'virsh dumpxml'; reading the source
code showed that --inactive was already implied, and that
the only way to alter a running guest rather than affecting
next boot is by hot-plugging individual devices, or by
something complex like saving the guest and modifying the
save image.
* tools/virsh.pod (define, edit): Mention behavior when guest is
already running.
Currently virsh supports only ^] as escape character for console.
However, some users might want to use something else. This patch
creates such ability by specifying '-e' switch on virsh command
line.
Prior to this patch, for a running dom, the commands:
$ virsh blkiotune dom --device-weights /dev/sda,502,/dev/sdb,498
$ virsh blkiotune dom --device-weights /dev/sda,503
$ virsh blkiotune dom
weight : 500
device_weight : /dev/sda,503
claim that /dev/sdb no longer has a non-default weight, but
directly querying cgroups says otherwise:
$ cat /cgroup/blkio/libvirt/qemu/dom/blkio.weight_device
8:0 503
8:16 498
After this patch, an explicit 0 is required to remove a device path
from the XML, and omitting a device path that was previously
specified leaves that device path untouched in the XML, to match
cgroups behavior.
* src/qemu/qemu_driver.c (parseBlkioWeightDeviceStr): Rename...
(qemuDomainParseDeviceWeightStr): ...and use correct type.
(qemuDomainSetBlkioParameters): After parsing string, modify
rather than replacing existing table.
* tools/virsh.pod (blkiotune): Tweak wording.
Support virsh command blkdeviotune. Can set or query a block disk
I/O throttle setting.
Signed-off-by: Lei Li <lilei@linux.vnet.ibm.com>
Signed-off-by: Zhi Yong Wu <wuzhy@linux.vnet.ibm.com>
Signed-off-by: Eric Blake <eblake@redhat.com>
This adds per-device weights to <blkiotune>. Note that the
cgroups implementation only supports weights per block device,
and not per-file within the device; hence this option must be
global to the domain definition rather than tied to individual
<devices>/<disk> entries:
<domain ...>
<blkiotune>
<device>
<path>/path/to/block</path>
<weight>1000</weight>
</device>
</blkiotune>
..
This patch also adds a parameter --device-weights to virsh command
blkiotune for setting/getting blkiotune.weight_device for any
hypervisor that supports it. All <device> entries under
<blkiotune> are concatenated into a single string attribute under
virDomain{Get,Set}BlkioParameters, named "device_weight".
Signed-off-by: Hu Tao <hutao@cn.fujitsu.com>
Signed-off-by: Eric Blake <eblake@redhat.com>
One of the top questions by libvirt users is how to create a host
bridge device so that guests can be directly on the physical
network. There are several example documents that explain how to do
this manually, but following them often results in confusion and
failure. virt-manager does a good job of creating a bridge based on an
existing network device, but not everyone wants to use virt-manager.
This patch adds a new command, iface-bridge that makes it just about
as simple as possible to create a new bridge device based on an
existing ethernet/vlan/bond device (including associating IP
configuration with the bridge rather than the now-attached device),
and start that new bridge up ready for action, eg:
virsh iface-bridge eth0 br0
For symmetry's sake, it also adds a command to remove a device from a
bridge, restoring the IP config to the now-unattached device:
virsh iface-unbridge br0
(I had a short debate about whether to do "iface-unbridge eth0"
instead, but that would involve searching through all bridge devices
for the one that contained eth0, which seems like a bit too much
trouble).
NOTE: These two commands require that the netcf library be available
on the host. Hopefully this will provide some extra incentive for
people using suse, debian, ubuntu, and other similar systems to polish
up (and push downstream) the ports to those distros recently pushed to
the upstream netcf repo by Dan Berrange. Anyone interested in helping
with that effort in any way should join the netcf-devel mailing list
(subscription info at
https://fedorahosted.org/mailman/listinfo/netcf-devel)
During creation of the bridge, it's possible to specify whether or not
the STP protocol should be started up on the bridge and, if so, how
many seconds the bridge should squelch traffic from newly added
devices while learning new topology (defaults are stp='on' and
delay='0', which seems to usually work best for bridges used in the
context of libvirt guests).
There is also an option to not immediately start the bridge (and a
similar option to not immediately start the un-attached device after
destroying the bridge. Default is to start the new device, because in
the case of iface-unbridge not starting is strongly discouraged as it
will leave the system with no network connectivity on that interface
(because it's necessary to destroy/undefine the bridge device before
the unattached device can be defined), and it seemed better to make
the option for iface-bridge behave consistently.
NOTE TO THOSE TRYING THESE COMMANDS FOR THE FIRST TIME: to guard
against any "unexpected" change to configuration, it is advisable to
issue an "virsh iface-begin" command before starting any interface
config changes, and "virsh iface-commit" only after you've verified
that everything is working as you expect. If something goes wrong,
you can always run "virsh iface-rollback" or reboot the system (which
should automatically do iface-rollback).
Aside from adding the code for these two functions, and the two
entries into the command table, the only other change to virsh.c was
to add the option name to vshCommandOptInterfaceBy(), because the
iface-unbridge command names its interface option as "bridge".
virsh.pod has also been updated with short descriptions of these two
new commands.
Clarify some of the effects of managed passthrough <hostdev> devices;
with recent changes (commit d093547), a nodedev-reattach is only needed
to pair up to an explicit nodedev-dettach (but beware that older
virt-manager has a bug where it uses explicit nodedev-dettach under the
hood when using the gui to hotplug a hostdev device).
* docs/formatdomain.html.in: Mention reattach.
* tools/virsh.pod (nodedev): Mention managed mode.
Rather than having to do:
$ virsh snapshot-revert dom $(virsh snapshot-current dom --name)
I thought it would be nice to do:
$ virsh snapshot-revert dom --current
I didn't add 'virsh snapshot-dumpxml --current' since we already have
'virsh snapshot-current' for the same task. snapshot-list accepted
a name but did not require it, and that remains the case, with
--current serving in place of that name. For all other commands,
name used to be required, and can now be replaced by --current;
I intentionally made it so that omitting both --current and a name
is an error (having the absence of a name imply --current seems
just a bit too magic, so --current must be explicit). I also had
to keep snapshot-edit backwards-compatible, as the only command
that already had a --current argument alongside a name, which still
works to both edit a named snapshot and make it current.
* tools/virsh.c (vshLookupSnapshot): New helper function.
(cmdSnapshotEdit, cmdSnapshotList, cmdSnapshotParent)
(cmdSnapshotDelete, cmdDomainSnapshotRevert): Use it, adding an
option where needed.
* tools/virsh.pod (snapshot-delete, snapshot-edit)
(snapshot-list, snapshot-parent, snapshot-revert): Document
use of --current.
(snapshot-dumpxml): Mention alternative.
Sometimes, we only care about one branch of the snapshot hierarchy.
Make it easier to list a single branch, by using the new APIs.
Technically, I could emulate these new virsh options on old servers
by doing a complete dump, then scraping xml to filter out just the
snapshots that I care about, but I didn't want to do that in this patch.
* tools/virsh.c (cmdSnapshotList): Add --from, --descendants.
* tools/virsh.pod (snapshot-list): Document them.
I was a bit surprised that 'virsh snapshot-edit dom name' silently
allowed me to clone things, while still telling me the old name,
especially since other commands like 'virsh edit dom' reject rename
attempts (*). This fixes things to be more explicit (**).
(*) Technically, 'virsh edit dom' relies on virDomainDefineXML
behavior, which rejects attempts to mix a new name with existing
uuid or new uuid with existing name, but you can create a new
domain by changing both uuid and name. On the other hand, while
snapshot-edit --clone is a true clone, creating a new domain
would also have to decide whether to clone snapshot metadata,
managed save, and any other secondary data related to the domain.
Domain renames are not trivial either.
(**) Renaming or creating a clone is still a risky proposition -
for offline snapshots and system checkpoints, if the new name
does not match an actual name recorded in the qcow2 internal
snapshots, then you cannot revert to the new checkpoint. But it
is assumed that anyone using the new virsh flags knows what they
are doing, and can deal with the fallout caused by a rename/clone;
that is, we can't completely prevent a user from shooting
themselves in the foot, so much as we are making the default
action less risky.
* tools/virsh.c (cmdSnapshotEdit): Add --rename, --clone.
* tools/virsh.pod (snapshot-edit): Document them.
Although reverting to a snapshot is a form of data loss, this is
normally expected. However, there are two cases where additional
surprises (failure to run the reverted state, or a break in
connectivity to the domain) can come into play. Requiring extra
acknowledgment in these cases will make it less likely that
someone can get into an unrecoverable state due to a default revert.
Also create a new error code, so users can distinguish when forcing
would make a difference, rather than having to blindly request force.
* include/libvirt/libvirt.h.in (VIR_DOMAIN_SNAPSHOT_REVERT_FORCE):
New flag.
* src/libvirt.c (virDomainRevertToSnapshot): Document it.
* include/libvirt/virterror.h (VIR_ERR_SNAPSHOT_REVERT_RISKY): New
error value.
* src/util/virterror.c (virErrorMsg): Implement it.
* tools/virsh.c (cmdDomainSnapshotRevert): Add --force to virsh.
* tools/virsh.pod (snapshot-revert): Document it.
This patch is based on a improvement suggested by Kazuhiro Kikuchi
of Fujitsu, it gives a description of the target parameter for that
command
* tools/virsh.pod: add description for target parameter of
attach-interface
The man page suggest that the cpu_shares parameter of schedinfo
allows values 0-262144, but the kernel remaps values 0 and 1 to
the minimum 2, just document that behaviour:
[root@test ~]# cat /cgroup/cpu/libvirt/qemu/cpu.shares
1024
[root@test ~]# echo 0 > /cgroup/cpu/libvirt/qemu/cpu.shares
[root@test ~]# cat /cgroup/cpu/libvirt/qemu/cpu.shares
2
[root@test ~]# echo 1 > /cgroup/cpu/libvirt/qemu/cpu.shares
[root@test ~]# cat /cgroup/cpu/libvirt/qemu/cpu.shares
2
[root@test ~]#
* tools/virsh.pod: update description of the cpu_shares parameter
to indicate the values 0 and 1 are automatically changed by the
kernel to minimal value 2
Reuse the tree listing of nodedev-list, coupled with the new helper
function to efficiently grab snapshot parent names, to produce
tree output for a snapshot hierarchy. For example:
$ virsh snapshot-list dom --tree
root1
|
+- sibling1
+- sibling2
| |
| +- grandchild
|
+- sibling3
root2
|
+- child
* tools/virsh.c (cmdSnapshotList): Add --tree.
* tools/virsh.pod (snapshot-list): Document it.
This section of the man page was completely missing; I stumbled on
it when I had no clue that I had to use nodedev-reattach after
I was done playing with <hostdev> device passthrough to one of my
guests.
* tools/virsh.pod (NODEDEV COMMANDS): New section.
(attach-device, detach-device): Add cross-references.
