LustreProgrammingInterfaces.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="lustreprogramminginterfaces">
   5   <title xml:id="lustreprogramminginterfaces.title">Programming Interfaces</title>
   6   <para>This chapter describes public programming interfaces to that can be
   7     used to control various aspects of a Lustre file system from userspace.
   8     This chapter includes the following sections:</para>
   9   <itemizedlist>
  10     <listitem>
  11       <para><xref linkend="identity_upcall"/></para>
  12     </listitem>
  13     <listitem>
  14       <para><xref linkend="perm_downcall_data"/></para>
  15     </listitem>
  16   </itemizedlist>
  17   <note>
  18     <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
  19   </note>
  20   <section xml:id="identity_upcall">
  21     <title><indexterm>
  22         <primary>programming</primary>
  23         <secondary>upcall</secondary>
  24       </indexterm>User/Group Upcall</title>
  25     <para>This section describes the supplementary user/group upcall, which
  26       allows the MDS to retrieve and verify the supplementary groups to which
  27       a particular user is assigned. This avoids the need to pass all the
  28       supplementary groups from the client to the MDS with every RPC.</para>
  29     <note>
  30       <para>For information about universal UID/GID requirements in a Lustre
  31         file system environment, see
  32           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
  33            linkend="section_rh2_d4w_gk"/>.</para>
  34     </note>
  35     <section remap="h3">
  36       <title>Synopsis</title>
  37       <para>The MDS uses the utility as specified by
  38        <literal>lctl get_param mdt.${FSNAME}-MDT{xxxx}.identity_upcall</literal>
  39        to look up the supplied UID in order to retrieve the user's supplementary
  40        group membership. The result is temporarily cached in the kernel (for
  41        five minutes, by default) to avoid the overhead of calling into
  42        userspace repeatedly.</para>
  43     </section>
  44     <section remap="h3">
  45       <title>Description</title>
  46       <para>The <literal>identity_upcall</literal> parameter contains the path
  47         to an executable that is run to map a numeric UID to a group membership
  48         list. This upcall executable opens the
  49         <literal>mdt.${FSNAME}-MDT{xxxx}.identity_info</literal> parameter file
  50         and writes the related <literal>identity_downcall_data</literal> data
  51         structure (see <xref linkend="perm_downcall_data"/>). The
  52         upcall is configured with
  53         <literal>lctl set_param mdt.${FSNAME}-MDT{xxxx}.identity_upcall</literal>.</para>
  54       <para>The default identity upcall program installed is
  55       <literal>lustre/utils/l_getidentity.c</literal> in the Lustre source
  56       distribution.</para>
  57       <section remap="h4">
  58         <title>Primary and Secondary Groups</title>
  59         <para>The mechanism for the primary/secondary group is as follows:
  60         </para>
  61         <itemizedlist>
  62           <listitem>
  63             <para>The MDS issues an upcall (set per MDS) to map the numeric
  64               UID to the supplementary group(s).</para>
  65           </listitem>
  66           <listitem>
  67             <para>If there is no upcall or if there is an upcall and it fails,
  68               one supplementary group at most will be added as supplied by the
  69               client.</para>
  70           </listitem>
  71           <listitem>
  72             <para>The default upcall <literal>/usr/sbin/l_getidentity</literal>
  73               can interact with the user/group database on the MDS to map the
  74               UID to the GID and supplementary GID. The user/group database
  75               depends on how authentication is configured on the MDS, such as
  76               local <literal>/etc/passwd</literal>, Network Information Service
  77               (NIS), Lightweight Directory Access Protocol (LDAP), or SMB
  78               Domain services, as configured. If the upcall interface is set
  79               to NONE, then upcall is disabled, and the MDS uses only the UID,
  80               GID, and one supplementary GID supplied by the client.</para>
  81           </listitem>
  82           <listitem>
  83             <para>The MDS will wait a limited time for the group upcall program
  84               to complete, to avoid MDS threads and clients hanging due to
  85               errors accessing a remote service node.  The upcall must finish
  86               within 30s before the MDS will continue without the supplementary
  87               data.  The upcall timeout in seconds can be set on the MDS using:
  88               <literal>lctl set_param mdt.*.identity_acquire_expire=<replaceable>seconds</replaceable></literal></para>
  89           </listitem>
  90           <listitem>
  91             <para>The default group upcall is set permanently by
  92               <literal>mkfs.lustre</literal>. To set a custom upcall for a
  93               particular filesystem, use
  94               <literal>tunefs.lustre --param</literal> or
  95               <literal>lctl set_param -P mdt.<replaceable>FSNAME</replaceable>-MDT<replaceable>xxxx</replaceable>.identity_upcall=<replaceable>path</replaceable></literal></para>
  96           </listitem>
  97           <listitem>
  98             <para>The group downcall data is cached by the kernel to avoid
  99               repeated upcalls for the same user slowing down the MDS.  This
 100               cache is expired from the kernel after 1200s (20 minutes) by
 101               default.  The cache age in seconds can be set on the MDS using:
 102               <literal>lctl set_param mdt.*.identity_expire=<replaceable>seconds</replaceable></literal></para>
 103           </listitem>
 104           <listitem>
 105             <para>To force eviction of cached identity data (e.g. after adding
 106               or removing a user from a supplementary group), the cache entry
 107               for a specific numeric UID can be flushed on the MDS using:
 108               <literal>lctl set_param mdt.*.identity_flush=<replaceable>UID</replaceable></literal>
 109               To flush the cached records for all users from cache, use
 110               <literal>-1</literal> for the UID:
 111               <literal>lctl set_param mdt.*.identity_flush=-1</literal>
 112             </para>
 113           </listitem>
 114         </itemizedlist>
 115       </section>
 116     </section>
 117     <section xml:id="perm_downcall_data">
 118       <title>Data Structures</title>
 119       <screen>struct perm_downcall_data {
 120      __u64 pdd_nid;
 121      __u32 pdd_perm;
 122      __u32 pdd_padding;
 123 };
 124
 125 struct identity_downcall_data{
 126      __u32        idd_magic;
 127      :
 128      :</screen>
 129     </section>
 130   </section>
 131 </chapter>
 132 <!--
 133   vim:expandtab:shiftwidth=2:tabstop=8:
 134   -->