knockd(1)																 knockd(1)

NAME

       knockd - port-knock server

SYNOPSIS

       knockd [options]

DESCRIPTION

       knockd is a port-knock server.  It listens to all traffic on an ethernet (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 destined 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.

COMMANDLINE OPTIONS

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

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

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

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

CONFIGURATION

       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.

	      [options]
		   logfile = /var/log/knockd.log

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

	      [closeSSH]
		   sequence    = 9000,8000,7000
		   seq_timeout = 10
		   tcpflags    = syn
		   command     = /usr/sbin/iptables -D INPUT -s %IP% -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.

	      [options]
		   logfile = /var/log/knockd.log

	      [opencloseSSH]
		   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 trigger an event, but a set of sequences taken from a sequence file (one
	      time sequences), specified by the one_time_sequences directive.  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).

	      [options]
		   logfile = /var/log/knockd.log

	      [opencloseSMTP]
		   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

CONFIGURATION
: GLOBAL DIRECTIVES
       UseSyslog
	      Log action messages through syslog().  This will insert log entries 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: /var/run/knockd.pid.

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

CONFIGURATION
: KNOCK/EVENT DIRECTIVES
       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 sequence 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 recommended that you leave a space at the beginning of each line.  Otherwise
	      the first digit in your knock sequence will be overwritten 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 direc-
	      tive.  Lines beginning with a '#' character will be ignored.

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

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

       TCPFlags = fin|syn|rst|psh|ack|urg
	      Only pay attention to packets that have this flag set.  When using 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  usually  inter-
	      fere 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 correct port-knock.  All instances of %IP%  will  be  replaced  with  the
	      knocker's IP address.  The Command directive is an alias for Start_Command.

       Cmd_Timeout = <timeout>
	      Time to wait between Start_Command and Stop_Command in seconds.  This directive 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 directive is optional.

SECURITY NOTES

       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 running 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.

SEE ALSO

       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.

AUTHOR

       Judd Vinet <jvinet@zeroflux.org>

knockd 0.5							   June 26, 2005							 knockd(1)