Environment

PhenixID Server version 2.0 to 3.2.

NOTE: If running two or more nodes in clustered environment, please also read this document:
Cluster

Situation

PhenixID Server prior to version 4.0 installed.

Upgrade to version 4.0 will be performed.

Version 4.0 of PAS will introduce a new internal database (hsqldb). This database will be used by default. Version 4.0 also introduce the possibility to use an external database, either MySQL or MSSQL. This option can be used if desired and is mandatory for installations where the database should be clustered.

Remember to have a full backup of the earlier installation, before starting the upgrade scenario.

Prerequisites and information needed

Prerequisite

Please see server requirements here:
Server requirements

For the database import make sure to have the correct database driver file when doing the import. Default drivers can be found in:
/mods/com.phenixidentity~phenix-store-mpl~4.0/lib

Some tools are needed for the upgrade, they can be downloaded from this document:
Configure Database

Information needed for new installation/configuration

• Operating System for PhenixID Server installation
• Ports in use
  • Port for administrative GUI
  • Port used by the configured applications
  • Port used by RADIUS
  • Ports used by PhenixID http API, if used
• What type of Scenarios has been made, ie RADIUS, OTPAdmin, Self Service and so on
• What type of LDAP store is used, address, port and service account used
• Encryption key/Password used for OrientDB
• What kind of delivery methods are in use, ie SMS, SMTP
• Is there any third party SMS gateways configured
• Is tokens being used
• Standalone or cluster
  • In case of cluster, read this document
• Is there a proxy in place for internet access
• Has the PhenixID default certificate been replaced
• Has any certificates been added to the JAVA trust store, cacerts
• Has there been any changes done to text in template files, like SMS or SMTP (meaning the text that is sent to users with OTP)
• To prepare for new version the following files contain important information (remember that some of these contain password, although encrypted):
  • /bin/start-PhenixID.sh (Linux)
  • /bin/*.vmoptions (Windows)
  • /classes/cluster.xml
  • /config/log4j2.xml (log4j.xml in early versions)
  • /config/boot.json
  • /config/phenix-store.json
  • /resources/*.xml and/or *.p12
  • Any template files where text has been changed
• If customization has been done to the web pages, PAS version 4.0 introduce a separate folder for these changes. See this document:
  Overlay folder
• To verify communication and credentials use  the PhenixID Testtool found in the bin folder.

Upgrade to 4.0

Follow the steps below to upgrade current installation to 4.0.

1. Backup
   Make sure to backup the current PAS installation.
2. Export of database
   Versions of PAS before 4.0 use OrientDB as database, starting from version 4.0, HSQLDB is used as default internal database.
   Version 4.0 also introduce the possibility to use MySQL or MSSQL as database.
   The data stored in earlier OrientDB will be exported and then imported into the new database.
   More information in this document:
   Export
3. Backup of ot_auth_template.json
   If changes have been made to /resources/ot_auth_template.json, take a copy of this file. It will be replaced during upgrade.
4. Upgrade
   Perform the in-place upgrade, but do not start the service yet.
5. Add new http client
   When upgrade is done, configuration for the new http client needs to be added to /config/boot.json.
   Instructions in this document:
   http client
6. New database
   We will now add configuration for the database of choice.
   This is also done in /config/boot.json.
   Instructions in this document:
   New database
7. Create database
   HSQLDB will be created when PAS is started. For Mysql and MSSQL, use the script “phenixid.sql” to create the initial database structure.
8. Replace cluster.xml
   If updating to 4.1 or 4.2 the cluster.xml has to be replaced.
   cluster.xml
9. Move Session-manager
   If updating to 4.1 or 4.2, the module for session manager must be moved in boot.json and must be removed in Advanced mode after startup.
   Session-manager
10. Patched files for log4j2
    Before starting the service, make sure to replace default log4j2 file(s), with patched ones:
    https://support.phenixid.se/uncategorized/log4j-fix/
    Be aware that log4j2 file can be in multiple directories, depending on the version of PAS.
    Follow the instructions:
    “Under <install_root>, locate all the occurrences  of log4j-core-*.jar.  Note that there could be multiple instances, found in different locations.”
11. Start PAS
    It’s now time to start PAS version 4.0. Verify the startup in /logs/server.log.
    NOTE: In clustered environments, the startup parameters used in versions earlier than 4.x must be removed. More information in this document.
12. Add new http client to modules
    When service is started, log in to the configuration portal. Then go to Advanced tab and Modules. Add the same configuration for http client as in step 4, but also add configuration parameter “id”.
    Instructions in this document:
    http client
    NOTE: Both outgoing and incoming communication has changed with this new module, where 2MB (2097152) is the default value.
    To change this value, use the startup parameter:
    “Dcom.phenixidentity.globals.httpRequestBodyMaxSize”
    More information in the above link.
13. Authentication API
    If the Authentication API is configured, make sure that a “http_configuration_ref” is set.
    More information:
    http_configuration_ref
14. Import database
    Instructions for the database import can be found in this document:
    Import
15. Reports
    Some of the default reports use “limit” in the query. This is not supported by all types of databases. If it’s not supported, the following line is seen in server.log:
    “Incorrect syntax near ‘limit'”
    If “limit” is not supported, please adjust the query accordingly.
    Reports are located in folder:
    mods\com.phenixidentity~phenix-prism-report~4.0\js\reports
    Example of query using limit:

    "query": "select * from event where eventID ='EVT_001022' order by date desc limit 1000"

    Example with top instead of limit:

    "query": "select top 1000 * from event where eventID ='EVT_001022' order by date desc"

16. Overlay
    Create the overlay folder by unzipping the file from this document:
    Overlay folder
17. Logging
    Update log4j2.xml to add %X{trace_id} to your log pattern configuration. An example can be found in log4j2_template.xml.

    Example:

     <PatternLayout pattern="%d [%c{1}] %X{trace_id} %p: %m%n"/>