Python Wrapper for the Proxmox 2.x API (HTTP and SSH)
Project description
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
To use the ‘openssh’ backend, install openssh_wrapper
pip install openssh_wrapper
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 select a different service, use the service argument (currently supports ‘PVE’, ‘PMG’, and):
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: ensure you have the required libraries (listed above) for the connection method you are using
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:
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):
node = proxmox.nodes('proxmox_node') pprint(node.storage('local').content.get())
Listing contents of the local storage on the proxmox_node node (method 2):
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'),'rb')))
NOTE: for large file uploads, please ensure the requests_toolbelt pip module is installed. This provides support for larger files and reduces the memory requirement of uploads.
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.2.0 (2021-10-07)
Addition (https): Added OTP code support to authentication (John Hollowell)
Addition (https): Added support for large file uploads using requests_toolbelt module (John Hollowell)
Addition (all): Added support for Proxmox Mail Gateway (PMG) and Proxmox Backup Server (PBS) with parameter validation (Gabriel Cardoso de Faria and John Hollowell)
Addition (all): Added detailed information to ResourceException (mihailstoynov)
Bugfix (base_ssh): Resolved issue with values containing spaces by encapsulating values in quotes (mihailstoynov)
Bugfix (all): Resolved issue with using get/post/push/delete on a base ProxmoxAPI object (John Hollowell)
Bugfix (all): Added support for responses which are not JSON (John Hollowell)
Improvement: Added and updated documentation (Ananias Filho and Thomas Baag)
Improvement: Tests are now not installed when using PIP (Ville Skyttä)
Addition: Devcontainer definition now available to make development easier (John Hollowell)
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)
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.