Product SiteDocumentation Site

2.6. Upgrading from FreeIPA 2.1 to 2.2

FreeIPA is generally updated whenever a system is upgraded to a new release. Upgrades should be transparent and do not require any user or administrative intervention.

2.6.1. Upgrading Packages

The FreeIPA server packages are updated when the system packages are updated:
[root@ipaserver ~]# yum update *
This is the easiest way to upgrade the server because it automatically pulls in updates for related services, like SSSD, which provide FreeIPA functionality.
To upgrade the FreeIPA server packages specifically, run yum on the master server:
[root@ipaserver ~]# yum update freeipa-server
It can take several seconds for the update process to apply all of the changes.
The update process automatically updates all schema and LDAP configuration, Apache configuration, and other services configuration, and restarts all FreeIPA-associated services.
It is not necessary to update all servers and replicas at precisely the same time; the FreeIPA servers will still work with each other and replicate data successfully. The older FreeIPA servers will simply lack the new features.

NOTE

Schema changes are replicated between servers. So once one master server is updated, all servers and replicas will have the updated schema, even if their packages are not yet updated. This ensures that any new entries which use the new schema can still be replicated among all the servers in the FreeIPA domain.

NOTE

Clients do not need to have new packages installed. The client packages used to configured a Fedora system do not impact the enrollment of the client within the domain.
Updating client packages could bring in updated packages for other dependencies, such as certmonger which contain bug fixes, but this is not required to maintain client functionality or behavior within the FreeIPA domain.

2.6.2. Removing Browser Configuration for Ticket Delegation

As part of establishing Kerberos authentication, a principal is given a ticket granting ticket (TGT). Whenever that principal attempts to contact a service or application within the Kerberos domain, the service checks for an active TGT and then requests its own service-specific ticket from the TGT for that principal to access that service.
As part of configuring the web browser used to access the FreeIPA web UI (and any other Kerberos-aware web applications), previous versions of FreeIPA required that the TGT delegation be forwarded to the FreeIPA server. This required adding the delegation-uris parameter to the about:config setup in Firefox:
network.negotiate-auth.delegation-uris .example.com
FreeIPA 2.2 uses the Kerberos Services for User to Proxy (S4U2Proxy), so this additional delegation step is no longer required.
Updating Existing Configured Browsers
For browsers which have already been configured to use the FreeIPA web UI, the delegation-uris setting can be cleared after upgrading to ipa-server-2.2.0 or ipa-client-2.2.0.
There is no need to restart the browser after changing the delegation-uris setting.
Updating configure.jar for New Browser Configuration
The browser configuration is defined in the configure.jar file. This JAR file is generated when the server is installed and it is not updated with other files when FreeIPA is updated. Any browsers configured will still have the delegation-uris parameter set unnecessarily, even after the FreeIPA server is upgraded. However, the configure.jar file can be updated.
The preference.html file in configure.jar sets the delegation-uris parameter. The updated preference.html file can be added to configure.jar, and then configure.jar can be re-signed and re-deployed on the FreeIPA servers.

NOTE

Only update the configure.jar file on the initial FreeIPA server. This is the master server, and it is the only server which has a signing certificate. Then propagate the updated file to the other servers and replicas.
  1. Update the packages on the initial FreeIPA master server (the first instance). This will bring in the 2.2 UI packages, including the configure.jar file.
  2. Back up the existing configure.jar file.
    [root@ipaserver ~]# mv /usr/share/ipa/html/configure.jar /usr/share/ipa/html/configure.jar.old
  3. Create a temporary working directory.
    [root@ipaserver ~]# mkdir /tmp/sign
  4. Copy the updated preference.html file to the working directory.
    [root@ipaserver ~]# cp /usr/share/ipa/html/preferences.html /tmp/sign
  5. Use the signtool command (one of the NSS utilities) to add the new preference.html file and re-sign the configure.jar file.
    [root@ipaserver ~]# signtool -d /etc/httpd/alias -k Signing-Cert -Z /usr/share/ipa/html/configure.jar -e ".html" -p `cat /etc/httpd/alias/pwdfile.txt` /tmp/sign
    The -e option tells the tool to sign only files with a .html extension. The -Z option creates a new JAR file.
  6. Copy the regenerated configure.jar file to all other FreeIPA servers and replicas.

2.6.3. Testing Before Upgrading the FreeIPA Server

It can be beneficial, and safer, to test newer versions of FreeIPA before upgrading production systems. There is a relatively simple way to do this by creating a sacrificial replica and testing on that system.
  1. Set up a replica based on one of the production servers, with the same version of FreeIPA as is running in production, as described in Section 2.4, “Setting up FreeIPA Replicas”. For this example, this is called Test Replica. Make sure that Test Replica can successfully connect to the production server and domain.
  2. After verifying that Test Replica has been successfully added to the production domain, disconnect Test Replica from the network.
  3. Remove the replication agreements for Test Replica from the original FreeIPA server and from Test Replica.
  4. Reconnect Test Replica to the network.
  5. Upgrade the packages on Test Replica using yum or whatever package update tool is appropriate for your system. For example:
    [root@ipareplica ~]# yum update ipa*
  6. Test common things on Test Replica, like getting Kerberos credentials, opening the server UI, and running commands.