Configuration File

By default, padnag configuration is in a file called padnag.toml in the same directory as the executable. This can be changed with command line options.
The configuration file is in the .TOML file format. TOML is similar to an .INI file but has several technical features that make it more suitable for padnag.
TOML is case sensitive, backslash escaped and UTF8 encoded.

Each section of the config file is described below in detail.


In most cases, providing values for server, user and password should be sufficient.

  • server : The resolvable name or IP address of your Active Directory server.
  • user : The account of the user to log in for simple bind (defaults to None)
  • password : The password of the user for simple bind (defaults to None)
  • other AD settings*


The connection details for the PostgreSQL database. Usually host, user, password and database will be enough.

  • user : The username to connect to the PostgreSQL server with. Only ascii and utf8 user names are supported
  • host : The hostname of the PostgreSQL server to connect with. Providing this parameter is necessary for TCP/IP connections. One of either host or unix_sock must be provided. The default is localhost.
  • unix_sock : The path to the UNIX socket to access the database through, for example, '/tmp/.s.PGSQL.5432'. One of either host or unix_sock must be provided.
  • port : The TCP/IP port of the PostgreSQL server instance. This parameter defaults to 5432, the registered common port of PostgreSQL TCP/IP servers.
  • database : The name of the database instance to connect with. Because all actions against this specified database can be committed in a single txn, it is preferable ( but not required ) that this is the principle database of the cluster, rather than a system database like "postgres". Only ascii and utf8 database names are supported. This parameter is optional; if omitted, the PostgreSQL server will assume the database name is the same as the username.
  • password : The user password to connect to the server with. Only ascii and utf8 passwords are supported. This parameter is optional; if omitted and the database server requests password-based authentication, the connection will fail to open. If this parameter is provided but not requested by the server, no error will occur.
  • ssl : Use SSL encryption for TCP/IP sockets if True. Defaults to False
  • timeout : This is the time in seconds before the connection to the database will time out. The default is no timeout.

Database Privileges

padnag expects that the database administrator will GRANT appropriate privileges to groups, rather than individual roles. padnag works with the Postresql convention that roles without the LOGIN privilege are considered groups. Inversely, roles with the LOGIN privilege are considered individuals. It is notable that once padnag has created a role or group, that does not imply that the new role has any privileges other than those derived from PUBLIC.


This section is the heart of padnag config. This is the main configuration for syncing the Active Directory and PostgreSQL groups and roles. For an [[Organisation]], any AD groups found will be searched for nested groups, and the same hierarchy of groups and users will be created in the database.
padnag will create the PostgreSQL groups as necessary. Then databases role matching the AD sAMAccountName (or role_attibute if specified ) will be created and granted as belonging to the PostgreSQL group role.

Padnag does not grant priviliges to database groups or roles. The database administrator should ensure the the PostgreSQL group role is assigned the appropriate database privileges.
Multiple [[Organisation]] sections are allowed. Note the double square brackets.

  • name : Because the AD query might not point to a named group, a name is required. This will be the name of the root group role in the database. The name can be the same in several [[Organisation]] sections, or a completely unique groups root name.
  • base : In Active Directory / LDAP syntax. e.g.


  • filter : In Active Directory / LDAP syntax. Internally this gets combined with ObjectClass filters for users and groups. e.g.


  • group_attribute : Optional, defaults to "name". The Acitve Directory attribute to for the name of database groups
  • role_attribute : Optional, defaults to "[email protected] The Active Directory attribute to use for the name of database roles
  • group_transforms : See the transforms section. Optional. Note the square brackets, this is a list
  • role_transforms : See the transforms section. Optional. Note the square brackets, this is a list


These are for supplementing the organisation sections. For example, if you have some users that don't fall under the [[Organisation]] definition, perhaps in another OU or unrelated security group. For roles found through the [[Flat_Role]] section, nested groups are not recursed or created in the database.
It is possible to "pull up" users from nested groups without matching the AD group hierarchy, by using an LDAP_MATCHING_RULE_IN_CHAIN.

means return nested users too but no hierarchy. See MSDN for more details.

Multiple [[Flat_Role]] sections are allowed. Note the double square brackets.

  • name : All user roles found will go into this database group. Required. The [[Flat_Role]] section name can be repeated to gather together roles in the database that are not grouped in the Active Directory.
  • base : In Active Directory / LDAP syntax. e.g.
  • filter : In Active Directory / LDAP syntax. Internally this gets combined with and ObjectClass filters for users. e.g.
  • role_attribute : Optional, defaults to "SAMAccountName". The Active Directory attribute to use for the name of database roles
  • role_transforms : See the transforms section. Optional. Note the square brackets, this is a list


The group and role names returned by the Active Directory can be manipulated using Python 3.6 regular expression re.sub() syntax. Multiple transforms can be provided for a PostgreSQL group or user role. They are applied in order, [[Global_Transforms]] last. The replacement can be any valid re.sub() string expression or one of the functions `upper` or `lower`. Other functions and lambdas are not supported. The input string name (shown as InputString here) is ignored by transforms, it's whatever comes from the group_attribute or role_attribute setting of the pertinent [[Organisation]] or [[Flat_Role]] section.
Transforms are written as a list of triple quoted strings using Python's VERBOSE style and lots of whitespace.


''' re.sub('.+', lower, InputString, count=0, flags=0) ''' ,      # Convert to lowercase
''' re.sub('^#+(?P<named>)', '\g <named>', InputString, count=0, flags=0) ''' , # Use a named pattern
''' re.sub('_+', '_', InputString, count=0, flags=0) ''' ,           # Subst repeated underscores
''' re.sub('^(.+?)(@padnag\.io)', '\g<1>', InputString, count=0, flags=0) ''' ,     # Remove trailing


Any command line options provided override these settings.

  • log_level : In order of decending verbosity, either "DEBUG", "INFO", "WARNING", "CRITICAL" or "ERROR". Default is "INFO"
  • verbose : Shows most SQL statements (excluding some select information queries). Default is False
  • force : Try proceed even if there are errors with the configuration. Default is False
  • test : Do not make any changes to the database, only log intended actions. Default is False
  • poll : Run continuously polling the Active Directory every n seconds. Default is run once and exit


other active directory settings

A number of other settings are available for unusual circumstances. They are documented here for completeness and generally won't be used.

  • version : LDAP protocol version (defaults to 3)
  • authentication : authentication method, can be one of ANONYMOUS, SIMPLE, SASL or NTLM. Defaults to AUTH_ANONYMOUS if user and password are both None else defaults to AUTH_SIMPLE. NTLM uses NTLMv2 authentication. Username must be in the form domain\user.
  • client_strategy : communication strategy used by the client (defaults to SYNC)
  • sasl_mechanism : specify the SASL mechanism to use for AUTH_SASL authentication. Available mechanism are EXTERNAL, DIGEST-MD5 (deprecated by RFCs because insecure) and GSSAPI.
  • sasl_credential : an object specific to the SASL mechanism chosen. Refer to the documentation for each SASL mechanism supported.
  • auto_bind : automatically opens and binds the connection. Can be AUTO_BIND_NONE, AUTO_BIND_NO_TLS, AUTO_BIND_TLS_AFTER_BIND, AUTO_BIND_TLS_BEFORE_BIND.
  • read_only : when True inhibits modify, delete, add and modifyDn (move) operations, defaults to True.
  • check_names : when True attribute names in assertions and filters will be checked against the schema (Server must have schema loaded with the get_info=ALL or get_info=SCHEMA parameter) and search result will be formatted as specified in schema.
  • return_empty_attributes : when a search is performed if an attribute is empty then sets its value to an empty list, default to False
  • auto_range : if a server returns a fixed amount of entries in searches using the range tag (RFCs 3866) setting this value to True let the ldap3 library automatically request all entries with additional searches. The entries are returned as if a single search is performed
  • use_referral_cache : when True referral connections are not immediately closed, and kept in a cache should another request need to contact the same server
  • auto_escape : automatically applies LDAP encoding to filter values, default to True
  • auto_encode : automatically tries to convert from local encoding to UTF8 for well known syntaxes and types, default to True