diff --git a/README.md b/README.md index af4dd16..82b65f9 100644 --- a/README.md +++ b/README.md @@ -34,31 +34,14 @@

- [About](#about) -- [Installation](#installation) - - [With Docker](#with-docker) - - [With Podman](#with-podman) - - [With Kubernetes](#with-kubernetes) - - [From a package repository](#from-a-package-repository) - - [With FreeBSD](#with-freebsd) - - [From source](#from-source) - - [Backend](#backend) - - [Frontend](#frontend) - - [Cross-compilation](#cross-compilation) +- [Installation](docs/install.md) - [Usage](#usage) - [Recommended architecture](#recommended-architecture) - [Client configuration](#client-configuration) - - [Compatible services](#compatible-services) + - [Known compatible services](#known-compatible-services) - [General configuration guide](#general-configuration-guide) - - [Integration with OS's](#integration-with-oss) - - [Sample client configurations](#sample-client-configurations) - [Incompatible services](#incompatible-services) -- [Migrating from SQLite](#migrating-from-sqlite) -- [Comparisons with other services](#comparisons-with-other-services) - - [vs OpenLDAP](#vs-openldap) - - [vs FreeIPA](#vs-freeipa) - - [vs Kanidm](#vs-kanidm) -- [I can't log in!](#i-cant-log-in) -- [Discord Integration](#discord-integration) +- [Frequently Asked Questions](#frequently-asked-questions) - [Contributions](#contributions) ## About @@ -100,404 +83,9 @@ MySQL/MariaDB or PostgreSQL. ## Installation -### With Docker +It's possible to install lldap from OCI images ([docker](docs/install.md#with-docker)/[podman](docs/install.md#with-podman)), from [Kubernetes](docs/install.md#with-kubernetes), or from [a regular distribution package manager](docs/install.md/#from-a-package-repository) (Archlinux, Debian, CentOS, Fedora, OpenSuse, Ubuntu, FreeBSD). -The image is available at `lldap/lldap`. You should persist the `/data` -folder, which contains your configuration and the SQLite database (you can -remove this step if you use a different DB and configure with environment -variables only). - -Configure the server by copying the `lldap_config.docker_template.toml` to -`/data/lldap_config.toml` and updating the configuration values (especially the -`jwt_secret` and `ldap_user_pass`, unless you override them with env variables). -Environment variables should be prefixed with `LLDAP_` to override the -configuration. - -If the `lldap_config.toml` doesn't exist when starting up, LLDAP will use -default one. The default admin password is `password`, you can change the -password later using the web interface. - -Secrets can also be set through a file. The filename should be specified by the -variables `LLDAP_JWT_SECRET_FILE` or `LLDAP_KEY_SEED_FILE`, and the file -contents are loaded into the respective configuration parameters. Note that -`_FILE` variables take precedence. - -Example for docker compose: - -- You can use either the `:latest` tag image or `:stable` as used in this example. -- `:latest` tag image contains recently pushed code or feature tests, in which some instability can be expected. -- If `UID` and `GID` no defined LLDAP will use default `UID` and `GID` number `1000`. -- If no `TZ` is set, default `UTC` timezone will be used. -- You can generate the secrets by running `./generate_secrets.sh` - -```yaml -version: "3" - -volumes: - lldap_data: - driver: local - -services: - lldap: - image: lldap/lldap:stable - ports: - # For LDAP, not recommended to expose, see Usage section. - #- "3890:3890" - # For LDAPS (LDAP Over SSL), enable port if LLDAP_LDAPS_OPTIONS__ENABLED set true, look env below - #- "6360:6360" - # For the web front-end - - "17170:17170" - volumes: - - "lldap_data:/data" - # Alternatively, you can mount a local folder - # - "./lldap_data:/data" - environment: - - UID=#### - - GID=#### - - TZ=####/#### - - LLDAP_JWT_SECRET=REPLACE_WITH_RANDOM - - LLDAP_KEY_SEED=REPLACE_WITH_RANDOM - - LLDAP_LDAP_BASE_DN=dc=example,dc=com - - LLDAP_LDAP_USER_PASS=adminPas$word - # If using LDAPS, set enabled true and configure cert and key path - # - LLDAP_LDAPS_OPTIONS__ENABLED=true - # - LLDAP_LDAPS_OPTIONS__CERT_FILE=/path/to/certfile.crt - # - LLDAP_LDAPS_OPTIONS__KEY_FILE=/path/to/keyfile.key - # You can also set a different database: - # - LLDAP_DATABASE_URL=mysql://mysql-user:password@mysql-server/my-database - # - LLDAP_DATABASE_URL=postgres://postgres-user:password@postgres-server/my-database - # If using SMTP, set the following variables - # - LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET=true - # - LLDAP_SMTP_OPTIONS__SERVER=smtp.example.com - # - LLDAP_SMTP_OPTIONS__PORT=465 # Check your smtp providor's documentation for this setting - # - LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION=TLS # How the connection is encrypted, either "NONE" (no encryption, port 25), "TLS" (sometimes called SSL, port 465) or "STARTTLS" (sometimes called TLS, port 587). - # - LLDAP_SMTP_OPTIONS__USER=no-reply@example.com # The SMTP user, usually your email address - # - LLDAP_SMTP_OPTIONS__PASSWORD=PasswordGoesHere # The SMTP password - # - LLDAP_SMTP_OPTIONS__FROM=no-reply # The header field, optional: how the sender appears in the email. The first is a free-form name, followed by an email between <>. - # - LLDAP_SMTP_OPTIONS__TO=admin # Same for reply-to, optional. -``` - -Then the service will listen on two ports, one for LDAP and one for the web -front-end. - -### With Podman - -LLDAP works well with rootless Podman either through command line deployment -or using [quadlets](example_configs/podman-quadlets/). The example quadlets -include configuration with postgresql and file based secrets, but have comments -for several other deployment strategies. - -### With Kubernetes - -See https://github.com/Evantage-WS/lldap-kubernetes for a LLDAP deployment for Kubernetes - -You can bootstrap your lldap instance (users, groups) -using [bootstrap.sh](example_configs/bootstrap/bootstrap.md#kubernetes-job). -It can be run by Argo CD for managing users in git-opt way, or as a one-shot job. - -### From a package repository - -**Do not open issues in this repository for problems with third-party -pre-built packages. Report issues downstream.** - -Depending on the distribution you use, it might be possible to install lldap -from a package repository, officially supported by the distribution or -community contributed. - -Each package offers a [systemd service](https://wiki.archlinux.org/title/systemd#Using_units) `lldap.service` or [rc.d_lldap](example_configs/freebsd/rc.d_lldap) `rc.d/lldap` to (auto-)start and stop lldap.
-When using the distributed packages, the default login is `admin/password`. You can change that from the web UI after starting the service. - -
-Arch Linux -
- Arch Linux offers unofficial support through the Arch User Repository (AUR).
- The package descriptions can be used to create and install packages.

- Support: Discussions
- Package repository: Arch User Repository

- - - - - - - - - - - - - - - - - - - - - -
Package nameMaintainerDescription
lldap@ZepmannBuilds the latest stable version.
lldap-bin@ZepmannUses the latest pre-compiled binaries from the releases in this repository.
- This package is recommended if you want to run LLDAP on a system with limited resources.
lldap-gitBuilds the latest main branch code.
-LLDAP configuration file: /etc/lldap.toml
-
-
-Debian -
- Unofficial Debian support is offered through the openSUSE Build Service.

- Maintainer: @Masgalor
- Support: Codeberg, Discussions
- Package repository: SUSE openBuildService
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
-LLDAP configuration file: /etc/lldap/lldap_config.toml
-
-
-CentOS -
- Unofficial CentOS support is offered through the openSUSE Build Service.

- Maintainer: @Masgalor
- Support: Codeberg, Discussions
- Package repository: SUSE openBuildService
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
-LLDAP configuration file: /etc/lldap/lldap_config.toml
-
-
-Fedora -
- Unofficial Fedora support is offered through the openSUSE Build Service.

- Maintainer: @Masgalor
- Support: Codeberg, Discussions
- Package repository: SUSE openBuildService
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
-LLDAP configuration file: /etc/lldap/lldap_config.toml
-
-
-OpenSUSE -
- Unofficial OpenSUSE support is offered through the openSUSE Build Service.

- Maintainer: @Masgalor
- Support: Codeberg, Discussions
- Package repository: SUSE openBuildService
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
-LLDAP configuration file: /etc/lldap/lldap_config.toml
-
-
-Ubuntu -
- Unofficial Ubuntu support is offered through the openSUSE Build Service.

- Maintainer: @Masgalor
- Support: Codeberg, Discussions
- Package repository: SUSE openBuildService
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
-LLDAP configuration file: /etc/lldap/lldap_config.toml
-
-
-FreeBSD -
- Official FreeBSD support is offered through the FreeBSD Freshport Build Service.

- Maintainer: @aokblast
- Support: Bugzilla, Discussions
- Package repository: FreeBSD Freshport Build
- FreeBSD Setup and Migration Manual: Using FreeBSD
- - - - - - -
Available packages:lldapLight LDAP server for authentication.
-LLDAP configuration file: /usr/local/lldap_server/lldap_config.toml
-
- -### From source - -#### Backend - -To compile the project, you'll need: - -- curl and gzip: `sudo apt install curl gzip` -- Rust/Cargo: [rustup.rs](https://rustup.rs/) - -Then you can compile the server (and the migration tool if you want): - -```shell -cargo build --release -p lldap -p lldap_migration_tool -``` - -The resulting binaries will be in `./target/release/`. Alternatively, you can -just run `cargo run -- run` to run the server. - -#### Frontend - -To bring up the server, you'll need to compile the frontend. In addition to -`cargo`, you'll need WASM-pack, which can be installed by running `cargo install wasm-pack`. - -Then you can build the frontend files with - -```shell -./app/build.sh -``` - -(you'll need to run this after every front-end change to update the WASM -package served). - -The default config is in `src/infra/configuration.rs`, but you can override it -by creating an `lldap_config.toml`, setting environment variables or passing -arguments to `cargo run`. Have a look at the docker template: -`lldap_config.docker_template.toml`. - -You can also install it as a systemd service, see -[lldap.service](example_configs/lldap.service). - -### Cross-compilation - -Docker images are provided for AMD64, ARM64 and ARM/V7. - -If you want to cross-compile yourself, you can do so by installing -[`cross`](https://github.com/rust-embedded/cross): - -```sh -cargo install cross -cross build --target=armv7-unknown-linux-musleabihf -p lldap --release -./app/build.sh -``` - -(Replace `armv7-unknown-linux-musleabihf` with the correct Rust target for your -device.) - -You can then get the compiled server binary in -`target/armv7-unknown-linux-musleabihf/release/lldap` and the various needed files -(`index.html`, `main.js`, `pkg` folder) in the `app` folder. Copy them to the -Raspberry Pi (or other target), with the folder structure maintained (`app` -files in an `app` folder next to the binary). +Building [from source](docs/install.md#from-source) and [cross-compiling](docs/install.md#cross-compilation) to a different hardware architecture is also supported. ## Usage @@ -548,7 +136,7 @@ If you are using containers, a sample architecture could look like this: ## Client configuration -### Compatible services +### Known compatible services Most services that can use LDAP as an authentication provider should work out of the box. For new services, it's possible that they require a bit of tweaking @@ -556,6 +144,13 @@ on LLDAP's side to make things work. In that case, just create an issue with the relevant details (logs of the service, LLDAP logs with `verbose=true` in the config). +Some specific clients have been tested to work and come with sample +configuration files, or guides. See the [`example_configs`](example_configs) +folder for example configs for integration with specific services. + +Integration with Linux accounts is possible, through PAM and nslcd. See [PAM +configuration guide](example_configs/pam/README.md). Integration with Windows (e.g. Samba) is WIP. + ### General configuration guide To configure the services that will talk to LLDAP, here are the values: @@ -579,93 +174,6 @@ administration access to many services. To prevent privilege escalation users in `lldap_password_manager` group are not allowed to change passwords of admins in the `lldap_admin` group. -### Integration with OS's - -Integration with Linux accounts is possible, through PAM and nslcd. See [PAM -configuration guide](example_configs/pam/README.md). - -Integration with Windows (e.g. Samba) is WIP. - -### Sample client configurations - -Some specific clients have been tested to work and come with sample -configuration files, or guides. See the [`example_configs`](example_configs) -folder for help with: - -- [Airsonic Advanced](example_configs/airsonic-advanced.md) -- [Apache Guacamole](example_configs/apacheguacamole.md) -- [Apereo CAS Server](example_configs/apereo_cas_server.md) -- [Authelia](example_configs/authelia_config.yml) -- [Authentik](example_configs/authentik.md) -- [Bookstack](example_configs/bookstack.env.example) -- [Calibre-Web](example_configs/calibre_web.md) -- [Carpal](example_configs/carpal.md) -- [Dell iDRAC](example_configs/dell_idrac.md) -- [Dex](example_configs/dex_config.yml) -- [Dokuwiki](example_configs/dokuwiki.md) -- [Dolibarr](example_configs/dolibarr.md) -- [Duo Auth Proxy](example_configs/duo_auth_proxy.md) -- [Ejabberd](example_configs/ejabberd.md) -- [Emby](example_configs/emby.md) -- [Ergo IRCd](example_configs/ergo.md) -- [Gitea](example_configs/gitea.md) -- [GitLab](example_configs/gitlab.md) -- [Grafana](example_configs/grafana_ldap_config.toml) -- [Grocy](example_configs/grocy.md) -- [Harbor](example_configs/harbor.md) -- [HashiCorp Vault](example_configs/hashicorp-vault.md) -- [Hedgedoc](example_configs/hedgedoc.md) -- [Home Assistant](example_configs/home-assistant.md) -- [Jellyfin](example_configs/jellyfin.md) -- [Jenkins](example_configs/jenkins.md) -- [Jitsi Meet](example_configs/jitsi_meet.conf) -- [Kasm](example_configs/kasm.md) -- [KeyCloak](example_configs/keycloak.md) -- [Kimai](example_configs/kimai.yaml) -- [LibreNMS](example_configs/librenms.md) -- [Maddy](example_configs/maddy.md) -- [Mailcow](example_configs/mailcow.md) -- [Mastodon](example_configs/mastodon.env.example) -- [Matrix](example_configs/matrix_synapse.yml) -- [Mealie](example_configs/mealie.md) -- [Metabase](example_configs/metabase.md) -- [MegaRAC-BMC](example_configs/MegaRAC-SP-X-BMC.md) -- [MinIO](example_configs/minio.md) -- [Netbox](example_configs/netbox.md) -- [Nextcloud](example_configs/nextcloud.md) -- [Nexus](example_configs/nexus.md) -- [OCIS (OwnCloud Infinite Scale)](example_configs/ocis.md) -- [OneDev](example_configs/onedev.md) -- [Organizr](example_configs/Organizr.md) -- [Peertube](example_configs/peertube.md) -- [Penpot](example_configs/penpot.md) -- [pgAdmin](example_configs/pgadmin.md) -- [Portainer](example_configs/portainer.md) -- [PowerDNS Admin](example_configs/powerdns_admin.md) -- [Prosody](example_configs/prosody.md) -- [Proxmox VE](example_configs/proxmox.md) -- [Quay](example_configs/quay.md) -- [Radicale](example_configs/radicale.md) -- [Rancher](example_configs/rancher.md) -- [Seafile](example_configs/seafile.md) -- [Shaarli](example_configs/shaarli.md) -- [Snipe-IT](example_configs/snipe-it.md) -- [SonarQube](example_configs/sonarqube.md) -- [Squid](example_configs/squid.md) -- [Stalwart](example_configs/stalwart.md) -- [Syncthing](example_configs/syncthing.md) -- [TheLounge](example_configs/thelounge.md) -- [Traccar](example_configs/traccar.xml) -- [UniFi OS](example_configs/udm_identity_end_point.md) -- [Vaultwarden](example_configs/vaultwarden.md) -- [WeKan](example_configs/wekan.md) -- [WG Portal](example_configs/wg_portal.env.example) -- [WikiJS](example_configs/wikijs.md) -- [XBackBone](example_configs/xbackbone_config.php) -- [Zendto](example_configs/zendto.md) -- [Zitadel](example_configs/zitadel.md) -- [Zulip](example_configs/zulip.md) - ### Incompatible services Though we try to be maximally compatible, not every feature is supported; LLDAP @@ -687,83 +195,12 @@ it duplicates the places from which a password hash could leak. In that category, the most prominent is Synology. It is, to date, the only service that seems definitely incompatible with LLDAP. -## Migrating from SQLite +## Frequently Asked Questions -If you started with an SQLite database and would like to migrate to -MySQL/MariaDB or PostgreSQL, check out the [DB -migration docs](/docs/database_migration.md). - -## Comparisons with other services - -### vs OpenLDAP - -[OpenLDAP](https://www.openldap.org) is a monster of a service that implements -all of LDAP and all of its extensions, plus some of its own. That said, if you -need all that flexibility, it might be what you need! Note that installation -can be a bit painful (figuring out how to use `slapd`) and people have mixed -experiences following tutorials online. If you don't configure it properly, you -might end up storing passwords in clear, so a breach of your server would -reveal all the stored passwords! - -OpenLDAP doesn't come with a UI: if you want a web interface, you'll have to -install one (not that many look nice) and configure it. - -LLDAP is much simpler to setup, has a much smaller image (10x smaller, 20x if -you add PhpLdapAdmin), and comes packed with its own purpose-built web UI. -However, it's not as flexible as OpenLDAP. - -### vs FreeIPA - -[FreeIPA](http://www.freeipa.org) is the one-stop shop for identity management: -LDAP, Kerberos, NTP, DNS, Samba, you name it, it has it. In addition to user -management, it also does security policies, single sign-on, certificate -management, linux account management and so on. - -If you need all of that, go for it! Keep in mind that a more complex system is -more complex to maintain, though. - -LLDAP is much lighter to run (<10 MB RAM including the DB), easier to -configure (no messing around with DNS or security policies) and simpler to -use. It also comes conveniently packed in a docker container. - -### vs Kanidm - -[Kanidm](https://kanidm.com) is an up-and-coming Rust identity management -platform, covering all your bases: OAuth, Linux accounts, SSH keys, Radius, -WebAuthn. It comes with a (read-only) LDAPS server. - -It's fairly easy to install and does much more; but their LDAP server is -read-only, and by having more moving parts it is inherently more complex. If -you don't need to modify the users through LDAP and you're planning on -installing something like [KeyCloak](https://www.keycloak.org) to provide -modern identity protocols, check out Kanidm. - -## I can't log in! - -If you just set up the server, can get to the login page but the password you -set isn't working, try the following: - -- If you have changed the admin password in the config after the first run, it - won't be used (unless you force its use with `force_ldap_user_pass_reset`). - The config password is only for the initial admin creation. -- (For docker): Make sure that the `/data` folder is persistent, either to a - docker volume or mounted from the host filesystem. -- Check if there is a `lldap_config.toml` file (either in `/data` for docker - or in the current directory). If there isn't, copy - `lldap_config.docker_template.toml` there, and fill in the various values - (passwords, secrets, ...). -- Check if there is a `users.db` file (either in `/data` for docker or where - you specified the DB URL, which defaults to the current directory). If - there isn't, check that the user running the command (user with ID 10001 - for docker) has the rights to write to the `/data` folder. If in doubt, you - can `chmod 777 /data` (or whatever the folder) to make it world-writeable. -- Make sure you restart the server. -- If it's still not working, join the - [Discord server](https://discord.gg/h5PEdRMNyP) to ask for help. - -## Discord Integration -[Use this bot](https://github.com/JaidenW/LLDAP-Discord) to Automate discord role syncronization for paid memberships. -- Allows users with the Subscriber role to self-serve create an LLDAP account based on their Discord username, using the `/register` command. +- [I can't login](docs/faq.md#i-cant-log-in) +- [Discord Integration](docs/faq.md#discord-integration) +- [Migrating from SQLite](docs/faq.md#migrating-from-sqlite) +- How does lldap compare [with OpenLDAP](docs/faq.md#how-does-lldap-compare-with-openldap)? [With FreeIPA](docs/faq.md#how-does-lldap-compare-with-freeipa)? [With Kanidm]?(docs/faq.md#how-does-lldap-compare-with-kanidm) ## Contributions diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..52e4bf5 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,83 @@ +# Frequently Asked Questions + +- [I can't login](#i-cant-log-in) +- [Discord Integration](#discord-integration) +- [Migrating from SQLite](#migrating-from-sqlite) +- How does LLDAP compare [with OpenLDAP](#how-does-lldap-compare-with-openldap)? [With FreeIPA](#how-does-lldap-compare-with-freeipa)? [With Kanidm](#how-does-lldap-compare-with-kanidm)? + +## I can't log in! + +If you just set up the server, can get to the login page but the password you +set isn't working, try the following: + +- If you have changed the admin password in the config after the first run, it + won't be used (unless you force its use with `force_ldap_user_pass_reset`). + The config password is only for the initial admin creation. +- (For docker): Make sure that the `/data` folder is persistent, either to a + docker volume or mounted from the host filesystem. +- Check if there is a `lldap_config.toml` file (either in `/data` for docker + or in the current directory). If there isn't, copy + `lldap_config.docker_template.toml` there, and fill in the various values + (passwords, secrets, ...). +- Check if there is a `users.db` file (either in `/data` for docker or where + you specified the DB URL, which defaults to the current directory). If + there isn't, check that the user running the command (user with ID 10001 + for docker) has the rights to write to the `/data` folder. If in doubt, you + can `chmod 777 /data` (or whatever the folder) to make it world-writeable. +- Make sure you restart the server. +- If it's still not working, join the + [Discord server](https://discord.gg/h5PEdRMNyP) to ask for help. + +## Discord Integration + +[Use this bot](https://github.com/JaidenW/LLDAP-Discord) to Automate discord role synchronization for paid memberships. +- Allows users with the Subscriber role to self-serve create an LLDAP account based on their Discord username, using the `/register` command. + +## Migrating from SQLite + +If you started with an SQLite database and would like to migrate to +MySQL/MariaDB or PostgreSQL, check out the [DB +migration docs](/docs/database_migration.md). + +## How does LLDAP compare with OpenLDAP? + +[OpenLDAP](https://www.openldap.org) is a monster of a service that implements +all of LDAP and all of its extensions, plus some of its own. That said, if you +need all that flexibility, it might be what you need! Note that installation +can be a bit painful (figuring out how to use `slapd`) and people have mixed +experiences following tutorials online. If you don't configure it properly, you +might end up storing passwords in clear, so a breach of your server would +reveal all the stored passwords! + +OpenLDAP doesn't come with a UI: if you want a web interface, you'll have to +install one (not that many look nice) and configure it. + +LLDAP is much simpler to setup, has a much smaller image (10x smaller, 20x if +you add PhpLdapAdmin), and comes packed with its own purpose-built web UI. +However, it's not as flexible as OpenLDAP. + +## How does LLDAP compare with FreeIPA? + +[FreeIPA](http://www.freeipa.org) is the one-stop shop for identity management: +LDAP, Kerberos, NTP, DNS, Samba, you name it, it has it. In addition to user +management, it also does security policies, single sign-on, certificate +management, linux account management and so on. + +If you need all of that, go for it! Keep in mind that a more complex system is +more complex to maintain, though. + +LLDAP is much lighter to run (<10 MB RAM including the DB), easier to +configure (no messing around with DNS or security policies) and simpler to +use. It also comes conveniently packed in a docker container. + +## How does LLDAP compare with kanidm? + +[Kanidm](https://kanidm.com) is an up-and-coming Rust identity management +platform, covering all your bases: OAuth, Linux accounts, SSH keys, Radius, +WebAuthn. It comes with a (read-only) LDAPS server. + +It's fairly easy to install and does much more; but their LDAP server is +read-only, and by having more moving parts it is inherently more complex. If +you don't need to modify the users through LDAP and you're planning on +installing something like [KeyCloak](https://www.keycloak.org) to provide +modern identity protocols, check out Kanidm. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..8cf8fb0 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,410 @@ +# Installing LLDAP + +- [With Docker](#with-docker) +- [With Podman](#with-podman) +- [With Kubernetes](#with-kubernetes) +- [From a package repository](#from-a-package-repository) +- [With FreeBSD](#with-freebsd) +- [From source](#from-source) + - [Backend](#backend) + - [Frontend](#frontend) +- [Cross-compilation](#cross-compilation) + +### With Docker + +The image is available at `lldap/lldap`. You should persist the `/data` +folder, which contains your configuration and the SQLite database (you can +remove this step if you use a different DB and configure with environment +variables only). + +Configure the server by copying the `lldap_config.docker_template.toml` to +`/data/lldap_config.toml` and updating the configuration values (especially the +`jwt_secret` and `ldap_user_pass`, unless you override them with env variables). +Environment variables should be prefixed with `LLDAP_` to override the +configuration. + +If the `lldap_config.toml` doesn't exist when starting up, LLDAP will use +default one. The default admin password is `password`, you can change the +password later using the web interface. + +Secrets can also be set through a file. The filename should be specified by the +variables `LLDAP_JWT_SECRET_FILE` or `LLDAP_KEY_SEED_FILE`, and the file +contents are loaded into the respective configuration parameters. Note that +`_FILE` variables take precedence. + +Example for docker compose: + +- You can use either the `:latest` tag image or `:stable` as used in this example. +- `:latest` tag image contains recently pushed code or feature tests, in which some instability can be expected. +- If `UID` and `GID` no defined LLDAP will use default `UID` and `GID` number `1000`. +- If no `TZ` is set, default `UTC` timezone will be used. +- You can generate the secrets by running `./generate_secrets.sh` + +```yaml +version: "3" + +volumes: + lldap_data: + driver: local + +services: + lldap: + image: lldap/lldap:stable + ports: + # For LDAP, not recommended to expose, see Usage section. + #- "3890:3890" + # For LDAPS (LDAP Over SSL), enable port if LLDAP_LDAPS_OPTIONS__ENABLED set true, look env below + #- "6360:6360" + # For the web front-end + - "17170:17170" + volumes: + - "lldap_data:/data" + # Alternatively, you can mount a local folder + # - "./lldap_data:/data" + environment: + - UID=#### + - GID=#### + - TZ=####/#### + - LLDAP_JWT_SECRET=REPLACE_WITH_RANDOM + - LLDAP_KEY_SEED=REPLACE_WITH_RANDOM + - LLDAP_LDAP_BASE_DN=dc=example,dc=com + - LLDAP_LDAP_USER_PASS=adminPas$word + # If using LDAPS, set enabled true and configure cert and key path + # - LLDAP_LDAPS_OPTIONS__ENABLED=true + # - LLDAP_LDAPS_OPTIONS__CERT_FILE=/path/to/certfile.crt + # - LLDAP_LDAPS_OPTIONS__KEY_FILE=/path/to/keyfile.key + # You can also set a different database: + # - LLDAP_DATABASE_URL=mysql://mysql-user:password@mysql-server/my-database + # - LLDAP_DATABASE_URL=postgres://postgres-user:password@postgres-server/my-database + # If using SMTP, set the following variables + # - LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET=true + # - LLDAP_SMTP_OPTIONS__SERVER=smtp.example.com + # - LLDAP_SMTP_OPTIONS__PORT=465 # Check your smtp provider's documentation for this setting + # - LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION=TLS # How the connection is encrypted, either "NONE" (no encryption, port 25), "TLS" (sometimes called SSL, port 465) or "STARTTLS" (sometimes called TLS, port 587). + # - LLDAP_SMTP_OPTIONS__USER=no-reply@example.com # The SMTP user, usually your email address + # - LLDAP_SMTP_OPTIONS__PASSWORD=PasswordGoesHere # The SMTP password + # - LLDAP_SMTP_OPTIONS__FROM=no-reply # The header field, optional: how the sender appears in the email. The first is a free-form name, followed by an email between <>. + # - LLDAP_SMTP_OPTIONS__TO=admin # Same for reply-to, optional. +``` + +Then the service will listen on two ports, one for LDAP and one for the web +front-end. + +### With Podman + +LLDAP works well with rootless Podman either through command line deployment +or using [quadlets](example_configs/podman-quadlets/). The example quadlets +include configuration with postgresql and file based secrets, but have comments +for several other deployment strategies. + +### With Kubernetes + +See https://github.com/Evantage-WS/lldap-kubernetes for a LLDAP deployment for Kubernetes + +You can bootstrap your lldap instance (users, groups) +using [bootstrap.sh](example_configs/bootstrap/bootstrap.md#kubernetes-job). +It can be run by Argo CD for managing users in git-opt way, or as a one-shot job. + +### From a package repository + +**Do not open issues in this repository for problems with third-party +pre-built packages. Report issues downstream.** + +Depending on the distribution you use, it might be possible to install LLDAP +from a package repository, officially supported by the distribution or +community contributed. + +Each package offers a [systemd service](https://wiki.archlinux.org/title/systemd#Using_units) `lldap.service` or [rc.d_lldap](example_configs/freebsd/rc.d_lldap) `rc.d/lldap` to (auto-)start and stop lldap.
+When using the distributed packages, the default login is `admin/password`. You can change that from the web UI after starting the service. + +
+Arch Linux +
+ Arch Linux offers unofficial support through the Arch User Repository (AUR).
+ The package descriptions can be used to create and install packages.

+ Support: Discussions
+ Package repository: Arch User Repository

+ + + + + + + + + + + + + + + + + + + + + +
Package nameMaintainerDescription
lldap@ZepmannBuilds the latest stable version.
lldap-bin@ZepmannUses the latest pre-compiled binaries from the releases in this repository.
+ This package is recommended if you want to run LLDAP on a system with limited resources.
lldap-gitBuilds the latest main branch code.
+LLDAP configuration file: /etc/lldap.toml
+
+
+Debian +
+ Unofficial Debian support is offered through the openSUSE Build Service.

+ Maintainer: @Masgalor
+ Support: Codeberg, Discussions
+ Package repository: SUSE openBuildService
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
+LLDAP configuration file: /etc/lldap/lldap_config.toml
+
+
+CentOS +
+ Unofficial CentOS support is offered through the openSUSE Build Service.

+ Maintainer: @Masgalor
+ Support: Codeberg, Discussions
+ Package repository: SUSE openBuildService
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
+LLDAP configuration file: /etc/lldap/lldap_config.toml
+
+
+Fedora +
+ Unofficial Fedora support is offered through the openSUSE Build Service.

+ Maintainer: @Masgalor
+ Support: Codeberg, Discussions
+ Package repository: SUSE openBuildService
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
+LLDAP configuration file: /etc/lldap/lldap_config.toml
+
+
+OpenSUSE +
+ Unofficial OpenSUSE support is offered through the openSUSE Build Service.

+ Maintainer: @Masgalor
+ Support: Codeberg, Discussions
+ Package repository: SUSE openBuildService
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
+LLDAP configuration file: /etc/lldap/lldap_config.toml
+
+
+Ubuntu +
+ Unofficial Ubuntu support is offered through the openSUSE Build Service.

+ Maintainer: @Masgalor
+ Support: Codeberg, Discussions
+ Package repository: SUSE openBuildService
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Available packages:lldapLight LDAP server for authentication.
lldap-extrasMeta-Package for LLDAP and its tools and extensions.
lldap-migration-toolCLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-passwordCLI tool to set a user password in LLDAP.
lldap-cliLLDAP-CLI is an unofficial command line interface for LLDAP.
+LLDAP configuration file: /etc/lldap/lldap_config.toml
+
+
+FreeBSD +
+ Official FreeBSD support is offered through the FreeBSD Freshport Build Service.

+ Maintainer: @aokblast
+ Support: Bugzilla, Discussions
+ Package repository: FreeBSD Freshport Build
+ FreeBSD Setup and Migration Manual: Using FreeBSD
+ + + + + + +
Available packages:lldapLight LDAP server for authentication.
+LLDAP configuration file: /usr/local/lldap_server/lldap_config.toml
+
+ +### From source + +#### Backend + +To compile the project, you'll need: + +- curl and gzip: `sudo apt install curl gzip` +- Rust/Cargo: [rustup.rs](https://rustup.rs/) + +Then you can compile the server (and the migration tool if you want): + +```shell +cargo build --release -p lldap -p lldap_migration_tool +``` + +The resulting binaries will be in `./target/release/`. Alternatively, you can +just run `cargo run -- run` to run the server. + +#### Frontend + +To bring up the server, you'll need to compile the frontend. In addition to +`cargo`, you'll need WASM-pack, which can be installed by running `cargo install wasm-pack`. + +Then you can build the frontend files with + +```shell +./app/build.sh +``` + +(you'll need to run this after every front-end change to update the WASM +package served). + +The default config is in `src/infra/configuration.rs`, but you can override it +by creating an `lldap_config.toml`, setting environment variables or passing +arguments to `cargo run`. Have a look at the docker template: +`lldap_config.docker_template.toml`. + +You can also install it as a systemd service, see +[lldap.service](example_configs/lldap.service). + +### Cross-compilation + +Docker images are provided for AMD64, ARM64 and ARM/V7. + +If you want to cross-compile yourself, you can do so by installing +[`cross`](https://github.com/rust-embedded/cross): + +```sh +cargo install cross +cross build --target=armv7-unknown-linux-musleabihf -p lldap --release +./app/build.sh +``` + +(Replace `armv7-unknown-linux-musleabihf` with the correct Rust target for your +device.) + +You can then get the compiled server binary in +`target/armv7-unknown-linux-musleabihf/release/lldap` and the various needed files +(`index.html`, `main.js`, `pkg` folder) in the `app` folder. Copy them to the +Raspberry Pi (or other target), with the folder structure maintained (`app` +files in an `app` folder next to the binary). diff --git a/example_configs/README.md b/example_configs/README.md new file mode 100644 index 0000000..8ffefa2 --- /dev/null +++ b/example_configs/README.md @@ -0,0 +1,78 @@ +# Example configurations + +Some specific clients have been tested to work and come with sample +configuration files: + +- [Airsonic Advanced](airsonic-advanced.md) +- [Apache Guacamole](apacheguacamole.md) +- [Apereo CAS Server](apereo_cas_server.md) +- [Authelia](authelia_config.yml) +- [Authentik](authentik.md) +- [Bookstack](bookstack.env.example) +- [Calibre-Web](calibre_web.md) +- [Carpal](carpal.md) +- [Dell iDRAC](dell_idrac.md) +- [Dex](dex_config.yml) +- [Dokuwiki](dokuwiki.md) +- [Dolibarr](dolibarr.md) +- [Duo Auth Proxy](duo_auth_proxy.md) +- [Ejabberd](ejabberd.md) +- [Emby](emby.md) +- [Ergo IRCd](ergo.md) +- [Gitea](gitea.md) +- [GitLab](gitlab.md) +- [Grafana](grafana_ldap_config.toml) +- [Grocy](grocy.md) +- [Harbor](harbor.md) +- [HashiCorp Vault](hashicorp-vault.md) +- [Hedgedoc](hedgedoc.md) +- [Home Assistant](home-assistant.md) +- [Jellyfin](jellyfin.md) +- [Jenkins](jenkins.md) +- [Jitsi Meet](jitsi_meet.conf) +- [Kasm](kasm.md) +- [KeyCloak](keycloak.md) +- [Kimai](kimai.yaml) +- [LibreNMS](librenms.md) +- [Maddy](maddy.md) +- [Mailcow](mailcow.md) +- [Mastodon](mastodon.env.example) +- [Matrix](matrix_synapse.yml) +- [Mealie](mealie.md) +- [Metabase](metabase.md) +- [MegaRAC-BMC](MegaRAC-SP-X-BMC.md) +- [MinIO](minio.md) +- [Netbox](netbox.md) +- [Nextcloud](nextcloud.md) +- [Nexus](nexus.md) +- [OCIS (OwnCloud Infinite Scale)](ocis.md) +- [OneDev](onedev.md) +- [Organizr](Organizr.md) +- [Peertube](peertube.md) +- [Penpot](penpot.md) +- [pgAdmin](pgadmin.md) +- [Portainer](portainer.md) +- [PowerDNS Admin](powerdns_admin.md) +- [Prosody](prosody.md) +- [Proxmox VE](proxmox.md) +- [Quay](quay.md) +- [Radicale](radicale.md) +- [Rancher](rancher.md) +- [Seafile](seafile.md) +- [Shaarli](shaarli.md) +- [Snipe-IT](snipe-it.md) +- [SonarQube](sonarqube.md) +- [Squid](squid.md) +- [Stalwart](stalwart.md) +- [Syncthing](syncthing.md) +- [TheLounge](thelounge.md) +- [Traccar](traccar.xml) +- [UniFi OS](udm_identity_end_point.md) +- [Vaultwarden](vaultwarden.md) +- [WeKan](wekan.md) +- [WG Portal](wg_portal.env.example) +- [WikiJS](wikijs.md) +- [XBackBone](xbackbone_config.php) +- [Zendto](zendto.md) +- [Zitadel](zitadel.md) +- [Zulip](zulip.md)