Chapter 28. Configuration: Configuring IdM Servers and Replicas

The IdM servers and backend services are configured with default settings that are applicable in most environments.
There are some configuration areas where the IdM server configuration can be tweaked to improve security or performance in certain situations.
This chapter covers information about the IdM configuration, including files and logs used by the IdM server, and procedures for updating the IdM server configuration itself.

28.1. Identity Management Files and Logs

Identity Management is a unifying framework that combines disparate Linux services into a single management context. However, the underlying technologies — such as Kerberos, DNS, 389 Directory Server, and Dogtag Certificate System — retain their own configuration files and log files. Identity Management directly manages each of these elements through their own configuration files and tools.
This section covers the directories, files, and logs used specifically by IdM. For more information about the configuration files or logs for a specific server used within IdM, see the product documentation.

28.1.1. A Reference of IdM Server Configuration Files and Directories

Table 28.1. IdM Server Configuration Files and Directories

Directory or File Description
Server Configuration
/etc/ipa/ The main IdM configuration directory.
/etc/ipa/default.conf The primary configuration file for IdM.
/etc/ipa/server.conf An optional configuration file for IdM. This does not exist by default, but can be created to load custom configuration when the IdM server is started.
/etc/ipa/cli.conf An optional configuration file for IdM command-line tools. This does not exist by default, but can be created to apply custom configuration when the ipa is used.
/etc/ipa/ca.crt The CA certificate issued by the IdM server's CA.
~/.ipa/ A user-specific IdM directory that is created on the local system in the system user's home directory the first time the user runs an IdM command.
IdM Logs
~/.ipa/log/cli.log The log file for errors returned by XML-RPC calls and responses by the IdM command-line tools. This is created in the home directory for the system user who runs the tools, who may have a different name than the IdM user.
/var/log/ipaclient-install.log The installation log for the client service.
/var/log/ipaserver-install.log The installation log for the IdM server.
/etc/logrotate.d/ The log rotation policies for DNS, SSSD, Apache, Tomcat, and Kerberos.
System Services
/etc/rc.d/init.d/ipa/ The IdM server init script.
Web UI
/etc/ipa/html/ A symlink directory in the main configuration directory for the HTML files used by the IdM web UI.
/etc/httpd/conf.d/ipa.conf
/etc/httpd/conf.d/ipa-rewrite.conf
The configuration files used by the Apache host for the web UI application.
/etc/httpd/conf/ipa.keytab The keytab file used by the web UI service.
/usr/share/ipa/ The main directory for all of the HTML files, scripts, and stylesheets used by the web UI.
/usr/share/ipa/ipa-rewrite.conf
/usr/share/ipa/ipa.conf
The configuration files used by the Apache host for the web UI application.
/usr/share/ipa/updates/ Contains any updated files, schema, and other elements for Identity Management.
/usr/share/ipa/html/ Contains the HTML files, JavaScript files, and stylesheets used by the web UI.
/usr/share/ipa/ipaclient/ Contains the JavaScript files used to access Firefox's autoconfiguration feature and set up the Firefox browser to work in the IdM Kerberos realm.
/usr/share/ipa/migration/ Contains HTML pages, stylesheets, and Python scripts used for running the IdM server in migration mode.
/usr/share/ipa/ui/ Contains all of the scripts used by the UI to perform IdM operations.
/var/log/httpd/ The log files for the Apache web server.
Kerberos
/etc/krb5.conf The Kerberos service configuration file.
SSSD
/usr/share/sssd/sssd.api.d/sssd-ipa.conf The configuration file used to identify the IdM server, IdM Directory Server, and other IdM services used by SSSD.
/var/log/sssd/ The log files for SSSD.
389 Directory Server
/var/lib/dirsrv/slapd-REALM_NAME/ All of the schema, configuration, and database files associated with the Directory Server instance used by the IdM server.
/var/log/dirsrv/slapd-REALM_NAME/ Log files associated with the Directory Server instance used by the IdM server.
Dogtag Certificate System
/etc/pki-ca/ The main directory for the IdM CA instance.
/var/lib/pki-ca/conf/CS.cfg The main configuration file for the IdM CA instance.
/var/lib/dirsrv/slapd-PKI-IPA/ All of the schema, configuration, and database files associated with the Directory Server instance used by the IdM CA.
/var/log/dirsrv/slapd-PKI-IPA/ Log files associated with the Directory Server instance used by the IdM CA.
Cache Files
/var/cache/ipa/ Cache files for the IdM server and the IdM Kerberos password daemon.
System Backups
/var/lib/ipa/sysrestore/ Contains backups of all of the system files and scripts that were reconfigured when the IdM server was installed. These include the original .conf files for NSS, Kerberos (both krb5.conf and kdc.conf), and NTP.
/var/lib/ipa-client/sysrestore/ Contains backups of all of the system files and scripts that were reconfigured when the IdM client was installed. Commonly, this is the sssd.conf file for SSSD authentication services.

28.1.2. IdM Domain Services and Log Rotation

The 389 Directory Server instances used by IdM as a backend and by the Dogtag Certificate System have their own internal log rotation policies. Log rotation settings such as the size of the file, the period between log rotation, and how long log files are preserved can all be configured by editing the 389 Directory Server configuration. This is covered in the Red Hat Directory Server Administrator's Guide.
Several IdM domain services use the system logrotate service to handle log rotation and compression:
  • named (DNS)
  • httpd (Apache)
  • tomcat6
  • sssd
  • krb5kdc (Kerberos domain controller)
Most of these policies use the logrotate defaults for the rotation schedule (weekly) and the archive of logs (four, for four weeks' worth of logs).
The individual policies set post-rotation commands to restart the service after log rotation, that a missing log file is acceptable, and compression settings.

Example 28.1. Default httpd Log Rotation 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
}
There are other potential log settings, like compress settings and the size of the log file, which can be edited in either the global logrotate configuration or in the individual policies. The logrotate settings are covered in the logrotate manpage.

WARNING

Two policies set special create rules. All of the services create a new log file with the same name, default owner, and default permissions as the previous log. For the named and tomcat6 logs, the create is set with explicit permissions and user/group ownership.
[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 not change the permissions or the user and group which own the log files. This is required for both IdM operations and SELinux settings. Changing the ownership of the log roation policy or of the files can cause the IdM domains services to fail or to be unable to start.

28.1.3. About default.conf and Context Configuration Files

Certain global defaults — like the realm information, the LDAP configuration, and the CA settings — are stored in the default.conf file. This configuration file is referenced when the IdM client and servers start and every time the ipa command is run to supply information as operations are performed.
The parameters in the default.conf file are simple attribute=value pairs. The attributes are case-insensitive and order-insensitive.
[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
When adding more configuration attributes or overriding the global values, users can create additional context configuration files. A server.conf and cli.conf file can be created to create different options when the IdM server is started or when the ipa command is run, respectively. The IdM server checks the server.conf and cli.conf files first, and then checks the default.conf file.
Any configuration files in the /etc/ipa directory apply to all users for the system. Users can set individual overrides by creating default.conf, server.conf, or cli.conf files in their local IdM directory, ~/.ipa/. This optional file is merged with default.conf and used by the local IdM services.

28.1.4. Checking IdM Server Logs

Identity Management unifies several different Linux services, so it relies on those services' native logs for tracking and debugging those services.
The other services (Apache, 389 Directory Server, and Dogtag Certificate System) all have detailed logs and log levels. See the specific server documentation for more information on return codes, log formats, and log levels.

Table 28.2. IdM Log Files

Service Log File Description Additional Information
IdM server /var/log/ipaserver-install.log Server installation log
IdM server ~/.ipa/log/cli.log Command-line tool log
IdM client /var/log/ipaclient-install.log Client installation log
Apache server
/var/log/httpd/access_log
/var/log/httpd/error_log
These are standard access and error logs for Apache servers. Both the web UI and the XML-RPC command-line interface use Apache, so some IdM-specific messages will be recorded in the error log along with the Apache messages. Apache log chapter
Dogtag Certificate System /var/log/pki-ca-install.log The installation log for the IdM CA.
Dogtag Certificate System
/var/log/pki-ca/debug
/var/log/pki-ca/system
/var/log/pki-ca/transactions
/var/log/pki-ca/signedAudit
These logs mainly relate to certificate operations. In IdM, this is used for service principals, hosts, and other entities which use certificates. Logging chapter
389 Directory Server
/var/log/dirsrv/slapd-REALM/access
/var/log/dirsrv/slapd-REALM/audit
/var/log/dirsrv/slapd-REALM/errors
The access and error logs both contain detailed information about attempted access and operations for the domain Directory Server instance. The error log setting can be changed to provide very detailed output. The access log is buffered, so the server only writes to the log every 30 seconds, by default.
389 Directory Server
/var/log/dirsrv/slapd-REALM/access
/var/log/dirsrv/slapd-REALM/audit
/var/log/dirsrv/slapd-REALM/errors
This directory server instance is used by the IdM CA to store certificate information. Most operational data here will be related to server-replica interactions. The access log is buffered, so the server only writes to the log every 30 seconds, by default.
Kerberos /var/log/krb5libs.log This is the primary log file for Kerberos connections. This location is configured in the krb5.conf file, so it could be different on some systems.
Kerberos /var/log/krb5kdc.log This is the primary log file for the Kerberos KDC server. This location is configured in the krb5.conf file, so it could be different on some systems.
Kerberos /var/log/kadmind.log This is the primary log file for the Kerberos administration server. This location is configured in the krb5.conf file, so it could be different on some systems.
DNS /var/log/messages DNS error messages are included with other system messages. DNS logging is not enabled by default. DNS logging is enabled by running the querylog command:
/usr/sbin/rndc querylog
This begins writing log messages to the system's /var/log/messages file. To turn off logging, run the querylog command again.

28.1.4.1. Enabling Server Debug Logging

Debug logging for the IdM server is set in the server.conf file.

NOTE

Editing the default.conf configuration file affects all IdM components, not only the IdM server.
  1. Edit or create the server.conf file.
    vim server.conf
  2. Add the debug line and set its value to true.
    [global]
    debug=True
  3. Restart the Apache daemon to load the changes.
    service httpd restart

28.1.4.2. Debugging Command-Line Operations

Any command-line operation with the ipa command can return debug information by using the -v option. For example:
$ ipa -v user-show admin
ipa: INFO: trying https://ipaserver.example.com/ipa/xml
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

Using the option twice, -vv, displays the XML-RPC exchange:
$ 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\nAccept-Language: en-us\r\nAuthorization: negotiate YIIFgQYJKoZIhvcSAQICAQBuggVwMIIFbKADAgEFoQMCAQ6iBwMFACAAAACjggGHYYIBgzCCAX+gAwIBBaEZGxdSSFRTLkVORy5CT1MuUkVESEFULkNPTaI5MDegAwIBA6EwMC4bBEhUVFAbJmRlbGwtcGUxODUwLTAxLnJodHMuZW5nLmJvcy5yZWRoYXQuY29to4IBIDCCARygAwIBEqEDAgECooIBDgSCAQpV2YEWv03X+SENdUBfOhMFGc3Fvnd51nELV0rIB1tfGVjpNlkuQxXKSfFKVD3vyAUqkii255T0mnXyTwayE93W1U4sOshetmG50zeU4KDmhuupzQZSCb5xB0KPU4HMDvP1UnDFJUGCk9tcqDJiYE+lJrEcz8H+Vxvvl+nP6yIdUQKqoEuNhJaLWIiT8ieAzk8zvmDlDzpFYtInGWe9D5ko1Bb7Npu0SEpdVJB2gnB5vszCIdLlzHM4JUqX8p21AZV0UYA6QZOWX9OXhqHdElKcuHCN2s9FBRoFYK83gf1voS7xSFlzZaFsEGHNmdA0qXbzREKGqUr8fmWmNvBGpDiR2ILQep09lL56JqSCA8owggPGoAMCARKiggO9BIIDuarbB67zjmBu9Ax2K+0klSD99pNv97h9yxol8c6NGLB4CmE8Mo39rL4MMXHeOS0OCbn+TD97XVGLu+cgkfVcuIG4PMMBoajuSnPmIf7qDvfa8IYDFlDDnRB7I//IXtCc/Z4rBbaxk0SMIRLrsKf5wha7aWtN1JbizBMQw+J0UlN8JjsWxu0Ls75hBtIDbPf3fva3vwBf7kTBChBsheewSAlck9qUglyNxAODgFVvRrXbfkw51Uo++9qHnhh+zFSWepfv7US7RYK0KxOKFd+uauY1ES+xlnMvK18ap2pcy0odBkKu1kwJDND0JXUdSY08MxK2zb/UGWrVEf6GIsBgu122UGiHp6C+0fEu+nRrvtORY65Bgi8E1vm55fbb/9dQWNcQheL9m6QJWPw0rgc+E5SO99ON6x3Vv2+Zk17EmbZXinPd2tDe7fJ9cS9o/z7Qjw8z8vvSzHL4GX7FKi2HJdBST3nEgOC8PqO46UnAJcA8pf1ZkwCK9xDWH+5PSph6WnvpRqugqf/6cq+3jk3MEjCrx+JBJ8QL6AgN3oEB4kvjZpAC+FfTkdX59VLDwfL/r0gMw3ZNk0nLLCLkiiYUMTEHZBzJw9kFbsX3LmS8qQQA6rQ2L782DYisElywfZ/0Sax8JO/G62Zvy7BHy7SQSGIvcdAOafeNyfxaWM1vTpvSh0GrnllYfs3FhZAKnVcLYrlPTapR23uLgRMv+0c9wAbwuUDfKgOOl5vAd1j55VUyapgDEzi/URsLdVdcF4zigt4KrTByCwU2/pI6FmEPqB2tsjM2A8JmqA+9Nt8bjaNdNwCOWE0dF50zeL9P8oodWGkbRZLk4DLIurpCW1d6IyTBhPQ5qZqHJWeoGiFa5y94zBpp27goMPmE0BskXT0JQmveYflOeKEMSzyiWPL2mwi7KEMtfgCpwTIGP2LRE/QxNvPGkwFfO+PDjZGVw+APKkMKqclVXxhtJA/2NmBrO1pZIIJ9R+41sR/QoACcXIUXJnhrTwwR1viKCB5Tec87gN+e0Cf0g+fmZuXNRscwJfhYQJYwJqdYzGtZW+h8jDWqa2EPcDwIQwyFAgXNQ/aMvh1yNTECpLEgrMhYmFAUDLQzI2BDnfbDftIs0rXjSC0oZn/Uaoqdr4F5syOrYAxH47bS6MW8CxyylreH8nT2qQXjenakLFHcNjt4M1nOc/igzNSeZ28qW9WSr4bCdkH+ra3BVpT/AF0WHWkxGF4vWr/iNHCjq8fLF+DsAEx0Zs696Rg0fWZy079A\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: "<?xml version='1.0' encoding='UTF-8'?>\n<methodCall>\n<methodName>user_add</methodName>\n<params>\n<param>\n<value><array><data>\n<value><string>jrussell</string></value>\n</data></array></value>\n</param>\n<param>\n<value><struct>\n<member>\n<name>all</name>\n<value><boolean>0</boolean></value>\n</member>\n<member>\n<name>displayname</name>\n<value><string>Jane Russell</string></value>\n</member>\n<member>\n<name>cn</name>\n<value><string>Jane Russell</string></value>\n</member>\n<member>\n<name>noprivate</name>\n<value><boolean>0</boolean></value>\n</member>\n<member>\n<name>uidnumber</name>\n<value><int>999</int></value>\n</member>\n<member>\n<name>raw</name>\n<value><boolean>0</boolean></value>\n</member>\n<member>\n<name>version</name>\n<value><string>2.11</string></value>\n</member>\n<member>\n<name>gecos</name>\n<value><string>Jane Russell</string></value>\n</member>\n<member>\n<name>sn</name>\n<value><string>Russell</string></value>\n</member>\n<member>\n<name>krbprincipalname</name>\n<value><string>jrussell@EXAMPLE.COM</string></value>\n</member>\n<member>\n<name>givenname</name>\n<value><string>Jane</string></value>\n</member>\n<member>\n<name>initials</name>\n<value><string>JR</string></value>\n</member>\n</struct></value>\n</param>\n</params>\n</methodCall>\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+iejB4oAMCARKicQRvVl5x6Zt9PbWNzvPEWkdu+3PTCq/ZVKjGHM+1zDBz81GL/f+/Pr75zTuveLYn9de0C3k27vz96fn2HQsy9qVH7sfqn0RWGQWzl+kDkuD6bJ/Dp/mpJvicW5gSkCSH6/UCNuE4I0xqwabLIz8MM/5o
header: Connection: close
header: Content-Type: text/xml; charset=utf-8
body: "<?xml version='1.0' encoding='UTF-8'?>\n<methodResponse>\n<params>\n<param>\n<value><struct>\n<member>\n<name>result</name>\n<value><struct>\n<member>\n<name>dn</name>\n<value><string>uid=jrussell,cn=users,cn=accounts,dc=example,dc=com</string></value>\n</member>\n<member>\n<name>has_keytab</name>\n<value><boolean>0</boolean></value>\n</member>\n<member>\n<name>displayname</name>\n<value><array><data>\n<value><string>Jane Russell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>uid</name>\n<value><array><data>\n<value><string>jrussell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>objectclass</name>\n<value><array><data>\n<value><string>top</string></value>\n<value><string>person</string></value>\n<value><string>organizationalperson</string></value>\n<value><string>inetorgperson</string></value>\n<value><string>inetuser</string></value>\n<value><string>posixaccount</string></value>\n<value><string>krbprincipalaux</string></value>\n<value><string>krbticketpolicyaux</string></value>\n<"
body: 'value><string>ipaobject</string></value>\n</data></array></value>\n</member>\n<member>\n<name>loginshell</name>\n<value><array><data>\n<value><string>/bin/sh</string></value>\n</data></array></value>\n</member>\n<member>\n<name>uidnumber</name>\n<value><array><data>\n<value><string>1966800004</string></value>\n</data></array></value>\n</member>\n<member>\n<name>initials</name>\n<value><array><data>\n<value><string>JR</string></value>\n</data></array></value>\n</member>\n<member>\n<name>gidnumber</name>\n<value><array><data>\n<value><string>1966800004</string></value>\n</data></array></value>\n</member>\n<member>\n<name>gecos</name>\n<value><array><data>\n<value><string>Jane Russell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>sn</name>\n<value><array><data>\n<value><string>Russell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>homedirectory</name>\n<value><array><data>\n<value><string>/home/jrussell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>has_password</name>\n<value><boolean>0</'
body: 'boolean></value>\n</member>\n<member>\n<name>krbprincipalname</name>\n<value><array><data>\n<value><string>jrussell@EXAMPLE.COM</string></value>\n</data></array></value>\n</member>\n<member>\n<name>givenname</name>\n<value><array><data>\n<value><string>Jane</string></value>\n</data></array></value>\n</member>\n<member>\n<name>cn</name>\n<value><array><data>\n<value><string>Jane Russell</string></value>\n</data></array></value>\n</member>\n<member>\n<name>ipauniqueid</name>\n<value><array><data>\n<value><string>bba27e6e-df34-11e0-a5f4-001143d2c060</string></value>\n</data></array></value>\n</member>\n</struct></value>\n</member>\n<member>\n<name>value</name>\n<value><string>jrussell</string></value>\n</member>\n<member>\n<name>summary</name>\n<value><string>Added user "jrussell"</string></value>\n</member>\n</struct></value>\n</param>\n</params>\n</methodResponse>\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
  UID: 1966800004
  GID: 1966800004
  Keytab: False
  Password: False

IMPORTANT

The -v and -vv options are global options and must be used before the subcommand when running ipa.