NgTech-LTD/gns3-server
2
0
Fork 0
mirror of https://github.com/GNS3/gns3-server.git synced 2026-09-03 08:35:15 +03:00
Code Issues Packages Projects Releases Wiki Activity
gns3-server/gns3server/agent/web_wireshark/WEB_WIRESHARK.md
grossmj 640910ec8e
Use gns3server-web-wireshark-setup in docs
2026-04-24 00:48:00 +08:00

13 KiB
Raw Blame History

This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.

GNS3 Web Wireshark Container Management Guide

This document describes how to manage GNS3 Web Wireshark containers using the management script or Docker commands.

Installation

Before using Web Wireshark, you need to set up the Docker image:

pip install . && gns3server-web-wireshark-setup

This will:

  1. First try to pull the gns3/web-wireshark:latest image from Docker Hub
  2. If pull fails, build the image locally using the Dockerfile

The setup command shows the output from docker pull or docker build directly, so you can see the progress.

Architecture Overview

┌─────────────────────────────────────────────────┐
│              Host Machine                        │
│                                                  │
│  ┌────────────────────────────────────────────┐ │
│  │   Docker Network: gns3-wireshark           │ │
│  │   (Bridge network for container-host       │ │
│  │    communication)                          │ │
│  │                                             │ │
│  │  ┌──────────────────────────────────────┐ │ │
│  │  │  Container: gns3-PROJECT-ID          │ │ │
│  │  │                                      │ │ │
│  │  │  Link 1: Display :10001, Port 10001  │ │ │
│  │  │  Link 2: Display :10002, Port 10002  │ │ │
│  │  │  Link 3: Display :10003, Port 10003  │ │ │
│  │  │  ...                                 │ │ │
│  │  └──────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Quick Start (Using Management Script)

Prerequisites

  • Docker is running
  • Virtual environment is activated: source venv/bin/activate

Start Session

# Start session (using all defaults)
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "5af0fe00-f39d-4985-8669-7e8c512d729c" \
  --link-id "f233f27f-7432-49c3-9aa2-50e326a10eec" \
  --jwt-token "YOUR_JWT_TOKEN"

# Use custom image
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "5af0fe00-f39d-4985-8669-7e8c512d729c" \
  --link-id "f233f27f-7432-49c3-9aa2-50e326a10eec" \
  --jwt-token "YOUR_JWT_TOKEN" \
  --image "gns3/web-wireshark:test"

Access Web Interface

After starting, access Wireshark at:

ws://<container-ip>:<port>

Stop Session

python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  stop \
  --project-id "test-project" \
  --link-id "link-1"

Delete Container

python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  delete-container \
  --project-id "test-project"

Resource Parameter Configuration

Memory Configuration

# Default 2GB memory
--memory "2g"

# Custom memory
--memory "4g"      # 4GB
--memory "512m"   # 512MB
--memory "1g" \
--memory-swap "2g" # 1GB memory + 2GB swap

CPU Configuration

# Default 1 CPU core
--cpus 1.0

# Custom CPU
--cpus 0.5    # 50% CPU
--cpus 2.0    # 2 CPU cores
--cpus 4.0    # 4 CPU cores

Process Limit Configuration

# Default max 1000 processes
--pids-limit 1000

# Custom limit
--pids-limit 500     # Max 500 processes
--pids-limit 2000    # Max 2000 processes

Complete Example

python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "test-project" \
  --link-id "link-1" \
  --jwt-token "test-token" \
  --image "gns3/web-wireshark:latest" \
  --memory "4g" \
  --memory-swap "6g" \
  --cpus 2.0 \
  --pids-limit 2000

Parameter Reference Table

Parameter Default Value Description Example
--image gns3/web-wireshark:latest Docker image ubuntu:latest
--memory 2g Memory limit 4g, 512m
--memory-swap Same as memory Memory swap limit 4g, 8g
--cpus 1.0 CPU cores 0.5, 2.0
--pids-limit 1000 Process limit 500, 2000

Docker Network Management

Create Network

docker network create \
  --driver bridge \
  --subnet=100.64.0.0/22 \
  gns3-wireshark

Delete Network

docker network rm gns3-wireshark

Warning: Stop and disconnect all containers before deleting the network.

View Network Information

# List all Docker networks
docker network ls

# View network details
docker network inspect gns3-wireshark

# List containers connected to the network
docker network inspect gns3-wireshark -f '{{range .Containers}}{{.Name}} {{end}}'

Performance Metrics

Per Wireshark Instance Resource Usage

Resource Type Usage Description
Memory 150-250 MB Depends on capture traffic and number of parsed protocols
CPU 0.5-2% Lower at idle, increases with high traffic
Threads ~30 threads Wireshark multi-threaded architecture
Disk I/O Minimal Mostly log writing

Container Resource Configuration Recommendations

Based on --pids-limit 1000 and --memory="2g" configuration:

Wireshark Instances Estimated Threads Estimated Memory Recommended Use Case
1-3 120-200 threads 450-750 MB Lightweight projects, small topologies
4-6 230-290 threads 600-1.5 GB Medium projects, multiple network links
7-10 320-410 threads 1-2.5 GB Large projects, dense capture
10+ >400 threads >2.5 GB Warning: Increase memory limit

Actual Test Data

Test Environment: 3 Wireshark instances running simultaneously

CONTAINER ID   NAME                     CPU %     MEM USAGE / LIMIT   MEM %     NET I/O          BLOCK I/O     PIDS
19363d29bd9d   gns3-PROJECT-ID          4.59%     735.6MiB / 2GiB     35.92%    386kB / 38.6MB   0B / 15.5MB   201

Detailed Process Statistics:

  • Total threads: ~204
  • Total processes: ~61
  • Per Wireshark instance: ~30 threads + 1 parent process

Performance Optimization Recommendations

  1. Memory is the main bottleneck, not PID limit

    • Default 2GB memory can support 6-8 Wireshark instances
    • When needing more instances, increase memory first rather than PID limit

  2. Start Wireshark on demand

    • Only start Wireshark for links that need packet capture
    • Stop sessions promptly when done to release resources

  3. Multi-container strategy

    • For super large projects (10+ links), consider using multiple containers
    • Each container handles 5-8 links for better resource isolation and stability

  4. Monitor resource usage

    # Real-time container resource monitoring
docker stats gns3-PROJECT-ID

# Check process count inside container
docker exec gns3-PROJECT_ID bash -c "ps -eLf | wc -l"

Management Commands (Docker)

View All Active xpra Sessions

docker exec "${CONTAINER_NAME}" xpra list

View Container Logs

docker logs "${CONTAINER_NAME}"

View Processes Inside Container

docker exec "${CONTAINER_NAME}" ps aux | grep -E "Xvfb|xpra"

Enter Container Shell

docker exec -it "${CONTAINER_NAME}" /bin/bash

Stop Container

docker stop "${CONTAINER_NAME}"

Delete Container

docker rm "${CONTAINER_NAME}"

Troubleshooting

Check if Container is Running

docker ps | grep "${CONTAINER_NAME}"

Check Network Connection

# Ping container from host
docker exec "${CONTAINER_NAME}" ping -c 3 100.64.0.1

# Check port listening
docker exec "${CONTAINER_NAME}" netstat -tlnp | grep xpra

View xpra Logs

docker exec "${CONTAINER_NAME}" ls -la /tmp/sessions/

Restart Specific Session

LINK_ID=1
DISPLAY_ID=$LINK_ID

# Stop session
docker exec "${CONTAINER_NAME}" xpra stop ":${DISPLAY_ID}"

# Clean up session files
docker exec "${CONTAINER_NAME}" rm -rf "/tmp/sessions/link-${LINK_ID}"

# Restart (see previous start commands)

Thread Creation Error (QThread::start: Thread creation error)

Error Message:

QThread::start: Thread creation error (Resource temporarily unavailable)

Root Cause Analysis:

  • Docker container PID limit (--pids-limit) actually limits thread count
  • Each Wireshark instance requires approximately 30 threads
  • Default limit of 200 may not be enough for multiple Wireshark instances

Solution:

# Check current thread usage
docker exec "${CONTAINER_NAME}" bash -c "ps -eLf | wc -l"

# Increase PID limit (recommended to set to 1000)
docker update --pids-limit 1000 "${CONTAINER_NAME}"

# Verify new limit
docker inspect "${CONTAINER_NAME}" --format '{{.HostConfig.PidsLimit}}'

Prevention:

  • Set a reasonable PID limit when starting the container: --pids-limit 1000
  • Refer to "Performance Metrics" section for appropriate configuration

XDG_RUNTIME_DIR Warning

Warning Message:

Warning: XDG_RUNTIME_DIR is not defined
 and '/run/user/1000' does not exist
 using '/tmp'

Explanation:

  • This is a warning, not an error; Xpra falls back to using /tmp
  • May affect some features relying on XDG specification

Solution: Ensure you are using the latest Docker image, which includes the following fix:

  • Create /run/user/1000 directory
  • Set XDG_RUNTIME_DIR environment variable

For manual fix:

docker exec "${CONTAINER_NAME}" mkdir -p /run/user/1000
docker exec "${CONTAINER_NAME}" bash -c "export XDG_RUNTIME_DIR=/run/user/1000"

Manual Testing (Step-by-Step)

This section preserves the original manual testing steps used during development.

Prerequisites

  • Docker is running
  • Virtual environment is activated: source venv/bin/activate

Basic Test Commands

# 1. Start session (using all defaults)
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "5af0fe00-f39d-4985-8669-7e8c512d729c" \
  --link-id "f233f27f-7432-49c3-9aa2-50e326a10eec" \
  --jwt-token "YOUR_JWT_TOKEN"

# 2. Use custom image
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "5af0fe00-f39d-4985-8669-7e8c512d729c" \
  --link-id "f233f27f-7432-49c3-9aa2-50e326a10eec" \
  --jwt-token "YOUR_JWT_TOKEN" \
  --image "gns3/web-wireshark:test"

# 3. View containers
docker ps | grep gns3-wireshark
docker logs gns3-wireshark-test-project

# 4. Stop session
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  stop \
  --project-id "test-project" \
  --link-id "link-1"

# 5. Delete container
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  delete-container \
  --project-id "test-project"

WebSocket Access URL

After starting a session, access Wireshark via WebSocket:

ws://192.168.1.140:3080/v3/projects/5af0fe00-f39d-4985-8669-7e8c512d729c/links/f233f27f-7432-49c3-9aa2-50e326a10eec/capture/web-wireshark?token=YOUR_JWT_TOKEN

Cleanup (If Tests Fail)

# Delete test containers
docker ps -a | grep 'gns3-wireshark-test' | awk '{print $1}' | xargs -r docker rm -f

# Delete test networks
docker network ls | grep 'gns3-wireshark' | awk '{print $2}' | xargs -r docker network rm

File Structure

gns3server/agent/web_wireshark/
├── setup_wireshark_image.py      # Docker image setup tool (gns3-wireshark-setup)
├── manage_wireshark.py           # CLI management tool
├── manager.py                    # Session management logic
├── docker_client.py             # Docker API client
├── docker/
│   └── Dockerfile               # Container image definition
└── WEB_WIRESHARK.md             # This documentation

Known Issues

  • JWT token is passed via command-line arguments (visible in /proc/<pid>/cmdline). Consider using a temporary file inside the container for improved security.
  • cmd_delete_container and cmd_delete in manage_wireshark.py are duplicate code.
  • stop-container and delete-container subcommands are defined but not registered in the commands dictionary.
  • link_id_to_display and link_id_to_port return the same value (10000-19999), which may cause confusion since xpra typically uses different display numbers and ports.
  • Container health check timeout (5 seconds) may be insufficient on slow systems.
  • Docker Unix socket connection error handling could be improved (FileNotFoundError not properly caught).

Notes

  • Default uses gns3/web-wireshark:latest image
  • Use --verbose to see detailed logs
  • Containers use 100.64.0.0/22 network
  • xpra port range: 10000-19999 (deterministic based on link_id)
  • Health check: xpra list
  • Log configuration: json-file, max-size=10m, max-file=3