This article describes how to update Agiloft to a newer version.

To identify the versions of the application being upgraded, see Release Version Numbering. If you are running a version of Agiloft with a release date prior to 2017_01 or 2019_01, you must install a minimum required version of Agiloft before you can upgrade to the current version.

You only need to update your system this way if you host your KB on-premise; if your KB is hosted by Agiloft, you do not need to complete any upgrade steps yourself. For more information, see Upgrades to Agiloft Hosted Servers.

Process Overview

In general, the update process has two steps:

Back up everything that should be backed up. This might include KBs, software code, database files, etc., depending on what is to be updated.
Perform the upgrade.

Update Methods

There are three ways to run the update process:

Online Update. This uses an online connection to download and install the newest version of Agiloft. This is the simplest method, provided you have a stable internet connection.
Manual Update. Download the installation files and install them locally. Use this option if your connection isn't stable.
EWUpdate Command Line Utility. This option is generally not necessary, but it can be useful for advanced functions, or in situations where the online and manual methods are unsuccessful.

Backing Up Data

Before you begin an upgrade, back up everything that should be backed up. This might include KBs, software code, database files, etc., depending on what is to be updated.

For smaller KBs, you can use the simpler but sometimes slower method of running a KB backup as part of the upgrade. The process is simple because the installer includes an option to create a full backup, and it automatically executes a set of integrity checks after the upgrade. In the rare case that something goes wrong and the system can't repair itself, it automatically rolls back to the pre-update state using the backup. However, creating a backup is time-consuming, so this is only recommended for smaller KBs.
For larger KBs, it's quicker to use native OS and database backup tools. For example, the Agiloft hosting service uses CephFS snapshots to create a backup of the file system. If you use one of these options to back up your data, during the upgrade, select the option not to create a backup. If necessary, you can even use this snapshot to test out the upgrade. Use the snapshot to restore your system onto a separate server, upgrade that server using the option not to create a backup, and then log in to that test environment to make sure everything is working smoothly.
If you have a larger KB, but you don't want the complexity of using native database facilities to create a backup, install on Linux with the default installation parameters. This means MySQL is installed on the same machine as the WildFly application server, so you can create a backup by simply shutting down the database and creating a .tar file. This is slower than taking a snapshot, but faster than a KB backup.

Preparing to Upgrade

Before you upgrade on a Windows server:

Open the command prompt as an Administrator and restart the Agiloft services. This clears up any long-waiting threads in the application or database process that might affect the upgrade. Here is an example of the command to use: C:\Agiloft\bin\ew-control.exe -a restart
Sign all other users out of that Windows server, aside from the user that runs the upgrade. This prevents other Windows users from interfering with the upgrade process, particularly while restarting services or accessing files and folders.

Minimum Required Versions

If you don't install every new version as it's released, you might need to upgrade to a minimum required version before proceeding to the current version of Agiloft. Review the list below and start by installing the earliest version of Agiloft that you don't yet have. You might need to install multiple minimum versions before you can upgrade to the current version of Agiloft. For example, if you're running version 2016_02 and want to upgrade to the latest version, you must first install the minimum required version 2017_01, then the next minimum required version 2019_01, before finally upgrading to the latest version.

Version 2019_01

If you're running a version of Agiloft with a release date prior to 2019_01, you must upgrade to the 2019_01 release before installing a later version.

Download the 2019_01 installer package from https://download.agiloft.com/upgrade/.
You cannot upgrade to version 2019_01 using the in-system Software Update option. You must download and run the installer package to upgrade to 2019_01.
Stop and disable the DHCP Client and Windows Event Log services, using the Services program or the Services tab of Task Manager. Make sure to disable them, not just stop them, so that they don't start running again during the upgrade.
Upgrade your system to 2019_01.
After the successful upgrade, upgrade to the current version of Agiloft, releases 2019_02 and later. You can enable the DHCP Client and Windows Event Log services at this point.

Version 2017_01

If you're running a version of Agiloft with a release date prior to 2017_01, you must upgrade to the 2017_01 release before installing a later version.

Download the 2017_01 installer package from https://download.agiloft.com/archive/2017_01/.
Stop and disable the DHCP Client and Windows Event Log services, using the Services program or the Services tab of Task Manager. Make sure to disable them, not just stop them, so that they don't start running again during the upgrade.
Upgrade your system to 2017_01.
After the successful upgrade, upgrade to the next minimum version of Agiloft, version 2019_01. You can enable the DHCP Client and Windows Event Log services at this point.

Running the Upgrade

Now, you can run the upgrade using one of the three methods.

Online Update

When possible, this is the recommended method because it's the simplest.

Stop and disable the DHCP Client and Windows Event Log services, using the Services program or the Services tab of Task Manager. Make sure to disable them, not just stop them, so that they don't start running again during the upgrade.
Run the Setup Assistant in your installation directory and select Software Update from the main menu, then click Check for updates online.
Setup automatically checks for a new version of Agiloft. If a new version is available, the Setup Assistant downloads it and starts the update.
You can monitor and set update options using the web interface.

Manual Update

If you aren't installing Agiloft for the first time, you can update the software by simply downloading and installing the latest version. The latest official release of Agiloft can be found here.

Stop and disable the DHCP Client and Windows Event Log services, using the Services program or the Services tab of Task Manager. Make sure to disable them, not just stop them, so that they don't start running again during the upgrade.
Run the downloaded installer. The installer detects an existing Agiloft instance and prompts the user about a possible update.
Confirm the selections on the Update Options screen. If you aren't familiar with the commands, be cautious in changing the default selections, particularly if you are working with a live system. The update options are explained in detail in Command Line Options.
Follow the steps in the installer to complete the upgrade.

EWUpdate Command Line Utility

The EWUpdate utility works the same way as the manual installer, but runs from the command line. If you run the utility with no options, it performs an update with all default options selected. If you need to change the options for the utility, use the command line options listed below.

Use the –help option (ewupdate --help) to see all the commands you can use with the utility.

Command Line Options

These options are available in the manual installer and in the EWUpdate command line utility. Default options can be changed using the command-line options listed, which correspond to the options presented in the installer. The list below consists of the most commonly recommended options.

Update option	Corresponding EWUpdate command-line option	Description
Backup database data using OS-level backup	-k,--skiposlevel	This command only applies if the built-in MySQL server is used. Under normal circumstances a full OS-level backup is made. Use this option to skip the default OS-level backup of the MySQL directory. No database restoration is possible if the upgrade fails.
Skip checkers unless any patchers were run	-p,--scup	When the application server starts, it performs data checks for consistency, which might take a long time. Use this option to skip data checking if no data was changed on update. This can speed the time taken to start the application server.
Skip project backup if possible	-K,--skipprjbckp	At the very beginning of the update process all existing projects are saved to the backup directory. If this option is set then no project backup is performed, if allowed. Some update modes require a project backup, in which case it isn't skipped.
Don't delete temporary files after update	-t,--keeptemp	During the update, temporary files are normally stored on the hard drive. These may include data backups, unpacked new code, etc. By default, temporary files are removed after an update. If this option is set, temporary files are left on the device. The temporary files are automatically deleted before the next update.
Don't backup temporary files - logs etc	-i,--backuptemp	If this option is set then no temporary files such as log files are backed up before the update. This saves used disk space and shortens the update time.

For additional update options, use the –help command to print a full list of commands.

Example: ewupdate --stable
 -s,--stable             Download stable release version (Offical Release)
 -d,--devel              Download development version (Alpha)
 -C,--custom <host>      Download from custom server
 -F,--file <file>        Upgrade from a distribution that has already been downloaded to the local hard drive
 -f,--force              Unattended update, all prompts are answered 'yes'
 -c,--caution            Unattended update, all prompts are answered 'no'
 -k,--skiposlevel        Skip OS level backup (avoid using this when skipping project backup)
 -K,--skipprjbckp        Skip project backups (avoid using this when skipping OS level backup)
 -t,--keeptemp           Keep temp files
 -p,--scup               Skip checkers unless patchers were run
 -i,--backuptemp         Backup temporary files such as logs (when unattended mode)
 -r,--requiredspace <Gb>   Disk space (Gb) required for update (use with care)
 -w,--warn <MMM or MMM:NNN>  Displays a warning message to customers about an impending update. Argument syntax is MMM or MMM:NNN, where MMM is the number of minutes before update and NNN is the estimated update duration in minutes
 -A,--allowsameversion   Do update even if new version is same as old one
 -X,--forceincompat      Forces an upgrade between releases that should not be compatible. Do not use this option.
 -v,--verbose            Print error details
 -h,--help               Prints this help

Rolling Back

If the upgrade fails, the system automatically troubleshoots problems and applies the proper fixes. If the upgrade still fails, the system prompts the user for input before rolling back to the pre-update version. All your settings are retained, and the logs are copied to <Agiloft-Home>\logs\ so you can use them to trace the cause of the failure and resolve it before trying the upgrade again.

If the upgrade still fails, and you did not create a backup using the upgrade installer, roll back your system using the snapshot or backup you created separately.

Upgrades to Agiloft Hosted Servers

Agiloft regularly updates hosted servers based on this schedule in the Agiloft Community.

Frequently Asked Questions

Can dedicated servers permanently opt out of wave-based automatic server upgrades?

We recommend that you upgrade to the most recent version of the product to benefit from the latest features, enhancements, and bug fixes. We send an upgrade notification email with the product release notes, server upgrade dates, and other specifics. Unless you submit a support ticket at least two business days in advance of the notified upgrade date to opt-out or reschedule, we go ahead with upgrading the servers.

Our server upgrade opt-out policy is applicable per release, and requests to opt out must be sent after release availability is announced through an email. There is no permanent opt-out option.

How can dedicated servers sign up for a monthly maintenance release?

Submit a one-time support ticket to opt-in for monthly maintenance releases on a dedicated server.

Or, if you want to receive the bug fixes for a particular release but not necessary receive the upgrade every month, you can submit an ad-hoc server upgrade request through a support ticket.

I only have one dedicated server, but I want to test this release ahead of upgrading my dedicated production server. What are my options?

We provide a cost-effective option to those with one dedicated server to have their test KB hosted on a shared server. Alternatively, you can purchase a separate dedicated server for testing purposes. Since running a server has an operating cost, we are unable to provide a free test KB hosting option on beta servers.

Please contact your Customer Success Manager or Account Executive to explore the options.

Page tree

Upgrade Guide