Product SiteDocumentation Site

2.3. Creating a FreeIPA Server Instance

The FreeIPA setup script creates a server instance, which includes configuring all of the required services for the FreeIPA domain:
The FreeIPA setup process can be minimal, where the administrator only supplies some required information, or it can be very specific, with user-defined settings for many parts of the FreeIPA services. The configuration is passed using arguments with the ipa-install-server script.

NOTE

The port numbers and directory locations used by FreeIPA are all defined automatically, as defined in Section 2.1.4.4, “System Ports” and . These ports and directories cannot be changed or customized.

2.3.1. About ipa-server-install

A FreeIPA server instance is created by running the ipa-server-install script. This script can accept user-defined settings for services, like DNS and Kerberos, that are used by the FreeIPA instance, or it can supply predefined values for minimal input from the administrator.
While ipa-server-install can be run without any options, so that it prompts for the required information, it has numerous arguments which allow the configuration process to be easily scripted or to supply additional information which is not requested during an interactive installation.
Table 2.3, “ipa-server-install Options” lists some common arguments with ipa-server-install, while Section 2.3.3, “Examples of Creating the FreeIPA Server” has examples of some common installation scenarios. The full list of options are in Section B.5.3, “ipa-server-install”. In real life, the ipa-server-install options are versatile enough to be customized to the specific deployment environment.
Table 2.3. ipa-server-install Options
Argument Description
-a ipa_admin_password The password for the FreeIPA administrator. This is used for the admin user to authenticate to the Kerberos realm.
--hostname=hostname The fully-qualified domain name of the FreeIPA server machine.

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.
-n domain_name The name of the LDAP server domain to use for the FreeIPA domain. This is usually based on the FreeIPA server's hostname.
-p directory_manager_password The password for the superuser, cn=Directory Manager, for the LDAP service.
-r realm_name The name of the Kerberos realm to create for the FreeIPA domain.
--subject=subject_DN Sets the base element for the subject DN of the issued certificates. This defaults to O=realm.
--forwarder=forwarder Gives a DNS forwarder to use with the DNS service. To specify more than one forwarder, use this option multiple times.
--no-forwarders Uses root servers with the DNS service instead of forwarders.
--no-reverse Does not create a reverse DNS zone when the DNS domain is set up.
--setup-dns Tells the installation script to set up a DNS service within the FreeIPA domain. Using an integrated DNS service is optional, so if this option is not passed with the installation script, then no DNS is configured.
--idmax=number Sets the upper bound for IDs which can be assigned by the FreeIPA server. The default value is the ID start value plus 199999.
--idstart=number Sets the lower bound (starting value) for IDs which can be assigned by the FreeIPA server. The default value is randomly selected.

2.3.2. Setting up a FreeIPA Server: Basic Interactive Installation

All that is required to set up a FreeIPA server is to run the ipa-server-install script. This launches the script interactively, which prompts for the required information to set up a server, but without more advanced configuration like DNS and CA options.
  1. Run the ipa-server-install script.
    # ipa-server-install
  2. Enter the hostname. This is determined automatically using reverse DNS.
    Server host name [ipaserver.example.com]:
  3. Enter the domain name. This is determined automatically based on the hostname.
    Please confirm the domain name [example.com]:
  4. The script then reprints the hostname, IP address, and domain name.
    The IPA Master Server will be configured with
    Hostname:    ipaserver.example.com
    IP address:  192.168.1.1
    Domain name: example.com
  5. Enter the new Kerberos realm name. This is usually based on the domain name.
    Please provide a realm name [EXAMPLE.COM]:
  6. Enter the password for the Directory Server superuser, cn=Directory Manager. There are password strength requirements for this password, including a minimum password length.
    Directory Manager password:
    Password (confirm):
  7. Enter the password for the FreeIPA system user account, admin. This user is created on the machine.
    IPA admin password:
    Password (confirm):
  8. After that, the script configures all of the associated services for FreeIPA, with task counts and progress bars.
    Configuring ntpd
      [1/4]: stopping ntpd
     ...
    done configuring ntpd.
    
    Configuring directory server for the CA: Estimated time 30 seconds
      [1/3]: creating directory server user
    ...
    done configuring pkids.
    
    Configuring certificate server: Estimated time 6 minutes
      [1/17]: creating certificate server user
    ....
    done configuring pki-cad.
    
    Configuring directory server: Estimated time 1 minute
      [1/32]: creating directory server user
    ...
    done configuring dirsrv.
    
    Configuring Kerberos KDC: Estimated time 30 seconds
      [1/14]: setting KDC account password
    ...
    done configuring krb5kdc.
    
    Configuring ipa_kpasswd
      [1/2]: starting ipa_kpasswd
      [2/2]: configuring ipa_kpasswd to start on boot
    done configuring ipa_kpasswd.
    
    Configuring the web interface: Estimated time 1 minute
      [1/12]: disabling mod_ssl in httpd
    ...
    done configuring httpd.
    Setting the certificate subject base
    restarting certificate server
    Applying LDAP updates
    Restarting the directory server
    Restarting the KDC
    Restarting the web server
    Sample zone file for bind has been created in /tmp/sample.zone.ygzij5.db
    ==============================================================================
    Setup complete
  9. Restart the SSH service to retrieve the Kerberos principal and to refresh the name server switch (NSS) configuration file:
    # service sshd restart
  10. Authenticate to the Kerberos realm using the admin user's credentials to ensure that the user is properly configured and the Kerberos realm is accessible.
    # kinit admin
    Password for admin@EXAMPLE.COM:
  11. Test the FreeIPA configuration by running a command like ipa user-find. For example:
    # ipa user-find admin
      --------------
      1 user matched
      --------------
      User login: admin
      Last name: Administrator
      Home directory: /home/admin
      Login shell: /bin/bash
      Account disabled: False
      Member of groups: admins
      ----------------------------
      Number of entries returned 1
      ----------------------------

2.3.3. Examples of Creating the FreeIPA Server

The way that a FreeIPA server is installed can be different depending on the network environment, security requirements within the organization, and the desired topology. These example illustrate some common options when installing the server. These examples are not mutually exclusive; it is entirely possible to use CA options, DNS options, and FreeIPA configuration options in the same server invocation. These are called out separately simply to make it more clear what each configuration area requires.

2.3.3.1. Non-Interactive Basic Installation

As shown in Section 2.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”, only a few pieces of information are required to configured a FreeIPA server. While the setup script can prompt for this information in interactive mode, this information can also be passed with the setup command to allow automated and unattended configuration:
  • Passwords for the FreeIPA administrative user and the Directory Server super user (Directory Manager)
  • The server hostname
  • The Kerberos realm name
  • The DNS domain name
This information can be passed with the ipa-server-install, along with the -U to force it to run without requiring user interaction.
Example 2.1. Basic Installation without Interaction
# ipa-server-install -a secret12 --hostname=ipaserver.example.com --r EXAMPLE.COM -p secret12 -n example.com -U
The script then prints the submitted values:
To accept the default shown in brackets, press the Enter key.

The IPA Master Server will be configured with
Hostname:    ipaserver.example.com
IP address:  192.168.1.1
Domain name: example.com
Then the script runs through the configuration progress for each FreeIPA service, as in Section 2.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”.

2.3.3.2. Using Different CA Configurations

FreeIPA uses an integrated certificate authority (CA) to create the certificates and keytabs used by users and hosts within the domain. There are three different ways that FreeIPA incorporates the CA into the FreeIPA server:
  • The installation script installs a root Dogtag Certificate System CA. The Dogtag Certificate System CA provides the fully range of certificate services, based on policies that are defined in the Dogtag Certificate System configuration.
    This is the default configuration.
  • Alternatively, the installation script can set up a Dogtag Certificate System CA that is subordinate to an external CA. A subordinate CA is chained to another CA, and it uses the policies and restrictions defined by that external CA. The root CA can be an external CA like Verisign or a corporate CA.
    A Dogtag Certificate System CA is still installed and configured as part of the FreeIPA server installation, but its CA certificates are issued by the external CA rather than by itself.
  • The FreeIPA server can use self-signed certificates without installing a CA. This is done by using the --selfsign option. When the FreeIPA server uses a self-signed certificate, the setup process is exactly the same as a normal installation, except that no Dogtag Certificate System instance is created. There is still a cacert.p12 file created that can be used by replicas, but the certificate services that the FreeIPA server can perform are much more limited.
Example 2.2. Using a Self-Signed Certificate
# ipa-server-install -a secret12 --hostname=ipaserver.example.com --r EXAMPLE.COM -p secret12 -n example.com -U --selfsign

NOTE

A self-signed certificate should only be used for a testing or development environment.
Alternatively, the FreeIPA server can use a certificate issued by an external CA. This can be a corporate CA or a third-party CA like Verisign or Thawte. As with a normal setup process, using an external CA still uses a Dogtag Certificate System instance for the FreeIPA server for issuing all of its client and replica certificates; the initial CA certificate is simply issued by a different CA.
When using an external CA, there are two additional steps that must be performed: submit the generated certificate request to the external CA and then load the CA certificate and issued server certificate to complete the setup.
Example 2.3. Using an External CA
  1. Run the ipa-server-install script, using the --external-ca option.
    # ipa-server-install -a secret12 --r EXAMPLE.COM -P password -p secret12 -n ipaserver.example.com --external-ca
  2. The script sets up the NTP and Directory Server services as normal.
  3. The script completes the CA setup and returns information about where the certificate signing request (CSR) is located, /root/ipa.csr. This request must be submitted to the external CA.
    Configuring certificate server: Estimated time 6 minutes
      [1/4]: creating certificate server user
      [2/4]: creating pki-ca instance
      [3/4]: restarting certificate server
      [4/4]: configuring certificate server instance
    The next step is to get /root/ipa.csr signed by your CA and re-run ipa-server-install.
  4. Submit the request to the CA. The process differs for every service.
  5. Retrieve the issued certificate and the CA certificate chain for the issuing CA. Again, the process differs for every certificate service, but there is usually a download link on a web page or in the notification email that allows administrators to download all the required certificates. Be sure to get the full certificate chain for the CA, not just the CA certificate.
  6. Rerun ipa-server-install, specifying the locations and names of the certificate and CA chain files. For example:
    # ipa-server-install --external_cert_file=/tmp/servercert20110601.p12 --external_ca_file=/tmp/cacert.p12
  7. Complete the setup process and verify that everything is working as expected, as in Section 2.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”.

2.3.3.3. Using DNS

FreeIPA can be configured to manage its own DNS, use an existing DNS, or not use DNS services at all (which is the default). Running the setup script alone does not configure DNS; this requires the --setup-dns option.
As with a basic setup, the DNS setup can either prompt for the required information or the DNS information can be passed with the script to allow an automatic or unattended setup process.
Example 2.4. Interactive DNS Setup
  1. Run the ipa-server-install script, using the --setup-dns option.
    # ipa-server-install -a secret12 --r EXAMPLE.COM -P password -p secret12 -n ipaserver.example.com --setup-dns
  2. The script configures the hostname and domain name as normal.
  3. The script then prompts for DNS forwarders. If forwarders will be used, enter yes, and then supply the list of DNS servers. If FreeIPA will manage its own DNS service, then enter no.
    Do you want to configure DNS forwarders? [yes]: no
    No DNS forwarders configured
  4. The script sets up the NTP, Directory Server, Certificate System, Kerberos, and Apache services.
  5. Before completing the configuration, the script prompts to ask whether it should configure reverse DNS services. If you select yes, then it configures the named service.
    Do you want to configure the reverse zone? [yes]: yes
    Configuring named:
      [1/9]: adding DNS container
      [2/9]: setting up our zone
      [3/9]: setting up reverse zone
      [4/9]: setting up our own record
      [5/9]: setting up kerberos principal
      [6/9]: setting up named.conf
      [7/9]: restarting named
      [8/9]: configuring named to start on boot
      [9/9]: changing resolv.conf to point to ourselves
    done configuring named.
    ==============================================================================
    Setup complete
  6. Verify that everything is working as expected, as in Section 2.3.2, “Setting up a FreeIPA Server: Basic Interactive Installation”.

If DNS is used with FreeIPA, then two pieces of information are required: any DNS forwarders that will be used and using (or not) reverse DNS. To perform a non-interactive setup, this information can be passed using the --forwarder or --no-forwarders option and --no-reverse option.
Example 2.5. Setting up DNS Non-Interactively
To use DNS always requires the --setup-dns. To user forwarders, use the --forwarder with a comma-separated list of forwarders.
# ipa-server-install ... --setup-dns --forwarder=1.2.3.0 --forwarder=1.2.255.0
Some kind of forwarder information is required. If no external forwarders will be used with the FreeIPA DNS service, then use the --no-forwarders option to indicate that only root servers will be used.
The script always assumes that reverse DNS is configured along with DNS, so it is not necessary to use any options to enable reverse DNS. To disable reverse DNS, use the --no-reverse option.
# ipa-server-install ... --setup-dns --no-reverse

2.3.4. Troubleshooting Installation Problems

The server installation log is located in /var/log/ipaserver-install.log. The FreeIPA logs, both for the server and for FreeIPA-associated services, are covered in Section 16.1.3, “Checking FreeIPA Server Logs”.
GSS Failures When Running IPA Commands
Immediately after installation, there can be Kerberos problems when trying to run an ipa-* command. For example:
ipa: ERROR: Kerberos error: ('Unspecified GSS failure.  Minor code may provide more information', 851968)/('Decrypt integrity check failed', -1765328353)
There are two potential causes for this:
  • DNS is not properly configured.
  • Active Directory is in the same domain as the FreeIPA server.
named Daemon Fails to Start
If a FreeIPA server is configured to manage DNS and is set up successfully, but the named service fails to start, this can indicate that there is a package conflict. Check the /var/log/messages file for error messages related to the named service and the ldap.so library:
ipaserver named[6886]: failed to dynamically load driver 'ldap.so': libldap-2.4.so.2: cannot open shared object file: No such file or directory
This usually means that the bind-chroot package is installed and is preventing the named service from starting. To resolve this issue, remove the bind-chroot package and then restart the FreeIPA server.
# yum remove bind-chroot

# ipactl restart