2022-04-27 13:22:11 +02:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Developer Guide - Kanidm Administration< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "favicon.svg" >
< 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 >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
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 type = "text/javascript" >
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 type = "text/javascript" >
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 type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
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" >
< 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 = "server_configuration.html" > < strong aria-hidden = "true" > 2.1.< / strong > Server Configuration< / a > < / li > < li class = "chapter-item expanded " > < a href = "security_hardening.html" > < strong aria-hidden = "true" > 2.2.< / strong > Security Hardening< / 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 " > < a href = "accounts_and_groups.html" > < strong aria-hidden = "true" > 4.< / strong > Accounts and Groups< / a > < / li > < li class = "chapter-item expanded " > < a href = "administrivia.html" > < strong aria-hidden = "true" > 5.< / strong > Administrative Tasks< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "monitoring.html" > < strong aria-hidden = "true" > 5.1.< / strong > Monitoring the platform< / a > < / li > < li class = "chapter-item expanded " > < a href = "password_quality.html" > < strong aria-hidden = "true" > 5.2.< / strong > Password Quality and Badlisting< / a > < / li > < li class = "chapter-item expanded " > < a href = "posix_accounts.html" > < strong aria-hidden = "true" > 5.3.< / strong > POSIX Accounts and Groups< / a > < / li > < li class = "chapter-item expanded " > < a href = "ssh_key_dist.html" > < strong aria-hidden = "true" > 5.4.< / strong > SSH Key Distribution< / a > < / li > < li class = "chapter-item expanded " > < a href = "recycle_bin.html" > < strong aria-hidden = "true" > 5.5.< / strong > The Recycle Bin< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "oauth2.html" > < strong aria-hidden = "true" > 6.< / strong > Oauth2< / a > < / li > < li class = "chapter-item expanded " > < a href = "pam_and_nsswitch.html" > < strong aria-hidden = "true" > 7.< / strong > PAM and nsswitch< / a > < / li > < li class = "chapter-item expanded " > < a href = "radius.html" > < strong aria-hidden = "true" > 8.< / strong > RADIUS< / a > < / li > < li class = "chapter-item expanded " > < a href = "ldap.html" > < strong aria-hidden = "true" > 9.< / strong > LDAP< / a > < / li > < li class = "chapter-item expanded " > < a href = "why_tls.html" > < strong aria-hidden = "true" > 10.< / strong > Why TLS?< / a > < / li > < li class = "chapter-item expanded " > < a href = "DEVELOPER_README.html" class = "active" > < strong aria-hidden = "true" > 11.< / strong > Developer Guide< / a > < / li > < / ol >
< / 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 (default)< / 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 >
< / 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 type = "text/javascript" >
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 >
< h2 id = "getting-started-for-developers" > < a class = "header" href = "#getting-started-for-developers" > Getting Started (for Developers)< / a > < / h2 >
< h3 id = "designs" > < a class = "header" href = "#designs" > Designs< / a > < / h3 >
< p > See the < a href = "https://github.com/kanidm/kanidm/tree/master/designs" > designs< / a > folder, and compile the private documentation locally:< / p >
< pre > < code > cargo doc --document-private-items --open --no-deps
< / code > < / pre >
< h3 id = "rust-documentation" > < a class = "header" href = "#rust-documentation" > Rust Documentation< / a > < / h3 >
2022-05-28 00:59:37 +02:00
< p > A list of links to the library documentation is < a href = "https://kanidm.com/documentation/" > here< / a > .< / p >
2022-04-27 13:22:11 +02:00
< h3 id = "minimum-supported-rust-version" > < a class = "header" href = "#minimum-supported-rust-version" > Minimum Supported Rust Version< / a > < / h3 >
< p > The MSRV is specified in the package < code > Cargo.toml< / code > files.< / p >
< h3 id = "dependencies" > < a class = "header" href = "#dependencies" > Dependencies< / a > < / h3 >
< h4 id = "macos" > < a class = "header" href = "#macos" > MacOS< / a > < / h4 >
< p > You will need < a href = "https://rustup.rs/" > rustup< / a > to install a rust toolchain.< / p >
< p > If you plan to work on the web-ui, you may also need npm for setting up some parts.< / p >
< pre > < code > brew install npm
< / code > < / pre >
< h4 id = "suse" > < a class = "header" href = "#suse" > SUSE< / a > < / h4 >
< p > You will need < a href = "https://rustup.rs/" > rustup< / a > to install a rust toolchain.< / p >
< p > You will also need some system libraries to build this:< / p >
< pre > < code > libudev-devel sqlite3-devel libopenssl-devel npm-default
< / code > < / pre >
2022-05-23 05:07:58 +02:00
< h4 id = "fedora" > < a class = "header" href = "#fedora" > Fedora< / a > < / h4 >
< p > You will need to install the rust toolchain packages.< / p >
< pre > < code > rust cargo
< / code > < / pre >
< p > You will also need some system libraries to build this:< / p >
< pre > < code > systemd-devel sqlite-devel openssl-devel pam-devel
< / code > < / pre >
< p > Building the web ui requires additional packages:< / p >
< pre > < code > perl-FindBin perl-File-Compare rust-std-static-wasm32-unknown-unknown
< / code > < / pre >
2022-04-27 13:22:11 +02:00
< h3 id = "get-involved" > < a class = "header" href = "#get-involved" > Get involved< / a > < / h3 >
< p > To get started, you'll need to fork or branch, and we'll merge based on PR's.< / p >
< p > If you are a contributor to the project, simply clone:< / p >
2022-05-28 00:59:37 +02:00
< pre > < code class = "language-shell" > git clone git@github.com:kanidm/kanidm.git
2022-04-27 13:22:11 +02:00
< / code > < / pre >
2022-05-28 00:59:37 +02:00
< p > If you are forking, then fork in GitHub and clone with:< / p >
< pre > < code class = "language-shell" > git clone https://github.com/kanidm/kanidm.git
2022-04-27 13:22:11 +02:00
cd kanidm
git remote add myfork git@github.com:< YOUR USERNAME> /kanidm.git
< / code > < / pre >
< p > Select an issue (always feel free to reach out to us for advice!), and create a branch to start working:< / p >
2022-05-28 00:59:37 +02:00
< pre > < code class = "language-shell" > git branch < feature-branch-name>
2022-04-27 13:22:11 +02:00
git checkout < feature-branch-name>
cargo test
< / code > < / pre >
< p > When you are ready for review (even if the feature isn't complete and you just want some advice)< / p >
2022-05-28 00:59:37 +02:00
< ol >
< li > Run the test suite: < code > cargo test --workspace< / code > < / li >
< li > Ensure rust formatting standards are followed: < code > cargo fmt --check< / code > < / li >
< li > Try following the suggestions from clippy, after running < code > cargo clippy< / code > . This is not a blocker on us accepting your code!< / li >
< li > Then commit your changes:< / li >
< / ol >
< pre > < code class = "language-shell" > git commit -m 'Commit message' change_file.rs ...
2022-04-27 13:22:11 +02:00
git push < myfork/origin> < feature-branch-name>
< / code > < / pre >
2022-05-28 00:59:37 +02:00
< p > If you receive advice or make further changes, just keep commiting to the branch, and pushing to your branch.
When we are happy with the code, we'll merge in GitHub, meaning you can now clean up your branch.< / p >
2022-04-27 13:22:11 +02:00
< pre > < code > git checkout master
git pull
git branch -D < feature-branch-name>
< / code > < / pre >
2022-05-28 00:59:37 +02:00
< h4 id = "rebasing" > < a class = "header" href = "#rebasing" > Rebasing< / a > < / h4 >
2022-04-27 13:22:11 +02:00
< p > If you are asked to rebase your change, follow these steps:< / p >
< pre > < code > git checkout master
git pull
git checkout < feature-branch-name>
git rebase master
< / code > < / pre >
< p > Then be sure to fix any merge issues or other comments as they arise. If you have issues, you can always stop and reset with:< / p >
< pre > < code > git rebase --abort
< / code > < / pre >
< h3 id = "development-server-quickstart-for-interactive-testing" > < a class = "header" href = "#development-server-quickstart-for-interactive-testing" > Development Server Quickstart for Interactive Testing< / a > < / h3 >
< p > After getting the code, you will need a rust environment. Please investigate < a href = "https://rustup.rs" > rustup< / a > for your platform to establish this.< / p >
< p > Once you have the source code, you need certificates to use with the server, because without certificates, authentication will fail. < / p >
< p > We recommend using < a href = "https://letsencrypt.org" > Let's Encrypt< / a > , but if this is not possible, please use our insecure cert tool (< code > insecure_generate_tls.sh< / code > ). The insecure cert tool creates < code > /tmp/kanidm< / code > and puts some self-signed certificates there.< / p >
< p > You can now build and run the server with the commands below. It will use a database in < code > /tmp/kanidm.db< / code > .< / p >
< p > Create the initial database and generate an < code > admin< / code > username:< / p >
< pre > < code > cargo run --bin kanidmd recover_account -c ./examples/insecure_server.toml -n admin
< snip>
Success - password reset to -> Et8QRJgQkMJu3v1AQxcbxRWW44qRUZPpr6BJ9fCGapAB9cT4
< / code > < / pre >
< p > Record the password above, then run the server start command:< / p >
< pre > < code > cd kanidmd/daemon
cargo run --bin kanidmd server -c ../../examples/insecure_server.toml
< / code > < / pre >
2022-04-29 02:54:36 +02:00
< p > (The server start command is also a script in < code > kanidmd/daemon/run_insecure_dev_server.sh< / code > )< / p >
2022-04-27 13:22:11 +02:00
< p > In a new terminal, you can now build and run the client tools with:< / p >
< pre > < code > cargo run --bin kanidm -- --help
cargo run --bin kanidm -- login -H https://localhost:8443 -D anonymous -C /tmp/kanidm/ca.pem
cargo run --bin kanidm -- self whoami -H https://localhost:8443 -D anonymous -C /tmp/kanidm/ca.pem
cargo run --bin kanidm -- login -H https://localhost:8443 -D admin -C /tmp/kanidm/ca.pem
cargo run --bin kanidm -- self whoami -H https://localhost:8443 -D admin -C /tmp/kanidm/ca.pem
< / code > < / pre >
< h3 id = "building-the-web-ui" > < a class = "header" href = "#building-the-web-ui" > Building the Web UI< / a > < / h3 >
< p > < strong > NOTE:< / strong > There is a pre-packaged version of the Web UI at < code > /kanidmd_web_ui/pkg/< / code > , which can be used directly. This means you don't need to build the Web UI yourself< / p >
< p > The web UI uses rust wasm rather than javascript. To build this you need to set up the environment.< / p >
< pre > < code > cargo install wasm-pack
npm install --global rollup
< / code > < / pre >
< p > Then you are able to build the UI.< / p >
< pre > < code > cd kanidmd_web_ui/
./build_wasm.sh
< / code > < / pre >
< p > The " developer" profile for kanidmd will automatically use the pkg output in this folder.< / p >
< p > Setting different developer profiles while building is done by setting the environment variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in < code > /profiles< / code > . < / p >
< p > For example: < code > KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd< / code > < / p >
2022-05-25 02:46:18 +02:00
< h3 id = "build-a-kanidm-container" > < a class = "header" href = "#build-a-kanidm-container" > Build a kanidm container< / a > < / h3 >
< p > Build a container with the current branch using:< / p >
2022-05-24 07:35:49 +02:00
< pre > < code > make < TARGET>
< / code > < / pre >
< p > Check < code > make help< / code > for a list of valid targets.< / p >
< p > The following environment variables control the build:< / p >
2022-05-25 02:46:18 +02:00
< table > < thead > < tr > < th > ENV variable< / th > < th > Definition< / th > < th > Default< / th > < / tr > < / thead > < tbody >
< tr > < td > < code > IMAGE_BASE< / code > < / td > < td > Base location of the container image.< / td > < td > < code > kanidm< / code > < / td > < / tr >
< tr > < td > < code > IMAGE_VERSION< / code > < / td > < td > Determines the container's tag.< / td > < td > None< / td > < / tr >
< tr > < td > < code > CONTAINER_TOOL_ARGS< / code > < / td > < td > Specify extra options for the container build tool.< / td > < td > None< / td > < / tr >
< tr > < td > < code > IMAGE_ARCH< / code > < / td > < td > Passed to < code > --platforms< / code > when the container is built.< / td > < td > < code > linux/amd64,linux/arm64< / code > < / td > < / tr >
< tr > < td > < code > CONTAINER_BUILD_ARGS< / code > < / td > < td > Override default ARG settings during the container build.< / td > < td > None< / td > < / tr >
< tr > < td > < code > CONTAINER_TOOL< / code > < / td > < td > Use an alternative container build tool.< / td > < td > < code > docker< / code > < / td > < / tr >
< tr > < td > < code > BOOK_VERSION< / code > < / td > < td > Sets version used when building the documentation book.< / td > < td > < code > master< / code > < / td > < / tr >
2022-05-24 07:35:49 +02:00
< / tbody > < / table >
2022-05-25 02:46:18 +02:00
< h4 id = "container-build-examples" > < a class = "header" href = "#container-build-examples" > Container build examples< / a > < / h4 >
< p > Build a < code > kanidm< / code > container using < code > podman< / code > :< / p >
2022-05-24 07:35:49 +02:00
< pre > < code > CONTAINER_TOOL=podman make build/kanidmd
< / code > < / pre >
2022-05-25 02:46:18 +02:00
< p > Build a < code > kanidm< / code > container and use a redis build cache:< / p >
< pre > < code > CONTAINER_BUILD_ARGS='--build-arg " SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379" ' make build/kanidmd
2022-05-24 07:35:49 +02:00
< / code > < / pre >
2022-05-28 00:59:37 +02:00
< h4 id = "automatically-built-containers" > < a class = "header" href = "#automatically-built-containers" > Automatically built containers< / a > < / h4 >
< p > To speed up testing across platforms, we're leveraging GitHub actions to build containers for test use.< / p >
< p > Whenever code is merged with the < code > master< / code > branch of Kanidm, containers are automatically built for < code > kanidmd< / code > and < code > radius< / code > . Sometimes they fail to build, but we'll try and keep them avilable.< / p >
< p > To find information on the packages, < a href = "https://github.com/orgs/kanidm/packages?repo_name=kanidm" > visit the Kanidm packages page here< / a > .< / p >
< p > An example command for pulling and running the radius container is below. You'll need to < a href = "https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry" > authenticate with the GitHub container registry first< / a > .< / p >
< pre > < code class = "language-shell" > docker pull ghcr.io/kanidm/radius:devel
docker run --rm -it \
-v $(pwd)/config.ini:/data/config.ini \
ghcr.io/kanidm/radius:devel
< / code > < / pre >
< p > This assumes you have a < code > config.ini< / code > file in the current working directory.< / p >
2022-04-27 13:22:11 +02:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "why_tls.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "why_tls.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< / body >
< / html >
