Performing post-upgrade tasks

Resource ResourceName contains an invalid path prefix and cannot be migrated to the target version. Manual intervention is required.

This occurs when the 2.1 path prefix contains functionality supported through a Java regex, but not by the wild card support in 3.1. The user must manually migrate the regex to 1 or more path prefixes in 3.1. For example, consider the 2.1 prefix,  /(app1|app2). This can be translated to a single resource in 3.1.1 with path prefixes of /app1 and /app2.

Resource ResourceName requires a case-sensitive path. This conflicts with its containing application, which requires a case-insensitive path. Manual intervention may be required.

The upgrade utility identifies path prefixes in 2.1 that start with /(?i) as path prefixes that are case-insensitive, and sets the case-sensitivity flag on the application appropriately. However, if multiple resources in a new application use inconsistent case sensitivity settings, the utility cannot determine what the case sensitivity should be. 2.1 resources are case-sensitive by default.

Resource ResourceName requires a case-insensitive path. This conflicts with its containing application, which requires a case-sensitive path. Manual intervention may be required.

This is the same as the previous setting, but with the requirement being for a case-insensitive path rather than a case-sensitive one.

Resource ResourceName is disabled in the source version. Resources can no longer be individually disabled. Application ApplicationName has been disabled due to this constraint.

In 2.1, individual resources can be disabled. In 3.1, only applications can be enabled or disabled. The upgrade utility takes the approach of disabling the application if any related resources are disabled. Check the final configuration and make sure this is the desired outcome.  If it is not, the disabled resources need to be deleted, and the application needs to be enabled.

Path prefix for resource ResourceName contains a '.' character. This will be treated as a literal '.' in the target version.

In a 2.1 setup, there might be resource names that accidentally contain a '.', assuming it is a literal '.' rather than part of a regex. For example, any file extension type resources will probably not be escaping the '.'. This message is intended to bring this change in semantics to the user’s attention. This action item will not show up if the user has correctly escaped the '.' character with the '\.' sequence.

Resource ResourceName could not be migrated to the target version due to application context root conflicts. Manual intervention is required.

This message indicates that multiple resources that use the same virtual host, but a different web session or site must be mapped under the same context root in the same application to preserve semantics.  For example, consider the following configuration:

This configuration triggers this error because these resources cannot be grouped in the same application, but they would need to be to preserve the semantics in the internal.example.com address space. This issue could be fixed by using rewrite rules to place Resource C or Resources A and B under a different namespace. For example, use /intranet/sales and /intranet/hr on the front-end and rewrite out the /intranet on the backend.

Application ApplicationName contains OAuth rules, but authenticates users with a web session. Unexpected results may occur.

Step 2.1 allows OAuth rules to be attached resources that use a web session. While this configuration is likely invalid in the first place, it would be possible to include both a PingAccess cookie and OAuth token in requests and PingAccess would apply policy to the requests as configured. In 3.1, however, an application programming interface (API) application and web application are mutually exclusive so the semantics of this particular configuration cannot be preserved.

The resource order for virtual host VirtualHostName has changed in the target version.

The upgrade utility checks that the resource order is consistent before and after the upgrade. This message indicates that the resource order from 2.1 does not match 3.1. This is likely due to how context roots in applications are ordered in 3.1. For 3.1, applications are ordered based on their context root, where the longest context root is checked first during resource matching.

One way to address this is to review and potentially change the application context root values associated with the virtual host to avoid Uniform Resource Locator (URL) overlaps between applications.

Application ApplicationName is no longer associated with an identity mapping. A web session or an authorization server is required to use identity mappings.

Indicates a misconfiguration in the source version. Check whether you intended to use an identity mapping for the application and associate an appropriate web session or authorization server if necessary.

OAuth rule with id RuleId is no longer associated with application ApplicationName because application ApplicationName is not an OAuth application. Manual intervention might be required.

Indicates a misconfiguration in the source version. Check whether the OAuth rule is necessary to implement the desired access control policy.

OAuth RuleSet with id RuleSetId is no longer associated with application ApplicationName because application ApplicationName is not an OAuth application. Manual intervention might be required.

Indicates a misconfiguration in the source version. Check whether the OAuth RuleSet is necessary to implement the desired access control policy.

Resource ResourceName from application with id ApplicationId was not migrated because the application is a web application while the resource has OAuth rules. Manual intervention might be required.

Indicates a resource associated with the application is associated with OAuth rules. This is likely a misconfiguration, and it is necessary to evaluate whether this was intended or not.

Upgrade created availability profile for site SiteName. A more descriptive name might be required.

Indicates that an availability profile was created for the site during the upgrade. You might want to give the availability profile a more descriptive name.

Application ApplicationName and associated resources were not migrated. The context root of /pa is reserved. Manual intervention might be required.

The /pa context root was allowed as a valid context root in PingAccess 3.0 and is no longer allowed.

Resource ResourceName from application with id ApplicationId was not migrated because the /pa prefix is reserved when the application context root is /. Manual intervention may be required.

The /pa path prefix was allowed as a valid path prefix in PingAccess 3.0 and is no longer allowed.

The OAuth Groovy script rule no longer controls the realm in the response sent for an unauthorized OAuth request.

With PingAccess 3.2, realms moved to the application. The Realm can still be set using the PingAccess admin API interface. With the change in context for how realms are applied, it is necessary to check existing OAuth Groovy rules to ensure that they behave as expected. This message is shown if any OAuth Groovy rules exist in the migrated configuration.

The property PropertyName was set to a blank value to maintain compatibility. Set this to PropertyName=PropertyValue.

New security headers properties values are not set during an upgrade to preserve the behavior from the source release in the upgrade. If there is no reason not to in your environment, update the run.properties file with the recommended setting.

As a security enhancement, the default value of CipherList has changed with this version of PingAccess. Your existing ciphers remain unchanged. Use the default value: PropertyName=CipherList.

This message applies to the admin.ssl.ciphers, engine.ssl.ciphers, and agent.ssl.ciphers lists. This message is displayed if the upgrade source version cipher lists are changed from the defaults. Update the configuration with the new default value if possible.

The property PropertyName was set to a blank value to maintain compatibility. Set this to PropertyName=CipherList.

This message applies to the site.ssl.protocols, site.ssl.ciphers, pf.ssl.protocols, and pf.ssl.ciphers settings. The upgrade utility sets these values as empty values to maintain backwards compatibility, but the recommended value should be used if possible.

The host for virtual host VirtualHost:Port already has a keypair associated with it. The keypair previously associated with this virtual host was removed. Only one keypair can be associated with a given host.

If a virtual host has more than one key pair associated with it, only one key pair will be associated with it after the upgrade completes. This message displays to indicate which key pair was used.

Application with name ApplicationName not migrated as the context root Path was a reserved path.

If an application’s context root is a reserved PingAccess path, the application will not be migrated. The indicated application will need to be created with a context root that does not conflict with the reserved path.

Resource with name ResourceName not migrated as the path Path was a reserved path.

If a resource path is a reserved PingAccess path, the application will not be migrated. The indicated application will need to be created with a context root that does not conflict with the reserved path.

The CIDR rule with name RuleName is associated with an agent application named ApplicationName and overrides the IP source configuration. A new Agent rule should be created that does not override the IP source.

With changes in IP source header handling, additional options are available to override the headers used to identify the source address. When an agent is involved, the changes in IP source handling might cause the specified rule to not behave as expected.

Require HTTPS option on application ApplicationName was set to Setting as virtual host had port Port. Please verify this setting is correct.

The upgrade utility attempts to set the Require HTTPS option based on the virtual host associated with an application during an upgrade. This message is an advisory to just verify that the setting was properly detected.

Virtual host VirtualHost was not migrated. An existing virtual host existed with the same logical name VirtualHost.

Virtual host names are now case-insensitive. During the upgrade, after making the names case-insensitive, a duplicate virtual host was identified. It will be necessary to either recreate the virtual host with a new name, or to modify the configuration so the proper virtual host is migrated to the upgraded system.

Renamed virtual host’s hostname from VirtualHost to NewVirtualHost due to virtual host spec compliance issue

If a virtual host name contains an underscore (_) character, that does not conform to host naming requirements. In this instance, the underscore will be renamed to the string a-z. For example, if a virtual host named my_virtual_host is migrated, the new name will be mya-zvirtuala-zhost.

Removed HTTP request rule with name RuleName, this rule must be converted to a Groovy script rule. Manual intervention might be required.

When an HTTP request rule is migrated from an earlier release of PingAccess, rules that specify a source of Body are not migrated. A Groovy script rule can be used to perform a similar match, but the details of such a Groovy script require administrator intervention.

A simple Groovy script rule that would perform a similar function might be:

A script should be constructed that performs additional validation to ensure the rule passes only when desired. A generic match like this could lead to unexpected results depending on what content might be in the request body.

The property PropertyName uses a customized value. "Your original value has not been modified. You may encounter startup or connection problems if this value is not supported by the JVM."

When migrating SSL settings between versions of PingAccess that use different Java Virtual Machine (JVM) or Java Development Kit (JDK) versions, custom settings might not be compatible. If the protocols or ciphers used are not compatible with the target JVM or JDK, this message indicates which settings need to be manually updated.

The PropertyName value can be any of the following values:

Rule with ID RuleId and name RuleName was not migrated as matcher was invalid for the Groovy rule type.

Invalid rules were removed from RuleSet RuleSetName which resulted in an empty set.

The RuleSet was removed. Please check your policy configuration.

Invalid rules were removed from RuleSet RuleSetName. Please check your policy configuration.

Invalid rules were removed from application ApplicationName. Please check your policy configuration.

Invalid RuleSets were removed from application ApplicationName. Please check your policy configuration.

Invalid rules were removed from resource resource name on application ApplicationName. Please check your policy configuration.

Invalid RuleSets were removed from Resource 'resource name' on Application 'ApplicationName'. Please check your policy configuration.

These messages might appear if the source PingAccess installation has misconfigured Groovy Rules.

This indicates that you are not permitted to add an OAuth rule to an Application of type Web by editing an existing rule set.

Groovy or OAuth Groovy rules will not be migrated for the following reasons:

Check the policy configuration.

Rule with name RuleName has been removed from RuleSet with name RuleSetName. Multiple rate limiting rules with the same policy granularity cannot be included in a RuleSet."

Rule with name RuleName has been removed from RuleSet with name RuleSetName. Multiple cross-Origin request rules cannot be included in a RuleSet."

The upgrade utility supports migrating a rule set containing multiple cross-origin resource sharing (CORS) or rate limiting rules with the same policy granularity. The upgrade utility will generate new action items, indicating that rules were removed from a rule set.

These messages indicate that if both rules exist, there is a restriction to a single rate limiting or CORS rule. Please check to confirm that you have applied the correct rule to the policy.

One or more notifications were issued while migrating from version SOURCE to version TARGET.

Setting clusterconfig.enabled to false

The new configuration query port feature has been disabled for backward compatibility. Please refer to the PingAccess clustering documentation before enabling this feature.

The new cluster config query port is enabled by default for new PingAccess 4.0 installations when running in CLUSTERED_CONSOLE or CLUSTERED_CONSOLE_REPLICA mode.

During the upgrade process to version 4.0, the new cluster config query port is disabled. Messages are written to upgrade.log and audit.log to indicate this cluster configuration change was made.

See the PingAccess clustering documentation before enabling this feature.

One or more notifications were issued while migrating from version SOURCE to version TARGET

For backward compatibility, when connecting to a protected, TLS SNI-enabled site, PingAccess will set the SNI server_name to the configured target host and not the HTTP request Host header value. Please refer to PingAccess' upgrade documentation for more information.

During upgrades to release 4.0 and higher, the upgrade utility sets the value of pa.site.tls.sni.legacyMode to true to maintain compatibility with existing configurations. This property is controlled in the run.properties file and is not enabled on new installs.

Localization property \{property name} was added to pa-messages.properties. Any customized localization files should be updated.

This message appears if new language properties are added between the source and target PingAccess versions and you have added additional language files or modified the en or en_US files. Update any customized files as required.

Localization property \{property name} in pa-messages.properties was modified. Any customized localization files should be updated.

This message appears if the language properties have changed between the source and target PingAccess versions and you have added additional language files or modified the en or en_US files. Update any customized files as required.

Localization property \{property name} was removed from pa-messages.properties. This property can be removed from any customized localization files.

This message appears if the language properties have been removed between the source and target PingAccess versions and you have added additional language files or modified the en or en_US files. Update any customized files as required.

WebSessionManagement contained an invalid cookie name. Replaced \{old cookie name} with \{new cookie name}. Please validate your configuration.

This message appears if the WebSessionManagement has an invalid cookie name. Invalid characters are replaced with an underscore. Update any references as required.

Legacy authentication requirements policy evaluation has been enabled to maintain backward compatibility with earlier versions of PingAccess. To disable this setting, remove the pa.policy.eval.acr.v42 property from run.properties.

This message appears on upgrade to release 4.3 or later if you have one or more authentication requirements rules. You can make adjustments to configured rules so you can remove this property or you can maintain the property to leave existing rules unaffected.

Property pa.audit.log.applicationResourceIdsAsIntegers was set to true in run.properties to maintain existing behavior. In order to log the ID of Global Unprotected Resources, this property should be removed or should be set to false (default). However, a value of false (default) will result in resourceId and applicationId audit logging fields being logged as strings, not integers, which may require audit logging database schema changes if these values are currently being used.

This message appears on upgrade to release 5.1 or later to support the existing logging behavior of application resource IDs as integers. The default behavior of release 5.1 and later is to log these IDs as strings. You can choose to log application resource IDs as strings after the upgrade by removing, or setting to false, the applicable property in the run.properties file. This change might require a modification to the audit logging database schema.

Invalid resource method Method was removed from resource ResourceName on application ApplicationName.

This message appears on upgrade to release 5.3 or later if the source version has an application resource that contains a method with whitespace. The resource is preserved by the upgrade, but the method is removed.

Invalid resource {name} on application {name} was removed because it did not have any valid methods.

This message appears on upgrade to release 5.3 or later if all of the methods associated with a resource were removed with an Invalid resource method error. The resource is not migrated by the upgrade.

As of PingAccess 6.0, runtime state clustering using JGroups has been deprecated. Deployments relying on runtime state clustering will continue to function but the functionality will be replaced in a future version.

This message appears on an upgrade to release 6.0 or later. The runtime state clustering feature has been deprecated.