Version:  2.0.40 2.2.26 2.4.37 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16

Linux/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 User-space changes
 55 ------------------
 56 
 57 In multi-instance mode (i.e '-o newinstance' mount option is specified at least
 58 once), following user-space issues should be noted.
 59 
 60 1. If -o newinstance mount option is never used, /dev/pts/ptmx can be ignored
 61    and no change is needed to system-startup scripts.
 62 
 63 2. To effectively use multi-instance mode (i.e -o newinstance is specified)
 64    administrators or startup scripts should "redirect" open of /dev/ptmx to
 65    /dev/pts/ptmx using either a bind mount or symlink.
 66 
 67         $ mount -t devpts -o newinstance devpts /dev/pts
 68 
 69    followed by either
 70 
 71         $ rm /dev/ptmx
 72         $ ln -s pts/ptmx /dev/ptmx
 73         $ chmod 666 /dev/pts/ptmx
 74    or
 75         $ mount -o bind /dev/pts/ptmx /dev/ptmx
 76 
 77 3. The '/dev/ptmx -> pts/ptmx' symlink is the preferred method since it
 78    enables better error-reporting and treats both single-instance and
 79    multi-instance mounts similarly.
 80 
 81    But this method requires that system-startup scripts set the mode of
 82    /dev/pts/ptmx correctly (default mode is 0000). The scripts can set the
 83    mode by, either
 84 
 85         - adding ptmxmode mount option to devpts entry in /etc/fstab, or
 86         - using 'chmod 0666 /dev/pts/ptmx'
 87 
 88 4. If multi-instance mode mount is needed for containers, but the system
 89    startup scripts have not yet been updated, container-startup scripts
 90    should bind mount /dev/ptmx to /dev/pts/ptmx to avoid breaking single-
 91    instance mounts.
 92 
 93    Or, in general, container-startup scripts should use:
 94 
 95         mount -t devpts -o newinstance -o ptmxmode=0666 devpts /dev/pts
 96         if [ ! -L /dev/ptmx ]; then
 97                 mount -o bind /dev/pts/ptmx /dev/ptmx
 98         fi
 99 
100    When all devpts mounts are multi-instance, /dev/ptmx can permanently be
101    a symlink to pts/ptmx and the bind mount can be ignored.
102 
103 5. A multi-instance mount that is not accompanied by the /dev/ptmx to
104    /dev/pts/ptmx redirection would result in an unusable/unreachable pty.
105 
106         mount -t devpts -o newinstance lxcpts /dev/pts
107 
108    immediately followed by:
109 
110         open("/dev/ptmx")
111 
112     would create a pty, say /dev/pts/7, in the initial kernel mount.
113     But /dev/pts/7 would be invisible in the new mount.
114 
115 6. The permissions for /dev/pts/ptmx node should be specified when mounting
116    /dev/pts, using the '-o ptmxmode=%o' mount option (default is 0000).
117 
118         mount -t devpts -o newinstance -o ptmxmode=0644 devpts /dev/pts
119 
120    The permissions can be later be changed as usual with 'chmod'.
121 
122         chmod 666 /dev/pts/ptmx
123 
124 7. A mount of devpts without the 'newinstance' option results in binding to
125    initial kernel mount.  This behavior while preserving legacy semantics,
126    does not provide strict isolation in a container environment. i.e by
127    mounting devpts without the 'newinstance' option, a container could
128    get visibility into the 'host' or root container's devpts.
129    
130    To workaround this and have strict isolation, all mounts of devpts,
131    including the mount in the root container, should use the newinstance
132    option.

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us