tumbler is a protocol that enables a client piece of software to securely tell a server process on a remote machine to execute a predetermined command. tumbler is similar to port knocking and is designed so that a remote user can securly and steathily enable and disable server processes, or open and close firewall holes on a computer connected to the Internet.

It differs from port knocking in the following ways:

  1. Uses a single port: the tumblerd listens on a single UDP port for a single UDP datagram containing the 'knock' on the door.
  2. Secure: the 'knock' is an SHA-256 hash the includes a shared secret (similar to a password) and other information to prevent spoofing and replay attacks.
  3. Generic: the 'knock' can cause any command to be executed and is not limited to firewall reconfiguration.
There are two implementations available: one is in Perl and provides both a client (tumbler) and daemon (tumblerd); the other is in Java and provides an API for generating knocks.

[Project Page] [Download] [JavaDoc of TumblerKnock]

The Perl implementation is discussed below.


A secure knock can be set up that opens and closes a hole in the firewall using iptables for an SSH server. When the user knocks on the open door the firewall is reconfigured to allow external connections on port 22, when the user knocks on the close door then the port is closed.

First set up the appropriate tumbler.conf (by default /etc/tumblerd.conf):

# Comments start with #
# The common section contains configuration options
# for the tumblerd daemon, here we set the UDP
# port to listen on to 8675 and a log file

    port = 8675
    log  = /var/log/tumblerd.log

# Each door that a user can knock on is defined by
# a unique [door-X] section, the first section is
# for opening the SSH port, and second for closing
# Each door has a secret (i.e. the password for this
# door that is part of the knock) and a command to
# execute.
# In the command it's possible to use the macros
# %IP% for the IP address of the person who knocked and
# %NAME% for the name of the door (in the first door
# here the name is open-ssh)
# %USER% for the user name of the user opening the door
# if present

    secret  = open-pAsSwOrD
    jgc.secret = password
    command = /usr/sbin/iptables -A INPUT -p tcp -s %IP% --dport 22 -j ACCEPT
    secret  = close-pAsSwOrD
    command = /usr/sbin/iptables -D INPUT -p tcp -s %IP% --dport 22 -j ACCEPT

Then run tumblerd (or tumblerd --config /path/to/file if the config file isn't in the standard place).

To knock on the open door the remote user does the following:

tumbler --open tumbler://host:8675/

where host is the host on which tumblerd is running. The user will be prompted for the secret (in this case open-pAsSwOrD). Alternatively it's possible to specify the secret on the command line as follows:

tumbler --open tumbler://open-pAsSwOrD@host:8675/

That's it.

To close the port again the user would use the close-ssh door's secret.

TUMBLER protocol

The tumbler protocol consists of a single message sent as a UDP datagram that contains a string identifying the tumbler protocol version (currently 2) and a hash value. For example,

TUMBLER2: 844c17eee03d848cc0a60e90f608d5ea11f417d9bf0d2c1af2b52c665245bf22

The hash is a SHA 256 secure hash of the following three items:

  1. The current zulu date/time in minutes
  2. The IP address of the sender of the message
  3. The secret
  4. An optional (added in v2) user name

The inclusion of the IP address of the sender means that a sniffed message cannot be reused from a different IP address, the inclusion of the time means that messages automatically expire and the inclusion of the secret means that an attacker needs to obtain the password.

Hence the security of tumbler is the same as password security: choose a good secret for each door and change it often! The tumblerd implementation prevents the reuse of a hash within the same minute so that each command is only executed once.

If tumblerd determines that the hash is valid it executes the associated command. There is no response positive or negative to the sending of a message.

tumblerd documentation

The simplest invocation of tumblerd is:
and it will read the configuration file /etc/tumblerd.conf. tumblerd also has two command line options. Once invoked tumblerd listens for messages until terminated.


The configuration file (default /etc/tumblerd.conf) consists of sections that start with a line of the form [section]. Currently there are only two valid section types [common] (for options that affect the overall tumblerd daemon) and [door-X] (which define a door with name X).

Blank lines and anything after a # are ignored in the configuration file.

Within each section configuration parameters in the form param = val are accepted. Whitespace is stripped before and after the parameter name and value.

Each section has certain permitted parameters:

See the example above for a complete configuration file.

tumbler client documentation

The tumbler client has the following command line options:
tumbler was created by John Graham-Cumming who wrote the Perl implementation. Marty Lamb wrote the Java implementation.

Copyright (c) 2004 John Graham-Cumming.

SourceForge.net Logo