Appendix C. Additional Utilities

C.1. Domain Management Tool

Red Hat Enterprise Virtualization Manager uses directory services to authenticate users. While during installation the manager sets up a domain named internal this is only used for the admin user. To add and remove other users from the system it is first necessary to add the directory service(s) in which they are found.

The supported directory services are Active Directory and IPA. Red Hat Enterprise Virtualization Manager includes a domain management tool, rhevm-manage-domains, to add and remove domains provided by these services. In this way it is possible to grant access to the Red Hat Enterprise Virtualization environment to users stored across multiple domains. This is true even where some users are stored in a domain managed by Active Directory and others are stored in a domain managed by IPA.

You will find the rhevm-manage-domains command on the machine to which Red Hat Enterprise Virtualization Manager was installed. The rhevm-manage-domains command must be run as the root user.

C.1.1. Syntax

The usage syntax is:

Usage:	rhevm-manage-domains -action=ACTION [options]

Available actions are:

add: Add a domain to the manager's directory services configuration.
edit: Edit a domain in the manager's directory services configuration.
delete: Delete a domain from the manager's directory services configuration.
validate: Validate the manager's directory services configuration. The command attempts to authenticate to each domain in the configuration using the configured username and password.
list: List the manager's current directory services configuration.

The options available to be combined with the actions on the command line are:

-domain=DOMAIN: Specifies the domain the action must be performed on. The -domain parameter is mandatory for add, edit, and delete.
-user=USER: Specifies the domain user to use. The -user parameter is mandatory for add, and optional for edit.
-interactive: Specifies that the domain user's password is to be provided interactively. This option, or the -passwordFile option, must be used to provide the password for use with the add action.
-passwordFile=FILE: Specifies that the domain user's password is on the first line of the provided file. This option, or the -interactive option, must be used to provide the password for use with the add action.
-configFile=FILE: Specifies an alternative configuration file that the command must load. The -configFile parameter is always optional.
-report: Specifies that when performing the validate action all validation errors encountered will be reported in full.

Common usage examples are discussed further within this guide. For full usage information consult the rhevm-manage-domains command's help output:

# rhevm-manage-domains --help

C.1.2. Examples

The following examples demonstrate the use of the rhevm-manage-domains to perform basic manipulation of the Red Hat Enterprise Virtualization Manager domain configuration.

Example C.1. Adding Domains to Configuration

This example runs the rhevm-manage-domains command to add the directory.demo.redhat.com domain to the Red Hat Enterprise Virtualization Manager configuration. The configuration is set to use the admin user when querying the domain with the password to be provided interactively.

# rhevm-manage-domains -action=add -domain='directory.demo.redhat.com' -user='admin' -interactive
loaded template kr5.conf file
setting default_tkt_enctypes 
setting realms
setting domain realm
success
User guid is: 80b71bae-98a1-11e0-8f20-525400866c73
Successfully added domain directory.demo.redhat.com

Example C.2. Edit Domain in Configuration

This example runs the rhevm-manage-domains command to edit the directory.demo.redhat.com domain in the Red Hat Enterprise Virtualization Manager configuration. The configuration is updated to use the admin user when querying this domain with the password to be provided interactively.

# rhevm-manage-domains -action=edit -domain=directory.demo.redhat.com -user=admin -interactive
loaded template kr5.conf file
setting default_tkt_enctypes 
setting realms
setting domain realmo
success
User guid is: 80b71bae-98a1-11e0-8f20-525400866c73
Successfully edited domain directory.demo.redhat.com

Example C.3. Deleting Domains from Configuration

This example runs the rhevm-manage-domains command to remove the directory.demo.redhat.com domain from the Red Hat Enterprise Virtualization Manager configuration. Users defined in the removed domain will no longer be able to authenticate with Red Hat Enterprise Virtualization Manager. The entries for the affected users will remain defined in Red Hat Enterprise Virtualization Manager until they are explicitly removed.

The domain being removed in this example is the last one listed in the Red Hat Enterprise Virtualization Manager configuration. A warning is displayed highlighting this fact and that only the admin user from the internal domain will be able to log in until another domain is added.

# rhevm-manage-domains -action=delete -domain='directory.demo.redhat.com'
WARNING: Domain directory.demo.redhat.com is the last domain in the configuration. After deleting it you will have to either add another domain, or to use the internal admin user in order to login.
Successfully deleted domain directory.demo.redhat.com. Please remove all users and groups of this domain using the Administration portal or the API.

Example C.4. Validating Configuration

This example runs the rhevm-manage-domains command to validate the Red Hat Enterprise Virtualization Manager configuration. The command attempts to log into each listed domain with the credentials provided in the configuration. If the attempt is successful then the domain is reported as valid.

# rhevm-manage-domains -action=validate
User guid is: 80b71bae-98a1-11e0-8f20-525400866c73
Domain directory.demo.redhat.com is valid.

Example C.5. Listing Domains in Configuration

This example runs the rhevm-manage-domains command to list the domains defined in the Red Hat Enterprise Virtualization Manager configuration. For each configuration entry the command displays the domain, the username — in User Principle Name (UPN) format, and whether the domain is local or remote.

# rhevm-manage-domains -action=list
Domain: directory.demo.redhat.com
	User name: admin@DIRECTORY.DEMO.REDHAT.COM
	This domain is a remote domain.