cifs.upcall

cifs.upcall [--krb5] [--help] [--version] <call_type> <arguments>

--krb5
    Used to signal that the upcall relates to Kerberos authentication. This flag is typically set when handling Kerberos ticket acquisition.

--help
    Displays a brief usage message and exits.

--version
    Displays the version number of the cifs.upcall utility and exits.

<call_type>
    Specifies the type of operation the kernel module needs assistance with. Common types include key (for managing authentication keys like NTLM or Kerberos tickets), dfs (for resolving Distributed File System referrals), gid.krb5, uid.krb5, gid.idmap, uid.idmap, gid.sids, uid.sids (for ID mapping), among others.

<arguments>
    Additional parameters specific to the <call_type>, providing context or data for the operation. For example, for key types, it might include the UID, mount ID, and server principal.

cifs.upcall is a user-space helper program invoked by the Linux kernel's CIFS (Common Internet File System) module. Its primary role is to facilitate operations that require interaction with user-space services, which the kernel cannot perform directly. This typically includes authentication processes, particularly for NTLM and Kerberos, and resolving DFS (Distributed File System) referrals.

When the kernel needs a user-space service (e.g., obtaining a Kerberos ticket, hashing a password for NTLMv2, or handling a DFS redirect), it makes an "upcall" to cifs.upcall. This utility then interacts with system components like keyutils for managing authentication credentials (like NTLM hashes or Kerberos tickets) or Kerberos client tools (e.g., kinit). It plays a crucial role in enabling secure and complex CIFS/SMB access from Linux systems, especially when dealing with Active Directory environments or highly structured network shares. It is not typically run directly by users but is invoked automatically by the kernel.

cifs.upcall is primarily a kernel helper and is not intended for direct interactive use by end-users. Its proper functioning relies heavily on correct configuration of the system's key management facilities (e.g., keyutils) and, for Kerberos, the Kerberos client setup (e.g., krb5-user package and /etc/krb5.conf). Issues often manifest as authentication failures or inability to access certain network resources, and troubleshooting usually involves examining kernel logs (dmesg) and system logs for related errors.

cifs.upcall frequently interacts with the kernel's keyring service via the keyutils utilities. For NTLM authentication, it can store and retrieve NTLM hashes. For Kerberos, it manages Kerberos tickets by interacting with the Kerberos client libraries (e.g., via kinit if necessary) and then storing the resulting tickets in the kernel keyring, making them available for subsequent CIFS operations.

Unlike most commands, cifs.upcall is typically not executed manually by a user. Instead, it is automatically spawned by the Linux kernel's CIFS module (cifs.ko) when it encounters a situation that requires user-space assistance, such as during a mount operation involving Kerberos authentication or when resolving a DFS path.

The Linux CIFS client implementation has evolved significantly over the years to support modern SMB protocols and features. As the kernel's CIFS module gained capabilities such as Kerberos authentication and Distributed File System (DFS) support, the need for a user-space helper became apparent. cifs.upcall was developed as part of the cifs-utils package to bridge this gap, allowing the kernel to offload complex user-space interactions, particularly for secure authentication methods and DFS resolution, to a dedicated utility. Its development reflects the increasing sophistication of Linux's integration with Windows-based network services.

mount.cifs(8), keyctl(1), kinit(1), smbclient(1)