1. Administrator's Guide
  2. Configure
  3. Configuring Multi-Region Data Stores
  4. Use Case 1: Set up Multi-Region Environment
  5. Start XRegion Service

Start XRegion Service

The Xregion service in each region can be started using the xrstart command. The xrstart command has to be executed for each data store separately. The status of the xrstart command execution can be viewed by reading the contents of status.<number of agents>.<agentId>.txt file which contains the process ID of the successfully started agent. To get more details about xrstart command and its various parameters, see xrstart .

The command xrstart can be used in two ways:
  • The command for starting the Xregion service in the foreground is:
    java -Xms1G -Xmx1G -jar <path to jar file> xrstart -config <path to config file>
  • The command for starting the Xregion service in the background is:
    java -Xms1G -Xmx1G -jar <path to jar file> xrstart -config <path to config file> -bg

Example:

Start the XRegion Service in both the regions, Frankfurt and London.

There are two XRegion Service agents in both the regions, Frankfurt and London. In Frankfurt the XRegion agents are in host1 and host7 and in London, the XRegion agents are in host4 and host8. Both the XRegion agents have to be started in each region. 

# Start the first XRegion Service in host1 in the 'fra' Region
[oracle@host1 xrshome]$ java -Xms256m -Xmx2048m -jar $KVHOME/lib/kvstore.jar xrstart \
-config <path to the json config file> -bg

[1] 24356

# View the status of the xrstart command in host1 in the 'fra' Region
[oracle@host1 xrshome]$ cat status.<number of agents>.<agentId>.txt
Cross-region agent (region=fra,store=mrtstore, helpers=[host1:5000, host2:5000, host3:5000]) 
starts up from config file=/home/oracle/xrshome/ json.config at 2024-04-05 08:57:34 UTC
Similarly start the XRegion agent in host 7.
# Start the second XRegion Service in host 7 in the 'fra' Region

[oracle@host7 xrshome]$ java -Xms256m -Xmx2048m -jar $KVHOME/lib/kvstore.jar xrstart \
-config <path to the json config file> -bg

[1] 24489

 # View the status of the xrstart command in host7 in the 'fra' Region
[oracle@host7 xrshome]$ cat status.<number of agents>.<agentId>.txt
Cross-region agent (region=fra,store=mrtstore, helpers=[host1:5000, host2:5000, host3:5000]) 
starts up from config file=/home/oracle/xrshome/ json.config at 2024-04-05 08:59:34 UTC
# Start the first XRegion Service in host4 in the 'lnd' Region
[oracle@host4 xrshome]$ java -Xms256m -Xmx2048m -jar $KVHOME/lib/kvstore.jar xrstart \ 
-config <path to the json config file> -bg 

[1] 17587

# View the status of the xrstart command in host4 in the 'lnd' Region
[oracle@host4 xrshome]$ cat status.<number of agents>.<agentId>.txt
Cross-region agent (region=lnd,store=mrtstore, helpers=[host4:5000, host5:5000, host6:5000]) 
starts up from config file=/home/oracle/xrshome/ json.config at 2024-04-05 08:57:34 UTC
Similarly start the XRegion agent in host8.
# Start the second XRegion Service in host8 in the 'lnd' Region

[oracle@host8 xrshome]$ java -Xms256m -Xmx2048m -jar $KVHOME/lib/kvstore.jar xrstart \ 
-config <path to the json config file> -bg 

[1] 17587

# View the status of the xrstart command in the 'lnd' Region
[oracle@host8 xrshome]$ cat status.<number of agents>.<agentId>.txt
Cross-region agent (region=lnd,store=mrtstore, helpers=[host4:5000, host5:5000, host6:5000]) 
starts up from config file=/home/oracle/xrshome/ json.config at 2024-04-05 09:09:34 UTC

Status of XRegion Agent

To check the current status of the XRegion Agent, use the command xrstatus. This command provides information on the status as well as the exit codes indicating whether the agent has started, is already running, or has stopped, etc, see xrstatus

The below command will check the status of the agent.
java -Xms256m -Xmx2048m -jar $KVHOME/lib/kvstore.jar xrstatus -config <path to the json config file>
The status can be checked:
  • After starting the agent using the xrstart command.
  • When the agent is already running, to be sure if there was no failure in the connection.
  • After the agent has stopped using the xrstop command.
To view the status of the agent in the form of exit codes, use the command:
echo $?
For example, after starting the agent, check the status of the agent as follows:
# Start the agent
bash-4.4$ java -Xms256m -Xmx2048m -jar ./lib/kvstore.jar xrstart -config <path to the jsonconfig file>

[1] 102148

# View the status of the agent
bash-4.4$ java -Xms256m -Xmx2048m -jar ./lib/kvstore.jar xrstatus -config <path to the json config file>
Agent running

# View the exit code
bash-4.4$ echo $?
0

Running the xrstatus command shows the agent's status and using the echo $? command reveals the exit code corresponding to the agent's status. Look at the table to understand more.

Here are the exit codes and their descriptions for the agent's status after starting, while running, and after stopping:
  1. Agent status after Starting the agent:
    Exit Code Description
    0 The agent has started successfully.
    1 The agent has failed to start.
    2 The agent failed to start with timeout, meaning it started successfully but did not generate a status file with the process ID.
    3 The agent crashed after starting.
    4 The agent is already running and another agent cannot be started.
  2. Agent Status of a running agent:
    Exit Code Description
    0 The agent is currently running.
    1 The agent is currently not running.
    2 The agent has crashed after running for a few seconds.
  3. Agent status after stopping the agent:
    Exit Code Description
    0 The agent has stopped successfully.
    1 The agent has failed to stop.