[LUDOC-158] 33.1 "User/Group Cache Upcall" and 33.2 "l_getidentity Utility" need to be updated (Ch 33)

• Status: Resolved
• Project: Lustre Documentation
• Type: Bug
• Priority: Minor
• Reporter: Linda Bebernes (Inactive)
• Assignee: Linda Bebernes (Inactive)
• Resolution: Fixed
• Labels: QContent
• Business Value: 3
• Severity: 3

Description

Notes from Andreas:
"33.1. User/Group Cache Upcall" and "33.2.
l_getgroups Utility", with the caveat that this text was only partially updated for Lustre 2.x. The "l_getgroups" upcall was renamed "l_getidentity", and the /proc file is changed also, some (fragmented) updates to the text (... is typewriter font, [] are changes):

33.1. User/Group Cache Upcall

[This section describes the supplementary user and group upcall, which allows the
MDS to retrieve and verify the supplementary groups that a particular user is
assigned. This avoids the need to pass all of the supplementary groups from the
client to the MDS on every RPC.]

33.1.1 Name

The MDS will use the utility given by [{{lctl get_param mdt.$MDT.identity_upcall}}]
to look up the supplied UID in order to retrieve the user's supplementary group
membership.

33.1.2 Description

The [identity] upcall file ...
... This utility should [fill in the {{identity_downcall_data}}] data structure ...

For a sample upcall program, see [{{lustre/utils/l_getidentity.c}}] in ...

33.1.2.1

... and it fails, [at most one] supplementary group will be added as supplied
by the client.

Use tunefs.lustre --param=[mdt.identity_upcall=<upcall_program> to set the
upcall at format time.

[please just remove rmtacl and normtacl entirely from the description and text]

... [The {{/usr/sbin/l_getidentity}}] utility ...

Use [lctl set_param mdt.*.identity_expire=<seconds>] to set the cache time ...
Set the wait time via [lctl set_param
mdt.*.identity_acquire_expire=<seconds>]
to change the length of time that the kernel will wait for the upcall to finish.
Note that the client process will be blocked during this time. Cached entries
are flushed via [lctl set_param mdt.$MDT.identity_flush=0].

33.1.4 Data Structures

struct perm_downcall_data

{ __u64 pdd_nid; __u32 pdd_perm; __u32 pdd_padding; }

;

struct identity_downcall_data {
__u32 idd_magic;
:
:

33.2 [l_getidenity] Utility

The [l_getidentity] utility handles the Lustre supplementary group upcall by default,
as described in the preceding section.

33.2.1 Synopsis

l_getidentity

{mdtname}

{uid}

33.2.2 Description

The identity upcall file ... should complete the [{{identity_downcall_data}}] ...
... write it to the [{{/proc/fs/lustre/mdt/$MDT/identity_info}}] pseudo file.

[l_getidentity] is the reference ...

33.2.3 Files

/proc/fs/lustre/mdt/$MDT/identity_upcall
/proc/fs/lustre/mdt/$MDT/identity_info

Comments

[Linda Bebernes (Inactive)]

33.1. User/Group Cache Upcall
This section describes the supplementary user and group upcall,...
Should the heading for this sectionbe changed to "User/Group Upcall" or is it better to say "supplementary user and group cache upcall..." for consistency?

33.1.1 Name Is the heading for this section still appropriate?
The MDS will use the utility given by [{{lctl get_param mdt.$MDT.identity_upcall}}]
to look up the supplied UID in order to retrieve the user's supplementary group
membership.

33.1.2.1
Use tunefs.lustre --param=[mdt.identity_upcall=<upcall_program> to set the
upcall at format time.
Where does this go?

Can you provide a replacement for this code example?
/*

• permission file format is like this:
• {nid} {uid} {perms}
• '*' nid means any nid
• '*' uid means any uid
• the valid values for perms are:
• setuid/setgid/setgrp/rmtacl – enable corresponding perm
• nosetuid/nosetgid/nosetgrp/normtacl – disable corresponding perm
• they can be listed together, separated 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. */

33.1.3 Parameters
Parameters for ... What are these parameter for? ... are:

• Name of the MDS service
• Numeric UID

33.1.4 Data Structures
Did you intend for this to replace what's currently in the manual, or be added to it?
struct perm_downcall_data

{ __u64 pdd_nid; __u32 pdd_perm; __u32 pdd_padding; }

;

struct identity_downcall_data {
__u32 idd_magic;
:
:
Are the colons above supposed to be included?

Are the following edits to content OK? Should the last sentence be deleted? (don't worry about formatting - I'll take care of that)
33.2.2 Description
The identity upcall file contains the path to an executable that is invoked to resolve a numeric UID to a group membership list. This utility opens /proc/fs/lustre/mdt/

{mdtname}/identity_info, completes the identity_downcall_data data structure (see "Data Structures") and writes the data to the /proc/fs/lustre/mdt/$MDT/identity_info pseudo file. The data is persisted with lctl set_param mdt.{mdtname}

.identity_info.

[Linda Bebernes (Inactive)]

Changes are ready for review at http://review.whamcloud.com/#/c/6608/

[Linda Bebernes (Inactive)]

Changes approved and merged.