[pve-devel] [PATCH pve-docs] fix #3884: Add section for kernel samepage merging

[Dylan Whyte]

Adds a section to the "Host System Administration" section of the
Administration Guide, discussing KSM and its security risks

Signed-off-by: Dylan Whyte <d.whyte at proxmox.com>
---
 kernel-samepage-merging.adoc | 54 ++++++++++++++++++++++++++++++++++++
 sysadmin.adoc                |  2 ++
 2 files changed, 56 insertions(+)
 create mode 100644 kernel-samepage-merging.adoc

diff --git a/kernel-samepage-merging.adoc b/kernel-samepage-merging.adoc
new file mode 100644
index 0000000..5f55403
--- /dev/null
+++ b/kernel-samepage-merging.adoc
@@ -0,0 +1,54 @@
+[[kernel_samepage_merging]]
+Kernel Samepage Merging (KSM)
+-----------------------------
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Kernel Samepage Merging (KSM) is an optional memory deduplication feature
+offered by the Linux kernel, which is enabled by default in {pve}. KSM
+works by scanning a range of physical memory pages for identical content, and
+identifying the virtual pages that are mapped to them. If identical pages are
+found, the corresponding virtual pages are re-mapped so that they all point to
+the same physical page, and the old pages are freed. The virtual pages are
+marked as "copy-on-write", so that any writes to them will be written to a new
+area of memory, leaving the shared physical page intact.
+
+Implications of KSM
+~~~~~~~~~~~~~~~~~~~
+
+KSM can optimize memory usage in virtualization environments, as multiple VMs
+running similar operating systems or workloads could potentially share a lot of
+common memory pages.
+
+However, while KSM can reduce memory usage, it also comes with some security
+risks, as it can expose VMs to side-channel attacks. Research has shown that it
+is possible to infer information about a running VM via a second VM on the same
+host, by exploiting certain characteristics of KSM.
+
+Thus, if you are using {pve} to provide hosting services, you should consider
+disabling KSM, in order to provide your users with additional security.
+Furthermore, you should check your country's regulations, as disabling KSM may
+be a legal requirement.
+
+Disabling KSM
+~~~~~~~~~~~~~
+
+To see if KSM is active, you can check the output of:
+
+----
+# systemctl status ksmtuned
+----
+
+If it is, it can be disabled immediately with:
+
+----
+# systemctl disable --now ksmtuned
+----
+
+Finally, to unmerge all the currently merged pages, run:
+
+----
+# echo 2 > /sys/kernel/mm/ksm/run
+----
+
diff --git a/sysadmin.adoc b/sysadmin.adoc
index 361fe02..cc75671 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -70,6 +70,8 @@ include::certificate-management.adoc[]
 
 include::system-booting.adoc[]
 
+include::kernel-samepage-merging.adoc[]
+
 endif::wiki[]
 
 
-- 
2.30.2