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