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
