요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
====================
kAFS: AFS FILESYSTEM
====================
.. Contents:
- Overview.
- Usage.
- Mountpoints.
- Dynamic root.
- Proc filesystem.
- The cell database.
- Security.
- The @sys substitution.
Overview
========
This filesystem provides a fairly simple secure AFS filesystem driver. It is
under development and does not yet provide the full feature set. The features
it does support include:
(*) Security (currently only AFS kaserver and KerberosIV tickets).
(*) File reading and writing.
(*) Automounting.
(*) Local caching (via fscache).
It does not yet support the following AFS features:
(*) pioctl() system call.
Compilation
===========
The filesystem should be enabled by turning on the kernel configuration
options::
CONFIG_AF_RXRPC - The RxRPC protocol transport
CONFIG_RXKAD - The RxRPC Kerberos security handler
CONFIG_AFS_FS - The AFS filesystem
Additionally, the following can be turned on to aid debugging::
CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
They permit the debugging messages to be turned on dynamically by manipulating
the masks in the following files::
/sys/module/af_rxrpc/parameters/debug
/sys/module/kafs/parameters/debug
Usage
=====
When inserting the driver modules the root cell must be specified along with a
list of volume location server IP addresses::
modprobe rxrpc
modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
The first module is the AF_RXRPC network protocol driver. This provides the
RxRPC remote operation protocol and may also be accessed from userspace. See:
Documentation/networking/rxrpc.rst
The second module is the kerberos RxRPC security driver, and the third module
is the actual filesystem driver for the AFS filesystem.
Once the module has been loaded, more modules can be added by the following
procedure::
echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
Where the parameters to the "add" command are the name of a cell and a list of
volume location servers within that cell, with the latter separated by colons.
Filesystems can be mounted anywhere by commands similar to the following::
mount -t afs "%cambridge.redhat.com:root.afs." /afs
mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
mount -t afs "#root.afs." /afs
mount -t afs "#root.cell." /afs/cambridge
Where the initial character is either a hash or a percent symbol depending on
whether you definitely want a R/W volume (percent) or whether you'd prefer a
R/O volume, but are willing to use a R/W volume instead (hash).
The name of the volume can be suffixes with ".backup" or ".readonly" to
specify connection to only volumes of those types.
The name of the cell is optional, and if not given during a mount, then the
named volume will be looked up in the cell specified during modprobe.
Additional cells can be added through /proc (see later section).
Mountpoints
===========
AFS has a concept of mountpoints. In AFS terms, these are specially formatted
symbolic links (of the same form as the "device name" passed to mount). kAFS
presents these to the user as directories that have a follow-link capability
(i.e.: symbolic link semantics). If anyone attempts to access them, they will
automatically cause the target volume to be mounted (if possible) on that site.
Automatically mounted filesystems will be automatically unmounted approximately
twenty minutes after they were last used. Alternatively they can be unmounted
directly with the umount() system call.
Manually unmounting an AFS volume will cause any idle submounts upon it to be
culled first. If all are culled, then the requested volume will also be
unmounted, otherwise error EBUSY will be returned.
This can be used by the administrator to attempt to unmount the whole AFS tree
mounted on /afs in one go by doing::
umount /afs
Dynamic Root
============
A mount option is available to create a serverless mount that is only usable
for dynamic lookup. Creating such a mount can be done by, for example::
mount -t afs none /afs -o dyn
This creates a mount that just has an empty directory at the root. Attempting
to look up a name in this directory will cause a mountpoint to be created that
looks up a cell of the same name, for example::
ls /afs/grand.central.org/
Proc Filesystem
===============
The AFS module creates a "/proc/fs/afs/" directory and populates it:
(*) A "cells" file that lists cells currently known to the afs module and
their usage counts::
[root@andromeda ~]# cat /proc/fs/afs/cells
USE NAME
3 cambridge.redhat.com
(*) A directory per cell that contains files that list volume location
servers, volumes, and active servers known within that cell::
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
USE ADDR STATE
4 172.16.18.91 0
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
ADDRESS
172.16.18.91
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
USE STT VLID[0] VLID[1] VLID[2] NAME
1 Val 20000000 20000001 20000002 root.afs
The Cell Database
=================
The filesystem maintains an internal database of all the cells it knows and the
IP addresses of the volume location servers for those cells. The cell to which
the system belongs is added to the database when modprobe is performed by the
"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
the kernel command line.
Further cells can be added by commands similar to the following::
echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
No other cell database operations are available at this time.
Security
========
Secure operations are initiated by acquiring a key using the klog program. A
very primitive klog program is available at:
https://people.redhat.com/~dhowells/rxrpc/klog.c
This should be compiled by::
make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
And then run as::
./klog
Assuming it's successful, this adds a key of type RxRPC, named for the service
and cell, e.g.: "afs@<cellname>". This can be viewed with the keyctl program or
by cat'ing /proc/keys::
[root@andromeda ~]# keyctl show
Session Keyring
-3 --alswrv 0 0 keyring: _ses.3268
2 --alswrv 0 0 \_ keyring: _uid.0
111416553 --als--v 0 0 \_ rxrpc: [email protected]
Currently the username, realm, password and proposed ticket lifetime are
compiled into the program.
It is not required to acquire a key before using AFS facilities, but if one is
not acquired then all operations will be governed by the anonymous user parts
of the ACLs.
If a key is acquired, then all AFS operations, including mounts and automounts,
made by a possessor of that key will be secured with that key.
If a file is opened with a particular key and then the file descriptor is
passed to a process that doesn't have that key (perhaps over an AF_UNIX
socket), then the operations on the file will be made with key that was used to
open the file.
The @sys Substitution
=====================
The list of up to 16 @sys substitutions for the current network namespace can
be configured by writing a list to /proc/fs/afs/sysname::
[root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
or cleared entirely by writing an empty list::
[root@andromeda ~]# echo >/proc/fs/afs/sysname
The current list for current network namespace can be retrieved by::
[root@andromeda ~]# cat /proc/fs/afs/sysname
foo
amd64_linux_26
When @sys is being substituted for, each element of the list is tried in the
order given.
By default, the list will contain one item that conforms to the pattern
"<arch>_linux_26", amd64 being the name for x86_64.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
kAFS 개요와 지원 기능
1-38kAFS는 비교적 단순하고 보안 기능을 갖춘 AFS filesystem driver입니다. 개발 중이어서 전체 AFS 기능을 제공하지는 않습니다.
현재 AFS kaserver와 Kerberos IV ticket을 이용한 security, file read/write, automount, FS-Cache를 통한 local caching을 지원합니다. 아직 `pioctl()` system call은 지원하지 않습니다.
원문의 지원·미지원 항목을 구분했습니다.
.. SPDX-License-Identifier: GPL-2.0
====================
kAFS: AFS FILESYSTEM
====================
.. Contents:
- Overview.
- Usage.
- Mountpoints.
- Dynamic root.
- Proc filesystem.
- The cell database.
- Security.
- The @sys substitution.
Overview
========
This filesystem provides a fairly simple secure AFS filesystem driver. It is
under development and does not yet provide the full feature set. The features
it does support include:
(*) Security (currently only AFS kaserver and KerberosIV tickets).
(*) File reading and writing.
(*) Automounting.
(*) Local caching (via fscache).
It does not yet support the following AFS features:
(*) pioctl() system call.
kernel 구성과 동적 debug
39-60filesystem을 사용하려면 `CONFIG_AF_RXRPC`로 RxRPC protocol transport, `CONFIG_RXKAD`로 RxRPC Kerberos security handler, `CONFIG_AFS_FS`로 AFS filesystem을 활성화합니다.
debug를 돕기 위해 `CONFIG_AF_RXRPC_DEBUG`와 `CONFIG_AFS_DEBUG`를 추가할 수 있습니다. 각각 AF_RXRPC와 AFS debugging을 runtime에 켤 수 있게 합니다.
debug message는 `/sys/module/af_rxrpc/parameters/debug`와 `/sys/module/kafs/parameters/debug`의 mask를 조작해 동적으로 켜고 끕니다.
build option과 runtime control path를 연결합니다.
Compilation
===========
The filesystem should be enabled by turning on the kernel configuration
options::
CONFIG_AF_RXRPC - The RxRPC protocol transport
CONFIG_RXKAD - The RxRPC Kerberos security handler
CONFIG_AFS_FS - The AFS filesystem
Additionally, the following can be turned on to aid debugging::
CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
They permit the debugging messages to be turned on dynamically by manipulating
the masks in the following files::
/sys/module/af_rxrpc/parameters/debug
/sys/module/kafs/parameters/debug
root cell 등록과 volume mount
61-105driver module을 넣을 때 root cell과 volume location server IP 목록을 지정해야 합니다. 예는 `modprobe rxrpc` 뒤 `modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91`을 실행하는 것입니다.
AF_RXRPC network protocol driver는 RxRPC remote operation protocol을 제공하고 userspace에서도 접근할 수 있습니다. 자세한 내용은 `Documentation/networking/rxrpc.rst`를 참조합니다. Kerberos RxRPC security driver와 실제 AFS filesystem driver가 그 위에서 동작합니다.
module을 올린 뒤 `echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells`로 cell을 추가할 수 있습니다. `add`의 첫 인자는 cell name이고 뒤에는 colon으로 구분한 volume location server 목록이 옵니다.
AFS volume은 `mount -t afs "%cambridge.redhat.com:root.afs." /afs` 또는 `mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge`처럼 mount합니다. cell name을 생략한 `#root.afs.`와 `#root.cell.`은 `modprobe` 때 지정한 root cell에서 찾습니다.
device name의 첫 문자가 `%`이면 반드시 read/write volume을 요구합니다. `#`이면 read-only volume을 선호하되 필요하면 read/write volume도 사용합니다. volume name에 `.backup` 또는 `.readonly` suffix를 붙이면 해당 type volume에만 연결합니다.
mount device name의 prefix와 suffix 의미입니다.
Usage
=====
When inserting the driver modules the root cell must be specified along with a
list of volume location server IP addresses::
modprobe rxrpc
modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
The first module is the AF_RXRPC network protocol driver. This provides the
RxRPC remote operation protocol and may also be accessed from userspace. See:
Documentation/networking/rxrpc.rst
The second module is the kerberos RxRPC security driver, and the third module
is the actual filesystem driver for the AFS filesystem.
Once the module has been loaded, more modules can be added by the following
procedure::
echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
Where the parameters to the "add" command are the name of a cell and a list of
volume location servers within that cell, with the latter separated by colons.
Filesystems can be mounted anywhere by commands similar to the following::
mount -t afs "%cambridge.redhat.com:root.afs." /afs
mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
mount -t afs "#root.afs." /afs
mount -t afs "#root.cell." /afs/cambridge
Where the initial character is either a hash or a percent symbol depending on
whether you definitely want a R/W volume (percent) or whether you'd prefer a
R/O volume, but are willing to use a R/W volume instead (hash).
The name of the volume can be suffixes with ".backup" or ".readonly" to
specify connection to only volumes of those types.
The name of the cell is optional, and if not given during a mount, then the
named volume will be looked up in the cell specified during modprobe.
Additional cells can be added through /proc (see later section).
AFS mountpoint와 자동 unmount
106-128AFS mountpoint는 `mount`에 전달하는 device name과 같은 형식의 특수 symbolic link입니다. kAFS는 이를 follow-link capability가 있는 directory, 즉 symbolic-link semantics를 가진 directory로 표시합니다.
누군가 mountpoint에 접근하면 가능한 경우 target volume이 그 위치에 자동 mount됩니다. 자동 mount된 filesystem은 마지막 사용 약 20분 뒤 자동 unmount되며 `umount()`로 직접 내릴 수도 있습니다.
AFS volume을 수동 unmount하면 그 위의 idle submount를 먼저 제거합니다. 모두 제거되면 요청한 volume도 unmount하고, 남은 submount가 있으면 `EBUSY`를 반환합니다. 관리자는 `umount /afs` 한 번으로 전체 AFS tree 제거를 시도할 수 있습니다.
접근부터 idle unmount 또는 EBUSY까지의 흐름입니다.
Mountpoints
===========
AFS has a concept of mountpoints. In AFS terms, these are specially formatted
symbolic links (of the same form as the "device name" passed to mount). kAFS
presents these to the user as directories that have a follow-link capability
(i.e.: symbolic link semantics). If anyone attempts to access them, they will
automatically cause the target volume to be mounted (if possible) on that site.
Automatically mounted filesystems will be automatically unmounted approximately
twenty minutes after they were last used. Alternatively they can be unmounted
directly with the umount() system call.
Manually unmounting an AFS volume will cause any idle submounts upon it to be
culled first. If all are culled, then the requested volume will also be
unmounted, otherwise error EBUSY will be returned.
This can be used by the administrator to attempt to unmount the whole AFS tree
mounted on /afs in one go by doing::
umount /afs
serverless dynamic root
129-143`dyn` mount option은 server 없이 dynamic lookup만 가능한 mount를 만듭니다. 예는 `mount -t afs none /afs -o dyn`입니다.
처음에는 root에 빈 directory만 있습니다. 이 directory에서 이름을 lookup하면 같은 이름의 cell을 찾는 mountpoint를 동적으로 만듭니다. 예를 들어 `ls /afs/grand.central.org/`는 `grand.central.org` cell lookup을 유발합니다.
빈 root가 cell별 mountpoint를 만드는 과정입니다.
Dynamic Root
============
A mount option is available to create a serverless mount that is only usable
for dynamic lookup. Creating such a mount can be done by, for example::
mount -t afs none /afs -o dyn
This creates a mount that just has an empty directory at the root. Attempting
to look up a name in this directory will cause a mountpoint to be created that
looks up a cell of the same name, for example::
ls /afs/grand.central.org/
`/proc/fs/afs` runtime 정보
144-169AFS module은 `/proc/fs/afs/` directory를 만듭니다. `cells` file은 현재 알려진 cell과 usage count를 `USE NAME` 형식으로 표시합니다.
cell마다 별도 directory가 생기며 그 안의 `servers`, `vlservers`, `volumes` file이 해당 cell에서 알려진 active server, volume location server, volume 정보를 보여 줍니다.
예에서 `servers`는 usage, address, state를, `vlservers`는 address를, `volumes`는 usage, status, 세 volume ID와 name을 출력합니다.
각 proc file의 정보 범위를 정리했습니다.
Proc Filesystem
===============
The AFS module creates a "/proc/fs/afs/" directory and populates it:
(*) A "cells" file that lists cells currently known to the afs module and
their usage counts::
[root@andromeda ~]# cat /proc/fs/afs/cells
USE NAME
3 cambridge.redhat.com
(*) A directory per cell that contains files that list volume location
servers, volumes, and active servers known within that cell::
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
USE ADDR STATE
4 172.16.18.91 0
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
ADDRESS
172.16.18.91
[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
USE STT VLID[0] VLID[1] VLID[2] NAME
1 Val 20000000 20000001 20000002 root.afs
cell database 추가
170-186filesystem은 알고 있는 모든 cell과 각 cell의 volume location server IP를 내부 database에 유지합니다.
system이 속한 cell은 module 방식에서는 `rootcell=` argument로, built-in 방식에서는 kernel command line의 `kafs.rootcell=`로 database에 추가됩니다.
추가 cell은 `echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells`로 넣습니다. 현재는 이외의 cell database operation을 제공하지 않습니다.
boot/module 설정과 runtime 추가 경로입니다.
The Cell Database
=================
The filesystem maintains an internal database of all the cells it knows and the
IP addresses of the volume location servers for those cells. The cell to which
the system belongs is added to the database when modprobe is performed by the
"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
the kernel command line.
Further cells can be added by commands similar to the following::
echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
No other cell database operations are available at this time.
RxRPC key와 operation credential
187-228secure operation은 `klog` program으로 key를 얻어 시작합니다. primitive 구현은 `https://people.redhat.com/~dhowells/rxrpc/klog.c`에 있으며 `make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"`로 compile하고 `./klog`로 실행합니다.
성공하면 service와 cell 이름을 딴 `afs@<cellname>`이라는 RxRPC type key가 생깁니다. `keyctl show` 또는 `/proc/keys`에서 확인할 수 있습니다. 현재 username, realm, password와 요청 ticket lifetime은 program에 compile되어 있습니다.
AFS를 사용하기 전에 key를 반드시 얻을 필요는 없지만 key가 없으면 모든 operation은 ACL의 anonymous user 부분을 따릅니다. key를 얻으면 그 key를 보유한 주체가 수행하는 mount와 automount를 포함한 모든 AFS operation이 해당 key로 보호됩니다.
특정 key로 file을 열고 file descriptor를 그 key가 없는 process에 전달해도, 이후 file operation은 file을 열 때 사용한 key로 수행됩니다. AF_UNIX socket으로 descriptor를 전달하는 경우도 같습니다.
klog key 획득과 file descriptor의 key 유지 관계입니다.
Security
========
Secure operations are initiated by acquiring a key using the klog program. A
very primitive klog program is available at:
https://people.redhat.com/~dhowells/rxrpc/klog.c
This should be compiled by::
make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
And then run as::
./klog
Assuming it's successful, this adds a key of type RxRPC, named for the service
and cell, e.g.: "afs@<cellname>". This can be viewed with the keyctl program or
by cat'ing /proc/keys::
[root@andromeda ~]# keyctl show
Session Keyring
-3 --alswrv 0 0 keyring: _ses.3268
2 --alswrv 0 0 \_ keyring: _uid.0
111416553 --als--v 0 0 \_ rxrpc: [email protected]
Currently the username, realm, password and proposed ticket lifetime are
compiled into the program.
It is not required to acquire a key before using AFS facilities, but if one is
not acquired then all operations will be governed by the anonymous user parts
of the ACLs.
If a key is acquired, then all AFS operations, including mounts and automounts,
made by a possessor of that key will be secured with that key.
If a file is opened with a particular key and then the file descriptor is
passed to a process that doesn't have that key (perhaps over an AF_UNIX
socket), then the operations on the file will be made with key that was used to
open the file.
`@sys` substitution 목록
229-251현재 network namespace의 `@sys` substitution은 최대 16개이며 `/proc/fs/afs/sysname`에 목록을 써서 구성합니다. 예는 `echo foo amd64_linux_26 >/proc/fs/afs/sysname`입니다.
빈 목록을 쓰는 `echo >/proc/fs/afs/sysname`으로 모두 지울 수 있고 `cat /proc/fs/afs/sysname`으로 현재 목록을 읽습니다.
`@sys`를 치환할 때 목록의 각 원소를 주어진 순서대로 시험합니다. 기본 목록에는 `<arch>_linux_26` pattern을 따르는 항목 하나가 있으며 x86_64의 이름은 `amd64`입니다.
namespace별 후보 목록을 순서대로 적용합니다.
The @sys Substitution
=====================
The list of up to 16 @sys substitutions for the current network namespace can
be configured by writing a list to /proc/fs/afs/sysname::
[root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
or cleared entirely by writing an empty list::
[root@andromeda ~]# echo >/proc/fs/afs/sysname
The current list for current network namespace can be retrieved by::
[root@andromeda ~]# cat /proc/fs/afs/sysname
foo
amd64_linux_26
When @sys is being substituted for, each element of the list is tried in the
order given.
By default, the list will contain one item that conforms to the pattern
"<arch>_linux_26", amd64 being the name for x86_64.
요약·해설
afs.rst:1-251kAFS는 RxRPC와 Kerberos key를 이용해 AFS cell의 volume을 mount하고, special mountpoint·dynamic root·FS-Cache·`@sys` substitution을 제공합니다.
cell 등록부터 authenticated volume access까지의 관계입니다.