8.2. About the IdM Client Tools
IdM creates a domain of recognized services, host machines, and users with universally-applied authentication sources and common policies. From the perspective of a client machine and an IdM user, the domain itself is fairly transparent after the initial configuration. All users need to do is log into the domain using Kerberos, and that's it.
However, an administrator has two ongoing tasks: add principals to the IdM Kerberos domain and set the domain policies and server configuration that govern domain interactions. Identity Management has both command-line and web-based interfaces for administrators to use to manage the domain, services, and IdM entries.
The most common method to maintain the domain is using the command-line tools. Identity Management has an incredibly broad set of scripts and commands that are available to administrators. The entry management functions of the domain are carried out with a single script:
ipa. This script is a parent or control script for associated subcommands; each subcommand relates to a specific entry type.
The command-line scripts offer a number of benefits:
- The scripts allow management tasks to be automated and performed repeatedly in a consistent way without manual intervention.
- Entries can be added with all possible attributes configured (or a desired subset of attributes) in a single step. The web UI frequently requires two steps to fully configure an entry: the first to create the entry and the next to add optional attributes.
- The command-line scripts support adding additional attributes which may not be available in the UI or even custom attributes to entries, if the schema is configured.
8.2.1. The Structure of the ipa Command
The
ipa command is essentially a big plug-in container. It supports dozens of subcommands; these subcommands are actually plug-ins which manage specific types of objects in Identity Management.
The first type of a subcommand identifies the object type (such as user, sudo, group, host, or dns), and the second part identifies the operation being performed on that object.
ipa objectType-operation objectName --option=value
For example, adding a user is done using the
user-add subcommand:
ipa user-add entryName options
Related subcommands are grouped together into plug-in modules. Commands for managing DNS entries like
dnszone-add and dnsrecord-add all belong to the dns module or topic. All of the information for managing a specific area, with all of the supported commands and examples for each, are available by viewing the help for that topic:
ipa help topic
Note
To get a list of all available topics:
ipa help topics
All topic or command areas follow a consistent pattern for how entries are managed.
8.2.1.1. Adding, Editing, and Deleting Entries with ipa
New entries are added using an *-add command. For example:
$ ipa user-add jsmith
For
add operations, commands usually prompt for any required configuration attributes, which can be passed as command-line options or using --set/addattr options (Section 8.2.3, “Managing Entry Attributes with --setattr, --addattr, and --delattr”).
$ ipa user-add First name: John Last name: Smith User login [jsmith]: jsmith -------------------- Added user "jsmith" -------------------- ...
Likewise, entries are usually edited through a
*-mod commands, and then any new or edited attributes are listed as options after it.
$ ipa user-mod jsmith --title="Editor III"
Last, entries can be deleted using the
*-del command and the entry's name.
$ ipa user-del jsmith
8.2.1.2. Finding and Displaying Entries with ipa
Entries for an entire type are searched for using the
*-find command and an optional search criterion. The criterion is a string which can either be an exact match or a substring of any of the search attribute values. For example, this searches both for the exact match on the string smith (such as an sn value of Smith) and a substring search for values such as a username of jsmith or a longer surname, such as Smithson.
ipa user-find smith
All searches are automatically substring searches; it is not necessary to specify a wildcard.
With no search criterion, every entry of that type is displayed.
Searches (any
*-find command) have certain limits imposed as part of the server configuration, specifically how many entries are returned (size limits) and how long a search will run (time limits). This is covered in Section 9.11.3.1.2, “Setting IdM Search Limits”. Part of the server configuration is setting global defaults for size and time limits on searches. While these limits are always enforced in the web UI, they can be overridden with any *-find command with the --sizelimit and --timelimit options. For example, if the default time limit is 60 seconds and a search is going to take longer, the time limit can be increased to 120 seconds:
[jsmith@ipaserver ~]$ ipa user-find smith --timelimit=120
Not every possible attribute in an entry type can be searched for. A certain subset of attributes are predefined and indexed for searches. (This list is configurable for users and groups, but not for other types of entries.)
When entries are returned, only certain default attributes are displayed with the entry; to return all attributes currently set for entries, use the
--all option.
To display a specific entry, use the
*-show command and the entry name. As with searches, only a subset of attributes is displayed with the entry unless the --all option is used.
8.2.1.3. Adding Members to Groups and Containers with ipa
Group members are added and removed with separate commands, apart from simply modifying an entry. Member commands essentially create a relationship between different IdM entries. While this is obvious in traditional group-member roles, it is also true for some policy entries (like SELinux and sudo policies) where entries are associated with another entry.
Most commonly, the command format for adding a member entry is
*-add-member, although the command may specify an entry type, such as *-add-user.
Likewise, entries are removed as members (not deleted) using a
*-remove-member or *-remove-type command.
8.2.2. Positional Elements in ipa Commands
Usually,
ipa subcommands have only two elements: the name of the entry being modified (the object) and then any options available for the subcommand:
ipa command entryName --options=values
With a few types of entries, however, not only the entry name itself needs to be specified; the entry's parent must also be specified. This is the case with
automount commands, for example. With automount, the location must be included whenever a new key or map is created.
The parent entry name is given first, and then the child entry name. For example, for automount, the location is given first, and then the map or key entry name.
ipa command parentEntryName childEntryName --childOptions=childValues
8.2.3. Managing Entry Attributes with --setattr, --addattr, and --delattr
All identities and configuration in Identity Management are stored as LDAP entries, with standard attribute-value assertions (AVAs). Whether an entry is created through the UI or the CLI, there are certain attributes which are required and others which are available, depending on the default and custom object classes for that entry type.
For the most common attributes, the
ipa command uses specified command-line arguments to set values. For example, adding a mail attribute to a user can be done with the --mail argument; enabling dynamic updates for a DNS zone can be done with the --allow-dynupdate option with zone commands; and a map key for an automount map is given in the --key option.
However, entries can also allow attributes that may not have command-line (or UI) options for setting them. Partially, this is because the underlying LDAP schema is very rich, particularly for user entries, with many possible allowed attributes. Additionally, Identity Management allows schema extensions for users and groups, and those custom schema elements are not necessarily reflected in the UI or command-line tools.
Any supported attribute can be added or edited to an entry using the
--setattr and --addattr options.
Important
The value of the attribute being added is not validated by the modify command or the
--setattr or --addattr options.
Both options have this format:
--setattr=attribute=value
The
--setattr option sets one value for the given attribute; any existing values are overwritten, even for multi-valued attributes.
The
--addattr option adds a new value for an attribute; for a multi-valued attribute, it adds the new value while preserving any existing values.
Both
--setattr option and --addattr can be used multiple times in the same command invocation. For example:
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com --addattr=mail=jsmith@example.com --setattr=description="backup IT manager for the east coast branch"
Likewise, an attribute or specific attribute value can be removed from an entry using the
--delattr option. For a single-valued attribute, this removes the attribute; for a multi-valued attribute, it removes only the specified value. For example:
$ ipa user-mod jsmith --delattr=mail=johnnys@me.com
Note
Deleting attributes is evaluated last, after adding or editing attributes. If the same attribute is added and deleted in the same modify operation, it is a no-op.
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com --delattr=mail=johnnys@me.com
8.2.4. Using Special Characters with IdM Tools
The IdM command-line tools are run as any other utilities in a shell. If there are special characters in the command — such as angle brackets (> and <), ampersands (&), asterisks (*), and pipes (|) — the characters must be escaped. Otherwise, the command fails because the shell cannot properly parse the unescaped characters.
8.2.5. Logging into the IdM Domain Before Running
Before running any IdM commands (with the exception of the installation scripts, such as
ipa-server-install), the user must first authenticate to the IdM domain by obtaining a Kerberos ticket. This is done using kinit:
[jsmith@ipaserver ~]$ kinit admin
Different login options are described in Section 8.3, “Logging into IdM”.
