Installing SQL Clone Agents

Once you have installed SQL Clone Server, you will need to install one or more SQL Clone agents. You will need to install an agent on every machine with SQL Server where the cloned databases will be hosted.

As with any other database, a clone database can only be created on an instance where the SQL Server version is the same or higher than the source image.

The steps to install an Agent to create a Clone are the same as installing the Agent to create an Image.

The SQL Clone agent installed can be downloaded from the home page of the server's web app. You will need to download a separate agent installer file for every agent (SingleUseSqlCloneAgentInstaller.exe), as each executable file contains a unique key that can only be used once.

The agent installer requires a username and password for the agent service. These credentials will also be used to connect to databases if you choose "windows authentication" within the tool.

See Requirements for more information about what permissions the agent user requires.

The agent must be able to connect to SQL Clone Server on port 14146.

Passing parameters to the installer

You can pass parameters to the agent installer's executable SingleUseSQLCloneAgentInstaller.exe to customise your installation.

Key/value parameters are expected to be provided as space-separated key=value keywords without any preceding hyphens or forward slashes (e.g. SERVERURL=PATH and not -SERVERURL=PATH or /SERVERURL=PATH).

Invalid parameters are ignored

If given invalid arguments or in the wrong format, the installer doesn't offer any notification or warning - it simply ignores them during installation. Errors should still be written to the application event log though.

Server URL

You can customise the address that the agent uses to communicate with the server via the SERVERURL parameter. This override can be useful to resolve the correct external server name if you have multiple names or aliases set for the SQL Clone's server machine that may not always be externally accessible to the agent machines.

Clone server has two endpoints running, one for web browsers and other clients to talk to (normally port 14145, and HTTP by default, but both settings are configurable), and a second one reserved for agents (port 14146, and always HTTPS, not configurable).

You need to use the agent endpoint with SERVERURL - e.g. https://mycloneserver:14146.

You can set this on the installer with:

.\SingleUseSQLCloneAgentInstaller.exe SERVERURL=https://mycloneserver:14146

Silent install

SQL Clone agents can also be installed silently. This installation method is suitable for use via command line or with automation.

Single-use agent installers can be downloaded directly from:

http://sql.clone.server:14145/download/agentinstaller

And then silently installed with:

.\SingleUseSQLCloneAgentInstaller.exe -s SERVICEUSERNAME=<domain\service user> SERVICEPASSWORD=<service user's password>

For example, Powershell can download and silently install an agent as follows:

Invoke-WebRequest http://sql.clone.server:14145/download/agentinstaller -OutFile "SingleUseSQLCloneAgentInstaller.exe" -UseDefaultCredentials
.\SingleUseSQLCloneAgentInstaller.exe -s SERVICEUSERNAME=RED-GATE\jordan.miller SERVICEPASSWORD=hunter2

If anything goes wrong, the installer will write to the application event log.

Installing in a VM image

SQL Clone agent tries to register with the server during the installation. If you want to pre-install a SQL Clone agent on a virtual machine image that will then be cloned then you will have to postpone the registration to ensure that each cloned agent registers with its own unique identity.

To postpone agent registration you need to run a silent installation with POSTPONEREGISTRATION=true parameter.

Invoke-WebRequest http://sql.clone.server:14145/download/agentinstaller -OutFile "SingleUseSQLCloneAgentInstaller.exe" -UseDefaultCredentials
.\SingleUseSQLCloneAgentInstaller.exe -s SERVICEUSERNAME=RED-GATE\jordan.miller SERVICEPASSWORD=hunter2 POSTPONEREGISTRATION=true

In order to register an agent afterward, you also need to install the SQL Clone PowerShell cmdlets to the VM image.

Then, as a part of a cloned VM instance initialization you can register the preinstalled Agent by running the following as a local administrator:

Connect-SqlClone http://sql.clone.server:14145/
Start-SqlCloneAgent

SQL Clone 5

Installing an Agent to create a clone

Installing SQL Clone Agents

Passing parameters to the installer

Server URL

Silent install

Installing in a VM image

Troubleshooting the install