Overview of glocator

Definition

glocator is a utility which provides locations to a client and manages them in GOLDILOCKS cluster system.
The location information of cluster member nodes is provided to the glocator program through gloctl.
glocator communicates with the client and gloctl via UDP, and it communicates with gagent via TCP.

Usage

glocator [options]

Options

help

Description

It outputs a help message.

Example

$ glocator --help

Usage:
 glocator [options]

Options:

-c  --create       Create glocator environment
-s  --start        Start glocator
-t  --stop         Stop glocator
-f  --conf         Set configure file
-u  --status       Get glocator status
-l  --silent       Suppress display message
-r  --no-copyright Suppress display copy right and version
-h  --help         Print help message

create

Description

It creates the data file of glocator.

Example

$ glocator --create

glocator is created.

$ ls
README  glocator.dat  system_data.dbf  system_dict.dbf  system_undo.dbf

start

Description

It starts glocator. If glocator having the same port already has started, then an error occurs.

Example

$ glocator --start

glocator is started.

stop

Description

It stops glocator which is in operation. The same port should be set to stop glocator in operation.

Example

$ glocator --stop

glocator is stopped.

conf

Description

It sets the configure file when starting glocator.

Example

$ glocator --start --conf goldilocks.glocator.conf

glocator is started.

status

Description

It outputs the status message of glocator which is in operation. The same port should be set to check the status of glocator in operation.

Example

$ glocator --status

Process ID: 26058
Configuration file: goldilocks.glocator.conf
Unix domain path: /tmp/unix-glocator.42581
Udp listen host: 0.0.0.0, Port: 42581
glocator is running.

sync

Description

It connects with ALTERNATE_LOCATOR and synchronizes the data.

Data synchronization merges the data of two glocators, and in the event of a conflict, the more recent data is selected based on the creation time.

Example

The following is an example of using the sync option.

$ glocator --start --sync

glocator is started.

The following is an example of failure of a sync option. The ALTERNATE_LOCATOR property value is not set in the configure file.

$ glocator --start --sync

ERR-HY000(60016): Need more alternate locator host information.

silent

Description

It does not output the message of glocator about the execution.

Example

$ glocator --start --silent

no-copyright

Description

It does not output the message of glocator's copyright and version about the execution.

Example

$ glocator --start --no-copyright

glocator is started.

Using glocator

Data File

glocator data file should be created before starting glocator.

$ glocator --create

glocator is created.

The directory in which glocator data file is stored can be altered by editing configuration LOCATION_FILE_DIR. The default value is created in <GOLDILOCKS_DATA>/db. The data file can be altered by editing LOCATION_FILE_NAME. The default value is glocator.dat.

The maximum size and initial size of glocator data file can be altered by editing configuration LOCATION_FILE_MAX_SIZEand LOCATION_FILE_SIZE.

CSTARTUP and CSHUTDOWN

glocator can be used to CSTARTUP and CSHUTDOWN the GOLDILOCKS server.
For that, glocator should be in operation, and CSTARTUP or CSHUTDOWN should be executed through gsqlnet.
However, LOCATOR_DSN and the property should be set in odbc.ini of the device which executes gsqlnet. For more information, refer to GOLDILOCKS UNIX ODBC driver libraries.

The following contents is set in odbc.ini to use glocator.

[GOLDILOCKS]
HOST=127.0.0.1
PORT=20101
UID=sys
PWD=gliese
LOCATOR_DSN=GLOCATOR

[GLOCATOR]
HOST=127.0.0.1
PORT=42581

glocator should know the location information of member nodes to execute CSTARTUP and CSHUTDOWN.

Replication

Overview

glocator replication ensures data consistency, allowing for stable service through the remote glocator in the event of an error during operation.

Configuration

To use replication, the ALTERNATE_LOCATOR property must be set in the configuration file. This property should specify the locator name, which must also exist in the configuration file along with the HOST and PORT properties. The master glocator is not required to define the ALTERNATE_LOCATOR property; however, if it is defined, it must match the HOST and PORT properties of the sub glocator.

The following is how to set ALTERNATE_LOCATOR property.

[LOCATOR]
ALTERNATE_LOCATOR = locator_name1
[locator_name1]
HOST= ip_address
PORT = port_num

The following is an example of a configure file which sets ALTERNATE_LOCATOR property.

[LOCATOR]
PORT=42581
SYNC_RESPONSE_TIMEOUT = 2
SYNC_RETRY_COUNT = 2
LOCATION_FILE_NAME='glocator_1.dat'
ALTERNATE_LOCATOR=LOCATOR_2

[LOCATOR_2]
HOST=127.0.0.1
PORT=42582

Synchronizing Data

The data should be consistent when the replicated glocator is in service. If glocator in operation does not exist, then all glocator can perform the normal start. If glocator in operation exists, an alternate glocator can be started by synchronizing the data using a sync option.

The sync option merges the data of the two glocators. Any conflicting duplicate data is overwritten by the newly updated data.

When data changes during the glocator service, it attempts to synchronize the data. However, if synchronization fails due to reasons such as packet loss, discrepancies may arise between the datasets. In this case, use the gloctl program to directly modify the data on the affected glocator or restart the glocator with the sync option.

Replication and gagent

glocator replication is categorized into master and sub (substitute). This distinction is determined by their startup order. A later-started sub glocator must use the sync option to connect with the previously started master glocator.

The gagent must always connect to the master. This is to prevent the gagent from being distributed. If the glocator that the gagent is trying to connect to is a sub, the connection will be terminated, and it will adjust to connect to the master.

Features of glocator

Connection Service

It provides a service feature which enables arbitrarily access any node among user-defined nodes even though the location information of a specific node in a cluster environment is unknown.

The service feature is that a user specifies nodes managed by glocator an arbitrary group. This service can be registered by using gloctl program. Service lists managed by glocator can also be viewed by using gloctl program.

An application should be accessed by using ODBC driver, and LOCATOR_DSN and LOCATOR_SERVICE property should be specified in odbc.ini file.

The figure above describes that an application accesses to g1n1 belonging to service s3. The connecting sequence of ODBC driver by using the service is the same as the sequence of node registered in the service. If ODBC driver fails to connect to g1n1 in the example above, it will try to connect to the next node g2n1.

Cluster Failover

glocator is helpful when a server proceeds the failover.

When the value of server property CLUSTER_SPLIT_BRAIN_RESOLUTION_POLICY is set to 1 or 2, and connection between nodes is disconnected in a cluster environment, a failover occurs, then each node proceeds the cluster failover and queries its viability to glocator through gagent.

The glocator which received a query determines the viability between two nodes which were disconnected, and transfer the result to the gagent which enquired the query.

Nodes received the viabilty results are terminated or proceeds the failover.

glocator Configuration

Configuration File and Environment Variable

glocator can use a file or environment variable to set the configuration.

An environment variable can be set by using the name of which 'LOCATOR_' is added as a prefix to a configuration property name. For example, setting HOST in the configuration file has the same effect as specifying $LOCATOR_HOST.

The contents of a configuration file takes precedence over the environment variable setting values.

glocator reads the configuration file by reading DSN as the default value of [LOCATOR].

glocator has $GOLDILOCKS_DATA/conf/goldilocks.glocator.conf file as its environment file. To alter the driving environment of glocator, the file contents should be altered, or glocator should start after setting the environment variables.

Configuration Properties

HOST

It is an IP address of which glocator binds for UDP communication.
It uses an IP address in IP v4 form.

PORT

It is a port of which glocator receives a packet through UDP communication.
The port from 1024 to 49151 can be used.

WORKER_COUNT

It is the number of threads processing packets of which glocator received from a client or an internal process.

MAX_NODE_COUNT

It is the maximum number of connectable gagent.

MESSAGE_QUEUE_SIZE

It is the size of queue of which glocator stores packets received from a client or or an internal process before processing them.
A packet is stored in a queue as a single item in message unit.

MESSAGE_ALLOCATOR_SIZE

It is the size of an allocator which is used to allocate an item (message) to be stored in a message queue.

PACKET_ALLOCATOR_SIZE

It is the size of an allocator for a buffer which is allocated for glocator to receive packets.

SYSTEM_LOGGER_DIR

It is the directory path in which system trace log file of glocator is stored. <GOLDILOCKS_DATA> of the default value is replaced with the environment variable value of $GOLDILOCKS_DATA.

SYSTEM_UDS_DIR

It sets the directory path in which the unix domain socket file used in glocator is stored. The maximum length of the directory should be set within 60 bytes.

LOCATION_FILE_DIR

It sets the directory path in which the location file used in glocator is stored.

LOCATION_FILE_NAME

It sets the name of a location file which is used in glocator.
The default value is glocator.dat.

LOCATION_FILE_SIZE

It sets the initial size of a location file used in glocator.

LOCATION_FILE_MAX_SIZE

It sets the maximum size of a location file used in glocator.

MESSAGE_TIMEOUT

It sets the maximum time (seconds) for glocator to wait to receive packets. Packets exceeds the maximum time without being processed, are dumped.

ALTERNATE_LOCATOR

It sets Replication of glocator.

SYNC_RETRY_COUNT

It sets the number of redelivery of glocator synchronization.

glocator transfers the altered data to alternate locator when the data is altered, and it transfers the data again when it could not get any response.

SYNC_RESPONSE_TIMEOUT

It sets the time waits for the response for the synchronization data transferred from glocator.

KEEPALIVE_IDLE_TIME

It is the (idle) duration which the TCP packet is not sent nor is received before sending a keep alive packet. In other words, if TCP packet is not exchanged during the time set in KEEPALIVE_IDLE_TIME, then it performs the keep alive mechanism to detect the dead connection.

KEEPALIVE_COUNT

It is the number of performing keep alive mechanism.

KEEPALIVE_INTERVAL

It is the time interval to send the keep alive packet.