ManagingSecurity.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook"
   3  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US"
   4  xml:id="managingsecurity">
   5   <title xml:id="managingsecurity.title">Managing Security in a Lustre File System</title>
   6   <para>This chapter describes security features of the Lustre file system and
   7     includes the following sections:</para>
   8   <itemizedlist>
   9     <listitem>
  10       <para><xref linkend="managingSecurity.acl"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="managingSecurity.root_squash"/></para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="managingSecurity.isolation"/></para>
  17     </listitem>
  18     <listitem>
  19       <para><xref linkend="managingSecurity.sepol"/></para>
  20     </listitem>
  21     <listitem>
  22       <para><xref linkend="managingSecurity.clientencryption"/></para>
  23     </listitem>
  24   </itemizedlist>
  25   <section xml:id="managingSecurity.acl">
  26     <title><indexterm><primary>Access Control List (ACL)</primary></indexterm>
  27     Using ACLs</title>
  28     <para>An access control list (ACL), is a set of data that informs an
  29       operating system about permissions or access rights that each user or
  30       group has to specific system objects, such as directories or files. Each
  31       object has a unique security attribute that identifies users who have
  32       access to it. The ACL lists each object and user access privileges such as
  33       read, write or execute.</para>
  34     <section xml:id="managingSecurity.acl.howItWorks" remap="h3">
  35       <title><indexterm><primary>Access Control List (ACL)</primary><secondary>
  36         how they work</secondary></indexterm>How ACLs Work</title>
  37       <para>Implementing ACLs varies between operating systems. Systems that
  38         support the Portable Operating System Interface (POSIX) family of
  39         standards share a simple yet powerful file system permission model,
  40         which should be well-known to the Linux/UNIX administrator. ACLs add
  41         finer-grained permissions to this model, allowing for more complicated
  42         permission schemes. For a detailed explanation of ACLs on a Linux
  43         operating system, refer to the SUSE Labs article
  44         <link xl:href="https://www.usenix.org/legacyurl/posix-access-control-lists-linux">
  45           Posix Access Control Lists on Linux</link>.</para>
  46       <para>We have implemented ACLs according to this model. The Lustre
  47         software works with the standard Linux ACL tools, setfacl, getfacl, and
  48         the historical chacl, normally installed with the ACL package.</para>
  49       <note>
  50         <para>ACL support is a system-range feature, meaning that all clients
  51           have ACL enabled or not. You cannot specify which clients should
  52           enable ACL.</para>
  53       </note>
  54     </section>
  55     <section xml:id="managingSecurity.acl.using" remap="h3">
  56       <title><indexterm>
  57         <primary>Access Control List (ACL)</primary>
  58         <secondary>using</secondary>
  59       </indexterm>Using ACLs with the Lustre Software</title>
  60       <para>POSIX Access Control Lists (ACLs) can be used with the Lustre
  61         software. An ACL consists of file entries representing permissions based
  62         on standard POSIX file system object permissions that define three
  63         classes of user (owner, group and other). Each class is associated with
  64         a set of permissions [read (r), write (w) and execute (x)].</para>
  65       <itemizedlist>
  66         <listitem>
  67           <para>Owner class permissions define access privileges of the file
  68             owner.</para>
  69         </listitem>
  70         <listitem>
  71           <para>Group class permissions define access privileges of the owning
  72             group.</para>
  73         </listitem>
  74         <listitem>
  75           <para>Other class permissions define access privileges of all users
  76             not in the owner or group class.</para>
  77         </listitem>
  78       </itemizedlist>
  79       <para>The <literal>ls -l</literal> command displays the owner, group, and
  80         other class permissions in the first column of its output (for example,
  81         <literal>-rw-r- --</literal> for a regular file with read and write
  82         access for the owner class, read access for the group class, and no
  83         access for others).</para>
  84       <para>Minimal ACLs have three entries. Extended ACLs have more than the
  85         three entries. Extended ACLs also contain a mask entry and may contain
  86         any number of named user and named group entries.</para>
  87       <para>The MDS needs to be configured to enable ACLs. Use
  88         <literal>--mountfsoptions</literal> to enable ACLs when creating your
  89         configuration:</para>
  90       <screen>$ mkfs.lustre --fsname spfs --mountfsoptions=acl --mdt -mgs /dev/sda</screen>
  91       <para>Alternately, you can enable ACLs at run time by using the
  92         <literal>--acl</literal> option with <literal>mkfs.lustre</literal>:
  93       </para>
  94       <screen>$ mount -t lustre -o acl /dev/sda /mnt/mdt</screen>
  95       <para>To check ACLs on the MDS:</para>
  96       <screen>$ lctl get_param -n mdc.home-MDT0000-mdc-*.connect_flags | grep acl acl</screen>
  97       <para>To mount the client with no ACLs:</para>
  98       <screen>$ mount -t lustre -o noacl ibmds2@o2ib:/home /home</screen>
  99       <para>ACLs are enabled in a Lustre file system on a system-wide basis;
 100         either all clients enable ACLs or none do. Activating ACLs is controlled
 101         by MDS mount options <literal>acl</literal> / <literal>noacl</literal>
 102         (enable/disable ACLs). Client-side mount options acl/noacl are ignored.
 103         You do not need to change the client configuration, and the
 104         &apos;acl&apos; string will not appear in the client /etc/mtab. The
 105         client acl mount option is no longer needed. If a client is mounted with
 106         that option, then this message appears in the MDS syslog:</para>
 107       <screen>...MDS requires ACL support but client does not</screen>
 108       <para>The message is harmless but indicates a configuration issue, which
 109         should be corrected.</para>
 110       <para>If ACLs are not enabled on the MDS, then any attempts to reference
 111         an ACL on a client return an Operation not supported error.</para>
 112     </section>
 113     <section xml:id="managingSecurity.acl.examples" remap="h3">
 114         <title><indexterm>
 115           <primary>Access Control List (ACL)</primary>
 116           <secondary>examples</secondary>
 117         </indexterm>Examples</title>
 118       <para>These examples are taken directly from the POSIX paper referenced
 119         above. ACLs on a Lustre file system work exactly like ACLs on any Linux
 120         file system. They are manipulated with the standard tools in the
 121         standard manner. Below, we create a directory and allow a specific user
 122         access.</para>
 123       <screen>[root@client lustre]# umask 027
 124 [root@client lustre]# mkdir rain
 125 [root@client lustre]# ls -ld rain
 126 drwxr-x---  2 root root 4096 Feb 20 06:50 rain
 127 [root@client lustre]# getfacl rain
 128 # file: rain
 129 # owner: root
 130 # group: root
 131 user::rwx
 132 group::r-x
 133 other::---
 134
 135 [root@client lustre]# setfacl -m user:chirag:rwx rain
 136 [root@client lustre]# ls -ld rain
 137 drwxrwx---+ 2 root root 4096 Feb 20 06:50 rain
 138 [root@client lustre]# getfacl --omit-header rain
 139 user::rwx
 140 user:chirag:rwx
 141 group::r-x
 142 mask::rwx
 143 other::---</screen>
 144     </section>
 145   </section>
 146   <section xml:id="managingSecurity.root_squash">
 147     <title><indexterm>
 148       <primary>root squash</primary>
 149     </indexterm>Using Root Squash</title>
 150     <para>Root squash is a security feature which restricts super-user access
 151       rights to a Lustre file system. Without the root squash feature enabled,
 152       Lustre file system users on untrusted clients could access or modify files
 153       owned by root on the file system, including deleting them. Using the root
 154       squash feature restricts file access/modifications as the root user to
 155       only the specified clients. Note, however, that this does
 156       <emphasis>not</emphasis> prevent users on insecure clients from accessing
 157       files owned by <emphasis>other</emphasis> users.</para>
 158     <para>The root squash feature works by re-mapping the user ID (UID) and
 159       group ID (GID) of the root user to a UID and GID specified by the system
 160       administrator, via the Lustre configuration management server (MGS). The
 161       root squash feature also enables the Lustre file system administrator to
 162       specify a set of client for which UID/GID re-mapping does not apply.
 163     </para>
 164     <note><para>Nodemaps (<xref linkend="lustrenodemap.title" />) are an
 165       alternative to root squash, since it also allows root squash on a per-client
 166       basis.  With UID maps, the clients can even have a local root UID without
 167       actually having root access to the filesystem itself.</para></note>
 168     <section xml:id="managingSecurity.root_squash.config" remap="h3">
 169       <title><indexterm>
 170         <primary>root squash</primary>
 171         <secondary>configuring</secondary>
 172       </indexterm>Configuring Root Squash</title>
 173       <para>Root squash functionality is managed by two configuration
 174         parameters, <literal>root_squash</literal> and
 175         <literal>nosquash_nids</literal>.</para>
 176       <itemizedlist>
 177         <listitem>
 178           <para>The <literal>root_squash</literal> parameter specifies the UID
 179             and GID with which the root user accesses the Lustre file system.
 180           </para>
 181         </listitem>
 182         <listitem>
 183           <para>The <literal>nosquash_nids</literal> parameter specifies the set
 184             of clients to which root squash does not apply. LNet NID range
 185             syntax is used for this parameter (see the NID range syntax rules
 186             described in <xref linkend="managingSecurity.root_squash"/>). For
 187             example:</para>
 188         </listitem>
 189       </itemizedlist>
 190       <screen>nosquash_nids=172.16.245.[0-255/2]@tcp</screen>
 191       <para>In this example, root squash does not apply to TCP clients on subnet
 192         172.16.245.0 that have an even number as the last component of their IP
 193         address.</para>
 194     </section>
 195     <section xml:id="managingSecurity.root_squash.tuning">
 196       <title><indexterm>
 197         <primary>root squash</primary><secondary>enabling</secondary>
 198       </indexterm>Enabling and Tuning Root Squash</title>
 199       <para>The default value for <literal>nosquash_nids</literal> is NULL,
 200         which means that root squashing applies to all clients. Setting the root
 201         squash UID and GID to 0 turns root squash off.</para>
 202       <para>Root squash parameters can be set when the MDT is created
 203         (<literal>mkfs.lustre --mdt</literal>). For example:</para>
 204       <screen>mds# mkfs.lustre --reformat --fsname=testfs --mdt --mgs \
 205        --param &quot;mdt.root_squash=500:501&quot; \
 206        --param &quot;mdt.nosquash_nids=&apos;0@elan1 192.168.1.[10,11]&apos;&quot; /dev/sda1</screen>
 207       <para>Root squash parameters can also be changed on an unmounted device
 208         with <literal>tunefs.lustre</literal>. For example:</para>
 209       <screen>tunefs.lustre --param &quot;mdt.root_squash=65534:65534&quot;  \
 210 --param &quot;mdt.nosquash_nids=192.168.0.13@tcp0&quot; /dev/sda1
 211 </screen>
 212       <para>Root squash parameters can also be changed with the
 213       <literal>lctl conf_param</literal> command. For example:</para>
 214       <screen>mgs# lctl conf_param testfs.mdt.root_squash=&quot;1000:101&quot;
 215 mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;*@tcp&quot;</screen>
 216       <para>To retrieve the current root squash parameter settings, the
 217       following <literal>lctl get_param</literal> commands can be used:</para>
 218       <screen>mgs# lctl get_param mdt.*.root_squash
 219 mgs# lctl get_param mdt.*.nosquash_nids</screen>
 220       <note>
 221         <para>When using the lctl conf_param command, keep in mind:</para>
 222         <itemizedlist>
 223           <listitem>
 224             <para><literal>lctl conf_param</literal> must be run on a live MGS
 225             </para>
 226           </listitem>
 227           <listitem>
 228             <para><literal>lctl conf_param</literal> causes the parameter to
 229               change on all MDSs</para>
 230           </listitem>
 231           <listitem>
 232             <para><literal>lctl conf_param</literal> is to be used once per a
 233               parameter</para>
 234           </listitem>
 235         </itemizedlist>
 236       </note>
 237       <para>The root squash settings can also be changed temporarily with
 238       <literal>lctl set_param</literal> or persistently with
 239       <literal>lctl set_param -P</literal>.  For example:</para>
 240       <screen>mgs# lctl set_param mdt.testfs-MDT0000.root_squash="1:0"
 241 mgs# lctl set_param -P mdt.testfs-MDT0000.root_squash="1:0"</screen>
 242       <para>The <literal>nosquash_nids</literal> list can be cleared with:</para>
 243       <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;NONE&quot;</screen>
 244       <para>- OR -</para>
 245       <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;clear&quot;</screen>
 246       <para>If the <literal>nosquash_nids</literal> value consists of several
 247         NID ranges (e.g. <literal>0@elan</literal>, <literal>1@elan1</literal>),
 248         the list of NID ranges must be quoted with single (&apos;) or double
 249         (&apos;&apos;) quotation marks. List elements must be separated with a
 250         space. For example:</para>
 251       <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=&apos;0@elan1 1@elan2&apos;&quot; /dev/sda1
 252 lctl conf_param testfs.mdt.nosquash_nids=&quot;24@elan 15@elan1&quot;</screen>
 253       <para>These are examples of incorrect syntax:</para>
 254       <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=0@elan1 1@elan2&quot; /dev/sda1
 255 lctl conf_param testfs.mdt.nosquash_nids=24@elan 15@elan1</screen>
 256       <para>To check root squash parameters, use the lctl get_param command:
 257       </para>
 258       <screen>mds# lctl get_param mdt.testfs-MDT0000.root_squash
 259 lctl get_param mdt.*.nosquash_nids</screen>
 260       <note>
 261         <para>An empty nosquash_nids list is reported as NONE.</para>
 262       </note>
 263     </section>
 264     <section xml:id="managingSecurity.root_squash.tips" remap="h3">
 265         <title><indexterm>
 266           <primary>root squash</primary>
 267           <secondary>tips</secondary>
 268         </indexterm>Tips on Using Root Squash</title>
 269       <para>Lustre configuration management limits root squash in several ways.
 270       </para>
 271       <itemizedlist>
 272         <listitem>
 273           <para>The <literal>lctl conf_param</literal> value overwrites the
 274             parameter&apos;s previous value. If the new value uses an incorrect
 275             syntax, then the system continues with the old parameters and the
 276             previously-correct value is lost on remount. That is, be careful
 277             doing root squash tuning.</para>
 278         </listitem>
 279         <listitem>
 280           <para><literal>mkfs.lustre</literal> and
 281             <literal>tunefs.lustre</literal> do not perform parameter syntax
 282             checking. If the root squash parameters are incorrect, they are
 283             ignored on mount and the default values are used instead.</para>
 284         </listitem>
 285         <listitem>
 286           <para>Root squash parameters are parsed with rigorous syntax checking.
 287             The root_squash parameter should be specified as
 288             <literal>&lt;decnum&gt;:&lt;decnum&gt;</literal>. The
 289             <literal>nosquash_nids</literal> parameter should follow LNet NID
 290             range list syntax.</para>
 291         </listitem>
 292       </itemizedlist>
 293       <para>LNet NID range syntax:</para>
 294       <screen>&lt;nidlist&gt;     :== &lt;nidrange&gt; [ &apos; &apos; &lt;nidrange&gt; ]
 295 &lt;nidrange&gt;   :== &lt;addrrange&gt; &apos;@&apos; &lt;net&gt;
 296 &lt;addrrange&gt;  :== &apos;*&apos; |
 297            &lt;ipaddr_range&gt; |
 298            &lt;numaddr_range&gt;
 299 &lt;ipaddr_range&gt;       :==
 300 &lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;
 301 &lt;numaddr_range&gt;      :== &lt;number&gt; |
 302                    &lt;expr_list&gt;
 303 &lt;expr_list&gt;  :== &apos;[&apos; &lt;range_expr&gt; [ &apos;,&apos; &lt;range_expr&gt;] &apos;]&apos;
 304 &lt;range_expr&gt; :== &lt;number&gt; |
 305            &lt;number&gt; &apos;-&apos; &lt;number&gt; |
 306            &lt;number&gt; &apos;-&apos; &lt;number&gt; &apos;/&apos; &lt;number&gt;
 307 &lt;net&gt;        :== &lt;netname&gt; | &lt;netname&gt;&lt;number&gt;
 308 &lt;netname&gt;    :== &quot;lo&quot; | &quot;tcp&quot; | &quot;o2ib&quot;
 309            | &quot;ra&quot; | &quot;elan&quot;
 310 &lt;number&gt;     :== &lt;nonnegative decimal&gt; | &lt;hexadecimal&gt;</screen>
 311       <note>
 312         <para>For networks using numeric addresses (e.g. elan), the address
 313           range must be specified in the
 314           <literal>&lt;numaddr_range&gt;</literal> syntax. For networks using
 315           IP addresses, the address range must be in the
 316           <literal>&lt;ipaddr_range&gt;</literal>. For example, if elan is using
 317           numeric addresses, <literal>1.2.3.4@elan</literal> is incorrect.
 318         </para>
 319       </note>
 320     </section>
 321   </section>
 322   <section xml:id="managingSecurity.isolation">
 323     <title><indexterm><primary>Isolation</primary></indexterm>
 324     Isolating Clients to a Sub-directory Tree</title>
 325     <para>Isolation is the Lustre implementation of the generic concept of
 326       multi-tenancy, which aims at providing separated namespaces from a single
 327       filesystem. Lustre Isolation enables different populations of users on
 328       the same file system beyond normal Unix permissions/ACLs, even when users
 329       on the clients may have root access. Those tenants share the same file
 330       system, but they are isolated from each other: they cannot access or even
 331       see each other’s files, and are not aware that they are sharing common
 332       file system resources.</para>
 333     <para>Lustre Isolation leverages the Fileset feature
 334       (<xref linkend="SystemConfigurationUtilities.fileset" />)
 335       to mount only a subdirectory of the filesystem rather than the root
 336       directory.
 337       In order to achieve isolation, the subdirectory mount, which presents to
 338       tenants only their own fileset, has to be imposed to the clients. To that
 339       extent, we make use of the nodemap feature
 340       (<xref linkend="lustrenodemap.title" />). We group all clients used by a
 341       tenant under a common nodemap entry, and we assign to this nodemap entry
 342       the fileset to which the tenant is restricted.</para>
 343     <section xml:id="managingSecurity.isolation.clientid" remap="h3">
 344       <title><indexterm><primary>Isolation</primary><secondary>
 345         client identification</secondary></indexterm>Identifying Clients</title>
 346       <para>Enforcing multi-tenancy on Lustre relies on the ability to properly
 347         identify the client nodes used by a tenant, and trust those identities.
 348         This can be achieved by having physical hardware and/or network
 349         security, so that client nodes have well-known NIDs. It is also possible
 350         to make use of strong authentication with Kerberos or Shared-Secret Key
 351         (see <xref linkend="lustressk" />).
 352         Kerberos prevents NID spoofing, as every client needs its own
 353         credentials, based on its NID, in order to connect to the servers.
 354         Shared-Secret Key also prevents tenant impersonation, because keys
 355         can be linked to a specific nodemap. See
 356         <xref linkend="ssknodemaprole" /> for detailed explanations.
 357 </para>
 358     </section>
 359     <section xml:id="managingSecurity.isolation.configuring" remap="h3">
 360       <title><indexterm><primary>Isolation</primary><secondary>
 361         configuring</secondary></indexterm>Configuring Isolation</title>
 362       <para>Isolation on Lustre can be achieved by setting the
 363         <literal>fileset</literal> parameter on a nodemap entry. All clients
 364         belonging to this nodemap entry will automatically mount this fileset
 365         instead of the root directory. For example:</para>
 366       <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset '/dir1'</screen>
 367       <para>So all clients matching the <literal>tenant1</literal> nodemap will
 368         be automatically presented the fileset <literal>/dir1</literal> when
 369         mounting. This means these clients are doing an implicit subdirectory
 370         mount on the subdirectory <literal>/dir1</literal>.
 371       </para>
 372       <note>
 373         <para>
 374           If subdirectory defined as fileset does not exist on the file system,
 375           it will prevent any client belonging to the nodemap from mounting
 376           Lustre.
 377         </para>
 378       </note>
 379       <para>To delete the fileset parameter, just set it to an empty string:
 380       </para>
 381       <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset ''</screen>
 382     </section>
 383     <section xml:id="managingSecurity.isolation.permanent" remap="h3">
 384       <title><indexterm><primary>Isolation</primary><secondary>
 385         making permanent</secondary></indexterm>Making Isolation Permanent
 386       </title>
 387       <para>In order to make isolation permanent, the fileset parameter on the
 388         nodemap has to be set with <literal>lctl set_param</literal> with the
 389       <literal>-P</literal> option.</para>
 390       <screen>mgs# lctl set_param nodemap.tenant1.fileset=/dir1
 391 mgs# lctl set_param -P nodemap.tenant1.fileset=/dir1</screen>
 392       <para>This way the fileset parameter will be stored in the Lustre config
 393       logs, letting the servers retrieve the information after a restart.
 394       </para>
 395     </section>
 396   </section>
 397   <section xml:id="managingSecurity.sepol" condition='l2D'>
 398     <title><indexterm><primary>selinux policy check</primary></indexterm>
 399     Checking SELinux Policy Enforced by Lustre Clients</title>
 400     <para>SELinux provides a mechanism in Linux for supporting Mandatory Access
 401       Control (MAC) policies. When a MAC policy is enforced, the operating
 402       system’s (OS) kernel defines application rights, firewalling applications
 403       from compromising the entire system. Regular users do not have the ability to
 404       override the policy.</para>
 405     <para>One purpose of SELinux is to protect the
 406       <emphasis role="bold">OS</emphasis> from privilege escalation. To that
 407       extent, SELinux defines confined and unconfined domains for processes and
 408       users. Each process, user, file is assigned a security context, and
 409       rules define the allowed operations by processes and users on files.
 410     </para>
 411     <para>Another purpose of SELinux can be to protect
 412       <emphasis role="bold">data</emphasis> sensitivity, thanks to Multi-Level
 413       Security (MLS). MLS works on top of SELinux, by defining the concept of
 414       security levels in addition to domains. Each process, user and file is
 415       assigned a security level, and the model states that processes and users
 416       can read the same or lower security level, but can only write to their own
 417       or higher security level.
 418     </para>
 419     <para>From a file system perspective, the security context of files must be
 420       stored permanently. Lustre makes use of the
 421       <literal>security.selinux</literal> extended attributes on files to hold
 422       this information. Lustre supports SELinux on the client side. All you have
 423       to do to have MAC and MLS on Lustre is to enforce the appropriate SELinux
 424       policy (as provided by the Linux distribution) on all Lustre clients. No
 425       SELinux is required on Lustre servers.
 426     </para>
 427     <para>Because Lustre is a distributed file system, the specificity when
 428       using MLS is that Lustre really needs to make sure data is always accessed
 429       by nodes with the SELinux MLS policy properly enforced. Otherwise, data is
 430       not protected. This means Lustre has to check that SELinux is properly
 431       enforced on client side, with the right, unaltered policy. And if SELinux
 432       is not enforced as expected on a client, the server denies its access to
 433       Lustre.
 434     </para>
 435     <section xml:id="managingSecurity.sepol.determining" remap="h3">
 436       <title><indexterm><primary>selinux policy check</primary><secondary>
 437         determining</secondary></indexterm>Determining SELinux Policy Info
 438       </title>
 439       <para>A string that represents the SELinux Status info will be used by
 440         servers as a reference, to check if clients are enforcing SELinux
 441         properly. This reference string can be obtained on a client node known
 442         to enforce the right SELinux policy, by calling the
 443         <literal>l_getsepol</literal> command line utility:</para>
 444         <screen>client# l_getsepol
 445 SELinux status info: 1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</screen>
 446         <para>The string describing the SELinux policy has the following
 447           syntax:</para>
 448         <para><literal>mode:name:version:hash</literal></para>
 449         <para>where:</para>
 450           <itemizedlist>
 451             <listitem>
 452               <para><literal>mode</literal> is a digit telling if SELinux is in
 453                 Permissive mode (0) or Enforcing mode (1)</para>
 454             </listitem>
 455             <listitem>
 456               <para><literal>name</literal> is the name of the SELinux policy
 457               </para>
 458             </listitem>
 459             <listitem>
 460               <para><literal>version</literal> is the version of the SELinux
 461               policy</para>
 462             </listitem>
 463             <listitem>
 464               <para><literal>hash</literal> is the computed hash of the binary
 465                 representation of the policy, as exported in
 466                 /etc/selinux/<literal>name</literal>/policy/policy.
 467                 <literal>version</literal></para>
 468             </listitem>
 469           </itemizedlist>
 470     </section>
 471     <section xml:id="managingSecurity.sepol.configuring" remap="h3">
 472       <title><indexterm><primary>selinux policy check</primary><secondary>
 473         enforcing</secondary></indexterm>Enforcing SELinux Policy Check</title>
 474       <para>SELinux policy check can be enforced by setting the
 475         <literal>sepol</literal> parameter on a nodemap entry. All clients
 476         belonging to this nodemap entry must enforce the SELinux policy
 477         described by this parameter, otherwise they are denied access to the
 478         Lustre file system. For example:</para>
 479       <screen>mgs# lctl nodemap_set_sepol --name restricted
 480      --sepol '1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f'</screen>
 481       <para>So all clients matching the <literal>restricted</literal> nodemap
 482         must enforce the SELinux policy which description matches
 483         <literal>1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</literal>.
 484         If not, they will get Permission Denied when trying to mount or access
 485         files on the Lustre file system.</para>
 486       <para>To delete the <literal>sepol</literal> parameter, just set it to an
 487         empty string:</para>
 488       <screen>mgs# lctl nodemap_set_sepol --name restricted --sepol ''</screen>
 489       <para>See <xref linkend="lustrenodemap.title" /> for more details about
 490         the Nodemap feature.</para>
 491     </section>
 492     <section xml:id="managingSecurity.sepol.permanent" remap="h3">
 493       <title><indexterm><primary>selinux policy check</primary><secondary>
 494         making permanent</secondary></indexterm>Making SELinux Policy Check
 495         Permanent</title>
 496       <para>In order to make SELinux Policy check permanent, the sepol parameter
 497         on the nodemap has to be set with <literal>lctl set_param</literal> with
 498         the <literal>-P</literal> option.</para>
 499       <screen>mgs# lctl set_param nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f
 500 mgs# lctl set_param -P nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</screen>
 501       <para>This way the sepol parameter will be stored in the Lustre config
 502       logs, letting the servers retrieve the information after a restart.
 503       </para>
 504     </section>
 505     <section xml:id="managingSecurity.sepol.client" remap="h3">
 506       <title><indexterm><primary>selinux policy check</primary><secondary>
 507         sending client</secondary></indexterm>Sending SELinux Status Info from
 508         Clients</title>
 509       <para>In order for Lustre clients to send their SELinux status
 510         information, in case SELinux is enabled locally, the
 511         <literal>send_sepol</literal> ptlrpc kernel module's parameter has to be
 512         set to a non-zero value. <literal>send_sepol</literal> accepts various
 513         values:</para>
 514         <itemizedlist>
 515             <listitem>
 516               <para>0: do not send SELinux policy info;</para>
 517             </listitem>
 518             <listitem>
 519               <para>-1: fetch SELinux policy info for every request;</para>
 520             </listitem>
 521             <listitem>
 522               <para>N > 0: only fetch SELinux policy info every N seconds. Use
 523                 <literal>N = 2^31-1</literal> to have SELinux policy info
 524                 fetched only at mount time.</para>
 525             </listitem>
 526         </itemizedlist>
 527         <para>Clients that are part of a nodemap on which
 528           <literal>sepol</literal> is defined must send SELinux status info.
 529           And the SELinux policy they enforce must match the representation
 530           stored into the nodemap. Otherwise they will be denied access to the
 531           Lustre file system.</para>
 532     </section>
 533   </section>
 534   <section xml:id="managingSecurity.clientencryption" condition='l2E'>
 535     <title><indexterm><primary>Client-side encryption</primary></indexterm>
 536     Encrypting files and directories</title>
 537     <para>The purpose that client-side encryption wants to serve is to be able
 538       to provide a special directory for each user, to safely store sensitive
 539       files. The goals are to protect data in transit between clients and
 540       servers, and protect data at rest.</para>
 541     <para>This feature is implemented directly at the Lustre client level.
 542       Lustre client-side encryption relies on kernel <literal>fscrypt</literal>.
 543       <literal>fscrypt</literal> is a library which filesystems can hook into to
 544       support transparent encryption of files and directories. As a consequence,
 545       the key points described below are extracted from
 546     <literal>fscrypt</literal> documentation.</para>
 547     <para>For full details, please refer to documentation available with the
 548       Lustre sources, under the
 549       <literal>Documentation/client_side_encryption</literal> directory.
 550     </para>
 551     <note><para>The client-side encryption feature is available natively on
 552       Lustre clients running a Linux distribution with at least kernel 5.4. It
 553       is also available thanks to an additional kernel library provided by
 554       Lustre, on clients that run a Linux distribution with basic support for
 555       encryption, including:</para>
 556      <itemizedlist>
 557        <listitem><para>CentOS/RHEL 8.1 and later;</para></listitem>
 558        <listitem><para>Ubuntu 18.04 and later;</para></listitem>
 559        <listitem><para>SLES 15 SP2 and later.</para></listitem>
 560      </itemizedlist>
 561     </note>
 562     <section xml:id="managingSecurity.clientencryption.semantics" remap="h3">
 563       <title><indexterm><primary>encryption access semantics</primary>
 564       </indexterm>Client-side encryption access semantics</title>
 565       <para>Only Lustre clients need access to encryption master keys. Keys are
 566         added to the filesystem-level encryption keyring on the Lustre client.
 567         <itemizedlist>
 568           <listitem>
 569             <para><emphasis role="bold">With the key</emphasis></para>
 570             <para>With the encryption key, encrypted regular files, directories,
 571               and symlinks behave very similarly to their unencrypted
 572               counterparts --- after all, the encryption is intended to be
 573               transparent. However, astute users may notice some differences in
 574               behavior:</para>
 575             <itemizedlist>
 576               <listitem>
 577                 <para>Unencrypted files, or files encrypted with a different
 578                   encryption policy (i.e. different key, modes, or flags),
 579                   cannot be renamed or linked into an encrypted directory.
 580                   However, encrypted files can be renamed within an encrypted
 581                   directory, or into an unencrypted directory.</para>
 582                 <note><para>"moving" an unencrypted file into an encrypted
 583                   directory, e.g. with the <literal>mv</literal> program, is
 584                   implemented in userspace by a copy followed by a delete.  Be
 585                   aware the original unencrypted data may remain recoverable
 586                   from free space on the disk; it is best to keep all files
 587                   encrypted from the very beginning.</para></note>
 588               </listitem>
 589               <listitem><para>On Lustre, Direct I/O is supported for encrypted
 590                 files.</para>
 591               </listitem>
 592               <listitem><para>The <literal>fallocate()</literal> operations
 593                 <literal>FALLOC_FL_COLLAPSE_RANGE</literal>,
 594                 <literal>FALLOC_FL_INSERT_RANGE</literal>, and
 595                 <literal>FALLOC_FL_ZERO_RANGE</literal> are not
 596                 supported on encrypted files and will fail with
 597                 <literal>EOPNOTSUPP</literal>.
 598                 </para>
 599               </listitem>
 600               <listitem><para>DAX (Direct Access) is not supported on encrypted
 601                 files.</para>
 602               </listitem>
 603               <listitem><para><literal>mmap</literal> is supported.  This is
 604                 possible because the pagecache for an encrypted file contains
 605                 the plaintext, not the ciphertext.</para>
 606               </listitem>
 607             </itemizedlist>
 608           </listitem>
 609           <listitem>
 610             <para><emphasis role="bold">Without the key</emphasis></para>
 611             <para>Some filesystem operations may be performed on encrypted
 612               regular files, directories, and symlinks even before their
 613               encryption key has been added, or after their encryption key has
 614               been removed:</para>
 615             <itemizedlist>
 616               <listitem>
 617                 <para>File metadata may be read, e.g. using
 618                   <literal>stat()</literal>.</para>
 619               </listitem>
 620               <listitem>
 621                 <para>Directories may be listed, and the whole namespace tree
 622                   may be walked through.
 623                 </para>
 624               </listitem>
 625               <listitem>
 626                 <para>Files may be deleted.  That is, nondirectory files may be
 627                   deleted with <literal>unlink()</literal> as usual, and empty
 628                   directories may be deleted with <literal>rmdir()</literal> as
 629                   usual. Therefore, <literal>rm</literal> and
 630                   <literal>rm -r</literal> will work as expected.</para>
 631               </listitem>
 632               <listitem>
 633                 <para>Symlink targets may be read and followed, but they will
 634                   be presented in encrypted form, similar to filenames in
 635                   directories. Hence, they are unlikely to point to anywhere
 636                   useful.</para>
 637               </listitem>
 638             </itemizedlist>
 639             <para>Without the key, regular files cannot be opened or truncated.
 640               Attempts to do so will fail with <literal>ENOKEY</literal>. This
 641               implies that any regular file operations that require a file
 642               descriptor, such as <literal>read()</literal>,
 643               <literal>write()</literal>, <literal>mmap()</literal>,
 644               <literal>fallocate()</literal>, and <literal>ioctl()</literal>,
 645               are also forbidden.</para>
 646             <para>Also without the key, files of any type (including
 647               directories) cannot be created or linked into an encrypted
 648               directory, nor can a name in an encrypted directory be the source
 649               or target of a rename, nor can an <literal>O_TMPFILE</literal>
 650               temporary file be created in an encrypted directory. All such
 651               operations will fail with <literal>ENOKEY</literal>.</para>
 652             <para>It is not currently possible to backup and restore encrypted
 653               files without the encryption key.  This would require special
 654               APIs which have not yet been implemented.</para>
 655           </listitem>
 656           <listitem>
 657             <para><emphasis role="bold">Encryption policy enforcement
 658               </emphasis></para>
 659             <para>After an encryption policy has been set on a directory, all
 660              regular files, directories, and symbolic links created in that
 661              directory (recursively) will inherit that encryption policy.
 662              Special files --- that is, named pipes, device nodes, and UNIX
 663              domain sockets --- will not be encrypted.</para>
 664            <para>Except for those special files, it is forbidden to have
 665              unencrypted files, or files encrypted with a different encryption
 666              policy, in an encrypted directory tree.</para>
 667            </listitem>
 668          </itemizedlist>
 669       </para>
 670     </section>
 671     <section xml:id="managingSecurity.clientencryption.keyhierarchy" remap="h3">
 672       <title><indexterm><primary>encryption key hierarchy</primary>
 673       </indexterm>Client-side encryption key hierarchy</title>
 674       <para>Each encrypted directory tree is protected by a master key.</para>
 675       <para>To "unlock" an encrypted directory tree, userspace must provide the
 676        appropriate master key.  There can be any number of master keys, each
 677        of which protects any number of directory trees on any number of
 678        filesystems.</para>
 679     </section>
 680     <section xml:id="managingSecurity.clientencryption.modes" remap="h3">
 681       <title><indexterm><primary>encryption modes usage</primary>
 682       </indexterm>Client-side encryption modes and usage</title>
 683       <para><literal>fscrypt</literal> allows one encryption mode to be
 684        specified for file contents and one encryption mode to be specified for
 685        filenames. Different directory trees are permitted to use different
 686        encryption modes. Currently, the following pairs of encryption modes are
 687        supported:</para>
 688        <itemizedlist>
 689          <listitem>
 690            <para>AES-256-XTS for contents and AES-256-CTS-CBC for filenames
 691            </para>
 692          </listitem>
 693          <listitem>
 694            <para>AES-128-CBC for contents and AES-128-CTS-CBC for filenames
 695            </para>
 696          </listitem>
 697        </itemizedlist>
 698        <para>If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
 699       </para>
 700       <warning><para>In Lustre 2.14, client-side encryption only supports
 701        content encryption, and not filename encryption. As a consequence, only
 702        content encryption mode will be taken into account, and filename
 703        encryption mode will be ignored to leave filenames in clear text.</para>
 704       </warning>
 705     </section>
 706     <section xml:id="managingSecurity.clientencryption.threatmodel" remap="h3">
 707       <title><indexterm><primary>encryption threat model</primary>
 708       </indexterm>Client-side encryption threat model</title>
 709       <itemizedlist>
 710         <listitem>
 711           <para><emphasis role="bold">Offline attacks</emphasis></para>
 712           <para>For the Lustre case, block devices are Lustre targets attached
 713             to the Lustre servers. Manipulating the filesystem offline means
 714             accessing the filesystem on these targets while Lustre is offline.
 715           </para>
 716           <para>Provided that a strong encryption key is chosen,
 717             <literal>fscrypt</literal> protects the confidentiality of file
 718             contents in the event of a single point-in-time permanent offline
 719             compromise of the block device content.
 720             Lustre client-side encryption does not protect the confidentiality
 721             of metadata, e.g. file names, file sizes, file permissions, file
 722             timestamps, and extended attributes.  Also, the existence and
 723             location of holes (unallocated blocks which logically contain all
 724             zeroes) in files is not protected.</para>
 725         </listitem>
 726         <listitem>
 727           <para><emphasis role="bold">Online attacks</emphasis></para>
 728           <itemizedlist>
 729             <listitem>
 730               <para>On Lustre client</para>
 731               <para>After an encryption key has been added,
 732                 <literal>fscrypt</literal> does not hide the plaintext file
 733                 contents or filenames from other users on the same node.
 734                 Instead, existing access control mechanisms such as file mode
 735                 bits, POSIX ACLs, LSMs, or namespaces should be used for this
 736                 purpose.</para>
 737               <para>For the Lustre case, it means plaintext file contents or
 738                 filenames are not hidden from other users on the same Lustre
 739                 client.</para>
 740               <para>An attacker who compromises the system enough to read from
 741                 arbitrary memory, e.g. by exploiting a kernel security
 742                 vulnerability, can compromise all encryption keys that are
 743                 currently in use.
 744                 However, <literal>fscrypt</literal> allows encryption keys to
 745                 be removed from the kernel, which may protect them from later
 746                 compromise. Key removal can be carried out by non-root users.
 747                 In more detail, the key removal will wipe the master encryption
 748                 key from kernel memory.  Moreover, it will try to evict all
 749                 cached inodes which had been "unlocked" using the key, thereby
 750                 wiping their per-file keys and making them once again appear
 751                 "locked", i.e. in ciphertext or encrypted form.</para>
 752             </listitem>
 753             <listitem>
 754               <para>On Lustre server</para>
 755               <para>An attacker on a Lustre server who compromises the system
 756                 enough to read arbitrary memory, e.g. by exploiting a kernel
 757                 security vulnerability, cannot compromise Lustre files content.
 758                 Indeed, encryption keys are not forwarded to the Lustre servers,
 759                 and servers do not carry out decryption or encryption.
 760                 Moreover, bulk RPCs received by servers contain encrypted data,
 761                 which is written as-is to the underlying filesystem.</para>
 762             </listitem>
 763           </itemizedlist>
 764         </listitem>
 765       </itemizedlist>
 766     </section>
 767     <section xml:id="managingSecurity.clientencryption.fscrypt" remap="h3">
 768       <title><indexterm><primary>encryption fscrypt policy</primary>
 769       </indexterm>Manage encryption on directories</title>
 770       <para>By default, Lustre client-side encryption is enabled, letting users
 771        define encryption policies on a per-directory basis.</para>
 772       <note><para>Administrators can decide to prevent a Lustre client
 773        mount-point from using encryption by specifying the
 774        <literal>noencrypt</literal> client mount option. This can be also
 775        enforced from server side thanks to the
 776        <literal>forbid_encryption</literal> property on nodemaps. See
 777        <xref linkend="alteringproperties"/> for how to manage nodemaps.
 778       </para></note>
 779       <para><literal>fscrypt</literal> userspace tool can be used to manage
 780        encryption policies. See https://github.com/google/fscrypt for
 781        comprehensive explanations. Below are examples on how to use this tool
 782        with Lustre. If not told otherwise, commands must be run on Lustre
 783        client side.</para>
 784       <itemizedlist>
 785         <listitem>
 786           <para>Two preliminary steps are required before actually deciding
 787             which directories to encrypt, and this is the only
 788             functionality which requires root privileges. Administrator has to
 789             run:</para>
 790           <screen># fscrypt setup
 791 Customizing passphrase hashing difficulty for this system...
 792 Created global config file at "/etc/fscrypt.conf".
 793 Metadata directories created at "/.fscrypt".</screen>
 794           <para>This first command has to be run on all clients that want to use
 795             encryption, as it sets up global fscrypt parameters outside of
 796             Lustre.</para>
 797           <screen># fscrypt setup /mnt/lustre
 798 Metadata directories created at "/mnt/lustre/.fscrypt"</screen>
 799           <para>This second command has to be run on just one Lustre
 800             client.</para>
 801           <note><para>The file <literal>/etc/fscrypt.conf</literal> can be
 802             edited. It is strongly recommended to set
 803             <literal>policy_version</literal> to 2, so that
 804             <literal>fscrypt</literal> wipes files from memory when the
 805             encryption key is removed.</para></note>
 806         </listitem>
 807         <listitem>
 808           <para>Now a regular user is able to select a directory to
 809             encrypt:</para>
 810             <screen>$ fscrypt encrypt /mnt/lustre/vault
 811 The following protector sources are available:
 812 1 - Your login passphrase (pam_passphrase)
 813 2 - A custom passphrase (custom_passphrase)
 814 3 - A raw 256-bit key (raw_key)
 815 Enter the source number for the new protector [2 - custom_passphrase]: 2
 816 Enter a name for the new protector: shield
 817 Enter custom passphrase for protector "shield":
 818 Confirm passphrase:
 819 "/mnt/lustre/vault" is now encrypted, unlocked, and ready for use.</screen>
 820           <para>Starting from here, all files and directories created under
 821             <literal>/mnt/lustre/vault</literal> will be encrypted, according
 822             to the policy defined at the previsous step.</para>
 823           <note><para>The encryption policy is inherited by all subdirectories.
 824             It is not possible to change the policy for a subdirectory.</para>
 825           </note>
 826         </listitem>
 827         <listitem>
 828           <para>Another user can decide to encrypt a different directory with
 829             its own protector:</para>
 830             <screen>$ fscrypt encrypt /mnt/lustre/private
 831 Should we create a new protector? [y/N] Y
 832 The following protector sources are available:
 833 1 - Your login passphrase (pam_passphrase)
 834 2 - A custom passphrase (custom_passphrase)
 835 3 - A raw 256-bit key (raw_key)
 836 Enter the source number for the new protector [2 - custom_passphrase]: 2
 837 Enter a name for the new protector: armor
 838 Enter custom passphrase for protector "armor":
 839 Confirm passphrase:
 840 "/mnt/lustre/private" is now encrypted, unlocked, and ready for use.</screen>
 841         </listitem>
 842         <listitem>
 843           <para>Users can decide to lock an encrypted directory at any
 844             time:</para>
 845           <screen>$ fscrypt lock /mnt/lustre/vault
 846 "/mnt/lustre/vault" is now locked.</screen>
 847           <para>This action prevents access to encrypted content, and by
 848             removing the key from memory, it also wipes files from memory if
 849             they are not still open.</para>
 850         </listitem>
 851         <listitem>
 852           <para>Users regain access to the encrypted directory with the command:
 853           </para>
 854           <screen>$ fscrypt unlock /mnt/lustre/vault
 855 Enter custom passphrase for protector "shield":
 856 "/mnt/lustre/vault" is now unlocked and ready for use.</screen>
 857         </listitem>
 858         <listitem>
 859           <para>Actually, <literal>fscrypt</literal> does not give direct access
 860             to master keys, but to protectors that are used to encrypt them.
 861             This mechanism gives the ability to change a passphrase:</para>
 862             <screen>$ fscrypt status /mnt/lustre
 863 lustre filesystem "/mnt/lustre" has 2 protectors and 2 policies
 864
 865 PROTECTOR         LINKED  DESCRIPTION
 866 deacab807bf0e788  No      custom protector "shield"
 867 e691ae7a1990fc2a  No      custom protector "armor"
 868
 869 POLICY                            UNLOCKED  PROTECTORS
 870 52b2b5aff0e59d8e0d58f962e715862e  No        deacab807bf0e788
 871 374e8944e4294b527e50363d86fc9411  No        e691ae7a1990fc2a
 872
 873 $ fscrypt metadata change-passphrase --protector=/mnt/lustre:deacab807bf0e788
 874 Enter old custom passphrase for protector "shield":
 875 Enter new custom passphrase for protector "shield":
 876 Confirm passphrase:
 877 Passphrase for protector deacab807bf0e788 successfully changed.</screen>
 878           <para>It makes also possible to have multiple protectors for the same
 879             policy. This is really useful when several users share an encrypted
 880             directory, because it avoids the need to share any secret between
 881             them.</para>
 882            <screen>$ fscrypt status /mnt/lustre/vault
 883 "/mnt/lustre/vault" is encrypted with fscrypt.
 884
 885 Policy:   52b2b5aff0e59d8e0d58f962e715862e
 886 Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
 887 Unlocked: No
 888
 889 Protected with 1 protector:
 890 PROTECTOR         LINKED  DESCRIPTION
 891 deacab807bf0e788  No      custom protector "shield"
 892
 893 $ fscrypt metadata create protector /mnt/lustre
 894 Create new protector on "/mnt/lustre" [Y/n] Y
 895 The following protector sources are available:
 896 1 - Your login passphrase (pam_passphrase)
 897 2 - A custom passphrase (custom_passphrase)
 898 3 - A raw 256-bit key (raw_key)
 899 Enter the source number for the new protector [2 - custom_passphrase]: 2
 900 Enter a name for the new protector: bunker
 901 Enter custom passphrase for protector "bunker":
 902 Confirm passphrase:
 903 Protector f3cc1b5cf9b8f41c created on filesystem "/mnt/lustre".
 904
 905 $ fscrypt metadata add-protector-to-policy
 906           --protector=/mnt/lustre:f3cc1b5cf9b8f41c
 907           --policy=/mnt/lustre:52b2b5aff0e59d8e0d58f962e715862e
 908 WARNING: All files using this policy will be accessible with this protector!!
 909 Protect policy 52b2b5aff0e59d8e0d58f962e715862e with protector f3cc1b5cf9b8f41c? [Y/n] Y
 910 Enter custom passphrase for protector "bunker":
 911 Enter custom passphrase for protector "shield":
 912 Protector f3cc1b5cf9b8f41c now protecting policy 52b2b5aff0e59d8e0d58f962e715862e.
 913
 914 $ fscrypt status /mnt/lustre/vault
 915 "/mnt/lustre/vault" is encrypted with fscrypt.
 916
 917 Policy:   52b2b5aff0e59d8e0d58f962e715862e
 918 Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
 919 Unlocked: No
 920
 921 Protected with 2 protectors:
 922 PROTECTOR         LINKED  DESCRIPTION
 923 deacab807bf0e788  No      custom protector "shield"
 924 f3cc1b5cf9b8f41c  No      custom protector "bunker"</screen>
 925         </listitem>
 926       </itemizedlist>
 927     </section>
 928   </section>
 929 </chapter>
 930 <!--
 931   vim:expandtab:shiftwidth=2:tabstop=8:
 932   -->