1.3. Searches

1.3.1. Performing Searches in Red Hat Virtualization

The Administration Portal allows you to manage thousands of resources, such as virtual machines, hosts, users, and more. To perform a search, enter the search query (free-text or syntax-based) into the search bar, available on the main page for each resource. Search queries can be saved as bookmarks for future reuse, so you do not have to reenter a search query each time the specific search results are required. Searches are not case sensitive.

1.3.2. Search Syntax and Examples

The syntax of the search queries for Red Hat Virtualization resources is as follows:

result type: {criteria} [sortby sort_spec]

Syntax Examples

The following examples describe how the search query is used and help you to understand how Red Hat Virtualization assists with building search queries.

Table 1.15. Example Search Queries
Example	Result
Hosts: Vms.status = up page 2	Displays page 2 of a list of all hosts running virtual machines that are up.
Vms: domain = qa.company.com	Displays a list of all virtual machines running on the specified domain.
Vms: users.name = Mary	Displays a list of all virtual machines belonging to users with the user name Mary.
Events: severity > normal sortby time	Displays the list of all Events whose severity is higher than Normal, sorted by time.

1.3.3. Search Auto-Completion

The Administration Portal provides auto-completion to help you create valid and powerful search queries. As you type each part of a search query, a drop-down list of choices for the next part of the search opens below the Search Bar. You can either select from the list and then continue typing/selecting the next part of the search, or ignore the options and continue entering your query manually.

The following table specifies by example how the Administration Portal auto-completion assists in constructing a query:

Hosts: Vms.status = down

Table 1.16. Example Search Queries Using Auto-Completion
Input	List Items Displayed	Action
h	`Hosts` (1 option only)	Select `Hosts` or type Hosts
Hosts:	All host properties	Type v
Hosts: v	host properties starting with a `v`	Select `Vms` or type Vms
Hosts: Vms	All virtual machine properties	Type s
Hosts: Vms.s	All virtual machine properties beginning with `s`	Select `status` or type status
Hosts: Vms.status	`=` `!=`	Select or type =
Hosts: Vms.status =	All status values	Select or type down

1.3.4. Search Result Type Options

The result type allows you to search for resources of any of the following types:

Vms for a list of virtual machines
Host for a list of hosts
Pools for a list of pools
Template for a list of templates
Events for a list of events
Users for a list of users
Cluster for a list of clusters
DataCenter for a list of data centers
Storage for a list of storage domains

As each type of resource has a unique set of properties and a set of other resource types that it is associated with, each search type has a set of valid syntax combinations. You can also use the auto-complete feature to create valid queries easily.

1.3.5. Search Criteria

You can specify the search criteria after the colon in the query. The syntax of {criteria} is as follows:

<prop><operator><value>

or

<obj-type><prop><operator><value>

Examples

The following table describes the parts of the syntax:

Table 1.17. Example Search Criteria
Part	Description	Values	Example	Note
prop	The property of the searched-for resource. Can also be the property of a resource type (see `obj-type`), or tag (custom tag).	Limit your search to objects with a certain property. For example, search for objects with a status property.	Status	N/A
obj-type	A resource type that can be associated with the searched-for resource.	These are system objects, like data centers and virtual machines.	Users	N/A
operator	Comparison operators.	= != (not equal) > < >= <=	N/A	Value options depend on property.
Value	What the expression is being compared to.	String Integer Ranking Date (formatted according to Regional Settings)	Jones 256 normal	Wildcards can be used within strings. "" (two sets of quotation marks with no space between them) can be used to represent an un-initialized (empty) string. Double quotes should be used around a string or date containing spaces

1.3.6. Search: Multiple Criteria and Wildcards

Wildcards can be used in the <value> part of the syntax for strings. For example, to find all users beginning with m, enter m*.

You can perform a search having two criteria by using the Boolean operators AND and OR. For example:

Vms: users.name = m* AND status = Up

This query returns all running virtual machines for users whose names begin with "m".

Vms: users.name = m* AND tag = "paris-loc"

This query returns all virtual machines tagged with "paris-loc" for users whose names begin with "m".

When two criteria are specified without AND or OR, AND is implied. AND precedes OR, and OR precedes implied AND.

1.3.7. Search: Determining Search Order

You can determine the sort order of the returned information by using sortby. Sort direction (asc for ascending, desc for descending) can be included.

For example:

events: severity > normal sortby time desc

This query returns all Events whose severity is higher than Normal, sorted by time (descending order).

1.3.8. Searching for Data Centers

The following table describes all search options for Data Centers.

Table 1.18. Searching for Data Centers
Property (of resource or resource-type)	Type	Description (Reference)
`Clusters.clusters-prop`	Depends on property type	The property of the clusters associated with the data center.
`name`	String	The name of the data center.
`description`	String	A description of the data center.
`type`	String	The type of data center.
`status`	List	The availability of the data center.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Datacenter: type = nfs and status != up

This example returns a list of data centers with a storage type of NFS and status other than up.

1.3.9. Searching for Clusters

The following table describes all search options for clusters.

Table 1.19. Searching Clusters
Property (of resource or resource-type)	Type	Description (Reference)
`Datacenter.datacenter-prop`	Depends on property type	The property of the data center associated with the cluster.
`Datacenter`	String	The data center to which the cluster belongs.
`name`	String	The unique name that identifies the clusters on the network.
`description`	String	The description of the cluster.
`initialized`	String	True or False indicating the status of the cluster.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Clusters: initialized = true or name = Default

This example returns a list of clusters which are initialized or named Default.

1.3.10. Searching for Hosts

The following table describes all search options for hosts.

Table 1.20. Searching for Hosts
Property (of resource or resource-type)	Type	Description (Reference)
`Vms.Vms-prop`	Depends on property type	The property of the virtual machines associated with the host.
`Templates.templates-prop`	Depends on property type	The property of the templates associated with the host.
`Events.events-prop`	Depends on property type	The property of the events associated with the host.
`Users.users-prop`	Depends on property type	The property of the users associated with the host.
`name`	String	The name of the host.
`status`	List	The availability of the host.
`external_status`	String	The health status of the host as reported by external systems and plug-ins.
`cluster`	String	The cluster to which the host belongs.
`address`	String	The unique name that identifies the host on the network.
`cpu_usage`	Integer	The percent of processing power used.
`mem_usage`	Integer	The percentage of memory used.
`network_usage`	Integer	The percentage of network usage.
`load`	Integer	Jobs waiting to be executed in the run-queue per processor, in a given time slice.
`version`	Integer	The version number of the operating system.
`cpus`	Integer	The number of CPUs on the host.
`memory`	Integer	The amount of memory available.
`cpu_speed`	Integer	The processing speed of the CPU.
`cpu_model`	String	The type of CPU.
`active_vms`	Integer	The number of virtual machines currently running.
`migrating_vms`	Integer	The number of virtual machines currently being migrated.
`committed_mem`	Integer	The percentage of committed memory.
`tag`	String	The tag assigned to the host.
`type`	String	The type of host.
`datacenter`	String	The data center to which the host belongs.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Hosts: cluster = Default and Vms.os = rhel6

This example returns a list of hosts which are part of the Default cluster and host virtual machines running the Red Hat Enterprise Linux 6 operating system.

1.3.11. Searching for Networks

The following table describes all search options for networks.

Table 1.21. Searching for Networks
Property (of resource or resource-type)	Type	Description (Reference)
`Cluster_network.clusternetwork-prop`	Depends on property type	The property of the cluster associated with the network.
`Host_Network.hostnetwork-prop`	Depends on property type	The property of the host associated with the network.
`name`	String	The human readable name that identifies the network.
`description`	String	Keywords or text describing the network, optionally used when creating the network.
`vlanid`	Integer	The VLAN ID of the network.
`stp`	String	Whether Spanning Tree Protocol (STP) is enabled or disabled for the network.
`mtu`	Integer	The maximum transmission unit for the logical network.
`vmnetwork`	String	Whether the network is only used for virtual machine traffic.
`datacenter`	String	The data center to which the network is attached.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Network: mtu > 1500 and vmnetwork = true

This example returns a list of networks with a maximum transmission unit greater than 1500 bytes, and which are set up for use by only virtual machines.

1.3.12. Searching for Storage

The following table describes all search options for storage.

Table 1.22. Searching for Storage
Property (of resource or resource-type)	Type	Description (Reference)
`Hosts.hosts-prop`	Depends on property type	The property of the hosts associated with the storage.
`Clusters.clusters-prop`	Depends on property type	The property of the clusters associated with the storage.
`name`	String	The unique name that identifies the storage on the network.
`status`	String	The status of the storage domain.
`external_status`	String	The health status of the storage domain as reported by external systems and plug-ins.
`datacenter`	String	The data center to which the storage belongs.
`type`	String	The type of the storage.
`free-size`	Integer	The size (GB) of the free storage.
`used-size`	Integer	The amount (GB) of the storage that is used.
`total_size`	Integer	The total amount (GB) of the storage that is available.
`committed`	Integer	The amount (GB) of the storage that is committed.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Storage: free_size > 6 GB and total_size < 20 GB

This example returns a list of storage with free storage space greater than 6 GB, or total storage space less than 20 GB.

1.3.13. Searching for Disks

The following table describes all search options for disks.

Note

You can use the Disk Type and Content Type filtering options to reduce the number of displayed virtual disks.

Table 1.23. Searching for Disks
Property (of resource or resource-type)	Type	Description (Reference)
`Datacenters.datacenters-prop`	Depends on property type	The property of the data centers associated with the disk.
`Storages.storages-prop`	Depends on property type	The property of the storage associated with the disk.
`alias`	String	The human readable name that identifies the storage on the network.
`description`	String	Keywords or text describing the disk, optionally used when creating the disk.
`provisioned_size`	Integer	The virtual size of the disk.
`size`	Integer	The size of the disk.
`actual_size`	Integer	The actual size allocated to the disk.
`creation_date`	Integer	The date the disk was created.
`bootable`	String	Whether the disk can or cannot be booted. Valid values are one of `0`, `1`, `yes`, or `no`
`shareable`	String	Whether the disk can or cannot be attached to more than one virtual machine at a time. Valid values are one of `0`, `1`, `yes`, or `no`
`format`	String	The format of the disk. Can be one of `unused`, `unassigned`, `cow`, or `raw`.
`status`	String	The status of the disk. Can be one of `unassigned`, `ok`, `locked`, `invalid`, or `illegal`.
`disk_type`	String	The type of the disk. Can be one of `image` or `lun`.
`number_of_vms`	Integer	The number of virtual machine(s) to which the disk is attached.
`vm_names`	String	The name(s) of the virtual machine(s) to which the disk is attached.
`quota`	String	The name of the quota enforced on the virtual disk.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Disks: format = cow and provisioned_size > 8

This example returns a list of virtual disks with QCOW format and an allocated disk size greater than 8 GB.

1.3.14. Searching for Volumes

The following table describes all search options for volumes.

Table 1.24. Searching for Volumes
Property (of resource or resource-type)	Type	Description (Reference)
`Cluster`	String	The name of the cluster associated with the volume.
`Cluster.cluster-prop`	Depends on property type (examples: name, description, comment, architecture)	The property of the clusters associated with the volume.
`name`	String	The human readable name that identifies the volume.
`type`	String	Can be one of distribute, replicate, distributed_replicate, stripe, or distributed_stripe.
`transport_type`	Integer	Can be one of TCP or RDMA.
`replica_count`	Integer	Number of replica.
`stripe_count`	Integer	Number of stripes.
`status`	String	The status of the volume. Can be one of Up or Down.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Volume: transport_type = rdma and stripe_count >= 2

This example returns a list of volumes with transport type set to RDMA, and with 2 or more stripes.

1.3.15. Searching for Virtual Machines

The following table describes all search options for virtual machines.

Note

Currently, the Network Label, Custom Emulated Machine, and Custom CPU Type properties are not supported search parameters.

Table 1.25. Searching for Virtual Machines
Property (of resource or resource-type)	Type	Description (Reference)
`Hosts.hosts-prop`	Depends on property type	The property of the hosts associated with the virtual machine.
`Templates.templates-prop`	Depends on property type	The property of the templates associated with the virtual machine.
`Events.events-prop`	Depends on property type	The property of the events associated with the virtual machine.
`Users.users-prop`	Depends on property type	The property of the users associated with the virtual machine.
`Storage.storage-prop`	Depends on the property type	The property of storage devices associated with the virtual machine.
`Vnic.vnic-prop`	Depends on the property type	The property of the vNIC associated with the virtual machine.
`name`	String	The name of the virtual machine.
`status`	List	The availability of the virtual machine.
`ip`	Integer	The IP address of the virtual machine.
`uptime`	Integer	The number of minutes that the virtual machine has been running.
`domain`	String	The domain (usually Active Directory domain) that groups these machines.
`os`	String	The operating system selected when the virtual machine was created.
`creationdate`	Date	The date on which the virtual machine was created.
`address`	String	The unique name that identifies the virtual machine on the network.
`cpu_usage`	Integer	The percent of processing power used.
`mem_usage`	Integer	The percentage of memory used.
`network_usage`	Integer	The percentage of network used.
`memory`	Integer	The maximum memory defined.
`apps`	String	The applications currently installed on the virtual machine.
`cluster`	List	The cluster to which the virtual machine belongs.
`pool`	List	The virtual machine pool to which the virtual machine belongs.
`loggedinuser`	String	The name of the user currently logged in to the virtual machine.
`tag`	List	The tags to which the virtual machine belongs.
`datacenter`	String	The data center to which the virtual machine belongs.
`type`	List	The virtual machine type (server or desktop).
`quota`	String	The name of the quota associated with the virtual machine.
`description`	String	Keywords or text describing the virtual machine, optionally used when creating the virtual machine.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.
`next_run_configuration_exists`	Boolean	The virtual machine has pending configuration changes.

Example

Vms: template.name = Win* and user.name = ""

This example returns a list of virtual machines whose base template name begins with Win and are assigned to any user.

Example

Vms: cluster = Default and os = windows7

This example returns a list of virtual machines that belong to the Default cluster and are running Windows 7.

1.3.16. Searching for Pools

The following table describes all search options for Pools.

Table 1.26. Searching for Pools
Property (of resource or resource-type)	Type	Description (Reference)
`name`	String	The name of the pool.
`description`	String	The description of the pool.
`type`	List	The type of pool.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Pools: type = automatic

This example returns a list of pools with a type of automatic.

1.3.17. Searching for Templates

The following table describes all search options for templates.

Table 1.27. Searching for Templates
Property (of resource or resource-type)	Type	Description (Reference)
`Vms.Vms-prop`	String	The property of the virtual machines associated with the template.
`Hosts.hosts-prop`	String	The property of the hosts associated with the template.
`Events.events-prop`	String	The property of the events associated with the template.
`Users.users-prop`	String	The property of the users associated with the template.
`name`	String	The name of the template.
`domain`	String	The domain of the template.
`os`	String	The type of operating system.
`creationdate`	Integer	The date on which the template was created. Date format is mm/dd/yy.
`childcount`	Integer	The number of virtual machines created from the template.
`mem`	Integer	Defined memory.
`description`	String	The description of the template.
`status`	String	The status of the template.
`cluster`	String	The cluster associated with the template.
`datacenter`	String	The data center associated with the template.
`quota`	String	The quota associated with the template.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Template: Events.severity >= normal and Vms.uptime > 0

This example returns a list of templates where events of normal or greater severity have occurred on virtual machines derived from the template, and the virtual machines are still running.

1.3.18. Searching for Users

The following table describes all search options for users.

Table 1.28. Searching for Users
Property (of resource or resource-type)	Type	Description (Reference)
`Vms.Vms-prop`	Depends on property type	The property of the virtual machines associated with the user.
`Hosts.hosts-prop`	Depends on property type	The property of the hosts associated with the user.
`Templates.templates-prop`	Depends on property type	The property of the templates associated with the user.
`Events.events-prop`	Depends on property type	The property of the events associated with the user.
`name`	String	The name of the user.
`lastname`	String	The last name of the user.
`usrname`	String	The unique name of the user.
`department`	String	The department to which the user belongs.
`group`	String	The group to which the user belongs.
`title`	String	The title of the user.
`status`	String	The status of the user.
`role`	String	The role of the user.
`tag`	String	The tag to which the user belongs.
`pool`	String	The pool to which the user belongs.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Users: Events.severity > normal and Vms.status = up or Vms.status = pause

This example returns a list of users where events of greater than normal severity have occurred on their virtual machines AND the virtual machines are still running; or the users' virtual machines are paused.

1.3.19. Searching for Events

The following table describes all search options you can use to search for events. Auto-completion is offered for many options as appropriate.

Table 1.29. Searching for Events
Property (of resource or resource-type)	Type	Description (Reference)
`Vms.Vms-prop`	Depends on property type	The property of the virtual machines associated with the event.
`Hosts.hosts-prop`	Depends on property type	The property of the hosts associated with the event.
`Templates.templates-prop`	Depends on property type	The property of the templates associated with the event.
`Users.users-prop`	Depends on property type	The property of the users associated with the event.
`Clusters.clusters-prop`	Depends on property type	The property of the clusters associated with the event.
`Volumes.Volumes-prop`	Depends on property type	The property of the volumes associated with the event.
`type`	List	Type of the event.
`severity`	List	The severity of the event: Warning/Error/Normal.
`message`	String	Description of the event type.
`time`	List	Day the event occurred.
`usrname`	String	The user name associated with the event.
`event_host`	String	The host associated with the event.
`event_vm`	String	The virtual machine associated with the event.
`event_template`	String	The template associated with the event.
`event_storage`	String	The storage associated with the event.
`event_datacenter`	String	The data center associated with the event.
`event_volume`	String	The volume associated with the event.
`correlation_id`	Integer	The identification number of the event.
`sortby`	List	Sorts the returned results by one of the resource properties.
`page`	Integer	The page number of results to display.

Example

Events: Vms.name = testdesktop and Hosts.name = gonzo.example.com

This example returns a list of events, where the event occurred on the virtual machine named testdesktop while it was running on the host gonzo.example.com.

1.3.1. Performing Searches in Red Hat Virtualization

1.3.2. Search Syntax and Examples

1.3.3. Search Auto-Completion

1.3.4. Search Result Type Options

1.3.5. Search Criteria

1.3.6. Search: Multiple Criteria and Wildcards

1.3.7. Search: Determining Search Order

1.3.8. Searching for Data Centers

1.3.9. Searching for Clusters

1.3.10. Searching for Hosts

1.3.11. Searching for Networks

1.3.12. Searching for Storage

1.3.13. Searching for Disks

1.3.14. Searching for Volumes

1.3.15. Searching for Virtual Machines

1.3.16. Searching for Pools

1.3.17. Searching for Templates

1.3.18. Searching for Users

1.3.19. Searching for Events

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links