HOMESTEAD 0.95 README - 21 Nov 08  Del Castle
---------------------------------------------
Website
=======
http://homestead.sourceforge.net

Introduction
============
Homestead is a 3D real-time network visualizer, displaying hosts and packet traffic. Features include support for multiple sensors, analysis of packets to gather hostnames and services, configurable layout of subnetworks, recording/replaying of packet traffic, and the ability to filter packets by host, protocol or port.

hsen (Homestead Sensor) is a packet capture daemon which reads and sends packet header information to Homestead, locally or remotely. hsen also equates hostname to IP by reading DNS packets (UDP type A class IN standard query response). The relationship between hsen to Homestead can be one-to-one, one-to-many, many-to-one or many-to-many (many Homesteads would be on multiple computers on the same subnet, receiving packet header information from hsen via broadcast).

License
=======
GNU General Public License Version 2

Hardware Requirements
=====================
Scroll Mouse
Video Card supporting OpenGL (with drivers installed)

Software Requirements
=====================
Linux: Packages freeglut and libpcap (and their associated dependencies)
       To compile: Packages g++, freeglut3-dev and libpcap-dev (and their associated dependencies)

Windows (Homestead only): MinGW with pthreads-win32 (http://sourceware.org/pthreads-win32/) and freeglut-win (http://homestead.sourceforge.net)

Installation
============
Linux: tar xzvf homestead082.tar.gz
       cd homestead082
       ./configure
       make
       make install (as root, sudo)
Effect: Puts executable "homestead" in /usr/local/bin/
        Puts executable "hsen" in /usr/local/sbin/
        Puts man page "homestead.1" in /usr/local/share/man/man1/
        Puts man page "hsen.8" in /usr/local/share/man/man8/
Alternative: Run script "compile-hsen" to create executable "hsen".
             Run script "compile-homestead" to create executable "homestead".

Windows (Homestead only): Run script "compile-win.bat" to create executable "Homestead.exe".

Firewall Configuration: hsen talks to Homestead via UDP port 10111.

Starting
========
Starting order does not matter, however if hsen is running and Homestead is not, ICMP Port Unreachable (UDP port 10111) may be generated.

Run Homestead: homestead (Linux) or Homestead.exe (Windows)

As hsen captures packets in promiscuous mode you must start it as root (sudo).

Run hsen: hsen <id> <interface/file> [<destination>]
          id - Number used to identify packets from a specific hsen when multiple exist. Range 1 to 255.
          interface - Listen on interface: eth0, eth1, ppp0, wlan0, etc.; or
          file - Read packets from pcap file. Standard input is used if file is "-".
          destination - IP or broadcast address to send Homestead UDP packets to. If omitted, default is 127.0.0.1 (localhost).

In Linux Homestead and hsen both log to syslog, check when troubleshooting.

Data Files
==========
In Linux created in directory ".homestead". In Windows created in directory "hsd-data".

Homestead: controls.txt - Controls
           settings-hsd - Settings
           0network.hnl - Network Layout On-Exit
           1network.hnl - Network Layout 1
           2network.hnl - Network Layout 2
           3network.hnl - Network Layout 3
           4network.hnl - Network Layout 4
           netpos.txt - CIDR Notation Net Position/Colour
           traffic.hpt - Packet Traffic Record
           tmp-hinfo-hsd - Temporary Information
           tmp-netpos-hsd - Temporary Net Positions
           tmp-flist-hsd - Temporary Working Directory File List

Net Positions
=============
If a host is not a member of any net position entries, it is placed in the Grey Zone. If a host is a member of multiple net position entries, the first entry is used. Line format for net position entries is "pos net x-position y-position z-position colour", eg. "pos 123.123.123.123/32 10 0 -10 green".

Positions: Grey/Red - positive x-position
           Blue/Green - negative x-position
           Up - positive y-position
           Down - negative y-position
           Grey/Blue - positive z-position
           Red/Green - negative z-position

Colours: none (where multiple colours are used), default (grey), orange, yellow, fluro, green, mint, aqua, blue, purple and violet.

Start/Stop Local hsen in Homestead
==================================
The user starting Homestead must be in the /etc/sudoers file, as by default Homestead will start/stop the local hsen via a terminal with sudo. Thus the system may prompt for a password when starting/stopping a local hsen. The local hsen is stopped using the command "pkill hsen", which will kill all hsen processes.

Homestead Controls
==================
Press H key in Homestead to show controls.

Notes
=====
- Support only for IPv4.
- Fragmented packets are ignored.
- If GRE or 802.1q encapsulation is present use "nude" to strip (see website).
- IP protocol 249 unassigned, used to identify ARP packet.
- IP protocol 250 unassigned, used to identify unknown IP packet.
- In Homestead, by default hosts are added from packet source IP address, option Add Dests will also add from destination IP address.
- In Homestead, if show broadcasts is off, a (B) indicates broadcast present.
- In Homestead, anomalies are a new host or host service.
- In Homestead, using the menu options to move/arrange a few thousand hosts may take a few minutes.
- In Homestead, deleting hosts, updating net positions, using the menu options to move/arrange hosts, or clearing/restoring a net layout will cause packets to be dropped, thus affect packet recording.
- In Homestead, clicking a multiple host object will cycle through selecting hosts within.
- In Windows, Homestead window will flicker when starting.
- In Windows, a blank Command Prompt window will be present, on exit close Homestead window first.
- In Windows, Homestead will stall when running a system command on selection, until commands complete. Command output is displayed in related Command Prompt window.

Reporting Bugs
==============
Report bugs to <delcastle@users.sourceforge.net>.
