Summary

Guidance for upgrading Tachyon.

Upgrading Tachyon Server to version 3.3

Backup First!

Before doing a re-installation or upgrade of the Tachyon Server, make a backup of the following:

  • 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 3.3. 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 3.3.


On this page:

The following process is used when upgrading Tachyon Server from Tachyon 3.0, 3.1 and 3.2 to Tachyon 3.3 and keeping the same configuration and 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.

RefStepNotes
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 are upgrading on the same server
  • The new version is only a minor version upgrade

You will need a new license file if either of the following:

  • You are installing on a different server
  • The new version is a major version upgrade
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.

  1. Stop or uninstall external or third-party Consumers such as Tachyon Security.
  2. Stop the Tachyon services
    • 1E Tachyon Switch Host service
    • 1E Tachyon Coordinator service
  3. Stop the Tachyon website and application pools

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 Tachyon Switch Host service can take some time stopping its services.

4Close 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.

5Backup 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.

6Make a copy of the Tachyon Server installation folder.

The installation folder contains the following non-default files:

  • Switch certificate files in the SSL folder, these are required during the upgrade and should be copied to the directory with the TachyonServer.msi.
  • Configuration files for the website, web applications, services and Switch (*.config files)
  • Other customisations
  • Agent resources in the Background folders (these are the Content and Updates folder in %ALLUSERSPROFILE%\1E\Tachyon)
7Install Tachyon Server.

Install Tachyon Server using the same configuration as before. Do not drop the databases.

Please refer to Tachyon Setup for more details.

8Post-install tasks.

Repeat Tachyon Server post-installation tasks.

9Customisations.

Re-instate non-default settings.

  • Configuration files for the website, web applications, services and Switch (*.config files)
  • Other customisations
  • Agent resources in the Background folders (these are the Content and Updates folder in %ALLUSERSPROFILE%\1E\Tachyon)

Do not simply replace config files. Instead compare the old and new versions and consider which changes can or need to be re-instated. In some cases, new versions may contain fixes for workarounds included in the old files. Please contact 1E for advice.

10Verify.See Verifying page.

Upgrading Windows Tachyon Agents to version 3.3

You can upgrade Tachyon Agent from earlier versions of Tachyon. Installer properties are described in Tachyon Agent installer and configuration properties. You can perform the upgrade by following the same process as deploying the Tachyon Agent.

The following is important if you are upgrading Tachyon Agents from version 3.2 or earlier to version 3.3 or later.

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. The default is 90 days.
  • Reduce the number of days by editing the  RemoveDeviceAfterInactiveDays value in  C:\Program Files\1E\Tachyon\Coordinator\Tachyon.Server.Coordinator.exe.config  then restart the 1E Tachyon Coordinator service. 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 you can change this back to the default.

These options will not have any affect on a device's ability to receive and run instructions when it is next online.

Upgrading Mac Tachyon Agents to version 3.3

For Mac Tachyon Agents the upgrade can be done by simply re-running the Mac installation of the new package, as described in the Mac installation heading on the Deploying Tachyon Agents page.

Upgrading other non-Windows Tachyon Agents to version 3.3

Upgrades for non-Windows Tachyon Agents, other than the Mac version, are not directly supported. You must first uninstall the old version and then install the new version.

Backup first!

Before doing a re-installation 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 Tachyon.Agent.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 Tachyon Agent.

File Locations

DirectoryFile

/etc/1E/Tachyon/Agent/.sslcerts

/Library/Application Support/1E/Tachyon/Agent/.sslcerts [Mac]

cacert.pem

Tachyon.pfx

/etc/1E/Tachyon/Agent/DBs

/Library/Application Support/1E/Tachyon/Agent/DBs [Mac]

Inventory.dat

/etc/1E/Tachyon/Agent

/Library/Application Support/1E/Tachyon/Agent [Mac]

Tachyon.Agent.conf

/etc/1E/Tachyon/Agent/Persist

/Library/Application Support/1E/Tachyon/Agent/Persist [Mac]

*

/var/log/1E/Tachyon

/Library/Logs [Mac]

Tachyon.Agent.log

Changing Tachyon configuration when reinstalling or upgrading

At this time 1E recommends the same server configuration is applied when reinstalling (i.e. uninstall then reinstall) or upgrading the Server.

Adding new Tachyon servers to the system 

Each server that has Tachyon Server components installed requires its own DNS Name. The Master Stack enables Tachyon users, approvers and administrators to connect to the Explorer and Admin portals, therefore, it helps users if it has a recognizable and convenient DNS Name such as tachyon.

Tachyon Agents need to connect to Switches and the Background Channel using a DNS Name FQDN defined in the Agent's configuration file. A single-server installation only needs one DNS Name. A Master Stack and Response Stack can only share the same DNS Name if both are installed on the same server. 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.

The same DNS Name would be used by all the Switches on a Response Stack, but it can also be shared across multiple Response Stacks provided the Name is not also shared with the Master Stack. For this reason, a datacenter serving more than 300000 devices would have two Response Stack servers using the same DNS Name (eg. tachyonrs), and a dedicated Master Stack server using a different DNS Name (eg. tachyon).

A DMZ Server is a special case which needs two DNS Names, an internal DNS Name for the internal network interface, and an external facing DNS Name which may be shared by multiple external facing Switch network interfaces.

Each DNS Name used to access a Tachyon Server must be included as DNS Names in the Subject Alternate Name (SAN) entry of the web server certificate, and the Switch certificate files.

Moving or changing the server's computername

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 Agents.

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 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 Agent language.