Upgrading from AnyCAGateway DCOM Version 20.x or Later

If you are upgrading from a version of the AnyCAGateway DCOM that already makes use of a SQL database, follow these upgrade instructions.

Important:  If you are installing the AnyCAGateway DCOM in a clustered environment, please refer to the section on Configure the Keyfactor AnyCA Gateway DCOM with Clustering (Optional) before proceeding.
Note:  You may choose to configure Windows authentication or SQL authentication. The instructions for each are included.

Upgrade the gateway as follows:

  1. Perform this pre-requisite check before upgrading.

    • Run this SQL command:

      SELECT CARequestID, COUNT(CARequestID) FROM Certificates GROUP BY CARequestID HAVING COUNT(CARequestID) > 1

    • If it returns results, find the duplicate records by running:

      SELECT * FROM Certificates WHERE CARequestID=<insert the id returned above>

    • Determine the record to delete (usually an expired or revoked certificate) and delete it:

      DELETE FROM Certificates WHERE Id = <Id>
  2. Do not uninstall the old gateway. Install the new gateway over the old gateway.

  3. Update the database using the DatabaseManagementConsole.exe upgrade command.

    To update the AnyCAGateway DCOM database, from the command line at the installation directory execute a command similar to:

    .\DatabaseManagementConsole.exe upgrade --server <Database-Server>\<SQL-Instance>,<Port> --database <Database>

    For example, to update the database using the default instance and port (using appropriate values for the server name and database name):

    .\DatabaseManagementConsole.exe upgrade --server sqlsrvr.keyexample.com --database CAGateway

    For example, to update the database using a custom instance and port (using appropriate values for the server name, database name, instance name, and port):

    .\DatabaseManagementConsole.exe upgrade --server sqlsrvr.keyexample.com\MyInstance,1434 --database CAGateway

    For example, to update the database using the default instance and port and SQL authentication (using appropriate values for the server name, database name, username, and password):

    .\DatabaseManagementConsole.exe upgrade --server sqlsrvr.keyexample.com --database CAGateway --username MySQLUser --password MySecurePassword

    See Overview of the Database Management Console for more information on the parameters available for updating the AnyCAGateway DCOM SQL database.

    Tip:  You have the option to provide the parameters (e.g. server and database values) in a JSON configuration file or via environment variable, if desired, rather than with command-line flags. See Overview of the Database Management Console.
Tip:  If you want to change the configuration for any reason, use the cmdlets as follows:

  1. Import the PowerShell configuration cmdlets module. The Import-Module command is a standard PowerShell command. The configuration cmdlets DLLs were delivered to the installation directory during installation. This command imports them into the current PowerShell session. You will need to do this anytime you return to the Database Management Console.

    Import-Module ".\ConfigurationCmdlets.dll"

  2. Run the Get-KeyfactorGatewayConfig using the -FilePath parameterClosed A parameter or argument is a value that is passed into a function in an application. value to output the configuration values to a file (see Get-KeyfactorGatewayConfig). For example (using appropriate values for the gateway hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername)., the logical nameClosed The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two)., and the configuration file output path and filename):

    Get-KeyfactorGatewayConfig -CAHostname mygateway.keyexample.com -LogicalName MyGateway -FilePath C:\Temp\AnyGatewayConfigUpdate.json
  3. Edit the outputted values in the JSON file (see Edit the JSON Configuration File).

  4. Run the Set-KeyfactorGatewayConfig cmdlet using the -FilePath parameter value to import the updated configuration values from the JSON file (see Set-KeyfactorGatewayConfig). For example (using appropriate values for the gateway hostname, the logical name, and the configuration file output path and filename):

    Set-KeyfactorGatewayConfig -CAHostname mygateway.keyexample.com -LogicalName MyGateway -FilePath C:\Temp\AnyGatewayConfigUpdate.json

Note that after the first-time configuration, any future re-configurations check the security settings from the JSON file. The user would need to have administrator security for the AnyCAGateway DCOM server in order to make configuration changes (see Security Section).

The configuration can be changed, if necessary, at this point, or in the future.

Note:  Congratulations! You have upgraded your gateway to the latest version of the AnyCAGateway DCOM gateway. You may begin using it as you were previously. See the Optional Configuration.