add an example to the home page about authentication

[tmbdev]

The example on the diod home page disables authentication.

But that leaves first time users like myself wondering how authentication is supposed to work. I looked through the diod documentation, 9p documentation, and googled around a bit, and didn't see much that was relevant. It looks like there is another channel or service involved, but I couldn't figure out anything more than that.

So, I think it would be great if you could add an example of how authenticated exports are supposed to work.

[garlick]

That's a good idea, and sorry for the sparse documentation.

One reason why this was not documented is that at the time is it required a kernel patch to work. I'll have to check if that is still the case. Also, the only authentication mechanism supported is based on munge which is common in the HPC world but less so in other places. Anyway, I'll try to write something up as time permits, thanks.

[garlick]

Here's the old diod wiki page from google code on the topic of "security". I may have misspoken about the kernel patch being required to use munge (clearly I need to refresh my memory on this stuff)

DIOD security

diod 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.

Although 9P contains a framework for external authentication, it seemed more straightforward to simply pass the MUNGE credential in as the value of the uname= mount option on the client (v9fs) side. A 9P attach message is generated at mount time containing this credential in the uname field. If the initial authenticated attach is successful, subsequent attach messages on the same socket without MUNGE credentials are accepted, provided they originate from the same user name, or the original user was root.

public mounts

When a file system is mounted with

diodmount host:path dir

v9fs receives the following mount options:

access=user,uname=<root MUNGE cred>

In this mode, root is authenticated at mount time, and each new user that accesses the file system is introduced with a new attach, without credential, but since the original attach was root, it is accepted.

On server side, requests can be associated by fid with the original attach. The setfsuid, setfsgid, and setgroups system calls are used to change the identity of the server work crew thread (running as root) before handling a particular I/O request. The host file system then accepts or denies the request based on this identity.

private mounts

When a file system is mounted with

diodmount -p -u user host:path dir

v9fs receives the following mount options:

access=<uid of user>,uname=<user MUNGE cred>

Other users are unconditionally denied access to the file system by the client so only the initial attach is required.

In this mode the server can actually run all the time as the user. diodmount arranges this by first contacting the diodctl superserver, requesting that it run an instance of the diod server for user and obtaining a port to contact it on. The new diod server drops its root privileges, then only accepts attach messages from user.

It is worth mentioning that modern Linux kernels implement private file system namespaces similar to those described in The Use of Name Spaces in Plan 9 by Pike et al. With linux unshare system calls in the right places, it is possible to have multiple users sharing a compute node, each with a private set of diod mounts that are unmounted implicitly when their job terminates.

diodctl

The diodctl superserver implements a 9P synthetic file system. Its purpose is to spawn private instances of diod on demand that can be shared across multiple clients. diodctl runs as root and accepts MUNGE authentication just like diod. It contains three synthetic files: ctl, server, and exports.

diodmount requests a private server for user by:

• mounting the diodctl file system, which generates a MUNGE-authenticated attach for user
• writing "new" to ctl
• reading the port number of the private server from server
• mounting the private server as user

The "new" request is a no-op if a server is already running as user. Otherwise, diodctl spawns an instance of diod as root, passing user's uid on its command line. diod drops its root identity and becomes uid, then awaits mount requests.

The exports file simply provides a mechanism for diodmount to list the available exports. In the future, other synthetic files may be added to diodctl, e.g. to facilitate performance monitoring or batch system management of I/O resources.

other security

In addition to MUNGE authentication, diod and diodctl access can be limited by a configurable listen address list, configurable file system exports, and TCP wrapper support.