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     <listitem>
  25       <para><xref linkend="managingSecurity.kerberos"/></para>
  26     </listitem>
  27   </itemizedlist>
  28   <section xml:id="managingSecurity.acl">
  29     <title><indexterm><primary>Access Control List (ACL)</primary></indexterm>
  30     Using ACLs</title>
  31     <para>An access control list (ACL), is a set of data that informs an
  32       operating system about permissions or access rights that each user or
  33       group has to specific system objects, such as directories or files. Each
  34       object has a unique security attribute that identifies users who have
  35       access to it. The ACL lists each object and user access privileges such as
  36       read, write or execute.</para>
  37     <section xml:id="managingSecurity.acl.howItWorks" remap="h3">
  38       <title><indexterm><primary>Access Control List (ACL)</primary><secondary>
  39         how they work</secondary></indexterm>How ACLs Work</title>
  40       <para>Implementing ACLs varies between operating systems. Systems that
  41         support the Portable Operating System Interface (POSIX) family of
  42         standards share a simple yet powerful file system permission model,
  43         which should be well-known to the Linux/UNIX administrator. ACLs add
  44         finer-grained permissions to this model, allowing for more complicated
  45         permission schemes. For a detailed explanation of ACLs on a Linux
  46         operating system, refer to the SUSE Labs article
  47         <link xl:href="https://www.usenix.org/legacyurl/posix-access-control-lists-linux">
  48           Posix Access Control Lists on Linux</link>.</para>
  49       <para>We have implemented ACLs according to this model. The Lustre
  50         software works with the standard Linux ACL tools, setfacl, getfacl, and
  51         the historical chacl, normally installed with the ACL package.</para>
  52       <note>
  53         <para>ACL support is a system-range feature, meaning that all clients
  54           have ACL enabled or not. You cannot specify which clients should
  55           enable ACL.</para>
  56       </note>
  57     </section>
  58     <section xml:id="managingSecurity.acl.using" remap="h3">
  59       <title><indexterm>
  60         <primary>Access Control List (ACL)</primary>
  61         <secondary>using</secondary>
  62       </indexterm>Using ACLs with the Lustre Software</title>
  63       <para>POSIX Access Control Lists (ACLs) can be used with the Lustre
  64         software. An ACL consists of file entries representing permissions based
  65         on standard POSIX file system object permissions that define three
  66         classes of user (owner, group and other). Each class is associated with
  67         a set of permissions [read (r), write (w) and execute (x)].</para>
  68       <itemizedlist>
  69         <listitem>
  70           <para>Owner class permissions define access privileges of the file
  71             owner.</para>
  72         </listitem>
  73         <listitem>
  74           <para>Group class permissions define access privileges of the owning
  75             group.</para>
  76         </listitem>
  77         <listitem>
  78           <para>Other class permissions define access privileges of all users
  79             not in the owner or group class.</para>
  80         </listitem>
  81       </itemizedlist>
  82       <para>The <literal>ls -l</literal> command displays the owner, group, and
  83         other class permissions in the first column of its output (for example,
  84         <literal>-rw-r- --</literal> for a regular file with read and write
  85         access for the owner class, read access for the group class, and no
  86         access for others).</para>
  87       <para>Minimal ACLs have three entries. Extended ACLs have more than the
  88         three entries. Extended ACLs also contain a mask entry and may contain
  89         any number of named user and named group entries.</para>
  90       <para>The MDS needs to be configured to enable ACLs. Use
  91         <literal>--mountfsoptions</literal> to enable ACLs when creating your
  92         configuration:</para>
  93       <screen>$ mkfs.lustre --fsname spfs --mountfsoptions=acl --mdt -mgs /dev/sda</screen>
  94       <para>Alternately, you can enable ACLs at run time by using the
  95         <literal>--acl</literal> option with <literal>mkfs.lustre</literal>:
  96       </para>
  97       <screen>$ mount -t lustre -o acl /dev/sda /mnt/mdt</screen>
  98       <para>To check ACLs on the MDS:</para>
  99       <screen>$ lctl get_param -n mdc.home-MDT0000-mdc-*.connect_flags | grep acl acl</screen>
 100       <para>To mount the client with no ACLs:</para>
 101       <screen>$ mount -t lustre -o noacl ibmds2@o2ib:/home /home</screen>
 102       <para>ACLs are enabled in a Lustre file system on a system-wide basis;
 103         either all clients enable ACLs or none do. Activating ACLs is controlled
 104         by MDS mount options <literal>acl</literal> / <literal>noacl</literal>
 105         (enable/disable ACLs). Client-side mount options acl/noacl are ignored.
 106         You do not need to change the client configuration, and the
 107         &apos;acl&apos; string will not appear in the client /etc/mtab. The
 108         client acl mount option is no longer needed. If a client is mounted with
 109         that option, then this message appears in the MDS syslog:</para>
 110       <screen>...MDS requires ACL support but client does not</screen>
 111       <para>The message is harmless but indicates a configuration issue, which
 112         should be corrected.</para>
 113       <para>If ACLs are not enabled on the MDS, then any attempts to reference
 114         an ACL on a client return an Operation not supported error.</para>
 115     </section>
 116     <section xml:id="managingSecurity.acl.examples" remap="h3">
 117         <title><indexterm>
 118           <primary>Access Control List (ACL)</primary>
 119           <secondary>examples</secondary>
 120         </indexterm>Examples</title>
 121       <para>These examples are taken directly from the POSIX paper referenced
 122         above. ACLs on a Lustre file system work exactly like ACLs on any Linux
 123         file system. They are manipulated with the standard tools in the
 124         standard manner. Below, we create a directory and allow a specific user
 125         access.</para>
 126       <screen>[root@client lustre]# umask 027
 127 [root@client lustre]# mkdir rain
 128 [root@client lustre]# ls -ld rain
 129 drwxr-x---  2 root root 4096 Feb 20 06:50 rain
 130 [root@client lustre]# getfacl rain
 131 # file: rain
 132 # owner: root
 133 # group: root
 134 user::rwx
 135 group::r-x
 136 other::---
 137
 138 [root@client lustre]# setfacl -m user:chirag:rwx rain
 139 [root@client lustre]# ls -ld rain
 140 drwxrwx---+ 2 root root 4096 Feb 20 06:50 rain
 141 [root@client lustre]# getfacl --omit-header rain
 142 user::rwx
 143 user:chirag:rwx
 144 group::r-x
 145 mask::rwx
 146 other::---</screen>
 147     </section>
 148   </section>
 149   <section xml:id="managingSecurity.root_squash">
 150     <title><indexterm>
 151       <primary>root squash</primary>
 152     </indexterm>Using Root Squash</title>
 153     <para>Root squash is a security feature which restricts super-user access
 154       rights to a Lustre file system. Without the root squash feature enabled,
 155       Lustre file system users on untrusted clients could access or modify files
 156       owned by root on the file system, including deleting them. Using the root
 157       squash feature restricts file access/modifications as the root user to
 158       only the specified clients. Note, however, that this does
 159       <emphasis>not</emphasis> prevent users on insecure clients from accessing
 160       files owned by <emphasis>other</emphasis> users.</para>
 161     <para>The root squash feature works by re-mapping the user ID (UID) and
 162       group ID (GID) of the root user to a UID and GID specified by the system
 163       administrator, via the Lustre configuration management server (MGS). The
 164       root squash feature also enables the Lustre file system administrator to
 165       specify a set of client for which UID/GID re-mapping does not apply.
 166     </para>
 167     <note><para>Nodemaps (<xref linkend="lustrenodemap.title" />) are an
 168       alternative to root squash, since it also allows root squash on a per-client
 169       basis.  With UID maps, the clients can even have a local root UID without
 170       actually having root access to the filesystem itself.</para></note>
 171     <section xml:id="managingSecurity.root_squash.config" remap="h3">
 172       <title><indexterm>
 173         <primary>root squash</primary>
 174         <secondary>configuring</secondary>
 175       </indexterm>Configuring Root Squash</title>
 176       <para>Root squash functionality is managed by two configuration
 177         parameters, <literal>root_squash</literal> and
 178         <literal>nosquash_nids</literal>.</para>
 179       <itemizedlist>
 180         <listitem>
 181           <para>The <literal>root_squash</literal> parameter specifies the UID
 182             and GID with which the root user accesses the Lustre file system.
 183           </para>
 184         </listitem>
 185         <listitem>
 186           <para>The <literal>nosquash_nids</literal> parameter specifies the set
 187             of clients to which root squash does not apply. LNet NID range
 188             syntax is used for this parameter (see the NID range syntax rules
 189             described in <xref linkend="managingSecurity.root_squash"/>). For
 190             example:</para>
 191         </listitem>
 192       </itemizedlist>
 193       <screen>nosquash_nids=172.16.245.[0-255/2]@tcp</screen>
 194       <para>In this example, root squash does not apply to TCP clients on subnet
 195         172.16.245.0 that have an even number as the last component of their IP
 196         address.</para>
 197     </section>
 198     <section xml:id="managingSecurity.root_squash.tuning">
 199       <title><indexterm>
 200         <primary>root squash</primary><secondary>enabling</secondary>
 201       </indexterm>Enabling and Tuning Root Squash</title>
 202       <para>The default value for <literal>nosquash_nids</literal> is NULL,
 203         which means that root squashing applies to all clients. Setting the root
 204         squash UID and GID to 0 turns root squash off.</para>
 205       <para>Root squash parameters can be set when the MDT is created
 206         (<literal>mkfs.lustre --mdt</literal>). For example:</para>
 207       <screen>mds# mkfs.lustre --reformat --fsname=testfs --mdt --mgs \
 208        --param &quot;mdt.root_squash=500:501&quot; \
 209        --param &quot;mdt.nosquash_nids=&apos;0@elan1 192.168.1.[10,11]&apos;&quot; /dev/sda1</screen>
 210       <para>Root squash parameters can also be changed on an unmounted device
 211         with <literal>tunefs.lustre</literal>. For example:</para>
 212       <screen>tunefs.lustre --param &quot;mdt.root_squash=65534:65534&quot;  \
 213 --param &quot;mdt.nosquash_nids=192.168.0.13@tcp0&quot; /dev/sda1
 214 </screen>
 215       <para>Root squash parameters can also be changed with the
 216       <literal>lctl conf_param</literal> command. For example:</para>
 217       <screen>mgs# lctl conf_param testfs.mdt.root_squash=&quot;1000:101&quot;
 218 mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;*@tcp&quot;</screen>
 219       <para>To retrieve the current root squash parameter settings, the
 220       following <literal>lctl get_param</literal> commands can be used:</para>
 221       <screen>mgs# lctl get_param mdt.*.root_squash
 222 mgs# lctl get_param mdt.*.nosquash_nids</screen>
 223       <note>
 224         <para>When using the lctl conf_param command, keep in mind:</para>
 225         <itemizedlist>
 226           <listitem>
 227             <para><literal>lctl conf_param</literal> must be run on a live MGS
 228             </para>
 229           </listitem>
 230           <listitem>
 231             <para><literal>lctl conf_param</literal> causes the parameter to
 232               change on all MDSs</para>
 233           </listitem>
 234           <listitem>
 235             <para><literal>lctl conf_param</literal> is to be used once per a
 236               parameter</para>
 237           </listitem>
 238         </itemizedlist>
 239       </note>
 240       <para>The root squash settings can also be changed temporarily with
 241       <literal>lctl set_param</literal> or persistently with
 242       <literal>lctl set_param -P</literal>.  For example:</para>
 243       <screen>mgs# lctl set_param mdt.testfs-MDT0000.root_squash="1:0"
 244 mgs# lctl set_param -P mdt.testfs-MDT0000.root_squash="1:0"</screen>
 245       <para>The <literal>nosquash_nids</literal> list can be cleared with:</para>
 246       <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;NONE&quot;</screen>
 247       <para>- OR -</para>
 248       <screen>mgs# lctl conf_param testfs.mdt.nosquash_nids=&quot;clear&quot;</screen>
 249       <para>If the <literal>nosquash_nids</literal> value consists of several
 250         NID ranges (e.g. <literal>0@elan</literal>, <literal>1@elan1</literal>),
 251         the list of NID ranges must be quoted with single (&apos;) or double
 252         (&apos;&apos;) quotation marks. List elements must be separated with a
 253         space. For example:</para>
 254       <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=&apos;0@elan1 1@elan2&apos;&quot; /dev/sda1
 255 lctl conf_param testfs.mdt.nosquash_nids=&quot;24@elan 15@elan1&quot;</screen>
 256       <para>These are examples of incorrect syntax:</para>
 257       <screen>mds# mkfs.lustre ... --param &quot;mdt.nosquash_nids=0@elan1 1@elan2&quot; /dev/sda1
 258 lctl conf_param testfs.mdt.nosquash_nids=24@elan 15@elan1</screen>
 259       <para>To check root squash parameters, use the lctl get_param command:
 260       </para>
 261       <screen>mds# lctl get_param mdt.testfs-MDT0000.root_squash
 262 lctl get_param mdt.*.nosquash_nids</screen>
 263       <note>
 264         <para>An empty nosquash_nids list is reported as NONE.</para>
 265       </note>
 266     </section>
 267     <section xml:id="managingSecurity.root_squash.tips" remap="h3">
 268         <title><indexterm>
 269           <primary>root squash</primary>
 270           <secondary>tips</secondary>
 271         </indexterm>Tips on Using Root Squash</title>
 272       <para>Lustre configuration management limits root squash in several ways.
 273       </para>
 274       <itemizedlist>
 275         <listitem>
 276           <para>The <literal>lctl conf_param</literal> value overwrites the
 277             parameter&apos;s previous value. If the new value uses an incorrect
 278             syntax, then the system continues with the old parameters and the
 279             previously-correct value is lost on remount. That is, be careful
 280             doing root squash tuning.</para>
 281         </listitem>
 282         <listitem>
 283           <para><literal>mkfs.lustre</literal> and
 284             <literal>tunefs.lustre</literal> do not perform parameter syntax
 285             checking. If the root squash parameters are incorrect, they are
 286             ignored on mount and the default values are used instead.</para>
 287         </listitem>
 288         <listitem>
 289           <para>Root squash parameters are parsed with rigorous syntax checking.
 290             The root_squash parameter should be specified as
 291             <literal>&lt;decnum&gt;:&lt;decnum&gt;</literal>. The
 292             <literal>nosquash_nids</literal> parameter should follow LNet NID
 293             range list syntax.</para>
 294         </listitem>
 295       </itemizedlist>
 296       <para>LNet NID range syntax:</para>
 297       <screen>&lt;nidlist&gt;     :== &lt;nidrange&gt; [ &apos; &apos; &lt;nidrange&gt; ]
 298 &lt;nidrange&gt;   :== &lt;addrrange&gt; &apos;@&apos; &lt;net&gt;
 299 &lt;addrrange&gt;  :== &apos;*&apos; |
 300            &lt;ipaddr_range&gt; |
 301            &lt;numaddr_range&gt;
 302 &lt;ipaddr_range&gt;       :==
 303 &lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;.&lt;numaddr_range&gt;
 304 &lt;numaddr_range&gt;      :== &lt;number&gt; |
 305                    &lt;expr_list&gt;
 306 &lt;expr_list&gt;  :== &apos;[&apos; &lt;range_expr&gt; [ &apos;,&apos; &lt;range_expr&gt;] &apos;]&apos;
 307 &lt;range_expr&gt; :== &lt;number&gt; |
 308            &lt;number&gt; &apos;-&apos; &lt;number&gt; |
 309            &lt;number&gt; &apos;-&apos; &lt;number&gt; &apos;/&apos; &lt;number&gt;
 310 &lt;net&gt;        :== &lt;netname&gt; | &lt;netname&gt;&lt;number&gt;
 311 &lt;netname&gt;    :== &quot;lo&quot; | &quot;tcp&quot; | &quot;o2ib&quot;
 312            | &quot;ra&quot; | &quot;elan&quot;
 313 &lt;number&gt;     :== &lt;nonnegative decimal&gt; | &lt;hexadecimal&gt;</screen>
 314       <note>
 315         <para>For networks using numeric addresses (e.g. elan), the address
 316           range must be specified in the
 317           <literal>&lt;numaddr_range&gt;</literal> syntax. For networks using
 318           IP addresses, the address range must be in the
 319           <literal>&lt;ipaddr_range&gt;</literal>. For example, if elan is using
 320           numeric addresses, <literal>1.2.3.4@elan</literal> is incorrect.
 321         </para>
 322       </note>
 323     </section>
 324   </section>
 325   <section xml:id="managingSecurity.isolation">
 326     <title><indexterm><primary>Isolation</primary></indexterm>
 327     Isolating Clients to a Sub-directory Tree</title>
 328     <para>Isolation is the Lustre implementation of the generic concept of
 329       multi-tenancy, which aims at providing separated namespaces from a single
 330       filesystem. Lustre Isolation enables different populations of users on
 331       the same file system beyond normal Unix permissions/ACLs, even when users
 332       on the clients may have root access. Those tenants share the same file
 333       system, but they are isolated from each other: they cannot access or even
 334       see each other’s files, and are not aware that they are sharing common
 335       file system resources.</para>
 336     <para>Lustre Isolation leverages the Fileset feature
 337       (<xref linkend="SystemConfigurationUtilities.fileset" />)
 338       to mount only a subdirectory of the filesystem rather than the root
 339       directory.
 340       In order to achieve isolation, the subdirectory mount, which presents to
 341       tenants only their own fileset, has to be imposed to the clients. To that
 342       extent, we make use of the nodemap feature
 343       (<xref linkend="lustrenodemap.title" />). We group all clients used by a
 344       tenant under a common nodemap entry, and we assign to this nodemap entry
 345       the fileset to which the tenant is restricted.</para>
 346     <section xml:id="managingSecurity.isolation.clientid" remap="h3">
 347       <title><indexterm><primary>Isolation</primary><secondary>
 348         client identification</secondary></indexterm>Identifying Clients</title>
 349       <para>Enforcing multi-tenancy on Lustre relies on the ability to properly
 350         identify the client nodes used by a tenant, and trust those identities.
 351         This can be achieved by having physical hardware and/or network
 352         security, so that client nodes have well-known NIDs. It is also possible
 353         to make use of strong authentication with Kerberos or Shared-Secret Key
 354         (see <xref linkend="lustressk" />).
 355         Kerberos prevents NID spoofing, as every client needs its own
 356         credentials, based on its NID, in order to connect to the servers.
 357         Shared-Secret Key also prevents tenant impersonation, because keys
 358         can be linked to a specific nodemap. See
 359         <xref linkend="ssknodemaprole" /> for detailed explanations.
 360 </para>
 361     </section>
 362     <section xml:id="managingSecurity.isolation.configuring" remap="h3">
 363       <title><indexterm><primary>Isolation</primary><secondary>
 364         configuring</secondary></indexterm>Configuring Isolation</title>
 365       <para>Isolation on Lustre can be achieved by setting the
 366         <literal>fileset</literal> parameter on a nodemap entry. All clients
 367         belonging to this nodemap entry will automatically mount this fileset
 368         instead of the root directory. For example:</para>
 369       <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset '/dir1'</screen>
 370       <para>So all clients matching the <literal>tenant1</literal> nodemap will
 371         be automatically presented the fileset <literal>/dir1</literal> when
 372         mounting. This means these clients are doing an implicit subdirectory
 373         mount on the subdirectory <literal>/dir1</literal>.
 374       </para>
 375       <note>
 376         <para>
 377           If subdirectory defined as fileset does not exist on the file system,
 378           it will prevent any client belonging to the nodemap from mounting
 379           Lustre.
 380         </para>
 381       </note>
 382       <para>To delete the fileset parameter, just set it to an empty string:
 383       </para>
 384       <screen>mgs# lctl nodemap_set_fileset --name tenant1 --fileset ''</screen>
 385     </section>
 386     <section xml:id="managingSecurity.isolation.permanent" remap="h3">
 387       <title><indexterm><primary>Isolation</primary><secondary>
 388         making permanent</secondary></indexterm>Making Isolation Permanent
 389       </title>
 390       <para>In order to make isolation permanent, the fileset parameter on the
 391         nodemap has to be set with <literal>lctl set_param</literal> with the
 392       <literal>-P</literal> option.</para>
 393       <screen>mgs# lctl set_param nodemap.tenant1.fileset=/dir1
 394 mgs# lctl set_param -P nodemap.tenant1.fileset=/dir1</screen>
 395       <para>This way the fileset parameter will be stored in the Lustre config
 396       logs, letting the servers retrieve the information after a restart.
 397       </para>
 398     </section>
 399   </section>
 400   <section xml:id="managingSecurity.sepol" condition='l2D'>
 401     <title><indexterm><primary>selinux policy check</primary></indexterm>
 402     Checking SELinux Policy Enforced by Lustre Clients</title>
 403     <para>SELinux provides a mechanism in Linux for supporting Mandatory Access
 404       Control (MAC) policies. When a MAC policy is enforced, the operating
 405       system’s (OS) kernel defines application rights, firewalling applications
 406       from compromising the entire system. Regular users do not have the ability to
 407       override the policy.</para>
 408     <para>One purpose of SELinux is to protect the
 409       <emphasis role="bold">OS</emphasis> from privilege escalation. To that
 410       extent, SELinux defines confined and unconfined domains for processes and
 411       users. Each process, user, file is assigned a security context, and
 412       rules define the allowed operations by processes and users on files.
 413     </para>
 414     <para>Another purpose of SELinux can be to protect
 415       <emphasis role="bold">data</emphasis> sensitivity, thanks to Multi-Level
 416       Security (MLS). MLS works on top of SELinux, by defining the concept of
 417       security levels in addition to domains. Each process, user and file is
 418       assigned a security level, and the model states that processes and users
 419       can read the same or lower security level, but can only write to their own
 420       or higher security level.
 421     </para>
 422     <para>From a file system perspective, the security context of files must be
 423       stored permanently. Lustre makes use of the
 424       <literal>security.selinux</literal> extended attributes on files to hold
 425       this information. Lustre supports SELinux on the client side. All you have
 426       to do to have MAC and MLS on Lustre is to enforce the appropriate SELinux
 427       policy (as provided by the Linux distribution) on all Lustre clients. No
 428       SELinux is required on Lustre servers.
 429     </para>
 430     <para>Because Lustre is a distributed file system, the specificity when
 431       using MLS is that Lustre really needs to make sure data is always accessed
 432       by nodes with the SELinux MLS policy properly enforced. Otherwise, data is
 433       not protected. This means Lustre has to check that SELinux is properly
 434       enforced on client side, with the right, unaltered policy. And if SELinux
 435       is not enforced as expected on a client, the server denies its access to
 436       Lustre.
 437     </para>
 438     <section xml:id="managingSecurity.sepol.determining" remap="h3">
 439       <title><indexterm><primary>selinux policy check</primary><secondary>
 440         determining</secondary></indexterm>Determining SELinux Policy Info
 441       </title>
 442       <para>A string that represents the SELinux Status info will be used by
 443         servers as a reference, to check if clients are enforcing SELinux
 444         properly. This reference string can be obtained on a client node known
 445         to enforce the right SELinux policy, by calling the
 446         <literal>l_getsepol</literal> command line utility:</para>
 447         <screen>client# l_getsepol
 448 SELinux status info: 1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</screen>
 449         <para>The string describing the SELinux policy has the following
 450           syntax:</para>
 451         <para><literal>mode:name:version:hash</literal></para>
 452         <para>where:</para>
 453           <itemizedlist>
 454             <listitem>
 455               <para><literal>mode</literal> is a digit telling if SELinux is in
 456                 Permissive mode (0) or Enforcing mode (1)</para>
 457             </listitem>
 458             <listitem>
 459               <para><literal>name</literal> is the name of the SELinux policy
 460               </para>
 461             </listitem>
 462             <listitem>
 463               <para><literal>version</literal> is the version of the SELinux
 464               policy</para>
 465             </listitem>
 466             <listitem>
 467               <para><literal>hash</literal> is the computed hash of the binary
 468                 representation of the policy, as exported in
 469                 /etc/selinux/<literal>name</literal>/policy/policy.
 470                 <literal>version</literal></para>
 471             </listitem>
 472           </itemizedlist>
 473     </section>
 474     <section xml:id="managingSecurity.sepol.configuring" remap="h3">
 475       <title><indexterm><primary>selinux policy check</primary><secondary>
 476         enforcing</secondary></indexterm>Enforcing SELinux Policy Check</title>
 477       <para>SELinux policy check can be enforced by setting the
 478         <literal>sepol</literal> parameter on a nodemap entry. All clients
 479         belonging to this nodemap entry must enforce the SELinux policy
 480         described by this parameter, otherwise they are denied access to the
 481         Lustre file system. For example:</para>
 482       <screen>mgs# lctl nodemap_set_sepol --name restricted
 483      --sepol '1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f'</screen>
 484       <para>So all clients matching the <literal>restricted</literal> nodemap
 485         must enforce the SELinux policy which description matches
 486         <literal>1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</literal>.
 487         If not, they will get Permission Denied when trying to mount or access
 488         files on the Lustre file system.</para>
 489       <para>To delete the <literal>sepol</literal> parameter, just set it to an
 490         empty string:</para>
 491       <screen>mgs# lctl nodemap_set_sepol --name restricted --sepol ''</screen>
 492       <para>See <xref linkend="lustrenodemap.title" /> for more details about
 493         the Nodemap feature.</para>
 494     </section>
 495     <section xml:id="managingSecurity.sepol.permanent" remap="h3">
 496       <title><indexterm><primary>selinux policy check</primary><secondary>
 497         making permanent</secondary></indexterm>Making SELinux Policy Check
 498         Permanent</title>
 499       <para>In order to make SELinux Policy check permanent, the sepol parameter
 500         on the nodemap has to be set with <literal>lctl set_param</literal> with
 501         the <literal>-P</literal> option.</para>
 502       <screen>mgs# lctl set_param nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f
 503 mgs# lctl set_param -P nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58cccaaa2ca63641ed6e21b0a887dc21a684f508b78f</screen>
 504       <para>This way the sepol parameter will be stored in the Lustre config
 505       logs, letting the servers retrieve the information after a restart.
 506       </para>
 507     </section>
 508     <section xml:id="managingSecurity.sepol.client" remap="h3">
 509       <title><indexterm><primary>selinux policy check</primary><secondary>
 510         sending client</secondary></indexterm>Sending SELinux Status Info from
 511         Clients</title>
 512       <para>In order for Lustre clients to send their SELinux status
 513         information, in case SELinux is enabled locally, the
 514         <literal>send_sepol</literal> ptlrpc kernel module's parameter has to be
 515         set to a non-zero value. <literal>send_sepol</literal> accepts various
 516         values:</para>
 517         <itemizedlist>
 518             <listitem>
 519               <para>0: do not send SELinux policy info;</para>
 520             </listitem>
 521             <listitem>
 522               <para>-1: fetch SELinux policy info for every request;</para>
 523             </listitem>
 524             <listitem>
 525               <para>N > 0: only fetch SELinux policy info every N seconds. Use
 526                 <literal>N = 2^31-1</literal> to have SELinux policy info
 527                 fetched only at mount time.</para>
 528             </listitem>
 529         </itemizedlist>
 530         <para>Clients that are part of a nodemap on which
 531           <literal>sepol</literal> is defined must send SELinux status info.
 532           And the SELinux policy they enforce must match the representation
 533           stored into the nodemap. Otherwise they will be denied access to the
 534           Lustre file system.</para>
 535     </section>
 536   </section>
 537   <section xml:id="managingSecurity.clientencryption" condition='l2E'>
 538     <title><indexterm><primary>Client-side encryption</primary></indexterm>
 539     Encrypting files and directories</title>
 540     <para>The purpose that client-side encryption wants to serve is to be able
 541       to provide a special directory for each user, to safely store sensitive
 542       files. The goals are to protect data in transit between clients and
 543       servers, and protect data at rest.</para>
 544     <para>This feature is implemented directly at the Lustre client level.
 545       Lustre client-side encryption relies on kernel <literal>fscrypt</literal>.
 546       <literal>fscrypt</literal> is a library which filesystems can hook into to
 547       support transparent encryption of files and directories. As a consequence,
 548       the key points described below are extracted from
 549     <literal>fscrypt</literal> documentation.</para>
 550     <para>For full details, please refer to documentation available with the
 551       Lustre sources, under the
 552       <literal>Documentation/client_side_encryption</literal> directory.
 553     </para>
 554     <note><para>The client-side encryption feature is available natively on
 555       Lustre clients running a Linux distribution with at least kernel 5.4. It
 556       is also available thanks to an additional kernel library provided by
 557       Lustre, on clients that run a Linux distribution with basic support for
 558       encryption, including:</para>
 559      <itemizedlist>
 560        <listitem><para>CentOS/RHEL 8.1 and later;</para></listitem>
 561        <listitem><para>Ubuntu 18.04 and later;</para></listitem>
 562        <listitem><para>SLES 15 SP2 and later.</para></listitem>
 563      </itemizedlist>
 564     </note>
 565     <section xml:id="managingSecurity.clientencryption.semantics" remap="h3">
 566       <title><indexterm><primary>encryption access semantics</primary>
 567       </indexterm>Client-side encryption access semantics</title>
 568       <para>Only Lustre clients need access to encryption master keys. Keys are
 569         added to the filesystem-level encryption keyring on the Lustre client.
 570         <itemizedlist>
 571           <listitem>
 572             <para><emphasis role="bold">With the key</emphasis></para>
 573             <para>With the encryption key, encrypted regular files, directories,
 574               and symlinks behave very similarly to their unencrypted
 575               counterparts --- after all, the encryption is intended to be
 576               transparent. However, astute users may notice some differences in
 577               behavior:</para>
 578             <itemizedlist>
 579               <listitem>
 580                 <para>Unencrypted files, or files encrypted with a different
 581                   encryption policy (i.e. different key, modes, or flags),
 582                   cannot be renamed or linked into an encrypted directory.
 583                   However, encrypted files can be renamed within an encrypted
 584                   directory, or into an unencrypted directory.</para>
 585                 <note><para>"moving" an unencrypted file into an encrypted
 586                   directory, e.g. with the <literal>mv</literal> program, is
 587                   implemented in userspace by a copy followed by a delete.  Be
 588                   aware the original unencrypted data may remain recoverable
 589                   from free space on the disk; it is best to keep all files
 590                   encrypted from the very beginning.</para></note>
 591               </listitem>
 592               <listitem><para>On Lustre, Direct I/O is supported for encrypted
 593                 files.</para>
 594               </listitem>
 595               <listitem><para>The <literal>fallocate()</literal> operations
 596                 <literal>FALLOC_FL_COLLAPSE_RANGE</literal>,
 597                 <literal>FALLOC_FL_INSERT_RANGE</literal>, and
 598                 <literal>FALLOC_FL_ZERO_RANGE</literal> are not
 599                 supported on encrypted files and will fail with
 600                 <literal>EOPNOTSUPP</literal>.
 601                 </para>
 602               </listitem>
 603               <listitem><para>DAX (Direct Access) is not supported on encrypted
 604                 files.</para>
 605               </listitem>
 606               <listitem><para condition='l2F'>The st_size of an encrypted
 607                 symlink will not necessarily give the length of the symlink
 608                 target as required by POSIX. It will actually give the length of
 609                 the ciphertext, which will be slightly longer than the plaintext
 610                 due to NUL-padding and an extra 2-byte overhead.</para>
 611               </listitem>
 612               <listitem><para condition='l2F'>The maximum length of an encrypted
 613                 symlink is 2 bytes shorter than the maximum length of an
 614                 unencrypted symlink.</para>
 615               </listitem>
 616               <listitem><para><literal>mmap</literal> is supported.  This is
 617                 possible because the pagecache for an encrypted file contains
 618                 the plaintext, not the ciphertext.</para>
 619               </listitem>
 620             </itemizedlist>
 621           </listitem>
 622           <listitem>
 623             <para><emphasis role="bold">Without the key</emphasis></para>
 624             <para>Some filesystem operations may be performed on encrypted
 625               regular files, directories, and symlinks even before their
 626               encryption key has been added, or after their encryption key has
 627               been removed:</para>
 628             <itemizedlist>
 629               <listitem>
 630                 <para>File metadata may be read, e.g. using
 631                   <literal>stat()</literal>.</para>
 632               </listitem>
 633               <listitem>
 634                 <para condition='l2F'>Directories may be listed, in which case
 635                   the filenames will be listed in an encoded form derived from
 636                   their ciphertext. The algorithm is subject to change but it is
 637                   guaranteed that the presented filenames will be no longer than
 638                   NAME_MAX bytes, will not contain the <literal>/</literal> or
 639                   <literal>\0</literal> characters, and will uniquely identify
 640                   directory entries. The <literal>.</literal> and
 641                   <literal>..</literal> directory entries are special. They are
 642                   always present and are not encrypted or encoded.</para>
 643               </listitem>
 644               <listitem>
 645                 <para>Files may be deleted.  That is, nondirectory files may be
 646                   deleted with <literal>unlink()</literal> as usual, and empty
 647                   directories may be deleted with <literal>rmdir()</literal> as
 648                   usual. Therefore, <literal>rm</literal> and
 649                   <literal>rm -r</literal> will work as expected.</para>
 650               </listitem>
 651               <listitem>
 652                 <para>Symlink targets may be read and followed, but they will
 653                   be presented in encrypted form, similar to filenames in
 654                   directories. Hence, they are unlikely to point to anywhere
 655                   useful.</para>
 656               </listitem>
 657             </itemizedlist>
 658             <para>Without the key, regular files cannot be opened or truncated.
 659               Attempts to do so will fail with <literal>ENOKEY</literal>. This
 660               implies that any regular file operations that require a file
 661               descriptor, such as <literal>read()</literal>,
 662               <literal>write()</literal>, <literal>mmap()</literal>,
 663               <literal>fallocate()</literal>, and <literal>ioctl()</literal>,
 664               are also forbidden.</para>
 665             <para>Also without the key, files of any type (including
 666               directories) cannot be created or linked into an encrypted
 667               directory, nor can a name in an encrypted directory be the source
 668               or target of a rename, nor can an <literal>O_TMPFILE</literal>
 669               temporary file be created in an encrypted directory. All such
 670               operations will fail with <literal>ENOKEY</literal>.</para>
 671             <para>It is not currently possible to backup and restore encrypted
 672               files without the encryption key.  This would require special
 673               APIs which have not yet been implemented.</para>
 674           </listitem>
 675           <listitem>
 676             <para><emphasis role="bold">Encryption policy enforcement
 677               </emphasis></para>
 678             <para>After an encryption policy has been set on a directory, all
 679              regular files, directories, and symbolic links created in that
 680              directory (recursively) will inherit that encryption policy.
 681              Special files --- that is, named pipes, device nodes, and UNIX
 682              domain sockets --- will not be encrypted.</para>
 683            <para>Except for those special files, it is forbidden to have
 684              unencrypted files, or files encrypted with a different encryption
 685              policy, in an encrypted directory tree.</para>
 686            </listitem>
 687          </itemizedlist>
 688       </para>
 689     </section>
 690     <section xml:id="managingSecurity.clientencryption.keyhierarchy" remap="h3">
 691       <title><indexterm><primary>encryption key hierarchy</primary>
 692       </indexterm>Client-side encryption key hierarchy</title>
 693       <para>Each encrypted directory tree is protected by a master key.</para>
 694       <para>To "unlock" an encrypted directory tree, userspace must provide the
 695        appropriate master key.  There can be any number of master keys, each
 696        of which protects any number of directory trees on any number of
 697        filesystems.</para>
 698     </section>
 699     <section xml:id="managingSecurity.clientencryption.modes" remap="h3">
 700       <title><indexterm><primary>encryption modes usage</primary>
 701       </indexterm>Client-side encryption modes and usage</title>
 702       <para><literal>fscrypt</literal> allows one encryption mode to be
 703        specified for file contents and one encryption mode to be specified for
 704        filenames. Different directory trees are permitted to use different
 705        encryption modes. Currently, the following pairs of encryption modes are
 706        supported:</para>
 707        <itemizedlist>
 708          <listitem>
 709            <para>AES-256-XTS for contents and AES-256-CTS-CBC for filenames
 710            </para>
 711          </listitem>
 712          <listitem>
 713            <para>AES-128-CBC for contents and AES-128-CTS-CBC for filenames
 714            </para>
 715          </listitem>
 716        </itemizedlist>
 717        <para>If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
 718       </para>
 719       <warning><para>In Lustre 2.14, client-side encryption only supports
 720        content encryption, and not filename encryption. As a consequence, only
 721        content encryption mode will be taken into account, and filename
 722        encryption mode will be ignored to leave filenames in clear text.</para>
 723       </warning>
 724       <warning><para condition='l2F'>Ability to encrypt file and directory names
 725        is governed by new llite parameter named
 726        <literal>enable_filename_encryption</literal>, introduced in 2.15, and
 727        set to 0 by default.
 728        When this parameter is 0, new empty directories configured as encrypted
 729        use content encryption only, and not name encryption. This mode is
 730        inherited for all subdirectories and files.
 731        When <literal>enable_filename_encryption</literal> parameter is set to 1,
 732        new empty directories configured as encrypted use full encryption
 733        capabilities by encrypting file content and also file and directory
 734        names. This mode is inherited for all subdirectories and files.
 735        To set the <literal>enable_filename_encryption</literal> parameter
 736        globally for all clients, one can do on the MGS:
 737 <screen>mgs# lctl set_param -P llite.*.enable_filename_encryption=1</screen>
 738        Note however that new files and directories under a parent encrypted
 739        directory created with Lustre 2.14 will not have their names encrypted.
 740        Also, because files created with Lustre 2.14 did not have their names
 741        encrypted, they will remain so after upgrade to 2.15. To benefit from
 742        name encryption for an old directory previously created with Lustre 2.14,
 743        you need to do the following after upgrade to 2.15 is complete:
 744        <orderedlist>
 745          <listitem>
 746            <para>create a new encrypted directory. This can use an already
 747             existing protector.</para>
 748          </listitem>
 749          <listitem>
 750            <para>unlock the old encrypted directory.</para>
 751          </listitem>
 752          <listitem>
 753            <para>copy all files and directories recursively from the old
 754             encrypted directory to the newly created encrypted directory. Note
 755             that this operation will re-encrypt all files contents in addition
 756             to names.</para>
 757          </listitem>
 758          <listitem>
 759            <para>remove the old encrypted directory.</para>
 760          </listitem>
 761        </orderedlist>
 762       </para>
 763       </warning>
 764     </section>
 765     <section xml:id="managingSecurity.clientencryption.threatmodel" remap="h3">
 766       <title><indexterm><primary>encryption threat model</primary>
 767       </indexterm>Client-side encryption threat model</title>
 768       <itemizedlist>
 769         <listitem>
 770           <para><emphasis role="bold">Offline attacks</emphasis></para>
 771           <para>For the Lustre case, block devices are Lustre targets attached
 772             to the Lustre servers. Manipulating the filesystem offline means
 773             accessing the filesystem on these targets while Lustre is offline.
 774           </para>
 775           <para>Provided that a strong encryption key is chosen,
 776             <literal>fscrypt</literal> protects the confidentiality of file
 777             contents in the event of a single point-in-time permanent offline
 778             compromise of the block device content.
 779             Lustre client-side encryption does not protect the confidentiality
 780             of metadata, e.g. file names, file sizes, file permissions, file
 781             timestamps, and extended attributes.  Also, the existence and
 782             location of holes (unallocated blocks which logically contain all
 783             zeroes) in files is not protected.</para>
 784         </listitem>
 785         <listitem>
 786           <para><emphasis role="bold">Online attacks</emphasis></para>
 787           <itemizedlist>
 788             <listitem>
 789               <para>On Lustre client</para>
 790               <para>After an encryption key has been added,
 791                 <literal>fscrypt</literal> does not hide the plaintext file
 792                 contents or filenames from other users on the same node.
 793                 Instead, existing access control mechanisms such as file mode
 794                 bits, POSIX ACLs, LSMs, or namespaces should be used for this
 795                 purpose.</para>
 796               <para>For the Lustre case, it means plaintext file contents or
 797                 filenames are not hidden from other users on the same Lustre
 798                 client.</para>
 799               <para>An attacker who compromises the system enough to read from
 800                 arbitrary memory, e.g. by exploiting a kernel security
 801                 vulnerability, can compromise all encryption keys that are
 802                 currently in use.
 803                 However, <literal>fscrypt</literal> allows encryption keys to
 804                 be removed from the kernel, which may protect them from later
 805                 compromise. Key removal can be carried out by non-root users.
 806                 In more detail, the key removal will wipe the master encryption
 807                 key from kernel memory.  Moreover, it will try to evict all
 808                 cached inodes which had been "unlocked" using the key, thereby
 809                 wiping their per-file keys and making them once again appear
 810                 "locked", i.e. in ciphertext or encrypted form.</para>
 811             </listitem>
 812             <listitem>
 813               <para>On Lustre server</para>
 814               <para>An attacker on a Lustre server who compromises the system
 815                 enough to read arbitrary memory, e.g. by exploiting a kernel
 816                 security vulnerability, cannot compromise Lustre files content.
 817                 Indeed, encryption keys are not forwarded to the Lustre servers,
 818                 and servers do not carry out decryption or encryption.
 819                 Moreover, bulk RPCs received by servers contain encrypted data,
 820                 which is written as-is to the underlying filesystem.</para>
 821             </listitem>
 822           </itemizedlist>
 823         </listitem>
 824       </itemizedlist>
 825     </section>
 826     <section xml:id="managingSecurity.clientencryption.fscrypt" remap="h3">
 827       <title><indexterm><primary>encryption fscrypt policy</primary>
 828       </indexterm>Manage encryption on directories</title>
 829       <para>By default, Lustre client-side encryption is enabled, letting users
 830        define encryption policies on a per-directory basis.</para>
 831       <note><para>Administrators can decide to prevent a Lustre client
 832        mount-point from using encryption by specifying the
 833        <literal>noencrypt</literal> client mount option. This can be also
 834        enforced from server side thanks to the
 835        <literal>forbid_encryption</literal> property on nodemaps. See
 836        <xref linkend="alteringproperties"/> for how to manage nodemaps.
 837       </para></note>
 838       <para><literal>fscrypt</literal> userspace tool can be used to manage
 839        encryption policies. See https://github.com/google/fscrypt for
 840        comprehensive explanations. Below are examples on how to use this tool
 841        with Lustre. If not told otherwise, commands must be run on Lustre
 842        client side.</para>
 843       <itemizedlist>
 844         <listitem>
 845           <para>Two preliminary steps are required before actually deciding
 846             which directories to encrypt, and this is the only
 847             functionality which requires root privileges. Administrator has to
 848             run:</para>
 849           <screen># fscrypt setup
 850 Customizing passphrase hashing difficulty for this system...
 851 Created global config file at "/etc/fscrypt.conf".
 852 Metadata directories created at "/.fscrypt".</screen>
 853           <para>This first command has to be run on all clients that want to use
 854             encryption, as it sets up global fscrypt parameters outside of
 855             Lustre.</para>
 856           <screen># fscrypt setup /mnt/lustre
 857 Metadata directories created at "/mnt/lustre/.fscrypt"</screen>
 858           <para>This second command has to be run on just one Lustre
 859             client.</para>
 860           <note><para>The file <literal>/etc/fscrypt.conf</literal> can be
 861             edited. It is strongly recommended to set
 862             <literal>policy_version</literal> to 2, so that
 863             <literal>fscrypt</literal> wipes files from memory when the
 864             encryption key is removed.</para></note>
 865         </listitem>
 866         <listitem>
 867           <para>Now a regular user is able to select a directory to
 868             encrypt:</para>
 869             <screen>$ fscrypt encrypt /mnt/lustre/vault
 870 The following protector sources are available:
 871 1 - Your login passphrase (pam_passphrase)
 872 2 - A custom passphrase (custom_passphrase)
 873 3 - A raw 256-bit key (raw_key)
 874 Enter the source number for the new protector [2 - custom_passphrase]: 2
 875 Enter a name for the new protector: shield
 876 Enter custom passphrase for protector "shield":
 877 Confirm passphrase:
 878 "/mnt/lustre/vault" is now encrypted, unlocked, and ready for use.</screen>
 879           <para>Starting from here, all files and directories created under
 880             <literal>/mnt/lustre/vault</literal> will be encrypted, according
 881             to the policy defined at the previsous step.</para>
 882           <note><para>The encryption policy is inherited by all subdirectories.
 883             It is not possible to change the policy for a subdirectory.</para>
 884           </note>
 885         </listitem>
 886         <listitem>
 887           <para>Another user can decide to encrypt a different directory with
 888             its own protector:</para>
 889             <screen>$ fscrypt encrypt /mnt/lustre/private
 890 Should we create a new protector? [y/N] Y
 891 The following protector sources are available:
 892 1 - Your login passphrase (pam_passphrase)
 893 2 - A custom passphrase (custom_passphrase)
 894 3 - A raw 256-bit key (raw_key)
 895 Enter the source number for the new protector [2 - custom_passphrase]: 2
 896 Enter a name for the new protector: armor
 897 Enter custom passphrase for protector "armor":
 898 Confirm passphrase:
 899 "/mnt/lustre/private" is now encrypted, unlocked, and ready for use.</screen>
 900         </listitem>
 901         <listitem>
 902           <para>Users can decide to lock an encrypted directory at any
 903             time:</para>
 904           <screen>$ fscrypt lock /mnt/lustre/vault
 905 "/mnt/lustre/vault" is now locked.</screen>
 906           <para>This action prevents access to encrypted content, and by
 907             removing the key from memory, it also wipes files from memory if
 908             they are not still open.</para>
 909         </listitem>
 910         <listitem>
 911           <para>Users regain access to the encrypted directory with the command:
 912           </para>
 913           <screen>$ fscrypt unlock /mnt/lustre/vault
 914 Enter custom passphrase for protector "shield":
 915 "/mnt/lustre/vault" is now unlocked and ready for use.</screen>
 916         </listitem>
 917         <listitem>
 918           <para>Actually, <literal>fscrypt</literal> does not give direct access
 919             to master keys, but to protectors that are used to encrypt them.
 920             This mechanism gives the ability to change a passphrase:</para>
 921             <screen>$ fscrypt status /mnt/lustre
 922 lustre filesystem "/mnt/lustre" has 2 protectors and 2 policies
 923
 924 PROTECTOR         LINKED  DESCRIPTION
 925 deacab807bf0e788  No      custom protector "shield"
 926 e691ae7a1990fc2a  No      custom protector "armor"
 927
 928 POLICY                            UNLOCKED  PROTECTORS
 929 52b2b5aff0e59d8e0d58f962e715862e  No        deacab807bf0e788
 930 374e8944e4294b527e50363d86fc9411  No        e691ae7a1990fc2a
 931
 932 $ fscrypt metadata change-passphrase --protector=/mnt/lustre:deacab807bf0e788
 933 Enter old custom passphrase for protector "shield":
 934 Enter new custom passphrase for protector "shield":
 935 Confirm passphrase:
 936 Passphrase for protector deacab807bf0e788 successfully changed.</screen>
 937           <para>It makes also possible to have multiple protectors for the same
 938             policy. This is really useful when several users share an encrypted
 939             directory, because it avoids the need to share any secret between
 940             them.</para>
 941            <screen>$ fscrypt status /mnt/lustre/vault
 942 "/mnt/lustre/vault" is encrypted with fscrypt.
 943
 944 Policy:   52b2b5aff0e59d8e0d58f962e715862e
 945 Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
 946 Unlocked: No
 947
 948 Protected with 1 protector:
 949 PROTECTOR         LINKED  DESCRIPTION
 950 deacab807bf0e788  No      custom protector "shield"
 951
 952 $ fscrypt metadata create protector /mnt/lustre
 953 Create new protector on "/mnt/lustre" [Y/n] Y
 954 The following protector sources are available:
 955 1 - Your login passphrase (pam_passphrase)
 956 2 - A custom passphrase (custom_passphrase)
 957 3 - A raw 256-bit key (raw_key)
 958 Enter the source number for the new protector [2 - custom_passphrase]: 2
 959 Enter a name for the new protector: bunker
 960 Enter custom passphrase for protector "bunker":
 961 Confirm passphrase:
 962 Protector f3cc1b5cf9b8f41c created on filesystem "/mnt/lustre".
 963
 964 $ fscrypt metadata add-protector-to-policy
 965           --protector=/mnt/lustre:f3cc1b5cf9b8f41c
 966           --policy=/mnt/lustre:52b2b5aff0e59d8e0d58f962e715862e
 967 WARNING: All files using this policy will be accessible with this protector!!
 968 Protect policy 52b2b5aff0e59d8e0d58f962e715862e with protector f3cc1b5cf9b8f41c? [Y/n] Y
 969 Enter custom passphrase for protector "bunker":
 970 Enter custom passphrase for protector "shield":
 971 Protector f3cc1b5cf9b8f41c now protecting policy 52b2b5aff0e59d8e0d58f962e715862e.
 972
 973 $ fscrypt status /mnt/lustre/vault
 974 "/mnt/lustre/vault" is encrypted with fscrypt.
 975
 976 Policy:   52b2b5aff0e59d8e0d58f962e715862e
 977 Options:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2
 978 Unlocked: No
 979
 980 Protected with 2 protectors:
 981 PROTECTOR         LINKED  DESCRIPTION
 982 deacab807bf0e788  No      custom protector "shield"
 983 f3cc1b5cf9b8f41c  No      custom protector "bunker"</screen>
 984         </listitem>
 985       </itemizedlist>
 986     </section>
 987   </section>
 988   <section xml:id="managingSecurity.kerberos">
 989     <title><indexterm><primary>Kerberos</primary></indexterm>
 990     Configuring Kerberos (KRB) Security</title>
 991     <para>This chapter describes how to use Kerberos with Lustre.</para>
 992     <section xml:id="managingSecurity.kerberos.whatisit">
 993       <title>What Is Kerberos?</title>
 994       <para>Kerberos is a mechanism for authenticating all entities (such as
 995         users and servers) on an &quot;unsafe&quot; network. Each of these
 996         entities, known as &quot;principals&quot;, negotiate a runtime key with
 997         the Kerberos server. This key enables principals to verify that messages
 998         from the Kerberos server are authentic. By trusting the Kerberos server,
 999         users and services can authenticate one another.</para>
1000       <para>Setting up Lustre with Kerberos can provide advanced security
1001         protections for the Lustre network. Broadly, Kerberos offers three types
1002         of benefit:</para>
1003       <itemizedlist>
1004         <listitem>
1005           <para>Allows Lustre connection peers (MDS, OSS and clients) to
1006             authenticate one another.</para>
1007         </listitem>
1008         <listitem>
1009           <para>Protects the integrity of PTLRPC messages from being modified
1010             during network transfer.</para>
1011         </listitem>
1012         <listitem>
1013           <para>Protects the privacy of the PTLRPC message from being
1014             eavesdropped during network transfer.</para>
1015         </listitem>
1016       </itemizedlist>
1017       <para>Kerberos uses the “kernel keyring” client upcall mechanism.</para>
1018     </section>
1019     <section xml:id="managingSecurity.kerberos.securityflavor">
1020       <title>Security Flavor</title>
1021       <para>
1022         A security flavor is a string to describe what kind authentication
1023         and data transformation be performed upon a PTLRPC connection. It
1024         covers both RPC message and BULK data.
1025       </para>
1026       <para>
1027         The supported flavors are described in following table:
1028       </para>
1029       <informaltable>
1030         <tgroup cols="5">
1031           <colspec align="left" />
1032           <colspec align="left" />
1033           <colspec align="left" />
1034           <colspec align="left" />
1035           <colspec align="left" />
1036           <thead>
1037             <row>
1038               <entry>
1039                 Base Flavor
1040               </entry>
1041               <entry>
1042                 Authentication
1043               </entry>
1044               <entry>
1045                 RPC Message Protection
1046               </entry>
1047               <entry>
1048                 Bulk Data Protection
1049               </entry>
1050               <entry>
1051                 Notes
1052               </entry>
1053             </row>
1054           </thead>
1055           <tbody>
1056             <row>
1057               <entry>
1058                 <emphasis><emphasis role="strong">null</emphasis></emphasis>
1059               </entry>
1060               <entry>
1061                 N/A
1062               </entry>
1063               <entry>
1064                 N/A
1065               </entry>
1066               <entry>
1067                 N/A
1068               </entry>
1069             </row>
1070             <row>
1071               <entry>
1072                 <emphasis><emphasis role="strong">krb5n</emphasis></emphasis>
1073               </entry>
1074               <entry>
1075                 GSS/Kerberos5
1076               </entry>
1077               <entry>
1078                 null
1079               </entry>
1080               <entry>
1081                 checksum
1082               </entry>
1083               <entry>
1084                 No protection of RPC message, checksum protection
1085                 of bulk data, light performance overhead.
1086               </entry>
1087             </row>
1088             <row>
1089               <entry>
1090                 <emphasis><emphasis role="strong">krb5a</emphasis></emphasis>
1091               </entry>
1092               <entry>
1093                 GSS/Kerberos5
1094               </entry>
1095               <entry>
1096                 partial integrity (krb5)
1097               </entry>
1098               <entry>
1099                 checksum
1100               </entry>
1101               <entry>
1102                 Only header of RPC message is integrity protected, and
1103                 checksum protection of bulk data, more performance
1104                 overhead compare to krb5n.
1105               </entry>
1106             </row>
1107             <row>
1108               <entry>
1109                 <emphasis><emphasis role="strong">krb5i</emphasis></emphasis>
1110               </entry>
1111               <entry>
1112                 GSS/Kerberos5
1113               </entry>
1114               <entry>
1115                 integrity (krb5)
1116               </entry>
1117               <entry>
1118                 integrity (krb5)
1119               </entry>
1120               <entry>
1121                 transformation algorithm is determined by actual Kerberos
1122                 algorithms enforced by KDC and principals; heavy performance
1123                 penalty.
1124               </entry>
1125             </row>
1126             <row>
1127               <entry>
1128                 <emphasis><emphasis role="strong">krb5p</emphasis></emphasis>
1129               </entry>
1130               <entry>
1131                 GSS/Kerberos5
1132               </entry>
1133               <entry>
1134                 privacy (krb5)
1135               </entry>
1136               <entry>
1137                 privacy (krb5)
1138               </entry>
1139               <entry>
1140                 transformation privacy protection algorithm is determined
1141                 by actual Kerberos algorithms enforced by KDC and principals;
1142                 the heaviest performance penalty.
1143               </entry>
1144             </row>
1145           </tbody>
1146         </tgroup>
1147       </informaltable>
1148     </section>
1149     <section xml:id="managingSecurity.kerberos.kerberossetup">
1150       <title>Kerberos Setup</title>
1151       <section xml:id="managingSecurity.kerberos.kerberossetup.distribution">
1152         <title>Distribution</title>
1153         <para>We only support MIT Kerberos 5, from version 1.3.</para>
1154         <para>For environmental requirements in general, and clock
1155          synchronization in particular, please refer to section
1156          <xref linkend="section_rh2_d4w_gk"/>.</para>
1157       </section>
1158       <section xml:id="managingSecurity.kerberos.kerberossetup.configuration">
1159         <title>Principals Configuration</title>
1160         <itemizedlist>
1161           <listitem>
1162             <para>Configure client nodes:</para>
1163             <itemizedlist>
1164               <listitem>
1165                 <para>
1166                   For each client node, create a <literal>lustre_root</literal>
1167                   principal and generate keytab.
1168                 </para>
1169                 <screen>kadmin&gt; addprinc -randkey lustre_root/client_host.domain@REALM</screen>
1170                 <screen>kadmin&gt; ktadd lustre_root/client_host.domain@REALM</screen>
1171               </listitem>
1172               <listitem>
1173                 <para>
1174                   Install the keytab on the client node.
1175                 </para>
1176               </listitem>
1177             </itemizedlist>
1178           </listitem>
1179           <listitem>
1180             <para>Configure MGS nodes:</para>
1181             <itemizedlist>
1182               <listitem>
1183                 <para>
1184                   For each MGS node, create a <literal>lustre_mgs</literal>
1185                   principal and generate keytab.
1186                 </para>
1187                 <screen>kadmin&gt; addprinc -randkey lustre_mgs/mgs_host.domain@REALM</screen>
1188                 <screen>kadmin&gt; ktadd lustre_mds/mgs_host.domain@REALM</screen>
1189               </listitem>
1190               <listitem>
1191                 <para>
1192                   Install the keytab on the MGS nodes.
1193                 </para>
1194               </listitem>
1195             </itemizedlist>
1196           </listitem>
1197           <listitem>
1198             <para>Configure MDS nodes:</para>
1199             <itemizedlist>
1200               <listitem>
1201                 <para>
1202                   For each MDS node, create a <literal>lustre_mds</literal>
1203                   principal and generate keytab.
1204                 </para>
1205                 <screen>kadmin&gt; addprinc -randkey lustre_mds/mds_host.domain@REALM</screen>
1206                 <screen>kadmin&gt; ktadd lustre_mds/mds_host.domain@REALM</screen>
1207               </listitem>
1208               <listitem>
1209                 <para>
1210                   Install the keytab on the MDS nodes.
1211                 </para>
1212               </listitem>
1213             </itemizedlist>
1214           </listitem>
1215           <listitem>
1216             <para>Configure OSS nodes:</para>
1217             <itemizedlist>
1218               <listitem>
1219                 <para>
1220                   For each OSS node, create a <literal>lustre_oss</literal>
1221                   principal and generate keytab.
1222                 </para>
1223                 <screen>kadmin&gt; addprinc -randkey lustre_oss/oss_host.domain@REALM</screen>
1224                 <screen>kadmin&gt; ktadd lustre_oss/oss_host.domain@REALM</screen>
1225               </listitem>
1226               <listitem>
1227                 <para>
1228                   Install the keytab on the client node.
1229                 </para>
1230               </listitem>
1231             </itemizedlist>
1232           </listitem>
1233         </itemizedlist>
1234         <note>
1235           <itemizedlist>
1236             <listitem>
1237               <para>The <emphasis>host.domain</emphasis> should be the FQDN in
1238               your network, otherwise server might not recognize any GSS
1239               request.</para>
1240             </listitem>
1241             <listitem>
1242               <para>
1243                 As an alternative for the client keytab, if you want to save
1244                 the trouble of assigning unique keytab for each client node,
1245                 you can create a general lustre_root principal and its
1246                 keytab, and install the same keytab on as many client nodes
1247                 as you want. <emphasis role="strong">Be aware that in
1248                 this way one compromised client means all clients are
1249                 insecure</emphasis>.
1250               </para>
1251               <screen>kadmin&gt; addprinc -randkey lustre_root@REALM</screen>
1252               <screen>kadmin&gt; ktadd lustre_root@REALM</screen>
1253             </listitem>
1254             <listitem>
1255               <para>
1256                 Lustre support following <emphasis>enctypes</emphasis> for
1257                 MIT Kerberos 5 version 1.3 or higher:
1258               </para>
1259               <itemizedlist>
1260                 <listitem>
1261                   <para>
1262                     <emphasis>aes128-cts</emphasis>
1263                   </para>
1264                 </listitem>
1265                 <listitem>
1266                   <para>
1267                     <emphasis>aes256-cts</emphasis>
1268                   </para>
1269                 </listitem>
1270               </itemizedlist>
1271             </listitem>
1272           </itemizedlist>
1273         </note>
1274       </section>
1275     </section>
1276     <section xml:id="managingSecurity.kerberos.network">
1277       <title>Networking</title>
1278       <para>On networks for which name resolution to IP address is possible,
1279         like TCP or InfiniBand, the names used in the principals must be the
1280         ones that resolve to the IP addresses used by the Lustre NIDs.</para>
1281       <para>If you are using a network which is
1282         <emphasis role="strong">NOT</emphasis> TCP or InfiniBand (e.g.
1283         PTL4LND), you need to have a <literal>/etc/lustre/nid2hostname</literal>
1284         script on <emphasis role="strong">each</emphasis> node, which purpose is
1285         to translate NID into hostname.
1286         Following is a possible example for PTL4LND:</para>
1287       <screen>#!/bin/bash
1288 set -x
1289
1290 # convert a NID for a LND to a hostname
1291
1292 # called with thre arguments: lnd netid nid
1293 #   $lnd is the string "PTL4LND", etc.
1294 #   $netid is the network identifier in hex string format
1295 #   $nid is the NID in hex format
1296 # output the corresponding hostname,
1297 # or error message leaded by a '@' for error logging.
1298
1299 lnd=$1
1300 netid=$2
1301 # convert hex NID number to decimal
1302 nid=$((0x$3))
1303
1304 case $lnd in
1305     PTL4LND)   # simply add 'node' at the beginning
1306         echo "node$nid"
1307         ;;
1308     *)
1309         echo "@unknown LND: $lnd"
1310         ;;
1311 esac</screen>
1312     </section>
1313     <section xml:id="managingSecurity.kerberos.requiredpackages">
1314       <title>Required packages</title>
1315       <para>
1316         Every node should have following packages installed:
1317       </para>
1318       <itemizedlist>
1319         <listitem>
1320           <para>krb5-workstation</para>
1321         </listitem>
1322         <listitem>
1323           <para>krb5-libs</para>
1324         </listitem>
1325         <listitem>
1326           <para>keyutils</para>
1327         </listitem>
1328         <listitem>
1329           <para>keyutils-libs</para>
1330         </listitem>
1331       </itemizedlist>
1332       <para>On the node used to build Lustre with GSS support, following
1333         packages should be installed:</para>
1334       <itemizedlist>
1335         <listitem>
1336           <para>krb5-devel</para>
1337         </listitem>
1338         <listitem>
1339           <para>keyutils-libs-devel</para>
1340         </listitem>
1341       </itemizedlist>
1342     </section>
1343     <section xml:id="managingSecurity.kerberos.buildlustre">
1344       <title>Build Lustre</title>
1345       <para>
1346         Enable GSS at configuration time:
1347       </para>
1348       <screen>./configure --enable-gss --other-options</screen>
1349     </section>
1350     <section xml:id="managingSecurity.kerberos.running">
1351       <title>Running</title>
1352       <section xml:id="managingSecurity.kerberos.running.gssdaemons">
1353         <title>GSS Daemons</title>
1354         <para>
1355           Make sure to start the daemon process
1356           <literal>lsvcgssd</literal> on each server node (MGS, MDS and OSS)
1357           before starting Lustre. The command syntax is:
1358         </para>
1359         <screen>lsvcgssd [-f] [-v] [-g] [-m] [-o] -k</screen>
1360         <itemizedlist>
1361           <listitem>
1362             <para>-f: run in foreground, instead of as daemon</para>
1363           </listitem>
1364           <listitem>
1365             <para>-v: increase verbosity by 1. For example, to set the verbose
1366              level to 3, run 'lsvcgssd -vvv'. Verbose logging can help you make
1367              sure Kerberos is set up correctly.
1368             </para>
1369           </listitem>
1370           <listitem>
1371             <para>-g: service MGS</para>
1372           </listitem>
1373           <listitem>
1374             <para>-m: service MDS</para>
1375           </listitem>
1376           <listitem>
1377             <para>-o: service OSS</para>
1378           </listitem>
1379           <listitem>
1380             <para>-k: enable kerberos support</para>
1381           </listitem>
1382         </itemizedlist>
1383       </section>
1384       <section xml:id="managingSecurity.kerberos.running.settingsecurityflavors">
1385         <title>Setting Security Flavors</title>
1386         <para>
1387           Security flavors can be set by defining sptlrpc rules on the MGS.
1388           These rules are persistent, and are in the form:
1389           <literal>&lt;spec&gt;=&lt;flavor&gt;</literal>
1390         </para>
1391         <itemizedlist>
1392           <listitem>
1393             <para>To add a rule:</para>
1394             <screen>mgs&gt; lctl conf_param &lt;spec&gt;=&lt;flavor&gt;</screen>
1395             <para>
1396               If there is an existing rule on &lt;spec&gt;, it will be
1397               overwritten.</para>
1398           </listitem>
1399           <listitem>
1400             <para>To delete a rule:</para>
1401             <screen>mgs&gt; lctl conf_param -d &lt;spec&gt;</screen>
1402           </listitem>
1403           <listitem>
1404             <para>To list existing rules:</para>
1405             <screen>msg&gt; lctl get_param mgs.MGS.live.&lt;fs-name&gt; | grep "srpc.flavor"</screen>
1406           </listitem>
1407         </itemizedlist>
1408         <note>
1409           <itemizedlist>
1410             <listitem>
1411               <para>If nothing is specified, by default all RPC connections will
1412                 use <literal>null</literal> flavor, which means no security.
1413               </para>
1414             </listitem>
1415             <listitem>
1416               <para>
1417                 After you change a rule, it usually takes a few minutes to apply
1418                 the new rule to all nodes, depending on global system load.
1419               </para>
1420             </listitem>
1421             <listitem>
1422               <para>
1423                 Before you change a rule, make sure affected nodes are ready
1424                 for the new security flavor. E.g. if you change flavor from
1425                 <literal>null</literal> to <literal>krb5p</literal>
1426                 but GSS/Kerberos environment is not properly configured on
1427                 affected nodes, those nodes might be evicted because they cannot
1428                 communicate with each other.
1429               </para>
1430             </listitem>
1431           </itemizedlist>
1432         </note>
1433       </section>
1434       <section xml:id="managingSecurity.kerberos.running.rulessyntaxexamples">
1435         <title>Rules Syntax &amp; Examples</title>
1436         <para>
1437           The general syntax is:
1438         <literal>
1439           &lt;target&gt;.srpc.flavor.&lt;network&gt;[.&lt;direction&gt;]=flavor
1440         </literal></para>
1441         <itemizedlist>
1442           <listitem>
1443             <para>
1444               <literal>&lt;target&gt;</literal> can be filesystem name, or
1445               specific MDT/OST device name. For example
1446               <literal>testfs</literal>,
1447               <literal>testfs-MDT0000</literal>,
1448               <literal>testfs-OST0001</literal>.
1449             </para>
1450           </listitem>
1451           <listitem>
1452             <para>
1453               <literal>&lt;network&gt;</literal> is the LNet network name, for
1454               example <literal>tcp0</literal>, <literal>o2ib0</literal>, or
1455               <literal>default</literal> to not filter on LNet network.
1456             </para>
1457           </listitem>
1458           <listitem>
1459             <para>
1460               <literal>&lt;direction&gt;</literal> can be one of
1461               <emphasis>cli2mdt</emphasis>, <emphasis>cli2ost</emphasis>,
1462               <emphasis>mdt2mdt</emphasis>, <emphasis>mdt2ost</emphasis>.
1463               Direction is optional.
1464             </para>
1465           </listitem>
1466         </itemizedlist>
1467         <para>
1468           Examples:
1469         </para>
1470         <itemizedlist>
1471           <listitem>
1472             <para>
1473               Apply <literal>krb5i</literal> on
1474               <emphasis role="strong">ALL</emphasis> connections for file system
1475               <literal>testfs</literal>:
1476             </para>
1477           </listitem>
1478         </itemizedlist>
1479         <screen>mgs&gt; lctl conf_param testfs.srpc.flavor.default=krb5i</screen>
1480         <itemizedlist>
1481           <listitem>
1482             <para>
1483               Nodes in network <literal>tcp0</literal> use
1484               <literal>krb5p</literal>; all other nodes use
1485               <literal>null</literal>.
1486             </para>
1487           </listitem>
1488         </itemizedlist>
1489         <screen>mgs&gt; lctl conf_param testfs.srpc.flavor.tcp0=krb5p
1490 mgs&gt; lctl conf_param testfs.srpc.flavor.default=null</screen>
1491         <itemizedlist>
1492           <listitem>
1493             <para>
1494               Nodes in network <literal>tcp0</literal> use
1495               <literal>krb5p</literal>; nodes in
1496               <literal>o2ib0</literal> use <literal>krb5n</literal>;
1497               among other nodes, clients use <literal>krb5i</literal>
1498               to MDT/OST, MDTs use <literal>null</literal> to other MDTs,
1499               MDTs use <literal>krb5a</literal> to OSTs.
1500             </para>
1501           </listitem>
1502         </itemizedlist>
1503         <screen>mgs&gt; lctl conf_param testfs.srpc.flavor.tcp0=krb5p
1504 mgs&gt; lctl conf_param testfs.srpc.flavor.o2ib0=krb5n
1505 mgs&gt; lctl conf_param testfs.srpc.flavor.default.cli2mdt=krb5i
1506 mgs&gt; lctl conf_param testfs.srpc.flavor.default.cli2ost=krb5i
1507 mgs&gt; lctl conf_param testfs.srpc.flavor.default.mdt2mdt=null
1508 mgs&gt; lctl conf_param testfs.srpc.flavor.default.mdt2ost=krb5a</screen>
1509       </section>
1510       <section xml:id="managingSecurity.kerberos.running.authenticatenormalusers">
1511         <title>Regular Users Authentication</title>
1512         <para>
1513           On client nodes, non-root users need to issue
1514           <literal>kinit</literal> before accessing Lustre, just like other
1515            Kerberized applications.
1516         </para>
1517         <itemizedlist>
1518           <listitem>
1519             <para>
1520               Required by kerberos, the user&apos;s principal
1521               (<literal>username@REALM</literal>) should be added to the KDC.
1522             </para>
1523           </listitem>
1524           <listitem>
1525             <para>
1526               Client and MDT nodes should have the same user database
1527               used for name and uid/gid translation.
1528             </para>
1529           </listitem>
1530         </itemizedlist>
1531         <para>
1532           Regular users can destroy the established security contexts before
1533           logging out, by issuing:
1534         </para>
1535         <screen>lfs flushctx -k -r &lt;mount point&gt;</screen>
1536         <para>
1537           Here <literal>-k</literal> is to destroy the on-disk Kerberos
1538           credential cache, similar to <literal>kdestroy</literal>, and
1539           <literal>-r</literal> is to reap the revoked keys from the keyring
1540           when flushing the GSS context. Otherwise it only destroys established
1541           contexts in kernel memory.
1542         </para>
1543       </section>
1544     </section>
1545     <section xml:id="managingSecurity.kerberos.securemgsconnection">
1546       <title>Secure MGS connection</title>
1547       <para>
1548         Each node can specify which flavor to use to connect to the MGS, by
1549         using the <literal>mgssec=flavor</literal> mount option.
1550         Once a flavor is chosen, it cannot be changed until re-mount.
1551       </para>
1552       <para>
1553         Because a Lustre node only has one connection to the MGS, if there is
1554         more than one target or client on the node, they necessarily use the
1555         same security flavor to the MGS, being the one enforced when the first
1556         connection to the MGS was established.
1557       </para>
1558       <para>
1559         By default, the MGS accepts RPCs with any flavor. But it is possible to
1560         configure the MGS to only accept a given flavor. The syntax is identical
1561         to what is explained in paragraph
1562         <xref linkend="managingSecurity.kerberos.running.rulessyntaxexamples"/>,
1563         but with special target <literal>_mgs</literal>:
1564       </para>
1565       <screen>mgs&gt; lctl conf_param _mgs.srpc.flavor.&lt;network&gt;=&lt;flavor&gt;</screen>
1566     </section>
1567   </section>
1568 </chapter>
1569 <!--
1570   vim:expandtab:shiftwidth=2:tabstop=8:
1571   -->