-<?xml version="1.0" encoding="UTF-8"?>
-<article version="5.0" xml:lang="en-US" xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink">
- <info>
- <title>Lustre Programming Interfaces</title>
- </info>
- <informaltable frame="none">
- <tgroup cols="2">
- <colspec colname="c1" colwidth="50*"/>
- <colspec colname="c2" colwidth="50*"/>
-
-
- <tbody>
- <row>
- <entry align="left"><para>Lustre 2.0 Operations Manual</para></entry>
- <entry align="right" valign="top"><para><link xl:href="index.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/toc01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/toc01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="UserUtilities_HTML.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/prev01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/prev01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="SettingLustreProperties_HTML.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/next01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/next01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="ix.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/index01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/index01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para><link xl:href=""/></para>
- <informaltable frame="none">
- <tgroup cols="1">
- <colspec colname="c1" colwidth="100*"/>
-
- <tbody>
- <row>
- <entry align="right"><para><anchor xml:id="dbdoclet.50438291_pgfId-874" xreflabel=""/>C H A P T E R 33</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <informaltable frame="none">
- <tgroup cols="1">
- <colspec colname="c1" colwidth="100*"/>
-
- <tbody>
- <row>
- <entry align="right"><para><anchor xml:id="dbdoclet.50438291_pgfId-5529" xreflabel=""/><anchor xml:id="dbdoclet.50438291_66186" xreflabel=""/>Lustre Programming Interfaces</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293209" xreflabel=""/>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>
- <itemizedlist><listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294898" xreflabel=""/><anchor xml:id="dbdoclet.50438291_85876" xreflabel=""/><link xl:href="LustreProgrammingInterfaces.html#50438291_32926">User/Group Cache Upcall</link></para>
+<?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">
+ <title xml:id="lustreprogramminginterfaces.title">Programming Interfaces</title>
+ <para>This chapter describes public programming interfaces to that can be
+ used to control various aspects of a Lustre file system from userspace.
+ This chapter includes the following sections:</para>
+ <itemizedlist>
+ <listitem>
+ <para><xref linkend="dbdoclet.identity_upcall"/></para>
</listitem>
-<listitem>
- <para> </para>
+ <listitem>
+ <para><xref linkend="dbdoclet.perm_downcall_data"/></para>
</listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1295238" xreflabel=""/><link xl:href="LustreProgrammingInterfaces.html#50438291_73963">l_getgroups Utility</link></para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-</itemizedlist>
- <informaltable frame="none">
- <tgroup cols="1">
- <colspec colname="c1" colwidth="100*"/>
- <tbody>
- <row>
- <entry><para><emphasis role="bold">Note -</emphasis><anchor xml:id="dbdoclet.50438291_pgfId-1294899" xreflabel=""/>Lustre programming interface man pages are found in the lustre/doc folder.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <section remap="h2">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293216" xreflabel=""/></title>
- <section remap="h2">
- <title>33.1 <anchor xml:id="dbdoclet.50438291_32926" xreflabel=""/>User/Group <anchor xml:id="dbdoclet.50438291_marker-1293215" xreflabel=""/>Cache Upcall</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293217" xreflabel=""/>This section describes user and group upcall.</para>
- <informaltable frame="none">
- <tgroup cols="1">
- <colspec colname="c1" colwidth="100*"/>
- <tbody>
- <row>
- <entry><para><emphasis role="bold">Note -</emphasis><anchor xml:id="dbdoclet.50438291_pgfId-1293379" xreflabel=""/>For information on a universal UID/GID, see <link xl:href="InstallingLustre.html#50438261_19503">Environmental Requirements</link>.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <section remap="h3">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293218" xreflabel=""/>33.1.1 Name</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293219" xreflabel=""/>Use /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall to look up a given user’s group membership.</para>
- </section>
- <section remap="h3">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293220" xreflabel=""/>33.1.2 Description</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293221" xreflabel=""/>The group upcall file contains the path to an executable that, when installed, is invoked to resolve a numeric UID to a group membership list. This utility should complete the mds_grp_downcall_data data structure (see <link xl:href="LustreProgrammingInterfaces.html#50438291_33759">Data Structures</link>) and write it to the /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info pseudo-file.</para>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293225" xreflabel=""/>For a sample upcall program, see lustre/utils/l_getgroups.c in the Lustre source distribution.</para>
- <section remap="h4">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293226" xreflabel=""/>33.1.2.1 Primary and Secondary Groups</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293227" xreflabel=""/>The mechanism for the primary/secondary group is as follows:</para>
- <itemizedlist><listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293228" xreflabel=""/> The MDS issues an upcall (set per MDS) to map the numeric UID to the supplementary group(s).</para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293229" xreflabel=""/> 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>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293230" xreflabel=""/> The default upcall is /usr/sbin/l_getidentity, 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 /etc/passwd, NIS, LDAP, etc. If necessary, the administrator can use a parse utility to set /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall. If the upcall interface is set to NONE, then upcall is disabled. The MDS uses the UID/GID/suppgid supplied by the client.</para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293231" xreflabel=""/> The default group upcall is set by mkfs.lustre. Use tunefs.lustre --param or echo{path}>/proc/fs/lustre/mds/{mdsname}/group_upcall</para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294341" xreflabel=""/> The Lustre administrator can specify permissions for a specific UID by configuring /etc/lustre/perm.conf on the MDS. As commented in lustre/utils/l_getidentity.c</para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-</itemizedlist>
- <screen><anchor xml:id="dbdoclet.50438291_pgfId-1294527" xreflabel=""/>/** permission file format is like this: * {nid} {uid} {perms} * * '*' nid \
-means any nid* '*' uid means any uid* the valid values for perms are:* setu\
-id/setgid/setgrp/rmtacl -- enable corresponding perm* nosetuid/nosetgid/nos\
-etgrp/normtacl -- disable corresponding perm* they can be listed together, \
-seperated by ',',* when perm and noperm are in the same line (item), noperm\
- is preferential,* when they are in different lines (items), the latter is \
-preferential,* '*' nid is as default perm, and is not preferential.*/
-</screen>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294343" xreflabel=""/>Currently, rmtacl/normtacl can be ignored (part of security functionality), and used for remote clients. The /usr/sbin/l_getidentity utility can parse /etc/lustre/perm.conf to obtain permission mask for specified UID.</para>
- <itemizedlist><listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294268" xreflabel=""/> To avoid repeated upcalls, the MDS caches supplemental group information. Use /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_expire to set the cache time (default is 600 seconds). The kernel waits for the upcall to complete (at most, 5 seconds) and takes the "failure" behavior as described. Set the wait time in /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_acquire_expire (default is 15 seconds). Cached entries are flushed by writing to /proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_flush.</para>
- </listitem>
-<listitem>
- <para> </para>
- </listitem>
-</itemizedlist>
- </section>
- </section>
- <section remap="h3">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293233" xreflabel=""/>33.1.3 Parameters</title>
- <itemizedlist><listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293234" xreflabel=""/> Name of the MDS service</para>
+ </itemizedlist>
+ <note>
+ <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
+ </note>
+ <section xml:id="dbdoclet.identity_upcall">
+ <title><indexterm>
+ <primary>programming</primary>
+ <secondary>upcall</secondary>
+ </indexterm>User/Group Upcall</title>
+ <para>This section describes the supplementary user/group upcall, which
+ allows the MDS to retrieve and verify the supplementary groups to which
+ a particular user is assigned. This avoids the need to pass all the
+ supplementary groups from the client to the MDS with every RPC.</para>
+ <note>
+ <para>For information about universal UID/GID requirements in a Lustre
+ file system environment, see
+ <xref xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="section_rh2_d4w_gk"/>.</para>
+ </note>
+ <section remap="h3">
+ <title>Synopsis</title>
+ <para>The MDS uses the utility as specified by
+ <literal>lctl get_param mdt.${FSNAME}-MDT{xxxx}.identity_upcall</literal>
+ to look up the supplied UID in order to retrieve the user's supplementary
+ group membership. The result is temporarily cached in the kernel (for
+ five minutes, by default) to avoid the overhead of calling into
+ userspace repeatedly.</para>
+ </section>
+ <section remap="h3">
+ <title>Description</title>
+ <para>The <literal>identity_upcall</literal> parameter contains the path
+ to an executable that is run to map a numeric UID to a group membership
+ list. This upcall executable opens the
+ <literal>mdt.${FSNAME}-MDT{xxxx}.identity_info</literal> parameter file
+ and writes the related <literal>identity_downcall_data</literal> data
+ structure (see <xref linkend="dbdoclet.perm_downcall_data"/>). The
+ upcall is configured with
+ <literal>lctl set_param mdt.${FSNAME}-MDT{xxxx}.identity_upcall</literal>.</para>
+ <para>The default identity upcall program installed is
+ <literal>lustre/utils/l_getidentity.c</literal> in the Lustre source
+ distribution.</para>
+ <section remap="h4">
+ <title>Primary and Secondary Groups</title>
+ <para>The mechanism for the primary/secondary group is as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>The MDS issues an upcall (set per MDS) to map the numeric
+ UID to the supplementary group(s).</para>
</listitem>
-<listitem>
- <para> </para>
+ <listitem>
+ <para>If there is no upcall or if there is an upcall and it fails,
+ one supplementary group at most will be added as supplied by the
+ client.</para>
</listitem>
-<listitem>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1293235" xreflabel=""/> Numeric UID</para>
+ <listitem>
+ <para>The default upcall <literal>/usr/sbin/l_getidentity</literal>
+ can interact with the user/group database on the MDS to map the
+ UID to the GID and supplementary GID. The user/group database
+ depends on how authentication is configured on the MDS, such as
+ local <literal>/etc/passwd</literal>, Network Information Service
+ (NIS), Lightweight Directory Access Protocol (LDAP), or SMB
+ Domain services, as configured. If the upcall interface is set
+ to NONE, then upcall is disabled, and the MDS uses only the UID,
+ GID, and one supplementary GID supplied by the client.</para>
</listitem>
-<listitem>
- <para> </para>
+ <listitem>
+ <para>The MDS will wait a limited time for the group upcall program
+ to complete, to avoid MDS threads and clients hanging due to
+ errors accessing a remote service node. The upcall must finish
+ within 30s before the MDS will continue without the supplementary
+ data. The upcall timeout can be set on the MDS using:
+ <literal>lctl set_param mdt.*.identity_acquire_expire=<replaceable>seconds</replaceable></literal></para>
</listitem>
-</itemizedlist>
- </section>
- <section remap="h3">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1293237" xreflabel=""/>33.1.4 <anchor xml:id="dbdoclet.50438291_33759" xreflabel=""/>Data Structures</title>
- <screen><anchor xml:id="dbdoclet.50438291_pgfId-1293240" xreflabel=""/>struct identity_downcall_data {
-<anchor xml:id="dbdoclet.50438291_pgfId-1293241" xreflabel=""/> __u32 idd_magic;
-<anchor xml:id="dbdoclet.50438291_pgfId-1293242" xreflabel=""/> __u32 idd_err;
-<anchor xml:id="dbdoclet.50438291_pgfId-1293243" xreflabel=""/> __u32 idd_uid;
-<anchor xml:id="dbdoclet.50438291_pgfId-1293244" xreflabel=""/> __u32 idd_gid;
-<anchor xml:id="dbdoclet.50438291_pgfId-1293245" xreflabel=""/> __u32 idd_nperms;
-<anchor xml:id="dbdoclet.50438291_pgfId-1294332" xreflabel=""/> struct perm_downcall_data idd_perms[N_PERMS_MAX];
-<anchor xml:id="dbdoclet.50438291_pgfId-1294322" xreflabel=""/> __u32 idd_ngroups;
-<anchor xml:id="dbdoclet.50438291_pgfId-1293246" xreflabel=""/> __u32 idd_groups[0];
-<anchor xml:id="dbdoclet.50438291_pgfId-1293247" xreflabel=""/>};
-</screen>
+ <listitem>
+ <para>The default group upcall is set permanently by
+ <literal>mkfs.lustre</literal>. To set a custom upcall for a
+ particular filesystem, use
+ <literal>tunefs.lustre --param</literal> or
+ <literal>lctl set_param -P mdt.<replaceable>FSNAME</replaceable>-MDT<replaceable>xxxx</replaceable>.identity_upcall=<replaceable>path</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para>The group downcall data is cached by the kernel to avoid
+ repeated upcalls for the same user slowing down the MDS. This
+ cache is expired from the kernel after 1200s (20 minutes) by
+ default. The cache age can be set on the MDS using:
+ <literal>lctl set_param mdt.*.identity_expire=<replaceable>seconds</replaceable></literal></para>
+ </listitem>
+ </itemizedlist>
</section>
</section>
- <section remap="h2">
- <title>33.2 l_getgroups<anchor xml:id="dbdoclet.50438291_73963" xreflabel=""/><anchor xml:id="dbdoclet.50438291_marker-1294565" xreflabel=""/> Utility</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294567" xreflabel=""/>The l_getgroups utility handles Lustre user/group cache upcall.</para>
- <section remap="h5">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1294568" xreflabel=""/>Synopsis</title>
- <screen><anchor xml:id="dbdoclet.50438291_pgfId-1294569" xreflabel=""/>l_getgroups [-v] [-d|mdsname] uid]
-<anchor xml:id="dbdoclet.50438291_pgfId-1294570" xreflabel=""/>l_getgroups [-v] -s
-</screen>
- </section>
- <section remap="h5">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1294571" xreflabel=""/>Description</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294572" xreflabel=""/>The group upcall file contains the path to an executable that, when properly installed, is invoked to resolve a numeric UID to a group membership list. This utility should complete the mds_grp_downcall_data data structure (see Data structures) and write it to the /proc/fs/lustre/mds/mds-service/group_info pseudo-file.</para>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294573" xreflabel=""/>l_getgroups is the reference implementation of the user/group cache upcall.</para>
- </section>
- <section remap="h5">
- <title><anchor xml:id="dbdoclet.50438291_pgfId-1294574" xreflabel=""/>Files</title>
- <para><anchor xml:id="dbdoclet.50438291_pgfId-1294575" xreflabel=""/>/proc/fs/lustre/mds/mds-service/group_upcall</para>
- <!--
-Begin SiteCatalyst code version: G.5.
--->
- <!--
-End SiteCatalyst code version: G.5.
--->
- <informaltable frame="none">
- <tgroup cols="3">
- <colspec colname="c1" colwidth="33*"/>
- <colspec colname="c2" colwidth="33*"/>
- <colspec colname="c3" colwidth="33*"/>
-
-
-
- <tbody>
- <row>
- <entry align="left"><para>Lustre 2.0 Operations Manual</para></entry>
- <entry align="right"><para>821-2076-10</para></entry>
- <entry align="right" valign="top"><para><link xl:href="index.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/toc01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/toc01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="UserUtilities_HTML.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/prev01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/prev01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="SettingLustreProperties_HTML.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/next01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/next01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link><link xl:href="ix.html"><inlinemediaobject><imageobject role="html">
- <imagedata contentdepth="26" contentwidth="30" fileref="./shared/index01.gif" scalefit="1"/>
- </imageobject>
-<imageobject role="fo">
- <imagedata contentdepth="100%" contentwidth="" depth="" fileref="./shared/index01.gif" scalefit="1" width="100%"/>
- </imageobject>
-</inlinemediaobject></link></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para><link xl:href=""/></para>
- <para><link xl:href="copyright.html">Copyright</link> © 2011, Oracle and/or its affiliates. All rights reserved.</para>
- </section>
+ <section xml:id="dbdoclet.perm_downcall_data">
+ <title>Data Structures</title>
+ <screen>struct perm_downcall_data {
+ __u64 pdd_nid;
+ __u32 pdd_perm;
+ __u32 pdd_padding;
+};
+
+struct identity_downcall_data{
+ __u32 idd_magic;
+ :
+ :</screen>
</section>
</section>
-</article>
+</chapter>
git://git.whamcloud.com / doc / manual.git / blobdiff