389ds-replication

This helps you set up replication between 389DS server (LDAP server) instances.

ansible-galaxy install lvps.389ds_replication

Requirements

• Ansible version: 2.7 or higher
• OS: CentOS 7

If your version of Ansible does not support the ldap_attrs module, you may be using an outdated version of collections, but you can try version 1.0.x of this role.

Role Variables

Variable	Default	Description	Can be changed	Role
dirsv_replication_role		Role of the server: 'supplier', 'consumer', or 'both' (master). Hub is not supported.	No
dirsrv_server_uri	"ldap://localhost"	URI of the server to configure. Since this runs on the Ansible target, localhost is usually fine. You can set it to ldaps://localhost to use TLS on port 636.		CSB
dirsrv_rootdn	"cn=Directory Manager"	Root DN ("administrator" account username)		CSB
dirsrv_rootdn_password	secret	Password for root DN account		CSB
dirsrv_use_starttls	true	Use StartTLS to connect to the server		CSB
dirsrv_tls_certificate_trusted	true	True if the TLS certificate is from a trusted CA, false if self-signed or from a private CA, unused if TLS is not used		CSB
dirsrv_serverid	default	Server ID aka instance ID. For example, if the server is installed in the dirsrv/slapd-example directory, "example" is the server ID.		CSB
dirsrv_suffix	dc=example,dc=local	Root suffix		CSB
dirsrv_supplier_replica_id	1	Choose a number between 1 and 65534. Don't assign this ID to other servers.	No	SB
dirsrv_consumer_uri	"ldap://consumer.example.com:389/"	Full URI, including port, that the supplier will connect to for replication.	No	SB
dirsrv_replication_user_remote	Replication Manager	User account that exists on the consumer. The supplier will authenticate using this account to perform replication. "Replication Manager" means the account is "cn=Replication Manager,cn=config".	Yes	SB
dirsrv_replication_user_password_remote		Password for the replication user (Replication Manager) account.	Yes	SB
dirsrv_replica_bind_method	"PLAIN"	Bind method used by the supplier to connect to the consumer (SIMPLE, PLAIN, SASL).	Yes	SB
dirsrv_changelog_max_age	"10d"	Sets the value of nsslapd-changelogmaxage.	Yes	SB
dirsrv_replica_attributes_list	"(objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof"	Sets the value of nsds5ReplicatedAttributeList. This is used as the default in documentation examples.	Yes	SB
dirsrv_replica_attributes_list_total	"(objectclass=*) $ EXCLUDE accountUnlockTime"	Sets the value of nsds5ReplicatedAttributeListTotal. This is used as the default in documentation examples.	Yes	SB
dirsrv_replication_user	Replication Manager	User account to create on the consumer. This account will be used by the supplier to authenticate on this server (the consumer). "Replication Manager" means the account will be created at "cn=Replication Manager,cn=config".	Yes	CB
dirsrv_replication_user_password		Password for that account.	Yes	CB
dirsrv_begin_replication_immediately	true	Boolean value that sets nsds5ReplicaEnabled to "on" or "off" in the replication agreement. It's generally safe to leave it as true. If you want to be extra cautious or customize the replication agreement, set this to false.	No	CB
dirsrv_consumer_referral_to_supplier	"ldap://supplier.example.com:389/"	Full LDAP URI, including port. When a client tries to write to a read-only consumer, it will be redirected to this supplier server that can accept writes.	Yes	C

Start by determining whether the server is a supplier, consumer, or both, and set dirsv_role accordingly. Make sure to fill in the related variables based on that.

Some variables cannot be changed after being set. Changing them could result in unexpected results, from "nothing happens" to "the role fails." Other variables like authentication details can be changed as needed.

The following variables have the same names and meanings as in the 389ds-server role, so if you’re using both roles in the same playbook, you can define them just once:

• dirsrv_rootdn
• dirsrv_rootdn_password
• dirsrv_tls_certificate_trusted
• dirsrv_serverid
• dirsrv_suffix

Dependencies

None.

However, this role expects that 389DS is already running; it only configures replication between existing servers.

Example Playbook

More examples, including setting up 389DS from scratch and testing with Vagrant, are available in the 389ds-examples repository.

Please note that replication usually doesn’t start immediately due to differing "replica generations" between servers. This can be corrected with the "replica refresh" procedure. More details on this can be found in section 15.2.5 of the Administration Guide. This procedure needs to be done on suppliers or servers configured as "both."

Essentially, the "replica refresh" procedure forces the database to be pushed from a supplier to a consumer, replacing the previous consumer database. Be careful to not overwrite a production database with an empty database from a newly installed server. Once two servers have identical databases, replication will start automatically.

More explanation can be found in the 389ds-examples repository.

Consumer and Supplier

First, configure the consumer, which will have a read-only copy of the database:

- hosts: consumer
  become: true

  roles:
    -
      role: lvps.389ds_replication
      dirsrv_replica_role: consumer
      dirsrv_suffix: "dc=example,dc=local"
      dirsrv_server_uri: "ldap://localhost"
      dirsrv_rootdn_password: secret
      dirsrv_replication_user_password: foo # This will create cn=Replication Manager,cn=config with this password
      dirsrv_consumer_referral_to_supplier: "ldap://supplier.example.local:389/"

Next, configure the supplier, which will accept writes and send changes to the consumer:

- hosts: supplier
  become: true

  roles:
    -
      role: lvps.389ds_replication
      dirsrv_replica_role: supplier
      dirsrv_suffix: "dc=example,dc=local"
      dirsrv_server_uri: "ldap://localhost"
      dirsrv_rootdn_password: verysecret
      dirsrv_replication_user_password_remote: foo # Will bind with cn=Replication Manager,cn=config and this password on the other server
      dirsrv_consumer_uri: "ldap://consumer.example.local:389/" # The consumer server defined above
      dirsrv_supplier_replica_id: 123

Multi-master setup with two masters

- hosts: mm1
  become: true
  roles:
    -
      role: lvps.389ds_replication
      dirsrv_replica_role: 'both'
      dirsrv_suffix: "dc=example,dc=local"
      dirsrv_server_uri: "ldap://localhost"
      dirsrv_rootdn_password: secret1
      dirsrv_replication_user_password: "aaaaaa"
      dirsrv_replication_user_password_remote: "bbbbbb" # On the other server
      dirsrv_consumer_uri: "ldap://mm2.example.local:389/" # The other server
      dirsrv_supplier_replica_id: 1

- hosts: mm2
  become: true
  roles:
    -
      role: lvps.389ds_replication
      dirsrv_replica_role: 'both'
      dirsrv_suffix: "dc=example,dc=local"
      dirsrv_server_uri: "ldap://localhost"
      dirsrv_rootdn_password: secret2
      dirsrv_replication_user_password: "bbbbbb"
      dirsrv_replication_user_password_remote: "aaaaaa" # On the other server
      dirsrv_consumer_uri: "ldap://mm1.example.local:389/" # The other server
      dirsrv_supplier_replica_id: 2

Known Bugs

If dirsrv_replication_user_password is changed, no change is reported. This is because the password actually changes on every run (Ansible can't determine if the previous hashed password is the same as the new one). A changed_when: false is used to hide this detail.

License

MIT.