Also mention "vsyscall=emulate" in package description and README.Debian

Closes: #1028388

NEWS.markdown

@@ -18,6 +18,11 @@ Distribution Releases Changes
   + Bump default Ubuntu fallback release to 22.04 Jammy LTS.
   + Add support for Ubuntu Ports APT repos (i.e. Xen on ARM64).
 
+Documentation
+-------------
+
+* Place hints on "vsyscall=emulate" on more visible places.
+
 Other Changes
 -------------
 

README.markdown

@@ -89,8 +89,9 @@ known to work reliably, i.e.:
 <dt><a id="1" name="1">¹</a></dt><dd>
 
 Installation with `xen-create-image` and updating with
-`xen-update-image` might fail with newer kernels/distributions as Dom0
-without `vsyscall=emulate` on the kernel commandline.
+`xen-update-image` might fail with newer kernels/distributions running
+on the Dom0 unless they have been booted with `vsyscall=emulate` on
+the kernel commandline.
 
 </dd><dt><a id="2" name="2">²</a></dt><dd>
 

debian/README.Debian

@@ -1,8 +1,23 @@
 README
 ======
 
+Bootstrapping Wheezy, Precise or older Releases
+-----------------------------------------------
+
+For security reasons (avoid risk to circumvent ASLR), recent kernels
+have disabled the vsyscall mapping. Unfortunately older distributions
+don't run and hence can't be bootstrapped without it.
+
+To enable trapping and enabling emulate calls into the fixed vsyscall
+address mapping and hence to run and bootstrap older Linux
+distributions in a chroot (as xen-tools does), you need to add
+"vsyscall=emulate" to the kernel commandline, e.g. by adding it to
+GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, then running
+"update-grub" afterwards and finally reboot.
+
+
 Kernel/initrd guessing
-======================
+----------------------
 
 In xen-tools 3.4-1 a new feature was added which allows using 
 backtick expressions in xen-tools.conf.
@@ -15,7 +30,7 @@ changing/adding the following options in xen-tools.conf:
 
 
 Upgrading Existing kernel/initrd paths
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kernel, and initrd, settings which are included in the xen-tools
 (either statically or dynamically with `uname -r`) are only applied

debian/changelog

@@ -11,6 +11,8 @@ xen-tools (4.9.2-1) UNRELEASED; urgency=medium
   * Update upstream signing key to update its expiry date.
   * Depend and Build-Depend on non-(build-)essential package
     mount. (Closes: #1027383)
+  * Also mention "vsyscall=emulate" in package description and
+    README.Debian. (Closes: #1028388)
 
  -- Axel Beckert <abe@debian.org>  Mon, 09 Jan 2023 04:42:57 +0100
 

debian/control

@@ -114,3 +114,9 @@ Description: Tools to manage Xen virtual servers
    * Ubuntu 23.04 Lunar Lobster (preliminary support, under development)
    * CentOS 5
    * CentOS 6
+ .
+ Note: Debian 7 Wheezy, Ubuntu 12.04 Precise Pangolin and any older
+ release requires the Linux kernel of the hosting machine to be booted
+ with "vsyscall=emulate" on the kernel commandline (i.e. in the
+ bootloader) to bootstrap these releases with xen-tools. See
+ /usr/share/doc/xen-tools/README.Debian for details.