.\" Copyright (c) 1993,1996 Trusted Information Systems, Inc. .\" All rights reserved. .\" .\" .TH NETPERM-TABLE 5 "March 2007" "OpenFWTK" .SH NAME netperm-table \- configuration file for Firewall Toolkit proxies and utilities .SH DESCRIPTION The network permissions table .RI "(" netperm-table ")" contains configuration information for the Firewall Toolkit. The proxies and other applications read their configuration information from this table. The rules in the table include two types of information: generic proxy rules and application-specific rules. .PP The permissions/configuration file is organized into rules, one rule per `logical' line of text (`logical' line is single line of text with possible continualtion lines, which are specified by escaping trailing LF with `\\'. The first part of each rule is the name of the application that rule applies to, followed by a colon. Multiple applications can be targeted by a single rule, by separating the names with commas, or wildcarding them with an asterisk. When an application extracts its configuration information, it only extracts the rules that apply to it, preserving the order in which they appeared in the file. For example, if the application .B smtpd read its configuration rules, the following would all match: .sp 1 .nf .na # sample rules for smtpd smtpd, smtpfwdd: userid 4 smtpd, smtpfwdd: directory /mail/inspool smtpd: timeout \\ 3600 .fi .ad .LP Comments can be inserted in the configuration file by starting the line with '#' as the first character. .LP Once an application has matched a rule, the rule is tokenized into whitespace-delimited strings for later application specific use. Typically, the application retrieves matching rules based on the first word in the rule; the remaining words serve as parameters to that clause. Special modifiers are recognized for each clause, if it begins with a .B permit- or .B deny- the rule is internally flagged as granting or revoking permission for that clause. I.e., if an application retrieves all of its configuration clauses for "hosts", the following will be returned: .sp 1 .nf .na netacl-in.ftpd: permit-hosts 192.33.112.117 -exec /usr/etc/in.ftpd netacl-in.ftpd: permit-hosts 198.137.240.101 -exec /usr/etc/in.ftpd netacl-in.ftpd: deny-hosts unknown netacl-in.ftpd: deny-hosts * .fi .ad .sp 1 Some application may read more than one application name tag, applying specific policies when needed. A common example is squid-gw, which allows policies to be defined depending on multiple conditions: .sp 1 .nf .na squid-gw: permit-hosts 10.0.0.* -class int squid-gw-int: block -force javascript .fi .ad .SH NETPERM-TABLE SYNTAX .SS Precedence Applications and proxies read the tables from the top of the table to the bottom. They use the first rule that applies for a particular attribute. If there are multiple rules in the table that could apply for an attribute, the application uses the first one it finds. For example, a .I netperm-table contains the following rule: .sp 1 .nf .na .RS smtpd: userid uucp .RE .fa .fi .PP and later in the file contains the rule: .sp 1 .nf .na .RS smtpd: userid mail .RE .fa .fi .PP When .B smtpd parses the .IR netperm-table , it will use the first rule it finds, and run as the user uucp. .SS Format Each line in the .I netperm-table contains a separate configuration rule in the format: .sp 1 .I keyword: attribute valuelist .sp 1 where: .RS .TP .I keyword indicates the application to which the rule on that line applies. The wildcard (*) indicates the rule is valid for all applications and proxies. Comma separated lists of multiple keywords indicates the rules apply to the proxies or applications listed. The keyword usually matches the name of the service in the .I /etc/rc.local file. .TP .I attribute is a configuration parameter for that application or proxy. .TP .I valuelist is the value for the specific configuration parameter. Some attributes allow multiple values. .RE .PP A rule must fit on a single line. The length of a line varies by operating system, but is generally around 1,024 bytes. There is no provision for continuing lines. .PP Whitespace and tabs are both valid separators. .SS Macros Much like cpp(1) or m4(1), macros can be defined that will later be expanded in context. Macro names must start with a letter, and may contain letters, digits and underscores. Macros are not expanded inside quotes. Macro processing is designed to be compatible with global object definitions which may be used in system-wide configuration, say, controlling OpenBSD's pf and other. Plese note that macro expands exactly as it was defined, thus, if there is a configuration line where a group of parameters must be embraced with brackets, you should place it around the macro call. .nf .na .sp 1 MYNETWORK = 192.168.1.0/255.255.255.0 ftp-gw: TRUSTEDSERVERS="10.1.1.2 10.1.1.5" ftp-gw: permit-hosts $MYNETWORK -dest { $TRUSTEDSERVERS } .fi .ad .sp 1 As seen on the example above, macro definitions may exist in global namespace or may be keyword-bound. .SS Includes "include" statement followed by filename requests other netperm-table file to be included into rules processing. Example: .nf .na .sp 1 include PREFIX/etc/netperm-squid-gw.txt .fi .ad .sp 1 Failure when reading an included file is treated as fatal error. .SS Comments A hash mark (#) at the beginning of a line indicates a comment. Applications ignore any text between the # and the end of the line. .SH CONVENTIONS .LP Much of the usage of the .B netperm-table is application specific, but where possible, several conventions are enforced. When a host name or host IP address is given to match against, matching is performed based on whether the pattern to match against is all digits and decimal points, or whether it contains other characters. If the pattern to match against is entirely digits and decimals, matching is performed against the IP address, otherwise it is performed against the hostname. Generally, to prevent being vulnerable to DNS spoofing, one should use configuration rules based on IP addresses. When matching, asterisk wildcards are supported, with syntax similar to the shell's, matching as many characters as possible. When resolving IP addresses to DNS names, if the reverse lookup fails, the host name is set to "unknown." When resolution is performed, a check is made to ensure that the IP address for the DNS name returned by the reverse lookup is the same. If it is not, the host name is set to "unknown" and a warning is logged. This permits rules to specifically operate on hosts that didn't have valid DNS mappings. Thus: .sp 1 .nf .na 192.33.* will match against IP address *.tis.com will match against host name unknown will match against hosts not in the DNS .fi .ad .LP Note that sites using NIS or other resolver systems where the .I gethostbyaddr library routine returns a non-fully-qualified domain name will have problems generating a matching rule using their domain name. In this case, the numeric IP address should be used. In general, using IP addresses will provide better security, by removing the threat of DNS spoofing attacks. When IP-based address pattern is specified, it is possible to use generic netmask-based network definitions, like: .sp 1 .nf .na 10.0.0.0/255.255.255.0 will match C class network 10.0.0 .fi .ad .LP Other common configuration parameters (besides hostnames described above), being covered by specific proxy manuals, may include: .TP .I integers - as decimal values, .TP .I strings - tokenized in generic way, so if a string includes whitespace it should be embraced with quotation marks, .TP .I lists - any application with parameter that uses "values list" should employ { item [item..] } format, using space as separator. Individual values may be negated (excluded from list) with "!" prefix. .TP .I user and group ids - as numeric values or system-provided names, .TP .I tcp/ip ports - as numeric values or service names, .TP .I DSCPs - (diffserv codepoints) - ToS/QoS byte in decimal, octal (0 prefix) or hexadecimal (0x prefix) format, or symbolic reference to diffserv-codepoint line, like: .nf .na .sp 1 ftp-gw: permit-hosts 192.168.1.* -serverdata-dscp throughput ftp-gw: diffserv-codepoint throughput 0x08 .fi .ad .sp 1 .TP .I content-types - in type/subtype format, wildcards may apply, .TP .I content inspection servers - at the moment only Milter protocol is supported, and milter specification looks like unix:/path-to-unix-socket or inet:port@host. .SH DIAGNOSTICS .LP Syslog error messages are generated by malformed lines, including lines that are missing the application name or colon, lines that are missing any clause following the colon, lines that have too many tokens, or a memory allocation error. .SH FILES .PD 0 .TP 20 .B PREFIX/etc/netperm-table .PD .SH CAVEATS .LP The location of .B netperm-table is compiled into the components of the firewall toolkit. Its location may change, depending on compile time options. .LP Applications in the toolkit that attempt to open .B netperm-table and fail will exit with a warning in syslog. .SH FILES .IP PREFIX/etc/netperm-table The network permissions file contains configuration information for the Firewall Toolkit .SH BUGS Report bugs to ark@eltex.net or fwtk-users@buoy.com. 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 .IR netperm-table . .SH SEE ALSO .BR authmgr "(8), " "authsrv "(8), " .BR ftp-gw "(8), " .BR plug-gw "(8), " rlogin-gw "(8), " .BR smtpd "(8), " smtpfwdd "(8), " tn-gw "(8), " .BR x-gw "(8), " .BR hostmatch "(3), " peername "(3), " ip2name "(3), " namatch "(3), " .BR cfg_read "(3), " proxy_init "(3), " cfg_get "(3) " .SH HISTORY netperm-table file format was introduced by TIS; macros and continuation lines are OpenFWTK extensions. Gauntlet netperm-table shares the same basic syntax, but the proxy control differs so it is not compatible.