Product SiteDocumentation Site

Chapter 2. Installing a FreeIPA Server

2.1. Preparing to Install the FreeIPA Server
2.1.1. Hardware Requirements
2.1.2. Software Requirements
2.1.3. Supported Web Browsers
2.1.4. System Prerequisites
2.2. Installing the FreeIPA Server Packages
2.3. Creating a FreeIPA Server Instance
2.3.1. About ipa-server-install
2.3.2. Setting up a FreeIPA Server: Basic Interactive Installation
2.3.3. Examples of Creating the FreeIPA Server
2.3.4. Troubleshooting Installation Problems
2.4. Setting up FreeIPA Replicas
2.4.1. Prepping and Installing the Replica Server
2.4.2. Creating the Replica
2.4.3. Troubleshooting Replica Installation
2.5. Uninstalling FreeIPA Servers and Replicas
The FreeIPA domain is defined and managed by a FreeIPA server which is essentially a domain controller. There can be multiple domain controllers within a domain for load-balancing and failover tolerance. These additional servers are called replicas of the master FreeIPA server.
Both FreeIPA servers and replicas only run on Fedora systems. For both servers and replicas, the necessary packages must be installed and then the FreeIPA server or replica itself is configured through setup scripts, which configure all of the requisite services.

2.1. Preparing to Install the FreeIPA Server

Before you install FreeIPA, ensure that the installation environment is suitably configured. You also need to provide certain information during the installation and configuration procedures, including realm names and certain usernames and passwords. This section describes the information that you need to provide.

2.1.1. Hardware Requirements

A basic user entry is about 1 KB in size, as is a simple host entry with a certificate. The structure of the directory tree and the number of indexes in the Directory Server instance can impact the hardware required for the best performance. Table 2.1, “Minimum Hardware Requirements” lists the recommended minimums. For customized systems, additional indexes, or larger user entries, it is more effective to increase the RAM than to increase the disk space because the Directory Server stores much of its data in cache.

TIP

The Directory Server instance used by the FreeIPA server can be tuned to increase performance. For tuning information, see the Directory Server documentation at http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/8.2/html/Performance_Tuning_Guide/system-tuning.html.
The system requirements for both 32-bit and 64-bit platforms are the same.
Table 2.1. Minimum Hardware Requirements
Minimum Hardware Requirements 10,000 - 250,000 Entries 250,000 - 1,000,000 Entries Over 1,000,000 Entries
CPU P3; 500MHz
RAM 1 GB 1 GB 1 GB
Disk Space 2 GB 4 GB 8 GB

2.1.2. Software Requirements

Most of the packages that a FreeIPA server depends on are installed as dependencies when the FreeIPA packages are installed. There are some packages, however, which are required before installing the FreeIPA packages:
  • Kerberos 1.9
  • The named and bind-dyndb-ldap packages for DNS

2.1.3. Supported Web Browsers

The only supported browser to access the FreeIPA web UI is Firefox 3.x or 4.x.

2.1.4. System Prerequisites

The FreeIPA server is set up using a configuration script, and this script makes certain assumption about the host system. If the system does not meet these prerequisites, then server configuration may fail.

2.1.4.1. Hostname Requirements

Regardless of whether the DNS is within the FreeIPA server or external, the server host must have DNS properly configured:
  • The hostname must be a fully-qualified domain name. For example, ipaserver.example.com.

    IMPORTANT

    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
  • The server's machine name must be set and resolve to its public IP address. The fully-qualified domain name cannot resolve to the loopback address. It must resolve to the machine's public IP address, not to 127.0.0.1. The output of the hostname command cannot be localhost or localhost6.
  • The reverse of the address that the hostname resolves to must match the hostname.
  • The DNS must be correctly configured to resolve forward and reverse addresses. The DNS does not need to be on the same machine as the FreeIPA server, but it does need to be fully functional.
    If you do not have a functional DNS, you can use the --setup-dns option when you install FreeIPA to configure a suitable DNS automatically.
  • The installation process checks that the FreeIPA server name is a DNS A record and that its reverse and forward addresses match. This check is not performed if a FreeIPA DNS server is installed using the --setup-dns option because the script assumes that the FreeIPA server will use itself as a DNS.

2.1.4.2. Directory Server

There must not be any instances of 389 Directory Server installed on the host machine.

2.1.4.3. System Files

The server script overwrites system files to set up the FreeIPA domain. The system should be clean, without custom configuration for services like DNS and Kerberos, before configuring the FreeIPA server.

2.1.4.4. System Ports

FreeIPA uses a number of ports to communicate with its services. These ports, listed in Table 2.2, “FreeIPA Ports”, must be open and available for FreeIPA to work. They cannot be in use by another service or blocked by a firewall. To make sure that these ports are available, try iptables to list the available ports or nc, telnet, or nmap to connect to a port or run a port scan.
To open a port:
# iptables -A INPUT -p tcp --dport 389 -j ACCEPT
The iptables man page has more information on opening and closing ports on a system.
Table 2.2. FreeIPA Ports
Service Ports
HTTP/HTTPS
80
443
LDAP/LDAPS
389
636
Kerberos[a]
88
464
DNS[a] 53
NTP[b] 123
OCSP responder[c] 9180
Dogtag Certificate System
9180 (OCSP responder, non-SSL)
9443 (agents)
9444 (users, SSL)
9445 (administrators)
9446 (users, client authentication)
9701 (Tomcat)
7389 (internal LDAP database)
[a] This service uses both TCP and UDP ports.
[b] This service uses UDP ports only.
[c] This is part of the Dogtag Certificate System server.

2.1.4.5. NTP

If a server is being installed on a virtual machine, that server should not run an NTP server. To disable NTP for FreeIPA, use the --no-ntp option.

2.1.4.6. DNS

FreeIPA uses DNS for the FreeIPA clients to find (discover) the FreeIPA servers. The DNS service can be managed by FreeIPA itself, or FreeIPA can use an existing DNS server. Without a properly configured and working DNS, server discovery for clients and FreeIPA services like, LDAP, Kerberos, and SSL may fail to work.
2.1.4.6.1. The FreeIPA-Generated DNS File
To help create and configure a suitable DNS setup, the FreeIPA installation script creates a sample zone file. During the installation, FreeIPA displays a message similar to the following:
Sample zone file for bind has been created in /tmp/sample.zone.F_uMf4.db
If a DNS server is already configured in the network, then the configuration in the FreeIPA-generated file can be added to the existing DNS zone file. This allows FreeIPA clients to find LDAP and Kerberos servers that are required for them to participate in the FreeIPA domain. For example, this DNS zone configuration is created for an FreeIPA server with the KDC and DNS servers all on the same machine in the EXAMPLE.COM realm:
; ldap servers
_ldap._tcp              IN SRV 0 100 389        ipaserver.example.com

;kerberos realm
_kerberos               IN TXT EXAMPLE.COM

; kerberos servers
_kerberos._tcp          IN SRV 0 100 88         ipaserver.example.com
_kerberos._udp          IN SRV 0 100 88         ipaserver.example.com
_kerberos-master._tcp   IN SRV 0 100 88         ipaserver.example.com
_kerberos-master._udp   IN SRV 0 100 88         ipaserver.example.com
_kpasswd._tcp           IN SRV 0 100 464        ipaserver.example.com
_kpasswd._udp           IN SRV 0 100 464        ipaserver.example.com
2.1.4.6.2. IPA, DNS, and NSCD
It is strongly recommended that you avoid or restrict the use of nscd (Name Service Caching Daemon) in a FreeIPA deployment. The nscd service is extremely useful for reducing the load on the server, and for making clients more responsive, but there can be problems when a system is also using SSSD, which performs its own caching.
nscd caches authentication and identity information for all services that perform queries through nsswitch, including getent. Because nscd performs both positive and negative caching, if a request determines that a specific FreeIPA user does not exist, it marks this as a negative cache. Values stored in the cache remain until the cache expires, regardless of any changes that may occur on the server. The results of such caching is that new users and memberships may not be visible, and users and memberships that have been removed may still be visible.
Avoid clashes with SSSD caches and to prevent locking out users, avoid using nscd altogether. Alternatively, use a shorter cache time by resetting the time-to-live caching values in the /etc/nscd.conf file:
positive-time-to-live   group           3600
negative-time-to-live   group           60
positive-time-to-live   hosts           3600
negative-time-to-live   hosts           20
2.1.4.6.3. DNS and Kerberos
The Kerberos server requires a valid DNS A record, and reverse DNS needs to work correctly. It is safe to use CNAMEs if they point to the A name that corresponds to the principal name used to create service principal names (SPN) for the host. Avoid the use of DDNS names, however.
If necessary, add the hostname to the /etc/hosts file, as long as the fully qualified hostname must be listed first. For example:
192.168.1.1    ipaserver.example.com  ipaserver
The realm name does not have to match any or all of the domain name. For example, the domain name can be example.com and the realm name can be TESTIPA. It is only a convention that they match. FreeIPA adds the appropriate domain to realm mapping in the /etc/krb5.conf file.
A typical resolver looks in the /etc/hosts file first and DNS second. If nscd is running this may also cause issues because it caches lookups. The FreeIPA installer does not kill nscd until after the installation process has started, so there can be cached entries that interfere with any changes to the /etc/hosts. If you need to edit the /etc/hosts file, kill the nscd daemon first.
2.1.4.6.4. FreeIPA DNS and DNS Forwarders
There is an option to configure DNS forwarders as part of the FreeIPA DNS configuration. This is beneficial if there is limited direct access to root name servers, such as an organization's main DNS server or even an external DNS server.
Either interactively or through the install argument, forwarders can be listed as a comma-separated list of IP addresses.

NOTE

DNS forwarders must be specified as IP addresses, not as hostnames.
By default, any host is permitted to issue recursive queries against configured forwarders. The client installation script automatically adds a line to the /etc/named.conf file to allow these recursive queries.
        forward first;
        forwarders { 10.16.36.29; };
        allow-recursion { any; };
This default behavior can be changed by changing the allow-recursion statement. The name server documentation has more details on editing configuration statements.

2.1.4.7. Networking

2.1.4.7.1. Configuring Networking Services
The default networking service used by Fedora is NetworkManager, and due to the way this service works, it can cause problems with FreeIPA and the KDC. Consequently, it is highly recommended that you use the network service to manage the networking requirements in a FreeIPA environment and disable the NetworkManager service.
  1. Boot the machine into single-user mode and run the following commands:
    # chkconfig NetworkManager off; service NetworkManager stop
  2. If NetworkManagerDispatcher is installed, ensure that it is stopped and disabled:
    # chkconfig NetworkManagerDispatcher off; service NetworkManagerDispatcher stop
  3. Then, make sure that the network service is properly started.
    # chkconfig network on; service network start
  4. Ensure that static networking is correctly configured.
  5. Restart the system.
2.1.4.7.2. Configuring the /etc/hosts File
You need to ensure that your /etc/hosts file is configured correctly. A misconfigured file can prevent the FreeIPA command-line tools from functioning correctly and can prevent the FreeIPA web interface from connecting to the FreeIPA server.
Configure the /etc/hosts file to list the FQDN for the FreeIPA server before any aliases. Also ensure that the hostname is not part of the localhost entry. The following is an example of a valid hosts file:
127.0.0.1	localhost.localdomain	localhost
::1		localhost6.localdomain6	localhost6
192.168.1.1	ipaserver.example.com	ipaserver

Important

Do not omit the IPv4 entry in the /etc/hosts file. This entry is required by the FreeIPA web service.