Module Chainer

This module defines an abstract interface (class AbstractChainer) used by proxies to connect to their server endpoint, and some derived classes which fill the abstract class with some real function, most notably TransparentChainer and DirectedChainer.

Imported modules

Class AbstractChainer

Proxies are organized hierarchically, where the top level proxy is directly connected to server, and the low level proxy is connected to the upper level proxy. The term chaining means establishing the connection between a proxy and its parent. A chainer is a class responsible for chaining.

A chainer is only required for top level proxies, but may present in stacked ones too. The default chaining behaviour when there's no chainer defined (ie. self.session.chainer is None) is to pick up self.session.server_fd, which in turn gets set when the stacked proxy is started.

The task of chainers used for top level proxies is to connect to the target server.

Method connectServer

Function to perform chaining to the parent proxy or remote server.

Synopsis

connectServer (
        self,
        session,
        host,
        port,
        )

Description

This is an interface function to be called to chain up to the parent proxy (or to the remote server)

The parameters host and port are hints given by the proxy, they may be ignored (like in TransparentChainer) or taken into account (like in InbandChainer).

Arguments

Table 4-3. Arguments for AbstractChainer.connectServer()

self this instance
session Session object
host host to connect to (sockaddr).
port port to connect to

Exceptions

  • NotImplementedError

Method establishConnection

Function to actually establish a connection.

Synopsis

establishConnection (
        self,
        session,
        local,
        remote,
        )

Description

Internal function to establish a connection with the given local and remote addresses. It is used by derived chainer classes after finding out the destination address to connect to. This function performs access control checks.

Arguments

Table 4-4. Arguments for AbstractChainer.establishConnection()

self this instance
session Session object
local bind address
remote host to connect to

Exceptions

  • DACException

Returns

The fd of the connection to the server

Class DirectedChainer

This chainer connects to a predefined server determined at instance creation time, independently of the original destination of the connection request. It can be used to address a nonrouteable host from the firewall.

Attributes

Table 4-5. Attributes for class DirectedChainer

local The local data of the connection
remote The data of the server
forge_addrforge client address when connecting to the server

Examples

Example 4-1. Sample for DirectedChainer usage

            Service("inter_HTTP_dmz",
                    DirectedChainer(SockAddr(192.168.0.2, 80)),
                    HttpProxy)

Constructor __init__

Constructor to initialize a DirectedChainer instance.

Synopsis

__init__ (
        self,
        remote,
        local=None,
        forge_addr=0,
        )

Description

Sets instance attributes based on parameters.

Arguments

Table 4-6. Arguments for DirectedChainer.__init__()

self this instance
local Local address of the connection
remote Address of the server
forge_addrforge client address when connecting to the server

Method connectServer

Function to connect to the predefined remote server.

Synopsis

connectServer (
        self,
        session,
        host,
        port,
        )

Description

This function establishes connection to the remote server forging the client address if necessary.

Arguments

Table 4-7. Arguments for DirectedChainer.connectServer()

self this instance
session The data of the current session
host not used
port not used

Returns

The fd given by establishConnection

Class FailoverChainer

Failover chainer tries to connect several hosts in round robin fashion until one of them succeeds, forming a simple failover and load balance solution.

Attributes

Table 4-8. Attributes for class FailoverChainer

hosts The list of addresses to try
local the address of the local end of the connection
forge_addrforge client address
current_hostThe index of the actual host in the list

Constructor __init__

Constructor to initializes an instance of FailoverChainer

Synopsis

__init__ (
        self,
        hosts,
        local=None,
        forge_addr=0,
        )

Description

Sets attributes based on parameters.

Arguments

Table 4-9. Arguments for FailoverChainer.__init__()

self this instance
hosts The list of addresses to try
local address to bind to (Optional)
forge_addr forge client address (Optional)

Method connectServer

Called by the proxy to connect to the remote server.

Synopsis

connectServer (
        self,
        session,
        host,
        port,
        )

Description

Tries to connect to each host round-robin until one of them succeeds.

Arguments

Table 4-10. Arguments for FailoverChainer.connectServer()

self this instance
sessionThe data of the current session
host not used
port not used

Returns

The fd given by establishConnection

Method getHostAddress

Function to returns the actual host to attempt connection to.

Synopsis

getHostAddress ( self )

Description

Returns the actual current_host element of the host list hosts.

Arguments

Table 4-11. Arguments for FailoverChainer.getHostAddress()

selfthis instance

Returns

address to connect to

Method nextHost

Function to skip to the next host to try.

Synopsis

nextHost ( self )

Description

This function is called to skip to the next host to try in the hosts array. Increments current_host, zeroes it if overflowed.

Arguments

Table 4-12. Arguments for FailoverChainer.nextHost()

self this instance

Class InbandChainer

This chainer can be used for protocols where the target address is determined during the communication with the client. An example would be non-transparent HTTP where the target address is sent in the request.

Attributes

Table 4-13. Attributes for class InbandChainer

local the address of the local end of the connection
forge_addr use the client address for outgoing local address

Constructor __init__

Constructor to initialize an InbandChainer instance.

Synopsis

__init__ (
        self,
        local=None,
        forge_addr=0,
        )

Description

Creates an instance, sets its attributes based on constructor arguments.

Arguments

Table 4-14. Arguments for InbandChainer.__init__()

self this instance
local local address (optional)
forge_addrforge client address (optional)

Method connectServer

Function called by the proxy to connect to the remote end.

Synopsis

connectServer (
        self,
        session,
        host,
        port,
        )

Description

This function looks up the host given as parameter in the DNS and starts connecting there.

Arguments

Table 4-15. Arguments for InbandChainer.connectServer()

self this instance
session Session object
host Remote hostname as determined by the protocol
port Remote port as determinted by the protocol

Returns

The fd given by establishConnection

Class TransparentChainer

This chainer connects to the destination originally addressed by the client and is used for connections intercepted by the firewall.

You have to add a REDIRECT rule to your packet filter configuration to force connections going through your firewall to be serviced locally.

Make sure that the Listener port is protected by a DENY rule so that clients cannot connect to it directly, otherwise TransparentProxy may cause an infinite loop.

Attributes

Table 4-16. Attributes for class TransparentChainer

local bind address
forge_addr use client address as outgoing local address
forced_port if not 0 force it as destination port

Examples

Example 4-2. Sample for TransparentChainer usage

            Service("http", TransparentChainer(), HttpProxy)

Constructor __init__

Constructor to initialize a TransparentChainer instance.

Synopsis

__init__ (
        self,
        local=None,
        forge_addr=0,
        forced_port=0,
        )

Description

Sets various attributes as passed in as parameters.

Arguments

Table 4-17. Arguments for TransparentChainer.__init__()

self this instance
local local address, may be none (optional)
forge_addr if the client address shall be forged (optional)
forced_portuse this port on the remote server (optional)

Method connectServer

Function to connect to the remote server.

Synopsis

connectServer (
        self,
        session,
        host,
        port,
        )

Description

Finds out the original destination of the given connection and connects there.

Arguments

Table 4-18. Arguments for TransparentChainer.connectServer()

self this instance
session The data of the current session
host not used
port not used

Returns

The fd given by establishConnection