LustreProgrammingInterfaces.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <!-- This document was created with Syntext Serna Free. --><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">
   3   <title xml:id="lustreprogramminginterfaces.title">Lustre Programming Interfaces</title>
   4   <para>This chapter describes public programming interfaces to control various aspects of Lustre from userspace. These interfaces are generally not guaranteed to remain unchanged over time, although we will make an effort to notify the user community well in advance of major changes. This chapter includes the following section:</para>
   5   <itemizedlist>
   6     <listitem>
   7       <para><xref linkend="dbdoclet.50438291_32926"/></para>
   8     </listitem>
   9     <listitem>
  10       <para><xref linkend="dbdoclet.50438291_73963"/></para>
  11     </listitem>
  12   </itemizedlist>
  13   <note>
  14     <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
  15   </note>
  16   <section xml:id="dbdoclet.50438291_32926">
  17     <title><indexterm><primary>programming</primary><secondary>upcall</secondary></indexterm>User/Group Cache Upcall</title>
  18     <para>This section describes user and group upcall.</para>
  19     <note>
  20       <para>For information on a universal UID/GID, see <xref linkend="dbdoclet.50438261_19503"/>.</para>
  21     </note>
  22     <section remap="h3">
  23       <title>Name</title>
  24       <para>Use <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall</literal> to look up a given user&apos;s group membership.</para>
  25     </section>
  26     <section remap="h3">
  27       <title>Description</title>
  28       <para>The group upcall file contains the path to an executable that is invoked to resolve a numeric UID to a group membership list. This utility opens <literal>/proc/fs/lustre/mdt/{mdtname}/identity_info</literal> and writes the releated <literal>identity_downcall_data</literal> data structure (see <xref linkend="dbdoclet.50438291_33759"/>). The data is persisted with <literal>lctl set_param mdt.{mdtname}.identity_info</literal>.</para>
  29       <para>For a sample upcall program, see <literal>lustre/utils/l_getidentity.c</literal> in the Lustre source distribution.</para>
  30       <section remap="h4">
  31         <title>Primary and Secondary Groups</title>
  32         <para>The mechanism for the primary/secondary group is as follows:</para>
  33         <itemizedlist>
  34           <listitem>
  35             <para>The MDS issues an upcall (set per MDS) to map the numeric UID to the supplementary group(s).</para>
  36           </listitem>
  37           <listitem>
  38             <para>If there is no upcall or if there is an upcall and it fails, supplementary groups will be added as supplied by the client (as they are now).</para>
  39           </listitem>
  40           <listitem>
  41             <para>The default upcall is <literal>/usr/sbin/l_getidentity</literal>, which can interact with the user/group database to obtain UID/GID/suppgid. The user/group database depends on authentication configuration, and can be local <literal>/etc/passwd</literal>, NIS, LDAP, etc. If necessary, the administrator can use a parse utility to set <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall</literal>. If the upcall interface is set to NONE, then upcall is disabled. The MDS uses the UID/GID/suppgid supplied by the client.</para>
  42           </listitem>
  43           <listitem>
  44               <para>The default group upcall is set by mkfs.lustre. Use <literal>tunefs.lustre --param</literal> or <literal>lctl set_param mdt.{mdtname}.identity_upcall={path}</literal></para>
  45           </listitem>
  46           <listitem>
  47             <para>The Lustre administrator can specify permissions for a specific UID by configuring <literal>/etc/lustre/perm.conf</literal> on the MDS. As commented in <literal>lustre/utils/l_getidentity.c</literal></para>
  48           </listitem>
  49         </itemizedlist>
  50         <screen>
  51 /*
  52 * permission file format is like this:
  53 * {nid} {uid} {perms}
  54 *
  55 * &apos;*&apos; nid means any nid
  56 * &apos;*&apos; uid means any uid
  57 * the valid values for perms are:
  58 * setuid/setgid/setgrp/rmtacl -- enable corresponding perm
  59 * nosetuid/nosetgid/nosetgrp/normtacl -- disable corresponding perm
  60 * they can be listed together, seperated by &apos;,&apos;,
  61 * when perm and noperm are in the same line (item), noperm is preferential,
  62 * when they are in different lines (items), the latter is preferential,
  63 * &apos;*&apos; nid is as default perm, and is not preferential.*/</screen>
  64         <para>Currently, <literal>rmtacl/normtacl</literal> can be ignored (part of security functionality), and used for remote clients. The /usr/sbin/l_getidentity utility can parse <literal>/etc/lustre/perm.conf</literal> to obtain permission mask for specified UID.</para>
  65         <itemizedlist>
  66           <listitem>
  67             <para> To avoid repeated upcalls, the MDS caches supplemental group information. Use <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_expire</literal> to set the cache time (default is 600 seconds). The kernel waits for the upcall to complete (at most, 5 seconds) and takes the &quot;failure&quot; behavior as described. Set the wait time in <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_acquire_expire</literal> (default is 15 seconds). Cached entries are flushed by writing to <literal>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_flush</literal>.</para>
  68           </listitem>
  69         </itemizedlist>
  70       </section>
  71     </section>
  72     <section remap="h3">
  73       <title>Parameters</title>
  74       <itemizedlist>
  75         <listitem>
  76           <para> Name of the MDS service</para>
  77         </listitem>
  78         <listitem>
  79           <para> Numeric UID</para>
  80         </listitem>
  81       </itemizedlist>
  82     </section>
  83     <section xml:id="dbdoclet.50438291_33759">
  84       <title>Data Structures</title>
  85       <screen>struct identity_downcall_data {
  86    __u32           idd_magic;
  87    __u32           idd_err;
  88    __u32           idd_uid;
  89    __u32           idd_gid;
  90    __u32           idd_nperms;
  91    struct perm_downcall_data idd_perms[N_PERMS_MAX];
  92    __u32           idd_ngroups;
  93    __u32           idd_groups[0];
  94 };</screen>
  95     </section>
  96   </section>
  97   <section xml:id="dbdoclet.50438291_73963">
  98     <title><indexterm><primary>programming</primary><secondary>l_getidentity</secondary></indexterm><literal>l_getidentity</literal> Utility</title>
  99     <para>The <literal>l_getidentity</literal> utility handles Lustre user/group cache upcall.</para>
 100     <section remap="h5">
 101       <title>Synopsis</title>
 102       <screen>l_getidentity [-v] [-d|mdsname] uid]
 103 l_getidentity [-v] -s</screen>
 104     </section>
 105     <section remap="h5">
 106       <title>Description</title>
 107       <para>The group upcall file contains the path to an executable that is invoked to resolve a numeric UID to a group membership list. This utility opens <literal>/proc/fs/lustre/mdt/{mdtname}/identity_info</literal> and writes the releated <literal>identity_downcall_data</literal> data structure (see <xref linkend='dbdoclet.50438291_33759'/>). The data is persisted with <literal>lctl set_param mdt.{mdtname}.identity_info</literal>.</para>
 108       <para>l_getidentity is the reference implementation of the user/group cache upcall.</para>
 109     </section>
 110     <section remap="h5">
 111       <title>Files</title>
 112       <para><literal>/proc/fs/lustre/mdt/{mdt-name}/identity_upcall</literal></para>
 113     </section>
 114   </section>
 115 </chapter>