CloudNebulaProject/refraction-forger
1
0
Fork 0
mirror of https://github.com/CloudNebulaProject/refraction-forger.git synced 2026-04-10 21:30:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add mdbook documentation for image developers

Browse source 
Complete guide covering KDL spec language, composability (base/include/profiles),
distro support (OmniOS primary, Ubuntu secondary), output formats (QCOW2/OCI/tar),
architecture, CLI reference, and migration guides from omnios-image-builder and Packer.
This commit is contained in:
Till Wegmueller 2026-04-09 21:17:22 +02:00
parent 86c645f7ff
commit 38b359e382
111 changed files with 23912 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
book/book.toml Normal file
View file

@ -0,0 +1,5 @@
[book]
authors = ["Till Wegmueller"]
language = "en"
src = "src"
title = "Refraction Forger"

1
book/book/.nojekyll Normal file
View file

@ -0,0 +1 @@
This file makes sure that Github Pages doesn't process mdBook's output.

221
book/book/404.html Normal file
View file

@ -0,0 +1,221 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Page not found - Refraction Forger</title>
<base href="/">
<!-- 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="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" id="highlight-css" href="highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="document-not-found-404"><a class="header" href="#document-not-found-404">Document not found (404)</a></h1>
<p>This URL is invalid, sorry. Please use the navigation bar or search to continue.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</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 -->
</div>
</body>
</html>

4
book/book/FontAwesome/css/font-awesome.css vendored Normal file
View file

File diff suppressed because one or more lines are too long

BIN
book/book/FontAwesome/fonts/FontAwesome.ttf Normal file
View file

Binary file not shown.

BIN
book/book/FontAwesome/fonts/fontawesome-webfont.eot Normal file
View file

Binary file not shown.

2671
book/book/FontAwesome/fonts/fontawesome-webfont.svg Normal file
View file

File diff suppressed because it is too large Load diff
Side by side

After

Width:  |  Height:  |  Size: 434 KiB

BIN
book/book/FontAwesome/fonts/fontawesome-webfont.ttf Normal file
View file

Binary file not shown.

BIN
book/book/FontAwesome/fonts/fontawesome-webfont.woff Normal file
View file

Binary file not shown.

BIN
book/book/FontAwesome/fonts/fontawesome-webfont.woff2 Normal file
View file

Binary file not shown.

328
book/book/architecture/builder-vm.html Normal file
View file

@ -0,0 +1,328 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Remote Builder VMs - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="remote-builder-vms"><a class="header" href="#remote-builder-vms">Remote Builder VMs</a></h1>
<p>When the build host doesn't match the target OS, Forger delegates to an ephemeral builder VM. This chapter explains the internals.</p>
<h2 id="lifecycle"><a class="header" href="#lifecycle">Lifecycle</a></h2>
<pre><code>1. Image Resolution
├── OCI reference → pull from registry
├── URL → download
└── Local path → use directly
2. Cloud-Init Generation
├── Generate ephemeral Ed25519 SSH keypair
├── Create user-data: builder user, SSH key, passwordless sudo
└── Create cloud-init ISO
3. VM Creation
├── Create VmSpec (CPU, memory, disk, network)
├── Network: user-mode (SLIRP) — no root required
├── Disk: overlay on builder image (20GB default)
└── Hypervisor: auto-detect via vm-manager
4. Boot &amp; Connect
├── Start VM via hypervisor
└── SSH retry loop (up to 120 seconds)
5. Transfer
├── Upload forger binary via SCP
├── Upload spec files via SCP
└── Upload overlay files via SCP
6. Build
└── Execute forger build command via SSH
7. Download
└── Retrieve artifacts via SCP
8. Teardown (guaranteed, even on failure)
└── Destroy VM via hypervisor
</code></pre>
<h2 id="user-mode-networking"><a class="header" href="#user-mode-networking">User-Mode Networking</a></h2>
<p>Builder VMs use QEMU's user-mode networking (SLIRP). This means:</p>
<ul>
<li><strong>No root access</strong> needed on the host</li>
<li><strong>No bridge interfaces</strong> to configure</li>
<li><strong>No firewall rules</strong> to manage</li>
<li>Guest can access the internet through NAT</li>
<li>Host communicates with guest via port forwarding</li>
</ul>
<p>DNS is automatically configured if needed.</p>
<h2 id="security-model"><a class="header" href="#security-model">Security Model</a></h2>
<ul>
<li>SSH keys are <strong>ephemeral</strong> — generated per build, discarded after</li>
<li>The builder user has <strong>passwordless sudo</strong> but only exists for the build duration</li>
<li>The VM is <strong>destroyed</strong> after every build, even on failure</li>
<li>No persistent state from previous builds leaks into new ones</li>
</ul>
<h2 id="custom-builder-images"><a class="header" href="#custom-builder-images">Custom Builder Images</a></h2>
<p>Builder images are QCOW2 files with cloud-init support. To create your own:</p>
<ol>
<li>Build a base image with Forger (or any tool)</li>
<li>Ensure <code>cloud-init</code> is installed and enabled</li>
<li>Ensure SSH server is running</li>
<li>Include all build dependencies (<code>pkg</code>, <code>qemu-img</code>, <code>zfs</code>, etc.)</li>
<li>Push to an OCI registry or host as a downloadable file</li>
</ol>
<h3 id="minimum-requirements-for-a-builder-image"><a class="header" href="#minimum-requirements-for-a-builder-image">Minimum Requirements for a Builder Image</a></h3>
<ul>
<li>Cloud-init (for SSH key injection and user setup)</li>
<li>SSH server</li>
<li>The target distro's package manager</li>
<li><code>qemu-img</code> (for QCOW2 conversion)</li>
<li>Filesystem tools (<code>zfs</code>/<code>zpool</code> for ZFS, <code>parted</code>/<code>mkfs.ext4</code> for ext4)</li>
<li>Bootloader tools (GRUB, UEFI support)</li>
</ul>
<h2 id="disk-overlay"><a class="header" href="#disk-overlay">Disk Overlay</a></h2>
<p>The builder VM uses a disk overlay (copy-on-write layer) on top of the builder image. This means:</p>
<ul>
<li>The original builder image is never modified</li>
<li>The overlay provides additional working space (20GB by default)</li>
<li>Multiple builds can run concurrently from the same builder image</li>
</ul>
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<h3 id="vm-fails-to-boot"><a class="header" href="#vm-fails-to-boot">VM Fails to Boot</a></h3>
<ul>
<li>Check that the builder image has cloud-init enabled</li>
<li>Verify QEMU is installed and accessible</li>
<li>Check system resources (enough RAM and disk for the VM)</li>
</ul>
<h3 id="ssh-connection-times-out"><a class="header" href="#ssh-connection-times-out">SSH Connection Times Out</a></h3>
<ul>
<li>The 120-second timeout may be insufficient for slow storage</li>
<li>Check that the builder image's SSH server starts on boot</li>
<li>Verify user-mode networking isn't blocked by firewall</li>
</ul>
<h3 id="build-fails-inside-vm"><a class="header" href="#build-fails-inside-vm">Build Fails Inside VM</a></h3>
<ul>
<li>The error output from the remote build is captured and displayed</li>
<li>Check that the builder image has all required tools installed</li>
<li>For disk space issues, increase the disk overlay size in the builder config</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../architecture/crates.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 prefetch" href="../migration/from-image-builder.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="../architecture/crates.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 prefetch" href="../migration/from-image-builder.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 -->
</div>
</body>
</html>

330
book/book/architecture/crates.html Normal file
View file

@ -0,0 +1,330 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Crate Structure - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="crate-structure"><a class="header" href="#crate-structure">Crate Structure</a></h1>
<p>Forger is a Cargo workspace with five crates, each with a clear responsibility.</p>
<h2 id="workspace-layout"><a class="header" href="#workspace-layout">Workspace Layout</a></h2>
<pre><code>crates/
├── forger/ CLI entry point
├── spec-parser/ KDL parsing and resolution
├── forge-engine/ Build execution (Phase 1 + Phase 2)
├── forge-builder/ Remote VM builds
└── forge-oci/ OCI image and registry operations
</code></pre>
<h2 id="forger-cli"><a class="header" href="#forger-cli">forger (CLI)</a></h2>
<p>The binary crate. Defines five subcommands via clap:</p>
<div class="table-wrapper"><table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody>
<tr><td><code>build</code></td><td>Build image from spec</td></tr>
<tr><td><code>validate</code></td><td>Parse and check a spec</td></tr>
<tr><td><code>inspect</code></td><td>Show resolved, profile-filtered spec</td></tr>
<tr><td><code>push</code></td><td>Push artifact to OCI registry</td></tr>
<tr><td><code>targets</code></td><td>List targets in a spec</td></tr>
</tbody></table>
</div>
<p>This crate is thin — it parses CLI arguments and delegates to the library crates.</p>
<h2 id="spec-parser"><a class="header" href="#spec-parser">spec-parser</a></h2>
<p>Handles everything related to KDL spec files:</p>
<ul>
<li><strong>Parsing</strong>: Uses the <code>knuffel</code> crate to deserialize KDL into Rust structs (<code>ImageSpec</code>, <code>Target</code>, <code>Package</code>, etc.)</li>
<li><strong>Resolution</strong>: Recursively resolves <code>base</code> and <code>include</code> references, merging specs while detecting circular dependencies</li>
<li><strong>Profile filtering</strong>: Removes conditional blocks that don't match active profiles</li>
</ul>
<p>Key types:</p>
<ul>
<li><code>ImageSpec</code> — Root spec structure</li>
<li><code>DistroFamily</code> — Enum discriminating OmniOS vs Ubuntu</li>
<li><code>Target</code> / <code>TargetKind</code> — Output target definitions</li>
<li><code>Overlays</code> — File operations (file, ensure-dir, ensure-symlink, shadow, devfsadm, remove-files)</li>
</ul>
<h2 id="forge-engine"><a class="header" href="#forge-engine">forge-engine</a></h2>
<p>The build engine implementing both phases:</p>
<ul>
<li><strong>Phase 1</strong> (<code>phase1/mod.rs</code>): Distro-specific rootfs assembly
<ul>
<li>IPS operations for OmniOS</li>
<li>debootstrap + APT for Ubuntu</li>
<li>Overlay application (shared across distros)</li>
</ul>
</li>
<li><strong>Phase 2</strong> (<code>phase2/mod.rs</code>): Target production
<ul>
<li><code>qcow2_zfs.rs</code>: ZFS pool creation, BE management</li>
<li><code>qcow2_ext4.rs</code>: Partitioning, ext4 formatting</li>
<li>OCI image layout creation</li>
<li>Tar artifact packaging</li>
</ul>
</li>
</ul>
<p>Key abstraction: <strong><code>ToolRunner</code> trait</strong> — wraps all external tool execution (<code>pkg</code>, <code>apt</code>, <code>qemu-img</code>, <code>zfs</code>, <code>parted</code>, etc.) through a single interface. The real implementation (<code>SystemToolRunner</code>) uses <code>tokio::process::Command</code>. This trait enables testing without root access.</p>
<h2 id="forge-builder"><a class="header" href="#forge-builder">forge-builder</a></h2>
<p>Manages remote builds via ephemeral VMs:</p>
<ol>
<li>Resolve builder image (OCI ref, URL, or path)</li>
<li>Generate ephemeral SSH keypair</li>
<li>Create cloud-init config</li>
<li>Start QEMU via <code>vm-manager</code> crate (user-mode networking)</li>
<li>SSH connect with retry (up to 120s)</li>
<li>Transfer forger binary + spec + files via SCP</li>
<li>Execute remote build via SSH</li>
<li>Download artifacts</li>
<li>Destroy VM (guaranteed cleanup)</li>
</ol>
<p>Uses the external <code>vm-manager</code> crate for hypervisor abstraction (<code>RouterHypervisor</code> auto-detects QEMU/bhyve).</p>
<h2 id="forge-oci"><a class="header" href="#forge-oci">forge-oci</a></h2>
<p>OCI-specific operations:</p>
<ul>
<li><strong>tar_layer</strong>: Compress rootfs into gzip layer</li>
<li><strong>manifest</strong>: Build OCI config and manifest JSON</li>
<li><strong>layout</strong>: Write OCI Image Layout directory structure</li>
<li><strong>artifact</strong>: Package QCOW2 as OCI artifact with custom media types</li>
<li><strong>registry</strong>: Push to OCI registries (token auth, basic auth, anonymous)</li>
<li><strong>AuthConfig</strong>: GHCR token auto-detection, auth file parsing</li>
</ul>
<h2 id="dependency-flow"><a class="header" href="#dependency-flow">Dependency Flow</a></h2>
<pre><code>forger
├── spec-parser
├── forge-engine
│ └── spec-parser
├── forge-builder
│ ├── spec-parser
│ └── vm-manager (external)
└── forge-oci
</code></pre>
<p>All crates are async (tokio) and use miette for error diagnostics.</p>
<h2 id="key-external-dependencies"><a class="header" href="#key-external-dependencies">Key External Dependencies</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Category</th><th>Crate</th><th>Purpose</th></tr></thead><tbody>
<tr><td>KDL parsing</td><td><code>knuffel</code> 3.2</td><td>Spec deserialization</td></tr>
<tr><td>CLI</td><td><code>clap</code> 4.5</td><td>Argument parsing</td></tr>
<tr><td>Async</td><td><code>tokio</code> 1</td><td>Runtime, process, fs</td></tr>
<tr><td>OCI</td><td><code>oci-spec</code>, <code>oci-client</code></td><td>Image spec, registry client</td></tr>
<tr><td>SSH</td><td><code>ssh2</code></td><td>Remote builder communication</td></tr>
<tr><td>Errors</td><td><code>miette</code>, <code>thiserror</code></td><td>Rich diagnostics</td></tr>
<tr><td>VM</td><td><code>vm-manager</code> (path dep)</td><td>Hypervisor abstraction</td></tr>
</tbody></table>
</div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../architecture/pipeline.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 prefetch" href="../architecture/builder-vm.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="../architecture/pipeline.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 prefetch" href="../architecture/builder-vm.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 -->
</div>
</body>
</html>

286
book/book/architecture/overview.html Normal file
View file

@ -0,0 +1,286 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Design Overview - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="design-overview"><a class="header" href="#design-overview">Design Overview</a></h1>
<p>Refraction Forger is designed around three principles: <strong>declarative specs</strong>, <strong>two-phase execution</strong>, and <strong>distro abstraction</strong>.</p>
<h2 id="high-level-architecture"><a class="header" href="#high-level-architecture">High-Level Architecture</a></h2>
<pre><code> ┌─────────────┐
│ KDL Spec │
└──────┬──────┘
│
┌──────▼──────┐
│ spec-parser │ Parse → Resolve → Filter
└──────┬──────┘
│
┌──────▼──────┐
│ forger │ CLI routing
└──────┬──────┘
│
┌────────────┼────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Local Build │ │forge-builder│
└──────┬──────┘ └──────┬──────┘
│ │
│ Ephemeral VM
│ ┌─────────────┐
│ │ SSH + SCP │
│ └──────┬──────┘
│ │
┌──────▼─────────────────────────▼──────┐
│ forge-engine │
│ ┌──────────┐ ┌─────────────────┐ │
│ │ Phase 1 │────▶│ Phase 2 │ │
│ │ Rootfs │ │ QCOW2/OCI/Tar │ │
│ └──────────┘ └────────┬────────┘ │
└────────────────────────────┼──────────┘
│
┌──────▼──────┐
│ forge-oci │ Registry push
└─────────────┘
</code></pre>
<h2 id="key-design-decisions"><a class="header" href="#key-design-decisions">Key Design Decisions</a></h2>
<h3 id="declarative-over-imperative"><a class="header" href="#declarative-over-imperative">Declarative Over Imperative</a></h3>
<p>The old tools used shell scripts to orchestrate builds — ordering mattered, error handling was manual, and reuse required copy-paste. Forger uses a declarative spec where you describe <em>what</em> the image should contain, and the engine handles <em>how</em>.</p>
<h3 id="direct-assembly-over-installation"><a class="header" href="#direct-assembly-over-installation">Direct Assembly Over Installation</a></h3>
<p>Packer boots an ISO, types keystrokes into a virtual console, and waits for an installer to finish. Forger calls the package manager directly to assemble a rootfs, skipping the installer entirely. This is faster and more reliable.</p>
<h3 id="host-independence"><a class="header" href="#host-independence">Host Independence</a></h3>
<p>The old <code>omnios-image-builder</code> required an illumos host with ZFS and pfexec. Forger can build from any platform by spinning up an ephemeral builder VM. The build environment is part of the spec, not a prerequisite.</p>
<h3 id="oci-as-distribution-channel"><a class="header" href="#oci-as-distribution-channel">OCI as Distribution Channel</a></h3>
<p>Instead of custom upload scripts for each cloud provider, Forger uses OCI registries as a universal distribution mechanism. VM images, container images, and tar artifacts all flow through the same registry infrastructure.</p>
<h2 id="error-handling"><a class="header" href="#error-handling">Error Handling</a></h2>
<p>Forger uses <a href="https://docs.rs/miette">miette</a> for rich error diagnostics. When something fails, you get:</p>
<ul>
<li>The error message</li>
<li>Context about what was being attempted</li>
<li>Suggestions for how to fix it</li>
<li>Source location where the error originated</li>
</ul>
<p>This is deliberate — image building involves many external tools and system operations, and clear error messages are essential for debugging.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../formats/registry.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 prefetch" href="../architecture/pipeline.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="../formats/registry.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 prefetch" href="../architecture/pipeline.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 -->
</div>
</body>
</html>

296
book/book/architecture/pipeline.html Normal file
View file

@ -0,0 +1,296 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Two-Phase Build Pipeline - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="two-phase-build-pipeline"><a class="header" href="#two-phase-build-pipeline">Two-Phase Build Pipeline</a></h1>
<p>Every Forger build follows a two-phase architecture. Understanding this split is key to building efficient images and debugging build failures.</p>
<h2 id="phase-1-rootfs-assembly"><a class="header" href="#phase-1-rootfs-assembly">Phase 1: Rootfs Assembly</a></h2>
<p>Phase 1 creates a populated filesystem tree in a staging directory. The work is entirely distro-specific:</p>
<h3 id="omnios-path"><a class="header" href="#omnios-path">OmniOS Path</a></h3>
<ol>
<li><code>pkg image-create</code> — Initialize an IPS package image</li>
<li><code>pkg set-publisher</code> — Configure each publisher (name + origin URL)</li>
<li><code>pkg change-variant</code> — Set zone variant (<code>global</code> or <code>nonglobal</code>)</li>
<li><code>pkg approve-ca-cert</code> — Trust CA certificates for signed packages</li>
<li><code>pkg install</code> — Install all specified packages</li>
<li>Apply customizations (create users)</li>
<li>Apply overlays (files, directories, symlinks, shadow passwords, devfsadm)</li>
</ol>
<h3 id="ubuntu-path"><a class="header" href="#ubuntu-path">Ubuntu Path</a></h3>
<ol>
<li><code>debootstrap</code> — Bootstrap a minimal Debian/Ubuntu rootfs</li>
<li>Write <code>/etc/apt/sources.list</code> from repository configuration</li>
<li><code>apt update</code> — Refresh package lists</li>
<li><code>apt install</code> — Install all specified packages</li>
<li>Apply customizations and overlays (same as OmniOS)</li>
</ol>
<h3 id="output"><a class="header" href="#output">Output</a></h3>
<p>Phase 1 produces a staging directory containing a complete rootfs. This directory is consumed by Phase 2.</p>
<h2 id="phase-2-target-production"><a class="header" href="#phase-2-target-production">Phase 2: Target Production</a></h2>
<p>Phase 2 takes the rootfs from Phase 1 and packages it into the requested output format. This logic is <strong>shared across all distros</strong>.</p>
<h3 id="qcow2-path"><a class="header" href="#qcow2-path">QCOW2 Path</a></h3>
<pre><code>Create raw disk file (specified size)
→ Attach as loopback device
→ ZFS: create pool → create BE dataset → mount
→ ext4: partition → format → mount
→ Copy rootfs into mounted filesystem
→ Install bootloader (UEFI/GRUB)
→ ZFS: set bootfs → unmount → export pool
→ ext4: unmount
→ Detach loopback
→ qemu-img convert raw → qcow2
</code></pre>
<p>The ZFS path creates a unique pool name during build (e.g., <code>forgebuild_12345</code>) and renames to <code>rpool</code> after export. This prevents conflicts with existing pools on the build host.</p>
<h3 id="oci-path"><a class="header" href="#oci-path">OCI Path</a></h3>
<pre><code>Compress rootfs → tar.gz layer
→ Compute SHA256 digest
→ Build OCI config JSON (entrypoint, env)
→ Build OCI manifest JSON
→ Write OCI Image Layout directory
</code></pre>
<h3 id="artifact-path"><a class="header" href="#artifact-path">Artifact Path</a></h3>
<pre><code>Create tar archive from rootfs
</code></pre>
<h2 id="why-two-phases"><a class="header" href="#why-two-phases">Why Two Phases?</a></h2>
<p>The split serves several purposes:</p>
<ol>
<li><strong>Separation of concerns</strong>: Distro-specific logic (Phase 1) doesn't leak into format-specific logic (Phase 2)</li>
<li><strong>Multiple targets</strong>: One Phase 1 rootfs can produce QCOW2, OCI, and artifact targets without rebuilding</li>
<li><strong>Caching boundary</strong>: The base/child relationship creates a cache point between Phase 1 and Phase 2</li>
<li><strong>Testability</strong>: Each phase can be tested independently</li>
</ol>
<h2 id="error-recovery"><a class="header" href="#error-recovery">Error Recovery</a></h2>
<p>If Phase 2 fails (e.g., disk too small, bootloader installation error), Forger cleans up:</p>
<ul>
<li>Unmounts filesystems</li>
<li>Exports ZFS pools</li>
<li>Detaches loopback devices</li>
<li>Removes temporary files</li>
</ul>
<p>Cleanup runs even on failure, preventing resource leaks on the build host.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../architecture/overview.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 prefetch" href="../architecture/crates.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="../architecture/overview.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 prefetch" href="../architecture/crates.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 -->
</div>
</body>
</html>

78
book/book/ayu-highlight.css Normal file
View file

@ -0,0 +1,78 @@
/*
Based off of the Ayu theme
Original by Dempfi (https://github.com/dempfi/ayu)
*/
.hljs {
display: block;
overflow-x: auto;
background: #191f26;
color: #e6e1cf;
}
.hljs-comment,
.hljs-quote {
color: #5c6773;
font-style: italic;
}
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-attr,
.hljs-regexp,
.hljs-link,
.hljs-selector-id,
.hljs-selector-class {
color: #ff7733;
}
.hljs-number,
.hljs-meta,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #ffee99;
}
.hljs-string,
.hljs-bullet {
color: #b8cc52;
}
.hljs-title,
.hljs-built_in,
.hljs-section {
color: #ffb454;
}
.hljs-keyword,
.hljs-selector-tag,
.hljs-symbol {
color: #ff7733;
}
.hljs-name {
color: #36a3d9;
}
.hljs-tag {
color: #00568d;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #91b362;
}
.hljs-deletion {
color: #d96c75;
}

839
book/book/book.js Normal file
View file

@ -0,0 +1,839 @@
'use strict';
/* global default_theme, default_dark_theme, default_light_theme, hljs, ClipboardJS */
// Fix back button cache problem
window.onunload = function() { };
// Global variable, shared between modules
function playground_text(playground, hidden = true) {
const code_block = playground.querySelector('code');
if (window.ace && code_block.classList.contains('editable')) {
const editor = window.ace.edit(code_block);
return editor.getValue();
} else if (hidden) {
return code_block.textContent;
} else {
return code_block.innerText;
}
}
(function codeSnippets() {
function fetch_with_timeout(url, options, timeout = 6000) {
return Promise.race([
fetch(url, options),
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)),
]);
}
const playgrounds = Array.from(document.querySelectorAll('.playground'));
if (playgrounds.length > 0) {
fetch_with_timeout('https://play.rust-lang.org/meta/crates', {
headers: {
'Content-Type': 'application/json',
},
method: 'POST',
mode: 'cors',
})
.then(response => response.json())
.then(response => {
// get list of crates available in the rust playground
const playground_crates = response.crates.map(item => item['id']);
playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
});
}
function handle_crate_list_update(playground_block, playground_crates) {
// update the play buttons after receiving the response
update_play_button(playground_block, playground_crates);
// and install on change listener to dynamically update ACE editors
if (window.ace) {
const code_block = playground_block.querySelector('code');
if (code_block.classList.contains('editable')) {
const editor = window.ace.edit(code_block);
editor.addEventListener('change', () => {
update_play_button(playground_block, playground_crates);
});
// add Ctrl-Enter command to execute rust code
editor.commands.addCommand({
name: 'run',
bindKey: {
win: 'Ctrl-Enter',
mac: 'Ctrl-Enter',
},
exec: _editor => run_rust_code(playground_block),
});
}
}
}
// updates the visibility of play button based on `no_run` class and
// used crates vs ones available on https://play.rust-lang.org
function update_play_button(pre_block, playground_crates) {
const play_button = pre_block.querySelector('.play-button');
// skip if code is `no_run`
if (pre_block.querySelector('code').classList.contains('no_run')) {
play_button.classList.add('hidden');
return;
}
// get list of `extern crate`'s from snippet
const txt = playground_text(pre_block);
const re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
const snippet_crates = [];
let item;
// eslint-disable-next-line no-cond-assign
while (item = re.exec(txt)) {
snippet_crates.push(item[1]);
}
// check if all used crates are available on play.rust-lang.org
const all_available = snippet_crates.every(function(elem) {
return playground_crates.indexOf(elem) > -1;
});
if (all_available) {
play_button.classList.remove('hidden');
} else {
play_button.classList.add('hidden');
}
}
function run_rust_code(code_block) {
let result_block = code_block.querySelector('.result');
if (!result_block) {
result_block = document.createElement('code');
result_block.className = 'result hljs language-bash';
code_block.append(result_block);
}
const text = playground_text(code_block);
const classes = code_block.querySelector('code').classList;
let edition = '2015';
classes.forEach(className => {
if (className.startsWith('edition')) {
edition = className.slice(7);
}
});
const params = {
version: 'stable',
optimize: '0',
code: text,
edition: edition,
};
if (text.indexOf('#![feature') !== -1) {
params.version = 'nightly';
}
result_block.innerText = 'Running...';
fetch_with_timeout('https://play.rust-lang.org/evaluate.json', {
headers: {
'Content-Type': 'application/json',
},
method: 'POST',
mode: 'cors',
body: JSON.stringify(params),
})
.then(response => response.json())
.then(response => {
if (response.result.trim() === '') {
result_block.innerText = 'No output';
result_block.classList.add('result-no-output');
} else {
result_block.innerText = response.result;
result_block.classList.remove('result-no-output');
}
})
.catch(error => result_block.innerText = 'Playground Communication: ' + error.message);
}
// Syntax highlighting Configuration
hljs.configure({
tabReplace: ' ', // 4 spaces
languages: [], // Languages used for auto-detection
});
const code_nodes = Array
.from(document.querySelectorAll('code'))
// Don't highlight `inline code` blocks in headers.
.filter(function(node) {
return !node.parentElement.classList.contains('header');
});
if (window.ace) {
// language-rust class needs to be removed for editable
// blocks or highlightjs will capture events
code_nodes
.filter(function(node) {
return node.classList.contains('editable');
})
.forEach(function(block) {
block.classList.remove('language-rust');
});
code_nodes
.filter(function(node) {
return !node.classList.contains('editable');
})
.forEach(function(block) {
hljs.highlightBlock(block);
});
} else {
code_nodes.forEach(function(block) {
hljs.highlightBlock(block);
});
}
// Adding the hljs class gives code blocks the color css
// even if highlighting doesn't apply
code_nodes.forEach(function(block) {
block.classList.add('hljs');
});
Array.from(document.querySelectorAll('code.hljs')).forEach(function(block) {
const lines = Array.from(block.querySelectorAll('.boring'));
// If no lines were hidden, return
if (!lines.length) {
return;
}
block.classList.add('hide-boring');
const buttons = document.createElement('div');
buttons.className = 'buttons';
buttons.innerHTML = '<button class="fa fa-eye" title="Show hidden lines" \
aria-label="Show hidden lines"></button>';
// add expand button
const pre_block = block.parentNode;
pre_block.insertBefore(buttons, pre_block.firstChild);
pre_block.querySelector('.buttons').addEventListener('click', function(e) {
if (e.target.classList.contains('fa-eye')) {
e.target.classList.remove('fa-eye');
e.target.classList.add('fa-eye-slash');
e.target.title = 'Hide lines';
e.target.setAttribute('aria-label', e.target.title);
block.classList.remove('hide-boring');
} else if (e.target.classList.contains('fa-eye-slash')) {
e.target.classList.remove('fa-eye-slash');
e.target.classList.add('fa-eye');
e.target.title = 'Show hidden lines';
e.target.setAttribute('aria-label', e.target.title);
block.classList.add('hide-boring');
}
});
});
if (window.playground_copyable) {
Array.from(document.querySelectorAll('pre code')).forEach(function(block) {
const pre_block = block.parentNode;
if (!pre_block.classList.contains('playground')) {
let buttons = pre_block.querySelector('.buttons');
if (!buttons) {
buttons = document.createElement('div');
buttons.className = 'buttons';
pre_block.insertBefore(buttons, pre_block.firstChild);
}
const clipButton = document.createElement('button');
clipButton.className = 'clip-button';
clipButton.title = 'Copy to clipboard';
clipButton.setAttribute('aria-label', clipButton.title);
clipButton.innerHTML = '<i class="tooltiptext"></i>';
buttons.insertBefore(clipButton, buttons.firstChild);
}
});
}
// Process playground code blocks
Array.from(document.querySelectorAll('.playground')).forEach(function(pre_block) {
// Add play button
let buttons = pre_block.querySelector('.buttons');
if (!buttons) {
buttons = document.createElement('div');
buttons.className = 'buttons';
pre_block.insertBefore(buttons, pre_block.firstChild);
}
const runCodeButton = document.createElement('button');
runCodeButton.className = 'fa fa-play play-button';
runCodeButton.hidden = true;
runCodeButton.title = 'Run this code';
runCodeButton.setAttribute('aria-label', runCodeButton.title);
buttons.insertBefore(runCodeButton, buttons.firstChild);
runCodeButton.addEventListener('click', () => {
run_rust_code(pre_block);
});
if (window.playground_copyable) {
const copyCodeClipboardButton = document.createElement('button');
copyCodeClipboardButton.className = 'clip-button';
copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
copyCodeClipboardButton.title = 'Copy to clipboard';
copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
}
const code_block = pre_block.querySelector('code');
if (window.ace && code_block.classList.contains('editable')) {
const undoChangesButton = document.createElement('button');
undoChangesButton.className = 'fa fa-history reset-button';
undoChangesButton.title = 'Undo changes';
undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
buttons.insertBefore(undoChangesButton, buttons.firstChild);
undoChangesButton.addEventListener('click', function() {
const editor = window.ace.edit(code_block);
editor.setValue(editor.originalCode);
editor.clearSelection();
});
}
});
})();
(function themes() {
const html = document.querySelector('html');
const themeToggleButton = document.getElementById('theme-toggle');
const themePopup = document.getElementById('theme-list');
const themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
const themeIds = [];
themePopup.querySelectorAll('button.theme').forEach(function(el) {
themeIds.push(el.id);
});
const stylesheets = {
ayuHighlight: document.querySelector('#ayu-highlight-css'),
tomorrowNight: document.querySelector('#tomorrow-night-css'),
highlight: document.querySelector('#highlight-css'),
};
function showThemes() {
themePopup.style.display = 'block';
themeToggleButton.setAttribute('aria-expanded', true);
themePopup.querySelector('button#' + get_theme()).focus();
}
function updateThemeSelected() {
themePopup.querySelectorAll('.theme-selected').forEach(function(el) {
el.classList.remove('theme-selected');
});
const selected = get_saved_theme() ?? 'default_theme';
let element = themePopup.querySelector('button#' + selected);
if (element === null) {
// Fall back in case there is no "Default" item.
element = themePopup.querySelector('button#' + get_theme());
}
element.classList.add('theme-selected');
}
function hideThemes() {
themePopup.style.display = 'none';
themeToggleButton.setAttribute('aria-expanded', false);
themeToggleButton.focus();
}
function get_saved_theme() {
let theme = null;
try {
theme = localStorage.getItem('mdbook-theme');
} catch (e) {
// ignore error.
}
return theme;
}
function delete_saved_theme() {
localStorage.removeItem('mdbook-theme');
}
function get_theme() {
const theme = get_saved_theme();
if (theme === null || theme === undefined || !themeIds.includes(theme)) {
if (typeof default_dark_theme === 'undefined') {
// A customized index.hbs might not define this, so fall back to
// old behavior of determining the default on page load.
return default_theme;
}
return window.matchMedia('(prefers-color-scheme: dark)').matches
? default_dark_theme
: default_light_theme;
} else {
return theme;
}
}
let previousTheme = default_theme;
function set_theme(theme, store = true) {
let ace_theme;
if (theme === 'coal' || theme === 'navy') {
stylesheets.ayuHighlight.disabled = true;
stylesheets.tomorrowNight.disabled = false;
stylesheets.highlight.disabled = true;
ace_theme = 'ace/theme/tomorrow_night';
} else if (theme === 'ayu') {
stylesheets.ayuHighlight.disabled = false;
stylesheets.tomorrowNight.disabled = true;
stylesheets.highlight.disabled = true;
ace_theme = 'ace/theme/tomorrow_night';
} else {
stylesheets.ayuHighlight.disabled = true;
stylesheets.tomorrowNight.disabled = true;
stylesheets.highlight.disabled = false;
ace_theme = 'ace/theme/dawn';
}
setTimeout(function() {
themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
}, 1);
if (window.ace && window.editors) {
window.editors.forEach(function(editor) {
editor.setTheme(ace_theme);
});
}
if (store) {
try {
localStorage.setItem('mdbook-theme', theme);
} catch (e) {
// ignore error.
}
}
html.classList.remove(previousTheme);
html.classList.add(theme);
previousTheme = theme;
updateThemeSelected();
}
const query = window.matchMedia('(prefers-color-scheme: dark)');
query.onchange = function() {
set_theme(get_theme(), false);
};
// Set theme.
set_theme(get_theme(), false);
themeToggleButton.addEventListener('click', function() {
if (themePopup.style.display === 'block') {
hideThemes();
} else {
showThemes();
}
});
themePopup.addEventListener('click', function(e) {
let theme;
if (e.target.className === 'theme') {
theme = e.target.id;
} else if (e.target.parentElement.className === 'theme') {
theme = e.target.parentElement.id;
} else {
return;
}
if (theme === 'default_theme' || theme === null) {
delete_saved_theme();
set_theme(get_theme(), false);
} else {
set_theme(theme);
}
});
themePopup.addEventListener('focusout', function(e) {
// e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
if (!!e.relatedTarget &&
!themeToggleButton.contains(e.relatedTarget) &&
!themePopup.contains(e.relatedTarget)
) {
hideThemes();
}
});
// Should not be needed, but it works around an issue on macOS & iOS:
// https://github.com/rust-lang/mdBook/issues/628
document.addEventListener('click', function(e) {
if (themePopup.style.display === 'block' &&
!themeToggleButton.contains(e.target) &&
!themePopup.contains(e.target)
) {
hideThemes();
}
});
document.addEventListener('keydown', function(e) {
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
return;
}
if (!themePopup.contains(e.target)) {
return;
}
let li;
switch (e.key) {
case 'Escape':
e.preventDefault();
hideThemes();
break;
case 'ArrowUp':
e.preventDefault();
li = document.activeElement.parentElement;
if (li && li.previousElementSibling) {
li.previousElementSibling.querySelector('button').focus();
}
break;
case 'ArrowDown':
e.preventDefault();
li = document.activeElement.parentElement;
if (li && li.nextElementSibling) {
li.nextElementSibling.querySelector('button').focus();
}
break;
case 'Home':
e.preventDefault();
themePopup.querySelector('li:first-child button').focus();
break;
case 'End':
e.preventDefault();
themePopup.querySelector('li:last-child button').focus();
break;
}
});
})();
(function sidebar() {
const sidebar = document.getElementById('sidebar');
const sidebarLinks = document.querySelectorAll('#sidebar a');
const sidebarToggleButton = document.getElementById('sidebar-toggle');
const sidebarResizeHandle = document.getElementById('sidebar-resize-handle');
const sidebarCheckbox = document.getElementById('sidebar-toggle-anchor');
let firstContact = null;
/* Because we cannot change the `display` using only CSS after/before the transition, we
need JS to do it. We change the display to prevent the browsers search to find text inside
the collapsed sidebar. */
if (!document.documentElement.classList.contains('sidebar-visible')) {
sidebar.style.display = 'none';
}
sidebar.addEventListener('transitionend', () => {
/* We only change the display to "none" if we're collapsing the sidebar. */
if (!sidebarCheckbox.checked) {
sidebar.style.display = 'none';
}
});
sidebarToggleButton.addEventListener('click', () => {
/* To allow the sidebar expansion animation, we first need to put back the display. */
if (!sidebarCheckbox.checked) {
sidebar.style.display = '';
// Workaround for Safari skipping the animation when changing
// `display` and a transform in the same event loop. This forces a
// reflow after updating the display.
sidebar.offsetHeight;
}
});
function showSidebar() {
document.documentElement.classList.add('sidebar-visible');
Array.from(sidebarLinks).forEach(function(link) {
link.setAttribute('tabIndex', 0);
});
sidebarToggleButton.setAttribute('aria-expanded', true);
sidebar.setAttribute('aria-hidden', false);
try {
localStorage.setItem('mdbook-sidebar', 'visible');
} catch (e) {
// Ignore error.
}
}
function hideSidebar() {
document.documentElement.classList.remove('sidebar-visible');
Array.from(sidebarLinks).forEach(function(link) {
link.setAttribute('tabIndex', -1);
});
sidebarToggleButton.setAttribute('aria-expanded', false);
sidebar.setAttribute('aria-hidden', true);
try {
localStorage.setItem('mdbook-sidebar', 'hidden');
} catch (e) {
// Ignore error.
}
}
// Toggle sidebar
sidebarCheckbox.addEventListener('change', function sidebarToggle() {
if (sidebarCheckbox.checked) {
const current_width = parseInt(
document.documentElement.style.getPropertyValue('--sidebar-target-width'), 10);
if (current_width < 150) {
document.documentElement.style.setProperty('--sidebar-target-width', '150px');
}
showSidebar();
} else {
hideSidebar();
}
});
sidebarResizeHandle.addEventListener('mousedown', initResize, false);
function initResize() {
window.addEventListener('mousemove', resize, false);
window.addEventListener('mouseup', stopResize, false);
document.documentElement.classList.add('sidebar-resizing');
}
function resize(e) {
let pos = e.clientX - sidebar.offsetLeft;
if (pos < 20) {
hideSidebar();
} else {
if (!document.documentElement.classList.contains('sidebar-visible')) {
showSidebar();
}
pos = Math.min(pos, window.innerWidth - 100);
document.documentElement.style.setProperty('--sidebar-target-width', pos + 'px');
}
}
//on mouseup remove windows functions mousemove & mouseup
function stopResize() {
document.documentElement.classList.remove('sidebar-resizing');
window.removeEventListener('mousemove', resize, false);
window.removeEventListener('mouseup', stopResize, false);
}
document.addEventListener('touchstart', function(e) {
firstContact = {
x: e.touches[0].clientX,
time: Date.now(),
};
}, { passive: true });
document.addEventListener('touchmove', function(e) {
if (!firstContact) {
return;
}
const curX = e.touches[0].clientX;
const xDiff = curX - firstContact.x,
tDiff = Date.now() - firstContact.time;
if (tDiff < 250 && Math.abs(xDiff) >= 150) {
if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) {
showSidebar();
} else if (xDiff < 0 && curX < 300) {
hideSidebar();
}
firstContact = null;
}
}, { passive: true });
})();
(function chapterNavigation() {
document.addEventListener('keydown', function(e) {
if (e.altKey || e.ctrlKey || e.metaKey) {
return;
}
if (window.search && window.search.hasFocus()) {
return;
}
const html = document.querySelector('html');
function next() {
const nextButton = document.querySelector('.nav-chapters.next');
if (nextButton) {
window.location.href = nextButton.href;
}
}
function prev() {
const previousButton = document.querySelector('.nav-chapters.previous');
if (previousButton) {
window.location.href = previousButton.href;
}
}
function showHelp() {
const container = document.getElementById('mdbook-help-container');
const overlay = document.getElementById('mdbook-help-popup');
container.style.display = 'flex';
// Clicking outside the popup will dismiss it.
const mouseHandler = event => {
if (overlay.contains(event.target)) {
return;
}
if (event.button !== 0) {
return;
}
event.preventDefault();
event.stopPropagation();
document.removeEventListener('mousedown', mouseHandler);
hideHelp();
};
// Pressing esc will dismiss the popup.
const escapeKeyHandler = event => {
if (event.key === 'Escape') {
event.preventDefault();
event.stopPropagation();
document.removeEventListener('keydown', escapeKeyHandler, true);
hideHelp();
}
};
document.addEventListener('keydown', escapeKeyHandler, true);
document.getElementById('mdbook-help-container')
.addEventListener('mousedown', mouseHandler);
}
function hideHelp() {
document.getElementById('mdbook-help-container').style.display = 'none';
}
// Usually needs the Shift key to be pressed
switch (e.key) {
case '?':
e.preventDefault();
showHelp();
break;
}
// Rest of the keys are only active when the Shift key is not pressed
if (e.shiftKey) {
return;
}
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
if (html.dir === 'rtl') {
prev();
} else {
next();
}
break;
case 'ArrowLeft':
e.preventDefault();
if (html.dir === 'rtl') {
next();
} else {
prev();
}
break;
}
});
})();
(function clipboard() {
const clipButtons = document.querySelectorAll('.clip-button');
function hideTooltip(elem) {
elem.firstChild.innerText = '';
elem.className = 'clip-button';
}
function showTooltip(elem, msg) {
elem.firstChild.innerText = msg;
elem.className = 'clip-button tooltipped';
}
const clipboardSnippets = new ClipboardJS('.clip-button', {
text: function(trigger) {
hideTooltip(trigger);
const playground = trigger.closest('pre');
return playground_text(playground, false);
},
});
Array.from(clipButtons).forEach(function(clipButton) {
clipButton.addEventListener('mouseout', function(e) {
hideTooltip(e.currentTarget);
});
});
clipboardSnippets.on('success', function(e) {
e.clearSelection();
showTooltip(e.trigger, 'Copied!');
});
clipboardSnippets.on('error', function(e) {
showTooltip(e.trigger, 'Clipboard error!');
});
})();
(function scrollToTop() {
const menuTitle = document.querySelector('.menu-title');
menuTitle.addEventListener('click', function() {
document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
});
})();
(function controllMenu() {
const menu = document.getElementById('menu-bar');
(function controllPosition() {
let scrollTop = document.scrollingElement.scrollTop;
let prevScrollTop = scrollTop;
const minMenuY = -menu.clientHeight - 50;
// When the script loads, the page can be at any scroll (e.g. if you refresh it).
menu.style.top = scrollTop + 'px';
// Same as parseInt(menu.style.top.slice(0, -2), but faster
let topCache = menu.style.top.slice(0, -2);
menu.classList.remove('sticky');
let stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
document.addEventListener('scroll', function() {
scrollTop = Math.max(document.scrollingElement.scrollTop, 0);
// `null` means that it doesn't need to be updated
let nextSticky = null;
let nextTop = null;
const scrollDown = scrollTop > prevScrollTop;
const menuPosAbsoluteY = topCache - scrollTop;
if (scrollDown) {
nextSticky = false;
if (menuPosAbsoluteY > 0) {
nextTop = prevScrollTop;
}
} else {
if (menuPosAbsoluteY > 0) {
nextSticky = true;
} else if (menuPosAbsoluteY < minMenuY) {
nextTop = prevScrollTop + minMenuY;
}
}
if (nextSticky === true && stickyCache === false) {
menu.classList.add('sticky');
stickyCache = true;
} else if (nextSticky === false && stickyCache === true) {
menu.classList.remove('sticky');
stickyCache = false;
}
if (nextTop !== null) {
menu.style.top = nextTop + 'px';
topCache = nextTop;
}
prevScrollTop = scrollTop;
}, { passive: true });
})();
(function controllBorder() {
function updateBorder() {
if (menu.offsetTop === 0) {
menu.classList.remove('bordered');
} else {
menu.classList.add('bordered');
}
}
updateBorder();
document.addEventListener('scroll', updateBorder, { passive: true });
})();
})();

7
book/book/clipboard.min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

307
book/book/composability/base.html Normal file
View file

@ -0,0 +1,307 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Base Specs (Build Caching) - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="base-specs-build-caching"><a class="header" href="#base-specs-build-caching">Base Specs (Build Caching)</a></h1>
<p>The <code>base</code> directive establishes a parent-child relationship between specs. This is Forger's primary caching mechanism: <strong>a parent spec produces an artifact, and a child spec consumes it</strong>.</p>
<h2 id="how-it-works"><a class="header" href="#how-it-works">How It Works</a></h2>
<pre><code>omnios-base.kdl (parent)
→ builds artifact (tar archive cached on disk or in registry)
→ omnios-disk.kdl (child, consumes the artifact)
→ builds QCOW2
</code></pre>
<p>The parent handles the expensive, slow operations (OS installation, base package setup). The child adds customization and produces the final image. When the parent's output is cached, rebuilding the child skips the entire base installation.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<p>In the child spec:</p>
<pre><code class="language-kdl">base "omnios-base.kdl"
// Child-specific additions
packages {
package "/system/cloud-init"
package "/driver/virtio/vioif"
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
}
</code></pre>
<p>The parent spec (<code>omnios-base.kdl</code>) defines the foundation:</p>
<pre><code class="language-kdl">metadata name="omnios-base" version="1.0.0" description="Base OmniOS configuration"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
}
</code></pre>
<h2 id="what-gets-inherited"><a class="header" href="#what-gets-inherited">What Gets Inherited</a></h2>
<p>When a child references a parent via <code>base</code>:</p>
<ul>
<li><strong>Repositories</strong> are merged (deduplicated by name/URL)</li>
<li><strong>Packages</strong> from both parent and child are installed</li>
<li><strong>Overlays</strong> from the parent execute first, then the child's</li>
<li><strong>Customizations</strong> from both are applied</li>
<li><strong>Metadata</strong> from the child overrides the parent</li>
<li><strong>Targets</strong> from the child are used (parent targets are not inherited)</li>
</ul>
<h2 id="caching-pipeline"><a class="header" href="#caching-pipeline">Caching Pipeline</a></h2>
<p>The key insight is that <code>base</code> creates a <strong>build stage boundary</strong>. The parent's output (typically an artifact/tar) is the cache unit:</p>
<ol>
<li>First build: parent runs Phase 1 (full package installation), produces artifact</li>
<li>Subsequent builds: if the parent spec hasn't changed, skip Phase 1 and start from the cached artifact</li>
<li>The child only needs to apply its additional packages, overlays, and produce its targets</li>
</ol>
<p>This mirrors the strap→image→archive pipeline from the old <code>omnios-image-builder</code>, but expressed declaratively.</p>
<h2 id="multi-level-inheritance"><a class="header" href="#multi-level-inheritance">Multi-Level Inheritance</a></h2>
<p>Base specs can themselves have bases, creating a chain:</p>
<pre><code>distro-base.kdl
→ platform-base.kdl
→ application-image.kdl
</code></pre>
<p>Each level adds or refines what the previous level established. Circular references are detected and rejected.</p>
<h2 id="base-vs-include"><a class="header" href="#base-vs-include">Base vs Include</a></h2>
<div class="table-wrapper"><table><thead><tr><th></th><th>Base</th><th>Include</th></tr></thead><tbody>
<tr><td><strong>Relationship</strong></td><td>Parent → child (produces artifact for child to consume)</td><td>Sibling (shared steps imported)</td></tr>
<tr><td><strong>Caching</strong></td><td>Yes — parent output is the cache boundary</td><td>No — just DRY for config</td></tr>
<tr><td><strong>Merging</strong></td><td>Full merge with child overrides</td><td>Steps imported as-is</td></tr>
<tr><td><strong>Targets</strong></td><td>Child's targets used</td><td>No target interaction</td></tr>
</tbody></table>
</div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/builder.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 prefetch" href="../composability/includes.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="../spec/builder.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 prefetch" href="../composability/includes.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 -->
</div>
</body>
</html>

299
book/book/composability/includes.html Normal file
View file

@ -0,0 +1,299 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Includes (Shared Steps) - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="includes-shared-steps"><a class="header" href="#includes-shared-steps">Includes (Shared Steps)</a></h1>
<p>The <code>include</code> directive imports shared configuration steps from another spec file into the current spec. Unlike <code>base</code>, includes don't create a build-stage boundary — they simply pull in common definitions for reuse.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<pre><code class="language-kdl">include "common.kdl"
include "devfs.kdl"
</code></pre>
<h2 id="what-includes-do"><a class="header" href="#what-includes-do">What Includes Do</a></h2>
<p>An include file is a regular <code>.kdl</code> spec containing overlays, packages, customizations, or other configuration. When included, its contents are merged into the including spec as if they were written inline.</p>
<h3 id="example-commonkdl"><a class="header" href="#example-commonkdl">Example: <code>common.kdl</code></a></h3>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
file destination="/etc/inet/hosts" source="files/etc/hosts"
file destination="/etc/nodename" source="files/etc/nodename"
file destination="/etc/resolv.conf" source="files/etc/resolv.conf"
ensure-symlink "/etc/nsswitch.conf" target="/etc/nsswitch.dns"
}
</code></pre>
<h3 id="example-devfskdl"><a class="header" href="#example-devfskdl">Example: <code>devfs.kdl</code></a></h3>
<pre><code class="language-kdl">overlays {
devfsadm
remove-files "/dev/dsk" "/dev/rdsk" "/dev/cfg" "/dev/usb"
ensure-dir "/dev/cfg" owner="root" group="root" mode="755"
ensure-dir "/dev/dsk" owner="root" group="root" mode="755"
ensure-dir "/dev/rdsk" owner="root" group="root" mode="755"
ensure-dir "/dev/usb" owner="root" group="root" mode="755"
ensure-symlink "/dev/msglog" target="../devices/pseudo/log@0:msglog"
}
</code></pre>
<h2 id="using-includes"><a class="header" href="#using-includes">Using Includes</a></h2>
<p>A disk image spec can import these shared steps:</p>
<pre><code class="language-kdl">base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/system/cloud-init"
}
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
shadow username="root" password="$5$..."
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
}
</code></pre>
<h2 id="execution-order"><a class="header" href="#execution-order">Execution Order</a></h2>
<ol>
<li>Base spec's packages, overlays, and customizations run first</li>
<li>Include files run in the order they appear</li>
<li>The current spec's content runs last</li>
</ol>
<p>This gives you control over layering: device filesystem setup (<code>devfs.kdl</code>) before network configuration (<code>common.kdl</code>) before image-specific overlays.</p>
<h2 id="when-to-use-include-vs-base"><a class="header" href="#when-to-use-include-vs-base">When to Use Include vs Base</a></h2>
<ul>
<li><strong>Include</strong>: Shared configuration snippets used across multiple specs (SMF profiles, network setup, device nodes)</li>
<li><strong>Base</strong>: A full image foundation that produces a cached artifact consumed by derivative images</li>
</ul>
<p>Includes are lightweight — they don't trigger a separate build phase or produce intermediate artifacts.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../composability/base.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 prefetch" href="../composability/profiles.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="../composability/base.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 prefetch" href="../composability/profiles.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 -->
</div>
</body>
</html>

327
book/book/composability/pipelines.html Normal file
View file

@ -0,0 +1,327 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Multi-Stage Pipelines - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="multi-stage-pipelines"><a class="header" href="#multi-stage-pipelines">Multi-Stage Pipelines</a></h1>
<p>Forger's composability model enables multi-stage build pipelines where each stage's output feeds as input to the next. This is the key to fast, cacheable image builds.</p>
<h2 id="the-pipeline-pattern"><a class="header" href="#the-pipeline-pattern">The Pipeline Pattern</a></h2>
<p>A typical pipeline for a bootable OmniOS VM image looks like this:</p>
<pre><code>Stage 1: Base (expensive, cached)
omnios-base.kdl
→ Initializes IPS
→ Sets publishers
→ Installs core packages
→ Produces: artifact (tar archive)
Stage 2: Image (fast, incremental)
omnios-disk.kdl (base: omnios-base.kdl)
→ Consumes base artifact
→ Adds cloud-init, drivers
→ Applies overlays (config files, device nodes)
→ Produces: QCOW2 image
</code></pre>
<p>The first build runs both stages. Subsequent builds skip Stage 1 if the base hasn't changed, jumping straight to Stage 2.</p>
<h2 id="designing-your-pipeline"><a class="header" href="#designing-your-pipeline">Designing Your Pipeline</a></h2>
<h3 id="identify-the-cache-boundary"><a class="header" href="#identify-the-cache-boundary">Identify the Cache Boundary</a></h3>
<p>The most expensive operation in image building is package installation — downloading and extracting hundreds of packages from a repository. Put this in the base spec:</p>
<pre><code class="language-kdl">// omnios-base.kdl — the slow part, cached
metadata name="omnios-base" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
package "/web/curl"
package "/web/wget"
}
</code></pre>
<h3 id="derive-specific-images"><a class="header" href="#derive-specific-images">Derive Specific Images</a></h3>
<p>Then create derivative specs that add target-specific configuration:</p>
<pre><code class="language-kdl">// omnios-disk.kdl — fast, builds on cached base
base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/system/cloud-init"
package "/driver/virtio/vioif"
package "/driver/virtio/vioblk"
}
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
shadow username="root" password="$5$rounds=10000$..."
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<h3 id="multiple-derivatives-from-one-base"><a class="header" href="#multiple-derivatives-from-one-base">Multiple Derivatives from One Base</a></h3>
<pre><code>omnios-base.kdl
├── omnios-disk.kdl → QCOW2 VM image
├── omnios-rust-ci.kdl → Rust CI image (adds rust, git, build tools)
├── omnios-container.kdl → OCI container
└── omnios-aws.kdl → AWS-specific VM image
</code></pre>
<p>Each derivative shares the same cached base, so building all four images only runs the expensive Stage 1 once.</p>
<h2 id="comparison-with-predecessor-tools"><a class="header" href="#comparison-with-predecessor-tools">Comparison with Predecessor Tools</a></h2>
<h3 id="omnios-image-builder-shell--json"><a class="header" href="#omnios-image-builder-shell--json">omnios-image-builder (Shell + JSON)</a></h3>
<p>The old <code>omnios-image-builder</code> achieved the same pattern with ZFS snapshots:</p>
<pre><code>01-strap.json → pkg install entire → ZFS snapshot "strap"
02-image.json → pkg install extras → ZFS snapshot "image"
03-archive.json → pack_tar → omnios-bloody.tar.gz
aws.json → unpack_tar + make_bootable → raw disk
</code></pre>
<p>Each ZFS snapshot was a cache point. The <code>-f</code> flag forced a full rebuild.</p>
<p>Forger replaces this with the <code>base</code> directive. No ZFS on the build host required. No manual snapshot management. The caching is implicit in the spec relationship.</p>
<h3 id="packer-hcl"><a class="header" href="#packer-hcl">Packer (HCL)</a></h3>
<p>Packer has no native multi-stage caching. Each build starts from an ISO installation, runs provisioner scripts, and captures the result. There's no way to say "skip the OS install and start from here."</p>
<p>Forger's pipeline model is fundamentally more efficient for iterative development.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../composability/profiles.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 prefetch" href="../distros/illumos-overview.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="../composability/profiles.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 prefetch" href="../distros/illumos-overview.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 -->
</div>
</body>
</html>

332
book/book/composability/profiles.html Normal file
View file

@ -0,0 +1,332 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Profiles (Conditional Variants) - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="profiles-conditional-variants"><a class="header" href="#profiles-conditional-variants">Profiles (Conditional Variants)</a></h1>
<p>Profiles let you create multiple image variants from a single spec. Blocks tagged with <code>if="profile-name"</code> are only included when that profile is active.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<p>Tag any <code>packages</code>, <code>overlays</code>, or <code>customization</code> block with an <code>if</code> property:</p>
<pre><code class="language-kdl">// Always included (no condition)
packages {
package "/editor/vim"
package "/network/openssh-server"
}
// Only when --profile build is active
packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
}
// Only when --profile ci is active
customization if="ci" {
user "ci"
}
overlays if="debug" {
file destination="/etc/system" source="files/etc/system.debug"
}
</code></pre>
<h2 id="activating-profiles"><a class="header" href="#activating-profiles">Activating Profiles</a></h2>
<p>Use the <code>--profile</code> flag (repeatable) when building or inspecting:</p>
<pre><code class="language-bash"># No profiles — just the base packages
forger build --spec my-image.kdl
# With build tools
forger build --spec my-image.kdl --profile build
# With build tools AND CI user
forger build --spec my-image.kdl --profile build --profile ci
# Inspect with profiles to see what would be included
forger inspect --spec my-image.kdl --profile build --profile ci
</code></pre>
<h2 id="how-filtering-works"><a class="header" href="#how-filtering-works">How Filtering Works</a></h2>
<p>Profile filtering happens after spec resolution (base + include merging) but before the build starts:</p>
<ol>
<li>Parse and resolve the full spec (with all blocks)</li>
<li>Apply profile filter:
<ul>
<li>Blocks with <strong>no <code>if</code></strong> condition → always kept</li>
<li>Blocks where <code>if</code> value <strong>matches</strong> an active profile → kept</li>
<li>Blocks where <code>if</code> value <strong>doesn't match</strong> any active profile → removed</li>
</ul>
</li>
<li>Build proceeds with the filtered spec</li>
</ol>
<h2 id="use-cases"><a class="header" href="#use-cases">Use Cases</a></h2>
<h3 id="development-vs-production"><a class="header" href="#development-vs-production">Development vs Production</a></h3>
<pre><code class="language-kdl">packages {
package "/network/openssh-server"
}
packages if="dev" {
package "/developer/build-essential"
package "/diagnostic/top"
}
overlays if="dev" {
shadow username="root" password="$5$..."
}
</code></pre>
<h3 id="ci-variants"><a class="header" href="#ci-variants">CI Variants</a></h3>
<pre><code class="language-kdl">packages if="rust-ci" {
package "/ooce/developer/rust"
package "/developer/build/gnu-make"
}
packages if="go-ci" {
package "/ooce/developer/go"
}
</code></pre>
<h3 id="cloud-provider-specific"><a class="header" href="#cloud-provider-specific">Cloud Provider Specific</a></h3>
<pre><code class="language-kdl">overlays if="aws" {
file destination="/boot/conf.d/console" source="files/boot_console.aws"
file destination="/etc/dhcp/dhcpagent" source="files/dhcpagent.aws"
}
overlays if="digitalocean" {
file destination="/boot/conf.d/console" source="files/boot_console.do"
}
</code></pre>
<h2 id="combining-with-base-and-includes"><a class="header" href="#combining-with-base-and-includes">Combining with Base and Includes</a></h2>
<p>Profiles work across the full composition chain. Conditional blocks in base specs and includes are filtered together with the current spec's blocks:</p>
<pre><code class="language-kdl">// omnios-base.kdl
packages if="build" {
package "/developer/build-essential"
}
</code></pre>
<pre><code class="language-kdl">// my-image.kdl
base "omnios-base.kdl"
packages if="build" {
package "/ooce/developer/rust"
}
</code></pre>
<p>Building with <code>--profile build</code> activates both blocks from both files.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../composability/includes.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 prefetch" href="../composability/pipelines.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="../composability/includes.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 prefetch" href="../composability/pipelines.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 -->
</div>
</body>
</html>

725
book/book/css/chrome.css Normal file
View file

@ -0,0 +1,725 @@
/* CSS for UI elements (a.k.a. chrome) */
html {
scrollbar-color: var(--scrollbar) var(--bg);
}
#searchresults a,
.content a:link,
a:visited,
a > .hljs {
color: var(--links);
}
/*
body-container is necessary because mobile browsers don't seem to like
overflow-x on the body tag when there is a <meta name="viewport"> tag.
*/
#body-container {
/*
This is used when the sidebar pushes the body content off the side of
the screen on small screens. Without it, dragging on mobile Safari
will want to reposition the viewport in a weird way.
*/
overflow-x: clip;
}
/* Menu Bar */
#menu-bar,
#menu-bar-hover-placeholder {
z-index: 101;
margin: auto calc(0px - var(--page-padding));
}
#menu-bar {
position: relative;
display: flex;
flex-wrap: wrap;
background-color: var(--bg);
border-block-end-color: var(--bg);
border-block-end-width: 1px;
border-block-end-style: solid;
}
#menu-bar.sticky,
#menu-bar-hover-placeholder:hover + #menu-bar,
#menu-bar:hover,
html.sidebar-visible #menu-bar {
position: -webkit-sticky;
position: sticky;
top: 0 !important;
}
#menu-bar-hover-placeholder {
position: sticky;
position: -webkit-sticky;
top: 0;
height: var(--menu-bar-height);
}
#menu-bar.bordered {
border-block-end-color: var(--table-border-color);
}
#menu-bar i, #menu-bar .icon-button {
position: relative;
padding: 0 8px;
z-index: 10;
line-height: var(--menu-bar-height);
cursor: pointer;
transition: color 0.5s;
}
@media only screen and (max-width: 420px) {
#menu-bar i, #menu-bar .icon-button {
padding: 0 5px;
}
}
.icon-button {
border: none;
background: none;
padding: 0;
color: inherit;
}
.icon-button i {
margin: 0;
}
.right-buttons {
margin: 0 15px;
}
.right-buttons a {
text-decoration: none;
}
.left-buttons {
display: flex;
margin: 0 5px;
}
html:not(.js) .left-buttons button {
display: none;
}
.menu-title {
display: inline-block;
font-weight: 200;
font-size: 2.4rem;
line-height: var(--menu-bar-height);
text-align: center;
margin: 0;
flex: 1;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.menu-title {
cursor: pointer;
}
.menu-bar,
.menu-bar:visited,
.nav-chapters,
.nav-chapters:visited,
.mobile-nav-chapters,
.mobile-nav-chapters:visited,
.menu-bar .icon-button,
.menu-bar a i {
color: var(--icons);
}
.menu-bar i:hover,
.menu-bar .icon-button:hover,
.nav-chapters:hover,
.mobile-nav-chapters i:hover {
color: var(--icons-hover);
}
/* Nav Icons */
.nav-chapters {
font-size: 2.5em;
text-align: center;
text-decoration: none;
position: fixed;
top: 0;
bottom: 0;
margin: 0;
max-width: 150px;
min-width: 90px;
display: flex;
justify-content: center;
align-content: center;
flex-direction: column;
transition: color 0.5s, background-color 0.5s;
}
.nav-chapters:hover {
text-decoration: none;
background-color: var(--theme-hover);
transition: background-color 0.15s, color 0.15s;
}
.nav-wrapper {
margin-block-start: 50px;
display: none;
}
.mobile-nav-chapters {
font-size: 2.5em;
text-align: center;
text-decoration: none;
width: 90px;
border-radius: 5px;
background-color: var(--sidebar-bg);
}
/* Only Firefox supports flow-relative values */
.previous { float: left; }
[dir=rtl] .previous { float: right; }
/* Only Firefox supports flow-relative values */
.next {
float: right;
right: var(--page-padding);
}
[dir=rtl] .next {
float: left;
right: unset;
left: var(--page-padding);
}
/* Use the correct buttons for RTL layouts*/
[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";}
[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; }
@media only screen and (max-width: 1080px) {
.nav-wide-wrapper { display: none; }
.nav-wrapper { display: block; }
}
/* sidebar-visible */
@media only screen and (max-width: 1380px) {
#sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
#sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
}
/* Inline code */
:not(pre) > .hljs {
display: inline;
padding: 0.1em 0.3em;
border-radius: 3px;
}
:not(pre):not(a) > .hljs {
color: var(--inline-code-color);
overflow-x: initial;
}
a:hover > .hljs {
text-decoration: underline;
}
pre {
position: relative;
}
pre > .buttons {
position: absolute;
z-index: 100;
right: 0px;
top: 2px;
margin: 0px;
padding: 2px 0px;
color: var(--sidebar-fg);
cursor: pointer;
visibility: hidden;
opacity: 0;
transition: visibility 0.1s linear, opacity 0.1s linear;
}
pre:hover > .buttons {
visibility: visible;
opacity: 1
}
pre > .buttons :hover {
color: var(--sidebar-active);
border-color: var(--icons-hover);
background-color: var(--theme-hover);
}
pre > .buttons i {
margin-inline-start: 8px;
}
pre > .buttons button {
cursor: inherit;
margin: 0px 5px;
padding: 4px 4px 3px 5px;
font-size: 23px;
border-style: solid;
border-width: 1px;
border-radius: 4px;
border-color: var(--icons);
background-color: var(--theme-popup-bg);
transition: 100ms;
transition-property: color,border-color,background-color;
color: var(--icons);
}
pre > .buttons button.clip-button {
padding: 2px 4px 0px 6px;
}
pre > .buttons button.clip-button::before {
/* clipboard image from octicons (https://github.com/primer/octicons/tree/v2.0.0) MIT license
*/
content: url('data:image/svg+xml,<svg width="21" height="20" viewBox="0 0 24 25" \
xmlns="http://www.w3.org/2000/svg" aria-label="Copy to clipboard">\
<path d="M18 20h2v3c0 1-1 2-2 2H2c-.998 0-2-1-2-2V5c0-.911.755-1.667 1.667-1.667h5A3.323 3.323 0 \
0110 0a3.323 3.323 0 013.333 3.333h5C19.245 3.333 20 4.09 20 5v8.333h-2V9H2v14h16v-3zM3 \
7h14c0-.911-.793-1.667-1.75-1.667H13.5c-.957 0-1.75-.755-1.75-1.666C11.75 2.755 10.957 2 10 \
2s-1.75.755-1.75 1.667c0 .911-.793 1.666-1.75 1.666H4.75C3.793 5.333 3 6.09 3 7z"/>\
<path d="M4 19h6v2H4zM12 11H4v2h8zM4 17h4v-2H4zM15 15v-3l-4.5 4.5L15 21v-3l8.027-.032L23 15z"/>\
</svg>');
filter: var(--copy-button-filter);
}
pre > .buttons button.clip-button:hover::before {
filter: var(--copy-button-filter-hover);
}
@media (pointer: coarse) {
pre > .buttons button {
/* On mobile, make it easier to tap buttons. */
padding: 0.3rem 1rem;
}
.sidebar-resize-indicator {
/* Hide resize indicator on devices with limited accuracy */
display: none;
}
}
pre > code {
display: block;
padding: 1rem;
}
/* FIXME: ACE editors overlap their buttons because ACE does absolute
positioning within the code block which breaks padding. The only solution I
can think of is to move the padding to the outer pre tag (or insert a div
wrapper), but that would require fixing a whole bunch of CSS rules.
*/
.hljs.ace_editor {
padding: 0rem 0rem;
}
pre > .result {
margin-block-start: 10px;
}
/* Search */
#searchresults a {
text-decoration: none;
}
mark {
border-radius: 2px;
padding-block-start: 0;
padding-block-end: 1px;
padding-inline-start: 3px;
padding-inline-end: 3px;
margin-block-start: 0;
margin-block-end: -1px;
margin-inline-start: -3px;
margin-inline-end: -3px;
background-color: var(--search-mark-bg);
transition: background-color 300ms linear;
cursor: pointer;
}
mark.fade-out {
background-color: rgba(0,0,0,0) !important;
cursor: auto;
}
.searchbar-outer {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
}
#searchbar-outer.searching #searchbar {
padding-right: 30px;
}
#searchbar-outer .spinner-wrapper {
display: none;
}
#searchbar-outer.searching .spinner-wrapper {
display: block;
}
.search-wrapper {
position: relative;
}
.spinner-wrapper {
--spinner-margin: 2px;
position: absolute;
margin-block-start: calc(var(--searchbar-margin-block-start) + var(--spinner-margin));
right: var(--spinner-margin);
top: 0;
bottom: var(--spinner-margin);
padding: 6px;
background-color: var(--bg);
}
#searchbar {
width: 100%;
margin-block-start: var(--searchbar-margin-block-start);
margin-block-end: 0;
margin-inline-start: auto;
margin-inline-end: auto;
padding: 10px 16px;
transition: box-shadow 300ms ease-in-out;
border: 1px solid var(--searchbar-border-color);
border-radius: 3px;
background-color: var(--searchbar-bg);
color: var(--searchbar-fg);
}
#searchbar:focus,
#searchbar.active {
box-shadow: 0 0 3px var(--searchbar-shadow-color);
}
.searchresults-header {
font-weight: bold;
font-size: 1em;
padding-block-start: 18px;
padding-block-end: 0;
padding-inline-start: 5px;
padding-inline-end: 0;
color: var(--searchresults-header-fg);
}
.searchresults-outer {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
border-block-end: 1px dashed var(--searchresults-border-color);
}
ul#searchresults {
list-style: none;
padding-inline-start: 20px;
}
ul#searchresults li {
margin: 10px 0px;
padding: 2px;
border-radius: 2px;
}
ul#searchresults li.focus {
background-color: var(--searchresults-li-bg);
}
ul#searchresults span.teaser {
display: block;
clear: both;
margin-block-start: 5px;
margin-block-end: 0;
margin-inline-start: 20px;
margin-inline-end: 0;
font-size: 0.8em;
}
ul#searchresults span.teaser em {
font-weight: bold;
font-style: normal;
}
/* Sidebar */
.sidebar {
position: fixed;
left: 0;
top: 0;
bottom: 0;
width: var(--sidebar-width);
font-size: 0.875em;
box-sizing: border-box;
-webkit-overflow-scrolling: touch;
overscroll-behavior-y: contain;
background-color: var(--sidebar-bg);
color: var(--sidebar-fg);
}
.sidebar-iframe-inner {
--padding: 10px;
background-color: var(--sidebar-bg);
padding: var(--padding);
margin: 0;
font-size: 1.4rem;
color: var(--sidebar-fg);
min-height: calc(100vh - var(--padding) * 2);
}
.sidebar-iframe-outer {
border: none;
height: 100%;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
}
[dir=rtl] .sidebar { left: unset; right: 0; }
.sidebar-resizing {
-moz-user-select: none;
-webkit-user-select: none;
-ms-user-select: none;
user-select: none;
}
html:not(.sidebar-resizing) .sidebar {
transition: transform 0.3s; /* Animation: slide away */
}
.sidebar code {
line-height: 2em;
}
.sidebar .sidebar-scrollbox {
overflow-y: auto;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
padding: 10px 10px;
}
.sidebar .sidebar-resize-handle {
position: absolute;
cursor: col-resize;
width: 0;
right: calc(var(--sidebar-resize-indicator-width) * -1);
top: 0;
bottom: 0;
display: flex;
align-items: center;
}
.sidebar-resize-handle .sidebar-resize-indicator {
width: 100%;
height: 16px;
color: var(--icons);
margin-inline-start: var(--sidebar-resize-indicator-space);
display: flex;
align-items: center;
justify-content: flex-start;
}
.sidebar-resize-handle .sidebar-resize-indicator::before {
content: "";
width: 2px;
height: 12px;
border-left: dotted 2px currentColor;
}
.sidebar-resize-handle .sidebar-resize-indicator::after {
content: "";
width: 2px;
height: 16px;
border-left: dotted 2px currentColor;
}
[dir=rtl] .sidebar .sidebar-resize-handle {
left: calc(var(--sidebar-resize-indicator-width) * -1);
right: unset;
}
.js .sidebar .sidebar-resize-handle {
cursor: col-resize;
width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space));
}
/* sidebar-hidden */
#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
}
[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
}
.sidebar::-webkit-scrollbar {
background: var(--sidebar-bg);
}
.sidebar::-webkit-scrollbar-thumb {
background: var(--scrollbar);
}
/* sidebar-visible */
#sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
}
[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
}
@media only screen and (min-width: 620px) {
#sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: none;
margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width));
}
[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: none;
}
}
.chapter {
list-style: none outside none;
padding-inline-start: 0;
line-height: 2.2em;
}
.chapter ol {
width: 100%;
}
.chapter li {
display: flex;
color: var(--sidebar-non-existant);
}
.chapter li a {
display: block;
padding: 0;
text-decoration: none;
color: var(--sidebar-fg);
}
.chapter li a:hover {
color: var(--sidebar-active);
}
.chapter li a.active {
color: var(--sidebar-active);
}
.chapter li > a.toggle {
cursor: pointer;
display: block;
margin-inline-start: auto;
padding: 0 10px;
user-select: none;
opacity: 0.68;
}
.chapter li > a.toggle div {
transition: transform 0.5s;
}
/* collapse the section */
.chapter li:not(.expanded) + li > ol {
display: none;
}
.chapter li.chapter-item {
line-height: 1.5em;
margin-block-start: 0.6em;
}
.chapter li.expanded > a.toggle div {
transform: rotate(90deg);
}
.spacer {
width: 100%;
height: 3px;
margin: 5px 0px;
}
.chapter .spacer {
background-color: var(--sidebar-spacer);
}
@media (-moz-touch-enabled: 1), (pointer: coarse) {
.chapter li a { padding: 5px 0; }
.spacer { margin: 10px 0; }
}
.section {
list-style: none outside none;
padding-inline-start: 20px;
line-height: 1.9em;
}
/* Theme Menu Popup */
.theme-popup {
position: absolute;
left: 10px;
top: var(--menu-bar-height);
z-index: 1000;
border-radius: 4px;
font-size: 0.7em;
color: var(--fg);
background: var(--theme-popup-bg);
border: 1px solid var(--theme-popup-border);
margin: 0;
padding: 0;
list-style: none;
display: none;
/* Don't let the children's background extend past the rounded corners. */
overflow: hidden;
}
[dir=rtl] .theme-popup { left: unset; right: 10px; }
.theme-popup .default {
color: var(--icons);
}
.theme-popup .theme {
width: 100%;
border: 0;
margin: 0;
padding: 2px 20px;
line-height: 25px;
white-space: nowrap;
text-align: start;
cursor: pointer;
color: inherit;
background: inherit;
font-size: inherit;
}
.theme-popup .theme:hover {
background-color: var(--theme-hover);
}
.theme-selected::before {
display: inline-block;
content: "✓";
margin-inline-start: -14px;
width: 14px;
}
/* The container for the help popup that covers the whole window. */
#mdbook-help-container {
/* Position and size for the whole window. */
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
/* This uses flex layout (which is set in book.js), and centers the popup
in the window.*/
display: none;
align-items: center;
justify-content: center;
z-index: 1000;
/* Dim out the book while the popup is visible. */
background: var(--overlay-bg);
}
/* The popup help box. */
#mdbook-help-popup {
box-shadow: 0 4px 24px rgba(0,0,0,0.15);
min-width: 300px;
max-width: 500px;
width: 100%;
box-sizing: border-box;
display: flex;
flex-direction: column;
align-items: center;
background-color: var(--bg);
color: var(--fg);
border-width: 1px;
border-color: var(--theme-popup-border);
border-style: solid;
border-radius: 8px;
padding: 10px;
}
.mdbook-help-title {
text-align: center;
/* mdbook's margin for h2 is way too large. */
margin: 10px;
}

280
book/book/css/general.css Normal file
View file

@ -0,0 +1,280 @@
/* Base styles and content styles */
:root {
/* Browser default font-size is 16px, this way 1 rem = 10px */
font-size: 62.5%;
color-scheme: var(--color-scheme);
}
html {
font-family: "Open Sans", sans-serif;
color: var(--fg);
background-color: var(--bg);
text-size-adjust: none;
-webkit-text-size-adjust: none;
}
body {
margin: 0;
font-size: 1.6rem;
overflow-x: hidden;
}
code {
font-family: var(--mono-font) !important;
font-size: var(--code-font-size);
direction: ltr !important;
}
/* make long words/inline code not x overflow */
main {
overflow-wrap: break-word;
}
/* make wide tables scroll if they overflow */
.table-wrapper {
overflow-x: auto;
}
/* Don't change font size in headers. */
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
font-size: unset;
}
.left { float: left; }
.right { float: right; }
.boring { opacity: 0.6; }
.hide-boring .boring { display: none; }
.hidden { display: none !important; }
h2, h3 { margin-block-start: 2.5em; }
h4, h5 { margin-block-start: 2em; }
.header + .header h3,
.header + .header h4,
.header + .header h5 {
margin-block-start: 1em;
}
h1:target::before,
h2:target::before,
h3:target::before,
h4:target::before,
h5:target::before,
h6:target::before {
display: inline-block;
content: "»";
margin-inline-start: -30px;
width: 30px;
}
/* This is broken on Safari as of version 14, but is fixed
in Safari Technology Preview 117 which I think will be Safari 14.2.
https://bugs.webkit.org/show_bug.cgi?id=218076
*/
:target {
/* Safari does not support logical properties */
scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
}
.page {
outline: 0;
padding: 0 var(--page-padding);
margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
}
.page-wrapper {
box-sizing: border-box;
background-color: var(--bg);
}
html:not(.js) .page-wrapper,
.js:not(.sidebar-resizing) .page-wrapper {
transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
}
[dir=rtl]:not(.js) .page-wrapper,
[dir=rtl].js:not(.sidebar-resizing) .page-wrapper {
transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */
}
.content {
overflow-y: auto;
padding: 0 5px 50px 5px;
}
.content main {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
}
.content p { line-height: 1.45em; }
.content ol { line-height: 1.45em; }
.content ul { line-height: 1.45em; }
.content a { text-decoration: none; }
.content a:hover { text-decoration: underline; }
.content img, .content video { max-width: 100%; }
.content .header:link,
.content .header:visited {
color: var(--fg);
}
.content .header:link,
.content .header:visited:hover {
text-decoration: none;
}
table {
margin: 0 auto;
border-collapse: collapse;
}
table td {
padding: 3px 20px;
border: 1px var(--table-border-color) solid;
}
table thead {
background: var(--table-header-bg);
}
table thead td {
font-weight: 700;
border: none;
}
table thead th {
padding: 3px 20px;
}
table thead tr {
border: 1px var(--table-header-bg) solid;
}
/* Alternate background colors for rows */
table tbody tr:nth-child(2n) {
background: var(--table-alternate-bg);
}
blockquote {
margin: 20px 0;
padding: 0 20px;
color: var(--fg);
background-color: var(--quote-bg);
border-block-start: .1em solid var(--quote-border);
border-block-end: .1em solid var(--quote-border);
}
.warning {
margin: 20px;
padding: 0 20px;
border-inline-start: 2px solid var(--warning-border);
}
.warning:before {
position: absolute;
width: 3rem;
height: 3rem;
margin-inline-start: calc(-1.5rem - 21px);
content: "ⓘ";
text-align: center;
background-color: var(--bg);
color: var(--warning-border);
font-weight: bold;
font-size: 2rem;
}
blockquote .warning:before {
background-color: var(--quote-bg);
}
kbd {
background-color: var(--table-border-color);
border-radius: 4px;
border: solid 1px var(--theme-popup-border);
box-shadow: inset 0 -1px 0 var(--theme-hover);
display: inline-block;
font-size: var(--code-font-size);
font-family: var(--mono-font);
line-height: 10px;
padding: 4px 5px;
vertical-align: middle;
}
sup {
/* Set the line-height for superscript and footnote references so that there
isn't an awkward space appearing above lines that contain the footnote.
See https://github.com/rust-lang/mdBook/pull/2443#discussion_r1813773583
for an explanation.
*/
line-height: 0;
}
.footnote-definition {
font-size: 0.9em;
}
/* The default spacing for a list is a little too large. */
.footnote-definition ul,
.footnote-definition ol {
padding-left: 20px;
}
.footnote-definition > li {
/* Required to position the ::before target */
position: relative;
}
.footnote-definition > li:target {
scroll-margin-top: 50vh;
}
.footnote-reference:target {
scroll-margin-top: 50vh;
}
/* Draws a border around the footnote (including the marker) when it is selected.
TODO: If there are multiple linkbacks, highlight which one you just came
from so you know which one to click.
*/
.footnote-definition > li:target::before {
border: 2px solid var(--footnote-highlight);
border-radius: 6px;
position: absolute;
top: -8px;
right: -8px;
bottom: -8px;
left: -32px;
pointer-events: none;
content: "";
}
/* Pulses the footnote reference so you can quickly see where you left off reading.
This could use some improvement.
*/
@media not (prefers-reduced-motion) {
.footnote-reference:target {
animation: fn-highlight 0.8s;
border-radius: 2px;
}
@keyframes fn-highlight {
from {
background-color: var(--footnote-highlight);
}
}
}
.tooltiptext {
position: absolute;
visibility: hidden;
color: #fff;
background-color: #333;
transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
left: -8px; /* Half of the width of the icon */
top: -35px;
font-size: 0.8em;
text-align: center;
border-radius: 6px;
padding: 5px 8px;
margin: 5px;
z-index: 1000;
}
.tooltipped .tooltiptext {
visibility: visible;
}
.chapter li.part-title {
color: var(--sidebar-fg);
margin: 5px 0px;
font-weight: bold;
}
.result-no-output {
font-style: italic;
}

50
book/book/css/print.css Normal file
View file

@ -0,0 +1,50 @@
#sidebar,
#menu-bar,
.nav-chapters,
.mobile-nav-chapters {
display: none;
}
#page-wrapper.page-wrapper {
transform: none !important;
margin-inline-start: 0px;
overflow-y: initial;
}
#content {
max-width: none;
margin: 0;
padding: 0;
}
.page {
overflow-y: initial;
}
code {
direction: ltr !important;
}
pre > .buttons {
z-index: 2;
}
a, a:visited, a:active, a:hover {
color: #4183c4;
text-decoration: none;
}
h1, h2, h3, h4, h5, h6 {
page-break-inside: avoid;
page-break-after: avoid;
}
pre, code {
page-break-inside: avoid;
white-space: pre-wrap;
}
.fa {
display: none !important;
}

331
book/book/css/variables.css Normal file
View file

@ -0,0 +1,331 @@
/* Globals */
:root {
--sidebar-target-width: 300px;
--sidebar-width: min(var(--sidebar-target-width), 80vw);
--sidebar-resize-indicator-width: 8px;
--sidebar-resize-indicator-space: 2px;
--page-padding: 15px;
--content-max-width: 750px;
--menu-bar-height: 50px;
--mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace;
--code-font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
--searchbar-margin-block-start: 5px;
}
/* Themes */
.ayu {
--bg: hsl(210, 25%, 8%);
--fg: #c5c5c5;
--sidebar-bg: #14191f;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #5c6773;
--sidebar-active: #ffb454;
--sidebar-spacer: #2d334f;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #b7b9cc;
--links: #0096cf;
--inline-code-color: #ffb454;
--theme-popup-bg: #14191f;
--theme-popup-border: #5c6773;
--theme-hover: #191f26;
--quote-bg: hsl(226, 15%, 17%);
--quote-border: hsl(226, 15%, 22%);
--warning-border: #ff8e00;
--table-border-color: hsl(210, 25%, 13%);
--table-header-bg: hsl(210, 25%, 28%);
--table-alternate-bg: hsl(210, 25%, 11%);
--searchbar-border-color: #848484;
--searchbar-bg: #424242;
--searchbar-fg: #fff;
--searchbar-shadow-color: #d4c89f;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #252932;
--search-mark-bg: #e3b171;
--color-scheme: dark;
/* Same as `--icons` */
--copy-button-filter: invert(45%) sepia(6%) saturate(621%) hue-rotate(198deg) brightness(99%) contrast(85%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(68%) sepia(55%) saturate(531%) hue-rotate(341deg) brightness(104%) contrast(101%);
--footnote-highlight: #2668a6;
--overlay-bg: rgba(33, 40, 48, 0.4);
}
.coal {
--bg: hsl(200, 7%, 8%);
--fg: #98a3ad;
--sidebar-bg: #292c2f;
--sidebar-fg: #a1adb8;
--sidebar-non-existant: #505254;
--sidebar-active: #3473ad;
--sidebar-spacer: #393939;
--scrollbar: var(--sidebar-fg);
--icons: #43484d;
--icons-hover: #b3c0cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #141617;
--theme-popup-border: #43484d;
--theme-hover: #1f2124;
--quote-bg: hsl(234, 21%, 18%);
--quote-border: hsl(234, 21%, 23%);
--warning-border: #ff8e00;
--table-border-color: hsl(200, 7%, 13%);
--table-header-bg: hsl(200, 7%, 28%);
--table-alternate-bg: hsl(200, 7%, 11%);
--searchbar-border-color: #aaa;
--searchbar-bg: #b7b7b7;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #98a3ad;
--searchresults-li-bg: #2b2b2f;
--search-mark-bg: #355c7d;
--color-scheme: dark;
/* Same as `--icons` */
--copy-button-filter: invert(26%) sepia(8%) saturate(575%) hue-rotate(169deg) brightness(87%) contrast(82%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(36%) sepia(70%) saturate(503%) hue-rotate(167deg) brightness(98%) contrast(89%);
--footnote-highlight: #4079ae;
--overlay-bg: rgba(33, 40, 48, 0.4);
}
.light, html:not(.js) {
--bg: hsl(0, 0%, 100%);
--fg: hsl(0, 0%, 0%);
--sidebar-bg: #fafafa;
--sidebar-fg: hsl(0, 0%, 0%);
--sidebar-non-existant: #aaaaaa;
--sidebar-active: #1f1fff;
--sidebar-spacer: #f4f4f4;
--scrollbar: #8F8F8F;
--icons: #747474;
--icons-hover: #000000;
--links: #20609f;
--inline-code-color: #301900;
--theme-popup-bg: #fafafa;
--theme-popup-border: #cccccc;
--theme-hover: #e6e6e6;
--quote-bg: hsl(197, 37%, 96%);
--quote-border: hsl(197, 37%, 91%);
--warning-border: #ff8e00;
--table-border-color: hsl(0, 0%, 95%);
--table-header-bg: hsl(0, 0%, 80%);
--table-alternate-bg: hsl(0, 0%, 97%);
--searchbar-border-color: #aaa;
--searchbar-bg: #fafafa;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #e4f2fe;
--search-mark-bg: #a2cff5;
--color-scheme: light;
/* Same as `--icons` */
--copy-button-filter: invert(45.49%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(14%) sepia(93%) saturate(4250%) hue-rotate(243deg) brightness(99%) contrast(130%);
--footnote-highlight: #7e7eff;
--overlay-bg: rgba(200, 200, 205, 0.4);
}
.navy {
--bg: hsl(226, 23%, 11%);
--fg: #bcbdd0;
--sidebar-bg: #282d3f;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #505274;
--sidebar-active: #2b79a2;
--sidebar-spacer: #2d334f;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #b7b9cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #161923;
--theme-popup-border: #737480;
--theme-hover: #282e40;
--quote-bg: hsl(226, 15%, 17%);
--quote-border: hsl(226, 15%, 22%);
--warning-border: #ff8e00;
--table-border-color: hsl(226, 23%, 16%);
--table-header-bg: hsl(226, 23%, 31%);
--table-alternate-bg: hsl(226, 23%, 14%);
--searchbar-border-color: #aaa;
--searchbar-bg: #aeaec6;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #5f5f71;
--searchresults-border-color: #5c5c68;
--searchresults-li-bg: #242430;
--search-mark-bg: #a2cff5;
--color-scheme: dark;
/* Same as `--icons` */
--copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(46%) sepia(20%) saturate(1537%) hue-rotate(156deg) brightness(85%) contrast(90%);
--footnote-highlight: #4079ae;
--overlay-bg: rgba(33, 40, 48, 0.4);
}
.rust {
--bg: hsl(60, 9%, 87%);
--fg: #262625;
--sidebar-bg: #3b2e2a;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #505254;
--sidebar-active: #e69f67;
--sidebar-spacer: #45373a;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #262625;
--links: #2b79a2;
--inline-code-color: #6e6b5e;
--theme-popup-bg: #e1e1db;
--theme-popup-border: #b38f6b;
--theme-hover: #99908a;
--quote-bg: hsl(60, 5%, 75%);
--quote-border: hsl(60, 5%, 70%);
--warning-border: #ff8e00;
--table-border-color: hsl(60, 9%, 82%);
--table-header-bg: #b3a497;
--table-alternate-bg: hsl(60, 9%, 84%);
--searchbar-border-color: #aaa;
--searchbar-bg: #fafafa;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #dec2a2;
--search-mark-bg: #e69f67;
/* Same as `--icons` */
--copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(77%) sepia(16%) saturate(1798%) hue-rotate(328deg) brightness(98%) contrast(83%);
--footnote-highlight: #d3a17a;
--overlay-bg: rgba(150, 150, 150, 0.25);
}
@media (prefers-color-scheme: dark) {
html:not(.js) {
--bg: hsl(200, 7%, 8%);
--fg: #98a3ad;
--sidebar-bg: #292c2f;
--sidebar-fg: #a1adb8;
--sidebar-non-existant: #505254;
--sidebar-active: #3473ad;
--sidebar-spacer: #393939;
--scrollbar: var(--sidebar-fg);
--icons: #43484d;
--icons-hover: #b3c0cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #141617;
--theme-popup-border: #43484d;
--theme-hover: #1f2124;
--quote-bg: hsl(234, 21%, 18%);
--quote-border: hsl(234, 21%, 23%);
--warning-border: #ff8e00;
--table-border-color: hsl(200, 7%, 13%);
--table-header-bg: hsl(200, 7%, 28%);
--table-alternate-bg: hsl(200, 7%, 11%);
--searchbar-border-color: #aaa;
--searchbar-bg: #b7b7b7;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #98a3ad;
--searchresults-li-bg: #2b2b2f;
--search-mark-bg: #355c7d;
--color-scheme: dark;
/* Same as `--icons` */
--copy-button-filter: invert(26%) sepia(8%) saturate(575%) hue-rotate(169deg) brightness(87%) contrast(82%);
/* Same as `--sidebar-active` */
--copy-button-filter-hover: invert(36%) sepia(70%) saturate(503%) hue-rotate(167deg) brightness(98%) contrast(89%);
}
}

316
book/book/distros/adding-distro.html Normal file
View file

@ -0,0 +1,316 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Adding a New Distro - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="adding-a-new-distro"><a class="header" href="#adding-a-new-distro">Adding a New Distro</a></h1>
<p>Forger's distro support is built around the <code>DistroFamily</code> abstraction. Adding a new distribution means extending this abstraction at the spec-parsing and build-engine levels.</p>
<h2 id="architecture-overview"><a class="header" href="#architecture-overview">Architecture Overview</a></h2>
<p>The distro system has three touch points:</p>
<ol>
<li><strong><code>spec-parser</code></strong>: Maps distro strings to <code>DistroFamily</code> enum</li>
<li><strong><code>forge-engine</code> Phase 1</strong>: Distro-specific rootfs assembly logic</li>
<li><strong><code>forge-builder</code></strong>: Default builder image selection</li>
</ol>
<h2 id="step-1-extend-the-distrofamily-enum"><a class="header" href="#step-1-extend-the-distrofamily-enum">Step 1: Extend the DistroFamily Enum</a></h2>
<p>In <code>crates/spec-parser/src/lib.rs</code>, add your distro to the enum:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>pub enum DistroFamily {
OmniOS,
Ubuntu,
Fedora, // New
}
<span class="boring">}</span></code></pre></pre>
<p>Update the detection logic that maps the <code>distro</code> string to a family:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>fn detect_family(distro: &amp;str) -&gt; DistroFamily {
if distro.starts_with("ubuntu") {
DistroFamily::Ubuntu
} else if distro.starts_with("fedora") {
DistroFamily::Fedora
} else {
DistroFamily::OmniOS
}
}
<span class="boring">}</span></code></pre></pre>
<h2 id="step-2-add-repository-type"><a class="header" href="#step-2-add-repository-type">Step 2: Add Repository Type</a></h2>
<p>If your distro uses a different repository format, add it to the <code>repositories</code> parsing in the spec:</p>
<pre><code class="language-kdl">repositories {
// Existing
publisher name="..." origin="..." // IPS
apt-mirror "..." suite="..." components="..." // APT
// New: DNF/YUM
dnf-repo name="fedora" baseurl="https://..." gpgkey="..."
}
</code></pre>
<h2 id="step-3-implement-phase-1-logic"><a class="header" href="#step-3-implement-phase-1-logic">Step 3: Implement Phase 1 Logic</a></h2>
<p>In <code>crates/forge-engine/src/phase1/mod.rs</code>, add the rootfs assembly path for your distro. This is the core work — each distro has its own bootstrap process:</p>
<ul>
<li><strong>OmniOS</strong>: <code>pkg image-create</code> → set publishers → install</li>
<li><strong>Ubuntu</strong>: <code>debootstrap</code> → write sources.list → apt install</li>
<li><strong>Fedora</strong>: <code>dnf --installroot</code> → write repo files → dnf install</li>
</ul>
<p>The key operations:</p>
<ol>
<li>Initialize a package manager root in the staging directory</li>
<li>Configure repositories/mirrors</li>
<li>Install the base package set</li>
<li>Install user-specified packages</li>
</ol>
<h2 id="step-4-default-builder-image"><a class="header" href="#step-4-default-builder-image">Step 4: Default Builder Image</a></h2>
<p>In <code>crates/forge-builder/src/lib.rs</code>, add a default builder image:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>match distro_family {
DistroFamily::OmniOS =&gt; "oci://ghcr.io/cloudnebulaproject/omnios-builder:latest",
DistroFamily::Ubuntu =&gt; "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest",
DistroFamily::Fedora =&gt; "oci://ghcr.io/cloudnebulaproject/fedora-builder:latest",
}
<span class="boring">}</span></code></pre></pre>
<p>You'll also need to build and publish the builder image itself.</p>
<h2 id="step-5-add-example-specs"><a class="header" href="#step-5-add-example-specs">Step 5: Add Example Specs</a></h2>
<p>Create example specs in the <code>images/</code> directory showing common patterns for the new distro.</p>
<h2 id="step-6-document"><a class="header" href="#step-6-document">Step 6: Document</a></h2>
<p>Add a chapter to this book under <strong>Distro Guide</strong> covering:</p>
<ul>
<li>Required and recommended packages</li>
<li>Repository configuration</li>
<li>Filesystem and bootloader defaults</li>
<li>Any distro-specific overlay patterns</li>
</ul>
<h2 id="design-principles"><a class="header" href="#design-principles">Design Principles</a></h2>
<p>When adding a distro, keep these principles in mind:</p>
<ul>
<li><strong>The <code>ToolRunner</code> trait</strong> wraps all external tool execution. Use it for any new package manager commands — this enables testing without root access.</li>
<li><strong>Phase 1 is distro-specific, Phase 2 is not</strong>. The QCOW2/OCI/artifact target production is shared across all distros. Only rootfs assembly changes.</li>
<li><strong>Filesystem defaults</strong> should match what the distro community expects (ZFS for illumos, ext4 for most Linux).</li>
<li><strong>Error messages</strong> should use miette diagnostics to tell the user exactly what's wrong and how to fix it.</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../distros/ubuntu.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 prefetch" href="../formats/qcow2.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="../distros/ubuntu.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 prefetch" href="../formats/qcow2.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 -->
</div>
</body>
</html>

295
book/book/distros/illumos-overview.html Normal file
View file

@ -0,0 +1,295 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>illumos Overview - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="illumos-overview"><a class="header" href="#illumos-overview">illumos Overview</a></h1>
<p>Forger's primary focus is the <strong>illumos</strong> ecosystem. This chapter provides essential background for image developers working with illumos distributions.</p>
<h2 id="what-is-illumos"><a class="header" href="#what-is-illumos">What is illumos?</a></h2>
<p>illumos is a Unix operating system kernel derived from OpenSolaris. It powers several distributions including OmniOS, OpenIndiana, and SmartOS. Key technologies that distinguish illumos from Linux:</p>
<h3 id="zfs"><a class="header" href="#zfs">ZFS</a></h3>
<p>ZFS is the default and recommended filesystem for illumos. It provides:</p>
<ul>
<li><strong>Copy-on-write</strong>: Snapshots and clones are instant and space-efficient</li>
<li><strong>Boot Environments (BEs)</strong>: Multiple bootable system states on the same pool</li>
<li><strong>Data integrity</strong>: End-to-end checksumming</li>
<li><strong>Built-in compression</strong>: LZ4 by default on modern pools</li>
</ul>
<p>Forger creates ZFS pools natively for QCOW2 targets on illumos.</p>
<h3 id="ips-image-packaging-system"><a class="header" href="#ips-image-packaging-system">IPS (Image Packaging System)</a></h3>
<p>IPS is illumos's package manager. Key concepts:</p>
<ul>
<li><strong>Publishers</strong>: Named package repositories (e.g., <code>omnios</code>, <code>extra.omnios</code>)</li>
<li><strong>Incorporations</strong>: Meta-packages that constrain version compatibility (e.g., <code>entire</code>)</li>
<li><strong>Variants</strong>: Facets that select package subsets (e.g., <code>opensolaris.zone=global</code>)</li>
<li><strong>FMRIs</strong>: Hierarchical package names (e.g., <code>/network/openssh-server</code>)</li>
<li><strong>Signed packages</strong>: CA-verified package integrity</li>
</ul>
<p>Forger wraps IPS operations directly — no shell scripting needed.</p>
<h3 id="smf-service-management-facility"><a class="header" href="#smf-service-management-facility">SMF (Service Management Facility)</a></h3>
<p>SMF is illumos's service manager (similar to systemd on Linux, but predates it). Services are defined by XML manifests and managed via profiles:</p>
<ul>
<li><strong>Profiles</strong> control which services are enabled at boot</li>
<li><strong>generic_limited_net.xml</strong>: Basic networking</li>
<li><strong>inetd_generic.xml</strong>: Internet daemon services</li>
<li><strong>platform_none.xml</strong>: Platform-specific (none for VM images)</li>
<li><strong>ns_dns.xml</strong>: DNS name service</li>
</ul>
<p>Forger configures SMF profiles through symlink overlays:</p>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
}
</code></pre>
<h3 id="zones"><a class="header" href="#zones">Zones</a></h3>
<p>illumos zones are lightweight OS-level containers (similar to LXC/Docker, but predating both). The <code>opensolaris.zone</code> variant controls whether packages include global-zone-only components:</p>
<ul>
<li><code>global</code>: Full system including kernel modules, boot components, and hardware drivers</li>
<li><code>nonglobal</code>: Zone-only packages (no kernel or hardware support)</li>
</ul>
<p>For VM images, always use <code>global</code>:</p>
<pre><code class="language-kdl">variants {
set name="opensolaris.zone" value="global"
}
</code></pre>
<h3 id="device-filesystem-devfs"><a class="header" href="#device-filesystem-devfs">Device Filesystem (devfs)</a></h3>
<p>illumos manages device nodes through <code>devfsadm</code>, which discovers hardware and creates entries in <code>/dev</code>. For image building, this means:</p>
<ol>
<li>Clean up stale device nodes from the build environment</li>
<li>Run <code>devfsadm</code> to create correct entries for the target hardware</li>
<li>Ensure required directories exist (<code>/dev/dsk</code>, <code>/dev/rdsk</code>, <code>/dev/cfg</code>, <code>/dev/usb</code>)</li>
</ol>
<p>Forger handles this through the <code>devfsadm</code> overlay and the conventional <code>devfs.kdl</code> include.</p>
<h2 id="illumos-distributions"><a class="header" href="#illumos-distributions">illumos Distributions</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Distribution</th><th>Focus</th><th>Publisher URL</th></tr></thead><tbody>
<tr><td><strong>OmniOS</strong></td><td>Server/cloud, minimal, stable</td><td><code>pkg.omnios.org</code></td></tr>
<tr><td><strong>OpenIndiana</strong></td><td>Desktop/general-purpose, broader package set</td><td><code>pkg.openindiana.org</code></td></tr>
<tr><td><strong>SmartOS</strong></td><td>Hypervisor/container host (Joyent)</td><td>Not IPS-based</td></tr>
</tbody></table>
</div>
<p>Forger currently supports OmniOS. OpenIndiana support follows the same IPS path.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../composability/pipelines.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 prefetch" href="../distros/omnios.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="../composability/pipelines.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 prefetch" href="../distros/omnios.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 -->
</div>
</body>
</html>

355
book/book/distros/omnios.html Normal file
View file

@ -0,0 +1,355 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>OmniOS - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="omnios"><a class="header" href="#omnios">OmniOS</a></h1>
<p>OmniOS is Forger's primary target distribution. It's a server-focused illumos distribution maintained by the OmniOS Community Edition (OmniOSce) project.</p>
<h2 id="release-branches"><a class="header" href="#release-branches">Release Branches</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Branch</th><th>URL Path</th><th>Use Case</th></tr></thead><tbody>
<tr><td><strong>bloody</strong></td><td><code>/bloody/core/</code></td><td>Rolling development, latest packages</td></tr>
<tr><td><strong>stable</strong> (e.g., r151050)</td><td><code>/r151050/core/</code></td><td>Production, LTS releases</td></tr>
</tbody></table>
</div>
<h3 id="choosing-a-branch"><a class="header" href="#choosing-a-branch">Choosing a Branch</a></h3>
<ul>
<li>Use <strong>bloody</strong> for CI images, development, and testing the latest software</li>
<li>Use <strong>stable</strong> for production deployments where predictability matters</li>
</ul>
<h2 id="minimal-spec"><a class="header" href="#minimal-spec">Minimal Spec</a></h2>
<pre><code class="language-kdl">metadata name="omnios-base" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
}
</code></pre>
<h3 id="required-elements"><a class="header" href="#required-elements">Required Elements</a></h3>
<ul>
<li><strong><code>incorporation "entire"</code></strong>: Pins all packages to a consistent version set. Without this, you may get incompatible package versions.</li>
<li><strong><code>certificates</code></strong>: OmniOS packages are signed. The CA certificate file (<code>omniosce-ca.cert.pem</code>) must be available relative to the spec.</li>
<li><strong><code>variants</code> with <code>opensolaris.zone=global</code></strong>: Required for bootable VM images. Omitting this may exclude kernel modules.</li>
</ul>
<h2 id="common-packages"><a class="header" href="#common-packages">Common Packages</a></h2>
<h3 id="core-system"><a class="header" href="#core-system">Core System</a></h3>
<pre><code class="language-kdl">packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
package "/web/curl"
package "/web/wget"
}
</code></pre>
<h3 id="cloud--virtualization"><a class="header" href="#cloud--virtualization">Cloud &amp; Virtualization</a></h3>
<pre><code class="language-kdl">packages {
package "/system/cloud-init"
package "/driver/virtio/vioif" // Virtio network
package "/driver/virtio/vioblk" // Virtio block storage
package "/driver/virtio/vio9p" // 9p filesystem sharing
package "/driver/virtio/vioscsi" // Virtio SCSI
package "/driver/virtio/viorand" // Virtio RNG
}
</code></pre>
<h3 id="development"><a class="header" href="#development">Development</a></h3>
<pre><code class="language-kdl">packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
package "/developer/build/gnu-make"
}
</code></pre>
<h3 id="rust-toolchain"><a class="header" href="#rust-toolchain">Rust Toolchain</a></h3>
<pre><code class="language-kdl">packages if="rust" {
package "/ooce/developer/rust"
package "/developer/versioning/git"
}
</code></pre>
<h2 id="boot-configuration"><a class="header" href="#boot-configuration">Boot Configuration</a></h2>
<p>OmniOS VM images need console and boot configuration through overlays:</p>
<h3 id="serial-console-115200-baud"><a class="header" href="#serial-console-115200-baud">Serial Console (115200 baud)</a></h3>
<pre><code class="language-kdl">overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
file destination="/etc/ttydefs" source="files/ttydefs.115200"
file destination="/etc/default/init" source="files/default_init.utc"
}
</code></pre>
<p>The boot console file configures which console device is used:</p>
<ul>
<li><strong><code>ttya</code></strong>: Serial console (standard for cloud VMs)</li>
<li><strong><code>text</code></strong>: Framebuffer (for interactive debugging)</li>
</ul>
<h3 id="smf-profiles"><a class="header" href="#smf-profiles">SMF Profiles</a></h3>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
}
</code></pre>
<h2 id="qcow2-target-settings"><a class="header" href="#qcow2-target-settings">QCOW2 Target Settings</a></h2>
<p>For OmniOS, always use ZFS with UEFI:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<ul>
<li><strong><code>ashift=12</code></strong>: 4K sector alignment, correct for modern disks and virtual storage</li>
<li><strong>UEFI</strong>: Standard boot method for OmniOS</li>
</ul>
<h2 id="complete-example"><a class="header" href="#complete-example">Complete Example</a></h2>
<p>See <code>images/omnios-bloody-disk.kdl</code> in the repository for a full bootable OmniOS image spec, or the <a href="../reference/examples.html">Example Specs</a> chapter.</p>
<h2 id="omnios-extra-publisher"><a class="header" href="#omnios-extra-publisher">OmniOS Extra Publisher</a></h2>
<p>The <code>extra.omnios</code> publisher provides community-maintained packages not in the core repository, including:</p>
<ul>
<li>Rust (<code>/ooce/developer/rust</code>)</li>
<li>Go (<code>/ooce/developer/go</code>)</li>
<li>Python versions (<code>/ooce/runtime/python-*</code>)</li>
<li>Node.js (<code>/ooce/runtime/node-*</code>)</li>
<li>Build tools (<code>/ooce/developer/omnios-build-tools</code>)</li>
</ul>
<p>Always add this publisher if you need development tools or language runtimes.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../distros/illumos-overview.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 prefetch" href="../distros/ubuntu.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="../distros/illumos-overview.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 prefetch" href="../distros/ubuntu.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 -->
</div>
</body>
</html>

366
book/book/distros/ubuntu.html Normal file
View file

@ -0,0 +1,366 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Ubuntu - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="ubuntu"><a class="header" href="#ubuntu">Ubuntu</a></h1>
<p>Ubuntu is Forger's secondary target, providing Linux support for teams that need both illumos and Linux images from the same tooling.</p>
<h2 id="how-ubuntu-builds-differ"><a class="header" href="#how-ubuntu-builds-differ">How Ubuntu Builds Differ</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Aspect</th><th>OmniOS</th><th>Ubuntu</th></tr></thead><tbody>
<tr><td>Bootstrap</td><td><code>pkg image-create</code></td><td><code>debootstrap</code></td></tr>
<tr><td>Package manager</td><td>IPS (<code>pkg</code>)</td><td>APT (<code>apt</code>)</td></tr>
<tr><td>Repository config</td><td>Publishers</td><td><code>sources.list</code></td></tr>
<tr><td>Default filesystem</td><td>ZFS</td><td>ext4</td></tr>
<tr><td>Bootloader</td><td>UEFI (illumos)</td><td><code>grub-efi-amd64-bin</code></td></tr>
<tr><td>Init system</td><td>SMF</td><td>systemd</td></tr>
</tbody></table>
</div>
<h2 id="minimal-spec"><a class="header" href="#minimal-spec">Minimal Spec</a></h2>
<pre><code class="language-kdl">metadata name="ubuntu-base" version="1.0.0" description="Ubuntu 22.04 base"
distro "ubuntu-22.04"
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
packages {
package "openssh-server"
package "curl"
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
}
</code></pre>
<h3 id="key-differences-from-omnios"><a class="header" href="#key-differences-from-omnios">Key Differences from OmniOS</a></h3>
<ul>
<li><strong><code>distro "ubuntu-22.04"</code></strong> is required — without it, Forger assumes OmniOS</li>
<li><strong>No incorporation, variants, or certificates</strong> — these are IPS concepts</li>
<li><strong>Bootloader is <code>grub-efi-amd64-bin</code></strong> — the Ubuntu GRUB EFI package</li>
<li><strong>Filesystem is <code>ext4</code></strong> — ZFS is possible but not the Ubuntu default</li>
</ul>
<h2 id="repositories"><a class="header" href="#repositories">Repositories</a></h2>
<p>Ubuntu uses APT mirrors with suite and component selection:</p>
<pre><code class="language-kdl">repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-updates" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-security" components="main universe"
}
</code></pre>
<h3 id="components"><a class="header" href="#components">Components</a></h3>
<ul>
<li><strong>main</strong>: Officially supported free software</li>
<li><strong>universe</strong>: Community-maintained free software</li>
<li><strong>restricted</strong>: Proprietary drivers</li>
<li><strong>multiverse</strong>: Non-free software</li>
</ul>
<p>For most server images, <code>main universe</code> covers all needed packages.</p>
<h2 id="common-packages"><a class="header" href="#common-packages">Common Packages</a></h2>
<h3 id="core-system"><a class="header" href="#core-system">Core System</a></h3>
<pre><code class="language-kdl">packages {
package "openssh-server"
package "curl"
package "git"
package "cloud-init"
package "linux-image-generic"
}
</code></pre>
<blockquote>
<p><strong>Important</strong>: Include <code>linux-image-generic</code> for bootable VM images. Without a kernel, the image won't boot.</p>
</blockquote>
<h3 id="build-tools"><a class="header" href="#build-tools">Build Tools</a></h3>
<pre><code class="language-kdl">packages if="build" {
package "build-essential"
package "pkg-config"
package "libssl-dev"
}
</code></pre>
<h3 id="rust-toolchain"><a class="header" href="#rust-toolchain">Rust Toolchain</a></h3>
<pre><code class="language-kdl">packages if="rust" {
package "rustc"
package "cargo"
package "build-essential"
package "libssl-dev"
package "pkg-config"
}
</code></pre>
<h2 id="builder-vm"><a class="header" href="#builder-vm">Builder VM</a></h2>
<p>Ubuntu builds need an Ubuntu builder VM. Specify it explicitly or let Forger use the default:</p>
<pre><code class="language-kdl">builder {
image "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest"
vcpus 4
memory 4096
disk 20
}
</code></pre>
<h2 id="complete-example"><a class="header" href="#complete-example">Complete Example</a></h2>
<pre><code class="language-kdl">metadata name="ubuntu-rust-ci" version="1.0.0" description="Ubuntu Rust CI image"
distro "ubuntu-22.04"
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
packages {
package "build-essential"
package "rustc"
package "cargo"
package "git"
package "curl"
package "openssh-server"
package "cloud-init"
package "linux-image-generic"
package "grub-efi-amd64-bin"
package "libssl-dev"
package "pkg-config"
}
customization {
user "ci"
}
builder {
image "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest"
vcpus 4
memory 4096
disk 20
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
push-to "ghcr.io/cloudnebulaproject/ubuntu-rust:latest"
}
</code></pre>
<h2 id="future-ips-on-linux"><a class="header" href="#future-ips-on-linux">Future: IPS on Linux</a></h2>
<p>A long-term goal of the Forger project is to bring IPS to Linux via a Rust implementation. This would allow Linux images to use the same publisher-based, signed-package, incorporation-constrained model that makes illumos packaging robust. When this is available, Ubuntu and other Linux distros will gain IPS as an alternative package manager option within Forger.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../distros/omnios.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 prefetch" href="../distros/adding-distro.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="../distros/omnios.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 prefetch" href="../distros/adding-distro.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 -->
</div>
</body>
</html>

10
book/book/elasticlunr.min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

BIN
book/book/favicon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.5 KiB

22
book/book/favicon.svg Normal file
View file

@ -0,0 +1,22 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 199.7 184.2">
<style>
@media (prefers-color-scheme: dark) {
svg { fill: white; }
}
</style>
<path d="M189.5,36.8c0.2,2.8,0,5.1-0.6,6.8L153,162c-0.6,2.1-2,3.7-4.2,5c-2.2,1.2-4.4,1.9-6.7,1.9H31.4c-9.6,0-15.3-2.8-17.3-8.4
c-0.8-2.2-0.8-3.9,0.1-5.2c0.9-1.2,2.4-1.8,4.6-1.8H123c7.4,0,12.6-1.4,15.4-4.1s5.7-8.9,8.6-18.4l32.9-108.6
c1.8-5.9,1-11.1-2.2-15.6S169.9,0,164,0H72.7c-1,0-3.1,0.4-6.1,1.1l0.1-0.4C64.5,0.2,62.6,0,61,0.1s-3,0.5-4.3,1.4
c-1.3,0.9-2.4,1.8-3.2,2.8S52,6.5,51.2,8.1c-0.8,1.6-1.4,3-1.9,4.3s-1.1,2.7-1.8,4.2c-0.7,1.5-1.3,2.7-2,3.7c-0.5,0.6-1.2,1.5-2,2.5
s-1.6,2-2.2,2.8s-0.9,1.5-1.1,2.2c-0.2,0.7-0.1,1.8,0.2,3.2c0.3,1.4,0.4,2.4,0.4,3.1c-0.3,3-1.4,6.9-3.3,11.6
c-1.9,4.7-3.6,8.1-5.1,10.1c-0.3,0.4-1.2,1.3-2.6,2.7c-1.4,1.4-2.3,2.6-2.6,3.7c-0.3,0.4-0.3,1.5-0.1,3.4c0.3,1.8,0.4,3.1,0.3,3.8
c-0.3,2.7-1.3,6.3-3,10.8c-1.7,4.5-3.4,8.2-5,11c-0.2,0.5-0.9,1.4-2,2.8c-1.1,1.4-1.8,2.5-2,3.4c-0.2,0.6-0.1,1.8,0.1,3.4
c0.2,1.6,0.2,2.8-0.1,3.6c-0.6,3-1.8,6.7-3.6,11c-1.8,4.3-3.6,7.9-5.4,11c-0.5,0.8-1.1,1.7-2,2.8c-0.8,1.1-1.5,2-2,2.8
s-0.8,1.6-1,2.5c-0.1,0.5,0,1.3,0.4,2.3c0.3,1.1,0.4,1.9,0.4,2.6c-0.1,1.1-0.2,2.6-0.5,4.4c-0.2,1.8-0.4,2.9-0.4,3.2
c-1.8,4.8-1.7,9.9,0.2,15.2c2.2,6.2,6.2,11.5,11.9,15.8c5.7,4.3,11.7,6.4,17.8,6.4h110.7c5.2,0,10.1-1.7,14.7-5.2s7.7-7.8,9.2-12.9
l33-108.6c1.8-5.8,1-10.9-2.2-15.5C194.9,39.7,192.6,38,189.5,36.8z M59.6,122.8L73.8,80c0,0,7,0,10.8,0s28.8-1.7,25.4,17.5
c-3.4,19.2-18.8,25.2-36.8,25.4S59.6,122.8,59.6,122.8z M78.6,116.8c4.7-0.1,18.9-2.9,22.1-17.1S89.2,86.3,89.2,86.3l-8.9,0
l-10.2,30.5C70.2,116.9,74,116.9,78.6,116.8z M75.3,68.7L89,26.2h9.8l0.8,34l23.6-34h9.9l-13.6,42.5h-7.1l12.5-35.4l-24.5,35.4h-6.8
l-0.8-35L82,68.7H75.3z"/>
</svg>
<!-- Original image Copyright Dave Gandy — CC BY 4.0 License -->
Side by side

After

Width:  |  Height:  |  Size: 1.8 KiB

202
book/book/fonts/OPEN-SANS-LICENSE.txt Normal file
View file

@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

93
book/book/fonts/SOURCE-CODE-PRO-LICENSE.txt Normal file
View file

@ -0,0 +1,93 @@
Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL
-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.
The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).
"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).
"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.
"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:
1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.
2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.
5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are
not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.

100
book/book/fonts/fonts.css Normal file
View file

@ -0,0 +1,100 @@
/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'),
url('../fonts/open-sans-v17-all-charsets-300.woff2') format('woff2');
}
/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 300;
src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
url('../fonts/open-sans-v17-all-charsets-300italic.woff2') format('woff2');
}
/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 400;
src: local('Open Sans Regular'), local('OpenSans-Regular'),
url('../fonts/open-sans-v17-all-charsets-regular.woff2') format('woff2');
}
/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 400;
src: local('Open Sans Italic'), local('OpenSans-Italic'),
url('../fonts/open-sans-v17-all-charsets-italic.woff2') format('woff2');
}
/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 600;
src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
url('../fonts/open-sans-v17-all-charsets-600.woff2') format('woff2');
}
/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 600;
src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
url('../fonts/open-sans-v17-all-charsets-600italic.woff2') format('woff2');
}
/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 700;
src: local('Open Sans Bold'), local('OpenSans-Bold'),
url('../fonts/open-sans-v17-all-charsets-700.woff2') format('woff2');
}
/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 700;
src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
url('../fonts/open-sans-v17-all-charsets-700italic.woff2') format('woff2');
}
/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 800;
src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
url('../fonts/open-sans-v17-all-charsets-800.woff2') format('woff2');
}
/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 800;
src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
url('../fonts/open-sans-v17-all-charsets-800italic.woff2') format('woff2');
}
/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Source Code Pro';
font-style: normal;
font-weight: 500;
src: url('../fonts/source-code-pro-v11-all-charsets-500.woff2') format('woff2');
}

BIN
book/book/fonts/open-sans-v17-all-charsets-300.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-300italic.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-600.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-600italic.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-700.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-700italic.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-800.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-800italic.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-italic.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/open-sans-v17-all-charsets-regular.woff2 Normal file
View file

Binary file not shown.

BIN
book/book/fonts/source-code-pro-v11-all-charsets-500.woff2 Normal file
View file

Binary file not shown.

265
book/book/formats/artifact.html Normal file
View file

@ -0,0 +1,265 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Tar Artifacts - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="tar-artifacts"><a class="header" href="#tar-artifacts">Tar Artifacts</a></h1>
<p>Artifact targets produce a tar archive of the assembled rootfs. This is the simplest output format and serves as the building block for multi-stage pipelines.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<pre><code class="language-kdl">target "archive" kind="artifact" {
}
</code></pre>
<h2 id="use-cases"><a class="header" href="#use-cases">Use Cases</a></h2>
<h3 id="build-stage-caching"><a class="header" href="#build-stage-caching">Build Stage Caching</a></h3>
<p>The primary use of artifacts is as intermediate outputs in a <a href="../composability/pipelines.html">multi-stage pipeline</a>. A parent spec produces an artifact that a child spec consumes:</p>
<pre><code class="language-kdl">// base.kdl — produces artifact
target "base-archive" kind="artifact" {
}
</code></pre>
<pre><code class="language-kdl">// disk.kdl — consumes artifact from base
base "base.kdl"
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
}
</code></pre>
<h3 id="external-processing"><a class="header" href="#external-processing">External Processing</a></h3>
<p>Artifacts can be consumed by external tools for further processing:</p>
<ul>
<li>Import into a zone or container manually</li>
<li>Feed into another build system</li>
<li>Archive for distribution</li>
</ul>
<h3 id="rootfs-inspection"><a class="header" href="#rootfs-inspection">Rootfs Inspection</a></h3>
<p>Build an artifact to inspect what the rootfs looks like without committing to a disk image:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --target archive
tar -tzf output/archive.tar.gz | head -50
</code></pre>
<h2 id="output"><a class="header" href="#output">Output</a></h2>
<p>The artifact is written to the output directory as a tar archive (typically gzip-compressed). The archive contains the full rootfs tree starting from <code>/</code>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../formats/oci.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 prefetch" href="../formats/registry.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="../formats/oci.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 prefetch" href="../formats/registry.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 -->
</div>
</body>
</html>

315
book/book/formats/oci.html Normal file
View file

@ -0,0 +1,315 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>OCI Container Images - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="oci-container-images"><a class="header" href="#oci-container-images">OCI Container Images</a></h1>
<p>OCI targets produce container images compatible with Docker, Podman, and any OCI-compliant runtime.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<pre><code class="language-kdl">target "container" kind="oci" {
entrypoint command="/bin/sh"
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
set "TZ" "UTC"
}
}
</code></pre>
<h2 id="how-oci-targets-work"><a class="header" href="#how-oci-targets-work">How OCI Targets Work</a></h2>
<p>Phase 2 for an OCI target:</p>
<ol>
<li><strong>Compress</strong> the Phase 1 rootfs into a gzip tar layer</li>
<li><strong>Compute</strong> SHA256 digests for all blobs</li>
<li><strong>Build</strong> OCI config JSON (entrypoint, environment, layer diff IDs)</li>
<li><strong>Build</strong> OCI manifest JSON (media types, blob references, sizes)</li>
<li><strong>Write</strong> an OCI Image Layout directory:</li>
</ol>
<pre><code>output/container/
├── oci-layout # {"imageLayoutVersion": "1.0.0"}
├── index.json # Points to manifest
└── blobs/
└── sha256/
├── &lt;manifest&gt; # OCI manifest JSON
├── &lt;config&gt; # OCI config JSON
└── &lt;layer&gt; # Compressed rootfs layer
</code></pre>
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
<h3 id="entrypoint"><a class="header" href="#entrypoint">Entrypoint</a></h3>
<p>The command to run when the container starts:</p>
<pre><code class="language-kdl">entrypoint command="/usr/sbin/sshd"
</code></pre>
<p>If omitted, no entrypoint is set and the container runtime's default applies.</p>
<h3 id="environment-variables"><a class="header" href="#environment-variables">Environment Variables</a></h3>
<pre><code class="language-kdl">environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
set "LANG" "C.UTF-8"
set "TZ" "UTC"
}
</code></pre>
<h2 id="using-the-output"><a class="header" href="#using-the-output">Using the Output</a></h2>
<h3 id="load-into-docker"><a class="header" href="#load-into-docker">Load into Docker</a></h3>
<pre><code class="language-bash"># From OCI Image Layout directory
docker load &lt; output/container/
# Or use skopeo
skopeo copy oci:output/container docker-daemon:myimage:latest
</code></pre>
<h3 id="load-into-podman"><a class="header" href="#load-into-podman">Load into Podman</a></h3>
<pre><code class="language-bash">podman load &lt; output/container/
</code></pre>
<h3 id="push-to-registry"><a class="header" href="#push-to-registry">Push to Registry</a></h3>
<p>Use the <code>push</code> command or <code>push-to</code> in the target:</p>
<pre><code class="language-bash">forger push --image output/container/ --reference ghcr.io/myorg/myimage:latest
</code></pre>
<p>Or configure auto-push in the spec (see <a href="./registry.html">OCI Registry Push</a>).</p>
<h2 id="omnios-containers"><a class="header" href="#omnios-containers">OmniOS Containers</a></h2>
<p>OmniOS in a container is useful for CI builds and lightweight services:</p>
<pre><code class="language-kdl">metadata name="omnios-container" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="nonglobal"
}
packages {
package "/editor/vim"
package "/web/curl"
}
target "container" kind="oci" {
entrypoint command="/bin/bash"
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
}
}
</code></pre>
<p>Note: For containers, use <code>opensolaris.zone=nonglobal</code> to exclude kernel modules and hardware drivers that aren't needed in a container context.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../formats/qcow2.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 prefetch" href="../formats/artifact.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="../formats/qcow2.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 prefetch" href="../formats/artifact.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 -->
</div>
</body>
</html>

327
book/book/formats/qcow2.html Normal file
View file

@ -0,0 +1,327 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>QCOW2 VM Images - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="qcow2-vm-images"><a class="header" href="#qcow2-vm-images">QCOW2 VM Images</a></h1>
<p>QCOW2 (QEMU Copy-On-Write v2) is the primary output format for bootable virtual machine images.</p>
<h2 id="how-qcow2-targets-work"><a class="header" href="#how-qcow2-targets-work">How QCOW2 Targets Work</a></h2>
<p>Phase 2 for a QCOW2 target follows this sequence:</p>
<ol>
<li><strong>Create a raw disk</strong> of the specified size</li>
<li><strong>Attach via loopback device</strong> (or equivalent)</li>
<li><strong>Create filesystem</strong>:
<ul>
<li><strong>ZFS</strong>: Create pool → create boot environment dataset → mount</li>
<li><strong>ext4</strong>: Partition disk → format → mount</li>
</ul>
</li>
<li><strong>Populate</strong> from Phase 1 rootfs (copy files into mounted filesystem)</li>
<li><strong>Install bootloader</strong> (UEFI or GRUB)</li>
<li><strong>Finalize</strong>:
<ul>
<li>ZFS: Set bootfs property → unmount → export pool</li>
<li>ext4: Unmount</li>
</ul>
</li>
<li><strong>Detach</strong> loopback device</li>
<li><strong>Convert</strong> raw disk to QCOW2 via <code>qemu-img convert</code></li>
</ol>
<h2 id="zfs-based-images-illumos"><a class="header" href="#zfs-based-images-illumos">ZFS-Based Images (illumos)</a></h2>
<p>ZFS is the default and recommended filesystem for OmniOS images:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<h3 id="zfs-pool-details"><a class="header" href="#zfs-pool-details">ZFS Pool Details</a></h3>
<p>During build, Forger creates a uniquely-named ZFS pool (e.g., <code>forgebuild_12345</code>) to avoid conflicts with existing pools on the build host. After export, the pool is named <code>rpool</code> in the final image.</p>
<h3 id="pool-properties"><a class="header" href="#pool-properties">Pool Properties</a></h3>
<pre><code class="language-kdl">pool {
property name="ashift" value="12"
}
</code></pre>
<ul>
<li><strong><code>ashift=12</code></strong>: 4KB sector alignment. Use this for modern storage and virtual disks.</li>
<li>Additional ZFS pool properties can be set using the same syntax.</li>
</ul>
<h3 id="boot-environments"><a class="header" href="#boot-environments">Boot Environments</a></h3>
<p>ZFS images use boot environments (BEs), a core illumos concept. The image contains a single BE that becomes the default boot target. On first boot, the system can create new BEs for upgrades, allowing rollback to previous states.</p>
<h2 id="ext4-based-images-linux"><a class="header" href="#ext4-based-images-linux">ext4-Based Images (Linux)</a></h2>
<p>ext4 is the default filesystem for Ubuntu images:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
}
</code></pre>
<p>The disk is partitioned with an EFI System Partition and a root partition formatted as ext4.</p>
<h2 id="disk-sizing"><a class="header" href="#disk-sizing">Disk Sizing</a></h2>
<p>Specify the disk size as a string with a unit suffix:</p>
<pre><code class="language-kdl">disk-size "2G" // 2 gigabytes
disk-size "2000M" // 2000 megabytes
disk-size "8G" // 8 gigabytes
</code></pre>
<p>Choose a size that accommodates your installed packages plus reasonable free space. Typical sizes:</p>
<ul>
<li>Minimal OmniOS: 2G</li>
<li>OmniOS with development tools: 4-8G</li>
<li>Ubuntu with build tools: 8G</li>
</ul>
<h2 id="bootloader-options"><a class="header" href="#bootloader-options">Bootloader Options</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Value</th><th>Platform</th><th>Description</th></tr></thead><tbody>
<tr><td><code>uefi</code></td><td>illumos</td><td>Native UEFI boot (recommended for OmniOS)</td></tr>
<tr><td><code>grub</code></td><td>illumos</td><td>Legacy GRUB (BIOS boot)</td></tr>
<tr><td><code>grub-efi-amd64-bin</code></td><td>Ubuntu</td><td>GRUB EFI for x86_64 Linux</td></tr>
</tbody></table>
</div>
<h2 id="auto-push"><a class="header" href="#auto-push">Auto-Push</a></h2>
<p>QCOW2 images can be automatically pushed to an OCI registry as artifacts:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
push-to "ghcr.io/myorg/omnios-image:latest"
}
</code></pre>
<p>The QCOW2 file is wrapped as an OCI artifact with custom media types (<code>application/vnd.cloudnebula.qcow2.*</code>) and pushed to the registry. This allows distributing VM images through container registries.</p>
<h2 id="deploying-qcow2-images"><a class="header" href="#deploying-qcow2-images">Deploying QCOW2 Images</a></h2>
<p>QCOW2 images work with:</p>
<ul>
<li><strong>QEMU/KVM</strong>: Direct use (<code>qemu-system-x86_64 -drive file=image.qcow2,format=qcow2</code>)</li>
<li><strong>libvirt/virt-manager</strong>: Import as existing disk</li>
<li><strong>Proxmox</strong>: Upload to storage, create VM from disk</li>
<li><strong>Cloud platforms</strong>: Convert to platform-specific format if needed</li>
</ul>
<p>To convert to raw (for AWS, DigitalOcean, etc.):</p>
<pre><code class="language-bash">qemu-img convert -f qcow2 -O raw image.qcow2 image.raw
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../distros/adding-distro.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 prefetch" href="../formats/oci.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="../distros/adding-distro.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 prefetch" href="../formats/oci.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 -->
</div>
</body>
</html>

307
book/book/formats/registry.html Normal file
View file

@ -0,0 +1,307 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>OCI Registry Push - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="oci-registry-push"><a class="header" href="#oci-registry-push">OCI Registry Push</a></h1>
<p>Forger can push built images directly to OCI-compliant registries, including GitHub Container Registry (GHCR), Docker Hub, and self-hosted registries.</p>
<h2 id="auto-push-target-configuration"><a class="header" href="#auto-push-target-configuration">Auto-Push (Target Configuration)</a></h2>
<p>Set <code>push-to</code> on a target to automatically push after a successful build:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
push-to "ghcr.io/myorg/omnios-image:latest"
}
target "container" kind="oci" {
push-to "ghcr.io/myorg/omnios-container:latest"
}
</code></pre>
<p>Skip the push with:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --skip-push
</code></pre>
<h2 id="manual-push"><a class="header" href="#manual-push">Manual Push</a></h2>
<p>Push a previously built image:</p>
<pre><code class="language-bash"># Push OCI Image Layout
forger push --image output/container/ --reference ghcr.io/myorg/myimage:latest
# Push QCOW2 as OCI artifact
forger push --image output/vm.qcow2 --reference ghcr.io/myorg/myvm:latest --artifact
</code></pre>
<h3 id="options"><a class="header" href="#options">Options</a></h3>
<div class="table-wrapper"><table><thead><tr><th>Flag</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--image &lt;PATH&gt;</code></td><td>Path to OCI Image Layout directory or QCOW2 file</td></tr>
<tr><td><code>--reference &lt;REF&gt;</code></td><td>Registry reference (e.g., <code>ghcr.io/org/image:tag</code>)</td></tr>
<tr><td><code>--artifact</code></td><td>Push QCOW2 as OCI artifact (custom media types)</td></tr>
<tr><td><code>--auth-file &lt;PATH&gt;</code></td><td>JSON auth file for registry authentication</td></tr>
</tbody></table>
</div>
<h2 id="authentication"><a class="header" href="#authentication">Authentication</a></h2>
<h3 id="github-container-registry-ghcr"><a class="header" href="#github-container-registry-ghcr">GitHub Container Registry (GHCR)</a></h3>
<p>Forger automatically uses the <code>GITHUB_TOKEN</code> environment variable when pushing to <code>ghcr.io</code>:</p>
<pre><code class="language-bash">export GITHUB_TOKEN=ghp_...
forger build --spec my-image.kdl
</code></pre>
<p>In GitHub Actions, the token is available automatically:</p>
<pre><code class="language-yaml">- name: Build and push
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: forger build --spec images/omnios-rust-ci.kdl
</code></pre>
<h3 id="auth-file"><a class="header" href="#auth-file">Auth File</a></h3>
<p>For other registries, provide a JSON auth file:</p>
<pre><code class="language-json">{
"username": "myuser",
"password": "mypassword"
}
</code></pre>
<p>Or with a token:</p>
<pre><code class="language-json">{
"token": "my-registry-token"
}
</code></pre>
<pre><code class="language-bash">forger push --image output/container/ \
--reference registry.example.com/myimage:latest \
--auth-file auth.json
</code></pre>
<h3 id="anonymous-push"><a class="header" href="#anonymous-push">Anonymous Push</a></h3>
<p>Local registries (localhost, 127.0.0.1) are accessed without authentication over HTTP (insecure mode).</p>
<h2 id="qcow2-as-oci-artifact"><a class="header" href="#qcow2-as-oci-artifact">QCOW2 as OCI Artifact</a></h2>
<p>When pushing QCOW2 images with <code>--artifact</code>, Forger uses custom OCI media types:</p>
<ul>
<li>Config: <code>application/vnd.cloudnebula.qcow2.config.v1+json</code></li>
<li>Layer: <code>application/vnd.cloudnebula.qcow2.layer.v1</code></li>
</ul>
<p>This allows distributing VM disk images through container registries alongside container images, using a unified registry infrastructure.</p>
<h2 id="pulling-qcow2-artifacts"><a class="header" href="#pulling-qcow2-artifacts">Pulling QCOW2 Artifacts</a></h2>
<p>QCOW2 artifacts pushed to a registry can be pulled back as builder images or for deployment:</p>
<pre><code class="language-kdl">builder {
image "oci://ghcr.io/myorg/omnios-builder:latest"
}
</code></pre>
<p>Forger resolves <code>oci://</code> references by pulling from the registry.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../formats/artifact.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 prefetch" href="../architecture/overview.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="../formats/artifact.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 prefetch" href="../architecture/overview.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 -->
</div>
</body>
</html>

270
book/book/getting-started/build-modes.html Normal file
View file

@ -0,0 +1,270 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Build Modes - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="build-modes"><a class="header" href="#build-modes">Build Modes</a></h1>
<p>Forger supports two build modes: <strong>local</strong> and <strong>remote</strong>. The mode is selected automatically based on your environment, or you can force it with CLI flags.</p>
<h2 id="local-build"><a class="header" href="#local-build">Local Build</a></h2>
<p>A local build runs directly on your host machine. This is the fastest option but requires:</p>
<ul>
<li>The target distro's package manager to be available</li>
<li>Root/sudo access for filesystem operations</li>
<li>Matching architecture (e.g., building OmniOS images on OmniOS)</li>
</ul>
<pre><code class="language-bash">forger build --spec my-image.kdl --local
</code></pre>
<p>Use <code>--local</code> to skip builder VM detection and force a local build.</p>
<h2 id="remote-build-builder-vm"><a class="header" href="#remote-build-builder-vm">Remote Build (Builder VM)</a></h2>
<p>When your host doesn't match the target OS — for example, building OmniOS images from a Linux workstation — Forger spins up an ephemeral builder VM:</p>
<ol>
<li>Downloads or uses a cached builder image (OCI reference, URL, or local file)</li>
<li>Creates a cloud-init configuration with an ephemeral SSH keypair</li>
<li>Starts a QEMU VM with user-mode networking (no root needed on host)</li>
<li>Transfers the <code>forger</code> binary, spec file, and overlay files via SSH</li>
<li>Runs the build inside the VM</li>
<li>Downloads the finished artifacts</li>
<li>Destroys the VM</li>
</ol>
<pre><code class="language-bash">forger build --spec my-image.kdl --use-builder
</code></pre>
<p>Use <code>--use-builder</code> to force a remote build even when local build is possible.</p>
<h3 id="default-builder-images"><a class="header" href="#default-builder-images">Default Builder Images</a></h3>
<p>If no builder is specified in the spec or on the CLI, Forger uses sensible defaults:</p>
<div class="table-wrapper"><table><thead><tr><th>Target Distro</th><th>Default Builder Image</th></tr></thead><tbody>
<tr><td>OmniOS</td><td><code>oci://ghcr.io/cloudnebulaproject/omnios-builder:latest</code></td></tr>
<tr><td>Ubuntu</td><td><code>oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest</code></td></tr>
</tbody></table>
</div>
<h3 id="override-the-builder-image"><a class="header" href="#override-the-builder-image">Override the Builder Image</a></h3>
<p>From the CLI:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --builder-image oci://my-registry/my-builder:v1
</code></pre>
<p>Or in the spec file (see <a href="../spec/builder.html">Builder Configuration</a>).</p>
<h2 id="how-forger-chooses"><a class="header" href="#how-forger-chooses">How Forger Chooses</a></h2>
<p>When neither <code>--local</code> nor <code>--use-builder</code> is specified, Forger checks whether the current host can satisfy the build requirements (package manager availability, OS match). If it can, it builds locally. Otherwise, it falls back to a builder VM.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../getting-started/first-image.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 prefetch" href="../spec/overview.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="../getting-started/first-image.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 prefetch" href="../spec/overview.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 -->
</div>
</body>
</html>

299
book/book/getting-started/first-image.html Normal file
View file

@ -0,0 +1,299 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Your First Image - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="your-first-image"><a class="header" href="#your-first-image">Your First Image</a></h1>
<p>Let's build a minimal OmniOS VM image. Create a file called <code>my-image.kdl</code>:</p>
<pre><code class="language-kdl">metadata name="my-first-image" version="1.0.0" description="A minimal OmniOS image"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<h2 id="validate-first"><a class="header" href="#validate-first">Validate First</a></h2>
<p>Before building, validate the spec to catch syntax errors:</p>
<pre><code class="language-bash">forger validate --spec my-image.kdl
</code></pre>
<h2 id="inspect-the-resolved-spec"><a class="header" href="#inspect-the-resolved-spec">Inspect the Resolved Spec</a></h2>
<p>See what the build will do after resolving includes and applying profiles:</p>
<pre><code class="language-bash">forger inspect --spec my-image.kdl
</code></pre>
<h2 id="list-targets"><a class="header" href="#list-targets">List Targets</a></h2>
<p>Check what targets are defined:</p>
<pre><code class="language-bash">forger targets --spec my-image.kdl
</code></pre>
<p>Output:</p>
<pre><code>vm (qcow2)
</code></pre>
<h2 id="build"><a class="header" href="#build">Build</a></h2>
<pre><code class="language-bash">forger build --spec my-image.kdl
</code></pre>
<p>This will:</p>
<ol>
<li>Detect whether to build locally or spin up a builder VM</li>
<li><strong>Phase 1</strong>: Create a rootfs by initializing IPS, setting publishers, and installing packages</li>
<li><strong>Phase 2</strong>: Create a 2GB raw disk, set up a ZFS pool, populate it from the rootfs, install the UEFI bootloader, and convert to QCOW2</li>
</ol>
<p>The output lands in <code>./output/</code> by default.</p>
<h2 id="build-a-specific-target"><a class="header" href="#build-a-specific-target">Build a Specific Target</a></h2>
<p>If your spec defines multiple targets, build just one:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --target vm
</code></pre>
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
<ul>
<li>Add <a href="../spec/overlays.html">overlays</a> for custom configuration files</li>
<li>Set up <a href="../composability/base.html">base specs</a> for caching</li>
<li>Configure a <a href="../spec/builder.html">builder VM</a> for cross-platform builds</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../getting-started/installation.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 prefetch" href="../getting-started/build-modes.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="../getting-started/installation.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 prefetch" href="../getting-started/build-modes.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 -->
</div>
</body>
</html>

268
book/book/getting-started/installation.html Normal file
View file

@ -0,0 +1,268 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Installation - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="installation"><a class="header" href="#installation">Installation</a></h1>
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
<p>Forger is written in Rust and builds as a single static binary. You need:</p>
<ul>
<li><strong>Rust toolchain</strong> (1.85 or later) via <a href="https://rustup.rs/">rustup</a></li>
<li><strong>Git</strong> for fetching the source</li>
</ul>
<p>For <strong>local builds</strong> (building images directly on your machine), you also need:</p>
<ul>
<li>The target OS's package manager available (e.g., <code>pkg</code> on OmniOS, <code>debootstrap</code> + <code>apt</code> on Ubuntu)</li>
<li>Root/sudo access for filesystem operations</li>
<li><code>qemu-img</code> for QCOW2 conversion</li>
<li>ZFS utilities if building ZFS-based images</li>
</ul>
<p>For <strong>remote builds</strong> (the default when your host doesn't match the target), you only need:</p>
<ul>
<li>QEMU installed (for the builder VM)</li>
<li>No root access required — Forger uses user-mode networking</li>
</ul>
<h2 id="building-from-source"><a class="header" href="#building-from-source">Building From Source</a></h2>
<pre><code class="language-bash">git clone https://github.com/cloudnebulaproject/refraction-forger.git
cd refraction-forger
cargo build --release
</code></pre>
<p>The binary is at <code>target/release/forger</code>.</p>
<h3 id="cross-compilation-for-illumos"><a class="header" href="#cross-compilation-for-illumos">Cross-Compilation for illumos</a></h3>
<p>If you're building on Linux for deployment on illumos:</p>
<pre><code class="language-bash"># Install the cross-compilation tool
cargo install cross
# Build for illumos
cross build --release --target x86_64-unknown-illumos
</code></pre>
<p>The project includes a <code>Cross.toml</code> with the illumos target preconfigured.</p>
<h2 id="verify-installation"><a class="header" href="#verify-installation">Verify Installation</a></h2>
<pre><code class="language-bash">forger --help
</code></pre>
<p>You should see the five subcommands: <code>build</code>, <code>validate</code>, <code>inspect</code>, <code>push</code>, and <code>targets</code>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../introduction.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 prefetch" href="../getting-started/first-image.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="../introduction.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 prefetch" href="../getting-started/first-image.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 -->
</div>
</body>
</html>

83
book/book/highlight.css Normal file
View file

@ -0,0 +1,83 @@
/*
* An increased contrast highlighting scheme loosely based on the
* "Base16 Atelier Dune Light" theme by Bram de Haan
* (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
* Original Base16 color scheme by Chris Kempson
* (https://github.com/chriskempson/base16)
*/
/* Comment */
.hljs-comment,
.hljs-quote {
color: #575757;
}
/* Red */
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-attr,
.hljs-tag,
.hljs-name,
.hljs-regexp,
.hljs-link,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class {
color: #d70025;
}
/* Orange */
.hljs-number,
.hljs-meta,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #b21e00;
}
/* Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet {
color: #008200;
}
/* Blue */
.hljs-title,
.hljs-section {
color: #0030f2;
}
/* Purple */
.hljs-keyword,
.hljs-selector-tag {
color: #9d00ec;
}
.hljs {
display: block;
overflow-x: auto;
background: #f6f7f6;
color: #000;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #22863a;
background-color: #f0fff4;
}
.hljs-deletion {
color: #b31d28;
background-color: #ffeef0;
}

54
book/book/highlight.js Normal file
View file

File diff suppressed because one or more lines are too long

256
book/book/index.html Normal file
View file

@ -0,0 +1,256 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Introduction - Refraction Forger</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="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" id="highlight-css" href="highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="refraction-forger"><a class="header" href="#refraction-forger">Refraction Forger</a></h1>
<p>Refraction Forger is a declarative image building tool that creates optimized OS images from simple specification files. It is designed for infrastructure engineers, DevOps teams, and OS distribution maintainers who need reproducible, cacheable image builds across multiple platforms.</p>
<h2 id="what-it-does"><a class="header" href="#what-it-does">What It Does</a></h2>
<p>Forger reads a <code>.kdl</code> specification file that declares what your image should contain — packages, files, users, boot configuration — and produces ready-to-deploy artifacts:</p>
<ul>
<li><strong>QCOW2 virtual machine images</strong> with ZFS or ext4 filesystems</li>
<li><strong>OCI container images</strong> for container runtimes</li>
<li><strong>Tar archives</strong> for further processing or embedding</li>
</ul>
<p>Built artifacts can be pushed directly to OCI registries like GHCR.</p>
<h2 id="why-forger"><a class="header" href="#why-forger">Why Forger?</a></h2>
<p>Traditional image building tools fall into two camps:</p>
<ol>
<li><strong>Shell script orchestrators</strong> (like the illumos <code>image-builder</code>) that require a matching host OS, root privileges, and careful manual sequencing.</li>
<li><strong>ISO boot automators</strong> (like HashiCorp Packer) that spin up a full installer, type keystrokes into a virtual console, and wait — slowly.</li>
</ol>
<p>Forger takes a different approach. It assembles images <em>directly</em> by calling package managers and filesystem tools, skipping the installer entirely. Builds that took 20+ minutes with Packer complete in a fraction of the time.</p>
<p>When your host doesn't match the target OS, Forger automatically spins up an ephemeral builder VM, transfers the spec, builds inside it, and retrieves the artifacts — no manual VM management needed.</p>
<h2 id="primary-focus"><a class="header" href="#primary-focus">Primary Focus</a></h2>
<p>Forger's primary focus is <strong>illumos</strong> distributions, particularly <strong>OmniOS</strong>. The illumos ecosystem uses IPS (Image Packaging System) and ZFS, both of which Forger understands natively.</p>
<p>Linux support (starting with <strong>Ubuntu</strong>) is included as a secondary target. The long-term goal is to bring IPS to Linux via a Rust implementation, making Forger's packaging model available across operating systems. In the meantime, popular Linux distributions are supported to provide a broad userbase familiar with tools like Packer.</p>
<h2 id="how-this-book-is-organized"><a class="header" href="#how-this-book-is-organized">How This Book Is Organized</a></h2>
<ul>
<li><strong>Getting Started</strong> walks you through installation and building your first image.</li>
<li><strong>The KDL Spec Language</strong> is a complete guide to writing image specifications.</li>
<li><strong>Composability</strong> explains how to chain builds, share configuration, and create variants.</li>
<li><strong>Distro Guide</strong> covers distribution-specific details for illumos and Linux.</li>
<li><strong>Output Formats</strong> describes each artifact type and how to deploy them.</li>
<li><strong>Architecture</strong> explains the internal design for contributors and advanced users.</li>
<li><strong>Migration</strong> helps you move from <code>omnios-image-builder</code> or Packer.</li>
<li><strong>Reference</strong> provides CLI help, spec schema, and complete examples.</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="next prefetch" href="getting-started/installation.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="next prefetch" href="getting-started/installation.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 -->
</div>
</body>
</html>

256
book/book/introduction.html Normal file
View file

@ -0,0 +1,256 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Introduction - Refraction Forger</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="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" id="highlight-css" href="highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="refraction-forger"><a class="header" href="#refraction-forger">Refraction Forger</a></h1>
<p>Refraction Forger is a declarative image building tool that creates optimized OS images from simple specification files. It is designed for infrastructure engineers, DevOps teams, and OS distribution maintainers who need reproducible, cacheable image builds across multiple platforms.</p>
<h2 id="what-it-does"><a class="header" href="#what-it-does">What It Does</a></h2>
<p>Forger reads a <code>.kdl</code> specification file that declares what your image should contain — packages, files, users, boot configuration — and produces ready-to-deploy artifacts:</p>
<ul>
<li><strong>QCOW2 virtual machine images</strong> with ZFS or ext4 filesystems</li>
<li><strong>OCI container images</strong> for container runtimes</li>
<li><strong>Tar archives</strong> for further processing or embedding</li>
</ul>
<p>Built artifacts can be pushed directly to OCI registries like GHCR.</p>
<h2 id="why-forger"><a class="header" href="#why-forger">Why Forger?</a></h2>
<p>Traditional image building tools fall into two camps:</p>
<ol>
<li><strong>Shell script orchestrators</strong> (like the illumos <code>image-builder</code>) that require a matching host OS, root privileges, and careful manual sequencing.</li>
<li><strong>ISO boot automators</strong> (like HashiCorp Packer) that spin up a full installer, type keystrokes into a virtual console, and wait — slowly.</li>
</ol>
<p>Forger takes a different approach. It assembles images <em>directly</em> by calling package managers and filesystem tools, skipping the installer entirely. Builds that took 20+ minutes with Packer complete in a fraction of the time.</p>
<p>When your host doesn't match the target OS, Forger automatically spins up an ephemeral builder VM, transfers the spec, builds inside it, and retrieves the artifacts — no manual VM management needed.</p>
<h2 id="primary-focus"><a class="header" href="#primary-focus">Primary Focus</a></h2>
<p>Forger's primary focus is <strong>illumos</strong> distributions, particularly <strong>OmniOS</strong>. The illumos ecosystem uses IPS (Image Packaging System) and ZFS, both of which Forger understands natively.</p>
<p>Linux support (starting with <strong>Ubuntu</strong>) is included as a secondary target. The long-term goal is to bring IPS to Linux via a Rust implementation, making Forger's packaging model available across operating systems. In the meantime, popular Linux distributions are supported to provide a broad userbase familiar with tools like Packer.</p>
<h2 id="how-this-book-is-organized"><a class="header" href="#how-this-book-is-organized">How This Book Is Organized</a></h2>
<ul>
<li><strong>Getting Started</strong> walks you through installation and building your first image.</li>
<li><strong>The KDL Spec Language</strong> is a complete guide to writing image specifications.</li>
<li><strong>Composability</strong> explains how to chain builds, share configuration, and create variants.</li>
<li><strong>Distro Guide</strong> covers distribution-specific details for illumos and Linux.</li>
<li><strong>Output Formats</strong> describes each artifact type and how to deploy them.</li>
<li><strong>Architecture</strong> explains the internal design for contributors and advanced users.</li>
<li><strong>Migration</strong> helps you move from <code>omnios-image-builder</code> or Packer.</li>
<li><strong>Reference</strong> provides CLI help, spec schema, and complete examples.</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="next prefetch" href="getting-started/installation.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="next prefetch" href="getting-started/installation.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 -->
</div>
</body>
</html>

7
book/book/mark.min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

354
book/book/migration/from-image-builder.html Normal file
View file

@ -0,0 +1,354 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>From omnios-image-builder - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="from-omnios-image-builder"><a class="header" href="#from-omnios-image-builder">From omnios-image-builder</a></h1>
<p>This guide helps you migrate from the shell-based <code>omnios-image-builder</code> to Forger.</p>
<h2 id="architecture-comparison"><a class="header" href="#architecture-comparison">Architecture Comparison</a></h2>
<div class="table-wrapper"><table><thead><tr><th>omnios-image-builder</th><th>Forger</th></tr></thead><tbody>
<tr><td>Shell scripts (<code>strap.sh</code>, <code>aws.sh</code>, etc.)</td><td>Single <code>forger</code> binary</td></tr>
<tr><td>JSON templates with step arrays</td><td>KDL specs with declarative blocks</td></tr>
<tr><td>ZFS snapshots for caching</td><td><code>base</code> directive for caching</td></tr>
<tr><td>Requires illumos host with ZFS + pfexec</td><td>Any host (remote builder VM)</td></tr>
<tr><td>Manual pipeline (01-strap → 02-image → 03-archive → final)</td><td>Implicit pipeline via <code>base</code>/<code>include</code></td></tr>
</tbody></table>
</div>
<h2 id="mapping-concepts"><a class="header" href="#mapping-concepts">Mapping Concepts</a></h2>
<h3 id="json-steps--kdl-blocks"><a class="header" href="#json-steps--kdl-blocks">JSON Steps → KDL Blocks</a></h3>
<p>The old JSON templates used a <code>steps</code> array with typed objects:</p>
<pre><code class="language-json">{
"steps": [
{ "t": "pkg_image_create", "publisher": "omnios", "uri": "https://..." },
{ "t": "pkg_install", "pkgs": ["entire"] },
{ "t": "pkg_change_variant", "variant": "opensolaris.zone", "value": "global" }
]
}
</code></pre>
<p>In Forger, these become declarative blocks:</p>
<pre><code class="language-kdl">repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
}
</code></pre>
<h3 id="step-type-mapping"><a class="header" href="#step-type-mapping">Step Type Mapping</a></h3>
<div class="table-wrapper"><table><thead><tr><th>JSON Step</th><th>KDL Equivalent</th></tr></thead><tbody>
<tr><td><code>pkg_image_create</code></td><td><code>repositories { publisher ... }</code> (implicit)</td></tr>
<tr><td><code>pkg_set_publisher</code></td><td><code>repositories { publisher ... }</code></td></tr>
<tr><td><code>pkg_install</code></td><td><code>packages { package "..." }</code></td></tr>
<tr><td><code>pkg_change_variant</code></td><td><code>variants { set ... }</code></td></tr>
<tr><td><code>pkg_approve_ca_cert</code></td><td><code>certificates { ca ... }</code></td></tr>
<tr><td><code>pkg_uninstall</code></td><td>Not needed (don't install unwanted packages)</td></tr>
<tr><td><code>pkg_purge_history</code></td><td>Handled automatically</td></tr>
<tr><td><code>pkg_set_property</code></td><td>Handled automatically</td></tr>
<tr><td><code>ensure_file</code></td><td><code>overlays { file ... }</code></td></tr>
<tr><td><code>ensure_dir</code></td><td><code>overlays { ensure-dir ... }</code></td></tr>
<tr><td><code>ensure_symlink</code></td><td><code>overlays { ensure-symlink ... }</code></td></tr>
<tr><td><code>remove_files</code></td><td><code>overlays { remove-files ... }</code></td></tr>
<tr><td><code>shadow</code></td><td><code>overlays { shadow ... }</code></td></tr>
<tr><td><code>devfsadm</code></td><td><code>overlays { devfsadm }</code></td></tr>
<tr><td><code>seed_smf</code></td><td>Handled automatically</td></tr>
<tr><td><code>include</code></td><td><code>include "file.kdl"</code></td></tr>
<tr><td><code>create_be</code></td><td>Handled automatically (QCOW2 target)</td></tr>
<tr><td><code>unpack_tar</code></td><td>Handled automatically (<code>base</code> directive)</td></tr>
<tr><td><code>make_bootable</code></td><td><code>target ... { bootloader "uefi" }</code></td></tr>
<tr><td><code>pack_tar</code></td><td><code>target "..." kind="artifact"</code></td></tr>
</tbody></table>
</div>
<h3 id="three-stage-pipeline--base--child"><a class="header" href="#three-stage-pipeline--base--child">Three-Stage Pipeline → Base + Child</a></h3>
<p><strong>Old approach</strong> (three JSON files + shell orchestration):</p>
<pre><code>01-strap.json → pkg install entire → snapshot "strap"
02-image.json → pkg install extras → snapshot "image"
03-archive.json → pack_tar → omnios-bloody.tar.gz
aws.json → unpack_tar + make_bootable → raw disk
</code></pre>
<p><strong>New approach</strong> (two KDL files):</p>
<pre><code class="language-kdl">// omnios-base.kdl
repositories { publisher name="omnios" ... }
incorporation "entire"
packages { package "/editor/vim" ... }
</code></pre>
<pre><code class="language-kdl">// omnios-disk.kdl
base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages { package "/system/cloud-init" }
overlays { file destination="/boot/conf.d/console" ... }
target "vm" kind="qcow2" { ... }
</code></pre>
<p>The <code>base</code> directive replaces the ZFS snapshot pipeline. The parent's output is cached, and the child builds on top.</p>
<h3 id="pool-configuration"><a class="header" href="#pool-configuration">Pool Configuration</a></h3>
<p><strong>Old</strong> (<code>pool</code> in JSON):</p>
<pre><code class="language-json">{
"pool": { "name": "rpool", "ashift": 12, "uefi": true, "size": 2000 }
}
</code></pre>
<p><strong>New</strong> (in target block):</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "2000M"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<h3 id="output-formats"><a class="header" href="#output-formats">Output Formats</a></h3>
<p><strong>Old</strong>: Raw disk images only (convert to QCOW2/AMI externally)</p>
<p><strong>New</strong>: QCOW2 natively, plus OCI container images and tar artifacts</p>
<h3 id="cloud-provider-scripts"><a class="header" href="#cloud-provider-scripts">Cloud Provider Scripts</a></h3>
<p>The old <code>aws.sh</code>, <code>digitalocean.sh</code>, and <code>smartosbhyve.sh</code> scripts are replaced by profiles or separate specs:</p>
<pre><code class="language-kdl">// Cloud-provider-specific overlays via profiles
overlays if="aws" {
file destination="/boot/conf.d/console" source="files/boot_console.aws"
}
overlays if="digitalocean" {
file destination="/boot/conf.d/console" source="files/boot_console.do"
}
</code></pre>
<h2 id="migration-checklist"><a class="header" href="#migration-checklist">Migration Checklist</a></h2>
<ol>
<li>Identify your JSON templates and their step sequences</li>
<li>Map each step to the equivalent KDL block (see table above)</li>
<li>Split the three-stage pipeline into base + child specs</li>
<li>Move overlay files to a <code>files/</code> directory relative to the specs</li>
<li>Replace <code>setup.sh</code> dependency management with <code>forger</code> binary installation</li>
<li>Test with <code>forger validate</code> and <code>forger inspect</code> before building</li>
</ol>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../architecture/builder-vm.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 prefetch" href="../migration/from-packer.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="../architecture/builder-vm.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 prefetch" href="../migration/from-packer.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 -->
</div>
</body>
</html>

382
book/book/migration/from-packer.html Normal file
View file

@ -0,0 +1,382 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>From Packer (oi-packer) - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="from-packer-oi-packer"><a class="header" href="#from-packer-oi-packer">From Packer (oi-packer)</a></h1>
<p>This guide helps you migrate from HashiCorp Packer-based illumos image building to Forger.</p>
<h2 id="why-migrate"><a class="header" href="#why-migrate">Why Migrate?</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Packer</th><th>Forger</th></tr></thead><tbody>
<tr><td>Boots ISO, types keystrokes, waits</td><td>Direct package manager assembly</td></tr>
<tr><td>20+ minute builds</td><td>Minutes</td></tr>
<tr><td>No native caching</td><td>Multi-stage caching via <code>base</code></td></tr>
<tr><td>Shell provisioners (order-sensitive)</td><td>Declarative KDL spec</td></tr>
<tr><td>Vagrant boxes, raw disks</td><td>QCOW2, OCI, tar artifacts</td></tr>
<tr><td>External upload scripts</td><td>Built-in OCI registry push</td></tr>
</tbody></table>
</div>
<h2 id="mapping-concepts"><a class="header" href="#mapping-concepts">Mapping Concepts</a></h2>
<h3 id="packer-source--not-needed"><a class="header" href="#packer-source--not-needed">Packer Source → Not Needed</a></h3>
<p>Packer sources define the VM that runs the installer:</p>
<pre><code class="language-hcl">source "qemu" "oi-hipster" {
iso_url = "https://dlc.openindiana.org/isos/..."
iso_checksum = "sha256:..."
disk_size = "51200M"
memory = 4096
accelerator = "kvm"
}
</code></pre>
<p>Forger doesn't boot an ISO. It calls the package manager directly, so there's no installer VM to configure.</p>
<h3 id="boot-command--not-needed"><a class="header" href="#boot-command--not-needed">Boot Command → Not Needed</a></h3>
<p>Packer's boot command types keystrokes into the installer:</p>
<pre><code class="language-hcl">boot_command = [
"&lt;wait10&gt;&lt;wait10&gt;&lt;wait10&gt;",
"47&lt;enter&gt;&lt;wait&gt;", // Select installation
"7&lt;enter&gt;&lt;wait&gt;", // Select bootloader
// ... dozens more keystrokes
]
</code></pre>
<p>Forger skips the installer entirely. Package installation happens through direct <code>pkg</code> or <code>apt</code> calls.</p>
<h3 id="shell-provisioners--kdl-blocks"><a class="header" href="#shell-provisioners--kdl-blocks">Shell Provisioners → KDL Blocks</a></h3>
<p><strong>Packer</strong> (shell scripts that SSH into the VM):</p>
<pre><code class="language-hcl">provisioner "shell" {
scripts = [
"scripts/update.sh", // pkg update
"scripts/vagrant.sh", // Create vagrant user, install SSH keys
"scripts/cleanup.sh", // Remove SSH host keys, clear logs
]
}
</code></pre>
<p><strong>Forger</strong> (declarative):</p>
<pre><code class="language-kdl">packages {
package "/editor/vim"
package "/network/openssh-server"
}
customization {
user "deploy"
}
overlays {
file destination="/home/deploy/.ssh/authorized_keys" source="files/authorized_keys"
shadow username="deploy" password="$5$..."
}
</code></pre>
<h3 id="post-processors--targets"><a class="header" href="#post-processors--targets">Post-Processors → Targets</a></h3>
<p><strong>Packer</strong> (Vagrant box post-processor):</p>
<pre><code class="language-hcl">post-processor "vagrant" {
compression_level = 9
output = "OI-hipster-{{.Provider}}.box"
}
</code></pre>
<p><strong>Forger</strong> (target block):</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
push-to "ghcr.io/myorg/my-image:latest"
}
</code></pre>
<p>Forger doesn't produce Vagrant boxes directly. Instead, it produces QCOW2 images that work with QEMU/KVM, Proxmox, and other hypervisors. OCI container images are also available.</p>
<h3 id="variables--profiles"><a class="header" href="#variables--profiles">Variables → Profiles</a></h3>
<p><strong>Packer</strong> (HCL variables):</p>
<pre><code class="language-hcl">variable "build_version" { default = "20240426" }
</code></pre>
<p><strong>Forger</strong> (profiles for variants):</p>
<pre><code class="language-kdl">packages if="dev" {
package "/diagnostic/top"
}
</code></pre>
<h2 id="full-migration-example"><a class="header" href="#full-migration-example">Full Migration Example</a></h2>
<h3 id="packer-template-before"><a class="header" href="#packer-template-before">Packer Template (before)</a></h3>
<pre><code class="language-hcl">source "qemu" "oi-hipster" {
iso_url = "https://dlc.openindiana.org/isos/hipster/20240426/OI-hipster-text-20240426.iso"
disk_size = "51200M"
memory = 4096
format = "qcow2"
boot_command = ["&lt;wait30&gt;", "47&lt;enter&gt;", /* ... 30 more lines ... */]
}
build {
sources = ["source.qemu.oi-hipster"]
provisioner "shell" { scripts = ["scripts/update.sh"] }
provisioner "shell" { scripts = ["scripts/vagrant.sh"] }
provisioner "shell" { scripts = ["scripts/cleanup.sh"] }
post-processor "vagrant" {
output = "OI-hipster-{{.Provider}}.box"
}
}
</code></pre>
<h3 id="forger-spec-after"><a class="header" href="#forger-spec-after">Forger Spec (after)</a></h3>
<pre><code class="language-kdl">metadata name="oi-hipster" version="1.0.0" description="OpenIndiana Hipster image"
repositories {
publisher name="openindiana.org" origin="http://pkg.openindiana.org/hipster/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/driver/network/vioif"
package "/driver/storage/vioblk"
}
customization {
user "deploy"
}
overlays {
file destination="/home/deploy/.ssh/authorized_keys" source="files/authorized_keys"
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
push-to "ghcr.io/myorg/oi-hipster:latest"
}
</code></pre>
<p>Build time drops from 20+ minutes (ISO boot + install + provisioning) to a few minutes (direct package installation).</p>
<h2 id="migration-checklist"><a class="header" href="#migration-checklist">Migration Checklist</a></h2>
<ol>
<li>Identify packages installed by your shell provisioners</li>
<li>List files copied or modified by provisioners</li>
<li>Translate to KDL <code>packages</code>, <code>overlays</code>, and <code>customization</code> blocks</li>
<li>Replace ISO-based installation with <code>repositories</code> + <code>incorporation</code></li>
<li>Replace Vagrant post-processor with QCOW2 target + OCI push</li>
<li>Test with <code>forger validate</code> and <code>forger inspect</code></li>
<li>Build and verify the image boots correctly</li>
</ol>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../migration/from-image-builder.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 prefetch" href="../reference/cli.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="../migration/from-image-builder.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 prefetch" href="../reference/cli.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 -->
</div>
</body>
</html>

3034
book/book/print.html Normal file
View file

File diff suppressed because it is too large Load diff

335
book/book/reference/cli.html Normal file
View file

@ -0,0 +1,335 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>CLI Reference - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="cli-reference"><a class="header" href="#cli-reference">CLI Reference</a></h1>
<h2 id="forger-build"><a class="header" href="#forger-build">forger build</a></h2>
<p>Build an image from a spec file.</p>
<pre><code>forger build [OPTIONS] --spec &lt;PATH&gt;
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--spec &lt;PATH&gt;</code></td><td>Path to the KDL spec file (required)</td></tr>
<tr><td><code>--target &lt;NAME&gt;</code></td><td>Build only this target (default: all)</td></tr>
<tr><td><code>--profile &lt;PROFILE&gt;</code></td><td>Activate a profile (repeatable)</td></tr>
<tr><td><code>--output-dir &lt;PATH&gt;</code></td><td>Output directory (default: <code>./output</code>)</td></tr>
<tr><td><code>--local</code></td><td>Force local build (skip builder VM)</td></tr>
<tr><td><code>--use-builder</code></td><td>Force build inside a builder VM</td></tr>
<tr><td><code>--skip-push</code></td><td>Don't push to registry after build</td></tr>
<tr><td><code>--builder-image &lt;SPEC&gt;</code></td><td>Override builder VM image</td></tr>
</tbody></table>
</div>
<h3 id="examples"><a class="header" href="#examples">Examples</a></h3>
<pre><code class="language-bash"># Build all targets
forger build --spec images/omnios-bloody-disk.kdl
# Build specific target with profile
forger build --spec images/omnios-bloody-disk.kdl --target vm --profile build
# Force local build, custom output directory
forger build --spec images/omnios-bloody-disk.kdl --local --output-dir /tmp/images
# Build with custom builder image
forger build --spec images/ubuntu-rust-ci.kdl --builder-image /path/to/builder.qcow2
</code></pre>
<h2 id="forger-validate"><a class="header" href="#forger-validate">forger validate</a></h2>
<p>Parse and check a spec file for errors.</p>
<pre><code>forger validate --spec &lt;PATH&gt;
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--spec &lt;PATH&gt;</code></td><td>Path to the KDL spec file (required)</td></tr>
</tbody></table>
</div>
<p>Checks:</p>
<ul>
<li>KDL syntax</li>
<li>Schema conformance</li>
<li>Include/base resolution</li>
<li>Circular dependency detection</li>
</ul>
<h3 id="example"><a class="header" href="#example">Example</a></h3>
<pre><code class="language-bash">forger validate --spec images/omnios-bloody-disk.kdl
</code></pre>
<h2 id="forger-inspect"><a class="header" href="#forger-inspect">forger inspect</a></h2>
<p>Parse, resolve, and apply profiles, then display the resolved spec.</p>
<pre><code>forger inspect [OPTIONS] --spec &lt;PATH&gt;
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--spec &lt;PATH&gt;</code></td><td>Path to the KDL spec file (required)</td></tr>
<tr><td><code>--profile &lt;PROFILE&gt;</code></td><td>Activate a profile (repeatable)</td></tr>
</tbody></table>
</div>
<h3 id="examples-1"><a class="header" href="#examples-1">Examples</a></h3>
<pre><code class="language-bash"># Inspect without profiles
forger inspect --spec images/omnios-bloody-disk.kdl
# Inspect with build profile to see what's included
forger inspect --spec images/omnios-bloody-disk.kdl --profile build
</code></pre>
<h2 id="forger-push"><a class="header" href="#forger-push">forger push</a></h2>
<p>Push a built artifact to an OCI registry.</p>
<pre><code>forger push [OPTIONS] --image &lt;PATH&gt; --reference &lt;REF&gt;
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--image &lt;PATH&gt;</code></td><td>Path to OCI Image Layout directory or QCOW2 file</td></tr>
<tr><td><code>--reference &lt;REF&gt;</code></td><td>Registry reference (e.g., <code>ghcr.io/org/image:tag</code>)</td></tr>
<tr><td><code>--auth-file &lt;PATH&gt;</code></td><td>JSON auth file (optional)</td></tr>
<tr><td><code>--artifact</code></td><td>Push QCOW2 as OCI artifact</td></tr>
</tbody></table>
</div>
<h3 id="examples-2"><a class="header" href="#examples-2">Examples</a></h3>
<pre><code class="language-bash"># Push OCI image
forger push --image output/container/ --reference ghcr.io/myorg/myimage:latest
# Push QCOW2 as artifact
forger push --image output/vm.qcow2 --reference ghcr.io/myorg/myvm:latest --artifact
# Push with auth file
forger push --image output/container/ \
--reference registry.example.com/myimage:latest \
--auth-file auth.json
</code></pre>
<h2 id="forger-targets"><a class="header" href="#forger-targets">forger targets</a></h2>
<p>List targets defined in a spec file.</p>
<pre><code>forger targets --spec &lt;PATH&gt;
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody>
<tr><td><code>--spec &lt;PATH&gt;</code></td><td>Path to the KDL spec file (required)</td></tr>
</tbody></table>
</div>
<h3 id="example-1"><a class="header" href="#example-1">Example</a></h3>
<pre><code class="language-bash">forger targets --spec images/omnios-bloody-disk.kdl
</code></pre>
<p>Output:</p>
<pre><code>vm (qcow2)
</code></pre>
<h2 id="environment-variables"><a class="header" href="#environment-variables">Environment Variables</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody>
<tr><td><code>GITHUB_TOKEN</code></td><td>Used for GHCR authentication when pushing</td></tr>
<tr><td><code>RUST_LOG</code></td><td>Logging level (e.g., <code>info</code>, <code>debug</code>, <code>trace</code>)</td></tr>
</tbody></table>
</div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../migration/from-packer.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 prefetch" href="../reference/spec-reference.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="../migration/from-packer.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 prefetch" href="../reference/spec-reference.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 -->
</div>
</body>
</html>

401
book/book/reference/examples.html Normal file
View file

@ -0,0 +1,401 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Example Specs - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="example-specs"><a class="header" href="#example-specs">Example Specs</a></h1>
<p>Complete, production-ready examples from the <code>images/</code> directory.</p>
<h2 id="omnios-bloody-base"><a class="header" href="#omnios-bloody-base">OmniOS Bloody Base</a></h2>
<p>A reusable base spec for OmniOS bloody images. This is typically used as a <code>base</code> for other specs.</p>
<pre><code class="language-kdl">metadata name="omnios-bloody-base" version="1.0.0" description="Base OmniOS bloody image"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
package "/web/curl"
package "/web/wget"
package "/system/cloud-init"
}
packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
package "/developer/build/gnu-make"
}
</code></pre>
<h2 id="omnios-bloody-bootable-disk"><a class="header" href="#omnios-bloody-bootable-disk">OmniOS Bloody Bootable Disk</a></h2>
<p>A bootable QCOW2 VM image built on top of the base. Includes device filesystem setup, network configuration, and boot console settings.</p>
<pre><code class="language-kdl">metadata name="omnios-bloody-disk" version="1.0.0" description="OmniOS bloody bootable disk"
base "omnios-bloody-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/system/cloud-init"
package "/driver/virtio/viorand"
package "/driver/virtio/vioif"
package "/driver/virtio/vioblk"
package "/driver/virtio/vio9p"
package "/driver/virtio/vioscsi"
}
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
file destination="/etc/ttydefs" source="files/ttydefs.115200"
file destination="/etc/default/init" source="files/default_init.utc"
shadow username="root" password="$5$rounds=10000$..."
}
target "vm" kind="qcow2" {
disk-size "2000M"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
</code></pre>
<h2 id="omnios-rust-ci-image"><a class="header" href="#omnios-rust-ci-image">OmniOS Rust CI Image</a></h2>
<p>An OmniOS image with the Rust toolchain for continuous integration.</p>
<pre><code class="language-kdl">metadata name="omnios-rust-ci" version="1.0.0" description="OmniOS Rust CI image"
base "omnios-bloody-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/ooce/developer/rust"
package "/developer/versioning/git"
package "/system/cloud-init"
package "/driver/virtio/viorand"
package "/driver/virtio/vioif"
package "/driver/virtio/vioblk"
package "/driver/virtio/vio9p"
package "/driver/virtio/vioscsi"
}
builder {
image "oci://ghcr.io/cloudnebulaproject/omnios-builder:latest"
vcpus 4
memory 4096
disk 20
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
push-to "ghcr.io/cloudnebulaproject/omnios-rust:latest"
}
</code></pre>
<h2 id="ubuntu-rust-ci-image"><a class="header" href="#ubuntu-rust-ci-image">Ubuntu Rust CI Image</a></h2>
<p>An Ubuntu 22.04 image with the Rust toolchain.</p>
<pre><code class="language-kdl">metadata name="ubuntu-rust-ci" version="1.0.0" description="Ubuntu 22.04 Rust CI image"
distro "ubuntu-22.04"
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
packages {
package "build-essential"
package "rustc"
package "cargo"
package "git"
package "curl"
package "openssh-server"
package "cloud-init"
package "linux-image-generic"
package "grub-efi-amd64-bin"
package "libssl-dev"
package "pkg-config"
}
customization {
user "ci"
}
builder {
image "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest"
vcpus 4
memory 4096
disk 20
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
push-to "ghcr.io/cloudnebulaproject/ubuntu-rust:latest"
}
</code></pre>
<h2 id="device-filesystem-include"><a class="header" href="#device-filesystem-include">Device Filesystem Include</a></h2>
<p>Standard device node setup for bootable illumos images.</p>
<pre><code class="language-kdl">overlays {
devfsadm
remove-files "/dev/dsk" "/dev/rdsk" "/dev/cfg" "/dev/usb"
ensure-dir "/dev/cfg" owner="root" group="root" mode="755"
ensure-dir "/dev/dsk" owner="root" group="root" mode="755"
ensure-dir "/dev/rdsk" owner="root" group="root" mode="755"
ensure-dir "/dev/usb" owner="root" group="root" mode="755"
ensure-symlink "/dev/msglog" target="../devices/pseudo/log@0:msglog"
}
</code></pre>
<h2 id="common-system-configuration-include"><a class="header" href="#common-system-configuration-include">Common System Configuration Include</a></h2>
<p>Standard network and SMF profile setup for illumos images.</p>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
file destination="/etc/inet/hosts" source="files/etc/hosts"
file destination="/etc/nodename" source="files/etc/nodename"
file destination="/etc/resolv.conf" source="files/etc/resolv.conf"
ensure-symlink "/etc/nsswitch.conf" target="/etc/nsswitch.dns"
}
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../reference/spec-reference.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="../reference/spec-reference.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>
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 -->
</div>
</body>
</html>

394
book/book/reference/spec-reference.html Normal file
View file

@ -0,0 +1,394 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>KDL Spec Reference - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="kdl-spec-reference"><a class="header" href="#kdl-spec-reference">KDL Spec Reference</a></h1>
<p>Complete reference for all KDL spec nodes and properties.</p>
<h2 id="top-level-nodes"><a class="header" href="#top-level-nodes">Top-Level Nodes</a></h2>
<h3 id="metadata"><a class="header" href="#metadata">metadata</a></h3>
<pre><code class="language-kdl">metadata name="&lt;string&gt;" version="&lt;string&gt;" description="&lt;string&gt;"
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>name</code></td><td>string</td><td>Yes</td><td>Image name</td></tr>
<tr><td><code>version</code></td><td>string</td><td>Yes</td><td>Semantic version</td></tr>
<tr><td><code>description</code></td><td>string</td><td>No</td><td>Human-readable description</td></tr>
</tbody></table>
</div>
<h3 id="distro"><a class="header" href="#distro">distro</a></h3>
<pre><code class="language-kdl">distro "&lt;string&gt;"
</code></pre>
<p>Distro identifier. Determines the build path (IPS vs APT). Omit for OmniOS (default).</p>
<div class="table-wrapper"><table><thead><tr><th>Value</th><th>Family</th></tr></thead><tbody>
<tr><td><em>(omitted)</em></td><td>OmniOS</td></tr>
<tr><td><code>"ubuntu-22.04"</code></td><td>Ubuntu</td></tr>
</tbody></table>
</div>
<h3 id="base"><a class="header" href="#base">base</a></h3>
<pre><code class="language-kdl">base "&lt;path&gt;"
</code></pre>
<p>Parent spec file. Creates a build-stage boundary for caching. Path is relative to the current spec file.</p>
<h3 id="include"><a class="header" href="#include">include</a></h3>
<pre><code class="language-kdl">include "&lt;path&gt;"
</code></pre>
<p>Sibling spec file to merge. Imports shared steps. Path is relative to the current spec file.</p>
<h3 id="incorporation"><a class="header" href="#incorporation">incorporation</a></h3>
<pre><code class="language-kdl">incorporation "&lt;string&gt;"
</code></pre>
<p>IPS incorporation constraint (OmniOS only). Typically <code>"entire"</code>.</p>
<h2 id="block-nodes"><a class="header" href="#block-nodes">Block Nodes</a></h2>
<h3 id="repositories"><a class="header" href="#repositories">repositories</a></h3>
<pre><code class="language-kdl">repositories {
publisher name="&lt;string&gt;" origin="&lt;url&gt;"
apt-mirror "&lt;url&gt;" suite="&lt;string&gt;" components="&lt;string&gt;"
}
</code></pre>
<p><strong>publisher</strong> (IPS):</p>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>name</code></td><td>string</td><td>Yes</td></tr>
<tr><td><code>origin</code></td><td>string (URL)</td><td>Yes</td></tr>
</tbody></table>
</div>
<p><strong>apt-mirror</strong> (APT):</p>
<div class="table-wrapper"><table><thead><tr><th>Argument</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><em>(positional)</em></td><td>string (URL)</td><td>Yes</td></tr>
<tr><td><code>suite</code></td><td>string</td><td>Yes</td></tr>
<tr><td><code>components</code></td><td>string (space-separated)</td><td>Yes</td></tr>
</tbody></table>
</div>
<h3 id="certificates"><a class="header" href="#certificates">certificates</a></h3>
<pre><code class="language-kdl">certificates {
ca publisher="&lt;string&gt;" certfile="&lt;path&gt;"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>publisher</code></td><td>string</td><td>Yes</td></tr>
<tr><td><code>certfile</code></td><td>string (path)</td><td>Yes</td></tr>
</tbody></table>
</div>
<h3 id="variants"><a class="header" href="#variants">variants</a></h3>
<pre><code class="language-kdl">variants {
set name="&lt;string&gt;" value="&lt;string&gt;"
}
</code></pre>
<p>IPS variant settings. Common: <code>name="opensolaris.zone" value="global"</code>.</p>
<h3 id="packages"><a class="header" href="#packages">packages</a></h3>
<pre><code class="language-kdl">packages if="&lt;profile&gt;" {
package "&lt;name&gt;"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>if</code></td><td>string</td><td>No</td></tr>
</tbody></table>
</div>
<p>The <code>if</code> property enables profile filtering. Omit for unconditional packages.</p>
<h3 id="overlays"><a class="header" href="#overlays">overlays</a></h3>
<pre><code class="language-kdl">overlays if="&lt;profile&gt;" {
file destination="&lt;path&gt;" source="&lt;path&gt;"
ensure-dir "&lt;path&gt;" owner="&lt;string&gt;" group="&lt;string&gt;" mode="&lt;string&gt;"
ensure-symlink "&lt;path&gt;" target="&lt;path&gt;"
remove-files "&lt;path&gt;" "&lt;path&gt;" ...
shadow username="&lt;string&gt;" password="&lt;string&gt;"
devfsadm
}
</code></pre>
<p><strong>file</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>destination</code></td><td>string (absolute path)</td><td>Yes</td></tr>
<tr><td><code>source</code></td><td>string (relative path)</td><td>Yes</td></tr>
</tbody></table>
</div>
<p><strong>ensure-dir</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Argument/Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><em>(positional)</em></td><td>string (path)</td><td>Yes</td></tr>
<tr><td><code>owner</code></td><td>string</td><td>No</td></tr>
<tr><td><code>group</code></td><td>string</td><td>No</td></tr>
<tr><td><code>mode</code></td><td>string (octal)</td><td>No</td></tr>
</tbody></table>
</div>
<p><strong>ensure-symlink</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Argument/Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><em>(positional)</em></td><td>string (link path)</td><td>Yes</td></tr>
<tr><td><code>target</code></td><td>string (target path)</td><td>Yes</td></tr>
</tbody></table>
</div>
<p><strong>remove-files</strong>: One or more path arguments.</p>
<p><strong>shadow</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>username</code></td><td>string</td><td>Yes</td></tr>
<tr><td><code>password</code></td><td>string (crypt hash)</td><td>Yes</td></tr>
</tbody></table>
</div>
<p><strong>devfsadm</strong>: No arguments.</p>
<h3 id="customization"><a class="header" href="#customization">customization</a></h3>
<pre><code class="language-kdl">customization if="&lt;profile&gt;" {
user "&lt;username&gt;"
}
</code></pre>
<h3 id="builder"><a class="header" href="#builder">builder</a></h3>
<pre><code class="language-kdl">builder {
image "&lt;string&gt;"
vcpus &lt;integer&gt;
memory &lt;integer&gt;
disk &lt;integer&gt;
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th><th>Default</th></tr></thead><tbody>
<tr><td><code>image</code></td><td>string</td><td>No</td><td>Distro default</td></tr>
<tr><td><code>vcpus</code></td><td>integer</td><td>No</td><td>Host-dependent</td></tr>
<tr><td><code>memory</code></td><td>integer (MB)</td><td>No</td><td>Host-dependent</td></tr>
<tr><td><code>disk</code></td><td>integer (GB)</td><td>No</td><td>20</td></tr>
</tbody></table>
</div>
<h3 id="target"><a class="header" href="#target">target</a></h3>
<pre><code class="language-kdl">target "&lt;name&gt;" kind="&lt;kind&gt;" {
// kind-specific properties
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><em>(positional)</em></td><td>string (name)</td><td>Yes</td></tr>
<tr><td><code>kind</code></td><td>string</td><td>Yes</td></tr>
</tbody></table>
</div>
<p><strong>kind="qcow2"</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>disk-size</code></td><td>string (e.g., "8G")</td><td>Yes</td></tr>
<tr><td><code>bootloader</code></td><td>string</td><td>Yes</td></tr>
<tr><td><code>filesystem</code></td><td>string</td><td>No</td></tr>
<tr><td><code>push-to</code></td><td>string (registry ref)</td><td>No</td></tr>
<tr><td><code>pool</code> children</td><td>property nodes</td><td>No</td></tr>
</tbody></table>
</div>
<p><strong>kind="oci"</strong>:</p>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Type</th><th>Required</th></tr></thead><tbody>
<tr><td><code>entrypoint</code></td><td>node with <code>command</code></td><td>No</td></tr>
<tr><td><code>environment</code> children</td><td><code>set</code> nodes</td><td>No</td></tr>
<tr><td><code>push-to</code></td><td>string</td><td>No</td></tr>
</tbody></table>
</div>
<p><strong>kind="artifact"</strong>: No additional properties.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../reference/cli.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 prefetch" href="../reference/examples.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="../reference/cli.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 prefetch" href="../reference/examples.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 -->
</div>
</body>
</html>

554
book/book/searcher.js Normal file
View file

@ -0,0 +1,554 @@
'use strict';
/* global Mark, elasticlunr, path_to_root */
window.search = window.search || {};
(function search() {
// Search functionality
//
// You can use !hasFocus() to prevent keyhandling in your key
// event handlers while the user is typing their search.
if (!Mark || !elasticlunr) {
return;
}
// eslint-disable-next-line max-len
// IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
if (!String.prototype.startsWith) {
String.prototype.startsWith = function(search, pos) {
return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
};
}
const search_wrap = document.getElementById('search-wrapper'),
searchbar_outer = document.getElementById('searchbar-outer'),
searchbar = document.getElementById('searchbar'),
searchresults = document.getElementById('searchresults'),
searchresults_outer = document.getElementById('searchresults-outer'),
searchresults_header = document.getElementById('searchresults-header'),
searchicon = document.getElementById('search-toggle'),
content = document.getElementById('content'),
// SVG text elements don't render if inside a <mark> tag.
mark_exclude = ['text'],
marker = new Mark(content),
URL_SEARCH_PARAM = 'search',
URL_MARK_PARAM = 'highlight';
let current_searchterm = '',
doc_urls = [],
search_options = {
bool: 'AND',
expand: true,
fields: {
title: {boost: 1},
body: {boost: 1},
breadcrumbs: {boost: 0},
},
},
searchindex = null,
results_options = {
teaser_word_count: 30,
limit_results: 30,
},
teaser_count = 0;
function hasFocus() {
return searchbar === document.activeElement;
}
function removeChildren(elem) {
while (elem.firstChild) {
elem.removeChild(elem.firstChild);
}
}
// Helper to parse a url into its building blocks.
function parseURL(url) {
const a = document.createElement('a');
a.href = url;
return {
source: url,
protocol: a.protocol.replace(':', ''),
host: a.hostname,
port: a.port,
params: (function() {
const ret = {};
const seg = a.search.replace(/^\?/, '').split('&');
for (const part of seg) {
if (!part) {
continue;
}
const s = part.split('=');
ret[s[0]] = s[1];
}
return ret;
})(),
file: (a.pathname.match(/\/([^/?#]+)$/i) || ['', ''])[1],
hash: a.hash.replace('#', ''),
path: a.pathname.replace(/^([^/])/, '/$1'),
};
}
// Helper to recreate a url string from its building blocks.
function renderURL(urlobject) {
let url = urlobject.protocol + '://' + urlobject.host;
if (urlobject.port !== '') {
url += ':' + urlobject.port;
}
url += urlobject.path;
let joiner = '?';
for (const prop in urlobject.params) {
if (Object.prototype.hasOwnProperty.call(urlobject.params, prop)) {
url += joiner + prop + '=' + urlobject.params[prop];
joiner = '&';
}
}
if (urlobject.hash !== '') {
url += '#' + urlobject.hash;
}
return url;
}
// Helper to escape html special chars for displaying the teasers
const escapeHTML = (function() {
const MAP = {
'&': '&amp;',
'<': '&lt;',
'>': '&gt;',
'"': '&#34;',
'\'': '&#39;',
};
const repl = function(c) {
return MAP[c];
};
return function(s) {
return s.replace(/[&<>'"]/g, repl);
};
})();
function formatSearchMetric(count, searchterm) {
if (count === 1) {
return count + ' search result for \'' + searchterm + '\':';
} else if (count === 0) {
return 'No search results for \'' + searchterm + '\'.';
} else {
return count + ' search results for \'' + searchterm + '\':';
}
}
function formatSearchResult(result, searchterms) {
const teaser = makeTeaser(escapeHTML(result.doc.body), searchterms);
teaser_count++;
// The ?URL_MARK_PARAM= parameter belongs inbetween the page and the #heading-anchor
const url = doc_urls[result.ref].split('#');
if (url.length === 1) { // no anchor found
url.push('');
}
// encodeURIComponent escapes all chars that could allow an XSS except
// for '. Due to that we also manually replace ' with its url-encoded
// representation (%27).
const encoded_search = encodeURIComponent(searchterms.join(' ')).replace(/'/g, '%27');
return '<a href="' + path_to_root + url[0] + '?' + URL_MARK_PARAM + '=' + encoded_search
+ '#' + url[1] + '" aria-details="teaser_' + teaser_count + '">'
+ result.doc.breadcrumbs + '</a>' + '<span class="teaser" id="teaser_' + teaser_count
+ '" aria-label="Search Result Teaser">' + teaser + '</span>';
}
function makeTeaser(body, searchterms) {
// The strategy is as follows:
// First, assign a value to each word in the document:
// Words that correspond to search terms (stemmer aware): 40
// Normal words: 2
// First word in a sentence: 8
// Then use a sliding window with a constant number of words and count the
// sum of the values of the words within the window. Then use the window that got the
// maximum sum. If there are multiple maximas, then get the last one.
// Enclose the terms in <em>.
const stemmed_searchterms = searchterms.map(function(w) {
return elasticlunr.stemmer(w.toLowerCase());
});
const searchterm_weight = 40;
const weighted = []; // contains elements of ["word", weight, index_in_document]
// split in sentences, then words
const sentences = body.toLowerCase().split('. ');
let index = 0;
let value = 0;
let searchterm_found = false;
for (const sentenceindex in sentences) {
const words = sentences[sentenceindex].split(' ');
value = 8;
for (const wordindex in words) {
const word = words[wordindex];
if (word.length > 0) {
for (const searchtermindex in stemmed_searchterms) {
if (elasticlunr.stemmer(word).startsWith(
stemmed_searchterms[searchtermindex])
) {
value = searchterm_weight;
searchterm_found = true;
}
}
weighted.push([word, value, index]);
value = 2;
}
index += word.length;
index += 1; // ' ' or '.' if last word in sentence
}
index += 1; // because we split at a two-char boundary '. '
}
if (weighted.length === 0) {
return body;
}
const window_weight = [];
const window_size = Math.min(weighted.length, results_options.teaser_word_count);
let cur_sum = 0;
for (let wordindex = 0; wordindex < window_size; wordindex++) {
cur_sum += weighted[wordindex][1];
}
window_weight.push(cur_sum);
for (let wordindex = 0; wordindex < weighted.length - window_size; wordindex++) {
cur_sum -= weighted[wordindex][1];
cur_sum += weighted[wordindex + window_size][1];
window_weight.push(cur_sum);
}
let max_sum_window_index = 0;
if (searchterm_found) {
let max_sum = 0;
// backwards
for (let i = window_weight.length - 1; i >= 0; i--) {
if (window_weight[i] > max_sum) {
max_sum = window_weight[i];
max_sum_window_index = i;
}
}
} else {
max_sum_window_index = 0;
}
// add <em/> around searchterms
const teaser_split = [];
index = weighted[max_sum_window_index][2];
for (let i = max_sum_window_index; i < max_sum_window_index + window_size; i++) {
const word = weighted[i];
if (index < word[2]) {
// missing text from index to start of `word`
teaser_split.push(body.substring(index, word[2]));
index = word[2];
}
if (word[1] === searchterm_weight) {
teaser_split.push('<em>');
}
index = word[2] + word[0].length;
teaser_split.push(body.substring(word[2], index));
if (word[1] === searchterm_weight) {
teaser_split.push('</em>');
}
}
return teaser_split.join('');
}
function init(config) {
results_options = config.results_options;
search_options = config.search_options;
doc_urls = config.doc_urls;
searchindex = elasticlunr.Index.load(config.index);
searchbar_outer.classList.remove('searching');
searchbar.focus();
const searchterm = searchbar.value.trim();
if (searchterm !== '') {
searchbar.classList.add('active');
doSearch(searchterm);
}
}
function initSearchInteractions(config) {
// Set up events
searchicon.addEventListener('click', () => {
searchIconClickHandler();
}, false);
searchbar.addEventListener('keyup', () => {
searchbarKeyUpHandler();
}, false);
document.addEventListener('keydown', e => {
globalKeyHandler(e);
}, false);
// If the user uses the browser buttons, do the same as if a reload happened
window.onpopstate = () => {
doSearchOrMarkFromUrl();
};
// Suppress "submit" events so the page doesn't reload when the user presses Enter
document.addEventListener('submit', e => {
e.preventDefault();
}, false);
// If reloaded, do the search or mark again, depending on the current url parameters
doSearchOrMarkFromUrl();
// Exported functions
config.hasFocus = hasFocus;
}
initSearchInteractions(window.search);
function unfocusSearchbar() {
// hacky, but just focusing a div only works once
const tmp = document.createElement('input');
tmp.setAttribute('style', 'position: absolute; opacity: 0;');
searchicon.appendChild(tmp);
tmp.focus();
tmp.remove();
}
// On reload or browser history backwards/forwards events, parse the url and do search or mark
function doSearchOrMarkFromUrl() {
// Check current URL for search request
const url = parseURL(window.location.href);
if (Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM)
&& url.params[URL_SEARCH_PARAM] !== '') {
showSearch(true);
searchbar.value = decodeURIComponent(
(url.params[URL_SEARCH_PARAM] + '').replace(/\+/g, '%20'));
searchbarKeyUpHandler(); // -> doSearch()
} else {
showSearch(false);
}
if (Object.prototype.hasOwnProperty.call(url.params, URL_MARK_PARAM)) {
const words = decodeURIComponent(url.params[URL_MARK_PARAM]).split(' ');
marker.mark(words, {
exclude: mark_exclude,
});
const markers = document.querySelectorAll('mark');
const hide = () => {
for (let i = 0; i < markers.length; i++) {
markers[i].classList.add('fade-out');
window.setTimeout(() => {
marker.unmark();
}, 300);
}
};
for (let i = 0; i < markers.length; i++) {
markers[i].addEventListener('click', hide);
}
}
}
// Eventhandler for keyevents on `document`
function globalKeyHandler(e) {
if (e.altKey ||
e.ctrlKey ||
e.metaKey ||
e.shiftKey ||
e.target.type === 'textarea' ||
e.target.type === 'text' ||
!hasFocus() && /^(?:input|select|textarea)$/i.test(e.target.nodeName)
) {
return;
}
if (e.key === 'Escape') {
e.preventDefault();
searchbar.classList.remove('active');
setSearchUrlParameters('',
searchbar.value.trim() !== '' ? 'push' : 'replace');
if (hasFocus()) {
unfocusSearchbar();
}
showSearch(false);
marker.unmark();
} else if (!hasFocus() && (e.key === 's' || e.key === '/')) {
e.preventDefault();
showSearch(true);
window.scrollTo(0, 0);
searchbar.select();
} else if (hasFocus() && (e.key === 'ArrowDown'
|| e.key === 'Enter')) {
e.preventDefault();
const first = searchresults.firstElementChild;
if (first !== null) {
unfocusSearchbar();
first.classList.add('focus');
if (e.key === 'Enter') {
window.location.assign(first.querySelector('a'));
}
}
} else if (!hasFocus() && (e.key === 'ArrowDown'
|| e.key === 'ArrowUp'
|| e.key === 'Enter')) {
// not `:focus` because browser does annoying scrolling
const focused = searchresults.querySelector('li.focus');
if (!focused) {
return;
}
e.preventDefault();
if (e.key === 'ArrowDown') {
const next = focused.nextElementSibling;
if (next) {
focused.classList.remove('focus');
next.classList.add('focus');
}
} else if (e.key === 'ArrowUp') {
focused.classList.remove('focus');
const prev = focused.previousElementSibling;
if (prev) {
prev.classList.add('focus');
} else {
searchbar.select();
}
} else { // Enter
window.location.assign(focused.querySelector('a'));
}
}
}
function loadSearchScript(url, id) {
if (document.getElementById(id)) {
return;
}
searchbar_outer.classList.add('searching');
const script = document.createElement('script');
script.src = url;
script.id = id;
script.onload = () => init(window.search);
script.onerror = error => {
console.error(`Failed to load \`${url}\`: ${error}`);
};
document.head.append(script);
}
function showSearch(yes) {
if (yes) {
loadSearchScript(
window.path_to_searchindex_js ||
path_to_root + 'searchindex.js',
'search-index');
search_wrap.classList.remove('hidden');
searchicon.setAttribute('aria-expanded', 'true');
} else {
search_wrap.classList.add('hidden');
searchicon.setAttribute('aria-expanded', 'false');
const results = searchresults.children;
for (let i = 0; i < results.length; i++) {
results[i].classList.remove('focus');
}
}
}
function showResults(yes) {
if (yes) {
searchresults_outer.classList.remove('hidden');
} else {
searchresults_outer.classList.add('hidden');
}
}
// Eventhandler for search icon
function searchIconClickHandler() {
if (search_wrap.classList.contains('hidden')) {
showSearch(true);
window.scrollTo(0, 0);
searchbar.select();
} else {
showSearch(false);
}
}
// Eventhandler for keyevents while the searchbar is focused
function searchbarKeyUpHandler() {
const searchterm = searchbar.value.trim();
if (searchterm !== '') {
searchbar.classList.add('active');
doSearch(searchterm);
} else {
searchbar.classList.remove('active');
showResults(false);
removeChildren(searchresults);
}
setSearchUrlParameters(searchterm, 'push_if_new_search_else_replace');
// Remove marks
marker.unmark();
}
// Update current url with ?URL_SEARCH_PARAM= parameter, remove ?URL_MARK_PARAM and
// `#heading-anchor`. `action` can be one of "push", "replace",
// "push_if_new_search_else_replace" and replaces or pushes a new browser history item.
// "push_if_new_search_else_replace" pushes if there is no `?URL_SEARCH_PARAM=abc` yet.
function setSearchUrlParameters(searchterm, action) {
const url = parseURL(window.location.href);
const first_search = !Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM);
if (searchterm !== '' || action === 'push_if_new_search_else_replace') {
url.params[URL_SEARCH_PARAM] = searchterm;
delete url.params[URL_MARK_PARAM];
url.hash = '';
} else {
delete url.params[URL_MARK_PARAM];
delete url.params[URL_SEARCH_PARAM];
}
// A new search will also add a new history item, so the user can go back
// to the page prior to searching. A updated search term will only replace
// the url.
if (action === 'push' || action === 'push_if_new_search_else_replace' && first_search ) {
history.pushState({}, document.title, renderURL(url));
} else if (action === 'replace' ||
action === 'push_if_new_search_else_replace' &&
!first_search
) {
history.replaceState({}, document.title, renderURL(url));
}
}
function doSearch(searchterm) {
// Don't search the same twice
if (current_searchterm === searchterm) {
return;
}
searchbar_outer.classList.add('searching');
if (searchindex === null) {
return;
}
current_searchterm = searchterm;
// Do the actual search
const results = searchindex.search(searchterm, search_options);
const resultcount = Math.min(results.length, results_options.limit_results);
// Display search metrics
searchresults_header.innerText = formatSearchMetric(resultcount, searchterm);
// Clear and insert results
const searchterms = searchterm.split(' ');
removeChildren(searchresults);
for (let i = 0; i < resultcount ; i++) {
const resultElem = document.createElement('li');
resultElem.innerHTML = formatSearchResult(results[i], searchterms);
searchresults.appendChild(resultElem);
}
// Display results
showResults(true);
searchbar_outer.classList.remove('searching');
}
// Exported functions
search.hasFocus = hasFocus;
})(window.search);

1
book/book/searchindex.js Normal file
View file

File diff suppressed because one or more lines are too long

297
book/book/spec/builder.html Normal file
View file

@ -0,0 +1,297 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Builder Configuration - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="builder-configuration"><a class="header" href="#builder-configuration">Builder Configuration</a></h1>
<p>The <code>builder</code> block configures the ephemeral VM used for remote builds. This is optional — Forger selects sensible defaults when omitted.</p>
<h2 id="syntax"><a class="header" href="#syntax">Syntax</a></h2>
<pre><code class="language-kdl">builder {
image "oci://ghcr.io/cloudnebulaproject/omnios-builder:latest"
vcpus 4
memory 4096
disk 20
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody>
<tr><td><code>image</code></td><td>No</td><td>Distro-specific default</td><td>Builder VM image (OCI ref, URL, or path)</td></tr>
<tr><td><code>vcpus</code></td><td>No</td><td>Host-dependent</td><td>Number of virtual CPUs</td></tr>
<tr><td><code>memory</code></td><td>No</td><td>Host-dependent</td><td>Memory in MB</td></tr>
<tr><td><code>disk</code></td><td>No</td><td>20 (GB)</td><td>Disk overlay size in GB</td></tr>
</tbody></table>
</div>
<h2 id="image-sources"><a class="header" href="#image-sources">Image Sources</a></h2>
<p>The <code>image</code> property accepts three formats:</p>
<h3 id="oci-registry-reference"><a class="header" href="#oci-registry-reference">OCI Registry Reference</a></h3>
<pre><code class="language-kdl">builder {
image "oci://ghcr.io/myorg/my-builder:latest"
}
</code></pre>
<p>Pulls a QCOW2 image from an OCI registry.</p>
<h3 id="url"><a class="header" href="#url">URL</a></h3>
<pre><code class="language-kdl">builder {
image "https://example.com/builders/omnios-builder.qcow2"
}
</code></pre>
<p>Downloads the image directly.</p>
<h3 id="local-path"><a class="header" href="#local-path">Local Path</a></h3>
<pre><code class="language-kdl">builder {
image "/path/to/my-builder.qcow2"
}
</code></pre>
<p>Uses a local QCOW2 file.</p>
<h2 id="default-builder-images"><a class="header" href="#default-builder-images">Default Builder Images</a></h2>
<p>When no builder image is specified (neither in the spec nor on the CLI), Forger uses:</p>
<div class="table-wrapper"><table><thead><tr><th>Distro</th><th>Default Image</th></tr></thead><tbody>
<tr><td>OmniOS</td><td><code>oci://ghcr.io/cloudnebulaproject/omnios-builder:latest</code></td></tr>
<tr><td>Ubuntu</td><td><code>oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest</code></td></tr>
</tbody></table>
</div>
<h2 id="how-the-builder-vm-works"><a class="header" href="#how-the-builder-vm-works">How the Builder VM Works</a></h2>
<ol>
<li><strong>Image resolution</strong>: Downloads or locates the builder image</li>
<li><strong>Cloud-init</strong>: Generates a user-data config with an ephemeral SSH keypair and a <code>builder</code> user with passwordless sudo</li>
<li><strong>VM creation</strong>: Starts QEMU with user-mode networking (no host root needed)</li>
<li><strong>SSH connection</strong>: Retries SSH connection for up to 120 seconds while the VM boots</li>
<li><strong>Transfer</strong>: Uploads the <code>forger</code> binary, spec files, and overlay files</li>
<li><strong>Build</strong>: Executes the build command inside the VM</li>
<li><strong>Download</strong>: Retrieves the build artifacts</li>
<li><strong>Teardown</strong>: Destroys the VM (guaranteed, even on build failure)</li>
</ol>
<h2 id="cli-override"><a class="header" href="#cli-override">CLI Override</a></h2>
<p>The builder image can be overridden from the CLI, taking precedence over the spec:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --builder-image /path/to/custom-builder.qcow2
</code></pre>
<h2 id="resource-sizing"><a class="header" href="#resource-sizing">Resource Sizing</a></h2>
<p>For typical builds:</p>
<ul>
<li><strong>OmniOS base image</strong>: 2 vCPUs, 2048 MB RAM is sufficient</li>
<li><strong>OmniOS with Rust/build tools</strong>: 4 vCPUs, 4096 MB RAM recommended</li>
<li><strong>Ubuntu with build-essential</strong>: 4 vCPUs, 4096 MB RAM recommended</li>
<li><strong>Disk</strong>: 20 GB is sufficient for most images; increase for large package sets</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/targets.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 prefetch" href="../composability/base.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="../spec/targets.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 prefetch" href="../composability/base.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 -->
</div>
</body>
</html>

269
book/book/spec/customizations.html Normal file
View file

@ -0,0 +1,269 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Customizations - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="customizations"><a class="header" href="#customizations">Customizations</a></h1>
<p>The <code>customization</code> block configures users and system-level settings.</p>
<h2 id="users"><a class="header" href="#users">Users</a></h2>
<p>Create a user in the image:</p>
<pre><code class="language-kdl">customization {
user "ci"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><em>(argument)</em></td><td>Yes</td><td>Username to create</td></tr>
</tbody></table>
</div>
<p>The user is created with default settings appropriate for the target distro.</p>
<h2 id="conditional-customizations"><a class="header" href="#conditional-customizations">Conditional Customizations</a></h2>
<p>Like packages and overlays, customization blocks support profile filtering:</p>
<pre><code class="language-kdl">customization if="ci" {
user "ci"
}
</code></pre>
<p>This user is only created when the <code>ci</code> profile is active:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --profile ci
</code></pre>
<h2 id="combined-with-overlays"><a class="header" href="#combined-with-overlays">Combined with Overlays</a></h2>
<p>For full user setup, combine customization with overlay operations:</p>
<pre><code class="language-kdl">customization {
user "deploy"
}
overlays {
// Set user password
shadow username="deploy" password="$5$..."
// Ensure SSH directory
ensure-dir "/home/deploy/.ssh" owner="deploy" group="staff" mode="700"
// Deploy authorized keys
file destination="/home/deploy/.ssh/authorized_keys" source="files/authorized_keys"
}
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/overlays.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 prefetch" href="../spec/targets.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="../spec/overlays.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 prefetch" href="../spec/targets.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 -->
</div>
</body>
</html>

264
book/book/spec/metadata.html Normal file
View file

@ -0,0 +1,264 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Metadata &amp; Distro - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="metadata--distro"><a class="header" href="#metadata--distro">Metadata &amp; Distro</a></h1>
<h2 id="metadata"><a class="header" href="#metadata">Metadata</a></h2>
<p>The <code>metadata</code> node identifies your image:</p>
<pre><code class="language-kdl">metadata name="omnios-base" version="1.0.0" description="Base OmniOS bloody image"
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>name</code></td><td>Yes</td><td>Image name (used in output filenames)</td></tr>
<tr><td><code>version</code></td><td>Yes</td><td>Semantic version</td></tr>
<tr><td><code>description</code></td><td>No</td><td>Human-readable description</td></tr>
</tbody></table>
</div>
<h2 id="distro-selection"><a class="header" href="#distro-selection">Distro Selection</a></h2>
<p>The <code>distro</code> node tells Forger which OS family to target. This determines the package manager, filesystem defaults, and build path.</p>
<pre><code class="language-kdl">distro "ubuntu-22.04"
</code></pre>
<h3 id="supported-values"><a class="header" href="#supported-values">Supported Values</a></h3>
<div class="table-wrapper"><table><thead><tr><th>Distro String</th><th>Family</th><th>Package Manager</th><th>Default Filesystem</th></tr></thead><tbody>
<tr><td><em>(omitted)</em></td><td>OmniOS</td><td>IPS (<code>pkg</code>)</td><td>ZFS</td></tr>
<tr><td><code>"ubuntu-22.04"</code></td><td>Ubuntu</td><td>APT (<code>debootstrap</code> + <code>apt</code>)</td><td>ext4</td></tr>
</tbody></table>
</div>
<h3 id="how-distro-affects-the-build"><a class="header" href="#how-distro-affects-the-build">How Distro Affects the Build</a></h3>
<p>The distro string maps to a <code>DistroFamily</code> internally:</p>
<ul>
<li><strong>OmniOS</strong>: Uses <code>pkg image-create</code> to initialize IPS, sets publishers, handles incorporations, variants, and CA certificates. ZFS is the default filesystem for QCOW2 targets.</li>
<li><strong>Ubuntu</strong>: Uses <code>debootstrap</code> for initial rootfs, writes <code>sources.list</code>, runs <code>apt update</code> and <code>apt install</code>. ext4 is the default filesystem for QCOW2 targets.</li>
</ul>
<p>If no <code>distro</code> is specified, OmniOS is assumed. This reflects Forger's primary focus on the illumos ecosystem.</p>
<h3 id="distro-and-builder-images"><a class="header" href="#distro-and-builder-images">Distro and Builder Images</a></h3>
<p>The distro also determines the default builder VM image when no explicit builder is configured:</p>
<div class="table-wrapper"><table><thead><tr><th>Distro Family</th><th>Default Builder</th></tr></thead><tbody>
<tr><td>OmniOS</td><td><code>oci://ghcr.io/cloudnebulaproject/omnios-builder:latest</code></td></tr>
<tr><td>Ubuntu</td><td><code>oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest</code></td></tr>
</tbody></table>
</div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/overview.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 prefetch" href="../spec/repositories.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="../spec/overview.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 prefetch" href="../spec/repositories.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 -->
</div>
</body>
</html>

331
book/book/spec/overlays.html Normal file
View file

@ -0,0 +1,331 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Overlays - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="overlays"><a class="header" href="#overlays">Overlays</a></h1>
<p>Overlays let you place files, create directories, manage symlinks, and configure system state in the image. They run after package installation.</p>
<h2 id="file-overlay"><a class="header" href="#file-overlay">File Overlay</a></h2>
<p>Copy a local file into the image:</p>
<pre><code class="language-kdl">overlays {
file destination="/etc/ssh/sshd_config" source="files/etc/sshd_config"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>destination</code></td><td>Yes</td><td>Absolute path in the image</td></tr>
<tr><td><code>source</code></td><td>Yes</td><td>Local file path (relative to spec file)</td></tr>
</tbody></table>
</div>
<h2 id="ensure-directory"><a class="header" href="#ensure-directory">Ensure Directory</a></h2>
<p>Create a directory with specific ownership and permissions:</p>
<pre><code class="language-kdl">overlays {
ensure-dir "/opt/myapp" owner="root" group="root" mode="755"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><em>(argument)</em></td><td>Yes</td><td>Directory path in the image</td></tr>
<tr><td><code>owner</code></td><td>No</td><td>Owner user</td></tr>
<tr><td><code>group</code></td><td>No</td><td>Owner group</td></tr>
<tr><td><code>mode</code></td><td>No</td><td>Octal permissions</td></tr>
</tbody></table>
</div>
<h2 id="ensure-symlink"><a class="header" href="#ensure-symlink">Ensure Symlink</a></h2>
<p>Create a symbolic link:</p>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/nsswitch.conf" target="/etc/nsswitch.dns"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><em>(argument)</em></td><td>Yes</td><td>Symlink path in the image</td></tr>
<tr><td><code>target</code></td><td>Yes</td><td>What the symlink points to</td></tr>
</tbody></table>
</div>
<p>This is commonly used for SMF profiles on illumos:</p>
<pre><code class="language-kdl">overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
}
</code></pre>
<h2 id="remove-files"><a class="header" href="#remove-files">Remove Files</a></h2>
<p>Remove files or directories from the image:</p>
<pre><code class="language-kdl">overlays {
remove-files "/dev/dsk" "/dev/rdsk" "/dev/cfg" "/dev/usb"
}
</code></pre>
<p>Takes one or more path arguments. Useful for cleaning up device nodes before recreating them with <code>devfsadm</code>.</p>
<h2 id="shadow-password"><a class="header" href="#shadow-password">Shadow Password</a></h2>
<p>Set a password hash for a user:</p>
<pre><code class="language-kdl">overlays {
shadow username="root" password="$5$rounds=10000$hashedvalue"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>username</code></td><td>Yes</td><td>User whose password to set</td></tr>
<tr><td><code>password</code></td><td>Yes</td><td>Password hash (crypt format)</td></tr>
</tbody></table>
</div>
<h2 id="device-filesystem-devfsadm"><a class="header" href="#device-filesystem-devfsadm">Device Filesystem (devfsadm)</a></h2>
<p>Run <code>devfsadm</code> to populate <code>/dev</code> with device nodes. This is essential for bootable illumos images:</p>
<pre><code class="language-kdl">overlays {
devfsadm
}
</code></pre>
<p>This is typically used in a dedicated <code>devfs.kdl</code> include file alongside directory creation and cleanup.</p>
<h2 id="conditional-overlays"><a class="header" href="#conditional-overlays">Conditional Overlays</a></h2>
<p>Like packages, overlay blocks can be scoped to profiles:</p>
<pre><code class="language-kdl">overlays if="debug" {
file destination="/etc/system" source="files/etc/system.debug"
}
</code></pre>
<h2 id="execution-order"><a class="header" href="#execution-order">Execution Order</a></h2>
<p>Overlays execute in the order they appear in the spec. When multiple spec files are composed (base + includes), overlays from the base run first, followed by includes in order, then the current spec.</p>
<h2 id="complete-example"><a class="header" href="#complete-example">Complete Example</a></h2>
<pre><code class="language-kdl">overlays {
// Clean up device directories
remove-files "/dev/dsk" "/dev/rdsk" "/dev/cfg" "/dev/usb"
// Recreate them
ensure-dir "/dev/cfg" owner="root" group="root" mode="755"
ensure-dir "/dev/dsk" owner="root" group="root" mode="755"
ensure-dir "/dev/rdsk" owner="root" group="root" mode="755"
ensure-dir "/dev/usb" owner="root" group="root" mode="755"
// Populate device nodes
devfsadm
// System configuration
file destination="/etc/inet/hosts" source="files/etc/hosts"
file destination="/etc/nodename" source="files/etc/nodename"
ensure-symlink "/etc/nsswitch.conf" target="/etc/nsswitch.dns"
// Root password
shadow username="root" password="$5$rounds=10000$..."
}
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/packages.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 prefetch" href="../spec/customizations.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="../spec/packages.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 prefetch" href="../spec/customizations.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 -->
</div>
</body>
</html>

314
book/book/spec/overview.html Normal file
View file

@ -0,0 +1,314 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Spec Overview - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="spec-overview"><a class="header" href="#spec-overview">Spec Overview</a></h1>
<p>Forger uses <a href="https://kdl.dev/">KDL</a> (KDL Document Language) as its specification format. KDL is a node-based document language that's more expressive than TOML or JSON while being more readable than YAML.</p>
<h2 id="why-kdl"><a class="header" href="#why-kdl">Why KDL?</a></h2>
<ul>
<li><strong>Node-based</strong>: natural fit for declaring image components (packages, files, targets)</li>
<li><strong>Arguments and properties</strong>: nodes can have positional arguments and named properties on the same line</li>
<li><strong>Children blocks</strong>: nested structure without deep indentation</li>
<li><strong>Type annotations</strong>: optional type safety</li>
<li><strong>Comments</strong>: <code>//</code> line comments and <code>/* */</code> block comments</li>
</ul>
<h2 id="spec-file-structure"><a class="header" href="#spec-file-structure">Spec File Structure</a></h2>
<p>A complete spec file has these top-level sections:</p>
<pre><code class="language-kdl">// Identity
metadata name="my-image" version="1.0.0" description="What this image is"
// Which OS (omit for OmniOS default)
distro "ubuntu-22.04"
// Composability
base "path/to/parent.kdl"
include "path/to/shared-steps.kdl"
// Package sources
repositories {
// IPS publishers or APT mirrors
}
// IPS-specific
incorporation "entire"
variants { /* ... */ }
certificates { /* ... */ }
// What to install
packages {
package "pkg-name"
}
// Files and directories to place
overlays {
// file, ensure-dir, ensure-symlink, shadow, devfsadm, remove-files
}
// Users and system setup
customization {
user "username"
}
// Builder VM config (optional)
builder {
image "oci://..."
vcpus 4
memory 4096
}
// What to produce
target "name" kind="qcow2" {
// target-specific settings
}
</code></pre>
<p>All sections are optional except that you need at least one <code>target</code> to build anything.</p>
<h2 id="file-resolution"><a class="header" href="#file-resolution">File Resolution</a></h2>
<p>Paths in <code>base</code>, <code>include</code>, and overlay <code>source</code> fields are resolved relative to the spec file's directory. This means you can organize specs and their supporting files together:</p>
<pre><code>images/
omnios-base.kdl
omnios-disk.kdl # base "omnios-base.kdl"
common.kdl
devfs.kdl
files/
etc/
hosts
resolv.conf
sshd_config
omniosce-ca.cert.pem
</code></pre>
<h2 id="validation"><a class="header" href="#validation">Validation</a></h2>
<p>Always validate before building:</p>
<pre><code class="language-bash">forger validate --spec my-image.kdl
</code></pre>
<p>This checks:</p>
<ul>
<li>KDL syntax correctness</li>
<li>Schema conformance (required fields, valid types)</li>
<li>Include/base resolution (files exist, no circular references)</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../getting-started/build-modes.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 prefetch" href="../spec/metadata.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="../getting-started/build-modes.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 prefetch" href="../spec/metadata.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 -->
</div>
</body>
</html>

293
book/book/spec/packages.html Normal file
View file

@ -0,0 +1,293 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Packages - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="packages"><a class="header" href="#packages">Packages</a></h1>
<p>The <code>packages</code> block declares which packages to install in the image. Package names follow the conventions of the target distro's package manager.</p>
<h2 id="basic-usage"><a class="header" href="#basic-usage">Basic Usage</a></h2>
<pre><code class="language-kdl">packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
}
</code></pre>
<p>Each <code>package</code> node takes a single argument: the package name.</p>
<h2 id="ips-package-names-omnios"><a class="header" href="#ips-package-names-omnios">IPS Package Names (OmniOS)</a></h2>
<p>IPS uses hierarchical FMRI (Fault Management Resource Identifier) paths:</p>
<pre><code class="language-kdl">packages {
package "/editor/vim" // Editors
package "/network/openssh-server" // Network services
package "/ooce/developer/rust" // OmniOS Community Extra (OOCE)
package "/developer/build/gnu-make" // Build tools
package "/driver/virtio/vioif" // Virtio network driver
}
</code></pre>
<p>The leading <code>/</code> is conventional for IPS. You can find available packages with <code>pkg search</code> on an OmniOS system or browse <a href="https://pkg.omnios.org">pkg.omnios.org</a>.</p>
<h2 id="apt-package-names-ubuntu"><a class="header" href="#apt-package-names-ubuntu">APT Package Names (Ubuntu)</a></h2>
<p>Ubuntu uses flat package names:</p>
<pre><code class="language-kdl">packages {
package "build-essential"
package "curl"
package "git"
package "openssh-server"
package "linux-image-generic"
}
</code></pre>
<h2 id="conditional-packages-profiles"><a class="header" href="#conditional-packages-profiles">Conditional Packages (Profiles)</a></h2>
<p>Packages can be scoped to a <a href="../composability/profiles.html">profile</a> using the <code>if</code> property. They're only installed when that profile is active:</p>
<pre><code class="language-kdl">// Always installed
packages {
package "/editor/vim"
package "/network/openssh-server"
}
// Only when building with --profile build
packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
package "/developer/build/gnu-make"
}
</code></pre>
<p>Build with a profile:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --profile build
</code></pre>
<p>Multiple <code>packages</code> blocks with different <code>if</code> conditions can coexist in a single spec.</p>
<h2 id="ips-incorporations"><a class="header" href="#ips-incorporations">IPS Incorporations</a></h2>
<p>For OmniOS, the <code>incorporation</code> node pins the entire OS to a consistent version set:</p>
<pre><code class="language-kdl">incorporation "entire"
</code></pre>
<p>This ensures all installed packages are compatible. The <code>entire</code> incorporation is standard for OmniOS and should almost always be included.</p>
<h2 id="ips-variants"><a class="header" href="#ips-variants">IPS Variants</a></h2>
<p>Variants control which facets of packages are installed:</p>
<pre><code class="language-kdl">variants {
set name="opensolaris.zone" value="global"
}
</code></pre>
<p>Setting <code>opensolaris.zone</code> to <code>"global"</code> ensures you get the full global-zone package set, including kernel modules and boot components. Use <code>"nonglobal"</code> for zone-only images.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/repositories.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 prefetch" href="../spec/overlays.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="../spec/repositories.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 prefetch" href="../spec/overlays.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 -->
</div>
</body>
</html>

279
book/book/spec/repositories.html Normal file
View file

@ -0,0 +1,279 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Repositories &amp; Publishers - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="repositories--publishers"><a class="header" href="#repositories--publishers">Repositories &amp; Publishers</a></h1>
<p>The <code>repositories</code> block defines where packages are fetched from. The syntax differs between IPS (OmniOS) and APT (Ubuntu).</p>
<h2 id="ips-publishers-omnios"><a class="header" href="#ips-publishers-omnios">IPS Publishers (OmniOS)</a></h2>
<p>OmniOS uses IPS publishers — named package repositories with a URL origin:</p>
<pre><code class="language-kdl">repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>name</code></td><td>Yes</td><td>Publisher name (e.g., <code>"omnios"</code>, <code>"extra.omnios"</code>)</td></tr>
<tr><td><code>origin</code></td><td>Yes</td><td>Repository URL</td></tr>
</tbody></table>
</div>
<h3 id="common-omnios-publishers"><a class="header" href="#common-omnios-publishers">Common OmniOS Publishers</a></h3>
<div class="table-wrapper"><table><thead><tr><th>Name</th><th>Origin</th><th>Contents</th></tr></thead><tbody>
<tr><td><code>omnios</code></td><td><code>https://pkg.omnios.org/bloody/core/</code></td><td>Core OS packages (bloody)</td></tr>
<tr><td><code>extra.omnios</code></td><td><code>https://pkg.omnios.org/bloody/extra/</code></td><td>Additional packages (bloody)</td></tr>
<tr><td><code>omnios</code></td><td><code>https://pkg.omnios.org/r151050/core/</code></td><td>Core OS packages (stable)</td></tr>
</tbody></table>
</div>
<h3 id="publisher-verification"><a class="header" href="#publisher-verification">Publisher Verification</a></h3>
<p>OmniOS publishers use signed packages. Configure CA certificates in the <a href="./repositories.html#certificates"><code>certificates</code></a> block to enable verification:</p>
<pre><code class="language-kdl">certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
</code></pre>
<p>The <code>certfile</code> path is resolved relative to the spec file's directory.</p>
<h2 id="apt-mirrors-ubuntu"><a class="header" href="#apt-mirrors-ubuntu">APT Mirrors (Ubuntu)</a></h2>
<p>Ubuntu uses APT repositories with suite and component selection:</p>
<pre><code class="language-kdl">repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><em>(argument)</em></td><td>Yes</td><td>Mirror URL</td></tr>
<tr><td><code>suite</code></td><td>Yes</td><td>Distribution codename (e.g., <code>"jammy"</code>)</td></tr>
<tr><td><code>components</code></td><td>Yes</td><td>Space-separated component list (e.g., <code>"main universe"</code>)</td></tr>
</tbody></table>
</div>
<h3 id="common-ubuntu-mirrors"><a class="header" href="#common-ubuntu-mirrors">Common Ubuntu Mirrors</a></h3>
<pre><code class="language-kdl">repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-updates" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-security" components="main universe"
}
</code></pre>
<h2 id="deduplication"><a class="header" href="#deduplication">Deduplication</a></h2>
<p>When specs are composed via <code>base</code> or <code>include</code>, repositories are merged by name (IPS) or URL (APT). Duplicate entries are deduplicated automatically.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/metadata.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 prefetch" href="../spec/packages.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="../spec/metadata.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 prefetch" href="../spec/packages.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 -->
</div>
</body>
</html>

331
book/book/spec/targets.html Normal file
View file

@ -0,0 +1,331 @@
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Targets - Refraction Forger</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="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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<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 (`/`)" 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">Refraction Forger</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">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</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="targets"><a class="header" href="#targets">Targets</a></h1>
<p>Targets define what Forger produces from the assembled rootfs. Each spec can have multiple targets, and you can build them selectively.</p>
<h2 id="target-kinds"><a class="header" href="#target-kinds">Target Kinds</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Kind</th><th>Description</th><th>Typical Use</th></tr></thead><tbody>
<tr><td><code>qcow2</code></td><td>Bootable VM disk image</td><td>Cloud VMs, hypervisors</td></tr>
<tr><td><code>oci</code></td><td>OCI container image</td><td>Container runtimes</td></tr>
<tr><td><code>artifact</code></td><td>Tar archive of the rootfs</td><td>Intermediate build stage, embedding</td></tr>
</tbody></table>
</div>
<h2 id="qcow2-target"><a class="header" href="#qcow2-target">QCOW2 Target</a></h2>
<p>Produces a bootable virtual machine disk image:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
push-to "ghcr.io/myorg/my-image:latest"
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody>
<tr><td><code>disk-size</code></td><td>Yes</td><td>—</td><td>Disk size (e.g., <code>"2G"</code>, <code>"2000M"</code>)</td></tr>
<tr><td><code>bootloader</code></td><td>Yes</td><td>—</td><td><code>"uefi"</code>, <code>"grub"</code>, or <code>"grub-efi-amd64-bin"</code></td></tr>
<tr><td><code>filesystem</code></td><td>No</td><td>Distro default</td><td><code>"zfs"</code> or <code>"ext4"</code></td></tr>
<tr><td><code>push-to</code></td><td>No</td><td>—</td><td>OCI registry reference for auto-push</td></tr>
<tr><td><code>pool</code></td><td>No</td><td>—</td><td>ZFS pool properties (ZFS only)</td></tr>
</tbody></table>
</div>
<h3 id="zfs-pool-properties"><a class="header" href="#zfs-pool-properties">ZFS Pool Properties</a></h3>
<pre><code class="language-kdl">pool {
property name="ashift" value="12"
}
</code></pre>
<p><code>ashift=12</code> sets the ZFS block alignment to 4K sectors, which is correct for modern storage.</p>
<h3 id="bootloader-options"><a class="header" href="#bootloader-options">Bootloader Options</a></h3>
<ul>
<li><strong><code>uefi</code></strong>: UEFI bootloader — recommended for illumos and modern Linux</li>
<li><strong><code>grub</code></strong>: Legacy GRUB — for BIOS-boot OmniOS images</li>
<li><strong><code>grub-efi-amd64-bin</code></strong>: GRUB EFI for Ubuntu — use with ext4</li>
</ul>
<h2 id="oci-target"><a class="header" href="#oci-target">OCI Target</a></h2>
<p>Produces an OCI container image:</p>
<pre><code class="language-kdl">target "container" kind="oci" {
entrypoint command="/bin/sh"
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
set "TZ" "UTC"
}
}
</code></pre>
<div class="table-wrapper"><table><thead><tr><th>Property</th><th>Required</th><th>Description</th></tr></thead><tbody>
<tr><td><code>entrypoint</code></td><td>No</td><td>Container entrypoint command</td></tr>
<tr><td><code>environment</code></td><td>No</td><td>Environment variables</td></tr>
</tbody></table>
</div>
<p>The OCI target produces an OCI Image Layout directory containing:</p>
<ul>
<li>Compressed tar.gz layer(s) of the rootfs</li>
<li>OCI manifest and config JSON</li>
<li>SHA256-based blob digests</li>
</ul>
<h2 id="artifact-target"><a class="header" href="#artifact-target">Artifact Target</a></h2>
<p>Produces a tar archive of the rootfs:</p>
<pre><code class="language-kdl">target "archive" kind="artifact" {
}
</code></pre>
<p>Artifact targets are the primary mechanism for <a href="../composability/pipelines.html">multi-stage pipelines</a>. A parent spec can produce an artifact that a child spec consumes as its base.</p>
<h2 id="multiple-targets"><a class="header" href="#multiple-targets">Multiple Targets</a></h2>
<p>A single spec can define multiple targets:</p>
<pre><code class="language-kdl">target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
}
target "container" kind="oci" {
entrypoint command="/usr/sbin/sshd"
}
target "archive" kind="artifact" {
}
</code></pre>
<p>Build all targets:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl
</code></pre>
<p>Build a specific target:</p>
<pre><code class="language-bash">forger build --spec my-image.kdl --target vm
</code></pre>
<h2 id="auto-push"><a class="header" href="#auto-push">Auto-Push</a></h2>
<p>When <code>push-to</code> is set on a target, Forger automatically pushes the artifact to the OCI registry after a successful build (unless <code>--skip-push</code> is used):</p>
<pre><code class="language-bash"># Build and push
forger build --spec my-image.kdl
# Build without pushing
forger build --spec my-image.kdl --skip-push
</code></pre>
<h2 id="listing-targets"><a class="header" href="#listing-targets">Listing Targets</a></h2>
<p>View all targets in a spec:</p>
<pre><code class="language-bash">forger targets --spec my-image.kdl
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../spec/customizations.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 prefetch" href="../spec/builder.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="../spec/customizations.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 prefetch" href="../spec/builder.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 -->
</div>
</body>
</html>

32
book/book/toc.html Normal file
View file

File diff suppressed because one or more lines are too long

70
book/book/toc.js Normal file
View file

File diff suppressed because one or more lines are too long

104
book/book/tomorrow-night.css Normal file
View file

@ -0,0 +1,104 @@
/* Tomorrow Night Theme */
/* https://github.com/jmblog/color-themes-for-highlightjs */
/* Original theme - https://github.com/chriskempson/tomorrow-theme */
/* https://github.com/jmblog/color-themes-for-highlightjs */
/* Tomorrow Comment */
.hljs-comment {
color: #969896;
}
/* Tomorrow Red */
.hljs-variable,
.hljs-attribute,
.hljs-attr,
.hljs-tag,
.hljs-regexp,
.ruby .hljs-constant,
.xml .hljs-tag .hljs-title,
.xml .hljs-pi,
.xml .hljs-doctype,
.html .hljs-doctype,
.css .hljs-id,
.css .hljs-class,
.css .hljs-pseudo {
color: #cc6666;
}
/* Tomorrow Orange */
.hljs-number,
.hljs-preprocessor,
.hljs-pragma,
.hljs-built_in,
.hljs-literal,
.hljs-params,
.hljs-constant {
color: #de935f;
}
/* Tomorrow Yellow */
.ruby .hljs-class .hljs-title,
.css .hljs-rule .hljs-attribute {
color: #f0c674;
}
/* Tomorrow Green */
.hljs-string,
.hljs-value,
.hljs-inheritance,
.hljs-header,
.hljs-name,
.ruby .hljs-symbol,
.xml .hljs-cdata {
color: #b5bd68;
}
/* Tomorrow Aqua */
.hljs-title,
.hljs-section,
.css .hljs-hexcolor {
color: #8abeb7;
}
/* Tomorrow Blue */
.hljs-function,
.python .hljs-decorator,
.python .hljs-title,
.ruby .hljs-function .hljs-title,
.ruby .hljs-title .hljs-keyword,
.perl .hljs-sub,
.javascript .hljs-title,
.coffeescript .hljs-title {
color: #81a2be;
}
/* Tomorrow Purple */
.hljs-keyword,
.javascript .hljs-function {
color: #b294bb;
}
.hljs {
display: block;
overflow-x: auto;
background: #1d1f21;
color: #c5c8c6;
}
.coffeescript .javascript,
.javascript .xml,
.tex .hljs-formula,
.xml .javascript,
.xml .vbscript,
.xml .css,
.xml .hljs-cdata {
opacity: 0.5;
}
.hljs-addition {
color: #718c00;
}
.hljs-deletion {
color: #c82829;
}

59
book/src/SUMMARY.md Normal file
View file

@ -0,0 +1,59 @@
# Summary
[Introduction](./introduction.md)
# Getting Started
- [Installation](./getting-started/installation.md)
- [Your First Image](./getting-started/first-image.md)
- [Build Modes](./getting-started/build-modes.md)
# The KDL Spec Language
- [Spec Overview](./spec/overview.md)
- [Metadata & Distro](./spec/metadata.md)
- [Repositories & Publishers](./spec/repositories.md)
- [Packages](./spec/packages.md)
- [Overlays](./spec/overlays.md)
- [Customizations](./spec/customizations.md)
- [Targets](./spec/targets.md)
- [Builder Configuration](./spec/builder.md)
# Composability
- [Base Specs (Build Caching)](./composability/base.md)
- [Includes (Shared Steps)](./composability/includes.md)
- [Profiles (Conditional Variants)](./composability/profiles.md)
- [Multi-Stage Pipelines](./composability/pipelines.md)
# Distro Guide
- [illumos Overview](./distros/illumos-overview.md)
- [OmniOS](./distros/omnios.md)
- [Ubuntu](./distros/ubuntu.md)
- [Adding a New Distro](./distros/adding-distro.md)
# Output Formats
- [QCOW2 VM Images](./formats/qcow2.md)
- [OCI Container Images](./formats/oci.md)
- [Tar Artifacts](./formats/artifact.md)
- [OCI Registry Push](./formats/registry.md)
# Architecture
- [Design Overview](./architecture/overview.md)
- [Two-Phase Build Pipeline](./architecture/pipeline.md)
- [Crate Structure](./architecture/crates.md)
- [Remote Builder VMs](./architecture/builder-vm.md)
# Migration
- [From omnios-image-builder](./migration/from-image-builder.md)
- [From Packer (oi-packer)](./migration/from-packer.md)
# Reference
- [CLI Reference](./reference/cli.md)
- [KDL Spec Reference](./reference/spec-reference.md)
- [Example Specs](./reference/examples.md)

107
book/src/architecture/builder-vm.md Normal file
View file

@ -0,0 +1,107 @@
# Remote Builder VMs
When the build host doesn't match the target OS, Forger delegates to an ephemeral builder VM. This chapter explains the internals.
## Lifecycle
```
1. Image Resolution
├── OCI reference → pull from registry
├── URL → download
└── Local path → use directly
2. Cloud-Init Generation
├── Generate ephemeral Ed25519 SSH keypair
├── Create user-data: builder user, SSH key, passwordless sudo
└── Create cloud-init ISO
3. VM Creation
├── Create VmSpec (CPU, memory, disk, network)
├── Network: user-mode (SLIRP) — no root required
├── Disk: overlay on builder image (20GB default)
└── Hypervisor: auto-detect via vm-manager
4. Boot & Connect
├── Start VM via hypervisor
└── SSH retry loop (up to 120 seconds)
5. Transfer
├── Upload forger binary via SCP
├── Upload spec files via SCP
└── Upload overlay files via SCP
6. Build
└── Execute forger build command via SSH
7. Download
└── Retrieve artifacts via SCP
8. Teardown (guaranteed, even on failure)
└── Destroy VM via hypervisor
```
## User-Mode Networking
Builder VMs use QEMU's user-mode networking (SLIRP). This means:
- **No root access** needed on the host
- **No bridge interfaces** to configure
- **No firewall rules** to manage
- Guest can access the internet through NAT
- Host communicates with guest via port forwarding
DNS is automatically configured if needed.
## Security Model
- SSH keys are **ephemeral** — generated per build, discarded after
- The builder user has **passwordless sudo** but only exists for the build duration
- The VM is **destroyed** after every build, even on failure
- No persistent state from previous builds leaks into new ones
## Custom Builder Images
Builder images are QCOW2 files with cloud-init support. To create your own:
1. Build a base image with Forger (or any tool)
2. Ensure `cloud-init` is installed and enabled
3. Ensure SSH server is running
4. Include all build dependencies (`pkg`, `qemu-img`, `zfs`, etc.)
5. Push to an OCI registry or host as a downloadable file
### Minimum Requirements for a Builder Image
- Cloud-init (for SSH key injection and user setup)
- SSH server
- The target distro's package manager
- `qemu-img` (for QCOW2 conversion)
- Filesystem tools (`zfs`/`zpool` for ZFS, `parted`/`mkfs.ext4` for ext4)
- Bootloader tools (GRUB, UEFI support)
## Disk Overlay
The builder VM uses a disk overlay (copy-on-write layer) on top of the builder image. This means:
- The original builder image is never modified
- The overlay provides additional working space (20GB by default)
- Multiple builds can run concurrently from the same builder image
## Troubleshooting
### VM Fails to Boot
- Check that the builder image has cloud-init enabled
- Verify QEMU is installed and accessible
- Check system resources (enough RAM and disk for the VM)
### SSH Connection Times Out
- The 120-second timeout may be insufficient for slow storage
- Check that the builder image's SSH server starts on boot
- Verify user-mode networking isn't blocked by firewall
### Build Fails Inside VM
- The error output from the remote build is captured and displayed
- Check that the builder image has all required tools installed
- For disk space issues, increase the disk overlay size in the builder config

112
book/src/architecture/crates.md Normal file
View file

@ -0,0 +1,112 @@
# Crate Structure
Forger is a Cargo workspace with five crates, each with a clear responsibility.
## Workspace Layout
```
crates/
├── forger/ CLI entry point
├── spec-parser/ KDL parsing and resolution
├── forge-engine/ Build execution (Phase 1 + Phase 2)
├── forge-builder/ Remote VM builds
└── forge-oci/ OCI image and registry operations
```
## forger (CLI)
The binary crate. Defines five subcommands via clap:
| Command | Description |
|---|---|
| `build` | Build image from spec |
| `validate` | Parse and check a spec |
| `inspect` | Show resolved, profile-filtered spec |
| `push` | Push artifact to OCI registry |
| `targets` | List targets in a spec |
This crate is thin — it parses CLI arguments and delegates to the library crates.
## spec-parser
Handles everything related to KDL spec files:
- **Parsing**: Uses the `knuffel` crate to deserialize KDL into Rust structs (`ImageSpec`, `Target`, `Package`, etc.)
- **Resolution**: Recursively resolves `base` and `include` references, merging specs while detecting circular dependencies
- **Profile filtering**: Removes conditional blocks that don't match active profiles
Key types:
- `ImageSpec` — Root spec structure
- `DistroFamily` — Enum discriminating OmniOS vs Ubuntu
- `Target` / `TargetKind` — Output target definitions
- `Overlays` — File operations (file, ensure-dir, ensure-symlink, shadow, devfsadm, remove-files)
## forge-engine
The build engine implementing both phases:
- **Phase 1** (`phase1/mod.rs`): Distro-specific rootfs assembly
- IPS operations for OmniOS
- debootstrap + APT for Ubuntu
- Overlay application (shared across distros)
- **Phase 2** (`phase2/mod.rs`): Target production
- `qcow2_zfs.rs`: ZFS pool creation, BE management
- `qcow2_ext4.rs`: Partitioning, ext4 formatting
- OCI image layout creation
- Tar artifact packaging
Key abstraction: **`ToolRunner` trait** — wraps all external tool execution (`pkg`, `apt`, `qemu-img`, `zfs`, `parted`, etc.) through a single interface. The real implementation (`SystemToolRunner`) uses `tokio::process::Command`. This trait enables testing without root access.
## forge-builder
Manages remote builds via ephemeral VMs:
1. Resolve builder image (OCI ref, URL, or path)
2. Generate ephemeral SSH keypair
3. Create cloud-init config
4. Start QEMU via `vm-manager` crate (user-mode networking)
5. SSH connect with retry (up to 120s)
6. Transfer forger binary + spec + files via SCP
7. Execute remote build via SSH
8. Download artifacts
9. Destroy VM (guaranteed cleanup)
Uses the external `vm-manager` crate for hypervisor abstraction (`RouterHypervisor` auto-detects QEMU/bhyve).
## forge-oci
OCI-specific operations:
- **tar_layer**: Compress rootfs into gzip layer
- **manifest**: Build OCI config and manifest JSON
- **layout**: Write OCI Image Layout directory structure
- **artifact**: Package QCOW2 as OCI artifact with custom media types
- **registry**: Push to OCI registries (token auth, basic auth, anonymous)
- **AuthConfig**: GHCR token auto-detection, auth file parsing
## Dependency Flow
```
forger
├── spec-parser
├── forge-engine
│ └── spec-parser
├── forge-builder
│ ├── spec-parser
│ └── vm-manager (external)
└── forge-oci
```
All crates are async (tokio) and use miette for error diagnostics.
## Key External Dependencies
| Category | Crate | Purpose |
|---|---|---|
| KDL parsing | `knuffel` 3.2 | Spec deserialization |
| CLI | `clap` 4.5 | Argument parsing |
| Async | `tokio` 1 | Runtime, process, fs |
| OCI | `oci-spec`, `oci-client` | Image spec, registry client |
| SSH | `ssh2` | Remote builder communication |
| Errors | `miette`, `thiserror` | Rich diagnostics |
| VM | `vm-manager` (path dep) | Hypervisor abstraction |

71
book/src/architecture/overview.md Normal file
View file

@ -0,0 +1,71 @@
# Design Overview
Refraction Forger is designed around three principles: **declarative specs**, **two-phase execution**, and **distro abstraction**.
## High-Level Architecture
```
┌─────────────┐
│ KDL Spec │
└──────┬──────┘
│
┌──────▼──────┐
│ spec-parser │ Parse → Resolve → Filter
└──────┬──────┘
│
┌──────▼──────┐
│ forger │ CLI routing
└──────┬──────┘
│
┌────────────┼────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Local Build │ │forge-builder│
└──────┬──────┘ └──────┬──────┘
│ │
│ Ephemeral VM
│ ┌─────────────┐
│ │ SSH + SCP │
│ └──────┬──────┘
│ │
┌──────▼─────────────────────────▼──────┐
│ forge-engine │
│ ┌──────────┐ ┌─────────────────┐ │
│ │ Phase 1 │────▶│ Phase 2 │ │
│ │ Rootfs │ │ QCOW2/OCI/Tar │ │
│ └──────────┘ └────────┬────────┘ │
└────────────────────────────┼──────────┘
│
┌──────▼──────┐
│ forge-oci │ Registry push
└─────────────┘
```
## Key Design Decisions
### Declarative Over Imperative
The old tools used shell scripts to orchestrate builds — ordering mattered, error handling was manual, and reuse required copy-paste. Forger uses a declarative spec where you describe *what* the image should contain, and the engine handles *how*.
### Direct Assembly Over Installation
Packer boots an ISO, types keystrokes into a virtual console, and waits for an installer to finish. Forger calls the package manager directly to assemble a rootfs, skipping the installer entirely. This is faster and more reliable.
### Host Independence
The old `omnios-image-builder` required an illumos host with ZFS and pfexec. Forger can build from any platform by spinning up an ephemeral builder VM. The build environment is part of the spec, not a prerequisite.
### OCI as Distribution Channel
Instead of custom upload scripts for each cloud provider, Forger uses OCI registries as a universal distribution mechanism. VM images, container images, and tar artifacts all flow through the same registry infrastructure.
## Error Handling
Forger uses [miette](https://docs.rs/miette) for rich error diagnostics. When something fails, you get:
- The error message
- Context about what was being attempted
- Suggestions for how to fix it
- Source location where the error originated
This is deliberate — image building involves many external tools and system operations, and clear error messages are essential for debugging.

86
book/src/architecture/pipeline.md Normal file
View file

@ -0,0 +1,86 @@
# Two-Phase Build Pipeline
Every Forger build follows a two-phase architecture. Understanding this split is key to building efficient images and debugging build failures.
## Phase 1: Rootfs Assembly
Phase 1 creates a populated filesystem tree in a staging directory. The work is entirely distro-specific:
### OmniOS Path
1. `pkg image-create` — Initialize an IPS package image
2. `pkg set-publisher` — Configure each publisher (name + origin URL)
3. `pkg change-variant` — Set zone variant (`global` or `nonglobal`)
4. `pkg approve-ca-cert` — Trust CA certificates for signed packages
5. `pkg install` — Install all specified packages
6. Apply customizations (create users)
7. Apply overlays (files, directories, symlinks, shadow passwords, devfsadm)
### Ubuntu Path
1. `debootstrap` — Bootstrap a minimal Debian/Ubuntu rootfs
2. Write `/etc/apt/sources.list` from repository configuration
3. `apt update` — Refresh package lists
4. `apt install` — Install all specified packages
5. Apply customizations and overlays (same as OmniOS)
### Output
Phase 1 produces a staging directory containing a complete rootfs. This directory is consumed by Phase 2.
## Phase 2: Target Production
Phase 2 takes the rootfs from Phase 1 and packages it into the requested output format. This logic is **shared across all distros**.
### QCOW2 Path
```
Create raw disk file (specified size)
→ Attach as loopback device
→ ZFS: create pool → create BE dataset → mount
→ ext4: partition → format → mount
→ Copy rootfs into mounted filesystem
→ Install bootloader (UEFI/GRUB)
→ ZFS: set bootfs → unmount → export pool
→ ext4: unmount
→ Detach loopback
→ qemu-img convert raw → qcow2
```
The ZFS path creates a unique pool name during build (e.g., `forgebuild_12345`) and renames to `rpool` after export. This prevents conflicts with existing pools on the build host.
### OCI Path
```
Compress rootfs → tar.gz layer
→ Compute SHA256 digest
→ Build OCI config JSON (entrypoint, env)
→ Build OCI manifest JSON
→ Write OCI Image Layout directory
```
### Artifact Path
```
Create tar archive from rootfs
```
## Why Two Phases?
The split serves several purposes:
1. **Separation of concerns**: Distro-specific logic (Phase 1) doesn't leak into format-specific logic (Phase 2)
2. **Multiple targets**: One Phase 1 rootfs can produce QCOW2, OCI, and artifact targets without rebuilding
3. **Caching boundary**: The base/child relationship creates a cache point between Phase 1 and Phase 2
4. **Testability**: Each phase can be tested independently
## Error Recovery
If Phase 2 fails (e.g., disk too small, bootloader installation error), Forger cleans up:
- Unmounts filesystems
- Exports ZFS pools
- Detaches loopback devices
- Removes temporary files
Cleanup runs even on failure, preventing resource leaks on the build host.

99
book/src/composability/base.md Normal file
View file

@ -0,0 +1,99 @@
# Base Specs (Build Caching)
The `base` directive establishes a parent-child relationship between specs. This is Forger's primary caching mechanism: **a parent spec produces an artifact, and a child spec consumes it**.
## How It Works
```
omnios-base.kdl (parent)
→ builds artifact (tar archive cached on disk or in registry)
→ omnios-disk.kdl (child, consumes the artifact)
→ builds QCOW2
```
The parent handles the expensive, slow operations (OS installation, base package setup). The child adds customization and produces the final image. When the parent's output is cached, rebuilding the child skips the entire base installation.
## Syntax
In the child spec:
```kdl
base "omnios-base.kdl"
// Child-specific additions
packages {
package "/system/cloud-init"
package "/driver/virtio/vioif"
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
}
```
The parent spec (`omnios-base.kdl`) defines the foundation:
```kdl
metadata name="omnios-base" version="1.0.0" description="Base OmniOS configuration"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
}
```
## What Gets Inherited
When a child references a parent via `base`:
- **Repositories** are merged (deduplicated by name/URL)
- **Packages** from both parent and child are installed
- **Overlays** from the parent execute first, then the child's
- **Customizations** from both are applied
- **Metadata** from the child overrides the parent
- **Targets** from the child are used (parent targets are not inherited)
## Caching Pipeline
The key insight is that `base` creates a **build stage boundary**. The parent's output (typically an artifact/tar) is the cache unit:
1. First build: parent runs Phase 1 (full package installation), produces artifact
2. Subsequent builds: if the parent spec hasn't changed, skip Phase 1 and start from the cached artifact
3. The child only needs to apply its additional packages, overlays, and produce its targets
This mirrors the strap→image→archive pipeline from the old `omnios-image-builder`, but expressed declaratively.
## Multi-Level Inheritance
Base specs can themselves have bases, creating a chain:
```
distro-base.kdl
→ platform-base.kdl
→ application-image.kdl
```
Each level adds or refines what the previous level established. Circular references are detected and rejected.
## Base vs Include
| | Base | Include |
|---|---|---|
| **Relationship** | Parent → child (produces artifact for child to consume) | Sibling (shared steps imported) |
| **Caching** | Yes — parent output is the cache boundary | No — just DRY for config |
| **Merging** | Full merge with child overrides | Steps imported as-is |
| **Targets** | Child's targets used | No target interaction |

87
book/src/composability/includes.md Normal file
View file

@ -0,0 +1,87 @@
# Includes (Shared Steps)
The `include` directive imports shared configuration steps from another spec file into the current spec. Unlike `base`, includes don't create a build-stage boundary — they simply pull in common definitions for reuse.
## Syntax
```kdl
include "common.kdl"
include "devfs.kdl"
```
## What Includes Do
An include file is a regular `.kdl` spec containing overlays, packages, customizations, or other configuration. When included, its contents are merged into the including spec as if they were written inline.
### Example: `common.kdl`
```kdl
overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
file destination="/etc/inet/hosts" source="files/etc/hosts"
file destination="/etc/nodename" source="files/etc/nodename"
file destination="/etc/resolv.conf" source="files/etc/resolv.conf"
ensure-symlink "/etc/nsswitch.conf" target="/etc/nsswitch.dns"
}
```
### Example: `devfs.kdl`
```kdl
overlays {
devfsadm
remove-files "/dev/dsk" "/dev/rdsk" "/dev/cfg" "/dev/usb"
ensure-dir "/dev/cfg" owner="root" group="root" mode="755"
ensure-dir "/dev/dsk" owner="root" group="root" mode="755"
ensure-dir "/dev/rdsk" owner="root" group="root" mode="755"
ensure-dir "/dev/usb" owner="root" group="root" mode="755"
ensure-symlink "/dev/msglog" target="../devices/pseudo/log@0:msglog"
}
```
## Using Includes
A disk image spec can import these shared steps:
```kdl
base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/system/cloud-init"
}
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
shadow username="root" password="$5$..."
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
}
```
## Execution Order
1. Base spec's packages, overlays, and customizations run first
2. Include files run in the order they appear
3. The current spec's content runs last
This gives you control over layering: device filesystem setup (`devfs.kdl`) before network configuration (`common.kdl`) before image-specific overlays.
## When to Use Include vs Base
- **Include**: Shared configuration snippets used across multiple specs (SMF profiles, network setup, device nodes)
- **Base**: A full image foundation that produces a cached artifact consumed by derivative images
Includes are lightweight — they don't trigger a separate build phase or produce intermediate artifacts.

126
book/src/composability/pipelines.md Normal file
View file

@ -0,0 +1,126 @@
# Multi-Stage Pipelines
Forger's composability model enables multi-stage build pipelines where each stage's output feeds as input to the next. This is the key to fast, cacheable image builds.
## The Pipeline Pattern
A typical pipeline for a bootable OmniOS VM image looks like this:
```
Stage 1: Base (expensive, cached)
omnios-base.kdl
→ Initializes IPS
→ Sets publishers
→ Installs core packages
→ Produces: artifact (tar archive)
Stage 2: Image (fast, incremental)
omnios-disk.kdl (base: omnios-base.kdl)
→ Consumes base artifact
→ Adds cloud-init, drivers
→ Applies overlays (config files, device nodes)
→ Produces: QCOW2 image
```
The first build runs both stages. Subsequent builds skip Stage 1 if the base hasn't changed, jumping straight to Stage 2.
## Designing Your Pipeline
### Identify the Cache Boundary
The most expensive operation in image building is package installation — downloading and extracting hundreds of packages from a repository. Put this in the base spec:
```kdl
// omnios-base.kdl — the slow part, cached
metadata name="omnios-base" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
package "/web/curl"
package "/web/wget"
}
```
### Derive Specific Images
Then create derivative specs that add target-specific configuration:
```kdl
// omnios-disk.kdl — fast, builds on cached base
base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages {
package "/system/cloud-init"
package "/driver/virtio/vioif"
package "/driver/virtio/vioblk"
}
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
shadow username="root" password="$5$rounds=10000$..."
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
```
### Multiple Derivatives from One Base
```
omnios-base.kdl
├── omnios-disk.kdl → QCOW2 VM image
├── omnios-rust-ci.kdl → Rust CI image (adds rust, git, build tools)
├── omnios-container.kdl → OCI container
└── omnios-aws.kdl → AWS-specific VM image
```
Each derivative shares the same cached base, so building all four images only runs the expensive Stage 1 once.
## Comparison with Predecessor Tools
### omnios-image-builder (Shell + JSON)
The old `omnios-image-builder` achieved the same pattern with ZFS snapshots:
```
01-strap.json → pkg install entire → ZFS snapshot "strap"
02-image.json → pkg install extras → ZFS snapshot "image"
03-archive.json → pack_tar → omnios-bloody.tar.gz
aws.json → unpack_tar + make_bootable → raw disk
```
Each ZFS snapshot was a cache point. The `-f` flag forced a full rebuild.
Forger replaces this with the `base` directive. No ZFS on the build host required. No manual snapshot management. The caching is implicit in the spec relationship.
### Packer (HCL)
Packer has no native multi-stage caching. Each build starts from an ISO installation, runs provisioner scripts, and captures the result. There's no way to say "skip the OS install and start from here."
Forger's pipeline model is fundamentally more efficient for iterative development.

126
book/src/composability/profiles.md Normal file
View file

@ -0,0 +1,126 @@
# Profiles (Conditional Variants)
Profiles let you create multiple image variants from a single spec. Blocks tagged with `if="profile-name"` are only included when that profile is active.
## Syntax
Tag any `packages`, `overlays`, or `customization` block with an `if` property:
```kdl
// Always included (no condition)
packages {
package "/editor/vim"
package "/network/openssh-server"
}
// Only when --profile build is active
packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
}
// Only when --profile ci is active
customization if="ci" {
user "ci"
}
overlays if="debug" {
file destination="/etc/system" source="files/etc/system.debug"
}
```
## Activating Profiles
Use the `--profile` flag (repeatable) when building or inspecting:
```bash
# No profiles — just the base packages
forger build --spec my-image.kdl
# With build tools
forger build --spec my-image.kdl --profile build
# With build tools AND CI user
forger build --spec my-image.kdl --profile build --profile ci
# Inspect with profiles to see what would be included
forger inspect --spec my-image.kdl --profile build --profile ci
```
## How Filtering Works
Profile filtering happens after spec resolution (base + include merging) but before the build starts:
1. Parse and resolve the full spec (with all blocks)
2. Apply profile filter:
- Blocks with **no `if`** condition → always kept
- Blocks where `if` value **matches** an active profile → kept
- Blocks where `if` value **doesn't match** any active profile → removed
3. Build proceeds with the filtered spec
## Use Cases
### Development vs Production
```kdl
packages {
package "/network/openssh-server"
}
packages if="dev" {
package "/developer/build-essential"
package "/diagnostic/top"
}
overlays if="dev" {
shadow username="root" password="$5$..."
}
```
### CI Variants
```kdl
packages if="rust-ci" {
package "/ooce/developer/rust"
package "/developer/build/gnu-make"
}
packages if="go-ci" {
package "/ooce/developer/go"
}
```
### Cloud Provider Specific
```kdl
overlays if="aws" {
file destination="/boot/conf.d/console" source="files/boot_console.aws"
file destination="/etc/dhcp/dhcpagent" source="files/dhcpagent.aws"
}
overlays if="digitalocean" {
file destination="/boot/conf.d/console" source="files/boot_console.do"
}
```
## Combining with Base and Includes
Profiles work across the full composition chain. Conditional blocks in base specs and includes are filtered together with the current spec's blocks:
```kdl
// omnios-base.kdl
packages if="build" {
package "/developer/build-essential"
}
```
```kdl
// my-image.kdl
base "omnios-base.kdl"
packages if="build" {
package "/ooce/developer/rust"
}
```
Building with `--profile build` activates both blocks from both files.

101
book/src/distros/adding-distro.md Normal file
View file

@ -0,0 +1,101 @@
# Adding a New Distro
Forger's distro support is built around the `DistroFamily` abstraction. Adding a new distribution means extending this abstraction at the spec-parsing and build-engine levels.
## Architecture Overview
The distro system has three touch points:
1. **`spec-parser`**: Maps distro strings to `DistroFamily` enum
2. **`forge-engine` Phase 1**: Distro-specific rootfs assembly logic
3. **`forge-builder`**: Default builder image selection
## Step 1: Extend the DistroFamily Enum
In `crates/spec-parser/src/lib.rs`, add your distro to the enum:
```rust
pub enum DistroFamily {
OmniOS,
Ubuntu,
Fedora, // New
}
```
Update the detection logic that maps the `distro` string to a family:
```rust
fn detect_family(distro: &str) -> DistroFamily {
if distro.starts_with("ubuntu") {
DistroFamily::Ubuntu
} else if distro.starts_with("fedora") {
DistroFamily::Fedora
} else {
DistroFamily::OmniOS
}
}
```
## Step 2: Add Repository Type
If your distro uses a different repository format, add it to the `repositories` parsing in the spec:
```kdl
repositories {
// Existing
publisher name="..." origin="..." // IPS
apt-mirror "..." suite="..." components="..." // APT
// New: DNF/YUM
dnf-repo name="fedora" baseurl="https://..." gpgkey="..."
}
```
## Step 3: Implement Phase 1 Logic
In `crates/forge-engine/src/phase1/mod.rs`, add the rootfs assembly path for your distro. This is the core work — each distro has its own bootstrap process:
- **OmniOS**: `pkg image-create` → set publishers → install
- **Ubuntu**: `debootstrap` → write sources.list → apt install
- **Fedora**: `dnf --installroot` → write repo files → dnf install
The key operations:
1. Initialize a package manager root in the staging directory
2. Configure repositories/mirrors
3. Install the base package set
4. Install user-specified packages
## Step 4: Default Builder Image
In `crates/forge-builder/src/lib.rs`, add a default builder image:
```rust
match distro_family {
DistroFamily::OmniOS => "oci://ghcr.io/cloudnebulaproject/omnios-builder:latest",
DistroFamily::Ubuntu => "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest",
DistroFamily::Fedora => "oci://ghcr.io/cloudnebulaproject/fedora-builder:latest",
}
```
You'll also need to build and publish the builder image itself.
## Step 5: Add Example Specs
Create example specs in the `images/` directory showing common patterns for the new distro.
## Step 6: Document
Add a chapter to this book under **Distro Guide** covering:
- Required and recommended packages
- Repository configuration
- Filesystem and bootloader defaults
- Any distro-specific overlay patterns
## Design Principles
When adding a distro, keep these principles in mind:
- **The `ToolRunner` trait** wraps all external tool execution. Use it for any new package manager commands — this enables testing without root access.
- **Phase 1 is distro-specific, Phase 2 is not**. The QCOW2/OCI/artifact target production is shared across all distros. Only rootfs assembly changes.
- **Filesystem defaults** should match what the distro community expects (ZFS for illumos, ext4 for most Linux).
- **Error messages** should use miette diagnostics to tell the user exactly what's wrong and how to fix it.

84
book/src/distros/illumos-overview.md Normal file
View file

@ -0,0 +1,84 @@
# illumos Overview
Forger's primary focus is the **illumos** ecosystem. This chapter provides essential background for image developers working with illumos distributions.
## What is illumos?
illumos is a Unix operating system kernel derived from OpenSolaris. It powers several distributions including OmniOS, OpenIndiana, and SmartOS. Key technologies that distinguish illumos from Linux:
### ZFS
ZFS is the default and recommended filesystem for illumos. It provides:
- **Copy-on-write**: Snapshots and clones are instant and space-efficient
- **Boot Environments (BEs)**: Multiple bootable system states on the same pool
- **Data integrity**: End-to-end checksumming
- **Built-in compression**: LZ4 by default on modern pools
Forger creates ZFS pools natively for QCOW2 targets on illumos.
### IPS (Image Packaging System)
IPS is illumos's package manager. Key concepts:
- **Publishers**: Named package repositories (e.g., `omnios`, `extra.omnios`)
- **Incorporations**: Meta-packages that constrain version compatibility (e.g., `entire`)
- **Variants**: Facets that select package subsets (e.g., `opensolaris.zone=global`)
- **FMRIs**: Hierarchical package names (e.g., `/network/openssh-server`)
- **Signed packages**: CA-verified package integrity
Forger wraps IPS operations directly — no shell scripting needed.
### SMF (Service Management Facility)
SMF is illumos's service manager (similar to systemd on Linux, but predates it). Services are defined by XML manifests and managed via profiles:
- **Profiles** control which services are enabled at boot
- **generic_limited_net.xml**: Basic networking
- **inetd_generic.xml**: Internet daemon services
- **platform_none.xml**: Platform-specific (none for VM images)
- **ns_dns.xml**: DNS name service
Forger configures SMF profiles through symlink overlays:
```kdl
overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
}
```
### Zones
illumos zones are lightweight OS-level containers (similar to LXC/Docker, but predating both). The `opensolaris.zone` variant controls whether packages include global-zone-only components:
- `global`: Full system including kernel modules, boot components, and hardware drivers
- `nonglobal`: Zone-only packages (no kernel or hardware support)
For VM images, always use `global`:
```kdl
variants {
set name="opensolaris.zone" value="global"
}
```
### Device Filesystem (devfs)
illumos manages device nodes through `devfsadm`, which discovers hardware and creates entries in `/dev`. For image building, this means:
1. Clean up stale device nodes from the build environment
2. Run `devfsadm` to create correct entries for the target hardware
3. Ensure required directories exist (`/dev/dsk`, `/dev/rdsk`, `/dev/cfg`, `/dev/usb`)
Forger handles this through the `devfsadm` overlay and the conventional `devfs.kdl` include.
## illumos Distributions
| Distribution | Focus | Publisher URL |
|---|---|---|
| **OmniOS** | Server/cloud, minimal, stable | `pkg.omnios.org` |
| **OpenIndiana** | Desktop/general-purpose, broader package set | `pkg.openindiana.org` |
| **SmartOS** | Hypervisor/container host (Joyent) | Not IPS-based |
Forger currently supports OmniOS. OpenIndiana support follows the same IPS path.

157
book/src/distros/omnios.md Normal file
View file

@ -0,0 +1,157 @@
# OmniOS
OmniOS is Forger's primary target distribution. It's a server-focused illumos distribution maintained by the OmniOS Community Edition (OmniOSce) project.
## Release Branches
| Branch | URL Path | Use Case |
|---|---|---|
| **bloody** | `/bloody/core/` | Rolling development, latest packages |
| **stable** (e.g., r151050) | `/r151050/core/` | Production, LTS releases |
### Choosing a Branch
- Use **bloody** for CI images, development, and testing the latest software
- Use **stable** for production deployments where predictability matters
## Minimal Spec
```kdl
metadata name="omnios-base" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
}
```
### Required Elements
- **`incorporation "entire"`**: Pins all packages to a consistent version set. Without this, you may get incompatible package versions.
- **`certificates`**: OmniOS packages are signed. The CA certificate file (`omniosce-ca.cert.pem`) must be available relative to the spec.
- **`variants` with `opensolaris.zone=global`**: Required for bootable VM images. Omitting this may exclude kernel modules.
## Common Packages
### Core System
```kdl
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/service/network/ntpsec"
package "/web/curl"
package "/web/wget"
}
```
### Cloud & Virtualization
```kdl
packages {
package "/system/cloud-init"
package "/driver/virtio/vioif" // Virtio network
package "/driver/virtio/vioblk" // Virtio block storage
package "/driver/virtio/vio9p" // 9p filesystem sharing
package "/driver/virtio/vioscsi" // Virtio SCSI
package "/driver/virtio/viorand" // Virtio RNG
}
```
### Development
```kdl
packages if="build" {
package "/developer/build-essential"
package "/ooce/developer/omnios-build-tools"
package "/developer/build/gnu-make"
}
```
### Rust Toolchain
```kdl
packages if="rust" {
package "/ooce/developer/rust"
package "/developer/versioning/git"
}
```
## Boot Configuration
OmniOS VM images need console and boot configuration through overlays:
### Serial Console (115200 baud)
```kdl
overlays {
file destination="/boot/conf.d/console" source="files/boot_console.115200"
file destination="/etc/ttydefs" source="files/ttydefs.115200"
file destination="/etc/default/init" source="files/default_init.utc"
}
```
The boot console file configures which console device is used:
- **`ttya`**: Serial console (standard for cloud VMs)
- **`text`**: Framebuffer (for interactive debugging)
### SMF Profiles
```kdl
overlays {
ensure-symlink "/etc/svc/profile/generic.xml" target="generic_limited_net.xml"
ensure-symlink "/etc/svc/profile/inetd_services.xml" target="inetd_generic.xml"
ensure-symlink "/etc/svc/profile/platform.xml" target="platform_none.xml"
ensure-symlink "/etc/svc/profile/name_service.xml" target="ns_dns.xml"
}
```
## QCOW2 Target Settings
For OmniOS, always use ZFS with UEFI:
```kdl
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
```
- **`ashift=12`**: 4K sector alignment, correct for modern disks and virtual storage
- **UEFI**: Standard boot method for OmniOS
## Complete Example
See `images/omnios-bloody-disk.kdl` in the repository for a full bootable OmniOS image spec, or the [Example Specs](../reference/examples.md) chapter.
## OmniOS Extra Publisher
The `extra.omnios` publisher provides community-maintained packages not in the core repository, including:
- Rust (`/ooce/developer/rust`)
- Go (`/ooce/developer/go`)
- Python versions (`/ooce/runtime/python-*`)
- Node.js (`/ooce/runtime/node-*`)
- Build tools (`/ooce/developer/omnios-build-tools`)
Always add this publisher if you need development tools or language runtimes.

164
book/src/distros/ubuntu.md Normal file
View file

@ -0,0 +1,164 @@
# Ubuntu
Ubuntu is Forger's secondary target, providing Linux support for teams that need both illumos and Linux images from the same tooling.
## How Ubuntu Builds Differ
| Aspect | OmniOS | Ubuntu |
|---|---|---|
| Bootstrap | `pkg image-create` | `debootstrap` |
| Package manager | IPS (`pkg`) | APT (`apt`) |
| Repository config | Publishers | `sources.list` |
| Default filesystem | ZFS | ext4 |
| Bootloader | UEFI (illumos) | `grub-efi-amd64-bin` |
| Init system | SMF | systemd |
## Minimal Spec
```kdl
metadata name="ubuntu-base" version="1.0.0" description="Ubuntu 22.04 base"
distro "ubuntu-22.04"
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
packages {
package "openssh-server"
package "curl"
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
}
```
### Key Differences from OmniOS
- **`distro "ubuntu-22.04"`** is required — without it, Forger assumes OmniOS
- **No incorporation, variants, or certificates** — these are IPS concepts
- **Bootloader is `grub-efi-amd64-bin`** — the Ubuntu GRUB EFI package
- **Filesystem is `ext4`** — ZFS is possible but not the Ubuntu default
## Repositories
Ubuntu uses APT mirrors with suite and component selection:
```kdl
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-updates" components="main universe"
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy-security" components="main universe"
}
```
### Components
- **main**: Officially supported free software
- **universe**: Community-maintained free software
- **restricted**: Proprietary drivers
- **multiverse**: Non-free software
For most server images, `main universe` covers all needed packages.
## Common Packages
### Core System
```kdl
packages {
package "openssh-server"
package "curl"
package "git"
package "cloud-init"
package "linux-image-generic"
}
```
> **Important**: Include `linux-image-generic` for bootable VM images. Without a kernel, the image won't boot.
### Build Tools
```kdl
packages if="build" {
package "build-essential"
package "pkg-config"
package "libssl-dev"
}
```
### Rust Toolchain
```kdl
packages if="rust" {
package "rustc"
package "cargo"
package "build-essential"
package "libssl-dev"
package "pkg-config"
}
```
## Builder VM
Ubuntu builds need an Ubuntu builder VM. Specify it explicitly or let Forger use the default:
```kdl
builder {
image "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest"
vcpus 4
memory 4096
disk 20
}
```
## Complete Example
```kdl
metadata name="ubuntu-rust-ci" version="1.0.0" description="Ubuntu Rust CI image"
distro "ubuntu-22.04"
repositories {
apt-mirror "http://archive.ubuntu.com/ubuntu" suite="jammy" components="main universe"
}
packages {
package "build-essential"
package "rustc"
package "cargo"
package "git"
package "curl"
package "openssh-server"
package "cloud-init"
package "linux-image-generic"
package "grub-efi-amd64-bin"
package "libssl-dev"
package "pkg-config"
}
customization {
user "ci"
}
builder {
image "oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest"
vcpus 4
memory 4096
disk 20
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
push-to "ghcr.io/cloudnebulaproject/ubuntu-rust:latest"
}
```
## Future: IPS on Linux
A long-term goal of the Forger project is to bring IPS to Linux via a Rust implementation. This would allow Linux images to use the same publisher-based, signed-package, incorporation-constrained model that makes illumos packaging robust. When this is available, Ubuntu and other Linux distros will gain IPS as an alternative package manager option within Forger.

53
book/src/formats/artifact.md Normal file
View file

@ -0,0 +1,53 @@
# Tar Artifacts
Artifact targets produce a tar archive of the assembled rootfs. This is the simplest output format and serves as the building block for multi-stage pipelines.
## Syntax
```kdl
target "archive" kind="artifact" {
}
```
## Use Cases
### Build Stage Caching
The primary use of artifacts is as intermediate outputs in a [multi-stage pipeline](../composability/pipelines.md). A parent spec produces an artifact that a child spec consumes:
```kdl
// base.kdl — produces artifact
target "base-archive" kind="artifact" {
}
```
```kdl
// disk.kdl — consumes artifact from base
base "base.kdl"
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
}
```
### External Processing
Artifacts can be consumed by external tools for further processing:
- Import into a zone or container manually
- Feed into another build system
- Archive for distribution
### Rootfs Inspection
Build an artifact to inspect what the rootfs looks like without committing to a disk image:
```bash
forger build --spec my-image.kdl --target archive
tar -tzf output/archive.tar.gz | head -50
```
## Output
The artifact is written to the output directory as a tar archive (typically gzip-compressed). The archive contains the full rootfs tree starting from `/`.

118
book/src/formats/oci.md Normal file
View file

@ -0,0 +1,118 @@
# OCI Container Images
OCI targets produce container images compatible with Docker, Podman, and any OCI-compliant runtime.
## Syntax
```kdl
target "container" kind="oci" {
entrypoint command="/bin/sh"
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
set "TZ" "UTC"
}
}
```
## How OCI Targets Work
Phase 2 for an OCI target:
1. **Compress** the Phase 1 rootfs into a gzip tar layer
2. **Compute** SHA256 digests for all blobs
3. **Build** OCI config JSON (entrypoint, environment, layer diff IDs)
4. **Build** OCI manifest JSON (media types, blob references, sizes)
5. **Write** an OCI Image Layout directory:
```
output/container/
├── oci-layout # {"imageLayoutVersion": "1.0.0"}
├── index.json # Points to manifest
└── blobs/
└── sha256/
├── <manifest> # OCI manifest JSON
├── <config> # OCI config JSON
└── <layer> # Compressed rootfs layer
```
## Configuration
### Entrypoint
The command to run when the container starts:
```kdl
entrypoint command="/usr/sbin/sshd"
```
If omitted, no entrypoint is set and the container runtime's default applies.
### Environment Variables
```kdl
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
set "LANG" "C.UTF-8"
set "TZ" "UTC"
}
```
## Using the Output
### Load into Docker
```bash
# From OCI Image Layout directory
docker load < output/container/
# Or use skopeo
skopeo copy oci:output/container docker-daemon:myimage:latest
```
### Load into Podman
```bash
podman load < output/container/
```
### Push to Registry
Use the `push` command or `push-to` in the target:
```bash
forger push --image output/container/ --reference ghcr.io/myorg/myimage:latest
```
Or configure auto-push in the spec (see [OCI Registry Push](./registry.md)).
## OmniOS Containers
OmniOS in a container is useful for CI builds and lightweight services:
```kdl
metadata name="omnios-container" version="1.0.0"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="nonglobal"
}
packages {
package "/editor/vim"
package "/web/curl"
}
target "container" kind="oci" {
entrypoint command="/bin/bash"
environment {
set "PATH" "/usr/bin:/bin:/usr/sbin:/sbin"
}
}
```
Note: For containers, use `opensolaris.zone=nonglobal` to exclude kernel modules and hardware drivers that aren't needed in a container context.

122
book/src/formats/qcow2.md Normal file
View file

@ -0,0 +1,122 @@
# QCOW2 VM Images
QCOW2 (QEMU Copy-On-Write v2) is the primary output format for bootable virtual machine images.
## How QCOW2 Targets Work
Phase 2 for a QCOW2 target follows this sequence:
1. **Create a raw disk** of the specified size
2. **Attach via loopback device** (or equivalent)
3. **Create filesystem**:
- **ZFS**: Create pool → create boot environment dataset → mount
- **ext4**: Partition disk → format → mount
4. **Populate** from Phase 1 rootfs (copy files into mounted filesystem)
5. **Install bootloader** (UEFI or GRUB)
6. **Finalize**:
- ZFS: Set bootfs property → unmount → export pool
- ext4: Unmount
7. **Detach** loopback device
8. **Convert** raw disk to QCOW2 via `qemu-img convert`
## ZFS-Based Images (illumos)
ZFS is the default and recommended filesystem for OmniOS images:
```kdl
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
```
### ZFS Pool Details
During build, Forger creates a uniquely-named ZFS pool (e.g., `forgebuild_12345`) to avoid conflicts with existing pools on the build host. After export, the pool is named `rpool` in the final image.
### Pool Properties
```kdl
pool {
property name="ashift" value="12"
}
```
- **`ashift=12`**: 4KB sector alignment. Use this for modern storage and virtual disks.
- Additional ZFS pool properties can be set using the same syntax.
### Boot Environments
ZFS images use boot environments (BEs), a core illumos concept. The image contains a single BE that becomes the default boot target. On first boot, the system can create new BEs for upgrades, allowing rollback to previous states.
## ext4-Based Images (Linux)
ext4 is the default filesystem for Ubuntu images:
```kdl
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "grub-efi-amd64-bin"
filesystem "ext4"
}
```
The disk is partitioned with an EFI System Partition and a root partition formatted as ext4.
## Disk Sizing
Specify the disk size as a string with a unit suffix:
```kdl
disk-size "2G" // 2 gigabytes
disk-size "2000M" // 2000 megabytes
disk-size "8G" // 8 gigabytes
```
Choose a size that accommodates your installed packages plus reasonable free space. Typical sizes:
- Minimal OmniOS: 2G
- OmniOS with development tools: 4-8G
- Ubuntu with build tools: 8G
## Bootloader Options
| Value | Platform | Description |
|---|---|---|
| `uefi` | illumos | Native UEFI boot (recommended for OmniOS) |
| `grub` | illumos | Legacy GRUB (BIOS boot) |
| `grub-efi-amd64-bin` | Ubuntu | GRUB EFI for x86_64 Linux |
## Auto-Push
QCOW2 images can be automatically pushed to an OCI registry as artifacts:
```kdl
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
push-to "ghcr.io/myorg/omnios-image:latest"
}
```
The QCOW2 file is wrapped as an OCI artifact with custom media types (`application/vnd.cloudnebula.qcow2.*`) and pushed to the registry. This allows distributing VM images through container registries.
## Deploying QCOW2 Images
QCOW2 images work with:
- **QEMU/KVM**: Direct use (`qemu-system-x86_64 -drive file=image.qcow2,format=qcow2`)
- **libvirt/virt-manager**: Import as existing disk
- **Proxmox**: Upload to storage, create VM from disk
- **Cloud platforms**: Convert to platform-specific format if needed
To convert to raw (for AWS, DigitalOcean, etc.):
```bash
qemu-img convert -f qcow2 -O raw image.qcow2 image.raw
```

116
book/src/formats/registry.md Normal file
View file

@ -0,0 +1,116 @@
# OCI Registry Push
Forger can push built images directly to OCI-compliant registries, including GitHub Container Registry (GHCR), Docker Hub, and self-hosted registries.
## Auto-Push (Target Configuration)
Set `push-to` on a target to automatically push after a successful build:
```kdl
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
push-to "ghcr.io/myorg/omnios-image:latest"
}
target "container" kind="oci" {
push-to "ghcr.io/myorg/omnios-container:latest"
}
```
Skip the push with:
```bash
forger build --spec my-image.kdl --skip-push
```
## Manual Push
Push a previously built image:
```bash
# Push OCI Image Layout
forger push --image output/container/ --reference ghcr.io/myorg/myimage:latest
# Push QCOW2 as OCI artifact
forger push --image output/vm.qcow2 --reference ghcr.io/myorg/myvm:latest --artifact
```
### Options
| Flag | Description |
|---|---|
| `--image <PATH>` | Path to OCI Image Layout directory or QCOW2 file |
| `--reference <REF>` | Registry reference (e.g., `ghcr.io/org/image:tag`) |
| `--artifact` | Push QCOW2 as OCI artifact (custom media types) |
| `--auth-file <PATH>` | JSON auth file for registry authentication |
## Authentication
### GitHub Container Registry (GHCR)
Forger automatically uses the `GITHUB_TOKEN` environment variable when pushing to `ghcr.io`:
```bash
export GITHUB_TOKEN=ghp_...
forger build --spec my-image.kdl
```
In GitHub Actions, the token is available automatically:
```yaml
- name: Build and push
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: forger build --spec images/omnios-rust-ci.kdl
```
### Auth File
For other registries, provide a JSON auth file:
```json
{
"username": "myuser",
"password": "mypassword"
}
```
Or with a token:
```json
{
"token": "my-registry-token"
}
```
```bash
forger push --image output/container/ \
--reference registry.example.com/myimage:latest \
--auth-file auth.json
```
### Anonymous Push
Local registries (localhost, 127.0.0.1) are accessed without authentication over HTTP (insecure mode).
## QCOW2 as OCI Artifact
When pushing QCOW2 images with `--artifact`, Forger uses custom OCI media types:
- Config: `application/vnd.cloudnebula.qcow2.config.v1+json`
- Layer: `application/vnd.cloudnebula.qcow2.layer.v1`
This allows distributing VM disk images through container registries alongside container images, using a unified registry infrastructure.
## Pulling QCOW2 Artifacts
QCOW2 artifacts pushed to a registry can be pulled back as builder images or for deployment:
```kdl
builder {
image "oci://ghcr.io/myorg/omnios-builder:latest"
}
```
Forger resolves `oci://` references by pulling from the registry.

58
book/src/getting-started/build-modes.md Normal file
View file

@ -0,0 +1,58 @@
# Build Modes
Forger supports two build modes: **local** and **remote**. The mode is selected automatically based on your environment, or you can force it with CLI flags.
## Local Build
A local build runs directly on your host machine. This is the fastest option but requires:
- The target distro's package manager to be available
- Root/sudo access for filesystem operations
- Matching architecture (e.g., building OmniOS images on OmniOS)
```bash
forger build --spec my-image.kdl --local
```
Use `--local` to skip builder VM detection and force a local build.
## Remote Build (Builder VM)
When your host doesn't match the target OS — for example, building OmniOS images from a Linux workstation — Forger spins up an ephemeral builder VM:
1. Downloads or uses a cached builder image (OCI reference, URL, or local file)
2. Creates a cloud-init configuration with an ephemeral SSH keypair
3. Starts a QEMU VM with user-mode networking (no root needed on host)
4. Transfers the `forger` binary, spec file, and overlay files via SSH
5. Runs the build inside the VM
6. Downloads the finished artifacts
7. Destroys the VM
```bash
forger build --spec my-image.kdl --use-builder
```
Use `--use-builder` to force a remote build even when local build is possible.
### Default Builder Images
If no builder is specified in the spec or on the CLI, Forger uses sensible defaults:
| Target Distro | Default Builder Image |
|---|---|
| OmniOS | `oci://ghcr.io/cloudnebulaproject/omnios-builder:latest` |
| Ubuntu | `oci://ghcr.io/cloudnebulaproject/ubuntu-builder:latest` |
### Override the Builder Image
From the CLI:
```bash
forger build --spec my-image.kdl --builder-image oci://my-registry/my-builder:v1
```
Or in the spec file (see [Builder Configuration](../spec/builder.md)).
## How Forger Chooses
When neither `--local` nor `--use-builder` is specified, Forger checks whether the current host can satisfy the build requirements (package manager availability, OS match). If it can, it builds locally. Otherwise, it falls back to a builder VM.

94
book/src/getting-started/first-image.md Normal file
View file

@ -0,0 +1,94 @@
# Your First Image
Let's build a minimal OmniOS VM image. Create a file called `my-image.kdl`:
```kdl
metadata name="my-first-image" version="1.0.0" description="A minimal OmniOS image"
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
publisher name="extra.omnios" origin="https://pkg.omnios.org/bloody/extra/"
}
incorporation "entire"
certificates {
ca publisher="omnios" certfile="omniosce-ca.cert.pem"
}
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
}
target "vm" kind="qcow2" {
disk-size "2G"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
```
## Validate First
Before building, validate the spec to catch syntax errors:
```bash
forger validate --spec my-image.kdl
```
## Inspect the Resolved Spec
See what the build will do after resolving includes and applying profiles:
```bash
forger inspect --spec my-image.kdl
```
## List Targets
Check what targets are defined:
```bash
forger targets --spec my-image.kdl
```
Output:
```
vm (qcow2)
```
## Build
```bash
forger build --spec my-image.kdl
```
This will:
1. Detect whether to build locally or spin up a builder VM
2. **Phase 1**: Create a rootfs by initializing IPS, setting publishers, and installing packages
3. **Phase 2**: Create a 2GB raw disk, set up a ZFS pool, populate it from the rootfs, install the UEFI bootloader, and convert to QCOW2
The output lands in `./output/` by default.
## Build a Specific Target
If your spec defines multiple targets, build just one:
```bash
forger build --spec my-image.kdl --target vm
```
## Next Steps
- Add [overlays](../spec/overlays.md) for custom configuration files
- Set up [base specs](../composability/base.md) for caching
- Configure a [builder VM](../spec/builder.md) for cross-platform builds

52
book/src/getting-started/installation.md Normal file
View file

@ -0,0 +1,52 @@
# Installation
## Prerequisites
Forger is written in Rust and builds as a single static binary. You need:
- **Rust toolchain** (1.85 or later) via [rustup](https://rustup.rs/)
- **Git** for fetching the source
For **local builds** (building images directly on your machine), you also need:
- The target OS's package manager available (e.g., `pkg` on OmniOS, `debootstrap` + `apt` on Ubuntu)
- Root/sudo access for filesystem operations
- `qemu-img` for QCOW2 conversion
- ZFS utilities if building ZFS-based images
For **remote builds** (the default when your host doesn't match the target), you only need:
- QEMU installed (for the builder VM)
- No root access required — Forger uses user-mode networking
## Building From Source
```bash
git clone https://github.com/cloudnebulaproject/refraction-forger.git
cd refraction-forger
cargo build --release
```
The binary is at `target/release/forger`.
### Cross-Compilation for illumos
If you're building on Linux for deployment on illumos:
```bash
# Install the cross-compilation tool
cargo install cross
# Build for illumos
cross build --release --target x86_64-unknown-illumos
```
The project includes a `Cross.toml` with the illumos target preconfigured.
## Verify Installation
```bash
forger --help
```
You should see the five subcommands: `build`, `validate`, `inspect`, `push`, and `targets`.

41
book/src/introduction.md Normal file
View file

@ -0,0 +1,41 @@
# Refraction Forger
Refraction Forger is a declarative image building tool that creates optimized OS images from simple specification files. It is designed for infrastructure engineers, DevOps teams, and OS distribution maintainers who need reproducible, cacheable image builds across multiple platforms.
## What It Does
Forger reads a `.kdl` specification file that declares what your image should contain — packages, files, users, boot configuration — and produces ready-to-deploy artifacts:
- **QCOW2 virtual machine images** with ZFS or ext4 filesystems
- **OCI container images** for container runtimes
- **Tar archives** for further processing or embedding
Built artifacts can be pushed directly to OCI registries like GHCR.
## Why Forger?
Traditional image building tools fall into two camps:
1. **Shell script orchestrators** (like the illumos `image-builder`) that require a matching host OS, root privileges, and careful manual sequencing.
2. **ISO boot automators** (like HashiCorp Packer) that spin up a full installer, type keystrokes into a virtual console, and wait — slowly.
Forger takes a different approach. It assembles images *directly* by calling package managers and filesystem tools, skipping the installer entirely. Builds that took 20+ minutes with Packer complete in a fraction of the time.
When your host doesn't match the target OS, Forger automatically spins up an ephemeral builder VM, transfers the spec, builds inside it, and retrieves the artifacts — no manual VM management needed.
## Primary Focus
Forger's primary focus is **illumos** distributions, particularly **OmniOS**. The illumos ecosystem uses IPS (Image Packaging System) and ZFS, both of which Forger understands natively.
Linux support (starting with **Ubuntu**) is included as a secondary target. The long-term goal is to bring IPS to Linux via a Rust implementation, making Forger's packaging model available across operating systems. In the meantime, popular Linux distributions are supported to provide a broad userbase familiar with tools like Packer.
## How This Book Is Organized
- **Getting Started** walks you through installation and building your first image.
- **The KDL Spec Language** is a complete guide to writing image specifications.
- **Composability** explains how to chain builds, share configuration, and create variants.
- **Distro Guide** covers distribution-specific details for illumos and Linux.
- **Output Formats** describes each artifact type and how to deploy them.
- **Architecture** explains the internal design for contributors and advanced users.
- **Migration** helps you move from `omnios-image-builder` or Packer.
- **Reference** provides CLI help, spec schema, and complete examples.

159
book/src/migration/from-image-builder.md Normal file
View file

@ -0,0 +1,159 @@
# From omnios-image-builder
This guide helps you migrate from the shell-based `omnios-image-builder` to Forger.
## Architecture Comparison
| omnios-image-builder | Forger |
|---|---|
| Shell scripts (`strap.sh`, `aws.sh`, etc.) | Single `forger` binary |
| JSON templates with step arrays | KDL specs with declarative blocks |
| ZFS snapshots for caching | `base` directive for caching |
| Requires illumos host with ZFS + pfexec | Any host (remote builder VM) |
| Manual pipeline (01-strap → 02-image → 03-archive → final) | Implicit pipeline via `base`/`include` |
## Mapping Concepts
### JSON Steps → KDL Blocks
The old JSON templates used a `steps` array with typed objects:
```json
{
"steps": [
{ "t": "pkg_image_create", "publisher": "omnios", "uri": "https://..." },
{ "t": "pkg_install", "pkgs": ["entire"] },
{ "t": "pkg_change_variant", "variant": "opensolaris.zone", "value": "global" }
]
}
```
In Forger, these become declarative blocks:
```kdl
repositories {
publisher name="omnios" origin="https://pkg.omnios.org/bloody/core/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
}
```
### Step Type Mapping
| JSON Step | KDL Equivalent |
|---|---|
| `pkg_image_create` | `repositories { publisher ... }` (implicit) |
| `pkg_set_publisher` | `repositories { publisher ... }` |
| `pkg_install` | `packages { package "..." }` |
| `pkg_change_variant` | `variants { set ... }` |
| `pkg_approve_ca_cert` | `certificates { ca ... }` |
| `pkg_uninstall` | Not needed (don't install unwanted packages) |
| `pkg_purge_history` | Handled automatically |
| `pkg_set_property` | Handled automatically |
| `ensure_file` | `overlays { file ... }` |
| `ensure_dir` | `overlays { ensure-dir ... }` |
| `ensure_symlink` | `overlays { ensure-symlink ... }` |
| `remove_files` | `overlays { remove-files ... }` |
| `shadow` | `overlays { shadow ... }` |
| `devfsadm` | `overlays { devfsadm }` |
| `seed_smf` | Handled automatically |
| `include` | `include "file.kdl"` |
| `create_be` | Handled automatically (QCOW2 target) |
| `unpack_tar` | Handled automatically (`base` directive) |
| `make_bootable` | `target ... { bootloader "uefi" }` |
| `pack_tar` | `target "..." kind="artifact"` |
### Three-Stage Pipeline → Base + Child
**Old approach** (three JSON files + shell orchestration):
```
01-strap.json → pkg install entire → snapshot "strap"
02-image.json → pkg install extras → snapshot "image"
03-archive.json → pack_tar → omnios-bloody.tar.gz
aws.json → unpack_tar + make_bootable → raw disk
```
**New approach** (two KDL files):
```kdl
// omnios-base.kdl
repositories { publisher name="omnios" ... }
incorporation "entire"
packages { package "/editor/vim" ... }
```
```kdl
// omnios-disk.kdl
base "omnios-base.kdl"
include "devfs.kdl"
include "common.kdl"
packages { package "/system/cloud-init" }
overlays { file destination="/boot/conf.d/console" ... }
target "vm" kind="qcow2" { ... }
```
The `base` directive replaces the ZFS snapshot pipeline. The parent's output is cached, and the child builds on top.
### Pool Configuration
**Old** (`pool` in JSON):
```json
{
"pool": { "name": "rpool", "ashift": 12, "uefi": true, "size": 2000 }
}
```
**New** (in target block):
```kdl
target "vm" kind="qcow2" {
disk-size "2000M"
bootloader "uefi"
filesystem "zfs"
pool {
property name="ashift" value="12"
}
}
```
### Output Formats
**Old**: Raw disk images only (convert to QCOW2/AMI externally)
**New**: QCOW2 natively, plus OCI container images and tar artifacts
### Cloud Provider Scripts
The old `aws.sh`, `digitalocean.sh`, and `smartosbhyve.sh` scripts are replaced by profiles or separate specs:
```kdl
// Cloud-provider-specific overlays via profiles
overlays if="aws" {
file destination="/boot/conf.d/console" source="files/boot_console.aws"
}
overlays if="digitalocean" {
file destination="/boot/conf.d/console" source="files/boot_console.do"
}
```
## Migration Checklist
1. Identify your JSON templates and their step sequences
2. Map each step to the equivalent KDL block (see table above)
3. Split the three-stage pipeline into base + child specs
4. Move overlay files to a `files/` directory relative to the specs
5. Replace `setup.sh` dependency management with `forger` binary installation
6. Test with `forger validate` and `forger inspect` before building

195
book/src/migration/from-packer.md Normal file
View file

@ -0,0 +1,195 @@
# From Packer (oi-packer)
This guide helps you migrate from HashiCorp Packer-based illumos image building to Forger.
## Why Migrate?
| Packer | Forger |
|---|---|
| Boots ISO, types keystrokes, waits | Direct package manager assembly |
| 20+ minute builds | Minutes |
| No native caching | Multi-stage caching via `base` |
| Shell provisioners (order-sensitive) | Declarative KDL spec |
| Vagrant boxes, raw disks | QCOW2, OCI, tar artifacts |
| External upload scripts | Built-in OCI registry push |
## Mapping Concepts
### Packer Source → Not Needed
Packer sources define the VM that runs the installer:
```hcl
source "qemu" "oi-hipster" {
iso_url = "https://dlc.openindiana.org/isos/..."
iso_checksum = "sha256:..."
disk_size = "51200M"
memory = 4096
accelerator = "kvm"
}
```
Forger doesn't boot an ISO. It calls the package manager directly, so there's no installer VM to configure.
### Boot Command → Not Needed
Packer's boot command types keystrokes into the installer:
```hcl
boot_command = [
"<wait10><wait10><wait10>",
"47<enter><wait>", // Select installation
"7<enter><wait>", // Select bootloader
// ... dozens more keystrokes
]
```
Forger skips the installer entirely. Package installation happens through direct `pkg` or `apt` calls.
### Shell Provisioners → KDL Blocks
**Packer** (shell scripts that SSH into the VM):
```hcl
provisioner "shell" {
scripts = [
"scripts/update.sh", // pkg update
"scripts/vagrant.sh", // Create vagrant user, install SSH keys
"scripts/cleanup.sh", // Remove SSH host keys, clear logs
]
}
```
**Forger** (declarative):
```kdl
packages {
package "/editor/vim"
package "/network/openssh-server"
}
customization {
user "deploy"
}
overlays {
file destination="/home/deploy/.ssh/authorized_keys" source="files/authorized_keys"
shadow username="deploy" password="$5$..."
}
```
### Post-Processors → Targets
**Packer** (Vagrant box post-processor):
```hcl
post-processor "vagrant" {
compression_level = 9
output = "OI-hipster-{{.Provider}}.box"
}
```
**Forger** (target block):
```kdl
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
push-to "ghcr.io/myorg/my-image:latest"
}
```
Forger doesn't produce Vagrant boxes directly. Instead, it produces QCOW2 images that work with QEMU/KVM, Proxmox, and other hypervisors. OCI container images are also available.
### Variables → Profiles
**Packer** (HCL variables):
```hcl
variable "build_version" { default = "20240426" }
```
**Forger** (profiles for variants):
```kdl
packages if="dev" {
package "/diagnostic/top"
}
```
## Full Migration Example
### Packer Template (before)
```hcl
source "qemu" "oi-hipster" {
iso_url = "https://dlc.openindiana.org/isos/hipster/20240426/OI-hipster-text-20240426.iso"
disk_size = "51200M"
memory = 4096
format = "qcow2"
boot_command = ["<wait30>", "47<enter>", /* ... 30 more lines ... */]
}
build {
sources = ["source.qemu.oi-hipster"]
provisioner "shell" { scripts = ["scripts/update.sh"] }
provisioner "shell" { scripts = ["scripts/vagrant.sh"] }
provisioner "shell" { scripts = ["scripts/cleanup.sh"] }
post-processor "vagrant" {
output = "OI-hipster-{{.Provider}}.box"
}
}
```
### Forger Spec (after)
```kdl
metadata name="oi-hipster" version="1.0.0" description="OpenIndiana Hipster image"
repositories {
publisher name="openindiana.org" origin="http://pkg.openindiana.org/hipster/"
}
incorporation "entire"
variants {
set name="opensolaris.zone" value="global"
}
packages {
package "/editor/vim"
package "/network/openssh-server"
package "/network/rsync"
package "/driver/network/vioif"
package "/driver/storage/vioblk"
}
customization {
user "deploy"
}
overlays {
file destination="/home/deploy/.ssh/authorized_keys" source="files/authorized_keys"
}
target "vm" kind="qcow2" {
disk-size "8G"
bootloader "uefi"
filesystem "zfs"
push-to "ghcr.io/myorg/oi-hipster:latest"
}
```
Build time drops from 20+ minutes (ISO boot + install + provisioning) to a few minutes (direct package installation).
## Migration Checklist
1. Identify packages installed by your shell provisioners
2. List files copied or modified by provisioners
3. Translate to KDL `packages`, `overlays`, and `customization` blocks
4. Replace ISO-based installation with `repositories` + `incorporation`
5. Replace Vagrant post-processor with QCOW2 target + OCI push
6. Test with `forger validate` and `forger inspect`
7. Build and verify the image boots correctly

Some files were not shown because too many files have changed in this diff Show more