HONEYD(8)

NAME
honeyd - Honeypot Daemon

SYNOPSIS
honeyd [-dP] [-p fingerprints] [-f file] [-i interface] [net]

DESCRIPTION
honeyd creates virtual hosts for IP addresses matching the specified net. It can simulate any TCP service and replies to ICMP echo requests. Currently, all UDP ports are closed and honeyd will reply with an ICMP unreachable port message if the configured personality permits that.

This enables a single host to claim addresses on a LAN for network simulation.

In order for honeyd to receive network traffic for IP addresses that it should simulate, it is necessary to either explicitly route traffic to it, use proxy arp or run arpd(8) for unassigned IP addresses on a shared network.

honeyd exits on an interrupt or termination signal.

The options are as follows:

-d  Do not daemonize, and enable verbose debugging messages.

-P  On some operating systems, it is not possible to get event notifications for pcap via select(3). In that case, honeyd needs to run in polling mode. This flag enables polling.

-p fingerprints
    Read nmap style fingerprints. The names defined after the token are stored as personalities. The personalities can be used in the configuration file to modify the behaviour of the simulated TCP stack.

-f file
    Read the configuration in file. It is possible to create host templates with the configuration file that specify which servers should run and which scripts should be started to simulate them.

    The syntax is as follows:

        config	= creation | addition | binding | set | annotate | route [config]
        creation= "create" template-name | "create" "default"
        addition= "add" template-name proto "port" port-number action
        binding	= "bind" ip-address template-name |
        	  "clone" template-name template-name
        set	= "set" template-name "default" proto "action" action |
        	  "set" template-name "personality" personality-name |
        	  "set" template-name "personality" "random"
        	  "set" template-name "uptime" seconds
        	  "set" template-name "droprate" "in" percent
        	  "set" template-name "uid" number ["gid" number]
        annotate= "annotate" personality-name [no] finscan |
        	  "annotate" personality-name "fragment" \
        		("drop" | "old" | "new")
        route	= "route" "entry" ipaddr |
        	  "route" ipaddr "link" ipnetwork |
        	  "route" ipaddr "add" "net" ipnetwork ipaddr \
        		["latency" number"ms"] ["loss" percent]
        proto	= "tcp" | "udp" | "icmp"
        action	= "block" | "open" | "reset" | cmd-string | \
        		"proxy" ipaddr":"port

    The cmd-string and the personality-name are arbitrary strings enclosed with quotation marks. Variable expansion on the tokens $ipsrc, $ipdst, $sport and $dport is performed when executing the command string or when resolving the proxy address.

    If an IP address is not bound to a template, the actions specified in the default template are executed.

    Personalities need to be annotated before they are assigned to a template or an IP address.

    The default fragment policy is to accept fragment and resolve overlaps in favor of old data. If the personality returns TCP timestamps, the default uptime is a randomly chosen between zero and twenty days.

    The special include directive may be used to include other configuration files, for example to keep all personality annotations separate from the main configuration file.

-i interface
    Listen on interface.

net The IP address or network (specified in CIDR notation) to claim (e.g. ``10.0.0.3'' or ``10.0.0.0/16''). If unspecified, honeyd will attempt to claim any IP address it sees traffic for.

ROUTING TOPOLOGY
honeyd supports the creation of a complete network topology including routing. In order to enable the simulation of a network topology, a router entry point has to be configured with

      route entry <IP address>

Every route add net directive creates the specified gateway as a new router. The virtual machines that can be directly accessed by a router are defined as network range in the route link command.

The router entry point is the first address that inspects a packet. The packet follows a path defined by the network topology until the current router has the destination IP address on its local network.

EXAMPLES
A sample configuration file looks as follows:

    # Example of a simple host template and its binding
    include annotations
    create template
    set template personality "OpenBSD 2.6-2.7"
    add template tcp port 80 "sh scripts/web.sh"
    add template tcp port 22 "sh scripts/test.sh $ipsrc $dport"
    set template default tcp action reset
    set template uid 32767 gid 32767
    bind 10.11.69.2 template
    set 10.11.69.2 uptime 1327650

A simple example of a routing topology:

    route entry 10.0.0.1
    route 10.0.0.1 link 10.2.0.0/24
    route 10.0.0.1 add net 10.2.1.0/24 10.2.0.10 latency 10ms loss 3.4
    route 10.2.0.10 link 10.2.1.0/24

FILES

/var/run/honeyd.pid

SEE ALSO
arpd(8)

AUTHORS
Niels Provos <provos@citi.umich.edu>