This guide walks you from a fresh Dirless account to a Linux host resolving users natively - no LDAP server, no FreeIPA, no SSSD.
Dirless uses age encryption to protect identity snapshots end-to-end. The private key never leaves your hosts - the backend only ever sees the public key.
Generate your keypair at dirless.com/age-keypair.html
and save the downloaded private key file somewhere safe on each host you enroll
(e.g. /root/dirless-age.key). You use the same keypair across your
entire fleet.
After signing up at portal.dirless.com, open your account dashboard. Note down two values you'll need:
https://yourname.dirless.com
On the Linux host you want to enroll, add the Dirless RPM repository and install both packages:
curl -fsSL https://dirless.com/rpm/dirless.repo \
-o /etc/yum.repos.d/dirless.repo
dnf install -y dirless-cli dirless-agentThis installs dirless-cli (used once to enroll the host) and
dirless-agent (the daemon that runs permanently). The agent package
also installs libnss_dirless.so.2 and its systemd unit.
curl -fsSL https://github.com/dirless/dirless-cli/releases/latest/download/dirless-cli-x86_64 -o /usr/local/bin/dirless-cli && chmod +x /usr/local/bin/dirless-clicurl -fsSL https://github.com/dirless/dirless-agent/releases/latest/download/dirless-agent-x86_64 -o /usr/local/bin/dirless-agent && chmod +x /usr/local/bin/dirless-agent
Run dirless-cli enroll with your age key, enrollment token, and backend URL.
This registers the host with your backend and writes everything the agent needs
to /etc/dirless/ - including the agent config file.
dirless-cli enroll \
--age-key /root/dirless-age.key \
--token <your-enrollment-token> \
--server https://<yourname>.dirless.comdirless-cli enroll \
--age-key /root/dirless-age.key \
--tenant-id <your-tenant-id> \
--token <your-enrollment-token> \
--server https://<yourname>.dirless.com
On success, enrollment writes two files to /etc/dirless/:
age.key (your age private key) and hmac.key (the HMAC secret
used to authenticate with the backend). It also writes a ready-to-use
dirless-agent.toml with all values already filled in.
Enrollment already wrote /etc/dirless/dirless-agent.toml with the
correct backend URL, HMAC secret, tenant ID, and age key path. Just enable and
start the daemon:
systemctl enable --now dirless-agent
The agent connects to the backend, fetches the encrypted identity snapshot,
decrypts it with your age key, and writes user and group data to
/var/lib/dirless/local.db. It refreshes in the background
every 60 seconds by default.
RPM install: skip this step. The package automatically updates
/etc/nsswitch.conf on install (backing up the original to
/etc/nsswitch.conf.dirless-backup) and restores it on removal.
Binary install: add dirless to the
passwd, group, and shadow lines in
/etc/nsswitch.conf:
passwd: files dirless systemd
shadow: files dirless
group: files dirless systemd
The dirless keyword maps to libnss_dirless.so.2.
NSS lookups read from local.db directly - no network call,
no daemon socket. If the backend is unreachable, lookups continue working
from the last snapshot.
Add a user through the Dirless portal (or wait for the syncer to pull one from IAM Identity Center if you've set that up). After the next sync cycle - at most 60 seconds - the user should resolve on the host.
# Check that the user resolves
getent passwd alice
# Check group membership
id alice
# List all Dirless-managed users
getent passwd | grep -v nologin
If you see the user's entry (with a UID in the 60000+ range), Dirless
is working. The user now exists as a native Linux identity and can log in
via SSH, run sudo, and appear correctly in ls -la
output on shared filesystems.
journalctl -u dirless-agent -n 50
to see the agent's sync status. A fresh account has no users until you add
one through the portal or configure the syncer.
If your team already uses AWS IAM Identity Center, the Dirless syncer pulls users, groups, and memberships automatically and pushes them to your backend. Portal-managed users and synced IAM Identity Center users coexist - you can use both at the same time. Skip this section if you don't have an IAM Identity Center directory to sync from.
The syncer must run on an EC2 instance inside your AWS account with an IAM role attached. It fetches credentials from the instance metadata service - no static AWS keys are ever stored.
IAM permissions required on the instance role:
{
"Effect": "Allow",
"Action": [
"identitystore:ListUsers",
"identitystore:ListGroups",
"identitystore:ListGroupMemberships"
],
"Resource": "*"
}Install and configure the syncer on the EC2 instance:
# Install
dnf install -y dirless-syncer
# Create config
cat > /etc/dirless/dirless-syncer.toml <<'EOF'
[backend]
url = "https://<yourname>.dirless.com"
enrollment_token = "<your-enrollment-token>"
[syncer]
interval_seconds = 300
EOF
# Start
systemctl enable --now dirless-syncerOn first run the syncer uses the enrollment token to register with the backend, then begins pulling your Identity Center directory on the configured interval (default: every 5 minutes). The token can be removed from the config after the first successful run.
Once the syncer is running, any user or group change in Identity Center propagates to every enrolled Linux host within one sync interval. UIDs and GIDs are stable - they never change even if a user is removed and re-added.