community.general.proxmox_user_info module – Retrieve information about one or more Proxmox VE users

Note

This module is part of the community.general collection (version 9.4.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.proxmox_user_info.

New in community.general 1.3.0

Synopsis

  • Retrieve information about one or more Proxmox VE users

Requirements

The below requirements are needed on the host that executes this module.

  • proxmoxer

  • requests

Parameters

Parameter

Comments

api_host

string / required

Specify the target host of the Proxmox VE cluster.

api_password

string

Specify the password to authenticate with.

You can use PROXMOX_PASSWORD environment variable.

api_port

integer

added in community.general 9.1.0

Specify the target port of the Proxmox VE cluster.

Uses the PROXMOX_PORT environment variable if not specified.

api_token_id

string

added in community.general 1.3.0

Specify the token ID.

Requires proxmoxer>=1.1.0 to work.

api_token_secret

string

added in community.general 1.3.0

Specify the token secret.

Requires proxmoxer>=1.1.0 to work.

api_user

string / required

Specify the user to authenticate with.

domain

aliases: realm

string

Restrict results to a specific authentication realm.

user

aliases: name

string

Restrict results to a specific user.

userid

string

Restrict results to a specific user ID, which is a concatenation of a user and domain parts.

validate_certs

boolean

If false, SSL certificates will not be validated.

This should only be used on personally controlled sites using self-signed certificates.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

action_group

Action group: community.general.proxmox

added in community.general 9.0.0

Use group/community.general.proxmox in module_defaults to set defaults for this module.

check_mode

Support: full

This action does not modify state.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: List existing users
  community.general.proxmox_user_info:
    api_host: helldorado
    api_user: root@pam
    api_password: "{{ password | default(omit) }}"
    api_token_id: "{{ token_id | default(omit) }}"
    api_token_secret: "{{ token_secret | default(omit) }}"
  register: proxmox_users

- name: List existing users in the pve authentication realm
  community.general.proxmox_user_info:
    api_host: helldorado
    api_user: root@pam
    api_password: "{{ password | default(omit) }}"
    api_token_id: "{{ token_id | default(omit) }}"
    api_token_secret: "{{ token_secret | default(omit) }}"
    domain: pve
  register: proxmox_users_pve

- name: Retrieve information about admin@pve
  community.general.proxmox_user_info:
    api_host: helldorado
    api_user: root@pam
    api_password: "{{ password | default(omit) }}"
    api_token_id: "{{ token_id | default(omit) }}"
    api_token_secret: "{{ token_secret | default(omit) }}"
    userid: admin@pve
  register: proxmox_user_admin

- name: Alternative way to retrieve information about admin@pve
  community.general.proxmox_user_info:
    api_host: helldorado
    api_user: root@pam
    api_password: "{{ password | default(omit) }}"
    api_token_id: "{{ token_id | default(omit) }}"
    api_token_secret: "{{ token_secret | default(omit) }}"
    user: admin
    domain: pve
  register: proxmox_user_admin

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

proxmox_users

list / elements=dictionary

List of users.

Returned: always, but can be empty

comment

string

Short description of the user.

Returned: on success

domain

string

User’s authentication realm, also the right part of the user ID.

Returned: on success

email

string

User’s email address.

Returned: on success

enabled

boolean

User’s account state.

Returned: on success

expire

integer

Expiration date in seconds since EPOCH. Zero means no expiration.

Returned: on success

firstname

string

User’s first name.

Returned: on success

groups

list / elements=string

List of groups which the user is a member of.

Returned: on success

keys

string

User’s two factor authentication keys.

Returned: on success

lastname

string

User’s last name.

Returned: on success

tokens

list / elements=dictionary

List of API tokens associated to the user.

Returned: on success

comment

string

Short description of the token.

Returned: on success

expire

integer

Expiration date in seconds since EPOCH. Zero means no expiration.

Returned: on success

privsep

boolean

Describe if the API token is further restricted with ACLs or is fully privileged.

Returned: on success

tokenid

string

Token name.

Returned: on success

user

string

User’s login name, also the left part of the user ID.

Returned: on success

userid

string

Proxmox user ID, represented as user@realm.

Returned: on success

Authors

  • Tristan Le Guern (@tleguern)