PLUG-GW(8)

NAME
plug-gw - plug proxy

SYNOPSIS
plug-gw [ -daemon <port> ] [ -fastdaemon <port> ] [ -as <tag> ] service

DESCRIPTION
The Firewall Toolkit plug proxy is an application level proxy that provides configurable access control, authentication and logging mechanisms. The plug proxy, which runs on the firewall, passes LDAP or other TCP-based application requests through the firewall (at the application level), using rules you supply. You can configure instances of the plug proxy to service:

•   LDAP searches

•   webster

•   whois

This is not an exhaustive list. The plug proxy is protocol neutral, so you can tunnel a variety of other TCP-based applications. Weigh the risks carefully for each application.

For each version of the plug proxy, you can configure the proxy to allow connections based on:

•   source IP address

•   source host name

•   source port

•   destination IP address

•   destination host name

•   destination port

All packets, and therefore all application requests go to the firewall. On the firewall, the plug proxy software relays information from one side of the firewall to the other. The proxy prevents the applications on outside networks from talking directly with the applications on your inside network, and vice versa. No IP packets pass from one side of the firewall to the other. All data is passed at the application level.

The firewall runs different instances of the plug proxy (plug-gw) as daemons (invoked from /etc/rc.local) on different ports for different applications, based on the information in the /etc/services and /etc/rc.local files. These files indicate which services the firewall should run on which ports. For example, the firewall runs an instance of the plug proxy on port 389 to handle LDAP requests.

Whenever the system receives a request on one of these ports, the plug proxy checks its configuration information (in the netperm-table) and determines whether the initiating host has permission to initiate this type of request. If the host does not have permission, the plug daemon logs the connection attempt and displays an error message.

The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd). -daemon parameter should be omitted in this case.

If the host has permission, the proxy logs the transaction and passes the request to the destination host. The plug proxy remains active until either side closes the connection.

  WARNING:
Allowing proprietary protocols through your firewall is a really big unknown. Because the protocols are proprietary, the firewall and the proxy have no idea what sorts of data or requests the applications are sending. Nor do we have any idea how safe the actual application is. Do not use the plug proxy for proprietary protocols without first performing a risk assessment.

OPTIONS

  Command Line Options
The plug proxy recognizes the following command line options (whether started from the command line or from within /etc/rc.local):

-daemon port
    Indicates that the plug proxy runs as a daemon, and the port (name or number) on which the plug proxy listens. When -daemon option is used, configuration is being read from netperm-table for every new connection accepted by proxy.

-fastdaemon port
    Indicates that the plug proxy runs as a daemon, and the port (name or number) on which the plug proxy listens. When -fastdaemon option is used, configuration is being read from netperm-table once the daemon starts or if SIGHUP is received.

service
    Indicates the name of the service the plug proxy connects as.

-version
    Displays version information for the plug proxy on stdout.

  Configuration Options
The plug proxy reads configuration rules from the /usr/local/etc/netperm-table. It reads all rules using the plug-gw (or the name specified with the -as option) and * (wildcard) keywords. The plug proxy reads the netperm-table from top to bottom. If there are multiple rules in the table that could apply for a particular attribute, the plug proxy uses the first one that it finds. See netperm-table(5) for a more complete explanation of netperm-table syntax and precedence.

The plug proxy recognizes the following attributes:

    groupid group
        Specifies the name of the group the plug proxy uses when running.

        group
            Specifies either a name or numeric id from the /etc/group file.

    port portid host-pattern [options]
        It is the legacy way (included for TIS fwtk compatibility) to specify a connection rule. When a connection is made, a match is searched for on the port-id and calling host. The port-id may be either a numeric value (e.g.: 119) or a value from /etc/services (e.g.: "nntp"). If the calling port matches, then the host-pattern is checked for a match, following the standard address matching rules employed by the firewall. If the rule matches, the connection will be made based on the remaining options in the rule, all of which begin with '-'. The more unified and recommended connection rule form is

    hosts host-pattern [host-pattern..] [options]
        Sub-options are:

        -authuser username treat connection as authenticated with user name (for extended permissions)

        -authreq username authenticate via SSO keepalive request to authentication console

        -extnd specifies that the proxy should request extended authorization from authsrv

        -client-dscp dscp-tag-name
        -client-dscp dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for client to proxy connection.

        -server-dscp dscp-tag-name
        -server-dscp dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for proxy to server connection.

        -plug-to host specifies the name or address of the host to connect to. This option is mandatory.

        -transparent select destination from tranparency engine

        -privport indicates that a reserved port number should be used when connecting. Reserved port numbers must be specified for protocols like rlogin which rely on them for "security."

        -port portid specifies a different port. The default port is the same as the port used by the incoming connection.

        -ssl-client If the proxy is compiled with SSL, enable ssl/tls on client socket

        -ssl-server If the proxy is compiled with SSL, enable ssl/tls on server socket

        -client-verify If the proxy is compiled with SSL, verify client certificate

        -server-verify If the proxy is compiled with SSL, verify server certificate

private-key file
    Specifies SSL proxy private key file

certificate file
    Specifies SSL proxy certificate chain

CAfile file
    Specifies SSL proxy CA

timeout seconds
    Specifies the number of seconds the plug proxy is idle (with no network activity) before disconnecting.

userid user
    Specifies the user ID the proxy uses when running.

    user
        Specifies either a name or numeric id from the /etc/passwd file.

EXAMPLES
This example shows the configuration lines in the netperm-table for a one-to-one connection from inside to outside:

    # allows one host inside to connect to one host outside
    qotd-gw: port qotd 10.0.1.12 -plug-to info.bigu.edu -port qotd

FILES

/etc/rc.local
    Command script that controls automatic reboot, and includes startup information for the plug proxy.

/usr/local/etc/netperm-table
    The network permissions file contains configuration information for the Firewall Toolkit, including the plug proxy.

NOTES

Since incoming connection hosts can be wildcarded, plug-gw works well in a many-to-one relationship but does not work at all in a one-to-many relationship. If, for example, a site has 3 news feeds - it is easy to configure plug-gw to plugboard any connections from those 3 hosts to an internal news server, but unless there are multiple instances of plug-gw on different ports, and the internal news server's software can support connecting on a non-standard port, modification to software will be required.

BUGS

Report bugs to arkenoi@gmail.com or fwtk-users@buoy.com mailing list. Include a complete example, explaining what you expected to happen and what actually happened. Be sure to indicate the type of system (operating system, hardware, etc.) you are using, as well as the version of the plug proxy.

AUTHOR
ArkanoiD.

SEE ALSO
netperm-table(5), rc(8)