Product SiteDocumentation Site

Chapter 18. Configuration: Configuring the FreeIPA Server

18.1. FreeIPA Files and Logs
18.1.1. A Reference of FreeIPA Server Configuration Files and Directories
18.1.2. About default.conf and Context Configuration Files
18.1.3. Checking FreeIPA Server Logs
18.2. Disabling Anonymous Binds
18.3. Configuring Alternate Certificate Authorities
18.4. Configuring CRLs and OCSP Responders
18.4.1. Using an OSCP Responder with SELinux
18.4.2. Changing the CRL Update Interval
18.4.3. Changing the OCSP Responder Location
18.5. Setting a FreeIPA Server as an Apache Virtual Host
18.6. Setting DNS Entries for Multi-Homed Servers
18.7. Managing Replication Agreements Between FreeIPA Servers
18.7.1. Listing Replication Agreements
18.7.2. Creating and Removing Replication Agreements
18.7.3. Forcing Replication
18.7.4. Reinitializing FreeIPA Servers
18.7.5. Resolving Replication Conflicts
18.8. Moving CRL Generation from the Master (Original) Server to Another Replica
18.8.1. About the Master Server, Replicas, and Generating CRLs
18.8.2. Promoting a Replica
18.9. Removing a Replica
18.10. Troubleshooting
18.10.1. Starting FreeIPA with Expired Certificates
18.10.2. There are SASL, GSS-API, and Kerberos errors in the 389 Directory Server logs when the replica starts.
The FreeIPA servers and backend services are configured with default settings that are applicable in most environments.
There are some configuration areas where the FreeIPA server configuration can be tweaked to improve security or performance in certain situations.
This chapter covers information about the FreeIPA configuration, including files and logs used by the FreeIPA server, and procedures for updating the FreeIPA server configuration itself.

18.1. FreeIPA Files and Logs

FreeIPA 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. FreeIPA directly manages each of these elements through their own configuration files and tools.
This section covers the directories, files, and logs used specifically by FreeIPA. For more information about the configuration files or logs for a specific server used within FreeIPA, see the product documentation.

18.1.1. A Reference of FreeIPA Server Configuration Files and Directories

Table 18.1. FreeIPA Server Configuration Files and Directories
Directory or File Description
Server Configuration
/etc/ipa The main FreeIPA configuration directory.
/etc/ipa/default.conf The primary configuration file for FreeIPA.
/etc/ipa/ca.crt The CA certificate issued by the FreeIPA server's CA.
~/.ipa/ A user-specific FreeIPA directory that is created on the local system in the system user's home directory the first time the user runs a FreeIPA command.
FreeIPA Logs
~/.ipa/log/cli.log The log file for all XML-RPC calls and responses by the FreeIPA 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 FreeIPA user.
/var/log/ipaclient-install.log The installation log for the client service.
/var/log/ipaserver-install.log The installation log for the FreeIPA server.
System Services
/etc/rc.d/init.d/ipa The FreeIPA server init script.
/etc/rc.d/init.d/ipa_kpasswd The init script for the FreeIPA control daemon for Kerberos passwords.
/var/run/ipa_kpasswd.pid The PID file for the Kerberos password daemon used by the FreeIPA service.
Web UI
/etc/ipa/html A symlink directory in the main configuration directory for the HTML files used by the FreeIPA 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 FreeIPA.
/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 FreeIPA Kerberos realm.
/usr/share/ipa/migration Contains HTML pages, stylesheets, and Python scripts used for running the FreeIPA server in migration mode.
/usr/share/ipa/ui Contains all of the scripts used by the UI to perform FreeIPA operations.
/var/log/httpd The log files for the Apache web server.
Kerberos
/etc/krb5.conf The Kerberos service configuration file.
SSSD
/etc/sssd/sssd.api.d/sssd-ipa.conf The configuration file used to identify the FreeIPA server, FreeIPA Directory Server, and other FreeIPA 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 FreeIPA server.
/var/log/dirsrv/slapd-REALM_NAME Log files associated with the Directory Server instance used by the FreeIPA server.
Dogtag Certificate System
/etc/pki-ca The main directory for the FreeIPA CA instance.
/etc/pki-ca/conf/CS.cfg The main configuration file for the FreeIPA 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 FreeIPA CA.
/var/log/dirsrv/slapd-PKI-IPA/ Log files associated with the Directory Server instance used by the FreeIPA CA.
Cache Files
/var/cache/ipa Cache files for the FreeIPA server and the FreeIPA Kerberos password daemon.
System Backups
/var/lib/ipa/sysrestore Contains backups of all of the system files and scripts that were reconfigured when the FreeIPA 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 FreeIPA client was installed. Commonly, this is the sssd.conf file for SSSD authentication services.

18.1.2. 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 FreeIPA 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 FreeIPA server is started or when the ipa command is run, respectively. The FreeIPA 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 FreeIPA directory, ~/.ipa/. This optional file is merged with default.conf and used by the local FreeIPA services.

18.1.3. Checking FreeIPA Server Logs

FreeIPA 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 18.2. FreeIPA Log Files
Service Log File Description Additional Information
FreeIPA server /var/log/ipaserver-install.log Server installation log
FreeIPA server ~/.ipa/log/cli.log Command-line tool log
FreeIPA client /var/log/ipaclient-install.log Client installation log
Apache server
/var/log/httpd/access
/var/log/httpd/error
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 FreeIPA-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 FreeIPA 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 FreeIPA, 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 FreeIPA 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.

18.1.3.1. Enabling Server Debug Logging

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

NOTE

Editing the defaults.conf configuration file affects all FreeIPA components, not only the FreeIPA 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

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