freeIPA 1.2.1

Administration ReferenceIPA Solutions from the IPA Experts

Administration Reference

freeIPA 1.2.1 Administration ReferenceIPA Solutions from the IPA ExpertsEdition 1.0

Copyright © 2008 Red Hat. This material may only be distributed subject to the terms and conditionsset forth in the Open Publication License, V1.0 or later. The latest version of the OPL is presentlyavailable at http://www.opencontent.org/openpub/.

Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the UnitedStates and other countries.

All other trademarks referenced herein are the property of their respective owners.

The GPG fingerprint of the security@redhat.com key is:

CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E

1801 Varsity DriveRaleigh, NC 27606-2072USAPhone: +1 919 754 3700Phone: 888 733 4281Fax: +1 919 754 3701PO Box 13588Research Triangle Park, NC 27709USA

This reference provides detailed information about IPA, the technologies with which it works, andsome of the terminology used to describe it.

http://www.opencontent.org/openpub/

iii

Preface v1. Audience ........................................................................................................................ v2. Document Conventions ................................................................................................... v

2.1. Typographic Conventions ...................................................................................... v2.2. Pull-quote Conventions ........................................................................................ vii2.3. Notes and Warnings ............................................................................................ vii

3. We Need Feedback! ..................................................................................................... viii

1. Introduction to IPA 11.1. IPA and Directory Server .............................................................................................. 1

1.1.1. How IPA and Directory Server Work Together ..................................................... 21.2. IPA and Kerberos ......................................................................................................... 2

1.2.1. How IPA and Kerberos Work Together ................................................................ 21.2.2. IPA, Kerberos, and Service Principals ................................................................. 21.2.3. IPA, Kerberos, and DNS .................................................................................... 3

1.3. IPA and NTP ............................................................................................................... 31.3.1. How IPA and NTP Work Together ...................................................................... 3

1.4. IPA and DNS ............................................................................................................... 41.4.1. How IPA and DNS Work Together ...................................................................... 41.4.2. Using IPA with Multi-Homed Machines ................................................................ 5

1.5. Password Management in IPA ...................................................................................... 5

2. IPA and Windows Synchronization 72.1. Introduction .................................................................................................................. 72.2. Directory Server and Active Directory Synchronization Features ...................................... 7

2.2.1. What does IPA Synchronize? ............................................................................. 72.2.2. What does IPA Not Synchronize? ....................................................................... 82.2.3. Other Synchronization Features ......................................................................... 82.2.4. Changing Synchronization Subtrees ................................................................... 9

3. IPA Command-Line Tools and Services 113.1. IPA Command-Line Tools ............................................................................................ 113.2. IPA Services .............................................................................................................. 13

4. XML-RPC Application Programming Interface (API) Documentation 154.1. IPA XML-RPC Application Programming Interface (API) ................................................ 15

Glossary 21

A. Revision History 25

iv

v

PrefaceWelcome to the IPA Administration Reference. This reference provides detailed information aboutIPA servers and clients, their supporting technologies, and the tools and services required to use andmanage them. It also includes conceptual information about the technologies that comprise IPA, andhow they work together.

1. AudienceThis reference is intended for system administrators and those responsible for ensuring that IPA isinstalled and configured correctly for a particular deployment. It is also intended for those responsiblefor customizing or extending any aspects of IPA to suit the needs of a particular installation.

The IPA Administration Reference assumes a good understanding of various operating systems,including Linux, Solaris and other UNIX systems, Macintosh and Microsoft Windows. It alsoassumes a working knowledge of LDAP and either Red Hat or Fedora Directory Server.

2. Document ConventionsThis manual uses several conventions to highlight certain words and phrases and draw attention tospecific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts1 set. TheLiberation Fonts set is also used in HTML editions if the set is installed on your system. If not,alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includesthe Liberation Fonts set by default.

2.1. Typographic ConventionsFour typographic conventions are used to call attention to specific words and phrases. Theseconventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlightkey caps and key-combinations. For example:

To see the contents of the file my_novel in your current working directory, enter thecat my_novel command at the shell prompt and then press Enter.

The above example includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

Press Enter to execute the command.

Press Ctrl-Alt-F1 to switch to the first virtual terminal. Press Ctrl-Alt-F7 to returnto your X-Windows session.

1 https://fedorahosted.org/liberation-fonts/

https://fedorahosted.org/liberation-fonts/https://fedorahosted.org/liberation-fonts/

Preface

vi

The first sentence highlights the particular key cap to press. The second highlights two sets of threekey caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned valuesmentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

File-related classes include filesystem for file systems, file for files, and dir fordirectories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialoguebox text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. Forexample:

Choose System > Preferences > Mouse from the main menu bar to launch MousePreferences. In the Buttons tab, click the Left-handed mouse check box and clickClose to switch the primary mouse button from the left to the right (making the mousesuitable for use in the left hand).

The above text includes application names; system-wide menu names and items; application-specificmenu names; and buttons and text found within a GUI interface, all presented in Proportional Bold andall distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This avoids thedifficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the mainmenu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable orvariable text. Italics denotes text you do not input literally or displayed text that changes depending oncircumstance. For example:

To connect to a remote machine using ssh, type ssh username@domain.name ata shell prompt. If the remote machine is example.com and your username on thatmachine is john, type ssh john@example.com.

To see the version of a currently installed package, use the rpm -q packagecommand. It will return a result as follows: package-version-release.

Note the words in bold italics above — username, domain.name, package, version and release. Eachword is a placeholder, either for text you enter when issuing a command or for text displayed by thesystem.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new orimportant term. For example:

When the Apache HTTP Server accepts requests, it dispatches child processesor threads to handle them. This group of child processes or threads is known asa server-pool. Under Apache HTTP Server 2.0, the responsibility for creating andmaintaining these server-pools has been abstracted to a group of modules calledMulti-Processing Modules (MPMs). Unlike other modules, only one module from theMPM group can be loaded by the Apache HTTP Server.

Pull-quote Conventions

vii

2.2. Pull-quote ConventionsTwo, commonly multi-line, data types are set off visually from the surrounding text.

Output sent to a terminal is set in Mono-spaced Roman and presented thus:

books Desktop documentation drafts mss photos stuff svnbooks_tests Desktop1 downloads images notes scripts svgs

Source-code listings are also set in Mono-spaced Roman but are presented and highlighted asfollows:

package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient{ public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(); Object ref = iniCtx.lookup("EchoBean"); EchoHome home = (EchoHome) ref; Echo echo = home.create();

System.out.println("Created Echo");

System.out.println("Echo.echo('Hello') = " + echo.echo("Hello")); } }

2.3. Notes and WarningsFinally, we use three visual styles to draw attention to information that might otherwise be overlooked.

NoteA Note is a tip or shortcut or alternative approach to the task at hand. Ignoring a noteshould have no negative consequences, but you might miss out on a trick that makes yourlife easier.

ImportantImportant boxes detail things that are easily missed: configuration changes that onlyapply to the current session, or services that need restarting before an update will apply.Ignoring Important boxes won't cause data loss but may cause irritation and frustration.

Preface

viii

WarningA Warning should not be ignored. Ignoring warnings will most likely cause data loss.

3. We Need Feedback!If you find a typographical error in this manual, or if you have thought of a way to make this manualbetter, we would love to hear from you! Please submit a report in Bugzilla: https://bugzilla.redhat.com/enter_bug.cgi?product=freeIPA against the Documentation component.

When submitting a bug report, be sure to mention the manual's identifier: Administrators_Reference

If you have a suggestion for improving the documentation, try to be as specific as possible whendescribing it. If you have found an error, please include the section number and some of thesurrounding text so we can find it easily.

https://bugzilla.redhat.com/enter_bug.cgi?product=freeIPAhttps://bugzilla.redhat.com/enter_bug.cgi?product=freeIPA

Chapter 1.

1

Introduction to IPAIPA is an integrated solution which combines the following technologies:• Fedora (server-side)

• Fedora Directory Server

• MIT Kerberos™

• NTP

• DNS

• Web and command-line provisioning and administration tools

The architecture of an IPA server can be represented as follows:

Figure 1.1. Architecture of an IPA server.

1.1. IPA and Directory ServerFedora Directory Server is an open source, LDAP-based directory service, which provides an LDAPserver, a web management interface, and command-line and graphical management tools. It is highlyscalable, and supports a number of features including:

• Multi-master replication

• TLS/SSL and SASL security

• Support for custom plug-in extensions

• Online schema and configuration updates over LDAP

• Internationalized entries

• Optional on-disk encryption of selected attributes

• Virtual DIT views

Chapter 1. Introduction to IPA

2

Directory Server consists of several different components. The core directory server, ns-slapd,consists of a front end which handles network communications, extensible plug-ins which handle basicserver functions, and a database back-end which implements an indexed, transactional store on top ofa Berkeley DB.

1.1.1. How IPA and Directory Server Work TogetherDirectory Server is an integral part of IPA. In IPA, the Directory Server functions as the data store,maintaining all of an organization's information. The Directory Server's internal controls restrict thelevel of access that IPA users have to Directory Server information. These internal controls cannot beoverridden by any IPA permissions, delegations, or other controls.

1.2. IPA and KerberosKerberos is a network authentication protocol created by MIT, and uses symmetric-key cryptographyto authenticate users to network services. This means that passwords are never actually sent over thenetwork.

Consequently, when users authenticate to network services using Kerberos, unauthorized usersattempting to gather passwords by monitoring network traffic are effectively thwarted.

Kerberos' primary design goal is to eliminate the transmission of unencrypted passwords overthe network. If used properly, Kerberos effectively eliminates the threat that packet sniffers wouldotherwise pose on a network.

1.2.1. How IPA and Kerberos Work TogetherThe IPA implementation of Kerberos differs from a typical Kerberos implementation, mainly in thatit uses Directory Server to store data instead of a flat file. The Directory Server also provides accesscontrols to protect data. The IPA Kerberos implementation does not use the native Kerberos toolsbecause by default the KDC is not aware of the Directory Server.

IPA provides its own set of tools for working with Kerberos. Kerberos' native tools, for example,those provided by kadmin.local, should not be used. For many reasons, kadmin.local doesnot currently have permission to operate outside of cn=kerberos. One reason is that it cannotcommunicate using LDAP, which means that you cannot create principals anywhere that you mightwant. Another reason is that it cannot proxy a password change to the IPA plug-in. Consequently, if apassword change is performed via kadmin.local, it would corrupt the user entry.

WarningThe kadmin and kadmin.local tools are not supported in IPA, and it is highlyrecommended that you avoid their use.

1.2.2. IPA, Kerberos, and Service PrincipalsServer programs require Service Principals to perform Kerberos authentication. Kerberosauthentication works by obtaining an encrypted ticket for a service, a ticket that only the service candecrypt. This in turn verifies that the user obtained it from the KDC, indirectly proving that the client wasable to authenticate to the KDC and is therefore trustworthy.

IPA, Kerberos, and DNS

3

The client needs the Service Principal to indicate to the KDC which service it needs a ticket for. TheKDC uses the Service Principal to store and provide a secret to the service at the moment the ServicePrincipal is created.

Service Principals are typically released per service, although it is possible for one Service Principal tobe used for more services. For example, host/@REALM is used for both the SSH service andalso as the generic "host" principal.

1.2.3. IPA, Kerberos, and DNSAs discussed in Section 1.4.1, “How IPA and DNS Work Together”, IPA relies heavily on a fully-functional DNS for correct operation. Because of its tight integration with IPA, Kerberos also requiresthat the DNS be configured correctly.

1.2.3.1. Using CNAME and A RecordsWhen Kerberos requests a ticket to begin authentication, it always resolves a CNAME to itscorresponding A record; Kerberos libraries never use a CNAME to request a ticket. This means thatwhen you create service or host principals you need to use the host A record. Consider the followingzone file entry:

CNAME www.example.com -> A name web-01.example.com

If you use the following command to connect to the host via SSH, and want GSSAPI authentication:

$ ssh www.example.com

it will actually request a ticket for host/web-01.example.com@EXAMPLE.COM

This is the service principal that you must use to obtain and save tickets in /etc/krb5.keytab forthis host.

1.3. IPA and NTPMany computer services (for example, Kerberos) require that the time differential between hosts ona network be kept to a minimum for correct or accurate operation. The Network Time Protocol(NTP) is a protocol used to synchronize computer clocks over the network. Most operating systemscan be configured to synchronize their clocks with any of a number of time servers.

1.3.1. How IPA and NTP Work TogetherIPA combines a number of different technologies, many of which constantly communicate with eachother over the network. In order for these technologies to work together correctly, the time differentialbetween the clients and servers on the network must be kept to a minimum.

Kerberos, for example, only tolerates a five minute time difference between the KDC and aclient requesting authentication. A time difference greater than five minutes will result in a failedauthentication.

System Administrators also rely on accurate time keeping for correlation of system logs acrossmachines on the network. In the event of problems on the network or other aspects of a deployment, it

Chapter 1. Introduction to IPA

4

may be necessary to inspect the log files of various machines to determine if specific problems occurat the same time. Without NTP or another time synchronization system, such troubleshooting would beall but impossible.

The IPA startup process ensures that the NTP service starts and that the time and date aresynchronized before any other IPA-related processes start. This avoids problems with certificates,LDAP entry creation dates, password and account expiration dates, and other date-related issues.

1.4. IPA and DNSA Domain Name Service (DNS) associates host names with their respective IP addresses. Thisenables users to refer to networked machines by name, rather than having to remember IP addresses.

DNS is normally implemented using centralized servers that are authoritative for some domains andrefer to other DNS servers for other domains.

1.4.1. How IPA and DNS Work TogetherIPA 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.

1.4.1.1. Service Discovery using DNSThe recommended method for ensuring that IPA clients discover IPA servers is to use DNS. Thisrequires adding special records to the DNS configuration. The IPA server installation generates asample zone file which contains sample records for this purpose. In particular, it includes records forthe LDAP servers, Kerberos realm, and Kerberos servers required in an IPA deployment. Theserecords can be added to an existing DNS infrastructure - even one hosted on a different OS - or theycan be added to a new DNS server if one does not already exist.

The following is an extract from a zone file where the IPA server, KDC, and DNS server all exist on thesame machine (ipaserver) in the realm EXAMPLE.COM:

; ldap servers_ldap._tcp IN SRV 0 100 389 ipaserver

;kerberos realm_kerberos IN TXT EXAMPLE.COM

; kerberos servers_kerberos._tcp IN SRV 0 100 88 ipaserver_kerberos._udp IN SRV 0 100 88 ipaserver_kerberos-master._tcp IN SRV 0 100 88 ipaserver_kerberos-master._udp IN SRV 0 100 88 ipaserver_kpasswd._tcp IN SRV 0 100 464 ipaserver_kpasswd._udp IN SRV 0 100 464 ipaserver

If you already have DNS configured on your network, you can add this to the existing zone file (in thisexample, /var/named/example.com.zone.db) so that IPA clients can discover the LDAP andKerberos servers.

Using IPA with Multi-Homed Machines

5

Clients try to discover the IPA server first using parameters passed via the command line, then usingthe configuration file (/etc/ipa/ipa.conf), and then via DNS.

1.4.1.2. Service Discovery without using DNSIt is possible to implement IPA without a DNS, but this is not recommended. If you do not use DNS forservice discovery, then your clients will not automatically find other IPA services in a high-availabilitysetup.

During an IPA client installation, if the DNS is not configured so that the client can discover the IPAserver, you must enter the appropriate information manually.

1.4.2. Using IPA with Multi-Homed MachinesSome of the machines in your IPA deployment may support multiple Network Interface Cards (NICs).This is often the case for servers or other machines where high availability or failover is required.These multi-homed machines typically have multiple IPs assigned to the same host name. Normallythis will not be a problem for IPA, because it listens to all available interfaces except localhost.Similarly for the KDC; it only listens to the machine's public IP addresses. It does not listen to thelocalhost interface.

For an IPA server that has multiple NICs and IP addresses, you need to configure the DNS with theappropriate A records if the server is to be available via any interface.

For example, the zone file on the DNS server might have the following A records for an IPA server(ipaserver.example.com) with three NICs:

ipaserver IN A 192.168.1.100ipaserver IN A 192.168.1.101ipaserver IN A 192.168.1.102

This allows IPA clients to discover the IPA server using any of the available network interfaces.

1.5. Password Management in IPAIPA manages user passwords as part of its function as an identity management store. The first time apassword is set, or whenever a password is reset, its status is immediately set to "expired". New andreset passwords are referred to as initial passwords. Account owners are required to change theseinitial passwords before they can use their account. This behavior is built in to IPA to help addresscommon security issues, and cannot be changed.

Basic Password RequirementsThe fundamental requirement of a password is that it be known only by the user authorized to use it.If password authentication is the only authentication method in use, the user's password essentiallycomprises their entire identity. Consequently, only the authorized user should know the password.

Whenever an administrator creates an initial password for a user account, this requirement is notsatisfied. At least two people now know the password, which renders it ineffective as a means ofexclusively identifying a single user. It is important to remedy this situation as soon as possible.

Setting the status of initial passwords to "expired" forces users to remedy this situation before theybegin using their account, and reduces the threat of impersonation.

Chapter 1. Introduction to IPA

6

Password DistributionPassword distribution refers to the transmission of initial passwords from the administrator to theaccount holder. Whenever an administrator creates an initial password for a user account, not onlydoes the administrator now know the password for the user account, but must also transmit thispassword to the account holder. Common means of transmission include telephone, email, or writingthe password down and physically passing it on.

All of these methods pose a significant threat to the security of the password, and leave amplemargins for an attacker to gain access to system credentials. Forcing a password reset can reduce thethreat that a stolen password is abused and for the abuse to go unnoticed.

If an attacker gains access to the initial password during transmission, only a very small window ofopportunity exists to take advantage of this access. Initial passwords are one-time passwords. Thatis, they can only be used once to connect to IPA, at which point the user must change it to somethingthat only they know, and according to the IPA password policy. If the authorized user does this first, theattacker is left with a useless password. If the attacker does this first, when the authorized user triesto authenticate, the password will fail and access will be denied. At this point the user can notify theadministrator who can then investigate and take corrective action.

Again, immediately setting the status of initial passwords to "expired" reduces the opportunity forattackers to steal and take advantage of users' credentials.

This protection scheme is just one way that IPA attempts to protect user credentials. It is not aninfallible protection scheme, and you should make every effort to protect user credentials duringtransmission. Many other attack vectors exist that this scheme does not address at all. This justprovides an additional measure to make life more difficult for an attacker.

Chapter 2.

7

IPA and Windows Synchronization

2.1. IntroductionTo synchronize user identity information between Directory Server and Windows Active Directory,IPA employs a plug-in that extends the functionality of the Directory Server Windows Sync utility.This plug-in allows IPA to perform the data manipulation necessary to achieve synchronizationbetween Directory Server and Windows Active Directory. The IPA Windows Sync plug-in uses theipaWinSyncUserAttr parameter to specify what attributes and values to add to new users that aresynchronized from Active Directory.

Refer to the Directory Server Administration Guide1 for more information on the Windows Sync utility.

Refer to the Directory Server Plug-in Programmer's Guide2 for more information on working with plug-ins.

2.2. Directory Server and Active Directory SynchronizationFeaturesSome differences exist in the way that IPA synchronizes data between Directory Server and ActiveDirectory compared to an environment that does not include IPA. These are described below.

2.2.1. What does IPA Synchronize?• IPA only synchronizes user data.

The Windows subtree containing the users you want to synchronize can be specified in thesynchronization agreement. By default, IPA synchronizes the "CN=users,$SUFFIX" subtree.You can specify a different subtree using the --win-subtree argument when you create thesynchronization agreement. Refer to the ipa-replica-manage man page for more information.

NoteIf full POSIX attributes exist in Active Directory they are not synchronized.

• IPA synchronizes new users added to Active Directory.

Any necessary IPA attributes (POSIX, Kerberos) are created as part of the synchronizationprocess. These IPA attributes are not synchronized back to Active Directory.

Where necessary, IPA changes the DN and schema before the entry is stored in Directory Server.This involves flattening the DN, and discarding any OU RDNs.

1 http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Windows_Sync.html2 http://www.redhat.com/docs/manuals/dir-server/plugin/7.1/contents.htm

http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Windows_Sync.htmlhttp://www.redhat.com/docs/manuals/dir-server/plugin/7.1/contents.htmhttp://www.redhat.com/docs/manuals/dir-server/ag/8.0/Windows_Sync.htmlhttp://www.redhat.com/docs/manuals/dir-server/plugin/7.1/contents.htm

Chapter 2. IPA and Windows Synchronization

8

Consider the following Active Directory DN:

cn=Joe User, ou=Engineering, cn=Users, dc=example, dc=com

IPA removes the ou=Engineering RDN and modifies the entry to:

uid=juser,cn=users,cn=accounts,dc=example,dc=com

The user entry might appear as follows:

dn: uid=juser,cn=users,cn=accounts,dc=example,dc=comobjectclass: ipaUser...

Example 2.1. Example of flattening an Active Directory DN before synchronizing with RHDS.

• IPA synchronizes account lock information.

Accounts that are locked in AD are also locked in IPA, and vice versa. You can configure this featureto perform bidirectional or unidirectional synchronization, or disable it completely. The defaultconfiguration synchronizes account lock information (ipaWinSyncAcctDisable: both).

NoteMicrosoft Windows uses the terms Enabled and Disabled when referring to the status ofaccounts.

2.2.2. What does IPA Not Synchronize?• IPA does not synchronize groups.

• Users added to IPA are not synchronized to Active Directory.

You need to manually add these users to Active Directory, after which they are synchronizedbetween Directory Server and Active Directory. The synchronization key is the UID (username),which must be the same as the samAccountName in Active Directory.

2.2.3. Other Synchronization FeaturesTo ensure the correct synchronization of user entries between Directory Server and Active Directory,the IPA Windows Sync plug-in can also:

• Change the Active Directory dirsync search request arguments.

• Intercept and change a user entry, including the DN, before it is sent from Directory Server to ActiveDirectory, both in Initialization Mode (also known as a Total Update) and Update Mode (also knownas an Incremental Update).

Changing Synchronization Subtrees

9

• Intercept and change entries after they have been received from Active Directory, but before theyare processed by Directory Server. This includes changing the DN, both in Initialization Mode andUpdate Mode.

• Force synchronization between all users who exist in both IPA and Active Directory. This is specifiedby the --forceSync parameter in the synchronization agreement.

Set this parameter to true (default) to forcibly synchronize all users who have accounts in both IPAand Active Directory. For this to occur, the user's UID (username) in IPA must be the same as thesamAccountName in Active Directory. The ntUser objectclass and ntUserDomainID attribute willalways be added to the IPA user entry.

NoteEven if you remove them, the IPA Winsync plug-in always adds the ntUser andntUserDomainID attributes to the IPA user entry the next time a total or incrementalsynchronization occurs, provided the entry has been modified in Active Directory.

If --forceSync is set to false, the Winsync plug-in works the same way as in a standardDirectory Server deployment. Consequently, you need to manually add ntUser andntUserDomainID to existing IPA user entries in order to synchronize them with Active Directory.

2.2.4. Changing Synchronization SubtreesAfter you have created a synchronization agreement, and an IPA account is in sync with an ADaccount, the two accounts are permanently linked. If you make a change to the account in IPA,winsync looks up the entry using the GUID in the AD entry, under the domain suffix. This occurs evenif you delete the original synchronization agreement and create a new one that synchronizes with adifferent OU in AD.

Consider the following example, where an existing synchronization agreement exists using the defaultsubtree "CN=Users,DC=example,DC=com":

If you create a new AD user "aduser01", this account is automatically synchronized with IPA. Thisaccount has the following characteristics:

In AD: "CN=aduser 01,CN=Users,DC=example,DC=com"In IPA: " uid=aduser01,cn=users,cn=accounts,dc=example,dc=com"

You can delete this winsync agreement, and create a new agreement between the same IPA serverand AD server, but using the win-subtree argument to specify a different OU to synchronize (forexample, OU=nyoffice,DC=example,DC=com). New users that are created under the new OU areautomatically synchronized with IPA.

If you now make changes to the AD user "aduser01" on the IPA server, these changes are stillsynchronized with AD, even though the user is not in the OU specified by the active synchronizationagreement.

Example 2.2. Example of winsync behavior when changing synchronization agreements.

Chapter 2. IPA and Windows Synchronization

10

NoteThe reverse is not true. If you create a new user under the OU in AD specified by theoriginal agreement ("CN=Users,$SUFFIX"), this account is not synchronized with the IPAserver.

Chapter 3.

11

IPA Command-Line Tools and ServicesThis chapter provides a list of all IPA commands and services, including a brief description.

3.1. IPA Command-Line ToolsThe following is a list of the available IPA command-line tools.

NoteSome of these tools require root privileges. Refer to the man pages for full details ofeach command.

ipa-adddelegationAdds a new delegation. A delegation is used to grant write access to certain attributes from onegroup to another.

ipa-addgroupAdds a new group.

ipa-addserviceAdds a new service principal.

ipa-adduserAdds a new user.

ipa-change-master-keyChanges the IPA master key.

WarningThe ipa-change-master-key command is only for use in specific situations. It isnot for use by end-users.

ipa-client-installRuns the IPA client installation script. This script is Red Hat Enterprise Linux 5-specific. Installationscripts are currently only available for a limited number of operating systems.

ipa-client-setupRuns the IPA client installation script. This script is Red Hat Enterprise Linux 4-specific. Installationscripts are currently only available for a limited number of operating systems.

ipa-defaultoptionsDisplays or modifies the IPA search and user policies.

ipa-deldelegationDeletes an existing delegation.

ipa-delgroupDeletes an existing group.

Chapter 3. IPA Command-Line Tools and Services

12

ipa-delserviceDeletes an existing service principal.

ipa-deluserDeletes an existing user. Users are automatically removed from groups when they are deleted.

ipa-findgroupSearches for a group that contains a specified string. The search is a substring search the nameand description attributes.

ipa-findserviceSearches for a service principal that contains a specified string. The search is a substring searchin the service principal.

ipa-finduserSearches for a user that contains a specified string. The search is a substring search in theusername, given name, family name, telephone number, organization and title attributes.

ipa-getkeytabRetrieves and updates Kerberos keytabs.

ipa-ldap-updaterUpdates the IPA LDAP configuration.

If no file arguments are provided, ipa-ldap-updater processes all files in the /usr/share/ipa/updates directory with the .update extension.

ipa-listdelegationLists all current delegations.

ipa-lockuserLocks or unlocks a user account.

ipa-moddelegationModifies an existing delegation.

ipa-modgroupModifies an existing group.

ipa-moduserModifies an existing user.

ipa-passwdChanges a user's password.

ipa-pwpolicyDisplays and updates the password policy.

ipa-replica-installRuns the IPA replica installation script.

ipa-replica-manageManages (lists, adds, deletes) IPA server replicas.

IPA Services

13

ipa-replica-prepareCreates a replica information file for use by ipa-replica-install.

ipa-server-certinstallInstalls a CA certificate for use by IPA.

ipa-server-installRuns the IPA server installation script.

ipa-upgradeconfigUpdates the Apache configuration files of an installed server, if necessary, during an RPM update.This command should not be used by end-users.

3.2. IPA ServicesThe following is a list of the available IPA services.

NoteYou need root privileges to work with these services.

ipactlA wrapper script to start and stop IPA-related services.

ipa_kpasswdForwards password change operations to Directory Server.

ipa_webguiThe IPA Web graphical user interface service.

14

Chapter 4.

15

XML-RPC Application ProgrammingInterface (API) DocumentationThis chapter provides a listing of the XML-RPC API functions and arguments, including any providedhelp.

4.1. IPA XML-RPC Application Programming Interface (API)The XML-RPC can query the remote interface to retrieve the function and argument list, including anyprovided help.

add_group(group, group_container)Add a group in LDAP. Takes as input a dict where the key is the attribute name and the value iseither a string or in the case of a multi-valued field a list of values. group_container sets where inthe tree the group is placed.

add_groups_to_user(group_dns, user_dn)Given a list of group DNs, add them to the user.

Returns a list of the group DNs that were not added.

add_group_to_group(group, tgroup)Add a group to an existing group.

group is a DN of the group to add

tgroup is the DN of the target group to be added to

add_members_to_group(member_dns, group_dn)Given a list of dn's, add them to the group cn denoted by group

Returns a list of the member_dns that were not added to the group.

add_member_to_group(member_dn, group_dn)Add a member to an existing group.

add_service_principal(name, force)Given a name of the form: service/FQDN, create a service principal for it in the default realm.

If force (Boolean) is true, create the service principal even if the host does not exist in the DNSor is not an A record.

add_user(user, user_container)Add a user in LDAP. Takes as input a dict where the key is the attribute name and the value iseither a string or in the case of a multi-valued field a list of values. user_container sets where inthe tree the user is placed.

add_users_to_group(user_uids, group_dn)Given a list of user uid's add them to the group cn denoted by group

Returns a list of the users were not added to the group.

Chapter 4. XML-RPC Application Programming Interface (API) Documentation

16

add_user_to_group(user_uid, group_dn)Add a user to an existing group.

attrs_to_labels(attr_list)Take a list of LDAP attributes and convert them to more friendly labels.

delete_group(group_dn)Delete a group

group_dn is the DN of the group to delete

The memberOf plugin handles removing the group from any other groups.

delete_service_principal(principal)Delete a service principal.

principal is the full DN of the entry to delete.

This should be called with much care.

delete_user(uid)Delete a user. Not to be confused with inactivate_user. This function removes the usercompletely.

uid is the uid of the user to delete.

The memberOf plug-in handles removing the user from any other groups.

find_groups(criteria, sattrs, sizelimit=-1, timelimit=-1)Return a list containing a User object for each existing group that matches the criteria.

find_service_principal(criteria, sattrs, sizelimit=-1, timelimit=-1)Returns a list: counter followed by the results.

If the results are truncated, counter will be set to -1.

find_users(criteria, sattrs, sizelimit=-1, timelimit=-1)Returns a list: counter followed by the results.

If the results are truncated, counter will be set to -1.

get_aci_entry(sattrs)Returns the entry containing access control ACIs.

get_all_attrs()We have a list of hard-coded attributes -> readable labels. Return that complete list if someonewants it.

get_all_users()Return a list containing a User object for each existing user.

get_custom_fields()Get the list of custom user fields.

A schema is a list of dict's of the form:

IPA XML-RPC Application Programming Interface (API)

17

label: The label displayed to the user

field: the attribute name

required: true/false

It is displayed to the user in the order of the list.

get_entry_by_cn(cn, sattrs)Get a specific entry by cn. Return as a dict of values.

Multi-valued fields are represented as lists.

get_entry_by_dn(dn, sattrs)Get a specific entry. Return as a dict of values.

Multi-valued fields are represented as lists.

get_groups_by_member(member_dn, sattrs)Get all of the groups an object is explicitly a member of.

This does not include groups an entry may be a member of as a result of recursion (being a groupthat is a member of another group). In other words, this searches on 'member' and not 'memberof'.

Return as a dict of values.

Multi-valued fields are represented as lists.

get_ipa_config()Retrieve the IPA configuration

get_password_policy()Retrieve the IPA password policy

get_users_by_manager(manager_dn, sattrs)Gets the users that report to a particular manager.

get_user_by_email(email, sattrs)Get a specific user's entry. Return as a dict of values.

Multi-valued fields are represented as lists.

get_user_by_principal(principal, sattrs)Get a user entry searching by Kerberos Principal Name.

Return as a dict of values. Multi-valued fields are represented as lists.

get_user_by_uid(uid, sattrs)Get a specific user's entry.

Return as a dict of values. Multi-valued fields are represented as lists.

group_members(groupdn, attr_list, membertype)Do a memberOf search of groupdn and return the attributes in attr_list (an empty list returns allattributes).

Chapter 4. XML-RPC Application Programming Interface (API) Documentation

18

membertype = 0 all members returned

membertype = 1 only direct members are returned

membertype = 2 only inherited members are returned

Members may be included in a group as a result of being a member of a group that is a member ofthe group being queried.

mark_group_active(cn)Mark a group as active.

mark_group_inactive(cn)Mark a group as inactive

mark_user_active(uid)Mark a user as active

mark_user_inactive(uid)Mark a user as inactive

modifyPassword(principal, oldpass, newpass)Set/Reset a user's password

uid tells us who's password to change

oldpass is the old password (if available)

newpass is the new password

multiCall(calls)Execute a multicall. Execute each method call in the calls list, collecting results and errors, andreturn those as a list.

ping()Simple test to see if the XML-RPC is up and active.

remove_groups_from_user(group_dns, user_dn)Given a list of group dn's remove them from the user.

Returns a list of the group dns that were not removed.

remove_members_from_group(member_dns, group_dn)Given a list of member dn's remove them from the group.

Returns a list of the members not removed from the group.

remove_member_from_group(member_dn, group_dn)Remove a member_dn from an existing group.

remove_users_from_group(user_uids, group_dn)Given a list of user uid's remove them from the group

Returns a list of the user uids not removed from the group.

IPA XML-RPC Application Programming Interface (API)

19

remove_user_from_group(user_uid, group_dn)Remove a user from an existing group.

set_custom_fields(schema)Set the list of custom user fields.

A schema is a list of dict's of the form:

label: The label displayed to the user

field: the attribute name

required: true/false

It is displayed to the user in the order of the list.

update_entry(oldentry, newentry)Update an entry in LDAP

oldentry and newentry are XML-RPC structs.

If oldentry is not empty then it is used when determine what has changed.

If oldentry is empty then the value of newentry is compared to the current value of oldentry.

update_group(oldentry, newentry)Wrapper around update_entry with group-specific handling.

oldentry and newentry are XML-RPC structs.

If oldentry is not empty then it is used when determine what has changed.

If oldentry is empty then the value of newentry is compared to the current value of oldentry.

If you want to change the RDN of a group you must use this function. update_entry will fail.

update_ipa_config(oldconfig, newconfig)Update the IPA configuration.

oldconfig and newconfig are XML-RPC structs.

If oldconfig is not empty then it is used when determine what has changed.

If oldconfig is empty then the value of newconfig is compared to the current value of oldconfig.

update_password_policy(oldpolicy, newpolicy)Update the IPA configuration

oldpolicy and newpolicy are XML-RPC structs.

If oldpolicy is not empty then it is used when determine what has changed.

If oldpolicy is empty then the value of newpolicy is compared to the current value of oldpolicy.

update_user(oldentry, newentry)Wrapper around update_entry with user-specific handling.

Chapter 4. XML-RPC Application Programming Interface (API) Documentation

20

oldentry and newentry are XML-RPC structs.

If oldentry is not empty then it is used when determine what has changed.

If oldentry is empty then the value of newentry is compared to the current value of oldentry.

If you want to change the RDN of a user you must use this function. update_entry will fail.

version()The version of IPA

21

GlossaryAauthentication server (AS) A server that issues tickets for a desired service which are in turn

given to users for access to the service. The AS responds to requestsfrom clients who do not have or do not send credentials with arequest. It is usually used to gain access to the ticket-granting server(TGS) service by issuing a ticket-granting ticket (TGT). The ASusually runs on the same host as the key distribution center (KDC).

Cciphertext Encrypted data.

client An entity on the network (a user, a host, or an application) that canreceive a ticket from Kerberos.

credentials A temporary set of electronic credentials that verify the identity of aclient for a particular service. Also called a ticket.

credential cache or ticketfile

A file which contains the keys for encrypting communicationsbetween a user and various network services. Kerberos 5 supports aframework for using other cache types, such as shared memory, butfiles are more thoroughly supported.

crypt hash A one-way hash used to authenticate users. These are more securethan using unencrypted data, but they are still relatively easy todecrypt for an experienced cracker.

GGSS-API The Generic Security Service Application Program Interface (defined

in RFC-2743 published by The Internet Engineering Task Force) isa set of functions which provide security services. This API is usedby clients and services to authenticate to each other without eitherprogram having specific knowledge of the underlying mechanism.If a network service (such as cyrus-IMAP) uses GSS-API, it canauthenticate using Kerberos.

Hhash Also known as a hash value. A value generated by passing a string

through a hash function. These values are typically used to ensurethat transmitted data has not been tampered with.

hash function A way of generating a digital "fingerprint" from input data. Thesefunctions rearrange, transpose or otherwise alter data to produce ahash value.

Glossary

22

Kkey Data used when encrypting or decrypting other data. Encrypted data

cannot be decrypted without the proper key or extremely good fortuneon the part of the cracker.

key distribution center(KDC)

A service that issues Kerberos tickets, and which usually runs on thesame host as the ticket-granting server (TGS).

keytab (or key table) A file that includes an unencrypted list of principals and their keys.Servers retrieve the keys they need from keytab files instead ofusing kinit. The default keytab file is /etc/krb5.keytab. The KDCadministration server, /usr/kerberos/sbin/kadmind, is the onlyservice that uses any other file (it uses /var/kerberos/krb5kdc/kadm5.keytab).

kinit The kinit command allows a principal who has already logged in toobtain and cache the initial ticket-granting ticket (TGT). Refer to thekinit man page for more information.

LLDB Local Database. LDB is a memory-mapped, LDAP-like database with

persistence capabilities, developed by the Samba project. Becauseit is memory-mapped storage, it is fast and can act as a cache fordynamic identity data, for which IPA is the authoritative source. Itcan also be used to store local data. LDB also allows storing dataretrieved from Directory Server in the same format as it is storedcentrally.

Access to LDB is provided by an LDB library that the Info Pipe uses toaccess data.

Pprincipal (or principal name) The principal is the unique name of a user or service allowed to

authenticate using Kerberos. A principal follows the form root[/instance]@REALM. For a typical user, the root is the same as theirlogin ID. The instance is optional. If the principal has an instance, itis separated from the root with a forward slash ("/"). An empty string("") is considered a valid instance (which differs from the default NULLinstance), but using it can be confusing. All principals in a realmhave their own key, which for users is derived from a password or israndomly set for services.

Rrealm A network that uses Kerberos, composed of one or more servers

called KDCs and a potentially large number of clients.

Sservice A program accessed over the network.

23

Tticket A temporary set of electronic credentials that verify the identity of a

client for a particular service. Also called credentials.

ticket-granting server (TGS) A server that issues tickets for a desired service which are in turngiven to users for access to the service. The TGS usually runs on thesame host as the KDC.

ticket-granting ticket (TGT) A special ticket that allows the client to obtain additional ticketswithout applying for them from the KDC.

Uunencrypted password A plain text, human-readable password.

24

25

Appendix A. Revision HistoryRevision 1.3 13 May, 2009 David O'Brien davido@redhat.com

Update links in Feedback page.Revise tags used for API and Services for better presentation.

Revision 1.2 17 Apr, 2009 David O'Brien davido@redhat.com

Spell-check, add some new terms.

Revision 1.1 25 Nov, 2008 David O'Brien davido@redhat.com

BZ 470606. Document concept behind auto-expiry of user passwords.BZ 471494. Document --win-subtree behavior.BZ 469793. Updates from Tech Review.BZ 471508. Add default account lock sync behavior.Updates for AD synchronization.Updates to IPA command list.

Revision 1.0 20 May, 2008 David O'Brien davido@redhat.com

Created.

mailto:davido@redhat.commailto:davido@redhat.commailto:davido@redhat.commailto:davido@redhat.com

26

Administration ReferenceTable of ContentsPreface1. Audience2. Document Conventions2.1. Typographic Conventions2.2. Pull-quote Conventions2.3. Notes and Warnings

3. We Need Feedback!

Chapter 1. Introduction to IPA1.1. IPA and Directory Server1.1.1. How IPA and Directory Server Work Together

1.2. IPA and Kerberos1.2.1. How IPA and Kerberos Work Together1.2.2. IPA, Kerberos, and Service Principals1.2.3. IPA, Kerberos, and DNS1.2.3.1. Using CNAME and A Records

1.3. IPA and NTP1.3.1. How IPA and NTP Work Together

1.4. IPA and DNS1.4.1. How IPA and DNS Work Together1.4.1.1. Service Discovery using DNS1.4.1.2. Service Discovery without using DNS

1.4.2. Using IPA with Multi-Homed Machines

1.5. Password Management in IPA

Chapter 2. IPA and Windows Synchronization2.1. Introduction2.2. Directory Server and Active Directory Synchronization Features2.2.1. What does IPA Synchronize?2.2.2. What does IPA Not Synchronize?2.2.3. Other Synchronization Features2.2.4. Changing Synchronization Subtrees

Chapter 3. IPA Command-Line Tools and Services3.1. IPA Command-Line Tools3.2. IPA Services

Chapter 4. XML-RPC Application Programming Interface (API) Documentation4.1. IPA XML-RPC Application Programming Interface (API)

GlossaryAppendix A. Revision History