tcprules

## Name

tcprules — compile rules for tcpserver(1)

## Synopsis

`tcprules` {`cdb`} {`tmp`}

## Description

tcpserver(1) optionally follows rules to decide whether a TCP connection is acceptable.

For example, the rule

    192.0.2.32:deny

prohibits connections from IP address 192.0.2.32.

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

tcprules can be used while tcpserver(1) 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, and a list of instructions, with no extra spaces. When tcpserver(1) receives a connection from that address, it follows the instructions.

### Addresses

tcpserver(1) looks for rules with various addresses:

- `TCPREMOTEINFO`@`TCPREMOTEIP`, if `TCPREMOTEINFO` is set;

- `TCPREMOTEINFO`@=`TCPREMOTEHOST`, if `TCPREMOTEINFO` is set and `TCPREMOTEHOST` is set;

- `TCPREMOTEIP`;

- =`TCPREMOTEHOST`, if `TCPREMOTEHOST` is set;

- shorter and shorter prefixes of `TCPREMOTEIP` ending with a dot;

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

- =, if `TCPREMOTEHOST` is set; and finally

- the empty string.

### Caution

`TCPREMOTEINFO` and `TCPREMOTEHOST` are attacker-supplied or attacker-controlled data. Avoid setting up rules that use these variables.

tcpserver(1) uses the first rule it finds. You should use the [-p] option to tcpserver(1) if you rely on `TCPREMOTEHOST` here.

For example, here are some rules:

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

If `TCPREMOTEIP` is 10.119.75.38, tcpserver(1) will follow the third instructions.

If `TCPREMOTEIP` is 192.0.2.32, tcpserver(1) will follow the second instructions.

If `TCPREMOTEIP` is 127.0.0.1 and `TCPREMOTEINFO` is bill, tcpserver(1) will follow the fourth instructions.

If `TCPREMOTEIP` is 127.0.0.1 and `TCPREMOTEINFO` is joe, tcpserver(1) will follow the first instructions.

You can use tcprulescheck(1) to see how tcpserver will interpret rules in `cdb`.

### Address ranges

tcprules treats `203.0.113.37-53:ins` as an abbreviation for the rules `203.0.113.37:ins`, `203.0.113.38:ins`, and so on up through `203.0.113.53:ins`. Similarly, `10.2-3.:ins` is an abbreviation for `10.2.:ins` and `10.3.:ins`.

### Instructions

The instructions in a rule must begin with either `allow` or `deny`. `deny` tells tcpserver(1) to drop the connection without running anything.

The instructions may continue with some environment variables, in the form `var="x"`. tcpserver(1) adds an environment variable `var` with value `x`.

#### Examples

>     :deny

tells tcpserver(1) to drop all connections that aren't handled by more specific rules.

>     :allow,AXFR=""
>     203.0.113.90:allow,AXFR="example.com,example.org,example.net,example"
>     10.0.53.1:allow,AXFR="test,home.arpa"

tells tcpserver(1) to allow all connections that aren't handled by more specific rules, and always set the `AXFR` environment variable to something.

>     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"

## See also

tcpserver(1)
tcprulescheck(1)
argv0(1)
fixcrio(1)
recordio(1)
rblsmtpd(1)
tcpclient(1)
who@(1)
date@(1)
finger@(1)
http@(1)
tcpcat(1)
mconnect(1)
tcp-environ(5)

## Author

Original code and documentation by Daniel J. Bernstein. Converted to manual pages and updated by Gerrit Pape in 2000, 2001, and 2002. Converted to DocBook XML by Jonathan de Boyne Pollard.