Difference between revisions of "Proxmox VE API"

From Proxmox VE
Jump to: navigation, search
(References)
(Telegram Bot for Proxmox)
 
(47 intermediate revisions by 19 users not shown)
Line 1: Line 1:
{{Note|Article about Proxmox VE 2.0 beta}}
+
== Introduction ==
 
 
=Introduction=
 
  
 
Proxmox VE uses a REST like API. The concept is described in [1] (Resource Oriented Architectur - ROA).  
 
Proxmox VE uses a REST like API. The concept is described in [1] (Resource Oriented Architectur - ROA).  
  
We choose JSON as primary data format, and the whole API is formally defined using JSON Schema: http://pve.proxmox.com/pve2-api-doc/
+
We choose JSON as primary data format, and the whole API is formally defined using JSON Schema [2].
  
We will use the 'curl' command line tool for all examples.
+
You can explore the API documentation at http://pve.proxmox.com/pve-docs/api-viewer/index.html
  
==JSON and JSON Schema==
+
== JSON and JSON Schema ==
  
We use JSON as data format, because it is simple and parse-able by any
+
The API use JSON as data format, because it is simple and parse-able by any
 
web browser.
 
web browser.
  
Line 20: Line 18:
 
An great side effect was that we are able to use JSON Schema to
 
An great side effect was that we are able to use JSON Schema to
 
produce command line argument parsers automatically. In fact, the REST
 
produce command line argument parsers automatically. In fact, the REST
API and the command line tools use the same code.
+
API and the command line tools use the same code. A small utility called 'pvesh'  
 
+
exposes the whole REST API on the command line.
Object linkage is done using the JSON Hyper Schema (links property).
 
 
 
A small utility called 'pvesh' exposes the whole REST API on the command
 
line.
 
  
 
So here is a summary of the advantage:
 
So here is a summary of the advantage:
Line 32: Line 26:
 
* automatic parameter verification (we can also verify return values)
 
* automatic parameter verification (we can also verify return values)
 
* automatic generation of API documentation
 
* automatic generation of API documentation
* easy way to create command line tools (us
+
* easy way to create command line tools (use the same API)
  
==Authentification==
+
== API URL ==
  
PVE uses a Token Based Authentication. All request to the API need to include that token inside a Cookie. We usually call that token a 'ticket'.
+
The API uses the HTTPS protocol and the server listens to port 8006. So the base URL for that API is
  
Additionally, any write request must include a CSRF prevention token inside the HTTP header.
+
https://your.server:8006/api2/json/
 +
 
 +
Parameters can be passed using standard HTTP techniques:
 +
 
 +
* via the URL
 +
* using 'x-www-form-urlencoded' content-type for PUT and POST request.
 +
 
 +
It is possible specify the return format in the URL. Above example uses 'json', but you can use any of the following values:
 +
 
 +
* json: JSON
 +
* extjs: JSON variant compatible with ExtJS forms
 +
* html: html formatted text - sometimes useful for debugging
 +
* text: plain text - sometimes useful for debugging
 +
 
 +
Please contact use on the development mailing list if you need other data formats.
 +
 
 +
== Authentication ==
 +
 
 +
PVE uses a Token Based Authentication. All request to the API need to include that token inside a Cookie. We usually call that token a 'ticket'. Additionally, any write request must include a CSRF prevention token inside the HTTP header. The following examples use the 'curl' command line tool.
  
 
Example: get a new ticket and the CSRF prevention token
 
Example: get a new ticket and the CSRF prevention token
Line 64: Line 76:
 
</pre>
 
</pre>
  
==References==
+
NOTE: Tickets have a limited lifetime of 2 hours. But you can simple get a new ticket by passing the old ticket as password to the /access/ticket method.
 +
 
 +
== Step by step  example of LXC creation using the API ==
 +
assumptions:
 +
* the node where we login is called APINODE
 +
* the node on which is the container will be created is called TARGETNODE
 +
* the auth cookie will be placed in the file "cookie"
 +
* the CSRF token will be placed in the file "csrftoken"
 +
 
 +
Note: for ease of use we use the '''jq(1)''' package which parses and pretty prints json data
 +
 
 +
=== export variables ===
 +
 
 +
export APINODE=pve4
 +
export TARGETNODE=pve4
 +
 
 +
=== Save an authorization cookie on the hard drive ===
 +
 
 +
curl --silent --insecure --data "username=root@pam&password=yourpassword" \
 +
  https://$APINODE:8006/api2/json/access/ticket\
 +
| jq --raw-output '.data.ticket' | sed 's/^/PVEAuthCookie=/' > cookie
 +
 
 +
=== Save a CSRF token locally ===
 +
 
 +
curl --silent --insecure --data "username=root@pam&password=yourpassword" \
 +
  https://$APINODE:8006/api2/json/access/ticket \
 +
| jq --raw-output '.data.CSRFPreventionToken' | sed 's/^/CSRFPreventionToken:/' > csrftoken
 +
 
 +
=== Test auth credentials ===
 +
We display the target node status
 +
 
 +
curl  --insecure --cookie "$(<cookie)" https://$APINODE:8006/api2/json/nodes/$TARGETNODE/status | jq '.'
 +
 
 +
=== creates an lxc container (with the given parameters) ===
 +
Note: we need to encode the HTTP POST body when passing non alphanumeric parameters
 +
<pre>
 +
curl --silent --insecure  --cookie "$(<cookie)" --header "$(<csrftoken)" -X POST\
 +
--data-urlencode net0="name=myct0,bridge=vmbr0" \
 +
--data-urlencode ostemplate="local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz" \
 +
--data vmid=601\
 +
https://$APINODE:8006/api2/json/nodes/$TARGETNODE/lxc
 +
</pre>
 +
 
 +
This should return a json structure containing the task id of the creation process which looks like:
 +
{
 +
  "data": "UPID:pve4:00002F9D:000DC5EA:57500527:vzcreate:602:root@pam:"
 +
}
 +
 
 +
Make sure you use an available vmid when creating a container.
 +
 
 +
=Using 'pvesh' to access the API=
 +
 
 +
As mentioned above, there is a command line tool called 'pvesh' which exposes the whole REST API. This is the Swiss Army knife for developers and system administrators.
 +
 
 +
some example commands:
 +
 
 +
pvesh get /version
 +
pvesh get /access/users
 +
 
 +
or create a new user:
 +
 
 +
pvesh create /access/users -userid testuser@pve
 +
 
 +
or delete that user:
 +
 
 +
pvesh delete /access/users/testuser@pve
 +
 
 +
or create and then launch a new container:
 +
 
 +
pvesh create /nodes/{node}/lxc -vmid 100 -hostname test -storage local \
 +
                                  -password supersecret \
 +
                                  -ostemplate local:vztmpl/debian-9.0-standard_9.5-1_amd64.tar.gz \
 +
                                  -memory 512 -swap 512
 +
pvesh create /nodes/{node}/lxc/100/status/start
 +
 
 +
where ''{node}'' is the name of the node on which the container should be created.
 +
 
 +
The tool automatically proxies call to other cluster members using ssh.
 +
 
 +
== Clients ==
 +
 
 +
=== From Proxmox Team maintained ===
 +
 
 +
;perl
 +
:https://git.proxmox.com/?p=pve-apiclient.git;a=summary
 +
 
 +
Available in the Proxmox Repositories, via
 +
 
 +
apt-get install libpve-apiclient-perl
 +
 
 +
=== Community ===
 +
 
 +
;python
 +
:https://pypi.python.org/pypi/proxmoxer (used in the ansible proxmox and proxmox_kvm modules)
 +
:https://github.com/remofritzsche/proxmox-utils
 +
:https://pypi.python.org/pypi/pyproxmox
 +
:https://github.com/baseblack/Proxmoxia
 +
 
 +
;ruby
 +
:https://github.com/nledez/proxmox
 +
 
 +
;nodejs
 +
:https://www.npmjs.com/package/proxmox
 +
 
 +
;c#
 +
:https://github.com/ionelanton/ProxmoxSharp
 +
:https://github.com/Corsinvest/cv4pve-api-dotnet
 +
:https://github.com/Corsinvest/cv4pve-cli
 +
:https://github.com/Corsinvest/cv4pve-botgram
 +
 
 +
;PHP
 +
:https://github.com/CpuID/pve2-api-php-client
 +
:https://github.com/ZzAntares/ProxmoxVE
 +
:https://github.com/aheahe/pve-cli-utils
 +
:https://github.com/Corsinvest/cv4pve-api-php
 +
 
 +
;java
 +
:https://github.com/Elbandi/pve2-api-java
 +
:https://github.com/Corsinvest/cv4pve-api-java
 +
 
 +
;perl
 +
:http://search.cpan.org/~djzort/Net-Proxmox-VE-0.006/
 +
 
 +
Please add any other clients here as they become available.
 +
 
 +
== References ==
  
 
[1] RESTful Web Services - Web services for the real world
 
[1] RESTful Web Services - Web services for the real world
Line 72: Line 209:
 
[2] JSON Schema links: http://json-schema.org/
 
[2] JSON Schema links: http://json-schema.org/
  
[[Category: Proxmox VE 2.0]]
+
[[Category: HOWTO]]

Latest revision as of 19:18, 9 October 2019

Introduction

Proxmox VE uses a REST like API. The concept is described in [1] (Resource Oriented Architectur - ROA).

We choose JSON as primary data format, and the whole API is formally defined using JSON Schema [2].

You can explore the API documentation at http://pve.proxmox.com/pve-docs/api-viewer/index.html

JSON and JSON Schema

The API use JSON as data format, because it is simple and parse-able by any web browser.

Additionally, we use JSON Schema [2] to formally describe our API. So we can automatically generate the whole API Documentation, and we can verify all parameters and return values.

An great side effect was that we are able to use JSON Schema to produce command line argument parsers automatically. In fact, the REST API and the command line tools use the same code. A small utility called 'pvesh' exposes the whole REST API on the command line.

So here is a summary of the advantage:

  • easy, human readable data format (native web browser format)
  • automatic parameter verification (we can also verify return values)
  • automatic generation of API documentation
  • easy way to create command line tools (use the same API)

API URL

The API uses the HTTPS protocol and the server listens to port 8006. So the base URL for that API is

https://your.server:8006/api2/json/

Parameters can be passed using standard HTTP techniques:

  • via the URL
  • using 'x-www-form-urlencoded' content-type for PUT and POST request.

It is possible specify the return format in the URL. Above example uses 'json', but you can use any of the following values:

  • json: JSON
  • extjs: JSON variant compatible with ExtJS forms
  • html: html formatted text - sometimes useful for debugging
  • text: plain text - sometimes useful for debugging

Please contact use on the development mailing list if you need other data formats.

Authentication

PVE uses a Token Based Authentication. All request to the API need to include that token inside a Cookie. We usually call that token a 'ticket'. Additionally, any write request must include a CSRF prevention token inside the HTTP header. The following examples use the 'curl' command line tool.

Example: get a new ticket and the CSRF prevention token

# curl -k -d "username=root@pam&password=yourpassword"  https://10.0.0.1:8006/api2/json/access/ticket 
{ "data": { 
  "CSRFPreventionToken":"4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY",  
  "ticket":"PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv...", 
  "username":"root@pam"}
}


You need to pass the returned ticket with a cookie to any further request:

curl -k -b "PVEAuthCookie=PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv..." https://10.0.0.1:8006/api2/json/

Additionally, any write request (POST, PUT, DELETE) must include the CSRFPreventionToken header:

curl -XDELETE -H "CSRFPreventionToken: 4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY" ...

NOTE: Tickets have a limited lifetime of 2 hours. But you can simple get a new ticket by passing the old ticket as password to the /access/ticket method.

Step by step example of LXC creation using the API

assumptions:

  • the node where we login is called APINODE
  • the node on which is the container will be created is called TARGETNODE
  • the auth cookie will be placed in the file "cookie"
  • the CSRF token will be placed in the file "csrftoken"

Note: for ease of use we use the jq(1) package which parses and pretty prints json data

export variables

export APINODE=pve4
export TARGETNODE=pve4

Save an authorization cookie on the hard drive

curl --silent --insecure --data "username=root@pam&password=yourpassword" \
 https://$APINODE:8006/api2/json/access/ticket\
| jq --raw-output '.data.ticket' | sed 's/^/PVEAuthCookie=/' > cookie

Save a CSRF token locally

curl --silent --insecure --data "username=root@pam&password=yourpassword" \
 https://$APINODE:8006/api2/json/access/ticket \
| jq --raw-output '.data.CSRFPreventionToken' | sed 's/^/CSRFPreventionToken:/' > csrftoken

Test auth credentials

We display the target node status

curl  --insecure --cookie "$(<cookie)" https://$APINODE:8006/api2/json/nodes/$TARGETNODE/status | jq '.'

creates an lxc container (with the given parameters)

Note: we need to encode the HTTP POST body when passing non alphanumeric parameters

curl --silent --insecure  --cookie "$(<cookie)" --header "$(<csrftoken)" -X POST\
 --data-urlencode net0="name=myct0,bridge=vmbr0" \
 --data-urlencode ostemplate="local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz" \
 --data vmid=601\
 https://$APINODE:8006/api2/json/nodes/$TARGETNODE/lxc

This should return a json structure containing the task id of the creation process which looks like:

{
  "data": "UPID:pve4:00002F9D:000DC5EA:57500527:vzcreate:602:root@pam:"
}

Make sure you use an available vmid when creating a container.

Using 'pvesh' to access the API

As mentioned above, there is a command line tool called 'pvesh' which exposes the whole REST API. This is the Swiss Army knife for developers and system administrators.

some example commands:

pvesh get /version
pvesh get /access/users

or create a new user:

pvesh create /access/users -userid testuser@pve

or delete that user:

pvesh delete /access/users/testuser@pve

or create and then launch a new container:

pvesh create /nodes/{node}/lxc -vmid 100 -hostname test -storage local \
                                  -password supersecret \
                                  -ostemplate local:vztmpl/debian-9.0-standard_9.5-1_amd64.tar.gz \
                                  -memory 512 -swap 512
pvesh create /nodes/{node}/lxc/100/status/start

where {node} is the name of the node on which the container should be created.

The tool automatically proxies call to other cluster members using ssh.

Clients

From Proxmox Team maintained

perl
https://git.proxmox.com/?p=pve-apiclient.git;a=summary

Available in the Proxmox Repositories, via

apt-get install libpve-apiclient-perl

Community

python
https://pypi.python.org/pypi/proxmoxer (used in the ansible proxmox and proxmox_kvm modules)
https://github.com/remofritzsche/proxmox-utils
https://pypi.python.org/pypi/pyproxmox
https://github.com/baseblack/Proxmoxia
ruby
https://github.com/nledez/proxmox
nodejs
https://www.npmjs.com/package/proxmox
c#
https://github.com/ionelanton/ProxmoxSharp
https://github.com/Corsinvest/cv4pve-api-dotnet
https://github.com/Corsinvest/cv4pve-cli
https://github.com/Corsinvest/cv4pve-botgram
PHP
https://github.com/CpuID/pve2-api-php-client
https://github.com/ZzAntares/ProxmoxVE
https://github.com/aheahe/pve-cli-utils
https://github.com/Corsinvest/cv4pve-api-php
java
https://github.com/Elbandi/pve2-api-java
https://github.com/Corsinvest/cv4pve-api-java
perl
http://search.cpan.org/~djzort/Net-Proxmox-VE-0.006/

Please add any other clients here as they become available.

References

[1] RESTful Web Services - Web services for the real world

By Leonard Richardson and Sam Ruby, Publisher: O'Reilly Media, Released: May 2007

[2] JSON Schema links: http://json-schema.org/