d/copyright: reflect that now all is licensed under LGPL-2.1+

[lxcfs.git] / debian / patches / pve / 0002-README-clarify-SWAP.patch

From 22ba5818484aa5ffaa26967d5d2ab228b2789205 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber@ubuntu.com>
Date: Wed, 4 Nov 2020 23:06:00 -0500
Subject: [PATCH lxcfs 2/8] README: clarify SWAP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Stéphane Graber <stgraber@ubuntu.com>
---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/README.md b/README.md
index 5272a6c..3c638c3 100644
--- a/README.md
+++ b/README.md
@@ -104,3 +104,50 @@ docker run -it -m 256m --memory-swap 256m \
  In a system with swap enabled, the parameter "-u" can be used to set all values in "meminfo" that refer to the swap to 0.
 
  sudo lxcfs -u /var/lib/lxcfs
+
+## Swap handling
+If you noticed LXCFS not showing any SWAP in your container despite
+having SWAP on your system, please read this section carefully and look
+for instructions on how to enable SWAP accounting for your distribution.
+
+Swap cgroup handling on Linux is very confusing and there just isn't a
+perfect way for LXCFS to handle it.
+
+Terminology used below:
+ - RAM refers to `memory.usage_in_bytes` and `memory.limit_in_bytes`
+ - RAM+SWAP refers to `memory.memsw.usage_in_bytes` and `memory.memsw.limit_in_bytes`
+
+The main issues are:
+ - SWAP accounting is often opt-in and, requiring a special kernel boot
+   time option (`swapaccount=1`) and/or special kernel build options
+   (`CONFIG_MEMCG_SWAP`).
+
+ - Both a RAM limit and a RAM+SWAP limit can be set. The delta however
+   isn't the available SWAP space as the kernel is still free to SWAP as
+   much of the RAM as it feels like. This makes it impossible to render
+   a SWAP device size as using the delta between RAM and RAM+SWAP for that
+   wouldn't account for the kernel swapping more pages, leading to swap
+   usage exceeding swap total.
+
+ - It's impossible to disable SWAP in a given container. The closest
+   that can be done is setting swappiness down to 0 which severly limits
+   the risk of swapping pages but doesn't eliminate it.
+
+As a result, LXCFS had to make some compromise which go as follow:
+ - When SWAP accounting isn't enabled, no SWAP space is reported at all.
+   This is simply because there is no way to know the SWAP consumption.
+   The container may very much be using some SWAP though, there's just
+   no way to know how much of it and showing a SWAP device would require
+   some kind of SWAP usage to be reported. Showing the host value would be
+   completely wrong, showing a 0 value would be equallty wrong.
+
+ - Because SWAP usage for a given container can exceed the delta between
+   RAM and RAM+SWAP, the SWAP size is always reported to be the smaller of
+   the RAM+SWAP limit or the host SWAP device itself. This ensures that at no
+   point SWAP usage will be allowed to exceed the SWAP size.
+
+ - If the swappiness is set to 0 and there is no SWAP usage, no SWAP is reported.
+   However if there is SWAP usage, then a SWAP device of the size of the
+   usage (100% full) is reported. This provides adequate reporting of
+   the memory consumption while preventing applications from assuming more
+   SWAP is available.
-- 
2.20.1