Hosts3D 1.15 README - 10 May 11 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 agent 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: libglfw and libpcap (and their associated dependencies)
Compile: g++, libglfw-dev and libpcap-dev (and their associated dependencies)
Mac OS X: GLFW (http://www.glfw.org/)
Compile: Mac OS X SDK with GCC and GLFW
FreeBSD: Standard install (hsen only)
Windows: WinPcap (http://www.winpcap.org/)
Compile: MinGW with GLFW and WinPcap Developer's Pack
Installation
============
Extract tarball: tar xzvf hosts3d-1.15.tar.gz
cd hosts3d-1.15
Linux: ./configure
make
make install (as root, sudo)
Uninstall: make uninstall (as root, sudo)
Alternative: ./compile-hsen (to create executable "hsen")
./compile-hosts3d (to create executable "hosts3d")
Put executables "hsen" and "hosts3d" in /usr/local/bin/
Put man pages "hsen.1" and "hosts3d.1" in /usr/local/share/man/man1/
Mac OS X: ./compile-hsen (to create executable "hsen")
./compile-mac-hosts3d (to create executable "hosts3d")
Put executables "hsen" and "hosts3d" in /usr/local/bin/
Put man pages "hsen.1" and "hosts3d.1" in /usr/local/share/man/man1/
FreeBSD: ./compile-hsen (to create executable "hsen")
Put executable "hsen" in /usr/bin/
Put man page "hsen.1" in /usr/share/man/man1/
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
Run hsen: hsen <id> <interface/file> [<destination>] [-p] [-d]
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)
-p - Enable promiscuous mode (default disable)
-d - Run as daemon (default disable)
Windows: hsen -d
-d - Display interfaces
hsen <id> <interface/file> [<destination>] [-p]
To capture packets from some interfaces, or in promiscuous mode, you may have to start hsen as root (sudo). In Windows Vista, run as Administrator, even to display interfaces.
For Linux/Mac OS X/FreeBSD, Hosts3D and hsen both log to syslog, check when troubleshooting.
Data Files
==========
In Linux/Mac OS X, 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, violet and hold (place hosts in same position).
Start/Stop Local hsen in Hosts3D (Linux/Mac OS X)
=================================================
If sudo is required to start/stop a local hsen, the user starting Hosts3D must be in /etc/sudoers. The default command to stop a local hsen is "killall hsen", which will kill all hsen processes.
Hosts3D Help
============
Press H key in Hosts3D to show help.
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, activate Add Destination Hosts to also add from destination IP address.
- 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, using the menu options to move/arrange hosts, or clearing/restoring a net layout may affect packet recording.
- In Hosts3D, clicking a multiple host object will cycle through selecting hosts within.
- In Hosts3D, data files from 32-bit version are incompatible with 64-bit version and vice versa.
- In Windows, Hosts3D will stall when running a system command on selection, until commands complete. Command output is displayed in associated Command Prompt window.
Reporting Bugs
==============
Report bugs to <hosts3d@gmail.com>.
Copyright
=========
Copyright (c) 2006-2011 Del Castle
