julien_lecomte.proxmox.realm (1.0.2) — module

Install collection

Install with ansible-galaxy collection install julien_lecomte.proxmox:==1.0.2

Add to requirements.yml

  collections:
    - name: julien_lecomte.proxmox
      version: 1.0.2

Description

Adds, modifies, or removes a Proxmox realm.

Returned values will exist in a variable named 'realm'.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Create Active Directory realm.
  julien_lecomte.proxmox.realm:
    name: corp
    type: ad
    domain: corp.example.com
    server1: corp.example.com
    default: true
    secure: true
    comment: "Example Active Directory (corp.example.com)"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Sync Active Directory groups.
  julien_lecomte.proxmox.realm:
    name: corp
    sync: True
    sync_options:
      scope: "groups"
      full: False
      purge: False

Inputs

    
cert:
    description:
    - Path to the client certificate.
    type: str

mode:
    choices:
    - ldap
    - ldap+starttls
    - ldaps
    description:
    - LDAP protocol mode.
    type: str

name:
    description:
    - The realm name.
    required: true
    type: str

port:
    description:
    - Server port.
    type: int

sync:
    default: false
    description:
    - For a sync command to automatically sync users and groups for LDAP-based realms
      (LDAP & Microsoft Active Directory only)
    - This requires the correct fields to be set.
    - Please refer to the syncing sections of `pveum man page <https://pve.proxmox.com/pve-docs/pveum.1.html>`__.
    type: bool

type:
    choices:
    - ad
    - ldap
    - openid
    - pam
    - pve
    description:
    - Realm type.
    type: str

state:
    choices:
    - absent
    - present
    default: present
    description:
    - Specify if the realm should exist (present) or absent.
    type: str

capath:
    description:
    - Path to the CA certificate store.
    type: str

domain:
    description:
    - AD domain name.
    - Required when type is 'ad'.
    type: str

filter:
    description:
    - LDAP filter for user sync.
    type: str

prompt:
    description:
    - Specifies whether the Authorization Server prompts the End-User for reauthentication
      and consent. (?:none|login|consent|select_account|\S+)
    type: str

scopes:
    description:
    - B(Warning:) not to be confused with parameter I(scope) (singular).
    - Specifies the scopes (user details) that should be authorized and returned, for
      example email or profile.
    type: str

secure:
    description:
    - Use ssl.
    type: bool

verify:
    description:
    - "Verify the server\u2019s SSL certificate."
    type: bool

base_dn:
    description:
    - LDAP base domain name.
    - Required when type is 'ldap'.
    type: str

bind_dn:
    description:
    - LDAP bind domain name.
    type: str

certkey:
    description:
    - Path to the client certificate key.
    type: str

comment:
    description:
    - Optionally sets the comment field.
    type: str

default:
    description:
    - Use this as default realm.
    type: bool

server1:
    description:
    - Server IP address (or DNS name).
    - Required when type is 'ad' or 'ldap'.
    type: str

server2:
    description:
    - Fallback Server IP address (or DNS name).
    type: str

group_dn:
    description:
    - LDAP base domain name for group sync.
    - If not set, the base_dn will be used.
    type: str

password:
    description:
    - LDAP bind password. Will be stored in /etc/pve/priv/realm/<REALM>.pw.
    type: str

client_id:
    description:
    - OpenID Client ID.
    - Required when type is 'openid'.
    type: str

user_attr:
    description:
    - LDAP user attribute name.
    - Required when type is 'ldap'.
    type: str

acr_values:
    description:
    - Specifies the Authentication Context Class Reference values that theAuthorization
      Server is being requested to use for the Auth Request.
    type: str

autocreate:
    description:
    - Automatically create users if they do not exist.
    type: bool

client_key:
    description:
    - OpenID Client Key.
    type: str

issuer_url:
    description:
    - OpenID Issuer URL.
    - Required when type is 'openid'.
    type: str

sslversion:
    choices:
    - tlsv1
    - tlsv1_1
    - tlsv1_2
    - tlsv1_3
    description:
    - LDAPS TLS/SSL version. It's not recommended to use version older than 1.2!
    type: str

group_filter:
    description:
    - LDAP filter for group sync.
    type: str

sync_options:
    description:
    - Optional fields for when I(sync) is true
    suboptions:
      dry_run:
        default: false
        description:
        - Only when I(sync) is true.
        - If set, does not write anything.
        type: bool
      enable_new:
        description:
        - Only when I(sync) is true.
        - Enable newly synced users immediately.
        - Defaults to true unless set in I(sync_defaults_options).
        type: bool
      full:
        description:
        - Only when I(sync) is true.
        - B(Deprecated since Proxmox 7.2)
        - If set, uses the LDAP Directory as source of truth, deleting users or groups
          not returned from the sync and removing all locally modified properties of synced
          users.
        - If not set, only syncs information which is present in the synced data, and
          does not delete or modify anything else.
        - Must either be specified in task, or set with I(sync_defaults_options).
        type: bool
      purge:
        description:
        - Only when I(sync) is true.
        - B(Deprecated since Proxmox 7.2)
        - Remove ACLs for users or groups which were removed from the config during a
          sync.
        - Must either be specified in task, or set with I(sync_defaults_options).
        type: bool
      remove_vanished:
        description:
        - Only when I(sync) is true.
        - B(New since Proxmox 7.2)
        - A semicolon-separated list of things to remove when they or the user vanishes
          during a sync.
        - 'The following values are possible: C(entry) removes the user/group when not
          returned from the sync.'
        - C(properties) removes the set properties on existing user/group that do not
          appear in the source (even custom ones).
        - C(acl) removes acls when the user/group is not returned from the sync.
        - Must either be specified in task, or set with I(sync_defaults_options).
        type: str
      scope:
        choices:
        - both
        - groups
        - users
        description:
        - B(Warning:) not to be confused with parameter I(scopes) (plural).
        - Select what to sync.
    type: dict

user_classes:
    description:
    - The objectclasses for users. (default = C(inetorgperson, posixaccount, person, user))
    type: str

group_classes:
    description:
    - The objectclasses for groups.
    type: str

case_sensitive:
    description:
    - Username is case-sensitive.
    type: bool

username_claim:
    description:
    - OpenID claim used to generate the unique username.
    type: str

group_name_attr:
    description:
    - LDAP attribute representing a groups name.
    - If not set or found, the first value of the DN will be used as name.
    type: str

Outputs

comment:
  description: Comment field.
  returned: when realm exists
  type: str
name:
  description: Proxmox realmid.
  returned: always
  type: str
state:
  description: State ("absent" or "present").
  returned: always
  type: str
type:
  description: Realm type. (ad, ldap, openid, pam, pve)
  returned: when realm exists
  type: str

See also

• PVE API: Proxmox VE Application Programming Interface link