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
8 <para><xref linkend="dbdoclet.50438291_32926"/></para>
11 <para><xref linkend="dbdoclet.50438291_73963"/></para>
15 <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
17 <section xml:id="dbdoclet.50438291_32926">
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
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>
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
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>
49 <title>Primary and Secondary Groups</title>
50 <para>The mechanism for the primary/secondary group is as follows:</para>
53 <para>The MDS issues an upcall (set per MDS) to map the numeric UID to the supplementary
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>
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
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>
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>
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
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>
92 <para><literal>setuid/setgid/setgrp/<replaceable>XXX</replaceable></literal> -
93 enables the corresponding <replaceable>perm</replaceable></para>
96 <para><literal>nosetuid/nosetgid/nosetgrp/no<replaceable>XXX</replaceable></literal>
97 - disables the corresponding <replaceable>perm</replaceable></para>
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>
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>
111 <para>To avoid repeated upcalls, the MDS caches supplemental group information. Use
112 <literal>lctl set_param mdt.*.identity_expire=<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 "failure" behavior as described. </para>
115 <para>Set the wait time using <literal>lctl set_param
116 mdt.*.identity_acquire_expire=<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>
126 <title>Parameters</title>
129 <para> Name of the MDS service</para>
132 <para> Numeric UID</para>
136 <section xml:id="dbdoclet.50438291_33759">
137 <title>Data Structures</title>
138 <screen>struct perm_downcall_data{
144 struct identity_downcall_data{
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>
155 <title>Synopsis</title>
156 <screen>l_getidentity ${FSNAME}-MDT{xxxx} {uid}</screen>
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
174 <screen>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_upcall</screen>
175 <screen>/proc/fs/lustre/mdt/${FSNAME}-MDT{xxxx}/identity_info</screen>