Product SiteDocumentation Site

Chapter 4. Basic Usage

4.1. About the FreeIPA Client Tools
4.1.1. About the FreeIPA Command-Line Tools
4.1.2. Looking at the FreeIPA UI
4.2. Logging into FreeIPA
4.2.1. Logging into FreeIPA
4.2.2. Logging in When an FreeIPA User Is Different Than the System User
4.2.3. Checking the Current Logged in User
4.2.4. Caching User Kerberos Tickets
4.3. Using the FreeIPA Web UI
4.3.1. Supported Web Browsers
4.3.2. Opening the FreeIPA Web UI
4.3.3. Configuring the Browser
4.3.4. Using a Browser on Another System
4.3.5. Logging in with Simple Username/Password Credentials
4.3.6. Using the UI with Proxy Servers
4.3.7. Troubleshooting UI Connection Problems
4.4. Understanding Search Limits and Settings
4.4.1. Types of Search Limits and Where They Apply
4.4.2. Setting FreeIPA Search Limits
4.4.3. Overriding the Search Defaults
4.4.4. Setting Search Attributes
4.4.5. Attributes Returned in Search Results
All of the access to FreeIPA, both through the web UI and through the command line, is done by a user authenticating to the FreeIPA domain. This chapter covers the basics of setting up browsers to handle Kerberos authentication, logging into FreeIPA, and troubleshooting some common connection issues.

4.1. About the FreeIPA Client Tools

FreeIPA 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 a FreeIPA 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 FreeIPA Kerberos domain and set the domain policies and server configuration that govern domain interactions. FreeIPA has both command-line and web-based interfaces for administrators to use to manage the domain, services, and FreeIPA entries.

4.1.1. About the FreeIPA Command-Line Tools

The most common method to maintain the domain is using the command-line tools. FreeIPA 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.

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

TIP

To get a list of all available topics, run the help command without a topic name:
ipa help
All topic or command areas follow a consistent pattern for how entries are managed.
4.1.1.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 4.1.1.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
4.1.1.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 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.
4.1.1.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 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.

4.1.1.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 chidlEntryName --childOptions=childValues

4.1.1.3. Managing Entry 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

4.1.1.4. Using Special Characters with FreeIPA Tools

The FreeIPA 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.

4.1.1.5. Logging into the FreeIPA Domain Before Running

Before running any FreeIPA commands (with the exception of the installation scripts, such as ipa-server-install), the user must first authenticate to the FreeIPA domain by obtaining a Kerberos ticket. This is done using kinit:
[jsmith@ipaserver ~]$ kinit admin
Different login options are described in Section 4.2, “Logging into FreeIPA”.

4.1.2. Looking at the FreeIPA UI

The FreeIPA web UI is designed for simplicity. This was the primary design goal, and this means that the web UI offers benefits that make using FreeIPA simpler and clearer:
  • It shows instant, visual relationships between entries (such as a user and all the groups, sudo rules, netgroups, and policies which are associated with that user).
  • All entries are listed immediately without having to run a search. This makes it possible to browse entries. The UI also has a simple search box which quickly filters the list of entries.
  • The interface is intuitive to use, without having to learn the command-line tools.
  • The web UI can be accessed from machines outside the FreeIPA domain, so the domain can be managed from anywhere.
    Using the web UI requires a valid Kerberos ticket for the FreeIPA domain (by default), meaning that it can only be accessed from a machine within the FreeIPA domain. Alternatively, the web UI can be configured to allow password authentication along with Kerberos authentication, or a machine outside the FreeIPA can be configured to work with Kerberos (Section 4.3.4, “Using a Browser on Another System”).

4.1.2.1. The UI Layout

The web UI has three major functional areas which correspond to each of the major functions of FreeIPA: identity management, policy management, and domain configuration.
Table 4.1. Configuration Areas Per Tab
Main Menu Tab Configuration Areas
Identity
  • User entries
  • User groups entries
  • Host/client entries
  • Host group entries
  • Netgroups entries
  • Domain services entries
  • DNS (if configured)
Policy
  • Host-based access control
  • Sudo rules
  • Automount
  • User password policies
  • Kerberos ticket policy
FreeIPA Server (access controls within FreeIPA)
  • Role-based access control (permissions based on group membership)
  • Self permissions
  • Delegations (user access control over other users)

The main menu at the top of every page has three tabs which correspond to the functional areas listed in Table 4.1, “Configuration Areas Per Tab”. When a tab is selected, there is a submenu of the different configuration areas. Some configuration areas may have multiple possible entries; for example, role-based access controls define user roles/groups, the areas that access can be granted or denied (privileges), and then the permissions granted to those areas. Each separate configuration entry has its own task area beneath the primary configuration area.
The Main Menu
Figure 4.1. The Main Menu

All entries for a configuration area are listed together on the main page for that area. This page provides direct links to individual entry pages, as well as basic information (the attributes) about the entry. (This is usually just the description, but user entries show a lot more information.)
The page also has some tasks that can be performed on it. For a list page that shows entries, this can be creating or deleting an entry. For a list page for groups, the tasks are for establishing relationships between entities, either by adding (enrolling) or removing an entity from that group. Both individual entries and groups can be searched for through the list page.
List View
Figure 4.2. List View

Each entry page is a form which allows that entry to be edited. This is done by editing text fields or by selecting items from drop-down menus.
Form/Entry View
Figure 4.3. Form/Entry View

4.1.2.2. Page Elements

The web UI uses common elements on all pages.
The most basic is that all blue text is a link to an entry or to an action.
When a task like adding an entry or saving a change is possible, the task link is blue. When it is not possible (such as no items have been selected to be deleted) then the task is grayed out.

All list pages display direct links to entry pages. However, some entries are essentially nested. For example, in automount configuration, the primary entry is the location, and then keys, mount points, and maps are associated with that location as children entries. This hierarchy is reflected in breadcrumb navigation near the top of the page, so it is easy to identify where you are in the UI and how this entry relates to any other related entries.
Entry Breadcrumbs
Figure 4.5. Entry Breadcrumbs

Most entries have a variety of different configuration areas. A simple user entry has account activity settings, personal information, address information, organizational information, and other contact information. Related attributes are grouped together logically in the UI. These entry form areas can be collapsed or expanded using the arrows to control the amount of information displayed on the page.
Collapsing and Expanding Form Elements
Figure 4.6. Collapsing and Expanding Form Elements

When entries are created, they are added with only the required attributes. Additional attributes can be added manually. Some attributes have default values added to the entry and simply need to be edited; other attributes may not exist at all in the new entry and need to be added.
Add an Attribute
Figure 4.7. Add an Attribute

Any changes to any attribute can be undone. A single attribute change can be undone by clicking the dynamic undo button; all changes can be undone by clicking the Reset link at the top of the entry details page.
Undo Edits
Figure 4.8. Undo Edits

4.1.2.3. Showing and Changing Group Members

Members can be added to a group through the group configuration. There are tabs for all the member types which can belong to the group, and an administrator picks all of the marching entries and adds them as members.
However, it is also possible for an entity to be added to a group through its own configuration. Each entry has a list of tabs that displays group types that the entry can join. The list of all groups of that type are displayed, and the entity can be added to multiple groups at the same time.
Member Of...
Figure 4.9. Member Of...