Configuration

ADMan configuration is done using a YAML file.

Default path

By default, Adman looks for its config file at:

/etc/adman/config.yml when run as root
~/.config/adman/config.yml when run as a normal user

Types

ADMan configuration items expect inputs of certain types. The following standard YAML types are used:

boolean – True or False
int – A decimal integer
string – A string of text; recommended to be elcosed in quotes
list<T> – A YAML list of values of another type

Additionally, the following custom “types” are defined:

path – A YAML string; the path to a file. The path can either be absolute (start with a leading /), or relative to the directory containing the config.yml file.

range – A YAML mapping with required min and max integers

duration – A string describing duration of time, expressed as N UNITS where N is an integer and UNITS is a unit of time e.g. “days”

containers – A YAML mapping where:

The keys identify an LDAP container by its DN, relative to the domain DN. Put another way, they are one or more RDN strings joined by commas. See the example below.
The values are a mapping with the following keys:
Config Key

Type

Default

Description
scope

string

“subtree”
Scope of LDAP search in the container:

one (this container only)

subtree (this container and all child containers)
If there are no keys (i.e., YAML null or {}), then no containers are considered.
Some uses of the containers type may accept the string all to mean “all containers in the domain”, and may default to this if the entire config setting is omitted.

Common settings

These settings apply to ADMan as a whole, or multiple Tasks. Feature-specific configuration are described on each feature’s page.

Config Key	Type	Default	Description
`domain`	string	(required)	DNS name of domain (e.g. `ad.example.com`)
`changelog`	path	(standard error)	Path to file where changes are written
`ldap_auth`	ldap_auth settings	(required)	LDAP authentication options
`smtp`	smtp settings	(required 1)	Settings for sending email

Note

1

smtp is required if any of the following are used:

Password expiry notification
Find stale user / computer accounts stale_accounts.email_to config

`ldap_auth` settings

Config Key	Type	Default	Description
`mode`	string	(required)	LDAP authentication mode – choices: `gssapi` – Use Kerberos via GSSAPI
`krb_username`	string	(required 2)	Kerberos username
`krb_keytab`	path	(required 2)	Kerberos keytab path (see Setup)
`krb_cache`	path	(required 2)	Kerberos credential cache path

Note

2(1,2,3): ldap_auth.krb_* options are required if ADMan is to automatically manage kerberos tickets. These can be left unset if adman is to use the current user’s ticket.

`smtp` settings

Config Key	Type	Default	Description
`email_from`	string	(required)	Email address from which messages should be sent
`host`	string	“localhost”	SMTP server hostname/IP to which messages should be sent
`port`	integer	25 (or 465 for SSL)	SMTP server port number
`username`	string	(none)	SMTP username
`password`	string	(none) (req’d w/ username)	SMTP password
`encryption`	string	(none)	SMTP server encryption node; one of: (blank) – Not encrypted `starttls` – Opportunistic TLS (via `STARTTLS`) `ssl` – Implicit (mandatory) SSL/TLS

Example config file

# Any path entries can be given as either absolute paths
# or as relative paths, relative to the config file directory.

# The DNS name of the domain
domain: ad.example.com

# LDAP authentication
ldap_auth:
  # Mode of authentication; options: gssapi
  mode: gssapi

  # gssapi options
  # These are required if adman is to automatically manage kerberos tickets.
  # These can be left unset if adman is to use the current user's ticket.

  # Kerberos username
  krb_username: domain-janitor

  # Kerberos keytab path
  krb_keytab: domain-janitor.keytab

  # Kerberos credential cache path
  krb_cache: /tmp/domain-janitor.cc


# Path to file to which changes are logged
# Default: write to stderr
changelog: /var/log/adman-changes.log


# Assign RFC2307 uidNumber/gidNumber attributes to users and groups
id_assign:
  # Range of values to use for assigning uidNumber attributes
  uid_range:
    min: 100000
    max: 200000

  # Range of values to use for assigning gidNumber attributes
  gid_range:
    min: 100000
    max: 200000

  # Assign uidNumber to computer accounts? (default True)
  computers: True

  # The "only" key, if present, will restrict ID assignment to members of the
  # given containers. Optional scope can be be 'one' or 'subtree' (default).
  # This applies to both users (including computers) and groups.
  only:
    # Recommended to always include these three containers
    CN=Users:
    CN=Computers:
    OU=Domain Controllers:

    # Other custom containers
    OU=ADTest People:
      scope: one
# end id_assign

# Automatically create user directories
userdirs:
    # basepath is the directory in which to create each userdir
  - basepath: '//dc1.ad-test.vx/netlogon/users/'
    # Limit to these users
    only:
      OU=ADTest People:
        scope: one
    # owner is the account name to set as the owner of each userdir
    owner: Fileshare Owner
    group: Storage Admins
    acl:
      - "${user}:0/0/0x001201ff"    # Basically everything but delete
      - "${user}:0/11/0x001f01ff"   # Everything (inherit only)
      - "Domain Users:0/0/0x001200a9"   # Users can... traverse? (Requires access-based enumeration)
    # additional subdirectories to create in each user's directory
    # owner and group are inherited from above
    subdirs:
      - name: 'public'
        acl:
          - "${user}:0/0/0x001f01ff"        # Everything
          - "Domain Users:0/0/0x001200a9"   # TODO
# end userdirs


# Apply consistent UPN suffixes to all members of a container (OU)
upn_suffixes:

  # The key is the container which specifies the set of users to which the UPN
  # suffix will be applied. There are two ways to specify the UPN suffix to be
  # applied to a container:

  # 1. The simple format just specifies the suffix:
  CN=Users: example.com

  # 2. The complex format allows the scope to be specified,
  # which can be either 'one' or 'subtree' (the default)
  OU=Special Users,OU=People:
    suffix: special.com
    scope: one
# end upn_suffixes


# Notify users when their password is about to expire
# (Useful for LDAP-only users)
password_expiry_notification:
  # Users should be notified each time their password expires
  # in this many days
  days: [7, 3, 2, 1, 0]


  # The template to use for sending mail
  template_file: example_pwnotify.tmpl
# end password_expiry_notification


# Settings used for sending email
smtp:
  # The email address from which messages should be sent (required)
  email_from: "Domain Janitor <domain-janitor@example.com>"

  # Host is optional; defaults to localhost
  host: "smtp.example.com"

  # Port is optional; defaults to 25 (or 465 for SSL)
  port: 25

  # Username/password are optional
  username: "joe"
  password: "password"

  # Encryption is optional and can be "starttls" or "ssl"
  encryption: "starttls"


# Find stale user/computer accounts that haven't recently been logged into
stale_accounts:
  # Admin email to which reports are sent
  email_to: "System Administrator <sysadmin@example.com>"

  # Domain-wide settings
  # How old an account must be before it is "stale"
  older_than: "120 days"

  # Whether or not to disable stale accounts
  #disable: True

  # Whether or not to report already-disabled accounts (default: False)
  include_disabled: True

  # By default, the entire domain is searched for stale user and computer
  # accounts. That can be overridden for user and computer accounts separately.
  # LDAP containers to be searched can be specified here, along with settings
  # which override those above.
  users:
    OU=Special Users,OU=People:
      # LDAP search scope; can be 'one' or 'subtree' (default).
      scope: one
      older_than: "30 days"
      disable: True
      include_disabled: False

    CN=Users:
      #scope: subtree

  computers:
    CN=Computers:
      disable: True
    OU=Domain Controllers:
# end stale_accounts