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 client and gloctl by using UDP, and it communicates with gagent by using 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 synchronizes the data of glocator set in ALTERNATE_LOCATORS before driving glocator.

There are two methods for the data synchronization, whichare SOURCE and BOTH. SOURCE method brings data from ALTERNATE_LOCATORS, and BOTH method merges two glocators.

Example

The following is an example of a successful use of the sync option with the SOURCE type.

$ glocator --start --sync SOURCE

glocator is started.

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

$ glocator --start --sync SOURCE

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

The following is an example of failure of a sync option. glocator set in ALTERNATE_LOCATORS property does not response.

$ glocator --start --sync SOURCE

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

The following is an example of a failure when no argument is provided for the sync option.

$ glocator --start --sync

ERR-HY000(11000): Invalid argument

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 keeps data consistent, so it enables the stable service through the remote glocator when an error occurs.

Configuration

Each glocator should set ALTERNATE_LOCATORS property in a configure file to use the replication feature. Locator_name should be set in ALTERNATE_LOCATORS property and the specified Locator_name should be set in a configure file together with HOST, PORT properties.

The following is how to set ALTERNATE_LOCATORS property.

[LOCATOR]
ALTERNATE_LOCATORS = (locator_name1,locator_name2)
[locator_name1]
HOST= ip_address
PORT = port_num
[locator_name2]
HOST= ip_address
PORT = port_num

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

[LOCATOR]
PORT=42581
SYNC_RESPONSE_TIMEOUT = 2
SYNC_RETRY_COUNT = 2
LOCATION_FILE_NAME='glocator_1.dat'
ALTERNATE_LOCATORS=(LOCATOR_2,LOCATOR_3)

[LOCATOR_2]
HOST=127.0.0.1
PORT=42582

[LOCATOR_3]
HOST=127.0.0.1
PORT=42583

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.

sync option has BOTH and SOURCE. BOTH merges glocator's own data and alternate glocator's data. SOURCE brings the data from the counterpart glocator. The sync operation of glocator is 1 : 1 correspondence task between a glocator and an alternate glocator. Therefore, if A and B are already being operated, and C is operated after syncing by using BOTH for the replication of three (A, B, C) glocators, then the data of A and B glocators may be different.

glocator in service synchronizes only the updated content. If the data synchronization fails due to the packet loss or other reasons, then the data may be different. In this case, update the data within that glocator by using gloctl program, or restart glocator with sync option.

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 as 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.
Packets are stored as a single item of a message unit in a queue.

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_LOCATORS

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.