sqlf locator

Allows peers (including other locators) in a distributed system to discover each other without the need to hard-code anything about other peers.

Syntax


To start a stand-alone locator use the command:

sqlf locator start [-J<vmarg>]* [-dir=<workingdir>] 
                   [-classpath=<classpath>]
                   [-distributed-system-id=<id>]
                   [-max-heap=<size>] [-initial-heap=<size>]
                   [-peer-discovery-address=<addr> (default is 0.0.0.0)]
                   [-peer-discovery-port=<port> (default 10334)]
                   [-bind-address=<address> (default is the -peer-discover-address value)]
                   [-run-netserver=<true|false> (default true)]
                   [-client-bind-address=<addr> (default is GemFire
                     bind-address or if not set then loopback)]
                   [-client-port=<clientport> (default 1527)]
                   [-locators=<addresses>] [-auth-provider=<provider>]
                   [-remote-locators=<host[port]>[,<host[port]>]...]
                   [-server-auth-provider=<provider>]
                   [-user=<username>] [-password[=<password>]]
                   [-log-file=<path> (default sqlflocator.log)]
                   [-<prop-name>=<prop-value>]*
Note: Always start a locator as a background process using sqlf locator start &

This is required as the locator may not have been the last peer to go down in the cluster and thus will require the other cluster locators to also come up before it can be certain that its data is consistent with others.

When starting a locator using sqlf locator start, in addition to those listed above, you can use any other SQLFire boot properties (<prop-name>) on the command-line.

The startup script maintains the running status of the locator in a file .sqlflocator.ser.

To display the status of a running locator:

sqlf locator status [ -dir=<workingdir> ]

To stop a running locator:

sqlf locator stop [ -dir=<workingdir> ]

The table describes options for the sqlf locator command. Default values are used if you do not specify an option.

Option Description
-J

JVM option passed to the spawned SQLFire Locator JVM. For example, use -J-Xmx1024m to set the JVM heap to 1GB.

-dir

Working directory of the locator that will contain the SQLFire Locator status file and will be the default location for log file, persistent files, data dictionary, and so forth. This option defaults to the current directory.

-classpath

Location of user classes required by the SQLFire Locator. This path is appended to the current classpath.

-distributed-system-id

Integer that uniquely identifies this SQLFire cluster.

Set a unique value when using WAN replication between multiple SQLFire clusters. Configure Locators for WAN Member Discovery provides more information.

-max-heap

-initial-heap

Set the maximum heap size and initial heap and for the Java VM, using SQLFire default resource manager settings. If you use the -max-heap and -initial-heap options, by default SQLFire sets the critical-heap-percentage to 80% of the heap, and the eviction-heap-percentage to 80% of the critical heap. SQLFire also sets resource management properties for eviction and garbage collection if they are supported by the JVM.

Note: If you use the -J-Xms or -J-Xmx JVM properties instead of -initial-heap and -max-heap, then SQLFire does not use default JVM resource management properties. In this case, you must specify all properties manually for eviction, garbage collection, heap percentage, and so forth.
-peer-discovery-address

Address to which the locator binds for peer discovery (includes servers as well as other locators).

-peer-discovery-port

Port on which the locator listens for peer discovery (includes servers as well as other locators). Valid values are in the range 1-65535, with a default of 10334.

-bind-address The address to which this peer binds for receiving peer-to-peer messages. By default sqlf uses the -peer-discovery-address value.
-run-netserver

If true then it starts a network server (see the -client-bind-address and -client-port options to specify where the server should listen) that can service thin clients (defaults to true).

If set to false, then the -client-bind-address and -client-port options have no affect. This option defaults to true.

-client-bind-address

Address to which the network controller binds for client connections. This takes effect only if -run-netserver option is not set to false.

-client-port

Port that the network controller listens on for client connections, 1-65535 with default of 1527. This takes effect only if -run-netserver option is not set to false.

-locators

List of other locators as comma-separated host:port values used as backups in case one of the locators fails. The list must include all other locators in use, and must be configured consistently for every member of the distributed system.

Servers must be configured to use all the locators of the distributed system, which includes this locator and all of the others in the list.

-auth-provider

Authentication mechanism to use for client connections. If -server-auth-provider is not specified, then this same mechanism is also used for joining the cluster. Supported values are BUILTIN and LDAP.

By default, no authentication is used.

-remote-locators

Comma-separated list of addresses and port numbers of locators for remote SQLFire clusters.

Use this option when configuring WAN replication to identify connections to remote SQLFire clusters. Configure Locators for WAN Member Discovery provides more information.

-server-auth-provider

Authentication mechanism to use for joining the cluster and talking to other servers and locators in the cluster. Supported values are BUILTIN and LDAP. By default, SQLFire uses the value of -auth-provider if it is specified, otherwise no authentication is used.

-user

If the servers or locators have been configured to use authentication, this option specifies the user name to use for booting the server and joining the distributed system.

-password

If the servers or locators have been configured to use authentication, this option specifies the password for the user (specified with the -user option) to use for booting the server and joining the distributed system.

The password value is optional. If you omit the password, sqlf prompts you to enter a password from the console.

-log-file

Path of the file to which this locator writes log messages. The default is sqlflocator.log in the working directory.

-<prop-name>

Any other SQLFire boot property such as log-level.

Description

A SQLFire locator allows peers (including other locators) in a distributed system to discover one another without having to hard-code anything about other peers. The other mode of discovery is using multicast that requires the peers to use the same multicast address and port for discovery.

A locator can be started on its own, or can be embedded in a server with the full SQLFire engine. Standalone locators are also required for systems that enable network partitioning management. To start embedded locators use the "-start-locator" option to the SQLFire server.

Note: Locators are the recommended discovery method for production systems. Additionally, running standalone locators provides the highest reliability and availability for the locator service as a whole.

Because a locator has no data or meta-data available, it cannot directly service any of the user table related SQL statements from thin clients. It can only service queries involving inbuilt system tables, and inbuilt system procedure calls. Clients use the connection as a control connection to query the locator for the server with the least amount of load (measured in terms of other active client connections) and transparently create the actual data connection to the server as returned by the locator. The client also keeps track of all the other locators and peers in the distributed system by querying the locator. This practice avoids creating multiple control connections for the same distributed system. If the client detects any two separate user connections referring to locators or servers in the same distributed system then it will use the same control connection for both. The list of all locators and peers is also used for failover if the control connection itself fails.

SQLFire locators are necessary for load-balanced client connections, and for full availability of the transparent failover functionality provided by the thin client driver (high-availability, or HA in short). Without locators client connections cannot be load-balanced. Even though clients try to fail over transparently to other servers without locators, this behavior is not as reliable as using locators, and failover may not work transparently if multiple servers fail in quick succession.

Always start a locator as a background process. This is required as the locator may not have been the last peer to go down in the cluster and thus will require the other cluster locators to also come up before it can be certain that its data is consistent with others. Note that each locator locally persists a copy of the data dictionary required for basic functioning and may have to wait for other locators to come back online to ensure that it has all the latest updates to the data dictionary.

Example

Starting a locator generates output such as the following. XXX is the path of current working directory.

 Starting SQLFire Locator using peer discovery on: 0.0.0.0[10334]
Starting network server for SQLFire Locator at address localhost/127.0.0.1[1527] 
SQLFire Locator pid: 3722 status:running
Logs generated in <XXX>/sqlflocator.log

By default sqlf locator start starts the server process locally and uses the current working directory to store logs, locator state and the data dictionary, and uses default TCP port 10334 for peer discovery. A standalone locator does not store any user table data or table meta-data.

A sub-directory called datadictionary is created by default in the current working directory of the locator and contains the persistent meta-data of the DDLs required for startup by locator (for example, authentication related privileges) that have been executed in the distributed system from any of the clients or peers. This directory is necessary for a SQLFire locator to startup and function properly.

As the output above indicates, a network server is also started by default that binds to localhost on port 1527. This service allows thin clients to connect to one of the servers and execute SQL commands using the DRDA protocol.