Installing an Agent to create a clone
Published 09 F 2017
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
Troubleshooting the install
- "An existing connection was forcibly closed by the remote host" error
- "Could not load file or assembly 'RedGate.SqlClone.Unmanaged.dll' or one of its dependencies" error
- Agent communication problems during install configuration
- An agent doesn't work after using the SERVERURL command line flag during installation ('unauthorized received from server')
- Could not execute "...VCRedist2017": Installation error 1 when running
- Error 1603 Service ... could not be installed. Verify that you have sufficient privileges to install system services.
- Error 1923. Service ... could not be installed. Verify that you have sufficient privileges to install system services.
- Problems during configuration wizard
- Security alert during SQL Clone update