The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Net::Proxmox::VE::Access - Functions for the 'access' portion of the API

VERSION

version 0.38

SYNOPSIS

  # assuming $obj is a Net::Proxmox::VE object

  my @dir_index = $obj->access();

  my @domain_index = $obj->access_domains();
  my $domain = $obj->access_domains($realm);

METHODS

access

Without arguments, returns the 'Directory index':

Note: Accessible by all authententicated users.

access_domains

Gets a list of access domains (aka the Authentication domain index)

  @pools = $obj->access_domains();

Note: Anyone can access that, because we need that list for the login box (before the user is authenticated).

create_access_domains

Creates a new access domain

  $ok = $obj->create_access_domains( %args );
  $ok = $obj->create_access_domains( \%args );

%args may items contain from the following list

realm

String. The id of the authentication domain you wish to add, in pve-realm format. This is required.

type

Enum. This is the server type and is either 'ad' or 'ldap'. This is required.

base_dn

String. LDAP base domain name. Optional.

comment

String. This is a comment associated with the new domain, this is optional.

default

Boolean. Use this domain as the default. Optional.

domain

String. AD domain name. Optional.

port

Integer. Server port, user '0' if you want to use the default setting. Optional.

secure

Boolean. Use secure LDAPS protocol. Optional.

user_attr

String. LDAP user attribute name. Optional.

get_access_domains

Gets a single access domain

  $ok = $obj->get_access_domains('realm')

realm is a string in pve-realm format

update_access_domains

Updates (sets) a access domain's data

  $ok = $obj->update_access_domains( 'realm', %args );
  $ok = $obj->update_access_domains( 'realm', \%args );

realm is a string in pve-realm format

%args may items contain from the following list

base_dn

String. LDAP base domain name. Optional.

comment

String. This is a comment associated with the domain, this is optional.

default

Boolean. Use this domain as the default. Optional.

domain

String. AD domain name. Optional.

port

Integer. Server port, user '0' if you want to use the default setting. Optional.

secure

Boolean. Use secure LDAPS protocol. Optional.

user_attr

String. LDAP user attribute name. Optional.

delete_access_domains

Deletes a single access domain

  $ok = $obj->delete_access_domains('realm')

realm is a string in pve-realm format

access_groups

Gets a list of access groups (aka the Group index)

  @pools = $obj->access_groups();

Note: The returned list is restricted to groups where you have 'User.Modify', 'Sys.Audit' or 'Group.Allocate' permissions on /access/groups/<<group>>.

create_access_groups

Creates a new access group

  $ok = $obj->create_access_groups( %args );
  $ok = $obj->create_access_groups( \%args );

%args may items contain from the following list

groupid

String. The id of the access group you wish to add, in pve-groupid format. This is required.

comment

String. This is a comment associated with the new group, this is optional.

get_access_groups

Gets a single access group

  $ok = $obj->get_access_groups('groupid')

groupid is a string in pve-groupid format

update_access_groups

Updates (sets) a access group's data

  $ok = $obj->update_access_groups( 'groupid', %args );
  $ok = $obj->update_access_groups( 'groupid', \%args );

groupid is a string in pve-groupid format

%args may items contain from the following list

comment

String. This is a comment associated with the group, this is optional.

delete_access_groups

Deletes a single access group

  $ok = $obj->delete_access_groups('groupid')

groupid is a string in pve-groupid format

access_roles

Gets a list of access roles (aka the Role index)

  @pools = $obj->access_roles();

Note: Accessible by all authententicated users.

create_access_roles

Creates a new access role

  $ok = $obj->create_access_roles( %args );
  $ok = $obj->create_access_roles( \%args );

%args may items contain from the following list

roleid

String. The id of the access role you wish to add, in pve-roleid format. This is required.

privs

String. A string in pve-string-list format. Optional.

get_access_roles

Gets a single access role

  $ok = $obj->get_access_roles('roleid')

roleid is a string in pve-roleid format

update_access_roles

Updates (sets) a access role's data

  $ok = $obj->update_access_roles( 'roleid', %args );
  $ok = $obj->update_access_roles( 'roleid', \%args );

roleid is a string in pve-roleid format

%args may items contain from the following list

privs

String. A string in pve-priv-list format, this is required.

append

Booelean. Append privileges to existing. Optional.

delete_access_roles

Deletes a single access role

  $ok = $obj->delete_access_roles('roleid')

roleid is a string in pve-roleid format

access_users

Gets a list of users (aka the User index)

  @pools = $obj->access_users();

Note: You need 'Realm.AllocateUser' on '/access/realm/<<realm>>' on the realm of user <<userid>>, and 'User.Modify' permissions to '/access/groups/<<group>>' for any group specified (or 'User.Modify' on '/access/groups' if you pass no groups.

create_access_users

Creates a new user

  $ok = $obj->create_access_users( %args );
  $ok = $obj->create_access_users( \%args );

%args may items contain from the following list

userid

String. The id of the user you wish to add, in pve-userid format. This is required.

comment

String. This is a comment associated with the new user, this is optional.

email

String. The users email address in email-opt format. Optional.

enable

Boolean. If the user is enabled where the default is to be enabled. Disable with a 0 value. Optional.

expire

Integer. Account expiration date in seconds since epoch. 0 means never expire. Optional.

firstname

String. Optional.

groups

String. A string in pve-groupid-list format. Optional.

lastname

String. Optional.

password

String. The users initial passowrd. Optional.

get_access_users

Gets a single user

  $ok = $obj->get_access_users('userid')

userid is a string in pve-userid format

update_access_users

Updates (sets) a user's configuration

  $ok = $obj->update_access_users( 'userid', %args );
  $ok = $obj->update_access_users( 'userid', \%args );

userid is a string in pve-userid format

%args may items contain from the following list

append

Boolean. Optional.

comment

String. This is a comment associated with the user, this is optional.

email

String. The users email address in email-opt format. Optional.

enable

Boolean. If the user is enabled where the default is to be enabled. Disable with a 0 value. Optional.

expire

Integer. Account expiration date in seconds since epoch. 0 means never expire. Optional.

firstname

String. Optional.

groups

String. A string in pve-groupid-list format. Optional.

lastname

String. Optional.

delete_access_users

Deletes a single user

  $ok = $obj->delete_access_users('userid')

userid is a string in pve-userid format

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

get_access_acl

The returned list is restricted to objects where you have rights to modify permissions

  $pool = $obj->get_access_acl();

Note: The returned list is restricted to objects where you have rights to modify permissions.

login

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

Returns true if success

update_access_acl

Updates (sets) an acl's data

  $ok = $obj->update_access_acl( %args );
  $ok = $obj->update_access_acl( \%args );

%args may items contain from the following list

path

String. Access control path. Required.

roles

String. List of roles. Required.

delete

Boolean. Removes the access rather than adding it. Optional.

groups

String. List of groups. Optional.

propagate

Boolean. Allow to propagate (inherit) permissions. Optional.

users

String. List of users. Optional.

update_access_password

Updates a users password

  $ok = $obj->update_password( %args );
  $ok = $obj->update_password( \%args );

Each user is allowed to change his own password. See proxmox api document for which permissions are needed to change the passwords of other people.

%args may items contain from the following list

password

String. The new password. Required.

userid

String. User ID. Required.

Note: Each user is allowed to change his own password. A user can change the password of another user if he has 'Realm.AllocateUser' (on the realm of user <<userid>>) and 'User.Modify' permission on /access/groups/<<group>> on a group where user <<userid>> is member of.

SEE ALSO

Net::Proxmox::VE

AUTHOR

Brendan Beveridge <brendan@nodeintegration.com.au>, Dean Hamstead <dean@fragfest.com.au>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023 by Dean Hamstad.

This is free software, licensed under:

  The MIT (X11) License