Product SiteDocumentation Site

Chapter 2. Installing a FreeIPA Server

2.1. Preparing to Install the FreeIPA Server
2.1.1. Hardware Recommendations
2.1.2. Software Requirements
2.1.3. Supported Web Browsers
2.1.4. System Prerequisites
2.1.5. Networking
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
2.6. Upgrading from FreeIPA 2.1 to 2.2
2.6.1. Upgrading Packages
2.6.2. Removing Browser Configuration for Ticket Delegation
2.6.3. Testing Before Upgrading the FreeIPA Server
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 Recommendations

A basic user entry is about 1 KB in size, as is a simple host entry with a certificate. The most important hardware feature to size properly is RAM. While all deployments are different, depending on the number of users and groups and the type of data stored, there is a rule of thumb to use to help determine how much RAM to use:
  • For 10,000 users and 100 groups, have at least 2GB of RAM and 1GB swap space.
  • For 100,000 users and 50,000 groups, have at least 16GB of RAM and 4GB of swap space.

TIP

For larger deployments, it is more effective to increase the RAM than to increase disk space because much of the data are stored in cache.
The underlying 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.

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 and IP Address 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 hostname must be all lower-case.
  • The server's A record 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 server's hostname and IP address must be in its own /etc/hosts file.
  • It is recommended that a separate DNS domain be allocated for the FreeIPA server. While not required (clients from other domains can still be enrolled in the FreeIPA domain), this is a convenience for overall DNS management.

TIP

If the FreeIPA server is configured to host its own DNS server, any previous existing DNS ignored. A records and PTR records do not need to match for the FreeIPA server machine, and the machine can have any configured IP address.

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.1, “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:
[root@server ~]# 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.1. FreeIPA Ports
Service Ports Type
HTTP/HTTPS
80
443
TCP
LDAP/LDAPS
389
636
TCP
Kerberos
88
464
TCP and UDP
DNS 53 TCP and UDP
NTP 123 UDP
Dogtag Certificate System - LDAP 7389 TCP

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

It is strongly recommended that you avoid or restrict the use of nscd 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.5. Networking

2.1.5.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:
    [root@server ~]# chkconfig NetworkManager off; service NetworkManager stop
  2. If NetworkManagerDispatcher is installed, ensure that it is stopped and disabled:
    [root@server ~]# chkconfig NetworkManagerDispatcher off; service NetworkManagerDispatcher stop
  3. Then, make sure that the network service is properly started.
    [root@server ~]# chkconfig network on; service network start
  4. Ensure that static networking is correctly configured.
  5. Restart the system.

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