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