mirror of
https://github.com/containers/youki
synced 2025-04-21 00:38:02 +02:00
270 lines
16 KiB
HTML
270 lines
16 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>libcontainer - Youki User and Developer Documentation</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 to javascript -->
|
|
<script>
|
|
var path_to_root = "../";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
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>
|
|
var sidebar = null;
|
|
var 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 = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</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="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Youki User and Developer Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
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="libcontainer"><a class="header" href="#libcontainer">libcontainer</a></h1>
|
|
<p>This crate is one of the core crates of the youki workspace, and has functions and structs that deal with the actual craetion and management of the container processes.</p>
|
|
<p>Remember, in the end, a container is just another process in Linux, which has control groups, namespaces, pivot_root and other mechanisms applied to it. The program executing has the impression that is is running on a complete system, but from the host system's perspective, it is just another process, and has attributes such as pid, file descriptors, etc. associated with it like any other process.</p>
|
|
<p>Along with the container related functions, this crate also provides Youki Config, a subset of the OCI spec config. This config contains only the essential data required for running the containers, and due to its smaller size, parsing it and passing it around is more efficient than the complete OCI spec config struct.</p>
|
|
<p>Other than that, this crate also provides a wrapper over basic Linux sockets, which are then used internally as well as by youki to communicate between the main youki process and the forked container process as well as the intermediate process.</p>
|
|
<p>This crate also provides an interface for Apparmor which is another Linux Kernel module allowing to apply security profiles on a per-program basis. More information about it can be found at <a href="https://apparmor.net/">https://apparmor.net/</a>.</p>
|
|
<h3 id="notes"><a class="header" href="#notes">Notes</a></h3>
|
|
<h4 id="some-other-modules-expose-by-this-crate-are"><a class="header" href="#some-other-modules-expose-by-this-crate-are">Some other modules expose by this crate are</a></h4>
|
|
<ul>
|
|
<li>rootfs, which is a ramfs like simple filesystem used by kernel during initialization</li>
|
|
<li>hooks, which allow running of specified program at certain points in the container lifecycle, such as before and after creation, start etc.</li>
|
|
<li>signals, which provide a wrapper to convert to and from signal numbers and text representation of signal names</li>
|
|
<li>capabilities, which has functions related to set and reset specific capabilities, as well as to drop extra privileges
|
|
<ul>
|
|
<li><a href="https://blog.container-solutions.com/linux-capabilities-in-practice">Simple explanation of capabilities</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/capabilities.7.html">man page for capabilities</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>tty module which daels with providing terminal interface to the container process
|
|
<ul>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/pty.7.html">pseudoterminal man page</a> : Information about the pseudoterminal system, useful to understand console_socket parameter in create subcommand</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h4 id="executor"><a class="header" href="#executor">Executor</a></h4>
|
|
<p>By default and traditionally, the executor forks and execs into the binary
|
|
command that specified in the oci spec. Using executors, we can override this
|
|
behavior. For example, <code>youki</code> uses executor to implement running wasm
|
|
workloads. Instead of running the command specified in the process section of
|
|
the OCI spec, the wasm related executors can choose to execute wasm code
|
|
instead. The executor will run at the end of the container init process.</p>
|
|
<p>The API accepts only a single executor, so when using multiple executors, (try
|
|
wasm first, then defaults to running a binary), the users should compose
|
|
multiple executors into a single executor. The executor will return an error
|
|
when the executor can't handle the workload.</p>
|
|
<h4 id="namespaces--namespaces-provide-isolation-of-resources-such-as-filesystem-process-ids-networks-etc-on-kernel-level-this-module-contains-structs-and-functions-related-to-applying-or-un-applying-namespaces-to-the-calling-process"><a class="header" href="#namespaces--namespaces-provide-isolation-of-resources-such-as-filesystem-process-ids-networks-etc-on-kernel-level-this-module-contains-structs-and-functions-related-to-applying-or-un-applying-namespaces-to-the-calling-process">Namespaces : namespaces provide isolation of resources such as filesystem, process ids networks etc on kernel level. This module contains structs and functions related to applying or un-applying namespaces to the calling process</a></h4>
|
|
<ul>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/pid_namespaces.7.html">pid namespace man page</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man2/clone.2.html">CLONE_NEWUSER flag</a></li>
|
|
</ul>
|
|
<blockquote>
|
|
<p>Note: clone(2) offers us the ability to enter into user and pid namespace by creating only one process. However, clone(2) can only create new pid namespace, but cannot enter into existing pid namespaces. Therefore, to enter into existing pid namespaces, we would need to fork twice. Currently, there is no getting around this limitation.</p>
|
|
</blockquote>
|
|
<ul>
|
|
<li><a href="https://man7.org/linux/man-pages/man2/fork.2.html">fork(2) man page</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man2/clone.2.html">clone(2) man page</a></li>
|
|
</ul>
|
|
<h4 id="pausing-and-resuming"><a class="header" href="#pausing-and-resuming">Pausing and resuming</a></h4>
|
|
<p>Pausing a container indicates suspending all processes in it. This can be done with signals SIGSTOP and SIGCONT, but these can be intercepted. Using cgroups to suspend and resume processes without letting tasks know.</p>
|
|
<ul>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/cgroups.7.html">cgroups man page</a></li>
|
|
<li><a href="https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt">freezer cgroup kernel documentation</a></li>
|
|
</ul>
|
|
<h4 id="the-following-are-some-resources-that-can-help-understand-with-various-linux-features-used-in-the-code-of-this-crate"><a class="header" href="#the-following-are-some-resources-that-can-help-understand-with-various-linux-features-used-in-the-code-of-this-crate">The following are some resources that can help understand with various Linux features used in the code of this crate</a></h4>
|
|
<ul>
|
|
<li><a href="https://dev.to/rrampage/surviving-the-linux-oom-killer-2ki9">oom-score-adj</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man1/unshare.1.html">unshare man page</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/user_namespaces.7.html">user-namespace man page</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man3/wait.3p.html">wait man page</a></li>
|
|
<li><a href="https://man7.org/linux/man-pages/man2/pipe.2.html">pipe2 man page</a> : Definition and usage of pipe2</li>
|
|
<li><a href="https://man7.org/linux/man-pages/man7/unix.7.html">Unix Sockets man page</a> : Useful to understand sockets</li>
|
|
<li><a href="https://man7.org/linux/man-pages/man2/prctl.2.html">prctl man page</a> : Process control man pages</li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../developer/libcgroups.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="../developer/liboci_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="../developer/libcgroups.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="../developer/liboci_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>
|