[GH-ISSUE #539] [FEATURE REQUEST]: LDAP migration tool automation/save progress

kerem commented

2026-02-27 08:15:49 +03:00

Owner

Originally created by @stefandesu on GitHub (Apr 10, 2023).
Original GitHub issue: https://github.com/lldap/lldap/issues/539

Hi,

First of all, I would like to say that I really appreciate this tool and everybody working on it! I'm not using it in production yet (as I'm still struggling with user migration, hence this issue), but it's almost exactly what I've been looking for to manage my LDAP users.

I don't want to attack anyone who worked on this, so I hope you won't take this the wrong way... The LDAP migration tool is absolutely infuriating to use. It feels like it was only ever used in optimal case scenarios.

First of all, there seems to be no documentation on this. I only found it through the issue tracker and eventually figured out how to call it (docker compose exec lldap ./migration-tool).

It only seems to work in about 1 in 20 cases. In the other 19 cases, I get the following message:

❯ docker compose exec lldap ./migration-tool                                                                    
The migration tool requires access to both the original LDAP server and the HTTP API of the target LLDAP server.
Error: IoError: Invalid terminal Size { width: 0, height: 0 }. Both width and height must be larger than 0      
                                                                                                                
Caused by:                                                                                                      
    Invalid terminal Size { width: 0, height: 0 }. Both width and height must be larger than 0

Literally nothing was different between the calls where it worked and those where it don't.

Why do I know this? I've had to use it several times because whenever something is not exactly right (i.e. a user is missing a certain field), it quits. This also means that I needed to input all the configuration several times throughout this journey of using the tool.

Eventually, after adding uids to all users and adding missing email addresses, it worked and, supposedly, migrated all my users. Horray!

But... the login doesn't work. It seems like the passwords were not migrated correctly. I tried two different users (my personal user account and a test account) and it always shows "Invalid username or password". I'm assuming it's because I'm using "crypt" for password hashes (I don't remember why exactly, but that's what I researched back then).

I'm using both openldap and lldap via Docker (Compose) and for lldap I'm using the latest tag (only due to a fix for Safari that isn't released yet).

As I don't want this to be only a rant, I'll leave some ideas for improvements on the tool:

Document that this migration tool exists and how to call it (maybe there's a reason it isn't documented yet 😅).
Definitely fix the terminal size issue (I assume this might be because I'm using tmux, but it's not that uncommon).
Instead of quitting the script, output error messages and give the user the chance to fix the issue and try again, without having to rerun the script.
Ideally, offer manual mapping of fields so that certain issues don't appear in the first place. For example, I'm using cn for user names, and it would have been great to use that for the ID in lldap as well. Also the tool uses cn before displayName for the display name of users and for the last name as well, so after the import, the ID, display name, and last name of all users are simply the cn (or uid which I added to make the tool work).
I'm not sure if this is possible, but if it is, it would be nice if the tool could detect whether it can migrate the passwords correctly or not. Maybe it could show an option which hash method was used so that the passwords are migrated correctly.

I'm actually not sure if I can use lldap if no. 5 is not fixed because I don't want to force all my users to reset their passwords. I also don't know any Rust, otherwise I'd totally try to fix these issues myself.

I hope this was helpful in any way, even if it was a bit of a rant. If you have any idea how to fix the password issue, I'd be very grateful!

Originally created by @stefandesu on GitHub (Apr 10, 2023). Original GitHub issue: https://github.com/lldap/lldap/issues/539 Hi, First of all, I would like to say that I really appreciate this tool and everybody working on it! I'm not using it in production yet (as I'm still struggling with user migration, hence this issue), but it's almost exactly what I've been looking for to manage my LDAP users. I don't want to attack anyone who worked on this, so I hope you won't take this the wrong way... The LDAP migration tool is absolutely infuriating to use. It feels like it was only ever used in optimal case scenarios. First of all, there seems to be no documentation on this. I only found it through the issue tracker and eventually figured out how to call it (`docker compose exec lldap ./migration-tool`). It only seems to work in about 1 in 20 cases. In the other 19 cases, I get the following message: ``` ❯ docker compose exec lldap ./migration-tool The migration tool requires access to both the original LDAP server and the HTTP API of the target LLDAP server. Error: IoError: Invalid terminal Size { width: 0, height: 0 }. Both width and height must be larger than 0 Caused by: Invalid terminal Size { width: 0, height: 0 }. Both width and height must be larger than 0 ``` Literally nothing was different between the calls where it worked and those where it don't. Why do I know this? I've had to use it several times because whenever something is not exactly right (i.e. a user is missing a certain field), it quits. This also means that I needed to input all the configuration several times throughout this journey of using the tool. Eventually, after adding `uid`s to all users and adding missing email addresses, it worked and, supposedly, migrated all my users. Horray! But... the login doesn't work. It seems like the passwords were not migrated correctly. I tried two different users (my personal user account and a test account) and it always shows "Invalid username or password". I'm assuming it's because I'm using "crypt" for password hashes (I don't remember why exactly, but that's what I researched back then). I'm using both openldap and lldap via Docker (Compose) and for lldap I'm using the `latest` tag (only due to a fix for Safari that isn't released yet). As I don't want this to be only a rant, I'll leave some ideas for improvements on the tool: 1. Document that this migration tool exists and how to call it (maybe there's a reason it isn't documented yet 😅). 2. Definitely fix the terminal size issue (I assume this might be because I'm using tmux, but it's not that uncommon). 3. Instead of quitting the script, output error messages and give the user the chance to fix the issue and try again, without having to rerun the script. 4. Ideally, offer manual mapping of fields so that certain issues don't appear in the first place. For example, I'm using `cn` for user names, and it would have been great to use that for the ID in lldap as well. Also the tool uses `cn` before `displayName` for the display name of users and for the last name as well, so after the import, the ID, display name, and last name of all users are simply the `cn` (or `uid` which I added to make the tool work). 5. I'm not sure if this is possible, but if it is, it would be nice if the tool could detect whether it can migrate the passwords correctly or not. Maybe it could show an option which hash method was used so that the passwords are migrated correctly. I'm actually not sure if I can use lldap if no. 5 is not fixed because I don't want to force all my users to reset their passwords. I also don't know any Rust, otherwise I'd totally try to fix these issues myself. I hope this was helpful in any way, even if it was a bit of a rant. If you have any idea how to fix the password issue, I'd be very grateful!

kerem added the

labels

2026-02-27 08:15:49 +03:00

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@nitnelave commented on GitHub (Apr 10, 2023):

Hi! Sorry that the migration tool didn't work well for you :/

First of all, I've got some bad news for you: due to the security protocols used by LLDAP, it's not possible to import/export passwords (you can migrate them to another instance of LLDAP, but that's about it). This is due to the use of the OPAQUE protocol, so rather than a hash of the password, we store just enough information that we can negotiate a zero-knowledge proof with the user that they hold the same password as at registration time. Just to restate it:

It's not possible to migrate the passwords from another LDAP server to LLDAP.

It might be worth a warning at the beginning of the tool.
Now that we got that out of the way, let's have a look at what else we got wrong.

The migration tool is an interactive TUI tool, meant to be called directly. I think what was missing from your command line was -it (interactive, tty): docker compose exec -it lldap ./migration-tool. A more straight-forward way to call it would be just: docker run --rm -it --entrypoint ./migration-tool lldap/lldap. That should fix the invalid terminal size.
Lack of documentation, invalid attributes and so on: I haven't had much feedback on the tool, not many people have used it (also potentially because it's not well documented? But also not many people have asked). Thanks for the feedback! I didn't really think of cases where not every user has an email address. The script doesn't do much sanity checking: the uids can be invalid, the emails can be malformatted and so on, it's very much up to the admin to double-check that everything went well. It could use some more error-recovery mechanisms and being generally more flexible. However, I also don't want to make the tool a kitchen-sink of LDAP utilities, so some judgement will be necessary for what can make the cut.

It feels like it was only ever used in optimal case scenarios.

That is probably true :D It's more of a proof-of-concept that I made for my own needs than a well-polished universal tool.

I haven't had much demand for this tool so far, so I haven't invested a lot of time in it, but contributions are welcome!

@nitnelave commented on GitHub (Apr 10, 2023): Hi! Sorry that the migration tool didn't work well for you :/ First of all, I've got some bad news for you: due to the security protocols used by LLDAP, it's not possible to import/export passwords (you can migrate them to another instance of LLDAP, but that's about it). This is due to the use of the OPAQUE protocol, so rather than a hash of the password, we store just enough information that we can negotiate a zero-knowledge proof with the user that they hold the same password as at registration time. Just to restate it: **It's not possible to migrate the passwords from another LDAP server to LLDAP.** It might be worth a warning at the beginning of the tool. Now that we got _that_ out of the way, let's have a look at what else we got wrong. - The migration tool is an interactive TUI tool, meant to be called directly. I think what was missing from your command line was `-it` (interactive, tty): `docker compose exec -it lldap ./migration-tool`. A more straight-forward way to call it would be just: `docker run --rm -it --entrypoint ./migration-tool lldap/lldap`. That should fix the invalid terminal size. - Lack of documentation, invalid attributes and so on: I haven't had much feedback on the tool, not many people have used it (also potentially because it's not well documented? But also not many people have asked). Thanks for the feedback! I didn't really think of cases where not every user has an email address. The script doesn't do much sanity checking: the `uid`s can be invalid, the emails can be malformatted and so on, it's very much up to the admin to double-check that everything went well. It could use some more error-recovery mechanisms and being generally more flexible. However, I also don't want to make the tool a kitchen-sink of LDAP utilities, so some judgement will be necessary for what can make the cut. > It feels like it was only ever used in optimal case scenarios. That is probably true :D It's more of a proof-of-concept that I made for my own needs than a well-polished universal tool. I haven't had much demand for this tool so far, so I haven't invested a lot of time in it, but contributions are welcome!

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@stefandesu commented on GitHub (Apr 10, 2023):

Thanks @nitnelave for the quick reply!

It's not possible to migrate the passwords from another LDAP server to LLDAP.

That's good to know! As I really want to move away from OpenLDAP/phpLDAPadmin, I will need to ask my users to reset their passwords, it seems. But that does mean that the migration tool (kinda) worked for me, because I have at least all the users in there now. 😁

The migration tool is an interactive TUI tool, meant to be called directly. I think what was missing from your command line was -it (interactive, tty)

Ooooh I see. I wonder why it still worked some of the time though. Very strange. 😅

However, I also don't want to make the tool a kitchen-sink of LDAP utilities, so some judgement will be necessary for what can make the cut.

Yeah for sure! I guess with a little bit of documentation (especially about its caveats) and maybe a remapping feature, the migration tool would totally be fine. 👍 I have to admit that manually recreating the accounts would probably have been faster for me, but at least I created this issue because of it. 😅

@stefandesu commented on GitHub (Apr 10, 2023): Thanks @nitnelave for the quick reply! > It's not possible to migrate the passwords from another LDAP server to LLDAP. That's good to know! As I really want to move away from OpenLDAP/phpLDAPadmin, I will need to ask my users to reset their passwords, it seems. But that does mean that the migration tool (kinda) worked for me, because I have at least all the users in there now. 😁 > The migration tool is an interactive TUI tool, meant to be called directly. I think what was missing from your command line was -it (interactive, tty) Ooooh I see. I wonder why it still worked some of the time though. Very strange. 😅 > However, I also don't want to make the tool a kitchen-sink of LDAP utilities, so some judgement will be necessary for what can make the cut. Yeah for sure! I guess with a little bit of documentation (especially about its caveats) and maybe a remapping feature, the migration tool would totally be fine. 👍 I have to admit that manually recreating the accounts would probably have been faster for me, but at least I created this issue because of it. 😅

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@nitnelave commented on GitHub (Apr 11, 2023):

Note for future implementation: there may be a way forward to, at some point, be able to import passwords from other servers. In the context of this LLDAP RFC, calling attention to this specific paragraph: LLDAP RFC - OPAQUE Migration
Basically, have the general hash check available, and on first login convert to OPAQUE format for safety. Note that it does prevent you from re-exporting the passwords.

@nitnelave commented on GitHub (Apr 11, 2023): Note for future implementation: there may be a way forward to, at some point, be able to import passwords from other servers. In the context of this LLDAP RFC, calling attention to this specific paragraph: [LLDAP RFC - OPAQUE Migration](https://docs.google.com/document/d/1Y8rVSYyZzzzjKGJOVTYVFl38pKSnUopx-cijR24IMz4/edit#heading=h.6o95gf4ol41i) Basically, have the general hash check available, and on first login convert to OPAQUE format for safety. Note that it _does_ prevent you from re-exporting the passwords.

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@dvv commented on GitHub (Jan 31, 2024):

I gave up trying to automate the migration tool and drafted envvar-driven version here https://github.com/lldap/lldap/compare/filters...dvv:lldap:filters

@dvv commented on GitHub (Jan 31, 2024): I gave up trying to automate the migration tool and drafted envvar-driven version here https://github.com/lldap/lldap/compare/filters...dvv:lldap:filters

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@nitnelave commented on GitHub (Jan 31, 2024):

Yeah, it's not made to be automated, but rather to guide you through a one-time migration.

I'm curious, why do you need to automate the migration?

@nitnelave commented on GitHub (Jan 31, 2024): Yeah, it's not made to be automated, but rather to guide you through a one-time migration. I'm curious, why do you need to automate the migration?

kerem commented

2026-02-27 08:15:50 +03:00

Author

Owner

@dvv commented on GitHub (Jan 31, 2024):

@nitnelave I'm considering using it as a cron task to pull external (source, but badly maintained) ldap data into my (shiny)) lldap instance.

@dvv commented on GitHub (Jan 31, 2024): @nitnelave I'm considering using it as a cron task to pull external (source, but badly maintained) ldap data into my (shiny)) lldap instance.

kerem referenced this issue

2026-02-27 08:18:10 +03:00

[PR #197] [MERGED] build(deps): bump tokio from 1.11.0 to 1.13.1 #606

Rows
Columns

[GH-ISSUE #539] [FEATURE REQUEST]: LDAP migration tool automation/save progress #197