tportknockd - tiny port knocking daemon - is a ligthweight portknocking Daemon. tportknockd does not need extra libraries like the capturing library libpcap. The special PACKET_MMAP interface of the PACKET socket interface from the linux kernel is used directly for packet capturing. Therefore the tportknockd is fast and small in size (ca. 30kbyte).

tportknockd can more than the classical portknocking with different ports. It can use different TCP-flag combinations instead of different ports for knocking (flag-knocking).






Reporting Bugs


Source: tportknockd-0.1.0.tar.gz (ca. 12kbyte)



-c <config> Give the configuration file with port knock sequences.
-C <config> Check the configuration file with port knock sequences for typos and syntax errors and display all sequences.
-i <device> Interface to listen on.
-r <sec> Refresh IP address - get every <sec> seconds the IP address from the device. This could be useful if the IP address changes periodically.
-l List all available network devices.
-d Debug
-D Daemon mode
-h Help


The knock-sequences to use is given with a configuration file to the tportknockd. This configuration file can contain many different knock-sequences for different actions.

Every knock-event has it's own configuration block. Every configuration block begins with <EVENT_NAME> and ends with </EVENT_NAME>. Each event must have a unique name.

Each event consists of a knock-sequence, timeout and an command (start_command) to execute after an successful knocking. Optionally a second command (stop_command) can be started after a delay (command_delay).

 <EVENT_NAME>                   # define an knock event with name "EVENT_NAME"
  sequence = {frame}*           # port knocking sequence
  timeout  = {in seconds}       # timeout for the knock sequence
  start_command = {command}     # command to execute after successfull knock
  stop_command  = {command}     # (optional) execute after command_delay
  command_delay = {in seconds}  # (optional) delay for execute end_command
 </EVENT_NAME>                  # end of knock event definition

A knock-sequence contains of a comma separated list of frames. For each frame of the sequence the protocol (TCP or UDP) and the port must be specified. For TCP-frames you can also set the TCP-flags or combinations of flags. Protocol, port and flags must be separated by a colon (:).

 frame     ::= protocol:port[:{tcp flags}*]
 protocol  ::= tcp|udp
 port      ::= 1..65535
 tcp flags ::= fsrpauxni

You can combine all flags of the next listing:

 tcp flags description:  f - Fin flag
                         s - Syn flag
                         r - Reset flag
                         p - Push flag
                         a - Ack flag
                         u - Urgent flag
                         x - X-mas (all flags set)
                         n - None (all flag cleared)
                         i - Ignore (ignore flags)

If no flags are given for a frame then the tportknockd will use n (None) flag implicitly.

You can use the string %IP% in the start_command and stop_command. This string will be substituted with the IP-address of the knocking host.

For performance purposes the knock-sequence should use ports and flag-combinations for the first frame which are not occur in usual netwok communication.

The configuration file should be checked for errors with the -C option!

 tportknockd -C knock.conf


In the first example the tportknockd has to receive the whole knock-sequence within 10 seconds to start the event. Then the firewall will be opened for the knocking host to access the local SSH server (it use TCP port 22 typically). After 30 seconds the firewall will be closed again but with a stateful firewall an established connection should keep alive.

 sequence      = udp:1234 tcp:543 tcp:543:i tcp:123:frap tcp:434:x tcp:2345:n
 timeout       = 10
 start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 22 -j ACCEPT
 stop_command  = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 22 -j ACCEPT
 command_delay = 30

In the next example the OpenVPN client will be started to connect to the knocking host.

 sequence      = tcp:12430:a tcp:2711:i tcp:123:i tcp:8375:n tcp:1155:n
 timeout       = 10
 start_command = /bin/openvpn --remote %IP% --config /opt/openvpn/client.conf

Sometimes the network communication is limited to a few ports, e.g. due to a firewall. In this case the classical portknocking with different ports is not possible. Then you can use different TCP-flag combinations to knock (flag-knocking).

 sequence      = tcp:110:x tcp:110:up tcp:110:up tcp:110:n tcp:110:i
 timeout       = 10
 start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 22 -j ACCEPT
 stop_command  = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 22 -j ACCEPT
 command_delay = 30



You must enable the CONFIG_PACKET_MMAP option in the linux kernel. The PACKET_MMAP interface is available with Linux 2.4 and 2.6. If you want capturing at high speeds (this is relative to the cpu speed), you should check if the device driver of your network interface card supports some sort of interrupt load mitigation or (even better) if it supports NAPI, also make sure it is enabled.

Build and Install

You can compile and install the tportknockd easily with make and make install from source code.

 make install

For big-endian-architectures the compiler flag -DBIG_ENDIAN must be set in the Makefile.


Reporting Bugs

Report bugs to <fibu at users.sourceforge.net>.


Copyright © 2008 Michael Finsterbusch

This is free software. You may redistribute copies of it under the terms of the License. The License is in the source code. There is NO WARRANTY, to the extent permitted by law.