Fedora 15 FreeIPA Guide en US

Fedora 15

FreeIPA: Identity/Policy Management

Managing Identity and Authorization Policiesfor Linux-Based Enterprise Networks

Ella Deon Lackey


Fedora 15 FreeIPA: Identity/Policy ManagementManaging Identity and Authorization Policies for Linux-BasedEnterprise NetworksEdition 0.1

Author Ella Deon Lackey [email protected]

Copyright © 2011 Red Hat.

The text of and illustrations in this document are licensed by Red Hat under a Creative CommonsAttribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is availableat http://creativecommons.org/licenses/by-sa/3.0/. The original authors of this document, and Red Hat,designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance withCC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for theoriginal version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the InfinityLogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

For guidelines on the permitted uses of the Fedora trademarks, refer to https://fedoraproject.org/wiki/Legal:Trademark_guidelines.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

All other trademarks are the property of their respective owners.

Identity and policy management — for both users and machines — is a core function for almost anyenterprise environment. IPA provides a way to create an identity domain that allows machines to enrollto a domain and immediately access identity information reuqired for single sign-on and authenticationservices, as well as policy settings that govern authorization and access. This manual covers allaspects of installing, configuring, and managing IPA domains, including both servers and clients. Thisguide is intended for IT and systems administrators.

mailto:[email protected]

http://creativecommons.org/licenses/by-sa/3.0/

https://fedoraproject.org/wiki/Legal:Trademark_guidelines

https://fedoraproject.org/wiki/Legal:Trademark_guidelines

iii

Preface ix1. Audience and Purpose ................................................................................................... ix2. Examples and Formatting ............................................................................................... ix

2.1. Brackets .............................................................................................................. ix2.2. Client Tool Information ......................................................................................... ix2.3. Text Formatting and Styles ................................................................................... x

3. Giving Feedback ............................................................................................................. x4. Document Change History .............................................................................................. xi

1. Installing a FreeIPA Server 11.1. Preparing to Install the FreeIPA Server .......................................................................... 1

1.1.1. Hardware Requirements .................................................................................... 11.1.2. Software Requirements ...................................................................................... 11.1.3. System Prerequisites ......................................................................................... 2

1.2. Installing the FreeIPA Server Packages ......................................................................... 51.3. Creating a FreeIPA Server Instance .............................................................................. 5

1.3.1. About ipa-server-install ...................................................................................... 61.3.2. Setting up a FreeIPA Server: Basic Interactive Installation .................................... 91.3.3. Examples of Creating the FreeIPA Server ......................................................... 111.3.4. Troubleshooting Installation Problems ............................................................... 15

1.4. Setting up FreeIPA Replicas ....................................................................................... 151.4.1. Prepping and Installing the Replica Server ........................................................ 161.4.2. Creating the Replica ........................................................................................ 161.4.3. Troubleshooting Replica Installation .................................................................. 18

1.5. Uninstalling FreeIPA Servers and Replicas .................................................................. 18

2. Setting up Systems as FreeIPA Clients 192.1. What Happens in Client Setup .................................................................................... 192.2. Configuring a Fedora System as a FreeIPA Client ........................................................ 202.3. Configuring a Microsoft Windows System as a FreeIPA Client ....................................... 222.4. Configuring a Solaris System as a FreeIPA Client ........................................................ 23

2.4.1. Configuring Solaris 10 ...................................................................................... 232.4.2. Configuring Solaris 9 ....................................................................................... 25

2.5. Configuring an HP-UX System as a FreeIPA ................................................................ 252.5.1. Configuring NTP .............................................................................................. 252.5.2. Configuring LDAP Authentication ...................................................................... 252.5.3. Configuring Kerberos ....................................................................................... 272.5.4. Configuring PAM .............................................................................................. 272.5.5. Configuring SSH .............................................................................................. 302.5.6. Configuring Access Control .............................................................................. 312.5.7. Testing the Configuration .................................................................................. 31

2.6. Configuring an AIX System as a FreeIPA Client ........................................................... 322.6.1. Prerequisites ................................................................................................... 322.6.2. Configuring the AIX Client ................................................................................ 32

2.7. Configuring a Macintosh OS X System as a FreeIPA Client ........................................... 362.7.1. Configuring Kerberos Authentication ................................................................. 362.7.2. Configuring LDAP Authorization ........................................................................ 372.7.3. Configuring the LDAP Authorization Options ...................................................... 392.7.4. Configuring NTP .............................................................................................. 392.7.5. Testing the Configuration .................................................................................. 39

2.8. Uninstalling a FreeIPA Client ....................................................................................... 40

3. Basic Usage 413.1. Running FreeIPA Tools ............................................................................................... 413.2. Logging into FreeIPA .................................................................................................. 41


iv

3.2.1. Logging into FreeIPA ....................................................................................... 413.2.2. Logging in When an FreeIPA User Is Different Than the System User .................. 413.2.3. Checking the Current Logged in User ............................................................... 42

3.3. Opening the FreeIPA Web UI ...................................................................................... 423.4. Configuring the Browser ............................................................................................. 423.5. Using a Browser on Another System ........................................................................... 443.6. Enabling Username/Password Authentication in Your Browser ...................................... 443.7. Troubleshooting UI Connection Problems .................................................................... 45

4. Identity: Managing Users and User Groups 474.1. Setting up User Home Directories ............................................................................... 47

4.1.1. About Home Directories ................................................................................... 474.1.2. Enabling the PAM Home Directory Module ........................................................ 474.1.3. Manually Automounting Home Directories ......................................................... 48

4.2. Adding Users ............................................................................................................. 484.3. Editing Users ............................................................................................................. 504.4. Activating and Deactivating User Accounts .................................................................. 50

4.4.1. Using the Command Line ................................................................................. 504.5. Specifying Default User Settings ................................................................................. 504.6. Setting Default Search Limits ...................................................................................... 514.7. Deleting FreeIPA Users .............................................................................................. 53

4.7.1. Using the Command Line ................................................................................. 534.8. Creating User Groups ................................................................................................. 53

4.8.1. Creating FreeIPA Groups ................................................................................. 544.8.2. Editing FreeIPA Groups ................................................................................... 554.8.3. Deleting FreeIPA Groups ................................................................................. 56

4.9. Setting an Individual Password Policy .......................................................................... 564.9.1. Changing Passwords as the Directory Manager ................................................. 564.9.2. Changing Passwords as the FreeIPA Administrator ............................................ 564.9.3. Changing Passwords as a Regular User ........................................................... 574.9.4. Editing the Password Policy ............................................................................. 574.9.5. Setting Different Password Policies for Different User Groups ............................. 574.9.6. Password Policy Attributes ............................................................................... 604.9.7. Notifying Users of Password Expiration ............................................................. 614.9.8. Using SSH for Password Authentication ............................................................ 624.9.9. Using Local Logins .......................................................................................... 62

4.10. Searching for Users and Groups ............................................................................... 624.10.1. Searching for Users ....................................................................................... 634.10.2. Searching for Groups ..................................................................................... 64

5. Identity: Managing Hosts and Host Groups 655.1. A Summary of Host and Host Group Tools .................................................................. 655.2. Adding Host Entries .................................................................................................... 655.3. Extending the Permissions of FreeIPA Managed Hosts ................................................. 65

5.3.1. Delegating Service Management ...................................................................... 665.3.2. Delegating Host Management .......................................................................... 66

6. Identity: Using FreeIPA for a Kerberos Domain 696.1. About Kerberos .......................................................................................................... 696.2. Setting Kerberos Ticket Policies .................................................................................. 716.3. Creating and Using Service Principals ......................................................................... 71

6.3.1. Creating a FreeIPA Service .............................................................................. 726.3.2. Configuring an NFS Service Principal on the FreeIPA Server .............................. 74

6.4. Refreshing Kerberos Tickets ....................................................................................... 766.5. Rotating Keys ............................................................................................................ 77

v

6.6. Kerberos Errors .......................................................................................................... 78

7. Identity: Using Automount 797.1. About Automount and IPA ........................................................................................... 79

7.1.1. Known Issues with Automount .......................................................................... 797.1.2. Assumptions .................................................................................................... 79

7.2. Configuring Automount ............................................................................................... 797.2.1. Configuring autofs on Linux .............................................................................. 807.2.2. Solaris automount ............................................................................................ 807.2.3. Configuring Indirect Maps ................................................................................ 817.2.4. Links ............................................................................................................... 83

8. Identity: Integrating with Microsoft Active Directory 858.1. About Active Directory, IPA, and Identity Management .................................................. 85

8.1.1. Domain Name Considerations .......................................................................... 858.2. Setting up Active Directory .......................................................................................... 858.3. Configuring Active Directory Synchronization ............................................................... 868.4. Creating Synchronization Agreements ......................................................................... 878.5. Modifying Synchronization Agreements ........................................................................ 88

8.5.1. Changing the Default Synchronization Subtree .................................................. 888.6. Deleting Synchronization Agreements .......................................................................... 898.7. Winsync Agreement Failures ....................................................................................... 89

9. Identity: Integrating with NIS Domains and Netgroups 919.1. About NIS and IPA ..................................................................................................... 91

9.1.1. What are Netgroups? ....................................................................................... 919.1.2. The IPA Approach to Netgroups ....................................................................... 919.1.3. Adding Netgroups ............................................................................................ 939.1.4. IPA Netgroup Commands ................................................................................. 93

9.2. Configuring the Network Information Service (NIS) ....................................................... 959.2.1. Exposing Automount Maps to NIS Clients ......................................................... 95

9.3. Migrating from NIS to IPA ........................................................................................... 969.3.1. Preparing Your Environment ............................................................................. 979.3.2. Migrating Netgroups ......................................................................................... 97

10. Policy: Managing DNS 9910.1. About DNS in FreeIPA .............................................................................................. 9910.2. Configuring DNS ..................................................................................................... 10010.3. Finding and Displaying DNS Zones ......................................................................... 10010.4. Adding DNS Zones ................................................................................................. 10110.5. Modifying DNS Zones ............................................................................................. 10110.6. Enabling Dynamic DNS Updates ............................................................................. 10310.7. Enabling and Disabling Zones ................................................................................. 10310.8. Adding Records to DNS Zones ................................................................................ 10310.9. Deleting Records from DNS Zones .......................................................................... 10510.10. Resolving Hostnames in the FreeIPA Domain ......................................................... 105

11. Policy: Configuring Authorization 10711.1. Configuring Host-Based Access Control ................................................................... 10711.2. HBAC Service Groups ............................................................................................ 10711.3. HBAC Services ....................................................................................................... 107

12. Policy: Using sudo 10912.1. About sudo and IPA ................................................................................................ 109

12.1.1. Sudo with LDAP .......................................................................................... 10912.1.2. Limitations of the Existing Sudo LDAP Schema .............................................. 10912.1.3. Benefits of the IPA Alternative Schema ......................................................... 109


vi

12.1.4. Compatibility and Managed Entry Plug-in Configuration .................................. 11012.2. Configuring sudo .................................................................................................... 110

12.2.1. Server Configuration for Sudo Rules ............................................................. 11012.2.2. Client Configuration for Sudo Rules .............................................................. 112

13. Configuring the FreeIPA Server 11513.1. Defining Access Controls within FreeIPA .................................................................. 115

13.1.1. Server-side Access Control .......................................................................... 11513.1.2. Creating Roles ............................................................................................. 11813.1.3. Defining Self-Service Settings ....................................................................... 119

13.2. Disabling Anonymous Binds .................................................................................... 12013.3. Managing Unique UID and GID Number Assignments ............................................... 120

13.3.1. About ID Range Assignments During Installation ............................................ 12113.3.2. Adding New Ranges .................................................................................... 121

13.4. Configuring Certificates and Certificate Authorities .................................................... 12113.4.1. Installing Your Own Certificate ...................................................................... 12213.4.2. Using Your Own Certificate with Firefox ......................................................... 12213.4.3. Using OCSP ................................................................................................ 122

13.5. Setting a FreeIPA Server as an Apache Virtual Host ................................................. 12213.6. Using FreeIPA in a Cluster ...................................................................................... 123

13.6.1. Configuring Kerberos Credentials for a Clustered Environment ........................ 12413.6.2. Using the Same Service Principal for Multiple Services ................................... 124

13.7. FreeIPA Server Logging .......................................................................................... 12413.8. Promoting a Read-Only Replica to a FreeIPA Server ................................................ 12513.9. Testing Before Upgrading the FreeIPA Server ........................................................... 126

14. Managing Client Machines in the FreeIPA Domain 12714.1. About Machine Identity and Authentication ............................................................... 12714.2. Enrolling Clients Manually ....................................................................................... 128

14.2.1. Performing a Split Enrollment ....................................................................... 12814.2.2. Performing a Bulk or Kickstart Enrollment ...................................................... 128

14.3. Renaming Machines and Reconfiguring FreeIPA Client Configuration ......................... 12914.4. Manually Unconfiguring Client Machines .................................................................. 13014.5. Debugging Client Connection Problems ................................................................... 13114.6. Working with certmonger ......................................................................................... 132

14.6.1. Requesting a Certificate with certmonger ....................................................... 13214.6.2. Storing Certificates in NSS Databases .......................................................... 13314.6.3. Tracking Certificates with certmonger ............................................................ 133

A. Frequently Asked Questions 135Frequently Asked Questions ............................................................................................ 135

B. Migrating from a Directory Server to IPA 137B.1. Overview ................................................................................................................. 137

B.1.1. Assumptions .................................................................................................. 137B.1.2. Known Issues ................................................................................................ 137B.1.3. Possible Scenarios ........................................................................................ 137B.1.4. Initial and Final States ................................................................................... 138B.1.5. Recommended Sequence of Steps ................................................................. 140B.1.6. Implementation Details ................................................................................... 141

B.2. Performing a Server-based Migration ........................................................................ 141B.2.1. Phase 1: Migrating Existing Data to IPA .......................................................... 141B.2.2. Phase 2: Updating the Client Configuration ..................................................... 142B.2.3. Phase 3: Installing and Configuring SSSD ...................................................... 143B.2.4. Phase 4: Migrating Users ............................................................................... 143B.2.5. Phase 5: Decommission the DS ..................................................................... 143

vii

B.3. Performing a Client-based Migration .......................................................................... 143B.3.1. Phase 1: Installing and Configuring SSSD ...................................................... 143B.3.2. Phase 2: Migrating Existing Data to IPA .......................................................... 144B.3.3. Phase 3: Migrate SSSD Clients from LDAP to IPA ........................................... 144B.3.4. Phase 4: Reconfigure non-SSSD Clients ........................................................ 144B.3.5. Phase 5: Decommission the Directory Server .................................................. 144

Glossary 145

Index 159

viii

ix

PrefaceFreeIPA is a Fedora-based way to create a security, identity, and authentication domain. The differentsecurity and authentication protocols available to Linux and Unix systems (like Kerberos, NIS, DNS,PAM, and sudo) are complex, unrelated, and difficult to manage coherently, especially when combinedwith different identity stores.

FreeIPA provides a layer that unifies all of these disparate services and simplifies the administrativetasks for managing users, systems, and security. FreeIPA breaks management down into twocategories: identity and policy. It centralizes the functions of managing the users and entitieswithin your IT environment (identity) and then provides a framework to define authentication andauthorization for a global security framework and user-friendly tools like single sign-on (policy).

1. Audience and PurposeWith FreeIPA, a Fedora system can easily become the center of an identity/authentication domain andeven provide access to the domain for clients of other operating systems. FreeIPA is an integratedsystem, that builds on existing and reliable technologies like LDAP and certificate protocols, witha robust yet straightforward set of tools (including a web-based UI). The key to identity/policymanagement with FreeIPA is simplicity and flexibility:

• Centralized identity stores for authentication and single sign-on using both integrated LDAP services(with 389 Directory Server) and, optionally, NIS services

• Clear and manageable administrative control over system services like PAM, NTP, and sudo

• Simplified DNS domains and maintenance

• Scalable Kerberos realms and cross-realms which clients can easily join

This guide is written for systems administrators and IT staff who will manage FreeIPA domains, usersystems, and servers. This assumes a moderate knowledge of Linux-based systems administrationand familiarity with important concepts like access control, LDAP, and Kerberos.

This guide covers every aspect of using FreeIPA, including preparation and installation processes,administrative tasks, and the FreeIPA tools. This guide also explains the major concepts behind bothidentity and policy management, generally, and FreeIPA features specifically. Administrative tasksin this guide are categorized as either Identity or Policy in the chapter title to help characterize theadministrative functions.

2. Examples and FormattingEach of the examples used in this guide, such as file locations and commands, have certain definedconventions.

2.1. BracketsSquare brackets ([]) are used to indicate an alternative element in a name. For example, if a tool isavailable in /usr/lib on 32-bit systems and in /usr/lib64 on 64-bit systems, then the tool locationmay be represented as /usr/lib[64].

2.2. Client Tool InformationThe tools for FreeIPA are located in the /usr/bin and the /usr/sbin directories.

Preface

x

The LDAP tools used to edit the FreeIPA directory services, such as ldapmodify and ldapsearch,are from OpenLDAP. OpenLDAP tools use SASL connections by default. To perform a simple bindusing a username and password, use the -x argument to disable SASL.

2.3. Text Formatting and StylesCertain words are represented in different fonts, styles, and weights. Different character formatting isused to indicate the function or purpose of the phrase being highlighted.

Formatting Style Purpose

Monospace with a backgroundThis type of formatting is used for anythingentered or returned in a command prompt.

Italicized text Any text which is italicized is a variable, such asinstance_name or hostname. Occasionally, thisis also used to emphasize a new term or otherphrase.

Bolded text Most phrases which are in bold are applicationnames, such as Cygwin, or are fields or optionsin a user interface, such as a User Name Here:field or Save button. This can also indicate afile, package, or directory name, such as /usr/sbin.

Other formatting styles draw attention to important text.

NOTE

A note provides additional information that can help illustrate the behavior of the system orprovide more detail for a specific issue.

IMPORTANT

Important information is necessary, but possibly unexpected, such as a configuration change thatwill not persist after a reboot.

WARNING

A warning indicates potential data loss, as may happen when tuning hardware for maximumperformance.

3. Giving FeedbackIf there is any error in this book or there is any way to improve the documentation, please let us know.Bugs can be filed against the documentation for FreeIPA through Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible, so we can be more effective in correcting anyissues:

1. Select the Other group and the freeIPA product.

http://bugzilla.redhat.com/bugzilla

http://bugzilla.redhat.com/bugzilla

Document Change History

xi

2. Set the component to Documentation.

3. Set the version number to 2.1.

4. For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinctdescription of the problem, such as incorrect procedure or typo.

For enhancements, put in what information needs to be added and why.

5. Give a clear title for the bug. For example, "Incorrect command example for setupscript options" is better than "Bad example".

We appreciate receiving any feedback — requests for new sections, corrections, improvements,enhancements, even new ways of delivering the documentation or new styles of docs. You arewelcome to contact the Fedora docs team at [email protected].

4. Document Change HistoryRevision2.1.0-1

May 10, 2011 Ella Deon Lackey [email protected]

Beginning draft for the Fedora docs project.

1 mailto:[email protected]




xii

Chapter 1.

1

Installing a FreeIPA ServerThe FreeIPA domain is defined and managed by a FreeIPA server which is essentially a domaincontroller. There can be multiple domain controllers within a domain for load-balancing and failovertolerance. These additional servers are called replicas of the master FreeIPA server.

Both FreeIPA servers and replicas only run on Fedora systems. For both servers and replicas, thenecessary packages must be installed and then the FreeIPA server or replica itself is configuredthrough setup scripts, which configure all of the requisite services.

1.1. Preparing to Install the FreeIPA ServerBefore you install FreeIPA, ensure that the installation environment is suitably configured. You alsoneed to provide certain information during the installation and configuration procedures, includingrealm names and certain usernames and passwords. This section describes the information that youneed to provide.

1.1.1. Hardware RequirementsA basic user entry is about 1 KB in size, as is a simple host entry with a certificate. The structureof the directory tree and the number of indexes in the Directory Server instance can impact thehardware required for the best performance. Table 1.1, “Minimum Hardware Requirements” liststhe recommended minimums. For customized systems, additional indexes, or larger user entries,it is more effective to increase the RAM than to increase the disk space because the DirectoryServer stores much of its data in cache. Add info for disk layout/size recommendations, from https://www.redhat.com/archives/freeipa-users/2011-May/msg00012.html

TIP

The Directory Server instance used by the FreeIPA server can be tuned to increase performance.For tuning information, see the Directory Server documentation at http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/8.2/html/Performance_Tuning_Guide/system-tuning.html.

The system requirements for both 32-bit and 64-bit platforms are the same.

Table 1.1. Minimum Hardware Requirements

Minimum HardwareRequirements

10,000 -250,000 Entries

250,000 -1,000,000 Entries

Over 1,000,000Entries

CPU P3; 500MHz

RAM 1 GB 1 GB 1 GB

Disk Space 2 GB 4 GB 8 GB

1.1.2. Software RequirementsMost of the packages that a FreeIPA server depends on are installed as dependencies when theFreeIPA packages are installed. There are some packages, however, which are required beforeinstalling the FreeIPA packages:

• Kerberos 1.9

• The named and bind-dyndb-ldap packages for DNS

http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/8.2/html/Performance_Tuning_Guide/system-tuning.html

http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/8.2/html/Performance_Tuning_Guide/system-tuning.html

Chapter 1. Installing a FreeIPA Server

2

1.1.3. System PrerequisitesThe FreeIPA server is set up using a configuration script, and this script makes certain assumptionabout the host system. If the system does not meet these prerequisites, then server configuration mayfail.

1.1.3.1. Directory ServerThere must not be any instances of 389 Directory Server installed on the host machine.

1.1.3.2. System FilesThe server script overwrites system files to set up the FreeIPA domain. The system should be clean,without custom configuration for services like DNS and Kerberos, before configuring the FreeIPAserver.

1.1.3.3. System PortsFreeIPA uses a number of ports to communicate with its services. These ports, listed in Table 1.2,“FreeIPA Ports”, must be open and available for FreeIPA to work. They cannot be in use by anotherservice or blocked by a firewall. To make sure that these ports are available, try iptables to list theavailable ports or nc, telnet, or nmap to connect to a port or run a port scan.

Table 1.2. FreeIPA Ports

Service Ports

OCSP responder 9180

HTTP/HTTPS 80443

LDAP/LDAPS 389636

Kerberos1 88464

DNS1 53

NTP2 123

Dogtag Certificate System 9445 (administrators9443 (agents)9444 (users, SSL)9446 (users, client authentication)9180 (OCSP responder, non-SSL)9701 (Tomcat)7389 (interal LDAP database)

1 This service uses both TCP and UDP ports.2 This service uses UDP ports only.

1.1.3.4. DNSFreeIPA uses DNS for the FreeIPA clients to find (discover) the FreeIPA servers. The DNS servicecan be managed by FreeIPA itself, or FreeIPA can use an existing DNS server. Without a properlyconfigured and working DNS, server discovery for clients and FreeIPA services like, LDAP, Kerberos,and SSL may fail to work.

System Prerequisites

3

1.1.3.4.1. DNS RequirementsRegardless of whether the DNS is within the FreeIPA server or external, the server host must haveDNS properly configured:

• The server's machine name must be set and resolve to its public IP address. The fully-qualifieddomain name cannot resolve to the loopback address. It must resolve to the machine's public IPaddress, not to 127.0.0.1. The output of the hostname command cannot be localhost orlocalhost6.

• The hostname must be fully qualified. For example, ipa.example.com.

• The reverse of the address that the hostname resolves to must match the hostname.

• The DNS must be correctly configured to resolve forward and reverse addresses. The DNS doesnot need to be on the same machine as the FreeIPA server, but it does need to be fully functional.

If you do not have a functional DNS, you can use the --setup-dns option when you installFreeIPA to automatically configure a suitable DNS.

1.1.3.4.2. FreeIPA-Generated DNS FileTo help create and configure a suitable DNS setup, the FreeIPA installation script creates a samplezone file. During the installation, FreeIPA displays a message similar to the following:

Sample zone file for bind has been created in /tmp/sample.zone.F_uMf4.db

You should use this file in your DNS zone file.

1.1.3.4.3. IPA, DNS, and NSCDIt is strongly recommended that you avoid or restrict the use of nscd (Name Service CachingDaemon) in a FreeIPA deployment. The nscd service is extremely useful for reducing the load on theserver, and for making clients more responsive, but drawbacks also exist. This is especially true indeployments that take advantage of SSSD, which performs its own caching.

nscd performs caching operations for all services that perform queries via the nsswitch interface,including getent. Because nscd performs both positive and negative caching, if a requestdetermines that a specific FreeIPA user does not exist, it marks this as a negative cache. Valuesstored in the cache remain until the cache expires, regardless of any changes that may occur on theserver. The results of such caching is that new users and memberships may not be visible, and usersand memberships that have been removed may still be visible.

To alleviate these effects, you can avoid the use of nscd altogether, or use a shorter cache time.In particular, consider changing the following values in the /etc/nscd.conf file to suit the usagepatterns of your deployment:

positive-time-to-live group 3600negative-time-to-live group 60positive-time-to-live hosts 3600negative-time-to-live hosts 20

1.1.3.4.4. DNS and KerberosThe Kerberos server requires a valid DNS A record, and reverse DNS needs to work correctly. It issafe to use CNAMEs if they point to the A name that corresponds to the principal name used to createSPNs (Service Principal Names) for the host. You should avoid the use of DDNS names, however, asthis can cause major problems later on.


4

If necessary, add the hostname to the /etc/hosts file, as long as the fully qualified hostname mustbe listed first. For example:

10.0.0.1 ipa.example.com ipa

The realm name does not have to match any or all of the domain name. You can use the domainname example.com and the realm TESTIPA. It is only a convention that they match. FreeIPA addsthe appropriate domain to realm mapping in the /etc/krb5.conf file.

A typical resolver looks in the /etc/hosts file first and DNS second. If nscd is running this mayalso cause issues because it caches lookups. The FreeIPA installer does not kill nscd until after theinstallation process has started, so beware of cached entries if you modify /etc/hosts (killing nscdis recommended if you do).

The FreeIPA installation process includes checks to ensure that the FreeIPA server name is a DNSA record and that its reverse and forward addresses match. This check is not performed if you areinstalling a FreeIPA DNS server (that is, if you are using the --setup-dns option), as it is assumedthat the FreeIPA server will use itself as a DNS from that point forward.

The FreeIPA DNS set-up procedure allows for the configuration of forwarders. In some instances,for example within some companies, you may not have direct access to root name servers, so theimplementation of forwarders is necessary. These could be the company main DNS servers.

Note

DNS forwarders must be specified as IP addresses, not as hostnames.

1.1.3.5. Networking

1.1.3.5.1. Configuring Networking ServicesThe default networking service used by Fedora is NetworkManager, and due to the way this serviceworks, it can cause problems with FreeIPA and the KDC. Consequently, it is highly recommended thatyou use the network service to manage the networking requirements in a FreeIPA environment anddisable the NetworkManager service.

1. Boot the machine into single-user mode and run the following commands:

# chkconfig NetworkManager off; service NetworkManager stop

2. If NetworkManagerDispatcher is installed, ensure that it is stopped and disabled:

# chkconfig NetworkManagerDispatcher off; service NetworkManagerDispatcher stop

3. Then, make sure that the network service is properly started.

# chkconfig network on; service network start

4. Ensure that static networking is correctly configured.

5. Restart the system.

Installing the FreeIPA Server Packages

5

1.1.3.5.2. Configuring the /etc/hosts FileYou need to ensure that your /etc/hosts file is configured correctly. A misconfigured file can preventthe FreeIPA command-line tools from functioning correctly and can prevent the FreeIPA web interfacefrom connecting to the FreeIPA server.

Configure the /etc/hosts file to list the FQDN for the FreeIPA server before any aliases. Alsoensure that the hostname is not part of the localhost entry. The following is an example of a validhosts file:

127.0.0.1 localhost.localdomain localhost::1 localhost6.localdomain6 localhost6192.168.1.1 ipaserver.example.com ipaserver

Important

Do not omit the IPv4 entry in the /etc/hosts file. This entry is required by the FreeIPA webservice.

1.2. Installing the FreeIPA Server PackagesInstalling only the FreeIPA server requires a single package, . If the FreeIPA server will also manage aDNS server, then it requires two additional packages to set up the DNS.

All of these packages can be installed using the yum command:

# yum install freeipa-server bind bind-dyndb-ldap

Installing the also installs a large number of dependencies, such as 389-ds-base for the LDAP serviceand krb5-server for the Kerberos service, along with FreeIPA tools.

After the packages are installed, the server instance must be created using the ipa-server-install command. The options for configuring the new server instance are described in Section 1.3,“Creating a FreeIPA Server Instance”.

1.3. Creating a FreeIPA Server InstanceThe FreeIPA setup script creates a server instance, which includes configuring all of the requiredservices for the FreeIPA domain:

• The network time daemon (ntpd)

• A 389 Directory Server instance

• A Kerberos key distribution center (KDC)

• Apache (httpd)

• An updated SELinux targeted policy

• The Active Directory WinSync plug-in

• A certificate authority

• Optional. A domain name service (DNS) server


6

The FreeIPA setup process can be minimal, where the administrator only supplies some requiredinformation, or it can be very specific, with user-defined settings for many parts of the FreeIPAservices. The configuration is passed using arguments with the ipa-install-server script.

NOTE

The port numbers and directory locations used by FreeIPA are all defined automatically, asdefined in Section 1.1.3.3, “System Ports” and . These ports and directories cannot be changedor customized.

1.3.1. About ipa-server-installA FreeIPA server instance is created by running the ipa-server-install script. This script canaccept user-defined settings for services, like DNS nad Kerberos, that are used by the FreeIPAinstance, or it can supply predefined values for minimal input from the administrator.

While ipa-server-install can be run without any options, so that it prompts for the requiredinformation, it has numerous arguments which allow the configuration process to be easily scripted orto supply additional information which is not requested during an interactive installation.

Table 1.3, “ipa-server-install Options” lists the possible arguments with ipa-server-install, whileSection 1.3.3, “Examples of Creating the FreeIPA Server” has examples of some common installationscenarios. In real life, the ipa-server-install options are versatile enough to be customized tothe specific deployment environment.

Table 1.3. ipa-server-install Options

Argument Alternate Argument Description

Required Options1

-a ipa_admin_password --admin-password=ipa_admin_password

The password for the FreeIPAadministrator. This is used forthe admin user to authenticateto the Kerberos realm.

--hostname=hostname The fully-qualified domainname of the FreeIPA servermachine.

-n domain_name --domain=domain_name The name of the LDAP serverdomain to use for the FreeIPAdomain. This is usually basedon the FreeIPA server'shostname.

-pdirectory_manager_password

--ds-password=directory_manager_password

The password for thesuperuser, cn=DirectoryManager, for the LDAPservice.

-r realm_name --realm=realm_name The name of the Kerberosrealm to create for the FreeIPAdomain.

Certificate Authority Options

--external-ca Instructs the installation scriptto generate a certificate request

About ipa-server-install

7

Argument Alternate Argument Descriptionthat can be submitted to anexternal or third-party CA.

--external_ca_file=CA_cert_chain_file

Points to the PKCS#10file which contains the CAcertificate chain of the externalCA. This is required to validatethe certificate issued by theCA for the FreeIPA server. Ifan external CA is used, this isrequired in a second invocationof ipa-server-install tocomplete the setup process.

--external_cert_file=certificate_file

Points to the PKCS#10 filewhich contains the certificatethat was generated by anexternal CA. If an external CAis used, this is required in asecond invocation of ipa-server-install to completethe setup process.

--selfsign Uses a self-signed certificateinstead of a certificate issuedby the internal DogtagCertificate System or by anexternal CA. If this optionis selected, then no DogtagCertificate System instanceis configured as part of thesetup process, and the FreeIPAserver itself functionallyserves as a CA for clientsin the domain. This is notrecommended for productionenvironments, but can beused in test or developmentenvironments.

--subject=subject_DN Sets the base element forthe subject DN of the issuedcertificates. This defaults toO=realm.

DNS Options

--forwarder=forwarder Gives a comma-separated listof DNS forwarders to use withthe DNS service.

--no-forwarders Uses root servers with the DNSservice instead of forwarders.

--no-reverse Uses root servers with the DNSservice instead of forwarders.


8


--setup-dns Tells the installation scriptto set up a DNS servicewithin the FreeIPA domain.Using an integrated DNSservice is optional, so if thisoption is not passed with theinstallation script, then no DNSis configured.

--zonemgr=email_address Gives the email address to usefor the DNS zone manager. Ifnone is given, this defaults toroot.

Kerberos Options

--ip-address=ip_address Gives the IP address of theKerberos master KDC. This canbe used if there are multipleFreeIPA servers in the samerealm.

-P kerberos_master_password --master-password=kerberos_master_password

The password for the KDCaccount. This is randomlygenerated if no value is given.

NTP Options

-N, --no-ntp Does not configure the NTPservice for the FreeIPA server.This is normally done bydefault.

NOTE

If the FreeIPA server isrunning as a virtual guest,it should not run an NTPservice.

FreeIPA Server Configuration Options

--idmax=number Sets the upper bound for IDswhich can be assigned by theFreeIPA server. The defaultvalue is the ID start value plus199999.

--idstart=number Sets the lower bound (startingvalue) for IDs which can beassigned by the FreeIPAserver. The default value israndomly selected.

Setting up a FreeIPA Server: Basic Interactive Installation

9


--no_hbac_allow Disables the allow_all rulefor host-based access controlin the FreeIPA domain.

Other Setup Options

--no-host-dns Does not use DNS to look upthe hostname of the FreeIPAserver machine during theinstallation process.

-U --unattended Runs the ipa-server-install command withoutany interactive prompts.

--uninstall Uninstalls an existing FreeIPAserver.

General Tool Options

-d --debug Runs the ipa-server-install command in debugmode and outputs debugginginformation.

-h --help Prints the help information forthe ipa-server-installcommand.

--version Prints the version number ofthe ipa-server-installcommand.

1 The installation script will prompt for these options if they are not passed with the script.

1.3.2. Setting up a FreeIPA Server: Basic Interactive InstallationAll that is required to set up a FreeIPA server is to run the ipa-server-install script. This launchsthe script interactively, which prompts for the required information to set up a server, but without moreadvanced configuration like DNS and CA options.

1. Run the ipa-server-install script.

# ipa-server-install

2. Enter the hostname. This is determined automatically using reverse DNS.

Server host name [ipa2.server.example.com]:

3. Enter the domain name. This is determined automatically based on the hostname.

Please confirm the domain name [example.com]:

4. The script then reprints the hostname, IP address, and domain name.

The IPA Master Server will be configured withHostname: ipa2.server.example.comIP address: 1.2.3.4


10

Domain name: example.com

5. Enter the new Kerberos realm name. This is usually based on the domain name.

Please provide a realm name [EXAMPLE.COM]:

6. Enter the password for the Directory Server superuser, cn=Directory Manager. There arepassword strength requirements for this password, including a minimum password length.

Directory Manager password:Password (confirm):

7. Enter the password for the FreeIPA system user account, admin. This user is created on themachine.

IPA admin password:Password (confirm):

8. After that, the script configures all of the associated services for FreeIPA, with task counts andprogress bars.

Configuring ntpd [1/4]: stopping ntpd ...done configuring ntpd.

Configuring directory server for the CA: Estimated time 30 seconds [1/3]: creating directory server user...done configuring pkids.

Configuring certificate server: Estimated time 6 minutes [1/17]: creating certificate server user....done configuring pki-cad.

Configuring directory server: Estimated time 1 minute [1/32]: creating directory server user...done configuring dirsrv.

Configuring Kerberos KDC: Estimated time 30 seconds [1/14]: setting KDC account password...done configuring krb5kdc.

Configuring ipa_kpasswd [1/2]: starting ipa_kpasswd [2/2]: configuring ipa_kpasswd to start on bootdone configuring ipa_kpasswd.

Configuring the web interface: Estimated time 1 minute [1/12]: disabling mod_ssl in httpd...done configuring httpd.Setting the certificate subject baserestarting certificate serverApplying LDAP updatesRestarting the directory serverRestarting the KDC

Examples of Creating the FreeIPA Server

11

Restarting the web serverSample zone file for bind has been created in /tmp/sample.zone.ygzij5.db==============================================================================Setup complete

9. Restart the SSH service to retrive the Kerberos principal and to refresh the name server switch(NSS) configuration file:

# service sshd restart

10. Authenticate to the Kerberos realm using the admin user's credentials to ensure that the user isproperly configured and the Kerberos realm is accessible.

$ kinit adminPassword for [email protected]:

11. Test the FreeIPA configuration by running a command like ipa user-find. For example:

# ipa user-find admin -------------- 1 user matched -------------- User login: admin Last name: Administrator Home directory: /home/admin Login shell: /bin/bash Account disabled: False Member of groups: admins ---------------------------- Number of entries returned 1 ----------------------------

1.3.3. Examples of Creating the FreeIPA ServerThe way that a FreeIPA server is installed can be different depending on the network environment,security requirements within the organization, and the desired topology. These example illustrate somecommon options when installing the server. These examples are not mutually exclusive; it is entirelypossible to use CA options, DNS options, and FreeIPA configuration options in the same serverinvocation. These are called out separately simply to make it more clear what each configuration arearequires.

1.3.3.1. Non-Interactive Basic InstallationAs shown in Section 1.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”, only a fewpieces of information are required to configured a FreeIPA server. While the setup script can promptfor this information in interactive mode, this information can also be passed with the setup command toallow automated and unattended configuration:

• Passwords for the FreeIPA administrative user and the Directory Server super user (DirectoryManager)

• The server hostname

• The Kerberos realm name

• The DNS domain name


12

This information can be passed with the ipa-server-install, along with the -U to force it to runwithout requiring user interaction.

Example 1.1. Basic Installation without Interaction

# ipa-server-install -a secret12 --hostname=ipa2.server.example.com -r EXAMPLE.COM -p secret12 -n example.com -U

The script then prints the submitted values:

To accept the default shown in brackets, press the Enter key.

The IPA Master Server will be configured withHostname: ipa2.server.example.comIP address: 1.2.3.4Domain name: example.com

Then the script runs through the configuration progress for each FreeIPA service, as inSection 1.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”.

1.3.3.2. Using Different CAsThe default installation of FreeIPA uses an integrated Dogtag Certificate System instance asa certificate authority to issue certificates. However, this configuration is not required. FreeIPAonly requires a certificate authority. This can be an external CA like Verisign or a corporate CAinconjunction with the internal Certificate System, or it can even be the FreeIPA server itself, using aself-signed certificate.

For the FreeIPA server itself to work as a CA, it uses a self-signed certificate, meaning that it approvedand issued its own certificate. This is done by using the --selfsign option with the ipa-server-install command. When the FreeIPA server uses a self-signed certificate, the setup processis exactly the same as a normal installation, except that no Dogtag Certificate System instanceis created. There is still a cacert.p12 file created that can be used by replicas and the domainfunctions exactly the same. The only difference is what CA issues the certificates.

Example 1.2. Using a Self-Signed Certificate

# ipa-server-install -a secret12 --hostname=ipa2.server.example.com -r EXAMPLE.COM -p secret12 -n example.com -U --selfsign

NOTE

A self-signed certificate should only be used for a testing or development environment. Aproduction environment should use the Dogtag Certificate System instance or an external, publicCA.

Alternatively, the FreeIPA server can use a certificate issued by an external CA. This can be acorporate CA or a third-party CA like Verisign or Thawte. As with a normal setup process, using anexternal CA still uses a Dogtag Certificate System instance for the FreeIPA server for issuing all of itsclient and replica certificates; the initial CA certificate is simply issued by a different CA.

Examples of Creating the FreeIPA Server

13

When using an external CA, there are two additional steps that must be performed: submit thegenerated certificate request to the external CA and then load the CA certificate and issued servercertificate to complete the setup.

Example 1.3. Using an External CA1. Run the ipa-server-install script, using the --external-ca option.

# ipa-server-install -a secret12 -r EXAMPLE.COM -P password -p secret12 -n ipa.server.example.com --external-ca

2. The script sets up the NTP and Directory Server services as normal.

3. The script completes the CA setup and returns information about where the certificate signingrequest (CSR) is located, /root/ipa.csr. This request must be submitted to the external CA.

Configuring certificate server: Estimated time 6 minutes [1/4]: creating certificate server user [2/4]: creating pki-ca instance [3/4]: restarting certificate server [4/4]: configuring certificate server instanceThe next step is to get /root/ipa.csr signed by your CA and re-run ipa-server-install.

4. Submit the request to the CA. The process differs for every service.

5. Retrieve the issued certificate and the CA certificate chain for the issuing CA. Again, theprocess differs for every certificate service, but there is usually a download link on a web pageor in the notification email that allows administrators to download all the required certificates. Besure to get the full certificate chain for the CA, not just the CA certificate.

6. Rerun ipa-server-install, specifying the locations and names of the certificate and CAchain files. For example:

# ipa-server-install --external_cert_file=/tmp/servercert20110601.p12 --external_ca_file=/tmp/cacert.p12

7. Complete the setup process and verify that everything is working as expected, as inSection 1.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”.

1.3.3.3. Using DNSFreeIPA can be configured to manage its own DNS, use an existing DNS, or not use DNS services atall (which is the default). Running the setup script alone does not configure DNS; this requires the --setup-dns option.

As with a basic setup, the DNS setup can either prompt for the required information or the DNSinformation can be passed with the script to allow an automatic or unattended setup process.

Example 1.4. Interactive DNS Setup1. Run the ipa-server-install script, using the --setup-dns option.

# ipa-server-install -a secret12 -r EXAMPLE.COM -P password -p secret12 -n ipa.server.example.com --setup-dns

2. The script configures the hostname and domain name as normal.


14

3. The script then prompts for DNS forwarders. If forwarders will be used, enter yes, and thensupply the list of DNS servers. If FreeIPA will manage its own DNS service, then enter no.

Do you want to configure DNS forwarders? [yes]: noNo DNS forwarders configured

4. The script sets up the NTP, Directory Server, Certificate System, Kerberos, and Apacheservices.

5. Before completing the configuration, the script prompts to ask whether it should configurereverse DNS services. If you select yes, then it configures the named service.

Do you want to configure the reverse zone? [yes]: yesConfiguring named: [1/9]: adding DNS container [2/9]: setting up our zone [3/9]: setting up reverse zone [4/9]: setting up our own record [5/9]: setting up kerberos principal [6/9]: setting up named.conf [7/9]: restarting named [8/9]: configuring named to start on boot [9/9]: changing resolv.conf to point to ourselvesdone configuring named.==============================================================================Setup complete

6. Verify that everything is working as expected, as in Section 1.3.2, “Setting up a FreeIPA Server:Basic Interactive Installation”.

If DNS is used with FreeIPA, then two pieces of information are required: any DNS forwarders that willbe used and using (or not) reverse DNS. To perform a non-interactive setup, this information can bepassed using the --forwarder | --no-forwarders option and --no-reverse option.

Example 1.5. Setting up DNS Non-InteractivelyTo use DNS always requires the --setup-dns. To user forwarders, use the --forwarder with acomma-separated list of forwarders.

# ipa-server-install ... --setup-dns --forwarder=1.2.3.0,1.2.255.0

Some kind of forwarder information is required. If no external forwarders will be used with theFreeIPA DNS service, then use the --no-forwarders option to indicate that only root servers willbe used.

The script always assumes that reverse DNS is configured along with DNS, so it is not necessary touse any options to enable reverse DNS. To disable reverse DNS, use the --no-reverse option.

# ipa-server-install ... --setup-dns --no-reverse

Troubleshooting Installation Problems

15

1.3.4. Troubleshooting Installation Problems

GSS Failures When Running IPA CommandsImmediately after installation, there can be Kerberos problems when trying to run an ipa-* command.For example:

ipa: ERROR: Kerberos error: ('Unspecified GSS failure. Minor code may provide more information', 851968)/('Decrypt integrity check failed', -1765328353)

There are two potential causes for this:

• DNS is not properly configured.

• Active Directory is in the same domain as the FreeIPA server.

named Daemon Fails to StartIf a FreeIPA server is configured to manage DNS and is set up successfully, but the named servicefails to start, this can indicate that there is a package conflict. Check the /var/log/messages file forerror messages related to the named service and the ldap.so library:

ipaserver named[6886]: failed to dynamically load driver 'ldap.so': libldap-2.4.so.2: cannot open shared object file: No such file or directory

This usually means that the bind-chroot package is installed and is preventing the named service fromstarting. To resolve this issue, remove the bind-chroot package and then restart the FreeIPA server.

# yum remove bind-chroot

# ipactl restart

1.4. Setting up FreeIPA ReplicasIn the FreeIPA domain, there are three types of machines:

• Servers, which manage all of the services used by domain members

• Replicas, which are essentially read-only clones of servers

• Clients, which belong to the Kerberos domains, receive certificates and tickets issued by theservers, and use other centralized services for authentication and authorization

A replica is a clone of a specific FreeIPA server. The server and replica share the same internalinformation about users, machines, certificates, and configured policies. These data are copied fromthe server to the replica in a process called replication. The two Directory Server instances used by anFreeIPA server — the Directory Server instance used by the FreeIPA server as a data store and theDirectory Server instance used by the Dogtag Certificate System to store certificate information — arereplicated over to corresponding consumer Directory Server instances used by the FreeIPA replica.


16

TIP

If you are using the integrated Dogtag Certificate System instance as the CA for the FreeIPAdomain, then it is possible to make a replica of a replica. It is not possible to make a replica of areplica if you use the --selfsign option for the original FreeIPA server.

1.4.1. Prepping and Installing the Replica ServerReplicas are functionally the same as FreeIPA servers, so they have the same installationrequirements and packages.

• Make sure that the machine meets all of the prerequisites listed in Section 1.1, “Preparing to Installthe FreeIPA Server”.

• Install the server packages as in Section 1.2, “Installing the FreeIPA Server Packages”. However, donot run the ipa-server-install script.

IMPORTANT

The replica and the master server must be running the same version of FreeIPA.

• If there is an existing Dogtag Certificate System or Red Hat Certificate System instance on thereplica machine, make sure that port 7389 is free. This port is used by the master FreeIPA server tocommunicate with the replica.

• Make sure the appropriate ports are open on both the server and the replica machine during andafter the replica configuration. Servers and replicas connect to each other over ports 9443, 9444,9445, and 7389 during the replica configuration. Once the replica is set up, the server and replicacommunicate over port 7389.

1.4.2. Creating the Replica

NOTE

Make sure that the replica machine exists in the server's DNS before beginning to configure thereplica. If the server cannot contact the replica machine during the configuration process, thenthe replica configuration fails.

1. C\On the master server, create a replica information file. This contains realm and configurationinformation taken from the master server which will be used to configure the replica server.

Run the ipa-replica-repare command on the master FreeIPA server. The commandrequires the fully-qualified domain name of the replica machine. Using the --ip-address optionautomatically creates DNS entries for the replication, including the A and PTR records for thereplica to the DNS.

# ipa-replica-prepare ipareplica.example.com --ip-address 192.168.1.2

Determining current realm name

Creating the Replica

17

Getting domain name from LDAPPreparing replica for ipareplica.example.com from ipaserver.example.comCreating SSL certificate for the Directory ServerCreating SSL certificate for the Web ServerCopying additional filesFinalizing configurationPackaging the replica into replica-info-ipareplica.example.com

Each replica information file is created in the /var/lib/ipa/ directory as a GPG-encrypted file.Each file is named specifically for the replica server for which it is intended, such as replica-info-ipareplica.example.com.gpg.

NOTE

A replica information file cannot be used to create multiple replicas. It can only be used forthe specific replica and machine for which it was created.

WARNING

Replica information files contain sensitive information. Take appropriate steps to ensure thatthey are properly protected.

2. Copy the replica information file to the replica server:

# scp /var/lib/ipa/replica-info-ipareplica.example.com.gpg root@ipareplica:/var/lib/ipa/

3. On the replica server, run the replica installation script, referencing the replication information file:

# ipa-replica-install /var/lib/ipa/replica-info-ipareplica.example.com.gpg

The replica installation script runs a test to ensure that the replica file being installed matchesthe current hostname. If they do not match, the script returns a warning message and asks forconfirmation. This could occur on a multi-homed machine, for example, where mismatchedhostnames may not be an issue.

4. Enter the Directory Manager password when prompted. The script then configures a DirectoryServer instance based on information in the replica information file and initiates a replicationprocess to copy over data from the master server to the replica, a process called initialization.

5. Once the installation process completes, update the DNS entries so that FreeIPA clientscan discover the new server. For example, for a FreeIPA replica with a hostname ofipareplica.example.com:

_ldap._tcp IN SRV 0 100 389 ipareplica.example.com_kerberos._tcp IN SRV 0 100 88 ipareplica.example.com_kerberos._udp IN SRV 0 100 88 ipareplica.example.com_kerberos-master._tcp IN SRV 0 100 88 ipareplica.example.com_kerberos-master._udp IN SRV 0 100 88 ipareplica.example.com_kpasswd._tcp IN SRV 0 100 464 ipareplica.example.com_kpasswd._udp IN SRV 0 100 464 ipareplica.example.com_ntp._udp IN SRV 0 100 123 ipareplica.example.com


18

6. Optional. Set up DNS services for the replica. These are not configured by the setup script, even ifthe master server uses DNS.

Use the ipa-dns-install command to install the DNS manually, then use the the ipadnsrecord-add command to add the required DNS records. For example:

# ipa-dns-install

$ ipa dnsrecord-add example.com @ --ns-rec ipareplica.example.com.

IMPORTANT

Use the fully-qualified domain name of the replica, including the final period (.), otherwiseBIND will treat the hostname as relative to the domain.

1.4.3. Troubleshooting Replica InstallationIf the replica installation fails on step 3 ([3/11]: configuring certificate server instance), that usuallymeans that the required port is not available. This can be verified by checking the debug logs for theCA, /var/log/pki-ca/debug, which may show error messages about being unable to find certainentries. For example:

[04/Feb/2011:22:29:03][http-9445-Processor25]: DatabasePanelcomparetAndWaitEntries ou=people,o=ipaca not found, let's wait

The only resolution is to uninstall the replica:

# ipa-server-install --uninstall

After uninstalling the replica, ensure that port 7389 on the replica is available, and retry the replicainstallation.

1.5. Uninstalling FreeIPA Servers and ReplicasTo uninstall both a FreeIPA server and a FreeIPA replica, pass the --uninstall option to the ipa-server-install command:

# ipa-server-install --uninstall

Chapter 2.

19

Setting up Systems as FreeIPA ClientsA client is any system which is a member of the FreeIPA domain. While this is frequently a Fedorasystem (and FreeIPA has special tools to make configuring Fedora clients very simple), machines withother operating systems can also be added to the FreeIPA domain.

One important aspect of a FreeIPA client is that only the system configuration determines whether thesystem is part of the domain. (The configuration includes things like belonging to the Kerberos domain,DNS domain, and having the proper authentication and certificate setup.) FreeIPA does not requireany sort of agent or daemon running on a client.

This chapter explains how to configure a system to join a FreeIPA domain.

NOTE

Clients can only be configured after at least one FreeIPA server has been installed.

2.1. What Happens in Client SetupWhether the client configuration is performed automatically on Fedora systems using the client setupscript or manually on other systems, the general process of configuring a machine to serve as aFreeIPA client is mostly the same, with slight variation depending on the platform:

• Retrieve the CA certificate for the FreeIPA CA.

• Create a separate Kerberos configuration to test the provided credentials. This enables a Kerberosconnection to the FreeIPA XML-RPC server, necessary to join the FreeIPA client to the FreeIPAdomain. This Kerberos configuration is ultimately discarded.

Setting up the Kerberos configuration includes specifying the realm and domain details, and defaultticket attributes. Forwardable tickets are configured by default, which facilitates connection to theadministration interface from any operating system, and also provides for auditing of administrationoperations. For example, this is the Kerberos configuration for Fedora systems:

[libdefaults]default_realm = EXAMPLE.COMdns_lookup_realm = falsedns_lookup_kdc = falserdns = falseforwardable = yesticket_lifetime = 24h

[realms]EXAMPLE.COM = { kdc = ipaserver.example.com:88 admin_server = ipaserver.example.com:749 }[domain_realm].example.com = EXAMPLE.COMexample.com = EXAMPLE.COM

• Run the ipa-join command to perform the actual join

• Obtain a service principal for the host service and installs it into /etc/krb5.keytab. For example,host/[email protected].

Chapter 2. Setting up Systems as FreeIPA Clients

20

• Enable certmonger, retrieve an SSL server certificate, and install the certificate in /etc/pki/nssdb.

• Disable the nscd daemon.

• Configures SSSD or LDAP/KRB5, including NSS and PAM configuration files.

• Configure NTP.

2.2. Configuring a Fedora System as a FreeIPA ClientThere are two elements to prepare before beginning the client setup process for the Fedora client:

• There must be a way to connect the client machine to the Kerberos domain, either by having anavailable Kerberos identity (such as the admin user) or by manually adding the client machine to theKDC on the server with a one-time password before beginning the enrollment process for the clientmachine.

• If the network environment uses an Active Directory DNS, then manually provide the FreeIPA serverdetails during the client configuration. Active Directory has its own SRV records for Kerberos andLDAP, and the ipa-client-install script retrieves those DNS records instead of any recordsthat were added for FreeIPA.

The most efficient way to install the required client packages is to use the FreeIPA server as a yumrepository. This allows client packages to be installed directly from the FreeIPA server.

1. Install the client packages. These packages are used only as a simple way to configure thesystem; they do not install an agent or daemon on the client machine.

For a regular user system, this requires only the ipa-client package:

# yum install freeipa-client

An administrator machine requires the freeipa-admintools package, as well:

# yum install freeipa-client freeipa-admintools

2. If the FreeIPA server is configured as the DNS server and is in the same domain as the client, addthe server's IP address as the first entry in the client's /etc/resolv.conf file.

3. Run the client setup command.

# ipa-client-install

4. If prompted, enter the domain name for the FreeIPA's DNS domain.

DNS discovery failed to determine your DNS domainPlease provide the domain name of your IPA server (ex: example.com): example.com

5. Enter the fully-qualified domain name of the FreeIPA server.

DNS discovery failed to find the IPA ServerPlease provide your IPA server name (ex: ipa.example.com): ipaserver.example.com

Configuring a Fedora System as a FreeIPA Client

21

6. The client script then prompts for a Kerberos identity to use to contact and then join the Kerberosrealm. When these credentials are supplied, then the client is able to join the FreeIPA Kerberosdomain and then complete the configuration:

Continue to configure the system with these values? [no]: yesEnrollment principal: adminPassword for [email protected]:Enrolled in FreeIPA realm EXAMPLE.COMCreated /etc/ipa/default.confConfigured /etc/sssd/sssd.confConfigured /etc/krb5.conf for FreeIPA realm EXAMPLE.COMSSSD enabledKerberos 5 enabledNTP enabledClient configuration complete.

7. Test that the client can connect successfully to the FreeIPA domain and can perform basic tasks.For example, check that the FreeIPA tools can be used to get user and group information:

$ id$ getent passwd userID$ getent group ipausers

8. Set up NFS to work with Kerberos.

a. Obtain a Kerberos ticket for the admin user.

# kinit admin

b. Add an NFS service principal on the client.

# ipa service-add nfs/ipaclient.example.com

c. Obtain a keytab for the NFS service principal.

# ipa-getkeytab -s ipaserver.example.com -p nfs/ipaclient.example.com -k /etc/krb5.keytab

NOTE

Some versions of the Linux NFS implementation have limited encryption type support. Ifthe NFS server is hosted on a version older than Fedora 15, use the -e des-cbc-crcoption to the ipa-getkeytab command for any nfs/<FQDN> service keytabs to set up,both on the server and on all clients. This instructs the KDC to generate only DES keys.

When using DES keys, all clients and servers that rely on this encryption type need tohave the allow_weak_crypto option enabled in the [libdefaults] section of the/etc/krb5.conf file. Without these configuration changes, NFS clients and serversare unable to authenticate to each other, and attempts to mount NFS filesystems mayfail. The client's rpc.gssd and the server's rpc.svcgssd daemons may log errorsindicating that DES encryption types are not permitted.


22

d. Add the following line to the /etc/sysconfig/nfs file:

SECURE_NFS=yes

e. Start the rpcgssd daemon.

# service rpcgssd start

f. Test the NFS-Kerberos configuration:

# mount -v -t nfs4 -o sec=krb5 ipaserver.example.com:/ /mnt

2.3. Configuring a Microsoft Windows System as a FreeIPAClient

NOTE

FreeIPA does not support Microsoft Windows client authentication.

1. Download the MIT Kerberos 3.x package for Windows.

2. Run the kfw-3.x-exe file to launch the MIT Kerberos Installation Wizard.

3. Read and accept the license agreement.

4. Install the KfW client. All other components are optional.

5. Accept the default destination path.

6. Select Download from web path, and enter the URL to the FreeIPA server. For example:

http://ipaserver.example.com/ipa/config/

7. Select Autostart the Network Identity Manager each time you login to Windows.

8. Click Install to begin the installation. When the installation is complete, click Finish to exit theWizard.

9. Edit the hosts file and add the FreeIPA server. For example:

1.2.3.4 ipaserver.example.com ipaserver

Depending on the version of Windows, the HOSTS file could be located in different directories.

Configuring a Solaris System as a FreeIPA Client

23

2.4. Configuring a Solaris System as a FreeIPA Client

2.4.1. Configuring Solaris 101. As with Fedora systems, FreeIPA provides an automated method of configuring Solaris 10 to

function as a FreeIPA client. On the Solaris client, run the ldapclient with the name of theFreeIPA domain:

# ldapclient init ipa.example.com -v

When the command is run, it creates a configuration profile that will automatically set up thenecessary PAM and /etc/ldap.conf configuration.

2. Configure the /etc/krb5/krb5.conf file. The Kerberos configuration includes specifying therealm and domain details and default ticket attributes. The default file created by ldapclientconfigures forwardable tickets by default, which makes it possible to connect to the UI from anysystem and provides a way to audit administration operations.

[libdefaults]default_realm = EXAMPLE.COM

[realms]EXAMPLE.COM = {kdc = ipaserver.example.com:88admin_server = ipaserver.example.com:749}

[domain_realm].example.com = EXAMPLE.COMexample.com = EXAMPLE.COM

[logging]default = FILE:/var/krb5/kdc.logkdc = FILE:/var/krb5/kdc.logkdc_rotate = {period = 1dversions = 10}

[appdefaults]kinit = {renewable = trueforwardable= true}

3. Configure and enable NTP and make sure that time is synchronized between the client and theFreeIPA server.

4. Configure SSH access so that the Solaris FreeIPA client to accept incoming SSH requests andauthenticate with the user's Kerberos credentials.

a. On the FreeIPA server, add a host service principal for the Solaris client.

# ipa service-add host/solarisipaclient.example.com

b. On the FreeIPA server, create the host keytab file.


24

# ipa-getkeytab -s ipaserver.example.com -p host/solarisipaclient.example.com -k /tmp/krb5.keytab -e des-cbc-crc

c. Copy this keytab to the Solaris machine, and save it as /etc/krb5/krb5.keytab.

# scp /tmp/krb5.keytab [email protected]:/etc/krb5/krb5.keytab

d. Reboot the Solaris client machine.

5. Configure NFS to work with the Kerberos domain.

a. Obtain a Kerberos ticket for the admin user.

# kinit admin

b. Set up the NFS/Kerberos mapping for the Solaris client on the FreeIPA server.

i. Add an NFS service principal for the client.

# ipa service-add nfs/solarisipaclient.example.com

ii. Create the NFS keytab file.

# ipa-getkeytab -s ipaserver.example.com -p nfs/solarisipaclient.example.com -k /tmp/krb5.keytab -e des-cbc-crc

NOTE

Some versions of the Linux NFS implementation have limited encryption typesupport. If the NFS server is hosted on a version older than Fedora 15, use the -e des-cbc-crc option to the ipa-getkeytab command for any nfs/<FQDN>service keytabs to set up, both on the server and on all clients. This instructs theKDC to generate only DES keys.

When using DES keys, all clients and servers that rely on this encryption typeneed to have the allow_weak_crypto option enabled in the [libdefaults]section of the /etc/krb5.conf file. Without these configuration changes, NFSclients and servers are unable to authenticate to each other, and attempts to mountNFS filesystems may fail. The client's rpc.gssd and the server's rpc.svcgssddaemons may log errors indicating that DES encryption types are not permitted.

iii. Use the klist command to verify that the ticket was created:

# klist -ket /tmp/krb5.keytab

iv. Copy the keytab from the server to the client.

# scp /tmp/krb5.keytab [email protected]:/tmp/krb5.keytab

Configuring Solaris 9

25

c. On the FreeIPA client, use the ktutil command to import the contents into the main hostkeytab.

# ktutilktutil: read_kt /tmp/krb5.keytabktutil: write_kt /etc/krb5/krb5.keytabktutil: q

2.4.2. Configuring Solaris 91. Perform steps 1 through 4 in Section 2.4.1, “Configuring Solaris 10” to set up the Solaris 9 client.

2. Configure the /etc/pam.conf file to use PAM Kerberos. For example:

login auth requisite pam_authtok_get.so.1login auth sufficient pam_krb5.so.1 use_first_passlogin auth sufficient pam_unix.so.1 use_first_passlogin auth required pam_dhkeys.so.1login auth required pam_unix_auth.so.1login auth required pam_dial_auth.so.1

2.5. Configuring an HP-UX System as a FreeIPA

Note

The FreeIPA client installation process requires that a FreeIPA server already exist.

2.5.1. Configuring NTPConfigure and enable NTP and make sure that time is synchronized between the client and theFreeIPA server.

2.5.2. Configuring LDAP Authentication1. Install the ldapux client.

# swinstall -s J4269AA_B.04.15.01_HP-UX_B.11.23_IA_PA.depot

2. Change to the configuration directory, and run the setup script.

# cd /opt/ldapux/config/

# ./setup


26

NOTE

Running the setup script is only necessary for the first HP-UX client. Every subsequent HP-UX client only needs to know where the LDAP profile is stored. All clients will then use thesame configuration.

For more information on this, see the HP-UX documentation at http://docs.hp.com/en/J4269-90075/ch02s07.html.

The setup script prompts for information about the FreeIPA LDAP service, such as its port andhost, Directory Manager credentials, and schema and directory suffixes.

Would you like to continue with the setup? [Yes]Select which Directory Server you want to connect to ? [RedHat Directory]Directory server host ? [ipaserver.example.com]Directory Server port number [389]Would you like to extend the printer schema in this directory server? [No]Would you like to install PublicKey schema in this directory server? [No]Would you like to install the new automount schema ? [No]Profile Entry DN: [cn=ldapuxprofile,cn=etc,dc=example,dc=com]User DN [cn=Directory Manager]Password ? [Directory Manager's Password]Authentication method ? [ SIMPLE ]Enter the number of the hosts you want to specify [1]Default Base DN ? [dc=example,dc=com]Accept remaining defaults ? [n]Client binding [Anonymous]Bind time limit [5 seconds]Search time limit [no limit]Do you want client searches of the directory to follow referrals? [Yes]Profile TTL [0 = infinite]Do you want to remap any of the standard RFC 2307 attribute? [Yes]Specify the service you want to map? [ 3=Group]Specify the attribute you want to map [3 for memberuid ]Type the name of the attribute memberuid should be mapped to [member]Specify the service you want to map? [ 0 = exit ]Do you want to remap any of the standard RFC 2307 attribute? [ no this time ]Do you want to create custom search descriptors? [ No ]

3. Ensure that the LDAP client daemon is running.

# ps -ef | grep ldapclientd

If necessary, start the daemon:

# /opt/ldapux/bin/ldapclientd

4. Check that the user and group entries in the LDAP client are correct and available:

# nsquery passwd admin# nsquery group admins

5. Create a new group on the FreeIPA server.

http://docs.hp.com/en/J4269-90075/ch02s07.html

http://docs.hp.com/en/J4269-90075/ch02s07.html

Configuring Kerberos

27

# ipa group-add testgroup

6. Add a test user to the new group.

# ipa group-add-member -a testuser testgroup

Validate the new user and group:

# nsquery passwd testuser# nsquery group testgroup

7. To ensure that the LDAP client daemon starts when the system boots, add the following lines tothe /etc/opt/ldapux/ldapclientd.conf file:

[StartOnBoot]enable=yes

2.5.3. Configuring KerberosEdit the /etc/krb5.conf file to reflect the Kerberos domain used by the FreeIPA server. Settingup the Kerberos configuration includes specifying the realm and domain details, and defaultticket attributes. Forwardable tickets are configured by default, which facilitates connection to theadministration interface from any operating system, and also provides for auditing of administrationoperations. For example:

[libdefaults]default_realm = EXAMPLE.COMdefault_tkt_enctypes = DES-CBC-CRCdefault_tgs_enctypes = DES-CBC-CRCccache_type = 2

[realms]EXAMPLE.COM = { kpasswd_server = ipaserver.example.com kdc = ipaserver.example.com:88 admin_server = ipaserver.example.com:749 default_domain = example.com }

[domain_realm].example.com = EXAMPLE.COMexample.com = EXAMPLE.COM

[appdefaults]kinit = { forwardable = true }

2.5.4. Configuring PAMThe PAM configuration differs slightly between different versions of HP-UX.

2.5.4.1. HP-UX 11i v2Edit the /etc/pam.conf file so that all of the required modules are loaded for authentication. Forexample:


28

## PAM configuration## This pam.conf file is intended as an example only.# see pam.conf(4) for more details

# Authentication management#login auth required libpam_hpsec.so.1login auth sufficient libpam_krb5.so.1login auth required libpam_unix.so.1 try_first_passsu auth required libpam_hpsec.so.1su auth sufficient libpam_krb5.so.1su auth required libpam_unix.so.1 try_first_passdtlogin auth required libpam_hpsec.so.1dtlogin auth sufficient libpam_krb5.so.1dtlogin auth required libpam_unix.so.1 try_first_passdtaction auth required libpam_hpsec.so.1dtaction auth sufficient libpam_krb5.so.1dtaction auth required libpam_unix.so.1 try_first_passftp auth required libpam_hpsec.so.1ftp auth sufficient libpam_krb5.so.1ftp auth required libpam_unix.so.1 try_first_passsshd auth required libpam_hpsec.so.1sshd auth sufficient libpam_krb5.so.1sshd auth required libpam_unix.so.1 try_first_passOTHER auth required libpam_unix.so.1#

# Account management#login account required libpam_hpsec.so.1login account sufficient libpam_krb5.so.1login account required libpam_unix.so.1su account required libpam_hpsec.so.1su account sufficient libpam_krb5.so.1su account required libpam_unix.so.1dtlogin account required libpam_hpsec.so.1dtlogin account sufficient libpam_krb5.so.1dtlogin account required libpam_unix.so.1dtaction account required libpam_hpsec.so.1dtaction account sufficient libpam_krb5.so.1dtaction account required libpam_unix.so.1ftp account required libpam_hpsec.so.1ftp account sufficient libpam_krb5.so.1ftp account required libpam_unix.so.1sshd account required libpam_hpsec.so.1sshd account sufficient libpam_krb5.so.1sshd account required libpam_unix.so.1OTHER account required libpam_unix.so.1#

# Session management#login session required libpam_hpsec.so.1login session sufficient libpam_krb5.so.1login session required libpam_unix.so.1dtlogin session required libpam_hpsec.so.1dtlogin session sufficient libpam_krb5.so.1dtlogin session required libpam_unix.so.1dtaction session required libpam_hpsec.so.1dtaction session sufficient libpam_krb5.so.1dtaction session required libpam_unix.so.1sshd session required libpam_hpsec.so.1sshd session sufficient libpam_krb5.so.1sshd session required libpam_unix.so.1

Configuring PAM

29

OTHER session required libpam_unix.so.1#

# Password management#login password required libpam_hpsec.so.1login password sufficient libpam_krb5.so.1login password required libpam_unix.so.1passwd password required libpam_hpsec.so.1passwd password sufficient libpam_krb5.so.1passwd password required libpam_unix.so.1dtlogin password required libpam_hpsec.so.1dtlogin password sufficient libpam_krb5.so.1dtlogin password required libpam_unix.so.1dtaction password required libpam_hpsec.so.1dtaction password sufficient libpam_krb5.so.1dtaction password required libpam_unix.so.1OTHER password required libpam_unix.so.1

2.5.4.2. HP-UX 11i v1Edit the /etc/pam.conf file to reflect the following example:

## PAM configuration## This pam.conf file is intended as an example only.# see pam.conf(4) for more details#

# Authentication management#login auth sufficient /usr/lib/security/libpam_krb5.1login auth required /usr/lib/security/libpam_unix.1 try_first_passsu auth sufficient /usr/lib/security/libpam_krb5.1su auth required /usr/lib/security/libpam_unix.1 try_first_passdtlogin auth sufficient /usr/lib/security/libpam_krb5.1dtlogin auth required /usr/lib/security/libpam_unix.1 try_first_passdtaction auth sufficient /usr/lib/security/libpam_krb5.1dtaction auth required /usr/lib/security/libpam_unix.1 try_first_passftp auth sufficient /usr/lib/security/libpam_krb5.1ftp auth required /usr/lib/security/libpam_unix.1 try_first_passOTHER auth required /usr/lib/security/libpam_unix.1#

# Account management#login account sufficient /usr/lib/security/libpam_krb5.1login account required /usr/lib/security/libpam_unix.1su account sufficient /usr/lib/security/libpam_krb5.1su account required /usr/lib/security/libpam_unix.1dtlogin account sufficient /usr/lib/security/libpam_krb5.1dtlogin account required /usr/lib/security/libpam_unix.1dtaction account sufficient /usr/lib/security/libpam_krb5.1dtaction account required /usr/lib/security/libpam_unix.1ftp account sufficient /usr/lib/security/libpam_krb5.1ftp account required /usr/lib/security/libpam_unix.1OTHER account required /usr/lib/security/libpam_unix.1#

# Session management#login session sufficient /usr/lib/security/libpam_krb5.1login session required /usr/lib/security/libpam_unix.1dtlogin session sufficient /usr/lib/security/libpam_krb5.1


30

dtlogin session required /usr/lib/security/libpam_unix.1dtaction session sufficient /usr/lib/security/libpam_krb5.1dtaction session required /usr/lib/security/libpam_unix.1OTHER session required /usr/lib/security/libpam_unix.1#

# Password management#login password sufficient /usr/lib/security/libpam_krb5.1login password required /usr/lib/security/libpam_unix.1passwd password sufficient /usr/lib/security/libpam_krb5.1passwd password required /usr/lib/security/libpam_unix.1dtlogin password sufficient /usr/lib/security/libpam_krb5.1dtlogin password required /usr/lib/security/libpam_unix.1dtaction password sufficient /usr/lib/security/libpam_krb5.1dtaction password required /usr/lib/security/libpam_unix.1OTHER password required /usr/lib/security/libpam_unix.1

2.5.5. Configuring SSH1. Ensure that you have version A.05.10.007 or later of ssh installed. A current package can be

downloaded from the HO website at http://software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=T1471AA.

2. Edit the /etc/opt/ssh/ssh_config file:

• Remove any PreferredAuthentications entries.

• Add the following three lines:

Host * GSSAPIAuthentication yes PreferredAuthentications "gssapi-with-mic,publickey,password"

IMPORTANT

Include the tab character before the GSSAPIAuthentication andPreferredAuthentications lines, and include the double quotes around thePreferredAuthentications value.

3. Remove the /etc/krb5.keytab file.

4. Set up the NFS/Kerberos mapping for the Solaris client on the FreeIPA server.

a. Add a host service principal for the HP-UX client.

# ipa service-add host/hpuxipaclient.example.com

b. Create the host keytab file.

# ipa-getkeytab -s ipaserver.example.com -p host/hpuxipaclient.example.com -k /tmp/krb5.keytab -e des-cbc-crc

c. Copy this keytab to the HP-UX machine, and save it as /etc/krb5/krb5.keytab.

http://software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=T1471AA

http://software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=T1471AA

Configuring Access Control

31

# scp /tmp/krb5.keytab [email protected]:/etc/krb5/krb5.keytab

2.5.6. Configuring Access ControlHP-UX systems provide the pam_authz PAM module, which can be used to control login access tothe system based on a user's group membership. For details on how to configure access control withthis module, see the HP documenttion at http://docs.hp.com/en/B3921-60631/pam_authz.5.html.

Example 2.1. pam_authz.policy File: Allow User Access, Deny Admin AccessThis configuration in /etc/opt/ldapux/pam_authz.policy prevents the admin user fromlogging in while still allowing regular users to log in.

# pam_authz.policy.template:## An example file that could be copied over to /etc/opt/ldapux/pam_authz.policy.# pam_authz.policy is a local policy file that PAM_AUTHZ would use to help# determine which users would be allowed to login to the local host.## In this template file, by default, the only active access rule is# "allow:unix_local_user"# All the local users are authorized to login.## The policy file contains one or more access rule. The format of an access# rule is <action>:<type>:<object>## where <action> could be "deny", "allow", "status"# "PAM_SUCCESS", "PAM_PERM_DENIED", "PAM_MAXTRIES"# "PAM_AUTH_ERR", "PAM_NEW_AUTHTOK_REQD",# "PAM_AUTHTOKEN_REQD, "PAM_CRED_INSUFFICIENT",# "PAM_AUTHINFO_UNAVAIL", "PAM_USER_UNKNOWN"# "PAM_ACCT_EXPIRED", "PAM_AUTHOK_EXPIRED"## Note: "status" must use along with "rhds" or# "ads" <type>.# <type> could be "unix_user", "unix_local_user", "unix_group",# "netgroup", ldap_filter", "ldap_group"# "rhds" or "ads"## Note: When <type> is set to "rhds" or "ads",# the <action> filed must set to "status".# <object> contains search information. For example,#

deny:unix_group:adminsallow:unix_local_user

2.5.7. Testing the Configuration

NOTE

By default, the admin user is given /bin/bash as the shell to use and /home/admin as thehome directory. It may be necessary to install bash to be able to log in.

There are three quick ways to check the Kerberos and PAM configuration for the HP client:

http://docs.hp.com/en/B3921-60631/pam_authz.5.html


32

• Attempt to log into the Kerberos realm from the client machine by using the admin credentials:

# kinit admin# klist

• Attempt to log into the HP machine from another machine in the domain using SSH. The admin usershould be able to log in using SSH without being asked for a password.

# ssh [email protected]

• Log into the FreeIPA web UI using the administrator credentials on the HP machine.

2.6. Configuring an AIX System as a FreeIPA Client

2.6.1. PrerequisitesMake sure that all of these packages are installed on the AIX machine before beginning the clientconfiguration:

• v5.3 OS

• v5.3 Updates

• krb5 client packages

• openssh

• wget

• bash

• krb5 server

• ldap.client

• openssl

• modcrypt.base (for gssd)

Configure and enable NTP and make sure that time is synchronized between the client and theFreeIPA server.

2.6.2. Configuring the AIX ClientSetting up an AIX client requires setting up the client to work in the FreeIPA Kerberos domain and,optionally, to enable SSH authentication to the AIX client using FreeIPA credentials.

Kerberos configuration includes specifying the realm and domain details, and default ticket attributes.Forwardable tickets are configured by default, which facilitates connection to the administrationinterface from any operating system, and also provides for auditing of administration operations. Forexample:

1. Configure the krb5 client settings to use the FreeIPA Kerberos domain:

Configuring the AIX Client

33

# mkkrb5clnt -r EXAMPLE.COM -d example.com -c ipaclient.example.com -s ipaserver.example.com

2. Get a Kerberos ticket:

# kinit admin

3. Configure the LDAP client settings to use the FreeIPA directory services:

# mksecldap -c -h ipaserver.example.com -d cn=accounts,dc=example,dc=com -a uid=nss,cn=sysaccounts,cn=etc,dc=example,dc=com -p secret

4. In the /etc/security/ldap directory, create user and group map files:

• For example, for the FreeIPAuser.map file:

#FreeIPAuser.map filekeyobjectclass SEC_CHAR posixaccount s

# The following attributes are required by AIX to be functionalusername SEC_CHAR uid sid SEC_INT uidnumber spgrp SEC_CHAR gidnumber shome SEC_CHAR homedirectory sshell SEC_CHAR loginshell sgecos SEC_CHAR gecos sspassword SEC_CHAR userpassword slastupdate SEC_INT shadowlastchange s

• For example, for the FreeIPAgroup.map file:

#FreeIPAgroup.map filegroupname SEC_CHAR cn sid SEC_INT gidNumber susers SEC_LIST member m

5. Modify the /etc/security/ldap/ldap.cfg file to set the REALM and base DN values for theFreeIPA domain.

userbasedn:cn=users,cn=accounts,dc=example,dc=comgroupbasedn:cn=groups,cn=accounts,dc=example,dc=com

userattrmappath:/etc/security/ldap/FreeIPAuser.mapgroupattrmappath:/etc/security/ldap/FreeIPAgroup.map

userclasses:posixaccount

6. Start the LDAP client daemon:

# start-secldapclntd

7. Test the LDAP client connection to the FreeIPA server:

# lsldap -a passwd


34

8. Add the following sections to the /usr/lib/security/methods.cfg file to configure thesystem login to use Kerberos and LDAP:

KRB5A:program = /usr/lib/security/KRB5Aprogram_64 = /usr/lib/security/KRB5A_64options = authonly

LDAP:program = /usr/lib/security/LDAPprogram_64 =/usr/lib/security/LDAP64

KRB5ALDAP:options = auth=KRB5A,db=LDAP

9. Edit the /etc/security/user file, and modify the default section to use the Kerberos/LDAPsystem and the LDAP user registry.

SYSTEM = "KRB5ALDAP"registry = LDAP

10. To test the Kerberos configuration, log in as a FreeIPA user and verify that the user and groupinformation is correct:

$ id

11. Optionally, configure the FreeIPA client to accept incoming SSH requests and authenticate withthe user's Kerberos credentials.

a. Set the SSH syslog configuration:

auth.info /var/log/sshd.logauth.info /var/log/sshd.logauth.crit /var/log/sshd.logauth.warn /var/log/sshd.logauth.notice /var/log/sshd.logauth.err /var/log/sshd.log

b. Set the SSH logging configuration:

SyslogFacility AUTHLogLevel INFO

c. Configure sshd to use GSSAPI:

vim /etc/ssh/sshd_config

# GSSAPI optionsGSSAPIAuthentication yes#GSSAPICleanupCredentials yes

d. Restart the sshd daemon:

# stopsrc -s sshd# startsrc -s sshd

Configuring the AIX Client

35

e. Restart the syslogd daemon:

# stopsrc -s syslogd# startsrc -s syslogd

f. Add the client to the FreeIPA server's Kerberos configuration.

i. Add a host service principal for the client.

# ipa service-add host/ipaclient.example.com

ii. Retrieve the host keytab.

# ipa-getkeytab -s ipaserver -p host/ipaclient.example.com -k /tmp/krb5.keytab -e des-cbc-crc

iii. Copy the keytab from the server to the client.

# scp /tmp/krb5.keytab [email protected]:/tmp/krb5.keytab

g. On the FreeIPA client, use the ktutil command to import the contents into the main hostkeytab.

# ktutilktutil: read_kt /tmp/krb5.keytabktutil: write_kt /etc/krb5/krb5.keytabktutil: q

h. On the FreeIPA server, add a user that is only used for authentication. (This can be substitutedwith krb5 authentication if that works from the LDAP client). Otherwise go to the FreeIPAserver and use ldapmodify, bind as Directory Manager and create this user. The usershould be assigned a shared password.

ldapmodify -D "cn=directory manager" -w secret -p 389 -h ipaserver.example.com -x -a

dn: uid=nss,cn=sysaccounts,cn=etc,dc=example,dc=comobjectClass: accountobjectClass: simplesecurityobjectobjectClass: topuid: nssuserPassword: secretpassword

i. On the FreeIPA server, get a ticket for the admin user.

# kinit admin

j. To test the SSH configuration, try to log in as the admin user using SSH without providing apassword.



36

NOTE

By default, the admin user is given /bin/bash as the shell to use and /home/admin as thehome directory. It may be necessary to install bash to be able to log in.

2.7. Configuring a Macintosh OS X System as a FreeIPAClientThese instructions are specific to Mac OS X 10.4 (Tiger) because this version includes the requiredKerberos tools by default.

2.7.1. Configuring Kerberos AuthenticationConfiguring the Macintosh to use Kerberos for authentication with FreeIPA is a two-step process. First,Kerberos needs to be correctly installed and configured. Then, Kerberos authentication needs to beenabled.

2.7.1.1. Configuring KerberosSetting up the Kerberos configuration includes specifying the realm and domain details, and defaultticket attributes. Forwardable tickets are configured by default, which facilitates connection to theadministration interface from any operating system, and also provides for auditing of administrationoperations. For example, this is the Kerberos configuration for Fedora systems:

1. Make sure that the Kerberos version is 4.2 or higher. The Kerberos directory is /System/Library/CFMSupport/Kerberos. If that directory does not exist or is the wrong version, installthe Kerberos Extras support.

2. Launch the Kerberos management application. This is in /System/Library/Coreservices/Kerberos.

3. From the Edit menu, choose Edit Realms.

4. In the Settings tab, enter the FreeIPA server's Kerberos realm, for example, EXAMPLE.COM.

5. In the Servers tab, enter the FreeIPA server's hostname for the kdc and admin values:

kdc ipaserver.example.com 88admin ipaserver.example.com 749

6. In the Domains tab, replace the existing domains with the FreeIPA server's actual domain, suchas example.com:

.example.comexample.com

7. Click Make default to create the necessary configuration file, and then close the Kerberos tool.

This creates the /Library/Preferences/edu.mit.kerberos file. Check this file manually toensure that it is correct. For example:

[domain_realm]example.com = EXAMPLE.COM

Configuring LDAP Authorization

37

.example.com = .EXAMPLE.COM

[libdefaults]default_realm = EXAMPLE.COMdns_lookup_realm = truedns_lookup_kdc = trueticket_lifetime = 24hforwardable = yes

[realms]EXAMPLE.COM = { admin_server = ipaserver.example.com:749 default_domain = example.com kdc = ipaserver.example.com:88 }

2.7.1.2. Enabling Kerberos Authentication1. Log in as the admin user and launch a terminal.

2. Change to the /private/etc directory and make a backup of the existing authorization file.

# cd /private/etc

# cp -p authorization authorization_bak

3. Open the authorization file.

# vim /private/etc/authorization

4. Locate the string system.login.console, and then edit the dict and the mechanisms entryjust beneath this line.

5. Change authinternal to builtin:krb5authnoverify,privileged.

WARNING

Several instances of authinternal may occur in this file. Change only the instance forsystem.login.console.

6. Save and close the file.

7. Restart the machine to enable Kerberos authentication.

2.7.2. Configuring LDAP Authorization

2.7.2.1. Creating the LDAP Configuration1. Launch the Directory Access utility.

2. In the Services tab, clear all check boxes except LDAPv3 and Bonjour.

3. Select the LDAPv3 entry, and click Configure.


38

4. Make sure the Add DHCP-supplied LDAP servers checkbox is not selected.

5. Click the arrow next to the Show Options label, and then click New.

6. Enter the server hostname in the Server Name field, such as ipaserver.example.com.

7. Clear the Encrypt using SSL checkbox, and then click Manual.

8. Enter the configuration name, such as FreeIPA LDAP.

9. Select the Enable checkbox, and clear the SSL checkbox.

2.7.2.2. Setting up the LDAP Service Configuration Options1. Select the newly-created LDAP configuration, and click Edit.

2. In the Connection tab, specify the connection settings:

a. Open/close times out in 10 seconds

b. Query times out in 10 seconds

c. Re-bind attempted in 10 seconds

d. Connection idles out in 1 minute

Clear all checkboxes.

3. In the Search & Mappings tab, set the Access this LDAP server using value to CUSTOM.

4. Still in the Search & Mappings tab, configure the naming attributes used by entries:

a. In the Record Types and Attributes panel, select Default Attribute Types.

b. Click Add.

c. Select the Attribute Types option, then select RecordName from the list.

d. Select the newly-added RecordName attribute, and then click Add under the Map to anyitems in list panel.

e. Type uid in the text box to set the LDAP attribute used for naming. Click outside the text boxto set the value.

5. Still in the Search & Mappings tab, add a users record:

a. Under the Record Types and Attributes panel, click Add.

b. Select the Record Types option, and select Users from the list.

c. Select the newly-added Users record type, and then click Add under the Map to any items inlist panel.

d. Type inetOrgPerson in the text box. Click outside the text box to set the value.

e. In the Search base field, type the base DN of the FreeIPA LDAP service, such asdc=example,dc=com

f. Select the Search in all subtrees option.

Configuring the LDAP Authorization Options

39

6. Add attributes to the users record as appropriate.

a. Under the Record Types and Attributes panel, click Add.

b. Select the Attribute Types option, and then use Ctrl to select multiple attributes. Commonattributes to add include:

• AuthenticationAuthority

• PrimaryGroupID

• RealName

• RecordName

• UniqueID

• UserShell

7. Specify appropriate mappings for the new attributes. Select the Authentication Authority recordtype, and then click Add under the Map to any items in list panel. The attribute mappings havethe format #;Mac-attribute;;$LDAP-attribute$;value. For example, for the Kerberosv5 principal,the UID, and the realm, the mapping is #;Kerberosv5;;$uid$;EXAMPLE.COM. These arecommon mappings:

• Kerberosv5 and UID

• PrimaryGroupID and gidNumber

• UniqueID and uidNumber

8. Click OK to finish setting up the LDAP service configuration options.

2.7.3. Configuring the LDAP Authorization Options1. In the Authentication tab, change the Search value to Custom path.

2. Click Add.

3. Select the configuration created in Section 2.7.2.2, “Setting up the LDAP Service ConfigurationOptions”, and click Add.

4. Click Apply to update the LDAP configuration.

2.7.4. Configuring NTPOpen the Date and Time utility and point it to the FreeIPA server URL to set the date and timeautomatically.

2.7.5. Testing the ConfigurationIf client authentication is properly configured, a user can connect to the FreeIPA server using SSHwithout being prompted for a password.

1. Obtain a Kerberos ticket for the admin user.

# kinit admin


40

2. Log into the server using SSH.


Also, check the system login.

1. Log in as a FreeIPA user.

2. Check the user ID to make sure that both the user and group IDs are correct for the currentaccount.

$ id

uid=10678(jsmith) gid=10678(jsmith) groups=3(sys),100(users),1070(devel2),10678(jsmith)

3. Then, check that there is a valid Kerberos ticket.

$ klist

Ticket cache: FILE:/tmp/krb5cc_10678Default principal: [email protected]

Valid starting Expires Service principal05/12/11 12:12:26 05/12/11 22:12:26 krbtgt/[email protected] renew until 05/12/11 12:12:26

Kerberos 4 ticket cache: /tmp/tkt10678klist: You have no tickets cached

2.8. Uninstalling a FreeIPA ClientFor Fedora clients, the ipa-client-install utility can be used to uninstall the client and remove itfrom the FreeIPA domaine. To remove the client, use the --uninstall option.

# ipa-client-install --uninstall

NOTE

There is an uninstall option with the ipa-join command. This is called by ipa-client-install --uninstall as part of the uninstallation process. However, while the ipa-joinoption removes the client from the domain, it does not actually uninstall the client or properlyremove all of the FreeIPA-related configuration. Do not run ipa-join -u to attempt to uninstallthe FreeIPA client. The only way to uninstall a client completely is to use ipa-client-install--uninstall.

Chapter 3.

41

Basic UsageAll of the access to FreeIPA, both through the web UI and through the command line, is done by auser authenticating to the FreeIPA domain. This chapter covers the basics of setting up browsers tohandle Kerberos authentication, logging into FreeIPA, and troubleshooting some common connectionissues.

3.1. Running FreeIPA ToolsThe FreeIPA command-line tools are run as any other utilities in a shell. If there are special charactersin the command — such as angle brackets (> and <), ampersands (&), asterisks (*), and pipes (|) —the characters must be escaped. Otherwise, the command fails because the shell cannot properlyparse the unescaped characters.

3.2. Logging into FreeIPAUsers are authenticated to FreeIPA services, including the command-line tools and the web UI, usingKerberos authentication. This means that logging into FreeIPA requires running kinit.

As a result of this operation you will acquire what is known as a Kerberos ticket. You can use theklist command to inspect the details of the ticket that you have acquired.

3.2.1. Logging into FreeIPALogging into FreeIPA requires running kinit. Simply running kinit logs into FreeIPA as thecurrently logged-in user account. This user account must also be an FreeIPA user for them toauthenticate to the FreeIPA Kerberos domain successfully. For example, if you are logged into themachine as jsmith:

$ kinitPassword for [email protected]:

NOTE

If SSSD or pam_krb5 is configured on the FreeIPA client machine, then when a user logsinto the machine, a ticket is created which can be used for machine serivces which requireauthentication, such as sudo.

3.2.2. Logging in When an FreeIPA User Is Different Than theSystem UserTo specify an FreeIPA username — because a person's system username is different then theFreeIPA username or to switch FreeIPA user accounts — simply rerun the kinit command,specifying the new user. For example:

$ kinit userName Password for [email protected]:

When the server was first set up, an administrative user, admin, is created to perform normaladministrative activities. To authenticate as the admin user, use the name admin when running kinit:

$ kinit admin

Chapter 3. Basic Usage

42

NOTE

Only one set of tickets can be stored per logged-in user. The current stored credentials are theones that will be used when accessing FreeIPA services.

If you were already connected to the FreeIPA web UI as another user, refresh the browser todisplay the updated details for the new user.

3.2.3. Checking the Current Logged in UserUse the klist command to verify the identity and the ticket granting ticket (TGT) from the server:

$ klistTicket cache: FILE:/tmp/krb5cc_500Default principal: [email protected]

Valid starting Expires Service principal11/10/08 15:35:45 11/11/08 15:35:45 krbtgt/[email protected]

Kerberos 4 ticket cache: /tmp/tkt500klist: You have no tickets cached

It's important to know who the authenticated user is because the currently-authenticated user is theonly one who can access the FreeIPA services. The Kerberos client libraries for kinit have somelimitation, one of them being that the current ticket is overwritten with any new invocation of kinit.Authenticating as User A and then authenticating as User B overwites User A's ticket.

To allow there to be multiple authenticated users on a machine, set the KRB5CCNAME environmentvariable. This variable keeps credential caches separate in different shells.

3.3. Opening the FreeIPA Web UIThe browser must be properly configured, as described in Section 3.4, “Configuring the Browser”, tosupport Kerberos authentication so that the user can connect to the UI.

To open the web UI:

1. Get a valid Kerberos ticket using kinit, as in Section 3.2, “Logging into FreeIPA”.

2. Open the FreeIPA URL. The full URL is http://IPAserver-FQDN/ipa/ui, but this service isalso accessed simply by opening http://IPAserver-FQDN. For example:

http://server.example.comhttp://server.example.com/ipa/ui

3.4. Configuring the BrowserFirefox can use Kerberos credentials to authenticate to the FreeIPA UI, but Kerberos negotiationneeds to be configured to use the FreeIPA domain.

1. Open Firefox.

2. Type about:config in the address bar.

3. In the Search field, type negotiate to filter out the Kerberos-related parameters.

Configuring the Browser

43

4. On Fedora, enter the domain name for the URI parameters, including the preceding period (.) andset the gsslib parameter to true:

network.negotiate-auth.trusted-uris .example.comnetwork.negotiate-auth.delegation-uris .example.comnetwork.negotiate-auth.using-native-gsslib true

On Windows, enter the domain name for the URI parameters, including the preceding period (.)and set the sspi parameter to false:

network.negotiate-auth.trusted-uris .example.comnetwork.auth.use-sspi falsenetwork.negotiate-auth.delegation-uris .example.com

5. Open the web UI by going to the fully-qualified domain name of the FreeIPA server such ashttp://ipaserver.example.com. Make sure that you can open the web UI and that there areno Kerberos authentication errors.

6. Next, download the FreeIPA server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.

7. Select the first (Trust this CA to identify web sites) and third (Trust this CA to identifysoftware developers) check boxes.

8. Click OK.


44

3.5. Using a Browser on Another SystemIt is possible to connect to the FreeIPA web UI from a system which is not a member of the FreeIPAdomain. In this case, it is possible to specify a FreeIPA-specific Kerberos configuration file on theexternal (non-FreeIPA) machine before running kinit, and then the user can authenticate against theFreeIPA server domain.

This is especially useful there are multiple realms or overlapping domains across your infrastructure.

1. Copy the /etc/krb5.conf file from the FreeIPA server.

# scp /etc/krb5.conf [email protected]:/etc/krb5_ipa.conf

WARNING

Do not overwrite the existing krb5.conf file.

2. On the external machine, set the terminal session to use the copied FreeIPA Kerberosconfiguration file:

$ export KRB5_CONFIG=/etc/krb5_ipa.conf

3. Configure Firefox on the external machine as in Section 3.4, “Configuring the Browser”.

3.6. Enabling Username/Password Authentication in YourBrowserIf Kerberos authentication fails, then browser login also fails. That prevents access to the FreeIPA webUI. Configuring username/password authentication for the UI allows users to log in even if there areproblems with the Kerberos service.

1. Open the ipa.conf file used by the Apache web service.

vim /etc/httpd/conf.d/ipa.conf

2. In the <Location "/ipa"> location definition, change the KrbMethodK5Passwd attribute fromoff to on.

KrbMethodK5Passwd on

3. Restart the httpd service:

# service httpd restart

When this is configured, the web UI prompts for a FreeIPA username and password if it can't detectany Kerberos credentials.

Troubleshooting UI Connection Problems

45

Figure 3.1. FreeIPA Password Prompt

NOTE

This must be configured on every FreeIPA server in the domain.

3.7. Troubleshooting UI Connection ProblemsIf negotiate authentication is not working, turn on verbose logging for the authentication process tohelp diagnose the issue:

1. Close all browser windows.

2. In a terminal, set the new log levels for Firefox:

export NSPR_LOG_MODULES=negotiateauth:5export NSPR_LOG_FILE=/tmp/moz.log

This enables verbose logging and logs all information to /tmp/moz.log.

3. Restart the browser from the same terminal window and attempt t .

Some of the common error messages and workarounds are in Table 3.1, “UI Error Log Messages”.

Table 3.1. UI Error Log Messages

Error Log Message Description and Fix

-1208550944[90039d0]: entering nsNegotiateAuth::GetNextToken()-1208550944[90039d0]: gss_init_sec_context() failed: Miscellaneous failureNo credentials cache found

There are no Kerberos tickets. Run kinit.

-1208994096[8d683d8]: entering nsAuthGSSAPI::GetNextToken()-1208994096[8d683d8]: gss_init_sec_context() failed: Miscellaneous failure

This can occur when you have successfullyobtained Kerberos tickets but are still unable toauthenticate to the UI. This indicates that thereis a problem with the Kerberos configuration.


46

Error Log Message Description and FixServer not found in Kerberos database The first place to check is the [domain_realm]

section in the /etc/krb5.conf file. Makesure that the FreeIPA Kerberos domain entryis correct and matches the configuration in theFirefox negotiation parameters. For example:

.example.com = EXAMPLE.COMexample.com = EXAMPLE.COM

Nothing is in the log file. It is possible that you are behind a proxy whichis removing the HTTP headers required fornegotiate authentication. Try to connect to theserver using HTTPS instead, which allows therequest to pass through unmodified. Then checkthe log file again.

Chapter 4.

47

Identity: Managing Users and UserGroups

4.1. Setting up User Home DirectoriesA home directory is required for any FreeIPA user. Without a home directory in the expected location,a user may be unable to log into the domain. While systems administrators can manage homedirectories outside of FreeIPA, it is also possible to use a PAM module to create home directoriesautomatically on both FreeIPA servers and clients.

4.1.1. About Home DirectoriesFreeIPA, as part of managing users, can manage user home directories. However, FreeIPA hascertain defined parameters for any managed home directories:

• The default prefix for users' home directories is /home.

• FreeIPA does not automatically create home directories when users log in. Automatically creatinghome directories requires either the pam_oddjob_mkhomedir module or the pam_mkhomedirmodule. This module can be configured as part of client installation or after installation, as describedin Section 4.1.2, “Enabling the PAM Home Directory Module”.

The home directory process for FreeIPA first attempts to use the pam_oddjob_mkhomedir modulebecause this requires fewer user privileges and access to create the home directories, as well asintegrating smoothly with SELinux. If this module is not available, then the process falls back to thepam_mkhomedir module.

• It is possible to use an NFS file server that provides /home that can be made available to allmachines in the domain and then automounted on the FreeIPA server. Using automounts for homedirectories is described in Section 4.1.3, “Manually Automounting Home Directories”.

• If a suitable directory and mechanism are not available for to create home directories, users may notbe able to log in.

4.1.2. Enabling the PAM Home Directory ModuleFor a home directory to be created automatically when a user logs in, FreeIPA can use either thepam_oddjob_mkhomedir module or the pam_mkhomedir module. Because it requires fewerpermissions and works well with SELinux, FreeIPA preferentially uses the pam_oddjob_mkhomedirmodule. If that module is not installed, then it falls back to the pam_mkhomedir module.

NOTE

FreeIPA does not require the pam_oddjob_mkhomedir module or pam_mkhomedir modulebecause it may try to create home directories even when the shared storage is not available. Thesystem administrator must activate this module on each client or server as needed.

There are two ways to enable the pam_oddjob_mkhomedir (or pam_mkhomedir) module:

• The --mkhomedir option can be used with the ipa-client-install command. While this ispossible for clients, this option is not available to servers when they are set up.

Chapter 4. Identity: Managing Users and User Groups

48

• The pam_oddjob_mkhomedir module can be enabled using the system's authconfigcommand. For example:

authconfig --enablemkhomedir

This option can be used for both server and client machines post-installation.

4.1.3. Manually Automounting Home DirectoriesWhile PAM modules can be used to create home directories for user automatically, this may not bedesireable behavior in every environment. In that case, home directories can be manually added to theFreeIPA server from separate locations using NFS shares and automount.

1. Create a new location for the user directory maps:

$ ipa automountlocation-add userdirsLocation: userdirs

2. Add a direct map to the new location's auto.direct file. In this example, the mount point is /share:

$ ipa automountkey-add userdirs auto.direct --key=/share --info="-ro,soft, ipaserver.example.com:/home/share"

Key: /shareMount information: -ro,soft, ipaserver.example.com:/home/share

Using automounts with FreeIPA is described in detail in Chapter 7, Identity: Using Automount.

4.2. Adding UsersFreeIPA supports a wide range of username formats, but you need to be aware of any restrictions thatmay apply to your particular environment. For example, a username that starts with a digit may causeproblems for some UNIX systems.

The range of username formats supported by FreeIPA can be described by the following regularexpression:

[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]

The trailing $ symbol is permitted for Samba 3.x machine support.

Use the ipa user-add command to add users to FreeIPA. You can pass attributes directly on thecommand line, or run the command with no parameters to enter interactive mode. Interactive modeprompts you to enter the basic attributes required to add a new user. You can add further attributesusing the ipa user-mod command. Use the ipa user-mod --list command to view a list of theattributes that you can modify using this command.

Procedure 4.1. To create the user jlamb using the command line:• Open a shell and run the following command:

$ ipa user-add jlamb --first=John --last=Lamb --password

This will prompt for a password and then complete the new entry with default values.

Adding Users

49

The following example illustrates using the ipa user-add command in interactive mode to create auser account:

# ipa user-addFirst name: JinnyLast name: PattanajeeUser login [jpattanajee]: jpattan--------------------Added user "jpattan"--------------------User login: jpattanFirst name: JinnyLast name: PattanajeeHome directory: /home/jpattanGECOS field: jpattanLogin shell: /bin/shKerberos principal: [email protected]: 387115841

Press Enter at each prompt to accept the default values (enclosed in square brackets), or type analternative.

Refer to the ipa user-add help page for more information.

IMPORTANT

When a user is created without specifying a UID or GID number, then the user account isautomatically assigned an ID number that is next available in the server or replica range.(Number ranges are described more in Section 13.3, “Managing Unique UID and GID NumberAssignments”.) This means that a user always has a unique number for its UID number and, ifconfigured, for its private group.

If a number is manually assigned to a user entry, the server does not validate that theuidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behaviorfor Posix entries.

If two entries are assigned the same ID number, only the first entry is returned in a search forthat ID number. However, both entries will be returned in searches for other attributes or with ipauser-find --all.

You can now authenticate using the newly-created user and temporary password. Type kinituserLogin to log in to FreeIPA. This will prompt you for a password and then immediately request apassword change.

NOTE

Only one set of tickets can be stored per logged-in user. The current stored credentials are theones that will be used when accessing FreeIPA services.

If you authenticated as admin, added a new user, set the password, and then tried toauthenticate as that user, the administrator's ticket is lost. To prevent this from happening, aspecial environment variable, KRB5CCNAME, can be used. This allows you to keep credentialcaches separate in different shells.


50

4.3. Editing UsersUse the ipa user-mod command to modify user account details, such as adding, removing orchanging attributes. Refer to the following examples:

To update attributes for the user jsmith:

$ ipa user-mod jsmith [email protected] --title=Editor

To retrieve a list of attributes for a user:

$ ipa user-show --raw userName

The list of attributes corresponds to those available in the web interface, not including any customattributes that may have been defined.

4.4. Activating and Deactivating User AccountsFreeIPA user accounts can be set to a status of Active or Inactive. If you deactivate a useraccount, that user can no longer log in to FreeIPA, change their password, or perform any other tasks.Any existing connections will remain valid until their Kerberos TGT and other tickets expire, butthey will not be able to renew them. The account and all associated information still exists, but isinaccessible by the user.

4.4.1. Using the Command LineUse the ipa user-enable and ipa user-disable commands to enable and disable useraccounts, respectively. Refer to the following examples:

To disable the jsmith user account:

$ ipa user-disable jsmith

To enable the jsmith user account:

$ ipa user-enable jsmith

4.5. Specifying Default User SettingsYou can configure the default settings for FreeIPA users to suit your deployment. For example, youcan specify the maximum username length, the default path to the /home directory, the default shell,and other attributes.

FreeIPA supports the following User Settings:

• Maximum Username Length (ipaMaxUsernameLength): The maximum length of any username.The default value is eight.

• Root for Home Directories (ipaHomesRootDir): The root directory for all home directories. Thedefault value is /home.

• Default Shell (ipaDefaultLoginShell): The default shell for all user accounts. The default value is /bin/sh.

• Default User Group (ipaDefaultPrimaryGroup): The default group to which all newly createdaccounts are added. The default value is ipausers, which is automatically created during theFreeIPA server installation process.

Setting Default Search Limits

51

• Default E-mail Domain (ipaDefaultEmailDomain): The default domain used to create emailaddresses for all newly created accounts. The default is the domain to which the FreeIPA serverbelongs.

Use the ipa config-mod command to modify the default configuration attributes. The following is anexample of how to set the maximum username length to 64 characters, and the default home directoryto /users/home:

# ipa config-mod --maxusername=64 --homedirectory=/users/homeMax username length: 64Home directory base: /users/homeDefault shell: /bin/shDefault users group: ipausersDefault e-mail domain: mydomain.netSearch time limit: 2Search size limit: 100User search fields: uid,givenname,sn,telephonenumber,ou,titleGroup search fields: cn,descriptionMigration mode: FALSECertificate Subject base: O=MYDOMAIN.NET

Refer to the ipa help config page for more information.

Note

The default root directory for all home directories is /home, but it is the responsibility of thesystem administrator to ensure that whatever value is specified for this attribute is actuallyavailable.

Fedora includes a PAM module called pam_mkhomedir that can automatically create a homedirectory if one does not exist for the user authenticating against the system. FreeIPA does notforce the use of this module because it may try to create home directories even when the sharedstorage is not available. It is the responsibility of the system administrator to activate this moduleon the clients if needed.

4.6. Setting Default Search LimitsYou can set limits on the number of records returned when performing various queries, for examplewhen you run the ipa user-find command. These limits are specified by the Search sizelimit attribute in the default FreeIPA configuration. The default value for this attribute is 100.

To view the current configuration, run the # ipa config-show command. Refer to theipa help config help page for more information.

The following is a sample FreeIPA configuration:

[ming@myserver ~]$ ipa config-showMax username length: 32Home directory base: /homeDefault users group: ipausersDefault e-mail domain: mydomain.netSearch time limit: 2Search size limit: 20User search fields: uid,givenname,sn,telephonenumber,ou,titleGroup search fields: cn,descriptionCertificate Subject base: O=MYDOMAIN.NET


52

You can use the ipa config-mod command to specify a suitable value for the Search sizelimit attribute. For example, if you set this value to 10, the ipa user-find command will onlyreturn 10 entries, even if many more entries exist. If you set this value to 0 (zero) or −1, it means thatthere are no restrictions on the number of entries that can be returned.

Setting search size limits1. To set the Search size limit attribute to 50, run the following command:

# ipa config-mod --searchrecordslimit=50

Important

You need to be aware of the potential performance impact of setting the search size limit too high.You need to determine a suitable balance between the benefits of always returning all entriesmatched by a search, and the performance gained by implementing a search filter.

Note also that if the size limit is set too high or removed completely it might affect the behavior ofUI screens.

You can configure various aspects of the FreeIPA search functionality to suit your deployment. Forexample, you can restrict the number of fields upon which a user can base a search, or limit thenumber of records returned for any particular search.

FreeIPA supports the following search configuration attributes:

• Search Time Limit: The maximum time, in seconds, that a search will run before failing.

• Search Records Limit: The maximum number of records that a search can return. Set thisvalue to zero (0) to specify no limit. The directory server limit (the default value is 2000) still applies.

• User Search Fields: For a user search, specifies the fields to search for the values entered bya user.

• Group Search Fields: For a group search, specifies the fields to search for the values enteredby a user.

Use the ipa config-mod command to modify the default configuration attributes. For example, tospecify a search time limit of 60 seconds, use the following command:

# ipa config-mod --searchtimelimit=60

Refer to the ipa help config page for more information.

If you add attributes to the user or group search fields, you should also create a new LDAP index forthose attributes to avoid performance degradation. Conversely, the existence of too many indexes canimpact write performance, so you need to balance one against the other.

Refer to Creating Indexes1 in the 389 Directory Server Administration Guide for information oncreating indexes.

1 http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Managing_Indexes-Creating_Indexes.html

http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Managing_Indexes-Creating_Indexes.html

http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Managing_Indexes-Creating_Indexes.html

Deleting FreeIPA Users

53

4.7. Deleting FreeIPA UsersIf you delete a FreeIPA user account, all of the information stored in the entry for that identity is lost.This includes the user's full name, group membership, phone numbers, and passwords. The actualuser account and home directory still exist, be they on a server, local machine, or other provider, butthey are no longer accessible by FreeIPA.

Unlike deactivation, if you delete a user account, it cannot be retrieved. If you need this user accountagain, you need to recreate it and add all of the account details manually.

Note

Unlike in earlier versions of FreeIPA, it is now possible to delete the admin user. If, however, youdelete all of the admin users then you will need to use the Directory Manager account to create anew administrative user. Alternatively, if you have a user in the group management role, they canadd a new admin user.

4.7.1. Using the Command LineUse the ipa user-del command to delete user accounts. For example:

To delete the jsmith user account:

$ ipa user-del jsmith

If you intend to delete multiple users, you can use the --continue option to prevent the commandfrom stopping should it encounter any errors. For example:

$ ipa user-del --continue user_01 user_02 user_03

If you run this command without using the --continue option, FreeIPA will delete the listed useraccounts unless it encounters any errors, at which point it stops. For example, if user_02 did notexist, the previous command would only delete user_01; user_03 would not be affected.

The --continue option returns a summary of successes and failures to stdout.

4.8. Creating User GroupsFreeIPA uses groups to facilitate the management and administration of all types of objects, suchas users, hosts, tasks, roles, and others. This section introduces User Groups and how they areused within FreeIPA. Other object groups behave and are used in similar ways; these are discussedelsewhere.

User GroupsThree groups are created during the installation process: ipausers, admins, and editors. All ofthese groups are required for FreeIPA operation.

The FreeIPA Administrator is a member of the admins group. All other users belong to the globalgroup ipausers, and you can create as many additional groups as you require.


54

Note

Some operating systems limit the number of groups that you can create. For example, Solarisand AIX allow only 16 groups per user. FreeIPA Administrators need to be aware of thislimitation, especially when using nested groups.

The editors group is a special group used by the web interface. Members of this group have at leastone delegation, which means they can edit records apart from their own.

You can create groups based on the departments within your organization, for example, Development,Finance, and HR. You can also create groups based on the permissions, or roles, required to manageyour departmental or other groups.

Nested GroupsYou can also create nested groups. For example, you can create a group called "Documentation",and then create sub-groups such as "Writers", "Translators", and "Editors". You can add users toeach of the sub-groups to suit the needs of your organization. Any users that you add to a sub-groupautomatically become members of the parent group.

Warning

Avoid the creation of cyclic groups; that is, groups that contain groups that in turn contain theirown ancestors, and avoid creating group names that contain spaces. Either of these conditionscan lead to unexpected behavior.

4.8.1. Creating FreeIPA Groups

4.8.1.1. Using the Command LineUse the ipa group-add command to add groups. You can include attributes on the command line oruse the command interactively. For example:

To create a group called "Engineering" using the command line:

$ ipa group-addGroup name: EngineeringDescription: All members of the engineering group-------------------------Added group "engineering"------------------------- Group name: Engineering Description: All members of the engineering group GID: 387115842

Alternatively, include all of the required attributes on the command line:

$ ipa group-add --desc='All authors, editors, and translators' Documentation---------------------------Added group "documentation"--------------------------- Group name: documentation Description: All authors, editors, and translators GID: 387115845

Editing FreeIPA Groups

55

The group name and description are mandatory fields. If either of these are not included on thecommand line, you will be prompted to include them.

IMPORTANT

When a group is created without specifying a GID number, then the group entry is assigned theID number that is next available in the server or replica range. (Number ranges are describedmore in Section 13.3, “Managing Unique UID and GID Number Assignments”.) This means that agroup always has a unique number for its GID number.

If a number is manually assigned to a group entry, the server does not validate that thegidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behaviorfor Posix entries.

If two entries are assigned the same ID number, only the first entry is returned in a search forthat ID number. However, both entries will be returned in searches for other attributes or with ipagroup-find --all.

Adding members to a new groupYou cannot add members to a newly-created group using the ipa group-add command. First youneed to create the group, and then use the ipa group-add-member command to add members.For example:

$ ipa group-add-member --users=user01,user02,user03 engineering Group name: engineering Description: All members of the engineering group GID: 387115842 Member users: user01,user02,user03-------------------------Number of members added 3-------------------------

You can use the same process to create nested groups:

$ ipa group-add-member --groups=group01,group02 engineering Group name: engineering Description: All members of the engineering group GID: 387115842 Member groups: group01,group02 ------------------------- Number of members added 2 -------------------------

4.8.2. Editing FreeIPA GroupsYou can edit many of the attributes that define a group, as well as add or remove members. Someattributes are read-only by default, however you can edit these attributes if required.

You cannot edit the group name. The group name is the primary key, so changing it is the equivalentof deleting the group and creating a new one.

4.8.2.1. Using the Command LineUse the ipa group-mod command to modify specific attributes of FreeIPA groups. FreeIPA providesnumerous commands for working with groups, such as ipa group-add-member and ipa group-


56

detach; run the ipa help group command to access the FreeIPA group help page for moreinformation.

4.8.3. Deleting FreeIPA GroupsWhen you delete a FreeIPA group, only the immediate group is removed; members of the group arenot affected.

When you delete a FreeIPA group, any delegations that apply to that group are also removed. Forexample, suppose you added an "EngineeringManager" group specifically to set up delegations for theEngineering Manager. If you delete the EngineeringManager group, then those delegations are alsolost. These delegations cannot be retrieved. If you need this group and delegation again, you need torecreate them.

4.8.3.1. Using the Command LineUse the ipa group-del command to delete groups. For example:

To delete the Engineering group:

$ ipa group-del Engineering

4.9. Setting an Individual Password PolicyFreeIPA has a default policy of never exposing passwords, even hashed passwords, to clients, in theinterests of system security. This policy applies even if you still rely on NIS server functionality to somedegree, for example, as a result of a full or partial migration from NIS to FreeIPA. FreeIPA normallyexpects a switch to Kerberos for authentication, but this may not always be possible.

The FreeIPA password policy supports the specification of various password attributes that help toensure the security of your system, and also that of individual user accounts. You can specify thepassword lifetime, length, and the types of characters required, all as part of the FreeIPA passwordpolicy.

Note

• In Fedora 15, the FreeIPA password policy is enforced by the KDC. Only a limited number ofattributes are currently supported, but this will be extended in later versions.

• Because the password policy is enforced by the KDC, any further policy specifications that youimplement as part of the Directory Server password policy will not be visible in FreeIPA, andneither will they be enforced.

• Different rules apply to changing passwords, depending on your login credentials.

4.9.1. Changing Passwords as the Directory ManagerIf you reset a password using cn=Directory Manager credentials (only possible if you manuallyperform an LDAP password change operation) then you override any checks and the password is setto whatever you specify. The FreeIPA password policy is ignored.

4.9.2. Changing Passwords as the FreeIPA AdministratorIf you reset a password using admin credentials (that is, as part of the admins group), the FreeIPApassword policy is ignored, but the expiration date is set to "now". This means that the user is forced

Changing Passwords as a Regular User

57

to change the password at login time, and the password policy is then enforced. This is also true forusers who have had password changing rights delegated to them.

Consequently, the FreeIPA Administrator can easily create users with "default" passwords and resetuser's passwords, but will not know the actual, final password entered by the user. Further, anypassword that is transmitted from the FreeIPA Administrator to the user, even over insecure channels,is a temporary password. Consequently, it is not critical if it is accidentally disclosed, provided that theuser promptly resets it.

4.9.3. Changing Passwords as a Regular UserIf you are logged in as a regular user (that is, you are not part of the admins group, or possessedof any elevated privileges), then you can only change your own password, and these changes arealways subject to the FreeIPA password policy.

4.9.4. Editing the Password PolicyYou can use either the web interface or the command line to edit the FreeIPA password policy.However, you can only edit those attributes supported by FreeIPA.

4.9.4.1. Using the Command LineUse the ipa pwpolicy-* commands to create and modify FreeIPA password policies.These commands are provided as part of the ipa pwpolicy plug-in functionality. Theipa help pwpolicy command displays the help page and some examples of using this plug-in.

For example, use the following command to update the minimum global password length to 10characters, and to specify that no history of passwords be kept:

# ipa pwpolicy-mod --minlength=10 --history=0

To display the global password policy:

# ipa pwpolicy-show

Refer to Section 4.9.6, “Password Policy Attributes” for information on password policy attributes.

4.9.5. Setting Different Password Policies for Different User GroupsThe FreeIPA password policy plug-in (ipa pwpolicy) manages both global and per-group passwordpolicies. You can use this plug-in to display or modify existing password policies to suit the needs ofyour environment.

The following examples demonstrate how to display and modify existing password policies.

To display the password policy for a specific group:

# ipa pwpolicy-show --group=example

To add a new policy for a specific group:

# ipa pwpolicy-add --minlife=10 --priority=10 --group=example


58

Note

When adding or modifying the password policy for a group, that group needs to already exist butdoes not need to contain any members.

To remove an attribute from a password policy, use the ipa pwpolicy-mod command to set anempty value for the required attribute to delete it.

The following example illustrates adding a password policy with three specific attributes to an existinggroup:

# ipa pwpolicy-add --minlife=1 --maxlife=5 --priority=1 g1Group: g1Max lifetime (days): 5Min lifetime (hours): 1Priority: 1

The following command uses the ipa pwdpolicy-mod command to set an empty value to theminlife attribute:

# ipa pwpolicy-mod --minlife= g1Group: g1Max lifetime (days): 5

To display the policy for a given user:

# ipa pwpolicy-show --user=tuser1

Note

Password policies are not cumulative. That is, you cannot override a single setting in a policy andlet it fall back to the global policy on all the others; it is all or nothing.

4.9.5.1. Setting the Priority of Password PoliciesThe following example demonstrates the use of password priority, where a user and two groups arecreated, with a separate password policy for each group. Each policy has a different priority, and theuser is added to both groups.

1.Adding a userUse the ipa user-add command to add a new user:

# ipa user-add --first=Tim --last=User tuser1---------Added user "tuser1"--------- User login: tuser1 First name: Tim Last name: User Home directory: /home/tuser1 GECOS field: tuser1 Login shell: /bin/sh Kerberos principal: [email protected]

Setting Different Password Policies for Different User Groups

59

2. Use the ipa group-add command to add two new groups:

# ipa group-add --desc=Group1 g1----------Added group "g1"---------- Group name: g1 Description: Group1

# ipa group-add --desc=Group2 g2----------Added group "g2"----------Group name: g2Description: Group2

3. Use the ipa pwpolicy-add command to specify different policies for each group:

# ipa pwpolicy-add --minlife=10 --priority=10 --group=g1---------------------------Added policy for group "g1"--------------------------- Group: g1 Minimum lifetime (in hours): 10

# ipa pwpolicy-add --minlife=20 --priority=20 --group=g2---------------------------Added policy for group "g2"--------------------------- Group: g2 Minimum lifetime (in hours): 20

4. Use the ipa group-add-member command to add the user that you previously created to eachgroup. You can then use the ipa pwpolicy-show command to display the policy that is in effectfor the user.

1. Add the user to the g1 group and then check the policy:

$ ipa group-add-member --users=tuser1 g1 Group name: g1 Description: Group1 Member Users: tuser1 Users: Groups:-------------------------Number of members added 1-------------------------

$ ipa pwpolicy-show --user=tuser1 Group: g1 Minimum lifetime (in hours): 10

2. Add the user to the g2 group and recheck the policy:

$ ipa group-add-member --users=tuser1 g2 Group name: g2 Description: Group2


60

Member Users: tuser1 Users: Groups:-------------------------Number of members added 1-------------------------


Notice that the password policy that is in effect for the user tuser1 is taken from the g1group, because it has a higher priority.

5. Finally, use the ipa group-remove-member command to remove the user from the g1 groupto demonstrate that they still have a custom policy.

$ ipa group-remove-member --users=tuser1 g1---------------------------Number of members removed 1--------------------------- Users: Groups:


4.9.6. Password Policy AttributesThe password policy is enforced by the pwd_extop SLAPI plug-in. FreeIPA supports the followingpassword policy attributes:

• Minimum Password Lifetime (krbMinPwdLife): The minimum period of time, in hours, that a user'spassword must be in effect before the user can change it. The default value is one hour.

You can use this attribute to prevent users from changing their password to a "temporary" value andthen immediately changing it back to the original value.

• Maximum Password Lifetime (krbMaxPwdLife): The maximum period of time, in days, that auser's password can be in effect before it must be changed. The default value is 90 days.

• Minimum Number of Character Classes (krbPwdMinDiffChars): The minimum number of differentclasses, or types, of character that must exist in a password before it is considered valid. Thedefault value is 0 (zero).

For example, setting krbPwdMinDiffChars = 3 requires that passwords contain at least onecharacter from three of the supported classes. There are six supported character classes:

• Upper-case characters

• Lower-case characters

• Digits

• Special characters (for example, punctuation)

• 8-bit characters (characters whose decimal code starts at 128 or below)

Notifying Users of Password Expiration

61

• Number of repeated characters

This weights in the opposite direction, so that if you have too many repeated characters you willnot meet the quorum to satisfy the "level" expressed by krbPwdMinDiffChars.

• Minimum Length of Password (krbPwdMinLength): The minimum number of characters that mustexist in a password before it is considered valid. The default value is eight characters.

• Password History Size (krbPwdHistoryLength): The number of previous passwords that FreeIPAstores, and which a user is prevented from using. For example, if you set this value to 10, FreeIPAprevents a user from reusing any of their previous 10 passwords. The default value is 0 (zero)(disable password history).

Note

If password history checking is enabled, and a user attempts to use one of the passwords inthe history list, the error message returned by the system may be misleading. For example, youmay see the following error:

A database error occurred: Constraint violation: Password fails to meet minimum strength criteria

This is because python-ldap prevents the retrieval of extended information on password policyfailures over LDAP.

Note

Even with krbPwdHistoryLength set to zero, users cannot reuse their existing password.

• Priority (priority): The priority determines which policy is in effect. The lower the number the higherpriority. This is important if a user is in several groups, each with a password policy set.

• Maximum Consecutive Failures (maxfail): Specifies the maximum number of consecutive failuresto input the correct password before the user's account is locked.

• Fail Interval (failinterval): Specifies the period (in seconds) after which the failure count will bereset.

• Lockout Time (lockouttime): Specifies the period (in seconds) for which a lockout is enforced.

Refer to the ipa help pwpolicy-add help page for more information on configuring the FreeIPApassword policy.

4.9.7. Notifying Users of Password ExpirationIf it is installed and configured, SSSD can use the PAM module to send messages to users, warningthem about imminent password expiration. Fedora has a pam_pwd_expiration_warning optionto fine tune this feature. You can also manually search for passwords that are due to expire by aspecified date. For example, to retrieve all user entries whose passwords are due to expire beforeMarch 1st, 2011, run the following command:


62

$ ldapsearch -Y GSSAPI -b "cn=users,cn=accounts,dc=example,dc=com" '(krbPasswordExpiration<=20110301000000Z)'

4.9.8. Using SSH for Password AuthenticationIf you use password authentication (no GSSAPI authentication, and no ticket on the client) with anew user, or with a user whose password has expired, you need to enable Challenge-Responseauthentication. Otherwise, the password changing dialog box will not display.

This is not enabled by default because some older SSL clients may not support Challenge-Responseauthentication, and it is needed only if the password has expired.

To enable Challenge-Response authentication:• Set ChallengeResponseAuthentication to yes in the /etc/ssh/sshd_config file.

4.9.9. Using Local LoginsUser identity and authentication is managed by SSSD in recent versions of Fedora. The defaultsettings specified by the FreeIPA installation script include timeout settings that still allow locallogins to succeed if the client cannot access the FreeIPA server. These settings are specified inthe /etc/sssd/sssd.conf file, and can be tuned to suit your particular deployment. Further, ifSSSD's password caching feature is enabled, a user can log in even if the FreeIPA server is down. Atypical deployment would normally include two or more servers for redundancy, and so this would notnormally be a problem.

Warning

These timeout settings are only set on operating systems that support the FreeIPA installationscript, meaning Fedora 15 and later. On other versions, specify these values manually or it maybe impossible to log into the host if no FreeIPA servers are available.

4.10. Searching for Users and GroupsFreeIPA provides extensive search capabilities, which enable you to perform simple and partial-matchsearches on a range of attributes, including:

• First Name (givenname)

• Last Name (sn)

• Login (uid)

• Job Title (title)

• Organizational Unit Name (ou)

• Phone Number (telephoneNumber)

Searches are not case sensitive, and automatically search across multiple fields. Search results aredisplayed with exact matches listed first, followed by partial matches.

The default display lists users in alphabetical order. Click any column title to sort in alphabetical ornumerical order. Click the title again to sort in reverse order. The sort order is indicated by an icon nextto the title.

Searching for Users

63

Not all fields are indexed for searching. For example, you cannot search on the following user details:

• Initials

• Account Status

• Home Directory

• Login Shell

• Gecos

• Home Page

Note

You cannot use wildcards to search for users or groups. The search string must include at leastone character that appears in one of the indexed search fields.

4.10.1. Searching for Users

4.10.1.1. Using the Command LineUse the ipa user-find command to search for users from the command line. The basic syntax ofthis command is as follows:ipa user-find [ options ] { string }

Note

Unlike the web version of the Find User utility, you can only search for a single string using thecommand line version.

Refer to the ipa user-find man page for more information on the options available.

The following example demonstrates using the ipa user-find command to find users whose recordcontains the string "kay":

$ ipa user-find kay---------------2 users matched---------------User login: klimFirst name: KayLast name: LimHome directory: /home/klimLogin shell: /bin/shAccount disabled: FalseMember of groups: ipausers

User login: kmingFirst name: KayLast name: MingHome directory: /home/kmingLogin shell: /bin/shAccount disabled: False


64

Member of groups: ipausers----------------------------Number of entries returned 2----------------------------

If you do not see the entry that you are looking for, you may need to adjust the --searchrecordslimit option in the default FreeIPA configuration.

4.10.2. Searching for Groups

4.10.2.1. Using the Command LineUse the ipa group-find command to search for groups from the command line. The basic syntaxof this command is as follows:ipa group-find { string }

Note

Unlike the web version of the Find Group utility, you can only search for a single string using thecommand-line version.

Refer to the ipa group-find man page for more information on the options available.

The following example demonstrates using the ipa group-find command to find groups thatcontain the string "documentation":

$ ipa group-find documentation---------------1 group matched---------------Group name: documentationDescription: Group for all documentation authorsGID: 1453400012Member users: dkim, mkang, lming, klim----------------------------Number of entries returned 1----------------------------

Note

The ipa group-find command searches both group names and group descriptions. If yoursearch results are too extensive, use a more specific search string.

Chapter 5.

65

Identity: Managing Hosts and HostGroups

5.1. A Summary of Host and Host Group Tools

Table 5.1. Host Commands

Command Description

ipa host-add Adds a new host entry.

ipa host-mod Modifies an existing hostentry, either by changingattribute values or adding newattributes.

ipa host-del Deletes the host from the DNSfor the FreeIPA domain.

ipa host-disable Disables the host entry, whichfunctionally removes the hostfrom the service but does notdelete the entry.

5.2. Adding Host EntriesThe first part of enrollment is creating a host entry in the FreeIPA Directory Server and, if configured,its DNS. There are several FreeIPA command line tools that manage host entries, as well asmanaging host entries in the

Example 5.1. Creating Host Entries with DNSIf you are using a FreeIPA-based DNS system, you can use the --ip-address and --forceoptions to the ipa host-add command to provide the IP address and hostname of the FreeIPAmachine to the DNS. For example,

$ ipa host-add --force --ip-address=192.168.166.31 puma.example.com

IPA provides the ipa host-del command to delete FreeIPA hosts. You can pass the --updatedns option to this command to remove the associated records from the DNS. It will attemptto remove any record, A, AAAA, PTR, NS, SRV, and other entries that reference this host. Forexample,

$ ipa host-del --updatedns puma

5.3. Extending the Permissions of FreeIPA Managed HostsThe definition of "manage" is "being able to retrieve a keytab and certificates on behalf of another hostor service". Every host and service has a managedby entry. By default, a host can manage itself andall of its services. It is also possible to allow a host to manage other hosts, or services on other hosts,by updating the appropriate delegations or providing a suitable managedby entry.

Chapter 5. Identity: Managing Hosts and Host Groups

66

Note

If a host is provided with a managedby entry to another host, it does not mean management of allservices on that host. Each delegation has to be performed independently.

5.3.1. Delegating Service ManagementThis section describes how to create a new host and a service on that host, and then delegatemanagement of that service to another host. In this example, the FreeIPA server is installed onslinky.example.com

Procedure 5.1. To delegate service management to another host1. Create a new host:

# kinit admin# ipa host-add panther.example.com

2. Create a service on this host:

# ipa service-add test/panther.example.com

3. Delegate managing the service:

# ipa service-add-host --hosts=slinky panther

You can now use the host service principal on slinky to manage panther:

# kinit -kt /etc/krb5.keytab host/`hostname`# ipa-getkeytab -s `hostname` -k /tmp/test.keytab -p test/panther.example.comKeytab successfully retrieved and stored in: /tmp/test.keytab

4. To create a ticket for this service, create a CSR and then run the following command:

# ipa cert-request --add --principal=test/panther.example.com panther.csr Certificate: MIICETCCAXqgA...[snip] Subject: CN=panther.example.com,O=EXAMPLE.COM Issuer: CN=EXAMPLE.COM Certificate Authority Not Before: Tue Feb 08 18:51:51 2011 UTC Not After: Mon Feb 08 18:51:51 2016 UTC Fingerprint (MD5): c1:46:8b:29:51:a6:4c:11:cd:81:cb:9d:7c:5e:84:d5 Fingerprint (SHA1): 01:43:bc:fa:b9:d8:30:35:ee:b6:54:dd:a4:e7:d2:11:b1:9d:bc:38 Serial number: 1005

5.3.2. Delegating Host ManagementThis section describes how to delegate management of one host to another host. This example usesthe same hosts as those used in the previous example.

Procedure 5.2. To delegate host management to another host1. Ensure you have admin credentials and then add the appropriate managedby entry:

# kinit admin

Delegating Host Management

67

# ipa host-add-managedby --hosts=slinky panther

2. Obtain a TGT as the host slinky and then retrieve a keytab for panther:

# kinit -kt /etc/krb5.keytab host/`hostname`# ipa-getkeytab -s `hostname` -k /tmp/panther.keytab -p host/panther.example.comKeytab successfully retrieved and stored in: /tmp/panther.keytab

68

Chapter 6.

69

Identity: Using FreeIPA for a KerberosDomain

6.1. About KerberosThe Kerberos server is a part of FreeIPA. When you run the kinit command you invoke a client thatconnects to the Kerberos server. As a result of the authentication the client receives a ticket. Thisticket is a temporary pass; or a better description might be a pass-book. The best example from reallife might be a pass to a movie festival. A single pass to such a festival would allow someone to attenddifferent movies at their discretion. Kerberos is very similar. When a user tries to access any resourcethat is protected by Kerberos, that resource requires the user to present a valid ticket, the same as inthe movies.

To obtain such a ticket the user needs to prove their identity; that they are who they claim to be.Asking the user to constantly authenticate with their password would soon prove to be too annoyingand hard to manage. This is why a multi-tier process exists, where the user first authenticates andobtains a so-called ticket-granting ticket (TGT). This ticket can then be presented to the Kerberosserver at any time and a new ticket specific to the resource that the user wants to access can beacquired. All of these tickets have a configurable expiration time, so the user occasionally needs to re-authenticate, but it is much less of a burden.

Kerberos is a network authentication protocol which allows users to authenticate to services with thehelp of a KDC. Kerberos authentication requires that both the user and the service be known to theKDC and that each has previously shared a set of encryption keys with the KDC. A user's keys arederived from the user's password, and while a service's keys can also be derived from a password,it is more likely that they are randomly generated. Users and services are known to the KDC by whatare referred to as their principal names, and those users and services are often referred to simply asprincipals.

A service principal consists of three components:• the service name

• the fully-qualified domain name (FQDN)

• the Kerberos realm

The service name is an arbitrary case-sensitive string, such as host, HTTP, ldap, or DNS. Byconvention, daemons use a specific service; sometimes this service name is obvious, but not always.The sshd daemon, for example, uses the host service principal.

The syntax, or structure, of a service principal is as follows: service/FQDN@REALM. For example,the host service principal for a machine named test.example.com in the Kerberos realmEXAMPLE.COM would be host/[email protected]. By convention, this principal isstored in /etc/krb5.keytab.

Chapter 6. Identity: Using FreeIPA for a Kerberos Domain

70

Important

When you run the ipa-client-install command, it retrieves the host service principal andstores it in the /etc/krb5.keytab file. This host principal is stored within the host record sothat the service commands cannot be used with this principal. The idea behind this is that afteryou have run the ipa-client-install command, your client should be fully prepared toparticipate in the FreeIPA network.

Clients use service principals to inform the KDC which service they need a ticket for. The KDC usesthe key assigned to the service principal to encrypt the service ticket it grants to client. Serviceprincipals and their associated keys are stored in a keytab file. If the KDC has the service principal andthe key assigned to that principal, it can still provide the client with a ticket, but the service server willnot be able to decrypt the ticket without the key stored in that keytab file.

Service principals are typically released per service, although it is possible for one service principal tobe used for more than one service.

The Importance of Service Principals and keytabsService principals and their associated keys play a critical role in a Kerberos-aware environment.This is especially true when services are accessed by multiple users. As long as a valid ticket existsfor a specific service, users can access that service using their Kerberos credentials.

For example, if a user tries to mount an NFS directory using Kerberos, then both the NFS serverand the user require their own valid principal, and share their own secret key with the KDC. The NFSserver key is established during the FreeIPA NFS configuration on the server. If the secret key isreplaced on the server, for example, by getting a new keytab, then you need to export this new keytabto the KDC, which will then distribute it to the clients.

Protecting keytab FilesTo protect your keytab files, consider the following general rules with respect to their permissions andownership:• Owner: uid of the process that will use the keytab

• Mode: 0600

For example, set the owner of the Apache keytab (/etc/httpd/conf/ipa.keytab) to httpd andthe mode to 0600.

Warning

Clients attempting to mount NFS exports rely on the existence of a valid principal and secret keyon both the NFS server and the client host. Clients themselves should not have access to the NFSkeytab. The ticket for the NFS connection will be given to clients from the KDC.

Failure to export an updated keytab can cause problems that are difficult to isolate. For example,existing service connections may continue to function, but no new connections may be possible.

Due to the critical role that keytabs play in authenticating users and services, and the issues thatcan arise if they are compromised, ensure that all keytab files are appropriately secured, andhave suitable file ownership and permissions established.

Setting Kerberos Ticket Policies

71

6.2. Setting Kerberos Ticket PoliciesKerberos tickets are issued subject to the restraints of the Kerberos ticket policy. This policy definesthe maximum ticket lifetime and also the maximum renewal age, the period during which the ticketis renewable. You can use the ipa krbtpolicy-mod command to modify the policy to suit yourenvironment. You can also use the ipa krbtpolicy-reset command to reset the policy to thedefault values.

Important

Any change to the global Kerberos ticket policy requires a restart of the KDC for the changes totake effect. Use the following command to restart the KDC:

# service krb5kdc restart

Kerberos authentication is the core of the FreeIPA server. For a full discussion of how Kerberos works,configuration, and other aspects of Kerberos, see the MIT Kerberos project documentation at http://web.mit.edu/kerberos/www/.

FreeIPA uses a single Kerberos ticket policy. This policy defines the maximum ticket lifetime and themaximum renewal age; that is, the period during which the ticket is renewable. You can also create aper-user ticket policy by specifying the user login.

Note

Changes to the global policy require a restart of the KDC service to take effect, as follows:

# service krb5kdc restart

Changes to per-user policies take effect immediately for newly-requested tickets, for example,when the user next runs kinit.

6.3. Creating and Using Service PrincipalsYou can use the web interface to create service principals and also to search for existing serviceprincipals. For security and other reasons, however, it is not possible to retrieve a keytab using theweb interface. This has to be done either on the command line on the system where the service isaccessed, or on the FreeIPA server itself, and the keytab then exported to the client host.

The following example demonstrates creating a service principal and keytab on a client host for theHTTP service. In this example, the client host is ipaclient.example.com and the FreeIPA server isipaserver.example.com:

# kinit admin# ipa host-add ipaclient.example.com# ipa service-add HTTP/[email protected]# ipa-getkeytab -s ipaserver.example.com -p HTTP/ipaclient.example.com /-k /etc/httpd/conf/ipa.keytab

Note the location of the keytab. By default, FreeIPA saves its HTTP keytab to /etc/httpd/conf/ipa.keytab. This keytab is used in the webUI, and so you should be aware that if a key were storedin ipa.keytab and you later deleted that keytab file, the FreeIPA interface would stop working,because the original key would also be deleted.

http://web.mit.edu/kerberos/www/

http://web.mit.edu/kerberos/www/


72

Similar locations can be specified for each service that needs to be made Kerberos aware. There isno specific location that must be used, but, when using ipa-getkeytab, you should avoid using /etc/krb5.keytab. This file should not contain service-specific keytabs; each service should have itskeytab saved in a specific location and the access privileges (and possibly SELinux rules) should beconfigured so that only this service has access to the keytab.

Note

• The realm name is optional. The FreeIPA server automatically appends the Kerberos realmfor which it is configured. You cannot specify a different realm.

• The hostname must resolve to a DNS A record for it to work with Kerberos. You can use the--force flag to force the creation of a principal should this prove necessary.

• The ipa-getkeytab command is part of the freeipa-client package, which is only availablefor Fedora 15 or later. For other clients, you need to use this procedure on the server andmanually copy the keytab to the client.

• You can use the -e flag to include a comma-separated list of encryption types to include in thekeytab. This supersedes any default encryption type. Refer to the ipa-getkeytab man pagefor more information.

Warning

The ipa-getkeytab command resets the secret for the specified principal. This means that allother keytabs for that principal are rendered invalid.

FreeIPA provides a range of tools and commands to facilitate the creation and administration ofservices and the service principals and certificates required to use them. Some of this can beautomated, but there will always be a certain amount of manual intervention required to createservices and certificates after the initial joining of a host to a realm. These requirements andprocedures are discussed in the following sections.

6.3.1. Creating a FreeIPA Service

PrerequisitesBefore you can create a service for a FreeIPA host, you need to ensure that the host exists. Thisshould be true if it has already joined the realm. Use the following command to determine if the hostexists:

# ipa host-show myserver.mydomain.net

If the host does not exist in the realm, you will see an error message similar to the following:

ipa: ERROR: myserver.mydomain.net: host not found

To create a FreeIPA service:Use the following command to create a service for that host:

Creating a FreeIPA Service

73

# ipa service-add test/myserver.mydomain.net

This will produce output similar to the following:

-------------------------------------------------------Added service "test/[email protected]"------------------------------------------------------- Principal: test/[email protected] Managed by: myserver.mydomain.net

6.3.1.1. Requesting a Certificate for a ServiceUse the following command to request a certificate for the new service. The certificate request iscontained in the example.csr file.

# ipa cert-request --principal=test/myserver.mydomain.net example.csr

Note

You can use the --add option to create the service when requesting the certificate.

If necessary, create the CSR file using openssl. The following is an example session creating such afile:

# openssl req -out example.csr -new -newkey rsa:2048 -nodes -keyout private.keyGenerating a 2048 bit RSA private key.........................................................+++.............................+++writing new private key to 'private.key'-----You are about to be asked to enter information that will be incorporatedinto your certificate request.What you are about to enter is what is called a Distinguished Name or a DN.There are quite a few fields but you can leave some blankFor some fields there will be a default value,If you enter '.', the field will be left blank.-----Country Name (2 letter code) [XX]:AUState or Province Name (full name) []:QLDLocality Name (eg, city) [Default City]:BNEOrganization Name (eg, company) [Default Company Ltd]:MYDOMAIN.NETOrganizational Unit Name (eg, section) []:ECSCommon Name (eg, your name or your server's hostname) []:myserver.mydomain.netEmail Address []:[email protected]

Please enter the following 'extra' attributesto be sent with your certificate requestA challenge password []:An optional company name []:

6.3.1.2. Using certmonger to Manage Certificate RequestsYou can also use certmonger to manage the certificate request process for you. Use the followingcommand to request a certificate:


74

# ipa-getcert request -d /etc/pki/nssdb -n Server-Cert

The /etc/pki/nssdb file is the global NSS database, and Server-Cert is the nickname ofthis certificate. There is nothing special about this name; it can be anything, but it does need to beunique within this database. Use the ipa-getcert list command to display the current status ofcertificates managed by certmonger.

If you use certmonger to request a certificate for a service, you need to use the -K <principal>option. Without this option, certmonger assumes it is requesting a certificate for the host service(host/fqdn@REALM). For example:

# ipa-getcert request -d /etc/httpd/alias -n Server-Cert -KHTTP/[email protected] -N 'CN=myserver.mydomain.net,O=MYDOMAIN.NET'

You need to use the -N option to specify the subject when using the -K option. The subject format isas follows: CN=<fqdn>,O=<subject base>

You can configure the FreeIPA subject base as part of the FreeIPA server installation process; thedefault value is the same as the default value for the realm name, which is derived from the hostnameby default. Use the following command to determine the subject base:

$ ipa config-show | grep -i subject

FreeIPA will reject requests with invalid subject base values.

6.3.1.3. Using NSSIf you need to create an NSS database in which to store your key, use the certutil command asfollows:

$ certutil -N -d /path/to/database/dir$ certutil -R -s "CN=myserver.mydomain.net, O=MYDOMAIN.NET" \-d /path/to/database/dir -a > example.csr

CSR File FormatsThe format of the CSR is partly dependent upon the CA back end you are using.

If you are using Dogtag, then the Common Name (CN) is the only part of the request subject that isused; all other components are ignored.

If you are using the selfsigned CA back end, then the subject must match the configured certificatesubject base. You can find this with:

$ ipa config-show | grep -i subject

Certificate Subject base: O=MYDOMAIN.NET

This means you need to use MYDOMAIN.NET for the organization. FreeIPA will reject requests whosesubject base differs from this value.

6.3.2. Configuring an NFS Service Principal on the FreeIPA ServerThe following procedure describes how to configure NFS on the FreeIPA server and to set up an NFSservice principal.

Configuring an NFS Service Principal on the FreeIPA Server

75

Procedure 6.1. Configuring NFS on the FreeIPA Server1. Configure the export directory.

# mkdir /export# chmod 777 /export

2. Configure the /etc/exports file as follows:

/export *(rw,fsid=0,insecure,no_subtree_check)/export gss/krb5(rw,fsid=0,insecure,no_subtree_check)/export gss/krb5i(rw,fsid=0,insecure,no_subtree_check)/export gss/krb5p(rw,fsid=0,insecure,no_subtree_check)

3. To enable secure NFS, add the following line to /etc/sysconfig/nfs

SECURE_NFS=yes

4. Add a service principal and keytab for NFS.

# ipa service-add nfs/ipaserver.example.com# ipa-getkeytab -s ipaserver.example.com -p nfs/ipaserver.example.com \ -k /etc/nfs/conf/nfs.keytab

NFS Encryption Support

Some versions of the Linux NFS implementation have limited encryption type support. If yourNFS server is hosted on an older Fedora machine, you may need to use the -e des-cbc-crc option to the ipa-getkeytab command for any nfs/<FQDN> service keytabs you wantto set up, both on the server and on all clients. This instructs the KDC to generate only DESkeys.

If you use this option to generate DES keys, then all clients and servers that rely on thisencryption type need to have the allow_weak_crypto option enabled in the [libdefaults]section of the /etc/krb5.conf file. Without these configuration changes, NFS clients andservers will be unable to authenticate to each other, and attempts to mount NFS filesystemsmay fail. The client's rpc.gssd and the server's rpc.svcgssd daemons may log errorsindicating that DES encryption types are not permitted.

5. Run the following commands to reload the NFS configuration and restart the required services:

# exportfs -a# restart services# service nfs restart# service rpcgssd restart -k /etc/nfs/conf/nfs.keytab


76

Note

Note the use of the -k option when restarting rpcgssd. This is necessary to update theNFS configuration with the path to the NFS keytab.

6.4. Refreshing Kerberos TicketsSome compliance or company security policies may require that system administrators manuallyrefresh Kerberos tickets, perhaps annually or more frequently. The current version of FreeIPA does notprovide automatic renewal of Kerberos tickets.

Manually refreshing Kerberos tickets is a two step process: you first need to find all of the keytabs thatare older than a certain date, and then obtain a new keytab for the host or service in question. Thisprocess is described in detail below.

Procedure 6.2. How to manually refresh Kerberos keytabs1. Find all keytabs, both for host services and for any other services, issued before today. Use the

following queries (update the dates as necessary):

# ldapsearch -x -b "cn=computers,cn=accounts,dc=example,dc=com" "(&(krblastpwdchange<=20110110000000)(krblastpwdchange>=19710101000000))" dn krbprincipalname

# ldapsearch -x -b "cn=services,cn=accounts,dc=example,dc=com" "(&(krblastpwdchange<=20110110000000)(krblastpwdchange>=19710101000000))" dn krbprincipalname

Note

Dates are expressed in YYYYMMDD format, and times in HHMMSS format (GMT).

2. Log into each machine and obtain a new keytab for the given service. To do this, you need toknow the location of the keytab on the target system. For example, the default location for thehost/ principal is /etc/krb5.keytab. Use the ipa-getkeytab command to retrieve a newhost/principal:

# ipa-getkeytab -p host/[email protected] \ -s ipa.example.com -k /etc/krb5.keytab

To retrieve a new keytab for the HTTP service, run the following command instead:

# ipa-getkeytab -p HTTP/[email protected] \-s ipa.example.com -k /etc/httpd/conf/ipa.keytab

Rotating Keys

77

Note

The ipa-getkeytab command does not delete the old keytab in case it already exists inthe file.

You can use the klist command to view the new key version number (KVNO):

# klist -kt /path/to/keytab

Important

Some services, such as NFSv4, only support a limited set of encryption types. Ensure that youpass the appropriate arguments to the ipa-getkeytab command.

6.5. Rotating KeysKerberos keys are similar to passwords, and in the interests of security they should occasionally bechanged. The frequency of these changes may be determined by company or other policies. Each keyhas an associated version number, which are stored in the KVNO parameter.

Obtaining a new service principal Kerberos keyUse the ipa-getkeytab command to create a new Kerberos key. For example, use the followingcommand to refresh your FreeIPA keytab:

# ipa-getkeytab -s ipa.example.com -k /etc/dirsrv/ds.keytab -p ldap/[email protected]

This will add a new set of keys to your existing keytab. That is, you should now have two identical setsof principals, each with a separate KVNO.

Use the klist command to view the existing keys:

# klist -kt /etc/dirsrv/ds.keytabTicket cache: FILE:/tmp/krb5cc_0Default principal: [email protected]

Valid starting Expires Service principal03/08/11 13:57:18 03/09/11 13:57:16 krbtgt/[email protected]/08/11 13:57:27 03/09/11 13:57:16 HTTP/[email protected]/08/11 13:57:32 03/09/11 13:57:16 ldap/[email protected]

Use the kvno command to display the version number of a service ticket that you have been issued:

# kvno -c /tmp/krb5cc_0 ldap/[email protected]

The -c option specifies which credentials cache to use. The credentials cache (Ticket cache) isincluded in the output of the klist command, above.

Tickets issued against the old service will continue to work as expected but new tickets will be issuedusing the highest KVNO. This is to avoid any disruption to system operations. No service restart shouldbe needed.


78

You should maintain the old records for at least the amount of time that valid tickets are issues (8hours by default) so that any clients that have a ticket encrypted with the old key will continue to work.However, there is no real need to remove old keys.

FreeIPA does not currently provide an automated method of performing this task for all service tickets.Use the following queries to display a list of all services that have been issued keytabs:

# ldapsearch -LLL -x -b 'cn=services,cn=accounts,dc=example,dc=com' \ '(krblastpwdchange=*)' krbprincipalname# ldapsearch -LLL -x -b 'cn=computers,cn=accounts,dc=example,dc=com' \ '(krblastpwdchange=*)' krbprincipalname

This will display service and host keytab information. It is not possible to determine if it has a keydirectly, but you can infer that a keytab was issued by looking at the last change date.

6.6. Kerberos ErrorsIf kinit fails or you see an unusual Kerberos error back in the framework, inspect the following filesfor possible causes:• On the server: /var/log/krb5kdc.log

• If you were using the framework also look in /var/log/httpd/error_log

Chapter 7.

79

Identity: Using Automount

7.1. About Automount and IPAThis chapter describes how to configure automount on Linux and Solaris for use with IPA. Itdetails the procedures and configuration changes necessary to set up automount, the auto.masterfile and other map files used by autofs.

7.1.1. Known Issues with Automount

Additional Schema Required for Some SystemsIf you are supporting Solaris clients, you need to use the 2307bis-style automount schema,although Sun's version is NOT identical to the one at http://people.redhat.com/nalin/schema/autofs.schema.

7.1.2. AssumptionsIn order to illustrate the automount configuration procedures, this chapter assumes that:• The IPA server is correctly installed and operational.

• The domain is example.com.

• The NFS server is also configured as an IPA client.

• You have root access to the server where you want autofs to work. For the purposes of thisexercise, this server is called nfsserver.example.com

• The nfsserver.example.com server can communicate with the LDAP server for users andgroups.

• The NFS service is running on nfsserver.example.com

This chapter also assumes that the user has at least a basic understanding of NFS and automount.

NFS ConfigurationConfiguring NFS is beyond the scope of this document. Refer to the http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/96/html/Storage_Administration_Guide/ch-nfs.html for information onhow to configure NFS.

The following is an example of a suitable entry in the /etc/exports file:

/home 192.168.1.0/16 (rw,fsid=0,insecure,no_subtree_check,sync,anonuid=65534,anongid=65534)

You should test that you can mount the /home directory from the command line before proceedingwith the automount configuration. This makes troubleshooting easier if the configuration does notwork.

7.2. Configuring AutomountIPA natively supports automount and so only minimal configuration is required. IPA 2.0 also introducesthe concept of a location, which allows for different sets of maps for different purposes, or locations.

http://people.redhat.com/nalin/schema/autofs.schema

http://people.redhat.com/nalin/schema/autofs.schema

http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/96/html/Storage_Administration_Guide/ch-nfs.html

http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/96/html/Storage_Administration_Guide/ch-nfs.html

Chapter 7. Identity: Using Automount

80

Note

You can direct different clients to use different map sets. These map sets use a tree structure,which means that you cannot share maps between locations.

Any extra steps required for configuring automount on Linux or Solaris are described below. Refer tothe ipa help automount help page for more information and a list of available commands.

7.2.1. Configuring autofs on LinuxProcedure 7.1. To configure autofs on Linux:1. Edit the /etc/sysconfig/autofs file as follows. This specifies the attributes that autofs

searches for:

## Other common LDAP naming#MAP_OBJECT_CLASS="automountMap"ENTRY_OBJECT_CLASS="automount"MAP_ATTRIBUTE="automountMapName"ENTRY_ATTRIBUTE="automountKey"VALUE_ATTRIBUTE="automountInformation"

2. You also need to specify which LDAP server to use, and the basedn for LDAP searches:

LDAP_URI="ldap://ipa.example.com"SEARCH_BASE="cn=<location>,cn=automount,dc=example,dc=com"

Note

The default value for location is default.

3. Save the file and restart autofs:

# service autofs restart

7.2.1.1. Testing the ConfigurationTest the configuration by attempting to list a user's /home directory:

# ls /home/<username>

If this does not mount the remote file system, check the /var/log/messages file for errors orother indications of what the problem might be. You can also increase the debug level in the /etc/sysconfig/autofs file by setting the LOGGING parameter to debug.

7.2.2. Solaris automountThe following procedure describes the steps required to configure automount for Solaris.

Configuring Indirect Maps

81

1. If the NFS server is running on Linux, you need to specify on the Solaris machine that NFSv3is the maximum supported version. Edit the /etc/default/nfs file and set the followingparameter:

NFS_CLIENT_VERSMAX=3

2. IPA does not configure automount by default, so you need to use the ldapclient command tomanually configure your host to use LDAP:

ldapclient -v manual -a authenticationMethod=none \-a defaultSearchBase=dc=example,dc=com \-a defaultServerList=ipa.example.com \-a serviceSearchDescriptor=passwd:cn=users,cn=accounts,dc=example,dc=com \-a serviceSearchDescriptor=group:cn=groups,cn=compat,dc=example,dc=com \-a serviceSearchDescriptor=auto_master:automountMapName=auto.master, \ cn=<location>,cn=automount,dc=example,dc=com?one \-a serviceSearchDescriptor=auto_home:automountMapName=auto_home, \ cn=<location>,cn=automount,dc=example,dc=com?one \-a objectClassMap=shadow:shadowAccount=posixAccount \-a searchTimelimit=15 \-a bindTimeLimit=5

3. Enable automount as follows:

# svcadm enable svc:/system/filesystem/autofs

7.2.2.1. Testing the Configuration

Procedure 7.2. To test the automount configuration, run the following commands:1.

# ldapclient -l auto_masterdn: automountkey=/home,automountmapname=auto.master,cn=<location>,cn=automount,dc=example,dc=comobjectClass: automountobjectClass: topautomountKey: /homeautomountInformation: auto.home

2. Attempt to list a user's /home directory:

# ls /home/<username>

7.2.3. Configuring Indirect MapsAn indirect map defines a container for mount points. For example, if you create an indirect map /share, then all automount keys are relative to that map. If you define an automount key ipauser,the map would appear as /share/ipauser. In other words, indirect maps specify relative paths.Compare this to the absolute paths specified by direct maps.

The following example creates an indirect map for /usr/man using the built-in IPA commands. Thiscreates a single indirect map, /usr/man/man1, which:

• Creates a new automount map called auto.man

• Adds auto.man to auto.master on the mount point /usr/man

Chapter 7. Identity: Using Automount

82

• Adds an indirect mount of man1 to auto.man

Procedure 7.3. How to create an indirect map:1. Create a new location:

$ ipa automountlocation-add baltimore Location: baltimore

2. Create a map for man pages:

$ ipa automountmap-add baltimore auto.man Map: auto.man

3. Add this map to the location's auto.master on the mount point /usr/man:

$ ipa automountkey-add baltimore auto.master --key=/usr/man --info=auto.man Key: /usr/man Mount information: auto.man

Use the following command to export information on the automount configuration for a specificlocation. This is useful if you perform file-based automount. For example:

$ ipa automountlocation-tofiles baltimore/etc/auto.master:/- /etc/auto.direct/usr/man /etc/auto.man---------------------------/etc/auto.direct:---------------------------/etc/auto.man:

Configuring an Indirect Map on SolarisOn Solaris, use the following arguments with the ldapclient command:

-a serviceSearchDescriptor=auto_man:automountMapName=auto.man, \ cn=<location>,cn=automount,dc=example,dc=com?one \

7.2.3.1. Configuring Direct MapsDirect maps list exact locations to mount specified maps, for example /usr/local/bin or /mnt.That is, they specify absolute paths as mount points. Compare this to the relative paths specified byindirect maps.

To add a direct map configuration, IPA requires a number of modifications to the auto.direct file.The following two entries are created during the installation process:

dn: automountkey=/-,automountmapname=auto.master,cn=default,cn=automount,dc=example,dc=com objectClass: automount automountKey: '/-' automountInformation: auto.direct

automountmapname=auto.direct,cn=default,cn=automount,dc=example,dc=com objectClass: automountMap

Links

83

automountMapName: auto.direct

Use the following procedure to add a mount to this direct map for the /share directory:

Procedure 7.4. How to create a direct map:1. Create a new location:

$ ipa automountlocation-add brisbane Location: brisbane

2. Add the map to the location's auto.direct file on the mount point /share:

$ ipa automountkey-add brisbane auto.direct --key=/share \ --info="-ro,soft, ipaserver.ipadocs.org:/home/share" Key: /share Mount information: -ro,soft, ipaserver.ipadocs.org:/home/share

On Solaris, use the following arguments with the ldapclient command:

-a serviceSearchDescriptor=auto_direct:automountMapName=auto.direct, \ cn=<location>,cn=automount,dc=example,dc=com?one \

7.2.4. LinksThe following pages were used as references for this work:

• http://efod.se/blog/archive/2006/06/27/autofs-and-ldap

• http://www.linuxjournal.com/article/6266

• http://forums.fedoraforum.org/showthread.php?t=138992

• http://forums.fedoraforum.org/forum/showthread.php?t=135635&highlight=autofs+ldap

• http://blogs.sun.com/rohanpinto/entry/nis_to_ldap_migration_guide

http://efod.se/blog/archive/2006/06/27/autofs-and-ldap

http://www.linuxjournal.com/article/6266

http://forums.fedoraforum.org/showthread.php?t=138992

http://forums.fedoraforum.org/forum/showthread.php?t=135635&highlight=autofs+ldap

http://blogs.sun.com/rohanpinto/entry/nis_to_ldap_migration_guide

84

Chapter 8.

85

Identity: Integrating with MicrosoftActive DirectoryTo synchronize user identity information between 389 Directory Server and Windows Active Directory,IPA employs a plug-in that extends the functionality of the 389 Directory Server Windows Syncutility. This plug-in allows IPA to perform the data manipulation necessary to achieve synchronizationbetween 389 Directory Server and Windows Active Directory. The IPA Windows Sync plug-in uses theipaWinSyncUserAttr parameter to specify which attributes and values to add to new users that aresynchronized from Active Directory.

8.1. About Active Directory, IPA, and Identity Management

8.1.1. Domain Name ConsiderationsIPA clients find, or discover, IPA servers using a process known as Service Discovery. This can occurautomatically, using DNS, or manually, by entering the IPA server details during the client configurationphase. If your Active Directory installation is in the same domain as the IPA server, it is possible thatwhen you install IPA clients they will not discover the IPA server, but rather the Active Directory DNS.This means that IPA commands run on the client will fail because the client cannot contact the IPAserver.

To avoid this situation, use a separate domain for your IPA and Active Directory servers. If this is notpossible, use the --force parameter when you run the ipa-client-install script.

8.2. Setting up Active DirectoryThe Windows Sync utility requires TLS/SSL to synchronize password changes. Therefore, you needto set up Active Directory as an SSL server. The easiest way to achieve this is to install MicrosoftCertificate System in Enterprise Root Mode; Active Directory will then automatically enroll to retrieveits SSL server certificate.

Note

You need to install both the winsync and passsync utilities to synchronize User IDs andattributes as well as passwords.

You need to install the passsync utility on all AD domain controllers to enable passwordsynchronization from AD to IPA.

Refer to the Fedora Project Windows Sync Howto1 for information on setting up Active Directory as anSSL server.

After you have installed Microsoft Certificate System, you need to save the CA certificate in ASCII(PEM) format. This CA Certificate is required to create the synchronization agreement.

Procedure 8.1. To save the CA certificate in ASCII format:1. Navigate to My Network Places and drill down to the CA distribution point. On Windows 2003

Server this is typically C:\WINDOWS\system32\certsrv\CertEnroll\

1 http://directory.fedoraproject.org/wiki/Howto:WindowsSync

http://directory.fedoraproject.org/wiki/Howto:WindowsSync

http://directory.fedoraproject.org/wiki/Howto:WindowsSync

Chapter 8. Identity: Integrating with Microsoft Active Directory

86

2. Double-click the security certificate file (.crt file) to display the Certificate dialog box.

3. On the Details tab, click Copy to File to start the Certificate Export Wizard.

4. Click Next, select Base-64 encoded X.509 (.CER) and then click Next.

5. Specify a suitable directory and file name for the exported file. The file name is not important.Click Next to export the certificate, and then click Finish. You should receive a message statingthat the export was successful.

6. Click OK to exit the wizard.

Refer to Section 8.4, “Creating Synchronization Agreements” for information on how to use the CACertificate to create the synchronization agreement.

Figure 8.1. Select Base-64 encoded X.509 to export the security certificate as ASCII

8.3. Configuring Active Directory SynchronizationThe Windows Sync plug-in is installed on the IPA server, and enables one-way replication of usersand groups from Windows to IPA. The ipa-server-install script automatically installs the plug-inconfiguration entry and enables it by default. The Windows Sync plug-in is only ever called if WindowsSync is used.

Creating Synchronization Agreements

87

The passsync plug-in for Windows uses a standard ldapmodify operation to change users'passwords. These operations take effect immediately, and are still normally subject to passwordpolicy settings. When the special user used by passsync sets the password, these password policiesshould be bypassed and the password should not be set to immediately expire, as is the case whena normal administrator resets a user password. To achieve this, you need to add a list of passSyncManager DNs to the password plug-in configuration. These users will be exempt from password policyenforcement in the same way that the Directory Manager is exempt. This currently requires a manualconfiguration, as follows:

Procedure 8.2. To add a list of passSync Manager DNs to the password plug-in configuration:1. As Directory Manager, modify the entry cn=ipa_pwd_extop,cn=plugins,cn=config

2. Add or update the passSyncManagersDNs attribute. This is a multi-valued list of DNs thatbypass password policy.

The following is an example of adding the new entry uid=admin:

% ldapmodify -x -D "cn=Directory Manager" -WEnter LDAP Password: *******dn: cn=ipa_pwd_extop,cn=plugins,cn=configchangetype: modifyadd: passSyncManagersDNspassSyncManagersDNs: uid=admin,cn=users,cn=accounts,dc=example,dc=com

Note

The entry cn=Directory Manager always bypasses policy and does not need to be explicitlylisted.

8.4. Creating Synchronization AgreementsUse the ipa-replica-manage connect command to create synchronization agreements. Thefollowing command-line arguments apply to creating synchronization agreements:

• --winsync — specifies that this is a Windows Sync agreement. Winsync replication occurs everyfive minutes.

• --binddn — the full DN of the user to use. The DS will bind to Active Directory as this user to readand write changes. This user requires read, search, and write permissions on the Active Directorysubtree, including password changes, as well as permission to use the DirSync control (that is, itmust be able to use replication).

• --bindpw — the password for the user specified by the --binddn argument.

• --passsync — the password for the Windows PassSync user, and a required argument to ipa-replica-manage when creating winsync agreements.

• --cacert — the full path and file name of the ASCII/PEM-encoded Windows Active Directory CAcertificate. This certificate will be installed in the Directory Server certificate database as "ImportedCA".

• --win-subtree — the DN of the Windows subtree containing the users you want to synchronize.The default value is cn=Users,$SUFFIX — this is what Windows AD typically uses as the defaultvalue.

The following example illustrates adding a new WinSync agreement:


88

Example 8.1. Adding a WinSync agreement between an IPA server and an AD server.

ipa-replica-manage connect --winsync --binddn cn=administrator,cn=users,dc=example,dc=com \--bindpw password --passsync password --cacert /path/to/certfile.cer adserver.example.com -v

8.5. Modifying Synchronization AgreementsYou can change the behavior of the synchronization agreement to suit the changing needs of yourorganization. You can modify a number of attributes related to the synchronization agreement usingdefault tools provided with IPA.

The following example illustrates changing the synchronization behavior of account lock status. Bydefault, account lock status is synchronized between IPA and AD. This means that accounts that arelocked in IPA are also locked (disabled) in AD, and vice versa. You can change this synchronizationbehavior as follows:

Example 8.2. Configuring the IPA WinSync agreement to not synchronize account lock statusinformation.

$ ldapmodify -x -D "cn=directory manager" -w passworddn: cn=ipa-winsync,cn=plugins,cn=configchangetype: modifyreplace: ipaWinSyncAcctDisableipaWinSyncAcctDisable: none

modifying entry "cn=ipa-winsync,cn=plugins,cn=config"

The default value of the ipaWinSyncAcctDisable attribute is both. If you change this value tonone, as described in the example, account lock status synchronization is completely disabled. Validvalues for ipaWinSyncAcctDisable are both, to_ad, to_ds, and none.

8.5.1. Changing the Default Synchronization SubtreeWhen you create synchronization agreements, two default containers are used as the sourceof the user accounts to synchronize between IPA and Windows Active Directory. IPA uses thecn=users,cn=accounts,$SUFFIX subtree as the default container, and Windows uses theCN=Users,$SUFFIX subtree. You can use the --win-subtree argument to the ipa-replica-manage connect command to override the default Windows subtree.

Note

If you pass such arguments to the bash or other shell, ensure that you quote spaces and othershell metacharacters. For example, the argument --win-subtree=cn=users, dc=example,dc=com will fail. The argument --win-subtree="cn=users, dc=example, dc=com" willsucceed.

IPA does not currently support modifying the default synchronization container while you arecreating the synchronization agreement. You can, however, change the container after theagreement has been established. To do so, you can either modify the dse.ldif file directly

Deleting Synchronization Agreements

89

(ensure that you stop the directory server before editing this file), or use ldapmodify to changensds7WindowsReplicaSubtree.

8.6. Deleting Synchronization AgreementsYou can use the IPA administration tools to delete existing synchronization agreements. For example,to delete an agreement with the AD server adserver.example.com, run the following command:

# ipa-replica-manage disconnect adserver.example.com

This removes the replication agreement between the IPA and AD servers. To complete the operation,you need to remove the AD certificate from the IPA server. Run the following command to remove theAD certificate:

# certutil -D -d /etc/dirsrv/slapd-$REALM/ -n "Imported CA"

8.7. Winsync Agreement Failures

SymptomIf the creation of a winsync agreement fails, you may see an error message similar to the following:

"Update failed! Status: [81 - LDAP error: Can't contact LDAP server]

CauseOne example of this error occurring is if you use an invalid Windows Server Certificate when creatingthe winsync agreement. This can result in the wrong certificates being created in the certificatedatabase in the /etc/dirsrv/slapd-DOMAIN-NAME/ directory, and with same name, for example"Imported CA". The following is an example of a corrupt certificate database after such a failure (notethe duplicate "Imported CA" entries):

$ certutil -L -d /etc/dirsrv/slapd-DOMAIN-NAME/

Certificate Nickname Trust AttributesSSL,S/MIME,JAR/XPI

CA certificate CTu,u,CuImported CA CT,,CServer-Cert u,u,uImported CA CT,,C

SolutionTo resolve this issue, you need to clear the certificate database, as follows:

# certutil -d /etc/dirsrv/slapd-DOMAIN-NAME -D -n "Imported CA"

This will delete the CA from the AD server ("Imported CA"). You need to do this after each failedinvocation.

You may also see the following message:

"Windows PassSync entry exists, not resetting password"


90

This is not an error, but rather a notification that IPA is not re-adding the passync user, and neitheris it changing the original password. The passync user is a special user entry that can changepasswords in IPA.

Chapter 9.

91

Identity: Integrating with NIS Domainsand Netgroups

9.1. About NIS and IPA

9.1.1. What are Netgroups?Netgroups are a concept introduced in the directory service NIS. They were designed to contain users,hosts (machines) and other netgroups. A netgroup is a user-host-domain triplet. Refer to the followingfor more details about netgroups and their uses:

• http://compute.cnr.berkeley.edu/cgi-bin/man-cgi?netgroup+4

• http://directory.fedoraproject.org/wiki/Howto:Netgroups#What_are_NIS_netgroups_good_for.3F

Note

Do not read beyond the section "What are NIS netgroups good for?"; netgroup entries aredifferent in IPA.

Despite this difference, it is important to underline that there are two plug-ins in IPA that make the datain the new format available via NIS or the old standard RFC2307 and RFC2307bis LDAP schema. Fordetails, refer to the documentation and examples at: https://fedorahosted.org/slapi-nis1. The entriesstored using the new schema are converted into the standard NIS netgroup map and served via theNIS protocol by the first plug-in described on the slapi-nis project page and the compatibility plug-incan be used to create a virtual LDAP view that matches the standard 2307 or 2307bis schema fornetgroups using the IPA-specific schema.

Historically, netgroups have been used to define groups of hosts or users. The advantage of netgroupsfor user aggregation has been that netgroups allow nesting while normal UNIX user groups do not.Netgroups also provide the only way to aggregate hosts. There is no notion of host groups in NIS,although for effective centralized system management they are definitely needed. It is important tounderstand that netgroups are collections of entities, be they users, hosts, or both, but there is norelation between particular user-host pairs defined in the netgroup triplet.

9.1.2. The IPA Approach to NetgroupsIPA defines both user groups and host groups, each of which allow nesting. This is a much cleanerway of aggregation and allows better separation of duties and access control. In an IPA deployment,netgroups are a much less attractive approach to grouping than with other LDAP-based systemscompliant with RFC 2307 (this defines the LDAP schema for users, groups, netgroups and othermaps).

Client-side applications, for example, SUDO, need netgroups because there is no alternative to hostgrouping on the client side. Consequently, netgroups are far from obsolete on the client side. A lotof effort is still required within SSSD and IPA to provide clean interfaces to reliably (both online and

1 https://fedorahosted.org/slapi-nis/

http://compute.cnr.berkeley.edu/cgi-bin/man-cgi?netgroup+4

http://directory.fedoraproject.org/wiki/Howto:Netgroups#What_are_NIS_netgroups_good_for.3F

https://fedorahosted.org/slapi-nis/

https://fedorahosted.org/slapi-nis/

Chapter 9. Identity: Integrating with NIS Domains and Netgroups

92

offline) relay centrally-managed information to applications running on a client machine. IPA thereforeprovides a way to define and store netgroups, but they are viewed as secondary to user groups andhost groups.

9.1.2.1. How IPA Stores NetgroupsIPA stores netgroups in a different format from that specified in RFC2307 and RFC2307bis. Thenetgroup entries defined by the IPA schema allow relating different objects (users, groups, hosts,host groups) to each other. IPA also provides what is known as a compat (compatibility) plug-in. Thisplug-in creates a virtual view of the data stored in native IPA entries in the format expected by theRFC-compliant clients. This means that even though the internal data representation of netgroups isdifferent from the RFC, this deviation does not affect clients due to the presence of the compat plug-in.

Comparison of SchemaTo realize the differences, we can compare the standard RFC schema for netgroups and the schemaused by IPA. IPA defines the following object class:

objectClasses: (2.16.840.1.113730.3.8.4.8 NAME 'ipaNISNetgroup' DESC 'IPA version of NIS netgroup' SUP ipaAssociation STRUCTURAL MAY ( externalHost $ nisDomainName $ member $ memberOf ) X-ORIGIN 'IPA v2' )

The IPA netgroup object class is derived from the association object class:

objectClasses: (2.16.840.1.113730.3.8.4.6 NAME 'ipaAssociation' ABSTRACT MUST ( ipaUniqueID $ cn ) MAY ( memberUser $ userCategory $ memberHost $ hostCategory $ ipaEnabledFlag $ description ) X-ORIGIN 'IPA v2' )

The RFC2307bis schema defines the netgroup object as:

objectClasses: (1.3.6.1.1.1.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL DESC 'Abstraction of a netgroup. May refer to other netgroups' MUST cn MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) )

DiscussionThe nisNetgroupTriple is a string consisting of the host-user-domain triplet. The IPA formatallows referencing of other objects present in IPA, such as users and groups, instead of manuallyadding them to the value of the netgroup triplet. Such an arrangement provides a better administrativeexperience when a user or group is removed or renamed. Inspecting the memberUser attribute ofthe association, you can see that it can hold the DN of a user or a user group. In the same way, thememberHost attribute can hold a reference to a host or a host group entry. This means that thenetgroup can function as a wrapper for groups of users and groups of hosts.

For examples and more information on the meaning of the user and host category attributes, refer to:• http://www.freeipa.org/page/DS_Design_Summary#Association_of_Different_Entities

http://www.freeipa.org/page/DS_Design_Summary#Association_of_Different_Entities

Adding Netgroups

93

• http://www.freeipa.org/page/DS_Design_Summary#Netgroups

9.1.3. Adding NetgroupsNIS groups traditionally contain a so-called netgroup triple of the format: (machine, user, domain)

machine - machine name, a host nameuser - user namedomain - NIS domain of the machine and user

IPA does not use this triple. Instead, it uses the membership relationship between LDAP entries. It is asimple matter to add users, hosts, and even their groups as members of a netgroup. The domain fieldis constant for each netgroup and defaults to the current IPA domain.

The following is an example of a netgroup displayed using the IPA CLI:

# ipa netgroup-show net1Netgroup name: net1Description: test netgroupNIS domain name: pandaMember User: adminMember Host: icefloat.panda

Note

There is no necessary relationship between the machine and the user. Only one of those fields isusually used at a time to avoid confusion.

9.1.4. IPA Netgroup CommandsThe IPA netgroup management plug-in conforms to the Create, Read, Update, Delete (CRUD)command-naming conventions used in all other plug-ins that ship with the default IPA installation.You can use the following command to display a list of the IPA commands available for working withnetgroups:

# ipa help netgroup

Creating New NetgroupsUse the ipa netgroup-add command to add new netgroups to IPA:

# ipa netgroup-add NAME [--desc=DESCRIPTION] [--nisdomain=NISDOMAIN]

NAME - the name of the netgroup (can be anything, but must be unique)

DESCRIPTION - the netgroup description (required)

NISDOMAIN - the NIS domain name. Defaults to the current IPA domain

Deleting NetgroupsUse the ipa netgroup-del command to delete IPA netgroups:

# ipa netgroup-del NAME

http://www.freeipa.org/page/DS_Design_Summary#Netgroups


94

Displaying NetgroupsUse the ipa netgroup-show command to display information about IPA netgroups:

# ipa netgroup-show NAME

Modifying NetgroupsUse the ipa netgroup-mod command to modify details about IPA netgroups:

# ipa netgroup-mod NAME [--desc=DESCRIPTION] [--nisdomain=NISDOMAIN]

Same as ipa netgroup-add, except modifying the description is required and NISDOMAIN doesnot default to anything.

Searching for NetgroupsUse the ipa netgroup-find command to search for IPA netgroups:

# ipa netgroup-find [CRITERIA] [--name=NAME] [--desc=DESCRIPTION] [--nisdomain=NISDOMAIN] [--uuid=UUID]

CRITERIA is an optional substring, and if included in the query it must appear in either the name, thedescription or the NIS domain of the groups you are searching for. Other options are the same as ipanetgroup-add, except that nothing is required and there are no default values. There is a new UUIDoption that allows searching netgroups by ipaUniqueID. If one of these options is set, the commandreturns only exact matches of this option.

Adding Users and Hosts to NetgroupsUse the ipa netgroup-add-member command to add users and hosts to IPA netgroups:

# ipa netgroup-add-member NAME [--users=USERS] [--groups=GROUPS] [--hosts=HOSTS] \ [--hostgroups=HOSTGROUPS] [--netgroups=NETGROUPS]

USERS, GROUPS, HOSTS, HOSTGROUPS, and NETGROUPS are comma-separated lists of namesof the appropriate objects.

Removing Users and Hosts From NetgroupsUse the ipa netgroup-remove-member command to remove users and hosts from IPA netgroups:

ipa netgroup-remove-member { NAME } [ --users=USERS ] [ --groups=GROUPS ] [ --hosts=HOSTS ] [ --hostgroups=HOSTGROUPS ] [ --netgroups=NETGROUPS ]

Configuring the Network Information Service (NIS)

95

USERS, GROUPS, HOSTS, HOSTGROUPS, and NETGROUPS are comma-separated lists of namesof the appropriate objects.

9.1.4.1. ExamplesThe following examples provide an introduction to using the ipa netgroup-* commands:

# ipa netgroup-add net0 --desc="test netgroup" Netgroup name: net0 Description: test netgroup NIS domain name: pavlova IPA unique ID: 9e6e089c-2089-11df-b677-5452004c033a

# ipa netgroup-mod net0 --desc="description change" Netgroup name: net0 Description: description change NIS domain name: pavlova

# ipa netgroup-add-member net0 --users=admin --hosts=testbox.pavlova Netgroup name: net0 Description: description change NIS domain name: pavlova Member User: admin Member Host: testbox.pavlova-------------------------Number of members added 2-------------------------

# ipa netgroup-remove-member net0 --users=admin Netgroup name: net0 Description: description change NIS domain name: pavlova Member Host: testbox.pavlova---------------------------Number of members removed 1---------------------------

# ipa netgroup-del net0

# ipa netgroup-show net0ipa: ERROR: no such entry

9.2. Configuring the Network Information Service (NIS)The Network Information Service (NIS) is an RPC service, used in conjunction with portmap andother related services to distribute maps of usernames, passwords, and other sensitive information toany computer claiming to be within its domain.

IPA provides a NIS server plug-in to facilitate the integration of NIS clients with an IPA domain,including exposing any automount maps that have been configured.

9.2.1. Exposing Automount Maps to NIS ClientsCurrently, when the NIS service is enabled, the server is automatically configured to serve the NISdomain with the IPA domain's name, and to serve IPA users, groups, and netgroups (passwd, group,and netgroup maps) to the NIS domain.

If you have defined automount maps, these maps need to be manually added to the NIS server plug-in's configuration in the directory server in order to expose them to NIS clients.


96

The NIS plug-in needs to know the name of the NIS domain, the name of the NIS map, how to find thedirectory entries to use as the NIS map's contents, and which attributes to use as the NIS map's keyand value. Most of these settings will be the same for every map.

The IPA server stores the automount maps, grouped by automount location, in the cn=automountbranch of the IPA domain's tree.

9.2.1.1. Example Automount Map ConfigurationIf you have created an automount map named auto.example in a location named "default", youfirst need to add an entry to the configuration for the NIS server running on a host named dirsrv, asfollows:

LOCATION=defaultNISDOMAIN=example.comNISMAP=auto.masterNISSERVER=dirsrvIPASUFFIX=`echo ${NISDOMAIN} | sed -e 's,^,dc=,g' -e 's,\.,\,dc=,g'`

ldapadd -h ${NISSERVER} -x -D "cn=Directory Manager" -W << EOFdn: nis-domain=${NISDOMAIN}+nis-map=${NISMAP}, cn=NIS Server, cn=plugins, cn=configobjectClass: extensibleObjectnis-domain: ${NISDOMAIN}nis-map: ${NISMAP}nis-filter: (objectclass=automount)nis-key-format: %{automountKey}nis-value-format: %{automountInformation}nis-base: automountmapname=${NISMAP}, ${LOCATION:+cn=${LOCATION},} cn=automount, ${IPASUFFIX}

EOF

This entry instructs the plug-in to create a map named auto.master in the domain named${NISDOMAIN}, and that the data for that map should be read from the entries at and belowautomountmapname=${NISMAP}, which exists inside a container named cn=${LOCATION}. Thiscontainer is in the automount section of the IPA data store. The keys for the entries in the automountmap in NIS are the values of the automountKey attribute for the directory server entries, and thecorresponding values in the NIS map are the values of the automountInformation attribute inthose same entries.

You then need to repeat the process for the auto.direct map, and then any other maps that youhave defined.

9.3. Migrating from NIS to IPAThe IPA development team researched the topic of how netgroups are typically used in order to betterdetermine an optimal migration design solution. This research shows that the main use cases fornetgroups are the aggregation of users and the aggregation of hosts, but not both at the same time.IPA does not provide a special script or command to facilitate the migration of customers' existingnetgroups to IPA. This operation must be performed by the system administrator himself or with thehelp of professional services. This chapter provides some guidelines to ease the process of migratingnetgroups to IPA.

Preparing Your Environment

97

9.3.1. Preparing Your Environment

Note

These procedures are guidelines only, and are provided to help clean your environment andmake it more manageable. It is not a definitive set of instructions, and administrators need to becreative and factor in the real constraints present in their environment. If any steps describedbelow are not possible due to independent conditions, we recommend migrating netgroups on aone-to-one basis. This is described later in this chapter.

Procedure 9.1. To prepare your environment1. Inspect your client applications and determine which kind of grouping information they need from

the central server. For example, if netgroups exist that contain only users, and any applicationsthat rely on these netgroups can be converted to use UNIX groups instead of netgroups, then werecommend doing so. If this is not possible, we still recommend creating UNIX groups out of thenetgroups. If no applications use them, we recommend deleting these netgroups altogether. Referto the following example:

a. Given the following netgroup: (host1, user1, )(host2, user2,)(host3,user3, )..., create a group consisting of the users user1, user2, and user3 (assumingit does not already exist).

b. Create a netgroup that has a memberUser attribute equal to the DN of the newly-createdgroup. This netgroup will be equivalent to your original netgroup.

2. Migrating hosts is more straightforward. The creation of a host group automatically triggers thecreation of a netgroup that is linked to the newly-created host group. This functionality is enabledby default, and can be managed with the following commands:• ipa-host-net-manage status

• ipa-host-net-manage disable

• ipa-host-net-manage enable

This can be disabled when the clients no longer use netgroups for aggregation of hosts.

3. If none of the above recommendations are possible and the netgroups need to be converted on aone-to-one basis, then:

a. Ensure that all users referenced by a netgroup have been migrated. If not, then create them.

b. Ensure that all hosts referenced by a netgroup have been migrated. If not, then create them.

c. Create a netgroup with the same name as the original netgroup.

d. Add users and hosts as direct members of the netgroup, or, alternatively, put them intogroups and then add those groups as members to the netgroup.

For IPA clients, both methods result in the same thing — having the users and hostsmanaged in the netgroup — but from an administrative perspective, it may be simpler insome environments to use one option instead of the other.

9.3.2. Migrating NetgroupsThere are three main approaches that can be taken to the actual migration procedure:


98

1. a. Dump the netgroups from the source into an LDIF file.

b. Create a script that follows the instructions in Procedure 9.1, “To prepare your environment” toconvert the LDIF format into an LDIF file that contains IPA native objects.

c. Run the conversion script and load the resulting LDIF file into IPA using the ldapmodifycommand.

Refer to http://linux.die.net/man/1/ldapmodify or a similar man page for more details.

2. a. Create a script to retrieve data from the source (by parsing the LDIF file or by connecting tothe original source of information using the client utility).

b. Create a second script that invokes a sequence of IPA CLI commands. This script uses theinformation from the first script to create user, user group, host, host group and netgroupentries, and to create the appropriate associations.

Refer to the IPA CLI help system for more details. Use the ipa help command to display alist of available topics.

3. a. Use the UI to manually create a new structure of netgroups.

http://linux.die.net/man/1/ldapmodify

Chapter 10.

99

Policy: Managing DNSIf the FreeIPA server was installed with DNS configured, then all of the DNS entries for the domain —host entries, locations, records — can be managed using the FreeIPA tools.

10.1. About DNS in FreeIPADNS is one of the services that can be configured and maintained by the FreeIPA domain. DNS iscritical to the performance of the FreeIPA domain; DNS is used for the Kerberos services and SSLconnections for all servers and clients and for connections to domain services like LDAP.

While FreeIPA can use an external DNS service, there is a lot more flexibility and control over FreeIPA—DNS interactions when the DNS service is configured within the domain. For example, DNS recordsand zones can be managed within the domain using FreeIPA tools, and clients can update their ownDNS records dynamically. When a host is added to FreeIPA, a DNS record is automatically created inFreeIPA's DNS service for that host machine.

FreeIPA stores all DNS information as LDAP entries. Every resource record for each machine isstored for the domain. For example, the client1 resource has three IPv4 (A) records and one IPv6(AAAA) record:

dn: idnsname=client1,idnsname=example.com,cn=dns,dc=example,dc=comidnsname: client1arecord: 10.0.0.1arecord: 10.0.0.2arecord: 10.0.0.3aaaarecord: fc00::1objectclass: topobjectclass: idnsrecord

The schema used to define the the DNS entries is in the /usr/share/ipa/60basev2.ldifschema file.

FreeIPA communicates with both the BIND services and the LDAP directory using the bind-dyndb-ldapplug-in.

The ipa command has several subcommands to manage the DNS service.

Table 10.1. DNS Management Tools

Command Description

dns-resolve Resolves a hostname to see if it exists within theFreeIPA domain.

dnsrecord-add and dnsrecord-del Adds and deletes DNS records.

dnsrecord-find and dnsrecord-show Finds and displays DNS records.

dnszone-add and dnszone-del Adds and deletes DNS SOA records.

dnszone-enable and dnszone-disable Enables and disables DNS zones. These toolscontrol whether a DNS zone is active andavailable without deleting the configurationentries in the LDAP directory.

dnszone-find and dnszone-show Finds and displays DNS zone configuration.

Chapter 10. Policy: Managing DNS

100

10.2. Configuring DNSDNS can be configured as part of the FreeIPA server installation, simply by using the --setup-dns option. If DNS is not configured then, it can be configured later using the ipa-dns-installcommand. For example:

ipa-dns-install -p secret --ip-address=1.2.34.56 --no-forwarders

• -p gives the password for the Directory Manager user in the 389 Directory Server. All of th DNSentries are stored in the LDAP directory, so this directory must be accessed to add the DNSconfiguration.

• --ip-address gives the IP address for the master DNS server.

• --no-forwarders means that there are no forwarders used with the DNS service, only rootservers. Alternatively, a comma-separated list of forwarders can be given, using the --forwardersoption.

• Reverse DNS is configured automatically. It is possible to disable reverse DNS by using the --no-reverse option.

10.3. Finding and Displaying DNS ZonesThe first part of managing a DNS domain is simply knowing what the domain configuration is. This isdone by finding and displaying DNS zone records.

Finding and displaying records can be done using the dnszone-find command. This command canbe used either to return a list of all zones or to find a specific record based on any of the attirbutes inthe zone entry. Using either the dnszone-find or the dnszone-show command lists the full start ofauthority (SOA) record for the DNS zone.

At its simplest, simply running the dnszone-find returns all of the zones for the DNS service:

$ ipa dnszone-find

Zone name: example.com Authoritative nameserver: server.example.com. Administrator e-mail address: root.server.example.com. SOA serial: 2011130701 SOA refresh: 3600 SOA retry: 900 SOA expire: 1209600 SOA minimum: 3600 Active zone: TRUE

Zone name: 1.2.3.in-addr.arpa. Authoritative nameserver: server.example.com. Administrator e-mail address: root.1.2.3.in-addr.arpa. SOA serial: 2011130701 SOA refresh: 3600 SOA retry: 900 SOA expire: 1209600 SOA minimum: 3600 Active zone: TRUE----------------------------Number of entries returned 2----------------------------

Alternatively, the DNS zones can be filtered by searching for a particular attribute in the SOA record.For example, this searches for the example.com zone by the hostname:

Adding DNS Zones

101

$ ipa dnszone-find --name-server=server1.example.com

The dnszone-show command is equivalent to the dnszone-find --name command because itonly displays the record for the specific zone by its fully-qualified domain name.

$ ipa dnszone-show example.com

10.4. Adding DNS ZonesThe ipa dnszone-add command add a new zone to the DNS domain. At a minimum, this requiresthe name of the new subdomain:

$ ipa dnszone-add domainName

If the name is not given, the script prompts for it. Other command-line options can also be passed withthe ipa dnszone-add command; these are described in .

To add a zone entry:

1. Add the new zone. For example:

$ ipa dnszone-add newserver.example.com [email protected] --minimum=3000 --allow-dynupdate

2. Reload the named service to load the new zone into the DNS domain configuration. If the serviceis not restarted, the DNS server will not respond to queries for records in the new zone.

# service named reload

10.5. Modifying DNS ZonesA zone is created with a certain amount of configuration, set to default values:

dn: idnsname=example.com,cn=dns,dc=example,dc=com idnsname: example.com idnssoamname: server.example.com. idnssoarname: root.server.example.com. idnssoaserial: 2011130701 idnssoarefresh: 3600 idnssoaretry: 900 idnssoaexpire: 1209600 idnssoaminimum: 3600 idnsupdatepolicy: grant EXAMPLE.COM krb5-self * A; grant EXAMPLE.COM krb5-self * AAAA; idnszoneactive: TRUE idnsallowdynupdate: TRUE nsrecord: server.example.com. objectclass: top objectclass: idnsrecord objectclass: idnszone

The zone can be created with additional attributes and values different from the default by passingadditional options with the dnszeon-add command. Likewise, attributes can be added or modifiedin the zone entry by passing the same attribute options with the dnszone-mod command. These arelisted in Table 10.2, “Zone Attributes”.


102

If an attribute does not exist in the DNS zone entry, than the dnszone-mod command adds theattribute. If the attribute exists, then it overwrites the current value with the specified value.

For example, to set a time to live for SOA records:

$ ipa dnszone-mod server.example.com --ttl=1800

This adds a new attribute to the DNS zone entry:

dn: idnsname=example.com,cn=dns,dc=example,dc=com idnsname: example.com idnssoamname: server.example.com. idnssoarname: root.server.example.com. idnssoaserial: 2011130701 idnssoarefresh: 3600 idnssoaretry: 900 idnssoaexpire: 1209600 idnssoaminimum: 3600 dnsttl: 1800 idnsupdatepolicy: grant EXAMPLE.COM krb5-self * A; grant EXAMPLE.COM krb5-self * AAAA; idnszoneactive: TRUE idnsallowdynupdate: TRUE nsrecord: server.example.com. objectclass: top objectclass: idnsrecord objectclass: idnszone

Table 10.2. Zone Attributes

Attribute Command-Line Option Description

Zone name --name Sets the name of the zone.

Authoritative nameserver --name-server Sets the fully-qualified domainname of the DNS name server.

Administrator e-mail address --admin-email Sets the email address to usefor the zone administrator. Thisdefaults to the root account onthe host.

SOA serial --serial Sets a version number for theSOA record file.

SOA refresh --refresh Sets the interval, in seconds,for a secondary DNS server towait before requesting updatesfrom the primary DNS server.

SOA retry --retry Sets the time, in seconds, towait before retrying a failedrefresh operation.

SOA expire --expire Sets the time, in seconds, thata secondary DNS server willtry to perform a refresh updatebefore ending the operationattempt.

SOA minimum --minimum Sets the minimum amount oftime, in seconds, that data arekept in cache.

Enabling Dynamic DNS Updates

103

Attribute Command-Line Option Description

SOA time to live --ttl Sets the maximum time, inseconds, that information iskept in the data cache.

SOA class --class Sets the type of record. This isalmost always IN, which standsfor Internet.

BIND update policy --update-policy Sets the permissions allowed toclients in the DNS zone.

Dynamic update --allow-dynupdate Enables dynamic updates toDNS records for clients.

Name server --ip-address Adds the DNS name server byits IP address.

10.6. Enabling Dynamic DNS UpdatesDynamic DNS updates are not enabled by default for new DNS zones in FreeIPA. If dynamic updatesare not allowed, then it may not be possible for the ipa-client-install script to join a client to thedomain because it cannot add a DNS record pointing to the new client.

To allow dynamic updates to the DNS zones, set the --allow-dynupdate option.

$ ipa dnszone-mod server.example.com --allow-dynupdate

10.7. Enabling and Disabling ZonesActive zones can have clients added to them, are available for lookups, and are used by FreeIPAservices like Kerberos. Deleting a DNS zone removes the zone entry and all the associatedconfiguration.

There can be situations when it is necessary to remove a zone from activity without permanentlyremoving the zone. This can be done by using the dnszone-disable command.

For example:

$ ipa dnszone-disable server.example.com

When the zone needs to be brought back online, it can be re-enabled using the dnszone-enablecommand.

10.8. Adding Records to DNS ZonesFreeIPA supports several different types of DNS records, listed in Table 10.3, “DNS Record Types”.

Table 10.3. DNS Record Types

A DS NSEC3PARAM

AAAA HIP PTR

A6 IPSECKEY RRSIG

AFSDB KX RP

APL LOC SIG


104

CERT MX SPF

CNAME NAPTR SRV

DHCID NS SSHFP

DLV NSEC TA

DNAME NSEC3 TXT

DNSKEY

The ipa dnsrecord-add command adds records to DNS zones, based on the type. Adding arecord has the same basic command format:

$ ipa dnsrecord-add domainName urlLabel --recordType--rec record

The recordType is an identifier, such as a for A or IPv4 records. The record value is the actual entry,which has a value corresponding to the record type.

NOTE

The ipa dnsrecord-add command only creates forward entries, not reverse entries.

Example 10.1. IPv4 RecordType A resource records map hostnames to IPv4 addresses. The record value for these commands,then, is a standard IPv4 address. The URL label is usually www.

$ ipa dnsrecord-add example.com www --a-rec 10.64.14.165

This creates the record www.example.com with the IP address 10.64.14.165.

More information about A records is in RFC 10351.

Example 10.2. IPv6 RecordType AAAA resource records (quad-A records) map hostnames to IPv6 addresses. The recordvalue for these commands is an IPv6 address. As with Type A records, the URL label is usuallywww.

$ ipa dnsrecord-add example.com www --aaaa-rec fe80::20c:29ff:fe02:a1b3

This creates the record www.example.com with the IP address fe80::20c:29ff:fe02:a1b3. Moreinformation about AAAA records is in RFC 35962.

Example 10.3. SRV RecordService (SRV) resource records map service names to the DNS name of the server that is providingthat particular service. For example, this record type can map a service like an LDAP directory tothe DNS server which manages it.

As with Type A and Type AAAA records, SRV records specify a way to connect to and identify theservice, but the record format is different.

1 http://tools.ietf.org/html/rfc10352 http://tools.ietf.org/html/rfc3596

http://tools.ietf.org/html/rfc1035




Deleting Records from DNS Zones

105

The urlLabel identifies the service type and the connection protocol, in the format_service._protocol.

The record information has the format "priority weight port target".

$ ipa dnsrecord-add server.example.com _ldap._tcp --srv-rec="0 100 389 server1.example.com"

$ ipa dnsrecord-add server.example.com _ldap._tcp --srv-rec="1 100 389 server2.example.com"

More information about SRV records is in RFC 27823.

10.9. Deleting Records from DNS ZonesRecords are removed from the zone using the ipa dnsrecord-del command. As with addingrecords, records are deleted using an option that specifies the type of record (--recordType-rec) andthe record value.

For example, to remove the A type record:

$ ipa dnsrecord-del example.com www --a-rec 10.64.14.213

Alternatively, using the --del-all option removes all associated records for the zone.

10.10. Resolving Hostnames in the FreeIPA DomainIt is possible to check the DNS entries for FreeIPA domain members using the dns-resolvecommand. If the record exists and is properly formatted in the DNS configuration, then the commandreturns the DNS record. If not, the command returns an error, that the hostname is not recognizedwithin the DNS service.

$ipa dns-resolve server1.example.com

This can be helpful with troubleshooting connection problems between servers, clients, and services.

3 http://tools.ietf.org/html/rfc2782



106

Chapter 11.

107

Policy: Configuring Authorization

11.1. Configuring Host-Based Access ControlHost-based access control (HBAC) uses rules to determine who can access what services on whathosts and from where. You can use HBAC to control which users or groups on a source host canaccess a service, or group of services, on a target host. Target hosts and source hosts in HBAC rulesmust be hosts managed by IPA.

You can also specify a category of users, target hosts, and source hosts. This is currently limited to"all", but might be expanded in the future.

The available services and groups of services are controlled by the hbacsvc and hbacsvcgroupplug-ins, respectively.

11.2. HBAC Service GroupsHBAC service groups can contain any number of individual services (members), and are typically usedto group similar services to make it easier to create HBAC rules. All HBAC service groups require aname and description. IPA provides a single default group, SUDO, used for SUDO-related services.

Use the ipa hbacsvcgroup-find command to display the existing HBAC groups:

# ipa hbacsvcgroup-find----------------------------1 HBAC service group matched---------------------------- Service group name: SUDO Description: Default group of SUDO related services----------------------------Number of entries returned 1----------------------------

IPA provides commands for adding, removing and modifying HBAC service groups, adding andremoving members to and from those groups, and displaying group information. Refer to the ipahelp hbacsvcgroup help page for more information.

11.3. HBAC ServicesHBAC services refer to the PAM services that the IPA HBAC system can control access to. HBACservice names must exactly match the service name that PAM is evaluating. For example, use thefollowing command to add the tftp service as an HBAC service:

# ipa hbacsvc-add tftp-------------------------Added HBAC service "tftp"-------------------------

Use the ipa hbacsvc-find command to search for HBAC services. Note that in this example, tworesults are returned; the newly-added tftp service and the preexisting ftp service:

# ipa hbacsvc-find ftp-----------------------2 HBAC services matched-----------------------

Chapter 11. Policy: Configuring Authorization

108

Service name: ftpDescription: ftp

Service name: tftp----------------------------Number of entries returned 2----------------------------

Refer to the ipa help hbacsvc help page for more information.

Chapter 12.

109

Policy: Using sudo

12.1. About sudo and IPAThe sudo command allows a system administrator to delegate authority, allowing certain users (orgroups of users) the ability to run one or more commands as root or as another user, and at the sametime providing an audit trail of the commands and their arguments. For more information, includingcoverage of the options available for use with sudo, refer to the sudo and sudoers man pages.

12.1.1. Sudo with LDAPIn the past, sudo used a single, local, configuration file, /etc/sudoers. It is possible to share thesame sudoers file among machines, but there is no built-in mechanism to distribute it. Some haveattempted to work around this by synchronizing changes using CVS, RSYNC, RDIST, RCP, SCP, andeven NFS. By using LDAP for sudoers, IPA provides a centrally-administered, globally-availableconfiguration source for sudo.

12.1.2. Limitations of the Existing Sudo LDAP Schema

Groups of UsersThe current schema relies on LDAP-stored POSIX groups for its groups of users. The limitation here isthat you cannot use a group of users for sudo without the users inheriting potential POSIX rights.

Groups of HostsThe current schema does not have a concept of host groups. Instead, it relies on the legacy LDAPnisNetgroupTriple to manage groups of hosts.

Groups of CommandsThe current schema does not have a concept of command groups. This requires that individualcommands be present in each Sudo rule. It also limits the ability to reuse a group of commands formultiple Sudo rules.

12.1.3. Benefits of the IPA Alternative Schema

Groups of UsersGroups of users can be either POSIX or non-POSIX groups within IPA. This provides the flexibility togroup users without assigning POSIX rights or GID information to the group.

Groups of ComputersThe IPA alternative schema also addresses the issue of host groups and netgroups for the purposeof sudo. The sudo utility itself does not support host groups—a better and cleaner host groupingmechanism—but instead expects netgroups. To resolve this issue, IPA automatically creates a"shadow netgroup" with the same name as every host group that you create. This means that you cancreate host groups but still use netgroups with sudo without encountering any problems.

Chapter 12. Policy: Using sudo

110

Groups of CommandsCommand groups are a new concept introduced by IPA. These objects allow administrators theability to create groups of sudo commands that can be reused for multiple rules without the need ofassigning individual commands throughout.

12.1.4. Compatibility and Managed Entry Plug-in Configuration

Compatibility Translation for Native SudoThe native sudo binary does not yet support SSSD or the IPA Sudo Schema. As an interim solution,IPA has implemented a compatibility plug-in which transparently translates IPA Sudo rules into thosesupported by the current sudo binary.

Managed Entries for NIS NetgroupsIn order to seamlessly support the current implementation of sudo, IPA provides a managed entryplug-in for NIS netgroups. Whenever an IPA host group is created, a translated nisNetgroupTriple isalso created.

12.2. Configuring sudoTo fully implement Sudo rules, you need to perform various configuration steps on both the IPA serverand client. You should first create a Sudo command object, and optionally create any Sudo commandgroups. Finally, create a Sudo rule, which should contain at least the following components:One or more:

• users or groups of users

• hosts or groups of hosts

• commands or groups of commands

These steps are described in detail in the following sections.

12.2.1. Server Configuration for Sudo Rules

Procedure 12.1. How to configure your server to use Sudo rules:1. Set up a host group, and add the client to the host group:

a.$ ipa hostgroup-add bne_doc Description: BNE Documentation hosts ------------------------------- Added hostgroup "bne_doc" ------------------------------- Host-group: bne_doc Description: BNE Documentation hosts

b.$ ipa hostgroup-add-member bne_doc --hosts ipaclient.ipadocs.org Host-group: bne_doc Description: BNE Documentation hosts Member hosts: ipaclient.ipadocs.org-------------------------Number of members added 1-------------------------

Server Configuration for Sudo Rules

111

2. Set up a user group, and add the required users to this group. This procedure assumes that theIPA users already exist:

a.$ ipa group-add translators Description: Translation team ------------------------- Added group "translators" ------------------------- Group name: translators Description: Translation team GID: 1014000006

b.$ ipa group-add-member translators --users yhuang,klim,hchoi Group name: translators Description: Translation team GID: 1014000006 Member users: yhuang, klim, hchoi-------------------------Number of members added 3-------------------------

3. Set up a bind user. This requires setting the password for the sudo bind user.

$ LDAPTLS_CACERT=/etc/ipa/ca.crt /usr/bin/ldappasswd -S -W -h ipaserver.ipadocs.org -ZZ \ -D "cn=Directory Manager" uid=sudo,cn=sysaccounts,cn=etc,dc=ipadocs,dc=org New password: <sudo user's password> Re-enter new password: <sudo user's password> Enter LDAP Password: <Directory Manager's password>

4. Set up the Sudo commands.

a. Add one or more logically-related Sudo commands:

$ ipa sudocmd-add --desc 'For reading log files' '/usr/bin/less'----------------------------------Added sudo command "/usr/bin/less"---------------------------------- Sudo Command: /usr/bin/less Description: For reading log files

b. Add a suitable Sudo command group:

$ ipa sudocmdgroup-add --desc 'Read-only commands' readonly-----------------------------------Added sudo command group "readonly"----------------------------------- Sudo Command Group: readonly Description: Read-only commands

c. Add the command to the command group:

$ ipa sudocmdgroup-add-member --sudocmds '/usr/bin/less' readonly Sudo Command Group: readonly Description: Read-only commands Member Sudo commands: /usr/bin/less-------------------------Number of members added 1


112

-------------------------

5. Set up the Sudo rules.

a. Add the Sudo rule:

$ ipa sudorule-add readonly-commands-----------------------------------Added sudo rule "readonly-commands"----------------------------------- Rule name: readonly-commands Enabled: TRUE

b. Add the allowable commands. These are the commands enabled by this Sudo rule when it isactive.

$ ipa sudorule-add-allow-command --sudocmdgroups readonly readonly-commands Rule name: readonly-commands Enabled: TRUE Sudo Command Groups: readonly-------------------------Number of members added 1-------------------------

c. Add the hosts. These are the hosts and host groups to which this Sudo rule applies when it isactive.

$ ipa sudorule-add-host --hostgroups bne_doc readonly-commands Rule name: readonly-commands Enabled: TRUE Host Groups: bne_doc Sudo Command Groups: readonly-------------------------Number of members added 1-------------------------

d. Add the users (or groups of users). These are the IPA users affected by this Sudo rule:

$ ipa sudorule-add-user --groups translators readonly-commands Rule name: readonly-commands Enabled: TRUE Groups: translators Host Groups: bne_doc Sudo Command Groups: readonly-------------------------Number of members added 1-------------------------

12.2.2. Client Configuration for Sudo Rules

Procedure 12.2. How to configure your client to use Sudo rules:1. Configure sudo to look to LDAP for the sudoers file. Add the following line to /etc/

nsswitch.conf:

sudoers: ldap

Client Configuration for Sudo Rules

113

You can still use the local /etc/sudoers file in preference to the LDAP version. The followingconfiguration uses the local file before referring to LDAP to find sudo rules:

sudoers: files ldap

2. Configure SSSD to look for NIS netgroups.

a. Add the following line immediately after the ipa_server entry in the /etc/sssd/sssd.conf file:

ldap_netgroup_search_base = cn=ng,cn=compat,dc=ipadocs,dc=org

b. Restart the SSSD daemon:

# service sssd restart

3. Edit the LDAP configuration file for sudo:

a. Add the following lines to the /etc/nss_ldap.conf file. You may have to create this file if itdoes not already exist:

sudoers_base ou=SUDOers,dc=ipadocs,dc=orgbinddn uid=sudo,cn=sysaccounts,cn=etc,dc=ipadocs,dc=orgbindpw <sudo user's password>ssl start_tlstls_cacertfile /etc/ipa/ca.crttls_checkpeer yesbind_timelimit 5timelimit 15uri ldap://ipaserver.ipadocs.org

Note

The sudo user's password in this configuration is the same password you set up inProcedure 12.1, “How to configure your server to use Sudo rules:”.

If desired, you can also add the sudoers_debug parameter to this file to assist with anytroubleshooting processes. Valid values for this parameter are 0, 1, and 2. Refer to http://www.gratisoft.us/sudo/readme_ldap.html for more information.

b. To support compatibility with the legacy configuration, create the following symbolic link:

# ln -s /etc/nss_ldap.conf /etc/ldap.conf

4. Set up the NIS domain. Sudo still utilizes NIS netgroups, and so to support the client-sideidentification of NIS netgroup domains, you need to define your NIS domain name, as follows:

# nisdomainname example.com

http://www.gratisoft.us/sudo/readme_ldap.html

http://www.gratisoft.us/sudo/readme_ldap.html


114

Note

A bug has been filed in Fedora to have this configuration requirement addressed during theboot process.

12.2.2.1. NIS Configuration NotesOriginally called Yellow Pages (YP), NIS was created by Sun Microsystems and stands forNetwork Information Service. It was primarily used by UNIX to centrally manage authentication andenumeration information such as user/password, host/IP address, POSIX groups, and netgroups. NIS(the service) does not actually need to be configured on either the client or the server. Not only is itunnecessary, but might be considered a security risk if it were running. NIS is an RPC service and isinsecure by today's standards, partly because:• It provides no host authentication mechanisms

• It transmits all of its information over the network unencrypted, including password hashes

Modern Linux/BSD systems implement the Name Service Switch (NSS), which provides a means ofcontrolling and directing look ups for authentication and enumeration information.

The IPA LDAP implementation provides the schema to support NIS as defined in RFC 23071. NISobjects are automatically created inside of LDAP and NSS_LDAP, or SSSD fetches them using anencrypted LDAP connection.

Utilizing SSSD or NSS_LDAP, a client system can enumerate the necessary NIS information usingauthenticated and encrypted queries to the back end LDAP service provided by the IPA Server. Thiseliminates the need for NIS client configuration for systems that can support NIS using LDAP whenutilizing IPA.

1 http://tools.ietf.org/html/rfc2307



Chapter 13.

115

Configuring the FreeIPA Server

13.1. Defining Access Controls within FreeIPAAccess control is a mechanism which defines user access. That is, it defines the rights that usersand other objects have been granted in order to perform operations on other users or objects. Whenthe FreeIPA directory server receives a request, it uses the authentication information provided bythe user in the bind operation together with access control instructions (ACIs) defined in the server toallow or deny access to directory information. The server can allow or deny permissions for actions,such as read, write, search, and compare, on directory server entries. The permission level granted toa user may depend on the authentication information provided.

FreeIPA implements a number of different methods for controlling access to the various objects,commands and processes that exist within a FreeIPA domain. This includes a Kerberos Ticket Policy,a Password Policy, Host-based Access Control and SUDO Command Policies for controlling clientaccess to services and commands; that is, outside of the FreeIPA server, and a separate AccessControl Model for controlling server-side objects; that is, LDAP entries within the FreeIPA server.

FreeIPA relies on three separate types of access control rules:

• Role-based rules: specify what operations an entity can perform based on its FreeIPA Role.

• Self-service rules: specify what an entity can change within its own entry.

• Delegation rules: specify which groups can modify members of another group.

These three types of access control complement each other, and allow FreeIPA administrators tocreate a very flexible set of access control permissions and restrictions.

Role-based access control (RBAC) is a hierarchical way of organizing access to the data managed byFreeIPA. Users, groups, hosts, and host groups can be added to different FreeIPA Roles. These rolesprovide the necessary permissions for access. You can create as many roles as you need to suit therequirements of your deployment.

There are several aspects to working with roles. Because it is a hierarchical system, to create a fullyoperational role you need to create the role itself, add privileges to this role to establish what tasks itcan and cannot perform, and finally add members to the role, such as users, groups, etc. The reverseis also true; if you remove a role, then any users or groups who relied on this role to perform certaintasks will no longer be able to do so.

Note

You cannot create nested roles. That is, a role cannot contain another role.

13.1.1. Server-side Access ControlThe FreeIPA Access Control Model is based on the underlying 389 Directory Server access controlmodel, which uses access control instructions (ACIs) to define user access within the system. An ACIis a construct that can express a complex set of access control information.

As explained in the directory server documentation, the three main parts of an ACI statement are:• Target

• Permission

Chapter 13. Configuring the FreeIPA Server

116

• Bind Rule

The ACI structure itself is very flexible, but can also be confusing. FreeIPA attempts to structure theseACIs in order to provide a formalized input and output that can be expressed on the command line andin the WebUI, while at the same time maintaining sufficient flexibility to create complex access controlrules. In order to achieve this, FreeIPA implements three types of access control. These are discussedin the following sections.

13.1.1.1. Types of Access ControlFreeIPA relies on three separate types of access control rules:• Role-based

• Self-service

• Delegation

These three types of access control complement each other, allowing FreeIPA administrators tocreate a very flexible set of access control permissions and restrictions.

Role-based Access ControlRole-based access control (RBAC) is a hierarchical way of organizing access to the data managedby FreeIPA. Different users who perform the same tasks within an organization are typically combinedinto a group, and this group is made a member of a FreeIPA Role. This Role provides the membergroups and users the necessary permissions to perform their assigned tasks.

Self-service Access ControlSelf-service access control defines what operations an entity can perform on itself. This method ofcontrol is attribute based; that is, it defines what attributes can be modified for any particular entity.The ability of a user to update their own password is an example of self-service access control. Self-service access control applies to any authenticated entity performing an operation, not only to users.This method of access control should also be used with caution, to avoid the possibility that it lead tothe elevation of an entity's privileges.

Delegation Access ControlDelegation access control defines what operations one group of users or entries can perform onanother group of users or entries. In each case, the group of users or entries may be identified by aprovided filter. The core difference between delegation access control rules and other rules is thatthe target—the object of the access control rule—is not a class of entries but rather a set of specificentries that are members of a group or retrieved by a specific filter. The delegation rules allow targetedmanagement of specific user entries.

In each case, the access control rule resolves the constituents of the FreeIPA access controlexpression: "Who can do What to Whom". The following section explains these constituents in moredetail.

13.1.1.1.1. The FreeIPA Access Control Expression

The "Who" of Access ControlIn simple grammatical terms, the "who" of a FreeIPA access control instruction (ACI), or expression, isthe subject. It specifies the entity that interacts with the system and tries to perform an administrative

Server-side Access Control

117

task. This task could be an administrator adding a user, a user changing his home address, or a hostrequesting a certificate for a service running on the host.

It is important to understand that the "who" is not necessarily a person; it can be any entity that hassuccessfully authenticated against FreeIPA. In order to authenticate against the FreeIPA server, thisentity, the "who", needs to have a Kerberos principal. After the entity has authenticated, it can connectto the FreeIPA server and try to issue administrative commands. The system will either allow or denythe requested operation based on this entity's permissions.

The "What" of Access ControlTo continue the analogy with grammatical terms, the "what" of a FreeIPA ACI is the verb. Thisspecifies the actual administrative operation that the subject, the "who", is trying to perform. Suchoperations can target actual entries, such as adding or deleting users, or they can target specificattributes of entries, such as changing phone numbers for a user entry, or changing the memberattributes of a group entry.

Most entry attributes are optional, and the operations against attributes can be any of the following:• Add — allows the creation of a new attribute, or new values for multi-valued attributes.

• Delete — allows the removal of an attribute.

• Read — makes attributes accessible.

• Write — allows modification of existing attributes.

The "Whom" of Access ControlThe "whom" of a FreeIPA ACI is the object, or target, upon which the ACI acts. Targets can beexpressed in different ways:• As a class of entries, for example: user; group; host.

• As a location in a specific part of the directory tree, for example: everything under cn=accounts.

• As a specific attribute potentially used in many types of entries, for example: the cn attribute.

• As a specific entry, for example: fqdn=mycomp.mywork.com.

• As a set of entries selected by filter, for example: cn="filter".

13.1.1.1.2. 389 Directory Server ACIs and FreeIPA Access Control TypesThe following table summarizes the relationship between the different 389 Directory Server ACIcomponents and the FreeIPA access control types.

Table 13.1. Mapping 389 Directory Server and FreeIPA Access Control Types

Type of AccessControl

Target Permission Bind Rule

Role-based An entry as a whole(for add and delete), ora set of attributes of anentry.

Write, Add, or Delete.Read is implied.

Taskgroup.

(A taskgroup is aspecial internal entrydeveloped as part ofFreeIPA to constructthe access controlhierarchy. A taskgroupis a "container" that is


118

Type of AccessControl

Target Permission Bind Rule

granted permission toperform specific tasks.)

Self-service Attributes within theentity's own entry.

Write permission forspecific attributes. Allattributes are readableunless globally hidden.

The entity whoauthenticated.

Delegation A group of users or aset of entries selectedby a filter.

Write, Add, or Delete.Read is implied.

A group of users,usually a group ofadministrative users.

13.1.2. Creating Roles1. Add the new role:

# ipa role-add --desc="User Administrator" useradmin ------------------------ Added role "useradmin" ------------------------ Role name: useradmin Description: User Administrator

2. Add the required privileges to the role:

# ipa role-add-privilege --privileges="User Administrators" useradmin Role name: useradmin Description: User Administrator Privileges: user administrators ---------------------------- Number of privileges added 1----------------------------

3. Add the required groups to the role. In this case, we are adding only a single group, useradmin,which already exists.

# ipa role-add-member --groups=useradmins useradmin Role name: useradmin Description: User Administrator Member groups: useradmins Privileges: user administrators ------------------------- Number of members added 1-------------------------

The result of this procedure is that any user in the useradmins group can add, modify, and removeusers, change user passwords, add users to the default group, and unlock user accounts. You can usethe ipa privilege-show command to determine exactly which command set the user or group canaccess:

# ipa privilege-show 'user administrators' Privilege name: User Administrators Description: User Administrators Permissions: add users, change a user password, add user to default group, unlock user accounts, remove users, modify users

Defining Self-Service Settings

119

Granting privilege to roles: useradmin

As the needs of your enterprise change, you may need to modify the roles that you have established.For example, you may need to change the members of the role, or change the privileges associatedwith the role. You can use the ipa role-* commands to perform these functions. For example, toremove an existing privilege from a role, use the ipa role-remove-privilege command. Toremove members from a role, use the ipa role-remove-member command. Refer to the iparole help pages for more information.

You can use the ipa role-del command to delete FreeIPA roles from your configuration. Bearin mind, however, that any entities that rely on this role for access to FreeIPA objects or to performcertain tasks will no longer have that ability.

13.1.3. Defining Self-Service SettingsSelf-service access control rules define the operations that an entity can perform on itself. These rulesare attribute based; that is, they define what attributes can be modified for any particular entity. Youcan create self-service rules so that users can manage their own addresses, keep their contact detailscurrent, change their passwords, etc.

Self-service rules are defined and managed by a number of sub-commands. Use the ipa helpselfservice command to display the list of available commands.

The following example demonstrates how to add a new self-service rule that allows users to maintaintheir own name details. Note that access control rules whose names contain spaces or other specialcharacters need to be quoted.

$ ipa selfservice-add "Users can manage their own name details" --permissions=write --attrs=givenname,displayname,title,initials-----------------------------------------------------------Added selfservice "Users can manage their own name details"----------------------------------------------------------- Self-service name: Users can manage their own name details Permissions: write Attributes: givenname, displayname, title, initials

You can use the ipa selfservice-show command to display the newly-created rule.

You can use the ipa selfservice-mod command to manage your self-service rules. For example,you can add or remove various attributes from any of the defined rules, or change the permissions.For example, you can add telephone contact details to the rule we created in the previous example:

$ ipa selfservice-mod "Users can manage their own name details" --attrs=givenname,displayname,title,initials,homephone,mobile,telephonenumber--------------------------------------------------------------Modified selfservice "Users can manage their own name details"--------------------------------------------------------------Self-service name: Users can manage their own name detailsPermissions: writeAttributes: givenname, displayname, title, initials, homephone, mobile, telephonenumber

Important

You need to include all of the required attributes when you modify a self-service rule, includingexisting ones.


120

13.2. Disabling Anonymous BindsEven though the XML-RPC and WebUI always require authentication, the default FreeIPAconfiguration allows anonymous binds to the LDAP port by anyone in the same domain as the FreeIPAserver, and consequent retrieval of a range of data, including user, group, netgroup, host, host group,and service records. This is generally considered insecure, and some RFC standards require that itbe disabled to achieve compliance. With anonymous binds disabled, all connections to the directoryserver need to provide a valid identity.

To disable anonymous binds, perform this LDAP modification:

# ldapmodify -x -D "cn=Directory Manager" -WEnter LDAP Password:dn: cn=configchangetype: modifyreplace: nsslapd-allow-anonymous-accessnsslapd-allow-anonymous-access: off

# service dirsrv restart

13.3. Managing Unique UID and GID Number AssignmentsA FreeIPA server must generate random UID and GID values and simultaneously ensure that replicasnever generate the same UID or GID value. The need for unique UID and GID numbers might evencross FreeIPA domains, if a single organization has multiple disparate domains.

The UID and GID numbers are divided into ranges. By keeping separate numeric ranges for individualservers and replicas, the chances are minimal that any numbers issued by one server or replicawill duplicate those from another. Ranges are updated and shared intelligently between serversand replicas through the Dynamic Numeric Assignment (DNA) Plug-in, as part of the backend 389Directory Server instance for the domain. The same range is used for user IDs (uidNumber) andgroup IDs (gidNumber). A user and a group may have the same ID, but since the ID is set in differentattributes, there is no conflict. Using the same ID number for both a user and a group also allows anadministrator to configure user private groups, where a unique system group is created for each userand the ID number is the same for both the user and the group.

IMPORTANT

When a user is created interactively or without specifying a UID or GID number, then the useraccount is created with an ID number that is next available in the server or replica range. Thismeans that a user always has a unique number for its UID number and, if configured, for itsprivate group.

If a number is manually assigned to a user entry, the server does not validate that theuidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behaviorfor Posix entries. The same is true for group entries: a duplicate gidNumber can be manuallyassigned to the entry.

If two entries are assigned the same ID number, only the first entry is returned in a search forthat ID number. However, both entries will be returned in searches for other attributes or with ipauser-find --all.

About ID Range Assignments During Installation

121

13.3.1. About ID Range Assignments During InstallationThe FreeIPA administrator can initially define a range during server installation, using the --idstartand --idmax options with ipa-server-install. These options are not required, so the setupscript can assign random ranges during installation.

If no range is set manually when the first FreeIPA server is installed, a range of 200,000 IDs israndomly selected. There are 10,000 possible ranges. Selecting a random range from that numberprovides a high probability of non-conflicting IDs if two separate FreeIPA domains are ever merged inthe future.

With a single FreeIPA server, IDs are assigned to entries in order through the range. With replicas, theinitial server ID range is split and distributed.

When a replica is installed, it is configured with an invalid range. It also has a directory entry (that isshared among replicas) that instructs the replica where it can request a valid range. When the replicastarts, or as its current range is depleted so that less than 100 IDs are available, it can contact one ofthe available servers for a new range allotment. A special extended operation splits the range in two,so that the original server and the replica each have half of the available range.

13.3.2. Adding New RangesIf the range for the entire domain is close to depletion, a new range can be manually selectedand assigned to one of the master servers. All replicas then request ID ranges from the master asnecessary.

The changes to the range are done by editing the 389 Directory Server configuration to change theDNA Plug-in instance. The range is defined in the dnaNextRange parameter. For example:

ldapmodify -x -D "cn=Directory Manager" -W -h server.example.com -p 389Enter LDAP Password: *******dn: cn=Posix IDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=configchangetype: modifyadd: dnaNextRangednaNextRange: 123400000-123500000

NOTE

This command only adds the specified range of values; it does not check that the values in thatrange are actually available. This check is performed when an attempt is made to allocate thosevalues. If a range is added that contains mostly values that were already allocated, the systemwill cycle through the entire range searching for unallocated values, and then the operationultimately fails if none are available.

13.4. Configuring Certificates and Certificate AuthoritiesFreeIPA creates a self-signed Certificate Authority (CA) during the installation process. If you haveyour own or a preferred CA, however, and want to use your own certificates, FreeIPA provides thenecessary tools to import certificates for use by 389 Directory Server and the HTTP server. While nota prerequisite for the correct operation of FreeIPA, it is recommended that you save an ASCII copy ofyour CA certificate as /usr/share/ipa/html/ca.crt to ensure that users download the correctcertificate.


122

13.4.1. Installing Your Own CertificateUse the ipa-server-certinstall command to install your own certificate. You can install thecertificate for use by 389 Directory Server, HTTP Server, or both.

# /usr/sbin/ipa-server-certinstall -d /path/to/pkcs12.p12

13.4.2. Using Your Own Certificate with FirefoxTo continue using the Firefox auto-configuration feature, you need an object-signing certificate, andyou need to regenerate the /usr/share/ipa/html/configure.jar file.

To use your own certificate with Firefox:1. Create a suitable directory and then create the new certificate database in that directory.

# mkdir /tmp/signdb# certutil -N -d /tmp/signdb

2. Import the PKCS #12 file for the signing certificate into that same directory.

# pk12util -i /path/to/pkcs12.p12 -d /tmp/signdb

3. Make a temporary signing directory, and copy the FreeIPA javascript file to that directory.

# mkdir /tmp/sign# cp /usr/share/ipa/html/preferences.html /tmp/sign

4. Use the certificate you created earlier to sign the javascript file and to regenerate theconfigure.jar file.

# signtool -d /tmp/signdb -k Signing_cert_nickname -Z /usr/share/ipa/html/configure.jar -e .html

13.4.3. Using OCSPThe Online Certificate Status Protocol (OCSP) is natively provided by the CA embedded into FreeIPA.This is so that any client that supports it can use OCSP for certificate validity checks.

The OCSP responder URL is encoded into the certificates issued by FreeIPA. In order for thatresponder to be available, port 9180 needs to be open in the firewall. The OCSP URL uses thefollowing format:

http://ipa.example.com:9180/ca/ocsp

For more information on OCSP, refer to the RFC at http://www.ietf.org/rfc/rfc2560.txt.

13.5. Setting a FreeIPA Server as an Apache Virtual HostIf you have a standard Apache instance running on port 80, you can configure FreeIPA to run on asecondary port, for example, on port 8089. You should be aware, however, that in this configuration,FreeIPA does not use SSL; all requests will use standard HTTP.

The following procedure assumes that FreeIPA is configured to run on port 80, and that you want tomove it to port 8089.

http://www.ietf.org/rfc/rfc2560.txt

Using FreeIPA in a Cluster

123

To configure FreeIPA to run on port 8089:1. Log in as the root user.

2. Edit the /etc/httpd/conf.d/ipa.conf file. Add the following three lines to the beginning ofthe file:

Listen 8089NameVirtualHost *:8089<VirtualHost *:8089>

3. Add the following line to the end of the file:

</VirtualHost>

This wraps the entire FreeIPA configuration in a virtual host, and ensures that Apache is listeningto that port.

Note

You cannot use port 8080. This port is used by the ipa_webgui service.

4. Comment out the following rewrite rules from the /etc/httpd/conf.d/ipa.conf file:

----------------------------------------------------------------------# Redirect to the fully-qualified hostname. Not redirecting to secure# port so configuration files can be retrieved without requiring SSL.RewriteCond %{HTTP_HOST} !^host.foo.com$ [NC]RewriteRule ^/(.*) http://host.foo.com/$1 [L,R=301]

# Redirect to the secure port if not displaying an error or retrieving# configuration.RewriteCond %{SERVER_PORT} !^443$RewriteCond %{REQUEST_URI} !^/(errors|config|favicon.ico)RewriteRule ^/(.*) https://host.foo.com/$1 [L,R=301,NC]---------------------------------------------------------------------

5. Reload the httpd service.

# service httpd reload

This configures FreeIPA to run on port 8089, leaving port 80 free for your normal web site.

13.6. Using FreeIPA in a ClusterThe FreeIPA server currently does not specifically handle the case of a service running in a cluster.That is, the FreeIPA server is not cluster aware. It is possible to configure a clustered service to bepart of FreeIPA, although a certain amount of manual configuration is required. This involves sharingand synchronizing Kerberos keys across all of the participating hosts, and also configuring servicesrunning on the hosts to respond to whatever names the clients want to use.


124

13.6.1. Configuring Kerberos Credentials for a ClusteredEnvironmentUse the following procedure to set up the Kerberos credentials for an environment where yourmanaged host is a cluster of nodes.

Configuring Kerberos Credentials for a Clustered Environment1. Enroll all of the hosts in the FreeIPA domain, and collect any keytabs that have been set up. At a

minimum, this is /etc/krb5.keytab, although additional services may have their keys in otherfiles.

2. Use the ktutil command to produce a single keytab file that contains the contents of all of thekeytab files.

a. For each file, use the rkt command to read the keys from that file.

b. Use the wkt command to write all of the keys which have been read to a new keytab file.

3. Replace the keytab files on each host with the newly-created keytab file.

Each host in this cluster should now be able to impersonate any other host.

13.6.1.1. Service-specific ConfigurationAdditional service-specific configuration may be required if cluster members do not reset theirhostnames when they take over for a failed service.• For sshd, set GSSAPIStrictAcceptorCheck no in /etc/ssh/sshd_config

• For mod_auth_kerb, set KrbServiceName Any in /etc/httpd/conf.d/auth_kerb.conf

13.6.1.2. SSL Server ConfigurationFor SSL servers, it is important that the subject name or a subjectAlternativeName value forthe server's certificate look correct when a client connects to the clustered item. The simplest way todo this is to keep the private key and certificate synchronized across all of the hosts, but it is betterto share the private key if possible. Ensuring that certificates issued to each cluster member containsubjectAlternativeName values naming all of the cluster members should satisfy any clientconnection requirements.

13.6.2. Using the Same Service Principal for Multiple ServicesOne aspect of applying FreeIPA in a cluster use case is using the same service principal for multipleservices, spread across different machines. This is a simple procedure and could be implemented asfollows:1. Retrieve a service principal in the normal way, using the ipa-getkeytab command, or use the

keytab that is set up when the host joins the realm. That is, by using ipa-join, which creates orupdates the /etc/krb5.keytab file with a host/principal.

2. When you have the principal in a keytab on the system, you can direct multiple servers or servicesto use the same file, or you can copy the file to discrete locations as required.

13.7. FreeIPA Server LoggingIf you are using the FreeIPA command-line tools or the WebUI to manage FreeIPA data then youshould refer to the following sections to help troubleshoot any problems.

Promoting a Read-Only Replica to a FreeIPA Server

125

You should first check the /var/log/httpd/error_log file. This may contain more information onthe error and/or a python stacktrace.

To see the LDAP queries that are being made by the framework you can inspect the /var/log/dirsrv/slapd-INSTANCE/access file. Note that this file is buffered and so it only writes to diskabout every 30 seconds.

Increasing Server Debugging OutputTo increase the server debugging output you can create the /etc/ipa/server.conf file andinclude the following entry:

[global]debug=True

You need to restart the httpd daemon for this change to take effect.

Increasing Client Debugging OutputYou can increase debugging output on the client with the -v global option:

$ ipa -v user-show admin

You can use the -v option twice to display the XML-RPC exchange:

$ ipa -vv user-show admin

13.8. Promoting a Read-Only Replica to a FreeIPA ServerThe only difference between a replica and the master server is that the master owns the self-signedCA. If you copy the appropriate files from the master to the replica, import the CA into the replicadirectory server, and delete the existing replication agreements, that replica will then appear as amaster server.

Note

If you install with the --selfsign option, follow this procedure if you want to promote a replicato a master. This is because the private key for the self-signed CA is stored in the Apachedatabase (/etc/httpd/alias). The private key for a Dogtag Certificate System CA is stored inits own security database.

To promote a replica to a master server:1. Copy the /var/lib/ipa/ca_serialno file from the master to the replica.

2. Import the CA into the replica 389 Directory Server NSS database, as follows:

# cd /etc/dirsrv/slapd-REALM# pk12util -i /path/to/cacert.p12 -d .

The password on the PKCS#12 file is stored as /etc/dirsrv/slapd-REALM/pwdfile.txt onthe original server.

3. Delete the existing replication agreements, as follows:


126

# ipa-replica-manage del master.example.com

You now have two identical FreeIPA servers, neither of which know about the other. You can shutdown the old master and bring up the new machine (if you are introducing a new replica into yournetwork). Create a replica file on the new master and install it on the new machine.

13.9. Testing Before Upgrading the FreeIPA ServerIt can be beneficial, and safer, to test newer versions of FreeIPA before upgrading production systems.There is a relatively simple way to do this, by creating a sacrifical replica (which is a read-write server)and testing on that system.

1. Set up a replica based on one of the production servers, with the same version of FreeIPA asis running in production, as described in Section 1.4, “Setting up FreeIPA Replicas”. For thisexample, this is called Test Replica. Make sure that Test Replica can successfully connect to theproduction server and domain.

2. After verifying that Test Replica has been successfully added to the production domain,disconnect Test Replica from the network.

3. Remove the replication agreements for Test Replica from the original FreeIPA server and fromTest Replica.

4. Reconnect Test Replica to the network.

5. Upgrade the packages on Test Replica using yum or whatever tools are appropriate. For example:

# yum update freeipa*

6. Test common things on Test Replica, like getting Kerberos credentials, opening the server UI, andrunning commands.

If the update affects the ds-replication package or features which are used for replication betweenservers and replicas, then create two test replicas which communicate with each other (such as, makea test replica off a production server and then a replica off the test replica). Make sure that the tworeplicas can communicate with each other before and after updating the FreeIPA packages.

Chapter 14.

127

Managing Client Machines in theFreeIPA DomainBoth DNS and Kerberos are configured as part of the initial client configuration. This is requiredbecause these are the two services that bring the machine within the FreeIPA domain and allow itto identity the FreeIPA server it will connect with. After the initial configuration, FreeIPA has tools tomanage both of these services in response to changes in the domain services, changes to the ITenvironment, or changes on the machines themselves which affect Kerberos, certificate, and DNSservices, like changing the client hostname.

This chapter describes how to manage identity services that relate directly the the client machine:

• DNS entries and settings

• Machine authentication

• Hostname changes (which affect domain services)

14.1. About Machine Identity and AuthenticationA FreeIPA domain establishes a commonality between machines, with common identity information,common policies, and shared services. Any machine which belongs to a domain functions as a clientof the domain, which means it uses the services that the domain provides. A FreeIPA domain providesthree main services specifically for machines:

• DNS

• Kerberos

• Certificate management

Machines are treated as another identity that is managed by FreeIPA. Clients use DNS to identifyFreeIPA servers, services, and domain members — which, like user identities are stored in the 389Directory Server instance for the FreeIPA server. Like users, machines can authenticated to thedomain using Kerberos or certificates to verify the machine's identity.

From the machine perspective, there are several tasks that can be performed that access thesedomain services:

• Joining the DNS domain (machine enrollment)

• Managing DNS entries and zones

• Managing machine authentication

Authentication in FreeIPA includes machines as well as users. Machine authentication is required forthe FreeIPA server to trust the machine and to accept FreeIPA connections from the client softwareinstalled on that machine. After authenticating the client, the FreeIPA server can respond to itsrequests. FreeIPA supports two different approaches to machine authentication:

• Key tables (or keytabs, a symmetric key resembling to some extent a user password) and machinecertificates. Kerberos tickets are generated as part of the Kerberos services and policies definedby the server. Initially granting a Kerberos ticket, renewing the Kerberos credentials, and evendestroying the Kerberos session are all handled by the FreeIPA services. Managing Kerberos iscovered in Chapter 6, Identity: Using FreeIPA for a Kerberos Domain.

Chapter 14. Managing Client Machines in the FreeIPA Domain

128

• Machine certificates. In this case, the machine uses an SSL certificate that is issued by the FreeIPAserver's certificate authority and then stored in FreeIPA's Directory Server. The certificate is thensent to the machine to present when it authenticates to the server. On the client, certificatesare managed by a service called certmonger, which is described in Section 14.6, “Working withcertmonger”.

14.2. Enrolling Clients ManuallyEnrolling machines as clients in the FreeIPA domain is a two-part process. A host entry is created forthe client (and stored in the 389 Directory Server isntance), and then a keytab is created to provisionthe client.

Both parts are performed automatically by the ipa-client-install command. It also also possibleto perform those steps separately; this allows for administrators to prepare machines and FreeIPA inadvance of actually configuring the clients. This allows more flexible setup scenarios, including bulkdeployments.

When performing a manual enrollment, the host entry is created separately, and then enrollment iscompleted when the client script is run, which creates the requisite keytab.

NOTE

There are two ways to set the password. You can either supply your own or have FreeIPAgenerate a random one.

14.2.1. Performing a Split EnrollmentThere may be a situation where an administrator in one group is prohibited from creating a host entryand, therefore, from simply running the ipa-client-install command and allowing it to createthe host. However, that administrator may have the right to run the command after a host entry exists.In that case, one administrator can create the host entry manually, then the second administrator cancomplete the enrollment by running the ipa-client-install command.

1. An administrator creates the host entry, as described in Section 5.2, “Adding Host Entries”.

2. The second administrator installs the FreeIPA client packages on the machine, as in Section 2.2,“Configuring a Fedora System as a FreeIPA Client”.

3. When the second administrator runs the setup script, he must pass his Kerberos password andusername (principal) with the ipa-client-install command. For example:

$ ipa-client-install -w secret -p admin2

4. The keytab is generated on the server and provisioned to the client machine, so that the clientmachine is not able to connect to the FreeIPA domain. The keytab is saved with root:rootownership and 0600 permissions.

14.2.2. Performing a Bulk or Kickstart EnrollmentTwo variations of a split enrollment are a bulk enrollment and a kickstart enrollment. Combined, thatallows automatic provisioning of multiple hosts or virtual machines. This requires pre-creating thehosts on the FreeIPA server, with a predefined password that can be used to authenticate to completethe enrollment operation.

Renaming Machines and Reconfiguring FreeIPA Client Configuration

129

1. An administrator creates the host entry, as described in Section 5.2, “Adding Host Entries”. Set apassword to use for the bulk or automatic enrollment. For example:

$ ipa host-add bulkserver.example.com --password=secret

The password is set to expire after the first authentication attempt. After enrollment completes, thepassword expires and the host is authenticated using its keytab.

2. Run the kickstart script, using the given bulk password. The kickstart script performs all of thetasks performed manually by the second administrator in Section 14.2.1, “Performing a SplitEnrollment”:

• Kickstart installs the FreeIPA packages.

• Kickstart runs the enrollment script, passing in the password.

• The enrollment script connects to the FreeIPA server using the provided password and a bindDN derived from the machine name. It then authenticates using a simple bind over SSL.

14.3. Renaming Machines and Reconfiguring FreeIPA ClientConfigurationThe hostname of a system is critical for the correct operation of Kerberos and SSL. Both of thesesecurity mechanisms rely on the hostname to ensure that communication is occurring between thespecified hosts. Infrastructures which use virtual machines or clusterd servers will commonly havehosts which are renamed because systems are copied, moved, or renamed.

Fedora does not provide a simple rename command to facilitate the renaming of a FreeIPA host.Renaming a host in a FreeIPA domain involves deleting the entry in FreeIPA, uninstalling the clientsoftware, changing the hostname, and re-enrolling using the new name. Additionally, part of renaminghosts requires regenerating service principals.

To reconfigure the client:

1. Identify which services are running on the machine. These need to be re-created when themachine is re-enrolled.

# ipa service-find server.example.com

Each host has a default service which does not appear in the list of services. This service can bereferred to as the "host service". The service principal for the host service is host/<hostname>,such as host/server.example.com. This principal can also be referred to as the hostprincipal.

2. Identify all host groups to which the machine belongs.

# ipa hostgroup-find server.example.com

Identify which of the services have certificates associated with them.

The host service always has an associated certificate.

3. For any service principals (in addition to the host principal), determine the location of thecorresponding keytabs on server.example.com. The keytab location is different for eachservice, and FreeIPA does not store this information.


130

Each service on the client system has a Kerberos principal in the form service name/hostname@REALM, such as ldap/[email protected].

4. Unenroll the client machine from the FreeIPA domain:

# ipa-client-install --uninstall

5. For each identified keytab other than /etc/krb5.keytab, remove the old principals:

# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM

6. On another FreeIPA machine, as a FreeIPA administrator, remove the host entry. This removes allservices and revokes all certificates issued for that host:

# ipa host-del server.example.com

At this point, the host is completely removed from FreeIPA.

7. Rename the machine.

8. Re-enroll the system with FreeIPA:

# ipa-client-install

This generates a host principal for with the new hostname in /etc/krb5.keytab.

9. For every service that needs a new keytab, run the following command:

# ipa service-add serviceName/new-hostname

10. To generate certificates for services, use either certmonger or the FreeIPA administration tools.

11. Re-add the host to any applicable host groups.

14.4. Manually Unconfiguring Client MachinesA machine may need to be removed from one FreeIPA domain and moved to another domain or avirtual machine may be copied. There are a number of different situations where a FreeIPA clientneeds to be reconfigured. The easiest solution is to uninstall the client and then configure it afresh.

ipa-client-install --uninstall

If it is not possible to uninstall the client directly, then the FreeIPA configuration can be manuallyremoved from the virtual machine.

WARNING

When a machine is unenrolled, the procedure cannot be undone. The machine can only beenrolled again.

Debugging Client Connection Problems

131

1. Remove the old hostname from the main keytab. This can be done by removing every principal inthe realm or by removing specific principals. For example, to remove all principals:

$ ipa-rmkeytab -k /etc/krb5.keytab -r EXAMPLE.COM

To remove specific principals:

$ ipa-rmkeytab -k /etc/krb5.keytab -p host/[email protected]

2. Disable tracking in certmonger for every certificate. Each certificate must be removed fromtracking individually.

$ ipa-getcert stop-tracking -n Server-Cert -d /etc/pki/nssdb $ ipa-getcert stop-tracking -n Server2-Cert -d /etc/pki/nssdb

3. Remove the old host from the FreeIPA DNS domain. While this is optional, it cleans up the oldFreeIPA entries associated with the system and allows it to be re-enrolled cleanly at a later time.

$ ipa host-del server.example.com

4. If the system should be re-added to a new FreeIPA domain — such as a virtual machine whichwas moved from one location to another — then the system can be rejoined to FreeIPA using theipa-join command.

$ ipa-join

14.5. Debugging Client Connection ProblemsClient connection problems are apparent immediately. This can mean that users cannot log intoa machine or attempts to access user and group information fails (for example, getent passwdadmin).

Authentication in FreeIPA is managed with the SSSD daemon, which is described in the Red HatEnterprise Linux Deployment Guide. If there are problems with client authentication, then check theSSSD information.

First, check the SSSD logs in /var/log/sssd/. There is a specific log file for the DNS domain, suchas sssd_example.com.log. If there is not enough information in the logs at the default logginglevel, then increase the log level.

To increase the log level:

1. Open the sssd.conf file.

vim /etc/sssd/sssd.conf

2. In the [domain/example.com] section, set debug_level.

debug_level = 9

3. Restart the sssd daemon.


132

service sssd restart

4. Check the /var/log/sssd/sssd_example.com.log file for the debug messages.

14.6. Working with certmongerPart of managing machine authentication is managing machine certificates. The FreeIPA servercan handle this through an internal certificate authority. On clients, FreeIPA manages the certificatelifecycle with the certmonger service.

The certmonger daemon, and its command-line clients, simplifies the process of generating public/private key pairs, creating certificate reqests, and submitting requests to a CA for signing. As part ofmanaging certificates, the certmonger daemon monitors certificates for expiration and can renewcertificates that are about to expire. The certificates that certmonger monitors is tracked in filesstored in a configurable directory. The default location is /var/lib/certmonger/requests.

certmonger uses the getcert command to manage all certificates, but there are essentiallycontainer commands that perform the certificate management tasks depending on the certificateauthority type — the FreeIPA CA or self-signed. The command line tool used has different prefixes toidentify the different CA types:

• ipa-getcert

• selfsign-getcert

NOTE

Because of general security issues, self-signed certificates are not typically used in production,but can be used for development and testing.

14.6.1. Requesting a Certificate with certmongerWith the FreeIPA CA, certmonger uses the ipa-getcert command.

Example 14.1. Using certmonger with FreeIPA

ipa-getcert request -r -f /etc/httpd/conf/ssl.crt/server.crt -k /etc/httpd/conf/ssl.key/server.key -N CN=`hostname --fqdn` -D `hostname` -U id-kp-serverAuth

The options vary depending on whether you are using a self-signed certificate (selfsign-getcert),the desired configuration for the final certificate, and other settings. In Example 14.1, “Usingcertmonger with FreeIPA”, these are common options to use:

• The -r option will automatically renew the certificate if the keypair already exists. This is used bydefault.

• The -f option stores the certificate in the given file.

• The -k option either stores the key in the given file or, if the key file already exists, uses the key inthe file.

• The -N option gives the subject name.

Storing Certificates in NSS Databases

133

• The -D option gives the DNS domain name.

• The -U option sets the extended key usage flag.

14.6.2. Storing Certificates in NSS DatabasesBy default, certmonger uses plaintext files to store the key and the certificate, but these keys andcertificates can also be stored in NSS databases. This is done using the -d option to set the securitydatabase location and -n to give the certificate nickname which is used for the certificate in thedatabase. These options are used instead of the PEM files given in the -f and -k options.

For example:

# ipa-getcert request -d /export/alias -n ServerCert ...

14.6.3. Tracking Certificates with certmongercertmonger can manage the entire certificate lifecycle. Along with generating requests,certmonger can track a certificate and automatically renew it when it expires, at the end of its validityperiod.

This is done using the start-tracking command with the getcert command. The -I optioncreates the tracking entry, and then there are pointers to the key and certificate files, either in NSSdatabases (-d and -n) or in the PEM files (-f and -k). The -r option tells certmonger to renew thecertificate.

# ipa-getcert start-tracking -I cert1-tracker -d /export/alias -n ServerCert -r

TIP

The -r option can be passed with the request command, in Example 14.1, “Using certmongerwith FreeIPA”. In that case, the requested certificate is automatically tracked and renewed bycertmonger. Then, it is not necessary to configure tracking manually.

A certificate can be untracked by certmonger by using the stop-tracking command.

134

135

Appendix A. Frequently AskedQuestionsQ: Is it possible to change the IP address of the master server?

A: Yes. If you are only changing the IP address then it is sufficient to update the /etc/hosts file,the system configuration and the DNS entry.

Q: Why are there restrictions on the length of user and group names? How can I change this?

A: User and group name lengths are specified in the policy. The default maximum username lengthis 32 characters. The maximum configurable length for user or group names is 255 characters.This restriction was introduced because some non-Linux operating systems have limitations onthe length of username that they can support.

You can modify these settings either in the user interface or on the command line. For example,to specify the maximum username length, run the following command: ipa config-mod --maxusername=INT

Q: What is the difference between a replica and a master server?

A: The only difference between a replica and the initial IPA install (the "master") is that the firstserver owns the self-signed CA.

Q: Can I promote a replica to function as the master? How?

A: Yes. Refer to Section 13.8, “Promoting a Read-Only Replica to a FreeIPA Server”.

Q: Why does the ipa-client-install script fail to find the IPA server on a network that usesActive Directory DNS?

A: This is probably due to the fact that Active Directory has its own SRV records for Kerberos andLDAP, and so the ipa-client-install script retrieves those records instead of any that youmay have added for IPA.

Q: Can an administrator who is connected to "Server B" revoke a certificate issued by "Server A"?

A: Yes, assuming that Servers A and B contain non-cloned CAs whose portion of internal storagehas been replicated to share revocation information only.

136

137

Appendix B. Migrating from a DirectoryServer to IPA

B.1. OverviewThis appendix addresses the situation where a customer has previously deployed an internal DirectoryServer (DS) and is planning to use IPA instead. The customer needs to transfer all user data fromthe DS to IPA so that IPA can function fully and correctly. The goal is to perform this migration withoutrequiring that users change their passwords or perform some other specific action.

B.1.1. AssumptionsIt is not practical to identify and address each of the scenarios in which a DS and IPA might bedeployed, and where migration might be required. Consequently, the following assumptions are made:

• This is a one-to-one transition from one DS realm to one IPA realm. No consolidation is involved.

• User passwords are stored as a hash in the source DS in a form that the IPA DS can understand

• You are using LDAP as the central authentication service, and the client machines are configured touse pam_ldap and nss_ldap

• Some machines might be present that are managed by NIS or are not part of the DS deployment,but are planned to be part of the IPA domain

Machines that cannot be moved from the NIS domain to LDAP or IPA because they are old and donot support nss_ldap are assumed to remain in and be served by the NIS domain. The migrationof such machines to the IPA domain, while possible, is a challenging task and is out of the scope ofthe current use case.

B.1.2. Known IssuesA number of issues exist that need to be considered when planning the migration:

• A generic DS uses a different schema and Directory Information Tree (DIT) when compared to IPA.No known DS uses the same flat DIT structure that IPA uses. IPA is optimized for performance, andattempts to avoid any architectural design flaws that have occurred in the past.

• IPA uses Kerberos for authentication, and so each user requires that Kerberos keys be stored in theIPA DS, in addition to the standard LDAP hashes used by the DS

In order to generate these keys, the password needs to be available in clear text to IPA's DSpassword plug-in. It is available when the user is created in IPA using IPA tools or LDAP, butthis is not the case when the user is migrated from other external storage such as another DS.Consequently, the existing password hashes can be reloaded, but the Kerberos hashes cannot begenerated. IPA provides a number of solutions to overcome this issue; these are described later inthis appendix.

B.1.3. Possible ScenariosThe following have been identified as typical migration scenarios:

• Migrate an existing environment to IPA but do not use its Kerberos features for now

Appendix B. Migrating from a Directory Server to IPA

138

• Migrate an existing environment to IPA and use its Kerberos features using only IPA v1 functionality.That is, do not use SSSD.

• Migrate an existing environment to IPA and use its Kerberos features on some machines, whilesome machines will use SSSD and some will not; this is the primary use case.

B.1.4. Initial and Final StatesThe following sections describe the initial, pre�migration state, and the final, post�migration state of aDS deployment when migrating to a single IPA domain.

B.1.4.1. Initial StateIn the initial state, there is a single data source (the Directory Server) and a single client machineconfiguration. This client configuration uses LDAP to connect to the Directory Server and retrieveinformation about users and groups. This configuration uses PAM_LDAP and NSS_LDAP forauthentication and identity lookups. These modules enable the client systems to use data retrievedfrom the DS just as if it were stored in /etc/passwd or /etc/shadow. The following diagramillustrates this type of implementation, where LDAP is used to connect to the DS for both authenticationand authorization. The case where Kerberos is used for authentication and LDAP for identity, andwhere these two data stores are synchronized, is not described here. Consequently, the initial statemay not be as simple or as straightforward as displayed here, however the approach and the finalstate will be similar.

Figure B.1. Initial state of deployment before migrating to IPA.

B.1.4.2. Final StateIn the final state, even though only a single data source exists, multiple possible machineconfigurations are now possible. This is illustrated in Figure B.2, “Final state of deployment aftermigrating to IPA”

Initial and Final States

139

Figure B.2. Final state of deployment after migrating to IPA

B.1.4.2.1. Configuration Options

Connected to IPA via SSSD Using SSSD's LDAP Back EndClients connect to IPA via SSSD. SSSD is integrated into the PAM and NSS stacks by means ofPAM_SSS and NSS_SSS, respectively. SSSD's LDAP back end is configured for both authenticationand for identity lookups. In this use case, IPA functions like a normal DS.

Note

Kerberos authentication can be configured instead of LDAP authentication. In this case, IPA actsas a normal DS for identity lookups and a normal KDC for Kerberos authentication.

Connected to IPA via SSSD Using IPA's Back EndThis configuration is similar to that described above, except that SSSD has a special back end thatis more IPA-aware. If this back end is configured, then SSSD can take advantage of specific IPAfeatures, such as silent password migration and host-based access control.


140

LDAP-connected MachinesClients connect directly to IPA and use PAM_LDAP and NSS_LDAP. In this use case, too, IPAfunctions like a normal Directory Server.

KRB5/LDAP-connected MachinesClients connect directly to IPA and use PAM_KRB5 and NSS_LDAP. This is the same configuration asthat provided for IPA v1.x

In the initial state, clients use LDAP to communicate with the Directory Server to retrieve informationabout users and groups. PAM_LDAP and NSS_LDAP are modules that enable the client systems to usedata retrieved from the Directory Server as if it were stored in /etc/passwd or /etc/shadow. In thefinal state, IPA provides all of the same functionality and many more features besides.

B.1.5. Recommended Sequence of StepsThe migration from DS to IPA requires:

1. Installing IPA on a suitable machine

2. Migrating the user data. This step is performed by an IPA command which:

a. Dumps the data from DS

b. Converts the data into a format suitable for IPA

c. Loads the converted data into IPA

3. Reconfiguring clients to connect to IPA. This is required because the IPA Directory InformationTree (DIT) is different from the DS DIT.

To achieve a successful migration, changes are required both on the client and on the servermachines. Reconfiguration of the clients is not required immediately after changes are made to theserver. This allows for a transition period, without which it would not be possible to deploy the solution.

At present the only option is to run IPA and DS concurrently until all the clients are reconfigured topoint to IPA. Two main migration strategies currently exist:

• Migrate the server first

• Deploy SSSD first

Each approach is valid and accomplishes the same goal, but using a different sequence of operations.

B.1.5.1. Comparison of Migration StrategiesEach approach has a different impact on the IT team and the users. You need to select the approachthat best suits your deployment. These scenarios can be modified to meet the needs of yourenterprise. Provided you understand the implications and reasoning behind each step, there is norequirement to follow the steps in the given order. It is important to understand that until the Kerberoskeys are generated in IPA, users will not be able to authenticate with Kerberos credentials usingPAM_KRB5 or kinit.

You should also consider an alternative migration scenario, where passwords are not migrated. Inthis scenario, users are not migrated into IPA but rather added as new users with new passwords.Users would then change their password the first time they authenticate. The initial password would bedefined by IT and sent to users by email or communicated in some other way.

Implementation Details

141

Migrating users from an existing system provides a smoother transition but also requires parallelmanagement of DS and IPA during the migration. If you do not preserve passwords, the migration canbe performed more quickly and you can avoid the period of double management of IPA and DS.

B.1.6. Implementation DetailsThe following sequence of operations occurs when users are migrated using SSSD:

• A user tries to log in to the machine.

• SSSD passes authentication to the IPA identity provider back end.

• The IPA identity provider back end attempts Kerberos authentication.

• Even though the user exists in the system, the authentication will fail with the error "key type is notsupported", because the Kerberos keys do not yet exist.

• If SSSD is configured to migrate users, it will continue to the next step. Otherwise, it will failauthentication.

• The IPA identity provider back end then attempts to perform an LDAP bind.• Because it is going to perform a simple bind and send the password in the clear, this LDAP bind

operation must use startTLS.

• Perform a simple bind.

• The server-side plug-in will intercept this bind request and if the user has a Kerberos principal but noKerberos keys, then the plug-in will generate the keys and store them in the user entry.

• If the bind operation fails for any reason, the IPA identity provider back end will fail authentication,otherwise it will continue.

• The IPA identity provider back end will unbind and try Kerberos authentication again. This time it isexpected to succeed because the keys already exist in the entry.

B.2. Performing a Server-based Migration

Note

Each phase of the migration should be performed as a single step.

B.2.1. Phase 1: Migrating Existing Data to IPAThe first phase of the migration consists of setting up IPA and migrating data from the existing DSto that used by IPA. This involves the use of the ipa migrate-ds command, which dumps theuser data from the original DS, converts it into a format suitable for use by IPA, and then loads theconverted data into IPA.

The ipa migrate-ds command connects to the DS and binds as the Directory Manager, andthen extracts all objectClass=person objects from ou=People. This can be changed using the --user-container option. It also extracts all objects from ou=Groups. This can be changed usingthe --group-container option. It adds all object classes and attributes required by IPA (if theyare missing) and coverts DNs in attributes to match the IPA Directory Information Tree (DIT). Thecommand returns an error if migration is not enabled.


142

Refer to the ipa migrate-ds help page for more details about this command (ipa helpmigrate-ds).

Procedure B.1. To migrate existing data to IPA:1. Install IPA, including any custom DS schema, on a different machine from the existing DS. Refer

to

2. Use the following command to enable IPA migration mode:

# ipa config-mod --enable-migration=TRUE

3. To migrate users and groups from an existing Directory Server using a default configuration,reachable at ldap://example.com, use the following command:

# ipa migrate-ds ldap://example.com:389

To migrate users and groups from an existing IPAv1 installation using a default configuration,whose DS is reachable at ldap://example.com, use the following command:

# ipa migrate-ds --user-container=cn=users,cn=accounts \ --group-container=cn=groups,cn=accounts ldap://example.com:389

In this example, ldap://example.com:389 is the LDAP-URI and port number of the existingdirectory server from which you want to migrate your data. Update this URI to suit your ownenvironment.

Enter the Directory Manager password for the DS when prompted.

4. Check the log file for errors and instructions on how to address them.

Note

The migration log file is currently not implemented. Instead, any error messages are printedto standard output.

B.2.2. Phase 2: Updating the Client Configuration

Procedure B.2. To update the client configuration:• Update the client configuration to use PAM_LDAP and NSS_LDAP to connect to IPA instead of

connecting to DS, NIS, or using local files.• If the intention is to automatically generate the Kerberos keys when a user authenticates, the

configuration should use startTLS and simple bind authentication. For this to occur, the ITdepartment needs to ensure the IPA server certificate is copied to the client.

• If the intention is to install SSSD on a client at a later date, the startTLS and certificaterequirements do not apply.

Phase 3: Installing and Configuring SSSD

143

Important

You should not update your client configuration to use PAM_KRB5 and NSS_LDAP (that is, theequivalent of IPA v1) at this stage unless absolutely necessary. This is because the Kerberoskeys will not yet exist in the IPA user entries, and consequently users will not be able to login. If such a configuration is required, users can be directed to a specific web page on the IPAserver after the data has been loaded into the IPA server. This page will prompt the user for theirpassword and perform an LDAP bind. The DS password plug-in will capture these passwordsand generate the Kerberos keys.

B.2.3. Phase 3: Installing and Configuring SSSD

To install and configure SSSD:1. Install SSSD on the machines that can support it:

# yum install sssd

2. Configure SSSD to use IPA as a back end (Kerberos and LDAP). Installing SSSD and enrollingthe client with IPA will ensure delivery of the machine Kerberos key and server certificate to theclient. Refer to

B.2.4. Phase 4: Migrating Users

To migrate the users from DS to IPA:1. Instruct users to log in to IPA using either an SSSD client or a client that supports PAM_LDAP with

startTLS and simple bind. An SSSD client configured as described in Section B.2.3, “Phase 3:Installing and Configuring SSSD” will perform a silent migration. Clients configured with startTLSand simple bind will also trigger key generation. A Kerberos key is created the first time a userlogs in, and this key is stored in the IPA back end.

2. As the migration of the user population progresses (that is, as the Kerberos keys are generated onthe IPA server), you can begin to configure other, non-SSSD clients to suit your requirements.

B.2.5. Phase 5: Decommission the DS• When the migration of all clients and users is complete, decommission the DS.

B.3. Performing a Client-based Migration

B.3.1. Phase 1: Installing and Configuring SSSD• Install SSSD first on the machines that can support it:

# yum install sssd

• Configure SSSD with the LDAP back end and point it to the existing DS deployment.


144

B.3.2. Phase 2: Migrating Existing Data to IPAInstall IPA and migrate the existing DS data as described in Section B.2.1, “Phase 1: MigratingExisting Data to IPA”

B.3.3. Phase 3: Migrate SSSD Clients from LDAP to IPA• Start moving clients that have SSSD installed from the LDAP back end to the IPA back end, and

enroll them with IPA. This will download the required keys and certificates.

• Instruct users to use (that is, to log in at least once) the machines with SSSD and IPA back end, orgo to the web page and authenticate.

• Monitor the user migration process using the following LDAP query. This query detects the stateof the migration by determining which users do not have a Kerberos principal key but do have apassword.

This query will prompt for the Directory Manager password.

$ ldapsearch -LL -x -D 'cn=Directory Manager' -W -b 'cn=users,cn=accounts,dc=example,dc=com' \'(&(!(krbprincipalkey=*))(userpassword=*))' uid

Important

It is important to include the quotes around the filter so that it is not interpreted by the shell.

B.3.4. Phase 4: Reconfigure non-SSSD Clients• As the user population is migrated (the Kerberos keys are generated), you can start reconfiguring

other (non�SSSD) clients as required. The clients can be set up in any state shown on the diagramabove.

B.3.5. Phase 5: Decommission the Directory Server• When the migration of the clients is complete, decommission the DS.

145

GlossaryAaccess control instruction See ACI.

access control list See ACL.

access rights In the context of access control, specify the level of access grantedor denied. Access rights are related to the type of operation that canbe performed on the directory. The following rights can be granted ordenied: read, write, add, delete, search, compare, selfwrite, proxy andall.

account inactivation Disables a user account, group of accounts, or an entire domain sothat all authentication attempts are automatically rejected.

ACI An instruction that grants or denies permissions to entries in thedirectory.

See Also access control instruction.

ACL The mechanism for controlling access to your directory.

See Also access control list.

All IDs Threshold Replaced with the ID list scan limit in Directory Server version 7.1.A size limit which is globally applied to every index key managed bythe server. When the size of an individual ID list reaches this limit, theserver replaces that ID list with an All IDs token.

See Also ID list scan limit.

All IDs token A mechanism which causes the server to assume that all directoryentries match the index key. In effect, the All IDs token causes theserver to behave as if no index was available for the search request.

anonymous access When granted, allows anyone to access directory information withoutproviding credentials, and regardless of the conditions of the bind.

approximate index Allows for efficient approximate or "sounds-like" searches.

attribute Holds descriptive information about an entry. Attributes have a labeland a value. Each attribute also follows a standard syntax for the typeof information that can be stored as the attribute value.

attribute list A list of required and optional attributes for a given entry type orobject class.

authenticating directoryserver

In pass-through authentication (PTA), the authenticating DirectoryServer is the Directory Server that contains the authenticationcredentials of the requesting client. The PTA-enabled host sends PTArequests it receives from clients to the host.

authentication (1) Process of proving the identity of the client user to the DirectoryServer. Users must provide a bind DN and either the corresponding

Glossary

146

password or certificate in order to be granted access to the directory.Directory Server allows the user to perform functions or access filesand directories based on the permissions granted to that user by thedirectory administrator.

(2) Allows a client to make sure they are connected to a secureserver, preventing another computer from impersonating the server orattempting to appear secure when it is not.

authentication certificate Digital file that is not transferable and not forgeable and is issued by athird party. Authentication certificates are sent from server to client orclient to server in order to verify and authenticate the other party.

Bbase distinguished name See base DN.

base DN Base distinguished name. A search operation is performed on thebase DN, the DN of the entry and all entries below it in the directorytree.

bind distinguished name See bind DN.

bind DN Distinguished name used to authenticate to Directory Server whenperforming an operation.

bind rule In the context of access control, the bind rule specifies the credentialsand conditions that a particular user or client must satisfy in order toget access to directory information.

branch entry An entry that represents the top of a subtree in the directory.

browser Software, such as Mozilla Firefox, used to request and view WorldWide Web material stored as HTML files. The browser uses the HTTPprotocol to communicate with the host server.

browsing index Speeds up the display of entries in the Directory Server Console.Browsing indexes can be created on any branch point in the directorytree to improve display performance.

See Also virtual list view index .

CCA See Certificate Authority.

cascading replication In a cascading replication scenario, one server, often called the hubsupplier, acts both as a consumer and a supplier for a particularreplica. It holds a read-only replica and maintains a changelog. Itreceives updates from the supplier server that holds the master copyof the data and in turn supplies those updates to the consumer.

certificate A collection of data that associates the public keys of a network userwith their DN in the directory. The certificate is stored in the directoryas user object attributes.

147

Certificate Authority Company or organization that sells and issues authenticationcertificates. You may purchase an authentication certificate from aCertification Authority that you trust. Also known as a CA.

CGI Common Gateway Interface. An interface for external programs tocommunicate with the HTTP server. Programs written to use CGI arecalled CGI programs or CGI scripts and can be written in many of thecommon programming languages. CGI programs handle forms orperform output parsing that is not done by the server itself.

chaining A method for relaying requests to another server. Results for therequest are collected, compiled, and then returned to the client.

changelog A changelog is a record that describes the modifications that haveoccurred on a replica. The supplier server then replays thesemodifications on the replicas stored on replica servers or on othermasters, in the case of multi-master replication.

character type Distinguishes alphabetic characters from numeric or other charactersand the mapping of upper-case to lower-case letters.

ciphertext Encrypted information that cannot be read by anyone without theproper key to decrypt the information.

class definition Specifies the information needed to create an instance of a particularobject and determines how the object works in relation to otherobjects in the directory.

class of service See CoS.

classic CoS A classic CoS identifies the template entry by both its DN and thevalue of one of the target entry's attributes.

client See LDAP client.

code page An internal table used by a locale in the context of theinternationalization plug-in that the operating system uses to relatekeyboard keys to character font screen displays.

collation order Provides language and cultural-specific information about how thecharacters of a given language are to be sorted. This informationmight include the sequence of letters in the alphabet or how tocompare letters with accents to letters without accents.

consumer Server containing replicated directory trees or subtrees from asupplier server.

consumer server In the context of replication, a server that holds a replica that is copiedfrom a different server is called a consumer for that replica.

CoS A method for sharing attributes between entries in a way that isinvisible to applications.

CoS definition entry Identifies the type of CoS you are using. It is stored as an LDAPsubentry below the branch it affects.

CoS template entry Contains a list of the shared attribute values.

Glossary

148

See Also template entry.

Ddaemon A background process on a Unix machine that is responsible for

a particular system task. Daemon processes do not need humanintervention to continue functioning.

DAP Directory Access Protocol. The ISO X.500 standard protocol thatprovides client access to the directory.

data master The server that is the master source of a particular piece of data.

database link An implementation of chaining. The database link behaves like adatabase but has no persistent storage. Instead, it points to datastored remotely.

default index One of a set of default indexes created per database instance.Default indexes can be modified, although care should be takenbefore removing them, as certain plug-ins may depend on them.

definition entry See CoS definition entry.

Directory Access Protocol See DAP.

Directory Manager The privileged database administrator, comparable to the root user inUNIX. Access control does not apply to the Directory Manager.

directory service A database application designed to manage descriptive, attribute-based information about people and resources within an organization.

directory tree The logical representation of the information stored in the directory. Itmirrors the tree model used by most filesystems, with the tree's rootpoint appearing at the top of the hierarchy. Also known as DIT.

distinguished name String representation of an entry's name and location in an LDAPdirectory.

DIT See directory tree.

DM See Directory Manager.

DN See distinguished name.

DNS Domain Name System. The system used by machines on a networkto associate standard IP addresses (such as 198.93.93.10) withhostnames (such as www.example.com). Machines normally get theIP address for a hostname from a DNS server, or they look it up intables maintained on their systems.

DNS alias A DNS alias is a hostname that the DNS server knows points to adifferent host�specifically a DNS CNAME record. Machines alwayshave one real name, but they can have one or more aliases. Forexample, an alias such as www.yourdomain.domain might point toa real machine called realthing.yourdomain.domain where theserver currently exists.

149

Eentry A group of lines in the LDIF file that contains information about an

object.

entry distribution Method of distributing directory entries across more than one serverin order to scale to support large numbers of entries.

entry ID list Each index that the directory uses is composed of a table of indexkeys and matching entry ID lists. The entry ID list is used by thedirectory to build a list of candidate entries that may match the clientapplication's search request.

equality index Allows you to search efficiently for entries containing a specificattribute value.

Ffile extension The section of a filename after the period or dot (.) that typically

defines the type of file (for example, .GIF and .HTML). In the filenameindex.html the file extension is html.

file type The format of a given file. For example, graphics files are oftensaved in GIF format, while a text file is usually saved as ASCII textformat. File types are usually identified by the file extension (forexample, .GIF or .HTML).

filter A constraint applied to a directory query that restricts the informationreturned.

filtered role Allows you to assign entries to the role depending upon the attributecontained by each entry. You do this by specifying an LDAP filter.Entries that match the filter are said to possess the role.

Ggeneral access When granted, indicates that all authenticated users can access

directory information.

GSS-API Generic Security Services. The generic access protocol that is thenative way for UNIX-based systems to access and authenticateKerberos services; also supports session encryption.

Hhostname A name for a machine in the form machine.domain.dom, which is

translated into an IP address. For example, www.example.com isthe machine www in the subdomain example and com domain.

HTML Hypertext Markup Language. The formatting language used fordocuments on the World Wide Web. HTML files are plain text fileswith formatting codes that tell browsers such as the Mozilla Firefox

Glossary

150

how to display text, position graphics, and form items and to displaylinks to other pages.

HTTP Hypertext Transfer Protocol. The method for exchanging informationbetween HTTP servers and clients.

HTTPD An abbreviation for the HTTP daemon or service, a program thatserves information using the HTTP protocol. The daemon or serviceis often called an httpd.

HTTPS A secure version of HTTP, implemented using the Secure SocketsLayer, SSL.

hub In the context of replication, a server that holds a replica that is copiedfrom a different server, and, in turn, replicates it to a third server.

See Also cascading replication.

IID list scan limit A size limit which is globally applied to any indexed search operation.

When the size of an individual ID list reaches this limit, the serverreplaces that ID list with an all IDs token.

index key Each index that the directory uses is composed of a table of indexkeys and matching entry ID lists.

indirect CoS An indirect CoS identifies the template entry using the value of one ofthe target entry's attributes.

international index Speeds up searches for information in international directories.

International StandardsOrganization

See ISO.

IP address Also Internet Protocol address. A set of numbers, separated by dots,that specifies the actual location of a machine on the Internet (forexample, 198.93.93.10). Directory Server supports both IPv4 andIPv6 IP addresses.

ISO International Standards Organization.

Kknowledge reference Pointers to directory information stored in different databases.

LLDAP Lightweight Directory Access Protocol. Directory service protocol

designed to run over TCP/IP and across multiple platforms.

LDAP client Software used to request and view LDAP entries from an LDAPDirectory Server.

See Also browser.

151

LDAP Data InterchangeFormat

See LDAP Data Interchange Format.

LDAP URL Provides the means of locating Directory Servers using DNS and thencompleting the query via LDAP. A sample LDAP URL is ldap://ldap.example.com.

LDAPv3 Version 3 of the LDAP protocol, upon which Directory Server basesits schema format.

LDBM database A high-performance, disk-based database consisting of a set of largefiles that contain all of the data assigned to it. The primary data storein Directory Server.

LDIF LDAP Data Interchange Format. Format used to represent DirectoryServer entries in text form.

leaf entry An entry under which there are no other entries. A leaf entry cannotbe a branch point in a directory tree.

Lightweight DirectoryAccess Protocol

See LDAP.

locale Identifies the collation order, character type, monetary format andtime / date format used to present data for users of a specific region,culture, and/or custom. This includes information on how data of agiven language is interpreted, stored, or collated. The locale alsoindicates which code page should be used to represent a givenlanguage.

Mmanaged object A standard value which the SNMP agent can access and send to the

NMS. Each managed object is identified with an official name and anumeric identifier expressed in dot-notation.

managed role Allows creation of an explicit enumerated list of members.

management informationbase

See MIB.

mapping tree A data structure that associates the names of suffixes (subtrees) withdatabases.

master See supplier.

master agent See SNMP master agent.

matching rule Provides guidelines for how the server compares strings during asearch operation. In an international search, the matching rule tellsthe server what collation order and operator to use.

MD5 A message digest algorithm by RSA Data Security, Inc., which canbe used to produce a short digest of data that is unique with highprobability and is mathematically extremely hard to produce; a pieceof data that will produce the same message digest.

Glossary

152

MD5 signature A message digest produced by the MD5 algorithm.

MIB Management Information Base. All data, or any portion thereof,associated with the SNMP network. We can think of the MIB asa database which contains the definitions of all SNMP managedobjects. The MIB has a tree-like hierarchy, where the top levelcontains the most general information about the network and lowerlevels deal with specific, separate network areas.

MIB namespace Management Information Base namespace. The means for directorydata to be named and referenced. Also called the directory tree.

monetary format Specifies the monetary symbol used by specific region, whether thesymbol goes before or after its value, and how monetary units arerepresented.

multi-master replication An advanced replication scenario in which two servers each holda copy of the same read-write replica. Each server maintains achangelog for the replica. Modifications made on one server areautomatically replicated to the other server. In case of conflict, atime stamp is used to determine which server holds the most recentversion.

multiplexor The server containing the database link that communicates with theremote server.

Nn + 1 directory problem The problem of managing multiple instances of the same information

in different directories, resulting in increased hardware and personnelcosts.

name collisions Multiple entries with the same distinguished name.

nested role Allows the creation of roles that contain other roles.

network managementapplication

Network Management Station component that graphically displaysinformation about SNMP managed devices, such as which device isup or down and which and how many error messages were received.

network managementstation

See NMS.

NIS Network Information Service. A system of programs and datafiles that Unix machines use to collect, collate, and share specificinformation about machines, users, filesystems, and networkparameters throughout a network of computers.

NMS Powerful workstation with one or more network managementapplications installed. Also network management station.

ns-slapd Red Hat's LDAP Directory Server daemon or service that isresponsible for all actions of the Directory Server.

See Also slapd.

153

Oobject class Defines an entry type in the directory by defining which attributes are

contained in the entry.

object identifier A string, usually of decimal numbers, that uniquely identifies aschema element, such as an object class or an attribute, in an object-oriented system. Object identifiers are assigned by ANSI, IETF orsimilar organizations.

See Also OID.

OID See object identifier.

operational attribute Contains information used internally by the directory to keep track ofmodifications and subtree properties. Operational attributes are notreturned in response to a search unless explicitly requested.

Pparent access When granted, indicates that users have access to entries below their

own in the directory tree if the bind DN is the parent of the targetedentry.

pass-through authentication See PTA.

pass-through subtree In pass-through authentication, the PTA directory server will passthrough bind requests to the authenticating directory server from allclients whose DN is contained in this subtree.

password file A file on Unix machines that stores Unix user login names,passwords, and user ID numbers. It is also known as /etc/passwdbecause of where it is kept.

password policy A set of rules that governs how passwords are used in a givendirectory.

PDU Encoded messages which form the basis of data exchanges betweenSNMP devices. Also protocol data unit.

permission In the context of access control, permission states whether access tothe directory information is granted or denied and the level of accessthat is granted or denied.

See Also access rights.

pointer CoS A pointer CoS identifies the template entry using the template DNonly.

presence index Allows searches for entries that contain a specific indexed attribute.

protocol A set of rules that describes how devices on a network exchangeinformation.

protocol data unit See PDU.

Glossary

154

proxy authentication A special form of authentication where the user requesting access tothe directory does not bind with its own DN but with a proxy DN.

proxy DN Used with proxied authorization. The proxy DN is the DN of anentry that has access permissions to the target on which the client-application is attempting to perform an operation.

PTA Mechanism by which one Directory Server consults another to checkbind credentials. Also pass-through authentication.

PTA directory server In pass-through authentication (PTA), the PTA Directory Server is theserver that sends (passes through) bind requests it receives to theauthenticating directory server.

PTA LDAP URL In pass-through authentication, the URL that defines theauthenticating directory server, pass-through subtree(s), and optionalparameters.

RRAM Random access memory. The physical semiconductor-based memory

in a computer. Information stored in RAM is lost when the computer isshut down.

rc.local A file on Unix machines that describes programs that are run whenthe machine starts. It is also called /etc/rc.local because of itslocation.

RDN The name of the actual entry itself, before the entry's ancestors havebeen appended to the string to form the full distinguished name. Alsorelative distinguished name.

read-only replica A replica that refers all update operations to read-write replicas. Aserver can hold any number of read-only replicas.

read-write replica A replica that contains a master copy of directory information and canbe updated. A server can hold any number of read-write replicas.

referential integrity Mechanism that ensures that relationships between related entriesare maintained within the directory.

referral (1) When a server receives a search or update request from an LDAPclient that it cannot process, it usually sends back to the client apointer to the LDAP sever that can process the request.

(2) In the context of replication, when a read-only replica receivesan update request, it forwards it to the server that holds thecorresponding read-write replica. This forwarding process is called areferral.

relative distinguished name See RDN.

replica A database that participates in replication.

replica-initiated replication Replication configuration where replica servers, either hub orconsumer servers, pull directory data from supplier servers. Thismethod is available only for legacy replication.

155

replication Act of copying directory trees or subtrees from supplier servers toreplica servers.

replication agreement Set of configuration parameters that are stored on the supplier serverand identify the databases to replicate, the replica servers to whichthe data is pushed, the times during which replication can occur, theDN and credentials used by the supplier to bind to the consumer, andhow the connection is secured.

RFC Request for Comments. Procedures or standards documentssubmitted to the Internet community. People can send comments onthe technologies before they become accepted standards.

role An entry grouping mechanism. Each role has members, which are theentries that possess the role.

role-based attributes Attributes that appear on an entry because it possesses a particularrole within an associated CoS template.

root The most privileged user available on Unix machines. The root userhas complete access privileges to all files on the machine.

root suffix The parent of one or more sub suffixes. A directory tree can containmore than one root suffix.

SSASL An authentication framework for clients as they attempt to bind to a

directory. Also Simple Authentication and Security Layer .

schema Definitions describing what types of information can be stored asentries in the directory. When information that does not match theschema is stored in the directory, clients attempting to access thedirectory may be unable to display the proper results.

schema checking Ensures that entries added or modified in the directory conform to thedefined schema. Schema checking is on by default, and users willreceive an error if they try to save an entry that does not conform tothe schema.

Secure Sockets Layer See SSL.

self access When granted, indicates that users have access to their own entries ifthe bind DN matches the targeted entry.

Server Console Java-based application that allows you to perform administrativemanagement of your Directory Server from a GUI.

server daemon The server daemon is a process that, once running, listens for andaccepts requests from clients.

Server Selector Interface that allows you select and configure servers using abrowser.

server service A process on Windows that, once running, listens for and acceptsrequests from clients. It is the SMB server on Windows NT.

Glossary

156

service A background process on a Windows machine that is responsiblefor a particular system task. Service processes do not need humanintervention to continue functioning.

SIE Server Instance Entry. The ID assigned to an instance of DirectoryServer during installation.

Simple Authentication andSecurity Layer

See SASL.

Simple NetworkManagement Protocol

See SNMP.

single-master replication The most basic replication scenario in which multiple servers, upto four, each hold a copy of the same read-write replicas to replicaservers. In a single-master replication scenario, the supplier servermaintains a changelog.

SIR See supplier-initiated replication.

slapd LDAP Directory Server daemon or service that is responsible for mostfunctions of a directory except replication.

See Also ns-slapd.

SNMP Used to monitor and manage application processes running on theservers by exchanging data about network activity. Also SimpleNetwork Management Protocol.

SNMP master agent Software that exchanges information between the various subagentsand the NMS.

SNMP subagent Software that gathers information about the managed device andpasses the information to the master agent. Also called a subagent.

SOA See start of authority (SOA).

SSL A software library establishing a secure connection between twoparties (client and server) used to implement HTTPS, the secureversion of HTTP. Also called Secure Sockets Layer.

standard index An index maintained by default.

start of authority (SOA) A record which contains the core information about a DNS zone.

sub suffix A branch underneath a root suffix.

subagent See SNMP subagent.

substring index Allows for efficient searching against substrings within entries.Substring indexes are limited to a minimum of two characters for eachentry.

suffix The name of the entry at the top of the directory tree, below whichdata is stored. Multiple suffixes are possible within the same directory.Each database only has one suffix.

superuser The most privileged user available on Unix machines. The superuserhas complete access privileges to all files on the machine. Also calledroot.

157

supplier Server containing the master copy of directory trees or subtrees thatare replicated to replica servers.

supplier server In the context of replication, a server that holds a replica that is copiedto a different server is called a supplier for that replica.

supplier-initiated replication Replication configuration where supplier servers replicate directorydata to any replica servers.

symmetric encryption Encryption that uses the same key for both encrypting and decrypting.DES is an example of a symmetric encryption algorithm.

system index Cannot be deleted or modified as it is essential to Directory Serveroperations.

Ttarget In the context of access control, the target identifies the directory

information to which a particular ACI applies.

target entry The entries within the scope of a CoS.

TCP/IP Transmission Control Protocol/Internet Protocol. The main networkprotocol for the Internet and for enterprise (company) networks.

template entry See CoS template entry.

time/date format Indicates the customary formatting for times and dates in a specificregion.

TLS The new standard for secure socket layers; a public key basedprotocol. Also Transport Layer Security.

topology The way a directory tree is divided among physical servers and howthese servers link with one another.

Transport Layer Security See TLS.

Uuid A unique number associated with each user on a Unix system.

URL Uniform Resource Locater. The addressing system used by theserver and the client to request documents. It is often called alocation. The format of a URL is protocol://machine:port/document.The port number is necessary only on selected servers, and it is oftenassigned by the server, freeing the user of having to place it in theURL.

Vvirtual list view index Speeds up the display of entries in the Directory Server Console.

Virtual list view indexes can be created on any branch point in thedirectory tree to improve display performance.

See Also browsing index.

Glossary

158

XX.500 standard The set of ISO/ITU-T documents outlining the recommended

information model, object classes and attributes used by directoryserver implementation.

159

Index

160

Documents

Fedora 15 FreeIPA Guide en US