/ 
Net-Proxmox-VE-0.43
River stage zero No dependents
⭐ Starred 8 GitHub stars
/ Net::Proxmox::VE

NAME

Net::Proxmox::VE - Pure Perl API for Proxmox Virtual Environment

VERSION

version 0.43

SYNOPSIS

use Net::Proxmox::VE;

# User+Password Authentication
%args = (
    host     => 'proxmox.local.domain',
    password => 'barpassword',
    username => 'root', # optional
    port     => 8006,   # optional
    totp     => 123456, # optional
    realm    => 'pam',  # optional
);

$host = Net::Proxmox::VE->new(%args);

$host->login() or die ('Couldn\'t log in to proxmox host');

# API Token Authentication
%args = (
    host     => 'proxmox.local.domain',
    tokenid  => 'example',
    secret   => 'uuid',
    username => 'root', # optional
    port     => 8006,   # optional
    realm    => 'pam',  # optional
);

$host = Net::Proxmox::VE->new(%args);

DESCRIPTION

This Class provides a framework for talking to Proxmox VE REST API instances including ticket headers required for authentication. You can use just the get/delete/put/post abstraction layer or use the api function methods.

Object representations of the Proxmox VE REST API are included in seperate modules.

You can use either User+Password or API Tokens for authentication. See also https://pve.proxmox.com/wiki/User_Management

There is currently no support for 2FA (pull requests welcome).

WARNING

We are still moving things around and trying to come up with something that makes sense. We havent yet implemented all the API functions, so far we only have a basic internal abstraction of the REST interface and a few modules for each function tree within the API.

Any enhancements are greatly appreciated ! (use github, link below)

Please dont be offended if we refactor and rework submissions. Perltidy with default settings is prefered style.

Oh, our tests are all against a running server. Care to help make them better?

METHODS

action

This calls raw actions against your proxmox server. Ideally you don't use this directly.

api_version

Returns the API version of the proxmox server we are talking to, including some parts of the global datacenter config.

No arguments are available.

A hash will be returned which will include the following:

release

String. The current Proxmox VE point release in `x.y` format.

repoid

String. The short git revision from which this version was build.

version

String. The full pve-manager package version of this node.

console

Enum. The default console viewer to use. Optional.

Available values: applet, vv, html5, xtermjs

api_version_check

Checks that the api we are talking to is at least version 2.0

Returns true if the api version is at least 2.0 (perl style true or false)

check_login_ticket

Verifies if the objects login ticket is valid and not expired

Returns true if valid Returns false and clears the the login ticket details inside the object if invalid

clear_login_ticket

Clears the login ticket inside the object

debug

Has a single optional argument of 1 or 0 representing enable or disable debugging.

Undef (ie no argument) leaves the debug status untouched, making this method call simply a query.

Returns the resultant debug status (perl style true or false)

delete

An action helper method that just takes a path as an argument and returns the value of action() with the DELETE method

get

An action helper method that just takes a path as an argument and returns the value of action with the GET method

login

Initiates the login to the PVE Server using JSON API, and potentially obtains an Access Ticket.

Returns true if successful

new

Creates the Net::Proxmox::VE object and returns it.

Examples...

my $obj = Net::Proxmox::VE->new(%args);
my $obj = Net::Proxmox::VE->new(\%args);

Authentication arguments are...

username

User name used for authentication. Defaults to 'root', optional.

password

Pass word user for authentication. Either use this password field or tokenid and secret.

totp

Either the totp code or a sub ref to code that will return the totop code.

totp => '12345',
totp => sub { my %args = @_; return '12345' },

If a subref is provided, the %args will include the keys username, realm, and host with corresponding values. These may optionally be used to help determine the topt.

Only valid with username and password parameters.

tokenid

The tokenid of the API keys being used. Optional.

secret

The secret of the API keys being used. Optional, although required when a tokenid is provided.

This is distinct from the password field.

Other arguments are...

host

Proxmox host instance to interact with. Required so no default.

port

TCP port number used to by the Proxmox host instance. Defaults to 8006, optional.

realm

Authentication realm to request against. Defaults to 'pam' (local auth), optional.

ssl_opts

If you're using a self-signed certificate, SSL verification is going to fail, and we need to tell IO::Socket::SSL not to attempt certificate verification.

This option is passed on as ssl_opts options to LWP::UserAgent->new(), ultimately for IO::Socket::SSL.

Using it like this, causes LWP::UserAgent and IO::Socket::SSL not to attempt SSL verification:

use IO::Socket::SSL qw(SSL_VERIFY_NONE);
..
%args = (
    ...
    ssl_opts => {
        SSL_verify_mode => SSL_VERIFY_NONE,
        verify_hostname => 0
    },
    ...
);
my $proxmox = Net::Proxmox::VE->new(%args);

Your connection will work now, but beware: you are now susceptible to a man-in-the-middle attack.

debug

Enabling debugging of this API (not related to proxmox debugging in any way). Defaults to false, optional.

post

An action helper method that takes two parameters: $path, \%post_data $path to post to, hash ref to %post_data

You are returned what action() with the POST method returns

put

An action helper method that takes two parameters: $path, hash ref to \%put_data

You are returned what action() with the PUT method returns

url_prefix

Returns the url prefix used in the rest api calls

PVE VERSIONS SUPPORT

Firstly, there isn't currently any handling of different versions of the API.

Secondly, Proxmox API reference documentation is also, frustratingly, published only alongside the current release. This makes it difficult to support older versions of the API or different versions of the API concurrently.

Fortunately the API is relatively stable.

Based on the above the bug reporting policy is as follows:

A function in this module doesn't work against the current published API? This a bug and hope to fix it. Pull requests welcome.
A function in this module doesn't exist in the current published API? Pull requests welcomes and promptly merged.
A function in this module doesn't work against a previous version of the API? A note will be made in the pod only.
A function in this module doesn't exist against a previous version of the API? Pull requests will be merged on a case per case basis.

As such breaking changes may be made to this module to support the current API when necessary.

DESIGN NOTE

This API would be far nicer if it returned nice objects representing different aspects of the system. Such an arrangement would be far better than how this module is currently layed out. It might also be less repetitive code.

SEE ALSO

Proxmox Website

http://www.proxmox.com

API Reference

More details on the API can be found at http://pve.proxmox.com/wiki/Proxmox_VE_API and http://pve.proxmox.com/pve-docs/api-viewer/index.html

AUTHOR

Dean Hamstead <dean@fragfest.com.au>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2025 by Dean Hamstead.

This is free software, licensed under:

The MIT (X11) License