Chapter 3. Introduction to the IdM command-line utilities

Learn more about 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.

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 for managing 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.

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

  • Have an IdM server installed and running.
  • Be authenticated with a valid Kerberos ticket.

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]
  • [] — Brackets mean that all parameters are optional and you can write just ipa help and the command will be executed.
  • | — The pipe character means or. Therefore, you can specify a TOPIC, a COMMAND, or topics, or commands, with the basic ipa help command:

    • topics — You can run the command ipa help topics to display a list of topics that are covered by the IPA help, such as user, cert, server and many others.
    • TOPIC — The TOPIC with capital letters is a variable. Therefore, you can specify a particular topic, for example, ipa help user.
    • commands — You can enter the command ipa help commands to display 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 is a variable. Therefore, you can specify a particular command, for example, ipa help user-add.

3.3. Using IPA help topics

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

Procedure

  1. Open a terminal and connect to the IdM server.
  2. Enter ipa help topics to display a list of topics covered by help.

    $ ipa help topics
  3. Select one of the topics and create a command according to the following pattern: ipa help [topic_name]. Instead of the topic_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
  4. If the IPA help output 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 describes how to create IPA help commands in the command-line interface.

Procedure

  1. Open a terminal and connect to the IdM server.
  2. Enter ipa help commands to display a list of commands covered by help.

    $ ipa help commands
  3. 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

The 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 also includes an object: ipa user-mod USER_NAME [options].

3.6. Using an IPA command to add a user account to IdM

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

Prerequisites

  • You need to have administrator privileges to add user accounts to the IdM server.

Procedure

  1. Open a terminal and connect to the IdM server.
  2. Enter the command for adding a new user:

    $ ipa user-add

    The command runs a script that prompts you to provide basic data necessary for creating a user account.

  3. In the First name: field, enter the first name of the new user and press the Enter key.
  4. In the Last name: field, enter the last name of the new user and press the Enter key.
  5. In the User login [suggested user name]: enter the user name, or just press the Enter key to accept the suggested user name.

    The user name must be unique for the whole IdM database. If an error occurs because that user name already exists, repeat the process with the ipa user-add command and use a different, unique user name.

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
Note

By default, a user password is not set for the user account. To add a password while creating a user account, use the ipa user-add command with the following syntax:

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

The IPA CLI then prompts you to add or confirm a user name and password.

If the user has been created already, you can add 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.

Procedure

  1. Open a terminal and connect to the IdM server.
  2. Enter the ipa user-mod command, specify the user to modify, and any options, such as --password for adding a password:

    $ ipa user-mod euser --password

    The command runs a script where you can add the new password.

  3. Enter the new password and press the Enter key.

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.

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} ...

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} ...

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.