Packet_Pulse - UDP Pinger & Heartbeat (VM/Mininet & Docker)

A Python UDP client-server project implementing Pinger and Heartbeat applications, demonstrating round-trip timing, packet loss simulation, heartbeat monitoring, and containerized execution with Docker and Compose. This repository contains two small UDP client/server applications written in Python:

1. UDP Pinger — client sends 10 pings; server echoes; client reports RTT stats & packet loss.
2. UDP Heartbeat — client sends 10 heartbeats (every ~3s) with ~30% client-side loss; server logs status.

It ships in two runnable forms:

• Original VM + Linux + Mininet — mirrors the classroom topology workflow.
• Dockerized (no VM/Mininet required) — convenient, reproducible local runs with Docker.

---

At a Glance

• Language: Python 3 (stdlib only)
• Transport: UDP
• Dockerized layout: Two images (client/server), four Compose services:
  • server_pinger (UDP ${PING_PORT:-12345})
  • client_pinger (talks to server_pinger)
  • server_hb (UDP ${HB_PORT:-12346})
  • client_hb (talks to server_hb)

Both client/server scripts read HOST and PORT from environment variables (with sensible defaults) for portability.

---

Repository Layout

.
├─ README.md                      ← this file
└─ dockerized_version/
   ├─ docker-compose.yml
   ├─ run.sh                      ← Bash helper (pinger by default, or `hb`)
   ├─ down.sh                     ← Bash helper (tear down)
   ├─ client/
   │  ├─ Dockerfile
   │  └─ app/
   │     ├─ udp_pinger_client.py
   │     └─ udp_hb_client.py
   └─ server/
      ├─ Dockerfile
      └─ app/
         ├─ udp_pinger_server.py
         └─ udp_hb_server.py

If you’re on macOS/Linux and get a permission error, make the scripts executable:
chmod +x dockerized_version/run.sh dockerized_version/down.sh

---

Dockerized Version (Recommended)

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Confirm the daemon is running:

  docker version

---

Quick Start — Bash

From dockerized_version/:

# Pinger variant (default)
./run.sh

# Heartbeat variant
./run.sh hb

# Tear down
./down.sh

---

Quick Start — PowerShell (Windows)

PowerShell can’t run .sh files directly. Use the equivalent Compose commands:

Pinger

docker compose build
docker compose up -d server_pinger
docker compose run --rm client_pinger

Heartbeat

docker compose build
docker compose up -d server_hb
docker compose run --rm client_hb

Tear down

docker compose down -v

---

What to Expect

Pinger (client output)

• 10 attempts (Ping 1…Ping 10)
• Per-ping RTT or “Request timed out”
• Summary: min / max / avg RTT, packet loss %

Example:

Ping 1: rtt = 0.647 ms
Ping 2: rtt = 0.243 ms
Ping 3: Request timed out
...
Summary values:
min_rtt = 0.243 ms
max_rtt = 0.856 ms
avg_rtt = 0.565 ms
Packet loss: 40.00%

Heartbeat (client output)

• 10 time slots ~3s apart, each SENT or LOST (client simulates ~30% loss)

Example:

1,22:49:15
LOST
2,22:49:18
SENT
...

Heartbeat (server logs)

• In the Docker version, the heartbeat server logs to console by default (view with docker compose logs -f server_hb).
• In the VM/Mininet version, the server pipes its output to a generated report file by default (see below).

---

Running Both Servers (optional)

Start both servers (different UDP ports) and invoke clients when you want:

docker compose up -d server_pinger server_hb
docker compose run --rm client_pinger
docker compose run --rm client_hb

---

Configuration

• Pinger UDP port: ${PING_PORT:-12345}
• Heartbeat UDP port: ${HB_PORT:-12346}

Override examples

# Bash
PING_PORT=20001 docker compose up -d server_pinger
docker compose run --rm -e PORT=20001 client_pinger

# PowerShell
$env:PING_PORT=20001
docker compose up -d server_pinger
docker compose run --rm -e PORT=20001 client_pinger

Clients resolve servers by service name via Docker DNS: server_pinger, server_hb.

---

Heartbeat Logs (Docker)

By default, Docker runs are console-only for heartbeat logs. If later you want a file as well:

1. Start the server with a flag (if supported in your current codebase):

   HB_WRITE_TO_FILE=1 docker compose up -d server_hb

2. (Optional) Mount a host folder to collect reports, e.g.:

   server_hb:
     volumes:
       - ./hb_reports:/app/hb_reports
     environment:
       - REPORT_DIR=/app/hb_reports

---

Logs & Diagnostics

# What’s running?
docker compose ps

# Live logs
docker compose logs -f server_pinger
docker compose logs -f server_hb

Windows quirk: You might see lines like
http2: server: error reading preface from client //./pipe/docker_engine: file has already been closed
They’re harmless if containers start. If they persist, restart Docker Desktop (and wsl --shutdown if using WSL2).

---

Original Version (VM + Linux + Mininet)

This mirrors the classroom workflow using a 2-host Mininet topology inside a VM.

Prereqs

• Oracle VirtualBox
• A Linux VM with Mininet installed
• Python 3

Typical session

From the Mininet CLI:

mininet> h1 python3 udp_pinger_server.py &
mininet> h2 python3 udp_pinger_client.py

For the heartbeat variant, run the respective udp_hb_server.py and udp_hb_client.py.

Notes for coursework:

• Pinger: server simulates loss; client computes RTT stats & packet loss.
• Heartbeat: client simulates ~30% loss; server can record a per-client report (if required).

---

Troubleshooting

• Docker daemon not running
  Start Docker Desktop and wait until it’s ready.

• Client can’t reach server
  Ensure the proper server is running (docker compose ps) and ports/ENV match (HOST, PORT).

• PowerShell & .sh
  Use Git Bash/WSL or the PowerShell commands above.

• Port already in use
  Override PING_PORT / HB_PORT as shown in Configuration.