mirror of
https://github.com/kanidm/kanidm.git
synced 2025-02-24 13:07:00 +01:00
296 lines
18 KiB
HTML
296 lines
18 KiB
HTML
|
<!DOCTYPE HTML>
|
||
|
|
<html lang="en" class="sidebar-visible no-js light">
|
||
|
|
<head>
|
||
|
|
<!-- Book generated using mdBook -->
|
||
|
|
<meta charset="UTF-8">
|
||
|
|
<title>Server Configuration - 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" class="active"><strong aria-hidden="true">2.</strong> Installing the Server</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="installing_the_server.html" class="active"><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="ldap.html"><strong aria-hidden="true">6.</strong> LDAP</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="why_tls.html"><strong aria-hidden="true">9.</strong> Why TLS?</a></li><li class="chapter-item expanded "><a href="DEVELOPER_README.html"><strong aria-hidden="true">10.</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>
|
||
|
|
<h1 id="installing-the-server"><a class="header" href="#installing-the-server">Installing the Server</a></h1>
|
||
|
|
<blockquote>
|
||
|
|
<p><strong>NOTE</strong> Our preferred deployment method is in containers, the documentation assumes you're running in docker. Kanidm will run in traditional compute, and server builds are available for multiple platforms or you can build the binaries yourself.</p>
|
||
|
|
</blockquote>
|
||
|
|
<p>Currently we have docker images for the server components. They can be found at:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a href="https://hub.docker.com/r/kanidm/server">https://hub.docker.com/r/kanidm/server</a></li>
|
||
|
|
<li><a href="https://hub.docker.com/r/kanidm/radius">https://hub.docker.com/r/kanidm/radius</a></li>
|
||
|
|
</ul>
|
||
|
|
<p>You can fetch these by running the commands:</p>
|
||
|
|
<pre><code>docker pull kanidm/server:latest
|
||
|
|
docker pull kanidm/radius:latest
|
||
|
|
</code></pre>
|
||
|
|
<p>If you wish to use an x86_64 cpu-optimised version (See System Requirements CPU), you should use:</p>
|
||
|
|
<pre><code>docker pull kanidm/server:x86_64_latest
|
||
|
|
</code></pre>
|
||
|
|
<p>You may need to adjust your example commands throughout this document to suit.</p>
|
||
|
|
<h2 id="development-version"><a class="header" href="#development-version">Development Version</a></h2>
|
||
|
|
<p>If you are interested in running the latest code from development, you can do this by changing the
|
||
|
|
docker tag to <code>kanidm/server:devel</code> or <code>kanidm/server:x86_64_v3_devel</code> instead.</p>
|
||
|
|
<h2 id="system-requirements"><a class="header" href="#system-requirements">System Requirements</a></h2>
|
||
|
|
<h4 id="cpu"><a class="header" href="#cpu">CPU</a></h4>
|
||
|
|
<p>If you are using the x86_64 cpu-optimised version, you must have a CPU that is from 2013 or newer
|
||
|
|
(Haswell, Ryzen). The following instruction flags are used.</p>
|
||
|
|
<pre><code>cmov, cx8, fxsr, mmx, sse, sse2, cx16, sahf, popcnt, sse3, sse4.1, sse4.2, avx, avx2,
|
||
|
|
bmi, bmi2, f16c, fma, lzcnt, movbe, xsave
|
||
|
|
</code></pre>
|
||
|
|
<p>Older or unsupported CPU's may raise a SIGIL (Illegal Instruction) on hardware that is not supported
|
||
|
|
by the project.</p>
|
||
|
|
<p>In this case, you should use the standard server:latest image.</p>
|
||
|
|
<p>In the future we may apply a baseline of flags as a requirement for x86_64 for the server:latest
|
||
|
|
image. These flags will be:</p>
|
||
|
|
<pre><code>cmov, cx8, fxsr, mmx, sse, sse2
|
||
|
|
</code></pre>
|
||
|
|
<h4 id="memory"><a class="header" href="#memory">Memory</a></h4>
|
||
|
|
<p>Kanidm extensively uses memory caching, trading memory consumption to improve parallel throughput.
|
||
|
|
You should expect to see 64KB of ram per entry in your database, depending on cache tuning and settings.</p>
|
||
|
|
<h4 id="disk"><a class="header" href="#disk">Disk</a></h4>
|
||
|
|
<p>You should expect to use up to 8KB of disk per entry you plan to store. At an estimate 10,000 entry
|
||
|
|
databases will consume 40MB, 100,000 entry will consume 400MB.</p>
|
||
|
|
<p>For best performance, you should use NVME or other Flash media.</p>
|
||
|
|
<h2 id="tls"><a class="header" href="#tls">TLS</a></h2>
|
||
|
|
<p>You'll need a volume where you can place configuration, certificates, and the database:</p>
|
||
|
|
<pre><code>docker volume create kanidmd
|
||
|
|
</code></pre>
|
||
|
|
<p>You should have a chain.pem and key.pem in your kanidmd volume. The reason for requiring
|
||
|
|
TLS is explained in <a href="./why_tls.html">why tls</a>. In summary, TLS is our root of trust between the
|
||
|
|
server and clients, and a critical element of ensuring a secure system.</p>
|
||
|
|
<p>The key.pem should be a single PEM private key, with no encryption. The file content should be
|
||
|
|
similar to:</p>
|
||
|
|
<pre><code>-----BEGIN RSA PRIVATE KEY-----
|
||
|
|
MII...<base64>
|
||
|
|
-----END RSA PRIVATE KEY-----
|
||
|
|
</code></pre>
|
||
|
|
<p>The chain.pem is a series of PEM formatted certificates. The leaf certificate, or the certificate
|
||
|
|
that matches the private key should be the first certificate in the file. This should be followed
|
||
|
|
by the series of intermediates, and the final certificate should be the CA root. For example:</p>
|
||
|
|
<pre><code>-----BEGIN CERTIFICATE-----
|
||
|
|
<leaf certificate>
|
||
|
|
-----END CERTIFICATE-----
|
||
|
|
-----BEGIN CERTIFICATE-----
|
||
|
|
<intermediate certificate>
|
||
|
|
-----END CERTIFICATE-----
|
||
|
|
[ more intermediates if needed ]
|
||
|
|
-----BEGIN CERTIFICATE-----
|
||
|
|
<ca/croot certificate>
|
||
|
|
-----END CERTIFICATE-----
|
||
|
|
</code></pre>
|
||
|
|
<blockquote>
|
||
|
|
<p><strong>HINT</strong>
|
||
|
|
If you are using Let's Encrypt the provided files "fullchain.pem" and "privkey.pem" are already
|
||
|
|
correctly formatted as required for Kanidm.</p>
|
||
|
|
</blockquote>
|
||
|
|
<p>You can validate that the leaf certificate matches the key with the command:</p>
|
||
|
|
<pre><code># openssl rsa -noout -modulus -in key.pem | openssl sha1
|
||
|
|
d2188932f520e45f2e76153fbbaf13f81ea6c1ef
|
||
|
|
# openssl x509 -noout -modulus -in chain.pem | openssl sha1
|
||
|
|
d2188932f520e45f2e76153fbbaf13f81ea6c1ef
|
||
|
|
</code></pre>
|
||
|
|
<p>If your chain.pem contains the CA certificate, you can validate this file with the command:</p>
|
||
|
|
<pre><code>openssl verify -CAfile chain.pem chain.pem
|
||
|
|
</code></pre>
|
||
|
|
<p>If your chain.pem does not contain the CA certificate (Let's Encrypt chains do not contain the CA
|
||
|
|
for example) then you can validate with this command.</p>
|
||
|
|
<pre><code>openssl verify -untrusted fullchain.pem fullchain.pem
|
||
|
|
</code></pre>
|
||
|
|
<blockquote>
|
||
|
|
<p><strong>NOTE</strong> Here "-untrusted" flag means a list of further certificates in the chain to build up
|
||
|
|
to the root is provided, but that the system CA root should be consulted. Verification is NOT bypassed
|
||
|
|
or allowed to be invalid.</p>
|
||
|
|
</blockquote>
|
||
|
|
<p>If these verifications pass you can now use these certificates with Kanidm. To put the certificates
|
||
|
|
in place you can use a shell container that mounts the volume such as:</p>
|
||
|
|
<pre><code>docker run --rm -i -t -v kanidmd:/data -v /my/host/path/work:/work opensuse/leap:latest /bin/sh -c "cp /work/* /data/"
|
||
|
|
</code></pre>
|
||
|
|
<p>OR for a shell into the volume:</p>
|
||
|
|
<pre><code>docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
|
||
|
|
</code></pre>
|
||
|
|
<h1 id="continue-on-to-a-hrefserver_configurationhtmlconfiguring-the-servera"><a class="header" href="#continue-on-to-a-hrefserver_configurationhtmlconfiguring-the-servera">Continue on to <a href="server_configuration.html">Configuring the Server</a></a></h1>
|
||
|
|
|
||
|
|
</main>
|
||
|
|
|
||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
|
|
<!-- Mobile navigation buttons -->
|
||
|
|
<a rel="prev" href="intro.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="installing_the_server.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="intro.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="installing_the_server.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 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>
|