DEBOPS.PAM_ACCESS(5)

NAME
debops.pam_access - Manage pam_access(8) ACL rules using Ansible

SYNOPSIS

debops service/pam_access [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The Linux Pluggable Authentication Modules <https://en.wikipedia.org/wiki/Linux_PAM> provide dynamic authentication support to services on Linux hosts. The debops.pam_access role can be used to manage one aspect of PAM - access control rules that can be used to grant or revoke access to services based on users, groups and origins.

GETTING STARTED

  Default configuration

By default, the role does not configure any access rules in the /etc/security/access.conf file. Control over this file is initialized using a configuration entry named global. See the examples in the pam_access__rules for an explanation how to use it in the Ansible inventory to set the access rules.

Role is designed to be used by other Ansible roles to manage their own access lists, with a custom file per service. However, the rules defined via dependent variables are not tracked outside of the context of a given role (ie. in different playbooks), and roles cannot affect each other's access rules using this method. Similarly, in Ansible inventory users should set the state of the defined rules as append, so that they don't clobber the existing rule files when the debops.pam_access role is executed on its own, or via a different playbook.

The activation of the pam_access.so PAM module for each service is not managed by the debops.pam_access role itself, and should be managed by the Ansible roles designed to configure the services.

  Example inventory

The debops.pam_access role is included in the DebOps common playbook, therefore you don't need to do anything special to enable it on a host.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.pam_access role:

---
- name: Manage PAM Access Control Lists
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_pam_access' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: pam_access
      tags: [ 'role::pam_access', 'skip::pam_access' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::pam_access
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.pam_access Ansible role:

•   Manual pages: pam_access(8) <https://manpages.debian.org/pam_access(8)>, access.conf(5) <https://manpages.debian.org/access.conf(5)>

DEFAULT VARIABLE DETAILS

Some of the debops.pam_access default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  pam_access__rules

The pam_access__*_rules variables define the state of the /etc/security/access*.conf configuration files and their contents. The variables are merged in order defined by the pam_access__combined_rules variable, which allows modification of the default configuration through the Ansible inventory.

  Examples

Include some of the examples from the access.conf(5) <https://manpages.debian.org/access.conf(5)> manual page in the global /etc/security/access.conf configuration file. Note that the configuration is explicitly enabled because the role does not configure the global access list by default:

pam_access__rules:
  - name: 'global'
    state: 'present'
    options:
      - name: 'allow-root-locally'
        comment: |
          User root should be allowed to get access via cron, X11 terminal :0, tty1-6
        permission: 'allow'
        users: 'root'
        origins: [ 'crond', ':0', 'tty1', 'tty2', 'tty3', 'tty4', 'tty5', 'tty6' ]
      - name: 'allow-root-loopback'
        permission: '+'
        users: 'root'
        origins: '127.0.0.1'
      - name: 'allow-root-subnet'
        comment: |
          User root should get access from network 192.0.2. which can also be
          specified using a CIDR prefix, 192.0.2.0/24
        permission: 'allow'
        users: 'root'
        origins: [ '192.0.2.', '192.0.2.0/24' ]
      - name: 'allow-root-domain'
        comment: |
          User root should be able to have access from a specific domain
        permission: '+'
        users: 'root'
        origins: '.example.org'
      - name: 'deny-root'
        comment: |
          Deny access to the root account from any other sources
        permission: 'deny'
        users: 'root'
        origins: 'ALL'
      - name: 'allow-foo-admins'
        comment: |
          User 'foo' and members of netgroup 'admins' should be allowed to get
          access from all sources. This will only work if netgroup service is
          available.
        permission: '+'
        users: [ '@admins', 'foo' ]
        origins: 'ALL'
      - name: 'allow-john-ipv6subnet'
        comment: |
          User 'john' should get access from IPv6 net/mask.
        permission: 'allow'
        users: 'john'
        origins: '2001:db8:0:101::/64'
      - name: 'allow-local-wheel'
        comment: |
          Disallow console logins to all but the 'shutdown', 'sync' and all
          other accounts, which are a member of the 'wheel' group.
        permission: '-'
        groups_except: 'wheel'
        users_except: [ 'shutdown', 'sync' ]
        origins: 'LOCAL'
      - name: 'deny-all'
        comment: |
          All other users should be denied access from all sources. This rule
          will be placed at the end of the configuration, to allow easy
          addition of more rules before it.
        permission: 'deny'
        users: 'ALL'
        origins: 'ALL'
        weight: 99999

Add some of the examples from the default /etc/security/access.conf file installed by Debian to the /etc/security/access-sshd.conf configuration file used by the sshd service.

Note that the configuration has state append which means that even though the values are defined in the Ansible inventory, they will only be applied when the debops.pam_access role is used in the context of the debops.sshd role, via the sshd.yml playbook (the configuration entry was defined elsewhere and inventory entry is appended to it). Otherwise the custom access file used by the sshd service would be overwritten during normal usage of the debops.pam_access role.

The examples are nonsensical in the context of the OpenSSH service, but are provided here to show how to implement specific ACL rules.

pam_access__rules:
  - name: 'sshd'
    state: 'append'
    options:
      - name: 'deny-non-root'
        comment: 'Disallow non-root logins on tty1'
        permission: 'deny'
        users_except: 'root'
        origins: 'tty1'
      - name: 'deny-non-privileged'
        comment: 'Disallow non-local logins to privileged accounts'
        permission: '-'
        groups: 'wheel'
        origins_except: [ 'LOCAL', '.sub.example.org' ]

  Syntax

The variables contain a list of YAML dictionaries, each dictionary can have specific parameters:

name
    Required. Name of an access control configuration file managed by the debops.pam_access role. The role will create the file in:

    /etc/security/access-<name>.conf

    Configuration entries with the same name parameter will be merged together in order of appearance; this can be used to modify existing entries via the Ansible inventory.

filename
    Optional. Override the autogenerated file name. You should only specify the filename itself, files are stored in the /etc/security/ directory.

state
    Optional. If not specified or present, the configuration file will be generated. If absent, the specified configuration file will be removed. If init, the configuration entry will be initialized, but not active - this can be used to prepare an entry and activate it conditionally later. If ignore, a given configuration entry will not be evaluated by the role.

    If append, the configuration entry will be processed only if a given entry was defined earlier. This should be a preferred method to modify access rules defined by other Ansible roles through the Ansible inventory, otherwise the user roles will override the role rules.

divert
    Optional, boolean. If True, the role will automatically divert or revert the original access control rule file depending on its state, to preserve it for APT upgrades. This parameter shouldn't be changed if a diverted file is present, otherwise the role will not track the diversion.

fieldsep
    Optional. Specify the character that will be used as the field separator in the generated rule files. If not specified, colon (:) is used by default. See pam_access(8) <https://manpages.debian.org/pam_access(8)> for information about the usage of this parameter.

listsep
    Optional. Specify the character that will be used as the list element separator in the generated rule files. If not specified, space is used by default. See pam_access(8) <https://manpages.debian.org/pam_access(8)> for information about the usage of this parameter.

options
    Required. List of YAML dictionaries which describe PAM access rules. The lists in the entries with the same name parameter are merged together, with the rules that use the same name affecting each other in order of appearance. Rules can be defined using specific parameters:

name
    Required. Name of a given access rule, not used directly. Entries with the same name parameter will be merged together in order of appearance; this allows modification of existing entries via Ansible inventory.

permission
    Required. Specify the permission of a given access rule. Possible values:

•   allow / + / accept

•   deny / - / decline

users
    String or YAML list of usernames, netgroups or ALL that matches everyone. If users_except parameter is specified, this parameter is ignored.

users_except
    String or YAML list of usernames, netgroups or ALL that matches everyone. If this parameter is specified, the list of users or groups will be prefixed with ALL EXCEPT which allows for negation.

groups
    String or YAML list of UNIX group names, which will be automatically wrapped in parentheses (( )) to mark them as groups. If groups_except parameter is specified, this parameter is ignored.

groups_except
    String or YAML list of UNIX group names, which will be automatically wrapped in parentheses (( )) to mark them as groups. If this parameter is specified, the list of users or groups will be prefixed with ALL EXCEPT which allows for negation.

origins
    String or YAML list of "origins" - TTY names, hostnames, domain names (specified with the . prefix), IP addresses, network addresses (specified with the . suffix or with CIDR netmask), netgroup names, ALL which matches everything, or LOCAL which matches only local TTYs and services. If origins_except parameter is specified, this parameter is ignored.

origins_except
    String or YAML list of "origins" - TTY names, hostnames, domain names (specified with the . prefix), IP addresses, network addresses (specified with the . suffix or with CIDR netmask), netgroup names, ALL which matches everything, or LOCAL which matches only local TTYs and services. If this parameter is specified, the list of origins will be prefixed with ALL EXCEPT which allows for negation.

comment
    Optional. String or YAML text block that contains comments about a given access rule.

state
    Optional. If not specified or present, a given access rule will be included in the generated rule file. If absent, the rule will be removed from the generated rule file.

weight
    Optional. Positive or negative number, which can be used to affect the position of the rule within the rule file. Positive numbers will force the rule to be lower than normal (adding weight), negative numbers will move the role higher on the list (substracting weight).

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others