Package: openvpn-api
OpenVPN Management Interface Python APISummaryA Python API for interacting with the OpenVPN management interface.
Currently a work in progress so support for client management interfaces and events is lacking.Very useful for extracting metrics and status from OpenVPN server management interfaces.This project was inspired by the work of Marcus Furlong in creatingopenvpn-monitor.
It also usesopenvpn-statusby Jiangge Zhang for parsing the output of the OpenVPNstatuscommand as there's no point reinventing the wheel when an excellent solution already exists.Release notes can be foundhere on GitHub.RequirementsThis project requires Python >= 3.6.Other packages:netaddropenvpn-statusInstallationVia PyPIpip install openvpn-apiVia Sourcegit clone https://github.com/Jamie-/openvpn-api.git
cd openvpn-api
python setup.py installUsageIntroductionCreate aVPNobject for your management interface connection.importopenvpn_api.VPNv=openvpn_api.VPN('localhost',7505)Then you can either manage connection and disconnection yourselfv.connect()# Do some stuff, e.g.print(v.release)v.disconnect()If the connection is successful,v.connect()will returnTrue.
However, if the connection failsv.connect()will raise anopenvpn_api.errors.ConnectErrorexception with the reason for the connection failure.Or use the connection context managerwithv.connection():# Do some stuff, e.g.print(v.release)After initialising a VPN object, we can query specifics about it.We can get the address we're communicating to the management interface on>>>v.mgmt_address'localhost:7505'And also see if this is via TCP/IP or a Unix socket>>>v.type'ip'or>>>v.type'socket'These are represented by theVPNTypeclass asVPNType.IPorVPNType.UNIX_SOCKET>>>v.type'ip'>>>v.type==openvpn_api.VPNType.IPTrueDaemon InteractionAll the properties that get information about the OpenVPN service you're connected to are stateful.
The first time you call one of these methods it caches the information it needs so future calls are super fast.
The information cached is unlikely to change often, unlike the status and metrics we can also fetch which are likely to change very frequently.We can fetch the release string for the version of OpenVPN we're using>>>v.release'OpenVPN 2.4.4 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [LZ4] [EPOLL] [PKCS11] [MH/PKTINFO] [AEAD] built on Sep  5 2018'Or just the version number>>>v.version'2.4.4'We can get more information about the service by looking at it's state which is returned as a State object>>>s=v.state>>>s<models.state.Stateobjectat0x7f5eb549a630>The state cached by all 3 of these properties can be also be cleared and will be repopulated on the next callv.clear_cache()Daemon StateThe State object contains the following things:The daemon's current mode,clientorserver>>>s.mode'server'Date and time the daemon was started>>>s.up_sincedatetime.datetime(2019,6,5,23,3,21)The daemon's current state>>>s.state_name'CONNECTED'Which can be any of:CONNECTING- OpenVPN's initial state.WAIT- (Client only) Waiting for initial response from server.AUTH- (Client only) Authenticating with server.GET_CONFIG- (Client only) Downloading configuration options from server.ASSIGN_IP- Assigning IP address to virtual network interface.ADD_ROUTES- Adding routes to system.CONNECTED- Initialization Sequence Completed.RECONNECTING- A restart has occurred.EXITING- A graceful exit is in progress.RESOLVE- (Client only) DNS lookupTCP_CONNECT- (Client only) Connecting to TCP serverThe descriptive string - unclear from the OpenVPN documentation quite what this is, usuallySUCCESSor the reason for disconnection if the state isRECONNECTINGorEXITING>>>s.desc_string'SUCCESS'The daemon's local virtual (VPN internal) address, returned as anetaddr.IPAddressfor ease of sorting, it can be easily converted to a string withstr()>>>s.local_virtual_v4_addrIPAddress('10.0.0.1')>>>str(s.local_virtual_v4_addr)'10.0.0.1'If the daemon is in client mode, thenremote_addrandremote_portwill be populated with the address and port of the remote server>>>s.remote_addr'1.2.3.4'>>>s.remote_port1194If the daemon is in server mode, thenlocal_addrandlocal_portwill be populated with the address and port of the exposed server>>>s.local_addr'5.6.7.8'>>>s.local_port1194If 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>>>s.local_virtual_v6_addr'2001:db8:85a3::8a2e:370:7334'Daemon StatusThe daemon status is parsed from the management interface byopenvpn_statusan existing Python library for parsing the output from OpenVPN's status response.
The code for which can be found in it's GitHub repo:https://github.com/tonyseek/openvpn-statusTherefore when we fetch the status from the OpenVPN daemon, it'll be returned using their models.
For more information see their docs:https://openvpn-status.readthedocs.io/en/latest/api.htmlUnlike the VPN state, the status is not stateful as it's output is highly likely to change between calls.
Every time the status is requested, the management interface is queried for the latest data.A brief example:>>>status=v.get_status()>>>status<openvpn_status.models.Statusobjectat0x7f5eb54a2d68>>>>status.client_listOrderedDict([('1.2.3.4:56789',<openvpn_status.models.Clientobjectat0x7f5eb54a2128>)])