2022-12-29 04:22:16 +01:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > FreeIPA - Kanidm Administration< / title >
<!-- Custom HTML head -->
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "../highlight.css" >
< link rel = "stylesheet" href = "../tomorrow-night.css" >
< link rel = "stylesheet" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< / head >
< body >
2023-02-17 08:24:03 +01:00
< div id = "body-container" >
2022-12-29 04:22:16 +01:00
<!-- Provide site root to javascript -->
< script >
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script >
var html = document.querySelector('html');
2023-03-05 23:59:20 +01:00
var sidebar = null;
2022-12-29 04:22:16 +01:00
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
2023-03-05 23:59:20 +01:00
} else {
sidebar = 'hidden';
2022-12-29 04:22:16 +01:00
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2023-05-05 13:23:43 +02:00
< ol class = "chapter" > < li class = "chapter-item expanded " > < a href = "../intro.html" > < strong aria-hidden = "true" > 1.< / strong > Introduction to Kanidm< / a > < / li > < li class = "chapter-item expanded " > < a href = "../installing_the_server.html" > < strong aria-hidden = "true" > 2.< / strong > Installing the Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../choosing_a_domain_name.html" > < strong aria-hidden = "true" > 2.1.< / strong > Choosing a Domain Name< / a > < / li > < li class = "chapter-item expanded " > < a href = "../prepare_the_server.html" > < strong aria-hidden = "true" > 2.2.< / strong > Preparing for your Deployment< / a > < / li > < li class = "chapter-item expanded " > < a href = "../server_configuration.html" > < strong aria-hidden = "true" > 2.3.< / strong > Server Configuration and Install< / a > < / li > < li class = "chapter-item expanded " > < a href = "../security_hardening.html" > < strong aria-hidden = "true" > 2.4.< / strong > Platform Security Hardening< / a > < / li > < li class = "chapter-item expanded " > < a href = "../server_update.html" > < strong aria-hidden = "true" > 2.5.< / strong > Server Updates< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../client_tools.html" > < strong aria-hidden = "true" > 3.< / strong > Client Tools< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../installing_client_tools.html" > < strong aria-hidden = "true" > 3.1.< / strong > Installing client tools< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < li class = "part-title" > Administration< / li > < li class = "chapter-item expanded " > < a href = "../administrivia.html" > < strong aria-hidden = "true" > 4.< / strong > Administration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../accounts_and_groups.html" > < strong aria-hidden = "true" > 4.1.< / strong > Accounts and Groups< / a > < / li > < li class = "chapter-item expanded " > < a href = "../authentication.html" > < strong aria-hidden = "true" > 4.2.< / strong > Authentication and Credentials< / a > < / li > < li class = "chapter-item expanded " > < a href = "../posix_accounts.html" > < strong aria-hidden = "true" > 4.3.< / strong > POSIX Accounts and Groups< / a > < / li > < li class = "chapter-item expanded " > < a href = "../backup_restore.html" > < strong aria-hidden = "true" > 4.4.< / strong > Backup and Restore< / a > < / li > < li class = "chapter-item expanded " > < a href = "../database_maint.html" > < strong aria-hidden = "true" > 4.5.< / strong > Database Maintenance< / a > < / li > < li class = "chapter-item expanded " > < a href = "../domain_rename.html" > < strong aria-hidden = "true" > 4.6.< / strong > Domain Rename< / a > < / li > < li class = "chapter-item expanded " > < a href = "../monitoring.html" > < strong aria-hidden = "true" > 4.7.< / strong > Monitoring the platform< / a > < / li > < li class = "chapter-item expanded " > < a href = "../password_quality.html" > < strong aria-hidden = "true" > 4.8.< / strong > Password Quality and Badlisting< / a > < / li > < li class = "chapter-item expanded " > < a href = "../recycle_bin.html" > < strong aria-hidden = "true" > 4.9.< / strong > The Recycle Bin< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < li class = "part-title" > Services< / li > < li class = "chapter-item expanded " > < a href = "../integrations/pam_and_nsswitch.html" > < strong aria-hidden = "true" > 5.< / strong > PAM and nsswitch< / a > < / li > < li class = "chapter-item expanded " > < a href = "../ssh_key_dist.html" > < strong aria-hidden = "true" > 6.< / strong > SSH Key Distribution< / a > < / li > < li class = "chapter-item expanded " > < a href = "../integrations/oauth2.html" > < strong aria-hidden = "true" > 7.< / strong > Oauth2< / a > < / li > < li class = "chapter-item expanded " > < a href = "../integrations/ldap.html" > < strong aria-hidden = "true" > 8.< / strong > LDAP< / a > < / li > < li class = "chapter-item expanded " > < a href = "../integrations/radius.html" > < strong aria-hidden = "true" > 9.< / strong > RADIUS< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Synchronisation< / li > < li class = "chapter-item expanded " > < a href = "../sync/concepts.html" > < strong aria-hidden = "true" > 10.< / strong > Concepts< / a > < / li > < li class = "chapter-item expanded " > < a href = "../sync/freeipa.html" class = "active" > < strong aria-hidden = "true" > 11.< / strong > FreeIPA< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Integration Examples< / li > < li class = "chapter-item expanded " > < a href = "../ex
2022-12-29 04:22:16 +01:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Kanidm Administration< / h1 >
< div class = "right-buttons" >
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/kanidm/kanidm" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
2023-03-02 04:03:10 +01:00
< a href = "https://github.com/kanidm/kanidm/edit/master/book/src/sync/freeipa.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
2022-12-29 04:22:16 +01:00
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
< h1 id = "synchronising-from-freeipa" > < a class = "header" href = "#synchronising-from-freeipa" > Synchronising from FreeIPA< / a > < / h1 >
< p > FreeIPA is a popular opensource LDAP and Kerberos provider, aiming to be " Active Directory" for
Linux.< / p >
< p > Kanidm is able to synchronise from FreeIPA for the purposes of coexistence or migration.< / p >
< h2 id = "installing-the-freeipa-sync-tool" > < a class = "header" href = "#installing-the-freeipa-sync-tool" > Installing the FreeIPA Sync Tool< / a > < / h2 >
< p > See < a href = "../installing_client_tools.html" > installing the client tools< / a > .< / p >
< h2 id = "configure-the-freeipa-sync-tool" > < a class = "header" href = "#configure-the-freeipa-sync-tool" > Configure the FreeIPA Sync Tool< / a > < / h2 >
< p > The sync tool is a bridge between FreeIPA and Kanidm, meaning that the tool must be configured to
communicate to both sides.< / p >
< p > Like other components of Kanidm, the FreeIPA sync tool will read your /etc/kanidm/config if present
to understand how to connect to Kanidm.< / p >
< p > The sync tool specific components are configured in it's own configuration file.< / p >
< pre > < pre class = "playground" > < code class = "language-rust" > < span class = "boring" > #![allow(unused)]
< / span >
< span class = "boring" > fn main() {
< / span > < span class = "boring" > The sync account token as generated by " system sync generate-token" .
< / span > sync_token = " eyJhb..."
< span class = "boring" > A cron-like expression of when to run when in scheduled mode. The format is:
< / span > < span class = "boring" > sec min hour day of month month day of week year
< / span > < span class = "boring" >
< / span > < span class = "boring" > The default of this value is " 0 */5 * * * * *" which means " run every 5 minutes" .
< / span > < span class = "boring" > schedule = " "
< / span >
< span class = "boring" > If you want to monitor the status of the scheduled sync tool (you should)
< / span > < span class = "boring" > then you can set a bind address here.
< / span > < span class = "boring" >
< / span > < span class = "boring" > If not set, defaults to no status listener.
< / span > < span class = "boring" > status_bind = " "
< / span >
< span class = "boring" > The LDAP URI to FreeIPA. This MUST be LDAPS. You should connect to a unique single
< / span > < span class = "boring" > server in the IPA topology rather than via a load balancer or dns srv records. This
< / span > < span class = "boring" > is to prevent replication conflicts and issues due to how 389-ds content sync works.
< / span > ipa_uri = " ldaps://specific-server.ipa.dev.kanidm.com"
< span class = "boring" > Path to the IPA CA certificate in PEM format.
< / span > ipa_ca = " /path/to/kanidm-ipa-ca.pem"
< span class = "boring" > The DN of an account with content sync rights. By default cn=Directory Manager has
< / span > < span class = "boring" > this access.
< / span > ipa_sync_dn = " cn=Directory Manager"
ipa_sync_pw = " directory manager password"
< span class = "boring" > The basedn to examine.
< / span > ipa_sync_base_dn = " dc=ipa,dc=dev,dc=kanidm,dc=com"
< span class = "boring" > The sync tool can alter or exclude entries. These are mapped by their syncuuid
< / span > < span class = "boring" > (not their ipa-object-uuid). The syncuuid is derived from nsUniqueId in 389-ds.
< / span > < span class = "boring" > This is chosen oven DN because DN's can change with modrdn where nsUniqueId is
< / span > < span class = "boring" > immutable and requires an entry to be deleted and recreated.
< / span >
[ac60034b-3498-11ed-a50d-919b4b1a5ec0]
< span class = "boring" > my-problematic-entry
< / span > exclude = true
< span class = "boring" > }< / span > < / code > < / pre > < / pre >
< p > This example is located in
< a href = "https://github.com/kanidm/kanidm/blob/master/examples/kanidm-ipa-sync" > examples/kanidm-ipa-sync< / a > .< / p >
< p > In addition to this, you must make some configuration changes to FreeIPA to enable synchronisation.< / p >
< p > You can find the name of your 389 Directory Server instance with:< / p >
< pre > < code class = "language-bash" > dsconf --list
< / code > < / pre >
< p > Using this you can show the current status of the retro changelog plugin to see if you need to
change it's configuration.< / p >
< pre > < code class = "language-bash" > dsconf < instance name> plugin retro-changelog show
dsconf slapd-DEV-KANIDM-COM plugin retro-changelog show
< / code > < / pre >
< p > You must modify the retro changelog plugin to include the full scope of the database suffix so that
the sync tool can view the changes to the database. Currently dsconf can not modify the
include-suffix so you must do this manually.< / p >
< p > You need to change the < code > nsslapd-include-suffix< / code > to match your FreeIPA baseDN here. You can access
the basedn with:< / p >
< pre > < code class = "language-bash" > ldapsearch -H ldaps://< IPA SERVER HOSTNAME/IP> -x -b '' -s base namingContexts
# namingContexts: dc=ipa,dc=dev,dc=kanidm,dc=com
< / code > < / pre >
< p > You should ignore < code > cn=changelog< / code > and < code > o=ipaca< / code > as these are system internal namingContexts. You can
then create an ldapmodify like the following.< / p >
< pre > < pre class = "playground" > < code class = "language-rust" > < span class = "boring" > #![allow(unused)]
< / span > < span class = "boring" > fn main() {
< / span > dn: cn=Retro Changelog Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-include-suffix
nsslapd-include-suffix: dc=ipa,dc=dev,dc=kanidm,dc=com
< span class = "boring" > }< / span > < / code > < / pre > < / pre >
< p > And apply it with:< / p >
< pre > < code class = "language-bash" > ldapmodify -f change.ldif -H ldaps://< IPA SERVER HOSTNAME/IP> -x -D 'cn=Directory Manager' -W
# Enter LDAP Password:
< / code > < / pre >
< p > You must then reboot your FreeIPA server.< / p >
< h2 id = "running-the-sync-tool-manually" > < a class = "header" href = "#running-the-sync-tool-manually" > Running the Sync Tool Manually< / a > < / h2 >
< p > You can perform a dry run with the sync tool manually to check your configurations are correct and
that the tool can synchronise from FreeIPA.< / p >
< pre > < code class = "language-bash" > kanidm-ipa-sync [-c /path/to/kanidm/config] -i /path/to/kanidm-ipa-sync -n
kanidm-ipa-sync -i /etc/kanidm/ipa-sync -n
< / code > < / pre >
< h2 id = "running-the-sync-tool-automatically" > < a class = "header" href = "#running-the-sync-tool-automatically" > Running the Sync Tool Automatically< / a > < / h2 >
< p > The sync tool can be run on a schedule if you configure the < code > schedule< / code > parameter, and provide the
option " --schedule" on the cli< / p >
< pre > < code class = "language-bash" > kanidm-ipa-sync [-c /path/to/kanidm/config] -i /path/to/kanidm-ipa-sync --schedule
< / code > < / pre >
< h2 id = "monitoring-the-sync-tool" > < a class = "header" href = "#monitoring-the-sync-tool" > Monitoring the Sync Tool< / a > < / h2 >
< p > When running in schedule mode, you may wish to monitor the sync tool for failures. Since failures
block the sync process, this is important to ensuring a smooth and reliable synchronisation process.< / p >
< p > You can configure a status listener that can be monitored via tcp with the parameter < code > status_bind< / code > .< / p >
< p > An example of monitoring this with netcat is:< / p >
< pre > < code class = "language-bash" > # status_bind = " [::1]:12345"
# nc ::1 12345
Ok
< / code > < / pre >
< p > It's important to note no details are revealed via the status socket, and is purely for Ok or Err
status of the last sync.< / p >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../sync/concepts.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../examples/k8s_ingress_example.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "../sync/concepts.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../examples/k8s_ingress_example.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script >
window.playground_copyable = true;
< / script >
< script src = "../elasticlunr.min.js" > < / script >
< script src = "../mark.min.js" > < / script >
< script src = "../searcher.js" > < / script >
< script src = "../clipboard.min.js" > < / script >
< script src = "../highlight.js" > < / script >
< script src = "../book.js" > < / script >
<!-- Custom JS scripts -->
2023-02-17 08:24:03 +01:00
< / div >
2022-12-29 04:22:16 +01:00
< / body >
< / html >
