Product SiteDocumentation Site

Chapter 16. Configuring the FreeIPA Server

16.1. FreeIPA Files and Logs
16.1.1. A Reference of FreeIPA Server Configuration Files and Directories
16.1.2. About default.conf and Context Configuration Files
16.1.3. Checking FreeIPA Server Logs
16.2. Disabling Anonymous Binds
16.3. Configuring Alternate Certificate Authorities
16.4. Configuring CRLs and OCSP Responders
16.4.1. Using an OSCP Responder with SELinux
16.4.2. Changing the CRL Update Interval
16.4.3. Changing the OCSP Responder Location
16.5. Setting a FreeIPA Server as an Apache Virtual Host
16.6. Setting DNS Entries for Multi-Homed Servers
16.7. Managing Replication Agreements Between FreeIPA Servers
16.7.1. Listing Replication Agreements
16.7.2. Creating and Removing Replication Agreements
16.7.3. Forcing Replication
16.7.4. Reinitializing FreeIPA Servers
16.8. Promoting a Replica to a FreeIPA Server
16.8.1. Promoting a Replica with a Dogtag Certificate System CA
16.8.2. Promoting a Replica with a Self-Signed CA
16.9. Testing Before Upgrading the FreeIPA Server
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.

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

16.1.1. A Reference of FreeIPA Server Configuration Files and Directories

Table 16.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.

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

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

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

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