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 used to control various
   4     aspects of a Lustre file system from userspace. This chapter includes the following
   5     sections:</para>
   6   <itemizedlist>
   7     <listitem>
   8       <para><xref linkend="dbdoclet.50438291_32926"/></para>
   9     </listitem>
  10     <listitem>
  11       <para><xref linkend="dbdoclet.50438291_73963"/></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.50438291_32926">
  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 allows the MDS to
  23       retrieve and verify the supplementary groups to which a particular user is assigned. This
  24       avoids the need to pass all the supplementary groups from the client to the MDS with every
  25       RPC.</para>
  26     <note>
  27       <para>For information about universal UID/GID requirements in a Lustre file system
  28         environment, see <xref xmlns:xlink="http://www.w3.org/1999/xlink"
  29           linkend="section_rh2_d4w_gk"/>.</para>
  30     </note>
  31     <section remap="h3">
  32       <title>Synopsis</title>
  33       <para>The MDS uses the utility as specified by <literal>lctl get_param
  34           mdt.${FSNAME}-MDT{xxxx}.identity_upcall</literal> to look up the supplied UID in order to
  35         retrieve the user's supplementary group membership. The result is temporarily cached in the
  36         kernel (for five minutes, by default) to avoid the overhead of calling into userspace
  37         repeatedly.</para>
  38     </section>
  39     <section remap="h3">
  40       <title>Description</title>
  41       <para>The identity upcall file contains the path to an executable that is invoked to resolve a
  42         numeric UID to a group membership list. This utility opens
  43           <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info</literal> and fills in the
  44         related <literal>identity_downcall_data</literal> data structure (see <xref
  45           linkend="dbdoclet.50438291_33759"/>). The data is persisted with <literal>lctl set_param
  46           mdt.${FSNAME}-MDT{xxxx}.identity_info</literal>.</para>
  47       <para>For a sample upcall program, see <literal>lustre/utils/l_getidentity.c</literal> in the Lustre source distribution.</para>
  48       <section remap="h4">
  49         <title>Primary and Secondary Groups</title>
  50         <para>The mechanism for the primary/secondary group is as follows:</para>
  51         <itemizedlist>
  52           <listitem>
  53             <para>The MDS issues an upcall (set per MDS) to map the numeric UID to the supplementary
  54               group(s).</para>
  55           </listitem>
  56           <listitem>
  57             <para>If there is no upcall or if there is an upcall and it fails, one supplementary
  58               group at most will be added as supplied by the client.</para>
  59           </listitem>
  60           <listitem>
  61             <para>The default upcall is <literal>/usr/sbin/l_getidentity</literal>, which can
  62               interact with the user/group database to obtain UID/GID/suppgid. The user/group
  63               database depends on how authentication is configured, such as local
  64                 <literal>/etc/passwd</literal>, Network Information Service (NIS), or Lightweight
  65               Directory Access Protocol (LDAP). If necessary, the administrator can use a parse
  66               utility to set
  67                 <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall</literal>. If the
  68               upcall interface is set to NONE, then upcall is disabled. The MDS uses the
  69               UID/GID/suppgid supplied by the client.</para>
  70           </listitem>
  71           <listitem>
  72             <para>The default group upcall is set by <literal>mkfs.lustre</literal>. Use
  73                 <literal>tunefs.lustre --param</literal> or <literal>lctl set_param
  74                 mdt.${FSNAME}-MDT{xxxx}.identity_upcall={path}</literal></para>
  75           </listitem>
  76         </itemizedlist>
  77         <itemizedlist>
  78           <para>A Lustre file system administrator can specify permissions for a specific UID by
  79             configuring <literal>/etc/lustre/perm.conf</literal> on the MDS. The
  80               <literal>/usr/sbin/l_getidentity</literal> utility parses
  81               <literal>/etc/lustre/perm.conf</literal> to obtain the permission mask for a specified
  82             UID.</para>
  83           <para>The permission file format
  84             is:<screen>{<replaceable>nid</replaceable>} {<replaceable>uid</replaceable>} {<replaceable>perms</replaceable>}</screen>An
  85             asterisk (*) in the <replaceable>nid</replaceable> column or
  86               <replaceable>uid</replaceable> column matches any NID or UID respectively. When '*' is
  87             specified as the NID, it is used for the default permissions for all NIDS, unless
  88             permissions are specified for a particular NID.  In this case the specified permissions
  89             take precedence for that particular NID.  Valid values for
  90               <replaceable>perms</replaceable> are:<itemizedlist>
  91               <listitem>
  92                 <para><literal>setuid/setgid/setgrp/<replaceable>XXX</replaceable></literal> -
  93                   enables the corresponding <replaceable>perm</replaceable></para>
  94               </listitem>
  95               <listitem>
  96                 <para><literal>nosetuid/nosetgid/nosetgrp/no<replaceable>XXX</replaceable></literal>
  97                   - disables the corresponding <replaceable>perm</replaceable></para>
  98               </listitem>
  99             </itemizedlist>Permissions can be specified in a comma-separated list. When a
 100               <replaceable>perm</replaceable> and a <replaceable>noperm</replaceable> permission are
 101             listed in the same line, the <replaceable>noperm</replaceable> permission takes
 102             precedence. When they are listed on separate lines, the permission that appears later
 103             takes precedence.</para>
 104           <listitem>
 105             <?oxy_custom_start type="oxy_content_highlight" color="255,255,0"?>
 106             <para><?oxy_custom_end?>The <literal>/usr/sbin/l_getidentity</literal> utility can parse
 107                 <literal>/etc/lustre/perm.conf</literal> to obtain the permission mask for the
 108               specified UID.</para>
 109           </listitem>
 110           <listitem>
 111             <para>To avoid repeated upcalls, the MDS caches supplemental group information. Use
 112                 <literal>lctl set_param mdt.*.identity_expire=&lt;seconds></literal> to set the
 113               cache time. The default cache time is 600 seconds. The kernel waits for the upcall to
 114               complete (at most, 5 seconds) and takes the &quot;failure&quot; behavior as described. </para>
 115             <para>Set the wait time using <literal>lctl set_param
 116                 mdt.*.identity_acquire_expire=&lt;seconds></literal> to change the length of time
 117               that the kernel waits for the upcall to finish. Note that the client process is
 118               blocked during this time. The default wait time is 15 seconds.</para>
 119             <para>Cached entries are flushed using <literal>lctl set_param
 120                 mdt.${FSNAME}-MDT{xxxx}.identity_flush=0</literal>.</para>
 121           </listitem>
 122         </itemizedlist>
 123       </section>
 124     </section>
 125     <section remap="h3">
 126       <title>Parameters</title>
 127       <itemizedlist>
 128         <listitem>
 129           <para> Name of the MDS service</para>
 130         </listitem>
 131         <listitem>
 132           <para> Numeric UID</para>
 133         </listitem>
 134       </itemizedlist>
 135     </section>
 136     <section xml:id="dbdoclet.50438291_33759">
 137       <title>Data Structures</title>
 138       <screen>struct perm_downcall_data{
 139      __u64 pdd_nid;
 140      __u32 pdd_perm;
 141      __u32 pdd_padding;
 142 };
 143
 144 struct identity_downcall_data{
 145      __u32        idd_magic;
 146      :
 147      :</screen>
 148     </section>
 149   </section>
 150   <section xml:id="dbdoclet.50438291_73963">
 151     <title><indexterm><primary>programming</primary><secondary>l_getidentity</secondary></indexterm><literal>l_getidentity</literal> Utility</title>
 152     <para>The <literal>l_getidentity</literal> utility handles the Lustre supplementary group upcall
 153       by default as described in the previous section.</para>
 154     <section remap="h5">
 155       <title>Synopsis</title>
 156       <screen>l_getidentity ${FSNAME}-MDT{xxxx} {uid}</screen>
 157     </section>
 158     <section remap="h5">
 159       <title>Description</title>
 160       <para>The identity upcall file contains the path to an executable that is invoked to resolve a
 161         numeric UID to a group membership list. This utility opens
 162           <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info</literal>, completes the
 163           <literal>identity_downcall_data</literal> data structure (see <xref
 164           linkend="dbdoclet.50438291_33759"/>) and writes the data to the
 165           <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info</literal> pseudo file. The
 166         data is persisted with <literal>lctl set_param
 167           mdt.${FSNAME}-MDT{xxxx}.identity_info</literal>.</para>
 168       <para><literal>l_getidentity</literal> is the reference implementation of the user/group cache
 169         upcall.</para>
 170     </section>
 171     <section remap="h5">
 172       <title>Files</title>
 173       <para>
 174         <screen>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall</screen>
 175         <screen>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info</screen>
 176       </para>
 177     </section>
 178   </section>
 179 </chapter>