Chapter 3. Introduction to the IdM command-line utilities

The IPA command-line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration.

It supports a lot of subcommands for managing IdM, such as the ipa user-add command to add a new user.

IPA CLI allows you to:

The IPA help is a built-in documentation system for the IdM server.

The IPA command-line interface (CLI) generates available help topics from loaded IdM plugin modules. To use the IPA help utility, you must:

Entering the ipa help command without options displays information about basic help usage and the most common command examples.

You can use the following options for different ipa help use cases:

$ ipa help [TOPIC | COMMAND | topics | commands]

The following procedure describes how to use the IPA help in the command-line interface.

The IPA CLI displays a help page for the user topic. After reading the overview, you can see many examples with patterns for working with topic commands.

The following procedure describes how to create IPA help commands in the command-line interface.

The IPA CLI distinguishes the following types of commands:

The structure of IPA commands allows you to manage various types of objects. For example:

and many others.

For most of these objects, the IPA CLI includes commands to:

Commands have the following structure:

ipa user-add, ipa user-mod, ipa user-del, ipa user-find, ipa user-show

ipa host-add, ipa host-mod, ipa host-del, ipa host-find, ipa host-show

ipa dnsrecord-add, ipa dnsrecord-mod, ipa dnsrecord-del, ipa dnsrecord-find, ipa dnrecord-show

You can create a user with the ipa user-add [options], where [options] are optional. If you use just the ipa user-add command, the script asks you for details one by one.

To change an existing object, you need to define the object, therefore the command also includes an object: ipa user-mod USER_NAME [options].

The following procedure describes how to add a new user to the Identity Management (IdM) database using the command line.

After you add the user name, the user account is added to the IdM database and the IPA command-line interface (CLI) prints the following output:

----------------------
Added user "euser"
----------------------
User login: euser
First name: Example
Last name: User
Full name: Example User
Display name: Example User
Initials: EU
Home directory: /home/euser
GECOS: Example User
Login shell: /bin/sh
Principal name: euser@IDM.EXAMPLE.COM
Principal alias: euser@IDM.EXAMPLE.COM
Email address: euser@idm.example.com
UID: 427200006
GID: 427200006
Password: False
Member of groups: ipausers
Kerberos keys available: False

$ ipa user-add --first=Example --last=User --password

You can change many parameters for each user account. For example, you can add a new password to the user.

Basic command syntax is different from the user-add syntax because you need to define the existing user account for which you want to perform changes, for example, add a password.

The IPA CLI prints the following output:

----------------------
Modified user "euser"
----------------------
User login: euser
First name: Example
Last name: User
Home directory: /home/euser
Principal name: euser@IDM.EXAMPLE.COM
Principal alias: euser@IDM.EXAMPLE.COM
Email address: euser@idm.example.com
UID: 427200006
GID: 427200006
Password: True
Member of groups: ipausers
Kerberos keys available: True

The user password is now set for the account and the user can log into IdM.

Identity Management (IdM) stores values for multi-valued attributes in lists.

IdM supports the following methods of supplying multi-valued lists:

The examples above show a command permission-add which adds permissions to an object. The object is not mentioned in the example. Instead of …​ you need to add the object for which you want to add permissions.

When you update such multi-valued attributes from the command line, IdM completely overwrites the previous list of values with a new list. Therefore, when updating a multi-valued attribute, you must specify the whole new list, not just a single value you want to add.

For example, in the command above, the list of permissions includes reading, writing and deleting. When you decide to update the list with the permission-mod command, you must add all values, otherwise those not mentioned will be deleted.

Example 1: — The ipa permission-mod command updates all previously added permissions.

$ ipa permission-mod --right=read --right=write --right=delete ...

or

$ ipa permission-mod --right={read,write,delete} ...

Example 2 — The ipa permission-mod command deletes the --right=delete argument because it is not included in the command:

$ ipa permission-mod --right=read --right=write ...

or

$ ipa permission-mod --right={read,write} ...

When passing command-line arguments that include special characters to the ipa commands, escape these characters with a backslash (\). For example, common special characters include angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|).

For example, to escape an asterisk (*):

$ ipa certprofile-show certificate_profile --out=exported\*profile.cfg

Commands containing unescaped special characters do not work as expected because the shell cannot properly parse such characters.