MID Server pre-upgrade check

The instance automatically tests the MID Server's ability to upgrade on your system prior to the actual upgrade, to identify issues that could cause a MID Server outage or require reinstallation.

Each MID Server contains an AutoUpgrade monitor that compares the MID Server version with that of the instance to determine if the MID Server needs to upgrade. If the AutoUpgrade monitor discovers that the MID Server version is out of date, the monitor runs pre-upgrade validation tests for that MID Server. If an issue is detected, a message is logged to the MID Server Issue [ecc_agent_issue] table, and the upgrade is blocked. The AutoUpgrade monitor continues to run every hour, until the tests all pass. If there are no blocking issues, the MID Server downloads the appropriate upgrade package and begins the upgrade process.

Failed tests leave the MID Server in one of these states:
  • Upgrade Failed: For upgrades to a different release family, such as from Geneva to Jakarta.
  • Up: For upgrades within the same release family, such as an upgrade to a patch.
Errors, such as insufficient disk space for the installer and lack of connectivity to install.service-now.com, are written to both the MID Server agent log and to the MID Server Issue [ecc_agent_issue] table. These errors are published before the actual MID Server upgrade occurs and must be resolved before the upgrade can continue. You can view issues from the MID Server Issue [ecc_agent_issue] table in any of these locations;
  • MID Server Issues related list in a MID Server record.
  • MID Server > Server Issues navigation module.
  • MID Server Issues gauge on the MID Server dashboard.

Pre-upgrade tests

The pre-upgrade validation tests check these requirements:
  • At least 1GB of free disk space.
  • Access to the download site at install.service-now.com.
  • Permission to execute these file operations:
    • Extract a ZIP archive to a temp folder.
    • Copy files from the temp folder to the agent folder.
    • Read a text file.
    • Delete the pre-upgrade contents.
  • For Windows, ensure that the Log On As user for the Windows service is either LocalSystem or a user that is part of the local Administrator group. By default, domain administrators are added to the local Administrator group when joining a computer to a domain. If the PowerShell script that performs this test does not return the expected output, the system logs a warning to the MID Server Issue [ecc_agent_issue] table, but the test passes.

Data provided

When the instance encounters issues during the pre-upgrade check, it populates these fields in the MID Server Issue [ecc_agent_issue] table:
Table 1. MID Server issue fields
Field Description
Last detected Date and time the issue was last detected.
Short description Contents of the generated message that specifies a possible issue with available disk space, download server access, or file permissions.
MID Server Name of the MID Server affected by a pre-upgrade test failure.
Issue source The process that identified the issue. For all issues with MID Server pre-upgrade testing, the source is UpgradeCheck.
State The current state of the issue. Possible states are:
  • New: Starting state when the instance creates the issue.
  • Acknowledged: State set by the administrator when he or she first examines the issue.
  • Resolved: Ending state, set by the instance, indicating that the issue has been resolved. If the scheduled job does not encounter the issue when it runs again, the instance automatically sets the state to this value.
Domain Domain for the MID Server. For all issues derived from MID Server pre-upgrade testing, the domain value is inherited from the domain of the MID Server user.
Count Number of times an issue has been detected. Each time the pre-upgrade tests run and encounter the same issue, the AutoUpgrade monitor increments this field.

Errors that block the upgrade

These messages describe issues detected by the pre-upgrade test and published to the MID Server Issue [ecc_agent_issue] table. Failure of any of these tests blocks the upgrade.
  • Not enough free disk space. The system reports <n> bytes free: This message is displayed when less than 1GB of free disk space is detected on the MID Server host. This error is also written to the MID Server agent log.
  • Unable to download updates from install server: This message indicates that either the MID Server host does not have permission to download the installation package from install.service-now.com or network problems prevent connection. This error is also written to the MID Server agent log.
  • Unable to extract contents of pre upgrade check zip: This message indicates that the service account on the MID Server host does not have permission to extract the pre-upgrade ZIP archive to the temporary folder specified by the system property, java.io.tmpdir. On a UNIX host, the value for this property is typically /tmp or /var/tmp. On Microsoft Windows hosts, the path is c:\\WINNT\\TEMP.
  • Unable to create folder <upgrade check file path>: This message indicates that the MID Server service account does not have permission to create the upgradeCheck folder for the pre-upgrade checking files in the agent/package path.
  • Unable to verify file permissions: <message>: This message indicates an exception has occurred when checking file permissions, such as a file that does not exist or access failure.
  • MID Server Windows Service is not running as LocalSystem or a local Administrator: This message warns that the Windows service is not running with the desired permissions.

Non-blocking warnings

These warnings are displayed in the MID Server Issue [ecc_agent_issue] table and do not prevent a Windows MID Server from upgrading:
  • WARN: Unable to parse $logOnAsUser : This message warns that the Log On As User value for the Windows service is not in either of these expected formats:
    • user@domain.company.com
    • domain\user
  • WARN: Unable to look up Log On As user's groups: When the instance attempts to look up the logged on user's group memberships, it executes the net user <username> command. The instance expects a certain output structure by the Windows service from this command and issues this warning if the expected output does not match the actual output.
These PowerShell warnings are written to the MID Server agent log only. Because PowerShell is not required to use a MID Server, these configuration issues do not prevent a Windows MID Server from upgrading. However, these warnings might indicate issues in your environment that require attention.
  • Skipping PowerShell upgrade checks since PowerShell is not usable: PowerShell 2.0 (at a minimum) is not installed or powershell.exe is not available to the MID Server service user.
  • Continuing with upgrade, but the following issue was encountered during upgradeCheck: <exception message>: This message indicates that there was an issue running the PowerShell portion of the pre-upgrade tests.

Disabling the pre-upgrade check

A MID Server configuration parameter called mid.upgrade.run_precheck is set to true by default, which allows the automatic pre-upgrade test to run. To disable these tests for a single MID Server, add this parameter to that MID Server's config.xml file and set it to false. To disable these tests for all MID Servers, add a new record to the MID Server Property [ecc_agent_property] table called mid.upgrade.run_precheck. Set the value of this property to false and leave the MID Server field blank.