Installing PingFederate 11.0 - PingFederate - 11.0

PingFederate Server

bundle
pingfederate-110
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 11.0
category
Product
pf-110
pingfederate
ContentType_ce
Page created: 16 Jul 2021 |
Page updated: 19 Jan 2022
| 1 min read

Product PingFederate 11.0 Installation User task Product documentation Content Type Administrator Audience Software Deployment Method

You can install PingFederate on Windows and Linux operating systems.

Install PingFederate using the following methods:

  • Install PingFederate on a Windows system by running the installer for Windows or by extracting the distribution .zip archive. Using the installer for Windows is the preferred method.
  • Install PingFederate on a Linux system by extracting the distribution .zip archive.
Note:

This documentation refers to the installation directory path as <pf_install>. This is where the pingfederate directory is located. For example, <pf_install>/pingfederate/bin.

Important:

To avoid future problems with automated upgrades, do not rename the installed pingfederate directory.

If you are installing multiple instances of PingFederate on the same machine, such as a console node and an engine node in a clustered environment, install each instance using a unique <pf_install> directory.

If you are upgrading an existing PingFederate environment, see Upgrading PingFederate.

Installing PingFederate on Linux systems

Page created: 16 Jul 2021 |
Page updated: 19 Jan 2022
| 1 min read

Product PingFederate 11.0 Installation User task Product documentation Content Type Administrator Audience Software Deployment Method

You can install PingFederate on a Linux system using the distribution .zip archive.

  • See System requirements for a list of qualified Linux operating systems.
  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application. You must install and run PingFederate under a local user account.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java.
  1. Download the latest version of the PingFederate Server distribution .zip archive from the Downloads website.
  2. Extract the archive into the target installation directory.
  3. Start PingFederate manually by running the following script.

    <pf_install>/pingfederate/bin/run.sh

    Tip:

    To configure PingFederate to run as a service on Linux, install PingFederate on Linux manually.

    The startup process is complete when the following message appears.

    PingFederate running...

If your organization plans to manage keys and certificates using a hardware security module (HSM), see Supported hardware security modules.

Installing the PingFederate service on Linux manually

Page created: 16 Jul 2021 |
Page updated: 19 Jan 2022
| 4 min read

Product PingFederate 11.0 Installation User task Product documentation Content Type Administrator Audience Software Deployment Method

If you have not installed PingFederate on Linux using the distribution .zip archive, you can install it manually.

  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java in the PingFederate Server documentation.

To install the PingFederate service on Linux manually:

  1. Download the distribution .zip archive from the Ping Identity website.
  2. Extract the file into an installation directory, <pf_install>.
  3. Create a new local user account for the PingFederate service, such as pingfederate.
    Note:

    The service account is referred to as <pf_user>.

  4. Change the ownership of the PingFederate installation directory <pf_install> and update the read and write permissions using the following commands.
    chown -R <pf_user> <pf_install>
    chmod -R 775 <pf_install>
  5. If the operating system supports systemd, install the PingFederate unit file:
    1. Edit the pingfederate.service systemd unit file, located in the <pf_install>/pingfederate/sbin/linux directory.

      Replace the following variables with information from your environment:

      ${PF_VERSION}
      The version of PingFederate.
      ${PF_USER}
      The local user account for the PingFederate service.
      ${PF_HOME}
      The <pf_install>/pingfederate directory.
      For example, if <pf_install> is /opt/identity.fed, replace ${PF_HOME} with /opt/identity.fed/pingfederate.
      ${PF_JAVA_HOME}
      The JAVA_HOME environment variable value (a directory).
    2. Copy the pingfederate.service file to the systemd unit files directory, for example, /etc/systemd/system.
      Note:

      Depending on the operating system, the exact location might vary. Consult your system administrators as needed. The rest of the step assumes /etc/systemd/system is the systemd unit files directory.

    3. Use the following command to update the read and write permissions of the pingfederate.service systemd unit file.
      chmod 664 /etc/systemd/system/pingfederate.service
    4. Use the following commands to load the new system configuration changes and start the PingFederate service.
      systemctl daemon-reload ;\
      systemctl start pingfederate
    5. Use the following commands to configure the PingFederate service to start automatically as the server boots.
      systemctl enable pingfederate ;\
      systemctl daemon-reload ;\
      systemctl restart pingfederate

    After setting up the PingFederate systemd unit file, you can use the following systemctl command to manage the PingFederate service.

    systemctl start pingfederate
    systemctl stop pingfederate
    systemctl restart pingfederate
    systemctl status pingfederate
  6. If the operating system supports SysV initialization, follow these steps to install the PingFederate script.
    1. Edit the pingfederate script, located in the <pf_install>/pingfederate/sbin/linux directory.

      Replace the following statements with information from your environment:

      PF_HOME=$PF_HOME
      Replace $PF_HOME with the <pf_install>/pingfederate directory.
      For example, if <pf_install> is /opt/identity.fed, replace $PF_HOME with /opt/identity.fed/pingfederate.
      USER="pingfederate"
      If the PingFederate service account is not pingfederate, replace pingfederate with the local user account for the PingFederate service.
      For example, if <pf_user> is pingfed, replace pingfederate with pingfed.
      Example (truncated)
      If <pf_install> and <pf_user> are /opt/identity.fed and pingfederate respectively, the required modifications are as follows.
      ...
      PF_HOME=/opt/identity.fed/pingfederate
      DIR="$PF_HOME/sbin"
      USER="pingfederate"
      ...
    2. Copy the pingfederate script to the SysV initialization directory, for example, /etc/rc.d/init.d.

      The exact location might vary, depending on the operating system. Consult your system administrators, as needed. The rest of the step assumes /etc/rc.d/init.d is the SysV initialization directory.

    3. Use the following command to update the read and write permissions of the pingfederate SysV initialization script.
      chmod 755 /etc/rc.d/init.d/pingfederate
    4. Configure the operating system to start the PingFederate service at various runlevels.

      On an RHEL server, you can use the Service Configuration utility to do so.

      Alternatively, the initialization directories associated with various runlevels can accept manual symbolic links of the pingfederate script using the ln -s source target command.

      You can create the following symbolic links on an RHEL server where runlevels 2 and 4 are not used.

      ln -s /etc/rc.d/init.d/pingfederate /etc/rc3.d/S84pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc5.d/S84pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc0.d/K15pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc1.d/K15pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc6.d/K15pingfederate
      Note:

      Some operating systems might require a restart of the system to activate the new scripts. Consult your system administrators as needed.

After setting up the PingFederate SysV initialization script, you can use the Service Configuration utility or the following service commands to manage the PingFederate service.

service pingfederate start
service pingfederate stop
service pingfederate restart
service pingfederate status

Installing PingFederate on Windows

Page created: 16 Jul 2021 |
Page updated: 19 Jan 2022
| 2 min read

Product PingFederate 11.0 Installation User task Product documentation Content Type Administrator Audience Software Deployment Method

You can install PingFederate on a Windows system using the installer for Windows or the distribution .zip archive. Using the installer for Windows is the preferred method.

  • Request a license key through the Ping Identity licensing page.
  • Ensure your are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java.
  1. Install PingFederate using the installer for Windows or the distribution .zip archive as described in the following table.
    Installation medium Steps

    PingFederate installer for Windows

    To install PingFederate using the installer for Windows:

    1. Download the PingFederate installer for Windows from the Ping Identity website.
    2. Double-click the .msi file to open the PingFederate Setup Wizard, and follow the instructions to complete the installation.

    PingFederate is configured to run as a service and starts automatically at the end of the installation process.

    Note:

    The PingFederate installer for Windows installs only one instance of PingFederate on a Windows server. If you need additional PingFederate instances on the same Windows server, install them using the distribution .zip archive.

    You must manually configure various port settings in the <pf_install>/pingfederate/bin/run.properties file for each instance to avoid port conflicts.

    Distribution .zip file

    To install PingFederate using the distribution .zip archive:

    1. Download the distribution .zip archive from the Ping Identity website. The distribution .zip archive is identical for both Windows and Linux.
    2. Extract the file into an installation directory.
  2. If you have installed PingFederate by extracting the distribution .zip archive, start PingFederate manually by running the following script.

    <pf_install>/pingfederate/bin/run.bat

    Wait for the script to finish. The startup process completes when the following message appears.

    PingFederate running...
    Tip:

    To configure PingFederate to run as a service on Windows, install PingFederate on Windows manually.

    CAUTION:

    When running PingFederate for Windows, switching the Java version from 8 to 11 (or the reverse) will prevent the service from running, and you will not be able to start PingFederate. The problem occurs because garbage collection logging configuration arguments that are used by Java 8 are incompatible with those used by Java 11.

    To change Java versions:

    1. Run <pf_install>\pingfederate\sbin\win-x86-64\uninstall-service.bat to de-register the PingFederate service.
    2. Install the new Java version and update the JAVA_HOME and PATH environment variables.
    3. Run <pf_install>\pingfederate\sbin\win-x86-64\install-service.bat to register the PingFederate service.

If your organization plans to manage keys and certificates using a hardware security module (HSM), see Supported hardware security modules.

Installing the PingFederate service on Windows manually

Page created: 16 Jul 2021 |
Page updated: 19 Jan 2022
| 1 min read

Product PingFederate 11.0 Installation User task Product documentation Content Type Administrator Audience Software Deployment Method

If you have not installed PingFederate using the installer for Windows, you can install the PingFederate service manually.

  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. See Installing Java.
Note:

If you have installed PingFederate using the installer for Windows, skip these steps because PingFederate has already been configured to run as a service and to start automatically at the end of the installation process.

  1. Download the distribution .zip archive from the Ping Identity website.

    The distribution .zip archive is identical for both Windows and Linux.

  2. Extract the archive into an installation directory, <pf_install>.
  3. Start PowerShell or Command Prompt as an administrator.
  4. Run the <pf_install>\pingfederate\sbin\win-x86-64\install-service.bat file.
  5. Open the Control Panel > Administrative Tools > Services management console.
  6. Right-click the PingFederate service and select Start.

The PingFederate service starts automatically on reboot.