Hosts3D 1.03 README - 02 Sep 09  Del Castle
-------------------------------------------
Website
=======
http://hosts3d.sourceforge.net

Introduction
============
Hosts3D is a 3D real-time network monitor, 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 hosts, protocol or port.

hsen (Hosts3D Sensor) is a packet capture daemon which reads and sends packet header information to Hosts3D, locally or remotely. hsen also equates hostname to IP by reading DNS packets (UDP type A class IN standard query response). Multiple sensors can send information to multiple computers running Hosts3D on the same subnet via broadcast.

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

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

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

Windows: pthreadGC2.dll from pthreads-win32 (http://sourceware.org/pthreads-win32), freeglut.dll from freeglut-win (http://hosts3d.sourceforge.net) and WinPcap (http://www.winpcap.org)
  To compile: MinGW with pthreads-win32, freeglut-win and WinPcap Developer's Pack

Installation
============
Linux: tar xzvf hosts3d-1.03.tar.gz
       cd hosts3d-1.03
       ./configure
       make
       make install (as root, sudo)
Effect: Puts executable "hosts3d" in /usr/local/bin/
        Puts executable "hsen" in /usr/local/sbin/
        Puts man page "hosts3d.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-hosts3d" to create executable "hosts3d".

Windows: Run "compile-hsen.bat" to create executable "hsen.exe".
         Run "compile-hosts3d.bat" to create executable "Hosts3D.exe".

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

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

Run Hosts3D: hosts3d [-f]
             -f - Display full screen.

As hsen captures packets in promiscuous mode you must start it as root (sudo). In Windows Vista, run as Administrator.

Run hsen: hsen [-d] <id> <interface/file> [<destination>]
          -d - Display interfaces (Windows).
          id - Identify packets from a specific hsen when multiple exist (1 - 255).
          interface - Listen on interface (Linux: eth0, eth1, ppp0, wlan0, etc.); or
          file - Read packets from pcap file. Standard input is used if file is "-".
          destination - Hosts3D IP or broadcast address (default localhost).

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

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

Hosts3D: 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 Hosts3D (Linux)
========================================
The user starting Hosts3D must be in the /etc/sudoers file, as by default Hosts3D 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. By default the local hsen is stopped using the command "pkill hsen", which will kill all hsen processes.

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

Notes
=====
- Support only for IPv4.
- IP headers with options are ignored.
- Support for packets with optionless GRE or VLAN 802.1Q encapsulation.
- IP protocol 249 unassigned, used to identify ARP packet.
- IP protocol 250 unassigned, used to identify fragmented IP packet.
- In Hosts3D, by default hosts are added from packet source IP address, option Add Dests will also add from destination IP address.
- In Hosts3D, if show broadcasts is off, a (B) indicates broadcast present.
- In Hosts3D, anomalies are a new host or host service.
- In Hosts3D, using the menu options to move/arrange a few thousand hosts may take a few minutes.
- In Hosts3D, 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 Hosts3D, clicking a multiple host object will cycle through selecting hosts within.
- In Windows, Hosts3D window may flicker when starting.
- In Windows, a blank Command Prompt window will be present, on exit close Hosts3D window first.
- In Windows, Hosts3D 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 <hosts3d@gmail.com>.

Copyright
=========
Copyright (c) 2006-2009  Del Castle
