NFS ID Mapper | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Mapping 흐름

nfs-idmapper.rst:1-78

NFS는 `id_resolver` 요청을 먼저 request-key infrastructure로 처리하고, 설정이 없을 때 legacy `rpc.idmap` daemon으로 fallback합니다.

구성	동작
우선 경로	`/sbin/request-key`와 generic request-key cache
Fallback	Legacy `rpc.idmap` daemon과 NFS idmap cache
설정	`/etc/request-key.conf`의 `id_resolver` rule
Helper	`/usr/sbin/nfs.idmap`과 keyutils interface

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 =============

2 NFS ID Mapper

3 =============

5 Id mapper is used by NFS to translate user and group ids into names, and to

6 translate user and group names into ids. Part of this translation involves

7 performing an upcall to userspace to request the information. There are two

8 ways NFS could obtain this information: placing a call to /sbin/request-key

9 or by placing a call to the rpc.idmap daemon.

11 NFS will attempt to call /sbin/request-key first. If this succeeds, the

12 result will be cached using the generic request-key cache. This call should

13 only fail if /etc/request-key.conf is not configured for the id_resolver key

14 type, see the "Configuring" section below if you wish to use the request-key

15 method.

17 If the call to /sbin/request-key fails (if /etc/request-key.conf is not

18 configured with the id_resolver key type), then the idmapper will ask the

19 legacy rpc.idmap daemon for the id mapping. This result will be stored

20 in a custom NFS idmap cache.

23 Configuring

24 ===========

26 The file /etc/request-key.conf will need to be modified so /sbin/request-key can

27 direct the upcall. The following line should be added:

29 ``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...``

30 ``#====== ======= =============== =============== ===============================``

31 ``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600``

34 This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap.

35 The last parameter, 600, defines how many seconds into the future the key will

36 expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout

37 is not specified, nfs.idmap will default to 600 seconds.

39 id mapper uses for key descriptions::

41 uid: Find the UID for the given user

42 gid: Find the GID for the given group

43 user: Find the user name for the given UID

44 group: Find the group name for the given GID

46 You can handle any of these individually, rather than using the generic upcall

47 program. If you would like to use your own program for a uid lookup then you

48 would edit your request-key.conf so it look similar to this:

50 ``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...``

51 ``#====== ======= =============== =============== ===============================``

52 ``create id_resolver uid:* * /some/other/program %k %d 600``

53 ``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600``

56 Notice that the new line was added above the line for the generic program.

57 request-key will find the first matching line and corresponding program. In

58 this case, /some/other/program will handle all uid lookups and

59 /usr/sbin/nfs.idmap will handle gid, user, and group lookups.

61 See Documentation/security/keys/request-key.rst for more information

62 about the request-key function.

65 nfs.idmap

66 =========

68 nfs.idmap is designed to be called by request-key, and should not be run "by

69 hand". This program takes two arguments, a serialized key and a key

70 description. The serialized key is first converted into a key_serial_t, and

71 then passed as an argument to keyctl_instantiate (both are part of keyutils.h).

73 The actual lookups are performed by functions found in nfsidmap.h. nfs.idmap

74 determines the correct function to call by looking at the first part of the

75 description string. For example, a uid lookup description will appear as

76 "uid:user@domain".

78 nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise.

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

ID mapper 경로

1-22

NFS ID mapper는 user·group ID를 name으로, user·group name을 ID로 변환합니다. 일부 변환은 정보를 요청하는 userspace upcall을 사용하며 NFS는 `/sbin/request-key` 또는 `rpc.idmap` daemon으로 정보를 얻을 수 있습니다.

NFS는 먼저 `/sbin/request-key`를 호출합니다. 성공하면 generic request-key cache에 결과를 저장합니다. `/etc/request-key.conf`에 `id_resolver` key type이 구성되지 않은 경우에만 이 호출이 실패해야 합니다.

`/sbin/request-key`가 실패하면 idmapper는 legacy `rpc.idmap` daemon에 mapping을 요청하고 결과를 custom NFS idmap cache에 저장합니다.

Generic request-key 설정

23-38

`/sbin/request-key`가 upcall을 전달하도록 `/etc/request-key.conf`에 다음 rule을 추가합니다.

#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...
#======	=======	===============	===============	===============================
create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600

이 rule은 모든 `id_resolver` 요청을 `/usr/sbin/nfs.idmap`으로 보냅니다. 마지막 `600`은 key가 expire할 때까지의 초이며 optional입니다. 생략하면 `nfs.idmap`은 기본 600초를 사용합니다.

Key description 종류

39-45

ID mapper는 다음 key description prefix를 사용합니다.

uid:  Find the UID for the given user
gid:  Find the GID for the given group
user:  Find the user  name for the given UID
group:  Find the group name for the given GID

Prefix	Lookup
`uid:`	주어진 user의 UID 찾기
`gid:`	주어진 group의 GID 찾기
`user:`	주어진 UID의 user name 찾기
`group:`	주어진 GID의 group name 찾기

개별 lookup program 지정

46-63

Generic upcall program 대신 description별 program을 지정할 수 있습니다. 예를 들어 `uid` lookup만 자체 program으로 처리하려면 다음처럼 더 구체적인 rule을 generic rule보다 위에 둡니다.

#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...
#======	=======	===============	===============	===============================
create	id_resolver	uid:*	*		/some/other/program %k %d 600
create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600

`request-key`는 처음 일치하는 line의 program을 사용합니다. 따라서 이 예에서 `/some/other/program`은 모든 `uid` lookup을, `/usr/sbin/nfs.idmap`은 `gid`, `user`, `group` lookup을 처리합니다.

Request-key function의 자세한 내용은 `Documentation/security/keys/request-key.rst`를 참고합니다.

`nfs.idmap` 동작

64-78

`nfs.idmap`은 `request-key`가 호출하도록 설계됐으며 수동으로 실행하면 안 됩니다. Serialized key와 key description 두 인자를 받고, serialized key를 `key_serial_t`로 변환해 `keyctl_instantiate`에 전달합니다. 둘 다 `keyutils.h`에 속합니다.

실제 lookup은 `nfsidmap.h`의 function이 수행합니다. `nfs.idmap`은 description string의 첫 부분을 보고 호출할 function을 선택하며, `uid` lookup description의 예는 `uid:user@domain`입니다.

Key를 instantiate했으면 `nfs.idmap`은 0을 반환하고, 그렇지 않으면 non-zero를 반환합니다.