Home / Knowledge base / 3. INTERACTING WITH A REPSTANCE SERVER

INTERACTING WITH A REPSTANCE SERVER

There are three possible ways to engage with a running Repstance Server Instance, they are, either via the Command Line Interface (CLI) or via the Rest API or via Web User Interface (Web UI).

3.1 Command Line Interface (CLI)

The Repstance Command Line Interface utility (repcli) is the interface with the Repstance server, and it is used to configure and manage the server as well as providing a reporting mechanism.

The repcli utility can be invoked directly within this environment, and the user can start to configure Processes without the need for any further configuration.

Use SSH protocol to connect to the Repstance Server and run the repcli command:

$ repcli
$ repcli>help

Commands:
 alter         This command is used to change both the Capture and Apply process parameters
 clear         Clear The Screen
 exit          Exit The Program
 help          Display Help

etc.

The repcli utility can be configured to communicate with remote Repstance Server using the HTTPS protocol (see chapter 3.1.3 Configure repcli for Remote Access).

The repcli utility can operate in two modes either “Command Mode” or “Fully Interactive Mode“. The two different ways of using Repstance have been developed to provide alternate methods of controlling the product.

If repcli is executed without any parameters it starts functioning in “Fully Interactive Mode”, by default, which means that it will wait for an input command, until user issues the “exit” command at which point it returns to the console.

The “Fully Interactive Mode” is useful for a user to construct and/or configure Repstance, as it provides, at each stage of the process construction, a list of the possible commands and their applicable parameters, see the “Visuals” below.

“Command mode” is more likely to be used when there is a need to “Embed” Repstance functions into a deployment Script for Automation processes within the user’s own environment.

3.1.1 Fully Interactive Mode

This is the utility’s default behavior. As the user starts to provide a command for any Repstance Process and then “presses” the “Tab” key, repcli utility will supply the user with the expected possible parameters.

The following example shows the repcli interface displaying the list of all possible commands:

repcli>
status   exit   help   prepare   remove   alter   reset   clear    validate   show    run    stop

This example shows all commands starting with “s”:

repcli>s
status   show   stop

And the next one shows all the possible parameters for the “alter” command:

repcli>alter process=capture id=1
server=   port=   user=   password=   dbname=   name=   autostart=   debuglevel=    ddlinclude=    ddlexclude=    dmlinclude=   dmlexclude=   map=

The repcli has built-in help facility, which can be invoked to provide detailed “Help” for each of the commands, and is shown below:

repcli>alter help

This command is used to change the Capture or Apply process parameters.

The Syntax is:

alter process=capture|apply id=processID [parameter=value, ...]

Note: The 'id' parameter can not be changed.

The 'name' parameter for a Capture process as well as the 'capturename' parameter for an Apply process can be changed only in the case that it has not been provided before - eg. it must be “Unique”.

The process has to exist otherwise the command will fail.

To see available possible parameters, start to use the command.

3.1.2 Command Mode

This is the basic interface format, when used in this mode it will simply supply the result of the process defined and return to the console prompt:

$repcli status process=capture
  Capture Process 1, Name: czdt, DB: zdt, Server: source.repstance.com
  RUN (In Process), Waiting for Transactions
  Last Source DB Change : 2019/02/15 15:47:00.410 UTC (0x000006830000319C0004)
  Last Captured DB Change  :  2019/02/15 15:47:00.410 UTC (0x000006830000319C0004)
  Total since  2019/02/25 13:30:00.973 UTC (0x00000683000025750004):
  Processing the Transactions :  00:00:58.505
  Waiting for Transactions    :  00:45:22.859
  Average Speed (ops)   :  4.683
  Transactions: 274 (DDL: 0,  Delete: 137,  Insert: 137,  Update: 0)
  Capture Process 2, Name: newcap, DB: mydb, Server: local
  RUN (Failed), Waiting for the Next Command, [lookup local: no such host]
$

3.1.3 Configure repcli for Remote Access

The repcli tool can be used as standalone application to manage remote Repstance Server through the HTTPS protocol.

The tool can be found in the following directories, once the product is installed:

/opt/repstance/cli/macos – For MacOS Operating System
/opt/repstance/cli/win – For Windows
/opt/repstance/cli/linux – For Linux

Or they can be downloaded from here:

These remote clients are only able to connect using the HTTPS protocol and are supplied with the following default configuration:

HTTPS port is 8797
For HTTPS initial use a Self-Signed Certificate is provided
HTTPS authorisation “Token” in the form of the Repstance AWS Instance ID

In order to use the repcli utility to communicate with the remote Repstance Server it has to be configured using the repcli command “configure”.

The following example demonstrates the command syntax:

$ repcli configure url=https://hostname:8797/ token=aws-instance-id verifyhttps=0

Note – The verifyhttps parameter should be set to 0 to avoid the Self-signed certificate error.

As the product is initially supplied with a Self-Signed Certificate it is highly recommended that the user replaces this with a security certificate of the required Security level themselves. The new certificate and key needs to be supplied to the Repstance Server and the appropriate entries in the /opt/repstance/conf/repstance.conf file need to be edited to reflect these changes:

key – path to the key
crt – path to the certificate

Using this method, the default HTTPS port can also be changed by modifying the port parameter.

The default token used to access the server can also be changed by modifying the token parameter in the same file.

If the user wishes to prevent any external access, the port parameter should be set to value 0.

3.2 Web User Interface (Web UI)

Repstance Instance is delivered with Web UI Server, which allows to configure, manage and monitor Repstance Processes using a Web browser.

By default, Web UI Server is configured to use HTTPS protocol through the ports number 3000 and 8797, so these ports must be accessible from the client machine.

The Web UI Server is initially supplied with a Self-Signed Certificate it is highly recommended that the user replaces this with a security certificate of the required Security level themselves. The new certificate and key needs to be supplied to the Repstance Server and the appropriate entries in the /opt/repstance/conf/repstance.conf file need to be edited to reflect these changes:

key – path to the key
crt – path to the certificate

Using this method, the default HTTPS port can also be changed by modifying the port parameter.

After successful deployment of Repstance instance find its Public DNS. If the Public DNS is not configured, use the Private IP address.

To enter Repstance Web UI, use your web browser to access to the following address:

https://<Public DNS or Private IP>:3000

Use “repstance” as username. The default password in the AWS environment is the Instance ID and the VM Id in the Azure cloud. The password can also be found and changed in the /opt/repstance/conf/repstance.conf file (see “token” section).

3.3 REST API

This is the detailed command structure for communicating with Repstance Services, it sends an HTTP/HTTPS request in the “JSON Format” to the services and adheres to the established protocols for the JSON format. List of the available Repstance commands and their specification is provided in chapter 7. Commands to be used.

The following example demonstrates how to use REST API to call “status” command:

$curl --header "Content-Type: application/json" \
--request POST \
--data '{"command": "status"}' http://localhost:8796/control/process

2. GETTING STARTED WITH REPSTANCE IN AWS

4. SUPPORTED DATABASE REQUIREMENTS