{
    "info": {
        "author": "Jamie Scott",
        "author_email": "contact@jami.org.uk",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Developers",
            "Intended Audience :: System Administrators",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3.8"
        ],
        "description": "# OpenVPN Management Interface Python API\n\n[![Build Status](https://travis-ci.org/Jamie-/openvpn-api.svg?branch=master)](https://travis-ci.org/Jamie-/openvpn-api)\n![PyPI](https://img.shields.io/pypi/v/openvpn-api.svg)\n\n## Summary\n\nA Python API for interacting with the OpenVPN management interface.\nCurrently a work in progress so support for client management interfaces and events is lacking.\n\nVery useful for extracting metrics and status from OpenVPN server management interfaces.\n\nThis project was inspired by the work of Marcus Furlong in creating `openvpn-monitor`.\nIt also uses `openvpn-status` by Jiangge Zhang for parsing the output of the `status` command as there's no point reinventing the wheel when an excellent solution already exists.\n\n\n## Requirements\nThis project requires Python 3.6 or later.\n\n## Installation\n\n#### Via PyPI\n```\npip install openvpn-api\n```\n\n#### Via Source\n```\ngit clone https://github.com/Jamie-/openvpn-api.git\ncd openvpn-api\npython setup.py install\n```\n\n## Usage\n\n### Introduction\nCreate a `VPN` object for your management interface connection.\n```python\nimport openvpn_api.VPN\nv = openvpn_api.VPN('localhost', 7505)\n```\n\nThen you can either manage connection and disconnection yourself\n```python\nv.connect()\n# Do some stuff, e.g.\nprint(v.release)\nv.disconnect()\n```\nIf the connection is successful, `v.connect()` will return `True`.\nHowever, if the connection fails `v.connect()` will raise an `openvpn_api.errors.ConnectError` exception with the reason for the connection failure.\n\nOr use the connection context manager\n```python\nwith v.connection():\n    # Do some stuff, e.g.\n    print(v.release)\n```\n\nAfter initialising a VPN object, we can query specifics about it.\n\nWe can get the address we're communicating to the management interface on\n```python\n>>> v.mgmt_address\n'localhost:7505'\n```\n\nAnd also see if this is via TCP/IP or a Unix socket\n```python\n>>> v.type\n'ip'\n```\n\nor\n```python\n>>> v.type\n'socket'\n```\n\nThese are represented by the `VPNType` class as `VPNType.IP` or `VPNType.UNIX_SOCKET`\n```python\n>>> v.type\n'ip'\n>>> v.type == openvpn_api.VPNType.IP\nTrue\n```\n\n### Daemon Interaction\nAll the properties that get information about the OpenVPN service you're connected to are stateful.\nThe first time you call one of these methods it caches the information it needs so future calls are super fast.\nThe information cached is unlikely to change often, unlike the status and metrics we can also fetch which are likely to change very frequently.\n\nWe can fetch the release string for the version of OpenVPN we're using\n```python\n>>> v.release\n'OpenVPN 2.4.4 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [LZ4] [EPOLL] [PKCS11] [MH/PKTINFO] [AEAD] built on Sep  5 2018'\n```\n\nOr just the version number\n```python\n>>> v.version\n'2.4.4'\n```\n\nWe can get more information about the service by looking at it's state which is returned as a State object\n```python\n>>> s = v.state\n>>> s\n<models.state.State object at 0x7f5eb549a630>\n```\n\nThe state cached by all 3 of these properties can be also be cleared and will be repopulated on the next call\n```python\nv.clear_cache()\n```\n\n#### Daemon State\nThe State object contains the following things:\n\nThe daemon's current mode, `client` or `server`\n```python\n>>> s.mode\n'server'\n```\n\nDate and time the daemon was started\n```python\n>>> s.up_since\ndatetime.datetime(2019, 6, 5, 23, 3, 21)\n```\n\nThe daemon's current state\n```python\n>>> s.state_name\n'CONNECTED'\n```\nWhich can be any of:\n* `CONNECTING` - OpenVPN's initial state.\n* `WAIT` - (Client only) Waiting for initial response from server.\n* `AUTH` - (Client only) Authenticating with server.\n* `GET_CONFIG` - (Client only) Downloading configuration options from server.\n* `ASSIGN_IP` - Assigning IP address to virtual network interface.\n* `ADD_ROUTES` - Adding routes to system.\n* `CONNECTED` - Initialization Sequence Completed.\n* `RECONNECTING` - A restart has occurred.\n* `EXITING` - A graceful exit is in progress.\n* `RESOLVE` - (Client only) DNS lookup\n* `TCP_CONNECT` - (Client only) Connecting to TCP server\n\nThe descriptive string - unclear from the OpenVPN documentation quite what this is, usually `SUCCESS` or the reason for disconnection if the state is `RECONNECTING` or `EXITING`\n```python\n>>> s.desc_string\n'SUCCESS'\n```\n\nThe daemon's local virtual (VPN internal) address, returned as a `netaddr.IPAddress` for ease of sorting, it can be easily converted to a string with `str()`\n```python\n>>> s.local_virtual_v4_addr\nIPAddress('10.0.0.1')\n>>> str(s.local_virtual_v4_addr)\n'10.0.0.1'\n```\n\nIf the daemon is in client mode, then `remote_addr` and `remote_port` will be populated with the address and port of the remote server\n```python\n>>> s.remote_addr\n'1.2.3.4'\n>>> s.remote_port\n1194\n```\n\nIf the daemon is in server mode, then `local_addr` and `local_port` will be populated with the address and port of the exposed server\n```python\n>>> s.local_addr\n'5.6.7.8'\n>>> s.local_port\n1194\n```\n\nIf the daemon is using IPv6 instead of, or in addition to, IPv4 then the there is also a field for the local virtual (VPN internal) v6 address\n```python\n>>> s.local_virtual_v6_addr\n'2001:db8:85a3::8a2e:370:7334'\n```\n\n#### Daemon Status\nThe daemon status is parsed from the management interface by `openvpn_status` an existing Python library for parsing the output from OpenVPN's status response.\nThe code for which can be found in it's GitHub repo: https://github.com/tonyseek/openvpn-status\n\nTherefore when we fetch the status from the OpenVPN daemon, it'll be returned using their models.\nFor more information see their docs: https://openvpn-status.readthedocs.io/en/latest/api.html\n\nUnlike the VPN state, the status is not stateful as it's output is highly likely to change between calls.\nEvery time the status is requested, the management interface is queried for the latest data.\n\nA brief example:\n```python\n>>> status = v.get_status()\n>>> status\n<openvpn_status.models.Status object at 0x7f5eb54a2d68>\n>>> status.client_list\nOrderedDict([('1.2.3.4:56789', <openvpn_status.models.Client object at 0x7f5eb54a2128>)])\n```",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Jamie-/openvpn-api",
        "keywords": "openvpn monitor management",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "openvpn-api",
        "package_url": "https://pypi.org/project/openvpn-api/",
        "platform": "",
        "project_url": "https://pypi.org/project/openvpn-api/",
        "project_urls": {
            "Bug Reports": "https://github.com/Jamie-/openvpn-api/issues",
            "Homepage": "https://github.com/Jamie-/openvpn-api",
            "Source": "https://github.com/Jamie-/openvpn-api"
        },
        "release_url": "https://pypi.org/project/openvpn-api/0.1.2/",
        "requires_dist": null,
        "requires_python": ">=3.6",
        "summary": "A Python API for the OpenVPN management interface.",
        "version": "0.1.2"
    },
    "last_serial": 5553426,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ecb417b766e7a5f4a517677533cce255",
                    "sha256": "160907b50e5505701349724448b4dcf9c5d6eeefaaeed7094fb53a8a0be517d9"
                },
                "downloads": -1,
                "filename": "openvpn-api-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "ecb417b766e7a5f4a517677533cce255",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 8416,
                "upload_time": "2019-07-17T20:41:13",
                "url": "https://files.pythonhosted.org/packages/8f/b2/5bcb049ed237bf182edd5448802fa352cc0f4ea1ed5be9a280c6564089bb/openvpn-api-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "91cf16fe6363495d66f4f2203023fd74",
                    "sha256": "53392202781d35eef14d2e482a3d3bba5f450b6f12fd40e6316176dcd53322dd"
                },
                "downloads": -1,
                "filename": "openvpn-api-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "91cf16fe6363495d66f4f2203023fd74",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 8660,
                "upload_time": "2019-07-17T22:10:12",
                "url": "https://files.pythonhosted.org/packages/1b/02/1577979e3586d0fa2b65758bfaffb89e4b0e97e026fe4d097c24493356eb/openvpn-api-0.1.1.tar.gz"
            }
        ],
        "0.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3bbb04e6ca2ae98f25d431a86408f083",
                    "sha256": "1c87d3e24abdfdf9901472e7158b9ab19f29bf2240599acbbedd0c5e9cf570df"
                },
                "downloads": -1,
                "filename": "openvpn-api-0.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "3bbb04e6ca2ae98f25d431a86408f083",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 8764,
                "upload_time": "2019-07-18T21:35:15",
                "url": "https://files.pythonhosted.org/packages/5e/3b/156bfe27945e66a17b7792eaf1fcbd30c3c072da627a4bb02b669f4e5c7a/openvpn-api-0.1.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3bbb04e6ca2ae98f25d431a86408f083",
                "sha256": "1c87d3e24abdfdf9901472e7158b9ab19f29bf2240599acbbedd0c5e9cf570df"
            },
            "downloads": -1,
            "filename": "openvpn-api-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "3bbb04e6ca2ae98f25d431a86408f083",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 8764,
            "upload_time": "2019-07-18T21:35:15",
            "url": "https://files.pythonhosted.org/packages/5e/3b/156bfe27945e66a17b7792eaf1fcbd30c3c072da627a4bb02b669f4e5c7a/openvpn-api-0.1.2.tar.gz"
        }
    ]
}