Configuring a Linux Client for NFSv4.1 with Kerberos

This section describes how to configure a Linux client for using NFSv4.1 with Kerberos.

Note
Qumulo Core supports only Linux for using NFSv4.1 with Kerberos.

Linux systems implement Kerberos support as a series of loosely related packages and configuration files. For this reason, configuration depends on the Linux distribution and version. This section refers to tools, packages, dæmons, configuration files, and other elements in Ubuntu 18.04 LTS.

Joining a Linux Client to a Domain

There are two common ways of joining a Linux client to an Active Directory (AD) domain automatically, by using samba or realmd. Both methods require creating the /etc/krb5.conf configuration file and defining a default domain and the relationships between domains and realms.

Configuring the /etc/krb5.conf File

The following is an example configuration for joining a domain.

[libdefaults]
    default_realm = MY-DOMAIN.EXAMPLE.COM

[realms]
    MY-DOMAIN.EXAMPLE.COM = {
        kdc = my-domain.example.com:88
        admin_server = my-domain.example.com:749
    }

[domain_realm]
    my-domain.example.com = MY-DOMAIN.EXAMPLE.COM
    .my-domain.exmaple.com = MY-DOMAIN.EXAMPLE.COM

To Join a Linux Client to a Domain by using samba

samba is a suite of Linux tools that provides Windows-like functionality on Linux. The net ads join command creates a machine account on the domain.

To specify how the domain-join process behaves, edit the /etc/samba/smb.conf file. For example:

workgroup = my-domain
server role = member server
realm = my-domain.example.com
kerberos method = system keytab

To join the domain, run the net ads join command. For example:

$ net ads join my-domain.example.com -U Administrator

samba doesn’t create configuration files. Configure the sssd and idmapd tools manually. For more information, see Mapping External Identities to Linux Identities.

To Join a Linux Client to a Domain by using realmd

realmd is a tool that allows managing realm-based authentication. It can be somewhat more difficult to use than samba. However, it creates a more complete configuration. For example, it configures the sssd tool during the domain-join process.

To join a domain, run the realm join command. For example:

$ realm join my-domain.example.com -U Administrator

Configure the sssd and idmapd tools manually. For more information, see Mapping External Identities to Linux Identities.

To Configure DNS and Service Principal Name (SPN)

Kerberos relies on DNS to identify machines involved in authentication. NFS clients and servers require DNS A records for forward-DNS look-ups and PTR records for reverse-DNS look-ups.

After you configure DNS, check DNS resolution from your client. For example:
```
$ nslookup my-client-machine.my-domain.example.com
```
In addition to DNS configuration, Linux clients require a standard host SPN on the machine account created while joining the domain. We recommend configuring the SPN by using the setspn command on the domain controller after the join procedure. For example:

Note
Running this command resets the SPN to the default value for your machine.
```
setspn -r my-client_machine
```

Mapping External Identities to Linux Identities

During the ID mapping process, a Linux system converts external identities to Linux identities.

For Qumulo Core, external identities are equivalent to Kerberos principals.
For Linux, identities are simple integers: UIDs and GIDs.

Note
Because Linux can’t use complex external identities in system calls, a Linux system must perform identity conversion before operating on files.

ID mapping is bidirectional. A system call, such as chown, that takes a UID or GID as input requires mapping the UID or GID be mapped to a domain user or group before passing it to your Qumulo cluster over NFS.

A system call, such as stat, that returns a UID or GID, requires that the domain user or group that returned from your Qumulo cluster over NFS be converted to a UID or GID before the system can present it to the user.

Configuring Active Directory Authentication by using sssd

sssd (System Security Services Daemon) is a tool responsible for managing authentication with external providers in Linux. To use NFSv4.1 with Kerberos, you must configure sssd with AD as the identity provider.

If you join domains by using samba, you must create the /etc/sssd.conf file.
If you join domains by using realmd, you might already have a /etc/sssd.conf file. For detailed configuration information, see sssd-ldap in the Linux documentation.

In the following example, the sssd.conf file configures basic ID mapping for AD.

[sssd]
domains = my-domain.example.com
config_file_version = 2
services = nss, pam

[domain/my-domain.example.com]
ad_domain = my-domain.example.com
krb5_realm = MY_DOMAIN.EXAMPLE.COM
cache_credentials = True
id_provider = ad
krb5_store_password_if_offline = True
default_shell = /bin/bash
ldap_id_mapping = False
use_fully_qualified_names = False
fallback_homedir = /home/%u@%d
access_provider = ad

Configuring LDAP Queries against the Domain Controller (DC) by using sssd

Like Qumulo clusters, Linux systems can resolve details about user and group objects by querying the DC over LDAP. In particular, a Linux system looks for an object with a matching sAMAccountName (user) or CN (group)

To toggle RFC 2307 for mappings in the sssd.conf file, configure the ldap_id_mapping field.
- When you set the field to False, the client checks whether the RFC 2307 uidNumber or gidNumber are set on an object.
  - If the number is set, it becomes the Linux UID or GID for the operation.
    
    Important
    AD doesn’t prevent duplicate UID or GID numbers from being added to RFC 2307 values. For this reason, incorrect configuration can lead or UID or GUID collisions. When a Linux system determines that a collision has occurred, it chooses the first UID or GID it finds.
  - Otherwise, the UID or GID becomes nobody or nogroup (65534).
    
    Note
    In most cases, an owner or group becomes 65534 as a result of incorrect user mapping configuration in the client. To understand which LDAP queries run and why they have trouble finding the correct information, check your logs.
- When you set the field to True, the client assigns locally a new unique UID or GID to each objectSID that it finds on the DC.
  
  Note
  This is a more flexible approach than requiring RFC 2307. However, this also means that UIDs and GIDs aren’t the same across different Linux systems within the same domain.
In both cases, the client communicates with the DC by using its machine account.
To pick up changes to the /etc/sssd.conf file on a live system, restart the sssd service.

Configuring the Conversion of Local Identities to NFS Representations by Using idmapd

idmapd (or nfsidmap), is a tool that lets you convert local identities to their on-the-wire NFS representations. Although idmapd works with sssd, it has additional configuration options.

In the following example, the /etc/idmapd.conf file configures a Linux client joined to AD:

[General]
Domain = my-domain.example.com
Verbosity = 0
Pipefs-Directory = /run/rpc_pipefs

[Mapping]
Nobody-User = nobody
Nobody-Group = nogroup

Note
Depending on your Linux distribution and configuration, you might have to add the Domain field to the default configuration file.

Authenticating as an AD User and Mounting Your Qumulo Cluster

Qumulo Core supports three methods of authenticating as an AD user and mounting your cluster over NFSv4.1 as the AD user. These methods, from least to most complex, and in an increasing order of utility, are:

By using a machine account
By using manual authentication with the kinit tool
By using the autofs tool

To Authenticate as an AD User by Using a Machine Account and Mount Your Qumulo Cluster

Machine account authentication uses one AD user for each Linux system. This machine account user is the same as the machine account created on the domain during the domain-join operation. Any user on the Linux system who has access to the machine account mount point can operate as the machine account user on a Qumulo cluster.

Machine account authentication can be useful for simple scenarios in which trusted users on trusted Linux machines require a secure mechanism for communicating with a Qumulo cluster. Because this is also the easiest authentication method to configure, it can be a good starting point for administrators who configure NFSv4.1 with Kerberos for the first time.

Note
Both machine account authentication and kinit have limited usefulness because they limit the mount point to a single authenticated user. Between the two authentication options, kinit has an advantage because of the way it handles ID mapping.

Confirm that your /etc/nfs.conf file, contains the following flag.
```
[gssd]
use-machine-creds=true
```
The use-machine-creds flag specifies whether authentication uses machine credentials when sudo mount is invoked for NFSv4.1 with Kerberos. When you set the flag to true, gssd authenticates as the machine account for the system on behalf of the NFS client. (It performs a kinit operation as the machine account). The credential cache that results from the kinit is usually located in /tmp. To search for the cache, run the ls /tmp/*krb5* command.

Note
In versions of Ubuntu lower than 22.04 (and possibly on other Linux distributions), you can't use the /etc/nfs.conf file to configure gssd. If this is the case for your system, we recommend starting the rpc.gssd service by using the -n flag.

Mount your cluster by using the krb5 security mechanism. For example:

$ sudo mount -o vers=4.1,sec=krb5 my-cluster.my-domain.example.com:/ /mnt/point

Use the Qumulo file system.

$ cd /mnt/point
$ touch filename
$ ls -l filename
-rw-r--r--    1 MY_MACHINE$    domain computers         0 Jun  9 23:18 filename

Important
The machine account is the owner of any new files.

If the machine name isn’t visible, make sure that the AD container holds this machine in the Qumulo cluster’s Base DN configuration (typically, CN=Computers,DC=...). If the machine name is still not visible, configure the Linux client ID mapper to provide local mappings when no RFC 2307 mapping is available. It is uncommon for machine accounts to have RFC 2307 mappings.

To Authenticate as an AD User Manually by Using kinit and Mount Your Qumulo Cluster

kinit authentication is very similar to machine account authentication. The main difference is that you must create the credentials for the mount manually. You can use any user in the AD domain. However (this is also true for machine accounts), any local Linux user that can access the mount point can operate on the Qumulo cluster as this single user.

In environments where Linux systems map exactly to end users that have kinit-based Kerberos mounts on their Qumulo clusters, kinit might be sufficient.

Authenticate by using kinit. For example:
```
$ sudo kinit my-user
```
When prompted for a password, use the AD domain password for the user.
To confirm the result of the authentication operation, run the sudo klist command.
Confirm that the /etc/nfs.conf file contains the following flag:
```
[gssd]
use-machine-creds=false
```
The use-machine-creds flag specifies whether authentication uses machine credentials when sudo mount is invoked for NFSv4.1 with Kerberos. When you set the flag to false, gssd searches for an existing credential cache (which you created by running kinit) in /tmp/krb5cc_0 for authenticating with the Qumulo cluster.

Mount your cluster by using the krb5 security mechanism. For example:

$ sudo mount -o vers=4.1,sec=krb5 my-cluster.my-domain.example.com:/ /mnt/point

Use the Qumulo file system.

$ cd /mnt/point
$ touch filename
$ ls -l filename
-rw-r--r--    1 my-user    domain users         0 Jun  9 23:18 filename

Important
The kinit user is the owner of any new files.

To Authenticate as an AD User Manually by Using autofs and Mount Your Qumulo Cluster

autofs is a dæmon that manages mount points for individual Linux users. For this reason, Linux users have different views of a mount point. autofs can authenticate an AD user through SSH, the Linux file system, or a Qumulo cluster mounted on a Linux system.

Important
When you use autofs, the Linux system maps the root user to the machine account user for the Linux system on the Qumulo cluster. However, the machine account user doesn’t have all the privileges of the root user, such as special permissions for the Qumulo cluster. You must specify all permissions in ACLs.

Connect to an AD domain and configure sssd to authenticate with this domain. For example:
```
$ sudo login my-domain-user
```
Alternatively, you can run the following command.
```
$ ssh my-domain_user@my-linux-system
```
Configure the autofs mappings. For more information, see auto.master in the Linux documentation. The following is an example of a simple configuration that provides a single (direct) mount point which authenticates AD users automatically.
1. To define a mount point and the path to its map file, add the following line to the /etc/auto.master file.
```
/- /etc/auto.kerberos_nfs_mount_example --timeout 60
```
  For more information, see Autofs in the Ubuntu documentation.
2. Add the following line to the /etc/auto.kerberos_nfs_mount_example map file.
```
/mnt/qumulo_mount_point -vers=4.1,sec=krb5 <qumulo-cluster>.my-domain.example.com:/
```

Restart autofs.

$ sudo systemctl restart autofs

autofs creates the /mnt/qumulo_mount_point directory and mounts it as necessary for any user. For example:

$ ssh domain_user_1@my-linux-system touch /mnt/qumulo_mount_point/user1_file
$ ssh domain_user_2@my-linux-system touch /mnt/qumulo_mount_point/user2_file
$ ssh domain_user_3@my-linux-system ls -l /mnt/qumulo_mount_point
-rw-r--r--    1 user1    domain users         0 Jun  9 23:18 user1_file
-rw-r--r--    1 user2    domain users         0 Jun  9 23:18 user2_file

Important
The user you logged in to the AD domain with is the owner of any new files.

Network Time Protocol (NTP) Server

Kerberos is very sensitive to clock skew. It is important for all systems involved in a Kerberos relationship—the KDC, your Qumulo cluster, and any Linux clients—to have as little clock skew as possible. We recommend using the same NTP server for all three components.

You can use your AD domain controller as an NTP server. In the Qumulo Core Web UI, on the Active Directory page, for Use Active Directory as your primary time server, click Yes.
To configure any other NTP server in the Qumulo Core Web UI, click Cluster > Date & Time.

There are many NTP dæmons for Linux. For example, Ubuntu uses the NTP functionality in systemd (timedatectl and timesyncd).