# ============================================================================
#  VisualEther Hosts File — Tutorial
# ============================================================================
#
#  TUTORIAL: What is a hosts file?
#  --------------------------------
#  A hosts file maps IP addresses to human-readable names in sequence diagrams.
#  Without a hosts file, diagram axes show raw IPs (e.g., "10.0.0.145").
#  With a hosts file, they show friendly names (e.g., "Firefox.Client").
#
#  This makes diagrams immediately understandable — you see "Firefox" sending
#  a request to "Apache" instead of cryptic IP addresses.
#
#  Usage:
#    visualether generate --hosts-file hosts.txt --fxt explore.fxt.xml --input capture.pcap
#
# ============================================================================
#  TUTORIAL: Basic Format
# ============================================================================
#
#  Each line maps an IP address to a display name:
#
#    <IP_ADDRESS>  <DISPLAY_NAME>
#
#  Rules:
#    - One mapping per line
#    - IP and name separated by whitespace (spaces or tabs)
#    - Lines starting with '#' are comments
#    - Blank lines are ignored
#    - Names are case-sensitive
#
#  Example:
#    192.168.1.10  WebServer
#    192.168.1.20  Database
#
# ============================================================================
#  TUTORIAL: Hierarchical Naming with Dot Notation
# ============================================================================
#
#  Names can use dot notation to create a two-level hierarchy:
#
#    <IP_ADDRESS>  <Entity>.<Domain>
#
#  In the diagram, Entity appears as the axis label and Domain appears as
#  a grouping header above related entities. This is useful for showing
#  logical groupings such as:
#
#    - Application.Host       (e.g., Firefox.Client, Apache.Server)
#    - Service.NetworkZone    (e.g., WebApp.DMZ, Database.Internal)
#    - Component.System       (e.g., MME.EPC, eNB.RAN)
#
#  When multiple entities share the same Domain, they are visually grouped
#  together in the diagram under a common header. Entities with matching
#  domains are also placed next to each other on the axis — so hierarchy
#  doesn't just label, it also controls axis ordering and grouping in the
#  sequence diagram.
#
#  Example:
#    10.0.0.1   MME.EPC
#    10.0.0.2   SGW.EPC
#    10.0.0.3   PGW.EPC
#    10.0.0.10  eNB.RAN
#
#  This produces a diagram where MME, SGW, and PGW are grouped under "EPC"
#  and eNB appears under "RAN". The three EPC entities appear side by side
#  regardless of the order they first appear in the capture.
#
# ============================================================================
#  TUTORIAL: Port-Specific Mapping (IPv4)
# ============================================================================
#
#  You can map a specific IP:port combination to a name:
#
#    <IP_ADDRESS>:<PORT>  <DISPLAY_NAME>
#
#  This is useful when a single host runs multiple services on different
#  ports, and you want each service to appear as a separate axis.
#
#  Example — two services on the same server:
#    192.168.1.10:80   WebServer.Services
#    192.168.1.10:443  TLSProxy.Services
#    192.168.1.10:5432 Postgres.Services
#
#  Fallback behavior:
#    If a packet's IP:port has no port-specific entry, VisualEther falls
#    back to the IP-only mapping. So you only need port-specific entries
#    when you want to distinguish services on the same host.
#
#  Tip: Multiple entries can map to the SAME name to coalesce axes.
#  See the "Axis Coalescing" section below for details.
#
# ============================================================================
#  TUTORIAL: Port-Specific Mapping (IPv6)
# ============================================================================
#
#  IPv6 addresses contain colons, so port-specific mappings use bracket
#  notation to avoid ambiguity:
#
#    [<IPv6_ADDRESS>]:<PORT>  <DISPLAY_NAME>
#
#  Examples:
#    2001:db8::1          DNS.CoreNetwork
#    [2001:db8::1]:53     DNS.CoreNetwork
#    [2001:db8::2]:80     WebServer.DMZ
#    [2001:db8::2]:443    TLSServer.DMZ
#    [fe80::1%eth0]:546   DHCPv6Client.LAN
#
#  The bracket notation follows the standard URI convention (RFC 3986)
#  and is only needed when specifying a port. Plain IPv6 addresses
#  (without port) do not need brackets:
#
#    2001:db8::1  MyServer
#
# ============================================================================
#  TUTORIAL: Axis Coalescing (Merging Multiple Addresses onto One Axis)
# ============================================================================
#
#  A powerful technique is mapping multiple IPs (or IP:port pairs) to the
#  SAME display name. This coalesces their traffic onto a single axis in
#  the diagram — effectively treating them as one logical entity.
#
#  IP coalescing (--axis ip):
#    Map multiple IPs to the same name when they represent the same
#    logical entity (e.g., a load-balanced service, a dual-stack host,
#    or a failover cluster):
#
#    192.168.1.10  WebServer.Farm
#    192.168.1.11  WebServer.Farm
#    192.168.1.12  WebServer.Farm
#
#    All traffic to/from these three IPs appears on one "WebServer" axis.
#
#  Dual-stack coalescing (IPv4 + IPv6 on same host):
#    10.0.0.5         MyServer.Network
#    2001:db8::5      MyServer.Network
#
#    IPv4 and IPv6 traffic merge onto a single axis.
#
#  Port coalescing (--axis port):
#    When using --axis port, each IP:port gets its own axis by default.
#    Map multiple ports to the same name to merge them:
#
#    192.168.1.10:8080  WebApp.Server
#    192.168.1.10:8443  WebApp.Server
#
#    Traffic on ports 8080 and 8443 shares one "WebApp" axis.
#
#    This is especially useful for client-side ephemeral ports — without
#    coalescing, each ephemeral port creates a separate axis, cluttering
#    the diagram. Map them all to one name:
#
#    10.0.0.145:3372   Firefox.Client
#    10.0.0.145:3373   Firefox.Client
#    10.0.0.145:3374   Firefox.Client
#
#  Combined coalescing:
#    You can combine both techniques. Map different IPs and different
#    ports to the same name for maximum flexibility:
#
#    192.168.1.10:80    WebFrontend.DMZ
#    192.168.1.11:80    WebFrontend.DMZ
#    192.168.1.10:443   WebFrontend.DMZ
#    192.168.1.11:443   WebFrontend.DMZ
#
#    All HTTP and HTTPS traffic across both servers shares one axis.
#
# ============================================================================
#  TUTORIAL: Axis Selection Interaction
# ============================================================================
#
#  The hosts file works with the --axis option:
#
#    --axis ip   (default):  Groups all traffic by IP address.
#                            Port-specific entries are ignored.
#                            Use IP-only mappings.
#
#    --axis port:            Groups traffic by IP:port combination.
#                            Port-specific entries take effect.
#                            Unmapped ports fall back to IP-only name.
#
#  For this tutorial capture, --axis ip is appropriate since each host
#  runs a single service. Use --axis port when you need to distinguish
#  multiple services on the same host (e.g., localhost testing).
#
# ============================================================================
#  Mappings for tcp-sack-video.pcapng
# ============================================================================
#
#  This capture shows a Firefox browser downloading a video from an Apache
#  web server. The TCP connection exhibits SACK (Selective Acknowledgment)
#  behavior due to packet loss and reordering on the network path.
#
#  Endpoints:
#    10.0.0.145    — Client machine running Firefox
#    186.15.230.24 — Remote server running Apache on port 80
#

# --- Client ---
10.0.0.145  🖥 Firefox.Client

# --- Server ---
186.15.230.24  🏢 Apache.Server

# --- Port-specific examples (for use with --axis port) ---
# Uncomment these to see port-level separation with --axis port:
# 186.15.230.24:80  Apache-HTTP.Server
# 10.0.0.145:3372   Firefox-Ephemeral.Client
