78 lines
5.5 KiB
HTML
78 lines
5.5 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Troubleshooting — Keru OS</title>
|
|
<meta name="description" content="Common Keru problems by stage — live boot, network, fetch, build, install, first boot — and how to fix each.">
|
|
<link rel="stylesheet" href="assets/css/style.css">
|
|
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>ける</text></svg>">
|
|
</head>
|
|
<body>
|
|
|
|
<nav class="top" data-nav></nav>
|
|
|
|
<header class="pagehead">
|
|
<p class="crumbs"><a href="index.html">home</a> / <a href="docs.html">docs</a> / troubleshooting</p>
|
|
<h1>Troubleshooting</h1>
|
|
<p>Diagnose by stage. The stage points at the file to blame.</p>
|
|
</header>
|
|
|
|
<section>
|
|
<div class="wrap">
|
|
<div class="prose">
|
|
<p>Almost every Keru failure lands in exactly one of five stages: <strong>live boot</strong>, <strong>network</strong>, <strong>fetch</strong>, <strong>build</strong>, or <strong>finalize</strong>. Figure out which, and you're most of the way to a fix.</p>
|
|
|
|
<h3>Live boot</h3>
|
|
<table>
|
|
<tr><th>Symptom</th><th>Cause / fix</th></tr>
|
|
<tr><td>Drops to an emergency shell</td><td><code>live/init</code> couldn't find the installer payload or mount buffers. Check the ISO layout and that you wrote the whole image, not just the files.</td></tr>
|
|
<tr><td>Installer never auto-starts</td><td>The live init runs <code>installer/install.sh</code> on boot. Run it by hand from the shell to see its errors directly.</td></tr>
|
|
<tr><td>Nothing on screen</td><td>Terminal TTY not your display? Verify the kernel picks your console; a plain <code>getty</code> on tty1 is the default.</td></tr>
|
|
</table>
|
|
|
|
<h3>Network</h3>
|
|
<ul class="features">
|
|
<li><strong>Installer says offline.</strong> It probes several hosts (<code>1.1.1.1</code>, <code>github.com</code>) and loops: it will offer to run <code>nmtui</code>, then re-check. Let it. GitHub reachability matters — package recipes are fetched from GitHub.</li>
|
|
<li><strong>DHCP won't bite.</strong> Use <code>nmtui</code> and set a static address. The installer doesn't care how the link comes up, only that it does.</li>
|
|
<li><strong>Slow fetch.</strong> When <code>SOURCE_MIRROR</code> is set it's tried first; upstream is the fallback. A broken mirror yields timeouts — fix or unset <code>SOURCE_MIRROR</code>.</li>
|
|
</ul>
|
|
|
|
<h3>Fetch</h3>
|
|
<ul class="features">
|
|
<li><strong>404 on a download.</strong> The recipe's <code>url</code> missed a version bump. Fix it or report it — sources are pinned in kama-packages.</li>
|
|
<li><strong>Checksum mismatch.</strong> The tarball in the cache doesn't match the recipe. Clear the cache dir for that package: <code>rm -rf /var/cache/kama/dl/<pkg></code>.</li>
|
|
<li><strong>Mirror poison.</strong> If a third-party mirror serves a tampered file, fetch fails verification and refuses to proceed — by design.</li>
|
|
</ul>
|
|
|
|
<h3>Build</h3>
|
|
<table>
|
|
<tr><th>Symptom</th><th>Cause / fix</th></tr>
|
|
<tr><td>Compile error in a package</td><td>Often a <code>C(FLAGS)</code> interaction or a missing build dep. Add the dep and re-run <code>kama make</code> — stage dirs cache progress.</td></tr>
|
|
<tr><td>Missing header</td><td>That's a temp-dep gap in the recipe's <code>deps=()</code>. Contribute the fix: one line in kama-packages.</td></tr>
|
|
<tr><td>Toolchain failure</td><td>Stage 0 is the sharpest edge. A failing binutils/gcc/libc bootstrap is a bug — file it with the full <code>make.conf</code> combo.</td></tr>
|
|
<tr><td>Kernel build dies with no reason</td><td>Free disk or memory on the build host first; kernel builds are hungry. Then check <code>KERNEL_CONFIG</code> in make.conf.</td></tr>
|
|
</table>
|
|
|
|
<h3>Finalize and first boot</h3>
|
|
<ul class="features">
|
|
<li><strong>mkfs fails.</strong> The target device is in use or the filesystem tools for your pick are missing. Unmount and retry.</li>
|
|
<li><strong>Won't boot.</strong> The init you chose must agree with how your bootloader was told to run it — check the boot command line and your init's expectations.</li>
|
|
<li><strong>No network after boot.</strong> Your network tool choice (nmtui alone won't auto-connect) needs to be started on <code>default</code> runlevel or its service enabled.</li>
|
|
<li><strong>Unstable combo.</strong> Keru warns on unproven pairs (musl+systemd, uclibc-ng, zfs root ...). Heed the warning or expect rough edges. It never blocks you.</li>
|
|
</ul>
|
|
|
|
<div class="callout">When you file an issue, include the stage, your full <code>make.conf</code> combo, and the failing output. That's everything a maintainer needs. See <a href="contact.html">contact</a>.</div>
|
|
|
|
<p><a href="getting-started.html">← Getting started</a> · <a href="security.html">Security model →</a></p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<footer data-footer></footer>
|
|
|
|
<noscript><div style="text-align:center;padding:16px">See the <a href="sitemap.html">sitemap</a> for all pages.</div></noscript>
|
|
|
|
<script src="assets/js/include.js" data-base="."></script>
|
|
</body>
|
|
</html> |