Product SiteDocumentation Site

2.4. Creating an IPA Server Instance

The IPA setup script creates a server instance, which includes configuring all of the required services for the IPA domain:
The IPA 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 IPA services. The configuration is passed using arguments with the ipa-install-server script.

NOTE

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

2.4.1. About ipa-server-install

An IPA 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 IPA 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.4.3, “Examples of Creating the IPA 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 IPA administrator. This is used for the admin user to authenticate to the Kerberos realm.
--hostname=hostname The fully-qualified domain name of the IPA 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 IPA domain. This is usually based on the IPA 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 IPA 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 IPA 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 IPA 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 IPA server. The default value is randomly selected.

2.4.2. Setting up an IPA Server: Basic Interactive Installation

All that is required to set up an IPA 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 IPA 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 IPA, 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 IPA 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.4.3. Examples of Creating the IPA Server

The way that an IPA 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 IPA configuration options in the same server invocation. These are called out separately simply to make it more clear what each configuration area requires.

2.4.3.1. Non-Interactive Basic Installation

As shown in Section 2.4.2, “Setting up an IPA Server: Basic Interactive Installation”, only a few pieces of information are required to configured an IPA 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 IPA 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 IPA service, as in Section 2.4.2, “Setting up an IPA Server: Basic Interactive Installation”.

2.4.3.2. Using Different CA Configurations

Identity Management 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 IPA incorporates the CA into the IPA server:
  • The installation script installs a root Dogtag Certificate System CA. The Dogtag Certificate System CA provides the full 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 IPA server installation, but its CA certificates are issued by the external CA rather than by itself.
  • The IPA server can use self-signed certificates without installing a CA. This is done by using the --selfsign option. When the IPA 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 IPA 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 IPA 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 IPA 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.4.2, “Setting up an IPA Server: Basic Interactive Installation”.

2.4.3.3. Using DNS

IPA 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 IPA 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.4.2, “Setting up an IPA Server: Basic Interactive Installation”.

If DNS is used with IPA, 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 IPA 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.4.4. Troubleshooting Installation Problems

The server installation log is located in /var/log/ipaserver-install.log. The IPA logs, both for the server and for IPA-associated services, are covered in Section 16.1.3, “Checking IPA 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 IPA server.
named Daemon Fails to Start
If an IPA 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 IPA server. 
# yum remove bind-chroot

# ipactl restart