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
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
- user : The username to connect to the PostgreSQL server with. Only ascii and utf8 user names are
- 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
- 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.
padnag expects that the database administrator will GRANT appropriate privileges to groups, rather than
padnag works with the Postresql convention that roles without the LOGIN privilege are considered groups.
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
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.
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
It is possible to "pull up" users from nested groups without matching the AD group hierarchy, by using an
means return nested users too but no hierarchy.
for more details.
Multiple [[Flat_Role]] sections are allowed. Note the double square brackets.
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,
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
''' 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
other active directory settings
A number of other settings are available for unusual circumstances. They are documented here for
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
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
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
SASL mechanism supported.
- auto_bind : automatically opens and binds the connection. Can be AUTO_BIND_NONE,
- read_only : when True inhibits modify, delete, add and modifyDn (move) operations, defaults to
- check_names : when True attribute names in assertions and filters will be checked against the
(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
empty list, default to False
- auto_range : if a server returns a fixed amount of entries in searches using the range tag (RFCs
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
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
types, default to True