Details TOP Build

Usage

After building CHMPX, you can check the operation by the following procedure.

1. Sample Configuration

The following is the configuration used for CHMPX test. please refer.

1.1 For server node.

1.2 For slave node

2. Operation check

2.1 Creating a usage environment

There are two ways to install CHMPX in your environment.
One is to download and install the package of CHMPX from packagecloud.io.
The other way is to build and install CHMPX from source code yourself.
These methods are described below.

Installing packages

The CHMPX publishes packages in packagecloud.io - AntPickax stable repository so that anyone can use it.
The package of the CHMPX is released in the form of Debian package, RPM package.
Since the installation method differs depending on your OS, please check the following procedure and install it.

For recent Debian-based Linux distributions users, follow the steps below:
$ sudo apt-get update -y
$ sudo apt-get install curl -y
$ curl -s https://packagecloud.io/install/repositories/antpickax/stable/script.deb.sh | sudo bash
$ sudo apt-get install chmpx

To install the developer package, please install the following package.

$ sudo apt-get install chmpx-dev
For users who use supported Fedora other than latest version, follow the steps below:
$ sudo dnf makecache
$ sudo dnf install curl -y
$ curl -s https://packagecloud.io/install/repositories/antpickax/stable/script.rpm.sh | sudo bash
$ sudo dnf install chmpx

To install the developer package, please install the following package.

$ sudo dnf install chmpx-devel
For other recent RPM-based Linux distributions users, follow the steps below:
$ sudo yum makecache
$ sudo yum install curl -y
$ curl -s https://packagecloud.io/install/repositories/antpickax/stable/script.rpm.sh | sudo bash
$ sudo yum install chmpx

To install the developer package, please install the following package.

$ sudo yum install chmpx-devel
Other OS

If you are not using the above OS, packages are not prepared and can not be installed directly.
In this case, build from the source code described below and install it.

Build and install from source code

For details on how to build and install CHMPX from source code, please see Build.

2.2 Run CHMPX for server node

$ chmpx -conf test_server.ini

2.3 Run server program(chmpxbench server mode) which joins server node CHMPX

$ chmpxbench -s -conf test_server.ini -l 0 -proccnt 1 -threadcnt 1 -ta -dl 128 -pr -g err -dummykey TEST

2.4 Run CHMPX for slave node

$ chmpx -conf test_slave.ini

2.5 Run client program(chmpxbench client mode) which joins slave node CHMPX

$ chmpxbench -c -conf test_slave.ini -l 1 -proccnt 1 -threadcnt 1 -ta -dl 128 -pr -g err -dummykey TEST

If there is no error with the above operation, there is no problem.

3. Exit all programs

Send signal HUP to all programs (chmpx, chmpxbench), and it will exit automatically.

4. CHMPX control command

CHMPX is started by specifying the control port which is for controlling the CHMPX process itself and CHMPX server nodes on RING.
By connecting to this control port and sending control command, you can manage and confirm status for CHMPX process and CHMPX server nodes on RING. Control commands can be roughly divided into commands that control the CHMPX process itself that receives the commands and commands that control the CHMPX server nodes (RING) on the RING. You can use these control commands to check and change the status of CHMPX server nodes on RING and also to check and change the status of the CHMPX process itself.

We recommend not using the control command directly via this control port, but using chmpxlinetool which is easy to use.

4.1 How to use

There is an item of CTLPORT in the configuration(file or JSON string) for starting the CHMPX program.
You must specify a control port for this CTLPORT. You can connect to this control port and send control commands as a string to the CHMPX process. The CHMPX process receives a control command and processes and responds according to that command. Please note that we currently do not support SSL encryption for connection and communication with the control port. (It will be supported in the future)

4.2 About access to control port

Access to the control port is possible only for the server node and the slave node specified in the configuration (file or JSON string).

4.3 Control command (effective for CHMPX process only)

VERSION

This command returns the version of the CHMPX process.

SELFSTATUS

This command returns the state of only the connected CHMPX process. The result returns the basic state of the CHMPX process, which is rougher than the DUMP control command.

ALLSTATUS

Returns the status of all CHMPX server nodes and slave nodes held by the connected CHMPX process. This command returns the minimum necessary state of other CHMPX processes including self contained in the connected CHMPX process. With this command you can get the state on the RING between CHMPX processes.

UPDATESTATUS

This command sends the state of the CHMPX process that received this command to the other CHMPX process connected by this CHMPX process and forcibly updates the state. If one CHMPX process state is propagated to the other CHMPX process in the wrong state, this command can be forcibly set to the correct CHMPX process state. It is a case not normally occurring, but it is a recovery command to match the state of CHMPX process.

DUMP

This command returns all the internal information of the connected CHMPX process. You can check the detailed status of the current CHMPX process with this command.

Control command (effective for all CHMPX server node processes on RING)

SERVICEIN

This command instructs the connected CHMPX server node to provide the service. If the CHMPX process of the server node is started and participates in RING but is not providing the service(SERVICE OUT), it instructs to provide the service. You can use this command to set the CHMPX process ready for service provision(SERVICE IN, ADD, PENDING). When the AUTOMERGE setting is ON in the configuration, the CHMPX process performs initial operation so that it automatically enters the SERVICE IN state, so you do not need to use this command.

SERVICEOUT [hostname]:[control port number]

When a CHMPX server node process participates in RING and provides service(SERVICE IN), this command can instruct the CHMPX process not to provide service. When the CHMPX process receives this command, it becomes the service discontinuance ready state (SERVICE IN, DELETE, PENDING). You can specify a CHMPX process(host) other than the CHMPX process that sends this command for the specified host name and control port number. This is to make it possible for a server node that is not running the CHMPX process(DOWN) to be served out from another CHMPX server node. When the AUTOMERGE setting of the configuration is set to ON and the CHMPX process is stopped(terminated), the SERVICE OUT state automatically operates so that it does not need to use this command.

MERGE

When the state of the CHMPX server node is in the preparation state(PENDING) by SERVICEIN/SERVICEOUT commands, etc, this command starts data merging. When a client process(server side process) connecting with a CHMPX server node process has data, data must be merged with other CHMPX server node processes when starting or stopping service provision. This is a control command to start merging this data. If this command is successfully accepted, the CHMPX process will be in the merge executing state(DOING). The CHMPX server node process automatically shifts to the merge complete status(DONE) when data merging is completed. When the AUTOMERGE setting of the configuration is set to ON, the CHMPX server node process in the PENDING state automatically shifts to the DOING and DONE state as soon as preparation is completed.

COMPMERGE

When all CHMPX server node processes are in the merge complete status(DONE) of data, it becomes the service service provision/stop state(SERVICE IN/SERVICE OUT) by receiving this command. If at least one CHMPX server node process is not in the data merge complete state(DONE), this command will fail. When the AUTOMERGE setting of the configuration is set to ON, when all the CHMPX server node processes have reached the merge complete state(DONE) of the data, they are automatically set to the service service provision/stop state(SERVICE IN/SERVICE OUT).

ABORTMERGE

This command cancels the process when the CHMPX server node process is in the service provision/halt preparation state(PENDING), merging of data(DOING), and data merge complete(DONE), and returns the original state. This command is used to cancel the process in case the data merging process can not be completed or it takes time.

SUSPENDMERGE

CHMPX reads the setting of AUTOMERGE from the configuration at startup and decides whether to execute automatic merging processing. With this command you can specify whether to ignore AUTOMERGE configuration(SUSPEND) or valid it(NOSUSPEND). This command instructs all CHMPX server nodes on RING to ignore the AUTOMERGE setting(SUSPEND). With this command, this setting status is reflected not only to all CHMPX server nodes on RING at that time but also to CHMPX server nodes that join RING later. This command temporarily disables the setting of AUTOMERGE when many numerous CHMPX server nodes are input to RING at a time. For example, by starting service provision by SERVICEIN/MERGE/COMPMERGE commands after submission. When adding a large number of CHMPX server nodes at the same time by this method, AUTOMERGE is not automatically executed every addition, so that merge processing can be performed efficiently.

NOSUSPENDMERGE

This command instructs all CHMPX server nodes on RING to enable AUTOMERGE setting(NOSUSPEND). This command cancels the state where AUTOMERGE setting is invalid(SUSPEND). With this command, this setting state is reflected not only to all CHMPX server nodes on RING but also to CHMPX server nodes that join RING later.

5. Systemd Service

After installing CHMPX as a package, that package contains a systemd service called chmpx.service.
This section describes how to start the CHMPX process using this chmpx.service.

5.1 Configuration for CHMPX process

When starting CHMPX with chmpx.service, the /etc/antpickax/chmpx.ini file is used as the configuration file.
Please prepare this file first.

5.2 Start chmpx.service

Immediately after installing the CHMPX package, chmpx.service is disabled.
When the configuration file(/etc/antpickax/chmpx.ini) is ready, first enable chmpx.service and then start.

$ sudo systemctl enable chmpx.service
$ sudo systemctl start chmpx.service

With the above procedure, CHMPX will be started by chmpx.service.

5.3 Customizing

You can customize the behavior of chmpx.service by modifying the /etc/antpickax/chmpx-service-helper.conf file.
Alternatively, you can prepare the /etc/antpickax/override.conf file and customize it as well.
If both files customize for the same keyword, the /etc/antpickax/override.conf file takes precedence.

About chmpx-service-helper.conf

The keywords that can be customized in the chmpx-service-helper.conf file are listed below.

INI_CONF_FILE

Specifies the path to the configuration file that is specified when starting CHMPX.
The default is /etc/antpickax/chmpx.ini.

PIDDIR

Specifies the directory where the process IDs of CHMPX processes and processes related to chmpx.service are stored.
The default is /var/run/antpickax.

SERVICE_PIDFILE

Specifies the filename to store the process ID of the process associated with chmpx.service.
The default is chmpx-service-helper.pid.

SUBPROCESS_PIDFILE

Specifies the file name that stores the process ID of the CHMPX process.
The default is chmpx.pid.

SUBPROCESS_USER

Specifies the user to start the CHMPX process.
The default is the user who started chmpx.service.

LOGDIR

Specifies the directory that stores logs for CHMPX processes and processes related to chmpx.service.
By default, journald is responsible for log management.

SERVICE_LOGFILE

Specifies the filename to store logs for processes related to chmpx.service.
By default, journald is responsible for log management.

SUBPROCESS_LOGFILE

Specifies the name of the file that stores the CHMPX process logs.
By default, journald is responsible for log management.

WAIT_DEPENDPROC_PIDFILE

Before starting the CHMPX process, specify the file path of the process ID of the process waiting to start.
No default is specified. It means default case will start the CHMPX process without waiting for another process to start.

WAIT_SEC_AFTER_DEPENDPROC_UP

Waiting to start before starting the CHMPX process Specifies the amount of time to wait in seconds after the process starts.
The default is 15 seconds. However, since WAIT_DEPENDPROC_PIDFILE is not specified, it does not wait for another process to start.

WAIT_SEC_STARTUP

Specifies the amount of time in seconds to wait before starting the CHMPX process after chmpx.service is started.
The default is 10 seconds.

WAIT_SEC_AFTER_SUBPROCESS_UP

Specify the waiting time in seconds after starting the CHMPX process before checking the status of the CHMPX process.
The default is 15 seconds.

INTERVAL_SEC_FOR_LOOP

Specify the time in seconds when waiting for process restart, stop confirmation, etc.
The default is 10 seconds.

TRYCOUNT_STOP_SUBPROC

Specifies the maximum number of attempts to stop the CHMPX process. If this number is exceeded, it is considered that the CHMPX process stop has failed.
The default is 10 times.

SUBPROCESS_OPTIONS

Specifies the options to pass when the CHMPX process starts.
The default is empty.

BEFORE_RUN_SUBPROCESS

You can specify a command to execute before starting the CHMPX process.
The default is empty.

About override.conf

The override.conf file takes precedence over the chmpx-service-helper.conf file.
The keywords that can be customized in the override.conf file are the same as in the chmpx-service-helper.conf file.
However, the format of the override.conf file is different from the chmpx-service-helper.conf file.

Format 1
<customize configuration file path>:<keyword> = <value>

It is a format to set the value directly by specifying the path and keyword of the customized configuration file.
For example, specify as follows.

/etc/antpickax/chmpx-service-helper.conf:CHMPX_INI_CONF_FILE = /etc/antpickax/custom.ini
Format 2
<customize configuration file path>:<keyword> = <customize configuration file path>:<keyword>

It is a format to specify the path and keyword of the customized configuration file and set the value in another configuration file.
For example, specify as follows.

/etc/antpickax/chmpx-service-helper.conf:CHMPX_INI_CONF_FILE = /etc/antpickax/other.conf:CHMPX_INI_CONF_FILE

5.4 Stop chmpx.service

$ sudo systemctl stop chmpx.service

With the above procedure, CHMPX will be stopped by chmpx.service.

Details TOP Build