# pamd – Manage PAM Modules

- Synopsis
- Parameters
- Examples
- Return Values
- Status

## Synopsis

- Edit PAM service’s type, control, module path and module arguments.
- In order for a PAM rule to be modified, the type, control and module_path must match an existing rule. See man(5) pam.d for details.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

backup
boolean
added in 2.6

Choices:
- no ←
- yes

Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.

control string / required |  | The control of the PAM rule being modified. This may be a complicated control with brackets. If this is the case, be sure to put "[bracketed controls]" in quotes. The `type`, `control` and `module_path` all must match a rule to be modified.

module_arguments
list

When state is `updated`, the module_arguments will replace existing module_arguments.
When state is `args_absent` args matching those listed in module_arguments will be removed.
When state is `args_present` any args listed in module_arguments are added if missing from the existing rule.
Furthermore, if the module argument takes a value denoted by `=`, the value will be changed to that specified in module_arguments.

module_path string / required |  | The module path of the PAM rule being modified. The `type`, `control` and `module_path` all must match a rule to be modified.
name string / required |  | The name generally refers to the PAM service file to change, for example system-auth.
new_control string |  | The new control to assign to the new rule.
new_module_path string |  | The new module path to be assigned to the new rule.

new_type
string

Choices:
- account
- -account
- auth
- -auth
- password
- -password
- session
- -session

The new type to assign to the new rule.

path path | Default: "/etc/pam.d" | This is the path to the PAM service files.

state
string

Choices:
- absent
- before
- after
- args_absent
- args_present
- updated ←

The default of `updated` will modify an existing rule if type, control and module_path all match an existing rule.
With `before`, the new rule will be inserted before a rule matching type, control and module_path.
Similarly, with `after`, the new rule will be inserted after an existing rulematching type, control and module_path.
With either `before` or `after` new_type, new_control, and new_module_path must all be specified.
If state is `args_absent` or `args_present`, new_type, new_control, and new_module_path will be ignored.
State `absent` will remove the rule. The 'absent' state was added in Ansible 2.4.

type
string / required

Choices:
- account
- -account
- auth
- -auth
- password
- -password
- session
- -session

The type of the PAM rule being modified.
The `type`, `control` and `module_path` all must match a rule to be modified.

## Examples

    - name: Update pamd rule's control in /etc/pam.d/system-auth
      pamd:
        name: system-auth
        type: auth
        control: required
        module_path: pam_faillock.so
        new_control: sufficient

    - name: Update pamd rule's complex control in /etc/pam.d/system-auth
      pamd:
        name: system-auth
        type: session
        control: '[success=1 default=ignore]'
        module_path: pam_succeed_if.so
        new_control: '[success=2 default=ignore]'

    - name: Insert a new rule before an existing rule
      pamd:
        name: system-auth
        type: auth
        control: required
        module_path: pam_faillock.so
        new_type: auth
        new_control: sufficient
        new_module_path: pam_faillock.so
        state: before

    - name: Insert a new rule pam_wheel.so with argument 'use_uid' after an \
            existing rule pam_rootok.so
      pamd:
        name: su
        type: auth
        control: sufficient
        module_path: pam_rootok.so
        new_type: auth
        new_control: required
        new_module_path: pam_wheel.so
        module_arguments: 'use_uid'
        state: after

    - name: Remove module arguments from an existing rule
      pamd:
        name: system-auth
        type: auth
        control: required
        module_path: pam_faillock.so
        module_arguments: ''
        state: updated

    - name: Replace all module arguments in an existing rule
      pamd:
        name: system-auth
        type: auth
        control: required
        module_path: pam_faillock.so
        module_arguments: 'preauth
            silent
            deny=3
            unlock_time=604800
            fail_interval=900'
        state: updated

    - name: Remove specific arguments from a rule
      pamd:
        name: system-auth
        type: session
        control: '[success=1 default=ignore]'
        module_path: pam_succeed_if.so
        module_arguments: crond,quiet
        state: args_absent

    - name: Ensure specific arguments are present in a rule
      pamd:
        name: system-auth
        type: session
        control: '[success=1 default=ignore]'
        module_path: pam_succeed_if.so
        module_arguments: crond,quiet
        state: args_present

    - name: Ensure specific arguments are present in a rule (alternative)
      pamd:
        name: system-auth
        type: session
        control: '[success=1 default=ignore]'
        module_path: pam_succeed_if.so
        module_arguments:
        - crond
        - quiet
        state: args_present

    - name: Module arguments requiring commas must be listed as a Yaml list
      pamd:
        name: special-module
        type: account
        control: required
        module_path: pam_access.so
        module_arguments:
        - listsep=,
        state: args_present

    - name: Update specific argument value in a rule
      pamd:
        name: system-auth
        type: auth
        control: required
        module_path: pam_faillock.so
        module_arguments: 'fail_interval=300'
        state: args_present

    - name: Add pam common-auth rule for duo
      pamd:
        name: common-auth
        new_type: auth
        new_control: '[success=1 default=ignore]'
        new_module_path: '/lib64/security/pam_duo.so'
        state: after
        type: auth
        module_path: pam_sss.so
        control: 'requisite'

## Return Values

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

Key | Returned | Description
--- | --- | ---
action string added in 2.4 | always | That action that was taken and is one of: update_rule, insert_before_rule, insert_after_rule, args_present, args_absent, absent. This was available in Ansible 2.4 and removed in Ansible 2.8 Sample: update_rule
backupdest string added in 2.6 | success | The file name of the backup file, if created.
change_count integer added in 2.4 | success | How many rules were changed. Sample: 1
dest string | success | Path to pam.d service that was changed. This is only available in Ansible 2.3 and was removed in Ansible 2.4. Sample: /etc/pam.d/system-auth
new_rule string added in 2.4 | success | The changes to the rule. This was available in Ansible 2.4 and Ansible 2.5. It was removed in Ansible 2.6. Sample: None None None sha512 shadow try_first_pass use_authtok
updated_rule_(n) string added in 2.4 | success | The rule(s) that was/were changed. This is only available in Ansible 2.4 and was removed in Ansible 2.5. Sample: ['password sufficient pam_unix.so sha512 shadow try_first_pass use_authtok']

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Kenneth D. Evensen (@kevensen)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.