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 > Developer Guide - 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" > < 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 = "examples/k8s_ingress_example.html" > < strong aria-hidden = "true" > 12.< / strong > Kubernetes Ingress< / a > <
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/DEVELOPER_README.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 >
< h2 id = "getting-started-for-developers" > < a class = "header" href = "#getting-started-for-developers" > Getting Started (for Developers)< / a > < / h2 >
2023-03-02 14:07:28 +01:00
< h3 id = "setup-the-server" > < a class = "header" href = "#setup-the-server" > Setup the Server< / a > < / h3 >
< p > It's important before you start trying to write code and contribute that you understand what Kanidm
does and its goals.< / p >
< p > An important first step is to < a href = "installing_the_server.html" > install the server< / a > so if you have not done
that yet, go and try that now! 😄< / p >
< h3 id = "setting-up-your-machine" > < a class = "header" href = "#setting-up-your-machine" > Setting up your Machine< / a > < / h3 >
< p > Each operating system has different steps required to configure and build Kanidm.< / p >
2022-12-29 04:22:16 +01:00
< h4 id = "macos" > < a class = "header" href = "#macos" > MacOS< / a > < / h4 >
2023-03-02 14:07:28 +01:00
< p > A prerequisite is < a href = "https://apps.apple.com/au/app/xcode/id497799835?mt=12" > Apple Xcode< / a > for access to
git and compiler tools. You should install this first.< / p >
2022-12-29 04:22:16 +01:00
< p > You will need < a href = "https://rustup.rs/" > rustup< / a > to install a Rust toolchain.< / p >
2023-03-02 14:07:28 +01:00
< h4 id = "suse--opensuse" > < a class = "header" href = "#suse--opensuse" > SUSE / OpenSUSE< / a > < / h4 >
< p > You will need to install rustup and our build dependencies with:< / p >
< pre > < code class = "language-bash" > zypper in rustup git libudev-devel sqlite3-devel libopenssl-3-devel
2022-12-29 04:22:16 +01:00
< / code > < / pre >
2023-03-02 14:07:28 +01:00
< p > You can then use rustup to complete the setup of the toolchain.< / p >
2022-12-29 04:22:16 +01:00
< h4 id = "fedora" > < a class = "header" href = "#fedora" > Fedora< / a > < / h4 >
2023-03-02 14:07:28 +01:00
< p > You will need < a href = "https://rustup.rs/" > rustup< / a > to install a Rust toolchain.< / p >
2022-12-29 04:22:16 +01:00
< p > You will also need some system libraries to build this:< / p >
2023-02-28 02:55:48 +01:00
< pre > < code class = "language-text" > systemd-devel sqlite-devel openssl-devel pam-devel
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > Building the Web UI requires additional packages:< / p >
2023-03-02 14:07:28 +01:00
< pre > < code class = "language-text" > perl-FindBin perl-File-Compare
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< h4 id = "ubuntu" > < a class = "header" href = "#ubuntu" > Ubuntu< / a > < / h4 >
< p > You 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, which can be installed by running:< / p >
< pre > < code class = "language-bash" > sudo apt-get install libsqlite3-dev libudev-dev libssl-dev pkg-config libpam0g-dev
< / code > < / pre >
< p > Tested with Ubuntu 20.04 and 22.04.< / p >
< h4 id = "windows" > < a class = "header" href = "#windows" > Windows< / a > < / h4 >
2023-03-02 14:07:28 +01:00
<!-- deno - fmt - ignore - start -->
2023-05-05 13:23:43 +02:00
< p > {{#template templates/kani-warning.md
imagepath=images
title=NOTICE
text=Our support for Windows is still in development, so you may encounter some compilation or build issues.
}}< / p >
2023-03-02 14:07:28 +01:00
<!-- deno - fmt - ignore - end -->
2022-12-29 04:22:16 +01:00
< p > You need < a href = "https://rustup.rs/" > rustup< / a > to install a Rust toolchain.< / p >
< p > An easy way to grab the dependencies is to install
< a href = "https://vcpkg.io/en/getting-started.html" > vcpkg< / a > .< / p >
< p > This is how it works in the automated build:< / p >
< ol >
< li > Enable use of installed packages for the user system-wide:< / li >
< / ol >
< pre > < code class = "language-bash" > vcpkg integrate install
< / code > < / pre >
< ol start = "2" >
< li > Install the openssl dependency, which compiles it from source. This downloads all sorts of
dependencies, including perl for the build.< / li >
< / ol >
< pre > < code class = "language-bash" > vcpkg install openssl:x64-windows-static-md
< / code > < / pre >
< p > There's a powershell script in the root directory of the repository which, in concert with < code > openssl< / code >
will generate a config file and certs for testing.< / p >
2023-03-02 14:07:28 +01:00
< h3 id = "getting-the-source-code" > < a class = "header" href = "#getting-the-source-code" > Getting the Source Code< / a > < / h3 >
2022-12-29 04:22:16 +01: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 pull requests.< / p >
2023-03-02 14:07:28 +01:00
< p > Kanidm is (largely) a monorepo. This can be checked out with:< / p >
2022-12-29 04:22:16 +01:00
< pre > < code class = "language-bash" > git clone https://github.com/kanidm/kanidm.git
cd kanidm
2023-03-02 14:07:28 +01:00
< / code > < / pre >
< p > Other supporting projects can be found on the < a href = "https://github.com/kanidm" > project github< / a > < / p >
< p > If you are forking, then fork in GitHub and then add your remote.< / p >
< pre > < code class = "language-bash" > git remote add myfork git@github.com:< YOUR USERNAME> /kanidm.git
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > Select an issue (always feel free to reach out to us for advice!), and create a branch to start
working:< / p >
< pre > < code class = "language-bash" > git branch < feature-branch-name>
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 >
< ol >
2023-03-02 14:07:28 +01:00
< li > Run the test suite: < code > cargo test< / code > < / li >
2022-12-29 04:22:16 +01:00
< 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-bash" > git commit -m 'Commit message' change_file.rs ...
2023-03-02 14:07:28 +01:00
git push < myfork> < feature-branch-name>
2022-12-29 04:22:16 +01:00
< / code > < / pre >
2023-01-10 05:08:56 +01:00
< p > If you receive advice or make further changes, just keep committing to the branch, and pushing to
2022-12-29 04:22:16 +01:00
your branch. When we are happy with the code, we'll merge in GitHub, meaning you can now clean up
your branch.< / p >
< pre > < code class = "language-bash" > git checkout master
git pull
git branch -D < feature-branch-name>
< / code > < / pre >
< h4 id = "rebasing" > < a class = "header" href = "#rebasing" > Rebasing< / a > < / h4 >
< p > If you are asked to rebase your change, follow these steps:< / p >
< pre > < code class = "language-bash" > 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 class = "language-bash" > git rebase --abort
< / code > < / pre >
2023-03-02 14:07:28 +01:00
< h3 id = "building-the-book" > < a class = "header" href = "#building-the-book" > Building the Book< / a > < / h3 >
< p > You'll need < code > mdbook< / code > to build the book:< / p >
< pre > < code class = "language-bash" > cargo install mdbook
< / code > < / pre >
< p > To build it:< / p >
< pre > < code class = "language-bash" > make book
< / code > < / pre >
< p > Or to run a local webserver:< / p >
< pre > < code class = "language-bash" > cd book
mdbook serve
< / code > < / pre >
< h3 id = "designs" > < a class = "header" href = "#designs" > Designs< / a > < / h3 >
< p > See the " Design Documents" section of this book.< / p >
< h3 id = "rust-documentation" > < a class = "header" href = "#rust-documentation" > Rust Documentation< / a > < / h3 >
< p > A list of links to the library documentation is at
< a href = "https://kanidm.com/documentation/" > kanidm.com/documentation< / a > .< / p >
< h3 id = "advanced" > < a class = "header" href = "#advanced" > Advanced< / a > < / h3 >
< h4 id = "minimum-supported-rust-version" > < a class = "header" href = "#minimum-supported-rust-version" > Minimum Supported Rust Version< / a > < / h4 >
< p > The MSRV is specified in the package < code > Cargo.toml< / code > files.< / p >
< p > We tend to be quite proactive in updating this to recent rust versions so we are open to increasing
this value if required!< / p >
< h4 id = "build-profiles" > < a class = "header" href = "#build-profiles" > Build Profiles< / a > < / h4 >
< p > Build profiles allow us to change the operation of Kanidm during it's compilation for development or
release on various platforms. By default the " developer" profile is used that assumes the correct
relative paths within the monorepo.< / p >
< p > Setting different developer profiles while building is done by setting the environment variable
< code > KANIDM_BUILD_PROFILE< / code > to one of the bare filename of the TOML files in < code > /profiles< / code > .< / p >
< p > For example, this will set the CPU flags to " none" and the location for the Web UI files to
< code > /usr/share/kanidm/ui/pkg< / code > :< / p >
< pre > < code class = "language-bash" > KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd
< / code > < / pre >
< h4 id = "building-the-web-ui" > < a class = "header" href = "#building-the-web-ui" > Building the Web UI< / a > < / h4 >
< p > < strong > NOTE:< / strong > There is a pre-packaged version of the Web UI at < code > /server/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 WebAssembly rather than Javascript. To build this you need to set up the
environment:< / p >
< pre > < code class = "language-bash" > cargo install wasm-pack
< / code > < / pre >
< p > Then you are able to build the UI:< / p >
< pre > < code class = "language-bash" > cd server/web_ui/
./build_wasm_dev.sh
< / code > < / pre >
< p > To build for release, run < code > build_wasm_release.sh< / code > .< / p >
< p > The " developer" profile for kanidmd will automatically use the pkg output in this folder.< / p >
< h4 id = "development-server-for-interactive-testing" > < a class = "header" href = "#development-server-for-interactive-testing" > Development Server for Interactive Testing< / a > < / h4 >
< p > Especially if you wish to develop the WebUI then the ability to run the server from the source tree
is critical.< / p >
2022-12-29 04:22:16 +01:00
< p > Once you have the source code, you need encryption 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
2023-03-02 14:07:28 +01:00
our insecure certificate tool (< code > scripts/insecure_generate_tls.sh< / code > ). The insecure certificate tool
creates < code > /tmp/kanidm< / code > and puts some self-signed certificates there.< / p >
< p > < strong > NOTE:< / strong > Windows developers can use < code > scripts/insecure_generate_tls.ps1< / code > , which puts everything
(including a templated config file) in < code > $TEMP\kanidm< / code > . Please adjust paths below to suit.< / p >
2022-12-29 04:22:16 +01:00
< 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 >
2023-03-02 14:07:28 +01:00
< p > Create the initial database and generate an < code > admin< / code > password:< / p >
< pre > < code class = "language-bash" > cd server/daemon
./run_insecure_dev_server.sh recover-account admin
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > Record the password above, then run the server start command:< / p >
2023-03-02 14:07:28 +01:00
< pre > < code class = "language-bash" > ./run_insecure_dev_server.sh
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > In a new terminal, you can now build and run the client tools with:< / p >
< pre > < code class = "language-bash" > 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 >
2023-03-02 14:07:28 +01:00
< p > You may find it easier to modify < code > ~/.config/kanidm< / code > per the
< a href = "client_tools.html" > book client tools section< / a > for extended administration locally.< / p >
< h4 id = "raw-actions" > < a class = "header" href = "#raw-actions" > Raw actions< / a > < / h4 >
<!-- deno - fmt - ignore - start -->
2023-05-05 13:23:43 +02:00
< p > {{#template templates/kani-warning.md
imagepath=images
title=NOTICE
text=It's not recommended to use these tools outside of extremely complex or advanced development requirements. These are a last resort!
}}< / p >
2023-03-02 14:07:28 +01:00
<!-- deno - fmt - ignore - end -->
2022-12-29 04:22:16 +01:00
< p > The server has a low-level stateful API you can use for more complex or advanced tasks on large
numbers of entries at once. Some examples are below, but generally we advise you to use the APIs or
CLI tools. These are very handy to " unbreak" something if you make a mistake however!< / p >
< pre > < code class = "language-bash" > # Create from json (group or account)
kanidm raw create -H https://localhost:8443 -C ../insecure/ca.pem -D admin example.create.account.json
kanidm raw create -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin example.create.group.json
# Apply a json stateful modification to all entries matching a filter
kanidm raw modify -H https://localhost:8443 -C ../insecure/ca.pem -D admin '{" or" : [ {" eq" : [" name" , " idm_person_account_create_priv" ]}, {" eq" : [" name" , " idm_service_account_create_priv" ]}, {" eq" : [" name" , " idm_account_write_priv" ]}, {" eq" : [" name" , " idm_group_write_priv" ]}, {" eq" : [" name" , " idm_people_write_priv" ]}, {" eq" : [" name" , " idm_group_create_priv" ]} ]}' example.modify.idm_admin.json
kanidm raw modify -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin '{" eq" : [" name" , " idm_admins" ]}' example.modify.idm_admin.json
# Search and show the database representations
kanidm raw search -H https://localhost:8443 -C ../insecure/ca.pem -D admin '{" eq" : [" name" , " idm_admin" ]}'
# Delete all entries matching a filter
kanidm raw delete -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin '{" eq" : [" name" , " test_account_delete_me" ]}'
< / code > < / pre >
2023-03-02 14:07:28 +01:00
< h4 id = "build-a-kanidm-container" > < a class = "header" href = "#build-a-kanidm-container" > Build a Kanidm Container< / a > < / h4 >
2022-12-29 04:22:16 +01:00
< p > Build a container with the current branch using:< / p >
< pre > < code class = "language-bash" > 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 >
< div class = "table-wrapper" > < 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 >
< / tbody > < / table >
< / div >
2023-03-02 14:07:28 +01:00
< h5 id = "container-build-examples" > < a class = "header" href = "#container-build-examples" > Container Build Examples< / a > < / h5 >
2022-12-29 04:22:16 +01:00
< p > Build a < code > kanidm< / code > container using < code > podman< / code > :< / p >
< pre > < code class = "language-bash" > CONTAINER_TOOL=podman make build/kanidmd
< / code > < / pre >
< p > Build a < code > kanidm< / code > container and use a redis build cache:< / p >
< pre > < code class = "language-bash" > CONTAINER_BUILD_ARGS='--build-arg " SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379" ' make build/kanidmd
< / code > < / pre >
2023-03-02 14:07:28 +01:00
< h5 id = "automatically-built-containers" > < a class = "header" href = "#automatically-built-containers" > Automatically Built Containers< / a > < / h5 >
2022-12-29 04:22:16 +01:00
< 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
2023-01-10 05:08:56 +01:00
< code > kanidmd< / code > and < code > radius< / code > . Sometimes they fail to build, but we'll try to keep them available.< / p >
2022-12-29 04:22:16 +01:00
< p > To find information on the packages,
< a href = "https://github.com/orgs/kanidm/packages?repo_name=kanidm" > visit the Kanidm packages page< / 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-bash" > docker pull ghcr.io/kanidm/radius:devel
docker run --rm -it \
-v $(pwd)/kanidm:/data/kanidm \
ghcr.io/kanidm/radius:devel
< / code > < / pre >
< p > This assumes you have a < code > kanidm< / code > client configuration file in the current working directory.< / p >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2023-03-02 04:03:10 +01:00
< a rel = "prev" href = "glossary.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2022-12-29 04:22:16 +01:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2023-03-02 04:03:10 +01:00
< a rel = "next" href = "developers/faq.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2022-12-29 04:22:16 +01:00
< 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" >
2023-03-02 04:03:10 +01:00
< a rel = "prev" href = "glossary.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2022-12-29 04:22:16 +01:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2023-03-02 04:03:10 +01:00
< a rel = "next" href = "developers/faq.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2022-12-29 04:22:16 +01:00
< 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 >
