Contents
|
|  |
Backup First!
Before doing a re-installation or upgrade of the Tachyon Server, make a backup of the following (but first see the note below about automatic backups):
TachyonMaster database
Backing up the Tachyon Responses database is not usually needed, unless there are instruction responses that you need to keep. Tachyon responses are not permanently held data and will naturally expire according to the settings specified when an instruction was run, typically in hours or possibly days. If in doubt, there is no harm in backing up the Tachyon Responses database as well.
- Tachyon Server installation directory
- including the config files, which may have been manually updated in the previous installation
- Switch certificate files
Earlier versions of Product Packs that have been modified
You will not be able to load pre-3.1 Product Packs into Tachyon 5.0. From version 3.1 onwards, Product Packs completely changed both in format and licensing.
Product Packs from version 3.1 onwards can be loaded directly into Tachyon 5.0.
If the upgrade is done by means of the Tachyon Setup application, then it will automatically perform a backup of the following:
- TachyonMaster database. This is backed up to the default location for backups that is configured in the database server. By default, this points to a subfolder named "Backups" under the folder where the executable for SQL Server is installed. Unless you are installing a small lab or proof-of-concept, this is usually not a good location for the backups, so make sure that you configure the backup location in SQL Server to an adequate folder before starting the Tachyon upgrade.
- Tachyon Server installation directory. This is backed up to a subfolder named Tachyon.bak under the root installation folder for Tachyon. All files, including the .config files and certificate files, will be copied.
- IIS configuration. This is done by taking a copy of the applicationhost.config file from the Windows system folders. The backup file is placed at the same location, and is named like the original file with a suffix that indicates the date and time when the copy was taken.
The Product packs are not copied by themselves, but they are kept in a table within the TachyonMaster database, which is backed-up.
Partial Upgrades
Before version 4.1, if you tried to run Tachyon Setup when any of the products were already installed and their versions did not allow an update to the new versions provided with the installer, then you were shown an error message and installation was blocked unless you uninstalled the conflicting versions. This effectively prevented any components from being upgraded unless all of them could be upgraded.
For version 4.1 and later, this behavior has been modified. For instance, you could be upgrading a combination of Tachyon v4.1 and 1E Catalog v1.2 to Tachyon v5.0 and 1E Catalog v1.2. Note how the 1E Catalog version is unchanged – this would have blocked the upgrade in earlier versions. In the current version it is possible to perform this upgrade. You will see a warning message in the Welcome screen informing you of the affected version numbers, but you can proceed through the Setup steps until you reach the Ready to Install stage. Here you will once again see a warning message indicating that the existing version is the same that you are trying to install, and therefore the installation of this component will be skipped. You can safely click on the button to proceed with installation and everything will be done as expected.
You may still be asked at some intermediate steps about configuration information for the components that will not be installed. You should still provide it, because it may be relevant for Tachyon Setup at the time of configuring other components that are being installed so that they can interact with the components that are not being installed but are already present in the system.
The following process is used when upgrading Tachyon Server from Tachyon 3.x or 4.x to Tachyon 5.0 and keeping the same configuration and the TachyonMaster database.
Keeping the same configuration means using the same installer properties as the previous installation. If changing the configuration, please refer below to Changing the Tachyon Server configuration when re-installing or upgrading.
| Ref | Step | Notes |
|---|---|---|
| 1 | Ensure you have prerequisites ready for installation of the new version.
Review Known Issues for Upgrades. | Preparation for an in-place upgrade is not as complex compared to a new installation, provided the configuration remains the same. If changing the configuration, please refer below to Changing the Tachyon Server configuration when re-installing or upgrading. Determine if you will re-use the existing Web certificate or a new one. If re-using the certificate then ensure you make a copy of the certificate files in the Switch SSL folder. If using a new certificate then follow the guidance in Server Provisioning. If in doubt about your configuration review each of the configuration in the Tachyon installation folder. A later step in this process asks you to make a backup copy of the installation folder. This allows you to review configuration settings and also retain a backup of the Switch certificate files. 1E recommends using the same server installation account as the original installation, but this is not mandatory provided the account is an existing Tachyon administrator user. You can check which is the original installation account by looking in the Permissions page and finding the user which does not have an edit or delete icon. You can carry on with the same license file if both of the following:
You will need a new license file if either of the following:
|
| 2 | Inform Tachyon users when you plan to upgrade the system. | You should notify Tachyon users about the impending upgrade. This includes users of external consumers such as the extension described in Using Tachyon in Configuration Manager. To help identify the users of the Tachyon system you can review the Tachyon Permissions. You can also review the Tachyon Consumers in order to remind yourself of any 3rd party systems that will be affected by the upgrade. Any instructions that are running or pending approval prior to the Platform and Agent upgrade will not be affected, other than be delayed by services being temporarily down. |
| 3 | Shutdown the existing Tachyon system.
| If you want to keep any instruction responses, review the notes in the next step before shutting down the system. Shutting down the system gracefully ensures there are no instructions in process and prevents access. The installer will internally shutdown the services if you do not stop them manually. Stopping them manually gives you a greater control about when they are stopped. The services will be restarted automatically after the upgrade. Both the Tachyon Switch Host and the Coordinator can take some time stopping their services. Do not stop or disable the Tachyon website or application pools. The installer needs them to be active in order to complete all installation tasks. |
| 4 | Close all active connections to the Tachyon databases. | To avoid a particular known issue when upgrading you must ensure there are no active connections to the databases. You can use the following SQL script to identify which programs have active connections to the Tachyon databases. SELECT DB_NAME(dbid) as [database], loginame, hostname, program_name FROM sys.sysprocesses WHERE DB_NAME(dbid) LIKE 'Tachyon%' AND program_name LIKE 'Tachyon%' ORDER BY DB_NAME(dbid), loginame, hostname, program_name; You should track down each item on the list, which will largely consist of the Tachyon services and websites, and stop them. You will be able to safely continue with the upgrade process when this script returns no rows. |
| 5 | Backup the Tachyon Master database. | In most cases the Tachyon Master database is the only one that needs to be backed up. The following notes apply to the Responses database and whether you would need to create a backup of that database too: Backing up the Tachyon Responses database is not usually needed, unless there are instruction responses that you need to keep. Tachyon responses are not permanently held data and will naturally expire according to the settings specified when an instruction was run, typically in hours or possibly days. If in doubt, there is no harm in backing up the Tachyon Responses database as well. |
| 6 | Make a copy of the Tachyon Server installation folder. | The installation folder contains the following non-default files:
|
| 7 | Install Tachyon Server. | Install Tachyon Server using the same configuration as before. Do not drop the databases. Please refer to Tachyon Setup for more details. |
| 8 | Post-install tasks. | Repeat any Tachyon Server post-installation tasks that are relevant for an upgrade installation and are not performed automatically by Tachyon Setup. |
| 9 | Customizations. | Re-instate non-default settings.
|
| 10 | Verify. | See Verifying page. |
Changing Tachyon Server configuration when reinstalling or upgrading
Keep the DNS Names
Each server that has Tachyon platform components installed requires its own DNS Name.
Master Stack | The Master Stack is used by the following, therefore it helps users if it has a recognizable and convenient DNS Name such as tachyon - this is specified during installation of the Tachyon Server using Tachyon Setup.
Platform services also reside on the Master Stack, which non-Tachyon clients connect to, for example:
|
DMZ Server | The DMZ Server is a type of Response Stack used to provide Tachyon Real-time and Inventory services to Internet-based clients. It requires an external DNS Name - for example tachyonext - this is specified during installation of the DMZ Server using Tachyon Setup. The DNS Name is shared between the Switch network interfaces and Background Channel on the DMZ Server, and specified during installation of Tachyon clients, and stored in their configuration file. |
Response Stack | A Response Stack is used to provide Tachyon Real-time and Inventory services to clients on the internal (corporate) network. The choice of DNS Name is discussed in the table below. The DNS Name is shared between the Switch network interfaces and Background Channel on the Response Stack, and specified during installation of Tachyon clients, and stored in their configuration file. |
The number of DNS Names used by a system depend on the location of Tachyon and other Platform services. The table below describes options.
Single DNS Name | A Tachyon system can have a single DNS Name if all components are installed on the same server, for example tachyon - this is specified during installation of the Tachyon Server using Tachyon Setup. If the server has multiple Switches, and therefore multiple network interfaces, then the same DNS Name can be shared by all Switches, the Background Channel and Master Stack. If ActiveEfficiency Server is installed, it can share the same DNS Name provided the server supports less than 5,000 clients. ActiveEfficiency requires its own network interface and DNS Name if the server supports more than 5,000 clients, as described under |
Multiple client-facing DNS Names | Master and Response Stacks must have different DNS Names if they exist on different servers:
When a Response Stack is installed on the same server as the Master Stack, it will normally share the same DNS Name as the Master Stack as described under Single DNS Name above. However, if you have multiple Response Stacks and want them to share the same DNS Name, then the Master Stack must use a different DNS Name. This approach of all Response Stacks sharing the same DNS Name simplifies adding further Response Stacks at a later date. Only one client-facing DNS Name can be specified during installation, other HTTPS bindings are added manually after installation. If Master and Response Stack are on the same server and you want them to have different DNS Names, then specify the DNS Name for the Response Stack during installation, and manually add the HTTPS binding for the Response Stack after installation. You will need to seek guidance from 1E on how to configure Switches to use the second DNS Name. A simpler option is to put the Response Stack on its own server. Remote Response Stacks are recommended if the Master Stack is also hosting services for ActiveEfficiency Server, AppClarity Software Reclaimer or Application Migration. You can optionally have additional DNS Name(s) on the Master Stack server for other services such as ActiveEfficiency Server, AppClarity Software Reclaimer and Application Migration. These bindings would be added manually after installation, and do not require any further complex configuration. ActiveEfficiency Server requires its own network interface and DNS Name if it is installed on the same server as a Response Stack and supports more than 5,000 clients:
|
Internal DNS Names | A DMZ Server is a special example of a Response Stack. The DMZ Server itself requires two DNS Names:
Both DNS Names must be included in the web server certificate. The Response Stack also requires an additional DNS Name - for example tachyonalt - for internal communications with the DMZ Server. Please refer to Implementing a Tachyon DMZ Server for more detail about DMZ Servers. |
Tachyon Setup supports installation of one HTTP and one HTTPS binding, but you can manually add more bindings after installation. HTTPS bindings can share a web server certificate provided it includes all DNS Names, or each HTTPS binding can have its own certificate.
Each DNS Name used to access a Tachyon Server must be included as a DNS Name in the Subject Alternate Name (SAN) entry of the web server certificate, and the Switch certificate files.
A DNS Name can be a DNS alias, CNAME or Host (A) record.
Moving Server
Agents use the DNS Name FQDN to connect to the Switch and Background Channel. Provided the DNS Name FQDN remains the same, the server can be renamed or moved without having to re-configure clients.
If the server hosting a Tachyon Server is renamed or moved, then it will need a new certificate and Tachyon Server must be re-installed. The database can be kept. There is also a known issue where new website URLs do not get updated in the database tables.
Please contact 1E for advice if a new configuration is required when re-installing or upgrading a server.
Upgrading Instructions and Product Packs
Tachyon Instructions are designed as far as possible to be backwards compatible, but as a general rule we recommend that you update your Tachyon product packs to the latest version so that you can gain the benefit of newer features.
When upgrading you should be able to safely continue to use your existing Instructions. We recommend that newer versions of Instructions are verified in a test environment to ensure that they still behave as expected before updating in your production environment.
Your Tachyon license should retain any code signing certificates you may have registered. This means your custom instructions should continue to be licensed as normal following an upgrade of Tachyon. You may want to check the Writing Tachyon Instructions in the Tachyon SDK pages to check for any changes to the Tachyon SCALE language.
Moving Switch certificate files to the Windows Certificate Store
Prior to version 5.0, the Switch component used certificate files located on disk. From version 5.0 onward, the Switch uses certificates in the Windows Certificate Store. When upgrading, you might still be using file-based certificates that don't exist in the certificate store. This is more likely if your server certificate (used for IIS components) is different to the certificate your switch (or switches) present. This certificate needs to be imported into the certificate store:
If you don't have a .pfx file, you can assemble one from the existing switch certificate files and OpenSSL. If you do, skip this step:
openssl pkcs12 -export -out <outPfxFilePath> -inkey <keyFilePath> -in <cerFilePath> //example: openssl pkcs12 -export -out c:\mycerts\mypfx.pfx -inkey c:\mycerts\hello.cer -in c:\mycerts\hello.key
Import it into the Local Machine's Personal certificate store. This can also be done though mmc:
certutil -f -p <pfxPassword> -importpfx <pfxFilePath> //example: certutil -f -p Password -importpfx c:\mycerts\mypfx.pfx
In Tachyon.Setup, select the certificate when it appears on the Server Certificate screen:
This will set both the server (IIS) certificate and the Switch certificate. If your switch needs to use a different certificate, modify the Tachyon.Switch.Host.exe.config.
Upgrading devices to 1E Client 5.0
The following sub-headings are excerpts from the 1E Client 5.0 documentation. The links in the excerpts will also navigate to that documentation space.
Upgrading Tachyon Agent on Windows
Installer properties are described in 1E Client configuration settings and installer properties. You can perform the upgrade on Windows computers by following the same process as Deploying 1E Client on Windows.
The following is important if you are upgrading Tachyon Agents from version 3.2 or earlier to version 3.3 or later, or to 1E Client.
Each Tachyon Agent determines a unique identifier (GUID) for the device that they run on. From Tachyon version 3.3 the way that the identifiers are determined has changed to be consistent with other 1E products. As a result, when upgrading the Tachyon Agents from version 3.2 or earlier to version 3.3 or later, Tachyon will create new Tachyon Agent entries on the Tachyon Server and will not remove the old Tachyon Agent entries. The old Tachyon Agent entries will appear in Tachyon Explorer as offline, and upgraded Agents will appear as duplicates and online. The old Agents will naturally disappear according to the inactive days setting. It may be the case that Tachyon will temporarily indicate that your license has been exceeded, because of the duplicate Agents, but in this instance the indication may safely be ignored.
You can do either of the following:
- Allow the offline Agent device entries to naturally disappear after the defined number of days from the day they were upgraded. For Tachyon 5.0 and earlier the default is 90 days. For Tachyon 5.1 and later the default is 99.
Reduce the number of days by editing the
RemoveDeviceAfterInactiveDaysvalue inC:\Program Files\1E\Tachyon\Coordinator\Tachyon.Server.Coordinator.exe.configthen restart the1E Tachyon Coordinatorservice. You will then only need to wait for the changed days before the offline devices disappear. This will also make devices that are inactive for any other reason disappear sooner.When you have completed your Tachyon Agent upgrade deployment then you must change this back to the default.
These options will not have any effect on a device's ability to receive and run instructions when it is next online.
Upgrading Tachyon Agent on macOS computers
For macOS, Tachyon Agents can be upgraded by re-running the installation of the new package, as described in the Deploying 1E Client on macOS.
Upgrading Tachyon Agent on other non-Windows devices
Upgrades for non-Windows Tachyon Agents, other than the Mac version, are not directly supported. You must first uninstall the Tachyon Agent and then install the 1E Client:
- Deploying 1E Client on non-Windows: Uninstalling 1E Client
- Deploying 1E Client on non-Windows: Deploying on non-Windows platforms
Backup first!
Before uninstallation of a non-Windows Tachyon Agent, make a backup of the following:
- Log files
- Persistent storage files
- Tachyon.Agent.conf
- Keep a copy of this file if you have made post-installation modifications that need to be re-applied post-upgrade. These will have to be merged with the new 1E.Client.conf file laid down during installation
- The Tachyon Agent SSL certificate files:
- Copy the cacert.pem and Tachyon.pfx files to a secure location prior to uninstallation so that they can be moved back to their previous locations after installing the new 1E Client.
File Locations
| Directory | Tachyon Agent | 1E Client |
|---|---|---|
| /etc/1E/Tachyon/Agent/.sslcerts | cacert.pem Tachyon.pfx | cacert.pem Tachyon.pfx |
| /etc/1E/Tachyon/Agent/DBs | Inventory.dat | Inventory.dat |
| /etc/1E/Tachyon/Agent | Tachyon.Agent.conf | 1E.Client.conf |
| /etc/1E/Tachyon/Agent/Persist | * | * |
/var/log/1E/Tachyon | Tachyon.Agent.log | 1E.Client.log |