Documentation/filesystems/devpts.txt

   1
   2 To support containers, we now allow multiple instances of devpts filesystem,
   3 such that indices of ptys allocated in one instance are independent of indices
   4 allocated in other instances of devpts.
   5
   6 To preserve backward compatibility, this support for multiple instances is
   7 enabled only if:
   8
   9         - CONFIG_DEVPTS_MULTIPLE_INSTANCES=y, and
  10         - '-o newinstance' mount option is specified while mounting devpts
  11
  12 IOW, devpts now supports both single-instance and multi-instance semantics.
  13
  14 If CONFIG_DEVPTS_MULTIPLE_INSTANCES=n, there is no change in behavior and
  15 this referred to as the "legacy" mode. In this mode, the new mount options
  16 (-o newinstance and -o ptmxmode) will be ignored with a 'bogus option' message
  17 on console.
  18
  19 If CONFIG_DEVPTS_MULTIPLE_INSTANCES=y and devpts is mounted without the
  20 'newinstance' option (as in current start-up scripts) the new mount binds
  21 to the initial kernel mount of devpts. This mode is referred to as the
  22 'single-instance' mode and the current, single-instance semantics are
  23 preserved, i.e PTYs are common across the system.
  24
  25 The only difference between this single-instance mode and the legacy mode
  26 is the presence of new, '/dev/pts/ptmx' node with permissions 0000, which
  27 can safely be ignored.
  28
  29 If CONFIG_DEVPTS_MULTIPLE_INSTANCES=y and 'newinstance' option is specified,
  30 the mount is considered to be in the multi-instance mode and a new instance
  31 of the devpts fs is created. Any ptys created in this instance are independent
  32 of ptys in other instances of devpts. Like in the single-instance mode, the
  33 /dev/pts/ptmx node is present. To effectively use the multi-instance mode,
  34 open of /dev/ptmx must be a redirected to '/dev/pts/ptmx' using a symlink or
  35 bind-mount.
  36
  37 Eg: A container startup script could do the following:
  38
  39         $ chmod 0666 /dev/pts/ptmx
  40         $ rm /dev/ptmx
  41         $ ln -s pts/ptmx /dev/ptmx
  42         $ ns_exec -cm /bin/bash
  43
  44         # We are now in new container
  45
  46         $ umount /dev/pts
  47         $ mount -t devpts -o newinstance lxcpts /dev/pts
  48         $ sshd -p 1234
  49
  50 where 'ns_exec -cm /bin/bash' calls clone() with CLONE_NEWNS flag and execs
  51 /bin/bash in the child process.  A pty created by the sshd is not visible in
  52 the original mount of /dev/pts.
  53
  54 Total count of pty pairs in all instances is limited by sysctls:
  55 kernel.pty.max = 4096           - global limit
  56 kernel.pty.reserve = 1024       - reserve for initial instance
  57 kernel.pty.nr                   - current count of ptys
  58
  59 Per-instance limit could be set by adding mount option "max=<count>".
  60 This feature was added in kernel 3.4 together with sysctl kernel.pty.reserve.
  61 In kernels older than 3.4 sysctl kernel.pty.max works as per-instance limit.
  62
  63 User-space changes
  64 ------------------
  65
  66 In multi-instance mode (i.e '-o newinstance' mount option is specified at least
  67 once), following user-space issues should be noted.
  68
  69 1. If -o newinstance mount option is never used, /dev/pts/ptmx can be ignored
  70    and no change is needed to system-startup scripts.
  71
  72 2. To effectively use multi-instance mode (i.e -o newinstance is specified)
  73    administrators or startup scripts should "redirect" open of /dev/ptmx to
  74    /dev/pts/ptmx using either a bind mount or symlink.
  75
  76         $ mount -t devpts -o newinstance devpts /dev/pts
  77
  78    followed by either
  79
  80         $ rm /dev/ptmx
  81         $ ln -s pts/ptmx /dev/ptmx
  82         $ chmod 666 /dev/pts/ptmx
  83    or
  84         $ mount -o bind /dev/pts/ptmx /dev/ptmx
  85
  86 3. The '/dev/ptmx -> pts/ptmx' symlink is the preferred method since it
  87    enables better error-reporting and treats both single-instance and
  88    multi-instance mounts similarly.
  89
  90    But this method requires that system-startup scripts set the mode of
  91    /dev/pts/ptmx correctly (default mode is 0000). The scripts can set the
  92    mode by, either
  93
  94         - adding ptmxmode mount option to devpts entry in /etc/fstab, or
  95         - using 'chmod 0666 /dev/pts/ptmx'
  96
  97 4. If multi-instance mode mount is needed for containers, but the system
  98    startup scripts have not yet been updated, container-startup scripts
  99    should bind mount /dev/ptmx to /dev/pts/ptmx to avoid breaking single-
 100    instance mounts.
 101
 102    Or, in general, container-startup scripts should use:
 103
 104         mount -t devpts -o newinstance -o ptmxmode=0666 devpts /dev/pts
 105         if [ ! -L /dev/ptmx ]; then
 106                 mount -o bind /dev/pts/ptmx /dev/ptmx
 107         fi
 108
 109    When all devpts mounts are multi-instance, /dev/ptmx can permanently be
 110    a symlink to pts/ptmx and the bind mount can be ignored.
 111
 112 5. A multi-instance mount that is not accompanied by the /dev/ptmx to
 113    /dev/pts/ptmx redirection would result in an unusable/unreachable pty.
 114
 115         mount -t devpts -o newinstance lxcpts /dev/pts
 116
 117    immediately followed by:
 118
 119         open("/dev/ptmx")
 120
 121     would create a pty, say /dev/pts/7, in the initial kernel mount.
 122     But /dev/pts/7 would be invisible in the new mount.
 123
 124 6. The permissions for /dev/pts/ptmx node should be specified when mounting
 125    /dev/pts, using the '-o ptmxmode=%o' mount option (default is 0000).
 126
 127         mount -t devpts -o newinstance -o ptmxmode=0644 devpts /dev/pts
 128
 129    The permissions can be later be changed as usual with 'chmod'.
 130
 131         chmod 666 /dev/pts/ptmx
 132
 133 7. A mount of devpts without the 'newinstance' option results in binding to
 134    initial kernel mount.  This behavior while preserving legacy semantics,
 135    does not provide strict isolation in a container environment. i.e by
 136    mounting devpts without the 'newinstance' option, a container could
 137    get visibility into the 'host' or root container's devpts.
 138
 139    To workaround this and have strict isolation, all mounts of devpts,
 140    including the mount in the root container, should use the newinstance
 141    option.