AlpiNet is a lightweight, Alpine-based Docker image designed specifically for use as a virtual PC in GNS3. It comes pre-installed with a comprehensive suite of networking utilities and tools, making it perfect for network testing, troubleshooting, and education.
- 🐧 Lightweight: Based on Alpine Linux for minimal footprint
- 🛠️ Comprehensive Toolset: Pre-installed with essential networking utilities
- 🔧 GNS3 Ready: Optimized for use as a GNS3 appliance
- 💾 Persistent Storage:
/rootdirectory persists across container restarts - 🚀 Easy to Use: Simple setup and deployment
- IP Tools:
iproute2,iputils(includesarping),net-tools - Network Testing:
ping,traceroute,mtr - Traffic Analysis:
tcpdump,nmap - Performance Testing:
iperf,iperf3 - Network Utilities:
curl,wget,lynx,netcat,socat - Advanced:
bridge-utils,vlan,ethtool
- iptables: Traditional Linux firewall (IPv4)
- ip6tables: IPv6 firewall
- nftables: Modern Linux firewall framework
- lftp: Advanced FTP/FTPS/HTTP client
- tftp: TFTP client for network device configuration
host,nslookup,dig(bind-tools)
-
Editors:
vi,nano -
Terminal:
bash,tmux,screen -
Monitoring:
htop,procps -
File Tools:
rsync,tar,gzip -
Utilities:
jq,tree,less,grep,sed,awk
Note: Python is not included by default to keep the image lean (~84 MB). If needed, install it manually:
apk add python3 py3-pip pip3 install scapy netaddr ipython requests --break-system-packagesSince
/rootis persistent, Python installations survive container restarts.
# Clone the repository
git clone https://github.com/nazdridoy/alpinet.git
cd alpinet
# Build the Docker image
docker build -t nazdridoy/alpinet:latest .
# Or build with a specific version tag
docker build -t nazdridoy/alpinet:1.0.0 .# Pull the latest version
docker pull nazdridoy/alpinet:latest
# Or pull a specific version
docker pull nazdridoy/alpinet:1.0.0# Run interactively
docker run -it --rm nazdridoy/alpinet:latest
# Run with persistent storage
docker run -it --rm -v alpinet-data:/root nazdridoy/alpinet:latest
# Run with network host mode (for advanced testing)
docker run -it --rm --net=host --privileged nazdridoy/alpinet:latest- Download the
alpinet.gns3afile from this repository - In GNS3, go to File → Import appliance
- Select the
alpinet.gns3afile - Follow the import wizard
- GNS3 will automatically pull the Docker image
-
Build or pull the Docker image:
docker pull nazdridoy/alpinet:latest # or docker build -t nazdridoy/alpinet:latest .
-
In GNS3, go to Edit → Preferences → Docker containers
-
Click New and follow the wizard:
- Select the
nazdridoy/alpinet:latestimage - Set adapters to 1 (or more as needed)
- Configure console type (typically
telnet)
- Select the
-
The AlpiNet appliance will now appear in your GNS3 device list
When you start AlpiNet, you'll see a welcome banner:
.o. oooo o8o ooooo ooo .
.888. `888 `"' `888b. `8' .o8
.8"888. 888 oo.ooooo. oooo 8 `88b. 8 .ooooo. .o888oo
.8' `888. 888 888' `88b `888 8 `88b. 8 d88' `88b 888
.88ooo8888. 888 888 888 888 8 `88b.8 888ooo888 888
.8' `888. 888 888 888 888 8 `888 888 .o 888 .
o88o o8888o o888o 888bod8P' o888o o8o `8 `Y8bod8P' "888"
888
o888o
.
AlpiNet - Lightweight Alpine-based Networking Toolbox for GNS3
Type "alpinet-tools" for available utilities
Run the helper command to see all available utilities:
alpinet-tools# Check interface configuration
ip addr show
ip route show
# Test connectivity
ping -c 4 8.8.8.8
traceroute google.com
mtr -c 10 1.1.1.1# Capture packets
tcpdump -i eth0 -n
# Port scanning
nmap -sV 192.168.1.1
# Custom packet crafting with Scapy
python3
>>> from scapy.all import *
>>> sr1(IP(dst="8.8.8.8")/ICMP())# Server mode
iperf3 -s
# Client mode
iperf3 -c <server-ip># Simple GET request
curl -v https://example.com
# Download file
wget https://example.com/file.txt
# Text-based web browsing
lynx https://example.com
lynx -dump https://example.com # Dump page as text
lynx -source https://example.com # Get raw HTML
# JSON parsing
curl -s https://api.example.com/data | jq '.'# iptables - List current rules
iptables -L -n -v
ip6tables -L -n -v
# iptables - Block incoming traffic from an IP
iptables -A INPUT -s 192.168.1.100 -j DROP
# iptables - Allow specific port
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
# nftables - List rules
nft list ruleset
# nftables - Create a simple firewall
nft add table inet filter
nft add chain inet filter input { type filter hook input priority 0 \; }
nft add rule inet filter input ct state established,related accept
nft add rule inet filter input tcp dport 22 acceptNote: Firewall rules may require
--privilegedflag when running the container to have full access to netfilter.
# FTP - Connect and transfer files
lftp ftp://ftp.example.com
lftp -u username,password ftp://192.168.1.1
# FTP - One-liner download
lftp -c "get ftp://ftp.example.com/file.txt"
# TFTP - Get file from TFTP server (common for router configs)
tftp 192.168.1.1
> get router-config.cfg
> quit
# TFTP - One-liner
tftp -g -r config.bin 192.168.1.1
# SMB - List shares
smbclient -L //server -U username
# SMB - Connect to share
smbclient //server/share -U username
# SMB - Download file
smbclient //192.168.1.1/configs -U admin -c "get startup-config.txt"The /root directory is designed to be persistent. When using in GNS3, this directory maintains its contents across container restarts, allowing you to:
- Save scripts and configurations
- Store logs and packet captures
- Keep custom tool installations
You can customize the image by:
- Modifying the Dockerfile: Add or remove packages as needed
- Creating a custom image: Build from this base image
FROM nazdridoy/alpinet:latest
RUN apk add --no-cache your-package- Using Docker volumes: Mount custom scripts or configurations
docker run -it --rm -v $(pwd)/scripts:/root/scripts nazdridoy/alpinet:latestThe image is optimized for minimal size:
- Based on Alpine Linux (~5-10 MB base)
- Multi-layer caching for efficient builds
- APK cache cleaned after installation
Expected final image size: ~84 MB
alpinet/
├── Dockerfile # Main Dockerfile
├── README.md # This file
├── PACKAGES.md # Package justification
├── LICENSE # MIT License
├── .gitignore # Git ignore rules
├── .dockerignore # Docker ignore rules
├── alpinet.gns3a # GNS3 appliance file
└── temp-ref/ # Reference files
# Build with default tag
docker build -t nazdridoy/alpinet:latest .
# Build with custom tag
docker build -t nazdridoy/alpinet:1.0.0 .
# Build with no cache
docker build --no-cache -t nazdridoy/alpinet:latest .# Run tests
docker run -it --rm nazdridoy/alpinet:latest /bin/bash -c 'alpinet-tools && ip addr show'
# Verify all tools are installed
docker run -it --rm nazdridoy/alpinet:latest /bin/bash -c '
which ping && which tcpdump && which nmap && which iperf3 && echo "All tools OK"
'# Login to Docker Hub
docker login
# Tag the image (if not already tagged)
docker tag nazdridoy/alpinet:latest nazdridoy/alpinet:1.0.0
# Push to Docker Hub
docker push nazdridoy/alpinet:latest
docker push nazdridoy/alpinet:1.0.0Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
- Built on Alpine Linux
- Designed for GNS3
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- GNS3 Community: GNS3 Community Forum
Made with ❤️ for the GNS3 and networking community