Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

5.3. The IdM Command-Line Utilities

The basic command-line script for IdM is named ipa. The ipa script is a parent script for a number of subcommands. These subcommands are then used to manage IdM. For example, the ipa user-add command adds a new user:
$ ipa user-add user_name
Command-line management has certain benefits over management in UI; for example, the command-line utilities allow management tasks to be automated and performed repeatedly in a consistent way without manual intervention. Additionally, while most management operations are available both from the command line and in the web UI, some tasks can only be performed from the command line.
Note
This section only provides a general overview of the ipa subcommands. More information is available in the other sections dedicated to specific areas of managing IdM. For example, for information about managing user entries using the ipa subcommands, see Chapter 11, Managing User Accounts.

5.3.1. Getting Help for ipa Commands

The ipa script can display help about a particular set of subcommands: a topic. To display the list of available topics, use the ipa help topics command:
$ ipa help topics

automember         Auto Membership Rule.
automount          Automount
caacl              Manage CA ACL rules.
...
To display help for a particular topic, use the ipa help topic_name command. For example, to display information about the automember topic:
$ ipa help automember

Auto Membership Rule.

Bring clarity to the membership of hosts and users by configuring inclusive
or exclusive regex patterns, you can automatically assign a new entries into
a group or hostgroup based upon attribute information.

...

EXAMPLES:

 Add the initial group or hostgroup:
   ipa hostgroup-add --desc="Web Servers" webservers
   ipa group-add --desc="Developers" devel
...
The ipa script can also display a list of available ipa commands. To do this, use the ipa help commands command:
$ ipa help commands
automember-add                         Add an automember rule.
automember-add-condition               Add conditions to an automember rule.
...
For detailed help on the individual ipa commands, add the --help option to a command. For example:
$ ipa automember-add --help

Usage: ipa [global-options] automember-add AUTOMEMBER-RULE [options]

Add an automember rule.
Options:
  -h, --help            show this help message and exit
  --desc=STR            A description of this auto member rule
...
For more information about the ipa utility, see the ipa(1) man page.

5.3.2. Setting a List of Values

IdM stores entry attributes in lists. For example:
ipaUserSearchFields: uid,givenname,sn,telephonenumber,ou,title
Any update to a list of attributes overwrites the previous list. For example, an attempt to add a single attribute by only specifying this attribute replaces the whole previously-defined list with the single new attribute. Therefore, when changing a list of attributes, you must specify the whole updated list.
IdM supports the following methods of supplying a list of attributes:
  • Using the same command-line argument multiple times within the same command invocation. For example:
    $ ipa permission-add --permissions=read --permissions=write --permissions=delete
  • Enclosing the list in curly braces, which allows the shell to do the expansion. For example:
    $ ipa permission-add --permissions={read,write,delete}

5.3.3. Using Special Characters

When passing command-line arguments in ipa commands that include special characters, such as angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|), you must escape these characters by using a backslash (\). 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.

5.3.4. Searching IdM Entries

Listing IdM Entries

Use the ipa *-find commands to search for a particular type of IdM entries. For example:
  • To list all users:
    $ ipa user-find
    ---------------
    4 users matched
    ---------------
      ...
  • To list user groups whose specified attributes contain keyword:
    $ ipa group-find keyword
    ----------------
    2 groups matched
    ----------------
      ...
    To configure the attributes IdM searches for users and user groups, see Section 13.5, “Setting Search Attributes for Users and User Groups”.
When searching user groups, you can also limit the search results to groups that contain a particular user:
$ ipa group-find --user=user_name
You can also search for groups that do not contain a particular user:
$ ipa group-find --no-user=user_name

Showing Details for a Particular Entry

Use the ipa *-show command to display details about a particular IdM entry. For example:
$ ipa host-show server.example.com
 Host name: server.example.com
 Principal name: host/server.example.com@EXAMPLE.COM
 ...

5.3.4.1. Adjusting the Search Size and Time Limit

Some search results, such as viewing lists of users, can return a very large number of entries. By tuning these search operations, you can improve overall server performance when running the ipa *-find commands, such as ipa user-find, and when displaying corresponding lists in the web UI.
The search size limit:
  • Defines the maximum number of entries returned for a request sent to the server from a client, the IdM command-line tools, or the IdM web UI.
  • Default value: 100 entries.
The search time limit:
  • Defines the maximum time that the server waits for searches to run. Once the search reaches this limit, the server stops the search and returns the entries that discovered in that time.
  • Default value: 2 seconds.
If you set the values to -1, IdM will not apply any limits when searching.
Important
Setting search size or time limits too high can negatively affect server performance.

Web UI: Adjusting the Search Size and Time Limit

To adjust the limits globally for all queries:
  1. Select IPA ServerConfiguration.
  2. Set the required values in the Search Options area.
  3. Click Save at the top of the page.

Command Line: Adjusting the Search Size and Time Limit

To adjust the limits globally for all queries, use the ipa config-mod command and add the --searchrecordslimit and --searchtimelimit options. For example:
$ ipa config-mod --searchrecordslimit=500 --searchtimelimit=5
From the command line, you can also adjust the limits only for a specific query. To do this, add the --sizelimit or --timelimit options to the command. For example:
$ ipa user-find --sizelimit=200 --timelimit=120
Important
Note that adjusting the size or time limits using the ipa config-mod command with the --searchrecordslimit or the --searchtimelimit options affects the number of entries returned by ipacommands, such as ipa user-find.
In addition to these limits, the settings configured at the Directory Server level are also taken into account and may impose stricter limits. For more information on Directory Server limits, see the Red Hat Directory Server Administration Guide.