Product SiteDocumentation Site

B.5. Server Scripts

These are scripts that are used to manage the FreeIPA server configuration. These scripts do not manage FreeIPA domain entries; they manage the configuration of the server itself. This means that these scripts are run as system administrative users rather than domain administrative users.

B.5.1. ipa-replica-install

Uses a configuration file based on an existing FreeIPA server to create a replica, or copy, of that server. Once the replica is created, it functions as an equal participant and mirror of the original FreeIPA server within the FreeIPA domain. Any changes made on the server or any other replica are automatically propagated over to the other replicas and server.
A replica is created using a file that contains all of the configuration for the FreeIPA server. This initial file is created by running the ipa-replica-prepare on the FreeIPA server. Then the file is copied over to the replica machine, and the ipa-replica-install script is run.
As with the server and client install scripts, any replica arguments which require a parameter value (such as the Directory Manager password) will be prompted for during installation, unless the argument is passed with the command. Parameters with Boolean values (like configuring DNS) will assume that the default value should be used unless the argument is passed with the command.

B.5.1.1. Location

Description Location
Tool directory /usr/sbin
Package ipa-server

B.5.1.2. Syntax

ipa-replica-install [ options ] /path/to/replica_file

B.5.1.3. Options

Short Parameter Long Parameter Description
file Gives the full path and filename of the replica initialization file that was created from the FreeIPA server configuration.
-N --no-ntp Does not configure NTP on the replica system.
-d --debug Prints additional debug information.
-p --password Gives the Directory Manager password for the FreeIPA domain.
-w --admin-password Gives the Kerberos password for the FreeIPA admin user. This is used to check Kerberos and domain connectivity on the replica.
--setup-dns Sets up DNS services on the replica machine to connect to the FreeIPA DNS domain. If this is not used, then the default value is false, which does not enable DNS.
--forwarder Gives a comma-separated list of IP addresses for DNS forwarders.
--no-forwarders Disables DNS forwarder configuration and uses only domain root servers. If this is not used, then the default value is false, which prompts for DNS forwarder information.
--no-reverse Disables reverse DNS configuration. If this is not used, then the default value is true, which assumes that reverse DNS should be configured.
--no-host-dns Disables host DNS lookups during the replica installation process. If this is not used, then the default value is true, which performs the host DNS lookups.
--no-pkinit Disables PKI (Dogtag Certificate System) configuration. If this is not used, then the default value is true, which assumes that a local Dogtag Certificate System CA should be configured.
--skip-conncheck
Disables checks for the replica's connection to the FreeIPA domain. If this is not used, then the default value is true, which checks that the replica can connect to the Kerberos realm.
This can be useful if the replica is unable to reach the Directory Server or the CA used by the original FreeIPA server, such as the server is offline or the server's firewall is blocking access on the required ports (Section 2.1.4.4, “System Ports”).
-U --unattended Disables user prompts so that the replica installation script runs without user interaction.

B.5.2. ipa-replica-prepare

Creates a file that can be used to create a copy, or replica, of the FreeIPA server.
Each replica initialization file is unique to the replica machine because the configuration is based, in part, on the IP address and hostname of the replica machine. This host-specific configuration is especially critical for setting up services like Kerberos which use SSL because SSL certificates are created based on the hostname.
When the replica file is created, the prep script requires the hostname and, optionally, accepts the IP address.
Once the configuration file is created on the server using the ipa-replica-prepare command, then the replica file is copied over to the replica machine and the replica is configured using the ipa-replica-prepare command.

NOTE

If DNS is managed by FreeIPA, then use either the --ip-address option or configure DNS forwarders and allow reverse DNS lookups.

B.5.2.1. Location

Description Location
Tool directory /usr/sbin
Package ipa-server

B.5.2.2. Syntax

ipa-replica-prepare [ --dirsrv_pkcs12=file ] [ --http_pkcs12=file ] [ --dirsrv_pin=pin ] [ --http_pin=pin ] [ --ip-address=ipAddress ] hostname

B.5.2.3. Options

Parameter Description
--dirsrv_pkcs12 Gives the full path and filename of a PKCS #12 file (.p12) which contains the Directory Server's SSL certificate.
--dirsrv_pin Gives the password to access the Directory Server certificate file.
--http_pkcs12 Gives the full path and filename of a PKCS #12 file (.p12) which contains the Apache server's SSL certificate.
--http_pin Gives the password to access the Apache certificate file.
--ip-address Gives the IP address of the replica server. Using this option automatically adds A and PTR records for the replica host to the FreeIPA DNS configuration.

B.5.3. ipa-server-install

Configures all of the services used by the FreeIPA server for the FreeIPA domain:
  • Dogtag Certificate System, for issuing server certificates
  • 389 Directory Server, for storing all of the FreeIPA information
  • The Kerberos KDC, with the LDAP backend
  • Apache, for the web-based services
  • NTP
  • The ipa_kpasswd service
  • Optionally, DNS
This script can be run interactively, which prompts for many of the server values, or information can be passed directly to the script so that the server can be configured without human intervention.
The FreeIPA server configuration is very flexible. The setup script allows some customization to services like DNS, NTP, certificate issuance, and access control in FreeIPA so that the server can be suited to the network environment.

B.5.3.1. Location

Description Location
Tool directory /usr/sbin
Package ipa-server

B.5.3.2. Syntax

ipa-server-install -a ipa_admin_password --hostname=hostname -p directory_manager_password -n domain_name -r realm_name [[ --external-ca ] | [ --external_ca_file=CA_cert_chain_file ] | [ --external_cert_file=certificate_file ]] [ --selfsign ] [ --subject=subject_DN ] [ --setup-dns ] [ --forwarder=forwarder ] [ --no-forwarders ] [ --no-reverse ] [ --zone-refresh=seconds ] [ --zone-notif ] [ --zonemgr=email_address ] [ --ip-address=ip_address ] [ -P kerberos_master_password ] [ --no-ntp ] [ --idmax=number ] [ --idstart=number ] [ --no_hbac_allow ] [ --no-host-dns ] [ -U ] [ --uninstall ] [ --debug ] [ --help ] [ --version ]

B.5.3.3. Options

Argument Alternate Argument Description
Required Options[a]
-a ipa_admin_password --admin-password=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 --domain=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 --ds-password=directory_manager_password The password for the superuser, cn=Directory Manager, for the LDAP service.
-r realm_name --realm=realm_name The name of the Kerberos realm to create for the FreeIPA domain.
Certificate Authority Options
--external-ca Instructs the installation script to generate a certificate request that can be submitted to an external or third-party CA.
--external_ca_file=CA_cert_chain_file Points to the PKCS#10 file which contains the CA certificate chain of the external CA. This is required to validate the certificate issued by the CA for the FreeIPA server. If an external CA is used, this is required in a second invocation of ipa-server-install to complete the setup process.
--external_cert_file=certificate_file Points to the PKCS#10 file which contains the certificate that was generated by an external CA. If an external CA is used, this is required in a second invocation of ipa-server-install to complete the setup process.
--selfsign Uses a self-signed certificate instead of a certificate issued by the internal Dogtag Certificate System or by an external CA. If this option is selected, then no Dogtag Certificate System instance is configured as part of the setup process, and the FreeIPA server itself functionally serves as a CA for clients in the domain. This is not recommended for production environments, but can be used in test or development environments.
--subject=subject_DN Sets the base element for the subject DN of the issued certificates. This defaults to O=realm.
DNS Options
--forwarder=forwarder Gives a comma-separated list of DNS forwarders to use with the DNS service.
--no-forwarders Uses root servers with the DNS service instead of forwarders.
--no-reverse Uses root servers with the DNS service instead of forwarders.
--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.
--zone-refresh=seconds Sets whether the FreeIPA server should periodically check to see when new DNS zones are added and update its DNS server accordingly. The polling interval is set in seconds.
--zone-notif Opens a persistent search with its Directory Server and captures any new zone changes immediately..
--zonemgr=email_address Gives the email address to use for the DNS zone manager. If none is given, this defaults to root.
Kerberos Options
--ip-address=ip_address Gives the IP address of the Kerberos master KDC. This can be used if there are multiple FreeIPA servers in the same realm.
-P kerberos_master_password --master-password=kerberos_master_password The password for the KDC account. This is randomly generated if no value is given.
NTP Options
-N, --no-ntp Does not configure the NTP service for the FreeIPA server. This is normally done by default.

NOTE

If the FreeIPA server is running as a virtual guest, it should not run an NTP service.
FreeIPA Server Configuration Options
--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.
--no_hbac_allow Disables the allow_all rule for host-based access control in the FreeIPA domain.
Other Setup Options
--no-host-dns Does not use DNS to look up the hostname of the FreeIPA server machine during the installation process.
-U --unattended Runs the ipa-server-install command without any interactive prompts.
--uninstall Uninstalls an existing FreeIPA server.
General Tool Options
-d --debug Runs the ipa-server-install command in debug mode and outputs debugging information.
-h --help Prints the help information for the ipa-server-install command.
--version Prints the version number of the ipa-server-install command.
[a] The installation script will prompt for these options if they are not passed with the script.