16.7. Administering User Tasks From the Command Line

You can use the ovirt-aaa-jdbc-tool tool to manage user accounts on the internal domain. Changes made using the tool take effect immediately and do not require you to restart the ovirt-engine service. For a full list of user options, run ovirt-aaa-jdbc-tool user --help. Common examples are provided in this section.

Important

You must be logged in on the Manager machine.

16.7.1. Creating a New User

You can create a new user account. The optional --attribute command specifies account details. For a full list of options, run ovirt-aaa-jdbc-tool user add --help.
# ovirt-aaa-jdbc-tool user add test1 --attribute=firstName=John --attribute=lastName=Doe 
adding user test1...
user added successfully
You can add the newly created user in the Administration Portal and assign the user appropriate roles and permissions. See Section 16.6.1, “Adding Users and Assigning User Portal Permissions” for more information.

16.7.2. Setting a User Password

You can create a user password. You must set --password-valid-to. Otherwise, the password expiry time defaults to the current time. The date format is yyyy-MM-dd HH:mm:ssX. In this example, -0800 stands for GMT minus 8 hours. For more options, run ovirt-aaa-jdbc-tool user password-reset --help.
# ovirt-aaa-jdbc-tool user password-reset test1 --password-valid-to="2025-08-01 12:00:00-0800"
Password:
Reenter password:
updating user test1...
user updated successfully

Note

By default, the password policy for user accounts on the internal domain has the following restrictions:
  • A minimum of 6 characters.
  • Three previous passwords used cannot be set again during the password change.
For more information on the password policy and other default settings, run ovirt-aaa-jdbc-tool settings show.

16.7.3. Setting User Timeout

You can set the user timeout period:
# engine-config --set UserSessionTimeOutInterval=integer
The default user timeout period is 30 minutes. A negative value ensures that sessions never expire.

16.7.4. Pre-encrypting a User Password

You can create a pre-encrypted user password using the ovirt-engine-crypto-tool. This option is useful if you are adding users and passwords to the database with a script.

Note

Passwords are stored in the Manager database in encrypted form. The ovirt-engine-crypto-tool script is used because all passwords must be encrypted with the same algorithm.
If the password is pre-encrypted, password validity tests cannot be performed. The password will be accepted even if it does not comply with the password validation policy.
  1. Run the following command:
    # /usr/share/ovirt-engine/bin/ovirt-engine-crypto-tool.sh pbe-encode
    The script will prompt you to enter the password.
    Alternatively, you can use --password=file:file, with the password in the first line of the file:
    # /usr/share/ovirt-engine/bin/ovirt-engine-crypto-tool.sh pbe-encode --password=file:file
  2. Set the new password with the ovirt-aaa-jdbc-tool tool, using the --encrypted option:
    # ovirt-aaa-jdbc-tool user password-reset test1 --password-valid-to="2025-08-01 12:00:00-0800" --encrypted
    
  3. Enter and confirm the encrypted password:
    Password:
    Reenter password:
    updating user test1...
    user updated successfully

16.7.5. Viewing User Information

You can view detailed user account information:
# ovirt-aaa-jdbc-tool user show test1
This command displays more information than in the Administration Portal's Users tab.

16.7.6. Editing User Information

You can update user information, such as the email address:
# ovirt-aaa-jdbc-tool user edit test1 --attribute=email=jdoe@example.com

16.7.7. Removing a User

  1. You can remove a user account:
    # ovirt-aaa-jdbc-tool user delete test1
  2. Remove the user from the Administration Portal. See Section 16.6.4, “Removing Users” for more information.

16.7.8. Disabling the Internal Administrative User

You can disable users on the local domains including the admin@internal user created during engine-setup. Make sure you have at least one user in the environment with full administrative permissions before disabling the default admin user. See Section 16.6.1, “Adding Users and Assigning User Portal Permissions” for more information.
# ovirt-aaa-jdbc-tool user edit admin --flag=+disabled

Note

To enable a disabled user, run ovirt-aaa-jdbc-tool user edit username --flag=-disabled

16.7.9. Managing Groups

Managing group accounts is similar to managing user accounts. For a full list of group options, run ovirt-aaa-jdbc-tool group --help. Common examples are provided in this section.
You can create a new group:
# ovirt-aaa-jdbc-tool group add group1
You can add users to the group. The users must be created already.
# ovirt-aaa-jdbc-tool group-manage useradd group1 --user=test1

Note

For a full list of the group-manage options, run ovirt-aaa-jdbc-tool group-manage --help.
You can view group account details:
# ovirt-aaa-jdbc-tool group show group1
Add the newly created group in the Administration Portal and assign the group appropriate roles and permissions. The users in the group inherit the roles and permissions of the group. See Section 16.6.1, “Adding Users and Assigning User Portal Permissions” for more information.
You can create groups within groups.
  1. Create the first group:
    # ovirt-aaa-jdbc-tool group add group1
  2. Create the second group:
    # ovirt-aaa-jdbc-tool group add group1-1
  3. Add the second group to the first group:
    # ovirt-aaa-jdbc-tool group-manage groupadd group1 --group=group1-1
  4. Add the first group in the Administration Portal and assign the group appropriate roles and permissions. See Section 16.6.1, “Adding Users and Assigning User Portal Permissions” for more information.

16.7.10. Querying Users and Groups

You can query user and group information using the query module. For a full list of options, run ovirt-aaa-jdbc-tool query --help.
List all user account details:
# ovirt-aaa-jdbc-tool query --what=user
List all group account details:
# ovirt-aaa-jdbc-tool query --what=group
You can apply filters when listing account information, for example, listing user account details for names that start with j:
# ovirt-aaa-jdbc-tool query --what=user --pattern="name=j*"
List groups that have the department attribute set to marketing:
# ovirt-aaa-jdbc-tool query --what=group --pattern="department=marketing"

16.7.11. Managing Account Settings

You can change the default account settings with the settings module. To view all options, run ovirt-aaa-jdbc-tool settings show.
Update the default log-in session time (10080 minutes) to 60 minutes for all user accounts:
# ovirt-aaa-jdbc-tool settings set --name=MAX_LOGIN_MINUTES --value=60
Update the default number of failed login attempts (5) a user can perform before the user account is locked:
# ovirt-aaa-jdbc-tool settings set --name=MAX_FAILURES_SINCE_SUCCESS --value=3

Note

To unlock a locked user account, run ovirt-aaa-jdbc-tool user unlock test1.