Proxmoxer: A wrapper for Proxmox REST API

master branch:

develop branch:

What does it do and what's different?

Proxmoxer is a wrapper around the Proxmox REST API v2. Works with Proxmox Virtual Environment (PVE) and Proxmox Mail Gateway (PMG) API.

It was inspired by slumber, but it is dedicated only to Proxmox. It allows not only REST API use over HTTPS, but the same api over ssh and pvesh utility.

Like Proxmoxia, it dynamically creates attributes which responds to the attributes you've attempted to reach.

Installation

pip install proxmoxer

To use the 'https' backend, install requests

pip install requests

To use the 'ssh_paramiko' backend, install paramiko

pip install paramiko

Short usage information

The first thing to do is import the proxmoxer library and create ProxmoxAPI instance.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
                     password='secret_word', verify_ssl=False)

This will connect by default to PVE through the 'https' backend.

To define service to PVE or PMG, include service option into script:

Define PVE connection:

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
                     password='secret_word', verify_ssl=False, service='PVE')

Define PMG connection:

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
                     password='secret_word', verify_ssl=False, service='PMG')

You can also setup API Tokens which allow tighter access controls. API Tokens are also stateless, so they much better for long-lived programs that might have the standard username/password authentication timeout. API tokens can be created through the web UI or through the API.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin', token_name='test_token', token_value='ab27beeb-9ac4-4df1-aa19-62639f27031e')

For SSH access, it is possible to use pre-prepared public/private key authentication and ssh-agent.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='proxmox_admin', backend='ssh_paramiko')

Note: the 'https' backend needs the 'requests' library, the 'ssh_paramiko' backend needs the 'paramiko' library, and the 'openssh' backend needs the 'openssh_wrapper' library installed.

Queries are exposed via the access methods get, post, put and delete. For convenience two synonyms are available: create for post, and set for put.

Using the paths from the Proxmox REST API v2, you can create API calls using the access methods above.

for node in proxmox.nodes.get():
    for vm in proxmox.nodes(node['node']).openvz.get():
        print "{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status'])

>>> 141. puppet-2.london.example.com => running
    101. munki.london.example.com => running
    102. redmine.london.example.com => running
    140. dns-1.london.example.com => running
    126. ns-3.london.example.com => running
    113. rabbitmq.london.example.com => running

same code can be rewritten in the next way:

for node in proxmox.get('nodes'):
    for vm in proxmox.get('nodes/%s/openvz' % node['node']):
        print "%s. %s => %s" %  (vm['vmid'], vm['name'], vm['status'])

As a demonstration of the flexibility of usage of this library, the following lines accomplish the equivalent function:

proxmox.nodes(node['node']).openvz.get()
proxmox.nodes(node['node']).get('openvz')
proxmox.get('nodes/%s/openvz' % node['node'])
proxmox.get('nodes', node['node'], 'openvz')

Some more examples:

Listing VMs: .. code-block:: python

for vm in proxmox.cluster.resources.get(type='vm'):

print("{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status']))

Listing contents of the local storage on the proxmox_node node (method 1): .. code-block:: python

node = proxmox.nodes('proxmox_node') pprint(node.storage('local').content.get())

Listing contents of the local storage on the proxmox_node node (method 2): .. code-block:: python

node = proxmox.nodes.proxmox_node() pprint(node.storage.local.content.get())

creating a new lxc container:

node = proxmox.nodes('proxmox_node')
node.lxc.create(vmid=202,
    ostemplate='local:vztmpl/debian-9.0-standard_20170530_amd64.tar.gz',
    hostname='debian-stretch',
    storage='local',
    memory=512,
    swap=512,
    cores=1,
    password='secret',
    net0='name=eth0,bridge=vmbr0,ip=192.168.22.1/20,gw=192.168.16.1')

The same lxc container can be created with options set in a dictionary. This approach allows adding ssh-public-keys without getting syntax errors.

newcontainer = { 'vmid': 202,
    'ostemplate': 'local:vztmpl/debian-9.0-standard_20170530_amd64.tar.gz',
    'hostname': 'debian-stretch',
    'storage': 'local',
    'memory': 512,
    'swap': 512,
    'cores': 1,
    'password': 'secret',
    'net0': 'name=eth0,bridge=vmbr0,ip=192.168.22.1/20,gw=192.168.16.1' }
node = proxmox.nodes('proxmox_node')
node.lxc.create(**newcontainer)

Uploading a template:

local_storage = proxmox.nodes('proxmox_node').storage('local')
local_storage.upload.create(content='vztmpl',
    filename=open(os.path.expanduser('~/templates/debian-6-my-core_1.0-1_i386.tar.gz'))))

Downloading rrd CPU image data to a file:

response = proxmox.nodes('proxmox').rrd.get(ds='cpu', timeframe='hour')
with open('cpu.png', 'wb') as f:
    f.write(response['image'].encode('raw_unicode_escape'))

Example of usage of logging:

# now logging debug info will be written to stdout
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s:%(name)s: %(message)s')

Example of PMG usage:

from proxmoxer import ProxmoxAPI
import json

proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
                     password='secret_word', verify_ssl=False, service='PMG')

a = proxmox.statistics.sender.get()
c = json_formatted_str = json.dumps(a, indent=2)
print(c)

Changelog

1.1.1 (2020-06-23)

Bugfix (https): correctly renew ticket in the session, not just the auth (John Hollowell)

1.1.0 (2020-05-22)

Addition (https): Added API Token authentication (John Hollowell)
Improvement (https): user/password authentication refreshes ticket to prevent expiration (CompileNix and John Hollowell)
Bugfix (ssh_paramiko): Handle empty stderr from ssh connections (morph027)
DEPRECATED (https): using auth_token and csrf_token (ProxmoxHTTPTicketAuth) is now deprecated. Either pass the auth_token as the password or use the API Tokens.

1.0.4 (2020-01-24)

Improvement (https): Added timeout to authentication (James Lin)
Improvement (https): Handle AnyEvent::HTTP status codes gracefully (Georges Martin)
Improvement (https): Advanced error message with error code >=400 (ssi444)
Bugfix (ssh): Fix pvesh output format for version > 5.3 (timansky)
Transfered development to proxmoxer organization

1.0.3 (2018-09-10)

Improvement: Added option to specify port in hostname parameter (pvanagtmaal)
Improvement: Added stderr to the Response content (Jérôme Schneider)
Bugfix: Paramiko python3: stdout and stderr must be a str not bytes (Jérôme Schneider)
New lxc example in docu (Geert Stappers)

1.0.2 (2017-12-02)

Tarball repackaged with tests

1.0.1 (2017-12-02)

LICENSE file now included in tarball
Added verify_ssl parameter to ProxmoxHTTPAuth (Walter Doekes)

1.0.0 (2017-11-12)

Update Proxmoxer readme (Emmanuel Kasper)
Display the reason of API calls errors (Emmanuel Kasper, kantsdog)
Filter for ssh response code (Chris Plock)

0.2.5 (2017-02-12)

Adding sudo to execute CLI with paramiko ssh backend (Jason Meridth)
Proxmoxer/backends/ssh_paramiko: improve file upload (Jérôme Schneider)

0.2.4 (2016-05-02)

Removed newline in tmp_filename string (Jérôme Schneider)
Fix to avoid module reloading (jklang)

0.2.3 (2016-01-20)

Minor typo fix (Srinivas Sakhamuri)

0.2.2 (2016-01-19)

Adding sudo to execute pvesh CLI in openssh backend (Wei Tie, Srinivas Sakhamuri)
Add support to specify an identity file for ssh connections (Srinivas Sakhamuri)

0.2.1 (2015-05-02)

fix for python 3.4 (kokuev)

0.2.0 (2015-03-21)

Https will now raise AuthenticationError when appropriate. (scap1784)
Preliminary python 3 compatibility. (wdoekes)
Additional example. (wdoekes)

0.1.7 (2014-11-16)

Added ignore of "InsecureRequestWarning: Unverified HTTPS request is being made..." warning while using https (requests) backend.

0.1.4 (2013-06-01)

Added logging
Added openssh backend
Tests are reorganized

0.1.3 (2013-05-30)

Added next tests
Bugfixes

0.1.2 (2013-05-27)

Added first tests
Added support for travis and coveralls
Bugfixes

0.1.1 (2013-05-13)

Initial try.

terrydash/proxmoxer