Product SiteDocumentation Site

C.2. ipa

The primary FreeIPA command-line tool is the ipa command. This command has several dozen subcommands, grouped by configuration areas, to give specific control over different areas of the FreeIPA domain configuration. These subcommands are really plug-ins, that are implemented and called through the ipa command.
One crucial feature of the ipa command is that it is pluggable. Custom behavior can be defined for the FreeIPA domain through custom ipa subcommands.

C.2.1. Location

Description Location
Tool directory /usr/bin
Package ipa-admintools

C.2.2. Syntax

ipa [ global_options ] commands [ command_options ]

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 FreeIPA.
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
All topic or command areas follow a consistent pattern for how entries are managed.

C.2.2.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 C.2.5, “Managing 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

C.2.2.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 use an asterisk (*) as a wildcard.
ipa user-find *smith
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 4.4.2, “Setting FreeIPA 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 *sen --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 are displayed with the entry unless the --all option is used.

C.2.2.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 FreeIPA 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.

C.2.2.4. 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

C.2.3. Help Topics

All of the ipa plug-ins (subcommands) are loosely organized in groups, based on the configuration area that they relate to. These groups are called topics, and the ipa help information can be called for each topic group.
$ ipa help topicName
For example, to view the description of how FreeIPA handles automount and a list of all commands for managing automount configuration, view the help topic for automount:
$ ipa help automount
Topic Description
automount Adding and managing automount and NFS configuration.
cert Managing certificate operations.
config Managing the FreeIPA server configuration.
delegation Setting and controlling authorization delegated between groups.
dns Creating and managing the DNS entries within the FreeIPA DNS domain.
group Creating groups of users.
hbac Setting and testing host-based access controls.
host Creating and managing client (host) entries within the FreeIPA domain.
hostgroup Creating and managing groups of hosts.
krbtpolicy Managing the Kerberos ticket policy.
migration Managing migration to FreeIPA.
misc Viewing current environment variables and plug-ins.
netgroup Managing netgroups within the FreeIPA domain.
passwd Managing user passwords.
permission Setting access control rules for users, groups, and roles within FreeIPA to FreeIPA resources.
privilege Managing a group of permissions.
pwpolicy Managing the FreeIPA domain password policy.
role Creating and managing user roles, as part of access control.
selfservice Managing rights that users have to their own personal FreeIPA entries.
service Creating and managing system services that are managed as an FreeIPA resource.
sudo Creating and managing sudo rules and policies.
user Creating and managing FreeIPA user accounts.

C.2.4. Global Options

Global options are available to every subcommand.
Short Option Long Option Description
-h --help Prints the help for the command and exits.
-e key=value Sets a given environment variable (key) to the specified value before running the command.
-c file Loads the server configuration from a different file instead of default.conf.
-d --debug Uses debug logging when running the command.
-v --verbose Prints verbose messages to stdout when running the command. If two -v options are used, then the command returns the full XML-RPC request.
-a --prompt-all Prompts for every argument for the command, even optional ones.
-n --no-prompt Does not prompt for any argument, even required ones.
-f --no-fallback Uses only the server specified in the local default.conf and does not fallback to another server if that one is unavailable.
--all For find and show commands. Returns all of the attributes for the entry, not just the ones related to the command or configuration area.
--raw For find and show commands. Returns the raw, LDIF-formatted LDAP entry instead of the friendly-formatted versions.
--addattr=attribute=value For add and mod commands. Adds a new attribute with the given value.
--setattr=attribute=value For add and mod commands. Replaces the value of a given attribute with the new value.

C.2.5. Managing Attributes with --setattr, --addattr, and --delattr

All identities and configuration in FreeIPA 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 use 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, FreeIPA 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.
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

C.2.6. Return Codes

Return Code Description
0 An error occurred.
1 The operation was successful.
2 A resource or object was not found.

C.2.7. Commands

Table C.1. dnsrecord* Commands
Command Description
dnsrecord-add Creates a new DNS zone in the FreeIPA server.
dnsrecord-del Deletes a DNS zone from the DNS domain maintained by the FreeIPA server.
dnsrecord-find Searches for a DNS zone which matches the filter.
dnsrecord-mod Edits the configuration of an existing DNS domain.
dnsrecord-show Lists the details for any or all DNS zones, depending on the filter

Table C.2. dnszone-* Commands
Command Description
dnszone-add Creates a new DNS zone in the FreeIPA server.
dnszone-del Deletes a DNS zone from the DNS domain maintained by the FreeIPA server.
dnszone-find Searches for a DNS zone which matches the filter.
dnszone-mod Edits the configuration of an existing DNS domain.
dnszone-show Lists the details for any or all DNS zones, depending on the filter
dnszone-disable Disables a DNS zone, which removes it from being used but does not delete the zone or its configuration.
dnszone-enable Enables an existing DNS zone, which restores it to the FreeIPA domain with its previous configuration intact.