Comparing CIFS/SMB File Handle Types: Durable vs. Resilient vs. Persistent Handles in Network File Sharing


3 views

The Server Message Block (SMB) protocol, particularly in versions 2.x and 3.x, introduced several file handle types to improve reliability in network file operations. These handle types address different failure scenarios while maintaining session state.

Introduced in SMB 2.1, durable handles allow clients to reconnect to files after temporary network failures. The server maintains the file state for a limited time (typically 5-30 seconds).

// Example of requesting durable handle in C#
var createRequest = new CreateRequest
{
    Path = @"\server\share\file.txt",
    AccessMask = FileAccess.ReadWrite,
    ShareMode = FileShare.Read,
    CreateOptions = CreateOptions.NonDirectoryFile,
    CreateDisposition = FileOpen,
    DurableHandle = true // SMB2_DHANDLE_FLAG_PERSISTENT
};

Added in SMB 3.0, resilient handles provide extended durability (minutes to hours) and automatic reconnection capabilities. They're designed for long-term network instability scenarios.

// Resilient handle properties in SMB3
typedef struct _SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2 {
    UINT32 Timeout; // In milliseconds (0xFFFFFFFF for infinite)
    UINT32 Flags;   // SMB2_DHANDLE_FLAG_PERSISTENT
    GUID CreateGuid;
} SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2;

Introduced in SMB 3.0.2, persistent handles survive both client and server restarts. They're stored in persistent storage and identified by a unique GUID.

Feature Durable Resilient Persistent
Introduced in SMB 2.1 SMB 3.0 SMB 3.0.2
Survives Network blips Extended outages Server reboots
Timeout Seconds Configurable Infinite
Storage Memory Memory Disk
Use Case Temporary files Database files Critical shared resources

When choosing handle types, consider these factors:

  • Durable handles are lightweight but require quick reconnection
  • Resilient handles add overhead but handle longer outages
  • Persistent handles impact server performance due to disk storage

Windows clients can configure these settings via PowerShell:

# Set SMB client durable handle timeout (seconds)
Set-SmbClientConfiguration -DurableHandleTimeout 30

# Enable persistent handle recovery
Set-SmbClientConfiguration -PersistentHandleRecovery $true

For Linux SMB clients (cifs-utils), these options are specified in mount commands:

mount -t cifs //server/share /mnt -o username=user,password=pass,persistenthandles

In SMB protocol implementations (particularly SMB 2.0+), file handles can maintain state across network interruptions through three distinct mechanisms. Let's examine their technical characteristics:

Introduced in SMB 2.1, durable handles survive brief network disconnections (up to lease duration). The client can reconnect without file recreation:

// SMB2 CREATE_REQUEST with durable handle flag
CREATE_CONTEXT Request = {
  SMB2_CREATE_DURABLE_HANDLE_REQUEST {
    Timeout = 60; // Seconds before server releases
    Flags = SMB2_DHANDLE_FLAG_PERSISTENT;
  }
}

Enhanced in SMB 3.0 with active reconnection capabilities. Key differentiators:

  • Server maintains open for configurable duration (default: 30s)
  • Supports auto-reconnect without application involvement
  • Mandatory for Scale-Out File Server scenarios

The most robust option with these operational behaviors:

// PowerShell example enabling persistent handles
Set-SmbClientConfiguration -RequirePersistentHandle $true
Set-SmbClientConfiguration -SessionTimeout 3600
Feature Durable Resilient Persistent
Minimum SMB Version 2.1 3.0 3.1.1
Failover Support No Yes Yes
Client Reconnect Manual Automatic Automatic
Cluster Awareness No Yes Yes

For modern applications targeting Windows Server 2022:

// C# example using SMB3 persistent handles
var options = new SmbClientOptions {
    HandleType = FileHandleType.Persistent,
    ReconnectPolicy = ReconnectPolicy.Automatic,
    ClusterAware = true
};
using var file = await SmbFile.OpenAsync(path, options);

Key selection criteria:

  • Choose durable handles for simple temporary disconnections
  • Use resilient handles for HA environments with automatic failover
  • Persistent handles are required for long-running cluster operations

Common issues and resolution approaches:

# Check handle type in use (Windows)
Get-SmbConnection | fl ClientComputerName,ServerName,Durable,Resilient,Persistent

# Linux SMB client configuration (cifs-utils)
options=vers=3.1.1,cache=none,persistenthandles

Remember that handle behavior is negotiated during SMB session establishment and depends on both client and server capabilities.