.TH PLUG-GW 8 "August 2007" "OpenFWTK" .SH NAME plug-gw \- plug proxy .SH SYNOPSIS .B plug-gw [ .BI "-daemon " ] [ .BI "-fastdaemon " ] [ .BI "-as " ] .I service .SH DESCRIPTION .IX "plug-gw" "" "\(em plug proxy" 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: .IP \(bu 4n LDAP searches .IP \(bu 4n webster .IP \(bu 4n whois .PP 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. .PP For each version of the plug proxy, you can configure the proxy to allow connections based on: .IP \(bu 4n source IP address .IP \(bu 4n source host name .IP \(bu 4n source port .IP \(bu 4n destination IP address .IP \(bu 4n destination host name .IP \(bu 4n destination port .PP 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. .PP The firewall runs different instances of the plug proxy .RB "(" plug-gw ")" as daemons (invoked from .IR "/etc/rc.local" ) on different ports for different applications, based on the information in the .I /etc/services and .I /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. .PP Whenever the system receives a request on one of these ports, the plug proxy checks its configuration information (in the .IR "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. .PP The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd). .IR "-daemon" parameter should be omitted in this case. .PP 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. .PP .SS 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. .SH OPTIONS .SS Command Line Options The plug proxy recognizes the following command line options (whether started from the command line or from within .IR /etc/rc.local ): .TP .BI "-daemon " port Indicates that the plug proxy runs as a daemon, and the port (name or number) on which the plug proxy listens. When .IR "-daemon" option is used, configuration is being read from .IR netperm-table for every new connection accepted by proxy. .TP .BI "-fastdaemon " port Indicates that the plug proxy runs as a daemon, and the port (name or number) on which the plug proxy listens. When .IR "-fastdaemon" option is used, configuration is being read from .IR netperm-table once the daemon starts or if .IR SIGHUP is received. .TP .I service Indicates the name of the service the plug proxy connects as. .TP .B -version Displays version information for the plug proxy on stdout. .SS Configuration Options The plug proxy reads configuration rules from the .IR "/usr/local/etc/netperm-table" . It reads all rules using the .B plug-gw (or the name specified with the -as option) and .B * (wildcard) keywords. The plug proxy reads the .I 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 .BR "netperm-table" (5) for a more complete explanation of .I netperm-table syntax and precedence. .PP The plug proxy recognizes the following attributes: .RS .TP .BI "groupid " group Specifies the name of the group the plug proxy uses when running. .RS .TP .I group Specifies either a name or numeric id from the .I /etc/group file. .RE .TP .BI "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 .B /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 .TP .BI "hosts " "host-pattern [host-pattern..] [options]" Sub-options are: .IP .BI "\-authuser " username treat connection as authenticated with user name (for extended permissions) .IP .BI "\-authreq " username authenticate via SSO keepalive request to authentication console .IP .B \-extnd specifies that the proxy should request extended authorization from authsrv .IP .BI "\-client-dscp " dscp-tag-name .br .BI "\-client-dscp " dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for client to proxy connection. .IP .BI "\-server-dscp " dscp-tag-name .br .BI "\-server-dscp " dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for proxy to server connection. .IP .B \-plug-to .I host specifies the name or address of the host to connect to. This option is mandatory. .IP .B \-transparent select destination from tranparency engine .IP .B \-privport indicates that a reserved port number should be used when connecting. Reserved port numbers must be specified for protocols like .B rlogin which rely on them for "security." .IP .BI "\-port " portid specifies a different port. The default port is the same as the port used by the incoming connection. .IP .B \-ssl-client If the proxy is compiled with SSL, enable ssl/tls on client socket .IP .B \-ssl-server If the proxy is compiled with SSL, enable ssl/tls on server socket .IP .B \-client-verify If the proxy is compiled with SSL, verify client certificate .IP .B \-server-verify If the proxy is compiled with SSL, verify server certificate .RE .TP .BI "private-key " file Specifies SSL proxy private key file .TP .BI "certificate " file Specifies SSL proxy certificate chain .TP .BI "CAfile " file Specifies SSL proxy CA .TP .BI "timeout " seconds Specifies the number of seconds the plug proxy is idle (with no network activity) before disconnecting. .TP .BI "userid " user Specifies the user ID the proxy uses when running. .RS .TP .I user Specifies either a name or numeric id from the .I /etc/passwd file. .RE .SH EXAMPLES This example shows the configuration lines in the .I netperm-table for a one-to-one connection from inside to outside: .sp 1 .nf .na .RS .sp 1 # 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 .RE .fa .fi .SH FILES .IP /etc/rc.local Command script that controls automatic reboot, and includes startup information for the plug proxy. .IP /usr/local/etc/netperm-table The network permissions file contains configuration information for the Firewall Toolkit, including the plug proxy. .SH NOTES .LP Since incoming connection hosts can be wildcarded, .B 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 .B 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. .SH BUGS .LP 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. .SH AUTHOR ArkanoiD. .SH SEE ALSO .BR netperm-table "(5), " rc "(8)"