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-permissionsparameter is not specified, the SuperUser role is not assigned to the domain user. The--add-permissionsoption is optional. It is only valid when used in combination with theaddandeditactions. --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-msgoption is optional, and is only valid when used in combination with theaddandeditactions. --config-file=[FILE]- Specifies an alternate configuration file that the command must use. The
--config-fileparameter is always optional. --domain=[DOMAIN]- The domain on which the action will be performed. The
--domainparameter is mandatory for theadd,edit, anddeleteactions. --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, orERROR. These options are case insensitive. --log4j-config=[LOG4J_FILE]- A
log4j.xmlfile 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 thememberofplug-in installed in Red Hat Directory Server. To use thememberofplug-in, your users must beinetuser.itds- IBM Tivoli Directory Server.oldap- OpenLDAP.
--report- When used in conjunction with the
validateaction, 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
--userparameter is mandatory foradd, and optional foredit. --password-file=[FILE]- Specifies that the domain user's password is on the first line of the provided file. This option, or the
--interactiveoption, must be used to provide the password for use with theaddaction.
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.
