openvpn-status-reader 0.3.0__py3-none-any.whl

openvpn_status/__init__.py

@@ -0,0 +1,5 @@
+from .parser import ParsingError
+from .shortcuts import parse_status
+from .version import __version__
+
+__all__ = ["parse_status", "ParsingError", "__version__"]

openvpn_status/descriptors.py

@@ -0,0 +1,51 @@
+class LabelProperty:
+    """The property with label name."""
+
+    def __init__(self, label, default=None, input_type=None):
+        self.label = label
+        self.default = default
+        self.input_type = input_type
+        self.__name__ = None
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        if self.__name__ in instance.__dict__:
+            return instance.__dict__[self.__name__]
+        elif self.default is not None:
+            value = self.default()
+            instance.__dict__[self.__name__] = value
+            return value
+        else:
+            names = (owner.__name__, self.__name__)
+            raise AttributeError("%r object has no attribute %r" % names)
+
+    def __set__(self, instance, value):
+        if self.input_type is not None:
+            try:
+                value = self.input_type(value)
+            except ValueError as e:
+                raise AssignmentValueError(e)
+        instance.__dict__[self.__name__] = value
+
+
+_missing = object()
+
+
+def name_descriptors(cls):
+    for name, value in iter_descriptors(cls):
+        if getattr(value, "__name__", _missing) is None:
+            value.__name__ = name
+    return cls
+
+
+def iter_descriptors(cls):
+    for name, value in cls.__dict__.items():
+        if name.startswith("__"):
+            continue
+        if getattr(value, "__get__", None) or getattr(value, "__set__", None):
+            yield name, value
+
+
+class AssignmentValueError(ValueError):
+    pass

openvpn_status/models.py

@@ -0,0 +1,44 @@
+from collections import OrderedDict
+
+from .descriptors import LabelProperty, name_descriptors
+from .utils import parse_filesize, parse_peer, parse_time, parse_vaddr
+
+
+@name_descriptors
+class Status:
+    """The OpenVPN status model."""
+
+    client_list = LabelProperty("OpenVPN CLIENT LIST", OrderedDict)
+    routing_table = LabelProperty("ROUTING TABLE", OrderedDict)
+    global_stats = LabelProperty("GLOBAL STATS")
+    updated_at = LabelProperty("Updated", input_type=parse_time)
+
+
+@name_descriptors
+class Client:
+    """The OpenVPN client model."""
+
+    common_name = LabelProperty("Common Name")
+    real_address = LabelProperty("Real Address", input_type=parse_peer)
+    bytes_received = LabelProperty("Bytes Received", input_type=parse_filesize)
+    bytes_sent = LabelProperty("Bytes Sent", input_type=parse_filesize)
+    connected_since = LabelProperty("Connected Since", input_type=parse_time)
+
+
+@name_descriptors
+class Routing:
+    """The OpenVPN routing model."""
+
+    virtual_address = LabelProperty("Virtual Address", input_type=parse_vaddr)
+    common_name = LabelProperty("Common Name")
+    real_address = LabelProperty("Real Address", input_type=parse_peer)
+    last_ref = LabelProperty("Last Ref", input_type=parse_time)
+
+
+@name_descriptors
+class GlobalStats:
+    """The OpenVPN global stats model."""
+
+    max_bcast_mcast_queue_len = LabelProperty(
+        "Max bcast/mcast queue length", input_type=int
+    )

openvpn_status/parser.py

@@ -0,0 +1,144 @@
+from collections.abc import Iterator
+
+from .descriptors import AssignmentValueError, iter_descriptors
+from .models import Client, GlobalStats, Routing, Status
+
+
+class LogParser(Iterator):
+    """The parser for parsing OpenVPN status log.
+
+    This kind of parser is stateful. So the :meth:`LogParser.parse` could be
+    called once in the same instance of parser.
+    """
+
+    list_separator = ","
+    line_separator = "\n"
+    terminator = "END"
+
+    def __init__(self, lines):
+        self.lines = iter(lines)
+        self._last_line = None
+        self._rollback = False
+
+    def __next__(self):
+        if self._rollback:
+            self._rollback = False
+            return self._last_line
+        while True:
+            line = next(self.lines).strip()
+            if line:
+                self._last_line = line
+                return line
+
+    @classmethod
+    def fromstring(cls, content):
+        """Creates a parser from content of log.
+
+        :param str content: The log content.
+        :return: The parser instance.
+        """
+        return cls(content.strip().split(cls.line_separator))
+
+    def rollback(self):
+        self._rollback = True
+
+    def expect_line(self, content):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected %r but got end of input" % content)
+        if line != content:
+            raise ParsingError("expected %r but got %r" % (content, line))
+
+    def expect_list(self):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected list but got end of input")
+        splited = line.split(self.list_separator)
+        if len(splited) == 1:
+            raise ParsingError("expected list but got %r" % line)
+        return splited
+
+    def expect_tuple(self, name):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected 2-tuple but got end of input")
+        splited = line.split(self.list_separator)
+        if len(splited) != 2:
+            raise ParsingError("expected 2-tuple but got %r" % line)
+        if splited[0] != name:
+            raise ParsingError("expected 2-tuple starting with %r" % name)
+        return splited[1]
+
+    def parse(self):
+        """Parses the status log.
+
+        :raises ParsingError: if syntax error found in the log.
+        :return: The :class:`.models.Status` with filled data.
+        """
+        try:
+            return self._parse()
+        except AssignmentValueError as e:
+            msg = str(e).encode("ascii", "backslashreplace").decode("ascii")
+            raise ParsingError("expected valid format: %s" % msg)
+
+    def _parse(self):
+        status = Status()
+        self.expect_line(Status.client_list.label)
+
+        status.updated_at = self.expect_tuple(Status.updated_at.label)
+        status.client_list.update(
+            {
+                str(c.real_address): c
+                for c in self._parse_fields(Client, Status.routing_table.label)
+            }
+        )
+        status.routing_table.update(
+            {
+                str(r.virtual_address): r
+                for r in self._parse_fields(Routing, Status.global_stats.label)
+            }
+        )
+        status.global_stats = GlobalStats()
+        status.global_stats.max_bcast_mcast_queue_len = self.expect_tuple(
+            GlobalStats.max_bcast_mcast_queue_len.label
+        )
+
+        self.expect_line(self.terminator)
+        return status
+
+    def _parse_fields(self, cls, next_line):
+        labels = self.expect_list()
+        descriptors = iter_descriptors(cls)
+        label_to_name = {descriptor.label: name for name, descriptor in descriptors}
+        if len(labels) != len(label_to_name) or set(labels) != set(label_to_name):
+            raise ParsingError("invalid fields for %s" % cls.__name__)
+        index_to_name = {
+            index: label_to_name[label] for index, label in enumerate(labels)
+        }
+
+        while True:
+            try:
+                values = self.expect_list()
+            except ParsingError as list_error:
+                try:
+                    self.rollback()
+                    self.expect_line(next_line)
+                except ParsingError as line_error:
+                    raise ParsingError(*(list_error.args + line_error.args))
+                else:
+                    break
+
+            if len(values) != len(index_to_name):
+                raise ParsingError("invalid fields for %s" % cls.__name__)
+            instance = cls()
+            for index, value in enumerate(values):
+                name = index_to_name[index]
+                setattr(instance, name, value)
+            yield instance
+
+
+class ParsingError(Exception):
+    pass

openvpn_status/shortcuts.py

@@ -0,0 +1,16 @@
+from .parser import LogParser
+
+
+def parse_status(status_log, encoding="utf-8"):
+    """Parses the status log of OpenVPN.
+
+    :param status_log: The content of status log.
+    :type status_log: :class:`str`
+    :param encoding: Optional. The encoding of status log.
+    :type encoding: :class:`str`
+    :return: The instance of :class:`.models.Status`
+    """
+    if isinstance(status_log, bytes):
+        status_log = status_log.decode(encoding)
+    parser = LogParser.fromstring(status_log)
+    return parser.parse()

openvpn_status/utils.py

@@ -0,0 +1,82 @@
+import collections
+import datetime
+import ipaddress
+import re
+
+from humanize.filesize import naturalsize
+from netaddr import EUI, mac_unix
+
+DATETIME_FORMAT_OPENVPN_V2_5 = "%Y-%m-%d %H:%M:%S"
+DATETIME_FORMAT_OPENVPN_V2_4 = "%a %b %d %H:%M:%S %Y"
+RE_VIRTUAL_ADDR_MAC = re.compile(r"^(?:[a-f0-9]{2}:){5}[a-f0-9]{2}(?:@\d+)?$", re.I)
+RE_VIRTUAL_ADDR_NETWORK = re.compile("/(\\d{1,3})$")
+RE_VIRTUAL_ADDR_CLIENT = re.compile("C$")
+
+
+def parse_time(time):
+    """Parses date and time from input string in OpenVPN logging format."""
+    if isinstance(time, datetime.datetime):
+        return time
+    try:
+        # Try the current numeric timestamp before the legacy format.
+        return datetime.datetime.strptime(time, DATETIME_FORMAT_OPENVPN_V2_5)
+    except ValueError:
+        return datetime.datetime.strptime(time, DATETIME_FORMAT_OPENVPN_V2_4)
+
+
+def parse_peer(peer):
+    if isinstance(peer, PeerAddress):
+        return peer
+    host, port = peer.rsplit(":", 1)
+    return PeerAddress(ipaddress.ip_address(host), int(port))
+
+
+def parse_vaddr(virtual_addr):
+    match = RE_VIRTUAL_ADDR_MAC.search(virtual_addr)
+    if match:
+        return EUI(virtual_addr.split("@")[0], dialect=mac_unix)
+
+    match = RE_VIRTUAL_ADDR_NETWORK.search(virtual_addr)
+    if match and 0 < int(match.group(1)) <= 128:
+        return ipaddress.ip_network(virtual_addr)
+
+    match = RE_VIRTUAL_ADDR_CLIENT.search(virtual_addr)
+    if match:
+        return ipaddress.ip_address(RE_VIRTUAL_ADDR_CLIENT.sub("", virtual_addr))
+
+    return ipaddress.ip_address(virtual_addr)
+
+
+def parse_filesize(size):
+    if isinstance(size, FileSize):
+        return size
+    return FileSize(size)
+
+
+class PeerAddress(collections.namedtuple("PeerAddress", "host port")):
+    """The address of peer entity.
+
+    :param host: The host address of peer entity.
+    :type host: :class:`~ipaddress.IPv4Address` or
+                :class:`~ipaddress.IPv6Address`
+    :param port: The port of peer entity.
+    :type port: :class:`int`
+    """
+
+    def __str__(self):
+        return "{0}:{1}".format(self.host, self.port)
+
+
+class FileSize(int):
+    """The size of bytes."""
+
+    def __str__(self):
+        return self.humanize()
+
+    def humanize(self, **kwargs):
+        """Gets the human-friendly representation of file size.
+
+        :param kwargs: All keyword arguments will be passed to
+                       :func:`humanize.filesize.naturalsize`.
+        """
+        return naturalsize(self, **kwargs)

openvpn_status/version.py

@@ -0,0 +1,16 @@
+VERSION = (0, 3, 0, "final")
+
+
+def get_version():
+    version = "%s.%s.%s" % VERSION[:3]
+    if VERSION[3:] == ("alpha", 0):
+        return "%s pre-alpha" % version
+    if VERSION[3].startswith("post"):
+        return "%s.%s" % (version, VERSION[3])
+    if VERSION[3] != "final":
+        revision = VERSION[4] if len(VERSION) > 4 else 0
+        return "%s%s%s" % (version, VERSION[3][0], revision)
+    return version
+
+
+__version__ = get_version()

openvpn_status_reader-0.3.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: openvpn-status-reader
+Version: 0.3.0
+Summary: Parse OpenVPN status logs in Python
+Home-page: https://github.com/openwisp/openvpn-status-reader
+Author: OpenWISP
+Author-email: support@openwisp.org
+License: MIT
+Keywords: openvpn,status,log
+Platform: Any
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: Log Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: humanize<5,>=4.16
+Requires-Dist: netaddr<2,>=1.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+OpenVPN Status Reader
+=====================
+
+.. image:: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml/badge.svg?branch=master
+    :target: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml
+    :alt: CI build status
+
+.. image:: https://coveralls.io/repos/openwisp/openvpn-status-reader/badge.svg
+    :target: https://coveralls.io/r/openwisp/openvpn-status-reader
+
+.. image:: https://img.shields.io/librariesio/release/github/openwisp/openvpn-status-reader
+    :target: https://libraries.io/github/openwisp/openvpn-status-reader#repository_dependencies
+    :alt: Dependency monitoring
+
+.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square
+    :target: https://gitter.im/openwisp/general
+
+.. image:: https://badge.fury.io/py/openvpn-status-reader.svg
+    :target: https://badge.fury.io/py/openvpn-status-reader
+
+.. image:: https://pepy.tech/badge/openvpn-status-reader
+    :target: https://pepy.tech/project/openvpn-status-reader
+    :alt: downloads
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://pypi.org/project/black/
+    :alt: code style: black
+
+.. summary-begin
+
+**openvpn-status-reader** is an OpenWISP-maintained Python library for
+parsing OpenVPN status-version-1 logs into Python data structures. It
+supports both legacy and current numeric OpenVPN timestamps.
+
+.. summary-end
+
+This project is a fork of the original openvpn-status_ repository. It
+retains the ``openvpn_status`` import namespace for compatibility.
+
+It supports Python 3.11 and newer.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install openvpn-status-reader
+
+Don't forget to put it in ``setup.py`` / ``requirements.txt``.
+
+Getting Started
+---------------
+
+You could configure your OpenVPN server to log for client status. In usual
+it could be achieved by adding ``status /path/to/openvpn-status.log`` line
+to ``/etc/openvpn/openvpn.conf``. For example:
+
+::
+
+    proto udp
+    port 1194
+    dev tun0
+    status /var/run/openvpn-status.log
+
+Once OpenVPN server running, the log file will be created and written. It
+looks like:
+
+::
+
+    OpenVPN CLIENT LIST
+    Updated,Thu Jun 18 08:12:15 2015
+    Common Name,Real Address,Bytes Received,Bytes Sent,Connected Since
+    foo@example.com,10.10.10.10:49502,334948,1973012,Thu Jun 18 04:23:03 2015
+    bar@example.com,10.10.10.10:64169,1817262,28981224,Thu Jun 18 04:08:39 2015
+    ROUTING TABLE
+    Virtual Address,Common Name,Real Address,Last Ref
+    192.168.255.134,foo@example.com,10.10.10.10:49502,Thu Jun 18 08:12:09 2015
+    192.168.255.126,bar@example.com,10.10.10.10:64169,Thu Jun 18 08:11:55 2015
+    GLOBAL STATS
+    Max bcast/mcast queue length,0
+    END
+
+Now we could parse log file with this library:
+
+.. code-block:: python
+
+    from openvpn_status import parse_status
+
+    with open("/var/run/openvpn-status.log") as logfile:
+        status = parse_status(logfile.read())
+
+    print(status.updated_at)  # datetime.datetime(2015, 6, 18, 8, 12, 15)
+
+    foo_client = status.client_list["169.254.0.1"]
+    print(foo_client.common_name)  # foo@example.com
+    print(foo_client.bytes_received)  # 334.9 kB
+    print(foo_client.bytes_sent)  # 2.0 MB
+    print(int(foo_client.bytes_sent))  # 2097152
+
+More details are in the `API reference`_.
+
+.. _api reference: https://openvpn-status-reader.readthedocs.io/en/latest/api.html
+
+.. _openvpn-status: https://github.com/sgares/openvpn-status

openvpn_status_reader-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+openvpn_status/__init__.py,sha256=65Mw3mwHExVRbIDQnCRuEUn9VFvV5G-WWz_6cUaaVHE,161
+openvpn_status/descriptors.py,sha256=mdIdjJwcsQwqYV2Mp5dFQcHg23Gd8kCR4WKBR9bjUkQ,1501
+openvpn_status/models.py,sha256=Nq4zQrkmjUuctAgWQwR04tW7OTZeJvF4NCk6neHzcbU,1427
+openvpn_status/parser.py,sha256=SZjysxPLkjV6xHQ8ZNLf4lh2PZrnP_bdeApYssUmMQw,4745
+openvpn_status/shortcuts.py,sha256=RPzeOIOYqoVqcYbL_6-ri4RNdpDWLyuqdtj2O9xVfRg,519
+openvpn_status/utils.py,sha256=51L8qhL2-NIShLyF_gJHmU8pYtUTKgXH_mvAFx0vM4I,2461
+openvpn_status/version.py,sha256=9ooItZ1qzN0D6zvu82nrxKtjTC_TS1xAJ9OAYjlpbk4,447
+openvpn_status_reader-0.3.0.dist-info/licenses/AUTHORS.rst,sha256=_yZAhGNJkmhOmpjvSEz7nCEz8q4j1AE93Ng8avDyEjU,37
+openvpn_status_reader-0.3.0.dist-info/licenses/LICENSE,sha256=Ik-e1SSP7v1kYtaYghyMy3PoAkLQNFkSMCEmIlKtkjk,1074
+openvpn_status_reader-0.3.0.dist-info/METADATA,sha256=9zFhdGe8Ev-yaAwtRDrnlAKNLMhfkIFD0OpeI5WBZfM,4966
+openvpn_status_reader-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+openvpn_status_reader-0.3.0.dist-info/top_level.txt,sha256=KEaBstJM0_80gRTuMmOulOCKaLi3LAsU59T5XTbmO5o,15
+openvpn_status_reader-0.3.0.dist-info/RECORD,,

openvpn_status_reader-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openvpn_status_reader-0.3.0.dist-info/licenses/AUTHORS.rst

@@ -0,0 +1 @@
+- Jiangge Zhang <tonyseek@gmail.com>

openvpn_status_reader-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) Jiangge Zhang
+
+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.

openvpn_status_reader-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openvpn_status