wolproxypy

This is a simple package for sending Wake-On-LAN packets to other host in a local network. This started as a pet-project to put together and test a series of technologies I'm interested in. The all WOL packet sending is managed by the Python package wakeonlan, for which wolproxypy act as a wrapper.

However, wolproxypy also offers a fully-dockerozed web app (built on Flask) and an API (built on FastAPI) that act as proxy for routing magic WOL packets via Internet.

Installation

As a package

The wolproxypy package is available on PyPI. You can choose either of the following option to install the dependency in your project:

poetry add wolproxypy - Install via poetry
pip install wolproxypy - Install via pip

As a local project

git clone https://github.com/bateman/wolproxypy - Clone the project from GitHub.
make install - Install all dependencies via poetry.
make docs - Build the documentation site via mkdocs.

Usage

Programmatically

Once installed in your project, you can access it programmatically as follows:

from wolproxypy import wol

wol(macaddress)

Acceptable formats for supplying a mac address are: - AA:BB:CC:DD:EE:FF - AA-BB-CC-DD-EE-FF - AABBCCDDEEFF - AABBCC.DDEEFF

As optional parameters you can supply also: - ip - the ip address of the host to send the magic packet to. - port - the port of the host to send the magic packet to. - interface the ip address of the network adapter to route the magic packet through.

Please, refer to the module documentation for more.

Command line

The following assumes that you cloned the image locally as described in the Installation step 1 above. You can run the tool from the command line as follows:

poetry run wolproxypy-cli <MAC>

The CLI has been built using Typer, so the following command will give yout this pretty-printed help menu with all the arguments.

poetry run wolproxypy-cli --help

Usage: wolproxypy-cli [OPTIONS] MAC

  Wake up computers having any of the given mac addresses.

  Wake on lan must be enabled on the host device. Leverages the PyPy package
  wakeonlan.

  Args:     mac: One or more mac addresses of machines to wake.

  Keyword Args:     ip: the ip address of the host to send the magic packet
  to.     port: the port of the host to send the magic packet to.
  interface: the ip address of the network adapter to route the magic packet
  through.

  Returns:     status: "success" if the magic packet was sent successfully;
  "failure" otherwise.

Arguments:
  MAC  [required]

Options:
  --ip TEXT                       [default: 255.255.255.255]
  --port INTEGER                  [default: 9]
  --interface TEXT
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

Web

To launch the web application, run poetry run wolproxypy-api and connect to http://127.0.0.0:8000. You can change the port by editing the file config/uvicorn.config.

Docker

Assuming that you have Docker installed on your system and that you have cloned the GitHub repository locally as per the Installation step 1 above, to build and executed the image locally, run:

docker-compose up -d --build

The app will be available at http://127.0.0.0:8000. To change the port, edit the file docker-compose.yml accordingly and rebuild the image.

You can stop it by executing docker-compose stop.

Alternatively, if you don't want to clone the repository, just download the latest image from DockerHub, run:

docker pull bateman/wolproxypy:latest

docker start bateman/wolproxypy

The app will be again accessible at http://127.0.0.0:8000.