GCB Install & Running

Network Setup

One most important prerequisite of GCB is that your private or firewalled network must allow outbound connections. In other words, your NAT or firewall must allow (1) TCP connections initiated from private nodes and (2) UDP sessions initiated by private nodes. If you don't know how to set your network this way and you use Linux iptables on your headnode, you may find this site:Enable Outbound Connections Using Linux iptables helpful.

Installing from Binary

Untar the binary file you downloaded. bin, include, and lib will be created under gcb-platform-version directory. bin has daemons comprising GCB inagent; include and lib will have GCB header files and library, respectively.

Installing from Source

GCB is built using GNU build system. Untar the zip file and do the regular configure, make, and make install. The same directories and files will be created as if GCB is installed from the binary.

Running inagent

Copy files in $(GCB-install-dir)/bin to the machine that you want to run GCB inagent. Refer What goes where to figure out where you have to run GCB inagent.

GCB inagent needs several environment variables and takes an argument.

Environment variable setting

BrokerMasterLog: The log file name of BrokerMaster. All the log and debug messages from a daemon called BrokerMaster will be recorded to this file.
BrokerMasterDebug: The log level of BrokerMaster. "fulldebug" or "basic". "fulldebug" means more detailed logging.
BrokerMasterMaxLog: The maximum size of the BrokerMaster log file. When the log file reaches to this size, the content of the file will be moved to $(BrokerMasterLog).old.
BrokerLog: The log file name of Broker. All the log and debug messages from a daemon called Broker will be recorded to this file.
BrokerDebug: The log level of Broker. "fulldebug" or "basic". "fulldebug" means more detailed logging.
BrokerMaxLog: The maximum size of the Broker log file. When the log file reaches to this size, the content of the file will be moved to $(BrokerLog).old.
RelayServerLog: The log file name of RelayServer. Actual log file will be $(RelayServerLog).process_id.
RelayServerDebug: The log level of RelayServer.
RelayServerMaxLog: The maximum size of the RelayServer log file.
ACTIVE_TO_CLIENT: The fact whether GCB inagent can directly talk to servers running inside the network that it manages. "yes" or "no".

Command line arguments

GCB inagent is actually comprised of a BrokerMaster, a Broker, and multiple RelayServer running together. The number of RelayServers is dynamically determined by the number of server sockets that the inagent currently supports. You can bring the inagent up by running:

    BrokerMaster -i ip-address

    -i  Public IP address in dotted notation like "128.105.175.121".

Running Application

To run GCBnized application, you need to create a sort of routing table and set environment variables.

Routing table

When an application calls GCB_connect, GCB refers the GCB routing table to decide whether GCB mechanism should be used to connect to the destination. You have to tell GCB where the routing table is by setting $(GCB_ROUTE). The format of the routing table is very simple. Each line of the file contains one rule. Each rule consists of 'target' and 'method'. 'target' specifies destination IP address(es) to match and 'method' tells what mechanism must be used to connect to the destination. The 'target' must be specified as a valid IP string in the standard dotted notation, "/", and 'mask'. 'mask' tells how many bits of destination IP and IP of 'target' must match. 'method' must be either "GCB" or "direct" GCB stops searching the table as soon as it sees a rule that matches, therefore you must put specific rules before generic ones. The following shows an example routing table.

128.105.144.68/32   GCB
128.105.144.71/32   GCB
128.105.144.68/24   direct
*/0         direct

Environment variable setting

GCB_ENABLE: The fact that GCB must be used or not. Valid value is either "TRUE", "FALSE", or undefined. If $(GCB_ENABLE) is "FALSE" or undefined, GCB will be bypassed.
GCB_ROUTE: The full pathname of GCB routing table.
GCB_BROKER: The IP address of the GCB inagent. This must be the same value as the IP address you use with -i option to run the inagent.
GCB_LOG_FILE: The full pathname of the log file.
GCB_LOG_LEVEL: This variable defines how detail GCB will produce log and debug information. Set this variable to "fulldebug" for detailed log. If the variable is undefined or set to "basic", only basic and error messages will be logged.
GCB_LOG_MAXSIZE: The maximum size of the log file. After the log file reaches the size defined by this variable, GCB will move the current log file to $(GCB_LOG_FILE).old. Next log messages will go to $(GCB_LOG_FILE).