tcprules

Section: User Commands (1)
Index Return to Main Contents

NAME

tcprules - compiles rules for tcpserver or sslserver.

SYNOPSIS

tcprules cdb tmp

DESCRIPTION

tcpserver and sslserver optionally follow rules to decide whether a TCP connection is acceptable. A 'rule' consists of the tokens 'address', 'instruction', and 'expression' telling for which 'address' a 'instruction' is provided following a set of optional expressions, providing some environment variables. The 'address' token can be given as IPv4/IPv6 address in CIDR format, or - if prepended with a equal sign (=) - a hostname/FQDN, to be subject of DNS qualification. Additionally, environment variables can be provided and are promoted for a particular connection. Environment variables may include ':' (colons).

Intructions are allow and deny.

IPv4 ADDRESSES BASED RULES

For example, the rule

: 18.23.0.32:deny prohibits connections from IP address 18.23.0.32. Ranges of IPv4 addresses can be defined in a class-dependend manner
: 18.:deny or by means of a range of contiguous addresses
: 18.23.0.1-22:ins or by using a CIDR notation. The rule
: 127./8:allow accepts any connections from the loopback net.
Note: Always IP addresses with the longest matching prefix are considered.

IPv6 ADDRESSES BASED RULES

tcprules understands compactified IPv6 addresses in standard CIDR notation. The rule

: 2001:de01:2:3:4:a:b:c:d:deny rejects any IPv6 packet from a single host while
: 2002::/48:deny can be used to block an entire IPv6 (sub-)net in case the net-prefix (here: /48) is provided.
Note: Since the IPv6 address on input is evaluated in its compactified format, simply include the final '::' for convenience. The resulting address is truncated to the specified number of prefix bits. tcprules currently does not understand IPv6 mapped IPv4 addresses
: ::ffff:a.b.c.d where
: a.b.c.d is the IPv4 addresses. In consequence, an IPv4 address will not match a rule for the corresponding IPv6-mapped address, and vice versa.

USAGE

tcprules reads rules from its standard input and writes them into cdb in a binary format suited for quick access by tcpserver. Typically

tcprules rules.cdb rules.tmp < rules.txt

tcprules can be used while tcpserver or sslserver is running. It ensures that cdb is updated atomically. It does this by first writing the rules to tmp and then moving tmp on top of cdb. If tmp already exists, it is destroyed. The directories containing cdb and tmp must be writable to tcprules; they must also be on the same filesystem.

If there is a problem with the input or with tmp, tcprules complains and leaves cdb alone.

The binary cdb format is portable across machines.

RULE FORMAT

A rule is one line. A file containing rules may also contain comments: lines beginning with # are ignored.

Each rule contains an address, a colon, an instruction, and optionally a comma-separated list of expressions, with no extra spaces. When tcpserver receives a connection from that address, it follows the instruction and evaluates the expressions.

ADDRESS TOKENS

tcpserver looks for rules with various addresses:

1.

$TCPREMOTEINFO@$TCPREMOTEIP, if $TCPREMOTEINFO is set;

2.

$TCPREMOTEINFO@=$TCPREMOTEHOST, if $TCPREMOTEINFO is set and $TCPREMOTEHOST is set;

3.

$TCPREMOTEIP;

4.

=$TCPREMOTEHOST, if $TCPREMOTEHOST is set;

5.

shorter and shorter prefixes of $TCPREMOTEIP ending with a dot;

6.

$TCPREMOTEIP/PREFIX considering in order the longest matching provided PREFIX;

7.

shorter and shorter suffixes of $TCPREMOTEHOST starting with a dot, preceded by =, if $TCPREMOTEHOST is set;

8.

=, if $TCPREMOTEHOST is set; and finally

9.

the empty string. tcpserver uses the first rule it finds. You should use the -p option to tcpserver or sslserver if you rely on $TCPREMOTEHOST here.

For example, here are some rules:

     joe@127.0.0.1:first
     18.23.0.32:second
     :third
     127.:fourth

If $TCPREMOTEIP is 10.119.75.38, tcpserver will follow the third instruction.

If $TCPREMOTEIP is 18.23.0.32, tcpserver will follow the second instruction.

If $TCPREMOTEIP is 127.0.0.1 and $TCPREMOTEINFO is bill, tcpserver will follow the fourth instruction.

If $TCPREMOTEIP is 127.0.0.1 and $TCPREMOTEINFO is joe, tcpserver will follow the first instruction.

You can use tcprulescheck to see how tcpserver will interpret rules in cdb.

INSTRUCTIONS

The instructions in a rule must be either allow or deny. deny tells tcpserver to drop the connection without running anything. For example, the rule

: :deny tells tcpserver to drop all connections that aren't handled by more specific rules.
The rule may continue with further expressions used as environment variables, in the form var=x. tcpserver and sslserver adds an environment variable $var with value x. For example,
: 10.0.:allow,RELAYCLIENT="@fix.me" adds an environment variable $RELAYCLIENT with value @fix.me. The quotes may be replaced by any repeated character:
: 10.0.:allow,RELAYCLIENT=/@fix.me/ Any number of variables may be listed:
: 127.0.0.1:allow,RELAYCLIENT="",TCPLOCALHOST="movie.edu"

This document was created by man2html, using the manual pages.
Time: 13:39:03 GMT, July 14, 2025