Menu Close
Red Hat Training
A Red Hat training course is available for RHEL 8
Chapter 3. Introduction to the IdM command-line utilities
The following sections describe the basics of using the Identity Management (IdM) command-line utilities.
Prerequisites
Installed and accessible IdM server.
For details, see Installing Identity Management.
To use the IPA command line interface, authenticate to IdM with a valid Kerberos ticket.
For details about obtaining a valid Kerberos ticket, see Logging in to Identity Management from the command line.
3.1. What is the IPA command line interface
The IPA command line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration.
It supports a lot of subcommands that are used to manage IdM, such as the ipa user-add
command to add a new user.
IPA CLI allows you to:
- Add, manage, or remove users, groups, hosts and other objects in the network.
- Manage certificates.
- Search entries.
- Display and list objects.
- Set access rights.
- Get help with the correct command syntax.
3.2. What is the IPA help
The IPA help is a built-in documentation system for the IdM server.
IPA command line interface (CLI) generates available help topics from loaded IdM plugin modules. If you want to run the IPA help successfully, you need to:
- Have an IdM server installed and running.
- Be authenticated with a valid Kerberos ticket.
Executing the ipa help
command without options displays information about basic help usage and the most common command examples.
Executing help with options has the following syntax:
$ ipa help [TOPIC | COMMAND | topics | commands]
-
[]
— Brackets mean that all parameters are optional and you can write justipa help
and the command will be executed. -
|
— The pipe character means or. Therefore, you can use TOPIC or COMMAND or topics or commands with the basicipa help
command. -
topics
— You can run the commandipa help topics
and it will execute correctly. The command displays a list of topics that are covered by IPA help, for example,user
,cert
,server
and many others. -
TOPIC
— The TOPIC with capital letters means variable, therefore, you can use the particular topic, for example,ipa help user
-
commands
— You can run the commandipa help commands
and it will execute correctly. The command displays a list of commands which are covered by the IPA help, for example,user-add
,ca-enable
,server-show
and many others. -
COMMAND
— The COMMAND with capital letters means variable, therefore, you can use the particular command, for example,ipa help user-add
3.3. Using IPA help topics
The following procedure helps you to understand using the IPA help in the command line interface.
Procedure
- Open terminal and connect to the IdM server.
Enter
ipa help topics
to display a list of topics covered by help.$ ipa help topics
Select one of the topics and create a command according to the following pattern:
ipa help [topic_name]
, instead of thetopic_name
string, add one of the topics you listed in the previous step.In the example, we use the following topic:
user
$ ipa help user
If the IPA help command is too long and you cannot see the whole text, use the following syntax:
$ ipa help user | less
You can then scroll down and read the whole help.
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.
3.4. Using IPA help commands
The following procedure helps you to understand creating the IPA help commands in the command line interface.
Procedure
- Open terminal and connect to the IdM server.
Enter
ipa help commands
to display a list of commands covered by help.$ ipa help commands
Select one of the commands and create a help command according to the following pattern:
ipa help <COMMAND>
, instead of the<COMMAND>
string, add one of the commands you listed in the previous step.$ ipa help user-add
Additional resources
-
The
ipa
man page.
3.5. Structure of IPA commands
The IPA CLI distinguishes the following types of commands:
- Built-in commands — Built-in commands are all available in the IdM server.
- Plug-in provided commands
Structure of IPA commands allows you to manage various types of objects. For example:
- Users,
- Hosts,
- DNS records,
- Certificates,
and many others.
For most of these objects, the IPA CLI includes commands to:
-
Add (
add
) -
Modify (
mod
) -
Delete (
del
) -
Search (
find
) -
Display (
show
)
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 includes also object: ipa user-mod USER_NAME [options]
.
3.6. Using an IPA command to add a user account to IdM
The following describes adding a new user to the Identity Management (IdM) database using command line.
Prerequisites
- You need to have administrator privileges to add user accounts to the IdM server.
Procedure
- Open terminal and connect to the IdM server.
Enter the command for adding a new user:
$ ipa user-add
The command runs a script where you can add basic data necessary for creating a user account.
- In the First name: field, enter the first name of the new user and press the Enter key.
- In the Last name: field, enter the last name of the new user and press the Enter key.
In the User login [suggested user name]: enter the user name or just press the Enter key if the suggested user name works for you.
User name must be unique for the whole IdM database. If an error occurs, that the user already exists, you need to start from the beginning with the
ipa user-add
command and try a different user name.
After you successfully added the user name, the user account has been added to the IdM database and the IPA command line interface (CLI) prints on the output the following log:
---------------------- 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
As you can see, a user password is not set to the user account. If you want to add also password, use the ipa user-add
command in the following syntax:
$ ipa user-add --first=Example --last=User --password
The IPA CLI then asks you for adding or confirming a user name and password.
If the user has been already created, you can add only the password with the ipa user-mod
command.
Additional resources
-
Run the
ipa help user-add
command for more information about parameters.
3.7. Using an IPA command to modify a user account in IdM
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.
Prerequisites
- You need to have administrator privileges to modify user accounts in the IdM server.
Procedure
- Open terminal and connect to the IdM server.
Enter the command for adding a password:
$ ipa user-mod euser --password
The command runs a script where you can add the new password.
- Enter the new password and press the Enter key.
After you successfully added the user name, the user account has been added to the IdM database and the IPA CLI prints on the output the following log:
---------------------- 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.
Additional resources
-
Run the
ipa help user-mod
command for more information about parameters.
3.8. How to supply a list of values to the IdM utilities
Identity Management (IdM) stores values for multi-valued attributes in lists.
IdM supports the following methods of supplying multi-valued lists:
Using the same command-line argument multiple times within the same command invocation:
$ ipa permission-add --right=read --permissions=write --permissions=delete ...
Alternatively, you can enclose the list in curly braces, in which case the shell performs the expansion:
$ ipa permission-add --right={read,write,delete} ...
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.
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} ...
3.9. How to use special characters with the IdM utilities
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.