The kAFS Kernel-Userspace Interface

The pioctl Problem

There's a reserved system call for AFS (called afs) that's a multiplexor, one of the subfunctions of which is a path-based ioctl-equivalent (pioctl()). Unfortunately, Linus and various members of the Linux community hate pioctl() as it is highly abused. In OpenAFS, for example, various of its commands ignore the path they're given, so there's no way this will get into the Linux kernel.

This means that kAFS has to work around this lack, using a combination of:

Emulation of pioctl Commands Within kAFS

Command Purpose Proposed kAFS Implementation Kernel done? Comments
VIOC_FILE_CELL_NAME
VIOCIGETCELL
Get cell name the object is located within getxattr(path, "afs.cell") v4.13 Actually, I *really* need to dust off my extended-stat patches and also add an fsinfo syscall. fsinfo() would be able to return things like cell name, volume name, server name for AFS, CIFS, NFS, ...
fsinfo() with fsinfo_attr_cell_name Pending
? Determine in which volume the object is located getxattr(path, "afs.volume") v4.13
fsinfo() with fsinfo_attr_volume_name Pending
VIOCGETFID Get the fid getxattr(path, "afs.fid") v4.13
VIOCGETAL
VIOCSETAL 		Get/set acls on the object getxattr(path, "afs.acl")
setxattr(path, "afs.acl") 		v5.2 These get/set raw AFS3 ACL blobs; userspace toolage is required.
Get/set YFS acls on the object getxattr(path, "afs.yfs.acl")
setxattr(path, "afs.yfs.acl")
getxattr(path, "afs.yfs.vol_acl") 		v5.2 These get/set raw YFS ACL blobs; userspace toolage is required.
VIOCWHEREIS Determine on which servers the object is replicated fsinfo() with fsinfo_attr_server_name
fsinfo() with fsinfo_attr_server_address 		Pending This allows enumeration of the UUIDs and addresses of the servers backing a volume.
VIOCGETCACHEPARMS
VIOCSETCACHESIZE
Get/set caching attributes for the object, its volume, or everything fcachectl(int dirfd,
          const char *pathname,
          unsigned flags,
          const char *cmd,
          char *result,
          size_t *result_len); 		No New syscall as it can be applied to NFS and CIFS also. The cmd argument would be a string of the form:
"<command> <scope> [<key>=<val>]*"
e.g.
"flush volume"
"set file cache=pin"
flags would indicate the AT_* flags.
VIOCFLUSH
VIOCFLUSHCB
VIOC_FLUSHVOLUME
VIOC_FLUSHALL 		Flush the cache state (for the specified object, for the entire volume the object is in or for everything)
VIOCPREFETCH
Prefetch a file into the cache
VIOCGETVOLSTAT
VIOCSETVOLSTAT
Get/set volume state via the cache manager No
VIOC_AFS_CREATE_MT_PT
VIOC_AFS_DELETE_MT_PT
VIOC_AFS_STAT_MT_PT
VIOC_AFS_FLUSHMOUNT
Create, delete, get and flush information about mount points No Mountpoint operations are the tricky ones because we have to avoid triggering or crossing into an automount. However, there is a pathwalk control to help deal with that.
VIOC_AFS_SYSNAME Change the list of substitutions for @sys. echo x86_64 foo bar >/proc/fs/afs/sysname v4.17 An ordered list of substitutions is permitted. Each substitution is tried in turn.
VIOC_GET_WS_CELL Get/set the workstation cell and implement @cell substitution. cat /proc/fs/afs/rootcell
echo foo.bar.org \
>/proc/fs/afs/rootcell 		v4.17
VIOCGETCELL
VIOCNEWCELL
VIOC_NEWALIAS
VIOC_GETALIAS
Get/set cellservdb info cat /proc/fs/afs/cells
cat /proc/fs/afs/<cell>/vlservers
echo add your-file-system.com \  204.29.154.37 >/proc/fs/afs/cells 		Yes Possibly this should be deprecated in favour of using configfs, but it needs to be network-namespace aware, so perhaps not.
VIOC_GETSPREFS
VIOC_SETSPREFS
Get/set server preference rankings used to prefer one server instance over another Go through /proc/fs/afs/ No
afs(setpag)
VIOC_GETPAG
VIOCUNPAG
Get, set or unset process access group keyctl_join_session_keyring()
keyctl_session_to_parent()
keyctl_clear()
No
VIOCGETTOK
VIOCSETTOK
VIOCGETTOK2
VIOCSETTOK2
VIOCUNLOG
Get/set/delete token sets add_key()
keyctl_*()
No Might be worth adding an add_keys() syscall; this would load a token set as a keyring of keys. Would need to be able to automatically name keys.
VIOCGETRXKCRYPT
VIOCSETRXKCRYPT
Get/set encryption modes add_key() No Scope?
? Get the security class and mode used to obtain the status info and data for the current object from the remote server getxattr(path, "afs.sec_class")
getxattr(path, "afs.sec_mode")
 		No
VIOCNEWUUID Get/reset the cache manager's uuid /proc/fs/afs/uuid No
VIOC_RXSTAT_PROC
VIOC_RXSTAT_PEER
Get/reset RPC statistics for the server the object's volume is on or everything No Currently no stats kept since they're somewhat implementation-specific, but would make sense to go through /proc/fs/afs/ or /proc/net/rxrpc/.