Product SiteDocumentation Site

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

B.2.1. Location

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

B.2.2. Syntax

ipa [ global_options ] commands [ command_options ]

B.2.3. Help Topics

All of the ipa 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.

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

B.2.5. Adding Attributes with --setattr and --addattr

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. Additionally, FreeIPA allows limited schema extensions for users and groups, and those custom schema elements are not reflected in the UI or command-line tools.
Most ipa allow the --setattr and --addattr options to define attributes and values explicitly.
Both options have this format:
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 --setattr=description="backup IT manager for the east coast branch"

B.2.6. Return Codes

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

B.2.7. Commands

Table B.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 B.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.