[PATCH 00/15] Patches from others

[PATCH 00/15] Patches from others

[Alejandro Colomar]

Hi Michael,

Here's a patch set with some important fixes, additions, and clarifications.

Cheers,

Alex


Alejandro Colomar (7):
  memfd_secret.2: Minor tweaks to Mike's patch
  ioctl_tty.2: Minor tweaks to Pali's patch
  process_madvise.2: Minor tweaks to Zhangkui's patch
  process_madvise.2: ffix
  clone.2: ERRORS: Add EACCESS with CLONE_INTO_CGROUP + clone3
  veth.4: tfix
  termios.3: srcfix

Greg Banks (1):
  nscd.conf.5: describe reloading, clarifications

Jakub Wilk (1):
  futex.2: tfix

Mike Rapoport (1):
  memfd_secret.2: add NOTES section ...

Pali Rohár (3):
  termios.3: CIBAUD and IBSHIFT are implemented on Linux, just
    unsupported by glibc
  ioctl_tty.2: Add example how to get or set baudrate on the serial port
  ioctl_tty.2: Fix information about header include file

zhangkui (1):
  process_madvise.2: Add MADV_WILLNEED to process_madvise()

Štěpán Němec (1):
  veth.4: tfix

 man2/clone.2           |  10 ++++
 man2/futex.2           |   2 +-
 man2/ioctl_tty.2       | 119 +++++++++++++++++++++++++++++++++++-
 man2/memfd_secret.2    |  59 ++++++++++++++++++
 man2/process_madvise.2 |  12 ++--
 man3/termios.3         | 133 +++++++++++++++++++++++++----------------
 man4/veth.4            |   2 +-
 man5/nscd.conf.5       | 115 ++++++++++++++++++++++++++++++++++-
 8 files changed, 390 insertions(+), 62 deletions(-)

-- 
2.33.0

[PATCH 01/15] termios.3: CIBAUD and IBSHIFT are implemented on Linux, just unsupported by glibc

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/man3/termios.3 b/man3/termios.3
index c11937458..d0630fe23 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -348,7 +348,12 @@ bits.
 .B _BSD_SOURCE
 or
 .BR _SVID_SOURCE ]
-(Not implemented on Linux.)
+(Not implemented in glibc, supported on Linux via
+.BR TCGET *
+and
+.BR TCSET *
+ioctls; see
+.BR ioctl_tty (2))
 .TP
 .B CMSPAR
 (not in POSIX)
-- 
2.33.0

[PATCH 02/15] memfd_secret.2: add NOTES section ...

[Alejandro Colomar]

From: Mike Rapoport <rppt@linux.ibm.com>

... that explains the rationale for the system call

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/memfd_secret.2 | 61 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
index f3380818e..869480b48 100644
--- a/man2/memfd_secret.2
+++ b/man2/memfd_secret.2
@@ -147,6 +147,67 @@ system call first appeared in Linux 5.14.
 The
 .BR memfd_secret ()
 system call is Linux-specific.
+.SH NOTES
+.PP
+The
+.BR memfd_secret ()
+system call is designed to allow a user-space process
+to create a range of memory that is inaccessible to anybody else -
+kernel included.
+There is no 100% guarantee that kernel won't be able to access
+memory ranges backed by
+.BR memfd_secret ()
+in any circumstances, but nevertheless,
+it is much harder to exfiltrate data from these regions.
+.PP
+The
+.BR memfd_secret ()
+provides the following protections:
+.IP \(bu 3
+Enhanced protection
+(in conjunction with all the other in-kernel attack prevention systems)
+against ROP attacks.
+Absence of any in-kernel primitive for accessing memory backed by
+.BR memfd_secret ()
+means that one-gadget ROP attack
+can't work to perform data exfiltration.
+The attacker would need to find enough ROP gadgets
+to reconstruct the missing page table entries,
+which significantly increases difficulty of the attack,
+especially when other protections like the kernel stack size limit
+and address space layout randomization are in place.
+.IP \(bu
+Prevent cross-process userspace memory exposures.
+Once a region for a
+.BR memfd_secret ()
+memory mapping is allocated,
+the user can't accidentally pass it into the kernel
+to be transmitted somewhere.
+The memory pages in this region cannot be accessed via the direct map
+and they are disallowed in get_user_pages.
+.IP \(bu
+Harden against exploited kernel flaws.
+In order to access memory areas backed by
+.BR memfd_secret(),
+a kernel-side attack would need to
+either walk the page tables and create new ones,
+or spawn a new privileged userspace process to perform
+secrets exfiltration using
+.BR ptrace (2).
+.PP
+The way
+.BR memfd_secret ()
+allocates and locks the memory may impact overall system performance,
+therefore the system call is disabled by default and only available
+if the system administrator turned it on using
+"secretmem.enable=y" kernel parameter.
+.PP
+To prevent potiential data leaks of memory regions backed by
+.BR memfd_secret()
+from a hybernation image,
+hybernation is prevented when there are active
+.BR memfd_secret ()
+users.
 .SH SEE ALSO
 .BR fcntl (2),
 .BR ftruncate (2),
-- 
2.33.0

[PATCH 03/15] memfd_secret.2: Minor tweaks to Mike's patch

[Alejandro Colomar]

Cc: Mike Rapoport <rppt@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/memfd_secret.2 | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
index 869480b48..1b4e82954 100644
--- a/man2/memfd_secret.2
+++ b/man2/memfd_secret.2
@@ -148,7 +148,6 @@ The
 .BR memfd_secret ()
 system call is Linux-specific.
 .SH NOTES
-.PP
 The
 .BR memfd_secret ()
 system call is designed to allow a user-space process
@@ -160,7 +159,6 @@ memory ranges backed by
 in any circumstances, but nevertheless,
 it is much harder to exfiltrate data from these regions.
 .PP
-The
 .BR memfd_secret ()
 provides the following protections:
 .IP \(bu 3
@@ -177,7 +175,7 @@ which significantly increases difficulty of the attack,
 especially when other protections like the kernel stack size limit
 and address space layout randomization are in place.
 .IP \(bu
-Prevent cross-process userspace memory exposures.
+Prevent cross-process user-space memory exposures.
 Once a region for a
 .BR memfd_secret ()
 memory mapping is allocated,
@@ -191,7 +189,7 @@ In order to access memory areas backed by
 .BR memfd_secret(),
 a kernel-side attack would need to
 either walk the page tables and create new ones,
-or spawn a new privileged userspace process to perform
+or spawn a new privileged user-space process to perform
 secrets exfiltration using
 .BR ptrace (2).
 .PP
-- 
2.33.0

[PATCH 04/15] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Setting custom baudrate for which is not defined Bnnn constant is possible
via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.

These two fields are either in struct termios or struct termios2. Former
belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.

BOTHER flag with these two fields and new struct termios2 is not supported
by older versions of include header files.

Some architectures (e.g. amd64) provide both struct termios and struct
termios2, but c_ospeed and c_ispeed are only in struct termios2.

Some other architectures (e.g. alpha) provide both struct termios and struct
termios2 and both have c_ospeed and c_ispeed fields.

And some other architectures (e.g. powerpc) provide only struct termios
(no struct termios2) and it has c_ospeed and c_ispeed fields.

So basically to support all architectures it is needed to use
struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).

Setting input baudrate is done via IBSHIFT macro.

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_tty.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 186011ee7..fd1f3dc25 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -755,6 +755,106 @@ main(void)
     close(fd);
 }
 .EE
+.PP
+Get or set arbitrary baudrate on the serial port.
+.PP
+.EX
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+#include <asm/termbits.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+#ifndef BOTHER
+    fprintf(stderr, "BOTHER is unsupported\en");
+    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
+    exit(EXIT_FAILURE);
+#else
+    /* Declare tio structure, its type depends on supported ioctl */
+#ifdef TCGETS2
+    struct termios2 tio;
+#else
+    struct termios tio;
+#endif
+    int fd, rc;
+
+    if (argc != 2 && argc != 3 && argc != 4) {
+        fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
+    if (fd < 0) {
+        perror("open");
+        exit(EXIT_FAILURE);
+    }
+
+    /* Get the current serial port settings via supported ioctl */
+#ifdef TCGETS2
+    rc = ioctl(fd, TCGETS2, &tio);
+#else
+    rc = ioctl(fd, TCGETS, &tio);
+#endif
+    if (rc) {
+        perror("TCGETS");
+        close(fd);
+        exit(EXIT_FAILURE);
+    }
+
+    /* Change baud rate when more arguments were provided */
+    if (argc == 3 || argc == 4) {
+        /* Clear the current output baud rate and fill a new value */
+        tio.c_cflag &= ~CBAUD;
+        tio.c_cflag |= BOTHER;
+        tio.c_ospeed = atoi(argv[2]);
+
+        /* Clear the current input baud rate and fill a new value */
+        tio.c_cflag &= ~(CBAUD << IBSHIFT);
+        tio.c_cflag |= BOTHER << IBSHIFT;
+        /* When 4th argument is not provided reuse output baud rate */
+        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
+
+        /* Set new serial port settings via supported ioctl */
+#ifdef TCSETS2
+        rc = ioctl(fd, TCSETS2, &tio);
+#else
+        rc = ioctl(fd, TCSETS, &tio);
+#endif
+        if (rc) {
+            perror("TCSETS");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+
+        /* And get new values which were really configured */
+#ifdef TCGETS2
+        rc = ioctl(fd, TCGETS2, &tio);
+#else
+        rc = ioctl(fd, TCGETS, &tio);
+#endif
+        if (rc) {
+            perror("TCGETS");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+    }
+
+    close(fd);
+
+    printf("output baud rate: %u\en", tio.c_ospeed);
+    printf("input baud rate: %u\en", tio.c_ispeed);
+
+    exit(EXIT_SUCCESS);
+#endif
+}
+.EE
 .SH SEE ALSO
 .BR ldattach (1),
 .BR ioctl (2),
-- 
2.33.0

[PATCH 05/15] ioctl_tty.2: Minor tweaks to Pali's patch

[Alejandro Colomar]

Cc: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_tty.2 | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index fd1f3dc25..d0a10a508 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -772,17 +772,17 @@ Get or set arbitrary baudrate on the serial port.
 int
 main(int argc, char *argv[])
 {
-#ifndef BOTHER
+#if !defined BOTHER
     fprintf(stderr, "BOTHER is unsupported\en");
     /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
     exit(EXIT_FAILURE);
 #else
     /* Declare tio structure, its type depends on supported ioctl */
-#ifdef TCGETS2
+# if defined TCGETS2
     struct termios2 tio;
-#else
+# else
     struct termios tio;
-#endif
+# endif
     int fd, rc;
 
     if (argc != 2 && argc != 3 && argc != 4) {
@@ -797,11 +797,11 @@ main(int argc, char *argv[])
     }
 
     /* Get the current serial port settings via supported ioctl */
-#ifdef TCGETS2
+# if defined TCGETS2
     rc = ioctl(fd, TCGETS2, &tio);
-#else
+# else
     rc = ioctl(fd, TCGETS, &tio);
-#endif
+# endif
     if (rc) {
         perror("TCGETS");
         close(fd);
@@ -822,11 +822,11 @@ main(int argc, char *argv[])
         tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
 
         /* Set new serial port settings via supported ioctl */
-#ifdef TCSETS2
+# if defined TCSETS2
         rc = ioctl(fd, TCSETS2, &tio);
-#else
+# else
         rc = ioctl(fd, TCSETS, &tio);
-#endif
+# endif
         if (rc) {
             perror("TCSETS");
             close(fd);
@@ -834,11 +834,11 @@ main(int argc, char *argv[])
         }
 
         /* And get new values which were really configured */
-#ifdef TCGETS2
+# if defined TCGETS2
         rc = ioctl(fd, TCGETS2, &tio);
-#else
+# else
         rc = ioctl(fd, TCGETS, &tio);
-#endif
+# endif
         if (rc) {
             perror("TCGETS");
             close(fd);
-- 
2.33.0

[PATCH 06/15] process_madvise.2: Add MADV_WILLNEED to process_madvise()

[Alejandro Colomar]

From: zhangkui <zhangkui@oppo.com>

Add MADV_WILLNEED to process_madvise() for read-ahead swapped
out memory immediately when the app switches to forground.

https://lore.kernel.org/patchwork/patch/1472006/

Signed-off-by: zhangkui <zhangkui@oppo.com>
Reviewed-by: Suren Baghdasaryan <surenb@google.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/process_madvise.2 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man2/process_madvise.2 b/man2/process_madvise.2
index a6c8724d4..caa8bc0b3 100644
--- a/man2/process_madvise.2
+++ b/man2/process_madvise.2
@@ -112,6 +112,10 @@ See
 .BR MADV_PAGEOUT
 See
 .BR madvise (2).
+.TP
+.BR MADV_WILLNEED
+See
+.BR madvise (2).
 .PP
 The
 .I flags
-- 
2.33.0

[PATCH 07/15] process_madvise.2: Minor tweaks to Zhangkui's patch

[Alejandro Colomar]

I also fixed surrounding cases to avoid confusion.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/process_madvise.2 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man2/process_madvise.2 b/man2/process_madvise.2
index caa8bc0b3..6a5c6ebb9 100644
--- a/man2/process_madvise.2
+++ b/man2/process_madvise.2
@@ -105,15 +105,15 @@ The
 .I advice
 argument is one of the following values:
 .TP
-.BR MADV_COLD
+.B MADV_COLD
 See
 .BR madvise (2).
 .TP
-.BR MADV_PAGEOUT
+.B MADV_PAGEOUT
 See
 .BR madvise (2).
 .TP
-.BR MADV_WILLNEED
+.B MADV_WILLNEED
 See
 .BR madvise (2).
 .PP
-- 
2.33.0

[PATCH 08/15] process_madvise.2: ffix

[Alejandro Colomar]

And srcfix too

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/process_madvise.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man2/process_madvise.2 b/man2/process_madvise.2
index 6a5c6ebb9..47a56b235 100644
--- a/man2/process_madvise.2
+++ b/man2/process_madvise.2
@@ -49,7 +49,7 @@ necessitating the use of
 .\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
 .SH DESCRIPTION
 The
-.BR process_madvise()
+.BR process_madvise ()
 system call is used to give advice or directions to the kernel about the
 address ranges of another process or of the calling process.
 It provides the advice for the address ranges described by
@@ -95,7 +95,7 @@ specifies the number of elements in the
 .I iovec
 structure.
 This value must be less than or equal to
-.BR IOV_MAX
+.B IOV_MAX
 (defined in
 .I <limits.h>
 or accessible via the call
-- 
2.33.0

[PATCH 09/15] clone.2: ERRORS: Add EACCESS with CLONE_INTO_CGROUP + clone3

[Alejandro Colomar]

[Andrew]:
I noticed that clone3 can send the EACCES errno after I wrote a
program that used clone3 with the CLONE_INTO_CGROUP flag.
To me, it's important to know what kind of failure occurred if the
clone3() fails, so I was glad that a unique errno is set for
this case, but it wasn't documented on the clone man page.

[Christian]:
In essence, any error that could occur during regular fs-based migration
at write-time can also occur during CLONE_INTO_CGROUP. The clone3()
manpage just has the inverse of that above statement:

"Note that all of the usual restrictions (described in cgroups(7)) on
placing a process into a version 2 cgroup apply."

Reported-by: Andrew Wock <ajwock@gmail.com>
Acked-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/clone.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man2/clone.2 b/man2/clone.2
index e381da165..90db92ad6 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -1209,6 +1209,16 @@ in the caller's context, no child process is created, and
 is set to indicate the error.
 .SH ERRORS
 .TP
+.BR EACCES " (" clone3 "() only)"
+.B CLONE_INTO_CGROUP
+was specified in
+.IR cl_args.flags ,
+but the restrictions (described in
+.BR cgroups (7))
+on placing the child process into the version 2 cgroup referred to by
+.I cl_args.cgroup
+are not met.
+.TP
 .B EAGAIN
 Too many processes are already running; see
 .BR fork (2).
-- 
2.33.0

[PATCH 10/15] ioctl_tty.2: Fix information about header include file

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Header file termios.h contains incompatible definitions for linux ioctl
calls. Correct definitions are exported by header file linux/termios.h but
this file conflicts with sys/ioctl.h header file (required for ioctl()
call). Therefore include direct asm header file asm/termbits.h which
contains compatible definitions and structures for ioctl calls.

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_tty.2 | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index d0a10a508..68b48a00b 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
 .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,6 +33,19 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.I <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.IR <termios.h> .
+These ioctl calls require
+.B struct termios
+from
+.IR <asm/termbits.h> .
 .SS Get and set terminal attributes
 .TP
 .B TCGETS
-- 
2.33.0

[PATCH 11/15] veth.4: tfix

[Alejandro Colomar]

From: Štěpán Němec <stepnem@gmail.com>

Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man4/veth.4 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man4/veth.4 b/man4/veth.4
index b2d5a2fc7..bd2acdcc4 100644
--- a/man4/veth.4
+++ b/man4/veth.4
@@ -54,7 +54,7 @@ are the names assigned to the two connected end points.
 .PP
 Packets transmitted on one device in the pair are immediately received on
 the other device.
-When either devices is down the link state of the pair is down.
+When either device is down the link state of the pair is down.
 .PP
 .B veth
 device pairs are useful for combining the network
-- 
2.33.0

[PATCH 12/15] veth.4: tfix

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man4/veth.4 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man4/veth.4 b/man4/veth.4
index bd2acdcc4..7b9064720 100644
--- a/man4/veth.4
+++ b/man4/veth.4
@@ -54,7 +54,7 @@ are the names assigned to the two connected end points.
 .PP
 Packets transmitted on one device in the pair are immediately received on
 the other device.
-When either device is down the link state of the pair is down.
+When either device is down, the link state of the pair is down.
 .PP
 .B veth
 device pairs are useful for combining the network
-- 
2.33.0

[PATCH 13/15] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar]

From: Greg Banks <gbanks@linkedin.com>

- Added a subsection of NOTES describing nscd's reloading behavior
  and providing advice on how to configure it.
- Clarifications for the threads, reload-count, positive-time-to-live,
  check-files, and shared attributes.

Derived by reading the nscd, libresolv and glibc source and some
painful experience.

Signed-off-by: Greg Banks <gbanks@linkedin.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man5/nscd.conf.5 | 115 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 112 insertions(+), 3 deletions(-)

diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 7356bf7c2..25ee4901b 100644
--- a/man5/nscd.conf.5
+++ b/man5/nscd.conf.5
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
 .\" Author: Thorsten Kukuk <kukuk@suse.de>
+.\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
 .\" This program is free software; you can redistribute it and/or
@@ -53,9 +54,13 @@ The default is 0.
 .B threads
 .I number
 .RS
-This is the number of threads that are started to wait for
+This is the initial number of threads that are started to wait for
 requests.
 At least five threads will always be created.
+The number of threads may increase dynamically up to
+.B max\-threads
+in response to demand from clients,
+but never decreases.
 .RE
 .PP
 .B max\-threads
@@ -83,9 +88,20 @@ Specifies the user who is allowed to request statistics.
 unlimited |
 .I number
 .RS
-Limit on the number of times a cached entry gets reloaded without being used
+Sets a limit on the number of times a cached entry
+gets reloaded without being used
 before it gets removed.
-The default is 5.
+The limit can take values ranging from 0 to 254;
+values 255 or higher behave the same as
+.BR unlimited .
+Limit values can be specified in either decimal
+or hexadecimal with a "0x" prefix.
+The special value
+.B unlimited
+is case-insensitive.
+The default limit is 5.
+A limit of 0 turns off the reloading feature.
+See NOTES below for further discussion of reloading.
 .RE
 .PP
 .B paranoia
@@ -128,6 +144,9 @@ in the specified cache for
 is in seconds.
 Larger values increase cache hit rates and reduce mean
 response times, but increase problems with cache coherence.
+Note that for some name services (including specifically DNS)
+the TTL returned from the name service is used and
+this attribute is ignored.
 .RE
 .PP
 .B negative\-time\-to\-live
@@ -166,6 +185,7 @@ The files are
 .IR /etc/passwd ,
 .IR /etc/group ,
 .IR /etc/hosts ,
+.IR /etc/resolv.conf ,
 .IR /etc/services ,
 and
 .IR /etc/netgroup .
@@ -194,6 +214,8 @@ is shared with the clients so
 that they can directly search in them instead of having to ask the
 daemon over the socket each time a lookup is performed.
 The default is no.
+Note that a cache miss will still result in
+asking the daemon over the socket.
 .RE
 .PP
 .B max\-db\-size
@@ -236,6 +258,93 @@ from the source code of
 and are used if not overridden in the configuration file.
 The default values used in the configuration file of
 your distribution might differ.
+.SS Reloading
+.BR nscd (8)
+has a feature called reloading,
+whose behavior can be surprising.
+.PP
+Reloading is enabled when the
+.B reload-count
+attribute has a non-zero value.
+The default value in the source code enables reloading,
+although your distribution may differ.
+.PP
+When reloading is enabled,
+positive cached entries (the results of successful queries)
+do not simply expire when their TTL is up.
+Instead, at the expiry time,
+.B nscd
+will "reload",
+i.e.,
+re-issue to the name service the same query that created the cached entry,
+to get a new value to cache.
+Depending on
+.I /etc/nsswitch.conf
+this may mean that a DNS, LDAP, or NIS request is made.
+If the new query is successful,
+reloading will repeat when the new value would expire,
+until
+.B reload-count
+reloads have happened for the entry,
+and only then will it actually be removed from the cache.
+A request from a client which hits the entry will
+reset the reload counter on the entry.
+Purging the cache using
+.I nscd\~-i
+overrides the reload logic and removes the entry.
+.PP
+Reloading has the effect of extending cache entry TTLs
+without compromising on cache coherency,
+at the cost of additional load on the backing name service.
+Whether this is a good idea on your system depends on
+details of your applications' behavior,
+your name service,
+and the effective TTL values of your cache entries.
+Note that for some name services
+(for example, DNS),
+the effective TTL is the value returned from the name service and
+.I not
+the value of the
+.B positive\-time\-to\-live
+attribute.
+.PP
+Please consider the following advice carefully:
+.IP \(bu
+If your application will make a second request for the same name,
+after more than 1 TTL but before
+.B reload\-count
+TTLs,
+and is sensitive to the latency of a cache miss,
+then reloading may be a good idea for you.
+.IP \(bu
+If your name service is configured to return very short TTLs,
+and your applications only make requests rarely under normal circumstances,
+then reloading may result in additional load on your backing name service
+without any benefit to applications,
+which is probably a bad idea for you.
+.IP \(bu
+If your name service capacity is limited,
+reloading may have the surprising effect of
+increasing load on your name service instead of reducing it,
+and may be a bad idea for you.
+.IP \(bu
+Setting
+.B reload\-count
+to
+.B unlimited
+is almost never a good idea,
+as it will result in a cache that never expires entries
+and puts never-ending additional load on the backing name service.
+.PP
+Some distributions have an init script for
+.BR nscd (8)
+with a
+.I reload
+command which uses
+.I nscd\~-i
+to purge the cache.
+That use of the word "reload" is entirely different
+from the "reloading" described here.
 .SH SEE ALSO
 .BR nscd (8)
 .\" .SH AUTHOR
-- 
2.33.0

[PATCH 14/15] termios.3: srcfix

[Alejandro Colomar]

Replace a list with .nf,.ft,.fi requests and hardcoded tabs,
by commonly used (some not so common, such as TQ, but simple)
macros: .RS,.RE,.TP,.TQ,.B

Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 126 +++++++++++++++++++++++++++++--------------------
 1 file changed, 76 insertions(+), 50 deletions(-)

diff --git a/man3/termios.3 b/man3/termios.3
index d0630fe23..3a3c551cf 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -929,60 +929,86 @@ pointed to by
 .BR cfsetospeed ()
 sets the output baud rate stored in the \fItermios\fP structure pointed
 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
-.PP
-.nf
-.ft B
-	B0
-	B50
-	B75
-	B110
-	B134
-	B150
-	B200
-	B300
-	B600
-	B1200
-	B1800
-	B2400
-	B4800
-	B9600
-	B19200
-	B38400
-	B57600
-	B115200
-	B230400
-	B460800
-	B500000
-	B576000
-	B921600
-	B1000000
-	B1152000
-	B1500000
-	B2000000
-.ft P
-.fi
+.RS
+.TP
+.B B0
+.TQ
+.B B50
+.TQ
+.B B75
+.TQ
+.B B110
+.TQ
+.B B134
+.TQ
+.B B150
+.TQ
+.B B200
+.TQ
+.B B300
+.TQ
+.B B600
+.TQ
+.B B1200
+.TQ
+.B B1800
+.TQ
+.B B2400
+.TQ
+.B B4800
+.TQ
+.B B9600
+.TQ
+.B B19200
+.TQ
+.B B38400
+.TQ
+.B B57600
+.TQ
+.B B115200
+.TQ
+.B B230400
+.TQ
+.B B460800
+.TQ
+.B B500000
+.TQ
+.B B576000
+.TQ
+.B B921600
+.TQ
+.B B1000000
+.TQ
+.B B1152000
+.TQ
+.B B1500000
+.TQ
+.B B2000000
+.RE
 .PP
 These constants are additionally supported on the SPARC architecture:
-.PP
-.nf
-.ft B
-	B76800
-	B153600
-	B307200
-	B614400
-.ft P
-.fi
+.RS
+.TP
+.B B76800
+.TQ
+.B B153600
+.TQ
+.B B307200
+.TQ
+.B B614400
+.RE
 .PP
 These constants are additionally supported on non-SPARC architectures:
-.PP
-.nf
-.ft B
-	B2500000
-	B3000000
-	B3500000
-	B4000000
-.ft P
-.fi
+.RS
+.TP
+.B B2500000
+.TQ
+.B B3000000
+.TQ
+.B B3500000
+.TQ
+.B B4000000
+.RE
 .PP
 Due to differences between architectures, portable applications should check
 if a particular
-- 
2.33.0

[PATCH 15/15] futex.2: tfix

[Alejandro Colomar]

From: Jakub Wilk <jwilk@jwilk.net>

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/futex.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man2/futex.2 b/man2/futex.2
index 1dd77ac2f..72100300d 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -1137,7 +1137,7 @@ except that the clock against which
 is measured is selectable.
 By default, the (absolute) timeout specified in
 .I timeout
-is measured againt the
+is measured against the
 .B CLOCK_MONOTONIC
 clock, but if the
 .B FUTEX_CLOCK_REALTIME
-- 
2.33.0

Re: [PATCH 09/15] clone.2: ERRORS: Add EACCESS with CLONE_INTO_CGROUP + clone3

[Alejandro Colomar (man-pages)]

Hi Michael,

On 9/11/21 12:47 AM, Alejandro Colomar wrote:
> [Andrew]:
> I noticed that clone3 can send the EACCES errno after I wrote a
> program that used clone3 with the CLONE_INTO_CGROUP flag.
> To me, it's important to know what kind of failure occurred if the
> clone3() fails, so I was glad that a unique errno is set for
> this case, but it wasn't documented on the clone man page.
> 
> [Christian]:
> In essence, any error that could occur during regular fs-based migration
> at write-time can also occur during CLONE_INTO_CGROUP. The clone3()
> manpage just has the inverse of that above statement:
> 
> "Note that all of the usual restrictions (described in cgroups(7)) on
> placing a process into a version 2 cgroup apply."
> 
> Reported-by: Andrew Wock <ajwock@gmail.com>
> Acked-by: Christian Brauner <christian.brauner@ubuntu.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

I forgot to fix the author of the commit.  It should be Andrew, as he 
provided the diff, eventhough I commited it.

Please fix that.

Thanks,

Alex

> ---
>   man2/clone.2 | 10 ++++++++++
>   1 file changed, 10 insertions(+)
> 
> diff --git a/man2/clone.2 b/man2/clone.2
> index e381da165..90db92ad6 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -1209,6 +1209,16 @@ in the caller's context, no child process is created, and
>   is set to indicate the error.
>   .SH ERRORS
>   .TP
> +.BR EACCES " (" clone3 "() only)"
> +.B CLONE_INTO_CGROUP
> +was specified in
> +.IR cl_args.flags ,
> +but the restrictions (described in
> +.BR cgroups (7))
> +on placing the child process into the version 2 cgroup referred to by
> +.I cl_args.cgroup
> +are not met.
> +.TP
>   .B EAGAIN
>   Too many processes are already running; see
>   .BR fork (2).
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 09/15] clone.2: ERRORS: Add EACCESS with CLONE_INTO_CGROUP + clone3

[Christian Brauner]

On Sat, Sep 11, 2021 at 12:47:10AM +0200, Alejandro Colomar wrote:
> [Andrew]:
> I noticed that clone3 can send the EACCES errno after I wrote a
> program that used clone3 with the CLONE_INTO_CGROUP flag.
> To me, it's important to know what kind of failure occurred if the
> clone3() fails, so I was glad that a unique errno is set for
> this case, but it wasn't documented on the clone man page.
> 
> [Christian]:

Hey Alejandro,

I was on vacation last week so just catching up with mails now.

> In essence, any error that could occur during regular fs-based migration
> at write-time can also occur during CLONE_INTO_CGROUP. The clone3()
> manpage just has the inverse of that above statement:
> 
> "Note that all of the usual restrictions (described in cgroups(7)) on
> placing a process into a version 2 cgroup apply."
> 
> Reported-by: Andrew Wock <ajwock@gmail.com>
> Acked-by: Christian Brauner <christian.brauner@ubuntu.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---

Thanks for picking that up.
Christian

Re: [PATCH 13/15] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 7626 bytes --]

Hi Greg,

On 6/21/22 17:00, Greg Banks wrote:
> Hi Michael and Alejandro,
> 
> Did something useful happen to this patch?  I don't see it in any public 
> repo I'm aware of.

I think it's in the official git repository:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man5/nscd.conf.5?id=76954230a81187252201838fb329bff0beee4e8f>

Is that correct?

Thanks,

Alex

> 
> Greg.
> ------------------------------------------------------------------------
> *From:* Alejandro Colomar <alx.manpages@gmail.com>
> *Sent:* Friday, September 10, 2021 18:47
> *To:* mtk.manpages@gmail.com <mtk.manpages@gmail.com>
> *Cc:* Greg Banks <gbanks@linkedin.com>; linux-man@vger.kernel.org 
> <linux-man@vger.kernel.org>; Alejandro Colomar <alx.manpages@gmail.com>
> *Subject:* [PATCH 13/15] nscd.conf.5: describe reloading, clarifications
> From: Greg Banks <gbanks@linkedin.com>
> 
> - Added a subsection of NOTES describing nscd's reloading behavior
>    and providing advice on how to configure it.
> - Clarifications for the threads, reload-count, positive-time-to-live,
>    check-files, and shared attributes.
> 
> Derived by reading the nscd, libresolv and glibc source and some
> painful experience.
> 
> Signed-off-by: Greg Banks <gbanks@linkedin.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>   man5/nscd.conf.5 | 115 +++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 112 insertions(+), 3 deletions(-)
> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..25ee4901b 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 
> Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,13 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
>   At least five threads will always be created.
> +The number of threads may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients,
> +but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +88,20 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being 
> used
> +Sets a limit on the number of times a cached entry
> +gets reloaded without being used
>   before it gets removed.
> -The default is 5.
> +The limit can take values ranging from 0 to 254;
> +values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal
> +or hexadecimal with a "0x" prefix.
> +The special value
> +.B unlimited
> +is case-insensitive.
> +The default limit is 5.
> +A limit of 0 turns off the reloading feature.
> +See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +144,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and
> +this attribute is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +185,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +214,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in
> +asking the daemon over the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -236,6 +258,93 @@ from the source code of
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.BR nscd (8)
> +has a feature called reloading,
> +whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.
> +The default value in the source code enables reloading,
> +although your distribution may differ.
> +.PP
> +When reloading is enabled,
> +positive cached entries (the results of successful queries)
> +do not simply expire when their TTL is up.
> +Instead, at the expiry time,
> +.B nscd
> +will "reload",
> +i.e.,
> +re-issue to the name service the same query that created the cached entry,
> +to get a new value to cache.
> +Depending on
> +.I /etc/nsswitch.conf
> +this may mean that a DNS, LDAP, or NIS request is made.
> +If the new query is successful,
> +reloading will repeat when the new value would expire,
> +until
> +.B reload-count
> +reloads have happened for the entry,
> +and only then will it actually be removed from the cache.
> +A request from a client which hits the entry will
> +reset the reload counter on the entry.
> +Purging the cache using
> +.I nscd\~-i
> +overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs
> +without compromising on cache coherency,
> +at the cost of additional load on the backing name service.
> +Whether this is a good idea on your system depends on
> +details of your applications' behavior,
> +your name service,
> +and the effective TTL values of your cache entries.
> +Note that for some name services
> +(for example, DNS),
> +the effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.
> +.PP
> +Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name,
> +after more than 1 TTL but before
> +.B reload\-count
> +TTLs,
> +and is sensitive to the latency of a cache miss,
> +then reloading may be a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs,
> +and your applications only make requests rarely under normal circumstances,
> +then reloading may result in additional load on your backing name service
> +without any benefit to applications,
> +which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited,
> +reloading may have the surprising effect of
> +increasing load on your name service instead of reducing it,
> +and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea,
> +as it will result in a cache that never expires entries
> +and puts never-ending additional load on the backing name service.
> +.PP
> +Some distributions have an init script for
> +.BR nscd (8)
> +with a
> +.I reload
> +command which uses
> +.I nscd\~-i
> +to purge the cache.
> +That use of the word "reload" is entirely different
> +from the "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
> -- 
> 2.33.0
> 

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]