Lustre Programming Interfaces (man2)

C H A P T E R 29

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:

User/Group Cache Upcall

29.1 User/Group Cache Upcall

This section describes user and group upcall.

Note - For information on a universal UID/GID, see Environmental Requirements.

29.1.1 Name

Use /proc/fs/lustre/mds/mds-service/group_upcall to look up a given user’s group membership.

29.1.2 Description

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.

For a sample upcall program, see lustre/utils/l_getgroups.c in the Lustre source distribution.

29.1.2.1 Primary and Secondary Groups

The mechanism for the primary/secondary group is as follows:

The MDS issues an upcall (set per MDS) to map the numeric UID to the supplementary group(s).

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

The default upcall is /usr/sbin/l_getgroups, which uses the Lustre group-supplied upcall. It looks up the UID in /etc/passwd, and if it finds the UID, it looks for supplementary groups in /etc/group for that username. You are free to enhance l_getgroups to look at an external database for supplementary groups information.

The default group upcall is set by mkfs.lustre. To set the upcall, use echo {path} > /proc/fs/lustre/mds/{mdsname}/group_upcall or tunefs.lustre --param.

To avoid repeated upcalls, the MDS caches supplemental group information. Use /proc/fs/lustre/mds/{mdsname}/group_expire to set the cache time (default is 300 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/mds/{mdsname}/group_acquire_expire. Cached entries are flushed by writing to /proc/fs/lustre/mds/{mdsname}/group_flush.

29.1.3 Parameters

Name of the MDS service

Numeric UID

29.1.4 Data structures

#include <lustre/lustre_user.h>
#define MDS_GRP_DOWNCALL_MAGIC 0x6d6dd620
struct mds_grp_downcall_data {
	__u32		mgd_magic;
	__u32		mgd_err;
	__u32		mgd_uid;
	__u32		mgd_gid;
	__u32		mgd_ngroups;
	__u32		mgd_groups[0];
};