wolsocketproxy 0.1.1__tar.gz → 0.3.0__tar.gz

wolsocketproxy-0.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: wolsocketproxy
+Version: 0.3.0
+Summary: A socket proxy with wake-on-lan feature.
+Author-email: Song Fuchang <song.fc@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: source, https://github.com/notsyncing/wolsocketproxy
+Project-URL: issues, https://github.com/notsyncing/wol-socket-proxy/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp==3.13.5
+Requires-Dist: dataclass-wizard==0.39.1
+Requires-Dist: icmplib==3.0.4
+Requires-Dist: redfish==3.3.5
+Requires-Dist: setproctitle==1.3.7
+Requires-Dist: wakeonlan==3.1.0
+Provides-Extra: dev
+Requires-Dist: wolsocketproxy[lint]; extra == "dev"
+Requires-Dist: wolsocketproxy[build]; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ty; extra == "lint"
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: build
+Requires-Dist: build[virtualenv]==1.5.0; extra == "build"
+Dynamic: license-file
+
+# wol-socket-proxy
+
+A socket proxy with wake-on-lan and IPMI power control feature.
+
+It can forward TCP(bidirectional) and UDP(send-only) traffic from local machine to remote machine, and:
+
+- send a magic packet to wake it (wake-on-lan) 
+- invoke IPMI power on to wake it
+
+before forwarding traffic if the remote machine does not respond to ICMP ping or some HTTP URL.
+
+## Requirements
+
+Python 3.12+
+
+The remote machine must accept and respond to ICMP ping requests if you use `ping` method.
+
+## Usage
+
+You can install it from PyPI or use a prebuilt docker image.
+
+### Install from PyPI
+
+Simply install it:
+
+```
+pip install wolsocketproxy
+```
+
+Then create a config file:
+
+```
+cp wolsocketproxy.conf.example /etc/wolsocketproxy.conf
+```
+
+Modify the config file as your requirements.
+
+Finally, run it:
+
+```
+wolsocketproxy
+```
+
+### Use prebuilt docker image
+
+See `docker/docker-compose.yml` for more details.
+
+## Config
+
+The `wolsocketproxy.conf` has the following structure:
+
+```json5
+{
+    // NOTE: Comments are not allowed in actual config file
+
+    // Define machines
+    "machines": {
+        "some-server": {
+            "ip_address": "192.168.1.124",                              // the IP address of this machine, optional
+            "mac_address": "11:22:33:44:55:66",                         // The MAC address of this machine, optional
+            "wake_up_method": "ipmi",                                   // How to wake up this machine
+                                                                        //   "ipmi" - You must specify "ipmi_config_name"
+                                                                        //   "wol" - You must specify "mac_address"
+            "ipmi_config_name": "some-server-ipmi",                     // IPMI config of this machine, must match what defined in "ipmi_configs"
+            "online_check_method": "http",                              // How to check this machine is online
+                                                                        //   "http" - You must specify "online_check_http_url"
+                                                                        //   "ping" - You must specify "ip_address"
+            "online_check_http_url": "http://192.168.1.124/health",     // The URL used to check if machine is online, optional
+            "online_check_timeout": 300,                                // Timeout when checking machine is online, seconds, optional, default is 60
+            "online_check_http_expected_code": 200,                     // Expected HTTP status code when using "http" method, optional, default is 200
+            "ipmi_force_reset_if_power_up_failed": true,                // Use IPMI power reset if this machine is not online after timeout, optional, default is false
+            "ipmi_max_reset_try_count": 3                               // Max IPMI power reset retry count before giving-up, optional, default is 3
+        },
+        // ... more machines ...
+    },
+
+    // Define forwarding routes
+    "routes": [
+        {
+            "local_address": "0.0.0.0",              // The local address to listen
+            "local_port": 12345,                     // The local port to listen
+            "target_machine_name": "some-server",    // The target machine name, must match what defined in "machines"
+            "target_address": "192.168.1.124",       // The target address forwarding to
+            "target_port": 12345,                    // The target port forwarding to
+            "protocol": "tcp"                        // The protocol to use, can choose "tcp" or "udp"
+        },
+        // ... more routes ...
+    ],
+
+    // Define IPMI configs, optional
+    "ipmi_configs": [
+        {
+            "name": "some-server-ipmi",                 // IPMI config name
+            "redfish_url": "https://192.168.1.123/",    // IPMI Redfish API base URL (should not contain /redfish/v1)
+            "username": "admin",                        // IPMI Redfish API login username
+            "password": "123456"                        // IPMI Redfish API login password
+        },
+        // ... more IPMI configs ...
+    ]
+}
+```
+
+## Additional modes
+
+### Keep-alive daemon mode
+
+This mode is used for running on target machine with auto-suspend (e.g. running `circadian` or similar), to keep the target
+machine from auto suspending when running tasks.
+
+Use the following command on the target machine to enter this mode:
+
+```bash
+wolsocketproxy -k
+```
+
+The config file `wolsocketproxy.conf` should look like the following:
+
+
+```json5
+// Keep-alive daemon mode
+{
+    "listen_address": "0.0.0.0",                // The address to listen for HTTP server, default is 127.0.0.1
+    "listen_port": 18080,                       // The port to listen for HTTP server, default is 18080
+    "watchdog_feed_interval": 60,               // Watchdog feed interval, seconds, default is 600
+    "keep_alive_method": "special_process",     // How to keep target machine alive, default is "special_process"
+                                                //   "special_process" - Fork a child process with specified name
+    "special_process_name": "wsp-keepalive",    // The display name of the forked child process, default is "wsp-keepalive"
+}
+```
+
+You need to periodically send an HTTP GET request to `/watchdog/feed` at the `listen_port` in `watchdog_feed_interval` time,
+or the special process will be killed.
+You can combine this mode with `circadian`'s `process_block` config to keep it from auto-suspending.

wolsocketproxy-0.3.0/README.md

@@ -0,0 +1,133 @@
+# wol-socket-proxy
+
+A socket proxy with wake-on-lan and IPMI power control feature.
+
+It can forward TCP(bidirectional) and UDP(send-only) traffic from local machine to remote machine, and:
+
+- send a magic packet to wake it (wake-on-lan) 
+- invoke IPMI power on to wake it
+
+before forwarding traffic if the remote machine does not respond to ICMP ping or some HTTP URL.
+
+## Requirements
+
+Python 3.12+
+
+The remote machine must accept and respond to ICMP ping requests if you use `ping` method.
+
+## Usage
+
+You can install it from PyPI or use a prebuilt docker image.
+
+### Install from PyPI
+
+Simply install it:
+
+```
+pip install wolsocketproxy
+```
+
+Then create a config file:
+
+```
+cp wolsocketproxy.conf.example /etc/wolsocketproxy.conf
+```
+
+Modify the config file as your requirements.
+
+Finally, run it:
+
+```
+wolsocketproxy
+```
+
+### Use prebuilt docker image
+
+See `docker/docker-compose.yml` for more details.
+
+## Config
+
+The `wolsocketproxy.conf` has the following structure:
+
+```json5
+{
+    // NOTE: Comments are not allowed in actual config file
+
+    // Define machines
+    "machines": {
+        "some-server": {
+            "ip_address": "192.168.1.124",                              // the IP address of this machine, optional
+            "mac_address": "11:22:33:44:55:66",                         // The MAC address of this machine, optional
+            "wake_up_method": "ipmi",                                   // How to wake up this machine
+                                                                        //   "ipmi" - You must specify "ipmi_config_name"
+                                                                        //   "wol" - You must specify "mac_address"
+            "ipmi_config_name": "some-server-ipmi",                     // IPMI config of this machine, must match what defined in "ipmi_configs"
+            "online_check_method": "http",                              // How to check this machine is online
+                                                                        //   "http" - You must specify "online_check_http_url"
+                                                                        //   "ping" - You must specify "ip_address"
+            "online_check_http_url": "http://192.168.1.124/health",     // The URL used to check if machine is online, optional
+            "online_check_timeout": 300,                                // Timeout when checking machine is online, seconds, optional, default is 60
+            "online_check_http_expected_code": 200,                     // Expected HTTP status code when using "http" method, optional, default is 200
+            "ipmi_force_reset_if_power_up_failed": true,                // Use IPMI power reset if this machine is not online after timeout, optional, default is false
+            "ipmi_max_reset_try_count": 3                               // Max IPMI power reset retry count before giving-up, optional, default is 3
+        },
+        // ... more machines ...
+    },
+
+    // Define forwarding routes
+    "routes": [
+        {
+            "local_address": "0.0.0.0",              // The local address to listen
+            "local_port": 12345,                     // The local port to listen
+            "target_machine_name": "some-server",    // The target machine name, must match what defined in "machines"
+            "target_address": "192.168.1.124",       // The target address forwarding to
+            "target_port": 12345,                    // The target port forwarding to
+            "protocol": "tcp"                        // The protocol to use, can choose "tcp" or "udp"
+        },
+        // ... more routes ...
+    ],
+
+    // Define IPMI configs, optional
+    "ipmi_configs": [
+        {
+            "name": "some-server-ipmi",                 // IPMI config name
+            "redfish_url": "https://192.168.1.123/",    // IPMI Redfish API base URL (should not contain /redfish/v1)
+            "username": "admin",                        // IPMI Redfish API login username
+            "password": "123456"                        // IPMI Redfish API login password
+        },
+        // ... more IPMI configs ...
+    ]
+}
+```
+
+## Additional modes
+
+### Keep-alive daemon mode
+
+This mode is used for running on target machine with auto-suspend (e.g. running `circadian` or similar), to keep the target
+machine from auto suspending when running tasks.
+
+Use the following command on the target machine to enter this mode:
+
+```bash
+wolsocketproxy -k
+```
+
+The config file `wolsocketproxy.conf` should look like the following:
+
+
+```json5
+// Keep-alive daemon mode
+{
+    "listen_address": "0.0.0.0",                // The address to listen for HTTP server, default is 127.0.0.1
+    "listen_port": 18080,                       // The port to listen for HTTP server, default is 18080
+    "watchdog_feed_interval": 60,               // Watchdog feed interval, seconds, default is 600
+    "keep_alive_method": "special_process",     // How to keep target machine alive, default is "special_process"
+                                                //   "special_process" - Fork a child process with specified name
+    "special_process_name": "wsp-keepalive",    // The display name of the forked child process, default is "wsp-keepalive"
+}
+```
+
+You need to periodically send an HTTP GET request to `/watchdog/feed` at the `listen_port` in `watchdog_feed_interval` time,
+or the special process will be killed.
+You can combine this mode with `circadian`'s `process_block` config to keep it from auto-suspending.

wolsocketproxy-0.3.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wolsocketproxy"
+version = "0.3.0"
+description = "A socket proxy with wake-on-lan feature."
+authors = [
+    {name = "Song Fuchang", email = "song.fc@gmail.com"}
+]
+license = "Apache-2.0"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Topic :: System :: Networking"
+]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp==3.13.5",
+    "dataclass-wizard==0.39.1",
+    "icmplib==3.0.4",
+    "redfish==3.3.5",
+    "setproctitle==1.3.7",
+    "wakeonlan==3.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "wolsocketproxy[lint]",
+    "wolsocketproxy[build]",
+]
+lint = [
+    "ty",
+    "ruff",
+]
+build = [
+    "build[virtualenv]==1.5.0",
+]
+
+[project.urls]
+source = "https://github.com/notsyncing/wolsocketproxy"
+issues = "https://github.com/notsyncing/wol-socket-proxy/issues"
+
+[project.scripts]
+wolsocketproxy = "wolsocketproxy:main"
+
+[tool.ruff]
+line-length = 120
+src = ["src"]
+target-version = "py312"
+lint.select = ["ALL"]
+lint.ignore = [
+    "ASYNC110",
+    "COM812",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D107",
+    "D203",
+    "D211",
+    "D213",
+    "DTZ005",
+    "S101",
+    "EM102",
+    "FBT001",
+    "FBT003",
+    "ISC001",
+    "TRY003",
+    "TRY201",
+]

wolsocketproxy-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wolsocketproxy-0.3.0/src/wolsocketproxy/__init__.py

@@ -0,0 +1,75 @@
+import json
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+from sys import stdout
+
+import dataclass_wizard
+
+from wolsocketproxy.keepalive import KeepAliveConfig, KeepAliveDaemon
+from wolsocketproxy.proxy import Proxy, ProxyConfig
+
+
+def main() -> None:
+    logging.basicConfig(
+        format="%(asctime)s %(levelname)-8s %(name)s %(message)s",
+        level=logging.INFO,
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[
+            logging.StreamHandler(
+                stream=stdout,
+            ),
+        ],
+        force=True,
+    )
+
+    log = logging.getLogger()
+
+    parser = ArgumentParser(prog="wolsocketproxy", description="A socket proxy with wake-on-lan feature.")
+
+    parser.add_argument(
+        "-k",
+        "--keep-alive",
+        dest="keep_alive_mode",
+        default=False,
+        action="store_true",
+        help="Start in keep-alive daemon mode",
+    )
+
+    parser.add_argument(
+        "-c",
+        "--config",
+        help="The config file to use, default lookup order: /etc/wolsocketproxy.conf, ./wolsocketproxy.conf",
+    )
+
+    args = parser.parse_args()
+    config_path: Path
+
+    if "config" in args and args.config is not None:
+        config_path = Path(args.config)
+    else:
+        config_path = Path("/etc/wolsocketproxy.conf")
+
+        if not config_path.exists():
+            config_path = Path("./wolsocketproxy.conf")
+
+    if not config_path.exists():
+        log.error("Config file path %s does not exist!", config_path)
+        return
+
+    config_data = json.loads(config_path.read_text())
+
+    if args.keep_alive_mode:
+        config = dataclass_wizard.fromdict(KeepAliveConfig, config_data)
+
+        log.info("Loaded keep-alive mode config from %s", config_path)
+
+        keep_alive_daemon = KeepAliveDaemon(config)
+        keep_alive_daemon.start()
+    else:
+        config = dataclass_wizard.fromdict(ProxyConfig, config_data)
+
+        log.info("Loaded proxy mode config from %s", config_path)
+
+        proxy = Proxy(config)
+        proxy.start()

wolsocketproxy-0.3.0/src/wolsocketproxy/keepalive.py

@@ -0,0 +1,153 @@
+import asyncio
+import logging
+import os
+import signal
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from threading import Thread
+from typing import Literal
+
+from aiohttp import web
+from aiohttp.web import Request, Response
+from setproctitle import setproctitle
+
+
+@dataclass
+class KeepAliveConfig:
+    listen_address: str = "127.0.0.1"
+    listen_port: int = 18080
+
+    watchdog_feed_interval: int = 600
+
+    keep_alive_method: Literal["special_process"] = "special_process"
+
+    special_process_name: str | None = "wsp-keepalive"
+
+
+class KeepAliveDaemon:
+    _log: logging.Logger = logging.getLogger(__name__)
+
+    _config: KeepAliveConfig
+    _web_app: web.Application
+
+    _watchdog_last_feed_time: datetime
+    _watchdog_is_hungry: bool = False
+
+    _special_process_id: int = -1
+
+    def __init__(self, config: KeepAliveConfig) -> None:
+        self._config = config
+
+        self._web_app = web.Application()
+
+        self._web_app.add_routes(
+            [
+                web.get("/watchdog/feed", self._handle_watchdog_feed)
+            ]
+        )
+
+    async def _watchdog_timer(self) -> None:
+        while True:
+            previous_is_hungry = self._watchdog_is_hungry
+            last_feed_interval = datetime.now() - self._watchdog_last_feed_time
+
+            if last_feed_interval.total_seconds() > self._config.watchdog_feed_interval:
+                self._watchdog_is_hungry = True
+            else:
+                self._watchdog_is_hungry = False
+
+            if not previous_is_hungry and self._watchdog_is_hungry:
+                Thread(target=self._on_watchdog_hungry, daemon=True).start()
+            elif previous_is_hungry and not self._watchdog_is_hungry:
+                Thread(target=self._on_watchdog_feed, daemon=True).start()
+
+            await asyncio.sleep(1)
+
+    def _on_watchdog_hungry(self) -> None:
+        self._log.warning("Watchdog is hungry!")
+
+        if self._special_process_id > 0:
+            os.kill(self._special_process_id, signal.SIGKILL)
+            os.waitpid(self._special_process_id, 0)
+            self._log.warning("Killed special process PID %d", self._special_process_id)
+            self._special_process_id = -1
+
+    def _on_watchdog_feed(self) -> None:
+        self._log.info("Watchdog is feed.")
+
+        if self._config.keep_alive_method == "special_process" and self._special_process_id < 0:
+            self._start_special_process()
+
+    def _special_process(self) -> None:
+        assert self._config.special_process_name is not None
+        setproctitle(self._config.special_process_name)
+
+        while True:
+            time.sleep(60)
+
+            if os.getppid() == 1:
+                os._exit(0)
+
+    def _start_special_process(self) -> bool:
+        self._special_process_id = os.fork()
+
+        if self._special_process_id == 0:
+            self._special_process()
+            return True
+
+        self._log.info(
+            "Started special process with name %s, PID %d",
+            self._config.special_process_name, self._special_process_id
+        )
+
+        return False
+
+    def start(self) -> None:
+        self._watchdog_last_feed_time = datetime.now()
+        self._watchdog_is_hungry = False
+
+        if self._config.keep_alive_method == "special_process":  # noqa: SIM102
+            if self._start_special_process():
+                return
+
+        loop = asyncio.new_event_loop()
+
+        def _start_loop() -> None:
+            asyncio.set_event_loop(loop)
+            loop.run_forever()
+
+        Thread(target=_start_loop, daemon=True).start()
+
+        watchdog_task = asyncio.run_coroutine_threadsafe(self._watchdog_timer(), loop)
+
+        self._log.info(
+            "Keep-alive daemon started at %s:%d, watchdog feed interval %ds.",
+            self._config.listen_address, self._config.listen_port, self._config.watchdog_feed_interval
+        )
+
+        web.run_app(self._web_app, host=self._config.listen_address, port=self._config.listen_port)
+
+        self._log.info("Stopping...")
+
+        watchdog_task.cancel()
+        loop.stop()
+
+        if self._special_process_id > 0:
+            os.kill(self._special_process_id, signal.SIGKILL)
+            os.waitpid(self._special_process_id, 0)
+
+        self._log.info("Stopped.")
+
+    async def _handle_watchdog_feed(self, _: Request) -> Response:
+        last_feed = self._watchdog_last_feed_time
+        self._watchdog_last_feed_time = datetime.now()
+        interval = (self._watchdog_last_feed_time - last_feed).total_seconds()
+
+        return web.json_response(
+            {
+                "status": "ok",
+                "last_feed": last_feed.strftime("%Y-%m-%d %H:%M:%S"),
+                "interval": interval,
+            }
+        )