SA gateway properties file syntax

The entries in the Gateway Properties file control the operation and configuration of the gateways on the current host.

The SA Gateway Properties file is located in:

/var/opt/OPSWgw/gwname/opswgw.properties

on each core host.

For information about ./opswgw, seeopswgw command line arguments

An SA Gateway properties file can have the following entries:

Do not modify these entries unless you are certain you understand the impact of your change on the core.

Usage: ./opswgw-tc-70 [options]

--Gateway name

(Required) Set the name of the SA Gateway. This name must be unique in a Gateway mesh.

--Realm realm

(Required) All Gateways operate in a named Realm. A Realm is an SA construct that refers to a set of servers that are serviced by the Gateways in the Realm. Realms can support an IPv4 address space that may overlap with other Realms. Realms are also used to define bandwidth utilization constraints on SA functions.

--Root true | false

Specifies that this Gateway will act as a root of the Gateway mesh. All Gateways in a Root Realm must be Root Gateways.

Default: false.

--Level int

(Experimental) Routing level for the Gateway. There are eight possible levels, 0 through 7. All Gateways in a realm must have the same level.

Default: 0

--GWAddress lhost

Sets the local host address (if you are specifying the value for the Management Gateway, use the IP address only; do not use the hostname. You can, however, use the hostname for other, non-Management Gateways) that this Gateway uses to tell other components how to contact it. This value is used by the core to discover new core­side Gateways. It is also used to communicate the active list of Gateways that are servicing Realm to proxy clients (such as Agents) through the X­OPSW­GWLIST mime header.

--Daemon true | false

Daemonize the process.

Default: false.

--Watchdog true | false

Start an internal watchdog process to restart the Gateway in case of a failure or signal. A SIGTERM sent to the watchdog will stop the watchdog and Gateway processes.

Default: false.

--User name

Change to this user on startup.

--RunDir path

Change to this directory on startup.

--ChangeRoot true | false

If true chroot into RunDir. This can to used by a helper script to construct a jail.

Default: false

--PreBind proto:ip:port, ...

For security reasons, it can be useful to run a Gateway chrooted as a non-privileged use (only ports above 1024 can be used for any listeners). If you want to use a non-privileged user and a privileged listener port, you can use the --PreBind directive to reserve the port while the process is root and before privileges are dropped.

--HardExitTimeout seconds

The number of seconds after a restart or exit request that the main thread will wait for internal threads and queues to quiesce before performing a hard exit.

--LogLevel INFO | DEBUG | TRACE

Sets the logging level. Note that DEBUG and TRACE can produce a large amount of output, which typically is relevant only to developers and can negatively affect performance.

Default: INFO.

--LogFile file

The filename of the SA log file.

--LogNum num

The number of rolling log files to keep.

--LogSize size

The size, in bytes, of each log file.

--TunnelDst [lip1:]lport1[:crypto1],...

If specified, starts a tunnel destination listener. The tunnel listener can listen on multiple ports (a comma-separated list with no spaces). If the port is prefixed with an IP address, the listener will bind only to that IP address. For example: 2001, 10.0.0.2:2001, 2001:/var/foo.pem, 10.0.0.2:2001:/var/foo.pem

--TunnelSrc rhost1:rport1:cost1:bw1[:crypto1],...

If specified, creates a tunnel between this Gateway and the Gateway listening at rhost1:rport1. The link cost1 and link bandwidth bw1 must be set. The cost is a 32-bit unsigned int, and bandwidth is in Kbits/sec (K=1024bits). (Additional tunnels are separated by commas.) Examples: gw.foo.com:2001:1:0, gw.bar.com:2001:10:256:/var/foo.pem

--ProxyPort [lip1:]lport1,[lip2:]lport2,...

The HTTP CONNECT proxy listener port. If more than one proxy listener port is needed, you can add more using a comma-separated list. You can enable interface binding by prepending an IP address to the port.

--ForwardTCP [lip1:]lport1:realm1:rhost1:rport1,...

Creates a static TCP port forward. Forward the local port lport(x) to the remote service rhost(x):rport(x), which is in realm(x). A blank realm (such as lport::rhost:rport) means route to the closest Root Realm.

--ForwardTLS [lip1:]lport1:realm1:rhost1:rport1, ...

Creates a static TCP port forward that specializes in TLS traffic. The TLS session ID is parsed and sent to the egress Gateway for use in load-balancing algorithms. In all other respects, this feature behaves like ForwardTCP.

 

--ForwardUDP [lip1:]lport1:realm1:rhost1:rport1,...

Creates a static UDP port forward. Forward local port lport(x) to remote service rhost(x):rport(x), which is in realm(x). A blank realm (such as lport::rhost:rport) means route to the closest Root Realm. (Note: Some UDP services, such as DHCP, cannot be proxied in this way.)

--IdentPort [lip:]lport

Starts an IDENT service listening on local port lport (optionally bound to the local IP lip).

--AdminPort [lip:]lport[:crypto1]

Starts an administration interface listening on local port lport, which is optionally bound to the local IP lip. If you use crypto, include a crypto specification file name.

--ConnectionLimit int

Specifies the soft memory tuning limit for the maximum number of connections.

--OpenTimeout seconds

Waits a maximum seconds for a remote CONNECT call to establish a remote connection.

--ConnectTimeout seconds

Waits a maximum seconds for a connect() to complete. If a timeout occurs, then an HTTP 503 message is returned to the client (via the ingress Gateway). The client will get this message if the ConnectTimeout plus the Gateway mesh transit delay is less than the OpenTimeout.

--ReorderTimeout seconds

In the event of outoforder messages (for a TCP flow), limits the amount of time (seconds) to wait for messages needed for reassembly to arrive. The most common cause of out-of-order messages is when a transit tunnel fails and a new route is taken mid-flow.

--TunnelStreamPacketTimeout seconds

If a portion of a TCP flow cannot be delivered to an endpoint, then tears down the TCP connection after seconds.

--QueueWaitTimeout seconds

Specifies the maximum time that a tunnel message can wait at the head of an internal routing queue while waiting for a tunnel to be restored.

--KeepAliveRate seconds

Send link keepalive messages once every x seconds on each link.

--LsaPublishRateMultiple float

Link State Advertisements (LSA) are published once every k*M seconds, in which M is the number of Gateways in the mesh and k is a floating point constant specified using --LsaPublishRateMultiple. For example, if there are 100 Gateways in a mesh and --LsaPublishRateMultiple is set to 2.0, then an LSA is published approximately every 200 seconds (due to implementation factors, the actual delay will be somewhere between 190 and 210 seconds).

--LsaTTLMultiple float

Sets the TTL for LSA to float multiplied by the LsaPublishRate. Example: If LsaPublishRate is 10 seconds and LsaTTLMultiple is 3, then the TTL for LSA published by this Gateway is set to 30 seconds.

--MaxRouteAge seconds

Discards the routes from the routing table that have not been refreshed within seconds.

--RouteRecalcDutyCycle percentage

If the time to calculate Dijkstra takes tau seconds, then wait for
tau*(1/RouteRecalcDutyCycle-1) seconds until another recalculation can take place.

--TunnelTimeoutMultiple float

This number, multiplied by the KeepAliveRate, gives the maximum time that a tunnel can be idle before it is garbage collected.

 

--DoNotRouteService host1:port1,host2:port2,...

Specifies that, when a local client creates a proxy connection to host:port, do not route the message; service it locally. Use this property to ensure that certain services are handled locally, in the Gateway’s current Realm.

--ForceRouteService host1:port1:realm1,host2:port2:realm2,...

When a local client creates a proxy connection to host:port, forces the message to route to a specified Realm.

--HijackService host1:port1,host2:port2,...

When the local Gateway sees a connection to host:port via a tunnel, and the source Realm is not the local Realm, it must service the connection. If the connection is from the local Realm, the Gateway must allow the message to continue to its destination. You can use this feature to implement transparent caches.

--RouteMessages *true | false

If specified as true, turn on transit routing. If false, disable transit routing. If the destination of the message is not the local Gateway, then, by default, the message is routed based on the current routing table. If such routing is not desired, set this property to false.

--EgressFilter proto:dsthost1:dstport1:srchost1:srcrealm1,...

When the local Gateway sees a TCP connection attempt to dsthost:dstport from srchost1:srcrealm1, it must allow the connection. The implied default is to deny all connections. If you want to allow all connections, specify the egress filter as *:*:*:*:*. It is also common for an egress filter to allow connections only from the Root Realm. This can be expressed by leaving the srcrealm blank. Example: tcp:10.0.0.5:22:172.16.0.5: allows tcp connections to 10.0.0.5, port 22, from 172.16.0.5 in a Root Realm.

--IngressMap ip1:name,ip2:name,...

When sending an open message (and the srcip is in the ingress map), append (as metadata) the ip:name mapping to the open message. This allows a remote egress filter to use the name as the srchost instead of the ip. This feature supports the addition of a server to a farm without the need to individually add the server to many EgressFilter entries.

 

--LoadBalanceRule proto:thost:tport:mode:rhost1:rport1:
rhost2:rport2, ...

When receiving a new connection message for thost:tport, load balance the connection over real hosts rhost1:rport1, rhost2:rport2 etc. The load balance strategy is defined by mode.

There are six load-balancing modes:

STICKY: Send the connection to a working target based on a priority list randomized by a hash of the source IP and source Realm (the hash string can be overridden via the input MIME header X-OPSW-LBSOURCE).

LC: Send connection to a working target with the least number of connections.

RR: Send connection to the next working target in a round-robin fashion.

TLS_STICKY: Use an TLS1.0 session ID to send the connection back to the previous target based on a session ID cache. If the target is in error, or the session ID is missing from the cache, fall back to STICKY mode to make a new selection.

TLS_LC: Similar to TLS_STICKY mode, but falls back to LC mode (least connections).

TLS_RR: Similar to TLS_STICKY mode, but falls back to RR mode (round-robin). Remember to add an egress filter for proto:thost:tport. You do not need to add egress filters for the targets. Non-TLS load balancing modes can be used with UDP services.

--LoadBalanceRetryWindow seconds

If an error occurs when using a load balanced target (such as rhost1:rport1 above), then the target is marked in­error. This property controls how many seconds a Gateway will wait until it retries the target. If the target is missing (such as an RST is received upon the connection request), the load balancer will try to find a good target.

The number of seconds a load balanced TLS1.0 client can be idle before the sessionId association is reaped. This property affects the egress Gateway of a TLS flow.

--SessionIdCacheLimit slots

A soft limit on the number of TLS1.0 session IDs that the cache can hold. If this limit is exceeded, then the garbage collector begins reducing the SessionIdTimeout value in order to achieve the cache limit specified by --SessionIdCacheLimit.

--MinIdleTime seconds

Specifies the minimum number of seconds a connection can be idle during an overload condition before it will be considered for reaping.

--GCOverloadTrigger float

Specifies the fraction of SoftConnectionLimit at which to start overload protection measures. When the number of open connections reaches this overload trigger point, overload protection starts, reaping the most idle connections over MinIdleTime. Overload protection stops when the connection count falls below the overload trigger point.

--GCCloseOverload true | false

When a client tries to open a connection after the ConnectionLimit has been reached, this property tells the Gateway what to do with the new connection. A value of true causes the Gateway to close the new connection. A value of false causes the Gateway to park the new connection in the kernel’s backlog and to service it after the overload condition subsides. The proper setting is application dependent.

Default: false.

--VerifyRate seconds

When a connection stops moving data for the specified number of seconds, a connection verify message is sent to the remote Gateway to verify that the connection is still open. This check is repeated periodically and indefinitely when the timeout has expired.

--OutputQueueSize slots

Specifies the size of the tunnel output queues. These queues store messages destined for remote Gateways. Each remote Gateway has an output queue. Queues are garbage collected after MaxQueueIdleTime is reached.

--MaxQueueIdleTime seconds

Specifies the maximum time to keep an idle output queue before garbage collection removes it.

 

--TunnelManagementQueueSize slots

Specifies the size of the queues used to manage tunnel management traffic, such as LSA.

--TunnelTCPBuffer bytes

Specifies the size of the TCP SEND and RECV buffer in bytes. The operating system must be configured to handle the specified value. You can view the Gateway’s log file to see if the specified is denied by the operating system.

 

--DefaultChunkSize bytes

Specifies the default (maximum) IO chunk size when encapsulating a TCP stream. This property value can be applied only to links with no bandwidth constraint.

--LinkSaturationTime seconds

When a links has a bandwidth constraint, the chunk size, DefaultChunkSize, is computed based on two parameters. The first is the link’s bandwidth constraint. The second is the amount of time that the bandwidth shaper should use the full, real, bandwidth on the link. This parameter controls the duty cycle of the bandwidth shaper. Smaller values give a smoother bandwidth control at the cost of more overhead, because each smaller IO chunk has a header.

--TunnelPreLoad slots

Specifies the maximum number of output queue slots to use before waiting for the first Ack message. This allows for pipelining in Long Fat Pipes. This value is reduced geometrically to one as the number of queue slots diminish.

--BandwidthAveWindow samples

Specifies the maximum number of IO rate samples for the bandwidth estimation moving window. The samples in this window are averaged to provide a low-pass estimate of the bandwidth in use by a tunnel. This estimate has high frequency components due to the sharp edge of the filter window.

--BandwidthFilterPole float

Specifies the pole of a discrete­time first­order smoothing filter used to remove the high frequency components of the moving window estimator. Set the value to 0.0 to turn off this filter.

--StyleSheet URL

Adds a stylesheet link to a URL when rendering the admin UI. This is useful for embedding the admin UI in another web-­based UI. In addition to using this property to control the default stylesheet, a dynamic stylesheet override is supported by adding the variable StyleSheet=<url>/style.css to the admin UI URL.

 

--ValidatePeerCN true | false

Specifies whether the peer CN is validated against the peer configuration during a tunnel handshake operation. The peer must be turned off during the installation of an untrusted Gateway.

Default: true.

 

--PropertiesCache file

Link cost and bandwidth can be controlled via parameter­modify messages over tunnel connections. These real­time adjustments are made to the running process and written to a parameter cache, which will override the properties file or command-line arguments.

 

--PropertiesInclude file

Specifies an Include file to load and merge with the current properties. Properties in the include file can override properties from the original Properties File. This property can be specified from the command line. If so, it will override all properties, including command-line overrides. It is not recursive and does not support a list.

 

--PropertiesFile file

Places all command-line arguments into a properties file within the opswgw name space. Note that the PropertiesFile command-line argument itself must not be placed in the properties file within the opswgw name space.

opswgw command line arguments

All of the parameters in the preceding section can be specified as options for the opswgw command. For example, the opswgw.Gateway foo entry in the Gateway Properties file is equivalent to the following command-line argument:

/opt/opsware/opswgw/bin/opswgw --Gateway foo

Command-line arguments override corresponding entries in the Gateway Properties file. In addition to the entries listed in the preceding section, the opswgw command can specify a Gateway Properties file as an argument; for example:

/opt/opsware/opswgw/bin/opswgw --PropertiesFile filename