wol-cli 0.1.0__py3-none-any.whl

wol_cli/__init__.py

@@ -0,0 +1,15 @@
+"""Wake-on-LAN magic packet sender with VLAN support."""
+
+__version__ = "0.1.0"
+
+from .packet import build_magic_packet, parse_mac
+from .transport import broadcast_from_network, send_dot1q, send_udp
+
+__all__ = [
+    "__version__",
+    "build_magic_packet",
+    "parse_mac",
+    "send_udp",
+    "send_dot1q",
+    "broadcast_from_network",
+]

wol_cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for python -m wol_cli."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

wol_cli/cli.py

@@ -0,0 +1,92 @@
+"""Command-line interface for Wake-on-LAN tool."""
+
+import argparse
+import sys
+
+from . import __version__
+from .transport import broadcast_from_network, send_dot1q, send_udp
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="wol",
+        description="Send a Wake-on-LAN magic packet, with optional VLAN support.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Plain UDP broadcast (same subnet)
+  wol AA:BB:CC:DD:EE:FF
+
+  # Directed broadcast - auto-computes 192.168.10.255
+  wol AA:BB:CC:DD:EE:FF --network 192.168.10.0/24
+
+  # 802.1Q tagged raw frame (Linux, must be root)
+  sudo wol AA:BB:CC:DD:EE:FF --vlan-id 10 --interface eth0
+        """,
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument("mac", help="Target MAC address (AA:BB:CC:DD:EE:FF)")
+    parser.add_argument(
+        "--ip",
+        default="255.255.255.255",
+        help="Explicit broadcast/unicast IP (UDP modes, default: 255.255.255.255)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=9, help="UDP port (default: 9)"
+    )
+    parser.add_argument(
+        "--network",
+        metavar="CIDR",
+        help="VLAN subnet in CIDR notation - derives directed broadcast IP (e.g. 192.168.10.0/24)",
+    )
+    parser.add_argument(
+        "--vlan-id",
+        type=int,
+        metavar="ID",
+        help="802.1Q VLAN ID 1-4094 - sends tagged raw Ethernet frame (requires --interface, root)",
+    )
+    parser.add_argument(
+        "--interface",
+        metavar="IFACE",
+        help="Egress network interface for raw 802.1Q mode (e.g. eth0)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for the CLI."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.vlan_id is not None:
+            # Mode 3: raw 802.1Q
+            if not args.interface:
+                parser.error("--vlan-id requires --interface")
+            send_dot1q(args.mac, args.vlan_id, args.interface, args.port)
+
+        elif args.network:
+            # Mode 2: directed broadcast via CIDR
+            bcast = broadcast_from_network(args.network)
+            print(f"[INFO] Directed broadcast for {args.network} -> {bcast}")
+            send_udp(args.mac, bcast, args.port)
+
+        else:
+            # Mode 1: plain UDP broadcast
+            send_udp(args.mac, args.ip, args.port)
+
+        return 0
+
+    except PermissionError:
+        print("[ERROR] Raw socket requires root privileges. Re-run with sudo.", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wol_cli/packet.py

@@ -0,0 +1,35 @@
+"""Magic packet construction for Wake-on-LAN."""
+
+import re
+import struct
+
+
+def parse_mac(mac: str) -> bytes:
+    """Parse a MAC address string into bytes.
+
+    Accepts formats: AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF, AABB.CCDD.EEFF
+    """
+    clean = re.sub(r"[:\-.]", "", mac).upper()
+    if len(clean) != 12 or not all(c in "0123456789ABCDEF" for c in clean):
+        raise ValueError(f"Invalid MAC address: {mac!r}")
+    return bytes.fromhex(clean)
+
+
+def build_magic_packet(mac: str) -> bytes:
+    """Build a Wake-on-LAN magic packet for the given MAC address.
+
+    The magic packet consists of 6 bytes of 0xFF followed by the target
+    MAC address repeated 16 times.
+    """
+    mac_bytes = parse_mac(mac)
+    return b"\xff" * 6 + mac_bytes * 16
+
+
+def checksum(data: bytes) -> int:
+    """Calculate IP/UDP checksum."""
+    if len(data) % 2:
+        data += b"\x00"
+    s: int = sum(struct.unpack(f"!{len(data)//2}H", data))
+    while s >> 16:
+        s = (s & 0xFFFF) + (s >> 16)
+    return ~s & 0xFFFF

wol_cli/transport.py

@@ -0,0 +1,130 @@
+"""Network transport methods for Wake-on-LAN packets."""
+
+import ipaddress
+import socket
+import struct
+import sys
+
+from .packet import build_magic_packet, checksum, parse_mac
+
+ETH_P_8021Q = 0x8100
+ETH_P_IP = 0x0800
+IPPROTO_UDP = 17
+
+
+def send_udp(mac: str, ip: str = "255.255.255.255", port: int = 9) -> None:
+    """Send a magic packet via UDP broadcast.
+
+    Args:
+        mac: Target MAC address
+        ip: Broadcast IP address (default: 255.255.255.255)
+        port: UDP port (default: 9)
+    """
+    packet = build_magic_packet(mac)
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        sock.connect((ip, port))
+        sock.send(packet)
+    print(f"[UDP] Magic packet sent to {mac} via {ip}:{port}")
+
+
+def broadcast_from_network(cidr: str) -> str:
+    """Compute the broadcast address for a given CIDR network."""
+    net = ipaddress.IPv4Network(cidr, strict=False)
+    return str(net.broadcast_address)
+
+
+def build_udp_payload(magic: bytes, dst_ip: str, port: int) -> bytes:
+    """Wrap magic packet in a minimal IPv4/UDP frame (no IP options)."""
+    src_ip_bytes = socket.inet_aton("0.0.0.0")
+    dst_ip_bytes = socket.inet_aton(dst_ip)
+
+    udp_len = 8 + len(magic)
+    # UDP pseudo-header for checksum
+    pseudo = src_ip_bytes + dst_ip_bytes + struct.pack("!BBH", 0, IPPROTO_UDP, udp_len)
+    udp_header_no_cs = struct.pack("!HHHH", port, port, udp_len, 0)
+    udp_cs = checksum(pseudo + udp_header_no_cs + magic)
+    udp_header = struct.pack("!HHHH", port, port, udp_len, udp_cs)
+
+    ip_len = 20 + udp_len
+    ip_header_no_cs = struct.pack(
+        "!BBHHHBBH4s4s",
+        0x45, 0,          # version+IHL, DSCP/ECN
+        ip_len,           # total length
+        0, 0,             # identification, flags+fragment offset
+        64, IPPROTO_UDP,  # TTL, protocol
+        0,                # checksum placeholder
+        src_ip_bytes,
+        dst_ip_bytes,
+    )
+    ip_cs = checksum(ip_header_no_cs)
+    ip_header = struct.pack(
+        "!BBHHHBBH4s4s",
+        0x45, 0, ip_len, 0, 0, 64, IPPROTO_UDP,
+        ip_cs, src_ip_bytes, dst_ip_bytes,
+    )
+
+    return ip_header + udp_header + magic
+
+
+def build_dot1q_frame(
+    magic: bytes,
+    src_mac: bytes,
+    dst_mac: bytes,
+    vlan_id: int,
+    dst_ip: str,
+    port: int,
+) -> bytes:
+    """Build a complete 802.1Q tagged Ethernet frame."""
+    if not (0 < vlan_id < 4095):
+        raise ValueError(f"VLAN ID must be 1-4094, got {vlan_id}")
+
+    tci = vlan_id & 0x0FFF  # PCP=0, DEI=0, VID=vlan_id
+    payload = build_udp_payload(magic, dst_ip, port)
+
+    return (
+        dst_mac
+        + src_mac
+        + struct.pack("!HHH", ETH_P_8021Q, tci, ETH_P_IP)
+        + payload
+    )
+
+
+def get_iface_mac(iface: str) -> bytes:
+    """Read the hardware MAC of a local interface (Linux /sys)."""
+    try:
+        path = f"/sys/class/net/{iface}/address"
+        with open(path) as f:
+            return parse_mac(f.read().strip())
+    except FileNotFoundError:
+        raise RuntimeError(f"Interface '{iface}' not found (or not on Linux)")
+
+
+def send_dot1q(mac: str, vlan_id: int, iface: str, port: int = 9) -> None:
+    """Send a magic packet via 802.1Q tagged raw Ethernet frame.
+
+    This mode requires Linux and root privileges.
+
+    Args:
+        mac: Target MAC address
+        vlan_id: VLAN ID (1-4094)
+        iface: Network interface name (e.g., eth0)
+        port: UDP port (default: 9)
+    """
+    if sys.platform != "linux":
+        raise RuntimeError("802.1Q raw socket mode is only supported on Linux")
+
+    magic = build_magic_packet(mac)
+    dst_mac = bytes.fromhex("ffffffffffff")  # Ethernet broadcast
+    src_mac = get_iface_mac(iface)
+    dst_ip = "255.255.255.255"
+
+    frame = build_dot1q_frame(magic, src_mac, dst_mac, vlan_id, dst_ip, port)
+
+    # ETH_P_ALL = 0x0003 -> send raw frames
+    ETH_P_ALL = 3
+    with socket.socket(socket.AF_PACKET, socket.SOCK_RAW, socket.htons(ETH_P_ALL)) as sock:
+        sock.bind((iface, 0))
+        sock.send(frame)
+
+    print(f"[802.1Q] Magic packet sent to {mac} on VLAN {vlan_id} via {iface}")

wol_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: wol-cli
+Version: 0.1.0
+Summary: Wake-on-LAN magic packet sender with VLAN support
+Project-URL: Homepage, https://github.com/yourusername/wol-cli-tool
+Project-URL: Repository, https://github.com/yourusername/wol-cli-tool
+Project-URL: Issues, https://github.com/yourusername/wol-cli-tool/issues
+Project-URL: Changelog, https://github.com/yourusername/wol-cli-tool/releases
+Author-email: Your Name <you@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: magic-packet,network,vlan,wake-on-lan,wol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.4.3; extra == 'dev'
+Requires-Dist: mypy>=1.20.0; extra == 'dev'
+Requires-Dist: pyinstaller>=6.19.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wol-cli
+
+[![CI](https://github.com/yourusername/wol-cli-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/wol-cli-tool/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/wol-cli.svg)](https://badge.fury.io/py/wol-cli)
+[![Python versions](https://img.shields.io/pypi/pyversions/wol-cli.svg)](https://pypi.org/project/wol-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Wake-on-LAN magic packet sender with VLAN support.
+
+## Features
+
+- **UDP Broadcast**: Standard Wake-on-LAN via UDP broadcast
+- **Directed Broadcast**: Auto-compute broadcast address from CIDR notation
+- **802.1Q VLAN Support**: Send tagged Ethernet frames directly (Linux only, requires root)
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install wol-cli
+```
+
+### From GitHub Releases (standalone binary)
+
+Download the appropriate binary for your platform from the [Releases](https://github.com/yourusername/wol-cli-tool/releases) page:
+
+- `wol-linux-amd64` - Linux x86_64
+- `wol-windows-amd64.exe` - Windows x86_64
+- `wol-macos-amd64` - macOS x86_64
+
+### From source
+
+```bash
+pip install .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Plain UDP Broadcast (same subnet)
+
+```bash
+wol AA:BB:CC:DD:EE:FF
+```
+
+### Directed Broadcast
+
+Auto-computes the broadcast address from a CIDR network:
+
+```bash
+wol AA:BB:CC:DD:EE:FF --network 192.168.10.0/24
+```
+
+### 802.1Q Tagged Frame (Linux only)
+
+Send a VLAN-tagged raw Ethernet frame (requires root):
+
+```bash
+sudo wol AA:BB:CC:DD:EE:FF --vlan-id 10 --interface eth0
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--ip IP` | Explicit broadcast/unicast IP (default: 255.255.255.255) |
+| `--port PORT` | UDP port (default: 9) |
+| `--network CIDR` | Subnet for directed broadcast (e.g., 192.168.10.0/24) |
+| `--vlan-id ID` | 802.1Q VLAN ID (1-4094) |
+| `--interface IFACE` | Network interface for 802.1Q mode |
+| `--version` | Show version |
+
+## Library Usage
+
+```python
+from wol_cli import send_udp, send_dot1q, build_magic_packet
+
+# Send via UDP broadcast
+send_udp("AA:BB:CC:DD:EE:FF")
+
+# Send via directed broadcast
+send_udp("AA:BB:CC:DD:EE:FF", ip="192.168.10.255")
+
+# Build a magic packet manually
+packet = build_magic_packet("AA:BB:CC:DD:EE:FF")
+```
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest -v
+```
+
+Run linter:
+
+```bash
+ruff check src/ tests/
+```
+
+Run type checker:
+
+```bash
+mypy src/
+```
+
+## Releasing
+
+Releases are automated via GitHub Actions. To create a new release:
+
+1. Update the version in `pyproject.toml` and `src/wol_cli/__init__.py`
+2. Commit the changes
+3. Create and push a tag:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+The workflow will automatically:
+- Run tests
+- Build binaries for Linux, Windows, and macOS
+- Build the Python package
+- Publish to PyPI
+- Create a GitHub release with all artifacts
+
+### PyPI Setup
+
+To enable PyPI publishing, add a `PYPI_API_TOKEN` secret to your repository:
+
+1. Go to [PyPI Account Settings](https://pypi.org/manage/account/token/)
+2. Create an API token
+3. Add it as a repository secret named `PYPI_API_TOKEN`
+
+## License
+
+MIT

wol_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+wol_cli/__init__.py,sha256=Rw-fw2stZBmSzK7SYbMmaz2oXI6kG49UMC5dejWnt9U,340
+wol_cli/__main__.py,sha256=4XKkh05uFu3nM1s9a3rvk9_LnLoEVUEN77cIx-1MXfk,125
+wol_cli/cli.py,sha256=5kEmrbc8bBElyk6r-Phf_Xlr9j8gOs0pm2EwhboOeJM,2855
+wol_cli/packet.py,sha256=-QKUEjqqyI9JHnanMYJFEGtAZy242Q5svH2cF3hH9mM,1008
+wol_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wol_cli/transport.py,sha256=-VJ7B6mYTkBRuieGA7zdi8vYTlCMP0guR6tR3VdGSnI,4111
+wol_cli-0.1.0.dist-info/METADATA,sha256=XJvrXMS41Jxs_YnTMV4XsPyoDRyJAWqHdkuxrx6c-QI,4690
+wol_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wol_cli-0.1.0.dist-info/entry_points.txt,sha256=nLHk6MW6XSWtr1_QRxWjOpfBqAg0v7Wa9shn2sq6lBY,41
+wol_cli-0.1.0.dist-info/licenses/LICENSE,sha256=dUhuoK-TCRQMpuLEAdfme-qPSJI0TlcH9jlNxeg9_EQ,1056
+wol_cli-0.1.0.dist-info/RECORD,,

wol_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wol_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wol = wol_cli.cli:main

wol_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.