Skip to content

change the default access mode to "client" and add SECURITY section to diod(8) #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mergify merged 4 commits into from
Oct 31, 2025
Merged

change the default access mode to "client" and add SECURITY section to diod(8) #157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a3b561f
diod(8): add SECURITY description
garlick Oct 30, 2025
11fdb15
mount.diod: use access=client as the default
garlick Oct 30, 2025
fdc1ae5
mount.diod(8): update mount options
garlick Oct 30, 2025
5a3ae78
testsuite: update mount options
garlick Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 68 additions & 2 deletions man/diod.8.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,7 @@ diod \- distributed I/O daemon
.I "[OPTIONS]"
.SH DESCRIPTION
.B diod
is the distributed I/O daemon server, which
implements I/O forwarding on Linux clusters.
is a 9P2000.L file server.
.LP
Configuration is read from the diod.conf (5) config file.
Some configuration can be overridden on the command line, as described below.
Expand Down Expand Up @@ -48,6 +47,7 @@ This option overrides the \fIexportopts\fR setting in diod.conf (5).
.I "-n, --no-auth"
This option allows users to attach without security credentials.
It overrides the \fIauth_required\fR setting in diod.conf (5).
See SECURITY below.
.TP
.I "-H, --no-hostname-lookup"
This option disables hostname lookups.
Expand Down Expand Up @@ -90,6 +90,72 @@ Set the debug mask. The bit values are:
.TP
.I "-c, --config-file PATH"
Set config file path.
.SH SECURITY
\fBdiod\fR optionally uses MUNGE for authentication.
Briefly, a MUNGE credential is a user's uid and gid plus optional payload,
encrypted using a secret shared between client and server, then base64
encoded.
.LP
The 9P2000.L authentication sequence with MUNGE looks like this:
.sp 1
.nf
Tauth afid uname aname n_uname
Rauth aqid
Twrite afid offset count <munge cred>
Rwrite count
Tattach fid afid uname aname n_uname
Rattach qid
Tclunk afid
Rclunk
.fi
.LP
\fITauth\fR and \fITwrite\fR authenticate \fIuname\fR to the server on
\fIafid\fR, which, if the server accepts the credential, can then be used
in the \fITattach\fR to obtain access to the root of a file system represented
by \fIaname\fR as the \fIuname\fR user. The server knows that all accesses
to fids walked from the attachment fid are being performed by \fIuname\fR.
.LP
If authentication is disabled in the server, the \fITauth\fR may be skipped
and an \fIafid\fR of -1 may be presented in the \fITattach\fR.
.LP
It should be noted that even when authentication is enabled, network
connections between client and server are not protected from eavesdropping
or other attacks. It is best to use \fBdiod\fR only on networks that are
physically secure.
.LP
When the server is running as an unprivileged user, including when it starts
as root but drops that capability because it is squashing all requests down
to one user, all its file operations are performed as that user. This is
the simplest and safest mode for \fBdiod\fR to operate in from a security
standpoint.
.LP
Multi-user support is intended to be paired with the Linux v9fs client
and makes assumptions in the interest of correct functioning with v9fs
that may be surprising, notably:
.IP 1.
After \fITattach\fR is accepted for \fIuname=root\fR on a given connection,
subsequent \fITattach\fR requests as other users on the same connection will
be accepted without authentication (\fIafid\fR set to -1).
.IP 2.
Server worker threads handling a request on behalf of a user call setfsuid (2)
and setfsgid (2) to switch to the user's credentials. Supplementary groups
are also loaded, but only if the server determines that it can do so
in a thread-safe manner. A warning is issued at server startup if it cannot.
.IP 3.
Server worker threads handling a request on behalf of a non-root user on
a connection authenticated as root set \fBCAP_DAC_OVERRIDE\fR, \fBCAP_CHOWN\fR,
and \fBCAP_FOWNER\fR. The v9fs client is assumed to be performing access
checks. This largely works around complications that arise when supplementary
groups cannot be loaded.
.LP
Since the v9fs client does not know how to authenticate with MUNGE,
mount.diod (8) establishes the server connection and performs the
authentication exchange and an initial \fITattach\fR as root, then passes
the open file descriptor into the kernel with the mount (2) system call.
The kernel v9fs client then re-introduces itself as root with \fIafid\fR
set to -1. As noted above this \fITattach\fR and subsequent ones on this
connection are accepted by the server by virtue of the initial authenticated
root attachment.
.SH "FILES"
@X_SBINDIR@/diod
.br
Expand Down
58 changes: 26 additions & 32 deletions man/mount.diod.8.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,11 @@ Connect from a socket bound to a port in the range of 512-1023,
available to root only. This can be used in conjunction with the
\fIprivport\fR export option.
.SH MOUNT OPTIONS
The following file system specific mount options are handled by
\fBmount.diod\fR.
For a complete list of v9fs mount options, refer to the kernel
documentation at https://docs.kernel.org/filesystems/9p.html.
Some common options are described below.
.TP
.I "aname=name"
.I "aname=PATH"
The aname is the path of the exported file system on the server.
It can be specified in the mount spec in \fIhost:aname\fR format
like NFS, or it can be specified with this option.
Expand All @@ -66,16 +67,17 @@ Note that "ctl" must be explicitly exported.
.I "uname=USERNAME"
The user name to authenticate to the \fBdiod\fR server.
If neither \fIuname\fR nor \fIaccess\fR are specified,
\fIuname=root,access=user\fR is assumed.
\fIuname=root,access=client\fR is assumed.
.TP
.I "access=user"
The client allows any user to access the file system and enforces traditional
UNIX access controls. Each new user attaches to the server.
.I "access=client"
The client allows any user to access the file system and enforces access
control. Each new user attaches to the server.
Requires \fIuname=root\fR.
.TP
.I "access=client,posixacl"
The client allows any user to access the file system and enforces POSIX ACLs.
Only the authenticated user attaches to the server.
.I "access=user"
The same as \fIaccess=client\fR, but a weaker guarantee that the client
performs access control. \fBdiod\fR users are encouraged to use
\fIaccess=client\fR.
Requires \fIuname=root\fR.
.TP
.I "access=UID"
Expand All @@ -86,47 +88,39 @@ Only the authenticated user attaches to the server.
The client allows any user to access the filesystem.
Only the authenticated user attaches to the server.
.TP
.I "port=n"
.I "posixacl"
Enforce POSIX access control lists.
Requires \fIuname=root\fR and \fIaccess=client\fR.
.TP
.I "port=N"
Connect to the \fIdiod\fR server on the specified port.
The default is the IANA-assigned 9pfs port 564.
.TP
.I "trans=name"
.I "trans=fd"
Select a transport.
\fBmount.diod\fR only supports \fItrans=fd\fR
because of its strategy for authentication.
.TP
.I "rfdno=n,wfdno=n"
.I "rfdno=N,wfdno=N"
The file descriptor for reading and writing with \fItrans=fd\fR.
If set, \fBmount.diod\fR assumes this file descriptor is already
connected to a \fBdiod\fR server and ignores \fIhost\fR in the
device specification, and the \fIport=n\fR option.
.TP
.I "msize=n"
.I "msize=N"
The msize is the max 9P packet payload size.
The default is 65512 (65536-24)
.TP
.I "version=name"
.I "version=9p20000.L"
Select 9P protocol version.
\fBdiod\fR only supports \fI9p2000.L\fR.
.TP
.I "cache=mode"
Specify a caching policy. By default, no caches are used.
If \fIcache=loose\fR, no attempts are made at consistency.
This mode is intended for exclusive, read-only mounts.
If \fIcache=fscache\fR, use FS-Cache for a persistent, read-only
cache backend.
.TP
.I "cachetag"
In the context of \fIcache=fscache\fR, select the cache tag
to use for this session.
Cache tags for existing cache sessions are listed in /sys/fs/9p/caches.
.TP
.I "nodevmap"
Do not map special files. Represent them as normal files.
This can be used to share devices/named pipes/sockets between
hosts.
.I "cache=MODE"
Specify a caching policy.
Cache modes include \fInone\fR (default), \fIreadahead\fR, \fImmap\fR,
\fIloose\fR, and \fIfscache.
.TP
.I "debug=n"
.I "debug=MASK"
Specifies debug level for the kernel 9p module. The debug level is a bitmask.
.br
0x01 = display verbose error messages
Expand Down
9 changes: 4 additions & 5 deletions src/cmd/mount.diod.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ main (int argc, char *argv[])
goto done;
}

/* Ensure uname and access are set, and to diod-compatible values.
/* Ensure uname and access are set.
* The uname user becomes the euid which will be used by munge auth.
*/
_parse_uname_access (o);
Expand Down Expand Up @@ -356,15 +356,14 @@ _parse_uname_access (Opt o)

if (!uname && !access) {
opt_addf (o, "uname=%s", "root");
opt_addf (o, "access=%s", "user");
opt_addf (o, "access=%s", "client");
}
else if (!uname || !access) {
msg_exit (
"access,uname mount options must be set\n"
"Common examples:\n"
" -o uname=root,access=user Multi-user with UNIX access controls\n"
" -o uname=root,access=client,posixacl Multi-user with POSIX ACLs\n"
" -o uname=USERNAME,access=UID Single-user access");
" -o uname=root,access=client Multi-user\n"
" -o uname=USERNAME,access=UID Single-user");
}
}

Expand Down
8 changes: 4 additions & 4 deletions t/t0012-v9fs-multiuser.t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ test_expect_success 'create export/mount directories' '
test_expect_success 'wait for server socket' '
waitsock $DIOD_SOCKET 30
'
test_expect_success 'mount filesystem with access=user on mnt' '
$mountcmd -oaname=$exportdir,$mountopts,access=user \
test_expect_success 'mount filesystem with access=client on mnt' '
$mountcmd -oaname=$exportdir,$mountopts,access=client \
$DIOD_SOCKET mnt
'
test_expect_success STAT 'create a file' '
Expand Down Expand Up @@ -77,8 +77,8 @@ test_expect_success DIODMOUNT 'mount helper works with unix domain socket, no au
test_expect_success DIODMOUNT 'unmount mnt2' '
$umountcmd mnt2
'
test_expect_success DIODMOUNT 'mount helper allows -oaccess=client' '
$SUDO $PATH_MOUNT_DIOD -n -oaccess=client,uname=root \
test_expect_success DIODMOUNT 'mount helper allows -oaccess=user' '
$SUDO $PATH_MOUNT_DIOD -n -oaccess=user,uname=root \
$DIOD_SOCKET:$exportdir mnt2
'
test_expect_success 'unmount mnt2' '
Expand Down
7 changes: 2 additions & 5 deletions t/t0013-v9fs-acl.t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,18 +35,15 @@ test_under_diod unixsocketroot \
# gnome probes for .Trash, autorun.inf, etc asynchronously on new mounts,
# causing umount to fail with EBUSY if still in progress. Therefore --lazy.
umountcmd="$SUDO umount --lazy"
mountcmd="$SUDO mount -n -t 9p"
mountopts="trans=unix,uname=$(id -un)"

test_expect_success 'create export/mount directories' '
mkdir -p exp mnt
'
test_expect_success 'wait for server socket' '
waitsock $DIOD_SOCKET 30
'
test_expect_success 'mount filesystem with access=client,posixacl on mnt' '
$mountcmd -oaname=$exportdir,$mountopts,access=client,posixacl \
$DIOD_SOCKET mnt
test_expect_success 'mount filesystem with -o posixacl on mnt' '
$SUDO $PATH_MOUNT_DIOD -n -o posixacl $DIOD_SOCKET:$exportdir mnt
'
test_expect_success 'create a test file and setfacl -m u:root:r' '
touch mnt/testfile &&
Expand Down
7 changes: 2 additions & 5 deletions t/t0023-rsync.t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,18 +36,15 @@ test_under_diod unixsocketroot \
# gnome probes for .Trash, autorun.inf, etc asynchronously on new mounts,
# causing umount to fail with EBUSY if still in progress. Therefore --lazy.
umountcmd="$SUDO umount --lazy"
mountcmd="$SUDO mount -n -t 9p"
mountopts="trans=unix,uname=$(id -un)"

test_expect_success 'create export/mount directories' '
mkdir -p exp mnt
'
test_expect_success 'wait for server socket' '
waitsock $DIOD_SOCKET 30
'
test_expect_success 'mount filesystem with access=user' '
$mountcmd -oaname=$exportdir,$mountopts,access=user \
$DIOD_SOCKET mnt
test_expect_success 'mount filesystem with access=client' '
$SUDO $PATH_MOUNT_DIOD -n $DIOD_SOCKET:$exportdir mnt
'
test_expect_success 'rsync /etc to mnt/etc' '
mkdir -p mnt/etc &&
Expand Down