wolsocketproxy 0.1.0__tar.gz → 0.2.0__tar.gz

wolsocketproxy-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: wolsocketproxy
+Version: 0.2.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: 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.4.2; 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 300
+            "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 ...
+    ]
+}
+```

wolsocketproxy-0.2.0/README.md

@@ -0,0 +1,101 @@
+# 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 300
+            "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 ...
+    ]
+}
+```

wolsocketproxy-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wolsocketproxy"
+version = "0.2.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",
+    "wakeonlan==3.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "wolsocketproxy[lint]",
+    "wolsocketproxy[build]",
+]
+lint = [
+    "ty",
+    "ruff",
+]
+build = [
+    "build[virtualenv]==1.4.2",
+]
+
+[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 = [
+    "COM812",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D107",
+    "D203",
+    "D211",
+    "D213",
+    "S101",
+    "EM102",
+    "FBT001",
+    "FBT003",
+    "ISC001",
+    "TRY003",
+    "TRY201",
+]

wolsocketproxy-0.2.0/setup.cfg

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

wolsocketproxy-0.2.0/src/wolsocketproxy/monitor.py

@@ -0,0 +1,129 @@
+import asyncio
+import logging
+from dataclasses import dataclass
+from logging import Logger
+from threading import Thread
+from typing import Literal
+
+from aiohttp import ClientConnectionError, ClientSession, ClientTimeout
+from icmplib.multiping import async_multiping
+
+
+@dataclass
+class MonitorConfig:
+    online_check_method: Literal["ping", "http"] = "ping"
+    online_check_ip_address: str | None = None
+    online_check_http_url: str | None = None
+    online_check_http_expected_code: int = 200
+    online_check_timeout: int = 60
+
+
+class Monitor:
+    _log: Logger = logging.getLogger()
+    _monitor_configs: dict[str, MonitorConfig]
+    _machine_states: dict[str, bool]
+    _stop: bool = False
+
+    def __init__(self, watching_machines: dict[str, MonitorConfig]) -> None:
+        self._monitor_configs = {}
+        self._machine_states = {}
+
+        for name, config in watching_machines.items():
+            self._monitor_configs[name] = config
+            self._machine_states[name] = False
+
+    def start(self) -> None:
+        def _start() -> None:
+            asyncio.run(self.__check_machine_states())
+
+        t = Thread(target=_start, daemon=True)
+        t.start()
+
+    def stop(self) -> None:
+        self._stop = True
+
+    async def __check_http_urls(self, configs: dict[str, MonitorConfig]) -> dict[str, bool]:
+        if len(configs) <= 0:
+            return {}
+
+        async def fetch(session: ClientSession, url: str, timeout: ClientTimeout) -> int:  # noqa: ASYNC109
+            try:
+                async with session.get(url, timeout=timeout) as resp:
+                    return resp.status
+            except ClientConnectionError:
+                return -1
+
+        results = {}
+        result_names = []
+        result_futures = []
+
+        async with ClientSession(timeout=ClientTimeout(total=30)) as session:
+            for name, conf in configs.items():
+                assert conf.online_check_method == "http"
+                assert conf.online_check_http_url is not None
+
+                resp_future = fetch(
+                    session, conf.online_check_http_url, timeout=ClientTimeout(total=conf.online_check_timeout)
+                )
+
+                result_names.append(name)
+                result_futures.append(resp_future)
+
+            http_results = await asyncio.gather(*result_futures)
+
+            for i, http_result in enumerate(http_results):
+                results[result_names[i]] = http_result == conf.online_check_http_expected_code
+
+        return results
+
+    async def __check_machine_states(self) -> None:
+        self._log.info("Monitor started.")
+
+        while not self._stop:
+            ping_ip_list = [
+                conf.online_check_ip_address
+                for conf in self._monitor_configs.values()
+                if conf.online_check_method == "ping"
+            ]
+
+            if len(ping_ip_list) > 0:
+                ping_results_future = async_multiping(ping_ip_list, count=3, timeout=2, privileged=False)
+            else:
+                ping_results_future = asyncio.Future()
+                ping_results_future.set_result([])
+
+            http_results_future = self.__check_http_urls(
+                configs={
+                    name: conf for name, conf in self._monitor_configs.items() if conf.online_check_method == "http"
+                }
+            )
+
+            ping_results, http_results = await asyncio.gather(ping_results_future, http_results_future)
+
+            for result in ping_results:
+                original_state = self._machine_states[result.address]
+                self._machine_states[result.address] = result.is_alive
+
+                if original_state != result.is_alive:
+                    if original_state is False:
+                        self._log.info("Target %s now online by ping.", result.address)
+                    else:
+                        self._log.info("Target %s now offline by ping.", result.address)
+
+            for ip, result in http_results.items():
+                original_state = self._machine_states[ip]
+                self._machine_states[ip] = result
+
+                if original_state != result:
+                    if original_state is False:
+                        self._log.info("Target %s now online by http.", ip)
+                    else:
+                        self._log.info("Target %s now offline by http.", ip)
+
+            await asyncio.sleep(1)
+
+    def report_availablity(self, machine_name: str, available: bool) -> None:
+        self._machine_states[machine_name] = available
+
+    def is_available(self, machine_name: str) -> bool:
+        return self._machine_states.get(machine_name, False)