Product SiteDocumentation Site

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

C.5.1. A Quick Summary of Configuration Scripts

There are two basic categories of command-line scripts that FreeIPA has available.
The first is a selection of independent configuration scripts which are used to set up machines that operate within the domain. Most of these scripts are used to add servers and clients to the FreeIPA domain, such as the ipa-server-install, ipa-client-install, and ipa-replica-install scripts.
Some scripts are also available to enable services within the FreeIPA server, such as adding CA services to a replica or enabling DNS. Several services can be configured when a server or replica is installed, but few of those services are required. If a server is configured without a service like DNS, that service can be enabled later using a specific configuration script, such as ipa-dns-install.
Then there are scripts that are simply used to manage FreeIPA domain. These scripts can be used to create or delete keytabs and certificates for any service or host within the domain, to set management rules for hosts and services (managed by settings),
Then there are a handful of scripts which are strictly internal, like ipa-join, meaning they are called by other management scripts but are not invoked by administrators directly.
Table C.3. FreeIPA Scripts
Name Description
ipa-ca-install Installs a Dogtag CA on a replica which previously did not have a CA installed.
ipa-join Adds a client or host machine to the FreeIPA domain. Used by other scripts; not invoked by administrators directly.
ipa-replica-prepare Pulls the configuration from a FreeIPA server to use to set up a replica.
ipa-client-install Sets up the host entry for a Fedora system and configures all associated services.
ipa-ldap-updater Updates the 389 Directory Server databases used by the FreeIPA server. Used by other scripts; not invoked by administrators directly.
ipa-rmkeytab Deletes a keytab generated for a FreeIPA user, service, or host.
ipa-compat-manage Enables or disables the compatibility plug-in to use with NIS servers running with RFC 2307 schema.
ipa-managed-entries Enables or disables the 389 Directory Server Managed Entries Plug-in which manages user private groups.
ipa-server-certinstall Replaces the current SSL certificates used with the FreeIPA server with new certificates. (The certificates must be generated externally, such as using the pk12util tool.)
ipa-csreplica-manage Manages the replication agreements between the 389 Directory Server instances used by the certificate authorities for a server or replica.
ipa-nis-manage Enables or disables the NIS listener plug-in.
ipa-server-install Installs all of the backend servers used by a FreeIPA server and configures associated services and domains.
ipa-upgradeconfig Upgrades the Apache instance used by the FreeIPA web UI. Used by other scripts; not invoked by administrators directly.
ipa-replica-conncheck Checks the connection between a FreeIPA server and a replica. This is typically run internally when a replica is installed (with ipa-replica-install), but can be run manually to troubleshoot connection issues.
ipa-dns-install Installs and configures a DNS server for a FreeIPA server which was initially configured without DNS.
ipa-replica-install Installs and configures a FreeIPA replica instance, based on the submitted FreeIPA server configuration which was extracted using ipa-replica-prepare.
ipa-getcert Submits requests and manages certificates for user which are issued and tracked using the Certmonger utility.
ipa-getkeytab Requests a new keytab for a FreeIPA service, host, or user.
ipa-replica-manage Edits the replication agreements between FreeIPA servers and replicas and synchronization agreements between the FreeIPA server and Active Directory domain controller.

C.5.2. 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.

C.5.2.1. Location

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

C.5.2.2. Syntax

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

C.5.2.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.
--setup-ca Sets up a Dogtag Certificate System certificate authority. Otherwise, no CA is configured for the replica.
--ip-address=IPaddress Adds the host machine using its IP address, rather than the hostname.
-N --no-ntp Does not configure NTP on the replica system.
--no-sshd Does not configure the OpenSSH server or client.
--ssh-trust-dns Configures the OpenSSH client for the FreeIPA client to trust any domain DNS SSHFP records.
--no-ui-redirect Configures the Apache server to not automatically redirect to the FreeIPA web UI, so that the web UI has to be accessed through its /ipa/ui path.
-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.
--reverse-zone Gives a DNS reverse zone to use with the replica DNS services.
--no-reverse Disables reverse DNS creation through the server installation process. (If a reverse DNS zone is already configured, then that existing reverse DNS zone is used.) If this option is not used, then the default value is true, which assumes that reverse DNS should be configured by the installation script.
--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-dns-sshfp Configures the client to not configure DNS SSHFP records.
--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.

C.5.3. 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-install command.

NOTE

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

C.5.3.1. Location

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

C.5.3.2. Syntax

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

C.5.3.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.

C.5.4. 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.

C.5.4.1. Location

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

C.5.4.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 ]

C.5.4.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.
Additionally, the hostname must all be lower-case. No capital letters are allowed.
-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.
--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 Disables reverse DNS creation through the server installation process. (If a reverse DNS zone is already configured, then that existing reverse DNS zone is used.) If this option is not used, then the default value is true, which assumes that reverse DNS should be configured by the installation script.
--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.