Skip to content

Commit ad0e137

Browse files
author
docs-bot
committed
docs: update from source@b842178
1 parent 9f5cb6d commit ad0e137

7 files changed

Lines changed: 35 additions & 23 deletions

File tree

‎docs/features.html‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -442,7 +442,8 @@ <h3 id="why-it-matters">Why it matters <a class="header-anchor" href="#why-it-ma
442442
</ul>
443443
<p>Without cgroup isolation systemd cannot work: containers would collide in the cgroup hierarchy and service management would fail.</p>
444444
<h3 id="the-jail-trick">The &quot;jail&quot; trick <a class="header-anchor" href="#the-jail-trick">#</a></h3>
445-
<p>Before creating the cgroup namespace, Droidspaces moves the monitor process into the container's own cgroup. When <code>unshare(CLONE_NEWCGROUP)</code> is then called, the root of the new namespace maps to the container's subtree.</p>
445+
<p>A cgroup namespace is rooted wherever the process sits when it is created. So for every boot, the short-lived process that forks the container's init first joins the container's own cgroup and only then calls <code>unshare(CLONE_NEWCGROUP)</code>, and the root of the new namespace maps to the container's subtree.</p>
446+
<p>The supervising monitor never enters that cgroup. The cgroup is created fresh for each boot, including a restart and a reboot from inside the container, and removed when the container stops, so limits always match the current configuration.</p>
446447
<h3 id="cgroup-v1-and-v2-support">Cgroup v1 and v2 support <a class="header-anchor" href="#cgroup-v1-and-v2-support">#</a></h3>
447448
<p>Droidspaces supports both cgroup versions:</p>
448449
<ul>
@@ -483,6 +484,7 @@ <h3 id="resource-limits">Resource limits <a class="header-anchor" href="#resourc
483484
</tbody>
484485
</table></div>
485486
<p>If an option is missing, the limit is skipped at start with a warning that names it. See <a href="kernel-configuration.html">Kernel Configuration</a> to add them.</p>
487+
<p><code>--pids-limit</code> has a floor of 16. The limit counts every task in the container's cgroup, including the two the runtime keeps there and the three each <code>enter</code> or <code>run</code> session starts with. A systemd distribution needs far more, typically a few hundred.</p>
486488
<p><code>--memory</code> limits RAM only. A container that goes over it is pushed into swap (zram on Android) before anything is killed.</p>
487489
<h4 id="where-a-limit-is-applied">Where a limit is applied <a class="header-anchor" href="#where-a-limit-is-applied">#</a></h4>
488490
<p>For each limit Droidspaces looks for the controller in the container's cgroup v2 directory first. If it is not there, it finds the v1 hierarchy that owns the controller, wherever the host mounted it, and puts the container in <code>droidspaces/&lt;name&gt;</code> inside it. On a typical Android phone that means memory at <code>/dev/memcg/droidspaces/&lt;name&gt;</code>, while the container's own view, the one systemd manages, stays cgroup v2. <code>enter</code> and <code>run</code> sessions join the same cgroups, so they are held to the same limits.</p>
@@ -496,6 +498,7 @@ <h4 id="reading-limits-and-usage">Reading limits and usage <a class="header-anch
496498
<p>The same block, without the usage figures, is printed after <code>start</code> and <code>restart</code>.</p>
497499
<p><code>info --format</code> adds <code>memory_limit</code> (bytes), <code>cpu_quota</code>, <code>cpu_period</code> (microseconds) and <code>pids_limit</code>. <code>show --format</code> and <code>info --format</code> add <code>ram_limit_kb</code> and <code>cpu_limit_permill</code> per container, on the same scale as <code>ram_used_kb</code> and <code>cpu_permill</code>. All are 0 when unlimited.</p>
498500
<p>Memory use means one thing everywhere for a container with a memory cgroup: what the cgroup is charged, minus its file cache, which the kernel reclaims on its own. <code>info</code>, <code>show --format</code> and <code>free</code> or fastfetch inside the container all report that figure. The limit itself still counts the cache, so a container can be pushed to reclaim before &quot;used&quot; reaches the limit.</p>
501+
<p>One gap: a program that asks the kernel through the <code>sysinfo()</code> system call, and not through <code>/proc</code>, still sees the host's memory, load and uptime. OpenWRT's LuCI is the common case. The limit is enforced regardless, see <a href="troubleshooting.html#sysinfo-host-values">Troubleshooting</a>.</p>
499502
<h4 id="in-the-android-app">In the Android app <a class="header-anchor" href="#in-the-android-app">#</a></h4>
500503
<p>The container settings have a <strong>Resource Limits</strong> section with a switch per limit. Memory and CPU open a slider bounded by the device's real RAM and core count, the process limit a number field. A limit the kernel cannot enforce is greyed out with the missing option named. The limits also show on the container's card and in the installation summary, and the Panel tab shows usage against the limit, for example <code>94/512 MB (18%)</code>.</p>
501504
<h3 id="the-su-fix">The <code>su</code> fix <a class="header-anchor" href="#the-su-fix">#</a></h3>

‎docs/linux-cli.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -389,7 +389,7 @@ <h3 id="resource-limits">Resource limits <a class="header-anchor" href="#resourc
389389
</tr>
390390
<tr>
391391
<td><code>--pids-limit=N</code></td>
392-
<td>Most processes and threads at once.</td>
392+
<td>Most processes and threads at once. Minimum 16.</td>
393393
</tr>
394394
</tbody>
395395
</table></div>

‎docs/search.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎docs/troubleshooting.html‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
<link rel="apple-touch-icon" href="/favicon.ico">
2424
<link rel="stylesheet" href="/assets/css/site.css?v=b310d7c992">
2525
<link rel="stylesheet" href="/assets/css/main.css?v=ccd72260b9">
26-
<script type="application/ld+json">[{"@context": "https://schema.org", "@type": "TechArticle", "headline": "Troubleshooting", "description": "Fixes for common Droidspaces container problems: systemd hangs, paranoid networking, SELinux corruption, OverlayFS on f2fs, sparse image reclaim, Wi-Fi power save.", "url": "https://www.droidspaces.org/docs/troubleshooting.html", "inLanguage": "en", "dateModified": "2026-09-28", "author": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "publisher": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "isPartOf": {"@type": "WebSite", "name": "Droidspaces", "url": "https://www.droidspaces.org/"}}, {"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.droidspaces.org/"}, {"@type": "ListItem", "position": 2, "name": "Documentation", "item": "https://www.droidspaces.org/docs/"}, {"@type": "ListItem", "position": 3, "name": "Troubleshooting", "item": "https://www.droidspaces.org/docs/troubleshooting.html"}]}]</script>
26+
<script type="application/ld+json">[{"@context": "https://schema.org", "@type": "TechArticle", "headline": "Troubleshooting", "description": "Fixes for common Droidspaces container problems: systemd hangs, paranoid networking, SELinux corruption, OverlayFS on f2fs, sparse image reclaim, Wi-Fi power save.", "url": "https://www.droidspaces.org/docs/troubleshooting.html", "inLanguage": "en", "dateModified": "2026-10-04", "author": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "publisher": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "isPartOf": {"@type": "WebSite", "name": "Droidspaces", "url": "https://www.droidspaces.org/"}}, {"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.droidspaces.org/"}, {"@type": "ListItem", "position": 2, "name": "Documentation", "item": "https://www.droidspaces.org/docs/"}, {"@type": "ListItem", "position": 3, "name": "Troubleshooting", "item": "https://www.droidspaces.org/docs/troubleshooting.html"}]}]</script>
2727
<script>(function(){const t=localStorage.getItem('theme');if(t)document.documentElement.setAttribute('data-theme',t);})();</script>
2828
</head>
2929
<body>
@@ -93,6 +93,7 @@ <h3 id="quick-navigation">Quick navigation <a class="header-anchor" href="#quick
9393
<li><a href="#selinux-induced-rootfs-corruption-directory-mode">SELinux-induced rootfs corruption</a></li>
9494
<li><a href="#reclaim-storage">Reclaiming storage (sparse image)</a></li>
9595
<li><a href="#nuke-wifi-powersave">Wi-Fi <code>Power save: on</code> makes networking sluggish on Android</a></li>
96+
<li><a href="#sysinfo-host-values">LuCI, or another tool, shows the host's RAM and load despite a limit</a></li>
9697
<li><a href="#getting-help">Getting help</a></li>
9798
</ul>
9899
<hr />
@@ -341,6 +342,14 @@ <h3 id="3-wire-up-the-init-service">3. Wire up the init service <a class="header
341342
</code></pre></div>
342343
<div class="callout callout-note"><strong class="callout-title">Note</strong><p>This workaround <strong>requires host networking mode</strong> (<code>--net=host</code>). The script needs direct access to Android's <code>wlan0</code> interface, which is not visible in <code>NAT</code> or <code>None</code> modes. We recommend a small &quot;burner&quot; container used only for this watchdog.</p></div>
343344
<hr />
345+
<p><a id="sysinfo-host-values"></a></p>
346+
<h2 id="luci-or-another-tool-shows-the-hosts-ram-and-load-despite-a-limit">LuCI, or another tool, shows the host's RAM and load despite a limit <a class="header-anchor" href="#luci-or-another-tool-shows-the-hosts-ram-and-load-despite-a-limit">#</a></h2>
347+
<p><strong>Symptom:</strong> a container has a memory or CPU limit, and <code>free</code>, <code>nproc</code> and fastfetch inside it show the limited values, but OpenWRT's LuCI overview still shows the device's full RAM and its real load average.</p>
348+
<p><strong>Cause:</strong> there are two ways for a program to ask how much memory the machine has. Most read <code>/proc/meminfo</code>, which Droidspaces replaces with the container's own figures. Some call the kernel's <code>sysinfo()</code> system call instead, and a system call cannot be replaced by a file. OpenWRT's <code>procd</code> is one of them: <code>ubus call system info</code> takes total, free, shared and buffered memory, swap, load and uptime from <code>sysinfo()</code>, and LuCI displays what <code>procd</code> reports. Some Java runtimes and a few Alpine tools do the same.</p>
349+
<p><strong>What still holds:</strong> the limit is enforced either way. The container cannot use more than it was given. Only the number these tools display is wrong.</p>
350+
<p><strong>Checking a limit yourself:</strong> run <code>droidspaces -n &lt;name&gt; info</code> on the host, or <code>cat /proc/meminfo</code> inside the container.</p>
351+
<p>There is no fix for this at the moment. Intercepting <code>sysinfo()</code> needs seccomp user notifications, which only exist on kernel 5.0 and later.</p>
352+
<hr />
344353
<h2 id="getting-help">Getting help <a class="header-anchor" href="#getting-help">#</a></h2>
345354
<p>If your problem is not listed here:</p>
346355
<ol>
@@ -356,7 +365,7 @@ <h2 id="getting-help">Getting help <a class="header-anchor" href="#getting-help"
356365
<nav class="doc-nav" aria-label="Pages"><a href="cool-things-you-can-do.html" class="doc-nav-prev"><small>Previous</small>Cool things you can do</a><a href="community-supported-devices.html" class="doc-nav-next"><small>Next</small>Community-supported devices</a></nav>
357366
</main>
358367
<aside class="toc-column">
359-
<nav class="toc" aria-label="On this page"><p class="toc-title">On this page</p><ul><li class="toc-h3"><a href="#quick-navigation">Quick navigation</a></li><li class="toc-h2"><a href="#modern-distros-arch-fedora-etc-failure-on-legacy-kernels">Modern distros (Arch, Fedora, etc.) failure on legacy kernels</a></li><li class="toc-h2"><a href="#required-key-not-available">&quot;Required key not available&quot;</a></li><li class="toc-h2"><a href="#mount-errors-on-kernel-414">Mount errors on kernel 4.14</a></li><li class="toc-h2"><a href="#overlayfs-not-supported-f2fs">OverlayFS not supported (f2fs)</a></li><li class="toc-h2"><a href="#container-name-conflicts">Container name conflicts</a></li><li class="toc-h2"><a href="#systemd-hangs-on-older-kernels">systemd hangs on older kernels</a></li><li class="toc-h2"><a href="#container-wont-stop">Container won&#x27;t stop</a></li><li class="toc-h2"><a href="#rootfs-image-io-errors-on-android">Rootfs image I/O errors on Android</a></li><li class="toc-h2"><a href="#networking-is-completely-dead---ping-fails-with-socket-permission-denied">Networking is completely dead - ping fails with &quot;socket: permission denied&quot;</a></li><li class="toc-h2"><a href="#dns--name-resolution-issues">DNS / name resolution issues</a></li><li class="toc-h2"><a href="#wifimobile-data-disconnects">WiFi/mobile data disconnects</a></li><li class="toc-h2"><a href="#selinux-induced-rootfs-corruption-directory-mode">SELinux-induced rootfs corruption (directory mode)</a></li><li class="toc-h2"><a href="#reclaiming-storage-sparse-image">Reclaiming storage (sparse image)</a></li><li class="toc-h2"><a href="#wi-fi-power-save-on-causing-sluggish-networking-on-android">Wi-Fi Power save: on causing sluggish networking on Android</a></li><li class="toc-h3"><a href="#1-install-required-utilities">1. Install required utilities</a></li><li class="toc-h3"><a href="#2-create-the-watchdog-script">2. Create the watchdog script</a></li><li class="toc-h3"><a href="#3-wire-up-the-init-service">3. Wire up the init service</a></li><li class="toc-h2"><a href="#getting-help">Getting help</a></li></ul></nav>
368+
<nav class="toc" aria-label="On this page"><p class="toc-title">On this page</p><ul><li class="toc-h3"><a href="#quick-navigation">Quick navigation</a></li><li class="toc-h2"><a href="#modern-distros-arch-fedora-etc-failure-on-legacy-kernels">Modern distros (Arch, Fedora, etc.) failure on legacy kernels</a></li><li class="toc-h2"><a href="#required-key-not-available">&quot;Required key not available&quot;</a></li><li class="toc-h2"><a href="#mount-errors-on-kernel-414">Mount errors on kernel 4.14</a></li><li class="toc-h2"><a href="#overlayfs-not-supported-f2fs">OverlayFS not supported (f2fs)</a></li><li class="toc-h2"><a href="#container-name-conflicts">Container name conflicts</a></li><li class="toc-h2"><a href="#systemd-hangs-on-older-kernels">systemd hangs on older kernels</a></li><li class="toc-h2"><a href="#container-wont-stop">Container won&#x27;t stop</a></li><li class="toc-h2"><a href="#rootfs-image-io-errors-on-android">Rootfs image I/O errors on Android</a></li><li class="toc-h2"><a href="#networking-is-completely-dead---ping-fails-with-socket-permission-denied">Networking is completely dead - ping fails with &quot;socket: permission denied&quot;</a></li><li class="toc-h2"><a href="#dns--name-resolution-issues">DNS / name resolution issues</a></li><li class="toc-h2"><a href="#wifimobile-data-disconnects">WiFi/mobile data disconnects</a></li><li class="toc-h2"><a href="#selinux-induced-rootfs-corruption-directory-mode">SELinux-induced rootfs corruption (directory mode)</a></li><li class="toc-h2"><a href="#reclaiming-storage-sparse-image">Reclaiming storage (sparse image)</a></li><li class="toc-h2"><a href="#wi-fi-power-save-on-causing-sluggish-networking-on-android">Wi-Fi Power save: on causing sluggish networking on Android</a></li><li class="toc-h3"><a href="#1-install-required-utilities">1. Install required utilities</a></li><li class="toc-h3"><a href="#2-create-the-watchdog-script">2. Create the watchdog script</a></li><li class="toc-h3"><a href="#3-wire-up-the-init-service">3. Wire up the init service</a></li><li class="toc-h2"><a href="#luci-or-another-tool-shows-the-hosts-ram-and-load-despite-a-limit">LuCI, or another tool, shows the host&#x27;s RAM and load despite a limit</a></li><li class="toc-h2"><a href="#getting-help">Getting help</a></li></ul></nav>
360369
</aside>
361370
<footer class="footer">
362371
<div class="footer-inner">

‎docs/usage-android-app.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ <h3 id="port-forwarding">Port forwarding <a class="header-anchor" href="#port-fo
142142
<p>In NAT mode, the <strong>Port Forwarding</strong> section maps host ports to container ports (for example <code>22:22</code>). It also takes <strong>port ranges</strong> (for example <code>1000-2000:1000-2000</code>) for services that need several contiguous ports.</p>
143143
<hr />
144144
<h2 id="resource-limits">Resource limits <a class="header-anchor" href="#resource-limits">#</a></h2>
145-
<p>The container settings have a <strong>Resource Limits</strong> section, above <strong>Advanced Options</strong>:</p>
145+
<p>The container settings have a <strong>Resource Limits</strong> section, after <strong>Integration &amp; Hardware</strong>:</p>
146146
<ul>
147147
<li><strong>Limit memory</strong>: a slider from 128 MB up to the device's total RAM.</li>
148148
<li><strong>Limit CPU</strong>: a slider from half a core up to the device's core count.</li>

‎index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ <h1>A homelab that keeps running when the power cuts.</h1>
127127
<a href="/downloads.html" class="button button-filled"><span class="icon" aria-hidden="true">download</span>Download</a>
128128
<a href="/docs/" class="button button-outlined"><span class="icon" aria-hidden="true">menu_book</span>Documentation</a>
129129
</div>
130-
<p class="body-md">Release <span data-version>v6.6.0</span>, GPLv3. <span data-stars>2,266</span> stars and <span data-contributors>89</span> contributors <a href="https://github.com/ravindu644/Droidspaces-OSS" rel="noopener noreferrer">on GitHub</a>.</p>
130+
<p class="body-md">Release <span data-version>v6.6.0</span>, GPLv3. <span data-stars>2,270</span> stars and <span data-contributors>89</span> contributors <a href="https://github.com/ravindu644/Droidspaces-OSS" rel="noopener noreferrer">on GitHub</a>.</p>
131131
</div>
132132
<div class="stage">
133133
<div class="shape arrive" style="--shape: url(/assets/shapes/cookie-12.svg)"></div>

0 commit comments

Comments
 (0)