Whamcloud - gitweb
LUDOC-428 sec: doc for Lustre isolation
[doc/manual.git] / ManagingSecurity.xml
index 1f9a9b2..e65a4dc 100644 (file)
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter version="5.0" xml:lang="en-US" xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" xml:id='managingsecurity'>
-  <info>
-    <title xml:id='managingsecurity.title'>Managing Lustre Security</title>
-  </info>
-  <para><anchor xml:id="dbdoclet.50438221_pgfId-1292300" xreflabel=""/>This chapter describes Lustre security and includes the following sections:</para>
-
-  <itemizedlist><listitem>
-          <para><xref linkend="dbdoclet.50438221_16221"/></para>
+<?xml version='1.0' encoding='UTF-8'?><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="managingsecurity">
+  <title xml:id="managingsecurity.title">Managing Security in a Lustre File System</title>
+  <para>This chapter describes security features of the Lustre file system and
+    includes the following sections:</para>
+  <itemizedlist>
+    <listitem>
+      <para><xref linkend="managingSecurity.acl"/></para>
     </listitem>
-<listitem>
-    <para><xref linkend="dbdoclet.50438221_64726"/></para>
+    <listitem>
+      <para><xref linkend="managingSecurity.root_squash"/></para>
     </listitem>
-
-</itemizedlist>
-
-    <section xml:id="dbdoclet.50438221_16221">
-      <title>22.1 Using <anchor xml:id="dbdoclet.50438221_marker-1292306" xreflabel=""/>ACLs</title>
-      <para><anchor xml:id="dbdoclet.50438221_pgfId-1292308" xreflabel=""/>An access control list (ACL), is a set of data that informs an operating system about permissions or access rights that each user or group has to specific system objects, such as directories or files. Each object has a unique security attribute that identifies users who have access to it. The ACL lists each object and user access privileges such as read, write or execute.</para>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1292309" xreflabel=""/>22.1.1 How ACLs Work</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292310" xreflabel=""/>Implementing ACLs varies between operating systems. Systems that support the Portable Operating System Interface (POSIX) family of standards share a simple yet powerful file system permission model, which should be well-known to the Linux/Unix administrator. ACLs add finer-grained permissions to this model, allowing for more complicated permission schemes. For a detailed explanation of ACLs on Linux, refer to the SuSE Labs article, <emphasis>Posix Access Control Lists on Linux</emphasis>:</para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292312" xreflabel=""/><link xl:href="http://www.suse.de/~agruen/acl/linux-acls/online/">http://www.suse.de/~agruen/acl/linux-acls/online/</link></para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292313" xreflabel=""/>We have implemented ACLs according to this model. Lustre works with the standard Linux ACL tools, setfacl, getfacl, and the historical chacl, normally installed with the ACL package.</para>
-                <note><para>ACL support is a system-range feature, meaning that all clients have ACL enabled or not. You cannot specify which clients should enable ACL.</para></note>
-      </section>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1292315" xreflabel=""/>22.1.2 Using <anchor xml:id="dbdoclet.50438221_marker-1292314" xreflabel=""/>ACLs with Lustre</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292557" xreflabel=""/>POSIX Access Control Lists (ACLs) can be used with Lustre. An ACL consists of file entries representing permissions based on standard POSIX file system object permissions that define three classes of user (owner, group and other). Each class is associated with a set of permissions [read (r), write (w) and execute (x)].</para>
-        <itemizedlist><listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1292560" xreflabel=""/> Owner class permissions define access privileges of the file owner.</para>
-          </listitem>
-
-<listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1292569" xreflabel=""/> Group class permissions define access privileges of the owning group.</para>
-          </listitem>
-
-<listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1292572" xreflabel=""/> Other class permissions define access privileges of all users not in the owner or group class.</para>
-          </listitem>
-
-</itemizedlist>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292563" xreflabel=""/>The ls -l command displays the owner, group, and other class permissions in the first column of its output (for example, -rw-r- -- for a regular file with read and write access for the owner class, read access for the group class, and no access for others).</para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292512" xreflabel=""/>Minimal ACLs have three entries. Extended ACLs have more than the three entries. Extended ACLs also contain a mask entry and may contain any number of named user and named group entries.</para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292536" xreflabel=""/>The MDS needs to be configured to enable ACLs. Use --mountfsoptions to enable ACLs when creating your configuration:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292318" xreflabel=""/>$ mkfs.lustre --fsname spfs --mountfsoptions=acl --mdt -mgs /dev/sda
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292319" xreflabel=""/>Alternately, you can enable ACLs at run time by using the --acl option with mkfs.lustre:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292320" xreflabel=""/>$ mount -t lustre -o acl /dev/sda /mnt/mdt
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292472" xreflabel=""/>To check ACLs on the MDS:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292484" xreflabel=""/>$ lctl get_param -n mdc.home-MDT0000-mdc-*.connect_flags | grep acl acl
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292593" xreflabel=""/>To mount the client with no ACLs:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292597" xreflabel=""/>$ mount -t lustre -o noacl ibmds2@o2ib:/home /home
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292321" xreflabel=""/>ACLs are enabled in Lustre on a system-wide basis; either all clients enable ACLs or none do. Activating ACLs is controlled by MDS mount options acl / noacl (enable/disableACLs). Client-side mount options acl/noacl are ignored. You do not need to change the client configuration, and the â€œacl†string will not appear in the client /etc/mtab. The client acl mount option is no longer needed. If a client is mounted with that option, then this message appears in the MDS syslog:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292322" xreflabel=""/>...MDS requires ACL support but client does not
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292323" xreflabel=""/>The message is harmless but indicates a configuration issue, which should be corrected.</para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292324" xreflabel=""/>If ACLs are not enabled on the MDS, then any attempts to reference an ACL on a client return an Operation not supported error.</para>
-      </section>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1292326" xreflabel=""/>22.1.3 <anchor xml:id="dbdoclet.50438221_marker-1292325" xreflabel=""/>Examples</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1292327" xreflabel=""/>These examples are taken directly from the POSIX paper referenced above. ACLs on a Lustre file system work exactly like ACLs on any Linux file system. They are manipulated with the standard tools in the standard manner. Below, we create a directory and allow a specific user access.</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1292328" xreflabel=""/>[root@client lustre]# umask 027
-<anchor xml:id="dbdoclet.50438221_pgfId-1292329" xreflabel=""/>[root@client lustre]# mkdir rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292330" xreflabel=""/>[root@client lustre]# ls -ld rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292331" xreflabel=""/>drwxr-x---  2 root root 4096 Feb 20 06:50 rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292332" xreflabel=""/>[root@client lustre]# getfacl rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292333" xreflabel=""/># file: rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292334" xreflabel=""/># owner: root
-<anchor xml:id="dbdoclet.50438221_pgfId-1292335" xreflabel=""/># group: root
-<anchor xml:id="dbdoclet.50438221_pgfId-1292336" xreflabel=""/>user::rwx
-<anchor xml:id="dbdoclet.50438221_pgfId-1292337" xreflabel=""/>group::r-x
-<anchor xml:id="dbdoclet.50438221_pgfId-1292338" xreflabel=""/>other::---
-<anchor xml:id="dbdoclet.50438221_pgfId-1292339" xreflabel=""/> 
-<anchor xml:id="dbdoclet.50438221_pgfId-1292340" xreflabel=""/>[root@client lustre]# setfacl -m user:chirag:rwx rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292341" xreflabel=""/>[root@client lustre]# ls -ld rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292342" xreflabel=""/>drwxrwx---+ 2 root root 4096 Feb 20 06:50 rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292343" xreflabel=""/>[root@client lustre]# getfacl --omit-heade rain
-<anchor xml:id="dbdoclet.50438221_pgfId-1292344" xreflabel=""/>user::rwx
-<anchor xml:id="dbdoclet.50438221_pgfId-1292345" xreflabel=""/>user:chirag:rwx
-<anchor xml:id="dbdoclet.50438221_pgfId-1292346" xreflabel=""/>group::r-x
-<anchor xml:id="dbdoclet.50438221_pgfId-1292347" xreflabel=""/>mask::rwx
-<anchor xml:id="dbdoclet.50438221_pgfId-1292348" xreflabel=""/>other::---
-</screen>
-      </section>
+    <listitem>
+      <para><xref linkend="managingSecurity.isolation"/></para>
+    </listitem>
+  </itemizedlist>
+  <section xml:id="managingSecurity.acl">
+    <title><indexterm><primary>Access Control List (ACL)</primary></indexterm>
+    Using ACLs</title>
+    <para>An access control list (ACL), is a set of data that informs an
+      operating system about permissions or access rights that each user or
+      group has to specific system objects, such as directories or files. Each
+      object has a unique security attribute that identifies users who have
+      access to it. The ACL lists each object and user access privileges such as
+      read, write or execute.</para>
+    <section xml:id="managingSecurity.acl.howItWorks" remap="h3">
+      <title><indexterm><primary>Access Control List (ACL)</primary><secondary>
+        how they work</secondary></indexterm>How ACLs Work</title>
+      <para>Implementing ACLs varies between operating systems. Systems that
+        support the Portable Operating System Interface (POSIX) family of
+        standards share a simple yet powerful file system permission model,
+        which should be well-known to the Linux/UNIX administrator. ACLs add
+        finer-grained permissions to this model, allowing for more complicated
+        permission schemes. For a detailed explanation of ACLs on a Linux
+        operating system, refer to the SUSE Labs article
+        <link xl:href="http://wiki.lustre.org/images/5/57/PosixAccessControlInLinux.pdf">
+          Posix Access Control Lists on Linux</link>.</para>
+      <para>We have implemented ACLs according to this model. The Lustre
+        software works with the standard Linux ACL tools, setfacl, getfacl, and
+        the historical chacl, normally installed with the ACL package.</para>
+      <note>
+        <para>ACL support is a system-range feature, meaning that all clients
+          have ACL enabled or not. You cannot specify which clients should
+          enable ACL.</para>
+      </note>
     </section>
-    <section xml:id="dbdoclet.50438221_64726">
-      <title>22.2 Using <anchor xml:id="dbdoclet.50438221_marker-1294644" xreflabel=""/>Root Squash</title>
-      <para><anchor xml:id="dbdoclet.50438221_pgfId-1296220" xreflabel=""/>Lustre 1.6 introduced root squash functionality, a security feature which controls super user access rights to an Lustre file system. Before the root squash feature was added, Lustre users could run rm -rf * as root, and remove data which should not be deleted. Using the root squash feature prevents this outcome.</para>
-      <para><anchor xml:id="dbdoclet.50438221_pgfId-1296221" xreflabel=""/>The root squash feature works by re-mapping the user ID (UID) and group ID (GID) of the root user to a UID and GID specified by the system administrator, via the Lustre configuration management server (MGS). The root squash feature also enables the Lustre administrator to specify a set of client for which UID/GID re-mapping does not apply.</para>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1292937" xreflabel=""/>22.2.1 Configuring <anchor xml:id="dbdoclet.50438221_marker-1294610" xreflabel=""/>Root Squash</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296229" xreflabel=""/>Root squash functionality is managed by two configuration parameters, root_squash and nosquash_nids.</para>
-        <itemizedlist><listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1296230" xreflabel=""/> The root_squash parameter specifies the UID and GID with which the root user accesses the Lustre file system.</para>
-          </listitem>
-
-<listitem>
-    <para><anchor xml:id="dbdoclet.50438221_pgfId-1296231" xreflabel=""/> The nosquash_nids parameter specifies the set of clients to which root squash does not apply. LNET NID range syntax is used for this parameter (see the NID range syntax rules described in <xref linkend="dbdoclet.50438221_48757"/>). For example:</para>
-          </listitem>
-
-</itemizedlist>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296235" xreflabel=""/>nosquash_nids=172.16.245.[0-255/2]@tcp
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296236" xreflabel=""/>In this example, root squash does not apply to TCP clients on subnet 172.16.245.0 that have an even number as the last component of their IP address.</para>
-      </section>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1292749" xreflabel=""/>22.2.2 <anchor xml:id="dbdoclet.50438221_48757" xreflabel=""/>Enabling and <anchor xml:id="dbdoclet.50438221_marker-1294611" xreflabel=""/>Tuning Root Squash</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296245" xreflabel=""/>The default value for nosquash_nids is NULL, which means that root squashing applies to all clients. Setting the root squash UID and GID to 0 turns root squash off.</para>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296246" xreflabel=""/>Root squash parameters can be set when the MDT is created (mkfs.lustre --mdt). For example:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296247" xreflabel=""/>mkfs.lustre --reformat --fsname=Lustre --mdt --mgs \
-<anchor xml:id="dbdoclet.50438221_pgfId-1296248" xreflabel=""/>       --param &quot;mds.root_squash=500:501&quot; \
-<anchor xml:id="dbdoclet.50438221_pgfId-1296249" xreflabel=""/>       --param &quot;mds.nosquash_nids=&apos;0@elan1 192.168.1.[10,11]&apos;&quot; /dev/sda1
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296250" xreflabel=""/>Root squash parameters can also be changed on an unmounted device with tunefs.lustre. For example:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296251" xreflabel=""/>tunefs.lustre --param &quot;mds.root_squash=65534:65534&quot;  \
-<anchor xml:id="dbdoclet.50438221_pgfId-1296252" xreflabel=""/>--param &quot;mds.nosquash_nids=192.168.0.13@tcp0&quot; /dev/sda1
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296253" xreflabel=""/>Root squash parameters can also be changed with the lctl conf_param command. For example:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296254" xreflabel=""/>lctl conf_param Lustre.mds.root_squash=&quot;1000:100&quot;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296255" xreflabel=""/>lctl conf_param Lustre.mds.nosquash_nids=&quot;*@tcp&quot;
-</screen>
-                <note><para>When using the lctl conf_param command, keep in mind:</para><para> * lctl conf_param must be run on a live MGS</para><para> * lctl conf_param causes the parameter to change on all MDSs</para><para> * lctl conf_param is to be used once per a parameter</para></note>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296271" xreflabel=""/>The nosquash_nids list can be cleared with:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296272" xreflabel=""/>lctl conf_param Lustre.mds.nosquash_nids=&quot;NONE&quot;
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296273" xreflabel=""/>- OR -</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296274" xreflabel=""/>lctl conf_param Lustre.mds.nosquash_nids=&quot;clear&quot;
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296275" xreflabel=""/>If the nosquash_nids value consists of several NID ranges (e.g. 0@elan, 1@elan1), the list of NID ranges must be quoted with single (&apos;) or double (&apos;&apos;) quotation marks. List elements must be separated with a space. For example:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296276" xreflabel=""/>mkfs.lustre ... --param &quot;mds.nosquash_nids=&apos;0@elan1 1@elan2&apos;&quot; /dev/sda1
-<anchor xml:id="dbdoclet.50438221_pgfId-1296277" xreflabel=""/>lctl conf_param Lustre.mds.nosquash_nids=&quot;24@elan 15@elan1&quot;
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296278" xreflabel=""/>These are examples of incorrect syntax:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296279" xreflabel=""/>mkfs.lustre ... --param &quot;mds.nosquash_nids=0@elan1 1@elan2&quot; /dev/sda1
-<anchor xml:id="dbdoclet.50438221_pgfId-1296280" xreflabel=""/>lctl conf_param Lustre.mds.nosquash_nids=24@elan 15@elan1
-</screen>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296281" xreflabel=""/>To check root squash parameters, use the lctl get_param command:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296282" xreflabel=""/>lctl get_param mds.Lustre-MDT0000.root_squash
-<anchor xml:id="dbdoclet.50438221_pgfId-1296283" xreflabel=""/>lctl get_param mds.Lustre-MDT000*.nosquash_nids
+    <section xml:id="managingSecurity.acl.using" remap="h3">
+      <title><indexterm>
+        <primary>Access Control List (ACL)</primary>
+        <secondary>using</secondary>
+      </indexterm>Using ACLs with the Lustre Software</title>
+      <para>POSIX Access Control Lists (ACLs) can be used with the Lustre
+        software. An ACL consists of file entries representing permissions based
+        on standard POSIX file system object permissions that define three
+        classes of user (owner, group and other). Each class is associated with
+        a set of permissions [read (r), write (w) and execute (x)].</para>
+      <itemizedlist>
+        <listitem>
+          <para>Owner class permissions define access privileges of the file
+            owner.</para>
+        </listitem>
+        <listitem>
+          <para>Group class permissions define access privileges of the owning
+            group.</para>
+        </listitem>
+        <listitem>
+          <para>Other class permissions define access privileges of all users
+            not in the owner or group class.</para>
+        </listitem>
+      </itemizedlist>
+      <para>The <literal>ls -l</literal> command displays the owner, group, and
+        other class permissions in the first column of its output (for example,
+        <literal>-rw-r- --</literal> for a regular file with read and write
+        access for the owner class, read access for the group class, and no
+        access for others).</para>
+      <para>Minimal ACLs have three entries. Extended ACLs have more than the
+        three entries. Extended ACLs also contain a mask entry and may contain
+        any number of named user and named group entries.</para>
+      <para>The MDS needs to be configured to enable ACLs. Use
+        <literal>--mountfsoptions</literal> to enable ACLs when creating your
+        configuration:</para>
+      <screen>$ mkfs.lustre --fsname spfs --mountfsoptions=acl --mdt -mgs /dev/sda</screen>
+      <para>Alternately, you can enable ACLs at run time by using the
+        <literal>--acl</literal> option with <literal>mkfs.lustre</literal>:
+      </para>
+      <screen>$ mount -t lustre -o acl /dev/sda /mnt/mdt</screen>
+      <para>To check ACLs on the MDS:</para>
+      <screen>$ lctl get_param -n mdc.home-MDT0000-mdc-*.connect_flags | grep acl acl</screen>
+      <para>To mount the client with no ACLs:</para>
+      <screen>$ mount -t lustre -o noacl ibmds2@o2ib:/home /home</screen>
+      <para>ACLs are enabled in a Lustre file system on a system-wide basis;
+        either all clients enable ACLs or none do. Activating ACLs is controlled
+        by MDS mount options <literal>acl</literal> / <literal>noacl</literal>
+        (enable/disable ACLs). Client-side mount options acl/noacl are ignored.
+        You do not need to change the client configuration, and the
+        &apos;acl&apos; string will not appear in the client /etc/mtab. The
+        client acl mount option is no longer needed. If a client is mounted with
+        that option, then this message appears in the MDS syslog:</para>
+      <screen>...MDS requires ACL support but client does not</screen>
+      <para>The message is harmless but indicates a configuration issue, which
+        should be corrected.</para>
+      <para>If ACLs are not enabled on the MDS, then any attempts to reference
+        an ACL on a client return an Operation not supported error.</para>
+    </section>
+    <section xml:id="managingSecurity.acl.examples" remap="h3">
+        <title><indexterm>
+          <primary>Access Control List (ACL)</primary>
+          <secondary>examples</secondary>
+        </indexterm>Examples</title>
+      <para>These examples are taken directly from the POSIX paper referenced
+        above. ACLs on a Lustre file system work exactly like ACLs on any Linux
+        file system. They are manipulated with the standard tools in the
+        standard manner. Below, we create a directory and allow a specific user
+        access.</para>
+      <screen>[root@client lustre]# umask 027
+[root@client lustre]# mkdir rain
+[root@client lustre]# ls -ld rain
+drwxr-x---  2 root root 4096 Feb 20 06:50 rain
+[root@client lustre]# getfacl rain
+# file: rain
+# owner: root
+# group: root
+user::rwx
+group::r-x
+other::---
+[root@client lustre]# setfacl -m user:chirag:rwx rain
+[root@client lustre]# ls -ld rain
+drwxrwx---+ 2 root root 4096 Feb 20 06:50 rain
+[root@client lustre]# getfacl --omit-header rain
+user::rwx
+user:chirag:rwx
+group::r-x
+mask::rwx
+other::---</screen>
+    </section>
+  </section>
+  <section xml:id="managingSecurity.root_squash">
+    <title><indexterm>
+      <primary>root squash</primary>
+    </indexterm>Using Root Squash</title>
+    <para>Root squash is a security feature which restricts super-user access
+      rights to a Lustre file system. Without the root squash feature enabled,
+      Lustre file system users on untrusted clients could access or modify files
+      owned by root on the file system, including deleting them. Using the root
+      squash feature restricts file access/modifications as the root user to
+      only the specified clients. Note, however, that this does
+      <emphasis>not</emphasis> prevent users on insecure clients from accessing
+      files owned by <emphasis>other</emphasis> users.</para>
+    <para>The root squash feature works by re-mapping the user ID (UID) and
+      group ID (GID) of the root user to a UID and GID specified by the system
+      administrator, via the Lustre configuration management server (MGS). The
+      root squash feature also enables the Lustre file system administrator to
+      specify a set of client for which UID/GID re-mapping does not apply.
+    </para>
+               <note><para>Nodemaps (<xref linkend="lustrenodemap.title" />) are an
+               alternative to root squash, since it also allows root squash on a per-client
+               basis.  With UID maps, the clients can even have a local root UID without
+               actually having root access to the filesystem itself.</para></note>
+    <section xml:id="managingSecurity.root_squash.config" remap="h3">
+      <title><indexterm>
+        <primary>root squash</primary>
+        <secondary>configuring</secondary>
+      </indexterm>Configuring Root Squash</title>
+      <para>Root squash functionality is managed by two configuration
+        parameters, <literal>root_squash</literal> and
+        <literal>nosquash_nids</literal>.</para>
+      <itemizedlist>
+        <listitem>
+          <para>The <literal>root_squash</literal> parameter specifies the UID
+            and GID with which the root user accesses the Lustre file system.
+          </para>
+        </listitem>
+        <listitem>
+          <para>The <literal>nosquash_nids</literal> parameter specifies the set
+            of clients to which root squash does not apply. LNet NID range
+            syntax is used for this parameter (see the NID range syntax rules
+            described in <xref linkend="managingSecurity.root_squash"/>). For
+            example:</para>
+        </listitem>
+      </itemizedlist>
+      <screen>nosquash_nids=172.16.245.[0-255/2]@tcp</screen>
+      <para>In this example, root squash does not apply to TCP clients on subnet
+        172.16.245.0 that have an even number as the last component of their IP
+        address.</para>
+    </section>
+    <section xml:id="managingSecurity.root_squash.tuning">
+      <title><indexterm>
+        <primary>root squash</primary><secondary>enabling</secondary>
+      </indexterm>Enabling and Tuning Root Squash</title>
+      <para>The default value for <literal>nosquash_nids</literal> is NULL,
+        which means that root squashing applies to all clients. Setting the root
+        squash UID and GID to 0 turns root squash off.</para>
+      <para>Root squash parameters can be set when the MDT is created
+        (<literal>mkfs.lustre --mdt</literal>). For example:</para>
+      <screen>mds# mkfs.lustre --reformat --fsname=testfs --mdt --mgs \
+       --param &quot;mdt.root_squash=500:501&quot; \
+       --param &quot;mdt.nosquash_nids=&apos;0@elan1 192.168.1.[10,11]&apos;&quot; /dev/sda1</screen>
+      <para>Root squash parameters can also be changed on an unmounted device
+        with <literal>tunefs.lustre</literal>. For example:</para>
+      <screen>tunefs.lustre --param &quot;mdt.root_squash=65534:65534&quot;  \
+--param &quot;mdt.nosquash_nids=192.168.0.13@tcp0&quot; /dev/sda1
 </screen>
-                <note><para>An empty nosquash_nids list is reported as NONE.</para></note>
-      </section>
-      <section remap="h3">
-        <title><anchor xml:id="dbdoclet.50438221_pgfId-1293871" xreflabel=""/>22.2.3 Tips on Using <anchor xml:id="dbdoclet.50438221_marker-1296366" xreflabel=""/>Root Squash</title>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296298" xreflabel=""/>Lustre configuration management limits root squash in several ways.</para>
-        <itemizedlist><listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1296299" xreflabel=""/> The lctl conf_param value overwrites the parameter’s previous value. If the new value uses an incorrect syntax, then the system continues with the old parameters and the previously-correct value is lost on remount. That is, be careful doing root squash tuning.</para>
+      <para>Root squash parameters can also be changed with the
+      <literal>lctl conf_param</literal> command. For example:</para>
+      <screen>mgs# lctl conf_param testfs.mdt.root_squash=&quot;1000:101&quot;
+mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;*@tcp&quot;</screen>
+      <para>To retrieve the current root squash parameter settings, the
+      following <literal>lctl get_param</literal> commands can be used:</para>
+      <screen>mgs# lctl get_param mdt.*.root_squash
+mgs# lctl get_param mdt.*.nosquash_nids</screen>
+      <note>
+        <para>When using the lctl conf_param command, keep in mind:</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>lctl conf_param</literal> must be run on a live MGS
+            </para>
           </listitem>
-
-<listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1296300" xreflabel=""/>mkfs.lustre  and tunefs.lustre do not perform syntax checking. If the root squash parameters are incorrect, they are ignored on mount and the default values are used instead.</para>
+          <listitem>
+            <para><literal>lctl conf_param</literal> causes the parameter to
+              change on all MDSs</para>
           </listitem>
-
-<listitem>
-            <para><anchor xml:id="dbdoclet.50438221_pgfId-1296301" xreflabel=""/> Root squash parameters are parsed with rigorous syntax checking. The root_squash parameter should be specified as &lt;decnum&gt;&apos;:&apos;&lt;decnum&gt;. The nosquash_nids parameter should follow LNET NID range list syntax.</para>
+          <listitem>
+            <para><literal>lctl conf_param</literal> is to be used once per a
+              parameter</para>
           </listitem>
-
-</itemizedlist>
-        <para><anchor xml:id="dbdoclet.50438221_pgfId-1296302" xreflabel=""/>LNET NID range syntax:</para>
-        <screen><anchor xml:id="dbdoclet.50438221_pgfId-1296303" xreflabel=""/>&lt;nidlist&gt;     :== &lt;nidrange&gt; [ &apos; &apos; &lt;nidrange&gt; ]
-<anchor xml:id="dbdoclet.50438221_pgfId-1296304" xreflabel=""/>&lt;nidrange&gt;   :== &lt;addrrange&gt; &apos;@&apos; &lt;net&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296305" xreflabel=""/>&lt;addrrange&gt;  :== &apos;*&apos; |
-<anchor xml:id="dbdoclet.50438221_pgfId-1296306" xreflabel=""/>           &lt;ipaddr_range&gt; |
-<anchor xml:id="dbdoclet.50438221_pgfId-1296307" xreflabel=""/>           &lt;numaddr_range&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296308" xreflabel=""/>&lt;ipaddr_range&gt;       :==
-<anchor xml:id="dbdoclet.50438221_pgfId-1296309" xreflabel=""/>&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296310" xreflabel=""/>&lt;numaddr_range&gt;      :== &lt;number&gt; |
-<anchor xml:id="dbdoclet.50438221_pgfId-1296311" xreflabel=""/>                   &lt;expr_list&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296312" xreflabel=""/>&lt;expr_list&gt;  :== &apos;[&apos; &lt;range_expr&gt; [ &apos;,&apos; &lt;range_expr&gt;] &apos;]&apos;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296313" xreflabel=""/>&lt;range_expr&gt; :== &lt;number&gt; |
-<anchor xml:id="dbdoclet.50438221_pgfId-1296314" xreflabel=""/>           &lt;number&gt; &apos;-&apos; &lt;number&gt; |
-<anchor xml:id="dbdoclet.50438221_pgfId-1296315" xreflabel=""/>           &lt;number&gt; &apos;-&apos; &lt;number&gt; &apos;/&apos; &lt;number&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296316" xreflabel=""/>&lt;net&gt;        :== &lt;netname&gt; | &lt;netname&gt;&lt;number&gt;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296317" xreflabel=""/>&lt;netname&gt;    :== &quot;lo&quot; | &quot;tcp&quot; | &quot;o2ib&quot; | &quot;cib&quot; | &quot;openib&quot; | &quot;iib&quot; | 
-<anchor xml:id="dbdoclet.50438221_pgfId-1296318" xreflabel=""/>           &quot;vib&quot; | &quot;ra&quot; | &quot;elan&quot; | &quot;gm&quot; | &quot;mx&quot; | &quot;ptl&quot;
-<anchor xml:id="dbdoclet.50438221_pgfId-1296319" xreflabel=""/>&lt;number&gt;     :== &lt;nonnegative decimal&gt; | &lt;hexadecimal&gt;
-</screen>
-                <note><para>For networks using numeric addresses (e.g. elan), the address range must be specified in the &lt;numaddr_range&gt; syntax. For networks using IP addresses, the address range must be in the &lt;ipaddr_range&gt;. For example, if elan is using numeric addresses, 1.2.3.4@elan is incorrect.</para></note>
-      </section>
+        </itemizedlist>
+      </note>
+      <para>The root squash settings can also be changed temporarily with
+      <literal>lctl set_param</literal> or persistently with
+      <literal>lctl set_param -P</literal>.  For example:</para>
+      <screen>mgs# lctl set_param mdt.testfs-MDT0000.root_squash="1:0"
+mgs# lctl set_param -P mdt.testfs-MDT0000.root_squash="1:0"</screen>
+      <para>The <literal>nosquash_nids</literal> list can be cleared with:</para>
+      <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;NONE&quot;</screen>
+      <para>- OR -</para>
+      <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;clear&quot;</screen>
+      <para>If the <literal>nosquash_nids</literal> value consists of several
+        NID ranges (e.g. <literal>0@elan</literal>, <literal>1@elan1</literal>),
+        the list of NID ranges must be quoted with single (&apos;) or double
+        (&apos;&apos;) quotation marks. List elements must be separated with a
+        space. For example:</para>
+      <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=&apos;0@elan1 1@elan2&apos;&quot; /dev/sda1
+lctl conf_param testfs.mdt.nosquash_nids=&quot;24@elan 15@elan1&quot;</screen>
+      <para>These are examples of incorrect syntax:</para>
+      <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=0@elan1 1@elan2&quot; /dev/sda1
+lctl conf_param testfs.mdt.nosquash_nids=24@elan 15@elan1</screen>
+      <para>To check root squash parameters, use the lctl get_param command:
+      </para>
+      <screen>mds# lctl get_param mdt.testfs-MDT0000.root_squash
+lctl get_param mdt.*.nosquash_nids</screen>
+      <note>
+        <para>An empty nosquash_nids list is reported as NONE.</para>
+      </note>
+    </section>
+    <section xml:id="managingSecurity.root_squash.tips" remap="h3">
+        <title><indexterm>
+          <primary>root squash</primary>
+          <secondary>tips</secondary>
+        </indexterm>Tips on Using Root Squash</title>
+      <para>Lustre configuration management limits root squash in several ways.
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>The <literal>lctl conf_param</literal> value overwrites the
+            parameter&apos;s previous value. If the new value uses an incorrect
+            syntax, then the system continues with the old parameters and the
+            previously-correct value is lost on remount. That is, be careful
+            doing root squash tuning.</para>
+        </listitem>
+        <listitem>
+          <para><literal>mkfs.lustre</literal> and
+            <literal>tunefs.lustre</literal> do not perform parameter syntax
+            checking. If the root squash parameters are incorrect, they are
+            ignored on mount and the default values are used instead.</para>
+        </listitem>
+        <listitem>
+          <para>Root squash parameters are parsed with rigorous syntax checking.
+            The root_squash parameter should be specified as
+            <literal>&lt;decnum&gt;:&lt;decnum&gt;</literal>. The
+            <literal>nosquash_nids</literal> parameter should follow LNet NID
+            range list syntax.</para>
+        </listitem>
+      </itemizedlist>
+      <para>LNet NID range syntax:</para>
+      <screen>&lt;nidlist&gt;     :== &lt;nidrange&gt; [ &apos; &apos; &lt;nidrange&gt; ]
+&lt;nidrange&gt;   :== &lt;addrrange&gt; &apos;@&apos; &lt;net&gt;
+&lt;addrrange&gt;  :== &apos;*&apos; |
+           &lt;ipaddr_range&gt; |
+           &lt;numaddr_range&gt;
+&lt;ipaddr_range&gt;       :==
+&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;
+&lt;numaddr_range&gt;      :== &lt;number&gt; |
+                   &lt;expr_list&gt;
+&lt;expr_list&gt;  :== &apos;[&apos; &lt;range_expr&gt; [ &apos;,&apos; &lt;range_expr&gt;] &apos;]&apos;
+&lt;range_expr&gt; :== &lt;number&gt; |
+           &lt;number&gt; &apos;-&apos; &lt;number&gt; |
+           &lt;number&gt; &apos;-&apos; &lt;number&gt; &apos;/&apos; &lt;number&gt;
+&lt;net&gt;        :== &lt;netname&gt; | &lt;netname&gt;&lt;number&gt;
+&lt;netname&gt;    :== &quot;lo&quot; | &quot;tcp&quot; | &quot;o2ib&quot;
+           | &quot;ra&quot; | &quot;elan&quot;
+&lt;number&gt;     :== &lt;nonnegative decimal&gt; | &lt;hexadecimal&gt;</screen>
+      <note>
+        <para>For networks using numeric addresses (e.g. elan), the address
+          range must be specified in the
+          <literal>&lt;numaddr_range&gt;</literal> syntax. For networks using
+          IP addresses, the address range must be in the
+          <literal>&lt;ipaddr_range&gt;</literal>. For example, if elan is using
+          numeric addresses, <literal>1.2.3.4@elan</literal> is incorrect.
+        </para>
+      </note>
+    </section>
+  </section>
+  <section xml:id="managingSecurity.isolation">
+    <title><indexterm><primary>Isolation</primary></indexterm>
+    Isolating Clients to a Sub-directory Tree</title>
+    <para>Isolation is the Lustre implementation of the generic concept of
+      multi-tenancy, which aims at providing separated namespaces from a single
+      filesystem. Lustre Isolation enables different populations of users on
+      the same file system beyond normal Unix permissions/ACLs, even when users
+      on the clients may have root access. Those tenants share the same file
+      system, but they are isolated from each other: they cannot access or even
+      see each other’s files, and are not aware that they are sharing common
+      file system resources.</para>
+    <para>Lustre Isolation leverages the Fileset feature
+      (<xref linkend="SystemConfigurationUtilities.fileset" />)
+      to mount only a subdirectory of the filesystem rather than the root
+      directory.
+      In order to achieve isolation, the subdirectory mount, which presents to
+      tenants only their own fileset, has to be imposed to the clients. To that
+      extent, we make use of the nodemap feature
+      (<xref linkend="lustrenodemap.title" />). We group all clients used by a
+      tenant under a common nodemap entry, and we assign to this nodemap entry
+      the fileset to which the tenant is restricted.</para>
+    <section xml:id="managingSecurity.isolation.clientid" remap="h3">
+      <title><indexterm><primary>Isolation</primary><secondary>
+        client identification</secondary></indexterm>Identifying Clients</title>
+      <para>Enforcing multi-tenancy on Lustre relies on the ability to properly
+        identify the client nodes used by a tenant, and trust those identities.
+        This can be achieved by having physical hardware and/or network
+        security, so that client nodes have well-known NIDs. It is also possible
+        to make use of strong authentication with Kerberos or Shared-Secret Key
+       (see <xref linkend="lustressk" />).
+       Kerberos prevents NID spoofing, as every client needs its own
+       credentials, based on its NID, in order to connect to the servers.
+       Shared-Secret Key also prevents tenant impersonation, because keys
+       can be linked to a specific nodemap. See
+       <xref linkend="ssknodemaprole" /> for detailed explanations.
+</para>
+    </section>
+    <section xml:id="managingSecurity.isolation.configuring" remap="h3">
+      <title><indexterm><primary>Isolation</primary><secondary>
+        configuring</secondary></indexterm>Configuring Isolation</title>
+      <para>Isolation on Lustre can be achieved by setting the
+        <literal>fileset</literal> parameter on a nodemap entry. All clients
+       belonging to this nodemap entry will automatically mount this fileset
+       instead of the root directory. For example:</para>
+      <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset '/dir1'</screen>
+      <para>So all clients matching the <literal>tenant1</literal> nodemap will
+        be automatically presented the fileset <literal>/dir1</literal> when
+       mounting. This means these clients are doing an implicit subdirectory
+       mount on the subdirectory <literal>/dir1</literal>.
+      </para>
+      <note>
+        <para>
+         If subdirectory defined as fileset does not exist on the file system,
+         it will prevent any client belonging to the nodemap from mounting
+         Lustre.
+       </para>
+      </note>
+      <para>To delete the fileset parameter, just set it to an empty string:
+      </para>
+      <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset ''</screen>
+    </section>
+    <section xml:id="managingSecurity.isolation.permanent" remap="h3">
+      <title><indexterm><primary>Isolation</primary><secondary>
+        making permanent</secondary></indexterm>Making Isolation Permanent
+      </title>
+      <para>In order to make isolation permanent, the fileset parameter on the
+        nodemap has to be set with <literal>lctl set_param</literal> with the
+      <literal>-P</literal> option.</para>
+      <screen>mgs# lctl set_param nodemap.tenant1.fileset=/dir1
+mgs# lctl set_param -P nodemap.tenant1.fileset=/dir1</screen>
+      <para>This way the fileset parameter will be stored in the Lustre config
+      logs, letting the servers retrieve the information after a restart.
+      </para>
     </section>
+  </section>
 </chapter>