LustreProgrammingInterfaces.xml

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