Hosts3D 1.11 README - 29 Jun 10 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: 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: Basic install (hsen only)
Windows: glfw.dll from GLFW and WinPcap (http://www.winpcap.org/)
Compile: MinGW with GLFW and WinPcap Developer's Pack
Installation
============
Extract tarball: tar xzvf hosts3d-1.11.tar.gz
cd hosts3d-1.11
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 [-d] <id> <interface/file> [<destination>] [-p]
-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)
-p - Enable promiscuous mode (default disable)
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-2010 Del Castle
