Apache Directory Ds

Prerequisites

You need:

• An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.
• A VM size of Standard_B2s (2 vCPU / 4 GiB RAM) as a good starting point.
• A network security group (NSG) rule that allows inbound 22/tcp from your management network. No inbound application ports are needed, because you reach ApacheDS over the SSH tunnel.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal and choose Create a resource. Search the Marketplace for Apache Directory Server by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) only. Then choose Review + create, then Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:apache-directory-ds-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name apacheds \
  --image sac1647283583153:apache-directory-ds-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm ApacheDS is installed and running

ApacheDS runs as the apacheds.service systemd unit and binds LDAP and LDAPS to loopback only. Check the Java version, the service state and the listeners:

java -version systemctl is-active apacheds ss -tln | grep -E '10389|10636'

The output shows OpenJDK 17, active, and listeners on 127.0.0.1 for 10389 and 10636:

openjdk version "17.0.19" 2026-04-21 active LISTEN 0 50 [::ffff:127.0.0.1]:10636 *:* LISTEN 0 50 [::ffff:127.0.0.1]:10389 *:*

Step 5 - Retrieve your per-VM admin password

Each VM generates its own ApacheDS administrator password on first boot and writes it to a root-only credentials file:

sudo cat /root/apacheds-credentials.txt

The file contains APACHEDS_ADMIN_PASSWORD, the bind DN uid=admin,ou=system, the demo base DN dc=sac,dc=local, the loopback host and ports, and the SSH tunnel instructions. Store the password in your secrets manager.

In the commands below, <APACHEDS_ADMIN_PASSWORD> stands for the value of APACHEDS_ADMIN_PASSWORD.

Step 6 - Run an anonymous rootDSE query

ApacheDS permits an anonymous read of the rootDSE, so clients can discover server capabilities and naming contexts without credentials:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -s base -b '' namingContexts supportedLDAPVersion

namingContexts: ou=system namingContexts: dc=sac,dc=local supportedLDAPVersion: 3

dc=sac,dc=local is the seeded demo partition.

Step 7 - Search the seeded demo directory tree

Bind as the administrator and list the seeded directory tree under dc=sac,dc=local:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' \
  -b 'dc=sac,dc=local' '(objectclass=*)' dn

dn: dc=sac,dc=local dn: ou=people,dc=sac,dc=local dn: ou=groups,dc=sac,dc=local dn: uid=alice,ou=people,dc=sac,dc=local dn: uid=bob,ou=people,dc=sac,dc=local dn: cn=engineers,ou=groups,dc=sac,dc=local

Step 8 - Authenticated search for user attributes

Filter for the seeded inetOrgPerson users and return selected attributes. This proves the authenticated bind and the directory data:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' \
  -b 'dc=sac,dc=local' '(objectclass=inetOrgPerson)' cn sn mail uid

dn: uid=alice,ou=people,dc=sac,dc=local mail: alice@sac.local sn: Anderson cn: Alice Anderson uid: alice dn: uid=bob,ou=people,dc=sac,dc=local mail: bob@sac.local sn: Brown cn: Bob Brown uid: bob

Step 9 - Add your own entry

Add a new user with ldapadd. Create an LDIF file, then import it:

cat > /tmp/carol.ldif <<'LDIF' dn: uid=carol,ou=people,dc=sac,dc=local objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: person objectClass: top cn: Carol Carter sn: Carter uid: carol mail: carol@sac.local LDIF ldapadd -x -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' -f /tmp/carol.ldif

adding new entry "uid=carol,ou=people,dc=sac,dc=local"

Search for it, then remove it with ldapdelete:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' \
  -b 'dc=sac,dc=local' '(uid=carol)' cn mail ldapdelete -x -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' \
  'uid=carol,ou=people,dc=sac,dc=local'

Step 10 - Confirm authentication is enforced

ApacheDS rejects a wrong administrator password with LDAP result code 49 (Invalid credentials), so the directory is never readable with a bad credential. Run ldapsearch with a deliberately wrong password. This command is expected to fail:

$ ldapsearch -x -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w WRONG-PASSWORD \
  -b 'dc=sac,dc=local' '(objectclass=*)' ldap_bind: Invalid credentials (49) additional info: INVALID_CREDENTIALS: Bind failed: ERR_229 Cannot authenticate user uid=admin,ou=system

The bind fails immediately with result: 49. This confirms that authentication is enforced before any directory data is returned.

Step 11 - Connect remotely over an SSH tunnel

ApacheDS listens on 127.0.0.1:10389 (LDAP) and 127.0.0.1:10636 (LDAPS) only. It is not exposed publicly, which is the secure default. To reach it from your workstation, open an SSH tunnel and point a local LDAP client at localhost:10389:

# On your workstation:
ssh -L 10389:127.0.0.1:10389 azureuser@<vm-public-ip>
# In another terminal, with a local ldap-utils install: ldapsearch -x -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -w '<APACHEDS_ADMIN_PASSWORD>' \
  -b 'dc=sac,dc=local' '(objectclass=*)'

For remote access without a tunnel, bind ApacheDS to a private NIC and protect it with TLS through the LDAPS listener on 10636. Never expose the LDAP port to the internet without transport encryption and access controls.

Maintenance

• Persistence. The directory instance (JDBM partitions, configuration, logs and working directory) lives on the dedicated data disk at /var/lib/apacheds. The directory survives reboots, and you can resize the volume independently.
• Admin password. Rotate it with an ldapmodify that replaces userPassword on uid=admin,ou=system. You can also update the value in /root/apacheds-credentials.txt for reference. The per-VM password is generated once, at first boot.
• Service control. Run sudo systemctl restart apacheds to restart the directory. Run journalctl -u apacheds to read the logs.
• Security patches. unattended-upgrades stays enabled, so the OS keeps receiving security updates automatically.
• Compatibility. ApacheDS is a standard LDAP v3 server. Existing LDAP clients, libraries and tooling work unchanged against 10389 and 10636.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Apache Directory Server, ApacheDS and the Apache feather logo are trademarks of the Apache Software Foundation. SecureAnyCloud provides this image. It is not affiliated with or endorsed by the Apache Software Foundation.

Deploy on Azure

Launch Apache Directory Server on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Prerequisites

Before you deploy this image, you need:

• An Amazon Web Services account where you can launch EC2 instances.
• IAM permissions to launch instances, create security groups and subscribe to AWS Marketplace products.
• An EC2 key pair in the target Region for SSH access to the instance.
• A VPC and subnet in the target Region, with a security group that allows inbound port 22 from your management network only.
• An SSH client on your workstation. An LDAP browser is useful but not required.

You do not need to open ports 10389 or 10636 in the security group. You reach the directory through the SSH tunnel described later in this guide.

Launching from the AWS Marketplace

• Open the product page in AWS Marketplace and choose Continue to Subscribe.
• Accept the terms, then choose Continue to Configuration.
• Select the software version and the Region you want to deploy into, then choose Continue to Launch.
• Choose Launch through EC2 for full control of networking and storage.
• Pick an instance type. m5.large is the recommended minimum. Scale up as your entry count and query concurrency grow, because ApacheDS is a JVM service and benefits from additional memory.
• Select your VPC, subnet and key pair.
• Attach a security group that allows inbound TCP 22 from your management network. Do not add rules for 10389 or 10636.
• Launch, and wait for the instance to reach the 2/2 checks passed state.

Launching with the AWS CLI

Substitute your own AMI ID, key pair, security group and subnet:

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <your-sg-id> \
  --subnet-id <your-subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=apacheds}]'

Connecting to your instance

Connect over SSH on port 22 as the default login user for the operating system variant you launched:

OS variant SSH login user

Ubuntu 24.04 LTS ubuntu

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

First boot takes a few moments to generate and apply the administrator password. If the credentials file does not yet show a generated password, wait a few seconds and read it again.

Verifying the directory is running

Confirm that the service is active and that both listeners are bound to loopback only:

systemctl is-active apacheds.service
systemctl status apacheds.service --no-pager | head -4

Real output from a deployed instance:

active ● apacheds.service - Apache Directory Server (ApacheDS 2.0.0.AM27) Loaded: loaded (/etc/systemd/system/apacheds.service; enabled; preset: enabled) Active: active (running) since Tue 2026-07-21 19:18:37 UTC; 31s ago Main PID: 2547 (java)

Check the listening sockets. Both appear as the IPv4-mapped form [::ffff:127.0.0.1], which is the loopback address:

ss -tln | grep -E '10389|10636'

LISTEN 0 50 [::ffff:127.0.0.1]:10636 *:* LISTEN 0 50 [::ffff:127.0.0.1]:10389 *:*

Confirm the Java runtime:

java -version 2>&1 | head -1

openjdk version "17.0.19" 2026-04-21

Retrieving the administrator credentials

First boot writes the per-instance administrator password to a root-only file:

sudo cat /root/apacheds-credentials.txt

The file contains the generated password, the bind DN, the demonstration base DN, the LDAP and LDAPS ports, and a reminder that the listeners are loopback only:

# Apache Directory Server (ApacheDS) - generated on first boot
# This admin password is unique to this VM. Store it somewhere safe. APACHEDS_ADMIN_PASSWORD=<generated-on-first-boot> APACHEDS_BIND_DN=uid=admin,ou=system APACHEDS_DEMO_BASE_DN=dc=sac,dc=local APACHEDS_LDAP_HOST=127.0.0.1 APACHEDS_LDAP_PORT=10389 APACHEDS_LDAPS_PORT=10636 APACHEDS_PUBLIC_IP=<this-instance-public-ip>

Load the password into a shell variable instead of printing it, so it never lands in your shell history or terminal scrollback. The rest of this guide uses $PW:

PW=$(grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-) if [ -n "$PW" ]; then echo "administrator password loaded (${#PW} characters)"; else echo "not yet generated"; fi

administrator password loaded (32 characters)

Confirm the file is readable only by root:

stat -c '%a %U:%G' /root/apacheds-credentials.txt

600 root:root

Querying the directory

Anonymous rootDSE

Anyone can read the rootDSE anonymously. It is the quickest way to confirm that the directory is answering and to see which naming contexts it serves:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -s base -b '' '(objectclass=*)' namingContexts supportedLDAPVersion vendorName

dn: vendorName: Apache Software Foundation supportedLDAPVersion: 3 namingContexts: ou=system namingContexts: dc=sac,dc=local namingContexts: ou=schema namingContexts: ou=config

dc=sac,dc=local is the seeded demonstration partition. ou=system, ou=schema and ou=config are the server's own partitions.

Authenticated search of the demonstration partition

Bind as the administrator and search the seeded partition. The password comes from $PW, so it is never echoed:

PW=$(grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-) ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" -b 'dc=sac,dc=local' '(objectclass=inetOrgPerson)' cn mail uid

dn: uid=alice,ou=people,dc=sac,dc=local mail: alice@sac.local cn: Alice Anderson uid: alice dn: uid=bob,ou=people,dc=sac,dc=local mail: bob@sac.local cn: Bob Brown uid: bob

The seed also creates ou=people, ou=groups and a groupOfNames entry cn=engineers whose members are the two users above.

Confirming the administrator password is unique to your instance

ApacheDS ships a well-known upstream administrator password. This image rotates it on first boot, so it must no longer authenticate. This check proves both directions without printing either password. The generated password is accepted, and the upstream default is rejected:

PW=$(grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-)
GOOD=$(ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" -s base -b '' '(objectclass=*)' 2>&1 || true)
STOCK=$(ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w secret -s base -b '' '(objectclass=*)' 2>&1 || true)
echo "$GOOD" | grep -qi 'supportedLDAPVersion\|objectClass\|dn:' && echo "generated password: ACCEPTED" || echo "generated password: REJECTED"
echo "$STOCK" | grep -qi 'Invalid credentials\|result: 49' && echo "upstream default: REJECTED" || echo "upstream default: ACCEPTED"

generated password: ACCEPTED upstream default: REJECTED

If the second line ever reads ACCEPTED, the first-boot rotation did not complete. Check the status of apache-directory-ds-firstboot.service and contact SecureAnyCloud support.

Checking the directory data volume

The instance lives on its own EBS volume, so directory growth never competes with the root filesystem. Check the volume:

df -h /var/lib/apacheds | tail -1 findmnt -no SOURCE,TARGET,FSTYPE /var/lib/apacheds

/dev/nvme1n1 30G 6.3M 28G 1% /var/lib/apacheds /dev/nvme1n1 /var/lib/apacheds ext4

The mount is recorded in /etc/fstab by filesystem UUID, so it survives reboots and re-attaches correctly on any instance launched from this image. To grow it, expand the EBS volume in the AWS console, then extend the filesystem:

sudo resize2fs /dev/nvme1n1

Reaching the directory from your workstation

The listeners are loopback only, so use an SSH tunnel to reach the directory from an LDAP browser such as Apache Directory Studio, or from ldapsearch on your own machine. Run this command on your workstation, not on the instance:

ssh -i /path/to/your-key.pem -L 10389:127.0.0.1:10389 ubuntu@<public-ip>

Leave that session open. In another terminal on your workstation, the directory is now reachable at ldap://127.0.0.1:10389:

ldapsearch -x -LLL -H ldap://127.0.0.1:10389 \
  -D 'uid=admin,ou=system' -W \
  -b 'dc=sac,dc=local' '(objectclass=*)'

In Apache Directory Studio, create a connection to host 127.0.0.1, port 10389, with bind DN uid=admin,ou=system and the password from the credentials file.

For LDAPS, tunnel port 10636 the same way.

Adding your own directory data

The demonstration partition proves that the directory works. For real use, import your own entries or replace the suffix entirely.

Write an LDIF file that describes the entries you want, for example /tmp/my-entries.ldif:

dn: ou=staff,dc=sac,dc=local objectClass: organizationalUnit objectClass: top ou: staff dn: uid=jsmith,ou=staff,dc=sac,dc=local objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: person objectClass: top cn: Jane Smith sn: Smith uid: jsmith mail: jsmith@example.com

Then import it. This command modifies the directory:

PW=$(sudo grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-) ldapadd -x -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" -f /tmp/my-entries.ldif

To modify an existing entry, write an LDIF file with a changetype and apply it with ldapmodify:

dn: uid=jsmith,ou=staff,dc=sac,dc=local changetype: modify replace: mail mail: jane.smith@example.com

ldapmodify -x -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" -f /tmp/change.ldif

To remove an entry:

ldapdelete -x -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" 'uid=jsmith,ou=staff,dc=sac,dc=local'

To use your own suffix instead of dc=sac,dc=local, add a new partition through the ou=config partition with the configuration editor in Apache Directory Studio. You can also ask SecureAnyCloud support to help you plan the partition and index layout.

Changing the administrator password

The password generated at first boot is unique to your instance. To set your own, apply a modify against uid=admin,ou=system. Then update the credentials file so the value on disk stays accurate:

cat > /tmp/newpw.ldif <<'LDIF' dn: uid=admin,ou=system changetype: modify replace: userPassword userPassword: <your-new-password> LDIF
PW=$(sudo grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-) ldapmodify -x -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" -f /tmp/newpw.ldif shred -u /tmp/newpw.ldif

Then edit /root/apacheds-credentials.txt and replace the APACHEDS_ADMIN_PASSWORD= <set-at-first-boot>

Exposing the directory to your private network

Keeping the listeners on loopback is the safest default. If your applications need to reach the directory over the network, bind it to the instance's private address instead of all interfaces. Restrict access with a security group, and prefer LDAPS.

The bind addresses live in the server's own configuration partition. Edit them with Apache Directory Studio connected over the SSH tunnel. Open the ou=config partition, find the LDAP and LDAPS transports, and change ads-transportaddress from 127.0.0.1 to the instance's private IP address. Then restart the service:

sudo systemctl restart apacheds.service

Next, add an inbound rule to the security group that allows TCP 10636 from the private CIDR your application servers sit in, and only that CIDR. Do not expose either port to 0.0.0.0/0, and do not expose plain LDAP on 10389 beyond loopback. Use LDAPS on 10636 with a certificate your clients trust.

Backup and maintenance

The directory data lives entirely under /var/lib/apacheds. Two approaches are supported: an EBS snapshot of the data volume, and an LDIF export.

To export the demonstration partition as LDIF, run this command on the instance and copy the file off:

PW=$(sudo grep '^APACHEDS_ADMIN_PASSWORD=' /root/apacheds-credentials.txt | cut -d= -f2-) ldapsearch -x -LLL -H ldap://127.0.0.1:10389 -D 'uid=admin,ou=system' -w "$PW" \
  -b 'dc=sac,dc=local' '(objectclass=*)' '*' > /tmp/apacheds-export.ldif

For a consistent volume-level backup, stop the service. Take an EBS snapshot of the data volume in the AWS console or CLI, then start the service again:

sudo systemctl stop apacheds.service
# take the EBS snapshot of the volume mounted at /var/lib/apacheds
sudo systemctl start apacheds.service

Read the service logs through the journal:

journalctl -u apacheds.service --no-pager -n 5

Unattended upgrades, which are enabled on the image, apply operating system security updates. Restart the service after an OpenJDK update so it picks up the new runtime:

sudo systemctl restart apacheds.service

Troubleshooting

The service is not active. Check the unit status and the last few journal lines with the commands above. The most common cause is that the data volume is not mounted. The unit declares RequiresMountsFor=/var/lib/apacheds and does not start without it. Confirm with findmnt /var/lib/apacheds.

The credentials file does not show a generated password. First boot has not finished. Check systemctl status apache-directory-ds-firstboot.service. The service waits for the directory to accept LDAP before it rotates the password.

A bind returns Invalid credentials (49). Confirm that you are using the value from /root/apacheds-credentials.txt on that specific instance. Every instance generates its own password, so a password from another instance does not work.

ldapsearch: command not found on your workstation. Install your platform's OpenLDAP client utilities, or use Apache Directory Studio over the tunnel instead.

Nothing answers on 127.0.0.1:10389 through the tunnel. Confirm that the SSH session carrying the -L forward is still open and that the service is active on the instance.

Support

SecureAnyCloud engineers back every deployment with 24/7 support by email and live chat, with a one-hour average response for critical issues. Support covers deployment and instance sizing, directory schema and partition design, LDIF import, rebinding the listeners to a private interface, LDAPS and TLS certificate configuration, access control, backup and restore of the directory volume, and ApacheDS upgrades and JVM tuning.

Apache, Apache Directory, Apache Directory Server and ApacheDS are trademarks of The Apache Software Foundation. All product and company names are trademarks or registered trademarks of their respective holders. Their use does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch Apache Directory Server on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com