Linux Domain Identity, Authentication, And Policy Guide Red Hat Enterprise 7 Identity Authentication En US

Red_Hat_Enterprise_Linux-7-Linux_Domain_Identity_Authentication_and_Policy_Guide-en-US

User Manual:

Open the PDF directly: View PDF .
Page Count: 469

Download
Open PDF In Browser	View PDF

Red Hat Enterprise Linux 7
Linux Domain Identity,
Authentication, and Policy
Guide
Managing Identity and Authorization Policies for Linux-Based
Infrastructures

Tomáš Čapek

Aneta Petrová

Ella Deon Ballard

Red Hat Enterprise Linux 7 Linux Domain Identity,
Authentication, and Policy Guide

Managing Identity and Authorization Policies for Linux-Based
Infrastructures
Tomáš Čapek
Red Hat Customer Content Services
tcapek@redhat.com
Aneta Petrová
Red Hat Customer Content Services
apetrova@redhat.com
Ella Deon Ballard
Red Hat Customer Content Services

Legal No tice
Copyright © 2015 Red Hat.
This document is licensed by Red Hat under the Creative Commons AttributionShareAlike 3.0 Unported License. If you distribute this document, or a modified version
of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If
the document is modified, all Red Hat trademarks must be removed.
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 Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United
States and other countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other
countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the
United States and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European
Union and other countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not
formally related to or endorsed by the official Joyent Node.js open source or
commercial project.
The OpenStack ® Word Mark and OpenStack Logo are either registered
trademarks/service marks or trademarks/service marks of the OpenStack
Foundation, in the United States and other countries and are used with the
OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Keywo rds
1. FreeIPA. 2. Ident it y Management . 3. IdM. 4. IPA.
Abstract
Identity and policy management, for both users and machines, is a core function for
most enterprise environments. Identity Management provides a way to create an
identity domain that allows machines to enroll to a domain and immediately access
identity information required for single sign-on and authentication services, as well as
policy settings that govern authorization and access.

T able o f Co nt e nt s

T able o f Co ntents

. .hapt
⁠C
. . . .e.r. 1.
. . Int
. . .r.o.duc
. . .t.io
. .n. t.o. .Ide
. . nt
. . it
. .y. Manage
. . . . . . . me
. . .nt
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . .
⁠1 .1. IdM v. LDAP : A More Focused Type of Service
6
⁠1 .2. Bringing Linux Services Together
9
⁠1 .3. Relationships Between Servers and C lients
12
⁠1 .4. Additional Resources
16

. .ar
⁠P
. t. .I.. Ins
. . .t.alling
. . . . . Ide
. . . nt
. . it
. .y.Manage
. . . . . . .me
. . nt
. . .Se
. . r.ve
. . r.s. and
. . . . Se
. . r. vic
. . .e.s. . . . . . . . . . . . . . . . . . .18
..........

. .hapt
⁠C
. . . .e.r. 2.
. . Pr
. . e. r. e. quis
. . . . it
. .e.s. f.o. r. Ins
. . . t.allat
. . . .io
. .n. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
..........
⁠2.1. Supported Server P latform s
19
⁠2.2. Hardware Recom m endations
19
⁠2.3. Software Requirem ents
19
⁠2.4. System P rerequisites
20

. .hapt
⁠C
. . . .e.r. 3.
. . Ins
. . .t.alling
. . . . . and
. . . .Unins
. . . . .t.alling
. . . . . an
. . .IdM
. . . Se
. . .r ve
. . .r . . . . . . . . . . . . . . . . . . . . . . . . . .27
..........
⁠3 .1. The ipa-server-install utility
27
⁠3 .2. Installation P rocedure Descriptions and Exam ples
30
⁠3 .3. Uninstalling an IdM Server
43

. .hapt
⁠C
. . . .e.r. 4. .. Se
. . .t t. ing
. . . .up
. . IdM
. . . .Re
. . plic
. . . as
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.4. . . . . . . . .
⁠4 .1. P lanning the Server and Replica Topologies
44
⁠4 .2. P rerequisites for Installing a Replica Server
45
⁠4 .3. C reating the Replica
47
⁠4 .4. Adding Additional Replication Agreem ents
52
⁠4 .5. Uninstalling an IdM Replica
52

. .hapt
⁠C
. . . .e.r. 5.
. . Se
. . t. t. ing
. . . up
. . . Sys
. . . t. e. ms
. . . as
. . .IdM
. . . Clie
. . . .nt
. .s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
..........
⁠5.1. What Happens in C lient Setup
53
⁠5.2. O pening the IdM Required System P orts
54
⁠5.3. C onfiguring a Linux System as an IdM C lient
55
⁠5.4. Manually C onfiguring a Linux C lient
59
⁠5.5. Setting up a Linux C lient Through Kickstart
66
⁠5.6. Re-enrolling a Host
67
⁠5.7. Renam ing Machines and Reconfiguring IdM C lient C onfiguration
68
⁠5.8. P erform ing a Two-Adm inistrator Enrollm ent
69
⁠5.9. Rem oving C lients from the Dom ain
⁠5.10. Manually Unconfiguring C lient Machines

70
70

. .hapt
⁠C
. . . .e.r. 6. .. Upgr
. . . . .ading
. . . . .Ide
. . .nt
. .it. y
. .Manage
. . . . . . .me
. . nt
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
..........
⁠6 .1. Migrating the IdM Server to Red Hat Enterprise Linux 7
73

. .hapt
⁠C
. . . .e.r. 7.
. . T. he
. . . Bas
. . . ic
. .s. o
. f. .Managing
. . . . . . . . .t.he
. . IdM
. . . .Se
. . r.ve
. . r. and
. . . . Se
. . r. vic
. . .e.s. . . . . . . . . . . . . . . .8.1. . . . . . . . .
⁠7.1. Starting and Stopping the IdM Server
81
⁠7.2. Logging into IdM Using Kerberos
81
⁠7.3. The IdM C om m and-Line Utilities
83
⁠7.4. The IdM Web UI
85

. .hapt
⁠C
. . . .e.r. 8. .. Bac
. . . king
. . . . .Up
. . and
. . . . Re
..s
. t. o
. r. ing
. . . .Ide
. . nt
. . it
. .y. Manage
. . . . . . . me
. . .nt
. . . . . . . . . . . . . . . . . . . . .9.1. . . . . . . . .
⁠8 .1. Full-Server Backup and Data-O nly Backup
92
⁠8 .2. Restoring a Backup
96

. .ar
⁠P
. t. .II.
. .Managing
. . . . . . . . .Us
. .e. r. Ide
. . . nt
. . it
. .ie
.s
. .in
. .a. Linux
. . . . . .Do
. .main
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.8. . . . . . . . .

. .hapt
⁠C
. . . .e.r. 9. .. Managing
. . . . . . . . . Us
..e
. .r s
. .and
. . . .Us
. .e.r. Gr
. .o
. ups
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.9. . . . . . . . .
⁠9 .1. Setting up User Hom e Directories
99

1

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide
⁠9 .1. Setting up User Hom e Directories

99

⁠9 .2. Managing User Entries

101

⁠9 .3. Managing P ublic SSH Keys for Users

110

⁠9 .4. C hanging P asswords

115

⁠9 .5. Enabling and Disabling User Accounts
⁠9 .6. Unlocking User Accounts After P assword Failures

117
119

⁠9 .7. Managing User P rivate Groups
⁠9 .8. Managing Unique UID and GID Num ber Assignm ents
⁠9 .9. Managing User and Group Schem a
⁠9 .10. Managing User Groups
⁠9 .11. Issuing User C ertificates with the IdM C A
⁠9 .12. Managing User C ertificates

119
121
125
134
153
158

. .hapt
⁠C
. . . .e.r. 10
. . .. O
. .ne
. .-T
. .ime
. . . .Pas
. . .s.wo
. . r.ds
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
. .1. . . . . . . . .
⁠H ardware and Software Tokens
161
⁠1 0.1. O ne-Tim e P asswords in Identity Managem ent
161

. .hapt
⁠C
. . . .e.r. 11.
. . . Smar
. . . . .t .Car
. . .ds
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
. .9. . . . . . . . .
⁠1 1.1. Sm art C ard Authentication in Identity Managem ent
169

. .hapt
⁠C
. . . .e.r. 12.
. . . ID
. . Vie
. . . ws
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
...........
⁠1 2.1. User O verrides and Group O verrides
171
⁠1 2.2. ID Views and SSSD
171
⁠1 2.3. Managing ID Views from the Web UI
⁠1 2.4. Managing ID Views from the com m and line

172
177

. .ar
⁠P
. t. .III.
. . Managing
. . . . . . . . . Sys
. . . .t e
. .m. Ide
. . . nt
. . it
. .ie
.s
. .in
. .a. Linux
. . . . . .Do
. .main
. . . . . . . . . . . . . . . . . . . . . . . . . . .179
...........

. .hapt
⁠C
. . . .e.r. 13.
. . . Managing
. . . . . . . . . Ho
. . .s.t s
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
. .0. . . . . . . . .
⁠1 3.1. About Hosts, Services, and Machine Identity and Authentication
⁠1 3.2. About Host Entry C onfiguration P roperties
⁠1 3.3. Disabling and Re-enabling Host Entries

180
181
182

⁠1 3.4. C reating C ertificates for Hosts
⁠1 3.5. Managing P ublic SSH Keys for Hosts

183
190

⁠1 3.6. Setting Ethers Inform ation for a Host
⁠1 3.7. Managing Host Groups

196
196

. .hapt
⁠C
. . . .e.r. 14
. . .. Managing
. . . . . . . . . Se
. . .r vic
. . .e. s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
. .0. . . . . . . . .
⁠1 4.1. Adding and Editing Service Entries and Keytabs
200
⁠1 4.2. C reating C ertificates for Services
⁠1 4.3. Storing C ertificates in NSS Databases

203
214

⁠1 4.4. C onfiguring C lustered Services
⁠1 4.5. Using the Sam e Service P rincipal for Multiple Services
⁠1 4.6. Disabling and Re-enabling Service Entries

214
215
215

. .hapt
⁠C
. . . .e.r. 15.
. . . De
. . .le. gat
. . . ing
. . . .Us
. .e.r. Ac
. . c. e
.s
.s
. .t.o. Ho
. . .s.t.s.and
. . . .Se
. .r.vic
..e
. .s. . . . . . . . . . . . . . . . . . .217
...........
⁠1 5.1. Delegating Service Managem ent
217
⁠1 5.2. Delegating Host Managem ent
⁠1 5.3. Delegating Host or Service Managem ent in the Web UI

218
218

⁠1 5.4. Accessing Delegated Services

220

. .hapt
⁠C
. . . .e.r. 16
. . .. Int
. . .e.gr
. .at
. .ing
. . . wit
. . .h. NIS
. . . .Do
. . mains
. . . . . .and
. . . .Ne
. .t.gr
. .o.ups
. . . . . . . . . . . . . . . . . . . . . . .221
...........
⁠1 6.1. About NIS and Identity Managem ent
221

2

⁠1 6.2. Setting the NIS P ort for Identity Managem ent
⁠1 6.3. C reating Netgroups

222
223

⁠1 6.4. Exposing Autom ount Maps to NIS C lients
⁠1 6.5. Migrating from NIS to IdM

228
229

T able o f Co nt e nt s
⁠1 6.5. Migrating from NIS to IdM

229

. .hapt
⁠C
. . . .e.r. 17.
. . . Managing
. . . . . . . . . DNS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
...........
⁠1 7.1. Installing DNS Services Into an Existing Server
236
⁠1 7.2. BIND in Identity Managem ent
⁠1 7.3. Supported DNS Z one Types

236
237

⁠1 7.4. DNS C onfiguration P riorities
⁠1 7.5. Managing Master DNS Z ones
⁠1 7.6. Managing Dynam ic DNS Updates

238
238
252

⁠1 7.7. Managing DNS Forwarding
⁠1 7.8. Managing Reverse DNS Z ones

259
266

⁠1 7.9. Defining DNS Q uery P olicy

268

. .ar
⁠P
. t. .IV.
. . De
. . .f.ining
. . . . .Do
. . main-wide
. . . . . . . . . .Sys
. . .t.e.m
. .Po
. .lic
. .ie
. .s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
...........

. .hapt
⁠C
. . . .e.r. 18
. . .. Us
. . ing
. . . .Aut
. . .o.mo
. . .unt
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
...........
⁠1 8.1. About Autom ount and IdM
271
⁠1 8.2. C onfiguring Autom ount
⁠1 8.3. Setting up a Kerberized NFS Server
⁠1 8.4. C onfiguring Locations

272
277
280

⁠1 8.5. C onfiguring Maps

282

. .hapt
⁠C
. . . .e.r. 19
. . .. De
. . .f .ining
. . . . .Pas
. . .s.wo
. . r.d. .Po
. .lic
. .ie
. .s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
. .9. . . . . . . . .
⁠1 9.1. About P assword P olicies and P olicy Attributes
⁠1 9.2. Viewing P assword P olicies

289
291

⁠1 9.3. C reating and Editing P assword P olicies
⁠1 9.4. Managing P assword Expiration Lim its

297
300

⁠1 9.5. C hanging the P riority of Group P assword P olicies
⁠1 9.6. Setting Account Lockout P olicies
⁠1 9.7. Enabling a P assword C hange Dialog

301
301
304

. .hapt
⁠C
. . . .e.r. 20
. . .. Managing
. . . . . . . . . t. he
. . .Ke
. . r.be
. . r. o. s. .Do
. . main
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
. .5. . . . . . . . .
⁠20.1. About Kerberos
305
⁠20.2. Setting Kerberos Ticket P olicies
⁠20.3. Refreshing Kerberos Tickets

306
308

⁠20.4. Kerberos Flags for Services and Hosts
⁠20.5. C aching Kerberos P asswords

310
312

⁠20.6. Rem oving Keytabs

313

. .hapt
⁠C
. . . .e.r. 21.
. . . Us
. . ing
. . . .s.udo
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
...........
⁠21.1. About sudo and IP A
⁠21.2. Setting up sudo C om m ands and C om m and Groups
⁠21.3. Defining sudo Rules
⁠21.4. C onfiguring Hosts to Use IdM sudo P olicies

314
315
320
331

. .hapt
⁠C
. . . .e.r. 22.
. . . Co
. . nf
. . igur
. . . . ing
. . . Ho
. . .s.t.-Bas
. . . .e.d. Ac
..c
.e
. .s.s.Co
. . nt
. . r. o. l. . . . . . . . . . . . . . . . . . . . . . . . .334
...........
⁠22.1. About Host-Based Access C ontrol
334
⁠22.2. C reating Host-Based Access C ontrol Entries for Services and Service Groups
⁠22.3. Defining Host-Based Access C ontrol Rules
⁠22.4. Testing Host-Based Access C ontrol Rules

335
339
347

. .hapt
⁠C
. . . .e.r. 23.
. . . De
. . .f ining
. . . . . SELinux
. . . . . . . .Us
. .e.r. Maps
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
...........
⁠23.1. About Identity Managem ent, SELinux, and Mapping Users
352
⁠23.2. C onfiguring SELinux User Map O rder and Defaults
354
⁠23.3. Mapping SELinux Users and IdM Users
357

. .hapt
⁠C
. . . .e.r. 24
. . .. De
. . .f .ining
. . . . .Aut
. . .o.mat
. . . ic
. . Gr
. .o
. up
. . . Me
. . .mbe
. . . r. s. hip
. . . .f o
. .r .Us
. .e. r.s. and
. . . . Ho
. . .s.t s
. . . . . . . .36
. .3. . . . . . . . .

3

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

. .hapt
⁠C
. . . .e.r. 24
. . .. De
. . .f .ining
. . . . .Aut
. . .o.mat
. . . ic
. . Gr
. .o
. up
. . . Me
. . .mbe
. . . r. s. hip
. . . .f o
. .r .Us
. .e. r.s. and
. . . . Ho
. . .s.t s
. . . . . . . .36
. .3. . . . . . . . .
⁠24.1. About Autom em bership
363
⁠24.2. Defining Autom em bership Rules (Basic P rocedure)
⁠24.3. Exam ples of Using Autom em ber Groups

364
367

. .hapt
⁠C
. . . .e.r. 25.
. . . Re
..s
. t. r. ic
. .t.ing
. . .Do
. . mains
. . . . . .f.o.r. PAM
. . . . s. e
. r. vic
. . .e.s. . . . . . . . . . . . . . . . . . . . . . . . . . .370
...........
⁠O ptions to Restrict Access to Dom ains

370

. .ar
⁠P
. t. .V.
. .Co
. . nf
. . igur
. . . .ing
. . . t.he
. . .Ide
. . .nt
. .it.y. Manage
. . . . . . . me
. . .nt
. . Se
. . .r ve
. . .r . . . . . . . . . . . . . . . . . . . . . . . .372
...........

. .hapt
⁠C
. . . .e.r. 26
. . .. De
. . .f .ining
. . . . .Ac
. .c.e.s.s. Co
. . .nt
. .r o
. .l .f o
. .r .IdM
. . . Us
. . .e.r.s. . . . . . . . . . . . . . . . . . . . . . . . . .373
...........
⁠26.1. Access C ontrols for IdM Entries
373
⁠26.2. Defining Self-Service Settings
⁠26.3. Delegating P erm issions over Users
⁠26.4. Defining Role-Based Access C ontrols

374
378
380

. .hapt
⁠C
. . . .e.r. 27.
. . . Ide
. . .nt
. .it
.y
. .Manage
. . . . . . .me
. . nt
. . .File
. . .s. and
. . . . Lo
. . gs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
. .7. . . . . . . . .
⁠27.1. A Reference of IdM Server C onfiguration Files and Directories
397
⁠27.2. IdM Dom ain Services and Log Rotation
399
⁠27.3. About default.conf and C ontext C onfiguration Files
400
⁠27.4. C hecking IdM Server Logs

401

. .hapt
⁠C
. . . .e.r. 28
. . .. Managing
. . . . . . . . . Ce
. . .r t. if
. .ic. at
. . e. s. .and
. . . Ce
. . .r.t if
. .ic
. at
. .e
. .Aut
. . .ho
. . r. it
. .ie. s. . . . . . . . . . . . . . . .4.0.8. . . . . . . . .
⁠28.1. Renewal Messages
⁠28.2. Autom atic C A C ertificate Renewal
⁠28.3. Manual C A C ertificate Renewal
⁠28.4. C hanging C ertificate C haining
⁠28.5. Starting IdM with Expired C ertificates

408
408
408
409
410

⁠28.6. C onfiguring Alternate C ertificate Authorities
⁠28.7. P rom oting a Replica to a Master C A Server
⁠28.8. C onfiguring O C SP Responders
⁠28.9. C ertificate P rofiles

411
411
414
416

⁠28.10. C ertificate Authority AC L Rules

421

. .hapt
⁠C
. . . .e.r. 29
. . .. Dis
. . . abling
. . . . . . Ano
. . . .nymo
. . . . us
. . .Binds
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.28
..........

. .hapt
⁠C
. . . .e.r. 30
. . .. Changing
. . . . . . . . . Do
. . .main
. . . . DNS
. . . . Co
. . .nf
. .igur
. . . at
. . io
. .n. . . . . . . . . . . . . . . . . . . . . . . . . . . .4.29
..........
⁠3 0.1. Setting DNS Entries for Multi-Hom ed Servers
429
⁠3 0.2. Setting up Additional Nam e Servers
429
⁠3 0.3. C hanging Load Balancing for IdM Servers and Replicas

429

. .hapt
⁠C
. . . .e.r. 31.
. . . Managing
. . . . . . . . . t.he
. . .Se
. .r.ve
. .r.-Re
. . .plic
. . . a. .Re
. .lat
. . io
. .ns
. . hips
. . . . . . . . . . . . . . . . . . . . . . . . .4.31
..........
⁠3 1.1. Managing Replication Agreem ents Between IdM Servers
⁠3 1.2. Rem oving a Replica
⁠3 1.3. Renam ing a Server or Replica Host System

431
439
439

. .hapt
⁠C
. . . .e.r. 32.
. . . Migr
. . . . at
. .ing
. . . f. r.o. m
. .an
. . .LDAP
. . . . .Dir
. .e
.c
. t. o
. r. y
. .t.o. IdM
. . . . . . . . . . . . . . . . . . . . . . . . . . .4.4.1. . . . . . . . .
⁠3 2.1. An O verview of LDAP to IdM Migration
441
⁠3 2.2. Exam ples for Using m igrate-ds
449
⁠3 2.3. Scenario 1: Using SSSD as P art of Migration
451
⁠3 2.4. Scenario 2: Migrating an LDAP Server Directly to Identity Managem ent
⁠3 2.5. Scenario 3: Migrating over SSL

453
454

. .ppe
⁠A
. . .ndix
. . . . A.
. .T
. .r o
. .uble
. . . .s.ho
. .o.t.ing
. . . Ide
. . .nt
. .it
.y
. .Manage
. . . . . . .me
. . nt
. . . . . . . . . . . . . . . . . . . . . . . . . . .4.57
..........
⁠A.1. Installation Issues
457
⁠A.2. UI C onnection P roblem s
461
⁠A.3. IdM Server P roblem s
462

4

T able o f Co nt e nt s
⁠A.3. IdM Server P roblem s
⁠A.4. Host P roblem s

462
463

⁠A.5. Kerberos Errors
⁠A.6. SELinux Login P roblem s

464
465

. .ppe
⁠A
. . .ndix
. . . . B.
. . Re
. . .vis
. . io
. .n. His
. . . t. o. r. y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.6.6. . . . . . . . .

5

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 1. Int roduct ion t o Ident it y Management
Re d Hat Ide ntity Manage me nt is a way to cre ate ide ntity s tore s , ce ntraliz e d authe ntication,
domain control for Ke rbe ros and DNS s e rvice s , and authoriz ation policie s — all on Linux
s ys te ms , us ing native Linux tools . While ce ntraliz e d ide ntity, policy, and authoriz ation
s oftware is hardly ne w, Ide ntity Manage me nt is one of the only options that s upport Linux
and Unix domains .
Ide ntity Manage me nt provide s a unifying s kin for s tandards -de fine d, common ne twork
s e rvice s , including PAM, LDAP, Ke rbe ros , DNS, NTP, and ce rtificate s e rvice s , and it allows
Re d Hat Ente rpris e Linux s ys te ms to s e rve as the domain controlle rs .
Ide ntity Manage me nt de fine s a domain, with s e rve rs and clie nts that s hare ce ntrallymanage d s e rvice s , like Ke rbe ros and DNS. This introductory chapte r e xplains :
what Ide ntity Manage me nt is
how all the ce ntrally-manage d s e rvice s work toge the r within the IdM domain
how s e rve rs and clie nts inte ract with e ach othe r

1.1. IdM v. LDAP: A More Focused T ype of Service
At the mos t bas ic le ve l, Re d Hat Ide ntity Manage me nt is a domain controlle r for Linux and
Unix machine s . Ide ntity Manage me nt de fine s the domain, us ing controlling s e rve rs and
e nrolle d clie nt machine s . This provide s ce ntraliz e d s tructure that was pre vious ly
unavailable to Linux and Unix e nvironme nts , and it doe s it us ing native Linux applications
and protocols .

1.1.1. Def ining a T rue Linux Domain
Se curity information fre que ntly re late s to identities of us e rs , machine s , and s e rvice s .
Once the ide ntity is ve rifie d, the n acce s s to s e rvice s and re s ource s can be controlle d.
For e fficie ncy, ris k manage me nt, and e as e of adminis tration, IT adminis trators try to
manage ide ntitie s as ce ntrally as pos s ible and to unite ide ntity manage me nt with
authe ntication and authoriz ation policie s . His torically, Linux e nvironme nts have had a ve ry
difficult time e s tablis hing this ce ntraliz e d manage me nt. The re are a numbe r of diffe re nt
protocols (s uch as NIS and Ke rbe ros ) which de fine domains , while othe r applications s tore
data (s uch as LDAP) and s till othe rs manage acce s s (s uch as s udo). None of the s e
applications talk to e ach othe r or us e the s ame manage me nt tools . Eve ry application had
to be adminis te re d s e parate ly and it had to be manage d locally. The only way to ge t a
cons is te nt ide ntity policy was to copy configuration file s around manually or to try to
de ve lop a proprie tary application to manage ide ntitie s and policie s .
The goal of Ide ntity Manage me nt is to s implify that adminis trative ove rhe ad. With IdM,
users, machines, services, and po licies are all co nf igured in o ne place, using
t he same t o o ls. Be caus e IdM cre ate s a domain, multiple machine s can all us e the s ame
configuration and the s ame re s ource s s imply by joining the domain. Us e rs only have to
s ign into s e rvice s once , and adminis trators only have to manage a s ingle us e r account.
IdM doe s thre e things :

6

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

Cre ate a Linux-bas e d and Linux-controlle d domain. IdM s e rve rs and IdM clie nts are
Linux or Unix machine s , and Ide ntity Manage me nt is a manage me nt tool for Linux
domains . IdM can als o s ynchroniz e data with an Active Dire ctory domain to allow
inte gration with Windows s e rve rs , but it doe s not s upport Windows clie nts .
Ce ntraliz e ide ntity manage me nt and ide ntity policie s .
Build on e xis ting, native Linux applications and protocols . While IdM has its own
proce s s e s and configuration, its unde rlying te chnologie s are familiar and trus te d by
Linux adminis trators and are we ll e s tablis he d on Linux s ys te ms .
IdM s e rve s as a bridge be twe e n Linux and the IdM world. IdM, whe n us e d in conce rt with
Cros s -Re alm Ke rbe ros Authe ntication, make s it pos s ible for both IdM and Linux to
coope rate in te rms of ide ntity, authe ntication and authoriz ation. IdM and Ke rbe ros are e ach
able to us e the ir own native clie nts .
IdM provide s a ve ry s imple s olution to a ve ry common and ve ry s pe cific proble m: ide ntity
manage me nt. In a s e ns e , Ide ntity Manage me nt is n't making adminis trators do s ome thing
ne w; it is he lping the m do it be tte r. The following e xample s of how IdM can be us e d in
various company e nvironme nts illus trate s s ome of the capabilitie s of Re d Hat
Ide ntity Manage me nt.
IdM in a low control enviro nment
Little Example Corp. has s e ve ral Linux and Unix s e rve rs , but e ach one is
adminis te re d s e parate ly. All pas s words are ke pt on the local machine , s o the re is
no ce ntral ide ntity or authe ntication proce s s . Tim the IT Guy jus t has to manage
us e rs on e ve ry machine , s e t authe ntication and authoriz ation policie s s e parate ly,
and maintain local pas s words .
With IdM, things come to orde r. The re is a s imple way to have ce ntral us e r,
pas s word, and policy s tore s , s o Tim the IT Guy only has to maintain the ide ntitie s
on one machine (the IdM s e rve r) and us e rs and policie s are uniformly applie d to
all machine s . Us ing hos t-bas e d acce s s control, de le gation, and othe r rule s , he can
e ve n s e t diffe re nt acce s s le ve ls for laptops and re mote us e rs .
IdM in a medium control enviro nment
Mid-Example Corp. has s e ve ral Linux and Unix s e rve rs , but Bill the IT Guy has
trie d to maintain a gre ate r de gre e of control by cre ating a NIS domain for
machine s , an LDAP dire ctory for us e rs , and Ke rbe ros for authe ntication. While his
e nvironme nt is we ll unde r control, e ve ry application has to be maintaine d
s e parate ly, us ing diffe re nt tools . He als o has to update all of the s e rvice s
manually whe ne ve r a ne w machine is adde d to his infras tructure or whe n one is
take n offline .
In this s ituation, IdM gre atly re duce s his adminis trative ove rhe ad be caus e it
inte grate s all of the diffe re nt applications toge the r s e amle s s ly, us ing a s ingle and
s implifie d tool s e t. It als o make s it pos s ible for him to imple me nt s ingle s ign-on
s e rvice s for all of the machine s in his domain.
IdM in an absent control enviro nment
At Big Example Corp., mos t of the s ys te ms are Windows -bas e d and are manage d
in a tightly-knit Active Dire ctory fore s t. Howe ve r, de ve lopme nt, production, and
othe r te ams have many Linux and Unix s ys te ms , which are bas ically e xclude d
from the Windows controlle d e nvironme nt.

7

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

IdM brings native control to the Linux and Unix s e rve rs , us ing the ir native tools
and applications , which is s ome thing that is not pos s ible in an Active Dire ctory
fore s t. Additionally, be caus e IdM is Windows -aware , data can be s ynchroniz e d
be twe e n Active Dire ctory and IdM, pre s e rving a ce ntraliz e d us e r s tore .

1.1.2. Cont rast ing Ident it y Management wit h a St andard LDAP
Direct ory
The clos e s t re lative to Ide ntity Manage me nt is a s tandard LDAP dire ctory like Re d Hat
Dire ctory Se rve r. Howe ve r, the y have a diffe re nt purpos e . The primary fe ature of an
LDAP dire ctory is its ge ne rality; it can be made to fit into a varie ty of applications .
Ident it y Management , on the othe r hand, has a very specif ic purpo se and f it s a
very specif ic applicat io n: it is not a ge ne ral LDAP dire ctory, it is not a back e nd, and it
is not a ge ne ral policy s e rve r.
A dire ctory s e rvice is a colle ction of s oftware , hardware , and proce s s e s that s tore s
information. While dire ctory s e rvice s can be highly s pe cific (for e xample , DNS is a
dire ctory s e rvice be caus e it s tore s information on hos t name s ), a ge ne ric dire ctory
s e rvice can s tore and re trie ve any kind of information. LDAP dire ctorie s like Re d Hat
Dire ctory Se rve r are ge ne ric dire ctorie s . The y have a fle xible s che ma that s upports
e ntrie s for us e rs , machine s , ne twork e ntitie s , phys ical e quipme nt, and buildings , and that
s che ma can be cus tomiz e d to de fine e ntrie s of almos t anything. Be caus e of its
e xte ns ibility, LDAP s e rve rs like Dire ctory Se rve r are fre que ntly us e d as back e nds that
s tore data for othe r applications . Dire ctory Se rve r not only contains information, it
organiz e s information. LDAP dire ctorie s us e a hie rarchical s tructure , a directory tree, that
organiz e e ntrie s into root e ntrie s (s uffixe s ), inte rme diate or containe r e ntrie s (s ubtre e s
or branche s ), and le af e ntrie s (the actual data). Dire ctory tre e s can be ve ry comple x, with
a lot of branch points , or ve ry s imple (flat) with fe w branch points .
Ident it y Management f o cuses o n ident it ies (us e r and machine ) and po licies that
re late to thos e ide ntitie s and the ir inte ractions . While it us e s an LDAP back e nd to s tore
its data, IdM has a highly-cus tomiz e d and s pe cific s e t of s che ma that de fine s a particular
s e t of ide ntity-re late d e ntrie s and de fine s the m in de tail. It has a re lative ly flat and s imple
dire ctory tre e be caus e it has only a handful of e ntry type s and re lations hips that are
re le vant to its purpos e . It has rule s and limitations on how the IdM s e rve r can be de ploye d
be caus e it can only be de ploye d for a s pe cific purpos e : managing ide ntitie s .
The re s trictions on IdM als o give it a gre at de al of adminis trative s implicity. It has a s imple
ins tallation proce s s , a unifie d s e t of commands , and a cle arly de fine d role in the ove rall IT
infras tructure . An IdM domain is e as y to configure , e as y to join, and e as y to manage , and
the functions that it s e rve s , particularly ide ntity and authe ntication tas ks like e nte rpris e wide s ingle s ign-on, are als o e as ie r to do with IdM than with a more ge ne ral-purpos e
dire ctory s e rvice .
T able 1.1. Ident it y Management Co mpared t o Red Hat Direct o ry Server
Red Hat Direct o ry Server

Ident it y Management

Us e

Ge ne ral purpos e

Fle xibility

Highly-cus tomiz able

Sche ma

De fault LDAP s che ma

Dire ctory Tre e

Standard and fle xible
hie rarchy

Single domain, focus e d on
ide ntity manage me nt
Limitations to focus on
ide ntity and authe ntication
Optimiz e d, s pe cial s che ma
for ide ntity manage me nt
Flat tre e with a fixe d
hie rarchy

8

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

Red Hat Direct o ry Server

Ident it y Management

Authe ntication

LDAP

Active Dire ctory
Synchroniz ation

Bi-dire ctional

Pas s word Policie s
Us e r Tools

LDAP-bas e d
Java Cons ole and s tandard
LDAP utilitie s

Ke rbe ros or Ke rbe ros and
LDAP
Unidire ctional,
Active Dire ctory to
Ide ntity Manage me nt
Ke rbe ros -bas e d
We b-bas e d UI and s pe cial
Python command-line tools

LDAP dire ctorie s like Re d Hat Dire ctory Se rve r have fle xibility and adaptability which
make s the m a pe rfe ct back e nd to any numbe r of applications . Its primary purpos e is to
s tore and re trie ve data e fficie ntly.
IdM fills a ve ry diffe re nt niche . It is optimiz e d to pe rform a s ingle tas k ve ry e ffe ctive ly. It
s tore s us e r information and authe ntication and authoriz ation policie s , as we ll as othe r
information re late d to acce s s , like hos t information. Its s ingle purpos e is to manage
ide ntitie s .

1.2. Bringing Linux Services T oget her
Ide ntity Manage me nt unifie s various re late d Linux s e rvice s into a s ingle manage me nt
e nvironme nt. It e s tablis he s a s imple , e as y way to bring hos t machine s into the domain of
thos e s e rvice s .
At its core , an IdM s e rve r is an ide ntity and authe ntication s e rve r. The primary IdM s e rve r
is e s s e ntially a domain controlle r, and it us e s a Ke rbe ros s e rve r and KDC for
authe ntication. An LDAP back e nd contains all domain information including us e rs , clie nt
machine s , and domain configuration.

9

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 1.1. T he IdM Server: Unif ying Services
Othe r s e rvice s are include d to provide s upport for the core ide ntity and authe ntication
functions :
DNS is us e d for machine dis cove ry and for conne cting to othe r clie nts in the domain.
NTP is us e d to s ynchroniz e all domain clocks s o that logging, ce rtificate s , and
ope rations can occur as e xpe cte d.
A ce rtificate s ys te m provide s ce rtificate s for Ke rbe ros -aware s e rvice s .
All of the s e additional s e rvice s work toge the r unde r the control of the IdM s e rve r.
The IdM s e rve r als o has a s e t of tools which are us e d to manage all of the IdM-as s ociate d
s e rvice s . Rathe r than managing the LDAP s e rve r, KDC, or DNS s e ttings individually, us ing
diffe re nt tools on local machine s , IdM has a s ingle manage me nt tools e t (CLI and we b UI)
that allows ce ntraliz e d and cohe s ive adminis tration of the domain.

1.2.1. Aut hent icat ion: Kerberos KDC
Ke rbe ros is an authe ntication protocol. Ke rbe ros us e s s ymme tric ke y cryptography to
ge ne rate tickets to us e rs . Ke rbe ros -aware s e rvice s che ck the ticke t cache (a keytab) and
authe nticate us e rs with valid ticke ts .

10

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

Ke rbe ros authe ntication is s ignificantly s afe r than normal pas s word-bas e d authe ntication
be caus e pas s words are ne ve r s e nt ove r the ne twork, e ve n whe n s e rvice s are acce s s e d
on othe r machine s .
In Ide ntity Manage me nt, the Ke rbe ros adminis tration s e rve r is s e t up on the IdM domain
controlle r, and all of the Ke rbe ros data are s tore d in the Dire ctory Se rve r back e nd for
IdM. The Dire ctory Se rve r ins tance de fine s and e nforce s acce s s controls for the Ke rbe ros
data.

No te
The IdM Ke rbe ros s e rve r is manage d through IdM tools ins te ad of Ke rbe ros tools
be caus e all of its data are s tore d in the Dire ctory Se rve r ins tance . The KDC is
unaware of the Dire ctory Se rve r, s o managing the KDC with Ke rbe ros tools doe s not
affe ct the IdM configuration.

1.2.2. Dat a St orage: Red Hat Direct ory Server
Ide ntity Manage me nt contains an inte rnal Re d Hat Dire ctory Se rve r ins tance . All of the
Ke rbe ros information, us e r accounts , groups , s e rvice s , policy information, DNS z one and
hos t e ntrie s , and all othe r information in IdM is s tore d in this Dire ctory Se rve r ins tance .
Whe n multiple s e rve rs are configure d, the y can talk to e ach othe r be caus e
Dire ctory Se rve r s upports multi-master replication. Agre e me nts are automatically
configure d be twe e n the initial s e rve r and any additional replicas which are adde d to the
domain.

1.2.3. Aut hent icat ion: Red Hat Cert if icat e Syst em
Ke rbe ros can us e ce rtificate s along with ke ytabs for authe ntication, and s ome s e rvice s
re quire ce rtificate s for s e cure communication. Ide ntity Manage me nt include s a ce rtificate
authority, through Re d Hat Ce rtificate Sys te m, with the s e rve r. This CA is s ue s ce rtificate s
to the s e rve r, re plicas , and hos ts and s e rvice s within the IdM domain.
The CA can be a root CA or it can have its policie s de fine d by anothe r, e xte rnal CA (s o
that it is subordinate to that CA). In Re d Hat Ente rpris e Linux 7, CA is optional. You can s e t
up a CA-le s s IdM de ployme nt by only providing the ne ce s s ary s igne d ce rtificate s . For
more information about the pos s ible CA configurations , s e e Se ction 3.2.3, “Ins talling with
Diffe re nt CA Configurations ”.

1.2.4. Service Discovery: DNS
Ide ntity Manage me nt us e s the Domain Name Sys te m (DNS) for dynamic s e rvice
dis cove ry. The IdM clie nt ins tallation utility can us e information from DNS to automatically
configure the clie nt machine . Afte r the clie nt is e nrolle d in the IdM domain, it us e s DNS to
locate IdM s e rve rs and s e rvice s within the domain. For more information about s e rvice
dis cove ry, s e e the Sys te m-Le ve l Authe ntication Guide .
Having the IdM s e rve r als o be a DNS s e rve r is optional but s trongly re comme nde d. Whe n
the IdM s e rve r als o manage s DNS, the re is tight inte gration be twe e n the DNS and native
IdM tools which automate s s ome of DNS re cord manage me nt. Eve n if an IdM s e rve r is
us e d as a mas te r DNS s e rve r, othe r e xte rnal DNS s e rve rs can s till be us e d as s lave
s e rve rs .

11

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1.2.5. Management : SSSD
The Sys te m Se curity Se rvice s Dae mon (SSSD) is a platform application that cache s
cre de ntials . Mos t s ys te m authe ntication is configure d locally, which me ans that s e rvice s
mus t che ck with a local us e r s tore to de te rmine us e rs and cre de ntials . SSSD allows a
local s e rvice to che ck with a local cache in SSSD. The cache may be take n from any
varie ty of re mote ide ntity provide rs , including Ide ntity Manage me nt.
SSSD can cache us e r name s and pas s words , Ke rbe ros principals and ke ytabs , automount
maps , s udo rule s that are de fine d on IPA s e rve rs , and SSH ke ys that are us e d by
Ide ntity Manage me nt domain us e rs and s ys te ms . This allows two s ignificant be ne fits to
adminis trators : firs t, all ide ntity configuration can be ce ntraliz e d in a s ingle application (the
IdM s e rve r); and s e cond, e xte rnal information can be cache d on a local s ys te m to continue
normal authe ntication ope rations in cas e the s ys te m or the IdM s e rve r be come s
unavailable .
SSSD is automatically configure d by IdM clie nt ins tallation and manage me nt s cripts , s o the
s ys te m configuration ne ve r ne e ds to be manually update d, e ve n as domain configuration
change s .
Cons is te ntly with Windows Active Dire ctory, SSSD allows the us e r to log in with e ithe r the
us e r name attribute or the Us e r Principal Name (UPN) attribute .
SSSD s upports the true, false, and preserve value s for the case_sensitive option.
Whe n the preserve value is e nable d, the input matche s re gardle s s of the cas e , but the
output is always the s ame cas e as on the s e rve r; SSSD pre s e rve s the cas e for the UID
fie ld as it is configure d.
SSSD allows ce rtain cache d e ntrie s to be re fre s he d in the background, s o the e ntrie s are
re turne d ins tantly be caus e the back e nd ke e ps the m update d at all time s . Curre ntly,
e ntrie s for us e rs , groups , and ne tgroups are s upporte d.

1.2.6. Management : NT P
Many s e rvice s re quire that s e rve rs and clie nts have the s ame s ys te m time , within a
ce rtain variance . For e xample , Ke rbe ros ticke ts us e time s tamps to de te rmine the ir
validity. If the time s be twe e n the s e rve r and clie nt s ke w outs ide the allowe d range , the n
any Ke rbe ros ticke ts are invalidate d.
Clocks are s ynchroniz e d ove r a ne twork us ing Network Time Protocol (NTP). A ce ntral
s e rve r acts as an authoritative clock and all of the clie nts which re fe re nce that NTP s e rve r
s ync the ir time s to match.
Whe n the IdM s e rve r is the NTP s e rve r for the domain, all time s and date s are
s ynchroniz e d be fore any othe r ope rations are pe rforme d. This allows all of the date re late d s e rvice s — including pas s word e xpirations , ticke t and ce rtificate e xpirations ,
account lockout s e ttings , and e ntry cre ation date s — to function as e xpe cte d.
The IdM s e rve r, by de fault, works as the NTP s e rve r for the domain. Othe r NTP s e rve rs
can als o be us e d for the hos ts .

1.3. Relat ionships Bet ween Servers and Client s
Ide ntity Manage me nt its e lf de fine s a domain, a group of machine s that have s hare d
configuration, policie s , and ide ntity s tore s . The s hare d configuration allows the machine s
(and us e rs ) within the domain to be aware of e ach othe r and ope rate toge the r. This

12

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

aware ne s s can be us e d to e nable cros s -platform compatibility, like unifying Windows and
Linux s ys te ms , or to e nable infras tructure -wide s ingle s ign-on.

1.3.1. IdM Servers and Replicas
Ide ntity Manage me nt works by having ide ntifie d s e rve rs which are the mas te r s tore s of
information for us e r and machine ide ntitie s and domain-wide policie s . The s e s e rve rs hos t
domain-re late d s e rvice s s uch as ce rtificate authoritie s , NTP, Ke rbe ros , SSH, and DNS, and
the y als o act as ce ntral re pos itorie s of ide ntity and policy information.

No te
Mos t of the s upporte d s e rvice s , for which an IdM s e rve r s e rve s as a controlle r, are
not re quire d. For e xample , a s e rve r may have a CA, a DNS s e rve r, an NTP s e rve r,
or it can be ins talle d without thos e s e rvice s .
Clie nts inte ract indire ctly with IdM s e rve rs whe n the y atte mpt to acce s s domain
re s ource s , s uch as file s hare s , s e rvice s , re mote machine s , or authe ntication (through
SSSD and Ke rbe ros ).
Once an IdM s e rve r is s e t up, its configuration can be copie d and us e d as the bas is for
anothe r IdM s e rve r. Whe n an IdM s e rve r is copie d, that copy is calle d a replica. The re are
s ome diffe re nce s be twe e n IdM s e rve rs and IdM re plicas :
While a s e rve r is a ne w ins tallation, which me ans that it de fine s the domain
configuration, a re plica is bas e d on an e xis ting s e rve r and an e xis ting domain
configuration. Once an ins tance is configure d, s e rve rs and re plicas are bas ically
ide ntical in functionality and be havior within the IdM domain.
In ve rs ions of Re d Hat Ente rpris e Linux prior to 7.1, only one s e rve r in the IdM domain
ge ne rate s the CRL and re ne ws the PKI s ubs ys te m ce rtificate s .
Starting with Re d Hat Ente rpris e Linux 7.1, only one s e rve r in the IdM domain can re ne w
DNSSEC ke ys .

No te
The re is a good de al of fle xibility in the IdM s e rve r (and re plica) topology. For
e xample , Se rve r A can be ins talle d with a CA and DNS s e rvice s , while Re plica A can
be bas e d on the configuration of Se rve r A but not hos t e ithe r DNS or CA s e rvice s .
Re plica B can be adde d to the domain, als o without CA or DNS s e rvice s . At any time
in the future , a CA or DNS s e rvice can be cre ate d and configure d on Re plica A or
Re plica B.
Se rve rs and re plicas both us e unde rlying LDAP dire ctorie s to s tore us e r and hos t e ntrie s ,
configuration data, policy configuration, and ke ytabs , ce rtificate s , and ke ys . Se rve rs and
re plicas propagate data among e ach othe r through multi-master replication agreements.
Re plication agre e me nts are configure d for all LDAP back e nds as we ll as the LDAP
s ubtre e s us e d by Re d Hat Ce rtificate Sys te m. Both s e rve rs and re plicas are mas te rs
(pe e rs ) in the re plication topology.

13

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Be caus e the s e rve rs within the IdM domain are all LDAP pe e r s e rve rs , the re plication
topology mus t conform to the topology limits of a Re d Hat Dire ctory Se rve r domain.
Planning the s e rve r and re plica topology is de s cribe d more in Se ction 4.1, “Planning the
Se rve r and Re plica Topologie s ”.

Figure 1.2. Server and Replica Int eract io ns

No te
The re plication topology e s s e ntially cre ate s a cloud of IdM s e rve rs . One be ne fit of a
s e rve r domain is automatic load balancing, us ing the SRV re cords in DNS. The SRV
re cord s e ts the priority orde r that s e rve rs and re plicas are contacte d, while we ight
dis tribute s the load be twe e n s e rve rs /re plicas with the s ame priority. The s e rve r
and re plica DNS e ntrie s can be e dite d to change the load balancing, which is
cove re d in Example 17.5, “Adding an SRV Re cord” and Se ction 30.3, “Changing Load
Balancing for IdM Se rve rs and Re plicas ”.

1.3.2. IdM Client s
A clie nt is s imply any machine which is configure d to ope rate within the IdM domain, us ing
its Ke rbe ros and DNS s e rvice s , NTP s e ttings , and ce rtificate s e rvice s . That is an important
dis tinction: a clie nt doe s not re quire a dae mon or an ins talle d product. It re quire s only
s ys te m configurations which dire ct it to us e IdM s e rvice s .
IdM clie nts us e a numbe r of IdM-e nable d platform applications , as we ll as tools provide d by
IdM its e lf. For Re d Hat Ente rpris e Linux s ys te ms , the platform tools available for IdM to us e
include for e xample the Sys te m Se curity Se rvice s Dae mon (SSSD). IdM its e lf provide s
othe r tools , s uch as ce rtain PAM and NSS module s and IdM command-line utilitie s . The s e
are IdM compone nts , rathe r than platform compone nts us e d by IdM.

14

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

Figure 1.3. Server and Client Int eract io ns
IdM us e s the local s torage (cache ) on a clie nt to improve pe rformance by:
s toring IdM information whe n the machine is offline
ke e ping information active be yond its normal time out pe riod if the clie nt cannot acce s s
the ce ntral s e rve r; the cache is pe rs is te nt e ve n afte r re booting the machine
re ducing the round-trip time of re que s ts by che cking information locally be fore looking
at the s e rve r
Information is s tore d e ithe r in an LDB databas e (s imilar to LDAP) or the local file s ys te m
(as XML file s ), de pe nding on the type of information.
Ide ntity information (about us e rs , machine s , and groups ) is s tore d in the LDB databas e ,
which us e s the s ame s yntax as an LDAP dire ctory. This ide ntity information is originally
s tore d in the IdM s e rve r's Re d Hat Dire ctory Se rve r ins tance . Be caus e this information
change s fre que ntly and is re fe re nce d fre que ntly, it is important to be able to call the
more curre nt information quickly, which is pos s ible us ing an LDB databas e on the clie nt
and the Dire ctory Se rve r on the s e rve r.
Policy information is more s tatic than ide ntity information, and it can include
configuration for SELinux or s udo. The s e policie s are s e t globally on the s e rve r and
the n are propagate d to the clie nts . On the clie nt, the policy information is s tore d in the
file s ys te m in XML file s which can be downloade d and conve rte d into a native file for
whate ve r s e rvice is be ing manage d.
A s pe cific s e t of s e rvice s on the IdM s e rve r inte ract with a s ubs e t of s e rvice s and
module s on the IdM clie nt. A clie nt is any machine (a host) which can re trie ve a ke ytab or
ce rtificate s from the IdM domain.

15

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 1.4. Int eract io ns Bet ween IdM Services
Figure 1.4, “Inte ractions Be twe e n IdM Se rvice s ” s hows that Re d Hat Ente rpris e Linux us e s
two native dae mons to inte ract with the IdM s e rve r:
SSSD provide s the us e r authe ntication for the machine and e nforce s hos t-bas e d
acce s s control rule s .
The certmonger s e rvice monitors and re ne ws the ce rtificate s on the clie nt. It can
re que s t ne w ce rtificate s for the s e rvice s on the s ys te m, including virtual machine s .
Whe n a Re d Hat Ente rpris e Linux clie nt is adde d to the domain (enrolled), its SSSD and
certmonger are configure d to conne ct to the IdM s e rve r and the re quire d Ke rbe ros ke ytab
and hos t ce rtificate s are cre ate d. The hos t ce rtificate is not us e d dire ctly by IdM, but it
may be us e d by othe r s e rvice s , s uch as a we b s e rve r.

1.4. Addit ional Resources
In addition to this guide , you can find docume ntation on othe r fe ature s and s e rvice s
re late d to Re d Hat Ente rpris e Linux Ide ntity Manage me nt in the following guide s :
System-Level Authentication Guide
The System-Level Authentication Guide docume nts diffe re nt applications and
s e rvice s available to configure authe ntication on local s ys te ms , including the

16

⁠C hapt e r 1. Int r o duc t io n t o Ide nt it y Manage me nt

authconfig utility, the SSSD s e rvice , the Pluggable Authe ntication Module (PAM)
frame work, Ke rbe ros , the certmonger utility, and s ingle -s ign on (SSO) for
applications .
Windows Integration Guide
The Windows Integration Guide docume nts how to inte grate Linux domains with
Micros oft Windows Active Dire ctory (AD) us ing Ide ntity Manage me nt. Among othe r
topics , the guide cove rs various as pe cts of dire ct and indire ct AD inte gration,
us ing SSSD to acce s s a Commong Inte rne t File Sys te m (CIFS), and the realmd
s ys te m.

17

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

⁠P art I. Inst alling Ident it y Management Servers and
Services

18

⁠C hapt e r 2. Pr e r e quis it e s f o r Ins t allat io n

Chapt er 2. Prerequisit es for Inst allat ion
The Ide ntity Manage me nt ins tallation and configuration proce s s re quire s the e nvironme nt
to be s uitably configure d. You are als o re quire d to provide ce rtain information during the
ins tallation and configuration proce dure s , s uch as re alm name s and ce rtain us e r name s
and pas s words . The following s e ction de s cribe s the s e re quire me nts .

2.1. Support ed Server Plat forms
IdM 4.1 is s upporte d on the Re d Hat Ente rpris e Linux 7 x86_64 platform.

2.2. Hardware Recommendat ions
A bas ic us e r e ntry is approximate ly 1 KB in s iz e . A s imple hos t e ntry with a ce rtificate is
als o approximate ly 1 KB in s iz e .
RAM is the mos t important hardware fe ature to s iz e prope rly. While all de ployme nts are
diffe re nt, de pe nding on the numbe r of us e rs and groups and the type of data s tore d, you
can us e the following re comme ndations as guide line s for de te rmining how much RAM your
IdM de ployme nt might re quire :
For 10,000 us e rs and 100 groups , have at le as t 2 GB of RAM and 1 GB s wap s pace .
For 100,000 us e rs and 50,000 groups , have at le as t 16 GB of RAM and 4 GB of s wap
s pace .

No te
For large r de ployme nts , it is more e ffe ctive to incre as e the RAM than to incre as e
dis k s pace be caus e much of the data are s tore d in cache .
The unde rlying Dire ctory Se rve r ins tance us e d by the IdM s e rve r can be tune d to
incre as e pe rformance . For tuning information, s e e the chapte r about optimiz ing s ys te m
pe rformace in the Dire ctory Se rve r docume ntation.

2.3. Soft ware Requirement s
Mos t of the package s that an IdM s e rve r de pe nds on are ins talle d automatically as
de pe nde ncie s whe n the ipa-server package is ins talle d. The de pe nde ncie s ins talle d
toge the r with ipa-server include package s s uch as 389-ds-base for the LDAP s e rvice or
krb5-server for the Ke rbe ros s e rvice , as we ll as various IdM tools .
If you want to have the IdM s e rve r s e t up as a DNS s e rve r, which is s trongly
re comme nde d, ins tall the ipa-server-dns package be fore ins talling the IdM s e rve r.
For more information on DNS and why it is re comme nde d to run a DNS s e rve r on the IdM
s e rve r, s e e Se ction 1.2.4, “Se rvice Dis cove ry: DNS”.

19

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Impo rtant
Due to CVE-2014-3566, the Se cure Socke t Laye r ve rs ion 3 (SSLv3) protocol ne e ds
to be dis able d in the mod_nss module . You can e ns ure that by following the s e s te ps :
1. Edit the /etc/httpd/conf.d/nss.conf file and s e t the NSSProtocol
parame te r to TLSv1.0 (for backward compatibility) and TLSv1.1.
NSSProtocol TLSv1.0,TLSv1.1
2. Re s tart the httpd s e rvice .
# systemctl restart httpd.service
Note that Ide ntity Manage me nt in Re d Hat Ente rpris e Linux 7 automatically pe rforms
the above s te ps whe n the yum update ipa-* command is launche d to upgrade the
main package s .

2.4. Syst em Prerequisit es
The IdM s e rve r is s e t up us ing a configuration s cript that make s ce rtain as s umptions about
the hos t s ys te m. If the hos t s ys te m doe s not me e t the s e pre re quis ite s , s e rve r
configuration can fail.

2.4.1. Syst em Files
The s ys te m, on which IdM is ins talle d, is re comme nde d to be cle an. No cus tom
configuration for s e rvice s like DNS or Ke rbe ros s hould be pre s e nt on the s ys te m be fore
ins talling and configuring the IdM s e rve r.
The IdM s e rve r s cript ove rwrite s s ys te m file s to s e t up the IdM domain. Sys te m file s are
backe d up to /var/lib/ipa/sysrestore/ during the ins tallation of s e rve rs and re plicas .

2.4.2. Host Name and DNS Conf igurat ion
Prope r DNS configuration and hos t name s e ttings are re quire d for IdM s e rve rs and
re plicas of the s e s e rve rs to function corre ctly. The s e rve r hos t mus t have DNS prope rly
configure d re gardle s s of whe the r the DNS s e rve r is inte grate d within IdM or hos te d
e xte rnally.
Ident it y Management requires o ne separat e DNS do main t o be used f o r service
reco rds. T o avo id co nf lict s o n DNS level, t he primary DNS domain used f o r IdM
canno t be shared wit h any o t her syst em. Follow re comme nde d DNS naming
practice s , as de s cribe d in the Re d Hat Ente rpris e Linux Se curity Guide .
Note that hos t name s of IdM clie nts are not re quire d to be part of the primary DNS
domain.

20

⁠C hapt e r 2. Pr e r e quis it e s f o r Ins t allat io n

Warning
The primary DNS domain and the Ke rbe ros re alm cannot be change d afte r the initial
ins tallation. Re d Hat s trongly re comme nds that the Ke rbe ros re alm name is the
s ame as the primary DNS domain name , with all le tte rs uppe rcas e . For e xample , if
primary DNS domain is ipa.example.com, the IPA.EXAMPLE.COM Ke rbe ros re alm
name is re comme nde d. Diffe re nt naming practice s will pre ve nt you from us ing
Active Dire ctory trus ts and can have othe r ne gative cons e que nce s .
IdM can be configure d to us e a s e parate domain hos te d on a s tandard, non-inte grate d DNS
s e rve r. In s uch cas e s , the ne w domain mus t be manually cre ate d on the DNS s e rve r and
manually fille d with re cords from the z one file that will be ge ne rate d by the IdM ins talle r.
Als o, the s e re cords mus t be manually update d afte r ins talling or re moving a re plica, as
we ll as afte r any change s in the s e rvice configuration, s uch as afte r an Active Dire ctory
trus t is configure d.
To re duce the mainte nance burde n, Re d Hat re comme nds to ins tall IdM with an inte grate d
DNS s e rve r, as de s cribe d in Se ction 3.2.4, “Configuring DNS Se rvice s within the IdM
Domain”. This automate s mos t of the DNS re cord mainte nance . If an IdM-inte grate d DNS
s e rve r is us e d for DNS domain, s e t up corre ct de le gation from the pare nt domain to the
IdM s e rve rs . For e xample , if the IdM domain name is ipa.example.com, it mus t be
prope rly de le gate d from the example.com domain.

No te
You can ve rify the de le gation us ing the dig @IP address +norecurse +short
ipa.example.com. NS command, whe re IP address is the IP addre s s of the s e rve r
that manage s the example.com DNS domain. If the de le gation is corre ct, the
command lis ts the IdM s e rve rs that have a DNS s e rve r ins talle d.

Verif ying t he Server Host Name
Us e the hostname utility to dis play the hos t name .
[root@server ~]# hostname
server.example.com
The hos t name mus t be a fully-qualifie d domain name , s uch as server.example.com in
the above e xample .

Impo rtant
The fully-qualifie d domain name mus t be a valid DNS name , which me ans only
numbe rs , alphabe tic characte rs , and hyphe ns (-) are allowe d. Othe r characte rs , like
unde rs core s , in the hos t name caus e DNS failure s . Additionally, the hos t name mus t
be all lowe r-cas e ; no capital le tte rs are allowe d. For othe r re comme nde d naming
practice s , s e e the Re d Hat Ente rpris e Linux Se curity Guide .
The fully-qualifie d domain name cannot re s olve to the loopback addre s s . It mus t re s olve
to the machine 's public IP addre s s , not to 127.0.0.1. The output of the hostname utility

21

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

cannot be localhost or localhost6.

Verif ying t he Forward and Reverse DNS Conf igurat ion
1. Obtain the IP addre s s of the s e rve r. The ip addr show command dis plays both the
IPv4 and IPv6 addre s s e s :
The IPv4 addre s s is dis playe d on the line s tarting with inet. In the following
e xample , the configure d IPv4 addre s s is 192.0.2.1.
The IPv6 addre s s is dis playe d on the line s tarting with inet6. Only IPv6
addre s s e s with scope global are re le vant for this proce dure . In the following
e xample , the re turne d IPv6 addre s s is 2001:DB8::1111.
[root@server ~]# ip addr show
...
2: eth0:  mtu 1500 qdisc
pfifo_fast state UP group default qlen 1000
link/ether 00:1a:4a:10:4e:33 brd ff:ff:ff:ff:ff:ff
inet 192.0.2.1/24 brd 192.0.2.255 scope global dynamic eth0
valid_lft 106694sec preferred_lft 106694sec
inet6 2001:DB8::1111/32 scope global dynamic
valid_lft 2591521sec preferred_lft 604321sec
inet6 fe80::56ee:75ff:fe2b:def6/64 scope link
valid_lft forever preferred_lft forever
2. Ve rify the forward DNS configuration by us ing the dig utility and adding the hos t
name .
a. Run the dig +short server.example.com A command. The re turne d IPv4
addre s s mus t match the IP addre s s re turne d by ip addr show:
[root@server ~]# dig +short server.example.com A
192.0.2.1
b. Run the dig +short server.example.com AAAA command. If the command
re turns an addre s s , it mus t match the IPv6 addre s s re turne d by ip addr
show:
[root@server ~]# dig +short server.example.com AAAA
2001:DB8::1111

No te
If no output is re turne d for the AAAA re cord, it doe s not indicate
incorre ct configuration; no output only me ans that no IPv6 addre s s is
configure d in DNS for the s e rve r machine . If you do not inte nd to us e
the IPv6 protocol in your ne twork, you can proce e d with the ins tallation
in this s ituation.
3. Ve rify the re ve rs e DNS configuration (PTR re cords ) by us ing the dig utility and
adding the IP addre s s .

22

⁠C hapt e r 2. Pr e r e quis it e s f o r Ins t allat io n

a. Run the dig +short -x IPv4 address command. The s e rve r hos t name
mus t be dis playe d in the command output. For e xample :
[root@server ~]# dig +short -x 192.0.2.1
server.example.com
b. Us e dig to que ry the IPv6 addre s s as we ll if the dig +short -x
server.example.com AAAA command in the pre vious s te p re turne d an IPv6
addre s s . Again, the s e rve r hos t name mus t be dis playe d in the command
output. For e xample :
[root@server ~]# dig +short -x 2001:DB8::1111
server.example.com

No te
If dig +short server.example.com AAAA in the pre vious s te p did not
dis play any IPv6 addre s s , que rying the AAAA re cord doe s not output
anything. In this cas e , this is normal be havior and doe s not indicate
incorre ct configuration.
If a diffe re nt hos t name or no hos t name is dis playe d, e ve n though dig +short
server.example.com in the pre vious s te p re turne d an IP addre s s , it indicate s that
the re ve rs e DNS configuration is incorre ct.

Verif ying t he St andards-compliance of DNS Forwarders
Whe n configuring IdM with inte grate d DNS, ve rify that all DNS forwarde rs you want to us e
with the IdM DNS s e rve r comply with the Exte ns ion Me chanis ms for DNS (EDNS0) and DNS
Se curity Exte ns ions (DNSSEC) s tandards . To do this , ins pe ct the output of the following
command for e ach forwarde r s e parate ly:
$ dig +dnssec @IP_address_of_the_DNS_forwarder . SOA
The e xpe cte d output dis playe d by the command contains the following information:
s tatus : NOERROR
flags : ra
EDNS flags : do
The RRSIG re cord mus t be pre s e nt in the ANSWER s e ction
If any of the s e ite ms is mis s ing from the output, ins pe ct the docume ntation of your DNS
forwarde r and ve rify that EDNS0 and DNSSEC are s upporte d and e nable d. In late s t
ve rs ions of the BIND s e rve r, the dnssec-enabled yes; option mus t be s e t in the
/etc/named.conf file .
For e xample , the e xpe cte d output can look like this :
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48655
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1

23

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags: do; udp: 4096
;; ANSWER SECTION:
. 31679 IN SOA a.root-servers.net. nstld.verisign-grs.com. 2015100701
1800 900 604800 86400
. 31679 IN RRSIG SOA 8 0 86400 20151017170000 20151007160000 62530 .
GNVz7SQs [...]

T he /etc/hosts File

Impo rtant
Do not modify the /etc/hosts file manually. If /etc/hosts has be e n modifie d, make
s ure its conte nts conform to the following rule s .
The following is an e xample of a corre ctly configure d /etc/hosts file . It prope rly lis ts the
IPv4 and IPv6 localhos t e ntrie s for the hos t, followe d by the IdM s e rve r IP addre s s and
hos t name as the firs t e ntry. Note that the IdM s e rve r hos t name cannot be part of the
locahost e ntry.
127.0.0.1 localhost.localdomain localhost
::1 localhost6.localdomain6 localhost6
192.0.2.1 server.example.com
2001:DB8::1111 server.example.com

2.4.3. Red Hat Direct ory Server
The re mus t not be any ins tance s of Dire ctory Se rve r ins talle d on the hos t machine .

2.4.4. Syst em Port s
IdM us e s a numbe r of ports to communicate with its s e rvice s . The s e ports , lis te d in
Table 2.1, “IdM Ports ”, mus t be ope n and available for IdM to work. The y cannot be in us e
by anothe r s e rvice or blocke d by a fire wall. To make s ure that the s e ports are available ,
try nc, telnet, or nmap to conne ct to a port or run a port s can.
T able 2.1. IdM Po rt s
Service

Po rt s

T ype

HTTP/HTTPS
LDAP/LDAPS
Ke rbe ros
DNS
NTP

80, 443
389, 636
88, 464
53
123

TCP
TCP
TCP and UDP
TCP and UDP
UDP

24

⁠C hapt e r 2. Pr e r e quis it e s f o r Ins t allat io n

No te
Do not be conce rne d that IdM us e s port 389. Us ing it is s afe be caus e all
communication with IdM is e ncrypte d with GSSAPI.
In addition, IdM can lis te n on port 8080 and in s ome ins tallations als o on ports 8443 and
749. Howe ve r, the s e thre e ports are only us e d inte rnally: e ve n though IdM ke e ps the m
ope n, the y are not re quire d to be acce s s ible from outs ide . It is re comme nde d that you do
not ope n ports 8080, 8443, and 749 and ins te ad le ave the m blocke d by a fire wall.

Opening t he Required Port s
Ope ning ports re quire s the firewalld s e rvice to be running. To s tart firewalld as we ll
as to configure it to s tart automatically whe n the s ys te m boots :
[root@server ~]# systemctl start firewalld.service
[root@server ~]# systemctl enable firewalld.service

No te
You can de te rmine whe the r firewalld is curre ntly running us ing the systemctl
status firewalld.service command.
For e xample , to ope n one of the re quire d ports in the de fault z one and make the change
both pe rmane nt and runtime :
1. Run the firewall-cmd command with the --permanent option s pe cifie d.
[root@server ~]# firewall-cmd --permanent --add-port=389/tcp
2. Change s made with firewall-cmd --permanent are not e ffe ctive imme diate ly. To
e ns ure that the change s take place imme diate ly, run firewall-cmd again, this time
without --permanent.
[root@server ~]# firewall-cmd --add-port=389/tcp
If you adde d multiple ports , it is s imple r to make the change s take place
imme diate ly by running the firewall-cmd --reload command, which make s the
curre nt pe rmane nt configuration be come ne w runtime configuration.
[root@server ~]# firewall-cmd --reload
To ope n all the IdM re quire d ports in the de fault z one and make the change both
pe rmane nt and runtime :
1. Run the firewall-cmd command with the --permanent option s pe cifie d.
[root@server ~]# firewall-cmd --permanent --add-port=
{80/tcp,443/tcp,389/tcp,636/tcp,88/tcp,464/tcp,53/tcp,88/udp,464/u
dp,53/udp,123/udp}

25

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

2. Re load the firewall-cmd configuration to e ns ure that the change take s place
imme diate ly.
[root@server ~]# firewall-cmd --reload
For more information on firewalld and on ope ning and clos ing ports on a s ys te m, s e e
the Re d Hat Se curity Guide or the fire wall-cmd(1) man page .

2.4.5. NT P
Ne twork Time Protocol (NTP) s ynchroniz e s time be twe e n s ys te ms on a ne twork. An NTP
s e rve r ce ntraliz e s and manage s that clock s ynchroniz ation. By de fault,
Ide ntity Manage me nt ins talls and configure s an NTP s e rve r which is us e d by the domain to
s ynchroniz e clocks for othe r Ide ntity Manage me nt s e rve rs , re plicas , and s ys te ms and
s e rvice s within the IdM domain.
An NTP s e rve r mus t be running in orde r for s ome domain tas ks to function prope rly.
The s e domain tas ks include data re plication be twe e n s e rve rs and re plicas in the topology.
Ke rbe ros authe ntication doe s not work without pre cis e time ke e ping, e ithe r for s e rve r-tos e rve r authe ntication or for the initiation of re plication. T he IdM server do es no t have
t o ho st t he NT P server, but it is st ro ngly reco mmended. T his is t he def ault
co nf igurat io n.
Running an NTP s e rve r on an IdM s e rve r ins talle d on a virtual machine (VM) can le ad to
inaccurate time s ynchroniz ation in s ome e nvironme nts . To avoid pote ntial proble ms , it is
re comme nde d that IdM s e rve rs be ing ins talle d on a VM do not run an NTP s e rve r. To
dis able NTP for IdM, add the --no-ntp option to the ipa-server-install command whe n
ins talling the IdM s e rve r on a VM to pre ve nt an NTP s e rve r from be ing ins talle d. For more
information about the re liability of an NTP s e rve r run on a VM, s e e the re late d
Knowle dge bas e s olution.

2.4.6. NSCD
It is re comme nde d that NSCD is dis able d in IdM de ployme nts . Alte rnative ly, if dis abling
NSCD is not pos s ible , only e nable NSCD for maps that SSSD doe s not cache . Both NSCD
and the SSSD s e rvice pe rfom caching, and proble ms can occur whe n s ys te ms us e both
s e rvice s s imultane ous ly. Se e the Sys te m-Le ve l Authe ntication Guide for information on
how to avoid clas he s be twe e n NSCD and SSSD.

26

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

Chapt er 3. Inst alling and Uninst alling an IdM Server
An IdM server is a domain controlle r; it de fine s and manage s the IdM domain. Se tting up an
IdM s e rve r follows the s e bas ic s te ps :
1. Ins talling the ne ce s s ary package s on the machine
2. Configuring the s e rve r through s e tup s cripts
Multiple domain controlle rs can be s e t up within one domain for load-balancing and failove r
tole rance . The s e additional s e rve rs are replicas of the mas te r IdM s e rve r. This chapte r
de s cribe s ins talling an IdM s e rve r. For information on ins talling re plicas , s e e Chapte r 4,
Setting up IdM Replicas.

3.1. T he

ipa-server-install

ut ilit y

The ipa-server package is the only package re quire d to ins tall an IdM s e rve r. If you want to
have the IdM s e rve r s e t up as a DNS s e rve r, which is s trongly re comme nde d, ins tall the
ipa-server-dns package be fore ins talling the IdM s e rve r. Us e the yum utility to ins tall the
re quire d package s , for e xample :
[root@server ~]# yum install ipa-server ipa-server-dns
For information about the de pe nde ncie s ins talle d toge the r with ipa-server, s e e Se ction 2.3,
“Software Re quire me nts ”. For information about DNS and why it is re comme nde d to run a
DNS s e rve r on the IdM s e rve r, s e e Se ction 1.2.4, “Se rvice Dis cove ry: DNS”.

Warning
DNS re cords are vital for ne arly all IdM domain functions , including running LDAP
dire ctory s e rvice s , Ke rbe ros , and Active Dire ctory inte gration.
Be e xtre me ly cautious and e ns ure that you have a te s te d and functional DNS
s e rvice available , and that the s e rvice is configure d as de s cribe d in Se ction 2.4.2,
“Hos t Name and DNS Configuration”.
Note that the primary DNS domain and Ke rbe ros re alm cannot be change d afte r
ins tallation.

Afte r ins talling the package s , the s e rve r ins tance is cre ate d us ing the ipa-serverinstall utility, which s tarts the IdM s e rve r s e tup s cript.
If you run ipa-server-install without any options , the inte ractive s e tup prompts for all
the bas ic re quire d information. The s e tup s cript als o offe rs de fault value s for mos t of the
s e ttings . For an e xample of this proce dure , s e e Se ction 3.2.1, “Bas ic Inte ractive
Ins tallation” for ins talling without inte grate d DNS s e rvice s and Se ction 3.2.4.1, “Ins talling
with an Inte grate d DNS Se rvice Inte ractive ly” for ins talling an IdM-inte grate d DNS s e rve r.
Alte rnative ly, you can add command-line argume nts to ipa-server-install, which
pas s e s the s e ttings dire ctly to the s e tup s cript. Some advance d s e ttings , s uch as
choos ing othe r than de fault CA configuration, can only be pas s e d to ipa-server-install
us ing argume nts , be caus e the s e tup s cript doe s not prompt for the information during the

27

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

bas ic inte ractive ins tallation proce s s . For e xample s of running ipa-server-install with
various argume nts , s e e Se ction 3.2.2, “Bas ic Sile nt Non-Inte ractive Ins tallation”,
Se ction 3.2.3, “Ins talling with Diffe re nt CA Configurations ”, or Se ction 3.2.4, “Configuring
DNS Se rvice s within the IdM Domain”.

No te
The port numbe rs and dire ctory locations us e d by IdM are all de fine d automatically,
as de s cribe d in Se ction 2.4.4, “Sys te m Ports ” and Chapte r 27, Identity Management
Files and Logs. You cannot change or cus tomiz e the s e ports and dire ctorie s .
The ipa-server-install options are ve rs atile e nough to be cus tomiz e d to the s pe cific
de ployme nt e nvironme nt to ins tall and configure diffe re nt s e rvice s as ne e de d, and the y
als o allow the configuration proce s s to be e as ily s cripte d. Table 3.1, “ipa-server-install
Options ” lis ts s ome of the common argume nts us e d with ipa-server-install. For the full
lis t, s e e the ipa-s e rve r-ins tall(1) man page .
T able 3.1. ipa-server-install Opt io ns
Argument

Descript io n

--hostname=host name

The fully-qualifie d domain name of the IdM
s e rve r machine .

Impo rtant
The fully-qualifie d domain name mus t
be a valid DNS name , which me ans
only numbe rs , alphabe tic characte rs ,
and hyphe ns (-) are allowe d. Othe r
characte rs , like unde rs core s , in the
hos t name caus e DNS failure s .
Additionally, the hos t name mus t be
all lowe r-cas e ; no capital le tte rs are
allowe d. For othe r re comme nde d
naming practice s , s e e the Re d Hat
Ente rpris e Linux Se curity Guide .
-r realm_name

28

The name of the Ke rbe ros re alm to cre ate
for the IdM domain.

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

Argument

Descript io n

-n domain_name

The name of the primary DNS domain for
this IdM ins tallation.

Warning
Whe n de fining the domain name ,
make s ure to follow the
re quire me nts de s cribe d in
Se ction 2.4.2, “Hos t Name and DNS
Configuration”.
--subject=subject_DN

-a ipa_admin_password

-p directory_manager_password

-P kerberos_master_password

--idmax=number
--idstart=number
--ip-address

--setup-dns

--forwarder=forwarder

--no-forwarders
--no-reverse

Se ts the bas e e le me nt for the s ubje ct DN
of the is s ue d ce rtificate s . This de faults to
O=realm.
The pas s word for the IdM adminis trator.
This is us e d for the admin us e r to
authe nticate to the Ke rbe ros re alm.
The pas s word for the s upe rus e r,
cn=Directory Manager, for the LDAP
s e rvice .
The pas s word for the KDC adminis trator.
This is randomly ge ne rate d if no value is
give n.
Se ts the range for IDs which can be
as s igne d by the IdM s e rve r. Se e
Se ction 9.8.2, “ID Range As s ignme nts
During Ins tallation” for more de tails .
Spe cifie s the IP addre s s of the s e rve r.
Whe n adde d to ipa-server-install, this
option only acce pts IP addre s s e s
as s ociate d with the local inte rface .
Te lls the ins tallation s cript to s e t up a DNS
s e rvice within the IdM domain. Us ing an
inte grate d DNS s e rvice is optional, s o if
this option is not pas s e d with the
ins tallation s cript, the n no DNS is
configure d.
Give s a DNS forwarde r to us e with the DNS
s e rvice . To s pe cify more than one
forwarde r, us e this option multiple time s .
Us e s root s e rve rs with the DNS s e rvice
ins te ad of forwarde rs .
Doe s not cre ate a re ve rs e DNS z one whe n
the DNS domain is s e t up. Us e this option if
re ve rs e DNS z one s alre ady e xis t on
anothe r DNS s e rve r.
If you do not us e this option, the ins tallation
s cript automatically configure s re ve rs e
DNS.

29

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

3.2. Inst allat ion Procedure Descript ions and Examples
The way that an IdM s e rve r is ins talle d can be diffe re nt de pe nding on the ne twork
e nvironme nt, s e curity re quire me nts within the organiz ation, and the de s ire d topology. The
following ins tallation proce dure de s criptions and e xample s illus trate how to us e s ome
common options during s e rve r ins tallation.
The s e proce dure s and e xample s are not mutually e xclus ive ; it is pos s ible to us e CA
options , DNS options , and IdM configuration options in the s ame s e rve r invocation.
Example s in the following s e ctions are calle d out s e parate ly s imply to make it more cle ar
what e ach configuration are a re quire s .

3.2.1. Basic Int eract ive Inst allat ion
If you run the ipa-server-install command without any argume nts , the s e tup s cript
automatically prompts you for the bas ic re quire d information.
1. Run ipa-server-install.
[root@server ~]# ipa-server-install
The ins tallation proce s s s ugge s ts de fault value s for mos t of the configuration
s e ttings . The de fault value s are dis playe d in bracke ts ([ ]), and you can choos e
the m by pre s s ing the Enter ke y.
2. The s cript prompts to configure an inte grate d DNS s e rvice . In this e xample , the
de fault no option is chos e n, me aning the ins talle d IdM s e rve r will not run a DNS
s e rve r.
Do you want to configure integrated DNS (BIND)? [no]:

No te
For an e xample that de s cribe s ins talling the DNS s e rvice s , s e e Se ction 3.2.4,
“Configuring DNS Se rvice s within the IdM Domain”.
3. Ente r the hos t name . The de fault value is de te rmine d automatically us ing re ve rs e
DNS.
Server host name [ipaserver.example.com]:
4. Ente r the domain name . The de fault value is de te rmine d automatically bas e d on
the hos t name .
Please confirm the domain name [example.com]:
5. Ente r the ne w Ke rbe ros re alm name . The de fault value is bas e d on the domain
name .
Please provide a realm name [EXAMPLE.COM]:

30

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

6. Ente r the pas s word for the Dire ctory Se rve r s upe rus e r, cn=Directory Manager.
No de fault value is available for this s e tting.
Directory Manager password:
7. Ente r the pas s word for the IdM s ys te m us e r account, admin, which will be cre ate d
on the machine . No de fault value is available for this s e tting.
IPA admin password:
8. The s cript re prints the hos t name , IP addre s s , and domain name . Confirm that the
dis playe d information is corre ct by e nte ring yes.
The IPA Master Server will be configured with
Hostname:
ipaserver.example.com
IP address: 192.168.1.1
Domain name: example.com
Realm name: EXAMPLE.COM
Continue to configure the system with these values? [no]: yes
9. The s cript now configure s all of the as s ociate d s e rvice s for IdM. Wait for the
ope ration to comple te .
The following operations may take some minutes to complete.
Please wait until the prompt is returned.
Configuring NTP daemon (ntpd)
[1/4]: stopping ntpd
[2/4]: writing configuration
[3/4]: configuring ntpd to start on boot
[4/4]: starting ntpd
Done configuring NTP daemon (ntpd).
Configuring directory server (dirsrv): Estimated time 1 minute
[1/38]: creating directory server user
...
Restarting the directory server
Restarting the KDC
Restarting the certificate server
Sample zone file for bind has been created in
/tmp/sample.zone.2yv_RI.db
Restarting the web server
==================================================================
============
Setup complete
10. The ins tall s cript produce s a DNS z one file with re cords : the
/tmp/sample.zone.2yv_RI.db file in the e xample output in the pre vious s te p. Add
the s e re cords to the e xis ting DNS s e rve rs .
Note that the s e rve r ins tallation is not comple te until the DNS re cords are adde d to
the e xis ting DNS s e rve rs .

31

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

11. The s cript re comme nds you to back up the CA ce rtificate and to make s ure the
re quire d ne twork ports are ope n. For information about IdM port re quire me nts and
ins tructions on how to ope n the s e ports , s e e Se ction 2.4.4, “Sys te m Ports ”.
12. Authe nticate to the Ke rbe ros re alm us ing the admin cre de ntials to e ns ure that the
us e r is prope rly configure d and the Ke rbe ros re alm is acce s s ible .
[root@server ~]# kinit admin
13. Te s t the IdM configuration by running a command like ipa user-find. For e xample :
[root@server ~]# ipa user-find admin
-------------1 user matched
-------------User login: admin
Last name: Administrator
Home directory: /home/admin
Login shell: /bin/bash
UID: 939000000
GID: 939000000
Account disabled: False
Password: True
Kerberos keys available: True
---------------------------Number of entries returned 1
----------------------------

3.2.2. Basic Silent Non-Int eract ive Inst allat ion
To allow automate d and unatte nde d configuration, pas s the following bas ic re quire d
s e ttings dire ctly with the ipa-server-install utility:
the -r option give s the Ke rbe ros re alm name
the -p option give s the Dire ctory Manage r (DM) pas s word; DM is the Dire ctory Se rve r
s upe r us e r
the -a option give s the pas s word for the IdM adminis trator
The -U option force s the ins tallation to run unatte nde d without re quiring us e r inte raction.
Afte r you run ipa-server-install with the s e options , the s e tup s cript choos e s de fault
value s for othe r s e ttings , for e xample for the fully-qualifie d DNS name of the s e rve r or for
the DNS domain name . You can s upply cus tom value s for the othe r s e ttings by adding
additional options to ipa-server-install. For more information about available
argume nts , s e e Table 3.1, “ipa-server-install Options ” or the ipa-s e rve r-ins tall(1) man
page .

No te
If you pas s the s e s e ttings with ipa-server-install, the ins talle d IdM s e rve r will
not run a DNS s e rve r. For an e xample that de s cribe s ins talling the DNS s e rvice s ,
s e e Se ction 3.2.4, “Configuring DNS Se rvice s within the IdM Domain”.

32

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

Example 3.1. Basic Inst allat io n wit ho ut Int eract io n
1. Run the ipa-server-install utility, providing the re quire d s e ttings .
[root@server ~]# ipa-server-install -r EXAMPLE.COM -p
DM_password -a admin_password -U
2. The s e tup s cript now configure s all of the as s ociate d s e rvice s for IdM. Wait for
the ope ration to comple te .
The log file for this installation can be found in
/var/log/ipaserver-install.log
================================================================
==============
This program will set up the IPA Server.
This includes:
* Configure a stand-alone CA (dogtag) for certificate
management
* Configure the Network Time Daemon (ntpd)
* Create and configure an instance of Directory Server
* Create and configure a Kerberos Key Distribution Center
(KDC)
* Configure Apache (httpd)
The IPA Master Server will be configured with:
Hostname:
ipaserver.example.com
IP address(es): 2620:52:0:222f:21a:4aff:fe22:2114
Domain name:
example.com
Realm name:
EXAMPLE.COM
Configuring NTP daemon (ntpd)
[1/4]: stopping ntpd
[2/4]: writing configuration
...
Done.
Restarting the directory server
Restarting the KDC
Restarting the certificate server
Sample zone file for bind has been created in
/tmp/sample.zone._mS240.db
Restarting the web server
================================================================
==============
Setup complete
...
3. Comple te the s e tup proce s s and ve rify that e ve rything is working as e xpe cte d,
as de s cribe d in Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.

33

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

3.2.3. Inst alling wit h Dif f erent CA Conf igurat ions
Ide ntity Manage me nt us e s an inte grate d ce rtificate authority (CA) to cre ate the ce rtificate s
and ke ytabs us e d by us e rs and hos ts within the domain. Eve n inte rnal domain s e rvice s ,
s uch as the LDAP s e rve r and the Apache s e rve r for the IdM we b UI, re quire s e rve r
ce rtificate s to e s tablis h s e cure conne ctions with e ach othe r.
In mos t de ployme nts , a Re d Hat Ce rtificate Sys te m CA is ins talle d with the IdM s e rve r.
Ce rtificate Sys te m us e s a CA signing certificate to cre ate and s ign all of the s e rve r and
us e r ce rtificate s cre ate d within the IdM domain. The CA s igning ce rtificate is its e lf re quire d
to be s igne d by the CA that is s ue d it. The Ce rtificate Sys te m CA s igning ce rtificate can be
s igne d in two diffe re nt ways :
T he Cert if icat e Syst em is a root CA
The root CA is the highe s t CA in the CA hie rarchy, and it is s e lf-s igne d. If the
Ce rtificate Sys te m is a root CA, it can s ign its own ce rtificate . The root CA can
als o s e t its own ce rtificate policie s .
This is the de fault IdM configuration.
T he Cert if icat e Syst em CA is signed by an ext ernally-ho st ed CA
The Ce rtificate Sys te m can be s ubordinate to an e xte rnal CA in the CA hie rarchy.
The e xte rnal CA can be a corporate CA or a third-party CA like Ve ris ign or Thawte .
In s uch de ployme nts , the e xte rnal CA is the root CA. The ce rtificate s is s ue d
within the IdM domain are pote ntially s ubje ct to re s trictions s e t by the e xte rnal
root CA for attribute s like the validity pe riod.
Eve n whe n the root CA is an e xte rnal CA, a Re d Hat Ce rtificate Sys te m ins tance
is s till us e d to is s ue all of the IdM domain ce rtificate s , that is , all of the IdM clie nt
and re plica ce rtificate s . The only diffe re nce is that the initial CA ce rtificate is not
is s ue d by the Ce rtificate Sys te m CA but by a diffe re nt CA.
Anothe r configuration option is to ins tall IdM without a CA.
A CA-less IdM inst allat io n
In ve ry rare cas e s , it may not be pos s ible to ins tall ce rtificate s e rvice s with the
IdM s e rve r. In s uch s ituations , you can ins tall IdM without an inte grate d Re d Hat
Ce rtificate Sys te m ins tance , as long as all re quire d ce rtificate s are cre ate d and
ins talle d inde pe nde ntly.
Ins talling without a CA re quire s that all ce rtificate s us e d within the IdM domain be
cre ate d, uploade d, and re ne we d manually. The additional mainte nance burde n
might be s us tainable in s ome e nvironme nts be caus e of othe r re s trictions within
the infras tracture . Howe ve r, mos t de ployme nts us e an inte grate d
Ce rtificate Sys te m ins tance toge the r with the certmonger utility to manage IdM
domain ce rtificate s .

3.2.3.1. Inst alling wit h an Int ernal Root CA
Having the Re d Hat Ce rtificate Sys te m as a root CA is the de fault configuration and no
additional parame te rs or configuration s te ps are re quire d whe n ipa-server-install is
run. No additional argume nts are re quire d to be adde d to the ipa-server-install utility
to ins tall a Ce rtificate Sys te m ins tance as the root CA, be caus e the ipa-server-install
s e tup s cript automatically configure s the Ce rtificate Sys te m CA.

34

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

[root@server ~]# ipa-server-install
The log file for this installation can be found in /var/log/ipaserverinstall.log
========================================================================
======
This program will set up the IPA Server.
This includes:
* Configure a stand-alone CA (dogtag) for certificate management
* Configure the Network Time Daemon (ntpd)
* Create and configure an instance of Directory Server
* Create and configure a Kerberos Key Distribution Center (KDC)
* Configure Apache (httpd)
...
Configuring certificate server (pki-tomcatd): Estimated time 3 minutes
30 seconds
[1/27]: creating certificate server user
[2/27]: configuring certificate server instance
...

No te
For de taile d de s criptions for ins talling an IdM s e rve r with an inte rnal root CA, s e e
Se ction 3.2.1, “Bas ic Inte ractive Ins tallation” and Se ction 3.2.2, “Bas ic Sile nt NonInte ractive Ins tallation”.

3.2.3.2. Inst alling Using an Ext ernal CA
To ins tall an IdM s e rve r that us e s an e xte rnal CA, add the --external-ca option to the
ipa-server-install utility. You are the n re quire d to s ubmit the ge ne rate d ce rtificate
re que s t to the e xte rnal CA and to load the CA ce rtificate and the is s ue d s e rve r ce rtificate
to comple te the s e tup.

No te
The following proce dure s hows us ing the --external-ca option in the inte ractive
ins tallation proce s s , othe rwis e de s cribe d in Se ction 3.2.1, “Bas ic Inte ractive
Ins tallation”. You can us e --external-ca als o with the non-inte ractive ins tallation
that is de s cribe d in Se ction 3.2.2, “Bas ic Sile nt Non-Inte ractive Ins tallation”.
1. Add the --external-ca to the ipa-server-install command.
[root@server ~]# ipa-server-install --external-ca
The s cript configure s the as s ociate d s e rvice s for IdM, s uch as NTP and
Dire ctory Se rve r, as us ual. Wait for the ope ration to comple te .

35

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
The ipa-server-install utility can s ome time s fail with the following e rror:
ipa
: CRITICAL failed to configure ca instance
Command '/usr/sbin/pkispawn -s CA -f /tmp/configuration_file'
returned non-zero exit status 1
Configuration of CA failed
This failure occurs whe n the *_proxy e nvironme ntal variable s are s e t. For a
s olution on how to fix this proble m, s e e Se ction 3.2.3.5, “Uns e tting the
*_proxy Environme ntal Variable s ”

2. Afte r the s cript comple te s the s e tup, it re turns the location of the ce rtificate s igning
re que s t (CSR) in the /root/ipa.csr file and prints ins tructions for how to configure
the IdM s e rve r to us e an e xte rnal CA.
...
Configuring certificate server (pki-tomcatd): Estimated time 3
minutes 30 seconds
[1/8]: creating certificate server user
[2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run
/sbin/ipa-server-install as: /sbin/ipa-server-install --externalcert-file=/path/to/signed_certificate --external-certfile=/path/to/external_ca_certificate
The CSR is a re que s t for a CA s igning ce rtificate for the IdM s e rve r s o that the
s e rve r can is s ue ce rtificate s within the IdM domain.
3. Submit the CSR locate d in /root/ipa.csr to the e xte rnal CA. The proce s s diffe rs
de pe nding on the s e rvice to be us e d as the e xte rnal CA.

Impo rtant
It might be ne ce s s ary to re que s t the appropriate e xte ns ions for the
ce rtificate . The CA s igning ce rtificate ge ne rate d for the Ide ntity Manage me nt
s e rve r mus t be a valid CA ce rtificate . This re quire s e ithe r that the Bas ic
Cons traint be s e t to CA=true or that the Ke y Us age Exte ns ion be s e t on the
s igning ce rtificate to allow it to s ign ce rtificate s .
4. Re trie ve the is s ue d ce rtificate and the CA ce rtificate chain for the is s uing CA in a
bas e 64-e ncode d blob (e ithe r a PEM file or a Bas e _64 ce rtificate from a Windows
CA). Again, the proce s s diffe rs for e ve ry ce rtificate s e rvice . Us ually, a download link
on a we b page or in the notification e mail allows the adminis trator to download all
the re quire d ce rtificate s .

36

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

Impo rtant
Be s ure to ge t the full ce rtificate chain for the CA, not jus t the CA ce rtificate .
5. Run ipa-server-install again, this time s pe cifying the locations and name s of
the ne wly-is s ue d CA ce rtificate and the CA chain file s . For e xample :
[root@server ~]# ipa-server-install --external-certfile=/tmp/servercert20110601.pem --external-certfile=/tmp/cacert.pem
6. Comple te the s e tup proce s s and ve rify that e ve rything is working as e xpe cte d, as
de s cribe d in Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.

3.2.3.3. Inst alling wit hout a CA
A CA-le s s ins tallation re quire s you to provide :
An LDAP s e rve r ce rtificate and a private ke y
An Apache s e rve r ce rtificate and a private ke y
Full CA ce rtificate chain of the CA that is s ue d the LDAP and Apache s e rve r ce rtificate s
The s e ce rtificate s mus t be re que s te d from a third-party authority be fore be ginning the
ins tallation proce s s .
The re are s ome important limitations with how ce rtificate s can be manage d whe n the re is
no inte grate d Re d Hat Ce rtificate Sys te m ins tance :
certmonger is not us e d to track ce rtificate s , s o the re is no e xpiration warning.
It is not pos s ible to re ne w ce rtificate s through Ide ntity Manage me nt.
The ce rtificate manage me nt tools (ipa cert-*) cannot be us e d to vie w or manage
ce rtificate s .
All hos t ce rtificate s and any s e rvice ce rtificate s mus t be re que s te d, ge ne rate d, and
uploade d manually. This als o affe cts how hos t manage me nt tools like ipa host-add
function.
If a ce rtificate is re move d from an e ntry, it is not automatically re voke d.
Four or five options are re quire d with the ipa-server-install or ipa-replica-prepare
commands whe n ins talling without a CA to pas s the ne ce s s ary ce rtificate s dire ctly to the
s e tup proce s s :
LDAP s e rve r ce rtificate and a private ke y
--dirsrv-cert-file give s the ce rtificate and private ke y file s for the LDAP s e rve r
ce rtificate
--dirsrv-pin give s the pas s word to acce s s the private ke y in the file s s pe cifie d in
--dirsrv-cert-file
Apache s e rve r ce rtificate and private ke y

37

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

--http-cert-file give s the ce rtificate and private ke y file s for the Apache s e rve r
ce rtificate
--http-pin give s the pas s word to acce s s the private ke y in the file s s pe cifie d in -http-cert-file
Full CA ce rtificate chain of the CA that is s ue d the LDAP and Apache s e rve r ce rtificate s
--dirsrv-cert-file and --http-cert-file can give ce rtificate file s with the full
CA ce rtificate chain or a part of it
--ca-cert-file give s ce rtificate file s to comple te the full CA ce rtificate chain, if
ne e de d

No te
The s e five options are incompatible with the --external-ca option.
The --dirsrv-cert-file and --http-cert-file options can be s pe cifie d multiple time s .
The y acce pt:
PEM-e ncode d and DER-e ncode d X.509 ce rtificate file s
PKCS#1 and PKCS#8 private ke y file s
PKCS#7 ce rtificate chain file s
PKCS#12 file s
The --ca-cert-file option can als o be s pe cifie d multiple time s . It acce pts :
PEM-e ncode d and DER-e ncode d X.509 ce rtificate file s
PKCS#7 ce rtificate chain file s
The file s provide d us ing --dirsrv-cert-file and --http-cert-file mus t contain
e xactly one s e rve r ce rtificate and e xactly one private ke y. The file s provide d us ing -dirsrv-cert-file and --http-cert-file combine d with the file s provide d us ing --cacert-file mus t contain the full CA ce rtificate chain of the CA that is s ue d the LDAP and
Apache s e rve r ce rtificate s .

No te
The conte nt of the file s provide d us ing --dirsrv-cert-file and --http-certfile is ofte n ide ntical.

Example 3.2. Inst alling Ident it y Management Wit ho ut a CA
Run ipa-server-install and pas s the re quire d ce rtificate s by s pe cifying the --httpcert-file, --http-pin, --dirsrv-cert-file, --dirsrv-pin options , and if ne e de d
als o --ca-cert-file. For e xample :

38

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

[root@server ~]# ipa-server-install --http-cert-file /tmp/server.crt -http-cert-file /tmp/server.key --http-pin secret --dirsrv-cert-file
/tmp/server.crt --dirsrv-cert-file /tmp/server.key --dirsrv-pin secret
--ca-cert-file ca.crt

No te
Earlie r ve rs ions of Ide ntity Manage me nt re quire d you to s upply the --root-ca-file
option, s pe cifying the PEM file of the root CA ce rtificate , during a CA-le s s ins tallation.
This is no longe r ne ce s s ary be caus e the trus te d CA is always the is s ue r of the DS
and HTTP s e rve r ce rtificate s . IdM now automatically re cogniz e s the root CA
ce rtificate from the ce rtificate s s pe cifie d by --dirsrv-cert-file, --http-certfile, and --ca-cert-file.
Both the --root-ca-file option and the othe r options us e d for a CA-le s s
ins tallation in e arlie r ve rs ions of IdM s till work to e ns ure backward compatibility.

3.2.3.4. Inst alling a CA Cert if icat e Manually
The ipa-cacert-manage utility allows you to ins tall a ne w ce rtificate to IdM. It e nable s you
to change the curre nt ce rtificate , for e xample whe n the ce rtificate is ne aring its validity
e xpiration date .
To manually ins tall a CA ce rtificate :
1. Run the ipa-cacert-manage install command and s pe cify the path to the file
containing the ce rtificate . The command acce pts PEM ce rtificate file s . For e xample :
[root@server ~]# ipa-cacert-manage install /etc/group/cert.pem
The ce rtificate is now pre s e nt in the LDAP ce rtificate s tore .
2. Run the ipa-certupdate utility, which update s clie nt s e rve rs with the information
about the ne w ce rtificate from LDAP. You have to run ipa-certupdate on e ve ry
clie nt s e parate ly.

Impo rtant
If you do not run ipa-certupdate afte r ins talling a ce rtificate manually, the
ce rtificate will not be dis tribute d to clie nts .
The ipa-cacert-manage install command can take the following options :
-n
give s the nickname of the ce rtificate ; the de fault value is the s ubje ct name of the
ce rtificate
-t

39

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

s pe cifie s the trus t flags for the ce rtificate in the certutil format; the de fault
value is C,,. For information about the format in which to s pe cify the trus t flags ,
s e e the ipa-cace rt-manage (1) man page .

3.2.3.5. Unset t ing t he *_proxy Environment al Variables
The *_proxy e nvironme ntal variable s can caus e the ipa-server-install --externalca command to fail with the following e rror:
ipa
: CRITICAL failed to configure ca instance Command
'/usr/sbin/pkispawn -s CA -f /tmp/configuration_file' returned non-zero
exit status 1
Configuration of CA failed
If you e xpe rie nce this e rror, de te rmine whe the r the variable s are caus ing it by us ing the
env utility:
env|grep proxy
http_proxy=http://example.com:8080
ftp_proxy=http://example.com:8080
https_proxy=http://example.com:8080
If running env|grep proxy re turns variable s s uch as the above , follow the s e s te ps to
s olve the proble m:
1. Us e the following s he ll s cript to uns e t the *_proxy e nvironme ntal variable s :
# for i in ftp http https; do unset ${i}_proxy; done
2. Run the pkidestroy utility to re move the uns ucce s s ful CA s ubs ys te m ins tallation:
# pkidestroy -s CA -i pki-tomcat; rm -rf /var/log/pki/pki-tomcat
/etc/sysconfig/pki-tomcat /etc/sysconfig/pki/tomcat/pki-tomcat
/var/lib/pki/pki-tomcat /etc/pki/pki-tomcat /root/ipa.csr
3. Re move the faile d IdM s e rve r ins tallation:
# ipa-server-install --uninstall
Afte r this , run ipa-server-install --external-ca again.

3.2.4. Conf iguring DNS Services wit hin t he IdM Domain
IdM can be ins talle d with its inte grate d DNS s e rve r. Ins talling an IdM-inte grate d DNS
s e rve r is re comme nde d for conve nie nce . Whe n ins talling IdM with an inte grate d DNS
s e rve r, make s ure to follow the pre re quis ite s de s cribe d in Se ction 2.4.2, “Hos t Name and
DNS Configuration”.

40

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

No te
You can als o ins tall DNS s e rvice s into an e xis ting IdM s e rve r us ing the ipa-dnsinstall utility. The re fore , if you ins tall an IdM s e rve r without inte grate d DNS, you
can add DNS s e rvice s late r. For more information, s e e Se ction 17.1, “Ins talling DNS
Se rvice s Into an Exis ting Se rve r”.

3.2.4.1. Inst alling wit h an Int egrat ed DNS Service Int eract ively
To ins truct the ipa-server-install s e tup s cript to configure the IdM s e rve r as a DNS
s e rve r inte ractive ly, add the --setup-dns option to ipa-server-install. During the
inte ractive ins tallation, the s e tup s cript prompts you for the re quire d DNS information.
Prior to running the s e tup s cript, de cide whe the r you want to us e DNS forwarding. If you
are uns ure , s e e Se ction 17.7, “Managing DNS Forwarding” be fore continuing. If you de cide
to us e DNS forwarding, ope n the /etc/resolv.conf file and note the IP addre s s e s in the
file ; you will ne e d the s e addre s s e s late r to s upply the m as DNS forwarde rs during
ins tallation.
1. Run the ipa-server-install utility with the --setup-dns option. The s cript
dis plays a lis t of s e rvice s to be ins talle d, including DNS.
[root@server ~]# ipa-server-install --setup-dns
2. The s cript prompts to ove rwrite the e xis ting BIND configuration. Ente r yes for the
ins tallation to proce e d.
Existing BIND configuration detected, overwrite? [no]: yes
3. The s cript prompts for s e ve ral re quire d s e ttings . Providing the m is de s cribe d in
Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.
4. The s cript the n prompts for DNS forwarde rs .
Do you want to configure DNS forwarders? [yes]:
Ans we r yes to configure the DNS forwarde rs . Whe n prompte d to s pe cify the
forwarde rs , provide the IP addre s s e s from the /etc/resolv.conf file . Note that
the forwarde r IP addre s s e s will be adde d to the /etc/named.conf file on the
ins talle d IdM s e rve r as global forwarde rs with the forward first policy.
If you do not want to us e DNS forwarding, e nte r no.
5. The s cript the n prompts for the re ve rs e DNS z one . Only cre ate the re ve rs e z one if
it doe s not e xis t on anothe r DNS s e rve r.
To cre ate a re ve rs e z one , e nte r yes, and the n s pe cify the re ve rs e z one name . If
you do not want to cre ate a re ve rs e z one , e nte r no.
Do you want to configure the reverse zone? [yes]:
Please specify the reverse zone name [2.0.192.in-addr.arpa.]:
Using reverse zone 2.0.192.in-addr.arpa.

41

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

6. The s cript dis plays the configuration s e ttings you provide d and prompts for
confirmation. Ente r yes for the ins tallation to proce e d.
Continue to configure the system with these values? [no]: yes
7. The s cript now configure s the IdM s e rve r. Wait for the ope ration to comple te .
8. Comple te the ipa-server-install s e tup proce s s and ve rify that e ve rything is
working as e xpe cte d, as e xplaine d in Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.

3.2.4.2. Inst alling wit h an Int egrat ed DNS Service Non-Int eract ively
To ins truct the ipa-server-install s e tup s cript to configure the IdM s e rve r as a DNS
s e rve r non-inte ractive ly, add the --setup-dns to ipa-server-install, and als o provide
the re quire d DNS information to the ipa-server-install s e tup s cript:
DNS f o rwarders
To configure DNS forwarde rs , us e the --forwarder option to add a DNS
forwarde r. To s pe cify multiple forwarde rs , us e --forwarder multiple time s .
If you want no e xte rnal forwarde rs to be us e d with the IdM DNS s e rvice , add the -no-forwarders option, indicating that only root DNS s e rve rs are us e d.

No te
Eithe r --forwarder or --no-forwarders is always re quire d.
reverse DNS zo nes
By de fault, the s cript automatically configure s a de fault value for the re ve rs e DNS
z one .
To ins truct ipa-server-install not to cre ate a re ve rs e DNS z one , us e the -no-reverse option.
The s e options provide the re quire d DNS s e ttings dire ctly to the ipa-server-install
s e tup s cript, which e ns ure s that the s cript doe s not prompt for the information during the
ins tallation proce s s .

No te
In the following proce dure , only the DNS s e ttings are provide d to ipa-serverinstall, not the othe r IdM s e rve r s e ttings . The re fore , the s cript in the proce dure
s till re quire s s ome input from the us e r.
To achie ve a comple te ly automate d and unatte nde d ins tallation, als o provide the
re quire d IdM s e rve r s e ttings dire ctly to ipa-server-install, as de s cribe d in
Se ction 3.2.2, “Bas ic Sile nt Non-Inte ractive Ins tallation”.

To ins tall an IdM s e rve r with an inte grate d DNS s e rvice non-inte ractive ly, providing the
re quire d DNS information dire ctly to the s e tup s cript:

42

⁠C hapt e r 3. Ins t alling and Unins t alling an IdM Se r ve r

1. Run the ipa-server-install utility with the --setup-dns option, and add any
additional options that are re quire d to pas s the DNS s e ttings . The s cript dis plays a
[root@server ~]# ipa-server-install --setup-dns -forwarder=1.2.3.0 --forwarder=1.2.255.0 --no-reverse
The log file for this installation can be found in
/var/log/ipaserver-install.log
==================================================================
============
This program will set up the IPA Server.
This includes:
* Configure a stand-alone CA (dogtag) for certificate management
* Configure the Network Time Daemon (ntpd)
* Create and configure an instance of Directory Server
* Create and configure a Kerberos Key Distribution Center (KDC)
* Configure Apache (httpd)
* Configure DNS (bind)
...
2. The s cript prompts to ove rwrite the e xis ting BIND configuration. Ente r yes for the
ins tallation to proce e d.
Existing BIND configuration detected, overwrite? [no]: yes
3. The s cript the n prompts for s e ve ral s e ttings re quire d to configure the IdM s e rve r.
Providing the m is de s cribe d in Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.
4. The s cript dis plays the configuration s e ttings you provide d and prompts for
confirmation. Ente r yes for the ins tallation to proce e d.
Continue to configure the system with these values? [no]: yes
5. The s cript now configure s the IdM s e rve r. Wait for the ope ration to comple te .
6. Comple te the s e tup proce s s and ve rify that e ve rything is working as e xpe cte d, as
de s cribe d in Se ction 3.2.1, “Bas ic Inte ractive Ins tallation”.

3.3. Uninst alling an IdM Server
To unins tall an IdM s e rve r, add the --uninstall option to the ipa-server-install utility:
[root@server ~]# ipa-server-install --uninstall

No te
The proce dure for unins talling an IdM re plica is diffe re nt from unins talling a s e rve r.
For information about unins talling a re plica, s e e Se ction 31.2, “Re moving a Re plica”.

43

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 4. Set t ing up IdM Replicas
Re plicas are cre ate d by cloning the configuration of e xis ting Ide ntity Manage me nt s e rve rs ;
the re fore , s e rve rs and the ir re plicas s hare ide ntical core configuration. The re plica
ins tallation proce s s cons is ts of two phas e s :
1. Copying the e xis ting s e rve r configuration
2. Ins talling the re plica bas e d on the copie d configuration
Maintaining s e ve ral s e rve r re plicas is a re comme nde d backup s olution to avoid data los s ,
as de s cribe d in the "Backup and Re s tore in IdM/IPA" Knowle dge bas e s olution.

No te
Anothe r backup s olution, re comme nde d primarily for s ituations whe n re building the
IdM de ployme nt from re plicas is not pos s ible , is the ipa-backup utility, as de s cribe d
in Chapte r 8, Backing Up and Restoring Identity Management.

4.1. Planning t he Server and Replica T opologies
Thre e type s of machine s e xis t in the IdM domain:
Servers
Se rve rs manage all of the s e rvice s us e d by domain me mbe rs .
Replicas
Re plicas are copie s of s e rve rs . Once a re plica is ins talle d, it is functionally
ide ntical to a s e rve r.
Client s
Clie nts , which be long to the Ke rbe ros domains , re ce ive ce rtificate s and ticke ts
is s ue d by the s e rve rs , and us e othe r ce ntraliz e d s e rvice s for authe ntication and
authoriz ation.
Se rve rs and re plicas cre ate d from the s e s e rve rs s hare the s ame inte rnal information
about us e rs , machine s , ce rtificate s , and configure d policie s . This data is copie d from the
s e rve r to the re plica in a proce s s calle d replication.
An IdM s e rve r us e s a s ingle Dire ctory Se rve r ins tance . The ins tance is us e d by the IdM
s e rve r as a data s tore and by the Re d Hat Ce rtificate Sys te m to s tore ce rtificate
information. During re plication, this ins tance is re plicate d ove r to corre s ponding cons ume r
Dire ctory Se rve r ins tance us e d by the IdM re plica, with re plication agre e me nts manage d
s e parate ly for the re alm data and for the ce rtificate data.

44

⁠C hapt e r 4 . Se t t ing up IdM Re plic as

Figure 4.1. Server and Replica Agreement s
We re comme nd that you follow the s e guide line s whe n planning your s e rve r and re plica
topology:
Configure no more than four re plication agre e me nts on a s ingle s e rve r or re plica.
Do not involve more than 20 s e rve rs and re plicas in a s ingle Ide ntity Manage me nt
domain.
Configure a minimum of two re plication agre e me nts for e ve ry s e rve r or re plica. This
e ns ure s that no orphan s e rve rs or re plicas are cut out of the IdM domain if anothe r
s e rve r fails .
One of the mos t re s ilie nt topologie s is to cre ate a ce ll configuration for the s e rve rs and
re plicas with a s mall numbe r of s e rve rs in a ce ll. Each of the s e ce lls is a tight cell,
me aning that all the s e rve rs ins ide have re plication agre e me nts with e ach othe r. In
addition, e ach s e rve r has one re plication agre e me nt with anothe r s e rve r outside the ce ll,
loos e ly coupling that ce ll to e ve ry othe r ce ll in the ove rall domain.
To accomplis h this re s ilie nt ce ll topology, you can follow the s e re comme ndations :
Have at le as t one IdM s e rve r in e ach main office , data ce nte r, or locality. Pre fe rably,
have two IdM s e rve rs .
Do not have more than four s e rve rs pe r data ce nte r.
Rathe r than us ing a s e rve r or re plica, s mall office s can us e SSSD to cache cre de ntials
and us e an off-s ite IdM s e rve r as its data back e nd.

4.2. Prerequisit es for Inst alling a Replica Server

45

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The ins tallation re quire me nts and package s for re plicas are the s ame as for IdM s e rve rs .
Make s ure that the machine on which re plicas is to be ins talle d me e ts all of the
pre re quis ite s lis te d in Chapte r 2, Prerequisites for Installation.
In addition to the ge ne ral s e rve r re quire me nts , the following conditions mus t als o be me t
whe n ins talling a re plica:
T he replica must be running t he same o r lat er versio n o f IdM
For e xample , if the mas te r s e rve r is running on Re d Hat Ente rpris e Linux 7 and
us e s the IdM 4.1 package s , the n the re plica mus t als o run on Re d Hat
Ente rpris e Linux 7 or late r and us e IdM ve rs ion 4.1 or late r. This e ns ure s that
configuration can be prope rly copie d from the s e rve r to the re plica.

Impo rtant
IdM doe s not s upport cre ating a re plica of an e arlie r ve rs ion than the
ve rs ion of the mas te r. If you try to cre ate a re plica us ing an e arlie r ve rs ion,
the ins tallation fails during the atte mpt to configure the Re d Hat
Dire ctory Se rve r ins tance .
T he replica requires addit io nal po rt s t o be o pen
In addition to the s tandard IdM s e rve r port re quire me nts de s cribe d in
Se ction 2.4.4, “Sys te m Ports ”, make s ure the following port re quire me nts are
complie d as we ll:
During the re plica s e tup proce s s , ke e p the TCP port 22 ope n. This port is
re quire d in orde r to us e SSH to conne ct to the mas te r s e rve r.
If one of the s e rve rs is running Re d Hat Ente rpris e Linux 6 and has a CA
ins talle d, ke e p als o TCP port 7389 ope n during and afte r the re plica
configuration. In a pure ly Re d Hat Ente rpris e Linux 7 e nvironme nt, port 7389 is
not re quire d.

No te
The ipa-replica-install s cript include s the ipa-replica-conncheck
utility that ve rifie s the s tatus of the re quire d ports . You can als o run ipareplica-conncheck s e parate ly for trouble s hooting purpos e s . For
information on how to us e the utility, s e e the ipa-re plica-connche ck(1) man
page .
For information on how to ope n ports us ing the firewall-cmd utility, s e e
Se ction 2.4.4, “Sys te m Ports ”.
If t he replica manages cert if icat e request s, it must use t he same CA
co nf igurat io n as t he server
For e xample , if the s e rve r is its own root CA (us ing Re d Hat Ce rtificate Sys te m),
the n that mus t be the root CA for the re plica; if the s e rve r us e d an e xte rnal CA to
is s ue its ce rtificate s , the n the re plica mus t us e that s ame e xte rnal CA; and if the
s e rve r was ins talle d without a CA by providing the re quire d ce rtificate s manually,
the s ame ce rtificate s mus t be provide d whe n ins talling the re plica.

46

⁠C hapt e r 4 . Se t t ing up IdM Re plic as

4.3. Creat ing t he Replica
The package re quire me nts for IdM re plicas are the s ame as for IdM s e rve rs :
the ipa-server package
the ipa-server-dns package if you want the re plica to als o hos t DNS s e rvice s
During the re plica cre ation proce s s , the ipa-replica-prepare utility cre ate s a replica
information file name d afte r the re plica s e rve r in the /var/lib/ipa/ dire ctory. The
re plica information file is a GPG-e ncrypte d file containing re alm and configuration
information for the mas te r s e rve r.
The ipa-replica-install re plica s e tup s cript configure s a Dire ctory Se rve r ins tance
bas e d on the information containe d in the re plica information file and initiate s the replica
initialization proce s s , during which the s cript copie s ove r data from the mas te r s e rve r to
the re plica. A re plica information file can only be us e d to ins tall a re plica on the s pe cific
machine for which it was cre ate d. It cannot be us e d to cre ate multiple re plicas on multiple
machine s .
While much of the core configuration of the re plica is ide ntical to the configuration of the
initial s e rve r, s uch as the re alm name and dire ctory s e ttings , s e rvice s on the re plica and
on the s e rve r are not re quire d to match: the re plica doe s not have to manage the s ame
s e rvice s as the s e rve r. For e xample , it is pos s ible to ins tall a re plica without DNS from a
s e rve r that runs the DNS s e rvice s or to ins tall a re plica without a CA or without NTP.

No te
The following proce dure s and e xample s are not mutualy e xclus ive ; it is pos s ible to
us e the CA, DNS, and othe r configuration options s imultane ous ly. Example s in the
following s e ctions are calle d out s e parate ly s imply to make it more cle ar what e ach
configuration are a re quire s .

4.3.1. Inst alling a Replica wit hout DNS
1. On the master IdM server, run the ipa-replica-prepare utility and add the fullyqualifie d domain name (FQDN) of the replica machine . Note that the ipa-replicaprepare s cript doe s not validate the IP addre s s or ve rify if the IP addre s s of the
re plica is re achable by othe r s e rve rs .

Impo rtant
The fully-qualifie d domain name mus t be a valid DNS name , which me ans
only numbe rs , alphabe tic characte rs , and hyphe ns (-) are allowe d. Othe r
characte rs , like unde rs core s , in the hos t name caus e DNS failure s .
Additionally, the hos t name mus t be all lowe r-cas e ; no capital le tte rs are
allowe d. For othe r re comme nde d naming practice s , s e e the Re d Hat
Ente rpris e Linux Se curity Guide .
If the mas te r s e rve r is configure d with inte grate d DNS, s pe cify the IP addre s s of
the re plica machine us ing the --ip-address option. The ins tallation s cript the n
as ks if you want to configure the re ve rs e z one for the re plica. Only pas s --ip-

47

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

address if the IdM s e rve r was configure d with inte grate d DNS. Othe rwis e , the re is
no DNS re cord to update , and the atte mpt to cre ate the re plica fails whe n the DNS
re cord ope ration fails .
Ente r the initial mas te r s e rve r's Dire ctory Manage r (DM) pas s word whe n prompte d.
The output of ipa-replica-prepare dis plays the location of the re plica information
file . For e xample :
[root@server ~]# ipa-replica-prepare replica.example.com --ipaddress 192.0.2.0
Directory Manager (existing master) password:
Do you want to configure the reverse zone? [yes]: no
Preparing replica for replica.example.com from server.example.com
Creating SSL certificate for the Directory Server
Creating SSL certificate for the dogtag Directory Server
Saving dogtag Directory Server port
Creating SSL certificate for the Web Server
Exporting RA certificate
Copying additional files
Finalizing configuration
Packaging replica information into /var/lib/ipa/replica-inforeplica.example.com.gpg
Adding DNS records for replica.example.com
Waiting for replica.example.com. A or AAAA record to be resolvable
This can be safely interrupted (Ctrl+C)
The ipa-replica-prepare command was successful

Warning
Re plica information file s contain s e ns itive information. Take appropriate s te ps
to e ns ure that the y are prope rly prote cte d.
For othe r options that can be adde d to ipa-replica-prepare, s e e the ipa-re plicapre pare (1) man page .
2. On the replica machine, ins tall the ipa-server package .
[root@replica ~]# yum install ipa-server
3. Copy the re plica information file from the initial s e rve r to the re plica machine :
[root@server ~]# scp /var/lib/ipa/replica-inforeplica.example.com.gpg root@replica:/var/lib/ipa/
4. On the replica machine, run the ipa-replica-install utility and add the location of
the re plication information file to s tart the re plica initializ ation proce s s . Ente r the
original mas te r s e rve r's Dire ctory Manage r and admin pas s words whe n prompte d,
and wait for the re plica ins tallation s cript to comple te .
[root@replica ~]# ipa-replica-install /var/lib/ipa/replica-inforeplica.example.com.gpg
Directory Manager (existing master) password:

48

⁠C hapt e r 4 . Se t t ing up IdM Re plic as

Run connection check to master
Check connection from replica to remote master
'server.example.com':
...
Connection from replica to master is OK.
Start listening on required ports for remote master check
Get credentials to log in to remote master
admin@MASTER.EXAMPLE.COM password:
Check SSH connection to remote master
...
Connection from master to replica is OK.
...
Configuring NTP daemon (ntpd)
[1/4]: stopping ntpd
[2/4]: writing configuration
...
Restarting Directory server to apply updates
[1/2]: stopping directory server
[2/2]: starting directory server
Done.
Restarting the directory server
Restarting the KDC
Restarting the web server

No te
If the re plica file be ing ins talle d doe s not match the curre nt hos t name , the
re plica ins tallation s cript dis plays a warning me s s age and as ks for
confirmation. In s ome cas e s , s uch as on multi-home d machine s , you can
confirm to continue with the mis matche d hos t name s .
For command-line options that can be adde d to ipa-replica-install, s e e the ipare plica-pre pare (1) man page . Note that one of the options ipa-replica-install
acce pts is the --ip-address option. Whe n adde d to ipa-replica-install, --ipaddress only acce pts IP addre s s e s as s ociate d with the local inte rface .

4.3.2. Inst alling a Replica wit h DNS
To ins tall a re plica with inte grate d DNS, follow the proce dure for ins talling without DNS
de s cribe d in Se ction 4.3.1, “Ins talling a Re plica without DNS”, but add the following options
to the ipa-replica-install utility:
--setup-dns

49

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The --setup-dns option cre ate s a DNS z one if it doe s not e xis t alre ady and
configure s the re plica as the DNS s e rve r.
--forwarder o r --no-forwarders
To s pe cify a DNS forwarde r, us e the --forwarder option. To s pe cify multiple
forwarde rs , us e --forwarder multiple time s .
If you do not want to s pe cify any forwarde rs , us e the --no-forwarders option.
For e xample :
[root@replica ~]# ipa-replica-install /var/lib/ipa/replica-inforeplica.example.com.gpg --setup-dns --forwarder 198.51.100.0

No te
You can s e t up the re plica to s e rve as the DNS s e rve r e ve n if the initial mas te r
s e rve r was not ins talle d with inte grate d DNS.
The ipa-replica-install utility acce pts a numbe r of othe r options re late d to DNS
s e ttings , s uch as the --no-reverse or --no-host-dns options . For more information
about the m, s e e the ipa-re plica-ins tall(1) man page .
If you ins tall a re plica without DNS, you can s e t it up as the DNS s e rve r late r us ing the
ipa-dns-install utility, as de s cribe d in Se ction 17.1, “Ins talling DNS Se rvice s Into an
Exis ting Se rve r”, and add the DNS re cords manually, as de s cribe d in Se ction 17.5.4,
“Adding Re cords to DNS Zone s ”.

Verif ying t he DNS Records
Afte r ins talling a ne w re plica, you can make s ure that prope r DNS e ntrie s we re cre ate d s o
that IdM clie nts can dis cove r the ne w s e rve r. The following DNS re cords are ne ce s s ary for
re quire d domain s e rvice s :
_ldap._tcp
_kerberos._tcp
_kerberos._udp
_kerberos-master._tcp
_kerberos-master._udp
_ntp._udp
_kpasswd._tcp
_kpasswd._udp
If the initial IdM s e rve r was cre ate d with DNS e nable d, the n the re plica is automatically
cre ate d with the prope r DNS e ntrie s . To ve rify the e ntrie s are pre s e nt, follow this
e xample :
[root@replica ~]# DOMAIN=example.com

50

⁠C hapt e r 4 . Se t t ing up IdM Re plic as

[root@ipareplica ~]# NAMESERVER=replica
[root@ipareplica ~]# for i in _ldap._tcp _kerberos._tcp _kerberos._udp
_kerberos-master._tcp _kerberos-master._udp _ntp._udp; do echo ""; dig
@${NAMESERVER} ${i}.${DOMAIN} srv +nocmd +noquestion +nocomments
+nostats +noaa +noadditional +noauthority; done | egrep -v "^;" | egrep
_
_ldap._tcp.example.com. 86400
IN
server1.example.com.
_ldap._tcp.example.com. 86400
IN
server2.example.com.
_kerberos._tcp.example.com. 86400 IN
server1.example.com.
...

SRV

0 100 389

SRV

0 100 389

SRV

0 100 88

4.3.3. Inst alling a Replica wit h Various CA Conf igurat ions
While an inte grate d Re d Hat Ce rtificate Sys te m CA ins tance or a CA-le s s s e rve r
ins tallation are re quire d for mas te r s e rve rs , the y are only optional for re plicas . A re plica
can be s e t up without the ce rtificate s e rvice s , in which cas e it forwards all re que s ts for
ce rtificate ope rations to the initial mas te r s e rve r.

Warning
If only one s e rve r in the whole IdM de ployme nt has a CA ins talle d, the CA
configuration is los t if this s e rve r fails without any chance for re cove ry.
If you choos e to s e t up a CA on the re plica, the CA configuration on the re plica mus t mirror
the CA configuration of the s e rve r.

Inst alling a replica f rom a server wit h a Cert if icat e Syst em CA inst alled
To s e t up a CA on the re plica whe n the initial s e rve r was configure d with an inte grate d
Re d Hat Ce rtificate Sys te m ins tance (re gardle s s of whe the r it was a root CA or whe the r it
was s ubordinate to an e xte rnal CA), follow the bas ic ins tallation proce dure de s cribe d in
Se ction 4.3.1, “Ins talling a Re plica without DNS”, but add the --setup-ca option to the ipareplica-install utility. The --setup-ca option copie s the CA configuration from the
initial s e rve r's configuration.
[root@replica ~]# ipa-replica-install /var/lib/ipa/replica-inforeplica.example.com.gpg --setup-ca

Inst alling a replica f rom a server wit hout a Cert if icat e Syst em CA
inst alled
For a CA-le s s re plica ins tallation, follow the bas ic proce dure de s cribe d in Se ction 4.3.1,
“Ins talling a Re plica without DNS”, but add the following options whe n running the ipareplica-prepare utility on the initial s e rve r:
--dirsrv-cert-file
--dirsrv-pin

51

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

--http-cert-file
--http-pin
Do not add the --ca-cert-file option to ipa-replica-prepare; the utility take s this part
of the ce rtificate information automatically from the mas te r s e rve r. For de taile d
information about the file s that are provide d us ing the s e four options , s e e Se ction 3.2.3.3,
“Ins talling without a CA”.
For e xample :
[root@server ~]# ipa-replica-prepare replica.example.com --dirsrv-certfile /tmp/server.key --dirsrv-pin secret --http-cert-file
/tmp/server.crt --http-cert-file /tmp/server.key --http-pin secret -dirsrv-cert-file /tmp/server.crt

4.3.4. Inst alling a Replica wit h Ot her Set t ings
The ipa-replica-install utility acce pts a numbe r of othe r configuration options , s uch
as :
--no-ntp s pe cifie s that the re plica is configure d without the NTP s e rvice
--no-ssh s pe cifie s that no Ope nSSH clie nt is configure d on the re plica
--no-sshd s pe cifie s that the re plica is configure d without the Ope nSSH s e rve r
For a comple te lis t of the ipa-replica-install configuration options , s e e the ipa-re plicains tall(1) man page .

4.3.5. T est ing t he New Replica
To ve rify that re plication works afte r cre ating a ne w re plica, you can cre ate a us e r on one
of the s e rve rs and the n make s ure the us e r is vis ible on the othe r s e rve r. For e xample :
[root@master_server ~]$ ipa user-add test_user --first=Test --last=User
[root@replica_server ~]$ ipa user-show test_user

4.4. Adding Addit ional Replicat ion Agreement s
Ins talling a re plica us ing ipa-replica-install cre ate s an initial re plication agre e me nt
be twe e n the mas te r s e rve r and the re plica. To conne ct the re plica to othe r s e rve rs or
re plicas , add additional agre e me nts us ing the ipa-replica-manage utility.
If the mas te r s e rve r and the ne w re plica have a CA ins talle d, a re plication agre e me nt for
CA is als o cre ate d. To add additional CA re plication agre e me nts to othe r s e rve rs or
re plicas , us e the ipa-cs-replica-manage utility.
For more information on cre ating re plication agre e me nts , s e e Se ction 31.1.5, “Cre ating
Re plication Agre e me nts ”.

4.5. Uninst alling an IdM Replica
For information on how to unins tall an IdM Re plica, s e e Se ction 31.2, “Re moving a Re plica”.

52

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

Chapt er 5. Set t ing up Syst ems as IdM Client s
A client is any s ys te m which is a me mbe r of the Ide ntity Manage me nt domain. While this
is fre que ntly a Re d Hat Ente rpris e Linux s ys te m (and IdM has s pe cial tools to make
configuring Re d Hat Ente rpris e Linux clie nts ve ry s imple ), machine s with othe r ope rating
s ys te ms can als o be adde d to the IdM domain.
One important as pe ct of an IdM clie nt is that only the s ys te m configuration de te rmine s
whe the r the s ys te m is part of the domain. (The configuration include s things like be longing
to the Ke rbe ros domain, DNS domain, and having the prope r authe ntication and ce rtificate
s e tup.)

No te
IdM doe s not re quire any s ort of age nt or dae mon running on a clie nt for the clie nt to
join the domain. Howe ve r, for the be s t manage me nt options , s e curity, and
pe rformance , clie nts s hould run the Sys te m Se curity Se rvice s Dae mon (SSSD).
For more information on SSSD, s e e the SSSD chapte r in the Sys te m-Le ve l
Authe ntication Guide .

This chapte r e xplains how to configure a s ys te m to join an IdM domain.

No te
Clie nts can only be configure d afte r at le as t one IdM s e rve r has be e n ins talle d.

5.1. What Happens in Client Set up
Whe the r the clie nt configuration is pe rforme d automatically on Re d Hat Ente rpris e Linux
s ys te ms us ing the clie nt s e tup s cript or manually on othe r s ys te ms , the ge ne ral proce s s
of configuring a machine to s e rve as an IdM clie nt is mos tly the s ame , with s light variation
de pe nding on the platform:
Re trie ve the CA ce rtificate for the IdM CA.
Cre ate a s e parate Ke rbe ros configuration to te s t the provide d cre de ntials .
This e nable s a Ke rbe ros conne ction to the IdM XML-RPC s e rve r, ne ce s s ary to join the
IdM clie nt to the IdM domain. This Ke rbe ros configuration is ultimate ly dis carde d.
Se tting up the Ke rbe ros configuration include s s pe cifying the re alm and domain de tails ,
and de fault ticke t attribute s . Forwardable ticke ts are configure d by de fault, which
facilitate s conne ction to the adminis tration inte rface from any ope rating s ys te m, and
als o provide s for auditing of adminis tration ope rations . For e xample , this is the
Ke rbe ros configuration for Re d Hat Ente rpris e Linux s ys te ms :
[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm = false

53

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

dns_lookup_kdc = false
rdns = false
forwardable = yes
ticket_lifetime = 24h
[realms]
EXAMPLE.COM = {
kdc = ipaserver.example.com:88
admin_server = ipaserver.example.com:749
}
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
Run the ipa-join command to pe rform the actual join.
Obtain a s e rvice principal for the hos t s e rvice and ins talls it into /etc/krb5.keytab.
For e xample , host/ipa.example.com@EXAMPLE.COM.
Enable certmonger, re trie ve an SSL s e rve r ce rtificate , and ins tall the ce rtificate in
/etc/pki/nssdb.
Dis able the ns cd dae mon.
Configure SSSD or LDAP/KRB5, including NSS and PAM configuration file s .
Configure an Ope nSSH s e rve r and clie nt, as we ll as e nabling the hos t to cre ate DNS
SSHFP re cords .
Configure NTP.

5.2. Opening t he IdM Required Syst em Port s
IdM us e s a numbe r of ports to communicate with its s e rvice s . The s e ports mus t be ope n
and available for IdM to work. For more information on which ports IdM re quire s , s e e
Se ction 2.4.4, “Sys te m Ports ”.
Ope ning ports re quire s the firewalld s e rvice to be running. To s tart firewalld as we ll
as to configure it to s tart automatically whe n the s ys te m boots :
[root@server ~]# systemctl start firewalld.service
[root@server ~]# systemctl enable firewalld.service
To ope n all the IdM re quire d ports in the de fault z one and make the change both
pe rmane nt and runtime :
1. Run the firewall-cmd command with the --permanent option s pe cifie d.
[root@server ~]# firewall-cmd --permanent --add-port=
{80/tcp,443/tcp,389/tcp,636/tcp,88/tcp,464/tcp,53/tcp,88/udp,464/u
dp,53/udp,123/udp}
2. Re load the firewall-cmd configuration to e ns ure that the change take s place
imme diate ly.
[root@server ~]# firewall-cmd --reload

54

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

5.3. Configuring a Linux Syst em as an IdM Client
The re are two e le me nts to pre pare be fore be ginning the clie nt s e tup proce s s for the
Re d Hat Ente rpris e Linux clie nt:
The re mus t be a way to conne ct the clie nt machine to the Ke rbe ros domain, e ithe r by
having an available Ke rbe ros ide ntity (s uch as the admin us e r) or by manually adding
the clie nt machine to the KDC on the s e rve r with a one -time pas s word be fore
be ginning the e nrollme nt proce s s for the clie nt machine .
If the re is an Active Dire ctory s e rve r on the s ame ne twork that s e rve s DNS re cords ,
the Active Dire ctory DNS re cords could pre ve nt the clie nt from automatically de te cting
the IdM s e rve r addre s s . The ipa-client-install s cript re trie ve s the Active Dire ctory
DNS re cords ins te ad of any re cords that we re adde d for IdM.
In this cas e , it is ne ce s s ary to pas s the IdM s e rve r addre s s dire ctly to the ipaclient-install s cript.

5.3.1. Inst alling t he Client (Full Example)
1. Ins tall the clie nt package s . The s e package s provide a s imple way to configure the
s ys te m as a clie nt; the y als o ins tall and configure SSSD.
For a re gular us e r s ys te m, this re quire s only the ipa-client package :
[root@client ~]# yum install ipa-client
An adminis trator machine re quire s the ipa-admintools package , as we ll:
[root@client ~]# yum install ipa-client ipa-admintools
2. Employ prope r DNS de le gation, and do not alte r resolv.conf on clie nts .

No te
If e ve ry machine in the domain will be an IdM clie nt, the n add the IdM s e rve r
addre s s to the DHCP configuration.
3. Run the ipa-client-install command, which s e ts up the IdM clie nt.
The command automatically s e ts a NIS domain name to the IdM domain name by
de fault. To configure the clie nt without s e tting a NIS domain name , add the --nonisdomain option. To s pe cify a cus tom NIS domain name , s pe cify it us ing the -nisdomain option.
The command als o automatically configure s the SSSD s e rvice as the data provide r
for the s udo s e rvice by de fault. To avoid this , add the --no-sudo option.
To update DNS with the clie nt machine 's IP addre s s , add the --enable-dnsupdates option. You s hould only us e --enable-dns-updates if the IdM s e rve r was
ins talle d with inte grate d DNS or if the DNS s e rve r on the ne twork acce pts DNS
e ntry update s with the GSS-TSIG protocol.

55

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

For information about othe r options that you can us e with ipa-client-install,
s e e the ipa-clie nt-ins tall(1) man page .
4. If prompte d, e nte r the domain name for the IdM DNS domain.
5. If prompte d, e nte r the fully-qualifie d domain name of the IdM s e rve r. Alte rnative ly,
us e the --server option with the clie nt ins tallation s cript to s upply the fullyqualifie d domain name of the IdM s e rve r.

Impo rtant
The fully-qualifie d domain name mus t be a valid DNS name , which me ans
only numbe rs , alphabe tic characte rs , and hyphe ns (-) are allowe d. Othe r
characte rs , like unde rs core s , in the hos t name caus e DNS failure s .
Additionally, the hos t name mus t be all lowe r-cas e ; no capital le tte rs are
allowe d. For othe r re comme nde d naming practice s , s e e the Re d Hat
Ente rpris e Linux Se curity Guide .
6. The clie nt s cript the n prompts for a Ke rbe ros ide ntity to us e to contact and the n join
the Ke rbe ros re alm. Whe n the s e cre de ntials are s upplie d, the n the clie nt is able to
join the IdM Ke rbe ros domain and the n comple te the configuration:
Continue to configure the system with these values? [no]: y
User authorized to enroll computers: admin
Synchronizing time with KDC...
Password for admin@EXAMPLE.COM:
Successfully retrieved CA cert
Subject: CN=Certificate Authority,O=EXAMPLE.COM
Issuer: CN=Certificate Authority,O=EXAMPLE.COM
Valid From: Tue Aug 13 09:29:07 2015 UTC
Valid Until: Sat Aug 13 09:29:07 2033 UTC
Enrolled in IPA realm EXAMPLE.COM
Created /etc/ipa/default.conf
New SSSD config will be created
Configured /etc/sssd/sssd.conf
Configured /etc/krb5.conf for IPA realm EXAMPLE.COM
Adding SSH public key from /etc/ssh/ssh_host_rsa_key.pub
Adding SSH public key from /etc/ssh/ssh_host_dsa_key.pub
SSSD enabled
Configured /etc/openldap/ldap.conf
NTP enabled
Configured /etc/ssh/ssh_config
Configured /etc/ssh/sshd_config
Client configuration complete.
7. Te s t that the clie nt can conne ct s ucce s s fully to the IdM domain and can pe rform
bas ic tas ks . For e xample , che ck that the IdM tools can be us e d to ge t us e r and
group information:
[jsmith@client ~]$ id
[jsmith@client ~]$ getent passwd admin
[jsmith@client ~]$ getent group admins

56

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

8. Run the ipa-client-automount command which automatically configure s NFS for
IdM. For more information on ipa-client-automount, s e e Se ction 18.2.1,
“Configuring NFS Automatically”.

5.3.2. Examples of Ot her Client Inst allat ion Opt ions
The re are a numbe r of diffe re nt configuration options with the ipa-client-install
command which can be us e d to configure the clie nt s ys te m in diffe re nt ways , de pe nding
on the infras tructure re quire me nts .

Example 5.1. Enabling DNS Updat es
De pe nding on the DHCP configuration, the IP addre s s e s of clie nts can change with s ome
re gularity. If the IP addre s s change s , this can caus e dis cre pancie s be twe e n the DNS
re cords in the IdM s e rve r and the actual IP addre s s e s in us e , which could affe ct policie s
s e t within IdM and communications be twe e n clie nts and s e rvice s .
The --enable-dns-updates option s e ts the Sys te m Se curity Se rvice s Dae mon to
update the DNS e ntrie s whe ne ve r the IP addre s s for a clie nt change s .
[root@client ~]# ipa-client-install --enable-dns-updates

Example 5.2. Specif ying Do main Inf o rmat io n
Whe n jus t running the clie nt ins tallation command, the s cript prompts for re quire d IdM
domain information, including the name of an IdM s e rve r to re gis te r with, the DNS
domain name , and the Ke rbe ros re alm and principal.
All of the bas ic information can be pas s e d with the ins tallation command (which is us e ful
for automate d ins tallations ).
--domain for the DNS domain name (which is only us e d if the IdM s e rve r is
configure d to hos t DNS s e rvice s )
--server for the IdM s e rve r to re gis te r with (which can be any s e rve r or re plica in
the topology)

Impo rtant
The fully-qualifie d domain name mus t be a valid DNS name , which me ans only
numbe rs , alphabe tic characte rs , and hyphe ns (-) are allowe d. Othe r characte rs ,
like unde rs core s , in the hos t name caus e DNS failure s . Additionally, the hos t
name mus t be all lowe r-cas e ; no capital le tte rs are allowe d. For othe r
re comme nde d naming practice s , s e e the Re d Hat Ente rpris e Linux Se curity
Guide .
--realm for the Ke rbe ros re alm name and, optionally, -p for a Ke rbe ros principal
name
[root@client ~]# ipa-client-install --domain EXAMPLE.COM --server
ipaserver.example.com --realm EXAMPLE -p host/server.example.com

57

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Example 5.3. Set t ing a Specif ic IdM Server
The re can be multiple s e rve rs and re plicas within the IdM s e rve r topology. Whe n a
clie nt ne e ds to conne ct to a s e rve r for update s or to re trie ve us e r information, it (by
de fault) us e s a s e rvice s can to dis cove r available s e rve rs and re plicas in the domain.
This me ans that the actual s e rve r to which the clie nt conne cts is random, de pe nding on
the re s ults of the dis cove ry s can.
It is pos s ible to s e t a s pe cific s e rve r within the IdM domain which is us e d for clie nt
update s ; if for s ome re as on, conne cting to that s e rve r fails , the n the clie nt can dis cove r
anothe r s e rve r within the domain for failove r.
The pre fe rre d s e rve r is s e t in the --fixed-primary option.
[root@client ~]# ipa-client-install --fixed-primary
ipaserver.example.com

Example 5.4. Disabling Syst em Aut hent icat io n T o o ls
Re d Hat Ente rpris e Linux us e s the authconfig tool to s e t and update authe ntication
clie nts and s e ttings for a local s ys te m. Ide ntity Manage me nt us e s the Sys te m Se curity
Se rvice s Dae mon (SSSD) to s tore IdM s e rve r configuration and to re trie ve policy
information, us e rs , pas s words , and groups configure d within the IdM domain.
It is st ro ngly reco mmended t hat yo u use aut hco nf ig and SSSD t o manage
yo ur user, gro up, and o t her IdM client co nf igurat io n.
The re may be s ome s ituations whe re an adminis trator wants to dis able dynamic
change s to s ys te m authe ntication configuration. In that cas e , it is pos s ible to dis able IdM
from making update s to authconfig or SSSD.
The --noac option pre ve nts any change s through authconfig. The --no-sssd option
pre ve nts IdM from us ing SSSD.
[root@client ~]# ipa-client-install --noac --no-sssd
A re late d option is --preserve-sssd. While this allows the clie nt to change the SSSD
configuration file to configure the IdM domain, it s ave s the old SSSD configuration.

Example 5.5. Disabling Passwo rd Caching
One of the primary functions of SSSD is password caching. Normally, whe n a s ys te m
us e s an e xte rnal pas s word s tore , authe ntication fails if that pas s word s tore is e ve r
inacce s s ible . Howe ve r, SSSD can cache pas s words afte r a s ucce s s ful authe ntication
atte mpt and s tore thos e pas s words locally. This allows us e rs to log in and acce s s
domain s e rvice s (which the y have pre vious ly acce s s e d) e ve n if the IdM s e rve r is
inacce s s ible .
In highly-s e cure e nvironme nts , it may be ne ce s s ary to pre ve nt pas s word caching to
pre ve nt pote ntially unauthoriz e d acce s s . In that cas e , the --no-krb5-offlinepasswords option can be us e d to pre ve nt pas s words from be ing cache d in SSSD.
[root@client ~]# ipa-client-install --no-krb5-offline-passwords

58

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

5.4. Manually Configuring a Linux Client
The ipa-client-install command automatically configure s s e rvice s like Ke rbe ros ,
SSSD, PAM, and NSS. Howe ve r, if the ipa-client-install command cannot be us e d on a
s ys te m for s ome re as on, the n the IdM clie nt e ntrie s and the s e rvice s can be configure d
manually.

5.4.1. Set t ing up an IdM Client (Full Procedure)
1. Ins tall SSSD, if it is not alre ady ins talle d.
2. Optional. Ins tall the IdM tools s o that adminis trative tas ks can be pe rforme d from
the hos t.
[root@client ~]# yum install ipa-admintools
3. On the IdM s e rve r, cre ate a hos t e ntry for the clie nt.
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-add --force --ipaddress=192.168.166.31 ipaclient.example.com
Cre ating hos ts manually is cove re d in Se ction 5.4.2, “Othe r Example s of Adding a
Hos t Entry”.
4. On the IdM s e rve r, s e t the clie nt hos t to be manage d by the s e rve r.
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-add-managedby -hosts=ipaserver.example.com ipaclient.example.com
5. On the clie nt, configure SSSD by e diting the /etc/sssd/sssd.conf file to point to
the IdM domain.
[root@client ~]# touch /etc/sssd/sssd.conf
[root@client ~]# vim /etc/sssd/sssd.conf
[sssd]
config_file_version = 2
services = nss, pam
domains = example.com
[nss]
[pam]
[domain/example.com]
cache_credentials = True
krb5_store_password_if_offline = True
ipa_domain = example.com
id_provider = ipa
auth_provider = ipa
access_provider = ipa

59

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ipa_hostname = ipaclient.example.com
chpass_provider = ipa
ipa_server = ipaserver.example.com
ldap_tls_cacert = /etc/ipa/ca.crt
6. Configure NSS to us e SSSD for pas s words , groups , us e rs , and ne tgroups .
[root@client ~]# vim /etc/nsswitch.conf
...
passwd:
shadow:
group:
...
netgroup:
...

files sss
files sss
files sss
files sss

7. Configure the /etc/krb5.conf file to point to the IdM KDC.
[root@client ~]# vim /etc/krb5.conf
[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm = false
dns_lookup_kdc = false
rdns = false
ticket_lifetime = 24h
forwardable = yes
allow_weak_crypto = true
[realms]
EXAMPLE.COM = {
kdc = ipaserver.example.com:88
admin_server = ipaserver.example.com:749
default_domain = example.com
}
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
8. Ge ne rate the ke ytab for the clie nt.
[root@client ~]# kinit admin
[root@client ~]# ipa-getkeytab -s ipaserver.example.com -p
host/ipaclient.example.com -k /etc/krb5.keytab
9. Update the /etc/pam.d configuration to us e the pam_sss.so module s .
For /etc/pam.d/fingerprint-auth:

60

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

...
account
pam_sss.so
...
session

[default=bad success=ok user_unknown=ignore]

optional

pam_sss.so

For /etc/pam.d/system-auth:
...
auth
...
account
pam_sss.so
...
password
...
session

sufficient

pam_sss.so use_first_pass

[default=bad success=ok user_unknown=ignore]

sufficient

pam_sss.so use_authtok

optional

pam_sss.so

For /etc/pam.d/password-auth:
...
auth
...
account
pam_sss.so
...
password
...
session

sufficient

pam_sss.so use_first_pass

[default=bad success=ok user_unknown=ignore]

sufficient

pam_sss.so use_authtok

optional

pam_sss.so

For /etc/pam.d/smartcard-auth:
...
account
pam_sss.so
...
session

[default=bad success=ok user_unknown=ignore]

optional

pam_sss.so

10. Ins tall the IdM s e rve r's CA ce rtificate .
a. Obtain the ce rtificate from the s e rve r.
[root@client ~]# wget -O /etc/ipa/ca.crt
http://ipa.example.com/ipa/config/ca.crt
b. Ins tall the ce rtificate in the s ys te m's NSS databas e .
[root@client ~]# certutil -A -d /etc/pki/nssdb -n "IPA CA" -t
CT,C,C -a -i /etc/ipa/ca.crt
11. Se t up a hos t ce rtificate for the hos t in IdM.
a. Make s ure certmonger is running.

61

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@client ~]# systemctl start certmonger.service

No te
You can us e the systemctl utility to make the certmonger s e rvice
s tart by de fault.
[root@client ~]# systemctl enable certmonger.service

b. Us e the ipa-getcert command, which cre ate s and manage s the ce rtificate
through certmonger. The options are de s cribe d more in the certmonger
manpage .
[root@client ~]# ipa-getcert request -d /etc/pki/nssdb -n
Server-Cert -K HOST/ipaclient.example.com -N
'CN=ipaclient.example.com,O=EXAMPLE.COM'
If adminis trative tools we re not ins talle d on the clie nt, the n the ce rtificate can be
ge ne rate d on an IdM s e rve r, copie d ove r to the hos t, and ins talle d us ing certutil.
12. Configure the NIS domain name for the clie nt.
a. Se t the NIS domain name .
[root@client ~]# authconfig --nisdomain=example.org --update
b. Re s tart the domain name s e rvice to apply the change .
[root@client ~]# systemctl restart rhel-domainname.service
Note that the NIS domain doe s not actually have to e xis t, and that it is not re quire d
to have a NIS s e rve r ins talle d. For information about the NIS domain name
re quire me nts , s e e Se ction 21.1.2, “s udo and Ne tgroups ”.
13. Configure the sudo utility to be us e d with SSSD.
a. Cre ate the [sudo] s e ction in the /etc/sssd/sssd.conf file . The s e ction can
s tay e mpty.
b. Add sudo to the lis t of s e rvice s in the [sssd] s e ction in
/etc/sssd/sssd.conf.
[root@client ~]# vim /etc/sssd/sssd.conf
[sssd]
services = nss, pam, sudo
c. Enable SSSD as a s ource for sudo rule s by adding the following sudoers
e ntry to the /etc/nsswitch.conf file .
[root@client ~]# vim /etc/nsswitch.conf

62

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

...
sudoers: files sss
...
d. Re s tart SSSD.
[root@client ~]# systemctl restart sssd.service
14. Run the ipa-client-automount command which automatically configure s NFS for
IdM. For more information on ipa-client-automount, s e e Se ction 18.2.1,
“Configuring NFS Automatically”.

5.4.2. Ot her Examples of Adding a Host Ent ry
Se ction 5.4.1, “Se tting up an IdM Clie nt (Full Proce dure )” cove rs the full proce dure for
configuring an IdM clie nt manually. One of thos e s te ps is cre ating a hos t e ntry, and the re
are s e ve ral diffe re nt ways and options to pe rform that.

5.4.2.1. Adding Host Ent ries f rom t he Web UI
1. Ope n the Identity tab, and s e le ct the Hosts s ubtab.
2. Click Add at the top of the hos ts lis t.

Figure 5.1. Adding Ho st Ent ries
3. Fill in the machine name and s e le ct the domain from the configure d z one s in the
drop-down lis t. If the hos t has alre ady be e n as s igne d a s tatic IP addre s s , the n
include that with the hos t e ntry s o that the DNS e ntry is fully cre ate d.

63

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 5.2. Add Ho st Wizard
DNS z one s can be cre ate d in IdM, which is de s cribe d in Se ction 17.5.1, “Adding and
Re moving Mas te r DNS Zone s ”. If the IdM s e rve r doe s not manage the DNS s e rve r,
the z one can be e nte re d manually in the me nu are a, like a re gular te xt fie ld.

No te
Se le ct the Force che ckbox to add the hos t DNS re cord, e ve n if the hos t
name cannot be re s olve d.
This is us e ful for hos ts which us e DHCP and do not have a s tatic IP addre s s .
This e s s e ntially cre ate s a place holde r e ntry in the IdM DNS s e rvice . Whe n
the DNS s e rvice dynamically update s its re cords , the hos t's curre nt IP
addre s s is de te cte d and its DNS re cord is update d.

4. Click the Add and Edit button to go dire ctly to the e xpande d e ntry page and fill in
more attribute information. Information about the hos t hardware and phys ical
location can be include d with the hos t e ntry.

64

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

Figure 5.3. Expanded Ent ry Page

5.4.2.2. Adding Host Ent ries f rom t he Command Line
Hos t e ntrie s are cre ate d us ing the host-add command. This commands adds the hos t
e ntry to the IdM Dire ctory Se rve r. The full lis t of options with host-add are lis te d in the
ipa host manpage . At its mos t bas ic, an add ope ration only re quire s the clie nt hos t name
to add the clie nt to the Ke rbe ros re alm and to cre ate an e ntry in the IdM LDAP s e rve r:
$ ipa host-add client1.example.com
If the IdM s e rve r is configure d to manage DNS, the n the hos t can als o be adde d to the
DNS re s ource re cords us ing the --ip-address and --force options .

Example 5.6. Creat ing Ho st Ent ries wit h St at ic IP Addresses
$ ipa host-add --force --ip-address=192.168.166.31 client1.example.com

Commonly, hos ts may not have a s tatic IP addre s s or the IP addre s s may not be known at
the time the clie nt is configure d. For e xample , laptops may be pre configure d as
Ide ntity Manage me nt clie nts , but the y do not have IP addre s s e s at the time the y're
configure d. Hos ts which us e DHCP can s till be configure d with a DNS e ntry by us ing -force. This e s s e ntially cre ate s a place holde r e ntry in the IdM DNS s e rvice . Whe n the DNS
s e rvice dynamically update s its re cords , the hos t's curre nt IP addre s s is de te cte d and its
DNS re cord is update d.

Example 5.7. Creat ing Ho st Ent ries wit h DHCP

65

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

$ ipa host-add --force client1.example.com

Hos t re cords are de le te d us ing the host-del command. If the IdM domain us e s DNS, the n
the --updatedns option als o re move s the as s ociate d re cords of any kind for the hos t
from the DNS.
$ ipa host-del --updatedns client1.example.com

5.5. Set t ing up a Linux Client T hrough Kickst art
A kicks tart e nrollme nt automatically adds a ne w s ys te m to the IdM domain at the time it is
provis ione d.
This re quire s pre -cre ating the hos ts on the IdM s e rve r, with a pre de fine d pas s word that
can be us e d to authe nticate to comple te the e nrollme nt ope ration.
1. Cre ate the hos t e ntry on the IdM s e rve r and s e t a te mporary Ke rbe ros pas s word
for the e ntry.
Whe n the ipa-client-install s cript is run normally (inte ractive ly), it prompts for
authe ntication cre de ntials to acce s s the IdM domain. Howe ve r, whe n the s cript is
run automatically, the s ys te m has to have s ome way to acce s s the IdM domain
without us ing an e xis ting IdM us e r; this is done by s e tting the hos t principal in the
s cript and us ing a Ke rbe ros pas s word (configure d for the hos t account) to acce s s
the IdM domain.
For e xample :
[jsmith@ipaserver ~]$ ipa host-add kickstart-server.example.com -password=secret
The pas s word e xpire s afte r the firs t authe ntication atte mpt. Afte r e nrollme nt
comple te s , the hos t is authe nticate d us ing its ke ytab.
2. Include the ipa-client package with the othe r ins tall package s .
%packages
@ X Window System
@ Desktop
@ Sound and Video
ipa-client
...
3. Cre ate a pos t-ins tall ins truction that e ns ure s SSH ke ys are ge ne rate d be fore
e nrollme nt, runs the ipa-client-install s cript, pas s e s all the re quire d
information to acce s s and configure the IdM domain s e rvice s , and s pe cifie s the pre s e t pas s word. Us e the --unattended option to ins truct the s cript to run noninte ractive ly.
%post --log=/root/ks-post.log
# Generate SSH keys to ensure that ipa-client-install uploads them
to the IdM server

66

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

/usr/sbin/sshd-keygen
# Get the hostname to set as the host principal
/bin/hostname > /tmp/hostname.txt
# Run the client install script
/usr/sbin/ipa-client-install --domain=EXAMPLEDOMAIN --enable-dnsupdates --mkhomedir -w secret --realm=EXAMPLEREALM -server=ipaserver.example.com --unattended

No te
Re d Hat re comme nds not to s tart the sshd s e rvice prior to the kicks tart
e nrollme nt. While s tarting sshd be fore e nrolling the clie nt ge ne rate s the SSH
ke ys automatically, us ing the above s cript is the pre fe rre d s olution.
4. Run the kicks tart s cript.

5.6. Re-enrolling a Host
The re can be ins tance s whe n hos t information is corrupt or compromis e d or whe n a
s ys te m is be ing re provis ione d, and the hos t ne e ds to be re -e nrolle d to the IdM domain.
Re -e nrollme nt update s ide ntifying information for the hos t:
It re voke s the original hos t ce rtificate .
It ge ne rate s a ne w hos t ce rtificate .
It cre ate s ne w SSH ke ys .
It re tains the unique ide ntifie r for the hos t within the domain, and any his torical
configuration.
A hos t can be re -e nrolle d as long as its domain e ntry is active . This me ans that it cannot
have be e n une nrolle d (the ipa-client-install --uninstall command has ne ve r be e n
run), and the hos t e ntry is not dis able d (ipa host-disable).

No te
The hos t e ntry mus t be active for it to be re -e nrolle d. Dis abling a hos t re voke s all
as s ociate d ce rtificate s , Ke rbe ros ke ys , and s e rvice s , which pre ve nts that hos t from
participating in the IdM domain.
The ipa-client-install command can re -e nroll a hos t. The re are two ways to re -e nroll:
If the re -e nrollme nt is be ing done inte ractive ly, the n it is pos s ible to force a ne w
e nrollme nt ope ration with the --force-join option. This re quire s the adminis trator
pas s word for the domain.
[root@server ~]# ipa-client-install --force-join --password secret
If the re -e nrollme nt is automate d (s uch as a kicks tart e nrollme nt through a provis ioning

67

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

s ys te m) or if it is not fe as ible to us e the adminis trator pas s word, the n it is pos s ible to
re -e nroll us ing the e xis ting ke ytab to authe nticate . This is pas s e d in the --keytab
option. By de fault, the hos t ke ytab location is /etc/krb5.keytab.
[root@server ~]# ipa-client-install --keytab /etc/krb5.keytab
The e xis ting ke ytab is us e d to authe nticate to initiate the e nrollme nt. As part of the re e nrollme nt proce s s , a ne w ke ytab is ge ne rate d.

5.7. Renaming Machines and Reconfiguring IdM Client
Configurat ion
The hos t name of a s ys te m is critical for the corre ct ope ration of Ke rbe ros and SSL. Both
of the s e s e curity me chanis ms re ly on the hos t name to e ns ure that communication is
occurring be twe e n the s pe cifie d hos ts . Infras tructure s which us e virtual machine s or
clus te re d s e rve rs will commonly have hos ts which are re name d be caus e s ys te ms are
copie d, move d, or re name d.
Re d Hat Ente rpris e Linux doe s not provide a s imple re name command to facilitate the
re naming of an IdM hos t. Re naming a hos t in an IdM domain involve s de le ting the e ntry in
IdM, unins talling the clie nt s oftware , changing the hos t name , and re -e nrolling us ing the
ne w name . Additionally, part of re naming hos ts re quire s re ge ne rating s e rvice principals .
To re configure the clie nt:
1. Ide ntify which s e rvice s are running on the machine . The s e ne e d to be re -cre ate d
whe n the machine is re -e nrolle d.
# ipa service-find server.example.com
Each hos t has a de fault s e rvice which doe s not appe ar in the lis t of s e rvice s . This
s e rvice can be re fe rre d to as the "hos t s e rvice ". The s e rvice principal for the hos t
s e rvice is host/, s uch as host/server.example.com. This principal can
als o be re fe rre d to as the host principal.
2. Ide ntify all hos t groups to which the machine be longs .
[root@client ~]# kinit admin
[root@client ~]# ipa hostgroup-find server.example.com
3. Ide ntify which of the s e rvice s have ce rtificate s as s ociate d with the m. This can be
done us ing the ldapsearch command to che ck the e ntrie s in the IdM LDAP
databas e dire ctly:
[root@client ~]# ldapsearch -x -b "cn=accounts,dc=example,dc=com"
"(&(objectclass=ipaservice)(userCertificate=*))" krbPrincipalName
-D "cn=directory manager" -w secret -h ipaserver.example.com -p
389
4. For any s e rvice principals (in addition to the hos t principal), de te rmine the location
of the corre s ponding ke ytabs on server.example.com. The ke ytab location is
diffe re nt for e ach s e rvice , and IdM doe s not s tore this information.

68

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

Each s e rvice on the clie nt s ys te m has a Ke rbe ros principal in the form
service_name/hostname@REALM, s uch as
ldap/server.example.com@EXAMPLE.COM.
5. Une nroll the clie nt machine from the IdM domain:
[root@client ~]# ipa-client-install --uninstall
6. For e ach ide ntifie d ke ytab othe r than /etc/krb5.keytab, re move the old principals :
[root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM
7. On an IdM s e rve r, as an IdM adminis trator, re move the hos t e ntry. This re move s all
s e rvice s and re voke s all ce rtificate s is s ue d for that hos t:
[root@server ~]# kinit admin
[root@server ~]# ipa host-del server.example.com
At this point, the hos t is comple te ly re move d from IdM.
8. Re name the machine .
9. Re -e nroll the s ys te m with IdM:
[root@client ~]# ipa-client-install
This ge ne rate s a hos t principal for the ne w hos t name in /etc/krb5.keytab.
10. On an IdM s e rve r, add a ne w ke ytab for e ve ry s e rvice :
[root@server ~]# ipa service-add serviceName/new-hostname
11. To ge ne rate ce rtificate s for s e rvice s , us e e ithe r certmonger or the IdM
adminis tration tools .
12. Re -add the hos t to any applicable hos t groups .

5.8. Performing a T wo-Administ rat or Enrollment
Enrolling machine s as clie nts in the IdM domain is a two-part proce s s . A hos t e ntry is
cre ate d for the clie nt (and s tore d in the 389 Dire ctory Se rve r ins tance ), and the n a ke ytab
is cre ate d to provis ion the clie nt.
Both parts are pe rforme d automatically by the ipa-client-install command. It is als o
pos s ible to pe rform thos e s te ps s e parate ly; this allows for adminis trators to pre pare
machine s and the IdM s e rve r configuration in advance of actually configuring the clie nts .
This allows more fle xible s e tup s ce narios , including bulk de ployme nts .
Whe n pe rforming a manual e nrollme nt, the hos t e ntry is cre ate d s e parate ly, and the n
e nrollme nt is comple te d whe n the clie nt s cript is run, which cre ate s the re quis ite ke ytab.

69

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
The re are two ways to s e t the pas s word. You can e ithe r s upply your own or have
IdM ge ne rate a random one .
The re may be a s ituation whe re an adminis trator in one group is prohibite d from creating
a hos t e ntry and, the re fore , from s imply running the ipa-client-install command and
allowing it to cre ate the hos t. Howe ve r, that adminis trator may have the right to run the
command after a hos t e ntry e xis ts . In that cas e , one adminis trator can cre ate the hos t
e ntry manually, the n the s e cond adminis trator can comple te the e nrollme nt by running the
ipa-client-install command.
1. An adminis trator cre ate s the hos t e ntry, as de s cribe d in Se ction 5.4.2, “Othe r
Example s of Adding a Hos t Entry”.
2. The s e cond adminis trator ins talls the IdM clie nt package s on the machine , as in
Se ction 5.3, “Configuring a Linux Sys te m as an IdM Clie nt”.
3. Whe n the s e cond adminis trator runs the s e tup s cript, he mus t pas s his Ke rbe ros
pas s word and us e rname (principal) with the ipa-client-install command. For
e xample :
$ ipa-client-install -w secret -p admin2
4. The ke ytab is ge ne rate d on the s e rve r and provis ione d to the clie nt machine , s o
that the clie nt machine is not able to conne ct to the IdM domain. The ke ytab is
s ave d with root:root owne rs hip and 0600 pe rmis s ions .

5.9. Removing Client s from t he Domain
The re are a numbe r of diffe re nt s ituations whe re an IdM clie nt ne e ds to be re move d or
re configure d. For e xample , a clie nt s ys te m could be move d from one IdM domain to
anothe r or a virtual s ys te m could be clone d or move d be twe e n s ys te ms .
Une nrolling a clie nt (e ithe r pe rmane ntly or as part of re configuring the clie nt) is done
us ing the ipa-client-install command with the --uninstall option. This automatically
re move s all of the IdM-s pe cific configuration for s ys te m s e rvice s like SSSD and re s tore s
its pre vious configuration.
[root@server ~]# ipa-client-install --uninstall --updatedns
Us e the --updatedns option, as whe n ins talling a clie nt, to update the domain DNS
configuration automatically.

Warning
Whe n a machine is une nrolle d, the proce dure cannot be undone . The machine can
only be e nrolle d again.

5.10. Manually Unconfiguring Client Machines
70

⁠C hapt e r 5. Se t t ing up Sys t e ms as IdM Clie nt s

The re are a numbe r of diffe re nt s ituations whe re an IdM clie nt ne e ds to be re configure d.
If it is not pos s ible to unins tall the clie nt dire ctly, the n the IdM configuration can be
manually re move d from the clie nt s ys te m.

Warning
Whe n a machine is une nrolle d, the proce dure cannot be undone . The machine can
only be e nrolle d again.
1. On the clie nt, re move the old hos t name from the main ke ytab. This can be done by
re moving e ve ry principal in the re alm or by re moving s pe cific principals . For
e xample , to re move all principals :
[jsmith@client ~]$ ipa-rmkeytab -k /etc/krb5.keytab -r EXAMPLE.COM
To re move s pe cific principals :
[jsmith@client ~]$ ipa-rmkeytab -k /etc/krb5.keytab -p
host/server.example.com@EXAMPLE.COM
2. On the clie nt s ys te m, dis able tracking in certmonger for e ve ry ce rtificate . Each
ce rtificate mus t be re move d from tracking individually.
Firs t, lis t e ve ry ce rtificate be ing tracke d, and e xtract the databas e and nickname for
e ach ce rtificate . The numbe r of ce rtificate s de pe nds on the configure d s e rvice s for
the hos t.
[jsmith@client ~]$ ipa-getcert list
The n, dis able tracking for e ach. For e xample :
[jsmith@client ~]$ ipa-getcert stop-tracking -n "Server-Cert" -d
/etc/httpd/alias
3. On the IdM s e rve r, re move the old hos t from the IdM DNS domain. While this is
optional, it cle ans up the old IdM e ntrie s as s ociate d with the s ys te m and allows it to
be re -e nrolle d cle anly at a late r time .
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-del server.example.com
4. If the s ys te m s hould be re -adde d to a ne w IdM domain — s uch as a virtual machine
which was move d from one location to anothe r — the n the s ys te m can be re joine d
to IdM us ing the ipa-join command on the clie nt s ys te m.
[jsmith@client ~]$ ipa-join

71

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 6. Upgrading Ident it y Management
Ide ntity Manage me nt can be migrate d from a Re d Hat Ente rpris e Linux 6.5 s ys te m to a
Re d Hat Ente rpris e Linux 7 s ys te m. This is s imilar to cre ating and promoting a re plica to
re place a s e rve r; this proce s s migrate s the data and configuration from one ins tance to
anothe r. The olde r IdM ins tance can the n be de commis s ione d and re place d by the ne w
IdM ins tance .

Warning
If any of the ins tance s in your IdM de ployme nt are us ing Re d Hat Ente rpris e Linux
6.5 or e arlie r, upgrade the m to Re d Hat Ente rpris e Linux 6.6 be fore upgrading a
Re d Hat Ente rpris e Linux 7.0 IdM s e rve r to the 7.1 ve rs ion or be fore conne cting a
Re d Hat Ente rpris e Linux 7.1 IdM re plica.
Be fore upgrading IdM, make s ure you have applie d the RHBA-2015:0231-2 advis ory,
which provide s the 2.3-6.e l6_6 ve rs ion of the bind-dyndb-ldap package s and is
available with the Re d Hat Ente rpris e Linux 6.6 Exte nde d Update Support (EUS).
Us ing a pre vious bind-dyndb-ldap ve rs ion re s ults in incons is te nt be havior in DNS
forward z one s s e rving be twe e n the Re d Hat Ente rpris e Linux 6.6 DNS s e rve rs and
Re d Hat Ente rpris e Linux 7 DNS s e rve rs .

The following migration rule s s hould be note d whe n upgrading Ide ntity Manage me nt:
When a replica is creat ed, it must be o f an equal o r lat er versio n t han t he
mast er it is based o n.
For e xample , you can ins tall a Re d Hat Ente rpris e Linux 7 re plica agains t a Re d
Hat Ente rpris e Linux 6 mas te r, but you cannot ins tall a Re d Hat Ente rpris e Linux 6
re plica agains t a Re d Hat Ente rpris e Linux 7 mas te r.
Schema changes are replicat ed bet ween servers.
Once one mas te r s e rve r is update d, all s e rve rs and re plicas re ce ive the update d
s che ma, e ve n if the ir package s are not ye t update d. This e ns ure s that any ne w
e ntrie s which us e the ne w s che ma can s till be re plicate d among all the s e rve rs
in the IdM domain.

72

⁠C hapt e r 6 . Upgr ading Ide nt it y Manage me nt

Impo rtant
Due to CVE-2014-3566, the Se cure Socke t Laye r ve rs ion 3 (SSLv3) protocol ne e ds
to be dis able d in the mod_nss module . You can e ns ure that by following the s e s te ps :
1. Edit the /etc/httpd/conf.d/nss.conf file and s e t the NSSProtocol
parame te r to TLSv1.0 (for backward compatibility) and TLSv1.1.
NSSProtocol TLSv1.0,TLSv1.1
2. Re s tart the httpd s e rvice .
# systemctl restart httpd.service
Note that Ide ntity Manage me nt in Re d Hat Ente rpris e Linux 7 automatically pe rforms
the above s te ps whe n the yum update ipa-* command is launche d to upgrade the
main package s .

6.1. Migrat ing t he IdM Server t o Red Hat Ent erprise Linux 7
As is cove re d in Se ction 28.7, “Promoting a Re plica to a Mas te r CA Se rve r”, only one
s e rve r within the IdM domain ge ne rate s ce rtificate re vocation lis ts (CRLs ) and has the root
s igning ke y to ge ne rate ce rtificate s . This is the mas te r ce rtificate authority (CA), and it is
the mas te r s e rve r within the IdM e nvironme nt.
Whe n migrating an IdM s e rve r from Re d Hat Ente rpris e Linux 6 to Re d Hat Ente rpris e Linux
7, the proce s s is ve ry s imilar to promoting a re plica to a mas te r:
1. A ne w s e rve r is cre ate d on Re d Hat Ente rpris e Linux 7.
2. All data are migrate d ove r to the ne w s e rve r.
3. All s e rvice s , s uch as CRL and ce rtificate cre ation, DNS manage me nt, Ke rbe ros KDC
adminis tration, are trans itione d ove r to the ne w s ys te m.

Impo rtant
Migrating an IdM s e rve r from Re d Hat Ente rpris e Linux 6 to Re d Hat Ente rpris e Linux
7 involve s ins talling a re plica, which re quire s ce rtain s ys te m configuration. For
information on the s e pre re quis ite s , s e e Se ction 4.2, “Pre re quis ite s for Ins talling a
Re plica Se rve r”.
To migrate an IdM s e rve r from Re d Hat Ente rpris e Linux 6 to Re d Hat Ente rpris e Linux 7:
1. Update the Re d Hat Ente rpris e Linux 6 s ys te m to the late s t Re d Hat
Ente rpris e Linux 6 ve rs ion, and upgrade the ipa package s .
[root@rhel6 ~]# yum update ipa-*

73

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

2. Ope n the re quire d ports . Note that the firewalld s e rvice ne e ds to be running. You
can find information on which ports IdM re quire s and how to s tart firewalld in
Se ction 2.4.4, “Sys te m Ports ”.
For e xample , to ope n all the IdM re quire d ports in the de fault z one and make the
change both pe rmane nt and runtime :
a. Run the firewall-cmd command with the --permanent option s pe cifie d.
[root@rhel7 ~]# firewall-cmd --permanent --add-port=
{80/tcp,443/tcp,389/tcp,636/tcp,88/tcp,464/tcp,88/udp,464/udp
,22/tcp}
b. Re load the firewall-cmd configuration to e ns ure that the change take s
place imme diate ly.
[root@rhel7 ~]# firewall-cmd --reload
3. Ins tall the IdM package s on the Re d Hat Ente rpris e Linux 7 s ys te m.
[root@rhel7 ~]# yum install ipa-server ipa-server-dns
4. Copy the Python s che ma update s cript from the Re d Hat Ente rpris e Linux 7 s ys te m
to the Re d Hat Ente rpris e Linux 6 s ys te m.
[root@rhel7 ~]# scp /usr/share/ipa/copy-schema-to-ca.py
rhel6:/root/
Updating the s cript in this way is ne ce s s ary due to s che ma change s be twe e n IdM
ve rs ion 3.1 and late r IdM ve rs ions .
5. Run the s che ma update s cript on the Re d Hat Ente rpris e Linux 6 s ys te m.
[root@rhel6 ~]# python copy-schema-to-ca.py
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60kerberos.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60samba.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60ipaconfig.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60basev2.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60basev3.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/60ipadns.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/61kerberos-ipav3.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/65ipasudo.ldif
ipa
: INFO
Installed /etc/dirsrv/slapd-PKIIPA//schema/05rfc2247.ldif
ipa
: INFO
Restarting CA DS
ipa
: INFO
Schema updated successfully

74

⁠C hapt e r 6 . Upgr ading Ide nt it y Manage me nt

6. On the Re d Hat Ente rpris e Linux 6 s ys te m, cre ate the re plica file for the Re d Hat
Ente rpris e Linux 7 s ys te m; in this e xample , the ne w re plica s e rve r is
rhel7.example.com with the 192.0.2.1 IP addre s s .
[root@rhel6 ~]# ipa-replica-prepare rhel7.example.com --ip-address
192.0.2.1
Directory Manager (existing master) password:
Preparing replica for rhel7.example.com from rhel6.example.com
Creating SSL certificate for the Directory Server
Creating SSL certificate for the dogtag Directory Server
Saving dogtag Directory Server port
Creating SSL certificate for the Web Server
Exporting RA certificate
Copying additional files
Finalizing configuration
Packaging replica information into /var/lib/ipa/replica-inforhel7.example.com.gpg
Adding DNS records for rhel7.example.com
Using reverse zone 2.0.192.in-addr.arpa.
The ipa-replica-prepare command was successful
7. Ins tall the re plica, us ing the ne w re plica file , on the Re d Hat Ente rpris e Linux 7
s ys te m. Us e the --setup-ca option to s e t up a Dogtag Ce rtificate Sys te m ins tance
and the --setup-dns option to configure the DNS s e rve r. The re plica s e rve r's IP
addre s s in this e xample is 192.0.2.1.
[root@rhel7 ~]# ipa-replica-install --setup-ca --ipaddress=192.0.2.1 -p secret -w secret -N --setup-dns -forwarder=192.0.2.20 -U /var/lib/ipa/replica-inforhel7.example.com.gpg
Run connection check to master
Check connection from replica to remote master
'rhel6.example.com':
Directory Service: Unsecure port (389): OK
Directory Service: Secure port (636): OK
Kerberos KDC: TCP (88): OK
Kerberos Kpasswd: TCP (464): OK
HTTP Server: Unsecure port (80): OK
HTTP Server: Secure port (443): OK
PKI-CA: Directory Service port (7389): OK
...
8. Ve rify the configuration.
a. Ve rify that the IdM s e rvice s are running:
[root@rhel7 ~]# ipactl status
Directory Service: RUNNING
krb5kdc Service: RUNNING
kadmin Service: RUNNING
named Service: RUNNING
ipa_memcached Service: RUNNING

75

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

httpd Service: RUNNING
pki-tomcatd Service: RUNNING
ipa-otpd Service: RUNNING
ipa: INFO: The ipactl command was successful
b. Ve rify that both IdM CAs are configure d as mas te r s e rve rs .
[root@rhel7 ~]# kinit admin
[root@rhel7 ~]# ipa-replica-manage list
rhel6.example.com: master
rhel7.example.com: master
[root@rhel7 ~]# ipa-replica-manage list -v rhel7.example.com
rhel6.example.com: replica
last init status: None
last init ended: None
last update status: 0 Replica acquired successfully:
Incremental update started
last update ended: None
9. On the Red Hat Enterprise Linux 6 system. Edit the Re d Hat Ente rpris e Linux 6 IdM
s e rve r s o that it no longe r re ne ws the CA s ubs ys te m ce rtificate s or is s ue s CRLs .
a. Ide ntify which s e rve r ins tance is the mas te r CA s e rve r. Both CRL ge ne ration
and re ne wal ope rations are handle d by the s ame CA s e rve r. So, the mas te r
CA can be ide ntifie d by having the renew_ca_cert ce rtificate be ing tracke d
by certmonger.
[root@rhel6 ~]# getcert list -d /var/lib/pki-ca/alias -n
"subsystemCert cert-pki-ca" | grep post-save
post-save command: /usr/lib64/ipa/certmonger/renew_ca_cert
"subsystemCert cert-pki-ca"
b. On the original master CA, dis able tracking for all of the original CA
ce rtificate s .
[root@rhel6 ~]# getcert stop-tracking -d /var/lib/pkica/alias -n "auditSigningCert cert-pki-ca"
Request "20151127184547" removed.
[root@rhel6 ~]# getcert stop-tracking -d /var/lib/pkica/alias -n "ocspSigningCert cert-pki-ca"
Request "20151127184548" removed.
[root@rhel6 ~]# getcert stop-tracking -d /var/lib/pkica/alias -n "subsystemCert cert-pki-ca"
Request "20151127184549" removed.
[root@rhel6 ~]# getcert stop-tracking -d /etc/httpd/alias -n
ipaCert
Request "20151127184550" removed.
c. Re configure the original mas te r CA to re trie ve re ne we d ce rtificate s from a
ne w mas te r CA.
a. Copy the re ne wal he lpe r into the certmonger s e rvice dire ctory, and
s e t the appropriate pe rmis s ions .

76

⁠C hapt e r 6 . Upgr ading Ide nt it y Manage me nt

[root@rhel6 ~]# cp /usr/share/ipa/ca_renewal
/var/lib/certmonger/cas/ca_renewal
[root@rhel6 ~]# chmod 0600
/var/lib/certmonger/cas/ca_renewal
b. Update the SELinux configuration.
[root@rhel6 ~]# /sbin/restorecon
/var/lib/certmonger/cas/ca_renewal
c. Re s tart certmonger.
[root@rhel6 ~]# service certmonger restart
d. Che ck that the CA is lis te d to retrieve ce rtificate s . This is printe d in
the CA configuration.
[root@rhel6 ~]# getcert list-cas
...
CA 'dogtag-ipa-retrieve-agent-submit':
is-default: no
ca-type: EXTERNAL
helper-location: /usr/libexec/certmonger/dogtag-iparetrieve-agent-submit
e . Ge t the CA ce rtificate databas e PIN.
[root@rhel6 ~]# grep internal= /var/lib/pkica/conf/password.conf
f. Configure certmonger to track the ce rtificate s for e xte rnal re ne wal.
This re quire s the databas e PIN.
[root@rhel6 ~]# getcert start-tracking -c dogtag-iparetrieve-agent-submit -d /var/lib/pki-ca/alias -n
"auditSigningCert cert-pki-ca" -B
/usr/lib64/ipa/certmonger/stop_pkicad -C
'/usr/lib64/ipa/certmonger/restart_pkicad
"auditSigningCert cert-pki-ca"' -T "auditSigningCert
cert-pki-ca" -P database_pin
New tracking request "20151127184743" added.
[root@rhel6 ~]# getcert start-tracking -c dogtag-iparetrieve-agent-submit -d /var/lib/pki-ca/alias -n
"ocspSigningCert cert-pki-ca" -B
/usr/lib64/ipa/certmonger/stop_pkicad -C
'/usr/lib64/ipa/certmonger/restart_pkicad
"ocspSigningCert cert-pki-ca"' -T "ocspSigningCert
cert-pki-ca" -P database_pin
New tracking request "20151127184744" added.
[root@rhel6 ~]# getcert start-tracking -c dogtag-iparetrieve-agent-submit -d /var/lib/pki-ca/alias -n
"subsystemCert cert-pki-ca" -B
/usr/lib64/ipa/certmonger/stop_pkicad -C
'/usr/lib64/ipa/certmonger/restart_pkicad

77

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

"subsystemCert cert-pki-ca"' -T "subsystemCert certpki-ca" -P database_pin
New tracking request "20151127184745" added.
[root@rhel6 ~]# getcert start-tracking -c dogtag-iparetrieve-agent-submit -d /etc/httpd/alias -n ipaCert -C
/usr/lib64/ipa/certmonger/restart_httpd -T ipaCert -p
/etc/httpd/alias/pwdfile.txt
New tracking request "20151127184746" added.
d. Stop CRL ge ne ration on the original mas te r CA.
a. Stop CA s e rvice .
[root@rhel6 ~]# service pki-cad stop
b. Ope n the CA configuration file .
[root@rhel6 ~]# vim /var/lib/pki-ca/conf/CS.cfg
c. Change the value s of the ca.crl.MasterCRL.enableCRLCache and
ca.crl.MasterCRL.enableCRLUpdates parame te rs to false to
dis able CRL ge ne ration.
ca.crl.MasterCRL.enableCRLCache=false
ca.crl.MasterCRL.enableCRLUpdates=false
d. Start the CA s e rvice .
[root@rhel6 ~]# service pki-cad start
e . Configure Apache to re dire ct CRL re que s ts to the ne w mas te r.
a. Ope n the CA proxy configuration.
[root@rhel6 ~]# vim /etc/httpd/conf.d/ipa-pkiproxy.conf
b. Uncomme nt the RewriteRule on the las t line and re place the
e xample s e rve r URL with the ne w Re d Hat Ente rpris e Linux 7 s e rve r
URL.
RewriteRule ^/ipa/crl/MasterCRL.bin
https://rhel7.example.com/ca/ee/ca/getCRL?
op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
c. Re s tart Apache .
[root@rhel6 ~]# systemctl restart httpd.service
10. On the Red Hat Enterprise Linux 7 system. Configure the ne w Re d Hat
Ente rpris e Linux 7 IdM ins tance as the mas te r:
a. Configure CA re ne wal us ing the ipa-csreplica-manage utility.

78

⁠C hapt e r 6 . Upgr ading Ide nt it y Manage me nt

[root@rhel7 ~]# ipa-csreplica-manage set-renewal-master
b. Configure the ne w mas te r CA to ge ne rate CRLs .
a. Stop CA s e rvice .
[root@rhel7 ~]# systemctl stop pki-tomcatd@pkitomcat.service
b. Ope n the CA configuration file .
[root@rhel7 ~]# vim /etc/pki/pki-tomcat/ca/CS.cfg
c. Change the value s of the ca.crl.MasterCRL.enableCRLCache and
ca.crl.MasterCRL.enableCRLUpdates parame te rs to true to e nable
CRL ge ne ration.
ca.crl.MasterCRL.enableCRLCache=true
ca.crl.MasterCRL.enableCRLUpdates=true
d. Start CA s e rvice .
[root@rhel7 ~]# systemctl start pki-tomcatd@pkitomcat.service
c. Configure Apache to dis able re dire ct CRL re que s ts . As a clone , all CRL
re que s ts we re route d to the original mas te r. As the ne w mas te r, this
ins tance will re s pond to CRL re que s ts .
a. Ope n the CA proxy configuration.
[root@rhel7 ~]# vim /etc/httpd/conf.d/ipa-pkiproxy.conf
b. Comme nt out the RewriteRule argume nt on the las t line .
#RewriteRule ^/ipa/crl/MasterCRL.bin
https://server.example.com/ca/ee/ca/getCRL?
op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
c. Re s tart Apache .
[root@rhel7 ~]# systemctl restart httpd.service
11. Stop all s e rvice s on the Re d Hat Ente rpris e Linux 6 s ys te m; this force s domain
dis cove ry to the Re d Hat Ente rpris e Linux 7 s e rve r.
[root@rhel6 ~]# ipactl stop
Stopping CA Service
Stopping pki-ca:
]
Stopping HTTP Service
Stopping httpd:

[

OK

[

OK

79

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

]
Stopping MEMCACHE Service
Stopping ipa_memcached:
]
Stopping DNS Service
Stopping named: .
]
Stopping KPASSWD Service
Stopping Kerberos 5 Admin Server:
]
Stopping KDC Service
Stopping Kerberos 5 KDC:
]
Stopping Directory Service
Shutting down dirsrv:
EXAMPLE-COM...
]
PKI-IPA...
]

[

OK

[

OK

[

OK

[

OK

[

OK

[

OK

12. For e ach s e rve r in the e nvironme nt, cre ate a re plica file from the Re d Hat
Ente rpris e Linux 7 mas te r s e rve r, and ins tall it on the ne w Re d Hat Ente rpris e Linux
7 re plica s ys te m. Cre ating re plicas is cove re d in Chapte r 4, Setting up IdM Replicas.
13. De commis s ion the Re d Hat Ente rpris e Linux 6 hos t.
a. Re move the Re d Hat Ente rpris e Linux 6 s e rve r from the IdM s e rve r topology
by running the ipa-replica-manage del command on the Red Hat
Enterprise Linux 7 system.
[root@rhel7 ~]# ipa-replica-manage del rhel6.example.com
Connection to 'rhel6.example.com' failed:
Forcing removal of rhel6.example.com
Skipping calculation to determine if one or more masters
would be orphaned.
Deleting replication agreements between rhel6.example.com and
rhel7.example.com
Failed to get list of agreements from 'rhel6.example.com':
Forcing removal on 'rhel7.example.com'
Any DNA range on 'rhel6.example.com' will be lost
Deleted replication agreement from 'rhel7.example.com' to
'rhel6.example.com'
Background task created to clean replication data. This may
take a while.
This may be safely interrupted with Ctrl+C
b. Re move the local IdM configuration.
[root@rhel6 ~]# ipa-server-install --uninstall

80

⁠C hapt e r 7. T he Bas ic s o f Managing t he IdM Se r ve r and Se r vic e s

Chapt er 7. The Basics of Managing t he IdM Server and
Services
This chapte r de s cribe s the Ide ntity Manage me nt command-line and UI tools that are
available to manage the IdM s e rve r and s e rvice s , including me thods for authe nticating to
IdM.

7.1. St art ing and St opping t he IdM Server
A numbe r of diffe re nt s e rvice s are ins talle d toge the r with an IdM s e rve r, including
Dire ctory Se rve r, Ce rtificate Authority (CA), DNS, Ke rbe ros , and othe rs . Us e the ipactl
utility to s top, s tart, or re s tart the e ntire IdM s e rve r along with all the ins talle d s e rvice s .
To s tart the e ntire IdM s e rve r:
# ipactl start
To s top the e ntire IdM s e rve r:
# ipactl stop
To re s tart the e ntire IdM s e rve r:
# ipactl restart
If you only want to s top, s tart, or re s tart an individual s e rvice , us e the systemctl utility,
de s cribe d in the Sys te m Adminis trator's Guide . For e xample , us ing systemctl to manage
individual s e rvice s is us e ful whe n cus tomiz ing the Dire ctory Se rve r be havior: the
configuration change s re quire re s tarting the Dire ctory Se rve r ins tance , but it is not
ne ce s s ary to re s tart all the IdM s e rvice s .

Impo rtant
To re s tart multiple IdM domain s e rvice s , Re d Hat always re comme nds to us e
ipactl. Be caus e of de pe nde ncie s be twe e n the s e rvice s ins talle d with the IdM
s e rve r, the orde r in which the y are s tarte d and s toppe d is critical. The ipactl utility
e ns ure s that the s e rvice s are s tarte d and s toppe d in the appropriate orde r.

7.2. Logging int o IdM Using Kerberos
IdM s upports Ke rbe ros authe ntication for logging into its s e rvice s and us ing the IdM
command-line utilitie s and we b UI. The kinit utility is s ue s a Ke rbe ros ticket-granting ticket
(TGT) for s ingle s ign-on afte r the us e r pre s e nts the corre ct us e r name and pas s word. The
TGT can the n be re pe ate dly us e d to re que s t acce s s to the IdM s e rvice s , without the
s ys te m prompting for the cre de ntials again. For de tails on how Ke rbe ros works , s e e the
Sys te m-Le ve l Authe ntication Guide .

81

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
To us e kinit, the krb5-workstation package mus t be ins talle d.
By de fault, only machine s that are me mbe rs of the IdM domain can us e Ke rbe ros to
authe nticate to IdM. Howe ve r, it is pos s ible to configure e xte rnal s ys te ms for Ke rbe ros
authe ntication as we ll; for more information, s e e Se ction 7.4.3, “Configuring an Exte rnal
Sys te m for Ke rbe ros Authe ntication to the We b UI”.

Using kinit
Whe n run without s pe cifying a us e r name , kinit logs into IdM unde r the us e r name of the
us e r that is curre ntly logge d-in on the local s ys te m. For e xample , if you are logge d-in as
local_user on the local s ys te m, running kinit atte mpts to authe nticate you as the
local_user IdM us e r:
[local_user@server ~]$ kinit
Password for local_user@EXAMPLE.COM:

No te
If the us e r name of the local us e r doe s not match any us e r e ntry in IdM, the
authe ntication atte mpt fails .
To log in as a diffe re nt IdM us e r, pas s the re quire d us e r name as a parame te r to the
kinit utility. For e xample , to log in as the admin us e r:
[local_user@server ~]$ kinit admin
Password for admin@EXAMPLE.COM:

Obt aining Kerberos T icket s Aut omat ically
The pam_krb5 pluggable authe ntication module (PAM) and SSSD can be configure d to
automatically obtain a TGT for a us e r afte r a s ucce s s ful login into the de s ktop e nvironme nt
on an IdM clie nt machine . This e ns ure s that afte r logging in, the us e r is not re quire d to run
kinit.
On IdM s ys te ms that have IdM configure d in SSSD as the ide ntity and authe ntication
provide r, SSSD obtains the TGT automatically afte r the us e r logs in with the corre s ponding
Ke rbe ros principal name .
For information on configuring pam_krb5, s e e the pam_krb5(8) man page . For ge ne ral
information about PAM, s e e the Sys te m-Le ve l Authe ntication Guide .

St oring Mult iple Kerberos T icket s
By de fault, Ke rbe ros only s tore s one ticke t pe r logge d-in us e r in the cre de ntial cache .
Whe ne ve r a us e r runs kinit, Ke rbe ros ove rwrite s the curre ntly-s tore d ticke t with the
ne w ticke t. For e xample , if you us e kinit to authe nticate as user_A, the ticke t for user_A
will be los t afte r you authe nticate again as user_B.

82

⁠C hapt e r 7. T he Bas ic s o f Managing t he IdM Se r ve r and Se r vic e s

To obtain and s tore anothe r TGT for a us e r, s e t a diffe re nt cre de ntial cache , which
e ns ure s the conte nts of the pre vious cache are not ove rwritte n. You can do this in one of
the following two ways :
Run the export KRB5CCNAME=path_to_different_cache command, and the n us e
kinit to obtain the ticke t.
Run the kinit -c path_to_different_cache command, and the n re s e t the
KRB5CCNAME variable .
To re s tore the original TGT s tore d in the de fault cre de ntial cache :
1. Run the kdestroy command.
2. Re s tore the de fault cre de ntial cache location us ing the unset $KRB5CCNAME
command.

Checking t he Current Logged-in User
To ve rify what TGT is curre ntly s tore d and us e d for authe ntication, us e the klist utility to
lis t cache d ticke ts . In the following e xample , the cache contains a ticke t for user_A, which
me ans that only user_A is curre ntly allowe d to acce s s IdM s e rvice s :
$ klist
Ticket cache: KEYRING:persistent:0:0
Default principal: user_A@EXAMPLE.COM
Valid starting
Expires
Service principal
11/10/2015 08:35:45
11/10/2015 18:35:45
krbtgt/EXAMPLE.COM@EXAMPLE.COM

7.3. T he IdM Command-Line Ut ilit ies
The bas ic command-line s cript for IdM is name d ipa. The ipa s cript is a pare nt s cript for a
numbe r of s ubcommands . The s e s ubcommands are the n us e d to manage IdM. For
e xample , the ipa user-add command adds a ne w us e r:
$ ipa user-add user_name
Command-line manage me nt has ce rtain be ne fits ove r manage me nt in UI; for e xample , the
command-line utilitie s allow manage me nt tas ks to be automate d and pe rforme d
re pe ate dly in a cons is te nt way without manual inte rve ntion. Additionally, while mos t
manage me nt ope rations are available both from the command line and in the we b UI,
s ome tas ks can only be pe rforme d from the command line .

No te
This s e ction only provide s a ge ne ral ove rvie w of the ipa s ubcommands . More
information is available in the othe r s e ctions de dicate d to s pe cific are as of
managing IdM. For e xample , for information about managing us e r e ntrie s us ing the
ipa s ubcommands , s e e Chapte r 9, Managing Users and User Groups.

83

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The ipa s cript can dis play he lp about a particular s e t of s ubcommands : a topic. To dis play
the lis t of available topics , us e the ipa help topics command:
$ ipa help topics
automember
automount
caacl
...

Auto Membership Rule.
Automount
Manage CA ACL rules.

To dis play he lp for a particular topic, us e the ipa help topic_name command. For
e xample , to dis play information about the automember topic:
$ ipa help automember
Auto Membership Rule.
Bring clarity to the membership of hosts and users by configuring
inclusive
or exclusive regex patterns, you can automatically assign a new entries
into
a group or hostgroup based upon attribute information.
...
EXAMPLES:
Add the initial group or hostgroup:
ipa hostgroup-add --desc="Web Servers" webservers
ipa group-add --desc="Developers" devel
...
The ipa s cript can als o dis play a lis t of available ipa commands . To do this , us e the ipa
help commands command:
$ ipa help commands
automember-add
automember-add-condition
rule.
...

Add an automember rule.
Add conditions to an automember

For de taile d he lp on the individual ipa commands , add the --help option to a command.
For e xample :
$ ipa automember-add --help
Usage: ipa [global-options] automember-add AUTOMEMBER-RULE [options]
Add an automember rule.
Options:
-h, --help
show this help message and exit
--desc=STR
A description of this auto member rule
...
For more information about the ipa utility, s e e the ipa(1) man page .

84

⁠C hapt e r 7. T he Bas ic s o f Managing t he IdM Se r ve r and Se r vic e s

7.3.1. Set t ing a List of Values
IdM s tore s e ntry attribute s in lis ts . For e xample :
ipaUserSearchFields: uid,givenname,sn,telephonenumber,ou,title
Any update to a lis t of attribute s ove rwrite s the pre vious lis t. For e xample , an atte mpt to
add a s ingle attribute by only s pe cifying this attribute re place s the whole pre vious lyde fine d lis t with the s ingle ne w attribute . The re fore , whe n changing a lis t of attribute s , you
mus t s pe cify the whole update d lis t.
IdM s upports the following me thods of s upplying a lis t of attribute s :
Us ing the s ame command-line argume nt multiple time s within the s ame command
invocation. For e xample :
$ ipa permission-add --permissions=read --permissions=write -permissions=delete
Enclos ing the lis t in curly brace s , which allows the s he ll to do the e xpans ion. For
e xample :
$ ipa permission-add --permissions={read,write,delete}

7.3.2. Using Special Charact ers
Whe n pas s ing command-line argume nts in ipa commands that include s pe cial characte rs ,
s uch as angle bracke ts (< and >), ampe rs and (&), as te ris k (*), or ve rtical bar (|), you mus t
e s cape the s e characte rs by us ing a backs las h (\). For e xample , to e s cape an as te ris k (*):
$ ipa certprofile-show certificate_profile --out=exported\*profile.cfg
Commands containing une s cape d s pe cial characte rs do not work as e xpe cte d be caus e the
s he ll cannot prope rly pars e s uch characte rs .

7.4. T he IdM Web UI
The Ide ntity Manage me nt we b UI is a we b application for IdM adminis tration. It has mos t of
the capabilitie s of the ipa command-line utility. The re fore , the us e rs can choos e whe the r
the y want to manage IdM from the UI or from the command line .

No te
Manage me nt ope rations available to the logge d-in us e r de pe nd on the us e r's
acce s s rights . For the admin us e r and othe r us e rs with adminis trative privile ge s , all
manage me nt tas ks are available . For re gular us e rs , only a limite d s e t of ope rations
re late d to the ir own us e r account is available .

Support ed Web Browsers
Ide ntity Manage me nt s upports the following brows e rs for conne cting to the we b UI:

85

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Moz illa Fire fox 38 and late r
Google Chrome 46 and late r

7.4.1. Accessing t he Web UI and Aut hent icat ing
The we b UI can be acce s s e d both from IdM s e rve r and clie nt machine s , as we ll as from
machine s outs ide of the IdM domain. Howe ve r, to acce s s the UI from a non-domain
machine , you mus t firs t configure the non-IdM s ys te m to be able to conne ct to the IdM
Ke rbe ros domain; s e e Se ction 7.4.3, “Configuring an Exte rnal Sys te m for Ke rbe ros
Authe ntication to the We b UI” for more de tails .

Accessing t he Web UI
To acce s s the we b UI, type the IdM s e rve r URL into the brows e r addre s s bar:
https://server.example.com
This ope ns the IdM we b UI login s cre e n in your brows e r.

Figure 7.1. Web UI Lo gin Screen

Available Login Met hods
The us e r can authe nticate to the we b UI in two ways :
Wit h an act ive Kerbero s t icket
If the us e r has a valid TGT obtaine d with the kinit utility, clicking Login
automatically authe nticate s the us e r. Note that the brows e r mus t be configure d
prope rly to s upport Ke rbe ros authe ntication.
For information on obtaining a Ke rbe ros TGT, s e e Se ction 7.2, “Logging into IdM
Us ing Ke rbe ros ”. For information on configuring the brows e r, s e e Se ction 7.4.2,
“Configuring the Brows e r for Ke rbe ros Authe ntication”.
By pro viding user name and passwo rd
To authe nticate us ing a us e r name and pas s word, e nte r the us e r name and
pas s word on the we b UI login s cre e n.
IdM als o s upports one -time pas s word (OTP) authe ntication. For more information,
s e e Chapte r 10, One-Time Passwords.
Afte r the us e r authe nticate s s ucce s s fully, the IdM manage me nt window ope ns .

86

⁠C hapt e r 7. T he Bas ic s o f Managing t he IdM Se r ve r and Se r vic e s

Figure 7.2. T he IdM Web UI Layo ut

Web UI Session Lengt h
The de fault we b UI s e s s ion e xpiration pe riod is 20 minute s . If the us e r doe s not pe rform
any action for 20 minute s , the we b UI logs the us e r out. Howe ve r, if the us e r was logge d
in us ing Ke rbe ros , the we b UI automatically logs the us e r in again.

7.4.2. Conf iguring t he Browser f or Kerberos Aut hent icat ion
To e nable authe ntication with Ke rbe ros cre de ntials , you mus t configure your brows e r to
s upport Ke rbe ros ne gotiation for acce s s ing the IdM domain. Note that if your brows e r is
not configure d prope rly for Ke rbe ros authe ntication, an e rror me s s age appe ars afte r
clicking Login on the IdM we b UI login s cre e n.

Figure 7.3. Kerbero s Aut hent icat io n Erro r
You can configure your brows e r for Ke rbe ros authe ntication in thre e ways :
Automatically from the IdM we b UI. This option is only available for Fire fox. Se e
Se ction 7.4.2, “Automatic Fire fox Configuration in the We b UI” for de tails .

87

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Automatically from the command line during the IdM clie nt ins tallation. This option is
only available for Fire fox. Se e Se ction 7.4.2, “Automatic Fire fox Configuration from the
Command Line ” for de tails .
Manually in the Fire fox configuration s e ttings . This option is available for all s upporte d
brows e rs . Se e Se ction 7.4.2, “Manual Brows e r Configuration” for de tails .

No te
The Sys te m-Le ve l Authe ntication Guide include s a trouble s hooting guide for
Ke rbe ros authe ntication in Fire fox. If Ke rbe ros authe ntication is not working as
e xpe cte d, s e e this trouble s hooting guide for more advice .

Aut omat ic Firef ox Conf igurat ion in t he Web UI
To automatically configure Fire fox from the IdM we b UI:
1. Click the link for brows e r configuration on the we b UI login s cre e n.

Figure 7.4. Link t o Co nf iguring t he Bro wser in t he Web UI
2. Choos e the link for Fire fox configuration to ope n the Fire fox configuration page .

Figure 7.5. Link t o t he Firef o x Co nf igurat io n Page
3. Follow the s te ps on the Fire fox configuration page .

88

⁠C hapt e r 7. T he Bas ic s o f Managing t he IdM Se r ve r and Se r vic e s

Aut omat ic Firef ox Conf igurat ion f rom t he Command Line
Fire fox can be configure d from the command line during IdM clie nt ins tallation. To do this ,
us e the --configure-firefox option whe n ins talling the IdM clie nt with the ipa-clientinstall utility:
# ipa-client-install --configure-firefox
The --configure-firefox option cre ate s a global configuration file with de fault Fire fox
s e ttings that e nable Ke rbe ros for s ingle s ign-on (SSO).

Manual Browser Conf igurat ion
To manually configure your brows e r:
1. Click the link for brows e r configuration on the we b UI login s cre e n.

Figure 7.6. Link t o Co nf iguring t he Bro wser in t he Web UI
2. Choos e the link for manual brows e r configuration.

Figure 7.7. Link t o t he Manual Co nf igurat io n Page
3. Look for the ins tructions to configure your brows e r and follow the s te ps .

7.4.3. Conf iguring an Ext ernal Syst em f or Kerberos Aut hent icat ion t o
t he Web UI

89

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

To e nable Ke rbe ros authe ntication to the we b UI from a s ys te m that is not a me mbe r of
the IdM domain, you mus t de fine an IdM-s pe cific Ke rbe ros configuration file on the e xte rnal
machine . Enabling Ke rbe ros authe ntication on e xte rnal s ys te ms is e s pe cially us e ful whe n
your infras tructure include s multiple re alms or ove rlapping domains .
To cre ate the Ke rbe ros configuration file :
1. Copy the /etc/krb5.conf file from the IdM s e rve r to the e xte rnal machine . For
e xample :
# scp /etc/krb5.conf
root@externalmachine.example.com:/etc/krb5_ipa.conf

Warning
Do not ove rwrite the e xis ting krb5.conf file on the e xte rnal machine .
2. On the e xte rnal machine , s e t the te rminal s e s s ion to us e the copie d IdM Ke rbe ros
configuration file :
$ export KRB5_CONFIG=/etc/krb5_ipa.conf
3. Configure the brows e r on the e xte rnal machine as de s cribe d in Se ction 7.4.2,
“Configuring the Brows e r for Ke rbe ros Authe ntication”.
Us e rs on the e xte rnal s ys te m can now us e the kinit utility to authe nticate agains t the
IdM s e rve r domain.

7.4.4. Proxy Servers and Port Forwarding in t he Web UI
Us ing proxy s e rve rs to acce s s the we b UI doe s not re quire any additional configuration in
IdM.
Port forwarding is not s upporte d with the IdM s e rve r. Howe ve r, be caus e it is pos s ible to
us e proxy s e rve rs , an ope ration s imilar to port forwarding can be configure d us ing proxy
forwarding with Ope nSSH and the SOCKS option. This can be configure d us ing the -D
option of the ssh utility; for more information on us ing -D, s e e the s s h(1) man page .

90

⁠C hapt e r 8 . Bac king Up and Re s t o r ing Ide nt it y Manage me nt

Chapt er 8. Backing Up and Rest oring Ident it y
Management
Re d Hat Ente rpris e Linux Ide ntity Manage me nt provide s a s olution to manually back up and
re s tore the IdM s ys te m, for e xample whe n a s e rve r s tops pe rforming corre ctly or data
los s occurs . During backup, the s ys te m cre ate s a dire ctory containing information on your
IdM s e tup and s tore s it. During re s tore , you can us e this backup dire ctory to bring your
original IdM s e tup back.

Impo rtant
Us e the backup and re s tore proce dure s de s cribe d in this chapte r only if you cannot
re build the los t part of the IdM s e rve r group from the re maining s e rve rs in the
de ployme nt, by re ins talling the los t re plicas as re plicas of the re maining one s .
The "Backup and Re s tore in IdM/IPA" Knowle dge bas e s olution de s cribe s how to avoid
los s e s by maintaining s e ve ral s e rve r re plicas . Re building from an e xis ting re plica
with the s ame data is pre fe rable , be caus e the backe d-up ve rs ion us ually contains
olde r, thus pote ntially outdate d, information.

The pote ntial thre at s ce narios that backup and re s tore can pre ve nt include :
Catas trophic hardware failure on a machine occurs and the machine be come s incapable
of furthe r functioning. In this s ituation, you can re ins tall the ope rating s ys te m from
s cratch, configure the machine with the s ame fully-qualifie d domain name (FQDN) and
hos t name , ins tall the IdM package s as we ll as all othe r optional package s re lating to
IdM that we re pre s e nt on the original s ys te m, and re s tore the fully-backe d-up IdM
s e rve r.
An upgrade on an is olate d machine fails . The ope rating s ys te m re mains functional, but
the IdM data is corrupte d, which is why you want to re s tore the IdM s ys te m to a known
good s tate .

Impo rtant
In cas e s of hardware or upgrade failure , s uch as the two me ntione d above ,
re s tore from backup only if all re plicas or a re plica with a s pe cial role , s uch as
the only ce rtificate authority (CA), we re los t. If a re plica with the s ame data s till
e xis ts , it is re comme nde d to de le te the los t re plica and the n re build it from the
re maining one .
Unde s irable change s we re made to the LDAP conte nt, for e xample e ntrie s we re
de le te d, and you want to re ve rt the m. Re s toring backe d-up LDAP data re turns the LDAP
e ntrie s to the pre vious s tate without affe cting the IdM s ys te m its e lf.
The re s tore d s e rve r be come s the only s ource of information for IdM; othe r mas te r
s e rve rs are re -initializ e d from the re s tore d s e rve r. Any data cre ate d afte r the las t backup
was made are los t. The re fore you s hould not us e the backup and re s tore s olution for
normal s ys te m mainte nance . If pos s ible , always re build the los t s e rve r by re ins talling it
as a re plica.

91

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The backup and re s tore fe ature s can be manage d only from the command line and are
not available in the IdM we b UI.

8.1. Full-Server Backup and Dat a-Only Backup
IdM offe rs two backup options :
Full-IdM server backup
Full-s e rve r backup cre ate s a backup copy of all the IdM s e rve r file s as we ll as
LDAP data, which make s it a s tandalone backup. IdM affe cts hundre ds of file s ; the
file s that the backup proce s s copie s is a mix of whole dire ctorie s and s pe cific
file s , s uch as configuration file s or log file s , and re late dire ctly to IdM or to various
s e rvice s that IdM de pe nds on. Be caus e the full-s e rve r backup is a raw file
backup, it is pe rforme d offline . The s cript that pe rforms the full-s e rve r backup
s tops all IdM s e rvice s to e ns ure a s afe cours e of the backup proce s s .
For the full lis t of file s and dire ctorie s that the full-s e rve r backup copie s , s e e
Se ction 8.1.3, “Lis t of Dire ctorie s and File s Copie d During Backup”.
Dat a-o nly Backup
The data-only backup only cre ate s a backup copy of LDAP data and the change log.
The proce s s backs up the IPA-REALM ins tance and can als o back up multiple back
e nds or only a s ingle back e nd; the back e nds include the IPA back e nd and the
CA Dogtag back e nd. This type of backup als o backs up a re cord of the LDAP
conte nt s tore d in LDIF (LDAP Data Inte rchange Format). The data-only backup can
be pe rforme d both online and offline .
By de fault, IdM s tore s the cre ate d backups in the /var/lib/ipa/backup/ dire ctory. The
naming conve ntions for the s ubdire ctorie s containing the backups are :
ipa-full-YEAR-MM-DD-HH-MM-SS in the GMT time z one for the full-s e rve r backup
ipa-data-YEAR-MM-DD-HH-MM-SS in the GMT time z one for the data-only backup

8.1.1. Creat ing a Backup
Both full-s e rve r and data-only backups are cre ate d us ing the ipa-backup utility which
mus t always be run as root.
To cre ate a full-s e rve r backup, run ipa-backup.

Impo rtant
Pe rforming a full-s e rve r backup s tops all IdM s e rvice s be caus e the proce s s mus t
run offline . The IdM s e rvice s will s tart again afte r the backup is finis he d.
To cre ate a data-only backup, run the ipa-backup --data command.
You can add s e ve ral additional options to ipa-backup:
--online pe rforms an online backup; this option is only available with data-only
backups

92

⁠C hapt e r 8 . Bac king Up and Re s t o r ing Ide nt it y Manage me nt

--logs include s the IdM s e rvice log file s in the backup
For furthe r information on us ing ipa-backup, s e e the ipa-backup(1) man page .

8.1.2. Encrypt ing Backup
You can e ncrypt the IdM backup us ing the GNU Privacy Guard (GPG) e ncryption.
To cre ate a GPG ke y:
1. Cre ate a keygen file containing the ke y de tails , for e xample , by running cat
>keygen <keygen < %echo Generating a standard key
> Key-Type: RSA
> Key-Length:2048
> Name-Real: IPA Backup
> Name-Comment: IPA Backup
> Name-Email: root@example.com
> Expire-Dat: 0
> %pubring /root/backup.pub
> %secring /root/backup.sec
> %commit
> %echo done
> EOF
[root@server ~]#
2. Ge ne rate a ne w ke y pair calle d backup and fe e d the conte nts of keygen to the
command. The following e xample ge ne rate s a ke y pair with the path name s
/root/backup.sec and /root/backup.pub:
[root@server ~]#
[root@server ~]#
/root/backup.sec
--keyring

gpg --batch --gen-key keygen
gpg --no-default-keyring --secret-keyring
\
/root/backup.pub --list-secret-keys

To cre ate a GPG-e ncrypte d backup, pas s the ge ne rate d backup ke y to ipa-backup by
s upplying the following options :
--gpg, which ins tructs ipa-backup to pe rform the e ncrypte d backup
--gpg-keyring=GPG_KEYRING, which provide s the full path to the GPG ke yring without
the file e xte ns ion.
For e xample :
[root@server ~]# ipa-backup --gpg --gpg-keyring=/root/backup

93

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
You might e xpe rie nce proble ms if your s ys te m us e s the gpg2 utility to ge ne rate
GPG ke ys be caus e gpg2 re quire s an e xte rnal program to function. To ge ne rate the
ke y pure ly from cons ole in this s ituation, add the pinentry-program
/usr/bin/pinentry-curses line to the .gnupg/gpg-agent.conf file be fore
ge ne rating a ke y.

8.1.3. List of Direct ories and Files Copied During Backup
Dire ctorie s :
/usr/share/ipa/html
/root/.pki
/etc/pki-ca
/etc/pki/pki-tomcat
/etc/sysconfig/pki
/etc/httpd/alias
/var/lib/pki
/var/lib/pki-ca
/var/lib/ipa/sysrestore
/var/lib/ipa-client/sysrestore
/var/lib/ipa/dnssec
/var/lib/sss/pubconf/krb5.include.d/
/var/lib/authconfig/last
/var/lib/certmonger
/var/lib/ipa
/var/run/dirsrv
/var/lock/dirsrv
File s :
/etc/named.conf
/etc/named.keytab
/etc/resolv.conf
/etc/sysconfig/pki-ca
/etc/sysconfig/pki-tomcat
/etc/sysconfig/dirsrv
/etc/sysconfig/ntpd
/etc/sysconfig/krb5kdc
/etc/sysconfig/pki/ca/pki-ca
/etc/sysconfig/ipa-dnskeysyncd
/etc/sysconfig/ipa-ods-exporter
/etc/sysconfig/named
/etc/sysconfig/ods
/etc/sysconfig/authconfig
/etc/ipa/nssdb/pwdfile.txt
/etc/pki/ca-trust/source/ipa.p11-kit
/etc/pki/ca-trust/source/anchors/ipa-ca.crt
/etc/nsswitch.conf
/etc/krb5.keytab
/etc/sssd/sssd.conf
/etc/openldap/ldap.conf

94

⁠C hapt e r 8 . Bac king Up and Re s t o r ing Ide nt it y Manage me nt

/etc/security/limits.conf
/etc/httpd/conf/password.conf
/etc/httpd/conf/ipa.keytab
/etc/httpd/conf.d/ipa-pki-proxy.conf
/etc/httpd/conf.d/ipa-rewrite.conf
/etc/httpd/conf.d/nss.conf
/etc/httpd/conf.d/ipa.conf
/etc/ssh/sshd_config
/etc/ssh/ssh_config
/etc/krb5.conf
/etc/ipa/ca.crt
/etc/ipa/default.conf
/etc/dirsrv/ds.keytab
/etc/ntp.conf
/etc/samba/smb.conf
/etc/samba/samba.keytab
/root/ca-agent.p12
/root/cacert.p12
/var/kerberos/krb5kdc/kdc.conf
/etc/systemd/system/multi-user.target.wants/ipa.service
/etc/systemd/system/multi-user.target.wants/sssd.service
/etc/systemd/system/multi-user.target.wants/certmonger.service
/etc/systemd/system/pki-tomcatd.target.wants/pki-tomcatd@pkitomcat.service
/var/run/ipa/services.list
/etc/opendnssec/conf.xml
/etc/opendnssec/kasp.xml
/etc/ipa/dnssec/softhsm2.conf
/etc/ipa/dnssec/softhsm_pin_so
/etc/ipa/dnssec/ipa-ods-exporter.keytab
/etc/ipa/dnssec/ipa-dnskeysyncd.keytab
/etc/pki/nssdb/cert8.db
/etc/pki/nssdb/key3.db
/etc/pki/nssdb/secmod.db
/etc/ipa/nssdb/cert8.db
/etc/ipa/nssdb/key3.db
/etc/ipa/nssdb/secmod.db
Log file s and dire ctorie s :
/var/log/pki-ca
/var/log/pki/
/var/log/dirsrv/slapd-PKI-IPA
/var/log/httpd
/var/log/ipaserver-install.log
/var/log/kadmind.log
/var/log/pki-ca-install.log
/var/log/messages
/var/log/ipaclient-install.log
/var/log/secure
/var/log/ipaserver-uninstall.log
/var/log/pki-ca-uninstall.log
/var/log/ipaclient-uninstall.log
/var/named/data/named.run

95

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

8.2. Rest oring a Backup
If you have a dire ctory with a backup cre ate d us ing ipa-backup, you can re s tore your IdM
s e rve r or the LDAP conte nt to the s tate in which the y we re whe n the backup was
pe rforme d. You cannot re s tore a backup on a hos t diffe re nt from the hos t on which the
backup was originally cre ate d.

No te
Unins talling an IdM s e rve r doe s not automatically re move the backup of this s e rve r.

8.2.1. Rest oring f rom t he Full-Server or Dat a-Only Backup

Impo rtant
It is re comme nde d that you unins tall a s e rve r be fore pe rforming a full-s e rve r
re s tore on it.
Both full-s e rve r and data-only backups are re s tore d us ing the ipa-restore utility which
mus t always be run as root. Pas s the backup to the command:
Pas s only the name of the dire ctory with the backup if it is locate d in the de fault
/var/lib/ipa/backup/ dire ctory.
Pas s the full path to the backup if the dire ctory containing the backup is not locate d in
the de fault dire ctory. For e xample :
[root@server ~]# ipa-restore /path/to/backup
The ipa-restore utility automatically de te cts what type of backup the backup dire ctory
contains and by de fault pe rforms the s ame type of re s tore .
You can add the following options to ipa-restore:
--data pe rforms a data-only re s tore from a full-s e rve r backup, that is , re s tore s only
the LDAP data compone nt from a backup dire ctory containing the full-s e rve r backup
--online re s tore s the LDAP data in a data-only re s tore online
--instance s pe cifie s which 389 DS ins tance is re s tore d. IdM in Re d Hat
Ente rpris e Linux 7 only us e s the IPA-REALM ins tance , but it might be pos s ible , for
e xample , to cre ate a backup on a s ys te m with s e parate ins tance s ; in s uch cas e s , -instance allows you to re s tore only IPA-REALM. For e xample :
[root@server ~]# ipa-restore --instance=IPA-REALM /path/to/backup
You can us e this option only whe n pe rforming a data-only re s tore .

96

⁠C hapt e r 8 . Bac king Up and Re s t o r ing Ide nt it y Manage me nt

--backend s pe cifie s which back e nd is re s tore d; without this option, ipa-restore
re s tore s all back e nds it dis cove rs . The argume nts de fining the pos s ible back e nds are
userRoot, which re s tore s the IPA data back e nd, and ipaca, which re s tore s the CA back
e nd.
You can us e this option only whe n pe rforming a data-only re s tore .
--no-logs re s tore s the backup without re s toring the log file s

No te
It is re comme nde d that you re boot your s ys te m afte r re s toring from backup.
For furthe r information on us ing ipa-restore, s e e the ipa-re s tore (1) man page .

8.2.2. Rest oring wit h Mult iple Mast er Servers
Re s toring from backup s e ts the re s tore d s e rve r as the ne w data mas te r, and you will be
re quire d to re initializ e all othe r mas te rs afte r the re s tore . To re initializ e the othe r
mas te rs , run the ipa-replica-manage command and, on mas te rs that have a CA
ins talle d, the ipa-csreplica-manage command. For e xample :
[root@server ~]# ipa-replica-manage re-initialize -from=restored_master_FQDN
For furthe r information on re plication during re s tore and on re s toration on othe r mas te rs ,
s e e the ipa-re s tore (1) man page .

8.2.3. Rest oring f rom an Encrypt ed Backup
If you want to re s tore from a backup e ncrypte d with GPG, provide the full path to the
private and public ke ys us ing the --gpg-keyring option. For e xample :
[root@server ~]# ipa-restore --gpg-keyring=/root/backup /path/to/backup

97

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

⁠P art II. Managing User Ident it ies in a Linux Domain

98

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Chapt er 9. Managing Users and User Groups
Us e rs in Ide ntity Manage me nt are able to acce s s s e rvice s and s e rve rs within the domain
through Ke rbe ros authe ntication. This chapte r cove rs ge ne ral manage me nt tas ks for
us e rs , groups , pas s word policie s , and othe r configuration for us e rs .

9.1. Set t ing up User Home Direct ories
A home dire ctory is re quire d for any IdM us e r. Without a home dire ctory in the e xpe cte d
location, a us e r may be unable to log into the domain. While s ys te ms adminis trators can
manage home dire ctorie s outs ide of IdM, it is als o pos s ible to us e a PAM module to cre ate
home dire ctorie s automatically on both IdM s e rve rs and clie nts .

9.1.1. About Home Direct ories
IdM, as part of managing us e rs , can manage us e r home dire ctorie s . Howe ve r, IdM has
ce rtain de fine d parame te rs for any manage d home dire ctorie s :
The de fault pre fix for us e rs ' home dire ctorie s is /home.
IdM doe s not automatically cre ate home dire ctorie s whe n us e rs log in. Automatically
cre ating home dire ctorie s re quire s e ithe r the pam_oddjob_mkhomedir module or the
pam_mkhomedir module . This module can be configure d as part of clie nt ins tallation or
afte r ins tallation, as de s cribe d in Se ction 9.1.2, “Enabling the PAM Home Dire ctory
Module ”.
The home dire ctory proce s s for IdM firs t atte mpts to us e the pam_oddjob_mkhomedir
module be caus e this re quire s fe we r us e r privile ge s and acce s s to cre ate the home
dire ctorie s , as we ll as inte grating s moothly with SELinux. If this module is not available ,
the n the proce s s falls back to the pam_mkhomedir module .

No te
On Re d Hat Ente rpris e Linux 5 clie nts , the clie nt ins tallation s cript us e s the
pam_mkhomedir module e ve n if the pam_oddjob_mkhomedir module is available .
To us e the pam_oddjob_mkhomedir module on Re d Hat Ente rpris e Linux 5, e dit
the PAM configuration manually.
It is pos s ible to us e an NFS file s e rve r that provide s /home that can be made available
to all machine s in the domain and the n automounte d on the IdM s e rve r.
The re are pote ntial is s ue s whe n us ing NFS, s uch as s e curity is s ue s re late d to granting
root acce s s to the NFS us e r, pe rformance is s ue s with loading the e ntire /home tre e ,
and ne twork pe rformance is s ue s for us ing re mote s e rve rs for home dire ctorie s . The re
are s ome ge ne ral guide line s for us ing NFS with Ide ntity Manage me nt:
Us e automount to mount only the us e r's home dire ctory and only whe n the us e r
logs in, rathe r than loading the e ntire /home tre e .
Us e a re mote us e r who has limite d pe rmis s ions to cre ate home dire ctorie s and
mount the s hare on the IdM s e rve r as that us e r. Since the IdM s e rve r runs as an
httpd proce s s , it is pos s ible to us e sudo or a s imilar program to grant limite d
acce s s to the IdM s e rve r to cre ate home dire ctorie s on the NFS s e rve r.

99

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Us e a me chanis m, s uch as the pam_oddjob_mkhomedir module , to cre ate the home
dire ctory as that us e r.
Us ing automounts for home dire ctorie s is de s cribe d in Se ction 9.1.3, “Manually Mounting
Home Dire ctorie s ”.
If a s uitable dire ctory and me chanis m are not available to cre ate home dire ctorie s ,
us e rs may not be able to log in.

9.1.2. Enabling t he PAM Home Direct ory Module
For a home dire ctory to be cre ate d automatically whe n a us e r logs in, IdM can us e e ithe r
the pam_oddjob_mkhomedir module or the pam_mkhomedir module . Be caus e it re quire s
fe we r pe rmis s ions and works we ll with SELinux, IdM pre fe re ntially us e s the
pam_oddjob_mkhomedir module . If that module is not ins talle d, the n it falls back to the
pam_mkhomedir module .

No te
IdM doe s not re quire the pam_oddjob_mkhomedir module or pam_mkhomedir module .
This is be caus e the *_mkhomedir module may try to cre ate home dire ctorie s e ve n
whe n the s hare d s torage is not available . If the module is unable to cre ate the
home dire ctory, the n us e rs can be blocke d from logging into the IdM domain.
The s ys te m adminis trator mus t activate this module on e ach clie nt or s e rve r as
ne e de d.

The re are two ways to e nable the pam_oddjob_mkhomedir (or pam_mkhomedir) module :
The --mkhomedir option can be us e d with the ipa-client-install command. While
this is pos s ible for clie nts , this option is not available to s e rve rs whe n the y are s e t up.
The pam_oddjob_mkhomedir module can be e nable d us ing the s ys te m's authconfig
command. For e xample :
authconfig --enablemkhomedir --update
This option can be us e d for both s e rve r and clie nt machine s pos t-ins tallation.

No te
On Re d Hat Ente rpris e Linux 5 clie nts , the clie nt ins tallation s cript us e s the
pam_mkhomedir module e ve n if the pam_oddjob_mkhomedir module is available . To
us e the pam_oddjob_mkhomedir module on Re d Hat Ente rpris e Linux 5, e dit the PAM
configuration manually.

9.1.3. Manually Mount ing Home Direct ories

100

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

While PAM module s can be us e d to cre ate home dire ctorie s for us e rs automatically, this
may not be de s irable be havior in e ve ry e nvironme nt. In that cas e , home dire ctorie s can
be manually adde d to the IdM s e rve r from s e parate locations us ing NFS s hare s and
automount.
1. Cre ate a ne w location for the us e r dire ctory maps :
[bjensen@server ~]$ ipa automountlocation-add userdirs
Location: userdirs
2. Add a dire ct map to the ne w location's auto.direct file . In this e xample , the mount
point is /share:
[bjensen@server ~]$ ipa automountkey-add userdirs auto.direct -key=/share --info="-ro,soft, ipaserver.example.com:/home/share"
Key: /share
Mount information: -ro,soft, ipaserver.example.com:/home/share
Us ing automounts with IdM is de s cribe d in de tail in Chapte r 18, Using Automount.

9.2. Managing User Ent ries
9.2.1. About User Name Format s
The de fault le ngth for us e r name s is 32 characte rs .
IdM s upports a wide range of us e r name formats , bas e d on the following re gular
e xpre s s ion. Note that the trailing dollar s ign ($) s ymbol is pe rmitte d for Samba 3.x
machine s upport.
[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?
Sys te m limits apply to the us e r name s in IdM. Due to POSIX re quire me nts , portable
name s are not allowe d to s tart with hyphe ns (-).

Impo rtant
If the us e r name you e nte r contains uppe rcas e characte rs , IdM conve rts the m to
lowe rcas e characte rs whe n the us e r name is s ave d.
Eve n if you de fine a us e r name with one or more uppe rcas e characte rs , IdM always
re quire s the us e r to e nte r the us e r name all lowe rcas e during log in. It is als o not
pos s ible to add two us e r name s that only diffe r in le tte r cas ing, for e xample User
and user.

9.2.2. Adding Users
9.2.2.1. From t he Web UI

101

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click Add at the top of the us e rs lis t.

Figure 9.1. Users List
3. Fill in the us e r's firs t and las t name s . The us e r login (UID) is automatically
ge ne rate d bas e d on the us e r's full name , but can be als o s e t manually.

102

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.2. Adding a New User
4. Click the Add and Edit button to go dire ctly to the e xpande d e ntry page and fill in
more attribute information, as in Se ction 9.2.3.1, “From the We b UI”. The us e r e ntry
is cre ate d with s ome bas ic information alre ady fille d in, bas e d on the give n us e r
information and the us e r e ntry te mplate .

103

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.3. User Ident it y Set t ings

104

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.4. User Acco unt Set t ings

9.2.2.2. From t he Command Line
Ne w us e r e ntrie s are adde d with the user-add command. Attribute s (lis te d in Table 9.2,
“De fault Ide ntity Manage me nt Us e r Attribute s ”) can be adde d to the e ntry with s pe cific
value s or the command can be run with no argume nts .
[bjensen@server ~]$ ipa user-add [username] [attributes]
Whe n no argume nts are us e d, the command prompts for the re quire d us e r account
information and us e s the de faults for the othe r attribute s , with the de faults printe d be low.
For e xample :
[bjensen@server ~]$ ipa user-add
First name: John
Last name: Smith
User login [jsmith]: jsmith
-------------------Added user "jsmith"
-------------------User login: jsmith
First name: John
Last name: Smith
Full name: John Smith
Display name: John Smith
Initials: JS
Home directory: /home/jsmith
GECOS: John Smith
Login shell: /bin/sh
Kerberos principal: jsmith@EXAMPLE.COM
Email address: jsmith@example.com
UID: 882600007
GID: 882600007
Password: False
Member of groups: ipausers
Kerberos keys available: False
Any of the us e r attribute s can be pas s e d with the command. This will e ithe r s e t value s for
optional attribute s or ove rride the de fault value s for de fault attribute s .
[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith -manager=bjensen --email=johnls@example.com --homedir=/home/work/johns -password

105

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Impo rtant
Whe n a us e r is cre ate d without s pe cifying a UID or GID numbe r, the n the us e r
account is automatically as s igne d an ID numbe r that is ne xt available in the s e rve r
or re plica range . (Numbe r range s are de s cribe d more in Se ction 9.8, “Managing
Unique UID and GID Numbe r As s ignme nts ”.) This me ans that a us e r always has a
unique numbe r for its UID numbe r and, if configure d, for its private group.
If a numbe r is manually as s igne d to a us e r e ntry, the s e rve r doe s not validate that
the uidNumber is unique . It will allow duplicate IDs ; this is e xpe cte d (though
dis courage d) be havior for POSIX e ntrie s .
If two e ntrie s are as s igne d the s ame ID numbe r, only the firs t e ntry is re turne d in a
s e arch for that ID numbe r. Howe ve r, both e ntrie s will be re turne d in s e arche s for
othe r attribute s or with ipa user-find --all.

9.2.3. Edit ing Users
9.2.3.1. From t he Web UI
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click the name of the us e r to e dit.

Figure 9.5. User List
3. The re are a numbe r of diffe re nt type s of attribute s that can be e dite d for the us e r.
All of the de fault attribute s are lis te d in Table 9.2, “De fault Ide ntity Manage me nt
Us e r Attribute s ”. Mos t of the attribute s in the Identity Settings and Account
Settings are as have de fault value s fille d in for the m bas e d on the us e r
information or on the us e r e ntry te mplate .

106

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.6. User Ident it y Set t ings

107

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.7. User Acco unt Set t ings
4. Edit the fie lds or, if ne ce s s ary, click Add by an attribute to cre ate the attribute on
the e ntry.

Figure 9.8. Co nt act Set t ings
5. Whe n the e dits are done , click the Update link at the top of the page .

9.2.3.2. From t he Command Line
The user-mod command e dits us e r accounts by adding or changing attribute s . At its mos t
bas ic, the user-mod s pe cifie s the us e r account by login ID, the attribute to e dit, and the
ne w value :
[bjensen@server ~]$ ipa user-mod loginID --attributeName=newValue
For e xample , to change a us e r's work title from Editor II to Editor III:
[bjensen@server ~]$ ipa user-mod jsmith --title="Editor III"
Ide ntity Manage me nt allows multi-valued attribute s , bas e d on attribute s in LDAP that are
allowe d to have multiple value s . For e xample , a pe rs on may have two e mail addre s s e s ,
one for work and one for pe rs onal, that are both s tore d in the mail attribute . Managing
multi-value d attribute s can be done us ing the --addattr option.
If an attribute allows multiple value s — like mail — s imply us ing the command-line
argume nt will ove rwrite the value with the ne w value . This is als o true for us ing -setattr. Howe ve r, us ing --addattr will add a ne w attribute ; for a multi-value d attribute , it
adds the ne w value in addition to any e xis ting value s .

Example 9.1. Mult iple Mail At t ribut es
A us e r is cre ate d firs t us ing his work e mail account.

108

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith -email=johnls@example.com
The n, his pe rs onal e mail account is adde d.
[bjensen@server ~]$ ipa user-mod jsmith --addattr=mail=johnnys@me.com
Both e mail addre s s e s are lis te d for the us e r.
[bjensen@server ~]$ ipa user-find jsmith --all
-------------1 user matched
-------------dn: uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
User login: jsmith
.....
Email address: jsmith@example.com, jsmith@new.com
To s e t two value s at the s ame time , us e the --addattr option twice :
[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith -email=johnls@example.com --addattr=mail=johnnys@me.com -addattr=mail=admin@example.com

9.2.4. Delet ing Users
De le ting a us e r account pe rmane ntly re move s the us e r e ntry and all its information from
IdM, including group me mbe rs hips and pas s words . Exte rnal configuration — like a s ys te m
account and home dire ctory — will s till e xis t on any s e rve r or local machine whe re the y
we re cre ate d, but the y cannot be acce s s e d through IdM.
De le ting a us e r account is pe rmane nt. The information cannot be re cove re d; a ne w
account mus t be cre ate d.

No te
If all admin us e rs are de le te d, the n you mus t us e the Dire ctory Manage r account to
cre ate a ne w adminis trative us e r.
Alte rnative ly, any us e r who be longs in the group manage me nt role can als o add a
ne w admin us e r.

9.2.4.1. Wit h t he Web UI
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Se le ct the che ck boxe s by the name s of the us e rs to de le te .

109

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.9. User List
3. Click the Delete link at the top of the tas k are a.
4. Whe n prompte d, confirm the de le te action.

Figure 9.10 . Co nf irming User Remo val

9.2.4.2. From t he Command Line
Us e rs are de le te d us ing the user-del command and the n the us e r login. For e xample , a
s ingle us e r:
[bjensen@server ~]$ ipa user-del jsmith
To de le te multiple us e rs , s imply lis t the us e rs , s e parate d by s pace s .
[bjensen@server ~]$ ipa user-del jsmith bjensen mreynolds cdickens
Whe n de le ting multiple us e rs , us e the --continue option to force the command to
continue re gardle s s of e rrors . A s ummary of the s ucce s s ful and faile d ope rations is
printe d to s tdout whe n the command comple te s . If --continue is not us e d, the n the
command proce e ds with de le ting us e rs until it e ncounte rs an e rror, and the n it e xits .

9.3. Managing Public SSH Keys for Users

110

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Ope nSSH us e s public-private key pairs to authe nticate us e rs . A us e r atte mpts to acce s s
s ome ne twork re s ource and pre s e nts its ke y pair. The machine the n s tore s the us e r's
public ke y in an authorized_keys file . Any time that the us e r atte mpts to acce s s the
re s ource again, the machine s imply che cks its authorized_keys file and the n grants
acce s s automatically to approve d us e rs . If the targe t s ys te m doe s not s hare a common
home dire ctory, the us e r mus t copy the public part of his SSH ke y to the targe t s ys te m he
inte nds to log in to. The public portion of the SSH ke y mus t be copie d to e ach targe t
s ys te m the us e r inte nds to log in to.

No te
SSH ke ys have to be dis tribute d manually and s e parate ly to all machine s in an
e nvironme nt.
On Re d Hat Ente rpris e Linux, the Sys te m Se curity Se rvice s Dae mon (SSSD) can be
configure d to cache and re trie ve us e r SSH ke ys s o that applications and s e rvice s only
have to look in one location for us e r ke ys . Be caus e SSSD can us e Ide ntity Manage me nt as
one of its ide ntity information provide rs , Ide ntity Manage me nt provide s a unive rs al and
ce ntraliz e d re pos itory of ke ys . Adminis trators do not ne e d to worry about dis tributing,
updating, or ve rifying us e r SSH ke ys .

9.3.1. About t he SSH Key Format
Whe n ke ys are uploade d to the IdM e ntry, the ke y format can be e ithe r an Ope nSSH-s tyle
ke y or a raw RFC 4253-s tyle blob. Any RFC 4253-s tyle ke y is automatically conve rte d into
an Ope nSSH-s tyle ke y be fore it is importe d and s ave d into the IdM LDAP s e rve r.
The IdM s e rve r can ide ntify the type of ke y, s uch as an RSA or DSA ke y, from the
uploade d ke y blob. Howe ve r, in a ke y file s uch as id_rsa.pub, a ke y e ntry is ide ntifie d by
its type , the n the ke y its e lf, and the n an additional comme nt or ide ntifie r. For e xample , for
an RSA ke y as s ociate d with a s pe cific hos tname :
"ssh-rsa ABCD1234...== ipaclient.example.com"
All thre e parts from the ke y file can be uploade d to and vie we d for the us e r e ntry, or only
the ke y its e lf can be uploade d.

9.3.2. Uploading User SSH Keys T hrough t he Web UI
1. Ge ne rate a us e r ke y. For e xample , us ing the Ope nSSH tools :
[jsmith@server ~]$ ssh-keygen -t rsa -C jsmith@example.com
Generating public/private rsa key pair.
Enter file in which to save the key (/home/jsmith/.ssh/id_rsa):
Created directory '/home/jsmith/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/jsmith/.ssh/id_rsa.
Your public key has been saved in /home/jsmith/.ssh/id_rsa.pub.
The key fingerprint is:
a5:fd:ac:d3:9b:39:29:d0:ab:0e:9a:44:d1:78:9c:f2 jsmith@example.com
The key's randomart image is:
+--[ RSA 2048]----+

111

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

|
|
|
+ .
|
|
+ =
.
|
|
=
+
|
|
. E S..
|
|
.
. .o
|
|
. . . oo.
|
|
. o . +.+o
|
|
o .o..o+o
|
+-----------------+
2. Copy the public ke y from the ke y file . The full ke y e ntry has the form type key==
comment. Only the key== is re quire d, but the e ntire e ntry can be s tore d.
[jsmith@server ~]$ cat

/home/jsmith/.ssh/id_rsa.pub

ssh-rsa AAAAB3NzaC1yc2E...tJG1PK2Mq++wQ== jsmith@example.com
3. Ope n the Identity tab, and s e le ct the Users s ubtab.
4. Click the name of the us e r to e dit.

Figure 9.11. User List
5. In the Account Settings are a of the Settings tab, click SSH public keys: Add.

112

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.12. SSH public keys in t he Acco unt Set t ings
Alte rnative ly, click Show/Set key if you clicke d Add be fore , but have not confirme d.

Figure 9.13. Sho w/set key
6. Pas te in the public ke y for the us e r, and click Set.

113

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.14. Past ing in t he Public Key
The SSH public keys fie ld now s hows New: key set. Clicking Show/Set key
ope ns the s ubmitte d ke y. To upload multiple ke ys , click the Add link be low the lis t of
public ke ys , and upload the othe r ke ys .
7. Whe n all the ke ys have be e n s ubmitte d, click Save at the top of the us e r's page .
A s ave d public ke y e ntry is dis playe d as the ke y finge rprint, the comme nt (if one
was include d), and the ke y type . If the ke y type is not include d, it is de te rmine d
automatically.

Figure 9.15. Saved Public Key
Afte r uploading the us e r ke ys , configure SSSD to us e Ide ntity Manage me nt as one of its
ide ntity domains and s e t up Ope nSSH to us e SSSD for managing us e r ke ys . This is
cove re d in the "Configuring Se rvice s : Ope nSSH and Cache d Ke ys " s e ction in the Sys te mLe ve l Authe ntication Guide .

9.3.3. Uploading User SSH Keys T hrough t he Command Line
The --sshpubkey option uploads the bas e 64-e ncode d public ke y to the us e r e ntry. For
e xample :
[jsmith@server ~]$ ipa user-mod jsmith --sshpubkey="ssh-rsa RjlzYQo=
ipaclient.example.com"
A re al ke y als o us ually e nds with an e qual s ign (=) but is longe r.
To upload more than one ke y, e nte r multiple --sshpubkey command-line parame te rs :

114

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

--sshpubkey="RjlzYQo=" --sshpubkey="ZEt0TAo="
Afte r uploading the us e r ke ys , configure SSSD to us e Ide ntity Manage me nt as one of its
ide ntity domains and s e t up Ope nSSH to us e SSSD for managing us e r ke ys . This is
cove re d in the "Configuring Se rvice s : Ope nSSH and Cache d Ke ys " s e ction in the Sys te mLe ve l Authe ntication Guide .

9.3.4. Delet ing User Keys
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click the name of the us e r to e dit.

Figure 9.16. User List
3. Go to the Account Settings are a of the Settings tab and click Delete ne xt to the
public ke y you want to re move .

Figure 9.17. Delet ing User Public Key
4. Click Save at the top of the us e r's page to s ave the change s .
The command-line tools can be us e d to re move all ke ys . This is done by running ipa
user-mod with the --sshpubkey= s e t to a blank value ; this re move s all public ke ys for the
us e r. For e xample :
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa user-mod --sshpubkey= jsmith

9.4. Changing Passwords

115

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Pas s word policie s (Chapte r 19, Defining Password Policies) and minimal acce s s re s trictions
can be applie d to a pas s word change ope ration:
Re gular, non-adminis trative us e rs can change only the ir pe rs onal pas s words , and all
pas s words are cons traine d by the IdM pas s word policie s .
This allows adminis trators to s e t initial pas s words for us e rs or to re s e t pas s words
e as ily, while s till ke e ping the final pas s word confide ntial. Since any pas s word s e nt by
an adminis trator to the us e r is te mporary, the re is little s e curity ris k.
Changing a pas s word as the IdM admin us e r ove rride s any IdM pas s word policie s , but
the pas s word e xpire s imme diate ly. This re quire s the us e r to change the pas s word at
the ne xt login. Similarly, any us e r who has pas s word change rights can change a
pas s word and no pas s word policie s are applie d, but the othe r us e r mus t re s e t the
pas s word at the ne xt login.
Changing a pas s word as the LDAP Dire ctory Manage r us e r, using LDAP tools, ove rride s
any IdM pas s word policie s .

9.4.1. From t he Web UI
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click the name of the us e r for whom to re s e t the pas s word. All us e rs can change
the ir own pas s word; only adminis trators or us e rs with de le gate d pe rmis s ions can
change othe r us e r's pas s words .

3. Click Actions at the top of the us e r page and s e le ct Reset Passwo rd.

116

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.18. Reset t ing Passwo rd
4. Whe n the window ope ns , e nte r and confirm the ne w pas s word.

Figure 9.19. Co nf irming New Passwo rd

9.4.2. From t he Command Line
Changing a pas s word — your own or anothe r us e r's — is done us ing the user-mod
command, as with othe r us e r account change s .
[bjensen@ipaserver ~]$ kinit admin
[bjensen@ipaserver ~]$ ipa user-mod jsmith --password

9.5. Enabling and Disabling User Account s
Us e r accounts can be de activate d or disabled. A dis able d us e r cannot log into IdM or its
re late d s e rvice s (like Ke rbe ros ) and he cannot pe rform any tas ks . Howe ve r, the us e r
account s till e xis ts within Ide ntity Manage me nt and all of the as s ociate d information
re mains unchange d.

No te
Any e xis ting conne ctions re main valid until the Ke rbe ros TGT and othe r ticke ts
e xpire . Once the ticke t e xpire s , the us e r cannot re ne w the ticke t.

9.5.1. From t he Web UI
Multiple us e rs can be dis able d from the full us e rs lis t by s e le cting the che ck boxe s by the
de s ire d us e rs and the n clicking the Disable link at the top of the lis t.

117

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.20 . Disable and Enable But t o n at t he T o p o f t he Users List
A us e r account can als o be dis able d from the us e r's individual e ntry page .
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click the name of the us e r to de activate .
3. In the Actions drop-down me nu, s e le ct Disable.

Figure 9.21. Disabling a User
4. Click OK to confirm.
Whe n a us e r account is dis able d, it is s ignifie d by a minus (-) icon for the us e r s tatus in
the us e r lis t and by the us e rname on the e ntry page . Additionally, the te xt for the us e r is
gray (to s how it is inactive ) ins te ad of black.

118

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.22. Disable Ico n f o r User St at us

9.5.2. From t he Command Line
Us e rs are e nable d and dis able d us ing user-enable and user-disable commands . All that
is re quire d is the us e r login. For e xample :
[bjensen@server ~]$ ipa user-disable jsmith

9.6. Unlocking User Account s Aft er Password Failures
If a us e r atte mpts to log in and us e s the wrong pas s word a ce rtain numbe r of time s , the n
that us e r account is locke d. The e xact numbe r of faile d atte mpts that locks an account and
the duration of the lockout is de fine d as part of the pas s word policy (Se ction 19.6, “Se tting
Account Lockout Policie s ”).
A pas s word policy can implicitly de fine a re s e t pe riod, whe re the account unlocks naturally
afte r a ce rtain amount of time laps e s . Howe ve r, if the duration is fairly long or if the
de ployme nt re quire s s tronge r s e curity che cks be fore unlocking an account, the n an
adminis trator can unlock an account manually.
An account is unlocke d us ing the user-unlock command. For e xample :
[bjensen@ipaserver ~]$ kinit admin
[bjensen@ipaserver ~]$ ipa user-unlock jsmith

9.7. Managing User Privat e Groups
On Re d Hat Ente rpris e Linux s ys te ms , e ve ry time a us e r is cre ate d, a corre s ponding,
s e cre t us e r group is automatically cre ate d with that ne w us e r as its only me mbe r. This is
a user private group. Us ing us e r private groups make s it s imple r and s afe r to manage file
and dire ctory pe rmis s ions be caus e umask de faults only have to re s trict us e r acce s s , not
group acce s s .
Whe n a ne w us e r is cre ate d in the IdM domain, it is als o cre ate d with a corre s ponding
private group, following the Re d Hat Ente rpris e Linux conve ntion. For mos t e nvironme nts ,
this is an acce ptable de fault be havior, but the re may be ce rtain us e rs or type s of us e rs

119

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

which do not re quire a private group or the e nvironme nt may alre ady have thos e GIDs
[1] as s igne d to NIS groups or othe r s ys te m groups .

9.7.1. List ing User Privat e Groups
Us e r private groups are s pe cific to a s ingle us e r and are only us e d by the s ys te m. The y
are private , s o the y are not vie wable in the IdM UI. Howe ve r, not e ve ry us e r has a private
group, de pe nding on the options whe n a us e r is cre ate d, s o it can be us e ful to ge t a lis t of
configure d private groups within the IdM us e r domain. Private groups can be s e arche d and
lis te d by us ing the --private option with the group-find command. For e xample :
[root@server ~]# ipa group-find --private
--------------1 group matched
--------------Group name: jsmith
Description: User private group for jsmith
GID: 1084600001
---------------------------Number of entries returned 1
----------------------------

9.7.2. Disabling Privat e Groups f or a Specif ic User
Private group cre ation can be dis able d whe n a us e r is cre ate d by us ing the --noprivate
option.
The re is one thing to note whe n adding a us e r without a private group: the Linux s ys te m
s till e xpe cts a us e r GID for the ne w us e r. Howe ve r, the one de fault us e r group (ipausers)
is a non-POSIX group and, the re fore , doe s not have an as s ociate d GID. So that the add
ope ration doe s not fail, it is ne ce s s ary e ithe r to s e t an e xplicit us e r GID with the --gid
option or to cre ate a group with a GID and add the us e r to that group us ing an
automembership rule (cove re d in Chapte r 24, Defining Automatic Group Membership for
Users and Hosts).
[jsmith@server ~]$ ipa user-add jsmith --first=John --last=Smith -noprivate --gid 10000

9.7.3. Disabling Privat e Groups Globally
Us e r private groups are manage d through the Manage d Entrie s Plug-in in
389 Dire ctory Se rve r. This plug-in can be dis able d, which e ffe ctive ly dis able s private
group cre ation for all ne w us e rs .
This is done us ing the ipa-managed-entries command.
1. Us e the ipa-managed-entries command to lis t pos s ible Manage d Entrie s Plug-in
de finitions . By de fault, the re are two, one for ne w us e rs (UPG) and one for
ne tgroups (NGP).
[root@ipaserver ~]# ipa-managed-entries --list -p DMpassword
Available Managed Entry Definitions:
UPG Definition
NGP Definition

120

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

2. Dis able the de s ire d Manage d Entrie s Plug-in ins tance . For e xample :
[root@ipaserver ~]# ipa-managed-entries -e "UPG Definition" -p
DMpassword disable
Disabling Plugin
3. Re s tart the 389 Dire ctory Se rve r to load the ne w plug-in configuration.
[root@ipaserver ~]# systemctl restart dirsrv.target
Manage d Entrie s Plug-in ins tance s can be re -e nable d with the enable option.

9.8. Managing Unique UID and GID Number Assignment s
An IdM s e rve r ge ne rate s us e r ID (UID) and group ID (GID) value s and s imultane ous ly
e ns ure s that re plicas ne ve r ge ne rate the s ame IDs . The ne e d for unique UIDs and GIDs
might e ve n be acros s IdM domains , if a s ingle organiz ation us e s multiple s e parate
domains .

9.8.1. ID Ranges
The UID and GID numbe rs are divide d into ID ranges. By ke e ping s e parate nume ric range s
for individual s e rve rs and re plicas , the chance s are minimal that an ID value is s ue d for an
e ntry is alre ady us e d by anothe r e ntry on anothe r s e rve r or re plica.
The Dis tribute d Nume ric As s ignme nt (DNA) plug-in, as part of the back e nd
389 Dire ctory Se rve r ins tance for the domain, e ns ure s that range s are update d and
s hare d be twe e n s e rve rs and re plicas ; the plug-in manage s the ID range s acros s all
mas te rs and re plicas . Eve ry s e rve r or re plica has a curre nt ID range and an additional
next ID range that the s e rve r or re plica us e s afte r the curre nt range has be e n de ple te d.
For more information about the DNA Dire ctory Se rve r plug-in, s e e the
Re d Hat Dire ctory Se rve r De ployme nt Guide .

9.8.2. ID Range Assignment s During Inst allat ion
During s e rve r ins tallation, the ipa-server-install command by de fault automatically
as s igns a random curre nt ID range to the ins talle d s e rve r. The s e tup s cript randomly
s e le cts a range of 200,000 IDs from a total of 10,000 pos s ible range s . Se le cting a
random range in this way s ignificantly re duce s the probability of conflicting IDs in cas e you
de cide to me rge two s e parate IdM domains in the future .
Howe ve r, you can de fine a curre nt ID range manually during s e rve r ins tallation by us ing
the following two options with ipa-server-install:
--idstart give s the s tarting value for UID and GID numbe rs ; by de fault, the value is
s e le cte d at random,
--idmax give s the maximum UID and GID numbe r; by de fault, the value is the -idstart s tarting value plus 199,999.
If you have a s ingle IdM s e rve r ins talle d, a ne w us e r or group e ntry re ce ive s a random ID
from the whole range . Whe n you ins tall a ne w re plica and the re plica re que s ts its own ID
range , the initial ID range for the s e rve r s plits and is dis tribute d be twe e n the s e rve r and
re plica: the re plica re ce ive s half of the re maining ID range that is available on the initial

121

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

mas te r. The s e rve r and re plica the n us e the ir re s pe ctive portions of the original ID range
for ne w e ntrie s . Als o, if le s s than 100 IDs from the ID range that was as s igne d to a re plica
re main, me aning the re plica is clos e to de ple ting its allocate d ID range , the re plica
contacts the othe r available s e rve rs with a re que s t for a ne w ID range .
A s e rve r re ce ive s an ID range the firs t time the DNA plug-in is us e d; until the n, the
s e rve r has no ID range de fine d. For e xample , whe n you cre ate a re plica from a mas te r
s e rve r, the re plica doe s not re ce ive an ID range imme diate ly. The re plica re que s ts an ID
range from the initial mas te r only whe n the firs t ID is about to be as s igne d on the re plica.

No te
If the initial mas te r s tops functioning be fore the re plica re que s ts an ID range from it,
the re plica is unable to contact the mas te r with a re que s t for the ID range . An
atte mpt to add a ne w us e r on the re plica fails . In s uch s ituations , you can find out
what ID range is as s igne d to the dis able d mas te r and as s ign an ID range to the
re plica manually, which is de s cribe d in Se ction 9.8.5, “Manual ID Range Exte ns ion and
As s igning a Ne w ID Range ”.

9.8.3. Displaying Current ly Assigned ID Ranges
To dis play which ID range s are configure d for a s e rve r, us e the following commands :
ipa-replica-manage dnarange-show dis plays the curre nt ID range that is s e t on all
s e rve rs or, if you s pe cify a s e rve r, only on the s pe cifie d s e rve r, for e xample :
# ipa-replica-manage
masterA.example.com:
masterB.example.com:
masterC.example.com:

dnarange-show
1001-1500
1501-2000
No range set

# ipa-replica-manage dnarange-show masterA.example.com
masterA.example.com: 1001-1500
ipa-replica-manage dnanextrange-show dis plays the ne xt ID range curre ntly s e t on
all s e rve rs or, if you s pe cify a s e rve r, only on the s pe cifie d s e rve r, for e xample :
# ipa-replica-manage
masterA.example.com:
masterB.example.com:
masterC.example.com:

dnanextrange-show
1001-1500
No on-deck range set
No on-deck range set

# ipa-replica-manage dnanextrange-show masterA.example.com
masterA.example.com: 1001-1500
For more information about the s e two commands , s e e the ipa-re plica-manage (1) man
page .

9.8.4. Aut omat ic ID Range Ext ension Af t er Delet ing a Replica

122

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Whe n you de le te a functioning re plica, the ipa-replica-manage del command re trie ve s
the ID range s that we re as s igne d to the re plica and adds the m as a ne xt range to othe r
available IdM re plicas . This e ns ure s that ID range s re main available to be us e d by othe r
re plicas .
Afte r you de le te a re plica, you can ve rify which ID range s are configure d for othe r
s e rve rs by us ing the ipa-replica-manage dnarange-show and ipa-replica-manage
dnanextrange-show commands , de s cribe d in Se ction 9.8.3, “Dis playing Curre ntly As s igne d
ID Range s ”.

9.8.5. Manual ID Range Ext ension and Assigning a New ID Range
In ce rtain s ituations , it is ne ce s s ary to manually adjus t an ID range :
An assigned ID range has been deplet ed
A re plica has e xhaus te d the ID range that was as s igne d to it, and re que s ting
additional IDs faile d be caus e no more fre e IDs are available in the ID range s of
othe r re plicas . You want to e xte nd the ID range as s igne d to the re plica. This
might involve s plitting an e xis ting ID range or e xte nding it pas t the initial
configure d ID range for the s e rve r. Alte rnative ly, you might want to as s ign a ne w
ID range .

No te
If you as s ign a ne w ID range , the UIDs of the alre ady e xis ting e ntrie s on
the s e rve r or re plica s tay the s ame . This doe s not pos e a proble m
be caus e e ve n if you change the curre nt ID range , IdM ke e ps a re cord of
what range s we re as s igne d in the pas t.
A replica st o pped f unct io ning
ID range is not automatically re trie ve d whe n a re plica die s and ne e ds to be
de le te d, which me ans the ID range pre vious ly as s igne d to the re plica be come s
unavailable . You want to re cove r the ID range and make it available for othe r
re plicas .
If you want to re cove r the ID range be longing to a s e rve r that s toppe d functioning
and as s ign it to anothe r s e rve r, firs t find out what are the ID range value s us ing
the ipa-replica-manage dnarange-show command de s cribe d in Se ction 9.8.3,
“Dis playing Curre ntly As s igne d ID Range s ”, and the n manually as s ign that ID
range to the s e rve r. Als o, to avoid duplicate UIDs or GIDs , make s ure that no ID
value from the re cove re d range was pre vious ly as s igne d to a us e r or group; you
can do this by e xamining the UIDs and GIDs of e xis te nt us e rs and groups .
To manually de fine the ID range s , us e the following two commands :
ipa-replica-manage dnarange-set allows you to de fine the curre nt ID range for a
s pe cifie d s e rve r:
# ipa-replica-manage dnarange-set masterA.example.com 1250-1499
ipa-replica-manage dnanextrange-set allows you to de fine the ne xt ID range for a
s pe cifie d s e rve r:

123

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

# ipa-replica-manage dnanextrange-set masterB.example.com 1001-5000
For more information about the s e commands , s e e the ipa-re plica-manage (1) man page .

Impo rtant
Be care ful not to cre ate ove rlapping ID range s . If any of the ID range s you as s ign to
s e rve rs or re plicas ove rlap, it could re s ult in two diffe re nt s e rve rs as s igning the
s ame ID value to diffe re nt e ntrie s .
Do not s e t ID range s that include UID value s of 1000 and lowe r; the s e value s are
re s e rve d for s ys te m us e . Als o, do not s e t an ID range that would include the 0 value ; the
SSSD s e rvice doe s not handle the 0 ID value .
Whe n e xte nding an ID range manually, make s ure that the ne wly e xte nde d range is
include d in the IdM ID range ; you can che ck this us ing the ipa idrange-find command.
Run the ipa idrange-find -h command to dis play he lp for how to us e ipa idrangefind.

9.8.6. Ensuring T hat ID Values Are Unique
It is re comme nde d to avoid conflicting UIDs or GIDs . UIDs and GIDs s hould always be
unique : two us e rs s hould not have the s ame UID, and two groups s hould not have the
s ame GID.
Aut o mat ic ID assignment
Whe n a us e r or a group is cre ate d inte ractive ly or without a manually s pe cifie d ID
numbe r, the s e rve r as s igns the ne xt available ID numbe r from the ID range to
the us e r account. This e ns ure s that the UID or GID is always unique .
Manual ID assignment
Whe n you as s ign an ID to a us e r or a group e ntry manually, the s e rve r doe s not
ve rify that the s pe cifie d UID or GID is unique ; it doe s not warn you of a conflict if
you choos e a value that is alre ady us e d by anothe r e ntry.
As e xplaine d in Se ction 9.8.7, “Re pairing Change d UID and GID Numbe rs ”, the SSSD
s e rvice doe s not handle e ntrie s with ide ntical IDs . If two e ntrie s s hare the s ame ID
numbe r, a s e arch for this ID only re turns the firs t e ntry. Howe ve r, if you s e arch for othe r
attribute s or run the ipa user-find --all command, both e ntrie s are re turne d.
UIDs and GIDs are both s e le cte d from the s ame ID range . A us e r and a group can have
the s ame ID; no conflict aris e s in this s ituation be caus e the UID and the GID are s e t in two
diffe re nt attribute s : uidNumber and gidNumber.

No te
Se tting the s ame ID for both a us e r and a group allows you to configure us e r private
groups . To cre ate a unique s ys te m group for a us e r in this way, s e t the s ame ID
value for a us e r and als o for a group, in which the only me mbe r is the me ntione d
us e r.

124

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

9.8.7. Repairing Changed UID and GID Numbers
Whe n a us e r logs into an IdM s ys te m or s e rvice , SSSD on that s ys te m cache s the ir us e r
name toge the r with the UID and GID of the us e r. SSSD the n us e s the UID as the
ide ntifying ke y for the us e r. If a us e r with the s ame us e r name but a diffe re nt UID
atte mpts to log into the s ys te m, SSSD re gis te rs two diffe re nt UIDs and as s ume s that
the re are two diffe re nt us e rs with conflicting us e r name s . This can pos e a proble m if a
UID of a us e r change s . In s uch a s ituation, SSSD incorre ctly inte rpre ts the us e r with a
modifie d UID as a ne w us e r, ins te ad of re cogniz ing that it as the s ame us e r with a
diffe re nt UID. If the UID of an e xis ting us e r change s , the us e r cannot log into SSSD and
as s ociate d s e rvice s and domains . This als o affe cts clie nt applications that us e SSSD for
ide ntity information.
To work around this proble m, if a UID or GID change s , cle ar the SSSD cache , which
e ns ure s that the us e r is able to log in again. For e xample , to cle ar the SSSD cache for a
s pe cifie d us e r, us e the sss_cache utility as follows :
[root@server ~]# sss_cache -u user

9.9. Managing User and Group Schema
Whe n a us e r e ntry is cre ate d, it is automatically as s igne d ce rtain LDAP obje ct clas s e s
which, in turn, make available ce rtain attribute s . LDAP attribute s are the way that
information is s tore d in the dire ctory. (This is dis cus s e d in de tail in the Directory Server
Deployment Guide and the Directory Server Schema Reference.)
T able 9.1. Def ault Ident it y Management User Object Classes
Descript io n
IdM obje ct clas s e s

Object Classes
ipaobje ct
ipas s hus e r

Pe rs on obje ct clas s e s

pe rs on
organiz ationalpe rs on
ine torgpe rs on
ine tus e r
pos ixAccount

Ke rbe ros obje ct clas s e s

krbprincipalaux
krbticke tpolicyaux

Manage d e ntrie s (te mplate ) obje ct clas s e s

me pOriginEntry

A numbe r of attribute s are available to us e r e ntrie s . Some are s e t manually and s ome
are s e t bas e d on de faults if a s pe cific value is not s e t. The re is als o an option to add any
attribute s available in the obje ct clas s e s in Table 9.1, “De fault Ide ntity Manage me nt Us e r
Obje ct Clas s e s ”, e ve n if the re is not a UI or command-line argume nt for that attribute .
Additionally, the value s ge ne rate d or us e d by the de fault attribute s can be configure d, as
in Se ction 9.9.4, “Spe cifying De fault Us e r and Group Attribute s ”.

125

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

T able 9.2. Def ault Ident it y Management User At t ribut es
UI Field

Co mmand-Line Opt io n

Required, Opt io nal, o r
Def ault ⁠ [a]

Us e r login
Firs t name
Las t name
Full name
Dis play name
Initials
Home dire ctory
GECOS fie ld
She ll
Ke rbe ros principal
Email addre s s
Pas s word

username
--firs t
--las t
--cn
--dis playname
--initials
--home dir
--ge cos
--s he ll
--principal
--e mail
--pas s word ⁠ [b]

Re quire d
Re quire d
Re quire d
Optional
Optional
De fault
De fault
De fault
De fault
De fault
Optional
Optional

Us e r ID numbe r ⁠ [c]

--uid

De fault

Group ID numbe r [c]

--gidnumbe r

De fault

Stre e t addre s s
City
State /Province
Zip code
Te le phone numbe r
Mobile te le phone numbe r
Page r numbe r
Fax numbe r
Organiz ational unit
Job title
Manage r
Car lice ns e

--s tre e t
--city
--s tate
--pos talcode
--phone
--mobile
--page r
--fax
--orgunit
--title
--manage r
--carlice ns e
--noprivate
--s s hpubke y
--addattr

Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional

SSH Ke ys
Additional attribute s

[a] Required attributes m ust be set for every entry. O ptional attributes m ay be set, while
default attributes are autom atically added with a pre-defined value unless a specific value is
given.
[b] The script prom pts for the new password, rather than accepting a value with the
argum ent.
[c] When a user is created without specifying a UID num ber, then the user account is
autom atically assigned an ID num ber that is next available in the server or replica range.
(Num ber ranges are described m ore in Section 9.8, “Managing Unique UID and GID Num ber
Assignm ents”.) This m eans that a user always has a unique num ber for its UID num ber and, if
configured, for its private group.
If a num ber is manually assigned to a user entry, the server does not validate that the
uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged)
behavior for P O SIX entries.
If two entries are assigned the sam e ID num ber, only the first entry is returned in a search for
that ID num ber. However, both entries will be returned in searches for other attributes or with
ipa user-find --all .

126

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

9.9.1. About Changing t he Def ault User and Group Schema
It is pos s ible to add or change the obje ct clas s e s and attribute s us e d for us e r and group
e ntrie s (Se ction 9.9, “Managing Us e r and Group Sche ma”).
The IdM configuration provide s s ome validation whe n obje ct clas s e s are change d:
All of the obje ct clas s e s and the ir s pe cifie d attribute s mus t be known to the LDAP
s e rve r.
All de fault attribute s that are configure d for the e ntry mus t be s upporte d by the
configure d obje ct clas s e s .
The re are limits to the IdM s che ma validation, howe ve r. Mos t important, the IdM s e rve r
doe s not che ck that the de fine d us e r or group obje ct clas s e s contain all of the re quire d
obje ct clas s e s for IdM e ntrie s . For e xample , all IdM e ntrie s re quire the ipaobject obje ct
clas s . Howe ve r, whe n the us e r or group s che ma is change d, the s e rve r doe s not che ck to
make s ure that this obje ct clas s is include d; if the obje ct clas s is accide ntally de le te d, the n
future e ntry add ope rations will fail.
Als o, all obje ct clas s change s are atomic, not incre me ntal. The e ntire lis t of de fault obje ct
clas s e s has to be de fine d e ve ry time the re is a change . For e xample , a company may
cre ate a cus tom obje ct clas s to s tore e mploye e information like birthdays and
e mployme nt s tart date s . The adminis trator cannot s imply add the cus tom obje ct clas s to
the lis t; he mus t s e t the e ntire lis t of curre nt de fault obje ct clas s e s plus the ne w obje ct
clas s . The existing de fault obje ct clas s e s mus t always be include d whe n the configuration
is update d. Othe rwis e , the curre nt s e ttings will be ove rwritte n, which caus e s s e rious
pe rformance proble ms .

9.9.2. Applying Cust om Object Classes t o New User Ent ries
Us e r and group accounts are cre ate d with a pre -de fine d s e t of LDAP obje ct clas s e s
applie d to the e ntry. Any attribute s which be long to the obje ct clas s can be adde d to the
us e r e ntry.
While the s tandard and IdM-s pe cific LDAP obje ct clas s e s will cove r mos t de ployme nt
s ce narios , adminis trators may have cus tom obje ct clas s e s with cus tom attribute s which
s hould be applie d to us e r e ntrie s .

9.9.2.1. From t he Web UI
1. Add all of the cus tom s che ma e le me nts to the 389 Dire ctory Se rve r ins tance us e d
by Ide ntity Manage me nt. Adding s che ma e le me nts is de s cribe d in the s che ma
chapte r of the Dire ctory Se rve r Adminis trator's Guide .
2. Ope n the IPA Server tab.
3. Se le ct the Configuration s ubtab.
4. Scroll to the User Options are a.

127

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.23. User Opt io ns in Server Co nf igurat io n
5. At the bottom of the us e rs are a, click Add to include a ne w fie ld for anothe r obje ct
clas s .

Impo rtant
Always include the existing de fault obje ct clas s e s whe n the configuration is
update d. Othe rwis e , the curre nt s e ttings will be ove rwritte n. If any obje ct
clas s e s re quire d by Ide ntity Manage me nt are not include d, the n s ubs e que nt
atte mpts to add an e ntry will fail with obje ct clas s violations .

Figure 9.24. Changing Def ault User Object Classes
6. Whe n the change s are comple te , click Save at the top of the Configuration page .

9.9.2.2. From t he Command Line
1. Add all of the cus tom s che ma e le me nts to the 389 Dire ctory Se rve r ins tance us e d
by Ide ntity Manage me nt. Adding s che ma e le me nts is de s cribe d in the s che ma
chapte r of the Dire ctory Se rve r Adminis trator's Guide .

128

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

2. Add the ne w obje ct clas s to the lis t of obje ct clas s e s adde d to e ntrie s . The option
for us e r obje ct clas s e s is --userobjectclasses.

Impo rtant
Always include the existing de fault obje ct clas s e s whe n the configuration is
update d. Othe rwis e , the curre nt s e ttings will be ove rwritte n. If any obje ct
clas s e s re quire d by Ide ntity Manage me nt are not include d, the n s ubs e que nt
atte mpts to add an e ntry will fail with obje ct clas s violations .
All obje ct clas s e s mus t be include d in the lis t of obje ct clas s e s . The information
pas s e d with the config-mod command ove rwrite s the pre vious value s . This can be
done by s pe cifying e ach obje ct clas s with a --userobjectclasses argume nt or by
lis ting all of the obje ct clas s e s in a comma-s e parate d lis t ins ide curly brace s , s uch
as {attr1,attr2,attr3}. For long lis ts , it can be e as ie r to us e the curly brace s than
multiple options . For e xample :
[bjensen@server ~]$ ipa config-mod -userobjectclasses={top,person,organizationalperson,inetorgperson,i
netuser,posixaccount,krbprincipalaux,krbticketpolicyaux,ipaobject,
ipasshuser,employeeinfo}

9.9.3. Applying Cust om Object Classes t o New Group Ent ries
As with us e r e ntrie s , adminis trators may have cus tom obje ct clas s e s with cus tom
attribute s which s hould be applie d to group e ntrie s . The s e can be adde d automatically by
adding the obje ct clas s e s to the IdM s e rve r configuration.

9.9.3.1. From t he Web UI
1. Add all of the cus tom s che ma e le me nts to the 389 Dire ctory Se rve r ins tance us e d
by Ide ntity Manage me nt. Adding s che ma e le me nts is de s cribe d in the s che ma
chapte r of the Dire ctory Se rve r Adminis trator's Guide .
2. Ope n the IPA Server tab.
3. Se le ct the Configuration s ubtab.
4. Scroll to the Group Options are a.

129

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.25. Gro up Opt io ns in Server Co nf igurat io n
5. Click Add to include a ne w fie ld for anothe r obje ct clas s .

Impo rtant
Always include the existing de fault obje ct clas s e s whe n the configuration is
update d. Othe rwis e , the curre nt s e ttings will be ove rwritte n. If any obje ct
clas s e s re quire d by Ide ntity Manage me nt are not include d, the n s ubs e que nt
atte mpts to add an e ntry will fail with obje ct clas s violations .
6. Whe n the change s are comple te , click Save at the top of the Configuration page .

9.9.3.2. From t he Command Line
1. Add all of the cus tom s che ma e le me nts to the 389 Dire ctory Se rve r ins tance us e d
by Ide ntity Manage me nt. Adding s che ma e le me nts is de s cribe d in the s che ma
chapte r of the Dire ctory Se rve r Adminis trator's Guide .
2. Add the ne w obje ct clas s to the lis t of obje ct clas s e s adde d to e ntrie s . The option
for group obje ct clas s e s is --groupobjectclasses.

130

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Impo rtant
Always include the existing de fault obje ct clas s e s whe n the configuration is
update d. Othe rwis e , the curre nt s e ttings will be ove rwritte n. If any obje ct
clas s e s re quire d by Ide ntity Manage me nt are not include d, the n s ubs e que nt
atte mpts to add an e ntry will fail with obje ct clas s violations .
All obje ct clas s e s mus t be include d in the lis t of obje ct clas s e s . The information
pas s e d with the config-mod command ove rwrite s the pre vious value s . This can be
done by s pe cifying e ach obje ct clas s with a --groupobjectclasses argume nt or by
lis ting all of the obje ct clas s e s in a comma-s e parate d lis t ins ide curly brace s , s uch
as {attr1,attr2,attr3}. For long lis ts , it can be e as ie r to us e the curly brace s than
multiple options . For e xample :
[bjensen@server ~]$ ipa config-mod -groupobjectclasses={top,groupofnames,nestedgroup,ipausergroup,ipao
bject,ipasshuser,employeegroup}

9.9.4. Specif ying Def ault User and Group At t ribut es
Ide ntity Manage me nt us e s a te mplate whe n it cre ate s ne w e ntrie s .
For us e rs , the te mplate is ve ry s pe cific. Ide ntity Manage me nt us e s de fault value s for
s e ve ral core attribute s for IdM us e r accounts . The s e de faults can de fine actual value s for
us e r account attribute s (s uch as the home dire ctory location) or it can de fine the format of
attribute value s , s uch as the us e rname le ngth. The s e s e ttings als o de fine the obje ct
clas s e s as s igne d to us e rs .
For groups , the te mplate only de fine s the as s igne d obje ct clas s e s .
The s e de fault de finitions are all containe d in a s ingle configuration e ntry for the IdM
s e rve r, cn=ipaconfig,cn=etc,dc=example,dc=com.
The configuration can be change d us ing the ipa config-mod command.
T able 9.3. Def ault User Paramet ers
Field

Co mmand-Line Opt io n

Descript io ns

Maximum us e rname le ngth

--maxus e rname

Root for home dire ctorie s

--home dire ctory

De fault s he ll

--de faults he ll

Se ts the maximum numbe r
of characte rs for
us e rname s . The de fault
value is e ight.
Se ts the de fault dire ctory to
us e for us e r home
dire ctorie s . The de fault
value is /home.
Se ts the de fault s he ll to us e
for us e rs . The de fault value
is /bin/sh.

131

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Field

Co mmand-Line Opt io n

Descript io ns

De fault us e r group

--de faultgroup

De fault e -mail domain

--e maildomain

Se arch time limit

--s e archtime limit

Se arch s iz e limit

--s e archre cords limit

Us e r s e arch fie lds

--us e rs e arch

Group s e arch fie lds

--groups e arch

Se ts the de fault group to
which all ne wly cre ate d
accounts are adde d. The
de fault value is ipausers,
which is automatically
cre ate d during the IdM
s e rve r ins tallation proce s s .
Se ts the e mail domain to
us e to cre ate e mail
addre s s e s bas e d on the
ne w accounts . The de fault is
the IdM s e rve r domain.
Se ts the maximum amount
of time , in s e conds , to
s pe nd on a s e arch be fore
the s e rve r re turns re s ults .
Se ts the maximum numbe r
of re cords to re turn in a
s e arch.
Se ts the fie lds in a us e r
e ntry that can be us e d as a
s e arch s tring. Any attribute
lis te d has an inde x ke pt for
that attribute , s o s e tting too
many attribute s could affe ct
s e rve r pe rformance .
Se ts the fie lds in a group
e ntry that can be us e d as a
s e arch s tring.
Se ts the bas e DN to us e
whe n cre ating s ubje ct DNs
for clie nt ce rtificate s . This is
configure d whe n the s e rve r
is s e t up.
De fine s an obje ct clas s that
is us e d to cre ate IdM us e r
accounts . This can be
invoke d multiple time s . The
comple te lis t of obje ct
clas s e s mus t be give n
be caus e the lis t is
ove rwritte n whe n the
command is run.
De fine s an obje ct clas s that
is us e d to cre ate IdM group
accounts . This can be
invoke d multiple time s . The
comple te lis t of obje ct
clas s e s mus t be give n
be caus e the lis t is
ove rwritte n whe n the
command is run.

Ce rtificate s ubje ct bas e

De fault us e r obje ct clas s e s

--us e robje ctclas s e s

De fault group obje ct
clas s e s

--groupobje ctclas s e s

132

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Field

Co mmand-Line Opt io n

Descript io ns

Pas s word e xpiration
notification

--pwde xpnotify

Se ts how long, in days ,
be fore a pas s word e xpire s
for the s e rve r to s e nd a
notification.
Se ts the format of
pas s words that are allowe d
for us e rs .

Pas s word plug-in fe ature s

9.9.4.1. Viewing At t ribut es f rom t he Web UI
1. Ope n the IPA Server tab.
2. Se le ct the Configuration s ubtab.
3. The comple te configuration e ntry is s hown in thre e s e ctions , one for all s e arch
limits , one for us e r te mplate s , and one for group te mplate s .

Figure 9.26. Set t ing Search Limit s

Figure 9.27. User At t ribut es

133

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.28. Gro up At t ribut es

9.9.4.2. Viewing At t ribut es f rom t he Command Line
The config-show command s hows the curre nt configuration which applie s to all ne w us e r
accounts . By de fault, only the mos t common attribute s are dis playe d; us e the --all option
to s how the comple te configuration.
[bjensen@server ~]$ kinit admin
[bjensen@server ~]$ ipa config-show --all
dn: cn=ipaConfig,cn=etc,dc=example,dc=com
Maximum username length: 32
Home directory base: /home
Default shell: /bin/sh
Default users group: ipausers
Default e-mail domain: example.com
Search time limit: 2
Search size limit: 100
User search fields: uid,givenname,sn,telephonenumber,ou,title
Group search fields: cn,description
Enable migration mode: FALSE
Certificate Subject base: O=EXAMPLE.COM
Default group objectclasses: top, groupofnames, nestedgroup,
ipausergroup, ipaobject
Default user objectclasses: top, person, organizationalperson,
inetorgperson, inetuser, posixaccount, krbprincipalaux,
krbticketpolicyaux, ipaobject, ipasshuser
Password Expiration Notification (days): 4
Password plugin features: AllowNThash
SELinux user map order: guest_u:s0$xguest_u:s0$user_u:s0$staff_u:s0s0:c0.c1023$unconfined_u:s0-s0:c0.c1023
Default SELinux user: unconfined_u:s0-s0:c0.c1023
Default PAC types: MS-PAC, nfs:NONE
cn: ipaConfig
objectclass: nsContainer, top, ipaGuiConfig, ipaConfigObject

9.10. Managing User Groups
Us e r groups are a way of ce ntraliz ing control ove r important manage me nt tas ks ,
particularly acce s s control and pas s word policie s . Four groups are cre ate d during the
ins tallation, s pe cifically for us e by IdM ope rations :
ipaus e rs , which contains all us e rs .
admins , which contains adminis trative us e rs . The initial admin us e r be longs to this
group.

134

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

trus te d admins , which contains adminis trative us e rs us e d to manage Active Dire ctory
trus ts .
e ditors , which is a s pe cial group for us e rs working through the we b UI. This group
allows us e rs to edit othe r us e rs ' e ntrie s , though without all of the rights of the admin
us e r.

No te
Some ope rating s ys te ms limit the numbe r of groups that can be as s igne d to s ys te m
us e rs . For e xample , Solaris and AIX s ys te ms both limit us e rs to 16 groups pe r us e r.
This can be an is s ue whe n us ing ne s te d groups , whe n a us e r may be automatically
adde d to multiple groups .

9.10.1. T ypes of Groups in IdM
All groups in Ide ntity Manage me nt are e s s e ntially static groups , me aning that the
me mbe rs of the group are manually and e xplicitly adde d to the group. IdM allows nested
groups, whe re a group is a me mbe r of anothe r group. In that cas e , all of the group
me mbe rs of the me mbe r group automatically be long to the pare nt group, as we ll.
Autome mbe rs hip rule s allow ne w us e rs to be adde d to groups automatically, us ing
attribute s in the us e r e ntry to de te rmine what groups the us e r s hould be long to.
Autome mbe rs hip rule s are cove re d in Chapte r 24, Defining Automatic Group Membership
for Users and Hosts.
The way groups are de fine d in IdM is s imple , but the re are diffe re nt configuration options
for groups which can change what kinds of me mbe rs can be adde d.
Some type s of groups in IdM are bas e d not on how me mbe rs are adde d, but rathe r whe re
the me mbe r e ntrie s originate :
Inte rnal groups (the de fault), whe re all me mbe rs be long to the IdM domain.
Exte rnal groups , whe re s ome or all of the me mbe rs e xis t in an ide ntity s tore outs ide of
the IdM domain. This can be a local s ys te m, an Active Dire ctory domain, or a dire ctory
s e rvice .
Anothe r diffe re nce is whe the r groups are cre ate d with POSIX attribute s . Mos t Linux us e rs
re quire s ome kind of POSIX attribute s , but groups which inte ract with Active Dire ctory or
Samba mus t be non-POSIX. By de fault, IdM cre ate s POSIX groups . The re is an e xplicit
option to cre ate a non-POSIX group (by adding the --nonposix option).
Be caus e groups are e as y to cre ate , it is pos s ible to be ve ry fle xible in what groups to
cre ate and how the y are organiz e d. Groups can be de fine d around organiz ational divis ions
like de partme nts , phys ical locations , or IdM or infras tructure us age guide line s for acce s s
controls .

9.10.2. Group Object Classes
Whe n a group e ntry is cre ate d, it is automatically as s igne d ce rtain LDAP obje ct clas s e s .
(LDAP obje ct clas s e s and attribute s are dis cus s e d in de tail in the Directory Server
Deployment Guide and the Directory Server Schema Reference.) For groups , only two
attribute s truly matte r: the name and the de s cription.
T able 9.4. Def ault Ident it y Management Gro up Object Classes

135

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

T able 9.4. Def ault Ident it y Management Gro up Object Classes
Descript io n
IdM obje ct clas s e s

Object Classes
ipaobje ct
ipaus e rgroup
ne s te dgroup

Group obje ct clas s e s

groupofname s

9.10.2.1. Creat ing User Groups
9.10 .2.1.1. Wit h t he Web UI
1. Ope n the Identity tab, and s e le ct the User Groups s ubtab.
2. Click Add at the top of the groups lis t.

Figure 9.29. List o f User Gro ups
3. Ente r information for the group.

136

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.30 . Adding a User Gro up
A unique name . This is the ide ntifie r us e d for the group in the IdM domain, and it
cannot be change d afte r it is cre ate d. The name cannot contain s pace s , but
othe r s e parators like an unde rs core (_) are allowe d.
A te xt de s cription of the group.
Whe the r the group is a POSIX group, which adds Linux-s pe cific information to the
e ntry. By de fault, all groups are POSIX groups unle s s the y are e xplicitly
configure d not to be . Non-POSIX groups can be cre ate d for inte rope rability with
Windows or Samba.
Optionally, the GID numbe r for the group. All POSIX groups re quire a GID
numbe r, but IdM automatically as s igns the GID numbe r.
Se tting a GID numbe r is not ne ce s s ary be caus e of the ris k of collis ions . If a GID
numbe r is give n manually, IdM will not ove rride the s pe cifie d GID numbe r, e ve n
if it is not unique .
4. Click the Add and Edit button to go imme diate ly to the me mbe r s e le ction page .
5. Se le ct the me mbe rs , as de s cribe d in Se ction 9.10.2.2.1, “With the We b UI (Group
Page )”.
9.10 .2.1.2. Wit h t he Co mmand Line

137

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Ne w groups are cre ate d us ing the group-add command. (This adds only the group;
me mbe rs are adde d s e parate ly.)
Two attribute s are always re quire d: the group name and the group de s cription. If thos e
attribute s are not give n as argume nts , the n the s cript prompts for the m.
[bjensen@server ~]$ ipa group-add groupName --desc="description" [-nonposix]
Additionally, the re is one othe r configuration option, --nonposix. (By de fault, all groups
are cre ate d as POSIX groups .) To e nable inte rope rability with Windows us e rs and groups
and programs like Samba, it is pos s ible to cre ate non-POSIX groups by us ing the -nonposix option. This option te lls the s cript not to add the posixGroup obje ct clas s to the
e ntry.
For e xample :
[bjensen@server ~]$ ipa group-add examplegroup --desc="for examples" -nonposix
---------------------Added group "examplegroup"
---------------------Group name: examplegroup
Description: for examples
GID: 855800010
Whe n no argume nts are us e d, the command prompts for the re quire d group account
information:
[bjensen@server ~]$ ipa group-add
Group name: engineering
Description: for engineers
------------------------Added group "engineering"
------------------------Group name: engineering
Description: for engineers
GID: 387115842

138

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Impo rtant
Whe n a group is cre ate d without s pe cifying a GID numbe r, the n the group e ntry is
as s igne d the ID numbe r that is ne xt available in the s e rve r or re plica range .
(Numbe r range s are de s cribe d more in Se ction 9.8, “Managing Unique UID and GID
Numbe r As s ignme nts ”.) This me ans that a group always has a unique numbe r for its
GID numbe r.
If a numbe r is manually as s igne d to a group e ntry, the s e rve r doe s not validate that
the gidNumber is unique . It will allow duplicate IDs ; this is e xpe cte d (though
dis courage d) be havior for POSIX e ntrie s .
If two e ntrie s are as s igne d the s ame ID numbe r, only the firs t e ntry is re turne d in a
s e arch for that ID numbe r. Howe ve r, both e ntrie s will be re turne d in s e arche s for
othe r attribute s or with ipa group-find --all.

No te
You cannot e dit the group name . The group name is the primary ke y, s o changing it
is the e quivale nt of de le ting the group and cre ating a ne w one .

9.10.2.2. Adding Group Members
9.10 .2.2.1. Wit h t he Web UI (Gro up Page)

No te
This proce dure adds a us e r to a group. Us e r groups can contain othe r us e r groups
as the ir me mbe rs . The s e are nested groups .
It can take up to s e ve ral minute s for the me mbe rs of the child group to s how up as
me mbe rs of the pare nt group. This is e s pe cially true on virtual machine s whe re the
ne s te d groups have more than 500 me mbe rs .
Whe n cre ating ne s te d groups , be care ful not to cre ate recursive groups . For
e xample , if GroupA is a me mbe r of GroupB, do not add GroupB as a me mbe r of
GroupA. Re curs ive groups are not s upporte d and can caus e unpre dictable be havior.

1. Ope n the Identity tab, and s e le ct the User Groups s ubtab.
2. Click the name of the group to which to add me mbe rs .

139

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.31. Gro up List
3. Click Add at the top of the tas k are a.

Figure 9.32. Gro ups Menu
4. Se le ct the che ck box by the name s of the us e rs to add, and click the right arrow
button, >, to move the name s to the s e le ction box.

Figure 9.33. Adding Users int o a User Gro up

140

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

5. Click the Add button.
Group me mbe rs can be us e rs or othe r us e r groups . It can take up to s e ve ral minute s for
the me mbe rs of the child group to s how up as me mbe rs of the pare nt group. This is
e s pe cially true on virtual machine s whe re the ne s te d groups have more than 500
me mbe rs .
9.10 .2.2.2. Wit h t he Web UI (User's Page)
Us e rs can als o be adde d to a group through the us e r's page .
1. Ope n the Identity tab, and s e le ct the Users s ubtab.
2. Click the name of the us e r to e dit.

3. Ope n the User Groups tab on the us e r e ntry page .
4. Click the Add link at the top of the tas k are a.

Figure 9.34. Adding User Gro ups
5. Se le ct the che ck box by the name s of the groups for the us e r to join, and click the
right arrow button, >, to move the groups to the s e le ction box.

141

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.35. Select ing Gro ups a Member Sho uld be Added t o
6. Click the Add button.
9.10 .2.2.3. Wit h t he Co mmand Line
Me mbe rs are adde d to a group us ing the group-add-member command. This command can
add both us e rs as group me mbe rs and othe r groups as group me mbe rs .
The s yntax of the group-add-member command re quire s only the group name and the
us e rs or groups to add. Lis ts of e ntrie s can be s e t by us ing the option multiple time s with
the s ame command invocation or by lis ting the options in a comma-s e parate d lis t ins ide
curly brace s , s uch as --option={val1,val2,val3}.
[bjensen@server ~]$ ipa group-add-member groupName [--users=user1 ...]
[--groups=groups1 ...]
For e xample , this adds thre e us e rs to the engineering group:
[bjensen@server ~]$ ipa group-add-member engineering --users=jsmith -users=bjensen --users=mreynolds
Group name: engineering
Description: for engineers
GID: 387115842
Member users: jsmith,bjensen,mreynolds
------------------------Number of members added 3
------------------------Like wis e , othe r groups can be adde d as me mbe rs , which cre ate s ne s te d groups :
[bjensen@server ~]$ ipa group-add-member engineering --groups=dev -groups=qe1 --groups=dev2
Group name: engineering
Description: for engineers
GID: 387115842

142

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Member groups: dev,qe1,dev2
------------------------Number of members added 3
------------------------Whe n dis playing ne s te d groups , me mbe rs are lis te d as me mbe rs and the me mbe rs of
any me mbe r groups are lis te d as indire ct me mbe rs . For e xample :
[bjensen@server ~]$ ipa group-show examplegroup
Group name: examplegroup
Description: for examples
GID: 93200002
Member users: jsmith,bjensen,mreynolds
Member groups: californiausers
Indirect Member users: sbeckett,acalavicci
It can take up to s e ve ral minute s for the me mbe rs of the child group to s how up as
me mbe rs of the pare nt group. This is e s pe cially true on virtual machine s whe re the
ne s te d groups have more than 500 me mbe rs .

No te
Whe n cre ating ne s te d groups , be care ful not to cre ate recursive groups . For
e xample , if GroupA is a me mbe r of GroupB, do not add GroupB as a me mbe r of
GroupA. Re curs ive groups are not s upporte d and can caus e unpre dictable be havior.
A group me mbe r is re move d us ing the group-remove-member command.
[bjensen@server ~]$ ipa group-remove-member engineering --users=jsmith
Group name: engineering
Description: for engineers
GID: 855800009
Member users: bjensen,mreynolds
--------------------------Number of members removed 1
--------------------------9.10 .2.2.4. Viewing Direct and Indirect Members o f a Gro up
Us e r groups can contain othe r us e r groups as me mbe rs . This is calle d a nested group.
This als o me ans that a group has two type s of me mbe rs :
Direct members, which are adde d e xplicitly to the group
Indirect members, which are me mbe rs of the group be caus e the y are me mbe rs of
anothe r us e r group which is a me mbe r of the group
The IdM we b UI has an e as y way to vie w dire ct and indire ct me mbe rs of a group. The
me mbe rs lis t is filte re d by me mbe r type , and this can be toggle d by s e le cting the Direct
and Indirect radio buttons at the top right corne r of the me mbe rs lis t.

143

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.36. Indirect and Direct Members
Be ing able to track indire ct me mbe rs make s it e as ie r to as s ign group me mbe rs hip
prope rly, without duplicating me mbe rs hip.

9.10.2.3. Delet ing User Groups
Whe n a us e r group is de le te d, only the group is re move d. The us e r accounts of group
me mbe rs (including ne s te d groups ) are not affe cte d. Additionally, any acce s s control
de le gations that apply to that group are re move d.

Warning
De le ting a group is imme diate and pe rmane nt. If any group configuration (s uch as
de le gations ) is re quire d, it mus t be as s igne d to anothe r group or a ne w group
cre ate d.

9.10 .2.3.1. Wit h t he Web UI
1. Ope n the Identity tab, and s e le ct the User Groups s ubtab.
2. Se le ct the che ck box by the name of the group to de le te .

Figure 9.37. Select ing Gro ups t o Be Delet ed

144

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

3. Click the Delete link at the top of the tas k are a.
4. Whe n prompte d, confirm the de le te action.

Figure 9.38. Co nf irming Gro up Remo val
9.10 .2.3.2. Wit h t he Co mmand Line
The group-del command to de le te s the s pe cifie d group. For e xample :
[bjensen@server ~]$ ipa group-del examplegroup

9.10.3. Searching f or Users and Groups
The us e r s e arche s in IdM can be run agains t s imple (full word) or partial s e arch s trings .
The range of attribute s that are s e arche d is configure d as part of the de fault IdM
configuration, as in Se ction 9.9.4, “Spe cifying De fault Us e r and Group Attribute s ”.

9.10.3.1. Set t ing Search Limit s
9.10 .3.1.1. T ypes o f Search Limit s and Where T hey Apply
Some s e arche s can re s ult in a large numbe r of e ntrie s be ing re turne d, pos s ibly e ve n all
e ntrie s . Se arch limits improve ove rall s e rve r pe rformance by limiting how long the s e rve r
s pe nds in a s e arch and how many e ntrie s are re turne d.
Se arch limits have a dual purpos e to improve s e rve r pe rformance by re ducing the s e arch
load and to improve us ability by re turning a s malle r — and the re fore e as ie r to brows e —
s e t of e ntrie s .
The IdM s e rve r has s e ve ral diffe re nt limits impos e d on s e arche s :
The search limit configuration for the IdM server. This is a s e tting for the IdM s e rve r
its e lf, which is applie d to all re que s ts s e nt to the s e rve r from all IdM clie nts , the IdM CLI
tools , and the IdM we b UI for normal page dis play.
By de fault, this limit is 100 e ntrie s .
The time limit configuration for the IdM server. Much like the s e arch s iz e limit, the time
limit s e ts a maximum amount of time that the IdM s e rve r, its e lf, waits for s e arche s to
run. Once it re ache s that limit, the s e rve r s tops the s e arch and re turns whate ve r
e ntrie s we re re turne d in that time .

145

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

By de fault, this limit is two s e conds .
The page size limit. Although not s trictly a s e arch limit, the page s iz e limit doe s limit
how many e ntrie s are re turne d pe r page . The s e rve r re turns the s e t of e ntrie s , up to
the s e arch limit, and the n s orts and dis plays 20 e ntrie s pe r page . Paging re s ults
make s the re s ults more unde rs tandable and more vie wable .
This is hard-code d to 20 for all s e arche s .
The LDAP search limit (--pkey option). All s e arche s pe rforme d in the UI, and CLI
s e arche s which us e the --pkey option, ove rride the s e arch limit s e t in the IdM s e rve r
configuration and us e the s e arch limit s e t in the unde rlying LDAP dire ctory.
By de fault, this limit is 2000 e ntrie s . It can be e dite d by e diting the
389 Dire ctory Se rve r configuration.
9.10 .3.1.2. Set t ing IdM Search Limit s
Search limits s e t caps on the numbe r of re cords re turne d or the time s pe nt s e arching
whe n que rying the databas e for us e r or group e ntrie s . The re are two type s of s e arch
limits : time limits and s iz e (numbe r) limits .
With the de fault s e ttings , us e rs are limite d to two-s e cond s e arche s and no more than 100
re cords re turne d pe r s e arch.

Impo rtant
Se tting s e arch s iz e or time limits too high can ne gative ly affe ct IdM s e rve r
pe rformance .

9.10 .3.1.2.1. Wit h t he Web UI
1. Ope n the IPA Server tab.
2. Se le ct the Configuration s ubtab.
3. Scroll to the Search Options are a.

146

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.39. Set t ing t he Search Size and T ime Limit
4. Change the s e arch limit s e ttings .
Search size limit, the maximum numbe r of re cords to re turn in a s e arch.
Search time limit, the maximum amount of time , in s e conds , to s pe nd on a
s e arch be fore the s e rve r re turns re s ults .

No te
Se tting the time limit or s iz e limit value to -1 me ans that the re are no limits
on s e arche s .
5. Whe n the change s are comple te , click the Update link at the top of the
Configuration page .
9.10 .3.1.2.2. Wit h t he Co mmand Line
The s e arch limits can be change d us ing the config-mod command.
[bjensen@server ~]$ ipa config-mod --searchtimelimit=5 -searchrecordslimit=500
Max. username length: 32
Home directory base: /home
Default shell: /bin/sh
Default users group: ipausers
Default e-mail domain for new users: example.com
Search time limit: 5
Search size limit: 50
User search fields: uid,givenname,sn,telephonenumber,ou,title

147

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Group search fields: cn,description
Enable migration mode: FALSE
Certificate Subject base: O=EXAMPLE.COM
Password Expiration Notification (days): 4

No te
Se tting the time limit or s iz e limit value to -1 me ans that the re are no limits on
s e arche s .

9.10 .3.1.3. Overriding t he Search Def ault s
Part of the s e rve r configuration is s e tting global de faults for s iz e and time limits on
s e arche s . While the s e limits are always e nforce d in the we b UI, the y can be ove rridde n
with any *-find command run through the command line .
The --sizelimit and --timelimit options s e t alte rnative s iz e and time limits ,
re s pe ctive ly, for that s pe cific command run. The limits can be highe r or lowe r, de pe nding
on the kinds of re s ults you ne e d.
For e xample , if the de fault time limit is 60 s e conds and a s e arch is going to take longe r,
the time limit can be incre as e d to 120 s e conds :
[jsmith@ipaserver ~]$ ipa user-find smith --timelimit=120

9.10.3.2. Set t ing Search At t ribut es
A s e arch for us e rs or groups doe s not automatically s e arch e ve ry pos s ible attribute for
that attribute . Rathe r, it s e arche s a s pe cific s ubs e t of attribute s , and that lis t is
configurable .
Whe n adding attribute s to the us e r or group s e arch fie lds , make s ure that the re is a
corre s ponding inde x within the LDAP dire ctory for that attribute . Se arche s are pe rforme d
bas e d on inde xe s . Mos t s tandard LDAP attribute s have inde xe s , but any cus tom attribute s
mus t have inde xe s cre ate d for the m. Cre ating inde xe s is de s cribe d in the inde xe s
chapte r in the Dire ctory Se rve r Adminis trator's Guide .
9.10 .3.2.1. Def ault At t ribut es Checked by Searches
By de fault, the re are s ix attribute s that are inde xe d for us e r s e arche s and two that are
inde xe d for group s e arche s . The s e are lis te d in Table 9.5, “De fault Se arch Attribute s ”. All
s e arch attribute s are s e arche d in a us e r/group s e arch.
T able 9.5. Def ault Search At t ribut es
User Search At t ribut es
Firs t name
Login ID
Organiz ational unit
Gro up Search At t ribut es
Name

148

Las t name
Job title
Phone numbe r
De s cription

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

The attribute s which are s e arche d in us e r and group s e arche s can be change d, as
de s cribe d in Se ction 9.10.3.2, “Se tting Se arch Attribute s ” and Se ction 9.10.3.2.3, “Changing
Group Se arch Attribute s ”.
9.10 .3.2.2. Changing User Search At t ribut es
9.10 .3.2.2.1. Fro m t he Web UI
1. Ope n the IPA Server tab.
2. Se le ct the Configuration s ubtab.
3. Scroll to the User Options are a.

Figure 9.40 . User Opt io ns Area o f t he Co nf igurat io n Subt ab
4. Add any additional s e arch attribute s , in a comma-s e parate d lis t, in the User search
fields fie ld.
5. Whe n the change s are comple te , click Save at the top of the Configuration page .
9.10 .3.2.2.2. Fro m t he Co mmand Line
To change the s e arch attribute s , us e the --usersearch option to s e t the attribute s for
us e r s e arche s .
[bjensen@server ~]$ ipa config-mod --usersearch=
{uid,givenname,sn,telephonenumber,ou,title}

No te
Always give the comple te lis t of s e arch attribute s . Whate ve r value s are pas s e d with
the configuration argume nt ove rwrite the pre vious s e ttings .
This can be done by s pe cifying e ach attribute with a --usersearch argume nt or by
lis ting all of the attribute s in a comma-s e parate d lis t ins ide curly brace s , s uch as
{attr1,attr2,attr3}. For long lis ts , it can be e as ie r to us e the curly brace s than
multiple options .

149

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

9.10 .3.2.3. Changing Gro up Search At t ribut es
A s e arch for us e rs or groups doe s not automatically s e arch e ve ry pos s ible attribute for
that attribute . Rathe r, it s e arche s a s pe cific s ubs e t of attribute s , and that lis t is
configurable .
Whe n adding attribute s to the us e r or group s e arch fie lds , make s ure that the re is a
corre s ponding inde x within the LDAP dire ctory for that attribute . Se arche s are pe rforme d
bas e d on inde xe s . Mos t s tandard LDAP attribute s have inde xe s , but any cus tom attribute s
mus t have inde xe s cre ate d for the m. Cre ating inde xe s is de s cribe d in the inde xe s
chapte r in the Dire ctory Se rve r Adminis trator's Guide .
9.10 .3.2.3.1. Fro m t he Web UI
1. Ope n the IPA Server tab.
2. Se le ct the Configuration s ubtab.
3. Scroll to the Group Options are a.

Figure 9.41. Gro up Opt io ns Area o f t he Co nf igurat io n Subt ab
4. Add any additional s e arch attribute s , in a comma-s e parate d lis t, in the Group
search fields fie ld.
5. Whe n the change s are comple te , click Save at the top of the Configuration page .
9.10 .3.2.3.2. Fro m t he Co mmand Line
To change the s e arch attribute s , us e the --groupsearch options to s e t the attribute s for
group s e arche s .

150

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

[bjensen@server ~]$ ipa config-mod --groupsearch={cn,description}

No te
Always give the comple te lis t of s e arch attribute s . Whate ve r value s are pas s e d with
the configuration argume nt ove rwrite the pre vious s e ttings .
This can be done by s pe cifying e ach attribute with a --groupsearch argume nt or by
lis ting all of the attribute s in a comma-s e parate d lis t ins ide curly brace s , s uch as
{attr1,attr2,attr3}. For long lis ts , it can be e as ie r to us e the curly brace s than
multiple options .

9.10 .3.2.4. Limit s o n At t ribut es Ret urned in Search Result s
Se arche s can be pe rforme d on attribute s that are not dis playe d in the UI. This me ans that
e ntrie s can be re turne d in a s e arch that do not appe ar to match the give n filte r. This is
e s pe cially common if the s e arch information is ve ry s hort, which incre as e s the like lihood
of a match.

9.10.3.3. Searching f or Groups Based on T ype
Group de finitions are s imple , but be caus e it is pos s ible to cre ate autome mbe r rule s which
automatically as s ign e ntrie s to groups , ne s te d groups which include me mbe rs implicitly,
and groups bas e d on me mbe r attribute s s uch as POSIX, the re ality of the group de finitions
can be ve ry comple x.
The re are nume rous diffe re nt options with the group-find command which allow groups
to be s e arche d bas e d on who the me mbe rs are and are not and othe r attribute s of the
group de finition.
For e xample , us e r private groups are ne ve r dis playe d in the IdM UI and are not re turne d
in a re gular s e arch. Us ing the --private option, howe ve r, limits the s e arch re s ults to only
private groups .
[root@server ~]# ipa group-find --private
--------------1 group matched
--------------Group name: jsmith
Description: User private group for jsmith
GID: 1084600001
---------------------------Number of entries returned 1
---------------------------Group s e arche s can als o be bas e d on who doe s or doe s not be long to a group. This can
me an s ingle us e rs , othe r groups , or e ve n othe r configuration e ntrie s like role s and hos tbas e d acce s s control de finitions . For e xample , the firs t s e arch s hows what groups the
us e r jsmith be longs to:
[root@server ~]# ipa group-find --user=jsmith
---------------

151

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1 group matched
--------------Group name: ipausers
Description: Default group for all users
Member users: jsmith
---------------------------Number of entries returned 1
---------------------------The othe r s e arch s hows all the groups that jsmith doe s not be long to:
[root@server ~]# ipa group-find --no-user=jsmith
---------------3 groups matched
---------------Group name: admins
Description: Account administrators group
GID: 1084600000
Member users: admin
Group name: editors
Description: Limited admins who can edit other users
GID: 1084600002
Group name: trust admins
Description: Trusts administrators group
Member users: admin
---------------------------Number of entries returned 3
---------------------------Some us e ful group s e arch options are lis te d in Table 9.6, “Common Group Se arch
Options ”.
T able 9.6. Co mmo n Gro up Search Opt io ns
Opt io n

Crit eria Descript io n

--private
--gid

Dis plays only private groups .
Dis plays only the group which matche s the
comple te , s pe cifie d GID.
Dis plays only groups with that name or part
of the ir name .
Dis plays only groups which have the give n
us e rs as me mbe rs (or which do not include
the give n us e r).
Dis plays only groups which be long to a
give n hos t-bas e d acce s s control rule (or
which do not be long to the rule , for the -not-in option). The re are s imilar options to
dis play (or not) groups which be long to a
s pe cifie d s udo rule and role .

--group-name
--us e rs , --no-us e rs

--in-hbacrule s , --not-inhbac-rule s

152

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Opt io n

Crit eria Descript io n

--in-groups , --not-in-groups

Dis plays only groups which be long to
anothe r, s pe cifie d group (or which do not
be long to the group, for the --not-in
option). The re are s imilar options to dis play
(or not) groups which be long to a s pe cifie d
ne tgroup.

9.11. Issuing User Cert ificat es wit h t he IdM CA
Ide ntity Manage me nt e nable s the adminis trator to is s ue ce rtificate s to individual us e rs . In
addition, us e rs can re que s t ce rtificate s for the ms e lve s whe n pe rmitte d by the Ce rtificate
Authority acce s s control lis ts (CA ACLs ).
The following proce dure s us e IdM's ce rtificate profile s and CA ACLs , which are de s cribe d
s e parate ly in Se ction 28.9, “Ce rtificate Profile s ” and Se ction 28.10, “Ce rtificate Authority
ACL Rule s ”. For more de tails about us ing ce rtificate profile s and CA ACLs , s e e the s e
s e ctions .

Issuing Cert if icat es t o Users f rom t he Command Line
1. Cre ate or import a ne w cus tom ce rtificate profile for handling re que s ts for us e r
ce rtificate s . For e xample :
$ ipa certprofile-import certificate_profile -file=certificate_profile.cfg --store=True
2. Add a ne w Ce rtificate Authority (CA) ACL that will be us e d to pe rmit re que s ting
ce rtificate s for us e r e ntrie s . For e xample :
$ ipa caacl-add users_certificate_profile --usercat=all
3. Add the cus tom ce rtificate profile to the CA ACL.
$ ipa caacl-add-profile users_certificate_profile -certprofiles=certificate_profile
4. Ge ne rate a ce rtificate re que s t for the us e r. For e xample , us ing Ope nSSL:
$ openssl req -new -newkey rsa:2048 -days 365 -nodes -keyout
private.key -out cert.csr -subj '/CN=user'
5. Run the ipa cert-request command to have the IdM CA is s ue a ne w ce rtificate for
the us e r.
$ ipa cert-request cert.csr --principal=user --profileid=certificate_profile
To make s ure the ne wly-is s ue d ce rtificate is as s igne d to the us e r, you can us e the ipa
user-show command:
$ ipa user-show user

153

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

User login: user
...
Certificate: MIICfzCCAWcCAQA...
...

Issuing Cert if icat es t o Users in t he Web UI
1. Cre ate or import a ne w cus tom ce rtificate profile for handling re que s ts for us e r
ce rtificate s . Importing profile s is only pos s ible from the command line , for e xample :
$ ipa certprofile-import certificate_profile -file=certificate_profile.txt --store=True
For information about ce rtificate profile s , s e e Se ction 28.9, “Ce rtificate Profile s ”.
2. In the we b UI, unde r the Authentication tab, ope n the CA ACLs s e ction.

Figure 9.42. CA ACL Rules Management in t he Web UI
Click Add at the top of the lis t of Ce rtificate Authority (CA) ACLs to add a ne w CA ACL
that pe rmits re que s ting ce rtificate s for us e r e ntrie s .
a. In the Add CA ACL window that ope ns , fill in the re quire d information about
the ne w CA ACL.

154

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.43. Adding a New CA ACL
The n, click Add and Edit to go dire ctly to the CA ACL configuration page .
b. In the CA ACL configuration page , s croll to the Profiles s e ction and click Add
at the top of the profile s lis t.

Figure 9.44. Adding a Cert if icat e Pro f ile t o t he CA ACL
c. Add the cus tom ce rtificate profile to the CA ACL by s e le cting the profile and
moving it to the Prospective column.

155

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 9.45. Select ing a Cert if icat e Pro f ile
The n, click Add.
d. Scroll to the Permitted to have certificates issued s e ction to
as s ociate the CA ACL with us e rs or us e r groups .
You can e ithe r add us e rs or groups us ing the Add buttons , or s e le ct the
Anyone option to as s ociate the CA ACL with all us e rs .

Figure 9.46. Adding Users t o t he CA ACL
e . At the top of the CA ACL configuration page , click Save to confirm the
change s to the CA ACL.
3. Re que s t a ne w ce rtificate for the us e r.
a. Unde r the Identity tab and the Users s ubtab, choos e the us e r for whom
the ce rtificate will be re que s te d. Click on the us e r's us e r name to ope n the
us e r e ntry configuration page .
b. Click Actions at the top of the us e r configuration page , and the n click New
Certificate.

156

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

Figure 9.47. Request ing a Cert if icat e f o r a User
c. Fill in the re quire d information.

Figure 9.48. Issuing a Cert if icat e f o r a User
The n, click Issue.

157

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Afte r this , the ne wly is s ue d ce rtificate is vis ible in the us e r configuration page .

9.12. Managing User Cert ificat es
In Ide ntity Manage me nt, the adminis trator can add ce rtificate s is s ue d by CAs othe r than
the IdM CA to a us e r e ntry, as we ll as re move ce rtificate s from us e r e ntrie s . This allows
the us e rs to authe nticate us ing s mart cards : ce rtificate s is s ue d by the s mart card ve ndor
can be adde d to IdM.
Note that us e rs in IdM can have multiple ce rtificate s as s igne d.

Managing User Cert if icat es f rom t he Command Line
To add or re move us e r ce rtificate s from the command line , us e the following two
commands :
ipa user-add-cert
Adds one or more ce rtificate s to a s pe cifie d us e r e ntry.
ipa user-remove-cert
Re move s one or more ce rtificate s from a s pe cifie d us e r e ntry.
The commands re quire you to s pe cify the following information:
the name of the us e r to which the ce rtificate is to be adde d or from which it is to be
re move d
the Bas e 64-e ncode d DER ce rtificate to be adde d or re move d
You can pas s the us e r e ntry and the ce rtificate dire ctly with the command, for e xample :
$ ipa user-add-cert user --certificate=MIQTPrajQAwg...
If you run the commands without s pe cifying the s e attribute s , IdM automatically prompts
you for the m.
To dis play the ce rtificate s as s igne d to a us e r e ntry, us e the ipa user-show command:
$ ipa user-show user
User login: user
...
Certificate: MIICfzCCAWcCAQA...
...
You can als o s ave us e r's ce rtificate or ce rtificate s to a file . To do this , s pe cify the file to
which to e xport the ce rtificate s by adding the --out option to ipa user-show. For
e xample :
$ ipa user-show user --out=file_name
If the us e r has more than one ce rtificate , the --out option e xports all of the m. The
ce rtificate or ce rtificate s are e xporte d as PEM obje cts .

User Cert if icat es in t he Web UI

158

⁠C hapt e r 9 . Managing Us e r s and Us e r Gr o ups

The IdM we b UI curre ntly doe s not s upport adding or re moving us e r ce rtificate s . Howe ve r,
it is pos s ible to dis play the ce rtificate s as s igne d to a us e r e ntry:
1. Unde r the Identity tab, ope n the Users s ubtab.
2. Click on the us e r name to ope n the us e r e ntry configuration page .

Figure 9.49. Opening t he User Ent ry Co nf igurat io n Page
3. Scroll to the Certificate s e ction to vie w the ce rtificate as s igne d to the us e r
e ntry. The we b UI dis plays the ce rtificate e ncode d us ing the Bas e 64 e ncoding.

Figure 9.50 . Displaying t he User Cert if icat e in t he Web UI
To add or re move us e r ce rtificate s , us e the ipa user-add-cert and ipa user-removecert commands , as de s cribe d in Se ction 9.12, “Managing Us e r Ce rtificate s from the
Command Line ”.

159

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide
[1] See Section 9.8, “Managing Unique UID and GID Num ber Assignm ents” for inform ation on
changing GID/UID assignm ent ranges.

160

⁠C hapt e r 10 . O ne -T ime Pas s wo r ds

Chapt er 10. One-Time Passwords
One -time pas s word (OTP) is a pas s word that is valid for only one authe ntication s e s s ion; it
be come s invalid afte r us e . Unlike traditional s tatic pas s words that s tay the s ame for a
longe r pe riod of time , OTPs ke e p changing. OTPs are us e d as part of two-factor
authe ntication: the firs t s te p re quire s the us e r to authe nticate with a traditional s tatic
pas s word, and the s e cond s te p prompts for an OTP is s ue d by a re cogniz e d authe ntication
toke n.
Authe ntication us ing an OTP combine d with a s tatic pas s word is cons ide re d s afe r than
authe ntication us ing a s tatic pas s word alone . Be caus e an OTP can only be us e d for
s ucce s s ful authe ntication once , e ve n if a pote ntial intrude r inte rce pts the OTP during login,
the inte rce pte d OTP will alre ady be invalid by that point.

Hardware and Sof t ware T okens
Both hardware and s oftware toke ns are us e d for is s uing OTPs . A hardware toke n is s tore d
on a de dicate d phys ical de vice . A s oftware toke n, on the othe r hand, is typically s tore d on
the us e r's mobile de vice , s uch as a s martphone or a table t.
Hardware toke ns are ofte n, but not always , manage d by the adminis trator. For e xample ,
s ome hardware toke ns , s uch as the Yubike y toke n, are typically us e r-manage d.
Adminis trators can purchas e hardware toke ns in bulk and the n dis tribute the m to the
us e rs .
Similarly, s oftware toke ns are ofte n, but not always , manage d by the us e r. For e xample ,
companie s that is s ue mobile de vice s to the ir e mploye e s can us e adminis trator-manage d
s oftware toke ns .

10.1. One-T ime Passwords in Ident it y Management
Impo rtant
The IdM s olution for OTP authe ntication is only s upporte d for clie nts running Re d Hat
Ente rpris e Linux 7.1 and late r.

Warning
The following s e curity and othe r limitations curre ntly re late to the IdM native OTP
s upport:
The mos t important s e curity limitation is the pote ntial vulne rability to re play
attacks acros s the s ys te m. Re plication is as ynchronous , and an OTP code can
the re fore be re us e d during the re plication pe riod. A us e r might be able to log on
to two s e rve rs at the s ame time . Howe ve r, this vulne rability is us ually difficult to
e xploit due to compre he ns ive e ncryption.
It is not pos s ible to obtain a ticke t-granting ticke t (TGT) via a clie nt that doe s not
s upport OTP authe ntication. This might affe ct ce rtain us e cas e s , s uch as
authe ntication us ing the mod_auth_kerb module or the Ge ne ric Se curity Se rvice s
API (GSSAPI).

161

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Ide ntity Manage me nt allows both user-managed and administrator-managed OTP toke ns :
User-managed t o kens
Us e rs have full control ove r us e r-manage d toke ns in Ide ntity Manage me nt; the y
are allowe d to cre ate , e dit, or de le te the ir toke ns . To allow a us e r to manage the
toke n, make s ure toke n s upport is e nable d for the us e r or globally for all us e rs .
Administ rat o r-managed t o kens
Us e rs have re ad-only acce s s for adminis trator-manage d toke ns ; the y do not have
the pe rmis s ion to manage or modify the toke ns and the y are not re quire d to
configure the m in any way. To as s ign a toke n to a us e r as an adminis trator, make
s ure that toke n s upport is e nable d for the us e r or globally for all us e rs , and the n
add the toke n to the us e r's account.
Note that us e rs are always re quire d to have at le as t one active toke n; the y are not
allowe d to de le te or de activate a toke n if it is the ir only active toke n at the mome nt.
Similarly, the adminis trator is not allowe d to de le te or de active the las t re maining active
toke n as s igne d to a us e r.

Support ed OT P Algorit hms
Ide ntity Manage me nt s upports two s tandard OTP me chanis ms . All toke ns us e d within IdM
native OTP s upport are re quire d to imple me nt one of the m:
The HMAC-Bas e d One -Time Pas s word (HOTP) algorithm is bas e d on a counte r. HMAC
s tands for Has he d Me s s age Authe ntication Code .
The Time -Bas e d One -Time Pas s word (TOTP) algorithm is an e xte ns ion of HOTP to
s upport time -bas e d moving factor.

Of f line Aut hent icat ion and GNOME Keyring Service
IdM s upports offline OTP authe ntication and als o inte grate s OTP authe ntication with the
GNOME Ke yring s e rvice . Note that both offline authe ntication and GNOME Ke yring
inte gration re quire the us e r to e nte r the firs t and s e cond factors s e parate ly:
First factor: static_password
Second factor: one-time_password
For more information about offline OTP authe ntication in IdM, s e e Se ction 10.1.5, “Offline
Authe ntication with OTP”.

10.1.1. Enabling OT P Aut hent icat ion in IdM
Only the adminis trator can e nable or dis able OTP s upport; us e rs are not allowe d to do this .
The adminis trator can e nable OTP s upport only for s pe cifie d us e rs or globally for all us e rs .
As an adminis trator, you can control which authe ntication me thods are available to which
us e rs . You can s e t the allowe d authe ntication me thods globally for all us e rs or individually
on a pe r-us e r bas is . Ide ntity Manage me nt provide s you with the following authe ntication
me thods :
pas s word authe ntication
RADIUS proxy s e rve r authe ntication

162

⁠C hapt e r 10 . O ne -T ime Pas s wo r ds

two-factor authe ntication (pas s word + OTP)
You can s e t multiple options at once . If you do, e ithe r one of the m will be s ufficie nt for
s ucce s s ful authe ntication.
Us e rs can be authe nticate d agains t IdM ove r two protocols : Ke rbe ros and LDAP. With
pas s word-bas e d s ingle -factor authe ntication, us e rs authe nticate with the s ame pas s word
ove r e ithe r of the two protocols . With the OTP-bas e d two-factor authe ntication, minor
diffe re nce s e xis t de pe nding on which of the two protocols is us e d.
If you choos e the pas s word and two-factor authe ntication type s at once , Ke rbe ros s till
e nforce s authe ntication with both pas s word and OTP. LDAP allows authe ntication with
e ithe r one of the authe ntication type s in this s ituation.

No te
If you want to e nforce two-factor authe ntication for a us e r, us e Ke rbe ros from the
application that inte grate s with IdM. Othe rwis e , us e LDAP that allows the us e r to
authe nticate with a pas s word only.
If you choos e the RADIUS authe ntication type toge the r with anothe r authe ntication type ,
Ke rbe ros always us e s RADIUS, but LDAP ne ve r doe s . LDAP only re cogniz e s the pas s word
and two-factor authe ntication options .

No te
If you us e an e xte rnal two-factor authe ntication provide r, us e Ke rbe ros from your
applications . If you want to le t us e rs authe nticate with a pas s word only, us e LDAP. It
is re comme nde d that the applications le ve rage Apache module s and SSSD, which
allows to configure e ithe r Ke rbe ros or LDAP.

Def ining Aut hent icat ion Met hods
To s e t the global authe ntication me thods from the IdM we b UI, us e the Default user
authentication types options acce s s ible through the Configuration s ubtab unde r the
IdM server main tab.
To s e t the pe r-us e r authe ntication me thods from the IdM we b UI, us e the User
authentication types options on the de tails page of the corre s ponding us e r, which is
acce s s ible through the Users s ubtab unde r the Identity main tab.
To s e t the global authe ntication me thods from the command line , run the ipa config-mod
command and de fine the authe ntication me thod by s upplying the --user-auth-type
option with the command. The argume nts re cogniz e d by this option are password, radius,
and otp. For e xample , to s e t the authe ntication me thod to two-factor authe ntication:
[root@server ~]# ipa config-mod --user-auth-type=otp
To s e t the pe r-us e r authe ntication me thods from the command line , run the ipa user-mod
command and de fine the authe ntication me thod by s upplying the --user-auth-type
option. For e xample , to de fine that the employee us e r will be re quire d to authe nticate by
providing the ir pas s word:

163

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@server ~]# ipa user-mod employee --user-auth-type=password
To s e t multiple authe ntication me thods , pas s multiple --user-auth-type options with ipa
config-mod or ipa user-mod.

No te
Only adminis trators are allowe d to change the us e r authe ntication me thods .

10.1.2. Adding a User-Managed Sof t ware T oken
To add a us e r-manage d s oftware toke n, log in as the us e r with your s tandard pas s word,
and the n follow the s e s te ps :
1. Make s ure you have the FreeOTP Authenticator application for Android ins talle d
on your mobile de vice . To download FreeOTP Authenticator, s e e the Fre e OTP
s ource page .
2. Cre ate the s oftware toke n in the IdM we b UI or from the command line :
To cre ate the toke n from the we b UI, click the OTP Tokens tab, and the click Add
above the lis t of OTP toke ns . If you are logge d-in as the adminis trator, the OTP
Tokens tab is acce s s ible through the Authentication main tab.

Figure 10 .1. Adding an OT P T o ken f o r a User
Fill the form that s hows up, and the n click Add unde r the form.
To cre ate the toke n from the command line , run ipa otptoken-add.
3. A QR code s hows up in the we b UI or on the command line . Scan the QR code with
FreeOTP Authenticator. This provis ions the toke n to your s martphone or table t.

164

⁠C hapt e r 10 . O ne -T ime Pas s wo r ds

Figure 10 .2. QR Co de in t he Web UI

10.1.3. Adding a User-Managed YubiKey Hardware T oken
Due to brows e r limitations , a programmable hardware toke n, s uch as a YubiKe y, can only
be adde d on the command line . To add a YubiKe y hardware toke n as the us e r owning the
toke n, log in as the us e r with your s tandard pas s word, and the n follow the s e s te ps :
1. Ins e rt your YubiKe y toke n.

165

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

2. Run the ipa otptoken-add-yubikey command. If the YubiKe y has an e mpty s lot,
the command will pick it automatically. If no e mpty s lot is available , you will be
re quire d to choos e a s lot to ove rwrite by s upplying the --slot option with the
command. For e xample :
[user@server ~]$ ipa otptoken-add-yubikey --slot=2

10.1.4. Adding a T oken f or a User as an Administ rat or
The adminis trator can cre ate toke ns on be half of any us e r. To add a s oftware toke n as an
adminis trator:
1. Make s ure that you are logge d-in as the adminis trator.
2. Follow the s te ps outline d in Se ction 10.1.2, “Adding a Us e r-Manage d Software
Toke n” and s pe cify the us e r owning the toke n:
To s pe cify the owne r while adding the toke n from the we b UI, choos e the us e r
dire ctly in the form for adding a toke n us ing the Owner fie ld.
To s pe cify the owne r while adding the toke n from the command line , s upply the
--owner option with the ipa otptoken-add command. For e xample :
[root@server ~]# ipa otptoken-add --owner=employee
To add a programmable hardware toke n, s uch as a Yubike y, as an adminis trator:
1. Make s ure that you are logge d-in as the adminis trator.
2. Follow the s te ps outline d in Se ction 10.1.3, “Adding a Us e r-Manage d YubiKe y
Hardware Toke n” and s pe cify the us e r owning the toke n by adding the --owner
option to the ipa otptoken-add-yubikey command. For e xample :
[root@server ~]# ipa otptoken-add-yubikey --owner=employee

10.1.5. Of f line Aut hent icat ion wit h OT P
IdM s upports offline OTP authe ntication. Howe ve r, to be able to log in offline , the us e r mus t
firs t authe nticate whe n the s ys te m is online by e nte ring the s tatic pas s word and OTP
s e parate ly:
First factor: static_password
Second factor: one-time_password
If both pas s words are e nte re d s e parate ly like this whe n logging in online , the us e r will
s ubs e que ntly be able to authe nticate e ve n if the ce ntral authe ntication s e rve r is
unavailable . Note that IdM only prompts for the firs t-factor traditional s tatic pas s word whe n
the us e r authe nticate s offline .
IdM als o s upports e nte ring both the s tatic pas s word and OTP toge the r in one s tring in the
First factor prompt. Howe ve r, note that this is not compatible with offline OTP
authe ntication. If the us e r e nte rs both factors in a s ingle prompt, IdM will always have to
contact the ce ntral authe ntication s e rve r whe n authe nticating, which re quire s the s ys te m
to be online .

166

⁠C hapt e r 10 . O ne -T ime Pas s wo r ds

Impo rtant
If you us e OTP authe ntication on de vice s that als o ope rate offline , s uch as laptops ,
Re d Hat re comme nds to e nte r the s tatic pas s word and OTP s e parate ly to make s ure
offline authe ntication will be available . Othe rwis e , IdM will not allow you to log in afte r
the s ys te m goe s offline .
If you want to be ne fit from OTP offline authe ntication, apart from e nte ring the s tatic and
OTP pas s words s e parate ly, als o make s ure to me e t the following conditions :
The cache_credentials option in the /etc/sssd/sssd.conf file is s e t to True, which
e nable s caching the firs t factor pas s word.
The firs t-factor s tatic pas s word me e ts the pas s word le ngth re quire me nt de fine d in the
cache_credentials_minimal_first_factor_length option s e t in
/etc/sssd/sssd.conf. The de fault minimal le ngth is 8 characte rs . For more
information about the option, s e e the s s s d.conf(5) man page .
Note that e ve n if the krb5_store_password_if_offline option is s e t to true in
/etc/sssd/sssd.conf, SSSD doe s not atte mpt to re fre s h the Ke rbe ros ticke t-granting
ticke t (TGT) whe n the s ys te m goe s online again be caus e the OTP might alre ady be invalid
at that point. To obtain a TGT in this s ituation, the us e r mus t authe nticate again us ing both
factors .

10.1.6. Migrat ing f rom a Propriet ary OT P Solut ion
In orde r to migrate a large de ployme nt from a proprie tary OTP s olution to Ide ntity
Manage me nt with inte grate d OTP s upport, IdM offe rs a way to offload OTP validation to a
third-party RADIUS s e rve r for a s ubs e t of us e rs . The adminis trator cre ate s a s e t of
RADIUS proxie s ; e ach proxy can contain multiple individual RADIUS s e rve rs . The
adminis trator as s igns one of the s e proxy s e ts to a us e r. As long as the us e r has a
RADIUS proxy s e t as s igne d, IdM bypas s e s all othe r authe ntication me chanis ms .

No te
Ide ntity Manage me nt doe s not provide any toke n manage me nt or s ynchroniz ation
s upport for toke ns in the third-party s ys te m.
To configure a RADIUS s e rve r for OTP validation and to add a us e r to the proxy s e rve r:
1. Make s ure that the radius us e r authe ntication me thod is e nable d. Se e
Se ction 10.1.1, “De fining Authe ntication Me thods ”.
2. Run ipa radiusproxy-add testproxy and follow s ubs e que nt ins tructions to add a
RADIUS proxy.
3. Run ipa user-mod radiususer --radius=testproxy to as s ign a us e r to this
proxy.
4. If it is re quire d, configure the us e r name to be s e nt to RADIUS by running ipa
user-mod radiususer --radius-username=myradiususer.
5. The us e r OTP authe ntication will now be proce s s e d through the RADIUS proxy
s e rve r.

167

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Whe n the us e r is re ady to be migrate d to the IdM native OTP s ys te m, you can s imply
re move the RADIUS proxy as s ignme nt for the us e r.

10.1.7. T oken Synchronizat ion
If a toke n falls out of s ynchroniz ation, it cannot be us e d for a s ucce s s ful authe ntication
anymore . To s ynchroniz e a toke n again, click on the Sync OTP Token button on the IdM
we b UI login page or run ipa otptoken-sync from the command line . You will be as ke d to
e nte r your pas s word and two toke n code s in a row.

No te
A us e r can re -s ynchoniz e a toke n re gardle s s of what toke n type it is and whe the r or
not the us e r has pe rmis s ion to modify the toke n s e ttings .

168

⁠C hapt e r 11. Smar t Car ds

Chapt er 11. Smart Cards
Authe ntication bas e d on s mart cards is an alte rnative to pas s word-bas e d authe ntication.
Us e r cre de ntials are s tore d on the s mart card, and s pe cial s oftware and hardware is the n
us e d to acce s s the m. In orde r to authe nticate us ing a s mart card, the us e r mus t place the
s mart card into a s mart card re ade r and the n s upply the PIN code for the s mart card.

11.1. Smart Card Aut hent icat ion in Ident it y Management
Re d Hat Ide ntity Manage me nt (IdM) s upports two s mart card-bas e d authe ntication options :
local authe ntication and re mote ssh authe ntication. Both re quire the Sys te m Se curity
Se rvice s Dae mon (SSSD) to be running on the IdM clie nt.
With SSSD-bas e d s mart card authe ntication configure d, the s ys te m prompts for the s mart
card PIN code afte r the us e r atte mpts to log in. The us e r is s ucce s s fully authe nticate d if
the s upplie d PIN is corre ct, the ce rtificate on the s mart card is valid and be longs to the
us e r atte mpting to log in, and othe r configurable crite ria are me t.
Lo cal aut hent icat io n
IdM s upports s mart card authe ntication at a te xt or graphical cons ole , s uch as the
Gnome Dis play Manage r (GDM), as we ll as authe ntication us ing local
authe ntication s e rvice s like su or sudo.
Remo t e aut hent icat io n wit h ssh
Ce rtificate s on a s mart card are s tore d toge the r with the PIN-prote cte d private
ke y; this ke y is us e d for the ssh authe ntication. On the clie nt s ide , the ssh clie nt
program in Re d Hat Ente rpris e Linux acce s s e s the s mart card; on the s e rve r s ide ,
only the public ke y from the ce rtificate is the n us e d for ssh acce s s .
IdM only s upports the above -me ntione d local authe ntication s e rvice s and ssh for s mart
card authe ntication. Othe r s e rvice s , s uch as FTP, are not s upporte d.
Note that to be able to authe nticate us ing s mart cards , the pam_cert_auth option mus t be
s e t to True in the [pam] s e ction of the /etc/sssd/sssd.conf file .

Smart Card and Smart Card Reader Support in Ident it y Management
If your s mart card is s upporte d by the coolkey package , the PKCS #11 module re quire d by
the s mart card re ade r is alre ady pre s e nt in the ce ntral /etc/pki/nssdb/ NSS databas e .
If your s mart card re ade r is not s upporte d, you mus t add the re quire d PKCS #11 module
manually us ing the modutil utility. For e xample :
modutil -dbdir /etc/pki/nssdb -add "My PKCS#11 module" -libfile
libmypkcs11.so
...
Module "My PKCS#11 Module" added to database.
For de taile d information on us ing modutil, s e e the modutil(1) man page .

11.1.1. Conf iguring Smart Card Aut hent icat ion on an IdM Client

169

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1. Place the s mart card into the re ade r.
2. If you have the s mart card ce rtificate s ave d in a file , you can us e the bas e 64e ncode d ce rtificate s tring from the file for the ne xt s te p.
Alte rnative ly, e xtract the ce rtificate from the s mart card us ing the following
command:
# /usr/libexec/sssd/p11_child --pre --nssdb /etc/pki/nssdb/
Enter Password for Pin for "Smart Card":
MIIEkjC ...
3. As s ign the ce rtificate to an IdM us e r us ing the ipa user-mod or ipa user-addcert commands . Pas s the whole ce rtificate to the command us ing the -certificate option. For e xample , us ing ipa user-mod:
$ ipa user-mod user --certificate=MIIEkjC ...
-------------------User "user" modified
-------------------User login: user
...
Certificate: MIIEkjC ...
For information on us ing ipa user-add-cert, s e e Se ction 9.12, “Managing Us e r
Ce rtificate s ”.
Afte r this , the s mart card ce rtificate is mappe d to the us e r e ntry, which e nable s the us e r
to us e the s mart card for local authe ntication on an IdM clie nt or for logging in us ing ssh.
Note that whe n logging in with ssh, the us e r mus t s pe cify the following information:
the path to the s mart card re ade r module you want to us e
the us e r that you want to log in as
the name of the IdM clie nt to which you want to log in
For e xample :
$ ssh -I /usr/lib/libmypkcs11.so -l user@example.com host.example.com
Enter PIN for 'Smart Card':

170

⁠C hapt e r 12. ID Vie ws

Chapt er 12. ID Views
The ID Views fe ature e nable s you to s pe cify POSIX attribute s for us e rs or groups . Eve ry
ID vie w is a colle ction of user overrides and group overrides that apply to s pe cifie d hos ts .
An ove rride provide s a ne w us e r or group attribute that ove rride s the pre vious one . This
e nable s you to, for e xample , re place a pre vious ly ge ne rate d attribute with a ne w one .
An e xample us e cas e for ID vie ws is s e tting diffe re nt us e r SSH public ke ys for diffe re nt
production e nvironme nts , s uch as de ve lopme nt, te s ting, or production.

No te
ID vie ws als o have s e ve ral us e cas e s in e nvironme nts involving Active Dire ctory,
as de s cribe d in the Windows Inte gration Guide .
ID vie ws can be adde d, modifie d, or de le te d. Apart from s pe cifying which ID attribute s an
ID vie w s hould ove rride , you can als o de fine which clie nt hos ts it s hould apply to.

12.1. User Overrides and Group Overrides
Eve ry ove rride is re late d to a us e r or us e r group. The following us e r attribute s can be
ove rridde n in an ID vie w:
uid: us e r login name
uidNumber: us e r UID numbe r
gidNumber: us e r GID numbe r
loginShell: us e r login s he ll
gecos: us e r GECOS e ntry
homeDirectory: us e r home dire ctory
ipaSshPubkey: us e r SSH public ke y or ke ys
The following group attribute s can be ove rridde n in an ID vie w:
cn: group name
gidNumber: group GID numbe r

12.2. ID Views and SSSD
If the adminis trator applie s anothe r ID vie w on a clie nt, the clie nt and all the othe r clie nts
applying this ID vie w mus t re s tart the SSSD s e rvice . More ove r, if the ne w ID vie w
change s a UID or GID, the clie nt and all the othe r clie nts applying the ID vie w mus t cle ar
the SSSD cache .
Note that applying an ID vie w can have a ne gative impact on SSSD pe rformance be caus e
ce rtain optimiz ations and ID vie ws cannot run at the s ame time . For e xample , ID vie ws
pre ve nt SSSD from optimiz ing the proce s s of looking up groups on the s e rve r. With ID
vie ws , SSSD mus t che ck e ve ry me mbe r on the re turne d lis t of group me mbe r name s if

171

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

the group name is ove rridde n. Without ID vie ws , SSSD can only colle ct the us e r name s
from the me mbe r attribute of the group obje ct. This ne gative e ffe ct will mos t like ly
be come appare nt whe n the SSSD cache is e mpty or afte r cle aring the cache which make s
all e ntrie s invalid.

12.3. Managing ID Views from t he Web UI
To manage ID vie ws from the IdM We b UI, ope n the IPA Server main tab and the n s e le ct
the ID Views s ubtab.
To add a ne w ID vie w:
1. Click Add above the lis t of all ID vie ws .

Figure 12.1. Adding a New ID View
2. Fill out the information about the ne w ID vie w in the form that s hows up.

Figure 12.2. Fo rm f o r Adding a New ID View

172

⁠C hapt e r 12. ID Vie ws

3. Click the Add button unde r the form.
To de fine the prope rtie s of an ID vie w:
1. Click on the name of the ID vie w in the lis t of ID vie ws , and the n choos e the
appropriate tab.

Figure 12.3. ID View T abs
2. Users s hows the lis t of us e rs whos e us e r attribute s the ID vie w ove rride s .

Figure 12.4. Adding a User Override
Click Add to cre ate a ne w us e r ove rride ; you will be as ke d to fill out the ne w value s
for the us e r attribute s .

173

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 12.5. Adding a User Override
Click Delete to re move s e le cte d us e r ove rride s .
3. User Groups s hows the lis t of us e r groups whos e group attribute s the ID vie w
ove rride s .

174

⁠C hapt e r 12. ID Vie ws

Figure 12.6. User Gro ups T ab
Click Add to cre ate a ne w us e r group ove rride ; you will be as ke d to fill out the ne w
value s for the group attribute s .

Figure 12.7. Adding a Gro up Override
Click Delete to re move s e le cte d us e r group ove rride s .
4. Hosts s hows the lis t of hos ts or hos t groups to which the ID vie w applie s .

175

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 12.8. Ho st s T ab
Click Apply to hosts or Apply to host groups to add a ne w hos t or to add hos ts
be longing to a hos t group. In the form that s hows up, move the re quire d hos ts or
hos ts group from the Available to Prospective column and click Apply.

Figure 12.9. Applying an ID View t o a Ho st
Un-apply re move s the ID vie w from s pe cifie d hos ts . Un-apply from host groups
e nable s you to re move the ID vie w from s pe cifie d hos t groups .
5. Settings e nable s you to modify the ID vie w de s cription.

176

⁠C hapt e r 12. ID Vie ws

Figure 12.10 . Set t ings T ab

12.4. Managing ID Views from t he command line
To manage ID vie ws on the command line , us e the following commands :
ipa idview-add adds a ne w ID vie w
ipa idview-apply applie s an ID vie w to s pe cifie d hos ts or hos t groups ; any pre vious ly
applie d ID vie w is ove rridde n
ipa idview-del de le te s an ID vie w
ipa idview-find s e arche s for a s pe cifie d ID vie w
ipa idview-mod modifie s an ID vie w
ipa idview-show dis plays information about an ID vie w
ipa idview-unapply re move s an ID vie w from s pe cifie d hos ts or hos t groups
To manage group and us e r ID ove rride s , us e the following commands :
ipa idoverridegroup-add adds a ne w group ID ove rride
ipa idoverrideuser-add adds a ne w us e r ID ove rride
ipa idoverridegroup-del de le te s a group ID ove rride
ipa idoverrideuser-del de le te s a us e r ID ove rride
ipa idoverridegroup-find s e arche s for a s pe cifie d group ID ove rride
ipa idoverrideuser-find s e arche s for a s pe cifie d us e r ID ove rride
ipa idoverridegroup-mod modifie s a group ID ove rride
ipa idoverrideuser-mod modifie s a us e r ID ove rride
ipa idoverridegroup-show dis plays information about a group ID ove rride
ipa idoverrideuser-show dis plays information about a us e r ID ove rride
For de taile d information on what options can be pas s e d to the s e commands , s e e the
corre s ponding man page s or run one of the m with the --help option adde d.

177

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
The --hostgroups option applie s the ID vie w to hos ts be longing in a s pe cifie d hos t
group and can be us e d in the s ame way as the --hosts option. The --hostgroups
option doe s not as s ociate the ID vie w with the hos t group its e lf; it e xpands the
me mbe rs of the s pe cifie d hos t group and applie s --hosts individually to e ve ry one
of the m.

178

⁠P ar t III. Managing Sys t e m Ide nt it ie s in a Linux Do main

⁠P art III. Managing Syst em Ident it ies in a Linux Domain

179

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 13. Managing Host s
Both DNS and Ke rbe ros are configure d as part of the initial clie nt configuration. This is
re quire d be caus e the s e are the two s e rvice s that bring the machine within the IdM
domain and allow it to ide ntify the IdM s e rve r it will conne ct with. Afte r the initial
configuration, IdM has tools to manage both of the s e s e rvice s in re s pons e to change s in
the domain s e rvice s , change s to the IT e nvironme nt, or change s on the machine s
the ms e lve s which affe ct Ke rbe ros , ce rtificate , and DNS s e rvice s , like changing the clie nt
hos tname .
This chapte r de s cribe s how to manage ide ntity s e rvice s that re late dire ctly to the clie nt
machine :
DNS e ntrie s and s e ttings
Machine authe ntication
Hos tname change s (which affe ct domain s e rvice s )

13.1. About Host s, Services, and Machine Ident it y and
Aut hent icat ion
The bas ic function of an e nrollme nt proce s s is to cre ate a host e ntry for the clie nt
machine in the IdM dire ctory. This hos t e ntry is us e d to e s tablis h re lations hips be twe e n
othe r hos ts and e ve n s e rvice s within the domain. The s e re lations hips are part of
delegating authoriz ation and control to hos ts within the domain.
A hos t e ntry contains all of the information about the clie nt within IdM:
Se rvice e ntrie s as s ociate d with the hos t
The hos t and s e rvice principal
Acce s s control rule s
Machine information, s uch as its phys ical location and ope rating s ys te m
Some s e rvice s that run on a hos t can als o be long to the IdM domain. Any s e rvice that can
s tore a Ke rbe ros principal or an SSL ce rtificate (or both) can be configure d as an IdM
s e rvice . Adding a s e rvice to the IdM domain allows the s e rvice to re que s t an SSL
ce rtificate or ke ytab from the domain. (Only the public ke y for the ce rtificate is s tore d in
the s e rvice re cord. The private ke y is local to the s e rvice .)
An IdM domain e s tablis he s a commonality be twe e n machine s , with common ide ntity
information, common policie s , and s hare d s e rvice s . Any machine which be longs to a
domain functions as a clie nt of the domain, which me ans it us e s the s e rvice s that the
domain provide s . An IdM domain (as de s cribe d in Se ction 1.2, “Bringing Linux Se rvice s
Toge the r”) provide s thre e main s e rvice s s pe cifically for machine s :
DNS
Ke rbe ros
Ce rtificate manage me nt
Machine s are tre ate d as anothe r ide ntity that is manage d by IdM. Clie nts us e DNS to
ide ntify IdM s e rve rs , s e rvice s , and domain me mbe rs — which, like us e r ide ntitie s are

180

⁠C hapt e r 13. Managing Ho s t s

s tore d in the 389 Dire ctory Se rve r ins tance for the IdM s e rve r. Like us e rs , machine s can
be authe nticate d to the domain us ing Ke rbe ros or ce rtificate s to ve rify the machine 's
ide ntity.
From the machine pe rs pe ctive , the re are s e ve ral tas ks that can be pe rforme d that
acce s s the s e domain s e rvice s :
Joining the DNS domain (machine enrollment)
Managing DNS e ntrie s and z one s
Managing machine authe ntication
Authe ntication in IdM include s machine s as we ll as us e rs . Machine authe ntication is
re quire d for the IdM s e rve r to trus t the machine and to acce pt IdM conne ctions from the
clie nt s oftware ins talle d on that machine . Afte r authe nticating the clie nt, the IdM s e rve r
can re s pond to its re que s ts . IdM s upports thre e diffe re nt approache s to machine
authe ntication:
SSH ke ys . The SSH public ke y for the hos t is cre ate d and uploade d to the hos t e ntry.
From the re , the Sys te m Se curity Se rvice s Dae mon (SSSD) us e s IdM as an ide ntity
provide r and can work in conjunction with Ope nSSH and othe r s e rvice s to re fe re nce the
public ke ys locate d ce ntrally in Ide ntity Manage me nt. This is de s cribe d in Se ction 13.5,
“Managing Public SSH Ke ys for Hos ts ”.
Ke y table s (or keytabs, a s ymme tric ke y re s e mbling to s ome e xte nt a us e r pas s word)
and machine ce rtificate s . Ke rbe ros ticke ts are ge ne rate d as part of the Ke rbe ros
s e rvice s and policie s de fine d by the s e rve r. Initially granting a Ke rbe ros ticke t,
re ne wing the Ke rbe ros cre de ntials , and e ve n de s troying the Ke rbe ros s e s s ion are all
handle d by the IdM s e rvice s . Managing Ke rbe ros is cove re d in Chapte r 20, Managing
the Kerberos Domain.
Machine ce rtificate s . In this cas e , the machine us e s an SSL ce rtificate that is is s ue d by
the IdM s e rve r's ce rtificate authority and the n s tore d in IdM's Dire ctory Se rve r. The
ce rtificate is the n s e nt to the machine to pre s e nt whe n it authe nticate s to the s e rve r.
On the clie nt, ce rtificate s are manage d by a s e rvice calle d certmonger.

13.2. About Host Ent ry Configurat ion Propert ies
A hos t e ntry can contain information about the hos t that is outs ide its s ys te m
configuration, s uch as its phys ical location, its MAC addre s s , and ke ys and ce rtificate s .
This information can be s e t whe n the hos t e ntry is cre ate d if it is cre ate d manually;
othe rwis e , mos t of that information ne e ds to be adde d to the hos t e ntry afte r the hos t is
e nrolle d in the domain.
T able 13.1. Ho st Co nf igurat io n Pro pert ies
UI Field

Co mmand-Line Opt io n

Descript io n

De s cription
Locality

--de s c=description
--locality=locality

Location

--location=location

A de s cription of the hos t.
The ge ographic location of
the hos t.
The phys ical location of the
hos t, s uch as its data ce nte r
rack.

181

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

UI Field

Co mmand-Line Opt io n

Descript io n

Platform

--platform=string

Ope rating s ys te m

--os =string

MAC addre s s

--macaddre s s =address

SSH public ke ys

--s s hpubke y=string

Principal name (not
e ditable )

--principalname =principal

Se t One -Time Pas s word

--pas s word=string

-

--random

-

--ce rtificate =string

-

--update dns

The hos t hardware or
archite cture .
The ope rating s ys te m and
ve rs ion for the hos t.
The MAC addre s s for the
hos t. This is a multi-value d
attribute . The MAC addre s s
is us e d by the NIS plug-in to
cre ate a NIS e the rs map for
the hos t.
The full SSH public ke y for
the hos t. This is a multivalue d attribute , s o multiple
ke ys can be s e t.
The Ke rbe ros principal
name for the hos t. This
de faults to the hos tname
during the clie nt ins tallation,
unle s s a diffe re nt principal
is e xplicitly s e t in the -p.
This can be change d us ing
the command-line tools , but
cannot be change d in the UI.
Se ts a pas s word for the
hos t which can be us e d in
bulk e nrollme nt.
Ge ne rate s a random
pas s word to be us e d in bulk
e nrollme nt.
A ce rtificate blob for the
hos t.
This s e ts whe the r the hos t
can dynamically update its
DNS e ntrie s if its IP addre s s
change s .

13.3. Disabling and Re-enabling Host Ent ries
Active hos ts can be acce s s e d by othe r s e rvice s , hos ts , and us e rs within the domain.
The re can be s ituations whe n it is ne ce s s ary to re move a hos t from activity. Howe ve r,
de le ting a hos t re move s the e ntry and all the as s ociate d configuration, and it re move s it
pe rmane ntly.

13.3.1. Disabling Host Ent ries
Dis abling a hos t pre ve nts domain us e rs from acce s s it without pe rmane ntly re moving it
from the domain. This can be done by us ing the host-disable command.
For e xample :
[jsmith@ipaserver ~]$ kinit admin
[jsmith@ipaserver ~]$ ipa host-disable server.example.com

182

⁠C hapt e r 13. Managing Ho s t s

Impo rtant
Dis abling a hos t e ntry not only dis able s that hos t. It dis able s e ve ry configure d
s e rvice on that hos t as we ll.

13.3.2. Re-enabling Host s
Dis abling a hos t e s s e ntially kills its curre nt, active ke ytabs . Re moving the ke ytabs
e ffe ctive ly re move s the hos t from the IdM domain without othe rwis e touching its
configuration e ntry.
To re -e nable a hos t, s imply us e the ipa-getkeytab command. The -s option s e ts which
IdM s e rve r to re que s t the ke ytab, -p give s the principal name , and -k give s the file to
which to s ave the ke ytab.
For e xample , re que s ting a ne w hos t ke ytab:
[jsmith@ipaserver ~]$ ipa-getkeytab -s ipaserver.example.com -p
host/server.example.com -k /etc/krb5.keytab -D
fqdn=server.example.com,cn=computers,cn=accounts,dc=example,dc=com -w
password
If the ipa-getkeytab command is run on an active IdM clie nt or s e rve r, the n it can be run
without any LDAP cre de ntials (-D and -w). The IdM us e r us e s Ke rbe ros cre de ntials to
authe nticate to the domain. To run the command dire ctly on the dis able d hos t, the n s upply
LDAP cre de ntials to authe nticate to the IdM s e rve r. The cre de ntials s hould corre s pond to
the hos t or s e rvice which is be ing re -e nable d.

13.4. Creat ing Cert ificat es for Host s
By de fault, the IdM s e rve r has an inte grate d ce rtificate authority. This CA can be us e d to
cre ate , re voke , and is s ue ce rtificate s for hos ts in the IdM domain.

13.4.1. Showing Cert if icat es
13.4.1.1. In t he Web UI
Hos t ce rtificate can be dis playe d on the hos t e ntry configuration page :
1. Ope n the Identity tab, and s e le ct the Hosts s ubtab.
2. Click on the hos t name to ope n the hos t configuration page .

183

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 13.1. List o f Ho st s
3. Click Show in the Host Certificate s e ction of the hos t configuration page .
Alte rnative ly, the ce rtificate can be dis playe d on the ce rtificate information page :
1. Ope n the Authentication tab, and s e le ct the Certificates s ubtab.
2. In the Certificates s e ction, a lis t of all ce rtificate s is dis playe d. Click on the s e rial
numbe r of the ce rtificate you want dis playe d to ope n the ce rtificate information
page .

Figure 13.2. List o f Cert if icat es
3. The ce rtificate is dis playe d in the Certificate fie ld on the ce rtificate information
page .

13.4.1.2. In t he Command Line
All of the ce rtificate s which have be e n is s ue d by the IdM CA are lis te d with the ipa certfind command.
[root@server ~]# kinit admin
[root@server ~]# ipa cert-find
----------------------10 certificates matched
----------------------Serial number (hex): 0x1
Serial number: 1

184

⁠C hapt e r 13. Managing Ho s t s

Status: VALID
Subject: CN=Certificate Authority,O=EXAMPLE.COM
...
----------------------------Number of entries returned 10
----------------------------With a large numbe r of ce rtificate s , it can be e as ie r to s e arch for a s pe cific ce rtificate by
s e rial numbe r or by an is s ue date . To s e arch by a s e rial numbe r, s imply include it with the
cert-show command.
[root@server ~]# ipa cert-show 132
Serial number: 132
Certificate:
MIIDtzCCAp+gAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMR8wHQYDVQQKExZMQUIu
...
LxIQjrEFtJmoBGb/TWRlwGEWy1ayr4iTEf1ayZ+RGNylLalEAtk9RLjEjg==
Subject: CN=Certificate Authority,O=EXAMPLE.COM
Issuer: CN=Certificate Authority,O=EXAMPLE.COM
Not Before: Sun Jun 08 05:51:11 2014 UTC
Not After: Thu Jun 08 05:51:11 2034 UTC
Fingerprint (MD5): 46:53:2b:e9:88:c8:6b:ca:ec:5b:81:80:af:17:ea:85
Fingerprint (SHA1):
19:bc:93:e9:af:8c:ee:61:a3:10:07:6a:27:8b:5f:0a:25:d2:b0:72
Serial number (hex): 0x132
Serial number: 132
The --issuedon-from and --issuedon-to options can s e t s tart/e nd points or a pe riod of
time to us e to s e arch for ce rtificate s .
ipa cert-find --issuedon-from=2013-02-01 --issuedon-to=2015-02-07

13.4.2. Revoking and Rest oring Cert if icat es
Eve ry ce rtificate has a s pe cifie d e xpiration date , but the re can be time s whe n it is
ne ce s s ary to te rminate (re voke ) a ce rtificate be fore that e xpiration. Re voking a ce rtificate
make s it invalid, s o the hos t cannot us e it for authe ntication.
Whe n a ce rtificate is re voke d, the re has to be a re as on give n. The pos s ible re as ons are
lis te d in Table 13.2, “Re vocation Re as ons ”.
T able 13.2. Revo cat io n Reaso ns
ID

Reaso n

0
1

Uns pe cifie d
Ke y Compromis e d

2

CA Compromis e d

Descript io n
The unde rlying ke y was
compromis e d. This could
me an a toke n was los t or
file was imprope rly
acce s s e d.
The CA which is s ue d the
ce rtificate was
compromis e d.

185

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ID

Reaso n

Descript io n

3

Affiliation Change d

4

Supe rs e de d

5

Ce s s ation of Ope ration

6

Ce rtificate Hold

8

Re move from CRL

9

Privile ge Withdrawn

10

Attribute Authority (AA)
Compromis e

The pe rs on or hos t to which
the ce rtificate was is s ue d is
changing affiliations . This
could me an that the pe rs on
has le ft the company (or the
hos t is be ing re tire d) or that
it has move d de partme nts ,
if the affiliation is tie d to an
organiz ational s tructure .
The ce rtificate has be e n
re place d by a ne we r
ce rtificate .
The hos t is be ing
de commis s ione d.
The ce rtificate is
te mporarily re voke d. This is
the only re vocation re as on
that allows the ce rtificate to
be re s tore d.
The ce rtificate is not
include d in the ce rtificate
re vocation lis t.
The hos t s hould no longe r
be is s ue d the ce rtificate .
The AA ce rtificate was
compromis e d

13.4.2.1. In t he Web UI
To re voke a ce rtificate :
1. Ope n the Authentication tab, and s e le ct the Certificates s ubtab.
2. In the Certificates s e ction, a lis t of all ce rtificate s is dis playe d. Click on the s e rial
numbe r of the ce rtificate you want dis playe d to ope n the ce rtificate information
page .

Figure 13.3. List o f Cert if icat es

186

⁠C hapt e r 13. Managing Ho s t s

3. Click Act io ns → Revo ke Cert if icat e.

Figure 13.4. Revo king a Cert if icat e
4. Se le ct the re as on for the re vocation, and click Revoke. For a de s cription of the
available re as ons , s e e Table 13.2, “Re vocation Re as ons ”.
If the re as on for re voking the ce rtificate was a ce rtificate hold, you can re s tore the
ce rtificate again by clicking Act io ns → Rest o re Cert if icat e.

13.4.2.2. In t he Command Line
To re voke a ce rtificate from the command line , s pe cify the ce rtificate s e rial numbe r and
give the re as on for the re vocation in the --revocation-reason option.
[root@server ~]# kinit admin
[root@server ~]# ipa cert-revoke --revocation-reason=6 1032
If the re as on for the re vocation is a ce rtificate hold (6), the n the ce rtificate can be
re s tore d with the cert-remove-hold command.
[root@server ~]# ipa cert-remove-hold 1032

13.4.3. Request ing New Host Cert if icat es
The ce rtificate re que s t mus t be ge ne rate d with a third-party tool s uch as certutil. The
re s ulting ce rtificate re que s t can be s ubmitte d through the IdM we b UI or command-line
tools .
The hos t mus t alre ady e xis t for a ce rtificate to be re que s te d. A ce rtificate cannot be
re que s te d for a ne w hos t be fore it is cre ate d.

13.4.3.1. In t he UI
1. Ope n the Identity tab, and s e le ct the Hosts s ubtab.
2. Click the name of the hos t to ope n the hos t configuration page .

187

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 13.5. List o f Ho st s
3. Click Act io ns → New Cert if icat e.

Figure 13.6. Request ing a New Cert if icat e
4. Follow the proce dure for re que s ting a ce rtificate us ing certutil, and the n pas te
the ce rtificate re que s t into the we b UI.

188

⁠C hapt e r 13. Managing Ho s t s

Figure 13.7. Issuing a Cert if icat e
5. Click Issue.

13.4.3.2. In t he Command Line
1. Ge ne rate a ce rtificate re que s t for the hos t. For e xample :
Firs t, cre ate a s e t of ce rtificate databas e s that can be us e d to cre ate and s tore the
ce rtificate locally.
[root@server ~]# certutil -N -d ~/test-certs/
The n, cre ate the ce rtificate re que s t.
[root@server ~]# certutil -R -d ~/test-certs -R -a -g 256 -s
"CN=server.example.com,O=EXAMPLE.COM" -o ~/test-certs/host.csr
2. Submit the PEM file of the ce rtificate re que s t to the IdM s e rve r. Along with the
re que s t its e lf, s pe cify the Ke rbe ros principal to cre ate and as s ociate with the
ne wly-is s ue d ce rtificate .
[root@server ~]# ipa cert-request -principal=host/server.example.com host.csr
Note that you can us e the --profile-id option with the ipa cert-request command to
s e le ct a cus tom ce rtificate profile to be us e d for the ce rtificate . By de fault, IdM us e s the
caIPAserviceCert profile . For more information about ce rtificate profile s , s e e
Se ction 28.9, “Ce rtificate Profile s ”.

189

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

13.5. Managing Public SSH Keys for Host s
Ope nSSH us e s public keys to authe nticate hos ts . One machine atte mpts to acce s s anothe r
machine and pre s e nts its ke y pair. The firs t time the hos t authe nticate s , the adminis trator
on the targe t machine has to approve the re que s t manually. The machine the n s tore s the
hos t's public ke y in a known_hosts file . Any time that the re mote machine atte mpts to
acce s s the targe t machine again, the targe t machine s imply che cks its known_hosts file
and the n grants acce s s automatically to approve d hos ts .
The re are a fe w proble ms with this s ys te m:
The known_hosts file s tore s hos t e ntrie s in a triple t of the hos t IP addre s s , hos tname ,
and ke y. This file can rapidly be come out of date if the IP addre s s change s (which is
common in virtual e nvironme nts and data ce nte rs ) or if the ke y is update d.
SSH ke ys have to be dis tribute d manually and s e parate ly to all machine s in an
e nvironme nt.
Adminis trators have to approve hos t ke ys to add the m to the configuration, but it is
difficult to ve rify e ithe r the hos t or ke y is s ue r prope rly, which can cre ate s e curity
proble ms .
On Re d Hat Ente rpris e Linux, the Sys te m Se curity Se rvice s Dae mon (SSSD) can be
configure d to cache and re trie ve hos t SSH ke ys s o that applications and s e rvice s only
have to look in one location for hos t ke ys . Be caus e SSSD can us e Ide ntity Manage me nt as
one of its ide ntity information provide rs , Ide ntity Manage me nt provide s a unive rs al and
ce ntraliz e d re pos itory of ke ys . Adminis trators do not ne e d to worry about dis tributing,
updating, or ve rifying hos t SSH ke ys .

13.5.1. About t he SSH Key Format
Whe n ke ys are uploade d to the IdM e ntry, the ke y format can be e ithe r an Ope nSSH-s tyle
ke y or a raw RFC 4253-s tyle blob. Any RFC 4253-s tyle ke y is automatically conve rte d into
an Ope nSSH-s tyle ke y be fore it is importe d and s ave d into the IdM LDAP s e rve r.
The IdM s e rve r can ide ntify the type of ke y, s uch as an RSA or DSA ke y, from the
uploade d ke y blob. Howe ve r, in a ke y file s uch as ~/.ssh/known_hosts, a ke y e ntry is
ide ntifie d by the hos tname and IP addre s s of the s e rve r, its type , the n las tly the ke y
its e lf. For e xample :
host.example.com,1.2.3.4 ssh-rsa AAA...ZZZ==
This is s lightly diffe re nt than a us e r public ke y e ntry, which has the e le me nts in the orde r
type key== comment:
"ssh-rsa ABCD1234...== ipaclient.example.com"
All thre e parts from the ke y file can be uploade d to and vie we d for the hos t e ntry. In that
cas e , the hos t public ke y e ntry from the ~/.ssh/known_hosts file ne e ds to be re orde re d
to match the format of a us e r ke y, type key== comment:
ssh-rsa AAA...ZZZ== host.example.com,1.2.3.4

190

⁠C hapt e r 13. Managing Ho s t s

The ke y type can be de te rmine d automatically from the conte nt of the public ke y, and the
comme nt is optional, to make ide ntifying individual ke ys e as ie r. The only re quire d e le me nt
is the public ke y blob its e lf.

13.5.2. About ipa-client -inst all and OpenSSH
The ipa-client-install s cript, by de fault, configure s an Ope nSSH s e rve r and clie nt on
the IdM clie nt machine . It als o configure s SSSD to pe rform hos t and us e r ke y caching.
Es s e ntially, s imply configuring the clie nt doe s all of the configuration ne ce s s ary for the
hos t to us e SSSD, Ope nSSH, and Ide ntity Manage me nt for ke y caching and re trie val.
If the SSH s e rvice is e nable d with the clie nt ins tallation (which is the de fault), the n an RSA
ke y is cre ate d whe n the ssh s e rvice is firs t s tarte d.

No te
Whe n the machine is adde d as an IdM clie nt us ing ipa-client-install, the clie nt
is cre ate d with two SSH ke ys , RSA and DSS.
The re is an additional clie nt configuration option, --ssh-trust-dns, which can be run with
ipa-client-install and automatically configure s Ope nSSH to trus t the IdM DNS re cords ,
whe re the ke y finge rprints are s tore d.
Alte rnative ly, it is pos s ible to dis able Ope nSSH at the time the clie nt is ins talle d, us ing the
--no-sshd option. This pre ve nts the ins tall s cript from configuring the Ope nSSH s e rve r.
Anothe r option, --no-dns-sshfp, pre ve nts the hos t from cre ating DNS SSHFP re cords with
its own DNS e ntrie s . This can be us e d with or without the --no-sshd option.

13.5.3. Uploading Host SSH Keys T hrough t he Web UI
1. The ke y for a hos t can probably be re trie ve d from a ~/.ssh/known_hosts. For
e xample :
server.example.com,1.2.3.4 ssh-rsa
AAAAB3NzaC1yc2EAAAABIwAAAQEApvjBvSFSkTU0WQW4eOweeo0DZZ08F9Ud21xlLy
6FOhzwpXFGIyxvXZ52+siHBHbbqGL5+14N7UvElruyslIHx9LYUR/pPKSMXCGyboLy
5aTNl5OQ5EHwrhVnFDIKXkvp45945R7SKYCUtRumm0Iw6wq0XD4o+ILeVbV3wmcB1b
Xs36ZvC/M6riefn9PcJmh6vNCvIsbMY6S+FhkWUTTiOXJjUDYRLlwM273FfWhzHK+S
SQXeBp/zIn1gFvJhSZMRi9HZpDoqxLbBB9QIdIw6U4MIjNmKsSI/ASpkFm2GuQ7ZK9
KuMItY2AoCuIRmRAdF8iYNHBTXNfFurGogXwRDjQ==
If ne ce s s ary, ge ne rate a hos t ke y. Whe n us ing the Ope nSSH tools , make s ure to
us e a blank pas s phras e and to s ave the ke y to a diffe re nt location than the us e r's
~/.ssh/ dire ctory, s o it will not ove rwrite any e xis ting ke ys .
[jsmith@server ~]$ ssh-keygen -t rsa -C
"server.example.com,1.2.3.4"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/jsmith/.ssh/id_rsa):
/home/jsmith/.ssh/host_keys
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

191

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Your identification has been saved in /home/jsmith/.ssh/host_keys.
Your public key has been saved in /home/jsmith/.ssh/host_keys.pub.
The key fingerprint is:
4f:61:ee:2c:f7:d7:da:41:17:93:de:1d:19:ac:2e:c8 server.example.com
The key's randomart image is:
+--[ RSA 2048]----+
|
.. |
|
.+|
|
o
.* |
|
o . .. *|
|
S + . o+|
|
E . .. .|
|
. = . o |
|
o . ..o|
|
.....|
+-----------------+
2. Copy the public ke y from the ke y file . The full ke y e ntry has the form hostname,IP
type key==. Only the key== is re quire d, but the e ntire e ntry can be s tore d. To us e
all e le me nts in the e ntry, re arrange the e ntry s o it has the orde r type key==
[hostname,IP]
[jsmith@server ~]$ cat /home/jsmith/.ssh/host_keys.pub
ssh-rsa AAAAB3NzaC1yc2E...tJG1PK2Mq++wQ==
server.example.com,1.2.3.4
3. Ope n the Identity tab, and s e le ct the Hosts s ubtab.
4. Click the name of the hos t to e dit.

Figure 13.8. List o f Ho st s
5. In the Host Settings are a of the Settings tab, click Add ne xt to SSH public
keys.

192

⁠C hapt e r 13. Managing Ho s t s

Figure 13.9. Adding an SSH Key
6. Pas te in the public ke y for the hos t, and click Set.

Figure 13.10 . Set t ing an SSH Key
The SSH public keys are a now s hows the ne w ke y. Clicking Show/Set key ope ns
the s ubmitte d ke y.

193

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

7. To upload multiple ke ys , click the Add link be low the lis t of public ke ys , and upload
the othe r ke ys .
8. Whe n all the ke ys have be e n s ubmitte d, click Save at the top of the hos t's page to
s ave the change s .
Whe n the public ke y is s ave d, the e ntry is dis playe d as the ke y finge rprint, the comme nt
(if one was include d), and the ke y type ⁠ [2] .
Afte r uploading the hos t ke ys , configure SSSD to us e Ide ntity Manage me nt as one of its
ide ntity domains and s e t up Ope nSSH to us e the SSSD tooling for managing hos t ke ys .
This is cove re d in the "Configuring Se rvice s : Ope nSSH and Cache d Ke ys " in the Sys te mLe ve l Authe ntication Guide .

13.5.4. Adding Host Keys f rom t he Command Line
Hos t SSH ke ys are adde d to hos t e ntrie s in IdM, e ithe r whe n the hos t is cre ate d us ing
host-add or by modifying the e ntry late r.

No te
RSA and DSS hos t ke ys are cre ate d by the ipa-client-install command, unle s s
the SSH s e rvice is e xplicitly dis able d in the ins tallation s cript.
1. Run the host-mod command with the --sshpubkey option to upload the bas e 64e ncode d public ke y to the hos t e ntry.
Adding a hos t ke y als o change s the DNS SSHFP e ntry for the hos t, s o als o us e the
--updatedns option to update the hos t's DNS e ntry.
For e xample :
[jsmith@server ~]$ ipa host-mod --sshpubkey="ssh-rsa RjlzYQo==" -updatedns host1.example.com
A re al ke y als o us ually e nds with an e qual s ign (=) but is longe r.
To upload more than one ke y, e nte r multiple --sshpubkey command-line
parame te rs :
--sshpubkey="RjlzYQo==" --sshpubkey="ZEt0TAo=="

No te
A hos t can have multiple public ke ys .
2. Afte r uploading the hos t ke ys , configure SSSD to us e Ide ntity Manage me nt as one
of its ide ntity domains and s e t up Ope nSSH to us e the SSSD tooling for managing
hos t ke ys . This is cove re d in the "Configuring Se rvice s : Ope nSSH and Cache d
Ke ys " in the Sys te m-Le ve l Authe ntication Guide .

13.5.5. Removing Host Keys

194

⁠C hapt e r 13. Managing Ho s t s

13.5.5. Removing Host Keys
Hos t ke ys can be re move d once the y e xpire or are no longe r valid.
To re move an individual hos t ke y, it is e as ie s t to re move the ke y through the we b UI:
1. Ope n the Identity tab, and s e le ct the Hosts s ubtab.
2. Click the name of the hos t to e dit.

Figure 13.11. List o f Ho st s
3. In the SSH public keys are a, click Delete by the finge rprint of the ke y to re move
it.

Figure 13.12. Public Key Delet io n
4. Click Save at the top of the hos t's page to s ave the change s .

195

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The command-line tools can be us e d to re move all ke ys . This is done by running ipa
host-mod with the --sshpubkey= s e t to a blank value ; this re move s all public ke ys for the
hos t. Als o, us e the --updatedns option to update the hos t's DNS e ntry. For e xample :
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-mod --sshpubkey= --updatedns
host1.example.com

13.6. Set t ing Et hers Informat ion for a Host
NIS can hos t an e the rs table which can be us e d to manage DHCP configuration file s for
s ys te ms bas e d on the ir platform, ope rating s ys te m, DNS domain, and MAC addre s s — all
information s tore d in hos t e ntrie s in IdM.
In Ide ntity Manage me nt, e ach s ys te m is cre ate d with a corre s ponding e the rs e ntry in the
dire ctory, in the ou=ethers s ubtre e .
cn=server,ou=ethers,dc=example,dc=com
This e ntry is us e d to cre ate a NIS map for the e the rs s e rvice which can be manage d by
the NIS compatibility plug-in in IdM.
To configure NIS maps for e the rs e ntrie s :
1. Add the MAC addre s s attribute to a hos t e ntry. For e xample :
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-mod --macaddress=12:34:56:78:9A:BC
server.example.com
2. Ope n the nsswitch.conf file .
3. Add a line for the e the rs s e rvice , and s e t it to us e LDAP for its lookup.
ethers: ldap
4. Che ck that the e the rs information is available for the clie nt.
[root@server ~]# getent ethers server.example.com

13.7. Managing Host Groups
Hos t groups are a way of ce ntraliz ing control ove r important manage me nt tas ks ,
particularly acce s s control.
All groups in Ide ntity Manage me nt are e s s e ntially static groups , me aning that the
me mbe rs of the group are manually and e xplicitly adde d to the group. IdM allows nested
groups, whe re a group is a me mbe r of anothe r group. In that cas e , all of the group
me mbe rs of the me mbe r group automatically be long to the pare nt group, as we ll.

196

⁠C hapt e r 13. Managing Ho s t s

Be caus e groups are e as y to cre ate , it is pos s ible to be ve ry fle xible in what groups to
cre ate and how the y are organiz e d. Groups can be de fine d around organiz ational divis ions
like de partme nts , phys ical locations , or IdM or infras tructure us age guide line s for acce s s
controls .

13.7.1. Creat ing Host Groups
13.7.1.1. Creat ing Host Groups f rom t he Web UI
1. Ope n the Identity tab, and s e le ct the Host Groups s ubtab.
2. Click Add at the top of the groups lis t.
3. Ente r the name and a de s cription for the group.
4. Click the Add and Edit button to go imme diate ly to the me mbe r s e le ction page .
5. Se le ct the me mbe rs , as de s cribe d in Se ction 13.7.2.2, “Adding Hos t Group
Me mbe rs from the We b UI”.

13.7.1.2. Creat ing Host Groups f rom t he Command Line
Ne w groups are cre ate d us ing the hostgroup-add command. (This adds only the group;
me mbe rs are adde d s e parate ly.)
Two attribute s are always re quire d: the group name and the group de s cription. If thos e
attribute s are not give n as argume nts , the n the s cript prompts for the m.
$ ipa hostgroup-add groupName --desc="description"

13.7.2. Adding Host Group Members
13.7.2.1. Showing and Changing Group Members
Me mbe rs can be adde d to a group through the group configuration. The re are tabs for all
the me mbe r type s which can be long to the group, and an adminis trator picks all of the
matching e ntrie s and adds the m as me mbe rs .
Howe ve r, it is als o pos s ible for an e ntity to be adde d to a group through its own
configuration. Each e ntry has a lis t of tabs that dis plays group type s that the e ntry can join.
The lis t of all groups of that type is dis playe d, and the e ntity can be adde d to multiple
groups at the s ame time .
On the hos t group page in the we b UI, host_group members s hows e ntrie s that can join
the dis playe d hos t group, and host_group is a member of s hows groups that the
dis playe d hos t group can join.

197

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 13.13. Ho st Gro up Page

13.7.2.2. Adding Host Group Members f rom t he Web UI
1. Ope n the Identity tab, and s e le ct the Host Groups s ubtab.
2. Click the name of the group to which to add me mbe rs .

Figure 13.14. List o f Ho st Gro ups
3. Click the Add link at the top of the tas k are a.

Figure 13.15. Adding a Member t o a Ho st Gro up

198

⁠C hapt e r 13. Managing Ho s t s

4. Move the name s of the hos ts to add to the Prospective column, and the n click Add
to confirm.

13.7.2.3. Adding Host Group Members f rom t he Command Line
Me mbe rs are adde d to a hos t group us ing the hostgroup-add-member command. This
command can add both hos ts as group me mbe rs and othe r groups as group me mbe rs .
The s yntax of the hostgroup-add-member command re quire s only the group name and
the hos ts to add. Lis ts of e ntrie s can be s e t by us ing the option multiple time s with the
s ame command or by lis ting the options in a comma-s e parate d lis t ins ide curly brace s ,
s uch as --option={val1,val2,val3}.
$ ipa hostgroup-add-member groupName [--hosts=host1 ...] [-hostgroups=hostGroup1 ...]
For e xample , this adds thre e hos ts to the caligroup group:
$ ipa hostgroup-add-member caligroup --hosts=ipaserver.example.com -hosts=client1.example.com --hosts=client2.example.com
Group name: caligroup
Description: for machines in california
GID: 387115842
Member hosts:
ipaserver.example.com,client1.example.com,client2.example.com
------------------------Number of members added 3
------------------------Like wis e , othe r groups can be adde d as me mbe rs , which cre ate s ne s te d groups :
$ ipa hostgroup-add-member caligroup --groups=mountainview -groups=sandiego
Group name: caligroup
Description: for machines in california
GID: 387115842
Member groups: mountainview,sandiego
------------------------Number of members added 2
-------------------------

[2] The key type is determ ined autom atically from the key itself, if it is not included in the
uploaded key.

199

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 14. Managing Services
Some s e rvice s that run on a hos t can als o be long to the IdM domain. Any s e rvice that can
s tore a Ke rbe ros principal or an SSL ce rtificate (or both) can be configure d as an IdM
s e rvice . Adding a s e rvice to the IdM domain allows the s e rvice to re que s t an SSL
ce rtificate or ke ytab from the domain. (Only the public ke y for the ce rtificate is s tore d in
the s e rvice re cord. The private ke y is local to the s e rvice .)
An IdM domain e s tablis he s a commonality be twe e n machine s , with common ide ntity
information, common policie s , and s hare d s e rvice s . Any machine which be longs to a
domain functions as a clie nt of the domain, which me ans it us e s the s e rvice s that the
domain provide s . An IdM domain (as de s cribe d in Se ction 1.2, “Bringing Linux Se rvice s
Toge the r”) provide s thre e main s e rvice s s pe cifically for machine s :
DNS
Ke rbe ros
Ce rtificate manage me nt

14.1. Adding and Edit ing Service Ent ries and Keyt abs
As with hos t e ntrie s , s e rvice e ntrie s for the hos t (and any othe r s e rvice s on that hos t
which will be long to the domain) mus t be adde d manually to the IdM domain. This is a two
s te p proce s s . Firs t, the s e rvice e ntry mus t be cre ate d, and the n a ke ytab mus t be
cre ate d for that s e rvice which it will us e to acce s s the domain.
By de fault, Ide ntity Manage me nt s ave s its HTTP ke ytab to /etc/httpd/conf/ipa.keytab.

No te
This ke ytab is us e d for the we b UI. If a ke y we re s tore d in ipa.keytab and that
ke ytab file is de le te d, the IdM we b UI will s top working, be caus e the original ke y
would als o be de le te d.
Similar locations can be s pe cifie d for e ach s e rvice that ne e ds to be made Ke rbe ros
aware . The re is no s pe cific location that mus t be us e d, but, whe n us ing ipa-getkeytab,
you s hould avoid us ing /etc/krb5.keytab. This file s hould not contain s e rvice -s pe cific
ke ytabs ; e ach s e rvice s hould have its ke ytab s ave d in a s pe cific location and the acce s s
privile ge s (and pos s ibly SELinux rule s ) s hould be configure d s o that only this s e rvice has
acce s s to the ke ytab.

14.1.1. Adding Services and Keyt abs f rom t he Web UI
1. Ope n the Identity tab, and s e le ct the Services s ubtab.
2. Click the Add link at the top of the s e rvice s lis t.

200

⁠C hapt e r 14 . Managing Se r vic e s

3. Se le ct the s e rvice type from the drop-down me nu, and give it a name .
4. Se le ct the hos tname of the IdM hos t on which the s e rvice is running. The hos tname
is us e d to cons truct the full s e rvice principal name .

5. Click the Add button to s ave the ne w s e rvice principal.

201

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

6. Us e the ipa-getkeytab command to ge ne rate and as s ign the ne w ke ytab for the
s e rvice principal.
[root@ipaserver ~]# # ipa-getkeytab -s ipaserver.example.com -p
HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256cts
The re alm name is optional. The IdM s e rve r automatically appe nds the Ke rbe ros
re alm for which it is configure d. You cannot s pe cify a diffe re nt re alm.
The hos tname mus t re s olve to a DNS A re cord for it to work with Ke rbe ros . You
can us e the --force flag to force the cre ation of a principal s hould this prove
ne ce s s ary.
The -e argume nt can include a lis t of e ncryption type s to include in the ke ytab.
This s upe rs e de s any de fault e ncryption type . Lis ts of e ntrie s can be s e t by
us ing the option multiple time s with the s ame command invocation or by lis ting
the options in a comma-s e parate d lis t ins ide curly brace s , s uch as --option=
{val1,val2,val3}.

Warning
Cre ating a ne w ke y re s e ts the s e cre t for the s pe cifie d principal. This me ans
that all othe r ke ytabs for that principal are re nde re d invalid.

14.1.2. Adding Services and Keyt abs f rom t he Command Line
1. Cre ate the s e rvice principal. The s e rvice is re cogniz e d through a name like
service/FQDN:
# ipa service-add serviceName/hostname
For e xample :
$ ipa service-add HTTP/server.example.com
------------------------------------------------------Added service "HTTP/server.example.com@EXAMPLE.COM"
------------------------------------------------------Principal: HTTP/server.example.com@EXAMPLE.COM
Managed by: ipaserver.example.com
2. Cre ate the s e rvice ke ytab file us ing the ipa-getkeytab command. This command
is run on the clie nt in the IdM domain. (Actually, it can be run on any IdM s e rve r or
clie nt, and the n the ke ys copie d to the appropriate machine . Howe ve r, it is s imple s t
to run the command on the machine with the s e rvice be ing cre ate d.)
The command re quire s the Ke rbe ros s e rvice principal (-p), the IdM s e rve r name (s), the file to write (-k), and the e ncryption me thod (-e). Be s ure to copy the ke ytab
to the appropriate dire ctory for the s e rvice .
For e xample :

202

⁠C hapt e r 14 . Managing Se r vic e s

# ipa-getkeytab -s server.example.com -p HTTP/server.example.com k /etc/httpd/conf/krb5.keytab -e aes256-cts
The re alm name is optional. The IdM s e rve r automatically appe nds the Ke rbe ros
re alm for which it is configure d. You cannot s pe cify a diffe re nt re alm.
The hos tname mus t re s olve to a DNS A re cord for it to work with Ke rbe ros . You
can us e the --force flag to force the cre ation of a principal s hould this prove
ne ce s s ary.
The -e argume nt can include a comma-s e parate d lis t of e ncryption type s to
include in the ke ytab. This s upe rs e de s any de fault e ncryption type . Lis ts of
e ntrie s can be s e t by us ing the option multiple time s with the s ame command
invocation or by lis ting the options in a comma-s e parate d lis t ins ide curly brace s ,
s uch as --option={val1,val2,val3}.

Warning
The ipa-getkeytab command re s e ts the s e cre t for the s pe cifie d principal.
This me ans that all othe r ke ytabs for that principal are re nde re d invalid.

14.2. Creat ing Cert ificat es for Services
By de fault, the IdM s e rve r has an inte grate d ce rtificate authority. This CA can be us e d to
cre ate , re voke , and is s ue ce rtificate s for s e rvice s in the IdM domain.

14.2.1. Showing Cert if icat es
14.2.1.1. In t he Service Ent ry in t he UI
1. Ope n the Identity tab, and s e le ct the Services s ubtab.
2. Click the name of the s e rvice .

203

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

3. In the Settings tab, s croll to the Service Certificate tab at the bottom.

4. If a ce rtificate has be e n is s ue d, click the View link to dis play the de tails about the
ce rtificate . To re trie ve the full ce rtificate , click the Get link.

204

⁠C hapt e r 14 . Managing Se r vic e s

14.2.1.2. In t he Cert if icat e List in t he UI
1. Ope n the Identity tab, and s e le ct the Certificates s ubtab.
2. Click the s e rial numbe r of the ce rtificate to vie w.

3. The top of the ce rtificate e ntry s hows the de tails of the ce rtificate , s uch as its CN.
The full ce rtificate blob is available at the bottom of the page .

205

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

14.2.1.3. In t he Command Line
All of the ce rtificate s which have be e n is s ue d by the IdM CA are lis te d with the ipa certfind command.
[root@server ~]# kinit admin
[root@server ~]# ipa cert-find
----------------------10 certificates matched
----------------------Serial number (hex): 0x1
Serial number: 1
Status: VALID
Subject: CN=Certificate Authority,O=EXAMPLE.COM
...
----------------------------Number of entries returned 10
----------------------------With a large numbe r of ce rtificate s , it can be e as ie r to s e arch for a s pe cific ce rtificate by
s e rial numbe r or by an is s ue date . To s e arch by a s e rial numbe r, s imply include it with the
cert-show command.
[root@server ~]# ipa cert-show 132
Serial number: 132
Certificate:
MIIDtzCCAp+gAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMR8wHQYDVQQKExZMQUIu
...
LxIQjrEFtJmoBGb/TWRlwGEWy1ayr4iTEf1ayZ+RGNylLalEAtk9RLjEjg==
Subject: CN=Certificate Authority,O=EXAMPLE.COM
Issuer: CN=Certificate Authority,O=EXAMPLE.COM
Not Before: Sun Jun 08 05:51:11 2014 UTC
Not After: Thu Jun 08 05:51:11 2034 UTC

206

⁠C hapt e r 14 . Managing Se r vic e s

Fingerprint (MD5): 46:53:2b:e9:88:c8:6b:ca:ec:5b:81:80:af:17:ea:85
Fingerprint (SHA1):
19:bc:93:e9:af:8c:ee:61:a3:10:07:6a:27:8b:5f:0a:25:d2:b0:72
Serial number (hex): 0x132
Serial number: 132
The --issuedon-from and --issuedon-to options can s e t s tart/e nd points or a pe riod of
time to us e to s e arch for ce rtificate s .
ipa cert-find --issuedon-from=2013-02-01 --issuedon-to=2015-02-07

14.2.2. Revoking and Rest oring Cert if icat es
Eve ry ce rtificate has a s pe cifie d e xpiration date , but the re can be time s whe n it is
ne ce s s ary to te rminate (re voke ) a ce rtificate be fore that e xpiration. Re voking a ce rtificate
make s it invalid, s o the s e rvice cannot us e it for authe ntication.
Whe n a ce rtificate is re voke d, the re has to be a re as on give n. The re are s e ve ral diffe re nt
re as ons — it was compromis e d, the e ntity has change d, the s e rvice is be ing pulle d from
s e rvice , or it has be e n re place d by a diffe re nt ce rtificate . The pos s ible re as ons are lis te d
in Table 14.1, “Re vocation Re as ons ”.
T able 14.1. Revo cat io n Reaso ns
ID

Reaso n

0
1

Uns pe cifie d
Ke y Compromis e d

2

CA Compromis e d

3

Affiliation Change d

4

Supe rs e de d

5

Ce s s ation of Ope ration

6

Ce rtificate Hold

Descript io n
The unde rlying ke y was
compromis e d. This could
me an a toke n was los t or
file was imprope rly
acce s s e d.
The CA which is s ue d the
ce rtificate was
compromis e d.
The pe rs on or s e rvice to
which the ce rtificate was
is s ue d is changing
affiliations . This could me an
that the pe rs on has le ft the
company (or the s e rvice is
be ing re tire d) or that it has
move d de partme nts , if the
affiliation is tie d to an
organiz ational s tructure .
The ce rtificate has be e n
re place d by a ne we r
ce rtificate .
The s e rvice is be ing
de commis s ione d.
The ce rtificate is
te mporarily re voke d. This is
the only re vocation re as on
that allows the ce rtificate to
be re s tore d.

207

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ID

Reaso n

Descript io n

8

Re move from CRL

9

Privile ge Withdrawn

10

Attribute Authority (AA)
Compromis e

The ce rtificate is not
include d in the ce rtificate
re vocation lis t.
The s e rvice s hould no
longe r be is s ue d the
ce rtificate .
The AA ce rtificate was
compromis e d

14.2.2.1. In t he Service Ent ry in t he UI
1. Ope n the Identity tab, and s e le ct the Services s ubtab.
2. Click the name of the s e rvice .

3. In the Settings tab, s croll to the Service Certificate tab at the bottom.

208

⁠C hapt e r 14 . Managing Se r vic e s

4. In the Actions are a, click the Revoke link.
5. Se le ct the re as on for the re vocation from the drop-down me nu, and click the
Revoke link. Table 14.1, “Re vocation Re as ons ” de s cribe s the diffe re nt options for
re voking a ce rtificate .

If the re as on for the re vocation is a ce rtificate hold, the n the ce rtificate can be re s tore d
late r by clicking the Restore link in the ce rtificate actions me nu.

14.2.2.2. In t he Cert if icat e List in t he UI

209

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1. Ope n the Identity tab, and s e le ct the Certificates s ubtab.
2. Click the s e rial numbe r of the ce rtificate to vie w.

3. In the Actions are a, click the Revoke link.
4. Se le ct the re as on for the re vocation from the drop-down me nu, and click the
Revoke link. Table 14.1, “Re vocation Re as ons ” de s cribe s the diffe re nt options for
re voking a ce rtificate .

210

⁠C hapt e r 14 . Managing Se r vic e s

If the re as on for the re vocation is a ce rtificate hold, the n the ce rtificate can be re s tore d
late r by clicking the Restore link in the ce rtificate actions me nu.

14.2.2.3. In t he Command Line
To re voke a ce rtificate from the command line , s pe cify the ce rtificate s e rial numbe r and
give the re as on for the re vocation in the --revocation-reason option.
[root@server ~]# kinit admin
[root@server ~]# ipa cert-revoke --revocation-reason=6 1032
If the re as on for the re vocation is a ce rtificate hold (6), the n the ce rtificate can be
re s tore d with the cert-remove-hold command.
[root@server ~]# ipa cert-remove-hold 1032

14.2.3. Request ing New Service Cert if icat es
The ce rtificate re que s t mus t be ge ne rate d with a third-party tool s uch as certutil. The
re s ulting ce rtificate re que s t can be s ubmitte d through the IdM we b UI or command-line
tools .
The s e rvice mus t alre ady e xis t for a ce rtificate to be re que s te d. If the s e rvice doe s not
ye t e xis t, the n with the command line , the re is an option to cre ate the s e rvice as part of
re que s ting the ce rtificate .

14.2.3.1. In t he UI
1. Ge ne rate a ce rtificate re que s t for the s e rvice . For e xample :
Firs t, cre ate a s e t of ce rtificate databas e s that can be us e d to cre ate and s tore the
ce rtificate locally.
[root@server ~]# certutil -N -d ~/test-certs/
The n, cre ate the ce rtificate re que s t.
[root@server ~]# certutil -R -d ~/test-certs -R -a -g 256 -s
"CN=server.example.com,O=EXAMPLE.COM" -o ~/test-certs/service.csr
2. Copy the te xt of the ne w ce rtificate re que s t.
3. Ope n the Identity tab, and s e le ct the Services s ubtab.
4. Click the name of the s e rvice .

211

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

5. In the Settings tab, s croll to the Service Certificate tab at the bottom.

6. In the Actions are a, click the Request link.
7. Pas te in the body of the ce rtificate re que s t, including the BEGIN NEW CERTIFICATE
REQUEST and END NEW CERTIFICATE REQUEST line s .

212

⁠C hapt e r 14 . Managing Se r vic e s

8. Click the Issue button.

14.2.3.2. In t he Command Line
1. Ge ne rate a ce rtificate re que s t for the s e rvice . For e xample :
Firs t, cre ate a s e t of ce rtificate databas e s that can be us e d to cre ate and s tore the
ce rtificate locally.
[root@server ~]# certutil -N -d ~/test-certs/
The n, cre ate the ce rtificate re que s t.
[root@server ~]# certutil -R -d ~/test-certs -R -a -g 256 -s
"CN=server.example.com,O=EXAMPLE.COM" -o ~/test-certs/service.csr
2. Submit the PEM file of the ce rtificate re que s t to the IdM s e rve r. Along with the
re que s t its e lf, s pe cify the Ke rbe ros principal to cre ate and as s ociate with the
ne wly-is s ue d ce rtificate .
If the s e rvice doe s not alre ady e xis t, the n us e the --add option to cre ate the
s e rvice , and the n is s ue the ce rtificate .
[root@server ~]# ipa cert-request -add -principal=ldap/server.example.com service.csr

213

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Note that you can us e the --profile-id option with the ipa cert-request command to
s e le ct a cus tom ce rtificate profile to be us e d for the ce rtificate . By de fault, IdM us e s the
caIPAserviceCert profile . For more information about ce rtificate profile s , s e e
Se ction 28.9, “Ce rtificate Profile s ”.

14.3. St oring Cert ificat es in NSS Dat abases
Whe n s e rvice s us e ce rtificate s , the ce rtificate s and ke ys can be s tore d in NSS databas e s
(which may als o be us e d by the s e rvice s the ms e lve s , as we ll as Ide ntity Manage me nt).
1. Cre ate the NSS databas e s .
$ certutil -N -d /path/to/database/dir
2. Re que s t the ce rtificate us ing certutil, an NSS tool.
$ certutil -R -s "CN=client1.example.com,O=EXAMPLE.COM" -d
/path/to/database/dir -a > example.csr
If the IdM domain is us ing Ce rtificate Sys te m for its CA, only the CN of the s ubje ct name is
us e d.

14.4. Configuring Clust ered Services
The IdM s e rve r is not cluster aware. Howe ve r, it is pos s ible to configure a clus te re d
s e rvice to be part of IdM by s ynchroniz ing Ke rbe ros ke ys acros s all of the participating
hos ts and configuring s e rvice s running on the hos ts to re s pond to whate ve r name s the
clie nts us e .
1. Enroll all of the hos ts in the clus te r into the IdM domain.
2. Cre ate any s e rvice principals and ge ne rate the re quire d ke ytabs .
3. Colle ct any ke ytabs that have be e n s e t up for s e rvice s on the hos t, including the
hos t ke ytab at /etc/krb5.keytab.
4. Us e the ktutil command to produce a s ingle ke ytab file that contains the conte nts
of all of the ke ytab file s .
a. For e ach file , us e the rkt command to re ad the ke ys from that file .
b. Us e the wkt command to write all of the ke ys which have be e n re ad to a
ne w ke ytab file .
5. Re place the ke ytab file s on e ach hos t with the ne wly-cre ate d combine d ke ytab file .
6. At this point, e ach hos t in this clus te r can now impe rs onate any othe r hos t.
7. Some s e rvice s re quire additional configuration to accommodate clus te r me mbe rs
which do not re s e t hos tname s whe n taking ove r a faile d s e rvice .
For sshd, s e t GSSAPIStrictAcceptorCheck no in /etc/ssh/sshd_config.
For mod_auth_kerb, s e t KrbServiceName Any in
/etc/httpd/conf.d/auth_kerb.conf.

214

⁠C hapt e r 14 . Managing Se r vic e s

No te
For SSL s e rve rs , the s ubje ct name or a s ubje ct alte rnative name for the s e rve r's
ce rtificate mus t appe ar corre ct whe n a clie nt conne cts to the clus te re d hos t. If
pos s ible , s hare the private ke y among all of the hos ts .
If e ach clus te r me mbe r contains a s ubje ct alte rnative name which include s the
name s of all the othe r clus te r me mbe rs , that s atis fie s any clie nt conne ction
re quire me nts .

14.5. Using t he Same Service Principal for Mult iple Services
Within a clus te r, the s ame s e rvice principal can be us e d for multiple s e rvice s , s pre ad
acros s diffe re nt machine s .
1. Re trie ve a s e rvice principal us ing the ipa-getkeytab command.
# ipa-getkeytab -s kdc.example.com -p HTTP/server.example.com -k
/etc/httpd/conf/krb5.keytab -e aes256-cts
2. Eithe r dire ct multiple s e rve rs or s e rvice s to us e the s ame file , or copy the file to
individual s e rve rs as re quire d.

14.6. Disabling and Re-enabling Service Ent ries
Active s e rvice s can be acce s s e d by othe r s e rvice s , hos ts , and us e rs within the domain.
The re can be s ituations whe n it is ne ce s s ary to re move a hos t or a s e rvice from activity.
Howe ve r, de le ting a s e rvice or a hos t re move s the e ntry and all the as s ociate d
configuration, and it re move s it pe rmane ntly.

14.6.1. Disabling Service Ent ries
Dis abling a s e rvice pre ve nts domain us e rs from acce s s it without pe rmane ntly re moving
it from the domain. This can be done by us ing the service-disable command.
For a s e rvice , s pe cify the principal for the s e rvice . For e xample :
[jsmith@ipaserver ~]$ kinit admin
$ ipa service-disable http/server.example.com

Impo rtant
Dis abling a hos t e ntry not only dis able s that hos t. It dis able s e ve ry configure d
s e rvice on that hos t as we ll.

14.6.2. Re-enabling Services

215

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Dis abling a s e rvice e s s e ntially kills its curre nt, active ke ytabs . Re moving the ke ytabs
e ffe ctive ly re move s the s e rvice from the IdM domain without othe rwis e touching its
configuration e ntry.
To re -e nable a s e rvice , s imply us e the ipa-getkeytab command. The -s option s e ts
which IdM s e rve r to re que s t the ke ytab, -p give s the principal name , and -k give s the file
to which to s ave the ke ytab.
For e xample , re que s ting a ne w HTTP ke ytab:
[root@ipaserver ~]# ipa-getkeytab -s ipaserver.example.com -p
HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256-cts
If the ipa-getkeytab command is run on an active IdM clie nt or s e rve r, the n it can be run
without any LDAP cre de ntials (-D and -w). The IdM us e r us e s Ke rbe ros cre de ntials to
authe nticate to the domain. To run the command dire ctly on a dis able d hos t, the n s upply
LDAP cre de ntials to authe nticate to the IdM s e rve r. The cre de ntials s hould corre s pond to
the hos t or s e rvice which is be ing re -e nable d.

216

⁠C hapt e r 15. De le gat ing Us e r Ac c e s s t o Ho s t s and Se r vic e s

Chapt er 15. Delegat ing User Access t o Host s and
Services
As dis cus s e d in Se ction 1.3, “Re lations hips Be twe e n Se rve rs and Clie nts ”, within the IdM
domain, manage me ans be ing able to re trie ve a ke ytab and ce rtificate s for anothe r hos t
or s e rvice . Eve ry hos t and s e rvice has a managedby e ntry which lis ts what hos ts or
s e rvice s can manage it. By de fault, a hos t can manage its e lf and all of its s e rvice s . It is
als o pos s ible to allow a hos t to manage othe r hos ts , or s e rvice s on othe r hos ts , by
updating the appropriate de le gations or providing a s uitable managedby e ntry.
An IdM s e rvice can be manage d from any IdM hos t, as long as that hos t has be e n grante d,
or delegated, pe rmis s ion to acce s s the s e rvice . Like wis e , hos ts can be de le gate d
pe rmis s ions to othe r hos ts within the domain.

Figure 15.1. Ho st and Service Delegat io n

No te
If a hos t is de le gate d authority to anothe r hos t through a managedBy e ntry, it doe s
not me an that the hos t has als o be e n de le gate d manage me nt for all s e rvice s on
that hos t. Each de le gation has to be pe rforme d inde pe nde ntly.

15.1. Delegat ing Service Management
A hos t is de le gate d control ove r a s e rvice us ing the service-add-host command. The re
are two parts to de le gating the s e rvice : s pe cifying the principal and ide ntifying the hos ts
with the control:
# ipa service-add-host principal --hosts=hostnames
For e xample :
[root@server ]# ipa service-add-host HTTP/web.example.com -hosts=client1.example.com

217

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Once the hos t is de le gate d authority, the hos t principal can be us e d to manage the
s e rvice :
[root@server ]# kinit -kt /etc/krb5.keytab host/`hostname`
# ipa-getkeytab -s `hostname` -k /tmp/test.keytab -p
HTTP/web.example.com
Keytab successfully retrieved and stored in: /tmp/test.keytab
To cre ate a ticke t for this s e rvice , cre ate a ce rtificate re que s t on the hos t with the
de le gate d authority and us e the cert-request command to cre ate a s e rvice e ntry and
load the ce rtification information:
[root@server ]# ipa cert-request --add --principal=HTTP/web.example.com
web.csr
Certificate: MIICETCCAXqgA...[snip]
Subject: CN=web.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
Note that you can us e the --profile-id option with the ipa cert-request command to
s e le ct a cus tom ce rtificate profile to be us e d for the ce rtificate . By de fault, IdM us e s the
caIPAserviceCert profile . For more information about ce rtificate profile s , s e e
Se ction 28.9, “Ce rtificate Profile s ”.

15.2. Delegat ing Host Management
Hos ts are de le gate d authority ove r othe r hos ts through the host-add-managedby
command. This cre ate s a managedby e ntry. Once the managedby e ntry is cre ate d, the n the
hos t can re trie ve a ke ytab for the hos t it has de le gate d authority ove r.
1. Log in as the admin us e r.
[root@server ]# kinit admin
2. Add the managedby e ntry. For e xample , this de le gate s authority over clie nt2 to
clie nt1.
[root@server ]# ipa host-add-managedby client2.example.com -hosts=client1.example.com
3. Obtain a ticke t as the hos t client1 and the n re trie ve a ke ytab for client2:
[root@server ]# kinit -kt /etc/krb5.keytab host/`hostname`
[root@server ~]# ipa-getkeytab -s `hostname` -k
/tmp/client2.keytab -p host/client2.example.com
Keytab successfully retrieved and stored in: /tmp/client2.keytab

15.3. Delegat ing Host or Service Management in t he Web UI
218

⁠C hapt e r 15. De le gat ing Us e r Ac c e s s t o Ho s t s and Se r vic e s

15.3. Delegat ing Host or Service Management in t he Web UI
Each hos t and s e rvice e ntry has a configuration tab that indicate s what hos ts have be e n
de le gate d manage me nt control ove r that hos t or s e rvice .
1. Ope n the Identity tab, and s e le ct the Hosts or Services s ubtab.
2. Click the name of the hos t or s e rvice that you are going to grant delegated
management to.
3. Click the Hosts s ubtab on the far right of the hos t/s e rvice e ntry. This is the tab
which lis ts hos ts that can manage the s e le cte d hos t/s e rvice .

Figure 15.2. Ho st Subt ab
4. Click the Add link at the top of the lis t.
5. Click the che ckbox by the name s of the hos ts to which to de le gate manage me nt for
the hos t/s e rvice . Click the right arrow button, >, to move the hos ts to the s e le ction
box.

Figure 15.3. Ho st /Service Delegat io n Management
6. Click the Add button to clos e the s e le ction box and to s ave the de le gation s e ttings .

219

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

15.4. Accessing Delegat ed Services
For both s e rvice s and hos ts , if a clie nt has de le gate d authority, it can obtain a ke ytab for
that principal on the local machine . For s e rvice s , this has the format
service/hostname@REALM. For hos ts , the service is host.
With kinit, us e the -k option to load a ke ytab and the -t option to s pe cify the ke ytab.
For e xample , to acce s s a hos t:
[root@server ]# kinit -kt /etc/krb5.keytab
host/ipa.example.com@EXAMPLE.COM
To acce s s a s e rvice :
[root@server ]# kinit -kt /etc/httpd/conf/krb5.keytab
http/ipa.example.com@EXAMPLE.COM

220

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

Chapt er 16. Int egrat ing wit h NIS Domains and
Net groups
Ne twork information s e rvice (NIS) is one of the mos t common ways to manage ide ntitie s
and authe ntication on Unix ne tworks . It is s imple and e as y to us e , but it als o has inhe re nt
s e curity ris ks and a lack of fle xibility that can make adminis te ring NIS domains
proble matic.
Ide ntity Manage me nt s upplie s a way to inte grate ne tgroups and othe r NIS data into the IdM
domain, which incorporate s the s tronge r s e curity s tructure of IdM ove r the NIS
configuration. Alte rnative ly, adminis trators can s imply migrate us e r and hos t ide ntitie s
from a NIS domain into the IdM domain.

16.1. About NIS and Ident it y Management
Ne twork information s e rvice (NIS) ce ntrally manage s authe ntication and ide ntity
information s uch as us e rs and pas s words , hos ts and IP addre s s e s , and POSIX groups . This
was originally calle d Yellow Pages (abbre viate d YP) be caus e of its s imple focus on ide ntity
and authe ntication lookups .
NIS is cons ide re d too ins e cure for mos t mode rn ne twork e nvironme nts be caus e it
provide s no hos t authe ntication me chanis ms and it trans mits all of its information ove r the
ne twork une ncrypte d, including pas s word has he s . Still, while NIS has be e n falling out of
favor with adminis trators , it is s till active ly us e d by many s ys te m clie nts . The re are ways
to work around thos e ins e curitie s by inte grating NIS with othe r protocols which offe r
e nhance d s e curity.
In Ide ntity Manage me nt, NIS obje cts are inte grate d into IdM us ing the unde rlying LDAP
dire ctory. LDAP s e rvice s offe r s upport for NIS obje cts (as de fine d in RFC 2307), which
Ide ntity Manage me nt cus tomiz e s to provide be tte r inte gration with othe r domain ide ntitie s .
The NIS obje ct is cre ate d ins ide the LDAP s e rvice and the n a module like nss_ldap or
SSSD fe tche s the obje ct us ing an e ncrypte d LDAP conne ction.
NIS e ntitie s are s tore d in netgroups. A ne tgroup allows ne s ting (groups ins ide groups ),
which s tandard Unix groups don't s upport. Als o, ne tgroups provide a way to group hos ts ,
which is als o mis s ing in Unix group.
NIS groups work by de fining us e rs and hos ts as me mbe rs of a large r domain. A ne tgroup
s e ts a trio of information — hos t, us e r, domain. This is calle d a triple.
host,user,domain
A ne tgroup triple as s ociate s the us e r or the hos t with the domain; it doe s not as s ociate
the us e r and the hos t with e ach othe r. The re fore , a triple us ually de fine s a hos t or a us e r
for be tte r clarity and manage me nt.
host.example.com,,nisdomain.example.com
-,jsmith,nisdomain.example.com
NIS dis tribute s more than jus t ne tgroup data. It s tore s information about us e rs and
pas s words , groups , ne twork data, and hos ts , among othe r information.
Ide ntity Manage me nt can us e a NIS lis te ne r to map pas s words , groups , and ne tgroups to
IdM e ntrie s .

221

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

In IdM LDAP e ntrie s , the us e rs in a ne tgroup can be a s ingle us e r or a group; both are
ide ntifie d by the memberUser parame te r. Like wis e , hos ts can be e ithe r a s ingle hos t or a
hos t group; both are ide ntifie d by the memberHost attribute .
dn: ipaUniqueID=d4453480-cc53-11dd-ad8b0800200c9a66,cn=ng,cn=accounts,...
objectclass: top
objectclass: ipaAssociation
objectclass: ipaNISNetgroup
ipaUniqueID: d4453480-cc53-11dd-ad8b-0800200c9a66
cn: netgroup1
memberHost: fqdn=host1.example.com,cn=computers,cn=accounts,...
memberHost: cn=VirtGuests,cn=hostgroups,cn=accounts,...
memberUser: cn=jsmith,cn=users,cn=accounts,...
memberUser: cn=bjensen,cn=users,cn=accounts,...
memberUser: cn=Engineering,cn=groups,cn=accounts,...
nisDomainName: nisdomain.example.com
In Ide ntity Manage me nt, the s e ne tgroup e ntrie s are handle d us ing the netgroup-*
commands , which s how the bas ic LDAP e ntry:
[root@server ~]# ipa netgroup-show netgroup1
Netgroup name: netgroup1
Description: my netgroup
NIS domain name: nisdomain
Member User: jsmith
Member User: bjensen
Member User: Engineering
Member Host: host1.example.com
Member Host: VirtGuests
Whe n a clie nt atte mpts to acce s s the NIS ne tgroup, the n Ide ntity Manage me nt trans late s
the LDAP e ntry into a traditional NIS map and s e nds it to a clie nt ove r the NIS protocol
(us ing a NIS plug-in) or it trans late s it into an LDAP format that is compliant with RFC 2307
or RFC 2307bis .

16.2. Set t ing t he NIS Port for Ident it y Management
The IdM s e rve r binds to its NIS s e rvice s ove r a random port that is s e le cte d whe n the
s e rve r s tarts . It s e nds that port as s ignme nt to the portmappe r s o that NIS clie nts know
what port to us e to contact the IdM s e rve r.
Adminis trators may ne e d to ope n a fire wall for NIS clie nts or may have othe r s e rvice s
that ne e d to know the port numbe r in advance and ne e d that port numbe r to re main the
s ame . In that cas e , an adminis trator can s pe cify the port to us e .

No te
Any available port numbe r be low 1024 can be us e d for the NIS Plug-in s e tting.
The NIS configuration is in the NIS Plug-in in Ide ntity Manage me nt's inte rnal
Dire ctory Se rve r ins tance . To s pe cify the port:

222

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

1. Enable the NIS lis te ne r and compatibility plug-ins :
[root@ipaserver ~]# ipa-nis-manage enable
[root@ipaserver ~]# ipa-compat-manage enable
2. Edit the plug-in configuration and add the port numbe r as an argume nt. For
e xample , to s e t the port to 514:
[root@ipaserver ~]# ldapmodify -x -D 'cn=directory manager' -w
secret
dn: cn=NIS Server,cn=plugins,cn=config
changetype: modify
add: nsslapd-pluginarg0
nsslapd-pluginarg0: 514
modifying entry "cn=NIS Server,cn=plugins,cn=config"
3. Re s tart the Dire ctory Se rve r to load the ne w plug-in configuration.
[root@ipaserver ~]# systemctl restart dirsrv.target

16.3. Creat ing Net groups
All ne tgroups in Ide ntity Manage me nt are e s s e ntially static groups , me aning that the
me mbe rs of the group are manually and e xplicitly adde d to the group. IdM allows nested
groups, whe re a group is a me mbe r of anothe r group. In that cas e , all of the group
me mbe rs of the me mbe r group automatically be long to the pare nt group, as we ll.
Ne tgroups are adde d in two s te ps : the group its e lf is cre ate d, and the n me mbe rs are
adde d to it.

16.3.1. Adding Net groups
16.3.1.1. Wit h t he Web UI
1. Ope n the Identity tab, and s e le ct the Netgroups s ubtab.
2. Click Add at the top of the ne tgroups lis t.

223

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 16.1. Net gro ups List
3. Ente r a unique name and, optionally, a de s cription.

Figure 16.2. Add Net gro up Dialo gue
The group name is the ide ntifie r us e d for the ne tgroup in the IdM domain, and it
cannot be change d afte r it is cre ate d. The name cannot contain s pace s , but othe r
s e parators like an unde rs core (_) are allowe d.
4. Click the Add and Edit button to go imme diate ly to the ne tgroup's e dit page s .
5. Optionally, s e t the NIS domain for the ne tgroup. This de faults to the IdM domain, but
it can be change d.
a. Click the name of the group you wis h to e dit.
b. In the General part of the s e ttings , e nte r the name of the alte rnate NIS
domain in the NIS domain name fie ld.

224

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

Figure 16.3. Net gro up T ab
The NIS domain name fie ld s e ts the domain that appe ars in the ne tgroup
triple . It doe s not affe ct which NIS domain the Ide ntity Manage me nt lis te ne r
re s ponds to.
6. Add me mbe rs , as de s cribe d in Se ction 16.3.2.1, “With the We b UI”.

16.3.1.2. Wit h t he Command Line
Ne w ne tgroups are adde d us ing the netgroup-add command. This adds only the group;
me mbe rs are adde d s e parate ly. Two attribute s are always re quire d: the group name and
the group de s cription. If thos e attribute s are not give n as argume nts , the n the s cript
prompts for the m. The re is als o an option to s e t the NIS domain name to us e for the
group; this de faults to the IdM domain, but it can be s e t to s ome thing diffe re nt, de pe nding
on the ne twork configuration.
[jsmith@server ~]$ ipa netgroup-add --desc="description"
nisdomain=domainName] groupName

[--

For e xample :
[root@server ~][root@server ~]# ipa netgroup-add --desc="my new

225

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

netgroup" example-netgroup
[root@server ~]# ipa netgroup-add-member --hosts=ipa.example.com
example-netgroup
[root@server ~]# ypcat -d example.com -h ipa.example.com netgroup
(ipa.example.com,-,example.com)

No te
The --nisdomain option s e ts the domain that appe ars in the ne tgroup triple . It doe s
not affe ct which NIS domain the Ide ntity Manage me nt lis te ne r re s ponds to.

16.3.2. Adding Net group Members

No te
Ne tgroups can contain us e r groups , hos t groups , and othe r ne tgroups as the ir
me mbe rs . The s e are nested groups .
It can take up to s e ve ral minute s for the me mbe rs of the child group to s how up as
me mbe rs of the pare nt group. This is e s pe cially true on virtual machine s whe re the
ne s te d groups have more than 500 me mbe rs .
Whe n cre ating ne s te d groups , be care ful not to cre ate recursive groups . For
e xample , if GroupA is a me mbe r of GroupB, do not add GroupB as a me mbe r of
GroupA. Re curs ive groups are not s upporte d and can caus e unpre dictable be havior.

16.3.2.1. Wit h t he Web UI
1. Ope n the Identity tab, and s e le ct the Netgroups s ubtab.
2. Click the name of the ne tgroup to which to add me mbe rs .

Figure 16.4. Net gro ups List
3. Choos e the type of ne tgroup me mbe r to add. Click Add by the lis t of the ne tgroup
me mbe rs .

226

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

Figure 16.5. User Menu in t he Net gro up T ab
4. Click the che ckbox by the name s of the us e rs to add, and click the right arrow
button, >, to move the name s to the s e le ction box.

Figure 16.6. Add User Menu in t he Net gro up T ab
5. Click Add.

16.3.2.2. Wit h t he Command Line

227

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Once the group is configure d, be gin adding ne tgroup me mbe rs with the netgroup-addmember command. Us e rs , groups , hos ts , hos t groups , and othe r ne tgroups can all be
adde d to the ne tgroup e ntry. The e ntry name of the NIS group be ing e dite d us ually come s
at the e nd of the command:
# ipa netgroup-add-member --users=users --groups=groups --hosts=hosts -hostgroups=hostGroups --netgroups=netgroups groupName
To s e t more than one me mbe r, e ithe r us e the option multiple time s or us e a commas e parate d lis t ins ide a s e t of curly brace s (for e xample , --option={val1,val2,val3}). For
e xample , this s e ts two us e rs and two hos ts with the othe r configuration:
[root@server ~]# ipa netgroup-add-member --users=jsmith --users=bjensen
--groups=ITadmin --hosts=host1.example.com --hosts=host2.example.com -hostgroups=EngDev --netgroups=nisgroup2 example-group

16.4. Exposing Aut omount Maps t o NIS Client s
Whe n the NIS s e rvice is e nable d on a s ys te m, the IdM s e rve r is automatically configure d
to s e t the NIS domain to the IdM domain's name , and to include IdM us e rs , groups , and
ne tgroups as pas s wd, group, and ne tgroup maps in the NIS domain.
If any automount maps are alre ady de fine d, the s e maps ne e d to be manually adde d to
the NIS configuration in Ide ntity Manage me nt for the m to be e xpos e d to NIS clie nts . The
NIS s e rve r is manage d by a s pe cial plug-in e ntry in the IdM LDAP dire ctory; this is a
containe r e ntry, and e ach NIS domain and map us e d by the NIS s e rve r is configure d as a
child e ntry be ne ath that containe r. The NIS domain e ntry mus t contain:
the name of the NIS domain
the name of the NIS map
information on how to find the dire ctory e ntrie s to us e as the NIS map's conte nts
information on which attribute s to us e as the NIS map's ke y and value
Mos t of the s e s e ttings will be the s ame for e ve ry map.
The IdM s e rve r s tore s the automount maps , groupe d by automount location, in the
cn=automount branch of the IdM dire ctory tre e .
The NIS domain and map is adde d us ing LDAP tools , like ldapadd, and e diting the dire ctory
dire ctly. For e xample , this adds an automount map that is name d auto.example in a
location name d default and for a s e rve r name d nisserver:
[root@server ~]# ldapadd -h nisserver.example.com -x -D "cn=Directory
Manager" -w secret
dn: nis-domain=example.com+nis-map=auto.example,cn=NIS
Server,cn=plugins,cn=config
objectClass: extensibleObject
nis-domain: example.com
nis-map: auto.example
nis-filter: (objectclass=automount)

228

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

nis-key-format: %{automountKey}
nis-value-format: %{automountInformation}
nis-base:
automountmapname=auto.example,cn=default,cn=automount,dc=example,dc=com
A s imilar add ope ration ne e ds to be run for e ve ry map that is configure d.

16.5. Migrat ing from NIS t o IdM
The re is no dire ct migration path from NIS to Ide ntity Manage me nt. This is a manual
proce s s with thre e major s te ps : s e tting up ne tgroup e ntrie s in IdM, e xporting the e xis ting
data from NIS, and importing that data into IdM. The re are s e ve ral options for how to s e t
up the IdM e nvironme nt and how to e xport data; the be s t option de pe nds on the type of
data and the ove rall ne twork e nvironme nt that you have .

16.5.1. Preparing Net group Ent ries in IdM
The firs t s te p is to ide ntify what kinds of ide ntitie s are be ing manage d by NIS. Fre que ntly,
a NIS s e rve r is us e d for e ithe r us e r e ntrie s or hos t e ntrie s , but not for both, which can
s implify the data migration proce s s .
Fo r user ent ries
De te rmine what applications are us ing the us e r information in the NIS s e rve r. While s ome
clie nts (like sudo) re quire NIS ne tgroups , many clie nts can us e Unix groups ins te ad. If no
ne tgroups are re quire d, the n s imply cre ate corre s ponding us e r accounts in IdM and de le te
the ne tgroups e ntire ly. Othe rwis e , cre ate the us e r e ntrie s in IdM and the n cre ate an IdMmanage d ne tgroup and add thos e us e rs as me mbe rs . This is de s cribe d in Se ction 16.3,
“Cre ating Ne tgroups ”.
Fo r ho st ent ries
Whe ne ve r a hos t group is cre ate d in IdM, a corre s ponding s hadow NIS group is
automatically cre ate d. The s e ne tgroups can the n be manage d us ing the ipa-host-netmanage command.
Fo r a direct co nversio n
It may be ne ce s s ary to have an e xact conve rs ion, with e ve ry NIS us e r and hos t having an
e xact corre s ponding e ntry in IdM. In that cas e , e ach e ntry can be cre ate d us ing the
original NIS name s :
1. Cre ate an e ntry for e ve ry us e r re fe re nce d in a ne tgroup.
2. Cre ate an e ntry for e ve ry hos t re fe re nce d in a ne tgroup.
3. Cre ate a ne tgroup with the s ame name as the original ne tgroup.
4. Add the us e rs and hos ts as dire ct me mbe rs of the ne tgroup. Alte rnative ly, add the
us e rs and hos ts into IdM groups or othe r ne tgroups , and the n add thos e groups as
me mbe rs to the ne tgroup.

16.5.2. Enabling t he NIS List ener in Ident it y Management

229

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The IdM Dire ctory Se rve r can function as a limite d NIS s e rve r. The slapi-nis plug-in s e ts
up a s pe cial NIS lis te ne r that re ce ive s incoming NIS re que s ts and manage s the NIS maps
within the Dire ctory Se rve r. Ide ntity Manage me nt us e s thre e NIS maps :
pas s wd
group
ne tgroup
Us ing IdM as an inte rme diate NIS s e rve r offe rs a re as onable way to handle NIS re que s ts
while migrating NIS clie nts and data.
The slapi-nis plug-in is not e nable d by de fault. To e nable NIS for Ide ntity Manage me nt:
1. Obtain ne w Ke rbe ros cre de ntials as an IdM admin us e r.
[root@ipaserver ~]# kinit admin
2. Enable the NIS lis te ne r and compatibility plug-ins :
[root@ipaserver ~]# ipa-nis-manage enable
[root@ipaserver ~]# ipa-compat-manage enable
3. Re s tart the port mappe r and Dire ctory Se rve r s e rvice :
[root@server ~]# systemctl start rpcbind.service
[root@server ~]# systemctl restart dirsrv.target

16.5.3. Export ing and Import ing t he Exist ing NIS Dat a
NIS can contain information for us e rs , groups , DNS and hos ts , ne tgroups , and automount
maps . Any of the s e e ntry type s can be migrate d ove r to the IdM s e rve r.
Migration is pe rforme d by e xporting the data us ing ypcat and the n looping through that
output and cre ating the IdM e ntrie s with the corre s ponding ipa *-add commands . While
this could be done manually, it is e as ie s t to s cript it. The s e e xample s us e a s he ll s cript.

16.5.3.1. Import ing User Ent ries
The /etc/passwd file contains all of the NIS us e r information. The s e e ntrie s can be us e d
to cre ate IdM us e r accounts with UID, GID, ge cos , s he ll, home dire ctory, and name
attribute s that mirror the NIS e ntrie s .
For e xample , this is nis-user.sh:
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 passwd > /dev/shm/nis-map.passwd 2>&1
IFS=$'\n'
for line in $(cat /dev/shm/nis-map.passwd); do
IFS=' '
username=$(echo $line|cut -f1 -d:)
# Not collecting encrypted password because we need cleartext
password to create kerberos key

230

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

uid=$(echo $line|cut -f3 -d:)
gid=$(echo $line|cut -f4 -d:)
gecos=$(echo $line|cut -f5 -d:)
homedir=$(echo $line|cut -f6 -d:)
shell=$(echo $line|cut -f7 -d:)
# Now create this entry
echo passw0rd1|ipa user-add $username --first=NIS --last=USER -password --gidnumber=$gid --uid=$uid --gecos=$gecos --homedir=$homedir -shell=$shell
ipa user-show $username
done
This can be run for a give n NIS domain:
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-user.sh nisdomain nis-master.example.com

No te
This s cript doe s not migrate us e r pas s words . Rathe r, it cre ate s a te mporary
pas s word which us e rs are the n prompte d to change whe n the y ne xt log in.

16.5.3.2. Import ing Group Ent ries
The /etc/group file contains all of the NIS group information. The s e e ntrie s can be us e d
to cre ate IdM us e r group accounts with the GID, ge cos , s he ll, home dire ctory, and name
attribute s that mirror the NIS e ntrie s .
For e xample , this is nis-group.sh:
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 group > /dev/shm/nis-map.group 2>&1
IFS=$'\n'
for line in $(cat /dev/shm/nis-map.group); do
IFS=' '
groupname=$(echo $line|cut -f1 -d:)
# Not collecting encrypted password because we need cleartext
password to create kerberos key
gid=$(echo $line|cut -f3 -d:)
members=$(echo $line|cut -f4 -d:)
# Now create this entry
ipa group-add $groupname --desc=NIS_GROUP_$groupname --gid=$gid
if [ -n "$members" ]; then
ipa group-add-member $groupname --users={$members}
fi
ipa group-show $groupname
done
This can be run for a give n NIS domain:

231

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-group.sh nisdomain nis-master.example.com

16.5.3.3. Import ing Host Ent ries
The /etc/hosts file contains all of the NIS hos t information. The s e e ntrie s can be us e d to
cre ate IdM hos t accounts that mirror the NIS e ntrie s .
For e xample , this is nis-hosts.sh:
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 hosts | egrep -v "localhost|127.0.0.1" > /dev/shm/nismap.hosts 2>&1
IFS=$'\n'
for line in $(cat /dev/shm/nis-map.hosts); do
IFS=' '
ipaddress=$(echo $line|awk '{print $1}')
hostname=$(echo $line|awk '{print $2}')
master=$(ipa env xmlrpc_uri |tr -d '[:space:]'|cut -f3 -d:|cut f3 -d/)
domain=$(ipa env domain|tr -d '[:space:]'|cut -f2 -d:)
if [ $(echo $hostname|grep "\." |wc -l) -eq 0 ]; then
hostname=$(echo $hostname.$domain)
fi
zone=$(echo $hostname|cut -f2- -d.)
if [ $(ipa dnszone-show $zone 2>/dev/null | wc -l) -eq 0 ]; then
ipa dnszone-add --name-server=$master --adminemail=root.$master
fi
ptrzone=$(echo $ipaddress|awk -F. '{print $3 "." $2 "." $1 ".inaddr.arpa."}')
if [ $(ipa dnszone-show $ptrzone 2>/dev/null|wc -l) -eq 0 ];
then
ipa dnszone-add $ptrzone --name-server=$master --adminemail=root.$master
fi
# Now create this entry
ipa host-add $hostname --ip-address=$ipaddress
ipa host-show $hostname
done
This can be run for a give n NIS domain:
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-hosts.sh nisdomain nis-master.example.com

No te
This s cript e xample doe s not account for s pe cial hos t s ce narios , s uch as us ing
alias e s .

232

⁠C hapt e r 16 . Int e gr at ing wit h NIS Do mains and Ne t gr o ups

16.5.3.4. Import ing Net group Ent ries
The /etc/netgroup file contains all of the NIS ne tgroup information. The s e e ntrie s can be
us e d to cre ate IdM ne tgroup accounts that mirror the NIS e ntrie s .
For e xample , this is nis-netgroup.sh:
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -k -d $1 -h $2 netgroup > /dev/shm/nis-map.netgroup 2>&1
IFS=$'\n'
for line in $(cat /dev/shm/nis-map.netgroup); do
IFS=' '
netgroupname=$(echo $line|awk '{print $1}')
triples=$(echo $line|sed "s/^$netgroupname //")
echo "ipa netgroup-add $netgroupname -desc=NIS_NG_$netgroupname"
if [ $(echo $line|grep "(,"|wc -l) -gt 0 ]; then
echo "ipa netgroup-mod $netgroupname --hostcat=all"
fi
if [ $(echo $line|grep ",,"|wc -l) -gt 0 ]; then
echo "ipa netgroup-mod $netgroupname --usercat=all"
fi
for triple in $triples; do
triple=$(echo $triple|sed -e 's/-//g' -e 's/(//' -e
's/)//')
if [ $(echo $triple|grep ",.*,"|wc -l) -gt 0 ]; then
hostname=$(echo $triple|cut -f1 -d,)
username=$(echo $triple|cut -f2 -d,)
domain=$(echo $triple|cut -f3 -d,)
hosts=""; users=""; doms="";
[ -n "$hostname" ] && hosts="--hosts=$hostname"
[ -n "$username" ] && users="--users=$username"
[ -n "$domain"
] && doms="--nisdomain=$domain"
echo "ipa netgroup-add-member $hosts $users
$doms"
else
netgroup=$triple
echo "ipa netgroup-add $netgroup -desc=NIS_NG_$netgroup"
fi
done
done
As e xplaine d brie fly in Se ction 16.1, “About NIS and Ide ntity Manage me nt”, NIS e ntrie s
e xis t in a s e t of thre e value s , calle d a triple . The triple is host,user,domain, but not e ve ry
compone nt is re quire d; commonly, a triple only de fine s a hos t and domain or us e r and
domain. The way this s cript is writte n, the ipa netgroup-add-member command always
adds a hos t, us e r, and domain triple to the ne tgroup.
if [ $(echo $triple|grep ",.*,"|wc -l) -gt 0 ]; then
hostname=$(echo $triple|cut -f1 -d,)
username=$(echo $triple|cut -f2 -d,)
domain=$(echo $triple|cut -f3 -d,)

233

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

hosts=""; users=""; doms="";
[ -n "$hostname" ] && hosts="--hosts=$hostname"
[ -n "$username" ] && users="--users=$username"
[ -n "$domain"
] && doms="--nisdomain=$domain"
echo "ipa netgroup-add-member $hosts $users $doms"
Any mis s ing e le me nt is adde d as a blank, s o the triple is prope rly migrate d. For e xample ,
for the triple server,,domain the options with the me mbe r add command are -hosts=server --users="" --nisdomain=domain.
This can be run for a give n NIS domain by s pe cifying the NIS domain and NIS s e rve r:
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-hosts.sh nisdomain nis-master.example.com

16.5.3.5. Import ing Aut omount Maps
Automount maps are actually a s e rie s of ne s te d and inte r-re late d e ntrie s that de fine the
location (the pare nt e ntry), and the n as s ociate d ke ys and maps .
While the data are the s ame in the NIS and IdM e ntrie s , the way that data are de fine d is
diffe re nt. The NIS information is e xporte d and the n us e d to cons truct an LDAP e ntry for
the automount location and as s ociate d map; a s cript the n cre ate s an e ntry for e ve ry
configure d ke y for the map.
Unlike the othe r NIS migration s cript e xample s , this s cript take s options to cre ate an
automount location and a map name , along with the migrate d NIS domain and s e rve r.
#!/bin/sh
# 1 is for the automount entry in ipa
ipa automountlocation-add $1
# 2 is the nis domain, 3 is the nis master server, 4 is the map name
ypcat -k -d $2 -h $3 $4 > /dev/shm/nis-map.$4 2>&1
ipa automountmap-add $1 $4
basedn=$(ipa env basedn|tr -d '[:space:]'|cut -f2 -d:)
cat > /tmp/amap.ldif <value mus t be a
canonical hos t name of the hos t for which you want to cre ate the re cord. For more
information, s e e Example 17.6, “PTR Re cord”.

No te
Re ve rs e z one s can als o be configure d for IPv6 addre s s e s , with z one s in
the .ip6.arpa. domain. For more information about IPv6 re ve rs e z one s ,
s e e RFC 3596.
Whe n adding DNS re s ource re cords , note that many of the re cords re quire diffe re nt data.
For e xample , a CNAME re cord re quire s a hos t name , while an A re cord re quire s an IP
addre s s . In the we b UI, the fie lds in the form for adding a ne w re cord are update d
automatically to re fle ct what data is re quire d for the curre ntly s e le cte d type of re cord.

245

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Adding DNS Resource Records f rom t he Web UI
1. Ope n the DNS z one page , as de s cribe d in Se ction 17.5.2, “Editing the Zone
Configuration in the We b UI”.
2. In the DNS Resource Records s e ction, click Add to add a ne w re cord.

Figure 17.9. Adding a New DNS Reso urce Reco rd
3. Se le ct the type of re cord to cre ate and fill out the othe r fie lds as re quire d.

Figure 17.10 . Def ining a New DNS Reso urce Reco rd
4. Click Add to confirm the ne w re cord.

246

⁠C hapt e r 17. Managing DNS

Adding DNS Resource Records f rom t he Command Line
To add a DNS re s ource re cord of any type from the command line , us e the ipa
dnsrecord-add command. The command follows this s yntax:
$ ipa dnsrecord-add zone_name record_name --record_type_option=data
The zone_name is the name of the DNS z one to which the re cord is be ing adde d. The
record_name is an ide ntifie r for the ne w DNS re s ource re cord.
Table 17.2, “Common ipa dnsrecord-add Options ” lis ts options for the mos t common
re s ource re cord type s : A (IPv4), AAAA (IPv6), SRV, and PTR. Lis ts of e ntrie s can be s e t by
us ing the option multiple time s with the s ame command invocation or, in Bas h, by lis ting
the options in a comma-s e parate d lis t ins ide curly brace s , s uch as --option=
{val1,val2,val3}.
For more de taile d information on how to us e ipa dnsrecord-add and which DNS re cord
type s are s upporte d by IdM, run the ipa dnsrecord-add --help command.
T able 17.2. Co mmo n ipa dnsrecord-add Opt io ns
General Reco rd Opt io ns
Opt io n
--ttl=number
--s tructure d

Descript io n
Se ts the time to live for the re cord.
Pars e s the raw DNS re cords and re turns the m in a
s tructure d format.

"A" Reco rd Opt io ns
Opt io n
--a-re c=ARECORD
--a-ip-addre s s =string

Descript io n
Pas s e s a lis t of A re cords .
Give s the IP addre s s for the re cord.

"AAAA" Reco rd Opt io ns
Opt io n
--aaaa-re c=AAAARECORD
--aaaa-ip-addre s s =string

Descript io n
Pas s e s a lis t of AAAA (IPv6) re cords .
Give s the IPv6 addre s s for the re cord.

"PT R" Reco rd Opt io ns
Opt io n
--ptr-re c=PTRRECORD
--ptr-hos tname =string

Descript io n
Pas s e s a lis t of PTR re cords .
Give s the hos tname for the re cord.

"SRV" Reco rd Opt io ns
Opt io n
--s rv-re c=SRVRECORD
--s rv-priority=number

--s rv-we ight=number

Descript io n
Pas s e s a lis t of SRV re cords .
Se ts the priority of the re cord. The re can be multiple
SRV re cords for a s e rvice type . The priority (0 - 65535)
s e ts the rank of the re cord; the lowe r the numbe r, the
highe r the priority. A s e rvice has to us e the re cord with
the highe s t priority firs t.
Se ts the we ight of the re cord. This he lps de te rmine the
orde r of SRV re cords with the s ame priority. The s e t
we ights s hould add up to 100, re pre s e nting the
probability (in pe rce ntage s ) that a particular re cord is
us e d.

247

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

"SRV" Reco rd Opt io ns
--s rv-port=number
--s rv-targe t=string

Give s the port for the s e rvice on the targe t hos t.
Give s the domain name of the targe t hos t. This can be
a s ingle pe riod (.) if the s e rvice is not available in the
domain.

17.5.5. Examples of Adding or Modif ying DNS Resource Records f rom
t he Command Line
Example 17.2. Adding a IPv4 Reco rd
The following e xample cre ate s the re cord www.example.com with the IP addre s s
192.0.2.123.
$ ipa dnsrecord-add example.com www --a-rec 192.0.2.123

Example 17.3. Mo dif ying a IPv4 Reco rd
Whe n cre ating a re cord, the option to s pe cify the A re cord value is --a-record.
Howe ve r, whe n modifying an A re cord, the --a-record option is us e d to s pe cify the
curre nt value for the A re cord. The ne w value is s e t with the --a-ip-address option.
$ ipa dnsrecord-mod example.com www --a-rec 192.0.2.123 --a-ip-address
192.0.2.1

Example 17.4. Adding an IPv6 Reco rd
The following e xample cre ate s the re cord www.example.com with the IP addre s s
2001:db8::1231:5675.
$ ipa dnsrecord-add example.com www --aaaa-rec 2001:db8::1231:5675

Example 17.5. Adding an SRV Reco rd
In the following e xample , _ldap._tcp de fine s the s e rvice type and the conne ction
protocol for the SRV re cord. The --srv-rec option de fine s the priority, we ight, port, and
targe t value s .
For e xample :
[root@server ~]# ipa dnsrecord-add server.example.com _ldap._tcp -srv-rec="0 51 389 server1.example.com."
[root@server ~]# ipa dnsrecord-add server.example.com _ldap._tcp -srv-rec="1 49 389 server2.example.com."
The we ight value s (51 and 49 in this e xample ) add up to 100 and re pre s e nt the
probability (in pe rce ntage s ) that a particular re cord is us e d.

248

⁠C hapt e r 17. Managing DNS

Example 17.6. PT R Reco rd
Whe n adding the re ve rs e DNS re cord, the z one name us e d with the ipa dnsrecordadd command is re ve rs e , compare d to the us age for adding othe r DNS re cords :
$ ipa dnsrecord-add reverseNetworkIpAddress hostIpAddress --ptr-rec
FQDN
Typically, hostIpAddress is the las t octe t of IP addre s s in a give n ne twork.
For e xample , this adds a PTR re cord for server4.example.com with IPv4 addre s s
192.0.2.4:
$ ipa dnsrecord-add 2.0.192.in-addr.arpa 4 --ptr-rec
server4.example.com.

17.5.6. Delet ing Records f rom DNS Zones
Delet ing Records in t he Web UI
To de le te only a s pe cific re cord type from the re s ource re cord:
1. Ope n the DNS z one page , as de s cribe d in Se ction 17.5.2, “Editing the Zone
Configuration in the We b UI”.
2. In the DNS Resource Records s e ction, click the name of the re s ource re cord.

Figure 17.11. Select ing a DNS Reso urce Reco rd
3. Se le ct the che ck box by the name of the re cord type to de le te .

249

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.12. Delet ing a DNS Reso urce Reco rd
Afte r this , only the s e le cte d re cord type is de le te d; the othe r configuration is le ft
intact.
To de le te all re cords for the re s ource in the z one :
1. Ope n the DNS z one page , as de s cribe d in Se ction 17.5.2, “Editing the Zone
Configuration in the We b UI”.
2. In the DNS Resource Records s e ction, s e le ct the che ck box by the name of the
re s ource re cord to de le te , and the n click Delete at the top of the lis t of z one
re cords .

Figure 17.13. Delet ing an Ent ire Reso urce Reco rd
Afte r this , the e ntire re s ource re cord is de le te d.

Delet ing Records f rom t he Command Line

250

⁠C hapt e r 17. Managing DNS

To re move re cords from a z one , us e the ipa dnsrecord-del command and add the -recordType-rec option toge the r with the re cord value .
For e xample , to re move the A type re cord:
$ ipa dnsrecord-del example.com www --a-rec 192.0.2.1
If you run ipa dnsrecord-del without any options , the command prompts for information
about the re cord to de le te . Note that pas s ing the --del-all option with the command
re move s all as s ociate d re cords for the z one .
For de taile d information on how to us e ipa dnsrecord-del and a comple te lis t of options
acce pte d by the command, run the ipa dnsrecord-del --help command.

17.5.7. Disabling and Enabling Zones
IdM allows the adminis trator to dis able and e nable DNS z one s . While de le ting a DNS z one ,
de s cribe d in Se ction 17.5.1, “Re moving Mas te r DNS Zone s ”, comple te ly re move s the z one
e ntry and all the as s ociate d configuration, dis abling the z one re move s it from activity
without pe rmane ntly re moving the z one from IdM. A dis able d z one can als o be e nable d
again.

Disabling and Enabling Zones in t he Web UI
To manage DNS z one s from the We b UI, ope n the Network Services tab, and s e le ct the
DNS s ubtab, followe d by the DNS Zones s e ction.

Figure 17.14. Managing DNS Zo nes
To dis able a z one , s e le ct the che ck box ne xt to the z one name and click Disable.

251

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.15. Disabling a DNS Zo ne
Similarly, to e nable a dis able d z one , s e le ct the che ck box ne xt to the z one name and click
Enable.

Disabling and Enabling DNS Zones f rom t he Command Line
To dis able a DNS z one from the command line , us e the ipa dnszone-disable command.
For e xample :
[user@server ~]$ ipa dnszone-disable zone.example.com
----------------------------------------Disabled DNS zone "example.com"
----------------------------------------To re -e nable a dis able d z one , us e the ipa dnszone-enable command.

17.6. Managing Dynamic DNS Updat es
17.6.1. Enabling Dynamic DNS Updat es
Dynamic DNS update s are dis able d by de fault for ne w DNS z one s in IdM. With dynamic
update s dis able d, the ipa-client-install s cript cannot add a DNS re cord pointing to the
ne w clie nt.

No te
Enabling dynamic update s can pote ntially pos e a s e curity ris k. Howe ve r, if e nabling
dynamic update s is acce ptable in your e nvironme nt, you can do it to make clie nt
ins tallations e as ie r.
Enabling dynamic update s re quire s the following:
The DNS z one mus t be configure d to allow dynamic update s
The local clie nts mus t be configure d to s e nd dynamic update s

17.6.1.1. Conf iguring t he DNS Zone t o Allow Dynamic Updat es

252

⁠C hapt e r 17. Managing DNS

Enabling Dynamic DNS Updat es in t he Web UI
1. Ope n the Network Services tab, and s e le ct the DNS s ubtab, followe d by the DNS
Zones s e ction.

Figure 17.16. DNS Zo ne Management
2. Click on the z one name in the lis t of all z one s to ope n the DNS z one page .

Figure 17.17. Edit ing a Mast er Zo ne
3. Click Settings to s witch to the DNS z one s e ttings tab.

253

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.18. T he Set t ings T ab in t he Mast er Zo ne Edit Page
4. Scroll down to the Dynamic update fie ld, and s e t the value to True.

Figure 17.19. Enabling Dynamic DNS Updat es
5. Click Save at the top of the page to confirm the ne w configuration.

Enabling Dynamic DNS Updat es f rom t he Command Line
To allow dynamic update s to the DNS z one s from the command line , us e the ipa
dnszone-mod command with the --dynamic-update=TRUE option. For e xample :
[user@server ~]$ ipa dnszone-mod server.example.com --dynamicupdate=TRUE

17.6.1.2. Conf iguring t he Client s t o Send Dynamic Updat es
Clie nts are automatically s e t up to s e nd DNS update s whe n the y are e nrolle d in the
domain, by us ing the --enable-dns-updates option with the ipa-client-install s cript.
[root@client ~]# ipa-client-install --enable-dns-updates
The DNS z one has a time -to-live value s e t for re cords within its SOA configuration.
Howe ve r, the time -to-live for the dynamic update s is manage d on the local s ys te m by the
Sys te m Se curity Se rvice Dae mon (SSSD). To change the time -to-live value for the
dynamic update s , e dit the SSSD file to s e t a value ; the de fault is 1200 s e conds .
1. Ope n the SSSD configuration file .
[root@server ~]# vim /etc/sssd/sssd.conf
2. Find the domain s e ction for the IdM domain.
[domain/ipa.example.com]

254

⁠C hapt e r 17. Managing DNS

3. If dynamic update s have not be e n e nable d for the clie nt, the n s e t the
dyndns_update value to true .
dyndns_updates = true
4. Add or e dit the dyndns_ttl parame te r to s e t the value , in s e conds , for the update
time -to-live .
dyndns_ttl = 2400

17.6.2. Synchronizing A/AAAA and PT R Records
A and AAAA re cords are configure d s e parate ly from PTR re cords in re ve rs e z one s .
Be caus e the s e re cords are configure d inde pe nde ntly, it is pos s ible for A/AAAA re cords to
e xis t without corre s ponding PTR re cords , and vice ve rs a.
The re are s ome DNS s e tting re quire me nts for PTR s ynchroniz ation to work:
Both forward and re ve rs e z one s mus t be manage d by the IdM s e rve r.
Both z one s mus t have dynamic update s e nable d.
Enabling dynamic update s is cove re d in Se ction 17.6.1, “Enabling Dynamic DNS
Update s ”.
The PTR re cord will be update d only if the name of the re que s ting clie nt matche s the
name in the PTR re cord.

Impo rtant
Change s made through the IdM we b UI, through the IdM command-line tools , or by
e diting the LDAP e ntry dire ctly do no t update the PTR re cord. Only change s made
by the DNS s e rvice its e lf trigge r PTR re cord s ynchroniz ation.

Warning
A clie nt s ys te m can update its own IP addre s s . This me ans that a compromis e d
clie nt can be us e d to ove rwrite PTR re cords by changing its IP addre s s .

Conf iguring PT R Record Synchronizat ion in t he Web UI
Note that PTR re cord s ynchroniz ation mus t be configure d on the z one whe re A or AAAA
re cords are s tore d, not on the re ve rs e DNS z one whe re PTR re cords are locate d.
1. Ope n the Network Services tab, and s e le ct the DNS s ubtab, followe d by the DNS
Zones s e ction.

255

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.20 . DNS Zo ne Management
2. Click on the z one name in the lis t of all z one s to ope n the DNS z one page .

Figure 17.21. Edit ing a DNS Zo ne
3. Click Settings to s witch to the DNS z one s e ttings tab.

Figure 17.22. T he Set t ings T ab in t he Mast er Zo ne Edit Page
4. Se le ct the Allow PTR sync che ck box.

256

⁠C hapt e r 17. Managing DNS

Figure 17.23. Enabling PT R Synchro nizat io n
5. Click Save at the top of the page to confirm the ne w configuration.

Conf iguring PT R Record Synchronizat ion f rom t he Command Line
Note that PTR re cord s ynchroniz ation mus t be configure d on the z one whe re A or AAAA
re cords are s tore d, not on the re ve rs e DNS z one whe re PTR re cords are locate d.
To configure a DNS z one to allow its forward and re ve rs e e ntrie s to be s ynchroniz e d
automatically, s e t the --allow-sync-ptr option to 1 whe n the z one is cre ate d or whe n it
is e dite d. For e xample , us ing the ipa dnszone-mod command whe n e diting an e xis ting
z one :
[user@server ~]$ ipa dnszone-mod --allow-sync-ptr=1 server.example.com
The de fault --allow-sync-ptr value is 0, which dis able s s ynchroniz ation.

17.6.3. Updat ing DNS Dynamic Updat e Policies
DNS domains maintaine d by IdM s e rve rs can acce pt a DNS dynamic update according to
RFC 3007 ⁠ [4] .
The rule s that de te rmine which re cords can be modifie d by a s pe cific clie nt follow the
s ame s yntax as the update-policy s tate me nt in the /etc/named.conf file . For more
information on dynamic update policie s , s e e the BIND 9 docume ntation.
Note that if dynamic DNS update s are dis able d for the DNS z one , all DNS update s are
de cline d without re fle cting the dynamic update policy s tate me nt. For information on
e nabling dynamic DNS update s , s e e Se ction 17.6.1, “Enabling Dynamic DNS Update s ”.

Updat ing DNS Updat e Policies in t he Web UI
1. Ope n the Network Services tab, and s e le ct the DNS s ubtab, followe d by the DNS
Zones s e ction.

257

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.24. DNS Zo ne Management
2. Click on the z one name in the lis t of all z one s to ope n the DNS z one page .

Figure 17.25. Edit ing a DNS Zo ne
3. Click Settings to s witch to the DNS z one s e ttings tab.

Figure 17.26. T he Set t ings T ab in t he Mast er Zo ne Edit Page
4. Se t the re quire d update policie s in a s e mi-colon s e parate d lis t in the BIND update
policy te xt box.

258

⁠C hapt e r 17. Managing DNS

Figure 17.27. DNS Updat e Po licy Set t ings
5. Click Save at the top of the DNS z one page to confirm the ne w configuration.

Updat ing DNS Updat e Policies f rom t he Command Line
To s e t the DNS update policy from the command line , us e the --update-policy option
and add the acce s s control rule in a s tate me nt afte r the option. For e xample :
$ ipa dnszone-mod --update-policy "grant EXAMPLE.COM krb5-self * A;
grant EXAMPLE.COM krb5-self * AAAA; grant EXAMPLE.COM krb5-self *
SSHFP;"

17.7. Managing DNS Forwarding
DNS forwarding affe cts how DNS que rie s are ans we re d. By de fault, the BIND s e rvice
inte grate d with IdM is configure d to act as both an authoritative and re curs ive DNS s e rve r.
Whe n a DNS clie nt que rie s a name be longing to a DNS z one for which the IdM s e rve r is
authoritative , BIND re plie s with data containe d in the configure d z one . Authoritative data
always take s pre ce de nce ove r any othe r data.
Whe n a DNS clie nt que rie s a name for which the IdM s e rve r is not authoritative , BIND
atte mpts to re s olve the que ry us ing othe r DNS s e rve rs . If no forwarde rs are de fine d,
BIND as ks the root s e rve rs on the Inte rne t and us e s re curs ive re s olution algorithm to
ans we r the DNS que ry.
In s ome cas e s , it is not de s irable to le t BIND contact othe r DNS s e rve rs dire ctly and
pe rform the re curs ion bas e d on data available on the Inte rne t. The s e cas e s include :
Split DNS configuration, als o known as DNS views configuration, whe re DNS s e rve rs
re turn diffe re nt ans we rs to diffe re nt clie nts . Split DNS configuration is typical for
e nvironme nts whe re s ome DNS name s are available ins ide the company ne twork, but
not from the outs ide .
Configurations whe re a fire wall re s tricts acce s s to DNS on the Inte rne t.
Configurations with ce ntraliz e d filte ring or logging on the DNS le ve l.

259

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Configurations with forwarding to a local DNS cache , which he lps optimiz e ne twork
traffic.
In s uch configurations , BIND doe s not us e full re curs ion on the public Inte rne t. Ins te ad, it
us e s anothe r DNS s e rve r, a s o-calle d forwarder, to re s olve the que ry. Whe n BIND is
configure d to us e a forwarde r, que rie s and ans we rs are forwarde d back and forth
be twe e n the IdM s e rve r and the forwarde r, and the IdM s e rve r acts as the DNS cache for
non-authoritative data.

Forward Policies
IdM s upports the first and only s tandard BIND forward policie s , as we ll as the none IdMs pe cific forward policy.
Fo rward f irst (def ault )
DNS que rie s are forwarde d to the configure d forwarde r. If a que ry fails be caus e
of a s e rve r e rror or time out, BIND falls back to the re curs ive re s olution us ing
s e rve rs on the Inte rne t. The forward firs t policy is the de fault policy. It is s uitable
for traffic optimiz ation.
Fo rward o nly
DNS que rie s are forwarde d to the configure d forwarde r. If a que ry fails be caus e
of a s e rve r e rror or time out, BIND re turns an e rror to the clie nt. The forward only
policy is re comme nde d for e nvironme nts with s plit DNS configuration.
No ne: Fo rwarding disabled
DNS que rie s are not forwarde d. Dis abling forwarding is only us e ful as a z one s pe cific ove rride for global forwarding configuration. This options is the IdM
e quivale nt of s pe cifying an e mpty lis t of forwarde rs in BIND configuration.

Forwarding Does Not Combine Dat a f rom IdM and Ot her DNS Servers
Forwarding cannot be us e d to combine data in IdM with data from othe r DNS s e rve rs . The
BIND s e rvice doe s not forward que rie s to anothe r s e rve r if the que rie d DNS name
be longs to a z one for which the IdM s e rve r is authoritative . As a cons e que nce , forwarding
is not us e d whe n the clie nt que rie s a name that doe s not e xis t in an IdM-manage d z one .

Example 17.7. Example Scenario
The IdM s e rve r is authoritative for the test.example. DNS z one . BIND is configure d to
forward que rie s to the DNS s e rve r with the 192.0.2.254 IP addre s s .
Whe n a clie nt s e nds a que ry for the nonexistent.test.example. DNS name , BIND
de te cts that the IdM s e rve r is authoritative for the test.example. z one and doe s not
forward the que ry to the 192.0.2.254. s e rve r. As a re s ult, the DNS clie nt re ce ive s the
NXDomain ans we r, informing the us e r that the que rie d domain doe s not e xis t.

17.7.1. Conf iguring Global Forwarders
Global forwarders are DNS s e rve rs us e d for re s olving all DNS que rie s for which an IdM
s e rve r is not authoritative , as de s cribe d in Se ction 17.7, “Managing DNS Forwarding”.

260

⁠C hapt e r 17. Managing DNS

The adminis trator can configure IP addre s s e s and forward policie s for global forwarding in
the following two ways :
Using t he ipa dnsconfig-mod co mmand o r t he IdM web UI
Configuration s e t us ing the s e native IdM tools is imme diate ly applie d to all IdM
DNS s e rve rs . As e xplaine d in Se ction 17.4, “DNS Configuration Prioritie s ”, global
DNS configuration has highe r priority than local configuration de fine d in the
/etc/named.conf file s .
By edit ing t he /etc/named.conf f ile
Manually e diting the /etc/named.conf on e ve ry IdM DNS s e rve r allows us ing a
diffe re nt global forwarde r and policy on e ach of the s e rve rs . Note that the BIND
s e rvice mus t be re s tarte d afte r changing /etc/named.conf.

Conf iguring Forwarders in t he Web UI
To de fine the DNS global configuration in the IdM we b UI:
1. Click the Network Services tab, and s e le ct the DNS s ubtab, followe d by the DNS
Global Configuration s e ction.
2. To add a ne w global forwarde r, click Add and e nte r the IP addre s s . To de fine a ne w
forward policy, s e le ct it from the lis t of available policie s .

Figure 17.28. Edit ing Glo bal DNS Co nf igurat io n in t he Web UI
3. Click Save to confirm the ne w configuration.

261

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Conf iguring Forwarders f rom t he Command Line
To s e t a global lis t of forwarde rs from the command line , us e the ipa dnsconfig-mod
command. It e dits the DNS global configuration by e diting the LDAP data. The ipa
dnsconfig-mod command and its options affe ct all IdM DNS s e rve rs at once and ove rride
any local configuration.
For e xample , to e dit the lis t of global forwarde rs us ing ipa dnsconfig-mod:
[user@server ~]$ ipa dnsconfig-mod --forwarder=192.0.2.254
Global forwarders: 192.0.2.254

17.7.2. Conf iguring Forward Zones
Forward z one s do not contain any authoritative data and ins truct the name s e rve r to only
forward que rie s for name s be longing into a particular z one to a configure d forwarde r.

Impo rtant
Do not us e forward z one s unle s s abs olute ly re quire d. Limit the ir us e to ove rriding
global forwarding configuration. In mos t cas e s , it is suf f icient t o o nly co nf igure
glo bal f o rwarding, de s cribe d in Se ction 17.7.1, “Configuring Global Forwarde rs ”,
and forward z one s are not ne ce s s ary.
Forward z one s are a non-s tandard s olution, and us ing the m can le ad to une xpe cte d
and proble matic be havior. Whe n cre ating a ne w DNS z one , Re d Hat re comme nds to
always us e s tandard DNS de le gation us ing NS re cords and to avoid forward z one s .

For information on the s upporte d forward policie s , s e e Se ction 17.7, “Forward Policie s ”.
For furthe r information about the BIND s e rvice , s e e the Re d Hat Ente rpris e Linux
Ne tworking Guide , the BIND 9 Adminis trator Re fe re nce Manual include d in the
/usr/share/doc/bind-version_number/ dire ctory, or e xte rnal s ource s ⁠ [5] .

Conf iguring Forward Zones in t he Web UI
To manage forward z one s in the we b UI, click the Network Services tab, and s e le ct the
DNS s ubtab, followe d by the DNS Forward Zones s e ction.

262

⁠C hapt e r 17. Managing DNS

Figure 17.29. Managing DNS Fo rward Zo nes
In the DNS Forward Zones s e ction, the adminis trator can handle all re quire d ope rations
re garding forward z one s : s how curre nt lis t of forward z one s , add a ne w forward z one ,
de le te a forward z one , dis play a forward z one , allow to modify forwarde rs and forward
policy pe r a forward z one , and dis able or e nable a forward z one .

Conf iguring Forward Zones f rom t he Command Line
To manage forward z one s from the command line , us e the ipa dnsforwardzone-*
commands de s cribe d be low.

No te
The ipa dnsforwardzone-* commands be have cons is te ntly with the ipa dnszone* commands us e d to manage mas te r z one s .
The ipa dnsforwardzone-* commands acce pt s e ve ral options ; notably, the --forwarder,
--forward-policy, and --name-from-ip options . For de taile d information about the
available options , s e e Table 17.1, “Zone Attribute s ” or run the commands with the --help
option adde d, for e xample :
ipa dnsforwardzone-add --help
Adding Fo rward Zo nes
Us e the dnsforwardzone-add command to add a ne w forward z one . It is re quire d
to s pe cify at le as t one forwarde r if the forward policy is not s e t to none.
[user@server ~]$ ipa dnsforwardzone-add zone.test. -forwarder=172.16.0.1 --forwarder=172.16.0.2 --forwardpolicy=first
Zone name: zone.test.
Zone forwarders: 172.16.0.1, 172.16.0.2
Forward policy: first
Mo dif ying Fo rward Zo nes
Us e the dnsforwardzone-mod command to modify a forward z one . It is re quire d
to s pe cify at le as t one forwarde r if the forward policy is not none. Modifications
can be pe rforme d in s e ve ral ways .
[user@server ~]$ ipa dnsforwardzone-mod zone.test. -forwarder=172.16.0.3
Zone name: zone.test.
Zone forwarders: 172.16.0.3
Forward policy: first
[user@server ~]$ ipa dnsforwardzone-mod zone.test. --forwardpolicy=only

263

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Zone name: zone.test.
Zone forwarders: 172.16.0.3
Forward policy: only
Sho wing Fo rward Zo nes
Us e the dnsforwardzone-show command to dis play information about a s pe cifie d
forward z one .
[user@server ~]$ ipa dnsforwardzone-show zone.test.
Zone name: zone.test.
Zone forwarders: 172.16.0.5
Forward policy: first
Finding Fo rward Zo nes
Us e the dnsforwardzone-find command to locate a s pe cifie d forward z one .
[user@server ~]$ ipa dnsforwardzone-find zone.test.
Zone name: zone.test.
Zone forwarders: 172.16.0.3
Forward policy: first
---------------------------Number of entries returned 1
---------------------------Delet ing Fo rward Zo nes
Us e the dnsforwardzone-del command to de le te s pe cifie d forward z one s .
[user@server ~]$ ipa dnsforwardzone-del zone.test.
---------------------------Deleted forward DNS zone "zone.test."
---------------------------Enabling and Disabling Fo rward Zo nes
Us e dnsforwardzone-enable and dnsforwardzone-disable commands to
e nable and dis able forward z one s . Note that forward z one s are e nable d by
de fault.
[user@server ~]$ ipa dnsforwardzone-enable zone.test.
---------------------------Enabled forward DNS zone "zone.test."
---------------------------[user@server ~]$ ipa dnsforwardzone-disable zone.test.
---------------------------Disabled forward DNS zone "zone.test."

264

⁠C hapt e r 17. Managing DNS

---------------------------Adding and Remo ving Permissio ns
Us e dnsforwardzone-add-permission and dnsforwardzone-removepermission commands to add or re move s ys te m pe rmis s ions .
[user@server ~]$ ipa dnsforwardzone-add-permission zone.test.
--------------------------------------------------------Added system permission "Manage DNS zone zone.test."
--------------------------------------------------------Manage DNS zone zone.test.
[user@server ~]$ ipa dnsforwardzone-remove-permission zone.test.
--------------------------------------------------------Removed system permission "Manage DNS zone zone.test."
--------------------------------------------------------Manage DNS zone zone.test.

17.8. Managing Reverse DNS Zones
A re ve rs e DNS z one can be ide ntifie d in the following two ways :
By the z one name , in the format reverse_ipv4_address.in-addr.arpa or
reverse_ipv6_address.ip6.arpa.
The re ve rs e IP addre s s is cre ate d by re ve rs ing the orde r of the compone nts of the IP
addre s s . For e xample , if the IPv4 ne twork is 192.0.2.0/24, the re ve rs e z one name is
2.0.192.in-addr.arpa. (with the trailing pe riod).
By the ne twork addre s s , in the format network_ip_address/subnet_mask_bit_count
To cre ate the re ve rs e z one by its IP ne twork, s e t the ne twork information to the
(forward-s tyle ) IP addre s s , with the s ubne t mas k bit count. The bit count mus t be a
multiple of e ight for IPv4 addre s s e s or a multiple of four for IPv6 addre s s e s .

Adding a Reverse DNS Zone in t he Web UI
1. Ope n the Network Services tab, and s e le ct the DNS s ubtab, followe d by the DNS
Zones s e ction.

265

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 17.30 . DNS Zo ne Management
2. Click Add at the top of the lis t of all z one s .

Figure 17.31. Adding a Reverse DNS Zo ne
3. Fill in the z one name or the re ve rs e z one IP ne twork.
a. For e xample , to add a re ve rs e DNS z one by the z one name :

Figure 17.32. Creat ing a Reverse Zo ne by Name
b. Alte rnative ly, to add a re ve rs e DNS z one by the re ve rs e z one IP ne twork:

266

⁠C hapt e r 17. Managing DNS

Figure 17.33. Creat ing a Reverse Zo ne by IP Net wo rk
The validator for the Reverse zone IP network fie ld warns you about an
invalid ne twork addre s s during typing. The warning will dis appe ar once you
e nte r the full ne twork addre s s .
4. Click Add to confirm the ne w re ve rs e z one .

Adding a Reverse DNS Zone f rom t he Command Line
To cre ate a re ve rs e DNS z one from the command line , us e the ipa dnszone-add
command.
For e xample , to cre ate the re ve rs e z one by the z one name :
[user@server]$ ipa dnszone-add 2.0.192.in-addr.arpa.
Alte rnative ly, to cre ate the re ve rs e z one by the IP ne twork:
[user@server ~]$ ipa dnszone-add --name-from-ip=192.0.2.0/24

Ot her Management Operat ions f or Reverse DNS Zones
Se ction 17.5, “Managing Mas te r DNS Zone s ” de s cribe s othe r z one manage me nt
ope rations , s ome of which are als o applicable to re ve rs e DNS z one manage me nt, s uch as
e diting or dis abling and e nabling DNS z one s .

17.9. Defining DNS Query Policy
To re s olve hos t name s within the DNS domain, a DNS clie nt is s ue s a que ry to the DNS
name s e rve r. For s ome s e curity conte xts or for pe rformance , it might be advis able to
re s trict what clie nts can que ry DNS re cords in the z one .
DNS que rie s can be configure d whe n the z one is cre ate d or whe n it is modifie d by us ing
the --allow-query option with the ipa dnszone-mod command to s e t a lis t of clie nts
which are allowe d to is s ue que rie s .

267

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

For e xample :
[user@server ~]$ ipa dnszone-mod --allowquery=192.0.2.0/24;2001:DB8::/32;203.0.113.1 example.com
The de fault --allow-query value is any, which allows the z one to be que rie d by any
clie nt.

[3] For m ore inform ation about GSS-TSIG, see RFC 3545.
[4] For the full text of RFC 3007, see http://tools.ietf.org/htm l/rfc3007
[5] For m ore inform ation, refer to the BIND 9 C onfiguration Reference.

268

⁠C hapt e r 17. Managing DNS

⁠P art IV. Defining Domain-wide Syst em Policies

269

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 18. Using Aut omount
Automount is a way to manage , organiz e , and acce s s dire ctorie s acros s multiple s ys te ms .
Automount automatically mounts a dire ctory whe ne ve r acce s s to it is re que s te d. This
works e xce ptionally we ll within an IdM domain s ince it allows dire ctorie s on clie nts within
the domain to be s hare d e as ily. This is e s pe cially important with us e r home dire ctorie s ,
s e e Se ction 9.1, “Se tting up Us e r Home Dire ctorie s ”.
In IdM, automount works with the inte rnal LDAP dire ctory and als o with DNS s e rvice s if
configure d.

18.1. About Aut omount and IdM
Automount provide s a cohe re nt s tructure to the way that dire ctorie s are organiz e d. Eve ry
dire ctory is calle d a mount point or a key. Multiple ke ys that are groupe d toge the r cre ate a
map, and maps are as s ociate d according to the ir phys ical or conce ptual location.
The bas e configuration file for automount is the auto.master file in the /etc/ dire ctory. If
ne ce s s ary, the re can be multiple auto.master configuration file s in s e parate s e rve r
locations .
Whe n the autofs utility is configure d on a s e rve r and the s e rve r is a clie nt in an IdM
domain, the n all configuration information for automount is s tore d in the IdM dire ctory.
Rathe r than in s e parate te xt file s , the autofs configuration containing maps , locations , and
ke ys are s tore d as LDAP e ntrie s . For e xample , the de fault map file , auto.master, is
s tore d as :
dn:
automountmapname=auto.master,cn=default,cn=automount,dc=example,dc=com
objectClass: automountMap
objectClass: top
automountMapName: auto.master

Impo rtant
Ide ntity Manage me nt works with an e xis ting autofs de ployme nt but doe s not s e t up
or configure autofs its e lf.
Each ne w location is adde d as a containe r e ntry unde r
cn=automount,dc=example,dc=com, and e ach map and e ach ke y are s tore d be ne ath that
location.
As with othe r IdM domain s e rvice s , automount works with IdM native ly. The automount
configuration can be manage d by IdM tools :
The ipa automountlocation* commands for Locations,
The ipa automountmap* commands for dire ct and indire ct maps,
The ipa automountkey* commands for keys.

270

⁠C hapt e r 18 . Us ing Aut o mo unt

For automount to work within the IdM domain, the NFS s e rve r mus t be configure d as an IdM
clie nt. Configuring NFS its e lf is cove re d in the Re d Hat Ente rpris e Linux Storage
Adminis tration Guide .

18.2. Configuring Aut omount
in Ide ntity Manage me nt, configuring automount e ntrie s like locations and maps re quire s an
e xis ting autofs /NFS s e rve r. Cre ating automount e ntrie s doe s not cre ate the unde rlying
autofs configuration. Autofs can be configure d manually us ing LDAP or SSSD as a data
s tore , or it can be configure d automatically.

No te
Be fore changing the automount configuration, te s t that for at le as t one us e r, the ir
/home/ dire ctory can be mounte d from the command line s ucce s s fully. Making s ure
that NFS is working prope rly make s it e as ie r to trouble s hoot any pote ntial IdM
automount configuration e rrors late r.

18.2.1. Conf iguring NFS Aut omat ically
Afte r a s ys te m is configure d as an IdM clie nt, which include s IdM s e rve rs and re plicas that
are configure d as domain clie nts as part of the ir configuration, autofs can be configure d
to us e the IdM domain as its NFS domain and have autofs s e rvice s e nable d.
By de fault, the ipa-client-automount utility automatically configure s the NFS
configuration file s , /etc/sysconfig/nfs and /etc/idmapd.conf. It als o configure s SSSD
to manage the cre de ntials for NFS. If the ipa-client-automount command is run without
any options , it runs a DNS dis cove ry s can to ide ntify an available IdM s e rve r and cre ate s a
de fault location calle d default.
[root@ipa-server ~]# ipa-client-automount
Searching for IPA server...
IPA server: DNS discovery
Location: default
Continue to configure the system with these values? [no]: yes
Configured /etc/nsswitch.conf
Configured /etc/sysconfig/nfs
Configured /etc/idmapd.conf
Started rpcidmapd
Started rpcgssd
Restarting sssd, waiting for it to become available.
Started autofs
It is pos s ible to s pe cify an IdM s e rve r to us e and to cre ate an automount location othe r
than de fault:
[root@server ~]# ipa-client-automount --server=ipaserver.example.com -location=boston
Along with s e tting up NFS, the ipa-client-automount utility configure s SSSD to cache
automount maps , in cas e the e xte rnal IdM s tore is e ve r inacce s s ible . Configuring SSSD
doe s two things :

271

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

It adds s e rvice configuration information to the SSSD configuration. The IdM domain
e ntry is give n s e ttings for the autofs provide r and the mount location.
autofs_provider = ipa
ipa_automount_location = default
And NFS is adde d to the lis t of s upporte d s e rvice s (services = nss,pam,autofs...)
and give n a blank configuration e ntry ([autofs]).
The Name Se rvice Switch (NSS) s e rvice information is update d to che ck SSSD firs t for
automount information, and the n the local file s .
automount: sss files
The re may be s ome ins tance s , s uch as highly s e cure e nvironme nts , whe re it is not
appropriate for a clie nt to cache automount maps . In that cas e , the ipa-clientautomount command can be run with the --no-sssd option, which change s all of the
re quire d NFS configuration file s , but doe s not change the SSSD configuration.
[root@server ~]# ipa-client-automount --no-sssd
If --no-sssd is us e d, the lis t of configuration file s update d by ipa-client-automount is
diffe re nt:
The command update s /etc/sysconfig/autofs ins te ad of /etc/sysconfig/nfs.
The command configure s /etc/autofs_ldap_auth.conf with the IdM LDAP
configuration.
The command configure s /etc/nsswitch.conf to us e the LDAP s e rvice s for
automount maps .

No te
The ipa-client-automount command can only be run once . If the re is an e rror in
the configuration, than the configuration file s ne e d to be e dite d manually.

18.2.2. Conf iguring aut of s Manually t o Use SSSD and
Ident it y Management
1. Edit the /etc/sysconfig/autofs file to s pe cify the s che ma attribute s that autofs
s e arche s for:
#
# Other common LDAP naming
#
MAP_OBJECT_CLASS="automountMap"
ENTRY_OBJECT_CLASS="automount"
MAP_ATTRIBUTE="automountMapName"
ENTRY_ATTRIBUTE="automountKey"
VALUE_ATTRIBUTE="automountInformation"
2. Spe cify the LDAP configuration. The re are two ways to do this . The s imple s t is to le t

272

⁠C hapt e r 18 . Us ing Aut o mo unt

the automount s e rvice dis cove r the LDAP s e rve r and locations on its own:
LDAP_URI="ldap:///dc=example,dc=com"
Alte rnative ly, e xplicitly s e t which LDAP s e rve r to us e and the bas e DN for LDAP
s e arche s :
LDAP_URI="ldap://ipa.example.com"
SEARCH_BASE="cn=location,cn=automount,dc=example,dc=com"

No te
The de fault value for location is default. If additional locations are adde d
(Se ction 18.4, “Configuring Locations ”), the n the clie nt can be pointe d to us e
thos e locations , ins te ad.
3. Edit the /etc/autofs_ldap_auth.conf file s o that autofs allows clie nt
authe ntication with the IdM LDAP s e rve r.
Change authrequired to ye s .
Se t the principal to the Ke rbe ros hos t principal for the NFS clie nt s e rve r,
host/fqdn@REALM. The principal name is us e d to conne ct to the IdM dire ctory as
part of GSS clie nt authe ntication.

If ne ce s s ary, run klist -k to ge t the e xact hos t principal information.
4. Configure autofs as one of the s e rvice s which SSSD manage s .
a. Ope n the SSSD configuration file .
[root@server ~]# vim /etc/sssd/sssd.conf
b. Add the autofs s e rvice to the lis t of s e rvice s handle d by SSSD.
[sssd]
services = nss,pam,autofs
c. Cre ate a ne w [autofs] s e ction. This can be le ft blank; the de fault s e ttings
for an autofs s e rvice work with mos t infras tructure s .
[nss]
[pam]

273

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[sudo]
[autofs]
[ssh]
[pac]
d. Optionally, s e t a s e arch bas e for the autofs e ntrie s . By de fault, this is the
LDAP s e arch bas e , but a s ubtre e can be s pe cifie d in the
ldap_autofs_search_base parame te r.
[domain/EXAMPLE]
...
ldap_search_base = "dc=example,dc=com"
ldap_autofs_search_base = "ou=automount,dc=example,dc=com"
5. Re s tart SSSD:
[root@server ~]# systemctl restart sssd.service
6. Che ck the /etc/nsswitch.conf file , s o that SSSD is lis te d as a s ource for
automount configuration:
automount: sss files
7. Re s tart autofs :
[root@server ~]# systemctl restart autofs.service
8. Te s t the configuration by lis ting a us e r's /home dire ctory:
[root@server ~]# ls /home/userName
If this doe s not mount the re mote file s ys te m, che ck the /var/log/messages file
for e rrors . If ne ce s s ary, incre as e the de bug le ve l in the /etc/sysconfig/autofs
file by s e tting the LOGGING parame te r to debug.

No te
If the re are proble ms with automount, the n cros s -re fe re nce the automount atte mpts
with the 389 Dire ctory Se rve r acce s s logs for the IdM ins tance , which will s how the
atte mpte d acce s s , us e r, and s e arch bas e .
It is als o s imple to run automount in the fore ground with de bug logging on.
automount -f -d
This prints the de bug log information dire ctly, without having to cros s -che ck the LDAP
acce s s log with automount's log.

274

⁠C hapt e r 18 . Us ing Aut o mo unt

18.2.3. Conf iguring Aut omount on Solaris

No te
Solaris us e s a diffe re nt s che ma for autofs configuration than the s che ma us e d by
Ide ntity Manage me nt. Ide ntity Manage me nt us e s the 2307bis -s tyle automount
s che ma which is de fine d for 389 Dire ctory Se rve r (and us e d in IdM's inte rnal
Dire ctory Se rve r ins tance ).
1. If the NFS s e rve r is running on Re d Hat Ente rpris e Linux, s pe cify on the Solaris
machine that NFSv3 is the maximum s upporte d ve rs ion. Edit the /etc/default/nfs
file and s e t the following parame te r:
NFS_CLIENT_VERSMAX=3
2. Us e the ldapclient command to configure the hos t to us e 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=co
m
-a
serviceSearchDescriptor=auto_master:automountMapName=auto.master,c
n=location,cn=automount,dc=example,dc=com?one
-a
serviceSearchDescriptor=auto_home:automountMapName=auto_home,cn=lo
cation,cn=automount,dc=example,dc=com?one
-a objectClassMap=shadow:shadowAccount=posixAccount
-a searchTimelimit=15
-a bindTimeLimit=5
3. Enable automount:
# svcadm enable svc:/system/filesystem/autofs
4. Te s t the configuration.
a. Che ck the LDAP configuration:
# ldapclient -l auto_master
dn:
automountkey=/home,automountmapname=auto.master,cn=location,c
n=automount,dc=example,dc=com
objectClass: automount
objectClass: top
automountKey: /home
automountInformation: auto.home

275

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

b. Lis t a us e r's /home dire ctory:
# ls /home/userName

18.3. Set t ing up a Kerberized NFS Server
Ide ntity Manage me nt can be us e d to s e t up a Ke rbe riz e d NFS s e rve r.

No te
The NFS s e rve r doe s not ne e d to be running on Re d Hat Ente rpris e Linux.

18.3.1. Set t ing up a Kerberized NFS Server
1. Obtain a Ke rbe ros ticke t be fore running IdM tools .
[jsmith@server ~]$ kinit admin
2. If the NFS hos t machine has not be e n adde d as a clie nt to the IdM domain, the n
cre ate the hos t e ntry. Se e Se ction 5.4.2, “Othe r Example s of Adding a Hos t Entry”.
3. Cre ate the NFS s e rvice e ntry in the IdM domain. For e xample :
[jsmith@server ~]$ ipa service-add nfs/nfs-server.example.com
For more information, s e e Se ction 14.1, “Adding and Editing Se rvice Entrie s and
Ke ytabs ”.
4. Ge ne rate an NFS s e rvice ke ytab for the NFS s e rve r us ing the ipa-getkeytab
command, and s ave the ke ys dire ctly to the hos t ke ytab. For e xample :
[jsmith@server ~]$ ipa-getkeytab -s ipaserver.example.com -p
nfs/nfs-server.example.com -k /etc/krb5.keytab

No te
Ve rify that the NFS s e rvice has be e n prope rly configure d in IdM, with its
ke ytab, by che cking the s e rvice e ntry:
[jsmith@server ~]$ ipa service-show
nfs/ipaclient2.example.com
Principal: NFS/ipaclient2.example.com@EXAMPLE.COM
Keytab: True

276

⁠C hapt e r 18 . Us ing Aut o mo unt

No te
This proce dure as s ume s that the NFS s e rve r is running on a Re d Hat
Ente rpris e Linux s ys te m or a UNIX s ys te m which can run ipa-getkeytab.
If the NFS s e rve r is running on a s ys te m which cannot run ipa-getkeytab,
the n cre ate the ke ytab us ing s ys te m tools . Two things mus t be done :
The ke y mus t be cre ate d in the /root (or e quivale nt) dire ctory.
The ktutil command can me rge the ke ys into the s ys te m
/etc/krb5.keytab file . The ktutil man page de s cribe s how to us e the tool.
5. Ins tall the NFS package s . For e xample :
[root@nfs-server ~]# yum install nfs-utils
6. Configure we ak crypto s upport. This is re quire d for e ve ry NFS clie nt if any clie nt
(s uch as a Re d Hat Ente rpris e Linux 5 clie nt) in the domain will us e olde r e ncryption
options like DES.
a. Edit the krb5.conf file to allow we ak crypto.
[root@nfs-server ~]# vim /etc/krb5.conf
allow_weak_crypto = true
b. Update the IdM s e rve r Ke rbe ros configuration to s upport the DES e ncryption
type .
[jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager"
-w password -h ipaserver.example.com -p 389
dn: cn=EXAMPLEREALM,cn=kerberos,dc=example,dc=com
changetype: modify
add: krbSupportedEncSaltTypes
krbSupportedEncSaltTypes: des-cbc-crc:normal
add: krbSupportedEncSaltTypes
krbSupportedEncSaltTypes: des-cbc-crc:special
add: krbDefaultEncSaltTypes
krbDefaultEncSaltTypes: des-cbc-crc:special
7. Run the ipa-client-automount command to configure the NFS s e ttings .
By de fault, this e nable s s e cure NFS in the /etc/sysconfig/nfs file and s e ts the
IdM DNS domain in the Domain parame te r in the /etc/idmapd.conf file .
8. Edit the /etc/exports file and add the Ke rbe ros information:
/export

*(rw,sec=sys:krb5:krb5i:krb5p)

9. Re s tart the NFS s e rve r and re late d s e rvice s .

277

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@nfs-server
[root@nfs-server
[root@nfs-server
[root@nfs-server

~]#
~]#
~]#
~]#

systemctl
systemctl
systemctl
systemctl

restart
restart
restart
restart

nfs.service
nfs-server.service
nfs-secure.service
nfs-secure-server.service

10. Configure the NFS s e rve r as an NFS clie nt, following the dire ctions in Se ction 18.3.2,
“Se tting up a Ke rbe riz e d NFS Clie nt”.

18.3.2. Set t ing up a Kerberized NFS Client
1. Obtain a Ke rbe ros ticke t be fore running IdM tools .
[jsmith@server ~]$ kinit admin
2. If the NFS clie nt is not e nrolle d as a clie nt in the IdM domain, the n s e t up the
re quire d hos t e ntrie s , as de s cribe d in Se ction 5.4.2, “Othe r Example s of Adding a
Hos t Entry”.
3. Run the ipa-client-automount command to configure the NFS s e ttings .
By de fault, this e nable s s e cure NFS in the /etc/sysconfig/nfs file and s e ts the
IdM DNS domain in the Domain parame te r in the /etc/idmapd.conf file .
4. Start the GSS dae mon.
[root@nfs-client-server ~]# systemctl start rpc-gssd.service
[root@nfs-client-server ~]# systemctl start rpcbind.service
[root@nfs-client-server ~]# systemctl start nfs-idmapd.service
5. Mount the dire ctory.
[root@nfs-client-server ~]# echo "$NFSSERVER:/this /mnt/this nfs4
sec=krb5i,rw,proto=tcp,port=2049" >>/etc/fstab
[root@nfs-client-server ~]# mount -av
6. Configure SSSD on the clie nt s ys te m to manage home dire ctorie s and re ne w
Ke rbe ros ticke ts .
a. Enable SSSD with the --enablemkhomedir option.
[root@nfs-client-server ~]# authconfig --update --enablesssd
--enablesssdauth --enablemkhomedir
b. Re s tart the Ope nSSH clie nt.
[root@nfs-client-server ~]# systemctl start sssh.service
c. Edit the IdM domain s e ction in the SSSD configuration file to s e t the ke ytab
re ne wal options .
[root@nfs-client-server ~]# vim /etc/sssd/sssd.conf
[domain/EXAMPLE.COM]
cache_credentials = True

278

⁠C hapt e r 18 . Us ing Aut o mo unt

krb5_store_password_if_offline = True
ipa_domain = example.com
id_provider = ipa
auth_provider = ipa
...
krb5_renewable_lifetime = 50d
krb5_renew_interval = 3600
d. Re s tart SSSD.
[root@nfs-client-server ~]# systemctl restart sssd.service

18.4. Configuring Locat ions
A location is a s e t of maps , which are all s tore d in auto.master, and a location can s tore
multiple maps . The location e ntry only works as a containe r for map e ntrie s ; it is not an
automount configuration in and of its e lf.

Impo rtant
Ide ntity Manage me nt doe s not s e t up or configure autofs . That mus t be done
s e parate ly. Ide ntity Manage me nt works with an e xis ting autofs de ployme nt.

18.4.1. Conf iguring Locat ions t hrough t he Web UI
1. Click the Policy tab.
2. Click the Automount s ubtab.
3. Click the Add link at the top of the lis t of automount locations .

279

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

4. Ente r the name for the ne w location.

5. Click the Add and Edit button to go to the map configuration for the ne w location.
Cre ate maps , as de s cribe d in Se ction 18.5.1.1, “Configuring Dire ct Maps from the
We b UI” and Se ction 18.5.2.1, “Configuring Indire ct Maps from the We b UI”.

18.4.2. Conf iguring Locat ions t hrough t he Command Line
To cre ate a map, us ing the automountlocation-add and give the location name .
$ ipa automountlocation-add location
For e xample :
$ ipa automountlocation-add raleigh
---------------------------------Added automount location "raleigh"

280

⁠C hapt e r 18 . Us ing Aut o mo unt

---------------------------------Location: raleigh
Whe n a ne w location is cre ate d, two maps are automatically cre ate d for it, auto.master
and auto.direct. auto.master is the root map for all automount maps for the location.
auto.direct is the de fault map for dire ct mounts and is mounte d on /-.
To vie w all of the maps configure d for a location as if the y we re de ploye d on a file s ys te m,
us e the automountlocation-tofiles command:
$ ipa automountlocation-tofiles raleigh
/etc/auto.master:
//etc/auto.direct
--------------------------/etc/auto.direct:

18.5. Configuring Maps
Configuring maps not only cre ate s the maps , it as s ociate s mount points through the ke ys
and it as s igns mount options that s hould be us e d whe n the dire ctory is acce s s e d. IdM
s upports both dire ct and indire ct maps .

No te
Diffe re nt clie nts can us e diffe re nt map s e ts . Map s e ts us e a tre e s tructure , s o
maps cannot be s hare d be twe e n locations .

Impo rtant
Ide ntity Manage me nt doe s not s e t up or configure autofs . That mus t be done
s e parate ly. Ide ntity Manage me nt works with an e xis ting autofs de ployme nt.

18.5.1. Conf iguring Direct Maps
Dire ct maps de fine e xact locations , me aning abs olute paths , to the file mount point. In the
location e ntry, a dire ct map is ide ntifie d by the pre ce ding forward s las h:
--------------------------/etc/auto.direct:
/shared/man server.example.com:/shared/man

18.5.1.1. Conf iguring Direct Maps f rom t he Web UI
1. Click the Policy tab.
2. Click the Automount s ubtab.
3. Click name of the automount location to which to add the map.

281

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

4. In the Automount Maps tab, click the + Add link to cre ate a ne w map.

5. In pop-up window, s e le ct the Direct radio button and e nte r the name of the ne w
map.

282

⁠C hapt e r 18 . Us ing Aut o mo unt

6. In the Automount Keys tab, click the + Add link to cre ate a ne w ke y for the map.

7. Ente r the mount point. The ke y de fine s the actual mount point in the ke y name . The
Info fie ld s e ts the ne twork location of the dire ctory, as we ll as any mount options
to us e .

8. Click the Add button to s ave the ne w ke y.

283

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

8. Click the Add button to s ave the ne w ke y.

18.5.1.2. Conf iguring Direct Maps f rom t he Command Line
The ke y de fine s the actual mount point (in the ke y name ) and any options . A map is a
dire ct or indire ct map bas e d on the format of its ke y.
Each location is cre ate d with an auto.direct ite m. The s imple s t configuration is to de fine
a dire ct mapping by adding an automount ke y to the e xis ting dire ct map e ntry. It is als o
pos s ible to cre ate diffe re nt dire ct map e ntrie s .
Add the ke y for the dire ct map to the location's auto.direct file . The --key option
ide ntifie s the mount point, and --info give s the ne twork location of the dire ctory, as we ll
as any mount options to us e . For e xample :
$ ipa automountkey-add raleigh auto.direct --key=/share -info="ro,soft,ipaserver.example.com:/home/share"
Key: /share
Mount information: ro,soft,ipaserver.example.com:/home/share
Mount options are de s cribe d in the mount manpage , http://linux.die .ne t/man/8/mount.
On Solaris , add the dire ct map and ke y us ing the ldapclient command to add the LDAP
e ntry dire ctly:
ldapclient -a
serviceSearchDescriptor=auto_direct:automountMapName=auto.direct,cn=loca
tion,cn=automount,dc=example,dc=com?one

18.5.2. Conf iguring Indirect Maps
An indire ct map e s s e ntially s pe cifie s a re lative path for maps . A pare nt e ntry s e ts the
bas e dire ctory for all of the indire ct maps . The indire ct map ke y s e ts a s ub dire ctory;
whe ne ve r the indire ct map location is loade d, the ke y is appe nde d to that bas e dire ctory.
For e xample , if the bas e dire ctory is /docs and the ke y is man, the n the map is
/docs/man.

18.5.2.1. Conf iguring Indirect Maps f rom t he Web UI
1. Click the Policy tab.
2. Click the Automount s ubtab.
3. Click name of the automount location to which to add the map.

284

⁠C hapt e r 18 . Us ing Aut o mo unt

4. In the Automount Maps tab, click the + Add link to cre ate a ne w map.

5. In pop-up window, s e le ct the Indirect radio button and e nte r the re quire d
information for the indire ct map:

285

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The name of the ne w map
The mount point. The Mount fie ld s e ts the bas e dire ctory to us e for all the
indire ct map ke ys .
Optionally, a pare nt map. The de fault pare nt is auto.master, but if anothe r map
e xis ts which s hould be us e d, that can be s pe cifie d in the Parent Map fie ld.
6. Click the Add button to s ave the ne w ke y.

18.5.2.2. Conf iguring Indirect Maps f rom t he Command Line
The primary diffe re nce be twe e n a dire ct map and an indire ct map is that the re is no
forward s las h in front of an indire ct ke y.
--------------------------/etc/auto.share:
man
ipa.example.com:/docs/man
--------------------------1. Cre ate an indire ct map to s e t the bas e e ntry us ing the automountmap-addindirect command. The --mount option s e ts the bas e dire ctory to us e for all the
indire ct map ke ys . The de fault pare nt e ntry is auto.master, but if anothe r map
e xis ts which s hould be us e d, that can be s pe cifie d us ing the --parentmap option.
$ ipa automountmap-add-indirect location mapName --mount=directory
[--parentmap=mapName]
For e xample :
$ ipa automountmap-add-indirect raleigh auto.share --mount=/share
-------------------------------Added automount map "auto.share"
--------------------------------

286

⁠C hapt e r 18 . Us ing Aut o mo unt

2. Add the indire ct ke y for the mount location:
$ ipa automountkey-add raleigh auto.share --key=docs -info="ipa.example.com:/export/docs"
------------------------Added automount key "docs"
------------------------Key: docs
Mount information: ipa.example.com:/export/docs
3. To ve rify the configuration, che ck the location file lis t us ing automountlocationtofiles:
$ ipa automountlocation-tofiles raleigh
/etc/auto.master:
//etc/auto.direct
/share /etc/auto.share
--------------------------/etc/auto.direct:
--------------------------/etc/auto.share:
man
ipa.example.com:/export/docs
On Solaris , add the indire ct map us ing the ldapclient command to add the LDAP e ntry
dire ctly:
ldapclient -a
serviceSearchDescriptor=auto_share:automountMapName=auto.share,cn=locati
on,cn=automount,dc=example,dc=com?one

18.5.3. Import ing Aut omount Maps
If the re are e xis ting automount maps , the s e can be importe d into the IdM automount
configuration.
ipa automountlocation-import location map_file [--continuous]
The only re quire d information is the IdM automount location and the full path and name of
the map file . The --continuous option te lls the automountlocation-import command to
continue through the map file , e ve n if the command e ncounte rs e rrors .
For e xample :
$ ipa automountlocation-import raleigh /etc/custom.map

287

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 19. Defining Password Policies
All us e rs mus t have a pas s word which the y us e to authe nticate to the Ke rbe ros domain.
Ide ntity Manage me nt de fine s and e nforce s rule s about pas s word comple xity, pas s word
his torie s , and account lockouts in orde r to maintain s e curity.

No te
IdM, by de fault, doe s not e xpos e pas s words to clie nts , e ve n has he d pas s words , for
s ys te m s e curity.

19.1. About Password Policies and Policy At t ribut es
A password policy s e ts ce rtain s tandards for pas s words , s uch as the pas s word comple xity
and the rule s for changing pas s words . A pas s word policy minimiz e s the inhe re nt ris k of
us ing pas s words by e ns uring that the y me e t ade quate comple xity s tandards to thwart
brute force attacks and the y are change d fre que ntly e nough to mitigate the ris k of
s ome one re ve aling or dis cove ring a pas s word.
The re are thre e main configuration are as that are de fine d within the pas s word policy:
Stre ngth or comple xity re quire me nts
His tory
Account lockout
The IdM pas s word policy is e nforce d jointly by the KDC and the LDAP s e rve r. While the
pas s word policy is s e t in the LDAP dire ctory and is bas e d on 389 Dire ctory Se rve r
pas s word policy attribute s , the policy is ultimate ly cons traine d by the KDC pas s word policy
frame work. The KDC policy is le s s fle xible than the 389 Dire ctory Se rve r policy
frame work, s o the IdM pas s word policy can only imple me nt pas s word policy e le me nts
s upporte d in the KDC. Any othe r policy s e ttings made within the 389 Dire ctory Se rve r are
not vis ible or e nforce d in Ide ntity Manage me nt.
Pas s word policie s are as s igne d e ithe r globally or to groups in IdM, not to individual us e rs .
The pas s word policy is as s igne d a priority, s o that if a us e r be longs to multiple groups
with diffe re nt pas s word policie s , the policy with the highe s t priority will take pre ce de nce .
The diffe re nt policy attribute s that can be s e t are lis te d in Table 19.1, “Pas s word Policy
Se ttings ”.
T able 19.1. Passwo rd Po licy Set t ings
Co nf igurat io n Pro pert y

Co mmand-Line Opt io n

Opt io ns f o r bo t h t he UI and CLI

288

Descript io n

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

Co nf igurat io n Pro pert y

Co mmand-Line Opt io n

Descript io n

Minimum Pas s word Life time

--minlife

Maximum Pas s word
Life time

--maxlife

Minimum Numbe r of
Characte r Clas s e s

--minclas s e s

Se ts the minimum pe riod of
time , in hours , that a us e r's
pas s word mus t be in e ffe ct
be fore the us e r can change
it. This can pre ve nt a us e r
from changing a pas s word
and the n imme diate ly
changing it to the original
value . The de fault value is
one hour.
Se ts the maximum pe riod of
time , in days , that a us e r's
pas s word can be in e ffe ct
be fore it mus t be change d.
The de fault value is 90
days .
Se ts the minimum numbe r
of diffe re nt clas s e s , or
type s , of characte r that
mus t e xis t in a pas s word
be fore it is cons ide re d valid.
For e xample , s e tting this
value to 3 re quire s that any
pas s word mus t have
characte rs from at le as t
thre e cate gorie s in orde r to
be approve d. The de fault
value is z e ro (0), me aning
the re are no re quire d
clas s e s . The re are s ix
characte r clas s e s :
Uppe r-cas e characte rs
Lowe r-cas e characte rs
Digits
Spe cial characte rs (for
e xample , punctuation)
8-bit characte rs
(characte rs whos e
de cimal code s tarts at
128 or be low)
Numbe r of re pe ate d
characte rs
This we ights in the
oppos ite dire ction, s o
that too many re pe ate d
characte rs doe s me e t
the quorum to s atis fy the
"le ve l" e xpre s s e d by
krbPwdMinDiffChars .

289

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Co nf igurat io n Pro pert y

Co mmand-Line Opt io n

Descript io n

Minimum Le ngth of
Pas s word

--minle ngth

Pas s word His tory

--his tory

Se ts the minimum numbe r
of characte rs for a
pas s word. The de fault value
is e ight characte rs .
Se ts the numbe r of
pre vious pas s words that
are s tore d and which a us e r
is pre ve nte d from us ing. For
e xample , if this is s e t to
te n, IdM pre ve nts a us e r
from re us ing any of the ir
pre vious te n pas s words .
The de fault value is z e ro
(0), which dis able s
pas s word his tory.

No te
Eve n with the
pas s word his tory s e t
to z e ro, us e rs cannot
re us e a current
pas s word.

Opt io ns f o r t he CLI o nly
Priority

--priority

Maximum Cons e cutive
Failure s

--maxfail

Fail Inte rval

--failinte rval

Lockout Time

--lockouttime

19.2. Viewing Password Policies
290

Se ts the priority which
de te rmine s which policy is
in e ffe ct. The lowe r the
numbe r, the highe r priority.
Although this priority is
re quire d whe n the policy is
firs t cre ate d in the UI, it
cannot be re s e t in the UI. It
can only be re s e t us ing the
CLI.
Spe cifie s the maximum
numbe r of cons e cutive
failure s to input the corre ct
pas s word be fore the us e r's
account is locke d.
Spe cifie s the pe riod (in
s e conds ) afte r which the
failure count will be re s e t.
Spe cifie s the pe riod (in
s e conds ) for which a lockout
is e nforce d.

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

The re can be multiple pas s word policie s configure d in IdM. The re is always a global policy,
which is s e t whe n the s e rve r is cre ate d. Additional policie s can be cre ate d for groups in
IdM.
The UI lis ts all of the group pas s word policie s and the global policy on the Password
Policies page .
Us ing the CLI, both global and group-le ve l pas s word policie s can be vie we d us ing the
pwpolicy-show command. The CLI can als o dis play the pas s word policy in e ffe ct for a
us e r.

19.2.1. Viewing t he Global Password Policy
The global pas s word policy is cre ate d as part of the initial IdM s e rve r s e tup. This policy
applie s to e ve ry us e r until a group-le ve l pas s word policy s upe rs e de s it.
The de fault s e ttings for the global pas s word policy are lis te d in Table 19.2, “De fault Global
Pas s word Policy”.
T able 19.2. Def ault Glo bal Passwo rd Po licy
At t ribut e

Value

Max life time
Min life time
His tory s iz e
Characte r clas s e s
Min le ngth
Max failure s
Failure re s e t inte rval
Lockout duration

90 (days )
1 (hour)
0 (uns e t)
0 (uns e t)
8
6
60
600

19.2.1.1. Wit h t he Web UI
1. Click the Policy tab, and the n click the Password Policies s ubtab.
2. All of the policie s in the UI are lis te d by group. The global pas s word policy is
de fine d by the global_policy group. Click the group link.

291

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

3. The global policy is dis playe d.

292

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

19.2.1.2. Wit h t he Command Line
To vie w the global policy, s imply run the pwpolicy-show command with no argume nts :
[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-show
Group: global_policy
Max lifetime (days): 90
Min lifetime (hours): 1
History size: 0
Character classes: 0

293

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Min length: 8
Max failures: 6
Failure reset interval: 60
Lockout duration: 600

19.2.2. Viewing Group-Level Password Policies
19.2.2.1. Wit h t he Web UI
1. Click the Policy tab, and the n click the Password Policies s ubtab.
2. All of the policie s in the UI are lis te d by group. Click the name of the group which is
as s igne d the policy.

3. The group policy is dis playe d.

294

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

19.2.2.2. Wit h t he Command Line
For a group-le ve l pas s word policy, s pe cify the group name with the command:
[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-show ipausers
Group: ipausers
Max lifetime (days): 120
Min lifetime (hours): 10
Min length: 10
Priority: 50

19.2.3. Viewing t he Password Policy in Ef f ect f or a User
A us e r may be long to multiple groups , e ach with the ir own s e parate pas s word policie s .
The s e policie s are not additive . Only one policy is in e ffe ct at a time and it applie s to all
pas s word policy attribute s . To s e e which policy is in e ffe ct for a s pe cific us e r, the
pwpolicy-show command can be run for a s pe cific us e r. The re s ults als o s how which
group policy is in e ffe ct for that us e r.
[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-show --user=jsmith

295

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Group: global_policy
Max lifetime (days): 90
Min lifetime (hours): 1
History size: 0
Character classes: 0
Min length: 8
Max failures: 6
Failure reset interval: 60
Lockout duration: 600

19.3. Creat ing and Edit ing Password Policies
A pas s word policy can be s e le ctive ; it may only de fine ce rtain e le me nts . A global
pas s word policy s e ts de faults that are us e d for e ve ry us e r e ntry, unle s s a group policy
take s priority.

No te
A global policy always e xis ts , s o the re is no re as on to add a global pas s word policy.
Group-le ve l policie s ove rride the global policie s and offe r s pe cific policie s that only apply
to group me mbe rs . Pas s word policie s are not cumulative . Eithe r a group policy or the
global policy is in e ffe ct for a us e r or group, but not both s imultane ous ly.
Group-le ve l policie s do not e xis t by de fault, s o the y mus t be cre ate d manually.

No te
It is not pos s ible to s e t a pas s word policy for a non-e xis te nt group.

19.3.1. Creat ing Password Policies in t he Web UI
1. Click the Policy tab, and the n click the Password Policies s ubtab.
2. All of the policie s in the UI are lis te d by group. The global pas s word policy is
de fine d by the global_policy group. Click the group link.

296

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

3. Click the Add link at the top.
4. In the pop-up box, s e le ct the group for which to cre ate the pas s word policy.

5. Se t the priority of the policy. The highe r the numbe r, the lowe r the priority.
Conve rs e ly, the highe s t priority policy has the lowe s t numbe r.
Only one pas s word policy is in e ffe ct for a us e r, and that is the highe s t priority
policy.

297

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
The priority cannot be change d in the UI once the policy is cre ate d.
6. Click the Add and Edit button s o that the policy form imme diate ly ope ns .
7. Se t the policy fie lds . Le aving a fie ld blank me ans that attribute is not adde d the
pas s word policy configuration.
Max lifetime s e ts the maximum amount of time , in days , that a pas s word is valid
be fore a us e r mus t re s e t it.
Min lifetime s e ts the minimum amount of time , in hours , that a pas s word mus t
re main in e ffe ct be fore a us e r is pe rmitte d to change it. This pre ve nts a us e r
from atte mpting to change a pas s word back imme diate ly to an olde r pas s word or
from cycling through the pas s word his tory.
History size s e ts how many pre vious pas s words are s tore d. A us e r cannot re us e a pas s word that is s till in the pas s word his tory.
Character classes s e ts the number of diffe re nt cate gorie s of characte r that mus t
be us e d in the pas s word. This doe s not s e t which clas s e s mus t be us e d; it s e ts
the numbe r of diffe re nt (uns pe cifie d) clas s e s which mus t be us e d in a pas s word.
For e xample , a characte r clas s can be a numbe r, s pe cial characte r, or capital;
the comple te lis t of cate gorie s is in Table 19.1, “Pas s word Policy Se ttings ”. This
is part of s e tting the comple xity re quire me nts .
Min length s e ts how many characte rs mus t be in a pas s word. This is part of
s e tting the comple xity re quire me nts .

19.3.2. Creat ing Password Policies wit h t he Command Line
Pas s word policie s are adde d with the pwpolicy-add command.

298

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-add groupName --attribute-value
For e xample :
[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-add exampleGroup --minlife=7 --maxlife=49
--history= --priority=1
Group: exampleGroup
Max lifetime (days): 49
Min lifetime (hours): 7
Priority: 1

No te
Se tting an attribute to a blank value e ffe ctive ly re move s that attribute from the
pas s word policy.

19.3.3. Edit ing Password Policies wit h t he Command Line
As with mos t IdM e ntrie s , a pas s word policy is e dite d by us ing a *-mod command,
pwpolicy-mod, and the n the policy name . Howe ve r, the re is one diffe re nce with e diting
pas s word policie s : the re is a global policy which always e xis ts . Editing a group-le ve l
pas s word policy is s lightly diffe re nt than e diting the global pas s word policy.
Editing a group-le ve l pas s word policy follows the s tandard s yntax of *-mod commands . It
us e s the pwpolicy-mod command, the name of the policy e ntry, and the attribute s to
change . For e xample :
[jsmith@ipaserver ~]$ ipa pwpolicy-mod exampleGroup --lockouttime=300 -history=5 --minlength=8
To e dit the global pas s word policy, us e the pwpolicy-mod command with the attribute s to
change , but without specifying a password policy name. For e xample :
[jsmith@ipaserver ~]$ ipa pwpolicy-mod --lockouttime=300 --history=5 -minlength=8

19.4. Managing Password Expirat ion Limit s
Pas s word policie s are applie d at t he t ime a passwo rd is changed. So, whe n a
pas s word is s e t, it conforms to the pas s word policy in e ffe ct at that time . If the pas s word
policy is change d late r, that change is not applie d, re troactive ly, to the pas s word.
Se tting pas s word e xpiration pe riods is configure d as part of the group pas s word policy.
Cre ating and e diting pas s word policie s (including the e xpiration attribute in the policy) is
cove re d in Se ction 19.3, “Cre ating and Editing Pas s word Policie s ”.
With pas s word e xpiration pe riods , the re are two attribute s that are re late d:
The maximum life time s e tting give n in the pas s word policy (--maxlife)

299

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The actual date that the pas s word for a give n us e r e xpire s (krbPasswordExpiration)
Changing the pas s word e xpiration time in the pas s word policy doe s not affe ct the
e xpiration date for a us e r, until the us e r pas s word is change d. If the pas s word e xpiration
date ne e ds to be change d imme diate ly, it can be change d by e diting the us e r e ntry.
To force the e xpiration date to change , re s e t the krbPasswordExpiration attribute value
for the us e r. T his can o nly be do ne using ldapmo dif y. For e xample , for a s ingle us e r:
[bjensen@ipaserver ~]$ ldapmodify -D "cn=Directory Manager" -w secret -h
ipaserver.example.com -p 389 -vv
dn: uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
changetype: modify
replace: krbpasswordexpiration
krbpasswordexpiration: 20140202203734Z
Multiple e ntrie s can be e dite d s imultane ous ly by re fe re ncing an LDIF file in the -f option
with the ldapmodify command.

No te
If an adminis trator re s e ts a pas s word, it make s the pre vious pas s word e xpire d and
force s the us e r to update the pas s word. Whe n the us e r update s the pas s word, it
automatically us e s the ne w pas s word policie s , including a ne w e xpiration date .

19.5. Changing t he Priorit y of Group Password Policies
A us e r may be long to multiple groups , e ach with diffe re nt pas s word policie s . Since only
one policy can be in e ffe ct for a us e r, the re has to be a me thod to as s ign pre ce de nce to
policie s . That is done through priority.
The highe s t priority is z e ro (0). The lowe r the numbe r, the highe r the priority.
This is s e t initially whe n the pas s word policy is cre ate d. It can be modifie d afte r the policy
is cre ate d by re s e tting the --priority option.
[root@server ~]# kinit admin
[root@server ~]# ipa pwpolicy-mod examplegroup --priority=10
Whe n a us e r be longs to multiple groups , the group pas s word policy with the lowe s t priority
number has the highe s t priority.

19.6. Set t ing Account Lockout Policies
A brute force attack occurs whe n an attacke r atte mpts to gue s s a pas s word by s imply
flooding the s e rve r with multiple login atte mpts . An account lockout policy pre ve nts brute
force attacks by blocking an account from logging into the s ys te m afte r a ce rtain numbe r
of login failure s — e ve n if the corre ct pas s word is s ubs e que ntly e nte re d.

300

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

No te
A us e r account can be manually unlocke d by an adminis trator us ing the ipa userunlock command. Als o s e e Se ction 9.6, “Unlocking Us e r Accounts Afte r Pas s word
Failure s ”.

19.6.1. In t he UI
The s e attribute s are available in the pas s word policy form whe n a group-le ve l pas s word
policy is cre ate d or whe n any pas s word policy, including the global pas s word policy, is
e dite d.
1. Click the Policy tab, and the n click the Password Policies s ubtab.
2. Click the name of the policy to e dit.

3. Se t the account lockout attribute value s .

301

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The re are thre e parts to the account lockout policy:
Max Failures s e ts the numbe r of faile d login atte mpts be fore the account is
locke d.
Failure reset interval s e ts the numbe r of s e conds afte r a faile d login
atte mpt be fore the counte r re s e ts . Since mis take s do happe n hone s tly, the
count of faile d atte mpts is not ke pt fore ve r; it naturally laps e s afte r the s e t
amount of time .
Lockout duration s e ts the numbe r of s e conds for an account to re main locke d
afte r the maximum numbe r of faile d atte mpts is re ache d. Note that if this fie ld is
s e t to 0, the account will be pe rmane ntly locke d in s uch a cas e .

19.6.2. In t he CLI
The re are thre e parts to the account lockout policy:
The --maxfail option s pe cifie s the numbe r of faile d login atte mpts be fore the account
is locke d.
The --failinterval option s e ts the numbe r of s e conds afte r a faile d login atte mpt
be fore the counte r re s e ts . Since mis take s do happe n hone s tly, the count of faile d
atte mpts is not ke pt fore ve r; it naturally laps e s afte r the s e t amount of time .
The --lockouttime option s e ts the numbe r of s e conds for an account to re main locke d
afte r the maximum numbe r of faile d atte mpts is re ache d. Note that if the 0 value is
us e d, the account will be pe rmane ntly locke d in s uch a cas e .

302

⁠C hapt e r 19 . De f ining Pas s wo r d Po lic ie s

The s e account lockout options can all be s e t whe n a pas s word policy is cre ate d with
pwpolicy-add or adde d late r us ing pwpolicy-mod. For e xample :
[jsmith@ipaserver ~]$ kinit admin
[jsmith@ipaserver ~]$ ipa pwpolicy-mod examplegroup --maxfail=4 -lockouttime=600 --failinterval=30

19.7. Enabling a Password Change Dialog
The re may be s ituations whe n a us e r e xis ts in Ide ntity Manage me nt but doe s not have a
valid Ke rbe ros ticke t, me aning he cannot authe nticate to the IdM domain. This is pos s ible
for ne w us e rs or for us e rs whos e domain pas s words have e xpire d. Much like e nabling
pas s word authe ntication in the we b UI, it is pos s ible to e nable pas s word-bas e d
authe ntication to the clie nt. This ope ns up a pas s word change dialog box to allow the us e r
to re s e t the e xpire d pas s word.
The pas s word change dialog is e nable d by us ing Ope nSSH's challenge-response
authe ntication.
The challe nge -re s pons e dialog is optional. In many e nvironme nts , it is not ne ce s s ary
be caus e SSSD can handle changing e xpire d pas s words by invoking the re quire d PAM
module s . Howe ve r, us ing the challe nge -re s pons e option in Ope nSSH make s it pos s ible to
do pas s word change s dire ctly in PAM and to s upport full PAM conve rs ations .
This is not e nable d by de fault, but it can be e nable d by e diting the Ope nSSH configuration.
1. Ope n the /etc/ssh/sshd_config file .
2. Se t ChallengeResponseAuthentication to yes.

303

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 20. Managing t he Kerberos Domain
Ke rbe ros authe ntication is the core of authe ntication within the IdM domain. The IdM s e rve r
actually runs a Ke rbe ros s e rve r within it, and this Ke rbe ros s e rve r can be configure d for
cus tom policie s for managing ticke ts and ke ytabs .
For more information on Ke rbe ros conce pts , s e e the MIT Ke rbe ros docume ntation,
http://we b.mit.e du/ke rbe ros /www/.

Impo rtant
Ide ntity Manage me nt has its own command-line tools to us e to manage Ke rbe ros
policie s . Do no t us e kadmin or kadmin.local to manage IdM Ke rbe ros s e ttings .

20.1. About Kerberos
Ke rbe ros provide s an authe ntication laye r be twe e n s e rvice s and us e rs . Ke rbe ros
ce ntraliz e s authe ntication into a s ingle location; a us e r authe nticate s to the Ke rbe ros
s e rve r, and the n whe n that us e r atte mpts to acce s s any re s ource on the ne twork, that
re s ource can che ck the key distribution center (KDC) for the s tore d us e r cre de ntials . This
allows us e rs to acce s s multiple re s ource s without having to s upply cre de ntials s e parate ly
to e ach and e ve ry one .
All of the us e rs and s e rvice s , combine d, and all of the KDCs and Ke rbe ros s e rve rs that
are aware of e ach othe r cons titute a realm. Each us e r, machine , and s e rvice within the
re alm is ide ntifie d by a unique name calle d the principal. The us e r or s e rvice us e s the
principal and a ve rifying cre de ntial (us ually a pas s word) to authe nticate to the KDC. The
cre de ntial that is s hare d with the KDC is a key and it is s tore d in a file calle d a key table or
keytab.
Whe n the KDC ve rifie s the us e r's ide ntity, it is s ue s a ticket. The ticke t is a long-te rm pas s
to any s e rvice and machine on the re alm. The KDC is s ue s the us e r a s pe cial kind of ticke t
calle d a ticket-granting ticket (TGT). Whe ne ve r the us e r trie s to acce s s a re s ource within
the Ke rbe ros re alm, the re s ource s e nds a re que s t for a ticke t s pe cifically for it. The TGT
is us e d to is s ue a re s ource -s pe cific ticke t that the re s ource the n us e s to authe nticate the
us e r and grant acce s s .

No te
Whe n an IdM clie nt is firs t configure d, the hos t principal is automatically re trie ve d by
the s e tup s cript and s tore d in the /etc/krb5.keytab file . This hos t principal is
s tore d within the hos t re cord s o that local s e rvice commands cannot be us e d with
this principal. This pre pare s the clie nt to function in the IdM re alm.

20.1.1. About Principal Names
The principal ide ntifie s not only the us e r or s e rvice , but als o the re alm that the e ntity
be longs to. A principal name has two parts , the ide ntifie r and the re alm:
identifier@REALM

304

⁠C hapt e r 20 . Managing t he Ke r be r o s Do main

For a us e r, the identifier is only the Ke rbe ros us e rname . For a s e rvice , the identifier is a
combination of the s e rvice name and the hos tname of the machine it runs on:
service/FQDN@REALM
The service name is a cas e -s e ns itive s tring that is s pe cific to the s e rvice type , like host,
ldap, http, and DNS. Not all s e rvice s have obvious principal ide ntifie rs ; the sshd dae mon,
for e xample , us e s the hos t s e rvice principal.
The hos t principal is us ually s tore d in /etc/krb5.keytab.
Whe n Ke rbe ros re que s ts a ticke t, it always re s olve s the domain name alias e s (DNS
CNAME re cords ) to the corre s ponding DNS addre s s (A or AAAA re cords ). The hos tname
from the addre s s re cord is the n us e d whe n s e rvice or hos t principals are cre ate d.
For e xample :
www.example.com CNAME web-01.example.com
web-01.example.com A 192.0.2.145
A s e rvice atte mpts to conne ct to the hos t us ing its CNAME alias :
$ ssh www.example.com
The Ke rbe ros s e rve r re que s ts a ticke t for the re s olve d hos tname , web01.example.com@EXAMPLE.COM, s o the hos t principal mus t be host/web01.example.com@EXAMPLE.COM.

20.1.2. About Prot ect ing Keyt abs
To prote ct ke ytab file s , re s e t the pe rmis s ions and owne rs hip to re s trict acce s s to the file s
to only the ke ytab owne r. For e xample , s e t the owne r of the Apache ke ytab
(/etc/httpd/conf/ipa.keytab) to apache and the mode to 0600.

20.2. Set t ing Kerberos T icket Policies
The Ke rbe ros ticket policy s e ts bas ic re s trictions on managing ticke ts within the Ke rbe ros
re alm, s uch as the maximum ticke t life time and the maximum re ne wal age (the pe riod
during which the ticke t is re ne wable ).
The Ke rbe ros ticke t policy is s e t globally s o that it applie s to e ve ry ticke t is s ue d within the
re alm. IdM als o has the ability to s e t us e r-le ve l ticke t policie s which ove rride the global
policie s . This can be us e d, for e xample , to s e t e xte nde d e xpiration time s for
adminis trators or to s e t s horte r e xpiration time s for s ome e mploye e s .

20.2.1. Set t ing Global T icket Policies
20.2.1.1. From t he Web UI
1. Click the Policy tab, and the n click the Kerberos Ticket Policy s ubtab.
2. Change the ticke t life time policie s .

305

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Max renew s e ts the pe riod afte r a ticke t e xpire s that it can be re ne we d.
Max life s e ts the active pe riod (life time ) of a Ke rbe ros ticke t.
3. Click the Update link at the top of the policy page .
4. Re s tart the KDC.
[root@server ~]# systemctl start krb5kdc.service

Impo rtant
Any change to the global Ke rbe ros ticke t policy re quire s a re s tart of the KDC
for the change s to take e ffe ct.

20.2.1.2. From t he Command Line
The ipa krbtpolicy-mod command modifie s the policy, while the ipa krbtpolicy-reset
command re s e ts the policy to the de fault value s .
For e xample :
# ipa krbtpolicy-mod --maxlife=3600 --maxrenew=18000
Max life: 3600
Max renew: 18000

306

⁠C hapt e r 20 . Managing t he Ke r be r o s Do main

Impo rtant
Any change to the global Ke rbe ros ticke t policy re quire s a re s tart of the KDC for the
change s to take e ffe ct. Re s tart the KDC:
[root@server ~]# systemctl restart krb5kdc.service

20.2.2. Set t ing User-Level T icket Policies
Us e r-le ve l Ke rbe ros ticke t policie s are s e t us ing the s ame commands as global policie s ,
but the us e r is s pe cifie d in the command.
For e xample :
# ipa krbtpolicy-mod jsmith --maxlife=3600
Max life: 3600

Impo rtant
Us e r-le ve l policie s take e ffe ct imme diate ly on the ne xt re que s te d ticke t (s uch as
running kinit), without having to re s tart the KDC s e rvice .

20.3. Refreshing Kerberos T icket s
Ke rbe ros ke ys are analogous to pas s words . As with pas s word policie s , Ke rbe ros ticke ts
come unde r s e curity policie s which re quire the m to be manually re fre s he d afte r a
s pe cifie d inte rval.
The ve rs ion of the ke y is s hown in its key version number (KVNO). Re fre s hing (als o calle d
rotating) the principal's ke y incre me nts the KVNO in the ke ytab e ntry. Whe n a ke y is
re fre s he d, a ne w e ntry is adde d to the ke ytab with a highe r KVNO. The original ke y
re mains in the ke ytab but is no longe r us e d to is s ue ticke ts .
Each ke ytab for the IdM re alm has an e ntry in the IdM LDAP s e rve r, which include s its las t
change time . The principals which ne e d to be re fre s he d can be re ge ne rate d us ing the
ipa-getkeytab command.

No te
The ipa-getkeytab command doe s not de le te the old ke ytab in cas e it alre ady
e xis ts in the file .
1. Find all ke ytabs is s ue d be fore the re quis ite date . For e xample , this looks for any
principals cre ate d be twe e n midnight on January 1, 2010, and 11:59 PM on
De ce mbe r 31, 2010:
[root@server ~]# ldapsearch -x -b

307

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

"cn=computers,cn=accounts,dc=example,dc=com" "(&
(krblastpwdchange>=20100101000000)
(krblastpwdchange<=20101231235959))" dn krbprincipalname
...
[root@server ~]# ldapsearch -x -b
"cn=services,cn=accounts,dc=example,dc=com" "(&
(krblastpwdchange>=20100101000000)
(krblastpwdchange<=20101231235959))" dn krbprincipalname
Hos t (machine ) principals are s tore d unde r the
cn=computers,cn=accounts,dc=example,dc=com s ubtre e .
Se rvice principals are s tore d unde r the
cn=services,cn=accounts,dc=example,dc=com s ubtre e .
Filte r by the las t change date (krblastpwdchange).
Limit the s e arch re s ult information to only the e ntry name and principal by
s pe cifying the dn krbprincipalname attribute s .
Date s are e xpre s s e d in YYYYMMDD format, and time s in HHMMSS format (GMT).
2. Re trie ve a ne w ke ytab for the principal us ing the ipa-getkeytab command. This
re quire s the location of the original ke ytab for the s e rvice or hos t (-k), the principal
(-p), and the IdM s e rve r hos tname (-s).
For e xample , this re fre s he s the hos t principal with a ke ytab in the de fault location
of /etc/krb5.keytab:
# ipa-getkeytab -p host/client.example.com@EXAMPLE.COM -s
ipa.example.com -k /etc/krb5.keytab
This re fre s he s the ke ytab for the Apache s e rvice , with a ke ytab in the de fault
location of /etc/httpd/conf/ipa.keytab:
# ipa-getkeytab -p HTTP/client.example.com@EXAMPLE.COM -s
ipa.example.com -k /etc/httpd/conf/ipa.keytab
3. Re ge ne rate the ke ytab us ing ipa-getkeytab for e ve ry s e rvice .
The klist command dis plays the ne w ke y ve rs ion numbe r for the re fre s he d ke ytab. The
original ke ytab s till e xis ts in the databas e , and it is lis te d with the pre vious KVNO.
# klist -kt /etc/krb5.keytab
Keytab: WRFILE:/etc/krb5.keytab
KVNO Timestamp
Principal
---- ----------------- ------------------------------------------------------1 06/09/10 11:23:01 host/client.example.com@EXAMPLE.COM(aes256-ctshmac-sha1-96)
2 06/09/11 05:58:47 host/client.example.com@EXAMPLE.COM(aes256-ctshmac-sha1-96)
1 03/09/11 13:57:16 krbtgt/EXAMPLE.COM@EXAMPLE.COM(aes256-cts-hmacsha1-96)

308

⁠C hapt e r 20 . Managing t he Ke r be r o s Do main

1 03/09/11 13:57:16 HTTP/ipa.example.com@EXAMPLE.COM(aes256-cts-hmacsha1-96)
1 03/09/11 13:57:16 ldap/ipa.example.com@EXAMPLE.COM(aes256-cts-hmacsha1-96)
Ticke ts is s ue d agains t the old ke ytab continue to work, while ne w ticke ts are is s ue d us ing
the ke y with the highe s t KVNO. This avoids any dis ruption to s ys te m ope rations .

Impo rtant
Some s e rvice s , s uch as NFSv4, only s upport a limite d s e t of e ncryption type s . Pas s
the appropriate argume nts to the ipa-getkeytab command to configure the ke ytab
prope rly.

20.4. Kerberos Flags for Services and Host s
Various Ke rbe ros flags can be us e d to de fine ce rtain s pe cific as pe cts of the Ke rbe ros
ticke t be havior. You can add the s e flags to s e rvice and hos t Ke rbe ros principals .
Principals in IdM acce pt the following two Ke rbe ros flags :
OK_AS_DELEGATE
Us e this flag to s pe cify Ke rbe ros ticke ts trus te d for de le gation.
AD clie nts che ck the OK_AS_DELEGATE flag on the Ke rbe ros ticke t to de te rmine
whe the r the us e r cre de ntials can be forwarde d or de le gate d to the s pe cific
s e rve r; AD forwards the TGT only to s e rvice s or hos ts with OK_AS_DELEGATE s e t.
With this flag, SSSD can add the AD us e r TGT to the de fault Ke rbe ros cre de ntials
cache on the IdM clie nt machine .
REQUIRES_PRE_AUTH
Us e this flag to s pe cify that only pre -authe nticate d ticke ts are allowe d to
authe nticate to the principal.
With the REQUIRES_PRE_AUTH flag s e t, the KDC re quire s additional authe ntication:
the KDC is s ue s the TGT for a principal with REQUIRES_PRE_AUTH only if the TGT
has be e n pre -authe nticate d.
You can us e REQUIRES_PRE_AUTH to dis able pre -authe ntication for s e le cte d
s e rvice s or hos ts , which lowe rs the load on the KDC but als o s lightly incre as e s
the pos s ibility of a brute -force attack on a long-te rm ke y to s ucce e d.

20.4.1. Set t ing Kerberos Flags f rom t he Web UI
From the IdM we b UI, you can curre ntly only add the OK_AS_DELEGATE flag to a principal:
1. Se le ct the Services s ubtab, acce s s ible through the Identity main tab.

309

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 20 .1. List o f Services
2. Click on the s e rvice to which you want to add the flag.
3. Che ck the Trusted for delegation option.

Figure 20 .2. Adding t he OK_AS_DELEGAT E Flag

20.4.2. Set t ing Kerberos Flags f rom t he Command Line
To add a flag to a principal from the command line or to re move a flag, add one of the
following options to the ipa service-mod command:

310

⁠C hapt e r 20 . Managing t he Ke r be r o s Do main

--ok-as-delegate for OK_AS_DELEGATE
--requires-pre-auth for REQUIRES_PRE_AUTH
To add a flag, s e t the corre s ponding option to 1. For e xample , to add the OK_AS_DELEGATE
flag to the test/ipa.example.com@EXAMPLE.COM principal:
$ ipa service-mod test/ipa.example.com@EXAMPLE.COM --ok-as-delegate=1
To re move a flag or to dis able it, s e t the corre s ponding option to 0. For e xample , to
dis able the REQUIRES_PRE_AUTH flag for the test/ipa.example.com@EXAMPLE.COM principal:
$ ipa service-mod test/ipa.example.com@EXAMPLE.COM --requires-pre-auth=0
To find out if OK_AS_DELEGATE is curre ntly s e t for a principal, run the kvno utility and the n
the klist -f command. OK_AS_DELEGATE is re pre s e nte d by the O characte r in the klist
-f output:
$ kvno test/ipa.example.com@EXAMPLE.COM
$ klist -f
Ticket cache: KEYRING:persistent:0:0
Default principal: admin@EXAMPLE.COM
Valid starting Expires
Service principal
02/19/2014 09:59:02 02/20/2014 08:21:33 test/ipa/example.com@EXAMPLE.COM
Flags: FATO
To find out what flags are curre ntly s e t for a principal, us e the kadmin.local utility. The
curre nt flags are dis playe d on the Attributes line of kadmin.local output, for e xample :
# kadmin.local
kadmin.local: getprinc test/ipa.example.com
Principal: test/ipa.example.com@EXAMPLE.COM
Expiration date: [never]
Last password change: Mon Sep 16 15:44:21 EDT 2013
Password expiration date: [none]
Maximum ticket life: 1 day 00:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Mon Oct 14 23:42:53 EDT 2013 (admin/admin@EXAMPLE.COM)
Last successful authentication: Wed Mar 11 08:01:03 EDT 2015
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 6
Key: vno 1, aes256-cts-hmac-sha1-96, no salt
Key: vno 1, aes128-cts-hmac-sha1-96, no salt
Key: vno 1, des3-cbc-sha1, no salt
Key: vno 1, arcfour-hmac, no salt
Key: vno 1, camellia128-cts-cmac, no salt
Key: vno 1, camellia256-cts-cmac, no salt
MKey: vno 1
Attributes: REQUIRES_PRE_AUTH OK_AS_DELEGATE OK_TO_AUTH_AS_DELEGATE
Policy: [none]

20.5. Caching Kerberos Passwords
311

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

A machine may not always be on the s ame ne twork as the IdM domain; for e xample , a
machine may ne e d to be logge d into a VPN be fore it can acce s s the IdM domain. If a us e r
logs into a s ys te m whe n it is offline and the n late r atte mpts to conne ct to IdM s e rvice s ,
the n the us e r is blocke d be caus e the re is no IdM Ke rbe ros ticke t for that us e r. IdM works
around that limitation by us ing SSSD to s tore the Ke rbe ros pas s words in the SSSD cache .
This is configure d by de fault by the ipa-client-install s cript. A configuration parame te r
is adde d to the /etc/sssd/sssd.conf file which s pe cifically ins tructs SSSD to s tore thos e
Ke rbe ros pas s words for the IdM domain:
[domain/example.com]
cache_credentials = True
ipa_domain = example.com
id_provider = ipa
auth_provider = ipa
access_provider = ipa
chpass_provider = ipa
ipa_server = _srv_, server.example.com
krb5_store_password_if_offline = true
This de fault be havior can be dis able d during the clie nt ins tallation by us ing the --nokrb5-offline-passwords option.
This be havior can als o be dis able d by e diting the /etc/sssd/sssd.conf file and re moving
the krb5_store_password_if_offline line or changing its value to fals e .
[domain/example.com]
...
krb5_store_password_if_offline = false
The SSSD configuration options for Ke rbe ros authe ntication is cove re d in the "Configuring
Domains " s e ction of the SSSD chapte r in the Sys te m-Le ve l Authe ntication Guide .

20.6. Removing Keyt abs
Re fre s hing Ke rbe ros ticke ts adds a ne w ke y to the ke ytab, but it doe s not cle ar the
ke ytab. If a hos t is be ing une nrolle d and re -adde d to the IdM domain or if the re are
Ke rbe ros conne ction e rrors , the n it may be ne ce s s ary to re move the ke ytab and cre ate a
ne w ke ytab.
This is done us ing the ipa-rmkeytab command. To re move all principals on the hos t,
s pe cify the re alm with the -r option:
# ipa-rmkeytab -r EXAMPLE.COM -k /etc/krb5.keytab
To re move the ke ytab for a s pe cific s e rvice , us e the -p option to s pe cify the s e rvice
principal:
# ipa-rmkeytab -p ldap/client.example.com -k /etc/krb5.keytab

312

⁠C hapt e r 20 . Managing t he Ke r be r o s Do main

Chapt er 21. Using sudo
Ide ntity Manage me nt provide s a me chanis m for pre dictably and cons is te ntly applying sudo
policie s acros s the IdM domain. The sudo policie s apply to domain us e rs and domain
hos ts .

21.1. About sudo and IPA
The sudo command allows a s ys te m adminis trator to de le gate authority to s pe cific us e rs
to run s pe cific commands as root or anothe r s pe cifie d us e r. sudo provide s an audit trail of
the commands and the ir argume nts , s o acce s s can be tracke d.

21.1.1. General sudo Conf igurat ion in Ident it y Management
sudo us e s a local configuration file , /etc/sudoers, which de fine s the commands and
us e rs with s udo acce s s . While this file can be s hare d among machine s , the re 's no native
way to dis tribute sudo configuration file s among machine s .
Ide ntity Manage me nt us e s its ce ntraliz e d LDAP databas e to contain the sudo configuration,
which make s it globally available to all domain hos ts . Ide ntity Manage me nt als o has a
s pe cializ e d LDAP s che ma for sudo e ntrie s that allows a lot more fle xible and s imple r
configuration. This s che ma adds two ke y fe ature s :
The Ide ntity Manage me nt s che ma s upports hos t groups in addition to ne tgroups for
sudo, while sudo only s upports ne tgroups .
For e ve ry hos t group, Ide ntity Manage me nt als o cre ate s a corre s ponding s hadow
ne tgroup. This allows IdM adminis trators to cre ate sudo rule s that re fe re nce hos t
groups , while the local sudo command us e s the corre s ponding ne tgroup.
Ide ntity Manage me nt introduce s the conce pt of a sudo command group. The group
contains multiple commands , and the command group can be re fe re nce d in the sudo
configuration.
Be caus e sudo doe s not s upport hos t groups and command groups , Ide ntity Manage me nt
trans late s the IdM sudo configuration into native sudo configuration whe n the sudo rule s
are cre ate d.
Be caus e the sudo information is not available anonymous ly ove r LDAP by de fault,
Ide ntity Manage me nt de fine s a de fault sudo us e r,
uid=sudo,cn=sysaccounts,cn=etc,$SUFFIX, which can be s e t in the LDAP/sudo
configuration file , /etc/sudo-ldap.conf.
Both sudo and Ide ntity Manage me nt s upport us e r groups as part of the sudo configuration.
Us e r groups can be e ithe r Unix or non-POSIX groups . Cre ating non-POSIX groups can
cre ate s ome acce s s is s ue s be caus e any us e rs in the group inhe rit non-POSIX rights from
the group. Having the choice be twe e n Unix and non-POSIX groups allows adminis trators
the choice in group formatting and to avoid proble ms with inhe rite d pe rmis s ions or GID
information.

21.1.2. sudo and Net groups
As Se ction 21.1.1, “Ge ne ral s udo Configuration in Ide ntity Manage me nt” me ntions , the
LDAP s che ma us e d for s udo e ntrie s in Ide ntity Manage me nt s upports hos t group-s tyle
groups in addition to ne tgroups . Re ally, Ide ntity Manage me nt cre ate s two groups , a vis ible

313

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

hos t group and a s hadow ne tgroup. sudo its e lf only s upports NIS-s tyle ne tgroups for group
formats .
In orde r for ne tgroups and sudo, which re lie s on ne tgroups , to function prope rly, the NIS
domain name is re quire d to be s e t. Howe ve r, while sudo configuration re quire s NISformatte d ne tgroups and that a NIS domain be name d for ne tgroups , this NIS domain doe s
not actually ne e d to e xis t. It is not re quire d to have a NIS s e rve r ins talle d.

No te
The clie nt ins tallation proce s s , e xe cute d by the ipa-client-install command,
s e ts a NIS domain name automatically to the IdM domain name by de fault.
Whe n any group is cre ate d for sudo, the NIS obje ct is cre ate d in the Dire ctory Se rve r
ins tance , and the n the information is re trie ve d by NSS_LDAP or by SSSD. The clie nt (in
this cas e , sudo) the n e xtracts the re quire d NIS information from the information provide d
by Ide ntity Manage me nt's Dire ctory Se rve r.
The Ide ntity Manage me nt Dire ctory Se rve r ins tance us e s the s tandard LDAP s che ma for
NIS obje cts , de fine d in RFC 2307.

21.1.3. Support ed sudo Client s
Any s ys te m which is s upporte d as an IdM clie nt s ys te m can be configure d as a sudo clie nt
in IdM.

21.2. Set t ing up sudo Commands and Command Groups
Jus t as in re gular sudo configuration, any command which will be gove rne d by sudo acce s s
mus t be lis te d in the configuration. Ide ntity Manage me nt adds an e xtra control me as ure
with sudo command groups, which allow a group of commands to be de fine d and the n
applie d to the sudo configuration as one .
Adding a command or a command group make s it available to IdM to be de fine d in a sudo
rule ; s imply adding a command doe s not automatically include it in a sudo rule .

21.2.1. Adding sudo Commands
21.2.1.1. Adding sudo Commands wit h t he Web UI
1. Click the Policy tab.
2. Click the Sudo s ubtab, and the n s e le ct the Sudo Commands link.
3. Click the Add link at the top of the lis t of commands .

314

⁠C hapt e r 21. Us ing s udo

4. Ente r the full s ys te m path and name of the command and, optionally, a de s cription.

5. Click the Add and Edit button to go imme diate ly to the s e ttings page s for the
command.
6. In the Sudo Command Groups tab, click the Add button to add the s udo command to
a command group.
7. Click the che ckbox by the groups for the command to join, and click the right arrows
button, >>, to move the group to the s e le ction box.
8. Click the Add button.

21.2.1.2. Adding sudo Commands wit h t he Command Line
To add a s ingle command, us e the sudocmd-add command. This re quire s the full, local
path to the command e xe cutable and a de s cription of the command:
$ ipa sudocmd-add --desc "description" /local/path/to/command
For e xample :
$ ipa sudocmd-add --desc 'For reading log files' '/usr/bin/less'
----------------------------------

315

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Added sudo command "/usr/bin/less"
---------------------------------sudo Command: /usr/bin/less
Description: For reading log files

21.2.2. Adding sudo Command Groups
21.2.2.1. Adding sudo Command Groups wit h t he Web UI
1. Click the Policy tab.
2. Click the Sudo s ubtab, and the n s e le ct the Sudo Command Groups link.
3. Click the Add link at the top of the lis t of command groups .

4. Ente r the name and de s cription for the ne w command group.

5. Click the Add and Edit button to go imme diate ly to the s e ttings page s for the
group.
6. In the Sudo Commands tab, click the Add button to add a s udo command to the group.

316

⁠C hapt e r 21. Us ing s udo

7. In the Sudo Commands tab, click the Add button to add a s udo command to the group.

8. Click the che ckbox by the name s of the commands to add, and click the right arrows
button, >>, to move the command to the s e le ction box.

317

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

9. Click the Add button.

21.2.2.2. Adding sudo Command Groups wit h t he Command Line
Cre ating a command group re quire s cre ating two e ntrie s , one for the group and one for
the command its e lf:
1. Cre ate the command group us ing the sudocmdgroup-add command:
$ ipa sudocmdgroup-add --desc 'File editing commands' files
----------------------------------Added sudo command group "files"
----------------------------------sudo Command Group: files
Description: File editing commands
2. Cre ate a command e ntry us ing the sudocmd-add command:
$ ipa sudocmd-add --desc 'For editing files' '/usr/bin/vim'
---------------------------------Added sudo command "/usr/bin/vim"
---------------------------------sudo Command: /usr/bin/vim
Description: For editing files
3. Add the command, us ing its full dire ctory location as its name , to the command
group us ing the sudocmdgroup-add-member command:
$ ipa sudocmdgroup-add-member --sudocmds '/usr/bin/vim' files
sudo Command Group: files
Description: File editing commands
Member sudo commands: /usr/bin/vim

318

⁠C hapt e r 21. Us ing s udo

------------------------Number of members added 1
-------------------------

21.3. Defining

sudo

Rules

sudo rule s are in a s e ns e s imilar to acce s s control rule s : the y de fine us e rs who are
grante d acce s s , the commands which are within the s cope of the rule , and the n the targe t
hos ts to which the rule applie s . In IdM, additional information can be configure d in the rule ,
s uch as sudoers options and run-as s e ttings , but the bas ic e le me nts always de fine who,
what (s e rvice s ), and whe re (hos ts ).

21.3.1. About Ext ernal Users
sudo rule s de fine four e le me nts : who can do what, where, and as whom. The who is the
re gular us e r, and the as whom is the s ys te m or othe r us e r ide ntity which the us e r us e s to
pe rform tas ks . Thos e tas ks are s ys te m commands that can be run (or s pe cifically not run)
on a targe t machine .
Thre e of thos e e le me nts — who, as whom, and whe re — are ide ntitie s . The y are us e rs .
Mos t of the time , thos e ide ntitie s are going to be e ntitie s within the IdM domain be caus e
the re will be ove rlap be twe e n the s ys te m us e rs in the e nvironme nt and the us e rs and
hos ts be longing to the IdM domain.
Howe ve r, that is not ne ce s s arily the cas e with all ide ntitie s that a sudo policy may
re alis tically cove r. For e xample , sudo rule s could be us e d to grant root acce s s to a
me mbe r of the IT group in IdM, and that root us e r is not a us e r in IdM. Or, for anothe r
e xample , adminis trators may want to block acce s s to ce rtain hos ts that are on a ne twork
but are not part of the IdM domain.
The sudo rule s in Ide ntity Manage me nt s upport the conce pt of external us e rs — me aning,
us e rs which are s tore d and e xis t outs ide of the IdM configuration.

319

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 21.1. Ext ernal Ent it ies
Whe n configuring a sudo rule , the us e r and run-as s e ttings can point to an e xte rnal
ide ntity to be include d and e valuate d in the sudo rule .

21.3.2. About sudo Opt ions Format
The sudo rule can be configure d to us e any s upporte d sudoers options . For a comple te
lis t of options , s e e the s udoe rs (5) man page .
Howe ve r, the sudo rule configuration in Ide ntity Manage me nt does not allow the s ame
formatting as the configuration in the /etc/sudoers file . Spe cifically, Ide ntity Manage me nt
doe s not allow white s pace s in the options parame te r, whe the r it is s e t in the UI or the CLI.
For e xample , in the /etc/sudoers file , it is pe rmis s ible to lis t options in a commas e parate d lis t with s pace s be twe e n:
mail_badpass, mail_no_host, mail_no_perms, syslog = local2
Howe ve r, in Ide ntity Manage me nt, that s ame configuration would be inte rpre te d as
diffe re nt argume nts — including the e quals s ign (=) s ince it has s pace s around it. Ins te ad,
e ach option mus t be adde d individually, e ithe r through the UI or the command-line tools .
[jsmith@server ~]$ ipa sudorule-add-option readfiles
Sudo Option: mail_badpass
----------------------------------------------------Added option "mail_badpass" to Sudo rule "readfiles"
----------------------------------------------------[jsmith@server ~]$ ipa sudorule-add-option readfiles
Sudo Option: syslog=local2
----------------------------------------------------Added option "syslog=local2" to Sudo rule "readfiles"
----------------------------------------------------...
Like wis e , line bre aks that are ignore d in the /etc/sudoers file are not allowe d in the
Ide ntity Manage me nt configuration.
env_keep = "COLORS DISPLAY EDITOR HOSTNAME HISTSIZE INPUTRC
KDEDIR LESSSECURE LS_COLORS MAIL PATH PS1 PS2
QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE LC_COLLATE
LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES
LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE
LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET
XAUTHORITY"
For e xample , the s ame command in the IdM command line has all of the variable s on one
line and no s pace s around the e quals s ign.
[jsmith@server ~]$ ipa sudorule-add-option readfiles
Sudo Option: env_keep="COLORS DISPLAY EDITOR HOSTNAME HISTSIZE INPUTRC
KDEDIR LESSSECURE LS_COLORS MAIL PATH PS1 PS2 ... XAUTHORITY"

320

⁠C hapt e r 21. Us ing s udo

To us e multiple sudoers options in Ide ntity Manage me nt, configure e ach one as a
s e parate option s e tting, rathe r than all on one line .

21.3.3. Def ining sudo Rules in t he Web UI
1. Click the Policy tab.
2. Click the Sudo s ubtab, and the n s e le ct Sudo Rules.
3. Click the Add link at the top of the lis t of s udo rule s .

Figure 21.2. Adding a New sudo Rule
4. Ente r the name for the rule .

Figure 21.3. Naming a New sudo Rule
5. Click the Add and Edit button to go imme diate ly to s e t the configuration for the
rule .
The re are a numbe r of configuration are as for the rule . The mos t bas ic e le me nts
are s e t in the Who, Access This Host, and Run Commands are as ; the othe rs are
optional and are us e d to re fine the rule .
6. Optional. In the Options are a, add any sudoers options .

321

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
As de s cribe d in Se ction 21.3.2, “About s udo Options Format”, do not us e
options with white s pace in the value s . Rathe r than adding a lis t of options in
one line , add a s ingle option s e tting for e ach de s ire d option.
a. Click the Add link at the right of the options lis t.

Figure 21.4. Adding a sudo Opt io n
b. Ente r the sudoers option.

Figure 21.5. Ent ering a sudoers Opt io n
c. Click Add.
7. In the Who are a, s e le ct the us e rs or us e r groups to which the s udo rule is applie d.
a. Click the Add link at the right of the us e rs lis t.

322

⁠C hapt e r 21. Us ing s udo

Figure 21.6. Adding Users t o a sudo Rule
b. Click the che ckbox by the us e rs to add to the rule , and click the right arrow
button to move the us e rs to the s e le ction box.

Figure 21.7. Select ing Users f o r a sudo Rule
c. Click Add.
It is pos s ible to configure both IdM us e rs and e xte rnal s ys te m us e rs
(Se ction 21.3.1, “About Exte rnal Us e rs ”).

323

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

8. In the Access This Host are a, s e le ct the hos ts on which the s udo rule is in e ffe ct.
a. Click the Add link at the right of the hos ts lis t.

Figure 21.8. Adding Ho st s t o a sudo Rule
b. Click the che ckbox by the hos ts to include with the rule , and click the right
arrow button to move the hos ts to the s e le ction box.

Figure 21.9. Select ing Ho st s f o r a sudo Rule
c. Click Add.
9. In the Run Commands are a, s e le ct the commands which are include d in the s udo
rule . The sudo rule can grant acce s s or de ny acce s s to commands , and it can grant
allow acce s s to one command and als o de ny acce s s to anothe r.
a. In the Allow/Deny are a, click the Add link at the right of the commands lis t.

324

⁠C hapt e r 21. Us ing s udo

Figure 21.10 . Adding Co mmands t o a sudo Rule
b. Click the che ckbox by the commands or command groups to include with the
rule , and click the right arrow button to move the commands to the s e le ction
box.

Figure 21.11. Select ing Co mmands f o r a sudo Rule
c. Click Add.
10. Optional. The sudo rule can be configure d to run the give n commands as a s pe cific,
non-root us e r.
a. In the As Whom are a, click the Add link at the right of the us e rs lis t.

325

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 21.12. Co nf iguring sudo Rules t o Execut e Co mmands as a
Specif ic User
b. Click the che ckbox by the us e rs to run the command as , and click the right
arrow button to move the us e rs to the s e le ction box.

Figure 21.13. Select ing Users f o r t he Co mmand
c. Click Add.

21.3.4. Def ining sudo Rules in t he Command Line

326

⁠C hapt e r 21. Us ing s udo

Each e le me nt is adde d to the rule command us ing a diffe re nt command (lis te d in
Table 21.1, “s udo Commands ”).
The bas ic outline of a sudo rule command is :
$ ipa sudorule-add* options ruleName

Example 21.1. Creat ing Basic sudo Rules
In the mos t bas ic cas e , the sudo configuration is going to grant the right to one us e r for
one command on one hos t.
The firs t s te p is to add the initial rule e ntry.
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa sudorule-add files-commands
----------------------------------Added sudo rule "files-commands"
----------------------------------Rule name: files-commands
Enabled: TRUE
Ne xt, add the commands to grant acce s s to. This can be a s ingle command, us ing -sudocmds, or a group of commands , us ing --sudocmdgroups.
[jsmith@server ~]$ ipa sudorule-add-allow-command --sudocmds
"/usr/bin/vim" files-commands
Rule name: files-commands
Enabled: TRUE
sudo Commands: /usr/bin/vim
------------------------Number of members added 1
------------------------Add a hos t or a hos t group to the rule .
[jsmith@server ~]$ ipa sudorule-add-host --host server.example.com
files-commands
Rule name: files-commands
Enabled: TRUE
Hosts: server.example.com
sudo Commands: /usr/bin/vim
------------------------Number of members added 1
------------------------Las t, add the us e r or group to the rule . This is the us e r who is allowe d to us e sudo as
de fine d in the rule ; if no "run-as " us e r is give n, the n this us e r will run the sudo
commands as root.
[jsmith@server ~]$ ipa sudorule-add-user --user jsmith files-commands
Rule name: files-commands
Enabled: TRUE
Users: jsmith

327

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Hosts: server.example.com
sudo Commands: /usr/bin/vim"
------------------------Number of members added 1
-------------------------

Example 21.2. Allo wing and Denying Co mmands
The sudo rule can grant acce s s or de ny acce s s to commands . For e xample , this rule
would allow re ad acce s s to file s but pre ve nt e diting:
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa sudorule-add-allow-command --sudocmds
"/usr/bin/less" readfiles
[jsmith@server ~]$ ipa sudorule-add-allow-command --sudocmds
"/usr/bin/tail" readfiles
[jsmith@server ~]$ ipa sudorule-add-deny-command --sudocmds
"/usr/bin/vim" readfiles

Example 21.3. Using sudo ers Opt io ns
The sudoers file has a lot of pote ntial flags that can be s e t to control the be havior of
sudo us e rs . The comple te lis t of options is in the s udoe rs (5) man page .
Any of the s e options can be s e t for the IdM sudo rule us ing the sudorule-add-option
command. Whe n the command is run, it prompts for the option to add:
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa sudorule-add-option readfiles
Sudo Option: !authenticate
----------------------------------------------------Added option "!authenticate" to Sudo rule "readfiles"
-----------------------------------------------------

No te
As de s cribe d in Se ction 21.3.2, “About s udo Options Format”, do not us e options with
white s pace in the value s . Rathe r than adding a lis t of options in one line , add a
s ingle option s e tting for e ach de s ire d option.

Example 21.4. Running as Ot her Users
The sudo rule als o has the option of s pe cifying a non-root us e r or group to run the
commands as . The initial rule has the us e r or group s pe cifie d us ing the --sudoruleadd-runasuser or --sudorule-add-runasgroup command, re s pe ctive ly.
$ ipa sudorule-add-runasuser --users=jsmith readfiles
$ ipa sudorule-add-runasgroup --groups=ITadmins readfiles

328

⁠C hapt e r 21. Us ing s udo

Whe n cre ating a rule , the sudorule-add-runasuser or sudorule-add-runasgroup
command can only s e t specific us e rs or groups . Howe ve r, whe n e diting a rule , it is
pos s ible to run sudo as all us e rs or all groups by us ing the --runasusercat or -runasgroupcat option. For e xample :
$ ipa sudorule-mod --runasgroupcat=all ruleName

No te
The --sudorule-add-runasuser and --sudorule-add-runasgroup commands do
not s upport an all option, only s pe cific us e r or group name s . Spe cifying all us e rs or
all groups can only be us e d with options with the sudorule-mod command.

Example 21.5. Ref erencing Ext ernal Users
The "who" in a sudo rule can be an IdM us e r, but the re are many logical and us e ful
rule s whe re one of the re fe re nts is a s ys te m us e r. Similarly, a rule may ne e d to grant
or de ny acce s s to a hos t machine on the ne twork which is not an IdM clie nt.
In thos e cas e s , the sudo policy can re fe r to an external us e r — an ide ntity cre ate d and
s tore d outs ide of IdM (Se ction 21.3.1, “About Exte rnal Us e rs ”).
The options to add an e xte rnal ide ntity to a sudo rule are :
--e xte rnalus e r
--runas e xte rnalus e r
For e xample :
$ ipa sudorule-add-user --externaluser=ITAdmin readfiles
$ ipa sudorule-add-runasuser --runasexternaluser=root readfiles

T able 21.1. sudo Co mmands
Co mmand

Descript io n

s udorule -add
s udorule -add-us e r

Add a s udo rule e ntry.
Add a us e r or a us e r group to the s udo
rule . This us e r (or e ve ry me mbe r of the
group) is the n e ntitle d to s udo any of the
commands in the rule .
Add a targe t hos t for the rule . The s e are
the hos ts whe re the us e rs are grante d
s udo pe rmis s ions .
Se t a group to run the s udo commands as .
This mus t be a s pe cific us e r; to s pe cify all
us e rs , modify the rule us ing sudo-rule.
Se t a us e r to run the s udo commands as .
This mus t be a s pe cific us e r; to s pe cify all
us e rs , modify the rule us ing sudo-rule.

s udorule -add-hos t

s udorule -add-runas group

s udorule -add-runas us e r

329

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Co mmand

Descript io n

s udorule -add-allow-command

Add a command that us e rs in the rule have
s udo pe rmis s ion to run.
Add a command that us e rs in the rule are
e xplicitly denied s udo pe rmis s ion to run.
Add a s udoe rs flag to the s udo rule .
Te mporarily de activate a s udo rule e ntry.
Activate a pre vious ly s us pe nde d s udo rule .
Re move a s udo rule e ntire ly.

s udorule -add-de ny-command
s udorule -add-option
s udorule -dis able
s udorule -e nable
s udorule -de l

21.3.5. Suspending and Removing sudo Rules
De fine d sudo rule s can e ithe r be te mporarily de activate d or e ntire ly de le te d from the
we b UI or from the command line . Sus pe nde d rule s are re move d from the ou=sudoers
compat tre e without a ne e d for a s e rve r re s tart.

Suspending and Removing sudo Rules f rom t he Web UI
To s us pe nd or comple te ly de le te a rule from the we b UI, us e the Disable or Delete
buttons at the top of the lis t of sudo rule s :

Figure 21.14. Suspending o r Delet ing a sudo Rule f ro m t he Web UI

Suspending and Removing sudo Rules f rom t he Command Line
To s us pe nd a rule from the command line , run a command s uch as the following:
ipa sudorule-disable files-commands
To comple te ly de le te a rule from the command line , run a command s uch as the following:
ipa sudorule-del files-commands

21.4. Configuring Host s t o Use IdM sudo Policies

330

⁠C hapt e r 21. Us ing s udo

Actually imple me nting sudo policie s is more complicate d than s imply cre ating the rule s in
IdM. Thos e rule s ne e d to be applie d to e ve ry local machine , which me ans that e ach
s ys te m in the IdM domain has to be configure d to re fe r to IdM for its policie s .
You can apply sudo policie s to hos ts us ing SSSD or LDAP. Re d Hat s trongly re comme nds
to us e the SSSD-bas e d configuration.

21.4.1. Applying t he sudo Policies t o Host s Using SSSD
1. Se t up the hos t and sudo e ntrie s in IdM.
a. Se t up the sudo commands and command groups , as de s cribe d in
Se ction 21.2, “Se tting up s udo Commands and Command Groups ”.
b. Se t up the sudo rule s , as de s cribe d in Se ction 21.3, “De fining sudo Rule s ”.
c. Optional. Se t up a hos t group, as de s cribe d in Se ction 13.7, “Managing Hos t
Groups ”.
d. Optional. Cre ate a us e r group and add the us e rs , as de s cribe d in
Se ction 9.10.2.1, “Cre ating Us e r Groups ”.
2. Configure e ve ry s ys te m in the IdM domain to us e SSSD for sudo rule s .

No te
Only pe rform this s te p on s ys te ms bas e d on Re d Hat Ente rpris e Linux 7.0. In
Re d Hat Ente rpris e Linux 7.1 and late r, the ipa-client-install utility
configure s SSSD as the data provide r for sudo automatically.
a. Configure sudo to look to SSSD for the sudoers file .
vim /etc/nsswitch.conf
sudoers:

files sss

Le aving the files option in place allows sudo to che ck its local configuration
be fore che cking SSSD for the IdM configuration.
b. Add sudo to the lis t of s e rvice s manage d by the local SSSD clie nt.
[root@server ~]# vim /etc/sssd/sssd.conf
[sssd]
config_file_version = 2
services = nss, pam, sudo
domains = IPADOMAIN
c. Se t a name for the NIS domain in the sudo configuration. sudo us e s NIS-s tyle
ne tgroups , s o the NIS domain name mus t be s e t in the s ys te m configuration
for sudo to be able to find the hos t groups us e d in the IdM sudo
configuration.
a. Enable the rhel-domainname s e rvice if it is not alre ady e nable d to
e ns ure that the NIS domain name will be pe rs is te nt acros s re boots .

331

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@server ~]# systemctl enable rheldomainname.service
b. Se t the NIS domain name to us e with the sudo rule s .
[root@server ~]# nisdomainname example.com
c. Configure the s ys te m authe ntication s e ttings to pe rs is t the NIS
domain name . For e xample :
[root@server ~]# echo "NISDOMAIN=example.com.com" >>
/etc/sysconfig/network
This update s the /etc/sysconfig/network and /etc/yp.conf file s
with the NIS domain.
3. Optionally, e nable de bugging in SSSD to s how what LDAP s e ttings it is us ing.
[domain/IPADOMAIN]
debug_level = 6
....
The LDAP s e arch bas e us e d by SSSD for ope rations is re corde d in the
sssd_DOMAINNAME.log log.

21.4.2. Applying t he sudo Policies t o Host s Using LDAP

Impo rtant
Only us e the LDAP-bas e d configuration for clie nts that do not us e SSSD. Re d Hat
re comme nds to configure all othe r clie nts us ing the SSSD-bas e d configuration, as
de s cribe d in Se ction 21.4.1, “Applying the sudo Policie s to Hos ts Us ing SSSD”.
For information on applying sudo policie s us ing LDAP, s e e the Ide ntity Manage me nt Guide
for Re d Hat Ente rpris e Linux 6.
The LDAP-bas e d configuration is e xpe cte d to be us e d primarily for clie nts bas e d on
Re d Hat Ente rpris e Linux ve rs ions e arlie r than Re d Hat Ente rpris e Linux 7. It is the re fore
only de s cribe d in the docume ntation for Re d Hat Ente rpris e Linux 6.

332

⁠C hapt e r 21. Us ing s udo

Chapt er 22. Configuring Host -Based Access Cont rol
IdM can control acce s s to both machine s and the s e rvice s on thos e machine s within the
IdM domain. The rule s de fine who can acce s s what within the domain, not the le ve l of
acce s s (which are de fine d by s ys te m or application s e ttings ). The s e acce s s control rule s
grant acce s s , with all othe r us e rs and hos ts implicitly de nie d.
This is calle d host-based access control be caus e the rule de fine s what hos ts (targets)
within the domain a us e r is allowe d to acce s s . This acce s s can be furthe r broke n down to
us e rs and s e rvice s on thos e hos ts .

No te
Us ing hos t-bas e d acce s s control re quire s SSSD to be ins talle d and configure d on
the IdM clie nt machine .

22.1. About Host -Based Access Cont rol
Hos t-bas e d acce s s control rule s can be applie d to individual hos ts . Howe ve r, us ing hos t
groups allows ce ntraliz e d, and pote ntially s implifie d, acce s s control manage me nt be caus e
an acce s s control rule only ne e ds to be de fine d once and the n it is applie d imme diate ly
and cons is te ntly to all the hos ts within the group.

Figure 22.1. Ho st Gro ups and Ho st -Based Access Co nt ro l

No te
While acce s s mus t be e xplicitly grante d to us e rs and hos ts within the IdM domain,
IdM s e rve rs are configure d by de fault with an allow all acce s s control rule which
allows acce s s for e ve ry hos t within the domain to e ve ry hos t within the domain.
To cre ate an IdM s e rve r without the de fault allow all rule , run ipa-serverinstall with the --no_hbac_allow option.

The rule firs t de fine s things that can be acce s s e d, and the re are two type s of e ntitie s :

333

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Hosts, or targe t hos ts , within the IdM domain.
Services on the targe t hos ts . Multiple s e rvice s can be combine d into service groups.
The s e rvice group can be modifie d without having to e dit the acce s s control rule its e lf.
The rule als o s e ts who can have access (the IdM domain us e r).

No te
It is pos s ible to us e cate gorie s for us e rs and targe t hos ts ins te ad of adding e ach
one individually to the acce s s control rule . The only s upporte d cate gory is all.
The e ntitie s in hos t-bas e d acce s s control rule s follow the Ke rbe ros principal e ntrie s :
us e rs , hos ts (machine s ), and s e rvice s . Us e rs and targe t hos ts can be adde d dire ctly to
hos t-bas e d acce s s control rule s . Howe ve r, s e rvice s mus t be adde d to the hos t-bas e d
acce s s control configuration firs t to make it available to rule s , and the n adde d to the
acce s s control rule s .

22.2. Creat ing Host -Based Access Cont rol Ent ries for
Services and Service Groups
Any PAM s e rvice can be adde d to the hos t-bas e d acce s s control (HBAC) s ys te m in IdM.
The s e rvice e ntrie s us e d in hos t-bas e d acce s s control are s e parate from adding a
s e rvice to the IdM domain. Adding a s e rvice to the domain make s it a re cogniz e d re s ource
which is available to othe r re s ource s . Adding a domain re s ource to the hos t-bas e d acce s s
control configuration allows adminis trators to e xe rt de fine d control ove r what domain
us e rs and what domain clie nts can acce s s that s e rvice .
Some common s e rvice s are alre ady configure d as HBAC s e rvice s , s o the y can be us e d in
hos t-bas e d acce s s control rule s . Additional s e rvice s can be adde d, and s e rvice s can be
adde d into s e rvice groups for s imple r manage me nt.

22.2.1. Adding HBAC Services
22.2.1.1. Adding HBAC Services in t he Web UI
1. Click the Policy tab.
2. Click the Host-Based Access Control s ubtab, and the n s e le ct the HBAC Services
link.
3. Click the Add link at the top of the lis t of s e rvice s .

334

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

4. Ente r the s e rvice name and a de s cription.

5. Click the Add button to s ave the ne w s e rvice .
6. If a s e rvice group alre ady e xis ts , the n add the s e rvice to the de s ire d group, as
de s cribe d in Se ction 22.2.2.1, “Adding Se rvice Groups in the We b UI”.

22.2.1.2. Adding Services in t he Command Line
The s e rvice is adde d to the acce s s control s ys te m us ing the hbacsvc-add command,
s pe cifying the s e rvice by the name that PAM us e s to e valuate the s e rvice .
For e xample , this adds the tftp s e rvice :
# ipa hbacsvc-add --desc="TFTP service" tftp
------------------------Added HBAC service "tftp"
------------------------Service name: tftp
Description: TFTP service

335

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

If a s e rvice group alre ady e xis ts , the n the s e rvice can be adde d to the group us ing the
hbacsvcgroup-add-member command, as in Se ction 22.2.2.2, “Adding Se rvice Groups in
the Command Line ”.

22.2.2. Adding Service Groups
Once the individual s e rvice is adde d, it can be adde d to the acce s s control rule . Howe ve r,
if the re is a large numbe r of s e rvice s , the n it can re quire fre que nt update s to the acce s s
control rule s as s e rvice s change . Ide ntity Manage me nt als o allows groups of s e rvice s to
be adde d to acce s s control rule s . This make s it much e as ie r to manage acce s s control,
be caus e the me mbe rs of the s e rvice group can be change d without having to e dit the rule
its e lf.

22.2.2.1. Adding Service Groups in t he Web UI
1. Click the Policy tab.
2. Click the Host-Based Access Control s ubtab, and the n s e le ct the HBAC Service
Groups link.
3. Click the Add link at the top of the lis t of s e rvice groups .

4. Ente r the s e rvice group name and a de s cription.

336

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

5. Click the Add and Edit button to go imme diate ly to the s e rvice group configuration
page .
6. At the top of the HBAC Services tab, click the Add link.

7. Click the che ckbox by the name s of the s e rvice s to add, and click the right arrows
button, >>, to move the command to the s e le ction box.

8. Click the Add button to s ave the group me mbe rs hip.

22.2.2.2. Adding Service Groups in t he Command Line

337

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Firs t cre ate the s e rvice group e ntry, the n cre ate the s e rvice , and the n add that s e rvice to
the s e rvice group as a me mbe r. For e xample :
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa hbacsvcgroup-add --desc="login services" login
-------------------------------Added HBAC service group "login"
-------------------------------Service group name: login
Description: login services
[jsmith@server ~]$ ipa hbacsvc-add --desc="SSHD service" sshd
------------------------Added HBAC service "sshd"
------------------------Service name: sshd
Description: SSHD service
[jsmith@server ~]$ ipa hbacsvcgroup-add-member --hbacsvcs=sshd login
Service group name: login
Description: login services
------------------------Number of members added 1
-------------------------

No te
IdM de fine s two de fault s e rvice groups : SUDO for s udo s e rvice s and FTP for s e rvice s
which provide FTP acce s s .

22.3. Defining Host -Based Access Cont rol Rules
Acce s s controls , at a high le ve l, de fine who has acce s s to what. The who is an IdM us e r,
and the what can be e ithe r a hos t (targe t hos t), s e rvice , or s e rvice group, or a combination
of the thre e .

22.3.1. Set t ing Host -Based Access Cont rol Rules in t he Web UI
1. Click the Policy tab.
2. Click the Host-Based Access Control s ubtab, and the n s e le ct the HBAC Rules
link.
3. Click the Add link at the top of the lis t of hos t-bas e d acce s s control rule s .

338

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

4. Ente r the name for the rule .

5. Click the Add and Edit button to go imme diate ly to s e t the configuration for the
rule .
The re are a numbe r of configuration are as for the rule . The thre e bas ic e le me nts
are who the rule applie s to, what hos ts allow acce s s (the targe t), and, optionally,
what s e rvice s can be acce s s e d.
6. In the Who are a, s e le ct the us e rs or us e r groups to which the acce s s control rule is
applie d.
To apply the rule to all IdM us e rs , s e le ct the Anyone radio button.
To apply the rule to a s pe cific s e t of us e rs or us e r groups :
a. Se le ct the Specified Users and Groups radio button.
b. Click the + Add link at the right of the us e rs lis t.

c. Click the che ckbox by the us e rs to add to the rule , and click the right arrows
button, >>, to move the us e rs to the s e le ction box.

339

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

button, >>, to move the us e rs to the s e le ction box.

d. Click Add.
7. In the Accessing are a, s e le ct the targe t hos ts which can be acce s s e d through this
acce s s control rule .
To apply the rule to all IdM hos ts , s e le ct the Any Host radio button.
To apply the rule to a s pe cific s e t of hos ts or hos t groups :
a. Se le ct the Specified Hosts and Groups radio button.
b. Click the + Add link at the right of the hos ts lis t.

c. Click the che ckbox by the hos ts to include with the rule , and click the right
arrows button, >>, to move the hos ts to the s e le ction box.

340

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

d. Click Add.
8. In the Via Service are a, s e le ct s pe cific s e rvice s on the targe t hos ts which the
us e rs are allowe d to us e to acce s s targe t machine s .
To apply the rule to all IdM hos ts , s e le ct the Any Service radio button.
To apply the rule to a s pe cific s e t of hos ts or hos t groups :
a. Se le ct the Specified Services and Groups radio button.
b. Click the + Add link at the right of the commands lis t.

c. Click the che ckbox by the s e rvice s or groups to include with the rule , and
click the right arrows button, >>, to move the s e rvice s to the s e le ction box.

341

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

d. Click Add.

22.3.2. Set t ing Host -Based Access Cont rol Rules in t he Command Line
Acce s s control rule s are cre ate d us ing the hbacrule-* commands (lis te d in Table 22.1,
“Hos t-Bas e d Acce s s Control Command and Options ”). The firs t s te p is to cre ate a
containe r e ntry; from the re , us e rs , hos ts , and s e rvice s can be adde d to the acce s s control
e ntry.
The bas ic outline of all the acce s s control commands is :
$ ipa hbacrule-add* options ruleName

No te
To s e t e ve ry us e r or e ve ry hos t as a targe t, us e the cate gory options , s uch as -usercat=all.

Example 22.1. Grant ing All Access t o One Ho st
One s imple rule is to grant e ve ry us e r acce s s to a s ingle s e rve r. The firs t command
cre ate s the e ntry and us e s the cate gory options to apply e ve ry us e r.
$ ipa hbacrule-add --usercat=all allGroup
-------------------------Added HBAC rule "allGroup"
-------------------------Rule name: allGroup
User category: all
Enabled: TRUE

342

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

The s e cond command adds the targe t hos t to the HBAC rule :
$ ipa hbacrule-add-host --hosts=server.example.com allGroup
Rule name: allGroup
User category: all
Enabled: TRUE
Successful hosts/hostgroups:
member host: server.example.com
------------------------Number of members added 1
-------------------------

Example 22.2. Adding Co nt ro l f o r a Single User t o a Service
Anothe r acce s s control me thod is to s pe cify which s e rvice s us e rs are allowe d to us e to
acce s s the targe t hos ts .
Firs t, for the us e r to have acce s s to e ve ry machine , e ve ry hos t mus t be adde d as both
a hos t and targe t. This can be done us ing the cate gory options :
$ ipa hbacrule-add --hostcat=all sshd-jsmith
Since the acce s s control rule applie s to a s pe cific us e r, the us e r is adde d to the rule
us ing the hbacrule-add-user command:
$ ipa hbacrule-add-user --users=jsmith sshd-jsmith
The n, the s e rvice is adde d to the acce s s control rule . (The s e rvice s hould have alre ady
be e n adde d to the acce s s control s ys te m us ing the hbacsvc-add command.) This is the
s e rvice that the us e r can us e to conne ct to the machine .
$ ipa hbacrule-add-service --hbacsvcs=sshd sshd-jsmith

Example 22.3. Adding a Service Gro up t o t he Rule
While a s ingle s e rvice can be adde d to a rule , it is als o pos s ible to add an e ntire
s e rvice group. Like a s ingle s e rvice , this us e s the hbacrule-add-service command,
only with the --hbacsvcgroups option that s pe cifie s the group name .
$ ipa hbacrule-add-service --hbacsvcgroups=login loginRule

T able 22.1. Ho st -Based Access Co nt ro l Co mmand and Opt io ns
Co mmand

Descript io n

Argument s

So urce o r T arget
Ent ry

343

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Co mmand

Descript io n

hbacrule -add

Adds a ne w hos tbas e d acce s s
control rule .

hbacrule -add-hos t

Adds a targe t hos t
to the acce s s control
rule . A targe t hos t
can be acce s s e d by
othe r s e rve rs and
us e rs in the domain.

344

Argument s

So urce o r T arget
Ent ry

--us e rcat=all,
which applie s the
rule to e ve ry
us e r
--hos tcat=all,
which s e ts e ve ry
hos t as an
allowe d targe t
s e rve r
--s e rvice cat=all,
which s e ts e ve ry
configure d
s e rvice as an
allowe d targe t
s e rvice
ruleName, which
is the re quire d
unique ide ntifie r
for the ne w rule

--hos ts , which
adds an individual
s e rve r or commas e parate d lis t of
s e rve rs as an
allowe d targe t
s e rve r
--hos tgroups ,
which adds a hos t
group to the rule
and e ve ry hos t
within the hos t
group is an
allowe d targe t
s e rve r
ruleName, which
is the rule to
which to add the
targe t s e rve r

Targe t

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

Co mmand

Descript io n

hbacrule -adds e rvice

Adds a s e rvice type
to the rule .

Argument s

--hbacs vcs , which
adds an individual
s e rvice type or a
lis t of s e rvice
type s as an
allowe d targe t
s e rvice

So urce o r T arget
Ent ry
Targe t

Lis ts of e ntrie s
can be s e t by
us ing the option
multiple time s
with the s ame
command
invocation or by
lis ting the options
in a commas e parate d lis t
ins ide curly
brace s , s uch as -option=
{val1,val2,val3}.
--hbacs vcgroups ,
which adds a
s e rvice group to
the rule and
e ve ry s e rvice
within the s e rvice
group is an
allowe d targe t
s e rvice
Lis ts of e ntrie s
can be s e t by
us ing the option
multiple time s
with the s ame
command or by
lis ting the options
in a commas e parate d lis t
ins ide curly
brace s , s uch as -option=
{val1,val2,val3}.
ruleName, which
is the rule to
which to add the
targe t s e rvice

345

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Co mmand

Descript io n

hbacrule -add-us e r

Adds a us e r to the
acce s s control rule .
The us e r is the n
able to acce s s any
allowe d targe t hos t
or s e rvice within the
domain.

hbacrule -dis able |
hbacrule -e nable

Dis able s or e nable s
a hos t-bas e d acce s s
control rule . Rule s
can be dis able d if
the ir be havior
ne e ds to be
e valuate d (for
trouble s hooting or to
te s t a ne w rule ).

Argument s

--us e rs , which
adds an individual
us e r or commas e parate d lis t of
us e rs to the rule
--groups , which
adds a us e r
group to the rule
and, thus , e ve ry
us e r within the
group
ruleName, which
is the rule to
which to add the
us e r

So urce o r T arget
Ent ry
Source

ruleName, which is
the rule to dis able or
e nable

22.4. T est ing Host -Based Access Cont rol Rules
Imple me nting hos t-bas e d acce s s controls e ffe ctive ly can be tricky be caus e it re quire s
that all of the hos ts be prope rly configure d and the acce s s is prope rly applie d to us e rs
and s e rvice s .
The hbactest command can te s t diffe re nt hos t-bas e d acce s s control s ce narios to make
s ure that the rule s are working as e xpe cte d.

No te
The hbactest command doe s not work with trus te d Active Dire ctory us e rs .
Active Dire ctory us e r/group as s ociations are de te rmine d dynamically, as a us e r
logs in, and thos e data are not s tore d in the IdM LDAP dire ctory. The hbactest
command, the n, is unable to re s olve the group me mbe rs hips to che ck how acce s s
control rule s will be applie d.

22.4.1. T he Limit s of Host -Based Access Cont rol Conf igurat ion
The acce s s control configuration s hould always be te s te d be fore it is imple me nte d to
pre ve nt authoriz ation failure s .
Hos t-bas e d acce s s control rule s de pe nd on a lot of inte ractions — be twe e n hos ts ,
s e rvice s , DNS lookups , and us e rs . If any e le me nt is mis configure d, the n the rule can

346

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

be have in une xpe cte d ways .
Ide ntity Manage me nt include s a te s ting tool to ve rify that acce s s control rule s are
be having in the e xpe cte d way by te s ting the acce s s in a de fine d s ce nario. The re are
s e ve ral s ituations whe re this te s ting is us e ful:
A ne w rule ne e ds to be te s te d be fore it is imple me nte d.
The re are proble ms with the e xis ting rule s , and the te s ting tool can ide ntify what rule
is be having badly.
A s ubs e t of e xis ting rule s can be te s te d to s e e how the y are pe rforming.

22.4.2. T est Scenarios f or Host -Based Access Cont rol (CLI-Based)

No te
The hbactest command doe s not work with trus te d Active Dire ctory us e rs .
Active Dire ctory us e r/group as s ociations are de te rmine d dynamically, as a us e r
logs in, and thos e data are not s tore d in the IdM LDAP dire ctory. The hbactest
command, the n, is unable to re s olve the group me mbe rs hips to che ck how acce s s
control rule s will be applie d.
The hbactest command te s ts configure d hos t-bas e d acce s s control rule s in ve ry s pe cific
s ituations . A te s t run de fine s :
The us e r to run the ope ration as to te s t the rule pe rformance for that us e r (--user).
Us ing the login clie nt Y (--service).
To targe t hos t Z (--host).
The rule to te s t (--rules); if this is not us e d, the n all e nable d rule s are te s te d.
Optional The hbactest re turns de taile d information about which rule s we re matche d,
not matche d, or invalid. This de taile d rule output can be dis able d us ing --nodetail, s o
the te s t s imply runs and re turns whe the r acce s s was grante d.

No te
The hbactest s cript doe s not actually conne ct to the targe t hos t. Ins te ad, it us e s the
rule s within the IdM databas e to s imulate how thos e rule s would be applie d in a
s pe cific s ituation as if an SSSD clie nt we re conne cting to the IdM s e rve r.
More brie fly, it pe rforms a s imulate d te s t run bas e d on the give n information and
configuration, but it doe s not actually atte mpt a s e rvice re que s t agains t the targe t
hos t.

Example 22.4. T est ing All Act ive Rules

347

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The mos t bas ic command che cks all active rule s . It re quire s a s pe cific conne ction
s ce nario, s o the us e r, login s e rvice and targe t hos t have to be give n, and the te s ting
tool che cks the conne ction.
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa hbactest --user=jsmith -host=target.example.com --service=ssh
-------------------Access granted: True
-------------------Matched rules: allow_all
Matched rules: sshd-jsmith
Matched rules: web-rules
Not matched rules: allGroup

Example 22.5. T est ing a Specif ic Rule
It is pos s ible to che ck a s pe cific rule (or s e ve ral rule s ).
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa hbactest --user=jsmith -host=target.example.com --service=ssh --rules=myrule
--------------------Access granted: True
--------------------notmatched: myrule

Example 22.6. T est ing Specif ic Rules Plus All Enabled
The --rules option lis ts s pe cific rule s to te s t, but it may be us e ful to te s t the s pe cifie d
rule s agains t all of the e nable d rule s in the domain. This can be done by adding the -enabled option, which include s the (uns pe cifie d) e nable d rule s along with the s pe cifie d
rule s .
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa hbactest --user=jsmith -host=target.example.com --service=ssh --rules=myrule --enabled
-------------------Access granted: True
-------------------matched: my-second-rule
notmatched: my-third-rule
matched: myrule
matched: allow_all
It is pos s ible to run a s imilar comparis on agains t disabled rule s by us ing the -disabled option. With the --rules option, the s pe cifie d rule plus all of the dis able d
rule s are che cke d. With the --disabled option, all dis able d rule s are che cke d.

22.4.3. T est ing Host -Based Access Cont rol Rules in t he UI

348

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

As Se ction 22.4.1, “The Limits of Hos t-Bas e d Acce s s Control Configuration” de tails ,
mis configuring a hos t-bas e d acce s s -control rule can re s ult in unpre dictable be havior whe n
us e rs or s e rvice s atte mpt to conne ct to a re mote hos t.
Te s ting hos t-bas e d acce s s control can he lp confirm that the rule pe rforms as e xpe cte d
be fore it is de ploye d or to trouble s hoot a rule once it is alre ady active .

No te
The hbactest command doe s not work with trus te d Active Dire ctory us e rs .
Active Dire ctory us e r/group as s ociations are de te rmine d dynamically, as a us e r
logs in, and thos e data are not s tore d in the IdM LDAP dire ctory. The hbactest
command, the n, is unable to re s olve the group me mbe rs hips to che ck how acce s s
control rule s will be applie d.
By the nature of hos t-bas e d acce s s control rule s , a te s t mus t de fine and ve rify a ve ry
s pe cific s e t of crite ria. A te s t run de fine s :
The us e r to run the ope ration as to te s t the rule pe rformance for that us e r (Who).
To targe t hos t Z (Accessing).
Us ing the login clie nt Y (Via Service).
The rule to te s t; if this is not us e d, the n all e nable d rule s are te s te d (Rules).
The te s t e nvironme nt is de fine d on the HBAC TEST page in the Host Based Access
Control tab unde r Policy. A s e rie s of tabs is s e t up for e ach configuration s te p.

Figure 22.2. T he Fro m T ab t o Set up an HBAC T est

349

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Once the e nvironme nt is de fine d, the n the te s t is run s imply by clicking a button on the
Run Test page . The re s ults s how whe the r acce s s was grante d or de nie d to the us e rs and
als o dis play the rule s which matche d the give n parame te rs .

Figure 22.3. HBAC T est Result s

No te
To change s ome of the parame te rs and che ck for othe r re s ults , click the New Test
button at the bottom of the te s t re s ults page . If that button is not s e le cte d, the form
is not re s e t, s o a ne w te s t will not run, e ve n if te s t s e ttings are change d.

350

⁠C hapt e r 22. Co nf igur ing Ho s t -Bas e d Ac c e s s Co nt r o l

Chapt er 23. Defining SELinux User Maps
Se curity-e nhance d Linux (SELinux) s e ts rule s ove r what s ys te m us e rs can acce s s
proce s s e s , file s , dire ctorie s , and s ys te m s e ttings . Both the s ys te m adminis trator and
s ys te m applications can de fine security contexts that re s trict or allow us e r acce s s and
e ve n acce s s from othe r applications .
As part of de fining ce ntraliz e d s e curity policie s in the Ide ntity Manage me nt domain,
Ide ntity Manage me nt provide s a way to map IdM us e rs to (e xis ting) SELinux us e r conte xts
and grant or re s trict acce s s to clie nts and s e rvice s within the IdM domain, pe r hos t, bas e d
on the de fine d SELinux policie s .

23.1. About Ident it y Management , SELinux, and Mapping
Users
No te
Ide ntity Manage me nt doe s not cre ate or modify the SELinux conte xts on a s ys te m.
Rathe r, it us e s e xis ting conte xts as the bas is to map IdM us e rs (in the domain) to
SELinux us e rs (on a s ys te m).
Se curity-e nhance d Linux de fine s ke rne l-le ve l, mandatory acce s s controls for how us e rs ,
proce s s e s , and applications can inte ract with othe r re s ource s on a s ys te m. The s e rule s
for inte ractions , calle d contexts, look at the data and be havior characte ris tics of diffe re nt
obje cts on the s ys te m and the n s e t rule s , calle d policies, bas e d on the s e curity
implications of e ach s pe cific obje ct. This is in contras t to highe r-le ve l dis cre tionary acce s s
controls which are conce rne d primarily with file owne rs hip and us e r ide ntity, without
accounting for data criticality or application be havior. Eve ry re s ource on a s ys te m (us e rs ,
applications , file s , proce s s e s ) is as s igne d a conte xt.
Sys te m us e rs are as s ociate d with an SELinux role. The role is as s igne d both a multi-laye r
s e curity conte xt (MLS) and a multi-cate gory s e curity conte xt (MCS). The MLS/MCS conte xts
confine us e rs to what proce s s e s , file s , and ope rations the y can acce s s on the s ys te m.

351

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 23.1. SELinux Users in t he SELinux Manager
This is all de s cribe d in de tail in Re d Hat Ente rpris e Linux 6 Se curity-Enhance d Linux.
SELinux us e rs and policie s function at the s ys te m le ve l, not the ne twork le ve l. This me ans
that SELinux us e rs are configure d inde pe nde ntly on e ach s ys te m. While this is acce ptable
in many s ituations — SELinux has common de fine d s ys te m us e rs and SELinux-aware
s e rvice s de fine the ir own policie s — it has s ome is s ue s whe n de aling with re mote us e rs
and s ys te ms that acce s s local re s ource s . Re mote us e rs and s e rvice s can ge t s huffle d
into a de fault gue s t conte xt without a lot of inte llige nce about what the ir actual SELinux
us e r and role s hould be .
This is how Ide ntity Manage me nt can cle anly inte grate an ide ntity domain with local
SELinux s e rvice s . Ide ntity Manage me nt can map IdM us e rs to configure d SELinux role s per
host. Mapping SELinux and IdM us e rs improve s us e r adminis tration:
Re mote us e rs can be grante d appropriate SELinux us e r conte xts bas e d on the ir IdM
group as s ignme nts . This als o allows adminis trators to cons is te ntly apply the s ame
policie s to the s ame us e rs without having to cre ate local accounts or re configure
SELinux.
SELinux us e rs are automatically update d as hos ts are adde d to the IT e nvironme nt or
as us e rs are adde d, re move d, or change d, without having to e dit local s ys te ms .
SELinux policie s can be planne d and re late d to domain-wide s e curity policie s through
s e ttings like IdM hos t-bas e d acce s s control rule s .
Adminis trators gain e nvironme nt-wide vis ibility and control ove r how us e rs and
s ys te ms are as s igne d in SELinux.

352

⁠C hapt e r 23. De f ining SELinux Us e r Maps

SELinux us e r maps are compris e d of thre e parts : the SELinux us e r for the s ys te m, an IdM
us e r, and an IdM hos t. The s e de fine two s e parate re lations hips . Firs t, it de fine s a map for
the SELinux us e r on a s pe cific hos t (the local or targe t s ys te m). Se cond, it de fine s a map
for the SELinux us e r and the IdM us e r.
This arrange me nt allows adminis trators to s e t diffe re nt SELinux us e rs for the s ame IdM
us e rs , de pe nding on which hos t the y are acce s s ing.
SELinux us e r maps work with the Sys te m Se curity Se rvice s Dae mon (SSSD) and the
pam_selinux module . Whe n a re mote us e r atte mpts to log into a machine , SSSD che cks
its IdM ide ntity provide r to colle ct the us e r information, including any SELinux maps . The
PAM module the n proce s s e s the us e r and as s igns it the appropriate SELinux us e r conte xt.
The core of an SELinux mapping rule is the SELinux s ys te m us e r. Each map is as s ociate d
with the SELinux us e r firs t. The SELinux us e rs which are available for mapping are
configure d in the IdM s e rve r, s o the re is a ce ntral and unive rs al lis t. The s e are SELinux
us e rs which are configure d on e ve ry hos t in the IdM domain. By de fault, the re are five
common SELinux us e rs de fine d:
unconfine d_u (als o us e d as a de fault for IdM us e rs )
gue s t_u
xgue s t_u
us e r_u
s taff_u
In the IdM s e rve r configuration, e ach SELinux us e r is configure d with both its us e rname
and its MLS/MCS range , SELinux_username:MLS[:MCS], and this format is us e d to ide ntify
the SELinux us e r whe n configuring maps .
The IdM us e r and hos t configuration is ve ry fle xible . Us e rs and hos ts can be e xplicitly and
individually as s igne d to an SELinux us e r map, or us e r groups or hos t groups can be
e xplicitly as s igne d to the map.
An e xtra laye r of s e curity is pos s ible by us ing hos t-bas e d acce s s control rule s . As long as
the hos t-bas e d acce s s control rule de fine s a us e r and a hos t, it can be us e d for an
SELinux us e r map. Hos t-bas e d acce s s control rule s (de s cribe d in Chapte r 22, Configuring
Host-Based Access Control) he lp inte grate SELinux us e r maps with othe r acce s s controls in
IdM and can he lp limit or allow hos t-bas e d us e r acce s s for re mote us e rs , as we ll as
de fining local s e curity conte xts .

No te
If a hos t-bas e d acce s s control rule is as s ociate d with an SELinux us e r map, the hos tbas e d acce s s control rule cannot be de le te d until it is re move d from the SELinux
us e r map configuration.

23.2. Configuring SELinux User Map Order and Default s
SELinux us e r maps , as the name implie s , cre ate s an as s ociation be twe e n an SELinux us e r
and an IdM us e r. Be fore that as s ociation can be e s tablis he d, the IdM s e rve r has to be
aware of the unde rlying SELinux us e rs configuration on the s ys te ms it manage s .

353

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The available system SELinux us e r maps are part of the IdM s e rve r configuration. This is a
lis t, in orde r from mos t to le as t confine d, of the SELinux us e rs . The SELinux us e r e ntry
its e lf has this format:
SELinux_username:MLS[:MCS]
The individual us e r e ntrie s are s e parate d with a dollar s ign ($).
Since the re is no re quire me nt on us e r e ntrie s to have an SELinux map, many e ntrie s may
be unmappe d. The IdM s e rve r configuration s e ts a de fault SELinux us e r (one of the us e rs
from the total SELinux map lis t) to us e for unmappe d IdM us e r e ntrie s . This way, e ve n
unmappe d IdM us e rs have a functional SELinux conte xt.

No te
This configuration de fine s the map orde r of available s ys te m SELinux us e rs . This
doe s not de fine any IdM us e r SELinux policie s . The IdM us e r - SELinux us e r map
mus t be de fine d and the n us e rs are adde d to the map, as in Se ction 23.3, “Mapping
SELinux Us e rs and IdM Us e rs ”.

23.2.1. In t he Web UI
1. In the top me nu, click the IPA Server main tab and the Configuration s ubtab.
2. Scroll to the bottom of the lis t of s e rve r configuration are as , to SELINUX OPTIONS.
3. Se t the SELinux us e r configuration.
The re are two are as that can be e dite d: the prioritiz e d lis t of SELinux us e rs and the
de fault SELinux us e r to us e for unmappe d IdM us e rs .
The SELinux user map order give s the lis t of SELinux us e rs , de fine d on the local
Linux s ys te m , which are available for configuring mapping rule s . This is a
prioritiz e d lis t, from mos t to le as t confine d. Each SELinux us e r has the format
SELinux_user:MLS.
The Default SELinux user fie ld s e ts the SELinux us e r to us e for unmapped IdM
us e rs .

354

⁠C hapt e r 23. De f ining SELinux Us e r Maps

4. Click the Update link at the top of the page to s ave the change s .

23.2.2. In t he CLI
Be fore SELinux mapping rule s can be cre ate d, the re has to be a de fine d and unive rs al lis t
of SELinux us e rs which are available to be mappe d. This is s e t in the IdM s e rve r
configuration:
[jsmith@server ~]$ ipa config-show
...
SELinux user map order: guest_u:s0$xguest_u:s0$user_u:s0$staff_u:s0s0:c0.c1023$unconfined_u:s0-s0:c0.c1023
Default SELinux user: unconfined_u:s0-s0:c0.c1023
The SELinux us e r s e ttings can be e dite d us ing the config-mod command.

Example 23.1. List o f SELinux Users
The comple te lis t of SELinux us e rs is pas s e d in the --ipaselinuxusermaporder option.
This lis t s e ts a priority orde r, from mos t to le as t confine d us e rs .
The SELinux us e r e ntry its e lf has this format:

355

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

SELinux_user:MLS:MCS
The individual us e r e ntrie s are s e parate d with a dollar s ign ($).
For e xample :
[jsmith@server ~]$ ipa config-mod -ipaselinuxusermaporder="unconfined_u:s0s0:c0.c1023$guest_u:s0$xguest_u:s0$user_u:s0-s0:c0.c1023$staff_u:s0s0:c0.c1023"

No te
The de fault SELinux us e r, us e d for unmappe d e ntrie s , mus t be include d in the us e r
map lis t or the e dit ope ration fails . Like wis e , if the de fault is e dite d, it mus t be
change d to a us e r in the SELinux map lis t or the map lis t mus t be update d firs t.

Example 23.2. Def ault SELinux User
IdM us e rs are not re quire d to have a s pe cific SELinux us e r mappe d to the ir account.
Howe ve r, the local s ys te m s till che cks the IdM e ntry for an SELinux us e r to us e for the
IdM us e r account. The de fault SELinux us e r s e ts the fallback us e r to us e for unmappe d
IdM us e r e ntrie s ; this is , by de fault, the de fault SELinux us e r for s ys te m us e rs on
Re d Hat Ente rpris e Linux, unconfined_u.
This de fault us e r can be change d with the --ipaselinuxusermapdefault. For e xample :
[jsmith@server ~]$ ipa config-mod -ipaselinuxusermapdefault="guest_u:s0"

23.3. Mapping SELinux Users and IdM Users
An SELinux map as s ociate s an SELinux us e r conte xt on a local s ys te m with an IdM us e r (or
us e rs ) within the domain. An SELinux map has thre e parts : the SELinux us e r conte xt and
an IdM us e r/hos t pairing. That IdM us e r/hos t pair can be de fine d in one of two ways : it can
be s e t for e xplicit us e rs on e xplicit hos ts (or us e r and hos t groups ), or it can be de fine d
us ing a hos t-bas e d acce s s control rule .

23.3.1. In t he Web UI
1. In the top me nu, click the Policy main tab and the SELinux User Mappings s ubtab.
2. In the lis t of mappings , click the Add button to cre ate a ne w map.

356

⁠C hapt e r 23. De f ining SELinux Us e r Maps

3. Ente r the name for the map and the SELinux us e r exactly as it appears in the IdM
server configuration. SELinux us e rs have the format SELinux_username:MLS[:MCS].

4. Click Add and Edit to add the IdM us e r information.
5. To s e t a hos t-bas e d acce s s control rule , s e le ct the rule from the drop-down me nu
in the General are a of the configuration. Us ing a hos t-bas e d acce s s control rule
als o introduce s acce s s controls on what hos ts a re mote us e r can us e to acce s s a
targe t machine . Only o ne ho st -based access co nt ro l rule can be assigned.

No te
The hos t-bas e d acce s s control rule mus t contain us e rs and hos ts , not jus t
s e rvice s .

357

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Alte rnative ly, s croll down the Users and Hosts are as , and click the Add link to
as s ign us e rs , us e r groups , hos ts , or hos t groups to the SELinux map.

358

⁠C hapt e r 23. De f ining SELinux Us e r Maps

Se le ct the us e rs (or hos ts or groups ) on the le ft, click the right arrows button (>>) to
move the m to the Prospective column, and click the Add button to add the m to the
rule .

359

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
Eithe r a hos t-bas e d acce s s control rule can be give n or the us e rs and hos ts
can be s e t manually. Both options cannot be us e d at the s ame time .
6. Click the Update link at the top to s ave the change s to the SELinux us e r map.

23.3.2. In t he CLI
An SELinux map rule has thre e fundame ntal parts :
The SELinux us e r (--selinuxuser)
The us e r or us e r groups which are as s ociate d with the SELinux us e r (--users or -groups)
The hos t or hos t groups which are as s ociate d with the SELinux us e r (--hosts or -hostgroups)
Alte rnative ly, a hos t-bas e d acce s s control rule which s pe cifie s both hos ts and us e rs in
it (--hbacrule)
A rule can be cre ate d with all information at once us ing the selinuxusermap-add
command. Us e rs and hos ts can be adde d to a rule afte r it is cre ate d by us ing the
selinuxusermap-add-user and selinuxusermap-add-host commands , re s pe ctive ly.

Example 23.3. Creat ing a New SELinux Map
The --selinuxuser value mus t be the SELinux us e r name e xactly as it appe ars in the
IdM s e rve r configuration. SELinux us e rs have the format SELinux_username:MLS[:MCS].
Both a us e r and a hos t (or appropriate groups ) mus t be s pe cifie d for the SELinux
mapping to be valid. The us e r, hos t, and group options can be us e d multiple time s or
can be us e d once with a comma-s e parate d lis te d ins ide curly brace s , s uch as --option=
{val1,val2,val3}.
[jsmith@server ~]$ ipa selinuxusermap-add --users=jsmith -users=bjensen --users=jrockford --hosts=server.example.com -hosts=test.example.com --selinuxuser="xguest_u:s0" selinux1

Example 23.4. Creat ing an SELinux Map wit h a Ho st -Based Access Co nt ro l
Rule
The --hbacrule value ide ntifie s the hos t-bas e d acce s s control rule to us e for mapping.
Us ing a hos t-bas e d acce s s control rule introduce s acce s s controls on what hos ts a
re mote us e r can us e to acce s s a targe t machine , along with applying SELinux conte xts
afte r the re mote us e r has logge d into the targe t machine .
The acce s s control rule mus t s pe cify both us e rs and hos ts appropriate ly s o that the
SELinux map can cons truct the SELinux us e r, IdM us e r, and hos t triple .
Only one hos t-bas e d acce s s control rule can be s pe cifie d.

360

⁠C hapt e r 23. De f ining SELinux Us e r Maps

[jsmith@server ~]$ ipa selinuxusermap-add --hbacrule=webserver -selinuxuser="xguest_u:s0" selinux1
Hos t-bas e d acce s s control rule s are de s cribe d in Chapte r 22, Configuring Host-Based
Access Control.

Example 23.5. Adding a User t o an SELinux Map
While all of the us e rs and hos ts can be adde d to a map whe n it is cre ate d, us e rs and
hos ts can als o be adde d afte r the rule is cre ate d. This is done us ing a s pe cific
command, e ithe r selinuxusermap-add-user or selinuxusermap-add-host.
[jsmith@server ~]$ ipa selinuxusermap-add-user --users=jsmith selinux1
It is not ne ce s s ary to us e a s e parate command to add a hos t-bas e d acce s s control rule
afte r the rule is configure d be caus e the re can only be one . If the selinuxusermap-mod
command is us e d with the --hbacrule option, it adds the hos t-bas e d acce s s control
rule or ove rwrite s the pre vious one .

Example 23.6. Remo ving a User f ro m an SELinux Map
A s pe cific us e r or hos t can be re move d from an SELinux map by us ing e ithe r the
selinuxusermap-remove-host or selinuxusermap-remove-user command. For
e xample :
[jsmith@server ~]$ ipa selinuxusermap-remove-user --users=jsmith
selinux1

361

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 24. Defining Aut omat ic Group Membership for
Users and Host s
Mos t of the policie s and configuration within the Ide ntity Manage me nt domain are bas e d on
groups. Various s e ttings , s uch as s udo rule s , automount, or acce s s control, are de fine d for
groups . The s e s e ttings are the n applie d to individual group me mbe rs .
Managing group me mbe rs hip is an important factor in managing us e rs and hos ts . Cre ating
automember groups de fine s rule s to add us e rs and hos ts to s pe cifie d groups
automatically, as s oon as a ne w e ntry is adde d.

24.1. About Aut omembership
One of the mos t critical tas ks for managing policie s , ide ntitie s , and s e curity is managing
group me mbe rs hip in Ide ntity Manage me nt. Groups are the core of mos t policy
configuration.
By de fault, hos ts do not be long to any group whe n the y are cre ate d; us e rs are adde d to
the catchall ipausers group. Eve n if cus tom groups are configure d and all policy
configuration is in place , us e rs and hos ts cannot take advantage of thos e policie s until
the y are joine d to groups . Of cours e , this can be done manually, but it is both more
e fficie nt and more cons is te nt if group me mbe rs hip can be as s igne d automatically.
This is done with automembership groups.
Autome mbe rs hip is e s s e ntially an automatic, global e ntry filte r that organiz e s e ntrie s , at
le as t in part, bas e d on s pe cific crite ria. An autome mbe r rule , the n, is the way that that
filte r is s pe cifie d.
For e xample , the re can be a lot of diffe re nt, re pe atable ways to cate goriz e ide ntitie s
within the IT and organiz ational e nvironme nt:
Adding all hos ts or all us e rs to a s ingle global group.
Adding e mploye e s to s pe cific groups bas e d on the ir e mploye e type , ID numbe r,
manage r, or phys ical location.
Dividing hos ts bas e d on the ir IP addre s s or s ubne t.
Autome mbe rs provide a way to pre -s ort thos e e ntrie s . That make s it e as ie r to configure
the actual be havior that you want to configure — like granting diffe re nt s udo rule s to
diffe re nt us e r type s or machine s on diffe re nt s ubne ts or have diffe re nt automount
s e ttings for diffe re nt us e rs .

No te
Autome mbe rs hip only applie s to new us e rs or hos ts . Changing the configuration for
an e xis ting us e r or group doe s not trigge r a change of group me mbe rs hip.
Autome mbe rs hip is a targe t s e t on an e xis ting us e r group or hos t group. An
automembership rule is cre ate d as a policy. This is a s is te r e ntry to the actual group e ntry
and it s ignals that the give n group is us e d for automatic group me mbe rs hip.

362

⁠C hapt e r 24 . De f ining Aut o mat ic Gr o up Me mbe r s hip f o r Us e r s and Ho s t s

Once the rule is cre ate d — once the group is ide ntifie d as be ing a targe t — the n the ne xt
s te p is to de fine automember conditions. Conditions are re gular e xpre s s ion filte rs that are
us e d to ide ntify group me mbe rs . Conditions can be inclus ive or e xclus ive , me aning that
matching e ntrie s can be adde d or ignore d bas e d on thos e conditions .
The re can be multiple conditions in a s ingle rule . A us e r or hos t e ntry can match multiple
rule s and be adde d to multiple groups .
Autome mbe rs hip is a way of impos ing re liable orde r on us e r and hos t e ntrie s by adding
the m to groups as the y are cre ate d.
The ke y to us ing autome mbe r groups e ffe ctive ly is to plan your ove rall
Ide ntity Manage me nt s tructure — the acce s s control policie s , s udo rule s , hos t/s e rvice
manage me nt rule s , hos t groups , and us e r groups .
Once the s tructure is in place , the n s e ve ral things are cle ar:
What groups will be us e d in the Ide ntity Manage me nt
What s pe cific groups diffe re nt type s of us e rs and hos ts ne e d to be long to to pe rform
the ir de s ignate d functions
What de line ating attribute s can be us e d to filte r us e rs and hos ts into the appropriate
groups

24.2. Defining Aut omembership Rules (Basic Procedure)
24.2.1. From t he Web UI
1. Cre ate the us e r group (Se ction 9.10.2.1, “Cre ating Us e r Groups ”) or hos t group
(Se ction 13.7.1.1, “Cre ating Hos t Groups from the We b UI”).
2. Ope n the Policy tab, and s e le ct the Automembers s ubtab.
3. In the top of the Automembers are a, s e le ct the type of autogroup to cre ate , e ithe r
USER GROUP RULES or HOST GROUP RULES.

4. In the drop-down me nu, s e le ct the group for which to cre ate the autome mbe r rule .

363

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

5. Click the Add and Edit button.
6. In the e dit page for the rule , click the + Add by the type of condition to cre ate to
ide ntify e ntrie s .

7. Se le ct the attribute to us e as the bas is for the s e arch and the n s e t the re gular
e xpre s s ion to us e to match the attribute value .
Conditions can look for e ntrie s e ithe r to include in the group or to e xplicitly exclude
from the group. The format of a condition is a Pe rl-compatible re gular e xpre s s ion
(PCRE). For more information on PCRE patte rns , s e e the pcre s yntax(3) man page .

364

⁠C hapt e r 24 . De f ining Aut o mat ic Gr o up Me mbe r s hip f o r Us e r s and Ho s t s

No te
Exclude conditions are e valuate d firs t and take pre ce de nce ove r include
conditions .

8. Click Add and Add Another to add anothe r condition. A s ingle rule can have
multiple include and e xclude conditions . Whe n all conditions have be e n configure d,
click the Add button to s ave the las t condition and clos e the dialog window.

24.2.2. From t he CLI
The re are two commands us e d to de fine an autome mbe r rule :
A command to targe t the group as an autome mbe r group, automember-add
A command to add re gular e xpre s s ion conditions to ide ntify group me mbe rs ,
automember-add-condition
For e xample :
1. Cre ate the us e r group (Se ction 9.10.2.1.2, “With the Command Line ”) or hos t group
(Se ction 13.7.1.2, “Cre ating Hos t Groups from the Command Line ”).
2. Cre ate the autome mbe r rule e ntry for the group. Us e the --type to ide ntify
whe the r the targe t group is a us e r group (group) or a hos t group (hostgroup). This
command has the format:
ipa automember-add --type=group|hostgroup groupName
For e xample :
[jsmith@server ~]$ ipa automember-add --type=group exampleGroup
3. Cre ate the conditions for the rule . To s e t multiple patte rns , e ithe r give a commas e parate d lis t of patte rns ins ide a s e t of curly brace s with the --inclusiveregex|--exclusive-regex options (--option={pattern1,pattern2}) or run the
command multiple time s .
This command has the format:

365

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ipa automember-add-condition --type=group|hostgroup -key=attribute --inclusive-regex=regex | --exclusive-regex=regex
groupName
As with the autome mbe r rule , the condition mus t s pe cify the type of group (--type)
and the name of the targe t group (groupName).
The condition mus t als o s pe cify the attribute (the ke y) and any patte rns for the
attribute value . The --key is the attribute name that is the focus of the condition.
The n, the re is a re gular e xpre s s ion patte rn to ide ntify matching value s ; matching
e ntrie s can e ithe r be include d (--inclusive-regex) or e xclude d (--exclusiveregex) from the group. Exclus ion rule s take pre ce de nce .
For e xample , to include all e mploye e s with Barbara Je ns e n as a manage r, but
e xcluding the te mporary e mploye e s :
[jsmith@server ~]$ ipa automember-add-condition --type=group -key=manager --inclusive-regex=^uid=bjensen$ exampleGroup
[jsmith@server ~]$ ipa automember-add-condition --type=group -key=employeetype --exclusive-regex=^temp exampleGroup

No te
The re gular e xpre s s ion can match any part of the s tring. Us ing a care t (^)
me ans that it mus t match at the be ginning, and us ing a dollar s ign ($) me ans
that it mus t match at the e nd. Wrapping the patte rn in ^ and $ me ans that the
s tring as a whole mus t match.
For more information on Pe rl-compatible re gular e xpre s s ion (PCRE) patte rns , s e e
the pcre s yntax(3) man page .
To re move a condition for a rule , pas s the full condition information, both the ke y and the
re gular e xpre s s ion:
[jsmith@server ~]$ ipa automember-remove-condition --key=fqdn -type=hostgroup --inclusive-regex=^web[1-9]+\.example\.com webservers
To re move the e ntire rule , s imply run the automember-del command.

24.3. Examples of Using Aut omember Groups
No te
The s e e xample s are s hown us ing the CLI; the s ame configuration can be pe rforme d
in the we b UI.

A No t e o n Creat ing Def ault Gro ups
One common e nvironme nt re quire me nt is to have s ome s ort of de fault group that us e rs
or hos ts are adde d to. The re are a couple of diffe re nt ways to approach that.

366

⁠C hapt e r 24 . De f ining Aut o mat ic Gr o up Me mbe r s hip f o r Us e r s and Ho s t s

All e ntrie s can be adde d to a s ingle , global group re gardle s s of what othe r groups the y
are als o adde d to.
Entrie s can be adde d to s pe cific autome mbe r groups . If the ne w e ntry doe s not match
any autogroup, the n it is adde d to a de fault or fallback group.
The s e s trate gie s are mutually e xclus ive . If an e ntry matche s a global group, the n it doe s
match an autome mbe r group and would, the re fore , not be adde d to the fallback group.

24.3.1. Set t ing an All Users/Host s Rule
To add all us e rs or all hos ts to a s ingle group, us e an inclus ive re gular e xpre s s ion for
s ome attribute (s uch as cn or fqdn) which all e ntrie s will contain.
A re gular e xpre s s ion to match all e ntrie s is s imply .*. For e xample , to add all hos ts to the
s ame hos t group:
[jsmith@server ~]$ ipa automember-add-condition --type=hostgroup
allhosts --inclusive-regex=.* --key=fqdn
-------------------------------Added condition(s) to "allhosts"
-------------------------------Automember Rule: allhosts
Inclusive Regex: fqdn=.*
---------------------------Number of conditions added 1
---------------------------Eve ry hos t adde d afte r that is automatically adde d to the allhosts group:
[jsmith@server ~]$ ipa host-add test.example.com
----------------------------Added host "test.example.com"
----------------------------Host name: test.example.com
Principal name: host/test.example.com@EXAMPLE.COM
Password: False
Keytab: False
Managed by: test.example.com
[jsmith@server ~]$ ipa hostgroup-show allhosts
Host-group: allhosts
Description: Default hostgroup
Member hosts: test.example.com
For more information on PCRE patte rns , s e e the pcre s yntax(3) man page .

24.3.2. Def ining Def ault Aut omembership Groups
The re is a s pe cial command to s e t a de fault group, automember-default-group-set. This
s e ts the group name (--default-group) and group type (--type), s imilar to an
autome mbe r rule , but the re is no condition to match. By de finition, de fault group me mbe rs
are unmatche d e ntrie s .
For e xample :

367

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[jsmith@server ~]$ ipa automember-default-group-set --defaultgroup=ipaclients --type=hostgroup
[jsmith@server ~]$ ipa automember-default-group-set --defaultgroup=ipausers --type=group
A de fault group rule can be re move d us ing the automember-default-group-remove
command. Since the re is only one de fault group for a group type , it is only ne ce s s ary to
give the group type , not the group name :
[jsmith@server ~]$ ipa automember-default-group-remove --type=hostgroup

24.3.3. Using Aut omembership Groups wit h Windows Users
Whe n a us e r is cre ate d in IdM, that us e r is automatically adde d as a me mbe r to the
ipausers group (which is the de fault group for all ne w us e rs , apart from any autome mbe r
group). Howe ve r, whe n a Windows us e r is s ynce d ove r from Active Dire ctory, that us e r is
not automatically adde d to the ipausers group.
Ne w Windows us e rs can be adde d to the ipausers group, as with us e rs cre ate d in
Ide ntity Manage me nt, by us ing an autome mbe r group. Eve ry Windows us e r is adde d with
the ntUser obje ct clas s ; that obje ct clas s can be us e d as an inclus ive filte r to ide ntify ne w
Windows us e rs to add to the autome mbe r group.
Firs t, de fine the ipausers group as an autome mbe r group:
[jsmith@server ~]$ ipa automember-add --type=group ipausers
The n, us e the ntUser obje ct clas s as a condition to add us e rs :
[jsmith@server ~]$ ipa automember-add-condition ipausers -key=objectclass --type=group --inclusive-regex=ntUser

368

⁠C hapt e r 24 . De f ining Aut o mat ic Gr o up Me mbe r s hip f o r Us e r s and Ho s t s

Chapt er 25. Rest rict ing Domains for PAM services
Impo rtant
This fe ature re quire s SSSD to be running on the s ys te m.
SSSD e nable s you to re s trict which domains can be acce s s e d by PAM s e rvice s . SSSD
e valuate s authe ntication re que s ts from PAM s e rvice s bas e d on the us e r the particular
PAM s e rvice is running as . Whe the r the PAM s e rvice can acce s s an SSSD domain
de pe nds on whe the r the PAM s e rvice us e r is able to acce s s the domain.
An e xample us e cas e is an e nvironme nt whe re e xte rnal us e rs are allowe d to
authe nticate to an FTP s e rve r. The FTP s e rve r is running as a s e parate non-privile ge d
us e r that s hould only be able to authe nticate to a s e le cte d SSSD domain, s e parate from
inte rnal company accounts . With this fe ature , the adminis trator can allow the FTP us e r to
only authe nticate to s e le cte d domains s pe cifie d in the FTP PAM configuration file .

No te
This functionality is s imilar to le gacy PAM module s , s uch as pam_ldap, which we re
able to us e a s e parate configuration file as a parame te r for a PAM module .

Opt ions t o Rest rict Access t o Domains
The following options are available to re s trict acce s s to s e le cte d domains :
pam_trusted_users in /etc/sssd/sssd.conf
This option acce pts a lis t of nume rical UIDs or us e r name s re pre s e nting the PAM
s e rvice s that are to be trus te d by SSSD. The de fault s e tting is all, which me ans
all s e rvice us e rs are trus te d and can acce s s any domain.
pam_public_domains in /etc/sssd/sssd.conf
This option acce pts a lis t of public SSSD domains . Public domains are domains
acce s s ible e ve n for untrus te d PAM s e rvice us e rs . The option als o acce pts the
all and none value s . The de fault value is none, which me ans no domains are
public and untrus te d s e rvice us e rs the re fore cannot acce s s any domain.
domains f o r PAM co nf igurat io n f iles
This option s pe cifie s a lis t of domains agains t which a PAM s e rvice can
authe nticate . If you us e domains without s pe cifying any domain, the PAM s e rvice
will not be able to authe nticate agains t any domain, for e xample :
auth

required

pam_sss.so domains=

If domains is not us e d in the PAM configuration file , the PAM s e rvice is able to
authe nticate agains t all domains , on the condition that the s e rvice is running
unde r a trus te d us e r.
The domains option in the /etc/sssd/sssd.conf SSSD configuration file als o

369

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

s pe cifie s a lis t of domains to which SSSD atte mpts to authe nticate . Note that the
domains option in a PAM configuration file cannot e xte nd the lis t of domains in
sssd.conf, it can only re s trict the sssd.conf lis t of domains by s pe cifying a
s horte r lis t. The re fore , if a domain is s pe cifie d in the PAM file but not in
sssd.conf, the PAM s e rvice will not be able to authe nticate agains t the domain.
The de fault s e ttings pam_trusted_users = all and pam_public_domains = none
s pe cify that all PAM s e rvice us e rs are trus te d and can acce s s any domain. The domains
option for PAM configuration file s can be us e d in this s ituation to re s trict the domains that
can be acce s s e d.
If you s pe cify a domain us ing domains in the PAM configuration file while sssd.conf
contains pam_public_domains, it might be re quire d to s pe cify the domain in
pam_public_domains as we ll. If pam_public_domains is us e d but doe s not include the
re quire d domain, the PAM s e rvice will not be able to s ucce s s fully authe nticate agains t the
domain if it is running unde r an untrus te d us e r.

No te
Domain re s trictions de fine d in a PAM configuration file only apply to authe ntication
actions , not to us e r lookups .
For more information about the pam_trusted_users and pam_public_domains options ,
s e e the s s s d.conf(5) man page . For more information about the domains option us e d in
PAM configuration file s , s e e the pam_s s s (8) man page .

Example 25.1. Rest rict ing Do mains f o r a PAM Service
To re s trict the domains agains t which a PAM s e rvice can authe nticate :
1. Make s ure SSSD is configure d to acce s s the re quire d domain or domains . The
domains agains t which SSSD can authe nticate are de fine d in the domains option
in the /etc/sssd/sssd.conf file .
[sssd]
domains = domain1, domain2, domain3
2. Spe cify the domain or domains to which a PAM s e rvice will be able to
authe nticate . To do this , s e t the domains option in the PAM configuration file . For
e xample :
auth
sufficient
pam_sss.so forward_pass
domains=domain1
account
[default=bad success=ok user_unknown=ignore]
pam_sss.so
password
sufficient
pam_sss.so use_authtok
The PAM s e rvice is now only allowe d to authe nticate agains t domain1.

370

⁠C hapt e r 25. Re s t r ic t ing Do mains f o r PAM s e r vic e s

⁠P art V. Configuring t he Ident it y Management Server

371

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 26. Defining Access Cont rol for IdM Users
Acce s s control is a s e t of s e curity fe ature s which de fine s who can acce s s ce rtain
re s ource s , s uch as machine s , s e rvice s or e ntrie s , and what kinds of ope rations the y are
allowe d to pe rform. Ide ntity Manage me nt provide s s e ve ral acce s s control are as to make it
cle ar what kind of acce s s is be ing grante d and to whom it is grante d. As part of this ,
Ide ntity Manage me nt draws a dis tinction be twe e n acce s s controls to re s ource s within the
domain and acce s s control to the IdM configuration its e lf.
This chapte r de tails the diffe re nt inte rnal acce s s control me chanis ms that are available
for us e rs within IdM to the IdM s e rve r and othe r IdM us e rs .

26.1. Access Cont rols for IdM Ent ries
Acce s s control de fine s the rights or pe rmis s ions us e rs have be e n grante d to pe rform
ope rations on othe r us e rs or obje cts .
The Ide ntity Manage me nt acce s s control s tructure is bas e d on s tandard LDAP acce s s
controls . Acce s s within the IdM s e rve r is bas e d on the IdM us e rs , s tore d in the back e nd
Dire ctory Se rve r ins tance , who are allowe d to acce s s othe r IdM e ntitie s , als o s tore d as
LDAP e ntrie s in the Dire ctory Se rve r ins tance .
An acce s s control ins truction (ACI) has thre e parts :
Act o r
This is the e ntity who is be ing grante d pe rmis s ion to do s ome thing. In LDAP
acce s s control mode ls , this is calle d the bind rule be caus e it de fine s who the
us e r is and can optionally re quire othe r limits on the bind atte mpt, s uch as
re s tricting atte mpts to a ce rtain time of day or a ce rtain machine .
T arget
This de fine s the e ntry which the actor is allowe d to pe rform ope rations on.
Operat io n t ype
Operation type — the las t part de te rmine s what kinds of actions the us e r is
allowe d to pe rform. The mos t common ope rations are add, de le te , write , re ad,
and s e arch. In Ide ntity Manage me nt, all us e rs are implicitly grante d re ad and
s e arch rights to all e ntrie s in the IdM domain, with re s trictions only for s e ns itive
attribute s like pas s words and Ke rbe ros ke ys . Anonymous us e rs are re s tricte d
from s e e ing s e curity-re late d configuration, like sudo rule s and hos t-bas e d acce s s
control.
Whe n any ope ration is atte mpte d, the firs t thing that the IdM clie nt doe s is s e nd us e r
cre de ntials as part of the bind ope ration. The back e nd Dire ctory Se rve r che cks thos e
us e r cre de ntials and the n che cks the us e r account to s e e if the us e r has pe rmis s ion to
pe rform the re que s te d ope ration.

26.1.1. Access Cont rol Met hods in Ident it y Management
To make acce s s control rule s s imple and cle ar to imple me nt, Ide ntity Manage me nt divide s
acce s s control de finitions into thre e cate gorie s :
Self -service rules

372

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Se lf-s e rvice rule s , which de fine what ope rations a us e r can pe rform on his own
pe rs onal e ntry. The acce s s control type only allows write pe rmis s ions to
attribute s within the e ntry; it doe s not allow add or de le te ope rations for the e ntry
its e lf.
Delegat io n rules
De le gation rule s , which allow a s pe cific us e r group to pe rform write (e dit)
ope rations on s pe cific attribute s for us e rs in anothe r us e r group. Like s e lf-s e rvice
rule s , this form of acce s s control rule is limite d to e diting the value s of s pe cific
attribute s ; it doe s not grant the ability to add or re move whole e ntrie s or control
ove r uns pe cifie d attribute s .
Ro le-based access co nt ro l
Role -bas e d acce s s control, which cre ate s s pe cial acce s s control groups which are
the n grante d much broade r authority ove r all type s of e ntitie s in the IdM domain.
Role s can be grante d e dit, add, and de le te rights , me aning the y can be grante d
comple te control ove r e ntire e ntrie s , not jus t s e le cte d attribute s .
Some role s are alre ady cre ate d and available within Ide ntity Manage me nt.
Spe cial role s can be cre ate d to manage any type of e ntry in s pe cific ways , s uch
as hos ts , automount configuration, ne tgroups , DNS s e ttings , and IdM configuration.

26.2. Defining Self-Service Set t ings
Se lf-s e rvice acce s s control rule s de fine the ope rations that an e ntity can pe rform on
its e lf. The s e rule s de fine only what attribute s a us e r (or othe r IdM e ntity) can e dit on the ir
pe rs onal e ntrie s .
Thre e s e lf-s e rvice rule s e xis t by de fault:
A rule for e diting s ome ge ne ral attribute s in the pe rs onal e ntry, including give n name
and s urname , phone numbe rs , and addre s s e s .
A rule to e dit pe rs onal pas s words , including two Samba pas s words , the Ke rbe ros
pas s word, and the ge ne ral us e r pas s word.
A rule to manage pe rs onal SSH ke ys .

26.2.1. Creat ing Self -Service Rules f rom t he Web UI
1. Ope n the IPA Server tab in the top me nu, and s e le ct the Self Service
Permissions s ubtab.
2. Click Add at the top of the lis t of s e lf-s e rvice ACIs .

373

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.1. Adding a New Self -Service Rule
3. Ente r the name of the rule in the pop-up window. Space s are allowe d.

Figure 26.2. Fo rm f o r Adding a Self -Service Rule
4. Se le ct the che ckboxe s by the attribute s which this ACI will pe rmit us e rs to e dit.
5. Click the Add button to s ave the ne w s e lf-s e rvice ACI.

374

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

26.2.2. Creat ing Self -Service Rules f rom t he Command Line
A ne w s e lf-s e rvice rule can be adde d us ing the selfservice-add command. The s e two
options are re quire d:
--permissions to s e t which pe rmis s ions – s uch as write , add, or de le te – the ACI
grants
--attrs to give the full lis t of attribute s which this ACI grants pe rmis s ion to.
[jsmith@server ~]$ ipa selfservice-add "Users can manage their own name
details" --permissions=write --attrs=givenname --attrs=displayname -attrs=title --attrs=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

26.2.3. Edit ing Self -Service Rules
In the s e lf-s e rvice e ntry in the we b UI, the only e le me nt that can be e dite d is the lis t of
attribute s that are include d in the ACI. The che ckboxe s can be s e le cte d or de s e le cte d.

375

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.3. Self -Service Edit Page
With the command line , s e lf-s e rvice rule s are e dite d us ing the ipa selfservice-mod
command. The --attrs option ove rwrite s whate ve r the pre vious lis t of s upporte d
attribute s was , s o always include the comple te lis t of attribute s along with any ne w
attribute s .
[jsmith@server ~]$ ipa selfservice-mod "Users can manage their own name
details" --attrs=givenname --attrs=displayname --attrs=title -attrs=initials --attrs=surname
-------------------------------------------------------------Modified 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

376

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Impo rtant
Include all of the attribute s whe n modifying a s e lf-s e rvice rule , including e xis ting
one s .

26.3. Delegat ing Permissions over Users
De le gation is ve ry s imilar to role s in that one group of us e rs is as s igne d pe rmis s ion to
manage the e ntrie s for anothe r group of us e rs . Howe ve r, the de le gate d authority is much
more s imilar to s e lf-s e rvice rule s in that comple te acce s s is grante d but only to s pe cific
us e r attribute s , not to the e ntire e ntry. Als o, the groups in de le gate d authority are
e xis ting IdM us e r groups ins te ad of role s s pe cifically cre ate d for acce s s controls .

26.3.1. Delegat ing Access t o User Groups in t he Web UI
1. Ope n the IPA Server tab in the top me nu, and s e le ct the Delegations s ubtab.
2. Click the Add link at the top of the lis t of de le gation ACIs .

Figure 26.4. Adding a New Delegat io n
3. Name the ne w de le gation ACI.
4. Se t the pe rmis s ions by s e le cting the che ckboxe s whe the r us e rs will have the right
to vie w the give n attribute s (re ad) and add or change the give n attribute s (write ).
Some us e rs may have a ne e d to s e e information, but s hould not be able to e dit it.
5. In the User group drop-down me nu, s e le ct the group who is being granted
permissions to the e ntrie s of us e rs in the us e r group.

377

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.5. Fo rm f o r Adding a Delegat io n
6. In the Member user group drop-down me nu, s e le ct the group whose entries can be
edited by me mbe rs of the de le gation group.
7. In the attribute s box, s e le ct the che ckboxe s by the attribute s to which the me mbe r
us e r group is be ing grante d pe rmis s ion.
8. Click the Add button to s ave the ne w de le gation ACI.

26.3.2. Delegat ing Access t o User Groups in t he Command Line
A ne w de le gation acce s s control rule is adde d us ing the delegation-add command.
The re are thre e re quire d argume nts :
--group, the group who is being granted permissions to the e ntrie s of us e rs in the us e r
group.
--membergroup, the group whose entries can be edited by me mbe rs of the de le gation
group.
--attrs, the attribute s which us e rs in the me mbe r group are allowe d to e dit.

378

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

For e xample :
$ ipa delegation-add "basic manager attrs" --attrs=manager --attrs=title
--attrs=employeetype --attrs=employeenumber --group=engineering_managers
--membergroup=engineering
-------------------------------------Added delegation "basic manager attrs"
-------------------------------------Delegation name: basic manager attrs
Permissions: write
Attributes: manager, title, employeetype, employeenumber
Member user group: engineering
User group: engineering_managers
De le gation rule s are e dite d us ing the delegation-mod command. The --attrs option
ove rwrite s whate ve r the pre vious lis t of s upporte d attribute s was , s o always include the
comple te lis t of attribute s along with any ne w attribute s .
[jsmith@server ~]$ ipa delegation-mod "basic manager attrs" -attrs=manager --attrs=title --attrs=employeetype --attrs=employeenumber
--attrs=displayname
----------------------------------------Modified delegation "basic manager attrs"
----------------------------------------Delegation name: basic manager attrs
Permissions: write
Attributes: manager, title, employeetype, employeenumber, displayname
Member user group: engineering
User group: engineering_managers

Impo rtant
Include all of the attribute s whe n modifying a de le gation rule , including e xis ting
one s .

26.4. Defining Role-Based Access Cont rols
Role -bas e d acce s s control grants a ve ry diffe re nt kind of authority to us e rs compare d to
s e lf-s e rvice and de le gation acce s s controls . Role -bas e d acce s s controls are
fundame ntally adminis trative , with the pote ntial to, for e xample , add, de le te , or
s ignificantly modify e ntrie s .
The re are thre e parts to role -bas e d acce s s controls :
The permission. The pe rmis s ion de fine s a s pe cific ope ration or s e t of ope rations (s uch
as re ad, write , add, or de le te ) and the targe t e ntrie s within the IdM LDAP dire ctory to
which thos e ope rations apply. Pe rmis s ions are building blocks ; the y can be as s igne d to
multiple privile ge s as ne e de d.
With IdM pe rmis s ions , you can control which us e rs have acce s s to which obje cts and
e ve n which attribute s of the s e obje cts ; IdM e nable s you to white lis t or blacklis t
inidividual attribute s or change the e ntire vis ibility of a s pe cific IdM function, s uch as
us e rs , groups , or s udo, to all anonymous us e rs , all authe nticate d us e rs , or jus t a

379

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ce rtain group of privile ge d us e rs . This fle xible approach to pe rmis s ions is us e ful in
s ce narios whe n, for e xample , the adminis trator wants to limit acce s s of us e rs or
groups only to the s pe cific s e ctions the s e us e rs or groups ne e d to acce s s and to make
the othe r s e ctions comple te ly hidde n to the m.
The privileges available to a role . A privile ge is e s s e ntially a group of pe rmis s ions .
Pe rmis s ions are not applie d dire ctly to a role . Pe rmis s ions are adde d to a privile ge s o
that the privile ge cre ate s a cohe re nt and comple te picture of a s e t of acce s s control
rule s . For e xample , a pe rmis s ion can be cre ate d to add, e dit, and de le te automount
locations . The n that pe rmis s ion can be combine d with anothe r pe rmis s ion re lating to
managing FTP s e rvice s , and the y can be us e d to cre ate a s ingle privile ge that re late s
to managing file s ys te ms .
The role. This is the lis t of IdM us e rs who are able to pe rform the actions de fine d in the
privile ge s .
It is pos s ible to cre ate e ntire ly ne w pe rmis s ions , as we ll as to cre ate ne w privile ge s
bas e d on e xis ting pe rmis s ions or ne w pe rmis s ions .

26.4.1. Roles
26.4.1.1. Creat ing Roles in t he Web UI
1. Ope n the IPA Server tab in the top me nu, and s e le ct the Role Based Access
Control s ubtab.
2. Click the Add link at the top of the lis t of role -bas e d ACIs .

Figure 26.6. Adding a New Ro le
3. Ente r the role name and a de s cription.

380

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.7. Fo rm f o r Adding a Ro le
4. Click the Add and Edit button to s ave the ne w role and go to the configuration
page .
5. At the top of the Users tab, or in the Users Groups tab whe n adding groups , click
Add.

Figure 26.8. Adding Users
6. Se le ct the us e rs on the le ft and us e the > button to move the m to the
Prospective column.

381

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.9. Select ing Users
7. At the top of the Privileges tab, click Add.

Figure 26.10 . Adding Privileges
8. Se le ct the privile ge s on the le ft and us e the > button to move the m to the
Prospective column.

382

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.11. Select ing Privileges
9. Click the Add button to s ave .

26.4.1.2. Creat ing Roles in t he Command Line
1. Add the ne w role :
[root@server ~]# kinit admin
[root@server ~]# ipa role-add --desc="User Administrator"
useradmin
-----------------------Added role "useradmin"
-----------------------Role name: useradmin
Description: User Administrator
2. Add the re quire d privile ge s to the role :
[root@server ~]# ipa role-add-privilege --privileges="User

383

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Administrators" useradmin
Role name: useradmin
Description: User Administrator
Privileges: user administrators
---------------------------Number of privileges added 1
---------------------------3. Add the re quire d groups to the role . In this cas e , we are adding only a s ingle group,
useradmin, which alre ady e xis ts .
[root@server ~]# ipa role-add-member --groups=useradmins useradmin
Role name: useradmin
Description: User Administrator
Member groups: useradmins
Privileges: user administrators
------------------------Number of members added 1
-------------------------

26.4.2. Permissions
26.4.2.1. Creat ing New Permissions f rom t he Web UI
1. Ope n the IPA Server tab in the top me nu, and s e le ct the Role Based Access
Control s ubtab.
2. Se le ct the Permissions tas k link.

Figure 26.12. Permissio ns T ask
3. Click the Add button at the top of the lis t of pe rmis s ions .

384

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.13. Adding a New Permissio n
4. De fine the prope rtie s for the ne w pe rmis s ion in the form that s hows up.

385

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.14. Fo rm f o r Adding a Permissio n
5. Click the Add button unde r the form to s ave the pe rmis s ion.
You can s pe cify the following pe rmis s ion prope rtie s :
1. Ente r the name of the ne w pe rmis s ion.
2. Se le ct the appropriate Bind rule type:

386

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

permission is the de fault pe rmis s ion type , granting acce s s through privile ge s
and role s
all s pe cifie s that the pe rmis s ion applie s to all authe nticate d us e rs
anonymous s pe cifie s that the pe rmis s ion applie s to all us e rs , including
unauthe nticate d us e rs

No te
It is not pos s ible to add pe rmis s ions with a non-de fault bind rule type to
privile ge s . You als o cannot s e t a pe rmis s ion that is alre ady pre s e nt in a
privile ge to a non-de fault bind rule type .
3. Choos e the rights that the pe rmis s ion grants in Granted rights.
4. De fine the me thod to ide ntify the targe t e ntrie s for the pe rmis s ion:
Type s pe cifie s an e ntry type , s uch as us e r, hos t, or s e rvice . If you choos e a
value for the Type s e tting, a lis t of all pos s ible attribute s which will be acce s s ible
through this ACI for that e ntry type appe ars unde r Effective Attributes.
De fining Type s e ts Subtree and Target DN to one of the pre de fine d value s .
Subtree s pe cifie s a s ubtre e e ntry; e ve ry e ntry be ne ath this s ubtre e e ntry is
the n targe te d. Provide an e xis ting s ubtre e e ntry, as Subtree doe s not acce pt
wildcards or non-e xis te nt domain name s (DNs ). For e xample :
cn=automount,dc=example,dc=com
Extra target filter us e s an LDAP filte r to ide ntify which e ntrie s the
pe rmis s ion applie s to. The filte r can be any valid LDAP filte r, for e xample :
(!(objectclass=posixgroup))
IdM automatically che cks the validity of the give n filte r. If you e nte r an invalid
filte r, IdM warns you about this afte r you atte mpt to s ave the pe rmis s ion.
Target DN s pe cifie s the domain name (DN) and acce pts wildcards . For e xample :
uid=*,cn=users,cn=accounts,dc=com
Member of group s e ts the targe t filte r to me mbe rs of the give n group.
Afte r you fill out the filte r s e ttings and click Add, IdM validate s the filte r. If all the
pe rmis s ion s e ttings are corre ct, IdM will pe rform the s e arch. If s ome of the
pe rmis s ions s e ttings are incorre ct, IdM will dis play a me s s age informing you about
which s e tting is s e t incorre ctly.
5. If you s e t Type, choos e the Effective attributes from the lis t of available ACI
attribute s . If you did not us e Type, add the attribute s manually by writing the m into
the Effective attributes fie ld. Add a s ingle attribute at a time ; to add multiple
attribute s , click Add to add anothe r input fie ld.

387

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Impo rtant
If you do not s e t any attribute s for the pe rmis s ion, the n all attribute s are
include d by de fault.

26.4.2.2. Creat ing New Permissions f rom t he Command Line
To add a ne w pe rmis s ion, is s ue the ipa permission-add command. Spe cify the
prope rtie s of the pe rmis s ion by s upplying the corre s ponding options :
Supply the name of the pe rmis s ion. For e xample :
[root@server ~]# ipa permission-add "dns admin permission"
--bindtype s pe cifie s the bind rule type . This options acce pts the all, anonymous, and
permission argume nts . For e xample :
--bindtype=all
If you do not us e --bindtype, the type is automatically s e t to the de fault permission
value .

No te
It is not pos s ible to add pe rmis s ions with a non-de fault bind rule type to
privile ge s . You als o cannot s e t a pe rmis s ion that is alre ady pre s e nt in a privile ge
to a non-de fault bind rule type .
--permissions lis ts the rights grante d by the pe rmis s ion. You can s e t multiple
attribute s by us ing multiple --permissions options or by lis ting the options in a
comma-s e parate d lis t ins ide curly brace s . For e xample :
--permissions=read --permissions=write
--permissions={read,write}
--attrs give s the lis t of attribute s ove r which the pe rmis s ion is grante d. You can s e t
multiple attribute s by us ing multiple --attrs options or by lis ting the options in a
comma-s e parate d lis t ins ide curly brace s . For e xample :
--attrs=description --attrs=automountKey
--attrs={description,automountKey}
The attribute s provide d with --attrs mus t e xis t and be allowe d attribute s for the give n
obje ct type , othe rwis e the command fails with s che ma s yntax e rrors .
--type de fine s the e ntry obje ct type , s uch as us e r, hos t, or s e rvice . Each type has its
own s e t of allowe d attribute s . For e xample :

388

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

[root@server ~]# ipa permission-add "manage service" --permissions=all
--type=service --attrs=krbprincipalkey --attrs=krbprincipalname -attrs=managedby
--subtree give s a s ubtre e e ntry; the filte r the n targe ts e ve ry e ntry be ne ath this
s ubtre e e ntry. Provide an e xis ting s ubtre e e ntry; --subtree doe s not acce pt wildcards
or non-e xis te nt domain name s (DNs ). Include a DN within the dire ctory.
Be caus e IdM us e s a s implifie d, flat dire ctory tre e s tructure , --subtree can be us e d to
targe t s ome type s of e ntrie s , like automount locations , which are containe rs or pare nt
e ntrie s for othe r configuration. For e xample :
[root@server ~]# ipa permission-add "manage automount locations" -subtree="ldap://ldap.example.com:389/cn=automount,dc=example,dc=com" -permissions=write --attrs=automountmapname --attrs=automountkey -attrs=automountInformation
The --type and --subtree options are mutually e xclus ive .
--filter us e s an LDAP filte r to ide ntify which e ntrie s the pe rmis s ion applie s to. IdM
automatically che cks the validity of the give n filte r. The filte r can be any valid LDAP
filte r, for e xample :
[root@server ~]# ipa permission-add "manage Windows groups" --filter="
(!(objectclass=posixgroup))" --permissions=write --attrs=description
--memberof s e ts the targe t filte r to me mbe rs of the give n group afte r che cking that
the group e xis ts . For e xample :
[root@server ~]# ipa permission-add ManageHost --permissions="write" -subtree=cn=computers,cn=accounts,dc=testrelm,dc=com -attr=nshostlocation --memberof=admins
--targetgroup s e ts targe t to the s pe cifie d us e r group afte r che cking that the group
e xis ts .
The Target DN s e tting, available in the we b UI, is not available on the command line .

No te
For information about modifying and de le ting pe rmis s ions , run the ipa permissionmod --help and ipa permission-del --help commands .

26.4.2.3. Def ault Managed Permissions
Managed pe rmis s ions are pe rmis s ions that come pre -ins talle d with Ide ntity Manage me nt.
The y be have like re gular us e r-cre ate d pe rmis s ions , with the following diffe re nce s :
You cannot modify the ir name , location, and targe t attribute s .
You cannot de le te the m.
The y have thre e s e ts of attribute s :

389

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

default attribute s , which are manage d by IdM and the us e r cannot modify the m
included attribute s , which are additional attribute s adde d by the us e r; to add an
include d attribute to a manage d pe rmis s ion, s pe cify the attribute by s upplying the -includedattrs option with the ipa permission-mod command
excluded attribute s , which are attribute s re move d by the us e r; to add an e xclude d
attribute to a manage d pe rmis s ion, s pe cify the attribute by s upplying the -excludedattrs option with the ipa permission-mod command
A manage d pe rmis s ion applie s to all attribute s that appe ar in the de fault and include d
attribute s e ts but not in the e xclude d s e t.
If you us e the --attrs option whe n modifying a manage d pe rmis s ion, the include d and
e xclude d attribute s e ts automatically adjus t, s o that only the attribute s s upplie d with -attrs are e nable d.

No te
While you cannot de le te a manage d pe rmis s ion, s e tting its bind type to permission
and re moving the manage d pe rmis s ion from all privile ge s e ffe ctive ly dis able s it.
Name s of all manage d pe rmis s ions s tart with System:, for e xample System: Add Sudo rule
or System: Modify Services.
Earlie r ve rs ions of IdM us e d a diffe re nt s che me for de fault pe rmis s ions , which, for
e xample , forbade the us e r from modifiying the de fault pe rmis s ions and the us e r could
only as s ign the m to privile ge s . Mos t of the s e de fault pe rmis s ions have be e n turne d into
manage d pe rmis s ions , howe ve r, the following pe rmis s ions s till us e the pre vious s che me :
Add Autome mbe r Re build Me mbe rs hip Tas k
Add Re plication Agre e me nts
Ce rtificate Re move Hold
Ge t Ce rtificate s s tatus from the CA
Modify DNA Range
Modify Re plication Agre e me nts
Re move Re plication Agre e me nts
Re que s t Ce rtificate
Re que s t Ce rtificate s from a diffe re nt hos t
Re trie ve Ce rtificate s from the CA
Re voke Ce rtificate
Write IPA Configuration
If you atte mpt to modify a manage d pe rmis s ion from the we b UI, the attribute s that you
cannot modify will be graye d-out.

390

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.15. Grayed-Out At t ribut es
If you atte mpt to modify a manage d pe rmis s ion from the command line , the s ys te m will
not allow you to change the attribute s that you cannot modify. For e xample , atte mpting to
change a de fault System: Modify Users pe rmis s ion to apply to groups fails :
$ ipa permission-mod 'System: Modify Users' --type=group
ipa: ERROR: invalid 'ipapermlocation': not modifiable on managed
permissions
You can, howe ve r, make the System: Modify Users pe rmis s ion not to apply to the GECOS
attribute :
$ ipa permission-mod 'System: Modify Users' --excludedattrs=gecos
-----------------------------------------Modified permission "System: Modify Users"

26.4.2.4. Permissions in Earlier Versions of Ident it y Management
Earlie r ve rs ions of Ide ntity Manage me nt handle d pe rmis s ions diffe re ntly, for e xample :
Only write , add, and de le te pe rmis s ion type s we re available .
The pe rmis s ion-s e tting options we re not as fine -graine d, as it was not pos s ible to, for
e xample , add both a filte r and a s ubtre e in the s ame pe rmis s ion.

391

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The global IdM ACI grante d re ad acce s s to all us e rs of the s e rve r, e ve n anonymous –
that is , not logge d-in – us e rs .
The ne w way of handling pe rmis s ions has s ignificantly improve d the IdM capabilitie s for
controling us e r or group acce s s , while re taining backward compatibility with the e arlie r
ve rs ions . Upgrading from an e arlie r ve rs ion of IdM de le te s the global IdM ACI on all
s e rve rs and re place s it with managed permissions.
Pe rmis s ions cre ate d in the pre vious way are automatically conve rte d to the ne w s tyle
whe ne ve r you modify the m. If you do not atte mpt to change the m, the pre vious -s tyle
pe rmis s ions s tay unconve rte d. Once a pe rmis s ion us e s the ne w s tyle , it can ne ve r
downgrade to the pre vious s tyle .

No te
It is s till pos s ible to as s ign pe rmis s ions to privile ge s on s e rve rs running an e arlie r
ve rs ion of IdM.
The ipa permission-show and ipa permission-find commands re cogniz e both the
ne w-s tyle pe rmis s ions and the pre vious -s tyle pe rmis s ions . While the outputs from both of
the s e commands dis play pe rmis s ions in the ne w s tyle , the y do not change the
pe rmis s ions the ms e lve s ; the y upgrade the pe rmis s ion e ntrie s be fore outputting the data
only in me mory, without committing the change s to LDAP.
Both the pre vious -s tyle and the ne w-s tyle pe rmis s ions have e ffe ct on all s e rve rs – thos e
running pre vious ve rs ions of IdM, as we ll as thos e running the curre nt IdM ve rs ion.
Howe ve r, you cannot cre ate or modify the ne w-s tyle pe rmis s ions on s e rve rs running
pre vious ve rs ions of IdM.

26.4.3. Privileges
26.4.3.1. Creat ing New Privileges f rom t he Web UI
1. Ope n the IPA Server tab in the top me nu, and s e le ct the Role Based Access
Control s ubtab.
2. Se le ct the Privileges tas k link.

392

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.16. Privileges T ask
3. Click the Add link at the top of the lis t of privile ge s .

Figure 26.17. Adding a New Privilege
4. Ente r the name and a de s cription of the privile ge .

Figure 26.18. Fo rm f o r Adding a Privilege
5. Click the Add and Edit button to go to the privile ge configuration page to add
pe rmis s ions .
6. Se le ct the Permissions tab.
7. Click Add at the top of the lis t of pe rmis s ions to add pe rmis s ion to the privile ge .

393

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 26.19. Adding Permissio ns
8. Click the che ckbox by the name s of the pe rmis s ions to add, and us e the > button to
move the pe rmis s ions to the Prospective column.

394

⁠C hapt e r 26 . De f ining Ac c e s s Co nt r o l f o r IdM Us e r s

Figure 26.20 . Select ing Permissio ns
9. Click the Add button to s ave .

26.4.3.2. Creat ing New Privileges f rom t he Command Line
Privile ge e ntrie s are cre ate d us ing the privilege-add command, and the n pe rmis s ions
are adde d to the privile ge group us ing the privilege-add-permission command.
1. Cre ate the privile ge e ntry.
[jsmith@server ~]$ ipa privilege-add "managing filesystems" -desc="for filesystems"
2. As s ign the de s ire d pe rmis s ions . For e xample :
[jsmith@server ~]$ ipa privilege-add-permission "managing
filesystems" --permissions="managing automount" -permissions="managing ftp services"

395

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 27. Ident it y Management Files and Logs
Ide ntity Manage me nt is a unifying frame work that combine s dis parate Linux s e rvice s into
a s ingle manage me nt conte xt. Howe ve r, the unde rlying te chnologie s — s uch as Ke rbe ros ,
DNS, 389 Dire ctory Se rve r, and Dogtag Ce rtificate Sys te m — re tain the ir own configuration
file s and log file s . Ide ntity Manage me nt dire ctly manage s e ach of the s e e le me nts through
the ir own configuration file s and tools .
This chapte r cove rs the dire ctorie s , file s , and logs us e d s pe cifically by IdM. For more
information about the configuration file s or logs for a s pe cific s e rve r us e d within IdM, s e e
the product docume ntation.

27.1. A Reference of IdM Server Configurat ion Files and
Direct ories
T able 27.1. IdM Server Co nf igurat io n Files and Direct o ries
Direct o ry o r File
Server Co nf igurat io n
/e tc/ipa/
/e tc/ipa/de fault.conf
/e tc/ipa/s e rve r.conf

/e tc/ipa/cli.conf

/e tc/ipa/ca.crt
~/.ipa/

IdM Lo gs
~/.ipa/log/cli.log

/var/log/ipaclie nt-ins tall.log
/var/log/ipas e rve r-ins tall.log
/e tc/logrotate .d/
Syst em Services
/e tc/rc.d/init.d/ipa/
Web UI
/e tc/ipa/html/

396

Descript io n
The main IdM configuration dire ctory.
The primary configuration file for IdM.
An optional configuration file for IdM. This
doe s not e xis t by de fault, but can be
cre ate d to load cus tom configuration whe n
the IdM s e rve r is s tarte d.
An optional configuration file for IdM
command-line tools . This doe s not e xis t by
de fault, but can be cre ate d to apply cus tom
configuration whe n the ipa is us e d.
The CA ce rtificate is s ue d by the IdM
s e rve r's CA.
A us e r-s pe cific IdM dire ctory that is cre ate d
on the local s ys te m in the s ys te m us e r's
home dire ctory the firs t time the us e r runs
an IdM command.
The log file for e rrors re turne d by XML-RPC
calls and re s pons e s by the IdM commandline tools . This is cre ate d in the home
dire ctory for the system user who runs the
tools , who may have a diffe re nt name than
the IdM us e r.
The ins tallation log for the clie nt s e rvice .
The ins tallation log for the IdM s e rve r.
The log rotation policie s for DNS, SSSD,
Apache , Tomcat, and Ke rbe ros .
The IdM s e rve r init s cript.
A s ymlink dire ctory in the main
configuration dire ctory for the HTML file s
us e d by the IdM we b UI.

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

Direct o ry o r File

Descript io n

/e tc/httpd/conf.d/ipa.conf

The configuration file s us e d by the Apache
hos t for the we b UI application.

/e tc/httpd/conf.d/ipa-re write .conf
/e tc/httpd/conf/ipa.ke ytab
/us r/s hare /ipa/

/us r/s hare /ipa/ipa-re write .conf

The ke ytab file us e d by the we b UI s e rvice .
The main dire ctory for all of the HTML file s ,
s cripts , and s tyle s he e ts us e d by the we b
UI.
The configuration file s us e d by the Apache
hos t for the we b UI application.

/us r/s hare /ipa/ipa.conf
/us r/s hare /ipa/update s /
/us r/s hare /ipa/html/
/us r/s hare /ipa/ipaclie nt/

/us r/s hare /ipa/migration/

/us r/s hare /ipa/ui/
/var/log/httpd/
Kerbero s
/e tc/krb5.conf
SSSD
/us r/s hare /s s s d/s s s d.api.d/s s s d-ipa.conf

/var/log/s s s d/
389 Direct o ry Server
/var/lib/dirs rv/s lapd-REALM_NAME/

/e tc/dirs rv/s lapd-REALM_NAME/

/var/log/dirs rv/s lapd-REALM_NAME/

Do gt ag Cert if icat e Syst em
/e tc/pki-ca/
/var/lib/pki/pki-tomcat/conf/ca/CS.cfg
/var/log/dirs rv/s lapd-REALM/

Contains any update d file s , s che ma, and
othe r e le me nts for Ide ntity Manage me nt.
Contains the HTML file s , JavaScript file s ,
and s tyle s he e ts us e d by the we b UI.
Contains the JavaScript file s us e d to
acce s s Fire fox's autoconfiguration fe ature
and s e t up the Fire fox brows e r to work in
the IdM Ke rbe ros re alm.
Contains HTML page s , s tyle s he e ts , and
Python s cripts us e d for running the IdM
s e rve r in migration mode .
Contains all of the s cripts us e d by the UI to
pe rform IdM ope rations .
The log file s for the Apache we b s e rve r.
The Ke rbe ros s e rvice configuration file .
The configuration file us e d to ide ntify the
IdM s e rve r, IdM Dire ctory Se rve r, and othe r
IdM s e rvice s us e d by SSSD.
The log file s for SSSD.
All of the databas e as s ociate d with the
Dire ctory Se rve r ins tance us e d by the IdM
s e rve r.
All of the configuration and s che ma file s
as s ociate d with the Dire ctory Se rve r
ins tance us e d by the IdM s e rve r.
Log file s as s ociate d with the
Dire ctory Se rve r ins tance us e d by the IdM
s e rve r.
The main dire ctory for the IdM CA ins tance .
The main configuration file for the IdM CA
ins tance .
Log file s as s ociate d with the
Dire ctory Se rve r ins tance us e d by the IdM
CA.

Cache Files

397

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Direct o ry o r File

Descript io n

/var/cache /ipa/

Cache file s for the IdM s e rve r and the IdM
Ke rbe ros pas s word dae mon.

Syst em Backups
/var/lib/ipa/s ys re s tore /

/var/lib/ipa-clie nt/s ys re s tore /

Contains backups of all of the s ys te m file s
and s cripts that we re re configure d whe n
the IdM s e rve r was ins talle d. The s e include
the original .conf file s for NSS, Ke rbe ros
(both krb5.conf and kdc.conf), and NTP.
Contains backups of all of the s ys te m file s
and s cripts that we re re configure d whe n
the IdM clie nt was ins talle d. Commonly, this
is the sssd.conf file for SSSD
authe ntication s e rvice s .

27.2. IdM Domain Services and Log Rot at ion
The 389 Dire ctory Se rve r ins tance s us e d by IdM as a backe nd and by the
Dogtag Ce rtificate Sys te m have the ir own inte rnal log rotation policie s . Log rotation
s e ttings s uch as the s iz e of the file , the pe riod be twe e n log rotation, and how long log
file s are pre s e rve d can all be configure d by e diting the 389 Dire ctory Se rve r
configuration. This is cove re d in the Re d Hat Dire ctory Se rve r Adminis trator's Guide .
Se ve ral IdM domain s e rvice s us e the s ys te m logrotate s e rvice to handle log rotation
and compre s s ion:
name d (DNS)
httpd (Apache )
tomcat
sssd
krb5kdc (Ke rbe ros domain controlle r)
Mos t of the s e policie s us e the logrotate de faults for the rotation s che dule (we e kly) and
the archive of logs (four, for four we e ks ' worth of logs ).
The individual policie s s e t pos t-rotation commands to re s tart the s e rvice afte r log rotation,
that a mis s ing log file is acce ptable , and compre s s ion s e ttings .

Example 27.1. Def ault ht t pd Lo g Ro t at io n File
[root@server ~]# cat /etc/logrotate.d/httpd
/var/log/httpd/*log {
missingok
notifempty
sharedscripts
delaycompress
postrotate
/sbin/service httpd reload > /dev/null 2>/dev/null || true
endscript
}

398

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

The re are othe r pote ntial log s e ttings , like compre s s s e ttings and the s iz e of the log file ,
which can be e dite d in e ithe r the global logrotate configuration or in the individual
policie s . The logrotate s e ttings are cove re d in the logrotate manual page .

Warning
Two policie s s e t s pe cial create rule s : the policie s for the named and tomcat
s e rvice s . All of the s e rvice s cre ate a ne w log file with the s ame name , de fault
owne r, and de fault pe rmis s ions as the pre vious log. For the named and tomcat logs ,
the create is s e t with e xplicit pe rmis s ions and us e r/group owne rs hip.
[root@server ~]# cat /etc/logrotate.d/named
/var/named/data/named.run {
missingok
create 0644 named named
postrotate
/sbin/service named reload 2> /dev/null > /dev/null ||
true
endscript
}
Do no t change t he permissio ns o r t he user and gro up which o wn t he lo g
f iles. This is re quire d for both IdM ope rations and SELinux s e ttings . Changing the
owne rs hip of the log rotation policy or of the file s can caus e the IdM domains
s e rvice s to fail or to be unable to s tart.

27.3. About default .conf and Cont ext Configurat ion Files
Ce rtain global de faults — like the re alm information, the LDAP configuration, and the CA
s e ttings — are s tore d in the default.conf file . This configuration file is re fe re nce d whe n
the IdM clie nt and s e rve rs s tart and e ve ry time the ipa command is run to s upply
information as ope rations are pe rforme d.
The parame te rs in the default.conf file are s imple attribute=value pairs . The attribute s
are cas e -ins e ns itive and orde r-ins e ns itive .
[global]
basedn=dc=example,dc=com
realm=EXAMPLE.COM
domain=example.com
xmlrpc_uri=https://server.example.com/ipa/xml
ldap_uri=ldapi://%2fvar%2frun%2fslapd-EXAMPLE-COM.socket
enable_ra=True
ra_plugin=dogtag
mode=production
Whe n adding more configuration attribute s or ove rriding the global value s , us e rs can
cre ate additional context configuration file s . A server.conf and cli.conf file can be
cre ate d to cre ate diffe re nt options whe n the IdM s e rve r is s tarte d or whe n the ipa
command is run, re s pe ctive ly. The IdM s e rve r che cks the server.conf and cli.conf file s
firs t, and the n che cks the default.conf file .

399

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Any configuration file s in the /etc/ipa dire ctory apply to all us e rs for the s ys te m. Us e rs
can s e t individual ove rride s by cre ating default.conf, server.conf, or cli.conf file s in
the ir local IdM dire ctory, ~/.ipa/. This optional file is me rge d with default.conf and us e d
by the local IdM s e rvice s .

27.4. Checking IdM Server Logs
Ide ntity Manage me nt unifie s s e ve ral diffe re nt Linux s e rvice s , s o it re lie s on thos e
s e rvice s ' native logs for tracking and de bugging thos e s e rvice s .
The othe r s e rvice s (Apache , 389 Dire ctory Se rve r, and Dogtag Ce rtificate Sys te m) all
have de taile d logs and log le ve ls . Se e the s pe cific s e rve r docume ntation for more
information on re turn code s , log formats , and log le ve ls .
T able 27.2. IdM Lo g Files
Service

Lo g File

Descript io n

IdM s e rve r

/var/log/ipas e rve rins tall.log
~/.ipa/log/cli.log

Se rve r ins tallation
log
Command-line tool
log
Clie nt ins tallation log

IdM s e rve r
IdM clie nt
Apache s e rve r

/var/log/ipaclie ntins tall.log
/var/log/httpd/acce s s
_log
/var/log/httpd/e rror_l
og

Dogtag Ce rtificate S
ys te m
Dogtag Ce rtificate S
ys te m

/var/log/pki-cains tall.log
/var/log/pki-ca/de bug
/var/log/pkica/s ys te m
/var/log/pkica/trans actions
/var/log/pkica/s igne dAudit

400

The s e are s tandard
acce s s and e rror
logs for Apache
s e rve rs . Both the
we b UI and the XMLRPC command-line
inte rface us e
Apache , s o s ome
IdM-s pe cific
me s s age s will be
re corde d in the
e rror log along with
the Apache
me s s age s .
The ins tallation log
for the IdM CA.
The s e logs mainly
re late to ce rtificate
ope rations . In IdM,
this is us e d for
s e rvice principals ,
hos ts , and othe r
e ntitie s which us e
ce rtificate s .

Addit io nal
Inf o rmat io n

Apache log chapte r

Logging chapte r

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

Service
389 Dire ctory Se rve
r

Lo g File
/var/log/dirs rv/s lapdREALM/acce s s
/var/log/dirs rv/s lapdREALM/audit
/var/log/dirs rv/s lapdREALM/e rrors

389 Dire ctory Se rve
r

/var/log/dirs rv/s lapdREALM/acce s s
/var/log/dirs rv/s lapdREALM/audit
/var/log/dirs rv/s lapdREALM/e rrors

Descript io n

Addit io nal
Inf o rmat io n

The acce s s and
e rror logs both
contain de taile d
information about
atte mpte d acce s s
and ope rations for
the domain
Dire ctory Se rve r
ins tance . The e rror
log s e tting can be
change d to provide
ve ry de taile d output.
This dire ctory
s e rve r ins tance is
us e d by the IdM CA
to s tore ce rtificate
information. Mos t
ope rational data
he re will be re late d
to s e rve r-re plica
inte ractions .

The acce s s log is
buffe re d, s o the
s e rve r only write s to
the log e ve ry 30
s e conds , by de fault.

This location is
configure d in the
krb5.conf file , s o it
could be diffe re nt on
s ome s ys te ms .
This location is
configure d in the
krb5.conf file , s o it
could be diffe re nt on
s ome s ys te ms .
This location is
configure d in the
krb5.conf file , s o it
could be diffe re nt on
s ome s ys te ms .

Ke rbe ros

/var/log/krb5libs .log

This is the primary
log file for Ke rbe ros
conne ctions .

Ke rbe ros

/var/log/krb5kdc.log

This is the primary
log file for the
Ke rbe ros KDC
s e rve r.

Ke rbe ros

/var/log/kadmind.log

This is the primary
log file for the
Ke rbe ros
adminis tration
s e rve r.

Monitoring
s e rve rs and
databas e s
Log e ntrie s
e xplaine d
The acce s s log is
buffe re d, s o the
s e rve r only write s to
the log e ve ry 30
s e conds , by de fault.
Monitoring
s e rve rs and
databas e s
Log e ntrie s
e xplaine d

401

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Service

Lo g File

Descript io n

Addit io nal
Inf o rmat io n

DNS

/var/log/me s s age s

DNS e rror
me s s age s are
include d with othe r
s ys te m me s s age s .

DNS logging is not
e nable d by de fault.
DNS logging is
e nable d by running
the querylog
command:
/usr/sbin/rndc
querylog
This be gins writing
log me s s age s to the
s ys te m's
/var/log/messages
file . To turn off
logging, run the
querylog command
again.

27.4.1. Enabling Server Debug Logging
De bug logging for the IdM s e rve r is s e t in the server.conf file .

No te
Editing the default.conf configuration file affe cts all IdM compone nts , not only the
IdM s e rve r.
1. Edit or cre ate the server.conf file .
vim server.conf
2. Add the debug line and s e t its value to true .
[global]
debug=True
3. Re s tart the Apache dae mon to load the change s .
service httpd restart

27.4.2. Debugging Command-Line Operat ions
Any command-line ope ration with the ipa command can re turn de bug information by us ing
the -v option. For e xample :
$ ipa -v user-show admin
ipa: INFO: trying https://ipaserver.example.com/ipa/xml

402

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

First name: John
Last name: Smythe
User login [jsmythe]:
ipa: INFO: Forwarding 'user_add' to server
u'https://ipaserver.example.com/ipa/xml'
-------------------Added user "jsmythe"
-------------------User login: jsmythe
First name: John
Last name: Smythe
Full name: John Smythe
Display name: John Smythe
Initials: JS
Home directory: /home/jsmythe
GECOS field: John Smythe
Login shell: /bin/sh
Kerberos principal: jsmythe@EXAMPLE.COM
UID: 1966800003
GID: 1966800003
Keytab: False
Password: False

Us ing the option twice , -vv, dis plays the XML-RPC e xchange :
$ ipa -vv user-add
ipa: INFO: trying https://ipaserver.example.com/ipa/xml
First name: Jane
Last name: Russell
User login [jrussell]:
ipa: INFO: Forwarding 'user_add' to server
u'https://ipaserver.example.com/ipa/xml'
send: u'POST /ipa/xml HTTP/1.0\r\nHost: ipaserver.example.com\r\nAcceptLanguage: en-us\r\nAuthorization: negotiate
YIIFgQYJKoZIhvcSAQICAQBuggVwMIIFbKADAgEFoQMCAQ6iBwMFACAAAACjggGHYYIBgzCC
AX+gAwIBBaEZGxdSSFRTLkVORy5CT1MuUkVESEFULkNPTaI5MDegAwIBA6EwMC4bBEhUVFAb
JmRlbGwtcGUxODUwLTAxLnJodHMuZW5nLmJvcy5yZWRoYXQuY29to4IBIDCCARygAwIBEqED
AgECooIBDgSCAQpV2YEWv03X+SENdUBfOhMFGc3Fvnd51nELV0rIB1tfGVjpNlkuQxXKSfFK
VD3vyAUqkii255T0mnXyTwayE93W1U4sOshetmG50zeU4KDmhuupzQZSCb5xB0KPU4HMDvP1
UnDFJUGCk9tcqDJiYE+lJrEcz8H+Vxvvl+nP6yIdUQKqoEuNhJaLWIiT8ieAzk8zvmDlDzpF
YtInGWe9D5ko1Bb7Npu0SEpdVJB2gnB5vszCIdLlzHM4JUqX8p21AZV0UYA6QZOWX9OXhqHd
ElKcuHCN2s9FBRoFYK83gf1voS7xSFlzZaFsEGHNmdA0qXbzREKGqUr8fmWmNvBGpDiR2ILQ
ep09lL56JqSCA8owggPGoAMCARKiggO9BIIDuarbB67zjmBu9Ax2K+0klSD99pNv97h9yxol
8c6NGLB4CmE8Mo39rL4MMXHeOS0OCbn+TD97XVGLu+cgkfVcuIG4PMMBoajuSnPmIf7qDvfa
8IYDFlDDnRB7I//IXtCc/Z4rBbaxk0SMIRLrsKf5wha7aWtN1JbizBMQw+J0UlN8JjsWxu0L
s75hBtIDbPf3fva3vwBf7kTBChBsheewSAlck9qUglyNxAODgFVvRrXbfkw51Uo++9qHnhh+
zFSWepfv7US7RYK0KxOKFd+uauY1ES+xlnMvK18ap2pcy0odBkKu1kwJDND0JXUdSY08MxK2
zb/UGWrVEf6GIsBgu122UGiHp6C+0fEu+nRrvtORY65Bgi8E1vm55fbb/9dQWNcQheL9m6QJ
WPw0rgc+E5SO99ON6x3Vv2+Zk17EmbZXinPd2tDe7fJ9cS9o/z7Qjw8z8vvSzHL4GX7FKi2H
JdBST3nEgOC8PqO46UnAJcA8pf1ZkwCK9xDWH+5PSph6WnvpRqugqf/6cq+3jk3MEjCrx+JB
J8QL6AgN3oEB4kvjZpAC+FfTkdX59VLDwfL/r0gMw3ZNk0nLLCLkiiYUMTEHZBzJw9kFbsX3
LmS8qQQA6rQ2L782DYisElywfZ/0Sax8JO/G62Zvy7BHy7SQSGIvcdAOafeNyfxaWM1vTpvS
h0GrnllYfs3FhZAKnVcLYrlPTapR23uLgRMv+0c9wAbwuUDfKgOOl5vAd1j55VUyapgDEzi/
URsLdVdcF4zigt4KrTByCwU2/pI6FmEPqB2tsjM2A8JmqA+9Nt8bjaNdNwCOWE0dF50zeL9P

403

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

8oodWGkbRZLk4DLIurpCW1d6IyTBhPQ5qZqHJWeoGiFa5y94zBpp27goMPmE0BskXT0JQmve
YflOeKEMSzyiWPL2mwi7KEMtfgCpwTIGP2LRE/QxNvPGkwFfO+PDjZGVw+APKkMKqclVXxht
JA/2NmBrO1pZIIJ9R+41sR/QoACcXIUXJnhrTwwR1viKCB5Tec87gN+e0Cf0g+fmZuXNRscw
JfhYQJYwJqdYzGtZW+h8jDWqa2EPcDwIQwyFAgXNQ/aMvh1yNTECpLEgrMhYmFAUDLQzI2BD
nfbDftIs0rXjSC0oZn/Uaoqdr4F5syOrYAxH47bS6MW8CxyylreH8nT2qQXjenakLFHcNjt4
M1nOc/igzNSeZ28qW9WSr4bCdkH+ra3BVpT/AF0WHWkxGF4vWr/iNHCjq8fLF+DsAEx0Zs69
6Rg0fWZy079A\r\nUser-Agent: xmlrpclib.py/1.0.1 (by
www.pythonware.com)\r\nContent-Type: text/xml\r\nContent-Length:
1240\r\n\r\n'
send: "\n\nuser_add\n\n\n<
value>\njrussell\n
\n\n\n
\n\nall\n0
\n\n\ndisplayname\n
Jane Russell
\n\n\ncn\nJane
Russell
\n\n\nnoprivate\n
0
\n\n\nuidnumber\n
999\n\n\nraw\n
0
\n\n\nversion\n
2.11
\n\n\ngecos\nJane
Russell\n\n\nsn\n
Russell
\n\n\nkrbprincipalname\n
jrussell@EXAMPLE.COM
\n\n\ngivenname\n
Jane
\n\n\ninitials\n
JR\n\n
\n\n\n\n"
reply: 'HTTP/1.1 200 OK\r\n'
header: Date: Thu, 15 Sep 2011 00:50:39 GMT
header: Server: Apache/2.2.15 (Red Hat)
header: WWW-Authenticate: Negotiate
YIGZBgkqhkiG9xIBAgICAG+BiTCBhqADAgEFoQMCAQ+iejB4oAMCARKicQRvVl5x6Zt9PbWN
zvPEWkdu+3PTCq/ZVKjGHM+1zDBz81GL/f+/Pr75zTuveLYn9de0C3k27vz96fn2HQsy9qVH
7sfqn0RWGQWzl+kDkuD6bJ/Dp/mpJvicW5gSkCSH6/UCNuE4I0xqwabLIz8MM/5o
header: Connection: close
header: Content-Type: text/xml; charset=utf-8
body: "\n\n\n\n
\n\nresult\n
\n\ndn\n
uid=jrussell,cn=users,cn=accounts,dc=example,dc=com
\n\n\nhas_keytab\n
0
\n\n\ndisplayname\n
\nJane Russell\n
\n\n\nuid\n
\njrussell\n
\n\n\nobjectclass\n

404

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

\ntop\n
person\n
organizationalperson\n
inetorgperson\ninetuser
\nposixaccount\n
krbprincipalaux\n
krbticketpolicyaux\n<"
body: 'value>ipaobject\n
\n\n\nloginshell\n
\n/bin/sh\n
\n\n\nuidnumber\n
\n1966800004\n
\n\n\ninitials\n
\nJR\n
\n\n\ngidnumber\n
\n1966800004\n
\n\n\ngecos\n
\nJane Russell\n
\n\n\nsn\n
\nRussell\n
\n\n\nhomedirectory\n
\n/home/jrussell\n

\n\n\nhas_password\n
0
\n\n\nkrbprincipalname\n
\njrussell@EXAMPLE.COM
\n
\n\n\ngivenname\n
\nJane\n
\n\n\ncn\n
\nJane Russell\n
\n\n\nipauniqueid\n
\nbba27e6e-df34-11e0-a5f4-001143d2c060
\n\n\n
\n\n\nvalue\n
jrussell
\n\n\nsummary\n
Added user "jrussell"\n\n
\n\n\n\n'
--------------------Added user "jrussell"
--------------------User login: jrussell
First name: Jane
Last name: Russell
Full name: Jane Russell
Display name: Jane Russell
Initials: JR
Home directory: /home/jrussell
GECOS field: Jane Russell
Login shell: /bin/sh
Kerberos principal: jrussell@EXAMPLE.COM

405

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

UID: 1966800004
GID: 1966800004
Keytab: False
Password: False

Impo rtant
The -v and -vv options are global options and mus t be us e d be fore the
s ubcommand whe n running ipa.

406

⁠C hapt e r 27. Ide nt it y Manage me nt File s and Lo gs

Chapt er 28. Managing Cert ificat es and Cert ificat e
Aut horit ies
Almos t e ve ry IdM topology include s an inte grate d Dogtag Ce rtificate Sys te m to manage
ce rtificate s for s e rve rs , re plicas , hos ts , us e rs , and s e rvice s within the IdM domain. The
Dogtag Ce rtificate Sys te m configuration its e lf may re quire change s as the domain and the
phys ical machine s change .

28.1. Renewal Messages
All ce rtificate s is s ue d by the IdM s e rve rs , s uch as hos t and us e r ce rtificate s or
s ubs ys te m and s e rve r ce rtificate s us e d by inte rnal IdM s e rvice s , are tracke d by
certmonger and automatically re ne we d as the y ne ar e xpiration.
As a ce rtificate ne ars its e xpiration, certmonger logs me s s age s in /var/log/message, for
e xample :
certmonger: Certificate named "NSS Certificate DB" in token
"auditSigningCert cert-pki-ca" in database "/var/lib/pki-ca/alias" will
not be valid after 20160204065136.
Once a ce rtificate is re ne we d, certmonger re cords anothe r me s s age to indicate that the
re ne wal ope ration has s ucce e de d (or faile d), for e xample :
Certificate named "NSS Certificate DB" in token "auditSigningCert certpki-ca" in database "/var/lib/pki-ca/alias" renew success

28.2. Aut omat ic CA Cert ificat e Renewal
If you are us ing a root CA ce rtificate manage d inte rnally by Dogtag, the certmonger utility
automatically re ne ws the CA ce rtificate whe n it is ne aring e xpiration. For more information
on how certmonger monitors ce rtificate e xpiration date s , s e e the corre s ponding chapte r
in the Sys te m-Le ve l Authe ntication Guide .
Ce rtificate s s igne d by an e xte rnal CA cannot be automatically re ne we d by certmonger.
You have to re ne w the s e ce rtificate s manually.

28.3. Manual CA Cert ificat e Renewal
You can us e the ipa-cacert-manage utility to manually re ne w:
the s e lf-s igne d Dogtag CA ce rtificate
the Dogtag CA ce rtificate s igne d by an e xte rnal CA
The re ne we d ce rtificate s cre ate d with the ipa-cacert-manage renew command us e the
s ame ke y pair and s ubje ct name as the old ce rtificate s . Re ne wing a ce rtificate doe s not
re move its pre vious ve rs ion to e nable ce rtificate rollove r.
To manually re ne w the s e lf-s igne d Dogtag CA ce rtificate :

407

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

1. Run the ipa-cacert-manage renew command. The command doe s not re quire you
to s pe cify the path to the ce rtificate .
2. The re ne we d ce rtificate is now pre s e nt in the LDAP ce rtificate s tore and in the
/etc/pki/pki-tomcat/alias NSS databas e .
3. Run the ipa-certupdate utility on all clie nts to update the m with the information
about the ne w ce rtificate from LDAP. You have to run ipa-certupdate on e ve ry
clie nt s e parate ly.
To manually re ne w the Dogtag CA ce rtificate s igne d by an e xte rnal CA:
1. Run the ipa-cacert-manage renew command.
2. The command cre ate s the /var/lib/ipa/ca.crt CSR file . Sign the CSR file with
the e xte rnal CA to ge t the re ne we d CA ce rtificate . For information about s igning the
CSR file with an e xte rnal CA, s e e Se ction 3.2.3.2, “Ins talling Us ing an Exte rnal CA”.
3. Run ipa-cacert-manage renew again, and this time s pe cify the re ne we d CA
ce rtificate and the e xte rnal CA ce rtificate chain file s us ing the --external-certfile option. For e xample :
[root@server ~]# ipa-cacert-manage renew --external-cert-file
path/to/signed/certificate
4. The re ne we d CA ce rtificate and the e xte rnal CA ce rtificate chain are now pre s e nt
in the LDAP ce rtificate s tore and in the /etc/pki/pki-tomcat/alias NSS
databas e .
5. Run the ipa-certupdate utility on all clie nts to update the m with the information
about the ne w ce rtificate from LDAP. You have to run ipa-certupdate on e ve ry
clie nt s e parate ly.

Impo rtant
If you do not run ipa-certupdate afte r re ne wing a ce rtificate manually, the
re ne we d ce rtificate will not be dis tribute d to clie nts .
You can make s ure the re ne we d ce rtificate is prope rly ins talle d and pre s e nt in the NSS
databas e by us ing the certutil utility to lis t the ce rtificate s in the databas e . For e xample :
[root@server ~]# certutil -L -d /etc/pki/pki-tomcat/alias

28.4. Changing Cert ificat e Chaining
Whe n re ne wing a ce rtificate with the ipa-cacert-manage renew command, you can als o
modify the ce rtificate chaining. It is pos s ible to:
re ne w the s e lf-s igne d Dogtag CA ce rtificate as a CA ce rtificate s igne d by an e xte rnal
CA
re ne w the Dogtag CA ce rtificate s igne d by an e xte rnal CA as a s e lf-s igne d CA
ce rtificate

408

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

To re ne w the s e lf-s igne d Dogtag CA ce rtificate as a CA ce rtificate s igne d by an e xte rnal
CA, add the --external-ca option to ipa-cacert-manage renew. The re s t of the
proce dure is the s ame as manually re ne wing an e xte rnally-s igne d ce rtificate , which is
de s cribe d in Se ction 28.3, “Manual CA Ce rtificate Re ne wal”.
To re ne w the Dogtag CA ce rtificate s igne d by an e xte rnal CA as a s e lf-s igne d Dogtag CA
ce rtificate , add the --self-signed option to ipa-cacert-manage renew.

28.5. St art ing IdM wit h Expired Cert ificat es
If IdM adminis trative s e rve r ce rtificate s e xpire , the n mos t IdM s e rvice s will be
inacce s s ible , including adminis trative s e rvice s . The unde rlying Apache and
389 Dire ctory Se rve r s e rvice s can be configure d to allow SSL acce s s to thos e s e rvice s ,
e ve n if the ce rtificate s are e xpire d.

No te
Allowing limite d acce s s with e xpire d ce rtificate s pe rmits Apache , Ke rbe ros , DNS,
and 389 Dire ctory Se rve r s e rvice s to continue working. With thos e s e rvice s active ,
us e rs are able to log into the domain.
Clie nt s e rvice s s uch as sudo that re quire SSL for acce s s will s till fail be caus e of the
e xpire d s e rve r ce rtificate s .

1. Change the mod_nss configuration for the Apache s e rve r to not e nforce valid
ce rtificate s , in the NSSEnforceValidCerts parame te r. If this parame te r is not
alre ady in the file , the n add it.
Se t the value to off.
[root@ipaserver ~]# vim /etc/httpd/conf.d/nss.conf
NSSEnforceValidCerts off
2. Re s tart Apache .
[root@ipaserver ~]# systemctl restart httpd.service
3. Change the nsslapd-validate-cert attribute in the 389 Dire ctory Se rve r
configuration to warn ins te ad of true to dis able validity che cks .
[root@ipaserver ~]# ldapmodify -D "cn=directory manager" -w secret
-p 389 -h ipaserver.example.com
dn: cn=config
changetype: modify
replace: nsslapd-validate-cert
nsslapd-validate-cert: warn
4. Re s tart 389 Dire ctory Se rve r.
[root@ipaserver ~]# systemctl restart dirsrv.target

409

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

28.6. Configuring Alt ernat e Cert ificat e Aut horit ies
IdM cre ate s a Dogtag Ce rtificate Sys te m ce rtificate authority (CA) during the s e rve r
ins tallation proce s s . To us e an e xte rnal CA, it is pos s ible to cre ate the re quire d s e rve r
ce rtificate s and the n import the m into the 389 Dire ctory Se rve r and the HTTP s e rve r,
which re quire IdM s e rve r ce rtificate s .

No te
Save an ASCII copy of the CA ce rtificate as /usr/share/ipa/html/ca.crt. This
allows us e rs to download the corre ct ce rtificate whe n the y configure the ir brows e rs .
1. Us e the ipa-server-certinstall command to ins tall the ce rtificate .
# /usr/sbin/ipa-server-certinstall -d /path/to/pkcs12.p12
2. To ke e p us ing brows e r autoconfiguration in Fire fox, re ge ne rate the
/usr/share/ipa/html/configure.jar file .
a. Cre ate a dire ctory, and the n cre ate the ne w s e curity databas e s in that
dire ctory.
# mkdir /tmp/signdb
# certutil -N -d /tmp/signdb
b. Import the PKCS #12 file for the s igning ce rtificate into that dire ctory.
# pk12util -i /path/to/pkcs12.p12 -d /tmp/signdb
c. Make a te mporary s igning dire ctory, and copy the IdM JavaScript file to that
dire ctory.
# mkdir /tmp/sign
# cp /usr/share/ipa/html/preferences.html /tmp/sign
d. Us e the obje ct s igning ce rtificate to s ign the JavaScript file and to
re ge ne rate the configure.jar file .
# signtool -d /tmp/signdb -k Signing_cert_nickname -Z
/usr/share/ipa/html/configure.jar -e .html /tmp/sign

28.7. Promot ing a Replica t o a Mast er CA Server
The only diffe re nce be twe e n a mas te r s e rve r and a re plica is that only the mas te r CA
manage s re ne wal of CA s ubs ys te m ce rtificate s and ge ne rate s CRLs which are dis tribute d
among the othe r s e rve rs and re plicas in the topology. Othe rwis e , s e rve rs and re plicas
are e qual pe e rs in the s e rve r topology.

410

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

If the original s e rve r is going to be take n offline or de commis s ione d, a re plica ne e ds to be
configure d to take its place be caus e the re always mus t be one ins tance s ome whe re in
the IdM topology which is s ue s CRLs . Promoting a re plica to a mas te r s e rve r change s its
configuration and e nable s it to function as the root CA.
The firs t IdM s e rve r ins talle d owns the mas te r CA in the PKI hie rarchy. Se rve rs are almos t
always cre ate d to hos t CA s e rvice s . The s e are the original CA s e rvice s .

No te
The only e xce ption to this is if s ys te m ce rtificate s are manually loade d during the
ins tallation for a CA-le s s ins tallation. Othe rwis e , a Ce rtificate Sys te m ins tance is
ins talle d and configure d.
A re plica can hos t CA s e rvice s , but this is not re quire d. Se rve rs and re plicas which hos t a
CA are als o e qual pe e rs in the topology. The y can all is s ue ce rtificate s and ke ys to IdM
clie nts , and the y all re plicate information amongs t the ms e lve s .
Whe n the firs t s e rve r is ins talle d, it is configure d to is s ue CRLs . In its CA configuration file
at /etc/pki/pki-tomcat/ca/CS.cfg, it has CRL ge ne ration e nable d:
ca.crl.issuingPointId.enableCRLCache=true
ca.crl.issuingPointId.enableCRLUpdates=true
ca.listenToCloneModifications=false
All re plicas point to that mas te r CA as the s ource for CRL information and dis able the CRL
s e ttings :
ca.crl.issuingPointId.enableCRLUpdates=false
To promote a re plica to a mas te r CA, you mus t change which s e rve r handle s ce rtificate
re ne wal and which s e rve r ge ne rate s CRLs .

Changing Which Server Handles Cert if icat e Renewal
1. To de te rmine the hos t name of the curre nt re ne wal mas te r, us e the ldapsearch
utility. In the following e xample , it is server.example.com:
$ ldapsearch -H ldap://$HOSTNAME -D 'cn=Directory Manager' -W -b
'cn=masters,cn=ipa,cn=etc,dc=example,dc=com' '(&(cn=CA)
(ipaConfigString=caRenewalMaster))' dn
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base  with scope
subtree
# filter: (&(cn=CA)(ipaConfigString=caRenewalMaster))
# requesting: dn
#
# CA, server.example.com, masters, ipa, etc, example.com
dn:

411

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

cn=CA,cn=server.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc
=com
# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
2. Configure CA re ne wal on the ne w mas te r us ing the ipa-csreplica-manage utility:
# ipa-csreplica-manage set-renewal-master

No te
You are not re quire d to re configure the curre nt CA as a clone to manually
de comis s ion it. Clone re ne wal is configure d automatically whe n you s e t up anothe r
CA as the re ne wal mas te r s e rve r.

Changing Which Server Generat es CRLs
1. To ide ntify the curre nt CRL ge ne ration mas te r, e xamine the CS.cfg on e ach CA. For
e xample :
# grep ca.crl.MasterCRL.enableCRLUpdates /etc/pki/pkitomcat/ca/CS.cfg
ca.crl.MasterCRL.enableCRLUpdates=true
The ca.crl.MasterCRL.enableCRLUpdates parame te r is s e t to true on the CRL
ge ne ration mas te r. On clone s , it is s e t to false.
2. Stop CRL ge ne ration on the curre nt CRL ge ne ration mas te r.
a. Stop the CA s e rvice :
# systemctl stop pki-tomcatd@pki-tomcat.service
b. Se t the value s of the ca.crl.MasterCRL.enableCRLCache and
ca.crl.MasterCRL.enableCRLUpdates parame te rs to false in the
/etc/pki/pki-tomcat/ca/CS.cfg file to dis able CRL ge ne ration:
ca.crl.MasterCRL.enableCRLCache=false
ca.crl.MasterCRL.enableCRLUpdates=false
c. Start the CA s e rvice :
# systemctl start pki-tomcatd@pki-tomcat.service
d. Configure Apache to re dire ct CRL re que s ts to the ne w mas te r by
uncomme nting the RewriteRule on the las t line of the
/etc/httpd/conf.d/ipa-pki-proxy.conf file :

412

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

# Only enable this on servers that are not generating a CRL
RewriteRule ^/ipa/crl/MasterCRL.bin
https:///ca/ee/ca/getCRL?
op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
e . Re s tart Apache :
# systemctl restart httpd.service
3. Configure a re plica to ge ne rate CRLs as the ne w mas te r:
a. Stop the CA s e rvice :
# systemctl stop pki-tomcatd@pki-tomcat.service
b. Se t the value s of the ca.crl.MasterCRL.enableCRLCache and
ca.crl.MasterCRL.enableCRLUpdates parame te rs to true in
/etc/pki/pki-tomcat/ca/CS.cfg to e nable CRL ge ne ration:
ca.crl.MasterCRL.enableCRLCache=true
ca.crl.MasterCRL.enableCRLUpdates=true
c. Start the CA s e rvice :
# systemctl start pki-tomcatd@pki-tomcat.service
d. Configure Apache to dis able re dire cting CRL re que s ts by comme nting out the
RewriteRule argume nt on the las t line of the /etc/httpd/conf.d/ipapki-proxy.conf file :
#RewriteRule ^/ipa/crl/MasterCRL.bin
https://server.example.com/ca/ee/ca/getCRL?
op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
As a clone , all CRL re que s ts we re route d to the original mas te r. As the ne w
mas te r, this ins tance will re s pond to CRL re que s ts .
e . Re s tart Apache :
# systemctl restart httpd.service

28.8. Configuring OCSP Responders
A ce rtificate is cre ate d with a validity pe riod, me aning it has a point whe re it e xpire s and
is no longe r valid. The e xpiration date is containe d in the ce rtificate its e lf, s o a clie nt
always che cks the validity pe riod in the ce rtificate to s e e if the ce rtificate is s till valid.
Howe ve r, a ce rtificate can als o be re voke d be fore its validity pe riod is up, but this
information is not containe d in the ce rtificate . A CA publis he s a certificate revocation list
(CRL), which contains a comple te lis t of e ve ry ce rtificate that was is s ue d by that CA and
s ubs e que ntly re voke d. A clie nt can che ck the CRL to s e e if a ce rtificate within its validity
pe riod has be e n re voke d and is , the re fore , invalid.

413

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Validity che cks are pe rforme d us ing the online ce rtificate s tatus protocol (OCSP), which
s e nds a re que s t to an OCSP responder. Each CA inte grate d with the IdM s e rve r us e s an
inte rnal OCSP re s ponde r, and any clie nt which runs a validity che ck can che ck the IdM CA's
inte rnal OCSP re s ponde r.
Eve ry ce rtificate is s ue d by the IdM CA puts its OCSP re s ponde r s e rvice URL in the
ce rtificate . For e xample :
http://ipaserver.example.com:9180/ca/ocsp

No te
For the IdM OCSP re s ponde r to be available , port 9180 ne e ds to be ope n in the
fire wall.

28.8.1. Using an OSCP Responder wit h SELinux
Clie nts can us e the Ide ntity Manage me nt OCSP re s ponde r to che ck ce rtificate validity or to
re trie ve CRLs . A clie nt can be a numbe r of diffe re nt s e rvice s , but is mos t fre que ntly an
Apache s e rve r and the mod_re vocator module (which handle s CRL and OCSP ope rations ).
The Ide ntity Manage me nt CA has an OCSP re s ponde r lis te ning ove r port 9180, which is
als o the port available for CRL re trie val. This port is prote cte d by de fault SELinux policie s
to pre ve nt unauthoriz e d acce s s . If an Apache s e rve r atte mpts to conne ct to the OCSP
port, the n it may be de nie d acce s s by SELinux.
The Apache s e rve r, on the local machine , mus t be grante d acce s s to port 9180 for it to be
able to conne ct to the Ide ntity Manage me nt OCSP re s ponde r. The re are two ways to work
around this by changing the SELinux policie s :
Edit the SELinux policy to allow Apache s e rve rs us ing the mod_re vocator module to
conne ct to port 9180:
semodule -i revoker.pp
Ge ne rate a ne w SELinux policy to allow acce s s bas e d on the SELinux e rror logs for the
mod_re vocator conne ction atte mpt.
audit2allow -a -M revoker

28.8.2. Changing t he CRL Updat e Int erval
The CRL file is automatically ge ne rate d by the Dogtag Ce rtificate Sys te m CA e ve ry four
hours . This inte rval can be change d by e diting the Dogtag Ce rtificate Sys te m configuration.
1. Stop the CA s e rve r.
[root@server ~]# systemctl stop pki-tomcatd@pki-tomcat.service
2. Ope n the CS.cfg file .
[root@server ~]# vim /var/lib/pki/pki-tomcat/conf/ca/CS.cfg

414

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

3. Change the ca.crl.MasterCRL.autoUpdateInterval to the ne w inte rval s e tting.
4. Re s tart the CA s e rve r.
[root@server ~]# systemctl start pki-tomcatd@pki-tomcat.service

28.9. Cert ificat e Profiles
A ce rtificate profile de fine s the conte nt of ce rtificate s be longing to the particular profile , as
we ll as cons traints for is s uing the ce rtificate s , e nrollme nt me thod, and input and output
forms for e nrollme nt. A s ingle ce rtificate profile is as s ociate d with is s uing a particular type
of ce rtificate . Diffe re nt ce rtificate profile s can be de fine d for us e rs , s e rvice s , and hos ts in
IdM.
The CA us e s ce rtificate profile s in s igning of ce rtificate s to de te rmine :
whe the r the CA can acce pt a ce rtificate s igning re que s t (CSR)
what fe ature s and e xte ns ions s hould be pre s e nt on the ce rtificate
IdM include s the following two ce rtificate profile s by de fault: caIPAserviceCert and
IECUserRoles. In addition, cus tom profile s can be importe d.
Cus tom ce rtificate profile s allow is s uing ce rtificate s for s pe cific, unre late d purpos e s . For
e xample , it is pos s ible to re s trict us e of a particular profile to only one us e r or one group,
pre ve nting othe r us e rs and groups from us ing that profile to is s ue a ce rtificate for
authe ntication.

No te
By combining ce rtificate profile s and CA ACLs , Se ction 28.10, “Ce rtificate Authority
ACL Rule s ”, the adminis trator can de fine and control acce s s to cus tom ce rtificate
profile s . For a de s cription of us ing profile s and CA ACLs to is s ue us e r ce rtificate s ,
s e e Se ction 9.11, “Is s uing Us e r Ce rtificate s with the IdM CA”.

28.9.1. Cert if icat e Prof ile Management f rom t he Command Line
The certprofile plug-in for manage me nt of IdM profile s allows privile ge d us e rs to import,
modify, or re move IdM ce rtificate profile s . To dis play all commands s upporte d by the plugin, run the ipa certprofile command:
$ ipa certprofile
Manage Certificate Profiles
...
EXAMPLES:
Import a profile that will not store issued certificates:
ipa certprofile-import ShortLivedUserCert \
--file UserCert.profile --desc "User Certificates" \
--store=false

415

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Delete a certificate profile:
ipa certprofile-del ShortLivedUserCert
...
Note that to pe rform the certprofile ope rations , you mus t be ope rating as a us e r who
has the re quire d pe rmis s ions . IdM include s the following ce rtificate profile -re late d
pe rmis s ions by de fault:
Syst em: Read Cert if icat e Pro f iles
Enable s us e rs to re ad all profile attribute s .
Syst em: Impo rt Cert if icat e Pro f ile
Enable s us e rs to import a ce rtificate profile into IdM.
Syst em: Delet e Cert if icat e Pro f ile
Enable s us e rs to de le te an e xis ting ce rtificate profile .
Syst em: Mo dif y Cert if icat e Pro f ile
Enable s us e rs to modify the profile attribute s and to dis able or e nable the profile .
All the s e pe rmis s ions are include d in the de fault CA Administrator privile ge . For more
information on IdM role -bas e d acce s s controls and managing pe rmis s ions , s e e
Se ction 26.4, “De fining Role -Bas e d Acce s s Controls ”.

No te
Whe n re que s ting a ce rtificate , the --profile-id option can be adde d to the ipa
cert-request command to s pe cify which profile to us e . If no profile ID is s pe cifie d,
the de fault caIPAserviceCert profile is us e d for the ce rtificate .
This s e ction only de s cribe s the mos t important as pe cts of us ing the ipa certprofile
commands for profile manage me nt. For comple te information about a command, run it with
the --help option adde d, for e xample :
$ ipa certprofile-mod --help
Usage: ipa [global-options] certprofile-mod ID [options]
Modify Certificate Profile configuration.
Options:
-h, --help
show this help message and exit
--desc=STR
Brief description of this profile
--store=BOOL
Whether to store certs issued using this profile
...

Import ing Cert if icat e Prof iles
To import a ne w ce rtificate profile to IdM, us e the ipa certprofile-import command.
Running the command without any options s tarts an inte ractive s e s s ion in which the
certprofile-import s cript prompts your for the information re quire d to import the
ce rtificate .

416

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

$ ipa certprofile-import
Profile ID: smime
Profile description: S/MIME certificates
Store issued certificates [True]: TRUE
Filename of a raw profile. The XML format is not supported.: smime.cfg
-----------------------Imported profile "smime"
-----------------------Profile ID: smime
Profile description: S/MIME certificates
Store issued certificates: TRUE
The ipa certprofile-import command acce pts s e ve ral command-line options . Mos t
notably:
--file
This option pas s e s the file containing the profile configuration dire ctly to ipa
certprofile-import. For e xample :
$ ipa certprofile-import --file=smime.cfg
--store
This option s e ts the Store issued certificates attribute . It acce pts two value s :
True, which de live rs the is s ue d ce rtificate s to the clie nt and s tore s the m in
the targe t IdM principal's userCertificate attribute .
False, which de live rs the is s ue d ce rtificate s to the clie nt, but doe s not s tore
the m in IdM. This option is mos t commonly-us e d whe n is s uing multiple s hortte rm ce rtificate s is re quire d.
Import fails if the profile ID s pe cifie d with ipa certprofile-import is alre ady in us e or if
the profile conte nt is incorre ct. For e xample , the import fails if a re quire d attribute is
mis s ing or if the profile ID value de fine d in the s upplie d file doe s not match the profile ID
s pe cifie d with ipa certprofile-import.
To obtain a te mplate for a ne w profile , you can run the ipa certprofile-show command
with the --out option, which e xports a s pe cifie d e xis ting profile to a file . For e xample :
$ ipa certprofile-show caIPAserviceCert --out=file_name
You can the n e dit the e xporte d file as re quire d and import it as a ne w profile .

Displaying Cert if icat e Prof iles
To dis play all ce rtificate profile s curre ntly s tore d in IdM, us e the ipa certprofile-find
command:
$ ipa certprofile-find
-----------------3 profiles matched
-----------------Profile ID: caIPAserviceCert

417

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Profile description: Standard profile for network services
Store issued certificates: TRUE
Profile ID: IECUserRoles
...
To dis play information about a particular profile , us e the ipa certprofile-show
command:
$ ipa certprofile-show profile_ID
Profile ID: profile_ID
Profile description: S/MIME certificates
Store issued certificates: TRUE

Modif ying Cert if icat e Prof iles
To modify an e xis ting ce rtificate profile , us e the ipa certprofile-mod command. Pas s
the re quire d modifications with the command us ing the command-line options acce pte d by
ipa certprofile-mod. For e xample , to modify the de s cription of a profile and change
whe the r IdM s tore s the is s ue d ce rtificate s :
$ ipa certprofile-mod profile_ID --desc="New description" --store=False
-----------------------------------Modified Certificate Profile "profile_ID"
-----------------------------------Profile ID: profile_ID
Profile description: New description
Store issued certificates: FALSE
To update the ce rtificate profile configuration, import the file containing the update d
configuration us ing the --file option. For e xample :
$ ipa certprofile-mod profile_ID --file=new_configuration.cfg

Delet ing Cert if icat e Prof iles
To re move an e xis ting ce rtificate profile from IdM, us e the ipa certprofile-del
command:
$ ipa certprofile-del profile_ID
----------------------Deleted profile "profile_ID"
-----------------------

28.9.2. Cert if icat e Prof ile Management f rom t he Web UI
To manage ce rtificate profile s from the IdM we b UI:
1. Ope n the Authentication tab and the Certificates s ubtab.
2. Ope n the Certificate Profiles s e ction.

418

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

Figure 28.1. Cert if icat e Pro f ile Management in t he Web UI
In the Certificate Profiles s e ction, you can dis play information about e xis ting profile s ,
modify the ir attribute s , or de le te s e le cte d profile s .
For e xample , to modify an e xis ting ce rtificate profile :
1. Click on the name of the profile to ope n the profile configuration page .
2. In the profile configuration page , fill in the re quire d information.
3. Click Save to confirm the ne w configuration.

Figure 28.2. Mo dif ying a Cert if icat e Pro f ile in t he Web UI
If you e nable the Store issued certificates option, the is s ue d ce rtificate s are
de live re d to the clie nt as we ll as s tore d in the targe t IdM principal's userCertificate

419

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

attribute . If the option is dis able d, the is s ue d ce rtificate s are de live re d to the clie nt, but
not s tore d in IdM. Storing ce rtificate s is ofte n dis able d whe n is s uing multiple s hort-live d
ce rtificate s is re quire d.
Note that s ome ce rtificate profile manage me nt ope rations are curre ntly unavailable in the
we b UI:
It is not pos s ible to import a ce rtificate profile in the we b UI. To import a ce rtificate , us e
the ipa certprofile-import command.
It is not pos s ible to s e t, add, or de le te attribute and value pairs . To modify the attribute
and value pairs , us e the ipa certprofile-mod command.
It is not pos s ible to import update d ce rtificate profile configuration. To import a file
containing update d profile configuration, us e the ipa certprofile-mod -file=file_name command.
For more information about the commands us e d to manage ce rtificate profile s , s e e
Se ction 28.9.1, “Ce rtificate Profile Manage me nt from the Command Line ”.

28.9.3. Upgrading IdM Servers wit h Cert if icat e Prof iles
Whe n upgrading an IdM s e rve r, the profile s include d in the s e rve r are all importe d and
e nable d.
If you upgrade multiple s e rve r re plicas , the profile s of the firs t upgrade d re plica are
importe d. On the othe r re plicas , IdM de te cts the pre s e nce of othe r profile s and doe s not
import the m or re s olve any conflicts be twe e n the two s e ts of profile s . If you have cus tom
profile s de fine d on re plicas , make s ure the profile s on all re plicas are cons is te nt be fore
upgrading.

28.10. Cert ificat e Aut horit y ACL Rules
Ce rtificate Authority acce s s control lis t (CA ACL) rule s de fine which profile s can be us e d to
is s ue ce rtificate s to which us e rs , s e rvice s , or hos ts . By as s ociating profile s , principals ,
and groups , CA ACLs pe rmit principals or groups to re que s t ce rtificate s us ing particular
profile s :
an ACL can pe rmit acce s s to multiple profile s
an ACL can have multiple us e rs , s e rvice s , hos ts , us e r groups , and hos t groups
as s ociate d with it
For e xample , us ing CA ACLs , the adminis trator can re s trict us e of a profile inte nde d for
e mploye e s working from an office locate d in London only to hos ts that are me mbe rs of
the London office -re late d group.

No te
By combining ce rtificate profile s , de s cribe d in Se ction 28.9, “Ce rtificate Profile s ”, and
CA ACLs , the adminis trator can de fine and control acce s s to cus tom ce rtificate
profile s . For a de s cription of us ing profile s and CA ACLs to is s ue us e r ce rtificate s ,
s e e Se ction 9.11, “Is s uing Us e r Ce rtificate s with the IdM CA”.

420

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

28.10.1. CA ACL Management f rom t he Command Line
The caacl plug-in for manage me nt of CA ACL rule s allows privile ge d us e rs to add, dis play,
modify, or de le te a s pe cifie d CA ACL. To dis play all commands s upporte d by the plug-in,
run the ipa caacl command:
$ ipa caacl
Manage CA ACL rules.
...
EXAMPLES:
Create a CA ACL "test" that grants all users access to the
"UserCert" profile:
ipa caacl-add test --usercat=all
ipa caacl-add-profile test --certprofiles UserCert
Display the properties of a named CA ACL:
ipa caacl-show test
...
Note that to pe rform the caacl ope rations , you mus t be ope rating as a us e r who has the
re quire d pe rmis s ions . IdM include s the following CA ACL-re late d pe rmis s ions by de fault:
Syst em: Read CA ACLs
Enable s the us e r to re ad all attribute s of the CA ACL.
Syst em: Add CA ACL
Enable s the us e r to add a ne w CA ACL.
Syst em: Delet e CA ACL
Enable s the us e r to de le te an e xis ting CA ACL.
Syst em: Mo dif y CA ACL
Enable s the us e r to modify an attribute of the CA ACL and to dis able or e nable
the CA ACL.
Syst em: Manage CA ACL membership
Enable s the us e r to manage the CA, profile , us e r, hos t, and s e rvice me mbe rs hip
in the CA ACL.
All the s e pe rmis s ions are include d in the de fault CA Administrator privile ge . For more
information on IdM role -bas e d acce s s controls and managing pe rmis s ions , s e e
Se ction 26.4, “De fining Role -Bas e d Acce s s Controls ”.
This s e ction de s cribe s only the mos t important as pe cts of us ing the ipa caacl
commands for CA ACL manage me nt. For comple te information about a command, run it
with the --help option adde d, for e xample :
$ ipa caacl-mod --help
Usage: ipa [global-options] caacl-mod NAME [options]

421

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Modify a CA ACL.
Options:
-h, --help
--desc=STR
--profilecat=['all']
...

show this help message and exit
Description
Profile category the ACL applies to

Creat ing CA ACLs
To cre ate a ne w CA ACL, us e the ipa caacl-add command. Running the command without
any options s tarts an inte ractive s e s s ion in which the ipa caacl-add s cript prompts your
for the re quire d information about the ne w CA ACL.
$ ipa caacl-add
ACL name: smime_acl
-----------------------Added CA ACL "smime_acl"
-----------------------ACL name: smime_acl
Enabled: TRUE
Ne w CA ACLs are e nable d by de fault.
The mos t notable options acce pte d by ipa caacl-add are the options that as s ociate a CA
ACL with a ce rtificate profile , us e r, hos t, or s e rvice cate gory:
--profilecat
--usercat
--hostcat
--servicecat
IdM only acce pts the all value with the s e options , which as s ociate s the CA ACL with all
profile s , us e rs , hos ts , or s e rvice s . For e xample , to as s ociate the CA ACL with all us e rs
and us e r groups :
$ ipa caacl-add ca_acl_name --usercat=all
Profile , us e r, hos t, and s e rvice cate gorie s are an alte rnative to adding particular obje cts or
groups of obje cts to a CA ACL, which is de s cribe d in Se ction 28.10.1, “Adding Entrie s to CA
ACLs and Re moving Entrie s from CA ACLs ”. Note that it is not pos s ible to us e a cate gory
and als o add obje cts or groups of the s ame type ; for e xample , you cannot us e the -usercat=all option and the n add a us e r to the CA ACL with the ipa caacl-add-user -users=user_name command.

422

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

No te
Re que s ting a ce rtificate for a us e r or group us ing a ce rtificate profile fails if the us e r
or group are not adde d to the corre s ponding CA ACL. For e xample :
$ ipa cert-request CSR-FILE --principal user --profile-id
profile_id
ipa: ERROR Insufficient access: Principal 'user' is not permitted
to use CA '.' with profile 'profile_id' for certificate issuance.
You mus t e ithe r add the us e r or group to the CA ACL, as de s cribe d in
Se ction 28.10.1, “Adding Entrie s to CA ACLs and Re moving Entrie s from CA ACLs ”, or
as s ociate the CA ACL with the all us e r cate gory.

Displaying CA ACLs
To dis play all CA ACLs , us e the ipa caacl-find command:
$ ipa caacl-find
----------------2 CA ACLs matched
----------------ACL name: hosts_services_caIPAserviceCert
Enabled: TRUE
...
Note that ipa caacl-find acce pts the --profilecat, --usercat, --hostcat, and -servicecat options , which can be us e d to filte r the re s ults of the s e arch to CA ACLs with
the corre s ponding ce rtificate profile , us e r, hos t, or s e rvice cate gory. Note that IdM only
acce pts the all cate gory with the s e options . For more information about the options , s e e
Se ction 28.10.1, “Cre ating CA ACLs ”.
To dis play information about a particular CA ACL, us e the ipa caacl-show command:
$ ipa caacl-show ca_acl_name
ACL name: ca_acl_name
Enabled: TRUE
Host category: all
...

Modif ying CA ACLs
To modify an e xis ting CA ACL, us e the ipa caacl-mod command. Pas s the re quire d
modifications us ing the command-line options acce pte d by ipa caacl-mod. For e xample ,
to modify the de s cription of a CA ACL and as s ociate the CA ACL with all ce rtificate profile s :
$ ipa caacl-mod ca_acl_name --desc="New description" --profilecat=all
--------------------------Modified CA ACL "ca_acl_name"
---------------------------

423

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ACL name: smime_acl
Description: New description
Enabled: TRUE
Profile category: all
The mos t notable options acce pte d by ipa caacl-mod are the --profilecat, --usercat,
--hostcat, and --servicecat options . For a de s cription of the s e options , s e e
Se ction 28.10.1, “Cre ating CA ACLs ”.

Disabling and Enabling CA ACLs
To dis able a CA ACL, us e the ipa caacl-disable command:
$ ipa caacl-disable ca_acl_name
--------------------------Disabled CA ACL "ca_acl_name"
--------------------------A dis able d CA ACL is not applie d and cannot be us e d to re que s t a ce rtificate . Dis abling a
CA ACL doe s not re move it from IdM.
To e nable a dis able d CA ACL, us e the ipa caacl-enable command:
$ ipa caacl-enable ca_acl_name
--------------------------Enabled CA ACL "ca_acl_name"
---------------------------

Delet ing CA ACLs
To re move an e xis ting CA ACL, us e the ipa caacl-del command:
$ ipa caacl-del ca_acl_name

Adding Ent ries t o CA ACLs and Removing Ent ries f rom CA ACLs
Us ing the ipa caacl-add-* and ipa caacl-remove-* commands , you can add ne w
e ntrie s to a CA ACL or re move e xis ting e ntrie s .
ipa caacl-add-host and ipa caacl-remove-host
Adds or re move s a hos t or hos t group.
ipa caacl-add-profile and ipa caacl-remove-profile
Adds or re move s a profile .
ipa caacl-add-service and ipa caacl-remove-service
Adds or re move s a s e rvice .
ipa caacl-add-user and ipa caacl-remove-user
Adds or re move s a us e r or group.
For e xample :

424

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

$ ipa caacl-add-user ca_acl_name --groups=group_name
Note that it is not pos s ible to add an obje ct or a group of obje cts to a CA ACL and als o us e
a cate gory of the s ame obje ct, as de s cribe d in Se ction 28.10.1, “Cre ating CA ACLs ”; the s e
s e ttings are mutually e xclus ive . For e xample , if you atte mpt to run the ipa caacl-adduser --users=user_name command on a CA ACL s pe cifie d with the --usercat=all
option, the command fails :
$ ipa caacl-add-user ca_acl_name --users=user_name
ipa: ERROR: users cannot be added when user category='all'

No te
Re que s ting a ce rtificate for a us e r or group us ing a ce rtificate profile fails if the us e r
or group are not adde d to the corre s ponding CA ACL. For e xample :
$ ipa cert-request CSR-FILE --principal user --profile-id
profile_id
ipa: ERROR Insufficient access: Principal 'user' is not permitted
to use CA '.' with profile 'profile_id' for certificate issuance.
You mus t e ithe r add the us e r or group to the CA ACL, or as s ociate the CA ACL with
the all us e r cate gory, as de s cribe d in Se ction 28.10.1, “Cre ating CA ACLs ”.

For de taile d information on the re quire d s yntax for the s e commands and the available
options , run the commands with the --help option adde d. For e xample :
$ ipa caacl-add-user --help

28.10.2. CA ACL Management f rom t he Web UI
To manage CA ACLs from the IdM we b UI:
1. Ope n the Authentication tab and the Certificates s ubtab.
2. Ope n the CA ACLs s e ction.

425

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Figure 28.3. CA ACL Rules Management in t he Web UI
In the CA ACLs s e ction, you can add ne w CA ACLs , dis play information about e xis ting CA
ACLs , modify the ir attribute s , as we ll as e nable , dis able , or de le te s e le cte d CA ACLs .
For e xample , to modify an e xis ting CA ACL:
1. Click on the name of the CA ACL to ope n the CA ACL configuration page .
2. In the CA ACL configuration page , fill in the re quire d information.
The Profiles and Permitted to have certificates issued s e ctions allow you
to as s ociate the CA ACL with ce rtificate profile s , us e rs or us e r groups , hos ts or
hos t groups , or s e rvice s . You can e ithe r add the s e obje cts us ing the Add buttons ,
or s e le ct the Anyone option to as s ociate the CA ACL with all us e rs , hos ts , or
s e rvice s .
3. Click Save to confirm the ne w configuration.

Figure 28.4. Mo dif ying a CA ACL Rule in t he Web UI

426

⁠C hapt e r 28 . Managing Ce r t if ic at e s and Ce r t if ic at e Aut ho r it ie s

Chapt er 29. Disabling Anonymous Binds
Acce s s ing domain re s ource s and running clie nt tools always re quire Ke rbe ros
authe ntication. Howe ve r, the backe nd LDAP dire ctory us e d by the IdM s e rve r allows
anonymous binds by de fault. This pote ntially ope ns up all of the domain configuration to
unauthoriz e d us e rs , including information about us e rs , machine s , groups , s e rvice s ,
ne tgroups , and DNS configuration.
It is pos s ible to dis able anonymous binds on the 389 Dire ctory Se rve r ins tance by us ing
LDAP tools to re s e t the nsslapd-allow-anonymous-access attribute .
1. Change the nsslapd-allow-anonymous-access attribute to rootdse.
$ ldapmodify -x -D "cn=Directory Manager" -W -h server.example.com
-p 389 -ZZ
Enter LDAP Password:
dn: cn=config
changetype: modify
replace: nsslapd-allow-anonymous-access
nsslapd-allow-anonymous-access: rootdse
modifying entry "cn=config"

Impo rtant
Anonymous acce s s can be comple te ly allowe d (on) or comple te ly blocke d
(off). Howe ve r, comple te ly blocking anonymous acce s s als o blocks e xte rnal
clie nts from che cking the s e rve r configuration. LDAP and we b clie nts are not
ne ce s s arily domain clie nts , s o the y conne ct anonymous ly to re ad the root
DSE file to ge t conne ction information.
The rootdse allows acce s s to the root DSE and s e rve r configuration without
any acce s s to the dire ctory data.

2. Re s tart the 389 Dire ctory Se rve r ins tance to load the ne w s e tting.
# systemctl restart dirsrv.target

427

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 30. Changing Domain DNS Configurat ion
30.1. Set t ing DNS Ent ries for Mult i-Homed Servers
Some s e rve r machine s may s upport multiple ne twork inte rface cards (NICs ). Multi-home d
machine s typically have multiple IPs , all as s igne d to the s ame hos tname . This works fine
in IdM mos t of the time be caus e it lis te ns on all available inte rface s , e xce pt localhos t. For
a s e rve r to be available through any NIC, e dit the DNS z one file and add e ntrie s for e ach
IP addre s s . For e xample :
ipaserver
ipaserver
ipaserver

IN A
IN A
IN A

192.168.1.100
192.168.1.101
192.168.1.102

30.2. Set t ing up Addit ional Name Servers
The lis t of configure d name s e rve rs in /etc/resolv.conf only contains the IdM s e rve r
its e lf whe n configuration is finis he d. If the local named-pkcs11 s e rvice e ve r cras he s , the n
the IdM s e rve r is unable to run and DNS s e rvice s for the e ntire domain are no longe r
available .
Othe r DNS s e rve rs s hould be adde d manually to the IdM s e rve r's /etc/resolv.conf file .
[root@server ~]# vim /etc/resolv.conf
search example.com
; the IdM server
nameserver 127.0.0.1
; backup DNS servers
nameserver 198.51.100.0
nameserver 192.0.2.0

No te
A de fault limit of thre e s e rve rs is s e t for the /etc/resolv.conf file .
Othe r information about configuring the /etc/resolv.conf file is give n in the
resolv.conf manpage .

30.3. Changing Load Balancing for IdM Servers and Replicas
As Se ction 1.3.1, “IdM Se rve rs and Re plicas ” touche s on, IdM s e rve rs and re plicas in the
domain automatically s hare the load among ins tance s to maintain pe rformance . The load
balancing is de fine d firs t by the priority s e t for the s e rve r or re plica in its SRV e ntry, and
the n by the weight of that ins tance for s e rve rs /re plicas with the s ame priority. Clie nts
contact s e rve rs /re plicas with the highe s t priority and the n work the ir way down.

428

⁠C hapt e r 30 . Changing Do main DNS Co nf igur at io n

Load balancing is done automatically by s e rve rs , re plicas , and clie nts . The configuration
us e d for load balancing can be alte re d by changing the priority and the we ight give n to a
s e rve r or re plica.
(All re plicas are initially cre ate d with the s ame priority.)
For e xample , this give s s e rve r1 a highe r priority than s e rve r 2, me aning it will be
contacte d firs t:
$ 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 re cords is in RFC 2782.

429

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 31. Managing t he Server-Replica Relat ionships
Se ction 1.3.1, “IdM Se rve rs and Re plicas ” de s cribe s the re lations hip be twe e n s e rve rs
(original ins tance s ) and re plicas (copie d ins tance s ) in Ide ntity Manage me nt. This ne twork of
re late d s e rve rs and re plicas is the topology of the Ide ntity Manage me nt domain.
The topology is de fine d by a s e rie s of agre e me nts s e t be twe e n IdM s e rve rs and re plicas
that copy data be twe e n ins tance s . The s e re plication agre e me nts ide ntify what s e rve rs
and re plicas are active in the topology (me aning, re cogniz e d by othe r s e rve rs and
s e nding and updating information).
Changing the IdM topology by adding or re moving re plicas and s e rve rs is done by
managing the re plication agre e me nts be twe e n ins tance s . The s e re plication agre e me nts
are cre ate d be twe e n the mas te r s e rve r and the re plicas automatically by the ipareplica-install command as re plicas are cre ate d. Whe n re plicas are re move d or whe n
two ne w re plicas ne e d to communicate with e ach othe r, thos e re plication agre e me nts
mus t be manage d manually.

31.1. Managing Replicat ion Agreement s Bet ween IdM
Servers
Information is s hare d be twe e n the IdM s e rve rs and re plicas us ing multi-master replication.
What this me ans is that s e rve rs and re plicas all re ce ive update s and, the re fore , are data
mas te rs . The domain information is copie d be twe e n the s e rve rs and re plicas us ing
replication.

31.1.1. T he T opology of Replicat ion Agreement s
As re plicas are adde d to the domain, mutual re plication agre e me nts are automatically
cre ate d be twe e n the re plica and the s e rve r it is bas e d on. Additional re plication
agre e me nts can be cre ate d be twe e n othe r re plicas and s e rve rs or the configuration of
the re plication agre e me nt can be change d us ing the ipa-replica-manage command.
Whe n a re plica is cre ate d, the re plica ins tall s cript cre ate s two re plication agre e me nts :
one going from the mas te r s e rve r to the re plica and one going from the re plica to the
mas te r s e rve r.

430

⁠C hapt e r 31. Managing t he Se r ve r -Re plic a Re lat io ns hips

Figure 31.1. Server and Replica Agreement s
As more re plicas and s e rve rs are adde d to the domain, the re can be re plicas and
s e rve rs that have re plication agre e me nts to othe r s e rve rs and re plicas but not be twe e n
e ach othe r. For e xample , the firs t IdM s e rve r is Se rve r A. The n, the admin cre ate s Re plica
B, and the ins tall s cript cre ate s a Se rve r A => Re plica B re plication agre e me nt and a
Re plica B => Se rve r A re plication agre e me nt. Ne xt, the admin cre ate s Re plica C bas e d on
Se rve r A. The ins tall s cript cre ate s a Se rve r A => Re plica C re plication agre e me nt and a
Re plica C => Se rve r A re plication agre e me nt. Re plica B and Re plica C both have
re plication agre e me nts with Se rve r A — but the y do not have agre e me nts with e ach
othe r. For data availability, cons is te ncy, failove r tole rance , and pe rformance , it can be
be ne ficial to cre ate a pair of re plication agre e me nts be twe e n Re plica B and Re plica C,
e ve n though the ir data will e ve ntually be re plicate d ove r to e ach othe r through re plication
with Se rve r A.

31.1.2. T ypes of Replicat ion Agreement s
The re are thre e type s of re plication agre e me nts for IdM s e rve rs :
One s to re plicate dire ctory data (s uch as us e rs , groups , and policie s )
One s to re plicate us e r information with an Active Dire ctory s e rve r (a s ynchroniz ation
agre e me nt)
One s to re plicate ce rtificate and ke y data

31.1.3. Commands t o Manage Replicat ion Agreement s
Agre e me nts for both the dire ctory data and the s ynchroniz e d us e r data are manage d
us ing the ipa-replica-manage command. Agre e me nts for the ce rtificate and ke y data re
manage d us ing the ipa-csreplica-manage command.
The s e tools have the s ame commands , argume nts , and format. The diffe re nce s re late to
which s ubtre e within the IdM dire ctory is be ing re plicate d.

431

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

T able 31.1. Replica Management Co mmands
Co mmand

Descript io n

conne ct

Cre ate a ne w re plication agre e me nt
be twe e n the two s pe cifie d s e rve rs .
Re move s a re plication agre e me nt be twe e n
the two s pe cifie d s e rve rs .
Re move s all re plication agre e me nts for the
give n s e rve r and re move s it e ntire ly from
the re plication topology. This is us e d to
de commis s ion a s e rve r/re plica, not s imply
to change the re plication agre e me nts for it.
Lis ts the re plication agre e me nts . If no
s e rve r is give n, the n it lis ts all s e rve rs
involve d in the re plication topology. If a
s e rve r is s pe cifie d, the n it lis ts all of the
s e rve rs with which is has a re plication
agre e me nt.
Es s e ntially re s tarts re plication for the
give n s e rve r. It re trie ve s all of the
re plicate d data from the original s ource .
Force s an imme diate , incre me ntal update
(re plication e ve nt) for the s pe cifie d s e rve r.
Lis ts the re plication ID (a backe nd
ide ntifie r) for e ach s e rve r within the
re plication topology. For the ipa-replicamanage command only.
Runs a s pe cial tas k to re move all
outs tanding update s as s ociate d with a
give n re plication ID. For the ipa-replicamanage command only.

dis conne ct
de l

lis t

re -initializ e

force -s ync
lis t-ruv

cle an-ruv

31.1.4. List ing Replicat ion Agreement s
The ipa-replica-manage command can lis t all of the s e rve rs and re plicas in the
re plication topology, us ing the list command:
[root@server ~]# ipa-replica-manage list
srv1.example.com: master
srv2.example.com
srv3.example.com
srv4.example.com
Afte r ge tting the s e rve r/re plica lis t, the n it is pos s ible to lis t the re plication agre e me nts
for the s e rve r. The s e are the othe r s e rve rs /re plicas to which the s pe cifie d s e rve r s e nds
update s .
[root@server ~]# ipa-replica-manage list srv1.example.com
srv2.example.com
srv3.example.com
The s ame thing can be done for ce rtificate re plication agre e me nts by us ing the ipacsreplica-manage command.

432

⁠C hapt e r 31. Managing t he Se r ve r -Re plic a Re lat io ns hips

31.1.5. Creat ing Replicat ion Agreement s
Re plication agre e me nts are cre ate d by connecting one s e rve r to anothe r s e rve r. Whe n a
re plica is cre ate d from a mas te r s e rve r, thos e two s e rve rs have a re plication agre e me nt
be twe e n the m. Howe ve r, othe r s e rve rs within the topology do not have a re plication
agre e me nt with the ne w re plica. While data will mos t like ly be re plicate d acros s the
topology e ve ntually, adding additional re plication agre e me nts can improve pe rformance
and provide additional failove r. (In s ome topologie s , and de pe nding on how re plicas are
clone d from a mas te r, s ome change s could s till be mis s e d without additional re plication
agre e me nts .)
A ne w re plication agre e me nt is cre ate d us ing the connect command.
ipa-replica-manage connect server1 server2
If only one s e rve r is give n, the re plication agre e me nts are cre ate d be twe e n the local hos t
and the s pe cifie d s e rve r.
For e xample :
[root@server ~]# ipa-replica-manage connect srv2.example.com
srv4.example.com
Re plication occurs ove r s tandard LDAP; to e nable SSL, the n include the CA ce rtificate for
the local hos t (or the s pe cifie d server1). The CA ce rtificate is the n ins talle d in the re mote
s e rve r's ce rtificate databas e to e nable TLS/SSL conne ctions . For e xample :
[root@server ~]# ipa-replica-manage connect --cacert=/etc/ipa/ca.crt
srv2.example.com srv4.example.com
The s ame thing can be done for ce rtificate re plication agre e me nts by us ing the ipacsreplica-manage command.

31.1.6. Removing Replicat ion Agreement s
To re move a re plication agre e me nt be twe e n s pe cific s e rve rs /re plicas , us e the
disconnect command:
[root@server ~]# ipa-replica-manage disconnect srv2.example.com
srv4.example.com
Us ing the disconnect command re move s that one re plication agre e me nt but le ave s both
the s e rve r/re plica ins tance s in the ove rall re plication topology. To re move a s e rve r
e ntire ly from the IdM re plication topology, with all its data, (and, functionally, re moving it
from the IdM domain as a s e rve r), us e the del command:
[root@server ~]# ipa-replica-manage del srv2.example.com
The s ame thing can be done for ce rtificate re plication agre e me nts by us ing the ipacsreplica-manage command.

31.1.7. Forcing Replicat ion

433

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Re plication be twe e n s e rve rs and re plicas occurs on a s che dule . Although re plication is
fre que nt, the re can be time s whe n it is ne ce s s ary to initiate the re plication ope ration
manually. For e xample , if a s e rve r is be ing take n offline for mainte nance , it is ne ce s s ary
to flus h all of the que ue d re plication change s out of its change log be fore taking it down.
To initiate a re plication update manually, us e the force-sync command. The s e rve r which
re ce ive s the update is the local s e rve r; the s e rve r which s e nds the update s is s pe cifie d
in the --from option.
[root@server ~]# ipa-replica-manage force-sync --from srv1.example.com
The s ame thing can be done for ce rtificate re plication agre e me nts by us ing the ipacsreplica-manage command.

31.1.8. Reinit ializing IdM Servers
Whe n a re plica is firs t cre ate d, the databas e of the mas te r s e rve r is copie d, comple te ly,
ove r to the re plica databas e . This proce s s is calle d initialization. If a s e rve r/re plica is
offline for a long pe riod of time or the re is s ome kind of corruption in its databas e , the n
the s e rve r can be re -initializ e d, with a fre s h and update d s e t of data.
This is done us ing the re-initialize command. The targe t s e rve r be ing initializ e d is the
local hos t. The s e rve r or re plica from which to pull the data to initializ e the local databas e
is s pe cifie d in the --from option:
[root@server ~]# ipa-replica-manage re-initialize --from
srv1.example.com
The s ame thing can be done for ce rtificate re plication agre e me nts by us ing the ipacsreplica-manage command.

31.1.9. Resolving Replicat ion Problems
31.1.9.1. Serial Numbers Not Found Errors
The 389 Dire ctory Se rve r and Dogtag Ce rtificate Sys te m ins tance s s hare a s ingle
dire ctory databas e for data. Re plication agre e me nts are s e t up for diffe re nt s uffixe s within
that dire ctory.
The dire ctory and ce rtificate re plication agre e me nts are manage d through diffe re nt tools
and are cre ate d and re move d inde pe nde ntly. If a ce rtificate re plication agre e me nt is
re move d, but a data re plication agre e me nt is not, the re can be proble ms with us ing
ce rtificate s with s ome dire ctory e ntrie s .
For e xample , both data and ce rtificate re plication agre e me nts e xis t be twe e n Se rve r A and
Se rve r B. If the ce rtificate agre e me nt is re move d, both Se rve r A and Se rve r B s till have
ce rtificate authoritie s and are s till is s uing ce rtificate s , but that information is no longe r
be ing re plicate d. If Se rve r A is s ue s a ce rtificate to Hos t 1, and the n s ome one atte mpts to
us e Se rve r B to manage Hos t 1, Se rve r B re turns an e rror that it cannot ve rify Hos t 1's
ce rtificate s e rial numbe r.
Certificate operation cannot be completed: EXCEPTION (Certificate serial
number 0x2d not found)

434

⁠C hapt e r 31. Managing t he Se r ve r -Re plic a Re lat io ns hips

This is be caus e Se rve r B has information about Hos t 1 in its data dire ctory, but it doe s not
have the hos t ce rtificate in its ce rtificate dire ctory.
To work around this , e nable re plication be twe e n the two IdM s e rve rs .

31.1.9.2. Resolving Replicat ion Conf lict s
Change s — both for IdM domain data and for ce rtificate and ke y data — are re plicate d
be twe e n IdM s e rve rs and re plicas (and, in s imilar paths , be twe e n IdM and Active Dire ctory
s e rve rs ).
Eve n though re plication ope rations are run continuous ly, the re is a chance that change s
can be made on one IdM s e rve r at the s ame time diffe re nt change s are made to the
s ame e ntry on a diffe re nt IdM s e rve r. Whe n re plication be gins to proce s s thos e e ntrie s ,
the change s collide — this is a replication conflict.
Eve ry s ingle dire ctory modify ope ration is as s igne d a s e rve r-s pe cific change state number
(CSN) to track how thos e modifications are propagate d during re plication. The CSN als o
contains a modify time s tamp. Whe n the re is a re plication conflict, the time s tamp is
che cke d and the las t change wins .
Simply acce pting the mos t re ce nt change is e ffe ctive for re s olving conflicts with attribute
value s . That me thod is too blunt for s ome type s of ope rations , howe ve r, which affe ct the
dire ctory tre e . Some ope rations , like modrdn, DN change s , or adding or re moving pare nt
and child e ntrie s , re quire adminis trator re vie w be fore the conflict is re s olve d.

No te
Re plication conflicts are re s olve d by e diting the e ntrie s dire ctory in the LDAP
databas e .
Whe n the re is a re plication conflict, both e ntrie s are adde d to the dire ctory and are
as s igne d a nsds5ReplConflict attribute . This make s it e as y to s e arch for e ntrie s with a
conflict:
[jsmith@ server ~]$ ldapsearch -x -D "cn=directory manager" -w password
-b "dc=example,dc=com" "nsds5ReplConflict=*" \* nsds5ReplConflict
31.1.9.2.1. So lving Naming Co nf lict s
Whe n two e ntrie s are adde d to the IdM domain with the s ame DN, both e ntrie s are adde d
to the dire ctory, but the y are re name d to us e the nsuniqueid attribute as a naming
attribute . For e xample :
nsuniqueid=0a950601-435311e0-86a2f5bd3cd26022+uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
Thos e e ntrie s can be s e arche d for and dis playe d in the IdM CLI, but the y cannot be e dite d
or de le te d until the conflict is re s olve d and the DN is update d.
To re s olve the conflict:
1. Re name the e ntry us ing a diffe re nt naming attribute , and ke e p the old RDN. For
e xample :

435

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

ldapmodify -x -D "cn=directory manager" -w secret -h
ipaserver.example.com -p 389
dn: nsuniqueid=664460011dd211b2+uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
changetype: modrdn
newrdn: cn=TempValue
deleteoldrdn: 0
2. Re move the old RDN value of the naming attribute and the conflict marke r attribute .
For e xample :
ldapmodify -x -D "cn=directory manager" -w secret -h
ipaserver.example.com -p 389
dn: cn=TempValue,cn=users,cn=accounts,dc=example,dc=com
changetype: modify
delete: uid
dc: jsmith
delete: nsds5ReplConflict
-

No te
The unique ide ntifie r attribute nsuniqueid cannot be de le te d.
3. Re name the e ntry with the inte nde d attribute -value pair. For e xample :
ldapmodify -x -D "cn=directory manager" -w secret -h
ipaserver.example.com -p 389
dn: cn=TempValue,dc=example,dc=com
changetype: modrdn
newrdn: uid=jsmith
deleteoldrdn: 1
Se tting the value of the deleteoldrdn attribute to 1 de le te s the te mporary
attribute -value pair cn=TempValue. To ke e p this attribute , s e t the value of the
deleteoldrdn attribute to 0.
31.1.9.2.2. So lving Orphan Ent ry Co nf lict s
Whe n a de le te ope ration is re plicate d and the cons ume r s e rve r finds that the e ntry to be
de le te d has child e ntrie s , the conflict re s olution proce dure cre ate s a glue e ntry to avoid
having orphane d e ntrie s in the dire ctory.
In the s ame way, whe n an add ope ration is re plicate d and the cons ume r s e rve r cannot
find the pare nt e ntry, the conflict re s olution proce dure cre ate s a glue e ntry re pre s e nting
the pare nt s o that the ne w e ntry is not an orphan e ntry.
Glue entries are te mporary e ntrie s that include the obje ct clas s e s glue and
extensibleObject. Glue e ntrie s can be cre ate d in s e ve ral ways :

436

⁠C hapt e r 31. Managing t he Se r ve r -Re plic a Re lat io ns hips

If the conflict re s olution proce dure finds a de le te d e ntry with a matching unique
ide ntifie r, the glue e ntry is a re s urre ction of that e ntry, with the addition of the glue
obje ct clas s and the nsds5ReplConflict attribute .
In s uch cas e s , e ithe r modify the glue e ntry to re move the glue obje ct clas s and the
nsds5ReplConflict attribute to ke e p the e ntry as a normal e ntry or de le te the glue
e ntry and its child e ntrie s .
The s e rve r cre ate s a minimalis tic e ntry with the glue and extensibleObject obje ct
clas s e s .
In s uch cas e s , modify the e ntry to turn it into a me aningful e ntry or de le te it and all of its
child e ntrie s .

31.1.9.3. Cleaning RUV Errors
Each s e rve r re cords change s to its databas e in a change log; e ach change is as s igne d an
ide ntifie r calle d a replica update vector (RUV). The RUVs are a way of ide ntifying whe re
change s come from (the re plica) and the orde r to apply the m (through the change s tate
numbe r), as change s are made acros s multiple s e rve rs .
Whe n a s e rve r is re move d from re plication, all of the me tadata as s ociate d with that
s e rve r is re move d from the othe r s e rve rs ' re plication configuration. Howe ve r, if one
s e rve r is offline whe n the re plication topology is update d, the n the me tadata (RUVs ) for
the re plica re main in that s e rve r's configuration. Whe n re plication occurs , that s e rve r
re turns an e rror be caus e it e xpe cts information for a give n s e rve r (bas e d on the RUVs in
its configuration), and that one s e rve r is not s e nding update s any more .
[09/Sep/2011:09:03:43 -0600] NSMMReplicationPlugin - ruv_compare_ruv:
RUV [changelog max RUV] does not
contain element [{replica 55 ldap://localhost.localdomain:9389}
4e6a27ca000000370000 4e6a27e8000000370000]
which is present in RUV [database RUV]
...
[09/Sep/2011:09:03:43 -0600] NSMMReplicationPlugin replica_check_for_data_reload: Warning: for replica
dc=example,dc=com there were some differences between the changelog max
RUV and the database RUV.
To re s olve thos e e rrors , run a clean-ruv tas k to re move any RUVs as s ociate d with
re move d re plica. This is run agains t the re plica ID, which would be lis te d in the
389 Dire ctory Se rve r e rror logs :
...
contain element [{replica 55 ldap://localhost.localdomain:9389}
4e6a27ca000000370000 4e6a27e8000000370000]
...
For e xample :
[root@server ~]# ipa-replica-manage clean-ruv 55

437

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Warning
Running a clean-ruv tas k agains t the wrong re plica ID will corrupt all of the data
as s ociate d with that re plica in the re plication databas e . In that cas e , the re plica mus t
be re initializ e d to corre ct the e rrors ; re initializ ing a re plica is in Se ction 31.1.8,
“Re initializ ing IdM Se rve rs ”.

31.2. Removing a Replica
De le ting or demoting a re plica re move s the IdM re plica from the s e rve r/re plica topology
s o that it no longe r proce s s e s IdM re que s ts and it als o re move s the hos t machine its e lf
from the IdM domain.
1. On an IdM s e rve r, obtain a Ke rbe ros ticke t be fore running IdM tools .
[root@replica ~]# kinit admin
2. Lis t all of the configure d re plication agre e me nts for the IdM domain.
[root@replica ~]# ipa-replica-manage list
Directory Manager password:
ipaserver.example.com: master
ipaserver2.example.com: master
replica.example.com: master
replica2.example.com: master
3. Re moving the re plica from the topology involve s de le ting all the agre e me nts
be twe e n the re plica and the othe r s e rve rs in the IdM domain and all of the data
about the re plica in the domain configuration.
[root@replica ~]# ipa-replica-manage del replica.example.com
4. If the replica was configured with its own CA, the n als o us e the ipa-csreplicamanage command to re move all of the re plication agre e me nts be twe e n the
ce rtificate databas e s for the re plica.
This is re quire d if the re plica its e lf was configure d with a Dogtag Ce rtificate Sys te m
CA. It is not re quire d if only the mas te r s e rve r or othe r re plicas we re configure d
with a CA.
[root@replica ~]# ipa-csreplica-manage del replica.example.com
5. On the re plica, unins tall the re plica package s .
[root@replica ~]# ipa-server-install --uninstall -U

31.3. Renaming a Server or Replica Host Syst em

438

⁠C hapt e r 31. Managing t he Se r ve r -Re plic a Re lat io ns hips

The re is no way to change the hos tname for an IdM s e rve r or re plica machine . The
Ke rbe ros ke ys and ce rtificate manage me nt is too comple x to allow the hos tname to
change .
Rathe r, if a s e rve r or re plica ne e ds to be re name d, it is e as ie r to re place the ins tance .
1. Cre ate a ne w re plica, with a CA, with the ne w hos tname or IP addre s s . This is
de s cribe d in Chapte r 4, Setting up IdM Replicas.
2. Stop the original IdM s e rve r ins tance .
[root@oldserver ~]# ipactl stop
3. Ve rify that all othe r s e rve rs /re plicas and clie nts are working as be fore .
4. Unins tall the IdM s e rve r, as in Se ction 3.3, “Unins talling an IdM Se rve r”

439

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Chapt er 32. Migrat ing from an LDAP Direct ory t o IdM
Whe n an infras tructure has pre vious ly de ploye d an LDAP s e rve r for authe ntication and
ide ntity lookups , it is pos s ible to migrate the us e r data, including pas s words , to a ne w
Ide ntity Manage me nt ins tance , without los ing us e r or pas s word data.
Ide ntity Manage me nt has migration tools to he lp move dire ctory data and only re quire s
minimal update s to clie nts . Howe ve r, the migration proce s s as s ume s a s imple
de ployme nt s ce nario (one LDAP name s pace to one IdM name s pace ). For more comple x
e nvironme nts , s uch as one s with multiple name s pace s or cus tom s che ma, contact Re d Hat
s upport s e rvice s for as s is tance .

32.1. An Overview of LDAP t o IdM Migrat ion
The actual migration part of moving from an LDAP s e rve r to Ide ntity Manage me nt — the
proce s s of moving the data from one s e rve r to the othe r — is fairly s traightforward. The
proce s s is s imple : move data, move pas s words , and move clie nts .
T he crucial part o f migrat io n is no t dat a migrat io n; it is deciding ho w client s
are go ing t o be co nf igured t o use Ident it y Management . For e ach clie nt in the
infras tructure , you ne e d to de cide what s e rvice s (s uch as Ke rbe ros and SSSD) are be ing
us e d and what s e rvice s can be us e d in the final, IdM de ployme nt.
A s e condary, but s ignificant, cons ide ration is planning how to migrate pas s words .
Ide ntity Manage me nt re quire s Ke rbe ros has he s for e ve ry us e r account in addition to
pas s words . Some of the cons ide rations and migration paths for pas s words are cove re d in
Se ction 32.1.2, “Planning Pas s word Migration”.

32.1.1. Planning t he Client Conf igurat ion
Ide ntity Manage me nt can s upport a numbe r of diffe re nt clie nt configurations , with varying
de gre e s of functionality, fle xibility, and s e curity. De cide which configuration is be s t for
each individual client bas e d on its ope rating s ys te m, functional are a (s uch as de ve lopme nt
machine s , production s e rve rs , or us e r laptops ), and your IT mainte nance prioritie s .

Impo rtant
The diffe re nt clie nt configurations are not mutually exclusive. Mos t e nvironme nts will
have a mix of diffe re nt ways that clie nts us e to conne ct to the IdM domain.
Adminis trators mus t de cide which s ce nario is be s t for e ach individual clie nt.

32.1.1.1. Init ial Client Conf igurat ion (Pre-Migrat ion)
Be fore de ciding whe re you want to go with the clie nt configuration in Ide ntity Manage me nt,
firs t e s tablis h whe re you are be fore the migration.
The initial s tate for almos t all LDAP de ployme nts that will be migrate d is that the re is an
LDAP s e rvice providing ide ntity and authe ntication s e rvice s .

440

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

Figure 32.1. Basic LDAP Direct o ry and Client Co nf igurat io n
Linux and Unix clie nts us e PAM_LDAP and NSS_LDAP librarie s to conne ct dire ctly to the
LDAP s e rvice s . The s e librarie s allow clie nts to re trie ve us e r information from the LDAP
dire ctory as if the data we re s tore d in /etc/passwd or /etc/shadow. (In re al life , the
infras tructure may be more comple x if a clie nt us e s LDAP for ide ntity lookups and
Ke rbe ros for authe ntication or othe r configurations .)
The re are s tructural diffe re nce s be twe e n an LDAP dire ctory and an IdM s e rve r,
particularly in s che ma s upport and the s tructure of the dire ctory tre e . (For more
background on thos e diffe re nce s , s e e Se ction 1.1, “IdM v. LDAP: A More Focus e d Type of
Se rvice ”.) While thos e diffe re nce s may impact data (e s pe cially with the dire ctory tre e ,
which affe cts e ntry name s ), the y have little impact on the client configuration, s o it re ally
has little impact on migrating clie nts to Ide ntity Manage me nt.

32.1.1.2. Recommended Conf igurat ion f or Red Hat Ent erprise Linux
Client s
Re d Hat Ente rpris e Linux has a s e rvice calle d the System Security Services Daemon
(SSSD). SSSD us e s s pe cial PAM and NSS librarie s (pam_sss and nss_sss, re s pe ctive ly)
which allow SSSD to be inte grate d ve ry clos e ly with Ide ntity Manage me nt and le ve rage
the full authe ntication and ide ntity fe ature s in Ide ntity Manage me nt. SSSD has a numbe r of
us e ful fe ature s , like caching ide ntity information s o that us e rs can log in e ve n if the
conne ction is los t to the ce ntral s e rve r; the s e are de s cribe d in the System-Level
Authentication Guide.
Unlike ge ne ric LDAP dire ctory s e rvice s (us ing pam_ldap and nss_ldap), SSSD e s tablis he s
re lations hips be twe e n ide ntity and authe ntication information by de fining domains. A
domain in SSSD de fine s four backe nd functions : authe ntication, ide ntity lookups , acce s s ,
and pas s word change s . The SSSD domain is the n configure d to us e a provider to s upply
the information for any one (or all) of thos e four functions . An ide ntity provide r is always
re quire d in the domain configuration. The othe r thre e provide rs are optional; if an
authe ntication, acce s s , or pas s word provide r is not de fine d, the n the ide ntity provide r is
us e d for that function.
SSSD can us e Ide ntity Manage me nt for all of its backe nd functions . This is the ide al
configuration be caus e it provide s the full range of Ide ntity Manage me nt functionality, unlike
ge ne ric LDAP ide ntity provide rs or Ke rbe ros authe ntication. For e xample , during daily
ope ration, SSSD e nforce s hos t-bas e d acce s s control rule s and s e curity fe ature s in
Ide ntity Manage me nt.

441

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
During the migration proce s s from an LDAP dire ctory to Ide ntity Manage me nt, SSSD
can s e amle s s ly migrate us e r pas s words without additional us e r inte raction.

Figure 32.2. Client s and SSSD wit h an IdM Backend
The ipa-client-install s cript automatically configure d SSSD to us e IdM for all four of its
backe nd s e rvice s , s o Re d Hat Ente rpris e Linux clie nts are s e t up with the re comme nde d
configuration by de fault.

No te
This clie nt configuration is only s upporte d for Re d Hat Ente rpris e Linux 6.1 and late r
and Re d Hat Ente rpris e Linux 5.7 late r, which s upport the late s t ve rs ions of SSSD
and ipa-client. Olde r ve rs ions of Re d Hat Ente rpris e Linux can be configure d as
de s cribe d in Se ction 32.1.1.3, “Alte rnative Supporte d Configuration”.

32.1.1.3. Alt ernat ive Support ed Conf igurat ion
Unix and Linux s ys te ms s uch as Mac, Solaris , HP-UX, AIX, and Scie ntific Linux s upport all of
the s e rvice s that IdM manage s but do not us e SSSD. Like wis e , olde r Re d Hat
Ente rpris e Linux ve rs ions (6.1 and 5.6) s upport SSSD but have an olde r ve rs ion, which
doe s not s upport IdM as an ide ntity provide r.
Whe n it is not pos s ible to us e a mode rn ve rs ion of SSSD on a s ys te m, the n clie nts can be
configure d to conne ct to the IdM s e rve r as if it we re an LDAP dire ctory s e rvice for ide ntity
lookups (us ing nss_ldap) and to IdM as if it we re a re gular Ke rbe ros KDC (us ing
pam_krb5).

442

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

Figure 32.3. Client s and IdM wit h LDAP and Kerbero s
If a Re d Hat Ente rpris e Linux clie nt is us ing an olde r ve rs ion of SSSD, SSSD can s till be
configure d to us e the IdM s e rve r as its ide ntity provide r and its Ke rbe ros authe ntication
domain; this is de s cribe d in the SSSD configuration s e ction of the System-Level
Authentication Guide.
Any IdM domain clie nt can be configure d to us e nss_ldap and pam_krb5 to conne ct to the
IdM s e rve r. For s ome mainte nance s ituations and IT s tructure s , a s ce nario that fits the
lowe s t common de nominator may be re quire d, us ing LDAP for both ide ntity and
authe ntication (nss_ldap and pam_ldap). Howe ve r, it is ge ne rally be s t practice to us e the
mos t s e cure configuration pos s ible for a clie nt (me aning SSSD and Ke rbe ros or LDAP and
Ke rbe ros ).

32.1.2. Planning Password Migrat ion
Probably the mos t vis ible is s ue that can impact LDAP-to-Ide ntity Manage me nt migration is
migrating us e r pas s words .
Ide ntity Manage me nt (by de fault) us e s Ke rbe ros for authe ntication and re quire s that e ach
us e r has Ke rbe ros has he s s tore d in the Ide ntity Manage me nt Dire ctory Se rve r in addition
to the s tandard us e r pas s words . To ge ne rate the s e has he s , the us e r pas s word ne e ds to
be available to the IdM s e rve r in cle arte xt. This is the cas e whe n the us e r is cre ate d in
Ide ntity Manage me nt. Howe ve r, whe n the us e r is migrate d from an LDAP dire ctory, the
as s ociate d us e r pas s word is alre ady has he d, s o the corre s ponding Ke rbe ros ke y cannot
be ge ne rate d.

Impo rtant
Us e rs cannot authe nticate to the IdM domain or acce s s IdM re s ource s until the y
have Ke rbe ros has he s .
If a us e r doe s not have a Ke rbe ros has h ⁠ [6] , that us e r cannot log into the IdM domain
e ve n if he has a us e r account. The re are thre e options for migrating pas s words : forcing a
pas s word change , us ing a we b page , and us ing SSSD.
Migrating us e rs from an e xis ting s ys te m provide s a s moothe r trans ition but als o re quire s
paralle l manage me nt of LDAP dire ctory and IdM during the migration and trans ition
proce s s . If you do not pre s e rve pas s words , the migration can be pe rforme d more quickly
but it re quire s more manual work by adminis trators and us e rs .

443

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

32.1.2.1. Met hod 1: Using T emporary Passwords and Requiring a Change
Whe n pas s words are change d in Ide ntity Manage me nt, the y will be cre ate d with the
appropriate Ke rbe ros has he s . So one alte rnative for adminis trators is to force us e rs to
change the ir pas s words by re s e tting all us e r pas s words whe n us e r accounts are
migrate d. (This can als o be done s imply by re -cre ating the LDAP dire ctory accounts in IdM,
which automatically cre ate s accounts with the appropriate ke ys .) The ne w us e rs are
as s igne d a te mporary pas s word which the y change at the firs t login. No pas s words are
migrate d.

32.1.2.2. Met hod 2: Using t he Migrat ion Web Page
Whe n it is running in migration mode , Ide ntity Manage me nt has a s pe cial we b page in its
we b UI that will capture a cle arte xt pas s word and cre ate the appropriate Ke rbe ros has h.
https://ipaserver.example.com/ipa/migration
Adminis trators could te ll us e rs to authe nticate once to this we b page , which would
prope rly update the ir us e r accounts with the ir pas s word and corre s ponding Ke rbe ros
has h, without re quiring pas s word change s .

32.1.2.3. Met hod 3: Using SSSD (Recommended)
SSSD can work with IdM to mitigate the us e r impact on migrating by ge ne rating the
re quire d us e r ke ys . For de ployme nts with a lot of us e rs or whe re us e rs s houldn't be
burde ne d with pas s word change s , this is the be s t s ce nario.
1. A us e r trie s to log into a machine with SSSD.
2. SSSD atte mpts to pe rform Ke rbe ros authe ntication agains t the IdM s e rve r.
3. Eve n though the us e r e xis ts in the s ys te m, the authe ntication will fail with the e rror
key type is not supported be caus e the Ke rbe ros has he s do not ye t e xis t.
4. SSSD the n pe rforms a plain te xt LDAP bind ove r a s e cure conne ction.
5. IdM inte rce pts this bind re que s t. If the us e r has a Ke rbe ros principal but no
Ke rbe ros has he s , the n the IdM ide ntity provide r ge ne rate s the has he s and s tore s
the m in the us e r e ntry.
6. If authe ntication is s ucce s s ful, SSSD dis conne cts from IdM and trie s Ke rbe ros
authe ntication again. This time , the re que s t s ucce e ds be caus e the has h e xis ts in
the e ntry.
That e ntire proce s s is e ntire ly trans pare nt to the us e r; as far as us e rs know, the y s imply
log into a clie nt s e rvice and it works as normal.

32.1.2.4. Migrat ing Cleart ext LDAP Passwords
Although in mos t de ployme nts LDAP pas s words are s tore d e ncrypte d, the re may be s ome
us e rs or s ome e nvironme nts that us e cle arte xt pas s words for us e r e ntrie s .
Whe n us e rs are migrate d from the LDAP s e rve r to the IdM s e rve r, the ir cle arte xt
pas s words are not migrate d ove r. Ide ntity Manage me nt doe s not allow cle arte xt
pas s words . Ins te ad, a Ke rbe ros principle is cre ate d for the us e r, the ke ytab is s e t to true ,
and the pas s word is s e t as e xpire d. This me ans that Ide ntity Manage me nt re quire s the
us e r to re s e t the pas s word at the ne xt login.

444

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

No te
If pas s words are has he d, the pas s word is s ucce s s fully migrate d through SSSD and
the migration we b page , as in Se ction 32.1.2.2, “Me thod 2: Us ing the Migration We b
Page ” and Se ction 32.1.2.3, “Me thod 3: Us ing SSSD (Re comme nde d)”.

32.1.2.5. Aut omat ically Reset t ing Passwords T hat Do Not Meet
Requirement s
If us e r pas s words in the original dire ctory do not me e t the pas s word policie s de fine d in
Ide ntity Manage me nt, the n the pas s words mus t be re s e t afte r migration.
Pas s word re s e ts are done automatically the firs t time the us e rs atte mpts to kinit into
the IdM domain.
[jsmith@server ~]$ kinit
Password for jsmith@EXAMPLE.COM:
Password expired. You must change it now.
Enter new password:
Enter it again:

32.1.3. Migrat ion Considerat ions and Requirement s
As you are planning migrating from an LDAP s e rve r to Ide ntity Manage me nt, make s ure
that your LDAP e nvironme nt is able to work with the Ide ntity Manage me nt migration s cript.

32.1.3.1. LDAP Servers Support ed f or Migrat ion
The migration proce s s from an LDAP s e rve r to Ide ntity Manage me nt us e s a s pe cial s cript,
ipa migrate-ds, to pe rform the migration. This s cript has ce rtain e xpe ctations about the
s tructure of the LDAP dire ctory and LDAP e ntrie s in orde r to work. Migration is s upporte d
only for LDAPv3-compliant dire ctory s e rvice s , which include s e ve ral common dire ctorie s :
SunONE Dire ctory Se rve r
Apache Dire ctory Se rve r
Ope nLDAP
Migration from an LDAP s e rve r to Ide ntity Manage me nt has be e n te s te d with Re d Hat
Dire ctory Se rve r.

No te
Migration us ing the migration s cript is not s upporte d for Micros oft Active Dire ctory
be caus e it is not an LDAPv3-compliant dire ctory. For as s is tance with migrating from
Active Dire ctory, contact Re d Hat Profe s s ional Se rvice s .

32.1.3.2. Migrat ion Environment Requirement s

445

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The re are many diffe re nt pos s ible configuration s ce narios for both Re d Hat
Dire ctory Se rve r and Ide ntity Manage me nt, and any of thos e s ce narios may affe ct the
migration proce s s . For the e xample migration proce dure s in this chapte r, the s e are the
as s umptions about the e nvironme nt:
A s ingle LDAP dire ctory domain is be ing migrate d to one IdM re alm. No cons olidation is
involve d.
Us e r pas s words are s tore d as a has h in the LDAP dire ctory that the IdM
Dire ctory Se rve r can s upport.
The LDAP dire ctory ins tance is both the ide ntity s tore and the authe ntication me thod.
Clie nt machine s are configure d to us e pam_ldap or nss_ldap to conne ct to the LDAP
s e rve r.
Entrie s us e only s tandard LDAP s che ma. Cus tom attribute s will not be migrate d to
Ide ntity Manage me nt.

32.1.3.3. Migrat ion — IdM Syst em Requirement s
With a mode rate ly-s iz e d dire ctory (around 10,000 us e rs and 10 groups ), it is ne ce s s ary
to have a powe rful e nough targe t s ys te m (the IdM s ys te m) to allow the migration to
proce e d. The minimum re quire me nts for a migration are :
4 core s
4GB of RAM
30GB of dis k s pace
A SASL buffe r s iz e of 2MB
This is s e t in the nsslapd-sasl-max-buffer-size attribute in the
389 Dire ctory Se rve r ins tance for the IdM s e rve r. This attribute value is s e t us ing the
ldapmodify command in the cn=config s ubtre e .

32.1.3.4. Migrat ion T ools
Ide ntity Manage me nt us e s a s pe cific command, ipa migrate-ds, to drive the migration
proce s s s o that LDAP dire ctory data are prope rly formatte d and importe d cle anly into the
IdM s e rve r. Whe n us ing ipa migrate-ds, the re mote s ys te m us e r, s pe cifie d by the -binddn option, ne e ds to have re ad acce s s to the userPassword attribute , othe rwis e
pas s words will not be migrate d.
The Ide ntity Manage me nt s e rve r mus t be configure d to run in migration mode , and the n
the migration s cript can be us e d.

32.1.3.5. Improving Migrat ion Perf ormance
An LDAP migration is e s s e ntially a s pe cializ e d import ope ration for the
389 Dire ctory Se rve r ins tance within the IdM s e rve r. Tuning the 389 Dire ctory Se rve r
ins tance for be tte r import ope ration pe rformance can he lp improve the ove rall migration
pe rformance .
The re are two parame te rs that dire ctly affe ct import pe rformance :
The nsslapd-cachememsize attribute , which de fine s the s iz e allowe d for the e ntry
cache . This is a buffe r, that is automatically s e t to 80% of the total cache me mory s iz e .

446

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

For large import ope rations , this parame te r (and pos s ibly the me mory cache its e lf) can
be incre as e d to more e fficie ntly handle a large numbe r of e ntrie s or e ntrie s with large r
attribute s (s uch as ce rtificate chains and CRLs ).
This can be e dite d us ing the ldapmodify command; the configuration e ntrie s are in
cn=config.
The s ys te m ulimit s e tting, which s e ts the maximum numbe r of allowe d proce s s e s for
the s ys te m us e r. Es pe cially on 32-bit s ys te ms , it is pos s ible for the Dire ctory Se rve r
us e r to hit its proce s s limit whe n trying to proce s s a large databas e .
[root@server ~]# ulimit -u 4096
This is cove re d in the Re d Hat Dire ctory Se rve r Performance Tuning Guide at
https ://acce s s .re dhat.com/s ite /docume ntation/e nUS/Re d_Hat_Dire ctory_Se rve r/9.0/html/Pe rformance _Tuning_Guide /import.html.

32.1.3.6. Migrat ion Sequence
The re are four major s te ps whe n migrating to Ide ntity Manage me nt, but the orde r varie s
s lightly de pe nding on whe the r you want to migrate the s e rve r firs t or the clie nts firs t.
With a clie nt-bas e d migration, SSSD is us e d to change the clie nt configuration while an IdM
s e rve r is configure d:
1. De ploy SSSD.
2. Re configure clie nts to conne ct to the curre nt LDAP s e rve r and the n fail ove r to IdM.
3. Ins tall the IdM s e rve r.
4. Migrate the us e r data us ing the IdM ipa migrate-ds s cript. This e xports the data
from the LDAP dire ctory, formats for the IdM s che ma, and the n imports it into IdM.
5. Take the LDAP s e rve r offline and allow clie nts to fail ove r to Ide ntity Manage me nt
trans pare ntly.
With a s e rve r migration, the LDAP to Ide ntity Manage me nt migration come s firs t:
1. Ins tall the IdM s e rve r.
2. Migrate the us e r data us ing the IdM ipa migrate-ds s cript. This e xports the data
from the LDAP dire ctory, formats it for the IdM s che ma, and the n imports it into IdM.
3. Optional. De ploy SSSD.
4. Re configure clie nts to conne ct to IdM. It is not pos s ible to s imply re place the LDAP
s e rve r. The IdM dire ctory tre e — and the re fore us e r e ntry DNs — is diffe re nt than
the pre vious dire ctory tre e .
While it is re quire d that clie nts be re configure d, clie nts do not ne e d to be
re configure d imme diate ly. Update d clie nts can point to the IdM s e rve r while othe r
clie nts point to the old LDAP dire ctory, allowing a re as onable te s ting and trans ition
phas e afte r the data are migrate d.

447

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
Do not run both an LDAP dire ctory s e rvice and the IdM s e rve r for ve ry long in
paralle l. This introduce s the ris k of us e r data be ing incons is te nt be twe e n the
two s e rvice s .
Both proce s s e s provide a ge ne ral migration proce dure , but it may not work in e ve ry
e nvironme nt. Se t up a te s t LDAP e nvironme nt and te s t the migration proce s s be fore
atte mpting to migrate the re al LDAP e nvironme nt.

32.2. Examples for Using migrat e-ds
The data migration is pe rforme d with the ipa migrate-ds command. At its s imple s t, the
command take s the LDAP URL of the dire ctory to migrate and e xports the data bas e d on
common de fault s e ttings .
ipa migrate-ds ldap://ldap.example.com:389
It is pos s ible to cus tomiz e how the migrate-ds commands ide ntifie s and e xports data.
This is us e ful if the original dire ctory tre e has a unique s tructure or if s ome e ntrie s or
attribute s within e ntrie s s hould be e xclude d from migration.

32.2.1. Migrat ing Specif ic Subt rees
The de fault dire ctory s tructure place s pe rs on e ntrie s in the ou=People s ubtre e and group
e ntrie s in the ou=Groups s ubtre e . The s e s ubtre e s are containe r e ntrie s for thos e
diffe re nt type s of dire ctory data. If no options are pas s e d with the migrate-ds command,
the n the utility as s ume s that the give n LDAP dire ctory us e s the ou=People and
ou=Groups s tructure .
Many de ployme nts may have an e ntire ly diffe re nt dire ctory s tructure (or may only want to
e xport ce rtain parts of the dire ctory tre e ). The re are two options which allow
adminis trators to give the RDN of a diffe re nt us e r or group s ubtre e :
--user-container
--group-container

No te
In both cas e s , the s ubtre e mus t be the RDN only and mus t be re lative to the bas e
DN. For e xample , the ou=Employees,dc=example,dc=com s ubtre e can be migrate d
us ing --user-container=ou=Employees, but
ou=Employees,ou=People,dc=example,dc=com cannot be migrate d with that option
be caus e ou=Employees is not a dire ct child of the bas e DN.
For e xample :
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees -group-container="ou=employee groups" ldap://ldap.example.com:389

448

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

The re is a third option that allows adminis trators to s e t a bas e DN for migration: --basedn. With this option, it is pos s ible to change the targe t for containe r s ubtre e s . For
e xample :
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees --basedn="ou=people,dc=example,dc=com" ldap://ldap.example.com:389
Now, the ou=Employees us e r s ubtre e can be migrate d from within the large r ou=People
s ubtre e without migrating e ve ry pe ople -re late d s ubtre e .

32.2.2. Specif ically Including or Excluding Ent ries
By de fault, the migrate-ds s cript e xports e ve ry us e r e ntry with the person obje ct clas s
and e ve ry group e ntry within the give n us e r and group s ubtre e s .
In s ome migration paths , only s pe cific type s of us e rs and groups may ne e d to be
e xporte d, or, conve rs e ly, s pe cific us e rs and groups may ne e d to be e xclude d.
One option is to s e t pos itive ly which types of us e rs and groups to include . This is done by
s e tting which obje ct clas s e s to s e arch for whe n looking for us e r or group e ntrie s .
This is a re ally us e ful option whe n the re are cus tom obje ct clas s e s us e d in an
e nvironme nt for diffe re nt us e r type s . For e xample , this migrate s only us e rs with the
cus tom fullTimeEmployee obje ct clas s :
[root@ipaserver ~]# ipa migrate-ds --user-objectclass=fullTimeEmployee
ldap://ldap.example.com:389
Be caus e of the diffe re nt type s of groups , this is als o ve ry us e ful for migrating only ce rtain
type s of groups (s uch as us e r groups ) while e xcluding othe r type s of groups , like
ce rtificate groups . For e xample :
[root@ipaserver ~]# ipa migrate-ds --group-objectclass=groupOfNames -group-objectclass=groupOfUniqueNames ldap://ldap.example.com:389
Pos itive ly s pe cifying us e r and groups to migrate bas e d on obje ct clas s implicitly e xclude s
all othe r us e rs and groups from migration.
Alte rnative ly, it can be us e ful to migrate all us e r and group e ntrie s e xce pt for jus t a s mall
handful of e ntrie s . Spe cific us e r or group accounts can be e xclude d while all othe rs of that
type are migrate d. For e xample , this e xclude s a hobbie s group and two us e rs :
[root@ipaserver ~]# ipa migrate-ds --exclude-groups="Golfers Group" -exclude-users=jsmith --exclude-users=bjensen ldap://ldap.example.com:389
Spe cifying an obje ct clas s to migrate can be us e d toge the r with e xcluding s pe cific e ntrie s .
For e xample , this s pe cifically include s us e rs with the fullTimeEmployee obje ct clas s , ye t
e xclude s thre e manage rs :
[root@ipaserver ~]# ipa migrate-ds --user-objectclass=fullTimeEmployee -exclude-users=jsmith --exclude-users=bjensen --exclude-users=mreynolds
ldap://ldap.example.com:389

32.2.3. Excluding Ent ry At t ribut es

449

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

By de fault, e ve ry attribute and obje ct clas s for a us e r or group e ntry is migrate d. The re
are s ome cas e s whe re that may not be re alis tic, e ithe r be caus e of bandwidth and ne twork
cons traints or be caus e the attribute data are no longe r re le vant. For e xample , if us e rs are
going to be as s igne d ne w us e r ce rtificate s as the y join the IdM domain, the n the re is no
re as on to migrate the userCertificate attribute .
Spe cific obje ct clas s e s and attribute s can be ignore d by the migrate-ds by us ing any of
s e ve ral diffe re nt options :
--user-ignore-objectclass
--user-ignore-attribute
--group-ignore-objectclass
--group-ignore-attribute
For e xample , to e xclude the userCertificate attribute and strongAuthenticationUser
obje ct clas s for us e rs and the groupOfCertificates obje ct clas s for groups :
[root@ipaserver ~]# ipa migrate-ds --user-ignoreattribute=userCertificate --user-ignoreobjectclass=strongAuthenticationUser --group-ignoreobjectclass=groupOfCertificates ldap://ldap.example.com:389

No te
Make s ure not to ignore any re quire d attribute s . Als o, whe n e xcluding obje ct
clas s e s , make s ure to e xclude any attribute s which are only s upporte d by that
obje ct clas s .

32.2.4. Set t ing t he Schema t o Use
By de fault, Ide ntity Manage me nt us e s RFC2307bis s che ma to de fine us e r, hos t, hos t
group, and othe r ne twork ide ntitie s . This s che ma option can be re s e t to us e RFC2307
s che ma ins te ad:
[root@ipaserver ~]# ipa migrate-ds --schema=RFC2307
ldap://ldap.example.com:389

32.3. Scenario 1: Using SSSD as Part of Migrat ion
Impo rtant
This is a ge ne ral migration proce dure , but it may not work in e ve ry e nvironme nt.
It is s trongly re comme nde d that you s e t up a te s t LDAP e nvironme nt and te s t the
migration proce s s be fore atte mpting to migrate the re al LDAP e nvironme nt.

450

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

1. Se t up SSSD. Us ing SSSD allows the re quire d Ke rbe ros ke ys and s e rve r
ce rtificate s to be de live re d to the clie nts .
a. Ins tall SSSD on e ve ry clie nt machine :
[root@server ]# yum install sssd
b. Configure an LDAP ide ntity provide r in SSSD to us e the e xis ting
Dire ctory Se rve r for all functions (authe ntication, ide ntity lookups , acce s s ,
and pas s word change s ). This e ns ure s e ve ry clie nt works prope rly with the
e xis ting dire ctory s e rvice .
2. Ins tall Ide ntity Manage me nt, including any cus tom LDAP dire ctory s che ma ⁠ [7] , on a
diffe re nt machine from the e xis ting LDAP dire ctory.
3. Enable the IdM s e rve r to allow migration:
[root@server ]# ipa config-mod --enable-migration=TRUE
4. Dis able the compat plug-in.
[root@server ]# ipa-compat-manage disable
5. Re s tart the IdM Dire ctory Se rve r ins tance .
[root@server ]# systemctl restart dirsrv.target
6. Run the IdM migration s cript, ipa migrate-ds. At its mos t bas ic, this re quire s only
the LDAP URL of the LDAP dire ctory ins tance to migrate :
[root@server ]# ipa migrate-ds ldap://ldap.example.com:389
Simply pas s ing the LDAP URL migrate s all of the dire ctory data us ing common
de fault s e ttings . The us e r and group data can be s e le ctive ly migrate d by s pe cifying
othe r options , as cove re d in Se ction 32.2, “Example s for Us ing migrate -ds ”.
Once the information is e xporte d, the s cript adds all re quire d IdM obje ct clas s e s
and attribute s and conve rts DNs in attribute s to match the IdM dire ctory tre e .
7. Re -e nable the compat plug-in.
[root@server ]# ipa-compat-manage enable
8. Re s tart the IdM Dire ctory Se rve r ins tance .
[root@server ]# systemctl restart dirsrv.target
9. Move clie nts that have SSSD ins talle d from the LDAP backe nd to the
Ide ntity Manage me nt backe nd and e nroll the m as clie nt with IdM. This downloads
the re quire d ke ys and ce rtificate s .
On Re d Hat Ente rpris e Linux clie nts , this can be done us ing the ipa-clientinstall command. For e xample :

451

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

[root@server ~]# ipa-client-install --enable-dns-updates
10. Have us e rs log into a machine with SSSD and Ide ntity Manage me nt backe nd. This
ge ne rate s the re quire d Ke rbe ros ke ys for the us e r.
To monitor the us e r migration proce s s , que ry the e xis ting LDAP dire ctory to s e e
which us e r accounts have a pas s word but do not ye t have a Ke rbe ros principal ke y.
[jsmith@server ~]$ ldapsearch -LL -x -D 'cn=Directory Manager' -w
secret -b 'ou=people,dc=example,dc=com' '(&(!(krbprincipalkey=*))
(userpassword=*))' uid

No te
Include the quote s around the filte r s o that it is not inte rpre te d by the s he ll.
11. Once us e rs have be e n migrate d ove r, configure non-SSSD clie nts to us e the IdM
domain, as re quire d.
12. Whe n the migration of all clie nts and us e rs is comple te , de commis s ion the LDAP
dire ctory.

32.4. Scenario 2: Migrat ing an LDAP Server Direct ly t o
Ident it y Management
Impo rtant
This is a ge ne ral migration proce dure , but it may not work in e ve ry e nvironme nt.
It is s trongly re comme nde d that you s e t up a te s t LDAP e nvironme nt and te s t the
migration proce s s be fore atte mpting to migrate the re al LDAP e nvironme nt.

1. Ins tall the IdM s e rve r, including any cus tom LDAP dire ctory s che ma ⁠ [8] , on a
diffe re nt machine from the e xis ting LDAP dire ctory.
2. Dis able the compat plug-in.
[root@server ]# ipa-compat-manage disable
3. Re s tart the IdM Dire ctory Se rve r ins tance .
[root@server ]# systemctl restart dirsrv.target
4. Enable the IdM s e rve r to allow migration:
[root@server ]# ipa config-mod --enable-migration=TRUE

452

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

5. Run the IdM migration s cript, ipa migrate-ds. At its mos t bas ic, this re quire s only
the LDAP URL of the LDAP dire ctory ins tance to migrate :
[root@server ]# ipa migrate-ds ldap://ldap.example.com:389
Simply pas s ing the LDAP URL migrate s all of the dire ctory data us ing common
de fault s e ttings . The us e r and group data can be s e le ctive ly migrate d by s pe cifying
othe r options , as cove re d in Se ction 32.2, “Example s for Us ing migrate -ds ”.
Once the information is e xporte d, the s cript adds all re quire d IdM obje ct clas s e s
and attribute s and conve rts DNs in attribute s to match the IdM dire ctory tre e .
6. Re -e nable the compat plug-in.
[root@server ]# ipa-compat-manage enable
7. Re s tart the IdM Dire ctory Se rve r ins tance .
[root@server ]# systemctl restart dirsrv.target
8. Update the clie nt configuration to us e PAM_LDAP and NSS_LDAP to conne ct to IdM
ins te ad of conne cting to an LDAP dire ctory, NIS, or local file s .
9. Optional. Se t up SSSD. Us ing SSSD migrate s us e r pas s words without additional
us e r inte raction, as de s cribe d in Se ction 32.1.2, “Planning Pas s word Migration”.
a. Ins tall SSSD on e ve ry clie nt machine :
[root@server ]# yum install sssd
b. Run the ipa-client-install to configure SSSD and re late d s e rvice s to us e
the IdM s e rve r for ide ntity and Ke rbe ros authe ntication.
10. Ins truct us e rs to log into IdM us ing e ithe r SSSD clie nt or the migration we b page if
SSSD is not available on the clie nt. Both me thods automatically migrate the us e r
pas s word into Ide ntity Manage me nt.
https://ipaserver.example.com/ipa/migration
11. Optional. Re configure non-SSSD clie nts to us e Ke rbe ros authe ntication (pam_krb5)
ins te ad of LDAP authe ntication (pam_ldap).

No te
Us e PAM_LDAP module s until all of the us e rs have be e n migrate d; the n it is
pos s ible to us e PAM_KRB5.
12. Whe n the migration of all clie nts and us e rs is comple te , de commis s ion the LDAP
dire ctory.

32.5. Scenario 3: Migrat ing over SSL

453

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Both migrating us ing SSSD (Se ction 32.3, “Sce nario 1: Us ing SSSD as Part of Migration”)
and migrating dire ctly from LDAP (Se ction 32.4, “Sce nario 2: Migrating an LDAP Se rve r
Dire ctly to Ide ntity Manage me nt”) can be done ove r SSL. The migration proce dure its e lf is
the s ame , but it re quire s additional configuration on the IdM s e rve r.
IdM us e s the Ope nLDAP clie nt librarie s to conne ct to the re mote LDAP s e rve r. This me ans
that the Ope nLDAP configuration on the IdM s e rve r machine mus t have the CA ce rtificate
configuration for the LDAP directory's is s uing CA.
1. Download the CA ce rtificate for the CA which is s ue d the LDAP dire ctory's
ce rtificate s . The location and me thods to obtain the CA ce rtificate de pe nd on the CA
which is s ue d it or the location of the ce rtificate in the LDAP configuration.
Save the CA ce rtificate as /etc/ipa/remote.crt on the IdM s ys te m.
2. Update the SELinux labe ls for the CA ce rtificate file . The labe l s hould be
unconfined_u:object_r:etc_t:s0.
[root@server ~]# restorecon /etc/ipa/remote.crt
3. Configure the Ope nLDAP librarie s to us e the CA ce rtificate for the old LDAP
ins tance .
a. Ope n the Ope nLDAP configuration file .
[root@server ~]# vim /etc/openldap/ldap.conf
b. ⁠ The CA ce rtificate ne e ds to be importe d into the ce rtificate configuration.
The re are thre e ways that this can be done :
The TLS_CACERT parame te r can be s e t to the PEM file (remote.crt) for
the CA of the re mote LDAP s e rve r.
TLS_CACERT=/etc/ipa/remote.crt
The CA ce rtificate can be loade d into the IdM NSS databas e , and that can
the n be re fe re nce d in the TLS_CACERTDIR parame te r.
[root@server ~]# certutil -A -d /etc/dirsrv/slapd-EXAMPLECOM -n "CA certificate" -t "CT,," -a -i
/etc/ipa/remote.crt
[root@server ~]# vim /etc/openldap/ldap.conf
....
TLS_CACERTDIR=/etc/dirsrv/slapd-EXAMPLE-COM
The CA ce rtificate can be in any dire ctory on the s ys te m, and that location
can be give n in the TLS_CACERTDIR parame te r.
[root@server ~]# vim /etc/openldap/ldap.conf
....
TLS_CACERTDIR=/etc/ipa/
Only o ne o f t ho se co nf igurat io n set t ings is required.

454

⁠C hapt e r 32. Migr at ing f r o m an LDAP Dir e c t o r y t o IdM

c. Re s tart the IdM Apache ins tance . The SSL configuration is loade d through the
Apache s e rve r.
[root@server ~]# systemctl restart httpd.service
d. Go through any re quire d migration pre paration and run the ipa migrate-ds
s cript, as de s cribe d in Se ction 32.3, “Sce nario 1: Us ing SSSD as Part of
Migration” and Se ction 32.4, “Sce nario 2: Migrating an LDAP Se rve r Dire ctly to
Ide ntity Manage me nt”.
e . Undo any change s that we re made to the ldap.conf file in s te p b. This can
pre ve nt future proble ms with trus ting the IdM CA or othe r ce rtificate -re late d
conflicts .
f. Re s tart the IdM Apache ins tance to load the update d SSL configuration.
[root@server ~]# systemctl restart httpd.service

[6] It is possible to use LDAP authentication in Identity Managem ent instead of Kerberos
authentication, which m eans that Kerberos hashes are not required for users. However, this
lim its the capabilities of Identity Managem ent and is not recom m ended.
[7] There is lim ited support for custom user and group schem a in Identity Managem ent.
[8] There is lim ited support for custom user and group schem a in Identity Managem ent.

455

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

Appendix A. Troubleshoot ing Ident it y Management
A.1. Inst allat ion Issues
A.1.1. Server Inst allat ion
The s e rve r ins tallation log is locate d in /var/log/ipaserver-install.log. The IdM logs ,
both for the s e rve r and for IdM-as s ociate d s e rvice s , are cove re d in Se ction 27.4,
“Che cking IdM Se rve r Logs ”.

A.1.1.1. GSS Failures When Running IPA Commands
Imme diate ly afte r ins tallation, the re can be Ke rbe ros proble ms whe n trying to run an ipa* command. For e xample :
ipa: ERROR: Kerberos error: ('Unspecified GSS failure. Minor code may
provide more information', 851968)/('Decrypt integrity check failed', 1765328353)
The re are two pote ntial caus e s for this :
DNS is not prope rly configure d.
Active Dire ctory is in the s ame domain as the IdM s e rve r.

A.1.1.2. named Daemon Fails t o St art
If an IdM s e rve r is configure d to manage DNS and is s e t up s ucce s s fully, but the namedpkcs11 s e rvice fails to s tart, this can indicate that the re is a package conflict. Che ck the
/var/log/messages file for e rror me s s age s re late d to the named-pkcs11 s e rvice 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 us ually me ans that the bind-chroot package is ins talle d and is pre ve nting the namedpkcs11 s e rvice from s tarting. To re s olve this is s ue , re move the bind-chroot package and
the n re s tart the IdM s e rve r.
[root@server ~]# yum remove bind-chroot
# ipactl restart

A.1.2. Replica Inst allat ion
A.1.2.1. Cert if icat e Syst em set up f ailed.
If the re plica ins tallation fails during the ce rtificate s e rve r ins tance configuration, that
us ually me ans that the re quire d port is not available . This can be ve rifie d by che cking the
de bug logs for the CA, /var/log/pki-ca/debug, which may s how e rror me s s age s about
be ing unable to find ce rtain e ntrie s . For e xample :

456

⁠A ppe ndix A. T r o uble s ho o t ing Ide nt it y Manage me nt

[04/Feb/2015:22:29:03][http-9445-Processor25]: DatabasePanel
comparetAndWaitEntries ou=people,o=ipaca not found, let's wait
The only re s olution is to unins tall the re plica:
[root@ipareplica ~]# ipa-server-install --uninstall
Afte r unins talling the re plica, e ns ure that port 7389 on the re plica is available , and re try
the re plica ins tallation.

A.1.2.2. T here are SASL, GSS-API, and Kerberos errors in t he
389 Direct ory Server logs when t he replica st art s.
Whe n the re plica s tarts , the re can be a s e rie s of SASL bind e rrors re corde d in the
389 Dire ctory Se rve r logs s tating that the GSS-API conne ction faile d be caus e it could not
find a cre de ntials cache :
slapd_ldap_sasl_interactive_bind - Error: could not perform interactive
bind for id [] mech [GSSAPI]: error -2 (Local error) (SASL(-1): generic
failure: GSSAPI Error: Unspecified GSS failure. Minor code may provide
more information (Credentials cache file '/tmp/krb5cc_496' not found))
...
The re plica is looking for a cre de ntials cache in /tmp/krb5cc_496 (whe re 496 is the
389 Dire ctory Se rve r us e r ID) and cannot find it.
The re may als o be me s s age s that the s e rve r could not obtain Ke rbe ros cre de ntials for
the hos t principal:
set_krb5_creds - Could not get initial credentials for principal [ldap/
replica1.example.com] in keytab [WRFILE:/etc/dirsrv/ds.keytab]: 1765328324 (Generic error)
The s e e rrors are both re late d to how and whe n the 389 Dire ctory Se rve r ins tance loads
its Ke rbe ros cre de ntials cache .
While 389 Dire ctory Se rve r its e lf s upports multiple diffe re nt authe ntication me chanis ms ,
Ide ntity Manage me nt only us e s GSS-API for Ke rbe ros conne ctions . The
389 Dire ctory Se rve r ins tance for Ide ntity Manage me nt ke e ps its Ke rbe ros cre de ntials
cache in me mory. Whe n the 389 Dire ctory Se rve r proce s s e nds — like whe n the IdM
re plica is s toppe d — the cre de ntials cache is de s troye d.
Als o, the 389 Dire ctory Se rve r is us e d as the backe nd s torage for the principal
information for the KDC.
Whe n the re plica the n re s tarts , the 389 Dire ctory Se rve r ins tance s tarts firs t, s ince it
s upplie s information for the KDC, and the n the KDC s e rve r s tarts . This s tart orde r is what
caus e s the GSS-API and Ke rbe ros conne ction e rrors .
The 389 Dire ctory Se rve r atte mpts to ope n a GSS-API conne ction, but s ince the re is no
cre de ntials cache ye t and the KDC is not s tarte d, the GSS conne ction fails . Like wis e , any
atte mpt to obtain the hos t cre de ntials als o fails .

457

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

The s e e rrors are trans ie nt. The 389 Dire ctory Se rve r re -atte mpts the GSS-API conne ction
afte r the KDC s tarts and it has a cre de ntials cache . The 389 Dire ctory Se rve r logs the n
re cord a bind resumed me s s age .
The s e s tartup GSS-API conne ction failure s can be ignore d as long as that conne ction is
s ucce s s fully e s tablis he d.

A.1.2.3. T he DNS f orward record does not mat ch t he reverse address
Whe n configuring a ne w re plica, ins tallation can fail with a s e rie s of ce rtificate e rrors and,
ultimate ly an e rror that the DNS forward and re ve rs e re cords do not match.
ipa: DEBUG: approved_usage = SSLServer intended_usage = SSLServer
ipa: DEBUG: cert valid True for "CN=ipaserver2.example.com,O=EXAMPLE.COM"
ipa: DEBUG: handshake complete, peer = 192.168.17.37:9444
Certificate operation cannot be completed: Unable to communicate with
CMS (Not Found)
...
ipa: DEBUG: Created connection context.ldap2_21534032
ipa: DEBUG: Destroyed connection context.ldap2_21534032
The DNS forward record ipa-server2.example.com. does not match the
reverse address ipa-server2.example.org
The hos tname for e ve ry s e rve r and re plica in the IdM domain mus t be fully re s olvable for
both DNS forward (A) and re ve rs e (PTR) re cords . Both forward and re ve rs e re cords are
che cke d during authe ntication and ce rtificate -re late d ope rations . If the hos tname s in the
re cords do not match, the n both ce rtificate e rrors and DNS e rrors are re turne d.
This proble m can occur if multiple hos tname s are us e d for a s ingle PTR re cord. This is
allowe d in the DNS s tandard, but it cre ate s proble ms during IdM re plica cre ation whe n it
atte mpts to configure s e rvice s .
Ens ure the primary hos tname for the re plica hos t is the only one re turne d for PTR lookups
and re move any duplicate or additional hos tname s .
Ve rifying the DNS A and PTR re cords is cove re d in Se ction 2.4.2, “Hos t Name and DNS
Configuration”.

A.1.3. Client Inst allat ions
For clie nts configure d us ing ipa-client-install, the clie nt ins tallation log is locate d in
/var/log/ipaclient-install.log. The IdM logs , both for the s e rve r and clie nt and for
IdM-as s ociate d s e rvice s , are cove re d in Se ction 27.4, “Che cking IdM Se rve r Logs ”.
The following s e ctions de s cribe workarounds for ce rtain known clie nt ins tallation proble ms .

A.1.3.1. T he client can't resolve reverse host names when using an
ext ernal DNS.
While IdM can hos t its own DNS s e rve r as part of the domain s e rvice s , it can als o us e
e xte rnal DNS name s e rve r. Howe ve r, be caus e of s ome of the limitations of re ve rs e DNS,
the re can be proble ms with re s olving re ve rs e lookups if the e xte rnal DNS is lis te d in the
clie nt's /etc/resolv.conf file or if the re are othe r re s ource s on the ne twork with SRV

458

⁠A ppe ndix A. T r o uble s ho o t ing Ide nt it y Manage me nt

re cords , like Active Dire ctory.
The proble m is that the e xte rnal DNS name s e rve r re turns the wrong hos tname for the
IdM s e rve r.
One way this e xhibits is e rrors with finding the IdM s e rve r in the Ke rbe ros databas e :
Jun 30 11:11:48 server1 krb5kdc[1279](info): AS_REQ (4 etypes {18 17 16
23}) 192.168.60.135: NEEDED_PREAUTH: admin EXAMPLE COM for
krbtgt/EXAMPLE COM EXAMPLE COM, Additional pre-authentication required
Jun 30 11:11:48 server1 krb5kdc[1279](info): AS_REQ (4 etypes {18 17 16
23}) 192.168.60.135: ISSUE: authtime 1309425108, etypes {rep=18 tkt=18
ses=18}, admin EXAMPLE COM for krbtgt/EXAMPLE COM EXAMPLE COM
Jun 30 11:11:49 server1 krb5kdc[1279](info): TGS_REQ (4 etypes {18 17 16
23}) 192.168.60.135: UNKNOWN_SERVER: authtime 0, admin EXAMPLE COM for
HTTP/server1.wrong.example.com@EXAMPLE.COM, Server not found in Kerberos
database
The re are s e ve ral ways to work around this is s ue :
Edit the /etc/resolv.conf file to re move the e xte rnal DNS name s e rve r re fe re nce s .
Add re ve rs e lookup re cords for e ach IdM s e rve r.
Give the IdM clie nt or domain a s ubne t and forward all re que s ts for that s ubne t.

A.1.3.2. T he client is not added t o t he DNS zone.
If a clie nt is in a s ubne t not controlle d by an IdM DNS s e rve r, the n the nsupdate command
may fail to add the clie nt to the DNS z one whe n ipa-client-install runs .
If IdM is managing the DNS domain, the n add a z one e ntry for the clie nt manually, as
de s cribe d in Se ction 17.8, “Managing Re ve rs e DNS Zone s ”. For e xample :
[jsmith@ipaserver ~]$ kinit admin
[jsmith@ipaserver ~]$ ipa dnsrecord-add ipaclient.example.com www --arec 1.2.3.4
If the DNS domain is manage d outs ide of IdM, the re s ource re cord can be adde d manually
to the z one configuration. For information on DNS in Re d Hat Ente rpris e Linux, s e e the DNS
chapte r in the De ployme nt Guide .

A.1.4. Uninst alling an IdM Client
For Re d Hat Ente rpris e Linux clie nts , the ipa-client-install utility can be us e d to
unins tall the clie nt and re move it from the IdM domain. To re move the clie nt, us e the -uninstall option.
# ipa-client-install --uninstall

459

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

No te
The re is an unins tall option with the ipa-join command. This is calle d by ipaclient-install --uninstall as part of the unins tallation proce s s . Howe ve r, while
the ipa-join option re move s the clie nt from the domain, it doe s not actually
unins tall the clie nt or prope rly re move all of the IdM-re late d configuration. Do not run
ipa-join -u to atte mpt to unins tall the IdM clie nt. The only way to unins tall a clie nt
comple te ly is to us e ipa-client-install --uninstall.

A.2. UI Connect ion Problems
If ne gotiate authe ntication is not working, turn on ve rbos e logging for the authe ntication
proce s s to he lp diagnos e the is s ue :
1. Clos e all brows e r windows .
2. In a te rminal, s e t the ne w log le ve ls for Fire fox:
export NSPR_LOG_MODULES=negotiateauth:5
export NSPR_LOG_FILE=/tmp/moz.log
This e nable s ve rbos e logging and logs all information to /tmp/moz.log.
3. Re s tart the brows e r from the s ame te rminal window.
Some of the common e rror me s s age s and workarounds are in Table A.1, “UI Error Log
Me s s age s ”.
T able A.1. UI Erro r Lo g Messages
Erro r Lo g Message

Descript io n and Fix
The re are no Ke rbe ros ticke ts . Run kinit.

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

460

⁠A ppe ndix A. T r o uble s ho o t ing Ide nt it y Manage me nt

Erro r Lo g Message
-1208994096[8d683d8]: entering
nsAuthGSSAPI::GetNextToken()
-1208994096[8d683d8]:
gss_init_sec_context() failed:
Miscellaneous failure
Server not found in Kerberos
database

Descript io n and Fix
This can occur whe n you have s ucce s s fully
obtaine d Ke rbe ros ticke ts but are s till
unable to authe nticate to the UI. This
indicate s that the re is a proble m with the
Ke rbe ros configuration. The firs t place to
che ck is the [domain_realm] s e ction in the
/etc/krb5.conf file . Make s ure that the
IdM Ke rbe ros domain e ntry is corre ct and
matche s the configuration in the Fire fox
ne gotiation parame te rs . For e xample :
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM

Nothing is in the log file .

It is pos s ible that you are be hind a proxy
which is re moving the HTTP he ade rs
re quire d for ne gotiate authe ntication. Try to
conne ct to the s e rve r us ing HTTPS ins te ad,
which allows the re que s t to pas s through
unmodifie d. The n che ck the log file again.

A.3. IdM Server Problems
A.3.1. T here are SASL, GSS-API, and Kerberos errors in t he
389 Direct ory Server logs when t he replica st art s.
Whe n the re plica s tarts , the re can be a s e rie s of SASL bind e rrors re corde d in the
389 Dire ctory Se rve r logs s tating that the GSS-API conne ction faile d be caus e it could not
find a cre de ntials cache :
slapd_ldap_sasl_interactive_bind - Error: could not perform interactive
bind for id [] mech [GSSAPI]: error -2 (Local error) (SASL(-1): generic
failure: GSSAPI Error: Unspecified GSS failure. Minor code may provide
more information (Credentials cache file '/tmp/krb5cc_496' not found))
...
The re plica is looking for a cre de ntials cache in /tmp/krb5cc_496 (whe re 496 is the
389 Dire ctory Se rve r us e r ID) and cannot find it.
The re may als o be me s s age s that the s e rve r could not obtain Ke rbe ros cre de ntials for
the hos t principal:
set_krb5_creds - Could not get initial credentials for principal [ldap/
replica1.example.com] in keytab [WRFILE:/etc/dirsrv/ds.keytab]: 1765328324 (Generic error)
The s e e rrors are both re late d to how and whe n the 389 Dire ctory Se rve r ins tance loads
its Ke rbe ros cre de ntials cache .
While 389 Dire ctory Se rve r its e lf s upports multiple diffe re nt authe ntication me chanis ms ,
Ide ntity Manage me nt only us e s GSS-API for Ke rbe ros conne ctions . The
389 Dire ctory Se rve r ins tance for Ide ntity Manage me nt ke e ps its Ke rbe ros cre de ntials

461

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

cache in me mory. Whe n the 389 Dire ctory Se rve r proce s s e nds — like whe n the IdM
re plica is s toppe d — the cre de ntials cache is de s troye d.
Als o, the 389 Dire ctory Se rve r is us e d as the backe nd s torage for the principal
information for the KDC.
Whe n the re plica the n re s tarts , the 389 Dire ctory Se rve r ins tance s tarts firs t, s ince it
s upplie s information for the KDC, and the n the KDC s e rve r s tarts . This s tart orde r is what
caus e s the GSS-API and Ke rbe ros conne ction e rrors .
The 389 Dire ctory Se rve r atte mpts to ope n a GSS-API conne ction, but s ince the re is no
cre de ntials cache ye t and the KDC is not s tarte d, the GSS conne ction fails . Like wis e , any
atte mpt to obtain the hos t cre de ntials als o fails .
The s e e rrors are trans ie nt. The 389 Dire ctory Se rve r re -atte mpts the GSS-API conne ction
afte r the KDC s tarts and it has a cre de ntials cache . The 389 Dire ctory Se rve r logs the n
re cord a bind resumed me s s age .
The s e s tartup GSS-API conne ction failure s can be ignore d as long as that conne ction is
s ucce s s fully e s tablis he d.

A.4. Host Problems
A.4.1. Cert if icat e Not Found/Serial Number Not Found Errors
The IdM information is s tore d in a s e parate LDAP dire ctory than the ce rtificate information,
and the s e two LDAP databas e s are re plicate d s e parate ly. It is pos s ible for a re plication
agre e me nt to be broke n for one dire ctory and working for anothe r, which can caus e
proble ms with managing clie nts .
Spe cifically, if the re plication agre e me nt be twe e n the two CA databas e s is broke n, the n a
s e rve r may not be able to find ce rtificate information about a valid IdM clie nt, caus ing
ce rtificate e rrors :
Certificate operation cannot be completed: EXCEPTION (Certificate serial
number 0x2d not found)
For e xample , an IdM s e rve r and re plica have a function re plication agre e me nt be twe e n
the ir IdM databas e s , but the re plication agre e me nt be twe e n the ir CA databas e s is broke n.
If a hos t is cre ate d on the s e rve r, the hos t e ntry is re plicate d ove r to the re plica — but
the ce rtificate for that hos t is not re plicate d. The re plica is aware of the clie nt, but any
manage me nt ope rations for that clie nt will fail be caus e the re plica doe s n't have a copy of
its ce rtificate .

A.4.2. Debugging Client Connect ion Problems
Clie nt conne ction proble ms are appare nt imme diate ly. This can me an that us e rs cannot
log into a machine or atte mpts to acce s s us e r and group information fail (for e xample ,
getent passwd admin).
Authe ntication in IdM is manage d with the SSSD dae mon, which is de s cribe d in the SystemLevel Authentication Guide. If the re are proble ms with clie nt authe ntication, the n che ck the
SSSD information.

462

⁠A ppe ndix A. T r o uble s ho o t ing Ide nt it y Manage me nt

Firs t, che ck the SSSD logs in /var/log/sssd/. The re is a s pe cific log file for the DNS
domain, s uch as sssd_example.com.log. If the re is not e nough information in the logs at
the de fault logging le ve l, the n incre as e the log le ve l.
To incre as e the log le ve l:
1. Ope n the sssd.conf file .
vim /etc/sssd/sssd.conf
2. In the [domain/example.com] s e ction, s e t debug_level.
debug_level = 9
3. Re s tart the sssd dae mon.
service sssd restart
4. Che ck the /var/log/sssd/sssd_example.com.log file for the de bug me s s age s .

A.5. Kerberos Errors
Ke rbe ros e rrors fre que ntly be come appare nt whe n trying to conne ct to the re alm us ing
kinit or a s imilar clie nt. For information re late d to Ke rbe ros , firs t che ck the Ke rbe ros
manpage s , he lp file s , and othe r re s ource s .

Impo rtant
Ide ntity Manage me nt has its own command-line tools to us e to manage Ke rbe ros
policie s . Do no t us e kadmin or kadmin.local to manage IdM Ke rbe ros s e ttings .
The re are s e ve ral place s to look for Ke rbe ros e rror log information:
For kinit proble ms or othe r Ke rbe ros s e rve r proble ms , look at the KDC log in
/var/log/krb5kdc.log.
For IdM-s pe cific e rrors , look in /var/log/httpd/error_log.
The IdM logs , both for the s e rve r and for IdM-as s ociate d s e rvice s , are cove re d in
Se ction 27.4, “Che cking IdM Se rve r Logs ”.

A.5.1. Problems making connect ions wit h SSH when using GSS-API
If the re are bad re ve rs e DNS e ntrie s in the DNS configuration, the n it may not be pos s ible
to log into IdM re s ource s us ing SSH. Whe n SSH atte mpts to conne ct to a re s ource us ing
GSS-API as its s e curity me thod, GSS-API firs t che cks the DNS re cords . The bad re cords
pre ve nt SSH from locating the re s ource .
It is pos s ible to dis able re ve rs e DNS lookups in the SSH configuration. Rathe r than us ing
re ve rs e DNS re cords , SSH pas s e s the give n us e rname dire ctly to GSS-API.
To dis able re ve rs e DNS lookups with SSH, add or e dit the GSSAPITrustDNS dire ctive and
s e t the value to no.

463

Linux Do main Ide nt it y, Aut he nt ic at io n, and Po lic y Guide

# vim /etc/ssh/ssh_config
GSSAPITrustDNS no

A.5.2. T here are problems connect ing t o an NFS server af t er changing
a keyt ab
Clie nts atte mpting to mount NFS e xports re ly on the e xis te nce of a valid principal and
s e cre t ke y on both the NFS s e rve r and the clie nt hos t. Clie nts the ms e lve s s hould not
have acce s s to the NFS ke ytab. The ticke t for the NFS conne ction will be give n to clie nts
from the KDC.
Failure to e xport an update d ke ytab can caus e proble ms that are difficult to is olate . For
e xample , e xis ting s e rvice conne ctions may continue to function, but no ne w conne ctions
may be pos s ible .

A.6. SELinux Login Problems
SELinux maps only work for re mote us e rs , not for us e rs with a local account.
Whe n a re mote us e r logs in, authe nticating agains t the IdM s e rve r, the n the PAM SELinux
module s cre ate a file for that us e r in /etc/selinux/policy_name/logins/login.
If that file doe s not e xis t, the n it me ans that SSSD is not prope rly configure d to us e the
IdM s e rve r as one of its ide ntity provide rs . This is re quire d for SELinux mapping to work.
Configuring SSSD is cove re d in the "SSSD and Ide ntity Provide rs (Domains )" s e ction of the
Sys te m-Le ve l Authe ntication Guide .
If the file e xis ts but the re mote us e r was give n the wrong SELinux conte xt, the n the
pam_selinux module may not be prope rly configure d in the PAM s tack. This is the module
that re ads the SELinux information and s e ts the us e r conte xt. If the module is mis s ing,
the n nothing proce s s e s the SELinux map and the us e r is de fine d a de fault conte xt on the
s ys te m.

464

⁠A ppe ndix A. T r o uble s ho o t ing Ide nt it y Manage me nt

Appendix B. Revision Hist ory
Note that re vis ion numbe rs re late to the e dition of this manual, not to ve rs ion numbe rs of
Re d Hat Ente rpris e Linux.
Revisio n 7.0 -14
T ue Feb 0 9 20 16
Anet a Pet ro vá
As ync update : adde d s mart card authe ntication docs , update d s ome we b UI s cre e ns hots ,
update d the bas ics of manage me nt and re s tricting domains chapte rs , adde d ID vie ws and
OTP docs , move d unins tallation docs into ins tallation chapte rs , comme nte d out inde x, othe r
minor update s .
Revisio n 7.0 -13
T hu No v 19 20 15
Anet a Pet ro vá
Minor update s to ce rtificate profile manage me nt and promoting a re plica to mas te r.
Revisio n 7.0 -12
Fri No v 13 20 15
Anet a Pet ro vá
Ve rs ion for 7.2 GA re le as e with update s to DNS and othe r s e ctions .
Revisio n 7.0 -11
T hu No v 12 20 15
Ve rs ion for 7.2 GA re le as e .

Anet a Pet ro vá

Revisio n 7.0 -10
Fri Mar 13 20 15
As ync update with las t-minute e dits for 7.1.

T o máš Čapek

Revisio n 7.0 -8
Wed Feb 25 20 15
Ve rs ion for 7.1 GA re le as e .

T o máš Čapek

Revisio n 7.0 -6
Fri Dec 0 5 20 14
Re build to update the s ort orde r on the s plas h page .

T o máš Čapek

Revisio n 7.0 -4
Initial re le as e .

Ella Deo n Ballard

Wed Jun 11 20 14

465



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Title                           : Linux Domain Identity, Authentication, and Policy Guide
Creator                         : wkhtmltopdf 0.12.1-development
Producer                        : Qt 4.8.6
Create Date                     : 2016:02:09 06:34:27-05:00
Page Count                      : 469
Page Mode                       : UseOutlines

EXIF Metadata provided by EXIF.tools