Marius Mutu
acf234c600
- Added Windows PowerShell network scanner with auto-detection and interactive mode - Implemented dual scanning system (Windows + Linux fallback) - Added computer management features (rename, delete, duplicate checking) - Enhanced UI with modern responsive design and Romanian localization - Added comprehensive Windows-Linux integration with WSL interop - Improved error handling and user feedback throughout - Added hot reload for development and comprehensive documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
127 lines
4.7 KiB
Markdown
127 lines
4.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
See README.md for complete project description, installation instructions, and usage details.
|
|
|
|
This is a Wake-on-LAN (WOL) Manager - a containerized Flask web application for managing and remotely waking computers on a local network.
|
|
|
|
## Architecture & Code Structure
|
|
|
|
- **Backend**: Flask web application (`app/app.py`) with RESTful API endpoints
|
|
- **Frontend**: Single-page application with vanilla JavaScript (`app/templates/index.html`)
|
|
- **Storage**: File-based configuration in `/data/wol-computers.conf`
|
|
- **Deployment**: Docker with docker compose, requires privileged networking
|
|
|
|
### Key Components
|
|
|
|
- `WOLManager` class in `app/app.py`: Core logic for computer management, WOL operations, and network scanning
|
|
- Configuration format: `name|mac|ip` (pipe-separated values in `/data/wol-computers.conf`)
|
|
- Dependencies: `wakeonlan`, `nmap`, `ping`, `arp` system tools
|
|
- **Windows PowerShell scanner**: `scripts/windows-network-scan.ps1` - optimized network scanning from Windows host
|
|
|
|
## Development Commands
|
|
|
|
**For installation and basic usage, see README.md**
|
|
|
|
### Docker Development
|
|
|
|
**Note**: When running from WSL with Docker Desktop on Windows, use `docker.exe compose`:
|
|
|
|
```bash
|
|
# Development build and run
|
|
docker compose up -d --build
|
|
# From WSL: docker.exe compose up -d --build
|
|
|
|
# View real-time logs
|
|
docker compose logs -f wol-web
|
|
# From WSL: docker.exe compose logs -f wol-web
|
|
|
|
# Shell access to container
|
|
docker compose exec wol-web bash
|
|
# From WSL: docker.exe compose exec wol-web bash
|
|
|
|
# Stop containers
|
|
docker compose down
|
|
# From WSL: docker.exe compose down
|
|
```
|
|
|
|
### Network Requirements
|
|
- Runs on port 5000 (configurable via WOL_EXTERNAL_PORT env var)
|
|
- Requires `NET_ADMIN` and `NET_RAW` capabilities
|
|
- Uses `network_mode: host` for WOL packet transmission
|
|
- Must run with `privileged: true` for network operations
|
|
|
|
## Network Scanning
|
|
|
|
**Two scanning modes available:**
|
|
|
|
### 1. Container-based scanning (Limited)
|
|
- Uses Linux tools: `arp`, `ping`, `nmap`
|
|
- Limited in Docker Desktop Windows environment
|
|
- Fallback method when Windows scanning unavailable
|
|
|
|
### 2. Windows PowerShell scanning (Recommended)
|
|
- Script: `scripts/windows-network-scan.ps1`
|
|
- Features:
|
|
- Automatic local network detection
|
|
- Interactive network selection menu
|
|
- Parallel ping sweeps with configurable batch sizes
|
|
- Hostname resolution via DNS
|
|
- MAC address retrieval from ARP table/NetNeighbor
|
|
- Real-time progress indication
|
|
- Results saved to `/data/network-scan-results.json`
|
|
|
|
**Usage patterns:**
|
|
```powershell
|
|
# Interactive mode with network selection menu
|
|
scripts\windows-network-scan.ps1
|
|
|
|
# Direct network specification
|
|
scripts\windows-network-scan.ps1 -Network "192.168.1.0/24"
|
|
|
|
# Advanced options
|
|
scripts\windows-network-scan.ps1 -Network "192.168.100.0/24" -TimeoutMs 500 -BatchSize 20 -Verbose
|
|
```
|
|
|
|
**Integration:**
|
|
- Web app automatically reads Windows scan results from JSON file
|
|
- Results cached for 30 minutes
|
|
- App falls back to Linux scanning if Windows results unavailable
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /api/computers` - List configured computers with status
|
|
- `POST /api/wake` - Wake specific computer (`{mac, name, ip}`)
|
|
- `POST /api/wake-all` - Wake all configured computers
|
|
- `POST /api/add` - Add new computer (`{name, mac, ip}`)
|
|
- `GET /api/scan` - Network scan for devices (tries Windows results first, then Linux fallback)
|
|
- `POST /api/scan/windows` - Trigger Windows PowerShell scan (attempts automatic execution)
|
|
|
|
## Development Notes
|
|
|
|
- Application uses Romanian language in UI
|
|
- No authentication/authorization implemented
|
|
- Configuration persisted in volume-mounted `/data` directory
|
|
- Flask runs in debug=False mode in container
|
|
|
|
### Windows Integration Details
|
|
|
|
**File Integration:**
|
|
- Windows scan results: `/data/network-scan-results.json`
|
|
- Results format: `{success, timestamp, networks_scanned, computers[], message}`
|
|
- Computer format: `{ip, mac, hostname, status}`
|
|
- Results expire after 30 minutes
|
|
|
|
**WSL Integration:**
|
|
- App attempts automatic PowerShell execution via WSL interop
|
|
- Path: `/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe`
|
|
- Fallback: Manual execution instructions provided when auto-execution fails
|
|
|
|
**Scanning Logic in `app.py`:**
|
|
- `scan_network()` - Main entry point, tries Windows results first (`app/app.py:164`)
|
|
- `try_read_windows_scan_results()` - Reads and validates Windows JSON results (`app/app.py:176`)
|
|
- `scan_network_linux()` - Fallback Linux scanning using ARP/ping (`app/app.py:236`)
|
|
- Network filtering supported for custom CIDR ranges |