Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
knockd(1)							     knockd(1)

       knockd -	port-knock server

       knockd [options]

       knockd  is a port-knock server.	It listens to all traffic on an	ether-
       net (or PPP) interface, looking for special "knock" sequences of	 port-
       hits.   A client	makes these port-hits by sending a TCP (or UDP)	packet
       to a port on the	server.	 This port need	not be open  --	 since	knockd
       listens	at the link-layer level, it sees all traffic even if it's des-
       tined for a closed port.	 When the server detects a  specific  sequence
       of  port-hits,  it  runs	 a  command defined in its configuration file.
       This can	be used	to open	up holes in a firewall for quick access.

       -i, --interface <int>
	      Specify an interface to listen on.  The default is fxp0.

       -d, --daemon
	      Become a daemon.	This is	usually	desired	for normal server-like

       -c, --config <file>
	      Specify  an  alternate location for the config file.  Default is

       -D, --debug
	      Ouput debugging messages.

       -l, --lookup
	      Lookup DNS names for log entries.	This may be a  security	 risk!
	      See section SECURITY NOTES.

       -v, --verbose
	      Output verbose status messages.

       -V, --version
	      Display the version.

       -h, --help
	      Syntax help.

       knockd  reads  all  knock/event	sets  from a configuration file.  Each
       knock/event begins with a title marker, in the form [name], where  name
       is  the	name  of  the  event  that  will appear	in the log.  A special
       marker, [options], is used to define global options.

       Example #1:
	      This example uses	two knocks.  The first will allow the  knocker
	      to access	port 22	(SSH), and the second will close the port when
	      the knocker is complete.	As you can see,	this could  be	useful
	      if  you  run a very restrictive (DENY policy) firewall and would
	      like to access it	discreetly.

		   logfile = /var/log/knockd.log

		   sequence    = 7000,8000,9000
		   seq_timeout = 10
		   tcpflags    = syn
		   command     = /usr/sbin/iptables -A INPUT -s	%IP% --dport 22	-j ACCEPT

		   sequence    = 9000,8000,7000
		   seq_timeout = 10
		   tcpflags    = syn
		   command     = /usr/sbin/iptables -D INPUT -s	%IP% --dport 22	-j ACCEPT

       Example #2:
	      This example uses	a single knock to control access  to  port  22
	      (SSH).   After receiving a successful knock, the daemon will run
	      the start_command, wait for the time specified  in  cmd_timeout,
	      then  execute the	stop_command.  This is useful to automatically
	      close the	door behind a knocker.	The knock sequence  uses  both
	      UDP and TCP ports.

		   logfile = /var/log/knockd.log

		   sequence	 = 2222:udp,3333:tcp,4444:udp
		   seq_timeout	 = 15
		   tcpflags	 = syn,ack
		   start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --syn -j ACCEPT
		   cmd_timeout	 = 5
		   stop_command	 = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --syn -j ACCEPT

       Example #3:
	      This example doesn't use a single, fixed knock sequence to trig-
	      ger an event, but	a set of sequences taken from a	sequence  file
	      (one time	sequences), specified by the one_time_sequences	direc-
	      tive.  After each	successful knock, the used  sequence  will  be
	      invalidated  and the next	sequence from the sequence file	has to
	      be used for a successful knock.  This prevents an	attacker  from
	      doing  a	replay	attack after having discovered a sequence (eg,
	      while sniffing the network).

		   logfile = /var/log/knockd.log

		   one_time_sequences =	/etc/knockd/smtp_sequences
		   seq_timeout	      =	15
		   tcpflags	      =	fin,!ack
		   start_command      =	/usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
		   cmd_timeout	      =	5
		   stop_command	      =	/usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 25 -j ACCEPT

	      Log action messages through syslog().  This will insert log  en-
	      tries into your /var/log/messages	or equivalent.

       LogFile = /path/to/file
	      Log actions directly to a	file, usually /var/log/knockd.log.

       PidFile = /path/to/file
	      Pidfile	 to    use    when    in    daemon    mode,   default:

       Interface = <interface_name>
	      Network interface	to listen on. Only its name has	to  be	given,
	      not the path to the device (eg, "fxp0" and not "/dev/fxp0"). De-
	      fault: fxp0.

       Sequence	= <port1>[:<tcp|udp>][,<port2>[:<tcp|udp>] ...]
	      Specify the sequence of ports in the special knock. If  a	 wrong
	      port  with  the  same flags is received, the knock is discarded.
	      Optionally, you can define the protocol to be used on a per-port
	      basis (default is	TCP).

       One_Time_Sequences = /path/to/one_time_sequences_file
	      File  containing	the one	time sequences to be used.  Instead of
	      using a fixed sequence, knockd will read the sequence to be used
	      from  that  file.	  After	each successful	knock attempt this se-
	      quence will be disabled by writing a '#' character at the	 first
	      position	of  the	 line containing the used sequence.  That used
	      sequence will then be replaced by	the next valid	sequence  from
	      the file.

	      Because  the  first character is replaced	by a '#', it is	recom-
	      mended that you leave a space at the  beginning  of  each	 line.
	      Otherwise	 the  first digit in your knock	sequence will be over-
	      written with a '#' after it has been used.

	      Each line	in the one time	sequences file	contains  exactly  one
	      sequence and has the same	format as the one for the Sequence di-
	      rective.	Lines beginning	with a '#' character will be ignored.

	      Note: Do not edit	the file while knockd is running!

       Seq_Timeout = <timeout>
	      Time to wait (in seconds)	for a sequence to complete in seconds.
	      If  the  time  elapses  before the knock is complete, it is dis-

       TCPFlags	= fin|syn|rst|psh|ack|urg
	      Only pay attention to packets that have this flag	set.  When us-
	      ing  TCP	flags, knockd will IGNORE tcp packets that don't match
	      the flags.  This is different than the normal behavior, where an
	      incorrect	 packet	would invalidate the entire knock, forcing the
	      client to	start over.  Using "TCPFlags = syn" is useful  if  you
	      are testing over an SSH connection, as the SSH traffic will usu-
	      ally interfere with (and thus invalidate)	the knock.

	      Separate	multiple   flags   with	  commas   (eg,	  TCPFlags   =
	      syn,ack,urg).   Flags  can  be explicitly	excluded by a "!" (eg,
	      TCPFlags = syn,!ack).

       Start_Command = <command>
	      Specify the command to be	executed when a	client makes the  cor-
	      rect  port-knock.	  All  instances of %IP% will be replaced with
	      the knocker's IP address.	 The Command directive is an alias for

       Cmd_Timeout = <timeout>
	      Time  to	wait between Start_Command and Stop_Command.  This di-
	      rective is optional, only	required if Stop_Command is used.

       Stop_Command = <command>
	      Specify the command to be	executed when Cmd_Timeout seconds have
	      passed  since Start_Command has been executed.  All instances of
	      %IP% will	be replaced with the knocker's IP address.   This  di-
	      rective is optional.

       Using  the  -l  or --lookup commandline option to resolve DNS names for
       log entries may be a security risk!  An attacker	may find out the first
       port  of	 a sequence if he can monitor the DNS traffic of the host run-
       ning knockd.  Also a host supposed to be	stealth	(eg, dropping  packets
       to  closed  TCP	ports  instead of replying with	an ACK+RST packet) may
       give itself away	by resolving a DNS name	if an attacker manages to  hit
       the first (unknown) port	of a sequence.

       knock  is  the  accompanying port-knock client, though telnet or	netcat
       could be	used for simple	TCP knocks instead.  For more advanced knocks,
       see hping, sendip or packit.

       Judd Vinet <>

knockd 0.5			 June 26, 2005			     knockd(1)


Want to link to this manual page? Use this URL:

home | help