ipa(1)

📦
version 4.13.4 · 5 versions
, in centos-stream 10, centos-stream 9, fedora 43, fedora 44, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 ipa — the IPA command-line interface 💖

okay bestie, welcome to ipa(1), straight out of the IPA Manual Pages ✨ this is the main character of FreeIPA admin tooling and she is booked and busy. let's get into it.

✨ SYNOPSIS ✨

ipa [options] [-c FILE] [-e KEY=VAL] COMMAND [parameters]

🌸 DESCRIPTION 🌸

IPA is an integrated security information management solution built on top of 389 Directory Server (which you might know by its old name, Fedora Directory Server), MIT Kerberos, Dogtag Certificate System and DNS. it ships with a web interface and command-line administration tools for wrangling all your identity data. it's giving full-stack identity management 💅

this manual page is specifically about the ipa script — the main command-line interface (CLI) for IPA administration. she's the one you'll be typing at 2am, no cap.

want the full lore? the project homepage lives at http://www.freeipa.org 🦋

🎀 OPTIONS 🎀

  • -c FILE — load configuration from FILE.
  • -d, --debug — produce full debugging output. all of it. the whole thing.
  • --delegate — delegate the user's TGT to the IPA server.
  • -e KEY=VAL — set environmental variable KEY to the value VAL. this option overrides configuration files, she does not play 🫶
  • -h, --help — display a help message with a list of options.
  • -n, --no-prompt — don't prompt for any parameters of COMMAND, even if they are required. bold move but okay.
  • -a, --prompt-all — prompt for all parameters of COMMAND, even if they are optional.
  • -f, --no-fallback — don't fall back to other IPA servers if the default doesn't work.
  • --force-server fqdn — specify the IPA server to connect to. overrides the default server in /etc/ipa/default.conf, and does not fall back to SRV if the server doesn't reply. requires a fully-qualified domain name.
  • -v, --verbose — produce verbose output. a second -v pretty-prints the JSON request and response. a third -v displays the HTTP request and response. yes, they stack, and yes, it gets spicy 🔥
  • --version — display the IPA version and API version.

👑 COMMANDS 👑

the principal function of the CLI is to execute administrative commands specified by the COMMAND argument. the majority of commands are executed remotely over XML-RPC on an IPA server listed in the configuration file (peep the FILES section of this manual page 💜).

from the implementation perspective, the CLI distinguishes two types of commands — built-ins and plugin provided.

built-in commands 💅

built-in commands are static and are available in all installations of IPA. there are two of them:

  • console — start the IPA interactive Python console. main character energy fr fr.
  • help [TOPIC | COMMAND | topics | commands] — display help for a command or topic. the help command invokes the built-in documentation system. without parameters, a list of built-in commands and help topics is displayed. help topics are generated from loaded IPA plugin modules. executing help with the name of an available topic displays a help message provided by the corresponding plugin module and the list of commands it contains.

plugin provided commands 🧚

plugin provided commands, as the name suggests, originate from IPA plugin modules. the available set may vary depending on your configuration, and can be listed using the built-in help command (see above ✨).

most plugin provided commands are tied to a certain type of IPA object. IPA objects encompass common abstractions such as users (user identities/accounts), hosts (machine identities), services, password policies, etc. commands associated with an object are easily identified thanks to the enforced naming convention — the command names are composed of two parts separated with a dash: the name of the corresponding IPA object type, and the name of the action performed on it. for example, all commands used to manage user identities start with user- (e.g. user-add, user-del). iykyk 🎀

the following actions are available for most IPA object types:

  • add [PRIMARYKEY] [options] — create a new object.
  • show [PRIMARYKEY] [options] — display an existing object.
  • mod [PRIMARYKEY] [options] — modify an existing object.
  • del [PRIMARYKEY] — delete an existing object.
  • find [CRITERIA] [options] — search for existing objects.

the above types of commands except find take the object's primary key (e.g. user name for users) as their only positional argument, unless there can be only one object of the given type. they can also take a number of options (some of which might be required in the case of add) that represent the object's attributes.

find commands take an optional criteria string as their only positional argument. if present, all objects with an attribute that contains the criteria string are displayed. if an option representing an attribute is set, only objects with the attribute exactly matching the specified value are displayed. options with empty values are ignored. without parameters, all objects of the corresponding type are displayed.

member commands 🦋

for IPA objects with attributes that can contain references to other objects (e.g. groups), the following actions are usually available:

  • add-member [PRIMARYKEY] [options] — add references to other objects.
  • remove-member [PRIMARYKEY] [options] — remove references to other objects.

the above types of commands take the object's primary key as their only positional argument, unless there can be only one object of the given type. they also take a number of options that represent lists of other object primary keys. each of these options represents one type of object.

heads up bestie 🫶 for some types of objects, these commands might need to take more than one primary key. this applies to IPA objects organized in hierarchies, where the parent object needs to be identified first. parent primary keys are always aligned to the left (higher in the hierarchy = more to the left). for example, the automount IPA plugin enables users to manage automount maps per location — as a result, all automount commands take an automountlocation primary key as their first positional argument.

output control options 💖

all commands that display objects have three special options for controlling output:

  • --all — display all attributes. without this option, only the most relevant attributes are displayed.
  • --raw — display objects as they are stored in the backing store. disables formatting and attribute labels.
  • --rights — display effective rights on all attributes of the entry. you also have to specify --all for this to work. user rights are returned as a Python dictionary where the index is the name of an attribute and the value is a unicode string composed (hence the u'xxxx' format) of the letters specified below. note that user rights are primarily used for internal purposes of the CLI and WebUI.
    • r — read
    • s — search
    • w — write
    • o — obliterate (delete)
    • c — compare
    • W — self-write
    • O — self-obliterate

🌈 AUDIT AND LOGGING 🌈

the IPA API logs audit messages to the systemd journal about each command executed through the IPA API on the IPA server. you can find these messages by grepping the systemd journal with journalctl -g IPA.API command. the message includes the following information:

May 21 11:31:33 master1.ipa1.test /usr/bin/ipa[247422]: [IPA.API]
[autobind]: user_del: SUCCESS [ldap2_140328582446688] {"uid":
["foobar"], "continue": false, "version": "2.253"}
  • /usr/bin/ipa[247422] — executable name and PID (/mod_wsgi for HTTP end-point).
  • [IPA.API] — marker to allow searches with journalctl -g IPA.API.
  • username@REALM — authenticated Kerberos principal, or the [autobind] marker for LDAP-based operations done as root.
  • user_del — name of the command executed.
  • SUCCESS — result of execution: SUCCESS or an exception name.
  • [ldap2_140328582446688] — LDAP backend connection instance identifier. the identifier will be the same for all operations performed under the same request. this allows you to identify operations which were executed using the same LDAP connection. for API operations that didn't result in LDAP access, there will be a [no_connection_id] marker.
  • {"uid": ["foobar"], "continue": false, "version": "2.253"} — a list of arguments and options passed to the IPA API command, provided in JSON format. credentials are filtered out. 🙈

all explicitly requested operations are logged. internal operations, initiated as part of execution of the explicitly requested IPA API calls, aren't logged. for the HTTP end-point, operations will be logged as performed by the /mod_wsgi executable binary. remaining details can be inspected through the systemd journal, as journald records execution context. see systemd.journal-fields(7) for details. ✨

the details of the individual logged messages can be explained with the help of the journalctl -x command, while the full set of logged properties can be retrieved with journalctl -o json-pretty. see journalctl(1) for details on the systemd journal viewer.

for the sample message above, an explanation could be requested with journalctl -x -g ldap2_140328582446688, where the LDAP backend connection instance identifier can be used to uniquely fetch that individual message. slay 💅

✨ EXAMPLES ✨

okay bestie, example time 💖 these are the exact little commands you'll be running, and I'm gonna walk you through every single one. no cap, no skips.

ipa help commands

Shows you a list of all the available commands. It's giving "menu of everything you can do," and it's lowkey iconic. 🌸

ipa help topics

Shows you a high-level list of help topics. The vibe check before you dive deep. ✨

ipa help user

Shows you the documentation and the list of commands in the "user" topic. So all the user-related stuff is right there. 🫶

ipa env

Lists IPA environmental variables and their values. Basically a peek at your current environment, no cap. 🌈

ipa user-add foo --first foo --last bar

Creates a new user with username "foo", first name "foo" and last name "bar". Main character creation moment. 👑

ipa group-add bar --desc "this is an example group"

Creates a new group with name "bar" and description "this is an example group". The description is in quotes, keep it cute and exact. 💅

ipa group-add-member bar --users=foo

Adds user "foo" to the group "bar". One user, one group, slay. ✨

ipa group-add-member bar --users={admin,foo}

Adds users "admin" and "foo" to the group "bar". This approach depends on shell expansion feature. iykyk, that's shell expansion feature doing its thing. 🪄

ipa user-show foo --raw

Displays user "foo" as (s)he is stored on the server. Raw means raw, bestie — no prettying it up. 🙈

ipa group-show bar --all

Displays group "bar" and all of its attributes. Every single attribute, periodt. 👑

ipa config-mod --maxusername 20

Sets maximum user name length to 20 characters. Short and sweet, fr fr. 🍓

ipa user-find foo

Searches for all users with "foo" in either uid, first name, last name, full name, etc. A user with uid "foobar" would match the search criteria. So it's a broad vibe check. 🔥

ipa user-find foo --first bar

Same as the previous example, except this time the user's first name has to be exactly "bar". A user with uid "foobar" and first name "bar" would match the search criteria. More specific, still cute. 💖

ipa user-find foo --first bar --last foo

A user with uid "foobar", first name "bar" and last name "foo" would match the search criteria. That's the combo, bestie. 🎀

ipa user-find

All users would match the search criteria (as there are none). Yes literally all zero of them, it's giving "everyone and no one" 😭💀

🖥️ SERVERS 🖥️

okay so the ipa client is gonna figure out which server to connect to in this exact order:

  1. The server configured in /etc/ipa/default.conf in the xmlrpc_uri directive.
  2. An unordered list of servers from the ldap DNS SRV records.

If a kerberos error is raised by any of the requests then it will stop processing and display the error message. So no silent struggling, it just tells you. 💅

🌈 ENVIRONMENT VARIABLES 🌈

  • IPA_CONFDIR — Override path to confdir (default: /etc/ipa).

📁 FILES 📁

  • /etc/ipa/default.conf — IPA default configuration file.

🚦 EXIT STATUS 🚦

  • 0 — if the command was successful ✅
  • 1 — if an error occurred 😭
  • 2 — if an entry is not found 👀

👀 SEE ALSO 👀

bestie, here's the whole squad of related pages — every single one, no gatekeeping:

that's a wrap on the ipa(1) page from IPA, dated Apr 29 2016 🫶💖 periodt, bestie. go run some commands and slay. ✨

📦 where this page comes from