[PATCH] afs.rst-updates.patch

Jeffrey E Altman jaltman at auristor.com
Sat Jul 6 11:35:05 PDT 2024 

Documentation/filesystems/afs.rst has not been substantially updated 
since 2018 [6f8880d8e681].  The Andrew File System Wikipedia article 
references afs.rst and implies that kAFS is functionaly incomplete and 
not ready for production use.  The attached patch updates the Overview 
and Compilation sections and adds a new Differences from IBM AFS/OpenAFS 
section.  Once merged the Wikipedia page can be updated.

Please consider the proposed changes as a suggested starting point.  
Feel free to revise the content as appopriate.

Jeffrey Altman


-------------- next part --------------
From 6d3191f5ee31a7b08c033d9aea492b9240c8967a Mon Sep 17 00:00:00 2001
From: Jeffrey Altman <jaltman at auristor.com>
Date: Sat, 6 Jul 2024 14:12:20 -0400
Subject: [PATCH] afs.rst updates

Update the overview text to provide more detail regarding what is
and is not supported by kAFS.  As well as describing some of the
differences from IBM AFS derived implementations.  The Wikipedia
Andrew_File_System article references the following sentence in
afs.rst to imply that the Linux AFS implementation is not ready
for production use: "It is under development and does not yet
provide the full feature set."  This rewrite removes this
sentence.

The list of Linux config options available for use when building
kAFS has been updated to include CONFIG_AF_RXRPC_IPV6,
CONFIG_DNS_RESOLVER, CONFIG_FSCACHE, CONFIG_FSCACHE_STATS,
and CONFIG_AFS_FSCACHE.

A new section entitled "Differences from IBM AFS/OpenAFS" has
been added.  It references the use of a super-block per AFS
volume by kAFS and the lack of an IBM AFS-compatible "pioctl"
interface.

Link: https://en.wikipedia.org/wiki/Andrew_File_System
Signed-off-by: Jeffrey Altman <jaltman at auristor.com>
---
 Documentation/filesystems/afs.rst | 126 +++++++++++++++++++++++++++---
 1 file changed, 116 insertions(+), 10 deletions(-)

diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst
index f15ba388bbde..1692c686c34f 100644
--- a/Documentation/filesystems/afs.rst
+++ b/Documentation/filesystems/afs.rst
@@ -14,26 +14,85 @@ kAFS: AFS FILESYSTEM
  - The cell database.
  - Security.
  - The @sys substitution.
+ - Differences from IBM AFS/OpenAFS.
 
 
 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:
+This filesystem provides a secure AFS filesystem driver developed
+independent of the IBM AFS 3.6 and OpenAFS source code.  kAFS provides
+users access to the /afs global filesystem namespace and permits AFS
+volumes to be locally mounted outside of /afs.
 
- (*) Security (currently only AFS kaserver and KerberosIV tickets).
+Implemented features include:
 
- (*) File reading and writing.
-
- (*) Automounting.
+ (*) Reading and writing.
 
  (*) Local caching (via fscache).
 
-It does not yet support the following AFS features:
+ (*) Direct I/O.
+
+ (*) Advisory file locking.
+
+ (*) Encryption and authentication (rxkad only).
+
+ (*) Automounting of mountpoints.
+
+ (*) Location service failover.
+
+ (*) AFSDB and SRV DNS record lookup.
+
+ (*) Volume replica failover.
+
+ (*) Busy volume retries.
+
+ (*) Volume relocation.
+
+ (*) Path substitution variables (@sys and @cell).
+
+ (*) Silly rename.
+
+ (*) Kernel trace points.
+
+AuriStor File System implemented features:
+
+ (*) 64-bit Volume IDs
+
+ (*) 96-bit Vnode IDs
+
+ (*) IPv6 support.
+
+ (*) Mandatory file locking.
+
+ (*) Per-file access control.
+
+ (*) Cross-directory hard links.
+
+ (*) Multi-factor access control lists.
+
+Features that need to be added:
+
+ (*) A method of removing an AFS mountpoint upon which
+     an AFS volume is mounted.
+
+ (*) Network namespacing.
+
+ (*) Notifications (inotify and friends).
+
+ (*) Userspace tool interface (substitute for pioctl).
+
+ (*) Enhanced authentication and encryption (RXGK).
+
+ (*) Callback channel security (AuriStorFS).
+
+ (*) Opaque directories (AuriStorFS).
+
+ (*) Whiteout files (AuriStorFS).
+
+ (*) Additional atomic rename modes including
+     NoReplace, Exchange, Whiteout (AuriStorFS).
 
- (*) pioctl() system call.
 
 
 Compilation
@@ -42,10 +101,18 @@ Compilation
 The filesystem should be enabled by turning on the kernel configuration
 options::
 
-	CONFIG_AF_RXRPC		- The RxRPC protocol transport
+	CONFIG_AF_RXRPC		- The RxRPC protocol transport (IPv4)
+	CONFIG_AF_RXRPC_IPV6	- The RxRPC protocol transport (IPv6)
 	CONFIG_RXKAD		- The RxRPC Kerberos security handler
+	CONFIG_DNS_RESOLVER	- Enable DNS AFSDB and SRV record upcalls
 	CONFIG_AFS_FS		- The AFS filesystem
 
+Filesystem caching can be enabled if desired::
+
+	CONFIG_FSCACHE		- Enable fscache module
+	CONFIG_FSCACHE_STATS	- Enable cache statistics
+	CONFIG_AFS_FSCACHE	- AFS object caching via fscache
+
 Additionally, the following can be turned on to aid debugging::
 
 	CONFIG_AF_RXRPC_DEBUG	- Permit AF_RXRPC debugging to be enabled
@@ -249,3 +316,42 @@ 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.
+
+Differences from IBM AFS/OpenAFS
+================================
+
+The kAFS implementation of /afs differs from the IBM AFS/OpenAFS
+in several notable ways.
+
+The IBM derived AFS implementations create a single superblock for
+the entire /afs file namespace.  kAFS creates a separate superblock
+for each AFS volume which appears as a unique device.  Therefore,
+accurate space usage and availability can be reported for each
+AFS volume whereas IBM derived AFS implementations fake the results.
+
+The IBM derived AFS implementations provide a path-based ioctl-
+equivalent ("pioctl") interface that permits user-space to query
+and/or modify:
+
+ (*) kernel module settings including workstation cell (@cell),
+     sysname lists (@sys), server preferences, encryption mode,
+     cache manager UUID.
+
+ (*) AFS ACLs
+
+ (*) AFS mountpoints
+
+ (*) AFS status information including FileID, cell name,
+     volume replication sites, volume quota, etc.
+
+ (*) Process Authentication Group (PAG) and Token management.
+
+ (*) Cache management.
+
+Linux does not provide a "pioctl" equivalent and kAFS does not
+attempt to implement the IBM AFS/OpenAFS "pioctl" functions.
+
+  https://registrar.central.org/pioctls.txt
+
+kAFS does provide equivalent functionality via a combination of
+/proc files, xattrs, ioctls, keyring operations, and fsinfo.
-- 
2.45.2

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4039 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.infradead.org/pipermail/linux-afs/attachments/20240706/57ef8926/attachment.p7s>

More information about the linux-afs mailing list