Configuring liveGate

Before running liveGate on a server, the server's system administrator must first create a file - in the same directory - named "liveGateInit". The "liveGateInit" file specifies the remote endpoints of each multicast tunnel that's supported by this server. It contains one or more lines like the following:
liveGate_createTunnel foobar.example.com
In this example, "foobar.example.com" specifies the remote endpoint of a tunnel. (An IP address - i.e., in 'dotted quad' form - could have been used instead.)

Important note: The endpoint name (or address) must specify the source address of any packets that are sent to this server from the remote endpoint. (The reason for this is that the source addresses of incoming packets are used for validation.) This point is significant if the remote endpoint has more than one possible IP address.

The liveGate_createTunnel command has two extra, optional parameters:

   liveGate_createTunnel <endpoint> <destination port> <local port>
<destination port> - if present - specifies the port to which packets are sent, by liveGate, to reach the remote endpoint. <local port> - if present - specifies the port on which liveGate receives incoming packets from the remote endpoint. The default value for both ports is 10100.

Note for gurus: The "liveGateInit" file can contain any valid script in the Tcl scripting language. This means, for example, that you can set up multiple tunnels using scripts like the following:

foreach endpointMachineName {pluto snoopy dilbert) {
	liveGate_createTunnel $endpointMachineName.example.com
}
or
for {set hostNum 10} {$hostNum < 30} {incr hostNum} {
	liveGate_createTunnel 123.234.210.$hostNum
}

A tunnel that is not actively being used by the remote client consumes no resources other than about 100 bytes of memory. It's therefore OK to create several tunnels (within reason), even if they're rarely used.

For example, if your clients' IP addresses are dynamically assigned, you can create a tunnel for each possible source address that a client may have.

liveGate authenticates clients by their IP source address. (Note, however, that the tunneling protocol protects against IP source address spoofing.)

Creating dynamic tunnels

If, for some reason, it is not practical to use "liveGate_createTunnel" to create every possible tunnel, you can, instead use the liveGate_createDynamicTunnel command:
   liveGate_createDynamicTunnel <local port>
<local port> is optional (it defaults to 10100). This command (which can be used by licensed users only) causes a new tunnel to be created dynamically, whenever a packet is received from a new IP source address/port. This command is useful, for example, if the prospective tunnel endpoints are behind a NAPT ("network address and port translation") gateway, in such a way that makes it impossible to know, in advance, what source port(s) they will be using.

Important note: Note that the liveGate_createDynamicTunnel command allows potentially any host on the Internet to create a tunnel to your "liveGate" server.

Debugging

If you wish, you can turn on debugging output (to stderr) with an additional command:
liveGate_setDebugLevel <level>
where <level> is an integer 0 through 3. These levels of debugging output are as follows:
0 only serious internal errors are printed
1 (the default) as above, plus reports of bad packet data (see the note below), and the creation of new dynamic tunnels
2 as above, plus (static) tunnel creation/deletion and group join/leave events
3 as above, plus reports of all I/O
A liveGate_setDebugLevel command, if any, should occur at the start of the file, before any liveGate_createTunnel commands.

Alternatively, you can specify a debug level on the command line, e.g.

liveGate -d 2
(If there's also a "liveGate_setDebugLevel" command in the "liveGateInit" file, then it will override the command-line argument.)

Note: A "received packet from bad source" message indicates that an incoming packet had a source address (and/or source port) that is not a valid tunnel endpoint. This indicates that either

  1. the client is not a valid user of the tunneling service (i.e., a tunnel has not been specified for him), or
  2. a tunnel has been specified for this client, but with an address and/or port that was not the client's source address/port (see above)
The incoming packet is ignored in either case.

Configuring the built-in statistics web server


Return to the main liveGate page