-<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>