Metadata-Version: 1.1
Name: proxmoxer
Version: 1.2.0b1
Summary: Python Wrapper for the Proxmox 2.x API (HTTP and SSH)
Home-page: https://github.com/proxmoxer/proxmoxer
Author: Oleg Butovich
Author-email: obutovich@gmail.com
License: MIT
Download-URL: http://pypi.python.org/pypi/proxmoxer
Description: =========================================
        Proxmoxer: A wrapper for Proxmox REST API
        =========================================
        
        master branch:  |master_build_status| |master_coverage_status| |pypi_version| |pypi_downloads|
        
        develop branch: |develop_build_status| |develop_coverage_status|
        
        
        What does it do and what's different?
        -------------------------------------
        
        Proxmoxer is a wrapper around the `Proxmox REST API v2 <https://pve.proxmox.com/pve-docs/api-viewer/index.html>`_.
        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 <https://github.com/baseblack/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 <https://pve.proxmox.com/wiki/User_Management#pveum_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 <https://pve.proxmox.com/pve-docs/api-viewer/index.html#/access/users/{userid}/token/{tokenid}>`_.
        
        ::
        
            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 <https://pve.proxmox.com/pve-docs/api-viewer/index.html>`_, 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'))))
        
        
        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 <https://github.com/jhollowe>`_)
        
        1.1.0 (2020-05-22)
        ..................
        * Addition (https): Added API Token authentication (`John Hollowell <https://github.com/jhollowe>`_)
        * Improvement (https): user/password authentication refreshes ticket to prevent expiration (`CompileNix <https://github.com/compilenix>`_ and `John Hollowell <https://github.com/jhollowe>`_)
        * Bugfix (ssh_paramiko): Handle empty stderr from ssh connections (`morph027 <https://github.com/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 <https://github.com/ssi444>`_)
        * Bugfix (ssh): Fix pvesh output format for version > 5.3 (`timansky <https://github.com/timansky>`_)
        * Transfered development to proxmoxer organization
        
        1.0.3 (2018-09-10)
        ..................
        * Improvement: Added option to specify port in hostname parameter (`pvanagtmaal <https://github.com/pvanagtmaal>`_)
        * Improvement: Added stderr to the Response content (`Jérôme Schneider <https://github.com/merinos>`_)
        * Bugfix: Paramiko python3: stdout and stderr must be a str not bytes (`Jérôme Schneider <https://github.com/merinos>`_)
        * New lxc example in docu (`Geert Stappers <https://github.com/stappersg>`_)
        
        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 <https://github.com/wdoekes>`_)
        
        1.0.0 (2017-11-12)
        ..................
        * Update Proxmoxer readme (`Emmanuel Kasper <https://github.com/EmmanuelKasper>`_)
        * Display the reason of API calls errors (`Emmanuel Kasper <https://github.com/EmmanuelKasper>`_, `kantsdog <https://github.com/kantsdog>`_)
        * Filter for ssh response code (`Chris Plock <https://github.com/chrisplo>`_)
        
        0.2.5 (2017-02-12)
        ..................
        * Adding sudo to execute CLI with paramiko ssh backend (`Jason Meridth <https://github.com/jmeridth>`_)
        * Proxmoxer/backends/ssh_paramiko: improve file upload (`Jérôme Schneider <https://github.com/merinos>`_)
        
        0.2.4 (2016-05-02)
        ..................
        * Removed newline in tmp_filename string (`Jérôme Schneider <https://github.com/merinos>`_)
        * Fix to avoid module reloading (`jklang <https://github.com/jklang>`_)
        
        0.2.3 (2016-01-20)
        ..................
        * Minor typo fix (`Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
        
        0.2.2 (2016-01-19)
        ..................
        * Adding sudo to execute pvesh CLI in openssh backend (`Wei Tie <https://github.com/TieWei>`_, `Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
        * Add support to specify an identity file for ssh connections (`Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
        
        0.2.1 (2015-05-02)
        ..................
        * fix for python 3.4 (`kokuev <https://github.com/kokuev>`_)
        
        0.2.0 (2015-03-21)
        ..................
        * Https will now raise AuthenticationError when appropriate. (`scap1784 <https://github.com/scap1784>`_)
        * Preliminary python 3 compatibility. (`wdoekes <https://github.com/wdoekes>`_)
        * Additional example. (`wdoekes <https://github.com/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.
        
        .. |master_build_status| image:: https://travis-ci.org/proxmoxer/proxmoxer.png?branch=master
            :target: https://travis-ci.org/proxmoxer/proxmoxer
        
        .. |master_coverage_status| image:: https://coveralls.io/repos/proxmoxer/proxmoxer/badge.png?branch=master
            :target: https://coveralls.io/r/proxmoxer/proxmoxer
        
        .. |develop_build_status| image:: https://travis-ci.org/proxmoxer/proxmoxer.png?branch=develop
            :target: https://travis-ci.org/proxmoxer/proxmoxer
        
        .. |develop_coverage_status| image:: https://coveralls.io/repos/proxmoxer/proxmoxer/badge.png?branch=develop
            :target: https://coveralls.io/r/proxmoxer/proxmoxer
        
        .. |pypi_version| image:: https://img.shields.io/pypi/v/proxmoxer.svg
            :target: https://pypi.python.org/pypi/proxmoxer
        
        .. |pypi_downloads| image:: https://img.shields.io/pypi/dm/proxmoxer.svg
            :target: https://pypi.python.org/pypi/proxmoxer
        
Keywords: proxmox,api
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
