Configuration

Meerkat DSA is configured via environment variables. In the future, it will also be configurable via command-line arguments. Environment variables that are specific to Meerkat DSA are namespaced such that they all start with MEERKAT_.

Representation of Values

Meerkat DSA environment variables that represent boolean types will use 1 to represent TRUE and 0 to represent FALSE. This is because digits are more locale-independent. Most cultures would recognize 1 to mean TRUE and 0 to mean FALSE. In general, where boolean environment variables are used, anything other than 1 simply gets interpreted as FALSE.

Meerkat DSA environment variables that represent object identifiers only accept the dot-delimited, numeric representation of the object identifier, such as 2.5.4.3; human-friendly names for these object identifiers are not supported by Meerkat DSA (e.g. id-at-commonName).

Meerkat DSA does not validate environment variable values. If you supply invalid values, you will get unspecified behavior.

Updating Configuration

Meerkat DSA reads the environment variables one time: at start up. This means that, if you want to re-configure your Meerkat DSA instance, you will have to restart Meerkat DSA--you cannot simply modify the environment variables as it runs.

TLS and Signing Options

You will notice a few options that seem similar: in Meerkat DSA, TLS options and signing options (those pertaining to signed arguments, results, or errors) both have a suite of similar configuration options. The TLS options start with MEERKAT_TLS_ and the signing options start with MEERKAT_SIGNING_.

warning

The TLS options do not affect the signing options, and vice versa. That means that, if you want to configure, say, a certificate authorities file for verifying both TLS peers and the signatures on signed arguments, results, and errors, you will have to set both the MEERKAT_TLS_CA_FILE and MEERKAT_SIGNING_CA_FILE environment variables to the same value.

This makes Meerkat really flexible, but it also means that you can inadvertently leave certain security-related settings to their default values, which might not be what you intend!

To further complicate this, there is another set of similar options for signed arguments, results, and errors that only pertains to bind operations. These options start with MEERKAT_SIGNING_BIND_. These environment variables override the values of their equivalent MEERKAT_SIGNING_ environment variables, hence they are referred to as the "bind overrides."

info

The rationale for this design is that bind operations are typically (1) more security-sensitive, since they determine authorization for all future requests, (2) probable targets for brute-force and denial-of-service attacks, and (3) it is usually acceptable to have a somewhat high latency (like three seconds) for a bind operation, but not for subsequent operations. These three significant differences mean that it would be desirable for Meerkat DSA to support a different set of signing-related configuration options that pertain only to the bind operation for a given protocol.

DATABASE_URL

A database URL indicating the SQLite database to which Meerkat DSA must connect for persistent storage. Meerkat DSA assumes full read-write access to this database (not the DBMS, just the database). Read the Prisma Documentation for more information about this URL.

LANG

This is a standard environment variable on Unix-like systems. In Meerkat DSA, this environment variable determines the locale used for log and error messages.

MEERKAT_ADMINISTRATOR_EMAIL

The email that you specify here will be submitted along with telemetry events. This will help Meerkat network administrators reach out to you to offer support, inform you of security vulnerabilities or active attacks, or contact you for other Meerkat DSA-related things.

MEERKAT_ADMINISTRATOR_EMAIL_PUBLIC

If set to 1, the administrator email configured by MEERKAT_ADMINISTRATOR_EMAIL will be exposed in the root DSE as a value of the administratorsAddress attribute.

This can be handy for allowing people and organizations to reach out to you or your organization regarding your DSA, such as for GDPR data deletion requests, DMCA takedown notices, or to inform you of security vulnerabilities. On the other hand, exposing your email address could expose you to phishing, spam, or other security issues attendant to an exposed email address.

MEERKAT_ATTR_CERT_CHAIN_FILE

The filepath of the chain of attribute certificates and public key certificates path to use for outbound strong authentication (when your Meerkat DSA instance binds to another DSA). The attribute certificate path supplied here will populate the attributeCertificationPath field of the strong credentials. Meerkat DSA does not currently use this in any way other than that.

This file MUST contain only attribute certificates and public key certificates, which MUST have the PEM labels ATTRIBUTE CERTIFICATE and CERTIFICATE, respectively. The first and last PEM-encoded objects MUST be attribute certificates, not public key certificates. Any public key certificate is associated with the attribute certificate that follows it. There MUST NOT be multiple public key certificates adjacent to each other, but there MAY be two or more attribute certificates adjacent to each other.

Using A to represent an attribute certificate and P to represent a public key certificate, the following sequences are valid: AAA, APAPA, APAA. The following sequences are invalid: PAA, AAP, APPA, APAPPA.

info

If this strictness seems bizarre, it is because this file is used to populate this data structure (represented in ASN.1):

AttributeCertificationPath ::= SEQUENCE {
  attributeCertificate  AttributeCertificate,
  acPath                SEQUENCE OF ACPathData OPTIONAL,
  ... }

ACPathData ::= SEQUENCE {
  certificate           [0]  Certificate OPTIONAL,
  attributeCertificate  [1]  AttributeCertificate OPTIONAL,
  ... }

Perhaps you can see how a file, constructed as described above, can be used to populate the above data structure. Since this is used for access controls or authentication in some cases (not by Meerkat DSA, but perhaps by another DSA), it is important for there to be no ambiguity as to how a given certificate in the path is to be used.

The certs should be ordered by ascending authority: in other words, the Start Of Authority (SOA) attribute certificate should be closest to the bottom of the file and the end-entity attribute certificate (used directly by Meerkat DSA) should be closest to the top of the file.

The file contents should look like this if you open them up in a text editor:

-----BEGIN ATTRIBUTE CERTIFICATE-----
<Some base64-encoded data starting with "MII">
-----END ATTRIBUTE CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Some base64-encoded data starting with "MII">
-----END CERTIFICATE-----
-----BEGIN ATTRIBUTE CERTIFICATE-----
<Some base64-encoded data starting with "MII">
-----END ATTRIBUTE CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Some base64-encoded data starting with "MII">
-----END CERTIFICATE-----
-----BEGIN ATTRIBUTE CERTIFICATE-----
<Some base64-encoded data starting with "MII">
-----END ATTRIBUTE CERTIFICATE-----

This does not affect the production of signed arguments, results, or errors, nor does it affect TLS.

MEERKAT_ATTR_CERT_DURATION

An integer indicating the number of seconds that an attribute certificate produced via the Attribute Certificate Request extension will last. In other words, the notBeforeTime of the produced attribute certificate will be set to the current time, and the notAfterTime will be set to the current time, plus the number of seconds indicated by this configuration value.

If set to 0 or any non-positive integer value, this feature will be disabled. This defaults to 3600, meaning that attribute certificates will be valid for one hour by default.

MEERKAT_BIND_MIN_SLEEP_MS

This is the amount of time in milliseconds (at minimum) that Meerkat DSA will take to respond to a failed authentication attempt.

note

This exists to stifle timing attacks.

MEERKAT_BIND_SLEEP_RANGE_MS

This is the maximum amount of time in milliseconds that Meerkat DSA will add to the time taken to respond to a failed authentication attempt on top of the minimum as configured by the MEERKAT_BIND_MIN_SLEEP_MS environment variable. The additional time taken in milliseconds is selected uniformly and at random from 0 to this number.

note

This exists to stifle timing attacks.

MEERKAT_BULK_INSERT_MODE

If set to 1, this enables bulk-insert mode, where all access control checks are disabled, some schema checks are disabled, and other validation is disabled. This exists to speed up a bulk insertion of data when a directory is still being set up.

In some experiments, this has made addEntry operations run four times faster!

warning

Enabling this disables access controls. This should NOT be enabled if your directory is accessible over a network to users that should not have unrestricted access.

This SHOULD be turned off and Meerkat DSA SHOULD be restarted as soon as the initial bulk loading is complete.

note

The bulk loading of data does not have to be done in one session. It is possible to load some data, exit bulk insert mode, use the directory normally, and later re-enable bulk insert mode.

MEERKAT_CLIENT_CERT_ENGINE

This is an open-ended string that specifies the client certificate engine that OpenSSL can use to obtain a client certificate.

MEERKAT_CLEARANCE_AUTHORITIES

The filepath of a Trust Anchor List file. See IETF RFC 5914. This file contains the trust anchors whose signed attribute certificates will be seen as valid by Meerkat DSA, and whose clearances (values of the clearance attribute) will be associated with bound users that supply such attribute certificates in their strong authentication parameters.

The trust anchor list shall be encapsulated in a Cryptographic Message Syntax (CMS) message. It does not need to be the top-level object, however. It can be nested within authenticated data, signed data, or digested data objects, as defined in IETF RFC 5652.

This file may also be PEM-encoded. The PEM label must be TRUST ANCHOR LIST, such that the file looks like this when opened in a text editor:

-----BEGIN TRUST ANCHOR LIST-----
<Some base64-encoded data>
-----END TRUST ANCHOR LIST-----

MEERKAT_CHAINING_CHECK_SIG

If not set to 0, Meerkat DSA will verify the digital signatures on received signed DSP results and errors. It is better security for this to remain enabled, but one good reason to disable it is that DAP users might not care about the point-to-point security provided by DSP signing, so long as the chained DAP results are digitally signed and verifiable; for these users, this more stringent security could mean that their DAP requests simply fail in chaining.

MEERKAT_CHAINING_SIGN_REQUESTS

If not set to 0, Meerkat DSA will digitally sign DSP arguments, results, and errors.

MEERKAT_CHAINING_TLS_OPTIONAL

If set to 1, this permits the non-usage of TLS in chaining to other DSAs. In other words, if this is set to 1, this DSA will still chain operations to other DSAs after attempting to use StartTLS, regardless of whether StartTLS succeeds.

If this is enabled, transported operations, data, errors, responses, credentials, etc. are susceptible to inspection by intermediaries, which is a security problem. These operations may not be susceptible to tampering (other than by omission) if cryptographic signing is used.

MEERKAT_DEFAULT_ENTRY_TTL

The default value of the entryTtl operational attribute, if an entry was marked as a dynamic object using the dynamicObject object class, but the entryTtl attribute was not supplied in the attributes of the created entry. This value is a non-negative number of seconds before the entry should expire and disappear.

See IETF RFC 2589.

MEERKAT_ECDH_CURVES

A colon-separated list of ECDH curves to use in ECDH key agreement. Each curve can be an NID or name.

MEERKAT_ENABLE_DAP

If set to 0, this disables Directory Access Protocol (DAP).

MEERKAT_ENABLE_DISP

If set to 1, this enables Directory Information Shadowing Protocol (DISP).

MEERKAT_ENABLE_DOP

If set to 1, this enables Directory Operational Binding Management Protocol (DOP).

MEERKAT_ENABLE_DSP

If set to 1, this enables Directory System Protocol (DSP).

MEERKAT_ENTRIES_PER_SUBORDINATES_PAGE

The number of entries that Meerkat DSA will load into memory at a time when searching for a subordinate.

Meerkat DSA searches in order of descending IDs of entries, with the theory being that larger IDs are entries that have been recently added, and recently added entries are more likely to be requested than older entries. That said, this can generally be set to a fairly low number for optimal results.

MEERKAT_FORBID_ANONYMOUS_BIND

If set to 1, anonymous binds are declined entirely.

MEERKAT_GET_CLEARANCES_FROM_ATTR_CERTS

If not set to 0, Meerkat DSA will associate clearances with a bound user based on the values of the clearance attribute that are present in the presented attribute certificates of the strong authentication argument, provided, of course, that the attribute certificates are valid.

note

Meerkat DSA only supports directly-issued attribute certificates: it cannot currently validate indirectly issued attribute certificates / delegation paths. If a user supplies an attribute certification path that has an acPath parameter, Meerkat DSA will not attempt to validate the attribute certification path. Authentication may still succeed, but any clearances granted to the user via that path will not be applied.

This feature will be supported in some future release.

MEERKAT_GET_CLEARANCES_FROM_DSAIT

If not set to 0, Meerkat DSA will associate clearances with a bound user based on the values of the clearance attribute it has for the bound entry in its local DSAIT.

danger

Unfortunately, clearance is technically defined as a user attribute, even though the directory uses it for making access control decisions. This means that, if you define an access control rule that, for instance, allows a user to edit allUserAttributes, they will be able to modify the clearance attribute. As such, it is important to have access control rules that explicitly forbid editing clearance attribute values.

MEERKAT_GET_CLEARANCES_FROM_PKC

If not set to 0, Meerkat DSA will associate clearances with a bound user based on the values of the clearance attribute that are present in the presented subjectDirectoryAttributes extension of the public key certificate of the strong authentication argument, provided, of course, that the public key certification path is valid.

MEERKAT_HONOR_CIPHER_ORDER

If set to 1, Meerkat DSA will attempt to use its own preferred TLS cipher suites instead of the client's.

MEERKAT_IDM_BUFFER_SIZE

The number of bytes in size of the IDM buffer. This innately limits the size of an IDM frame. This should be large enough to accomodate all well-intentioned requests and responses, but small enough to prohibit nefariously large requests that are intended to exhaust Meerkat DSA's memory.

MEERKAT_IDM_PORT

If set, this names a TCP port on which Meerkat DSA listens locally for IDM traffic.

MEERKAT_IDMS_PORT

If set, this names a TCP port on which Meerkat DSA listens locally for IDMS (IDM over TLS) traffic.

MEERKAT_INIT_JS

If set, this is the filepath to an init script. At startup, Meerkat DSA will load this script and execute the default export or an export named init, if either one exists.

MEERKAT_ITOT_ABORT_TIMEOUT_IN_SECONDS

The timeout after which the OSI session layer will automatically abort the session connection in an ISO Transport Over TCP (ITOT) connection after not receiving a response from the session peer.

MEERKAT_ITOT_ACSE_PASSWORD

Currently unused. Reserved for future support for ACSE-level authentication. This is a fixed password that Meerkat DSA will require from ACSE initiators to establish an ACSE association.

MEERKAT_ITOT_CHAINING

By default, Meerkat DSA will chain requests to other DSAs that operate over ISO Transport Over TCP (ITOT). This can pose some security risks, due to the complexity of the OSI networking protocols. To disable ITOT chaining, set this environment variable to 0.

info

This may be desirable, since ITOT does not provide point-to-point encryption and authentication like TLS. You may need to run ITOT traffic over a VPN or a TLS or SSH tunnel.

MEERKAT_ITOT_MAX_NSDU_SIZE

The largest Network Service Data Unit (NSDU) that an ISO Transport Over TCP (ITOT) can buffer before being aborted or disconnected. In ISO Transport Over TCP (ITOT), this means the maximum size of TPKT packets, which are innately limited to 65531 bytes.

warning

If this value is set too low, clients will not be able to send data to the configured DSA, or they will take an extremely long time to transmit. If this value is set too high, malicious clients will be able to send large payloads that exhaust memory and/or compute on the DSA.

This option should almost always be left alone, since TPKTs are innately limited to 65531 bytes in size.

MEERKAT_ITOT_MAX_TPDU_SIZE

The largest Transport Protocol Data Unit (TPDU) that an ISO Transport Over TCP (ITOT) can transmit before being aborted or disconnected.

warning

This option should almost always be left alone, since the ITU X.224 OSI transport protocol used by the ITOT stack is limited in size by the maximum NSDU size, which for ITOT, is 65531 bytes (the size limit of a TPKT).

MEERKAT_ITOT_MAX_TSDU_SIZE

The largest Transport Service Data Unit (TSDU) that an ISO Transport Over TCP (ITOT) can buffer before being aborted or disconnected. This option defaults to a sensible value and should generally not be changed unless there is a problem that warrants it.

warning

MEERKAT_ITOT_MAX_SSDU_SIZE

The largest Session Service Data Unit (SSDU) that an ISO Transport Over TCP (ITOT) can buffer before being aborted or disconnected. This option defaults to a sensible value and should generally not be changed unless there is a problem that warrants it.

warning

MEERKAT_ITOT_MAX_PRESENTATION_CONTEXTS

The maximum number of presentation contexts Meerkat DSA will tolerate in an ITU X.226 OSI Presentation association when using ISO Transport Over TCP (ITOT). This defaults to 10. If more than this many presentation contexts are proposed by a presentation peer, the presentation association will be refused.

warning

This option exists to prevent denial-of-service attacks in which a large number of presentation contexts are presented.

MEERKAT_ITOT_PORT

The TCP port Meerkat DSA will listen on for ISO Transport Over TCP (ITOT) traffic, as described in IETF RFC 1006. If this is unset, Meerkat DSA will not listen for ITOT traffic.

Many legacy X.500 directory clients support ITOT.

warning

ISO Transport Over TCP (ITOT) does NOT provide point-to-point encryption or peer authentication like TLS does. This means that data sent over ITOT will be sent in clear text, meaning that ISPs, routers, and others will be able to snoop on your directory traffic. If you expect to send traffic over untrusted networks, be sure to use VPNs, TLS tunnels, or SSH tunnels to encrypt and authenticate data transmitted over the network.

Meerkat DSA does support ITOT over TLS via the MEERKAT_ITOTS_PORT configuration option, but most legacy clients will not support this.

To add to this, ISO Transport Over TCP (ITOT) is very complicated, because it entails another much more complicated networking stack operating over TCP/IP. Because of its gigantic attack surface, it is strongly encouraged that you leave this disabled unless you have a specific known need to support ITOT clients. IDM transport should always be preferred.

MEERKAT_ITOTS_PORT

The TCP port Meerkat DSA will listen on for ISO Transport Over TCP (ITOT) traffic, as described in IETF RFC 1006, but encapsulated within TLS. If this is unset, Meerkat DSA will not listen for ITOTS traffic.

Many legacy X.500 directory clients support ITOT, but no known legacy clients support ITOT over TLS.

warning

ISO Transport Over TCP (ITOT) is very complicated, because it entails another much more complicated networking stack operating over TCP/IP. Because of its gigantic attack surface, it is strongly encouraged that you leave this disabled unless you have a specific known need to support ITOT clients. IDM transport should always be preferred, and IDMS even moreso.

MEERKAT_LABELLING_AUTHORITIES

The filepath of the Trust Anchor List file. See IETF RFC 5914. This file contains information on the trust anchors to be used for verifying the security labels on attribute values that are applied using the attributeValueSecurityLabelContext context. This is used for implementing Rule-Based Access Control (RBAC). In other words, when the signatures on security labels on attribute values are checked, these trust anchors provide the public keys against which these security labels are verified and the names of the issuers.

This file may also be PEM-encoded. The PEM label must be TRUST ANCHOR LIST, such that the file looks like this when opened in a text editor:

-----BEGIN TRUST ANCHOR LIST-----
<Some base64-encoded data>
-----END TRUST ANCHOR LIST-----

MEERKAT_LCR_PARALLELISM

If greater than 1, Meerkat DSA will make parallel requests in the List Continuation Reference (LCR) procedure defined in ITU Recommendation X.518 (2019), Section 20.4.2. This number determines the number of simultaneous chained list operations that Meerkat DSA will issue at a given time. If set to 0, 1, or some other non-sense number or non-number, Meerkat DSA will simply run all chained subrequests in series. More parallelism generally means that the distributed list operation completes faster.

If this value is set too high, malicious users could issue requests that propagate into so many outbound chained requests that the responses act as a Distributed Denial-of-Service (DDoS).

Despite this setting, Meerkat DSA will not use parallel requests unless the operation has priority set to high.

MEERKAT_LDAP_BUFFER_SIZE

The number of bytes in size of the LDAP buffer. This innately limits the size of an LDAP message. This should be large enough to accomodate all well-intentioned requests and responses, but small enough to prohibit nefariously large requests that are intended to exhaust Meerkat DSA's memory.

MEERKAT_LDAP_PORT

If set, this names a TCP port on which Meerkat DSA listens locally for LDAP traffic.

MEERKAT_LDAPS_PORT

If set, this names a TCP port on which Meerkat DSA listens locally for LDAPS (LDAP over TLS) traffic.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_SSL3

The number of localQualifier "points" that Meerkat DSA grants to a client for using SSLv3 to secure their traffic.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_STARTTLS

The number of localQualifier "points" that Meerkat DSA grants to a client for using StartTLS to secure their traffic.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS

The number of localQualifier "points" that Meerkat DSA grants to a client for using any version of Transport Layer Security (TLS) to secure their traffic.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS_1_0

The number of localQualifier "points" that Meerkat DSA grants to a client for using TLS version 1.0 to secure their traffic. These points are added on top of the points granted via the MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS environment variable.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS_1_1

The number of localQualifier "points" that Meerkat DSA grants to a client for using TLS version 1.1 to secure their traffic. These points are added on top of the points granted via the MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS environment variable.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS_1_2

The number of localQualifier "points" that Meerkat DSA grants to a client for using TLS version 1.2 to secure their traffic. These points are added on top of the points granted via the MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS environment variable.

MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS_1_3

The number of localQualifier "points" that Meerkat DSA grants to a client for using TLS version 1.3 to secure their traffic. These points are added on top of the points granted via the MEERKAT_LOCAL_QUALIFIER_POINTS_FOR_USING_TLS environment variable.

MEERKAT_LOG_BOUND_DN

If set to 1, Meerkat DSA will log the distinguished names of bound clients, if they have authenticated using a mechanism that relates to an entry in the DIT, such as simple authentication (as opposed to anonymous access).

tip

It may be desirable to enable this for debugging integrations or for identifying brute force attacks.

warning

It might NOT be desirable to enable this because doing so could have legal implications. Meerkat DSA logs IP addresses. If Meerkat DSA also logs distinguished names, and if distinguished names can readily be related to a real person (e.g. C=US,ST=FL,CN=John Doe), it could be argued that the logs are storing Personally-Identifiable Information (PII), because the real person's IP address is stored in the logs along with their identity.

Consult with an attorney on the legality of using this. It may be safer to only enable this in corporate or home environments where no such right to privacy may exist.

MEERKAT_LOG_FILE

The filepath of the Meerkat DSA's log file. If set, Meerkat DSA will log to this file.

MEERKAT_LOG_FILE_MAX_FILES

The maximum number of log files Meerkat DSA will produce before it deletes the oldest one to make room for the newest one.

This has no effect if the MEERKAT_LOG_FILE environment variable is not set.

MEERKAT_LOG_FILE_MAX_SIZE

The maximum size (in bytes) of a log file before Meerkat DSA will start a new log file.

This has no effect if the MEERKAT_LOG_FILE environment variable is not set.

MEERKAT_LOG_JSON

Setting this to 1 will cause log messages to be logged in JSON format instead of the default plain / human-friendly format. This can be useful if your logs are exported to an SIEM like LogRhythm, or an APM like DataDog or ElasticSearch.

MEERKAT_LOG_LEVEL

This controls the logging level. Can be one of debug, info, warn, or error. Log messages at or above the specified level will get logged; all others will be silently discarded.

MEERKAT_LOG_TIMESTAMP

If set to 0 disables the timestamp field of the log output, if the logs are printed to the console; if set to any other value or unset, timestamps will be printed to the console, unless Meerkat DSA believes it is running as a SystemD service, in which case, this will need to be explicitly set to 1 to enable timestamps. The rationale for this behavior is that Journald keeps its own timestamps, so any that Meerkat prints are duplicated.

MEERKAT_LOG_SYSLOG

If set to 1, Meerkat DSA will log to the syslog facility. This does not require any further configuration if you are logging to localhost over UDP port 514. The application name will be meerkat by default.

This is not mutually exclusive with console logging or file logging. You can do all three.

note

Meerkat DSA was only going to support console or file logging since those are the universal and standard--if not the preferred--ways to log things in modern apps, but support for Syslog required only a tiny additional dependency (with no transitive dependencies) to work, so it was an obvious choice. In contrast, something like Windows Event Viewer, Sentry, OpenTelemetry, or AWS Cloudwatch logging would have required huge dependencies and those can't be tested as easily.

MEERKAT_LOG_SYSLOG_APP_NAME

The application name in Syslog, when Syslog logging is enabled. By default, this is meerkat.

MEERKAT_LOG_SYSLOG_HOST

The host to which Syslog logs will be sent. This is localhost by default. This has no effect if Syslog logging is not enabled.

MEERKAT_LOG_SYSLOG_PORT

The TCP or UDP port number to which Syslog logs will be sent. This is 514 by default. This has no effect if Syslog logging is not enabled.

MEERKAT_LOG_SYSLOG_TCP

If set to 1, your Syslog logs will be transmitted over TCP instead of UDP. This has no effect if Syslog logging is not enabled.

TCP is more reliable, and your logs will arrive in order and without duplicates, but it comes at a performance cost.

MEERKAT_LOG_SYSLOG_TIMEOUT

Decimal number indicating the number of milliseconds before the connection times out. This applies to both TCP and UDP.

MEERKAT_LOG_SYSLOG_TLS

If set to 1, Syslog will work use Transport Layer Security (TLS). This has no effect if Syslog logging is not enabled.

caution

If you do not use this, your Syslog logs will be transmitted without encryption or integrity. Meerkat DSA logs can contain sensitive data, so you might want to ensure that this is set unless you are only logging to localhost.

MEERKAT_LOG_SYSLOG_REJECT_UNAUTH

If set to 1, and if Syslog over TLS is enabled, Meerkat DSA's Syslog logging will not verify the logging sink's X.509 public key certificate ("TLS certificate").

danger

Setting this to 1 means that malicious hosts could impersonate your log sink and receive your logs.

MEERKAT_LOG_SYSLOG_CA

Contains a file path to a file containing one or more concatenated PEM-encoded trust anchor X.509 public key certificates.

This has no effect if Syslog logging is not enabled, or if Syslog over TLS is not enabled,

MEERKAT_LOG_SYSTEMD_LEVEL_PREFIX

If set to 1, Meerkat DSA will use an alternative log message format that is suitable for consumption by journald (part of systemd). This will allow journald to attribute log levels to logged messages instead of treating every log message as info-level. This has no effect if Meerkat DSA isn't running as a systemd service.

MEERKAT_LOG_TLS_SECRETS

Whether to log TLS master and pre-master secrets to the log so that TLS traffic can be decrypted. This is used for debugging purposes.

The logging format is the same as an individual line of the SSLKEYLOG format described here.

warning

Do not enable this unless:

You are debugging.
You need to debug TLS-encrypted traffic.
The traffic being decrypted is not sensitive at all.

For a more secure alternative, consider FIXME

MEERKAT_LOOKUP_UNCERT_STRONG_AUTH

If set to 1, a strong authentication attempt that does not provide a certification path, but which does provide a distinguished name in the name field of the strong credentials, will result in Meerkat DSA reading the DSE of having the distinguished name name if it is present locally, and, if it has object class pkiCertPath and has attribute values of type pkiPath, these values will be used as certification paths, and each will be tried until a certification path is found that verifies the bind token. If no such vindicating certification path is found, Meerkat DSA rejects the authentication attempt. It is strongly preferred for clients to supply a certification path in the bind argument so that this lookup need not happen.

warning

Enabling this opens up your Meerkat DSA instance to denial-of-service attacks. A particular lookup can be computationally expensive, and since a given user may have an unlimited number of pkiPath attribute values, this could result in a potentially unlimited number of certification path validations that must be done before your DSA accepts or rejects a strong authentication attempt.

It is recommended to keep this disabled, unless the certification path itself is highly sensitive and should not be sent over the network, and the potential threat of denial-of-service is controlled for.

Enabling this can be useful if your users must not transmit their certification path over the network.

MEERKAT_MAX_CONCURRENT_OPERATIONS_PER_CONNECTION

The number of maximum concurrent operations per connection. If a connection attempts more operations than this permits, they will be automatically rejected.

MEERKAT_MAX_CONNECTIONS

The absolute maximum number of connections globally. Connections opened after this maximum has been reached will be automatically closed.

MEERKAT_MAX_CONNECTIONS_PER_ADDRESS

The absolute maximum number of connections permitted from a given address. Connections by a given address opened after this maximum has been reached will be automatically closed. This is important for the prevention of Slow Loris attacks.

MEERKAT_MAX_IDM_PDU_SIZE

The maximum size, in bytes, of an IDM PDU. IDM PDUs larger than this will be rejected automatically, possibly before they are even fully read.

MEERKAT_MAX_IDM_SEGMENTS

The maximum number of IDM segments into which an IDM client may split an IDM PDU. This is important for preventing a denial of service. Without this limit, nefarious IDM clients may submit an infinitely-large number of IDM segments and exhaust memory.

MEERKAT_MAX_PRE_BIND_REQUESTS

ITU Recommendation X.519 permits clients to submit requests after the bind request has been submitted, but before the bind response or error has been received. Meerkat DSA can handle this, but it is important to limit the number of pre-bind requests so that unauthenticated users cannot flood the queue with an unlimited number of pending requests and exhaust memory.

It is not a security vulnerability for this to be a number greater than zero, but it should be a low number. It should probably not be higher than 10.

MEERKAT_MAX_RELAXATIONS

The maximum number of times that a search will be evaluated again with different matching to produce a desired number of results. This applies to both relaxations and tightenings. This defaults to 3, if unset. You generally do not want to make this much larger than three, otherwise nefarious users could use malicious search requests with a huge number of relaxations or tightenings to overwhelm your DSA with bogus search re-evaluations.

MEERKAT_MIN_AUTH_LEVEL_FOR_CHAINING

The integer representation of the minimum authentication level required for Meerkat DSA to chain requests to other DSAs. This is a security feature to prevent unauthenticated (and therefore, unaccountable) users from spamming the distributed directory with cumbersome (if not malicious) requests.

This is important, because chaining can have the effect of making a request "fan-out" to multiple DSAs. A nefarious request may multiply exponentially without this check in place.

This defaults to 1, which corresponds to simple authentication, meaning that, to utilize chaining, a user must have authenticated using simple authentication or something stronger.

Possible values are:

0 for no authentication / anonymous.
1 for simple authentication, which corresponds to any authentication mechanism using a password, regardless of whether that password is presented in plain text or with some form of hashing or encryption.
2 for strong authentication, which corresponds to Strong or SPKM authentication.

MEERKAT_MIN_AUTH_LEVEL_FOR_DISP

The integer representation of the minimum authentication level required for Meerkat DSA to accept DISP requests.

This defaults to 1, which corresponds to simple authentication, meaning that, to use DISP, a DSA must have authenticated using simple authentication or something stronger.

Possible values are:

0 for no authentication / anonymous.
1 for simple authentication, which corresponds to any authentication mechanism using a password, regardless of whether that password is presented in plain text or with some form of hashing or encryption.
2 for strong authentication, which corresponds to Strong or SPKM authentication.

MEERKAT_MIN_AUTH_LEVEL_FOR_OB

The integer representation of the minimum authentication level required for Meerkat DSA to accept DOP requests.

This defaults to 1, which corresponds to simple authentication, meaning that, to use DOP, a DSA must have authenticated using simple authentication or something stronger.

Possible values are:

0 for no authentication / anonymous.
1 for simple authentication, which corresponds to any authentication mechanism using a password, regardless of whether that password is presented in plain text or with some form of hashing or encryption.
2 for strong authentication, which corresponds to Strong or SPKM authentication.

MEERKAT_MIN_AUTH_LOCAL_QUALIFIER_FOR_CHAINING

The minimum localQualifier "points" required (on top of the minimum authentication level) for Meerkat DSA to chain requests to other DSAs. If the minimum authentication level--as configured by the MEERKAT_MIN_AUTH_LEVEL_FOR_CHAINING environment variable--is exceeded, this does not matter.

This is important, because chaining can have the effect of making a request "fan-out" to multiple DSAs. A nefarious request may multiply exponentially without this check in place.

MEERKAT_MIN_AUTH_LOCAL_QUALIFIER_FOR_DISP

The minimum localQualifier "points" required (on top of the minimum authentication level) for Meerkat DSA to accept DISP requests. If the minimum authentication level--as configured by the MEERKAT_MIN_AUTH_LEVEL_FOR_DISP environment variable--is exceeded, this does not matter.

MEERKAT_MIN_AUTH_LOCAL_QUALIFIER_FOR_OB

The minimum localQualifier "points" required (on top of the minimum authentication level) for Meerkat DSA to accept DOP requests. If the minimum authentication level--as configured by the MEERKAT_MIN_AUTH_LEVEL_FOR_OB environment variable--is exceeded, this does not matter.

MEERKAT_MIN_TRANSFER_SPEED_BYTES_PER_MINUTE

This specifies the minimum number of bytes a TCP connection is expected to transfer within one minute. If the average number of bytes per minute falls below this number, the TCP socket is closed.

note

This is important for the prevention of Slow Loris attacks.

MEERKAT_MRU_VERTEX_TTL

The number of seconds (the "time to live" or "TTL") during which the most recently used vertex remains cached in memory along with the connection.

Meerkat DSA caches the most recently used (MRU) vertex in memory along with the association. This was implemented because users typically "statefully" navigate the directory, like folders in a file system--they don't bounce around the DIT randomly. Since there is a strong chance that the next operation a user performs will be the last-used vertex or one of its subordinates, caching the most recently used vertex can dramatically reduce the number of database queries and make many operations extremely fast.

However, these cached vertices MUST eventually expire, otherwise, users could have out-of-date information or perform operations on entries to which they have had their permissions revoked since the last operation.

warning

To be clear, use of the most recent vertex bypasses access controls, regarding Browse and ReturnDN permissions. It is assumed that, if the user had Browse and ReturnDN permissions on the entry, say, three seconds ago, they still do. This is a small abridgement of access controls made for the sake of extreme performance gains.

Unless you are frequently modifying access controls, virtually any number should be fine. The higher a higher cache TTL will give you better performance, but slower-to-react access controls and potential for data inconsistency.

Note that the cached vertex lifespan is renewed on every operation, so if a user browses an entry, then you define access controls that prohibit that user from discovering that entry, the user can still discover it indefinitely for as long as they:

Remain associated
Periodically rejuvenate this cache by performing an operation with this entry
Do not perform any operation with any other entry on the same association

To disable this behavior entirely, set this to 0. Otherwise, this defaults to 300 (five minutes).

The MRU vertex is cached whenever a removeEntry or modifyDN operation is performed, since these can invalidate the cache.

MEERKAT_MUTUAL_AUTH_OPTIONAL

If set to 1, mutual authentication becomes optional when Meerkat DSA binds to other DSAs. If the remote DSA responds with a bind result containing no credentials, the DSA will be trusted by fiat. If the remote DSA responds with a bind result containing credentials, these credentials will be checked for validity, but if they are invalid, the association will not be aborted as it otherwise would.

MEERKAT_MY_ACCESS_POINT_NSAPS

Whitespace-separated NSAP URLs that locate this DSA. This is important for enabling other DSAs to chain requests to this DSA. These NSAP URLs are used to populate the myAccessPoint attribute in the Root DSE.

warning

Do NOT include usernames and passwords in any URL (e.g. https://username:password@example.com) you supply with this environment variable. These URLs will be disclosed freely to all users regardless of authentication or access control, so nothing sensitive should be included in them at all.

MEERKAT_NO_COLOR

If set to 1, Meerkat DSA will not use colors in log outputs.

MEERKAT_NO_CONSOLE

If set to 1, Meerkat DSA will not log to the console.

MEERKAT_OB_AUTO_ACCEPT

If set to 1, Meerkat DSA shall accept ALL requested operational bindings.

danger

Your DSA is INSECURE if this is enabled. It means that your DSA will automatically agree to:

Replicate an arbitrarily large amount of data
Defer to any other DSA for chained operations
Create any requested subtree within the DIT

MEERKAT_OPEN_TOP_LEVEL

If set to 1, Meerkat DSA will not apply any access controls to adding new entries to the top level. Note that this does not negate access controls for already-existing first-level DSEs.

warning

This option being enabled reduces security of the system, because users can arbitarily create new entries at the top level. Only enable this option if you would not mind any connected user creating an arbitrarily large number of top level entries.

info

This is useful for testing purposes, because you can create "test subtrees" within a single DSA for the purposes of testing functionality in isolation from other tests.

MEERKAT_PRINCIPLED_SERVICE_ADMIN

The X.500 specifications mandate that searches are not to recurse into other service administrative areas, but this means that service admin points will not be discoverable at all via search operations. Since LDAP has no list operation, it also means that LDAP users will never be able to find any entry that lies in a different service administrative area (except by "guessing" that it exists).

For example, if C=US,ST=FL is a service admin point, and a user performs a one-level search at C=US, the ST=FL subordinate will be hidden from the results entirely. The user will have no way of even finding ST=FL except for performing a list operation and noticing that this subordinate differs from the results obtained by a one-level search (since list is not governed by service administration).

Meerkat DSA deviates from the specification by recursing one entry into other service administrative areas so that the DIT is traversible to users. Continuing on the previous example, this means that, if a user performs a one-level search at C=US, the ST=FL subordinate will be returned. If a subtree search at C=US is performed, ST=FL will be returned as well, but none of its subordinates (the latter of which is technically correct behavior).

This option, if set to 1, disables this deviation. Meerkat DSA will thereby adhere strictly to the specifications and service admin points will be hidden from search results.

note

The above issue will be reported to the ITU working group that authors the X.500 specifications, so it may be resolved in a future version.

MEERKAT_PRIVATE_KEY_ENGINE

This is an open-ended string that specifies the private key engine that OpenSSL can use to obtain a private key.

MEERKAT_PROHIBIT_CHAINING

If set to 1, Meerkat DSA will not chain any requests. If you expect to operate your DSA instance in isolation from all other DSAs, it is recommended to enable this (meaning that chaining would be disabled).

MEERKAT_REMOTE_PWD_TIME_LIMIT

The number of seconds before the remote password checking procedure (described in ITU Recommendation X.511 (2019), Section 10.2.7) times out. If this is set to 0, this procedure is never used.

This defaults to 0, meaning that this procedure is disabled by default.

warning

It is strongly recommended to avoid enabling this feature unless the names of most or all entries in your DSA are NOT a secret. That is because a remote password assertion will introduce significant latency into the bind operation, which can be used to oracle which entries exist.

In other words, a nefarious user could guess common relative distinguished names, such as CN=John Smith, and see if the bind response (or error) for that entry returns significantly faster than a known non-existent entry (the nefarious user could just guess a random RDN, such as CN=qtuihqjoitjoqpoj1 for this purpose) to determine whether CN=John Smith exists locally in that DSA, even if this nefarious user does not have the proper permissions to discover that entry.

If this feature is enabled, it is recommended that you increase the values of the MEERKAT_BIND_MIN_SLEEP_MS and MEERKAT_BIND_SLEEP_RANGE_MS configuration options, which will help to obscure when asserted credentials are chained to a remote DSA.

In addition to the above concern, enabling this feature can slow down bind operations. If you are under regular brute-force attacks or are generally under resource strain, you may want to leave this feature disabled.

MEERKAT_REQUEST_CROSS_REFERENCES

If set to 1, Meerkat DSA will request cross references from other DSAs, and, pending validation, will apply them to the local DSAIT, which may make the routing of requests faster.

warning

This is off by default because there are some security risks of accepting cross references. Downstream DSAs may attempt to lie in an attempt to claim ownership of contexts that they do not own, or point to DSAs that serve an entirely separate DIT.

See ITU Recommendation X.501 (2019), Annex S, section S.2.

You should NOT turn this on unless you can trust all DSAs involved in your DSAIT to be trustworthy and competent.

MEERKAT_RETURN_CROSS_REFERENCES

If set to 1, Meerkat DSA will return cross references to context prefixes it owns and that it encounters during the process of name resolution within the DSAIT. Note that this does not--nor does any other option--determine whether the local DSA returns cross references returned from other DSAs. The local DSA will back-propagate cross references it receives to previous DSAs.

note

This is off by default because the use of cross references can disclose important secret information, such as the location or network addresses of other DSAs that are supposed to remain undisclosed.

You should NOT turn this on unless you can trust all DSAs involved in your DSAIT to be correctly implemented and you know that all knowledge references in your DSAIT are not secret.

MEERKAT_REVEAL_USER_PWD

If set to 1, Meerkat DSA will return non-zero-length OCTET STRINGs in the encryptedString field of the userPwd attribute's value. Meerkat DSA does not store passwords unencrypted.

For reference, this is the userPwd attribute's ASN.1 specification:

userPwd	ATTRIBUTE ::= {
  WITH SYNTAX              UserPwd
  EQUALITY MATCHING RULE   userPwdMatch
  SINGLE VALUE             TRUE
  LDAP-SYNTAX              userPwdDescription.&id
  LDAP-NAME                {"userPwd"}
  ID                       id-at-userPwd }

UserPwd ::= CHOICE {
  clear                 UTF8String,
  encrypted             SEQUENCE {
    algorithmIdentifier   AlgorithmIdentifier{{SupportedAlgorithms}},
    encryptedString       OCTET STRING,
    ...},
  ...}

warning

Meerkat DSA does not do this by default because it could expose your users to offline dictionary attacks, which is an exponentially greater threat than automated brute-force password guessing, because it can be done an order of magnitude faster.

If you enable this feature, attackers that have permissions to view values of the userPwd attribute can download / save those values and attempt rapid, repeated guesses of the hashed password without the rate-limiting that Meerkat DSA imposes.

It is recommended that you keep this disabled unless you know you need it for some reason. If enabled, you should configure access controls to prevent unauthorized users from viewing values of the userPwd attribute.

MEERKAT_SCR_PARALLELISM

If greater than 1, Meerkat DSA will make parallel requests in the Search Continuation Reference (SCR) procedure defined in ITU Recommendation X.518 (2019), Section 20.4.3. This number determines the number of simultaneous chained search operations that Meerkat DSA will issue at a given time. If set to 0, 1, or some other non-sense number or non-number, Meerkat DSA will simply run all chained subrequests in series. More parallelism generally means that the distributed search operation completes faster.

If this value is set too high, malicious users could issue requests that propagate into so many outbound chained requests that the responses act as a Distributed Denial-of-Service (DDoS).

Despite this setting, Meerkat DSA will not use parallel requests unless the operation has priority set to high.