17.2. The Domain Management Tool

17.2.1. The Domain Management Tool

Red Hat Enterprise Virtualization Manager authenticates users using directory services. To add users to Red Hat Enterprise Virtualization Manager you must first use the internal admin user to add the directory service that the users must be authenticated against. You add and remove directory services domains using the included domain management tool, engine-manage-domains.
The engine-manage-domains command is only accessible on the machine on which Red Hat Enterprise Virtualization Manager is installed. The engine-manage-domains command must be run as the root user.

Important

Red Hat Enterprise Virtualization 3.6 is the last version to support this tool. Use the LDAP provider implementation to configure directory servers for authenticating and authorizing users. See Section 14.3.1, “Configuring an External LDAP Provider (Interactive Setup)” for more information.
An upstream tool is available to assist with migrating from the old implementation to the new implementation. See https://github.com/machacekondra/ovirt-engine-kerbldap-migration/releases for more information.

17.2.2. Syntax for the Domain Management Tool

The usage syntax is: 
engine-manage-domains ACTION [options]
Available actions are:
add
Add a domain to Red Hat Enterprise Virtualization Manager's directory services configuration.
edit
Edit a domain in Red Hat Enterprise Virtualization Manager's directory services configuration.
delete
Delete a domain from Red Hat Enterprise Virtualization Manager's directory services configuration.
validate
Validate Red Hat Enterprise Virtualization Manager's directory services configuration. This command attempts to authenticate each domain in the configuration using the configured user name and password.
list
List Red Hat Enterprise Virtualization Manager's current directory services configuration.
These options can be combined with the actions on the command line:
--add-permissions
Specifies that the domain user will be given the SuperUser role in Red Hat Enterprise Virtualization Manager. By default, if the --add-permissions parameter is not specified, the SuperUser role is not assigned to the domain user. The --add-permissions option is optional. It is only valid when used in combination with the add and edit actions.
--change-password-msg=[MSG]
Specifies the message that is returned to the user at login when their password has expired. This allows you to direct users to a specific URL (must begin with http or https) where their password can be changed. The --change-password-msg option is optional, and is only valid when used in combination with the add and edit actions.
--config-file=[FILE]
Specifies an alternate configuration file that the command must use. The --config-file parameter is always optional.
--domain=[DOMAIN]
The domain on which the action will be performed. The --domain parameter is mandatory for the add, edit, and delete actions.
--force
Forces the command to skip confirmation of delete operations.
--ldap-servers=[SERVERS]
A comma delimited list of LDAP servers to be set to the domain.
--log-file=[LOG_FILE]
The name of a file into which to write logs for an operation.
--log-level=[LOG_LEVEL]
The log level. You can choose either DEBUG (the default option), INFO, WARN, or ERROR. These options are case insensitive.
--log4j-config=[LOG4J_FILE]
A log4j.xml file from which to read logging configuration information.
--provider=[PROVIDER]
The LDAP provider type of the directory server for the domain. Valid values are:
  • ad - Microsoft Active Directory.
  • ipa - Identity Management (IdM).
  • rhds - Red Hat Directory Server. Red Hat Directory Server does not come with Kerberos. Red Hat Enterprise Virtualization requires Kerberos authentication. Red Hat Directory Server must be running as a service inside a Kerberos domain to provide directory services to the Manager.

    Note

    To use Red Hat Directory Server as your directory server, you must have the memberof plug-in installed in Red Hat Directory Server. To use the memberof plug-in, your users must be inetuser.
  • itds - IBM Tivoli Directory Server.
  • oldap - OpenLDAP.
--report
When used in conjunction with the validate action, this command outputs a report of all validation errors encountered.
--resolve-kdc
Resolve key distribution center servers using DNS.
--user=[USER]
Specifies the domain user to use. The --user parameter is mandatory for add, and optional for edit.
--password-file=[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.
For further details on usage, see the engine-manage-domains command's help output: 
# engine-manage-domains --help

17.2.3. Using the Domain Management Tool

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

17.2.4. Listing Domains in Configuration

The engine-manage-domains command lists the directory services domains defined in the Red Hat Enterprise Virtualization Manager configuration. This command prints the domain, the user name in User Principal Name (UPN) format, and whether the domain is local or remote for each configuration entry.

Example 17.1. engine-manage-domains List Action

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

17.2.5. Adding Domains to Configuration

In this example, the engine-manage-domains command is used to add the IdM domain directory.demo.redhat.com to the Red Hat Enterprise Virtualization Manager configuration. The configuration is set to use the admin user when querying the domain; the password is provided interactively.

Example 17.2. engine-manage-domains Add Action

# engine-manage-domains add --domain=directory.demo.redhat.com --provider=IPA --user=admin
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. oVirt Engine restart is required in order for the changes to take place (service ovirt-engine restart).

17.2.6. Editing a Domain in the Configuration

In this example, the engine-manage-domains command is used 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; the password is provided interactively.

Example 17.3. engine-manage-domains Edit Action

# engine-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 guide is: 80b71bae-98a1-11e0-8f20-525400866c73
Successfully edited domain directory.demo.redhat.com. oVirt Engine restart is required in order for the changes to take place (service ovirt-engine restart).

17.2.7. Validating Domain Configuration

In this example, the engine-manage-domains command is used 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. The domain is reported as valid if the attempt is successful.

Example 17.4. engine-manage-domains Validate Action

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

17.2.8. Deleting a Domain from the Configuration

In this example, the engine-manage-domains command is used 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 the Red Hat Enterprise Virtualization Manager. The entries for the affected users will remain defined in the 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.

Example 17.5. engine-manage-domains Delete Action

# engine-manage-domains 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.