Skip to content

SMB Server Settings Example

This example demonstrates how to configure global SMB server settings on a Qumulo cluster using the qumulo_smb_settings resource. These settings control protocol-level behavior for all SMB connections.

Features

The qumulo_smb_settings resource configures:

  • Session encryption (NONE, PREFERRED, REQUIRED)
  • SMB protocol versions (dialects) supported
  • Message signing requirements
  • Share visibility for unauthorized users/hosts
  • Snapshot directory visibility
  • Traverse checking bypass for performance

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                          SMB SETTINGS SCOPE                                  │
└─────────────────────────────────────────────────────────────────────────────┘

                            QUMULO CLUSTER
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                  GLOBAL SMB SETTINGS                                │   │
│   │  qumulo_smb_settings                                          │   │
│   │                                                                     │   │
│   │  • Session Encryption: REQUIRED                                     │   │
│   │  • Signing: Required                                                │   │
│   │  • Dialects: SMB 3.0, SMB 3.11                                      │   │
│   │  • Hide from unauthorized: Yes                                      │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                   │                                         │
│                                   ▼                                         │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐     │
│   │  SMB Share  │   │  SMB Share  │   │  SMB Share  │   │  SMB Share  │     │
│   │  "finance"  │   │  "projects" │   │  "archive"  │   │  "home"     │     │
│   │  (inherits) │   │  (inherits) │   │  (inherits) │   │  (inherits) │     │
│   └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         │                         │                         │
         ▼                         ▼                         ▼
   ┌───────────┐             ┌───────────┐             ┌───────────┐
   │ Windows   │             │ Windows   │             │ macOS     │
   │ Client    │             │ Client    │             │ Client    │
   │ SMB 3.11  │             │ SMB 3.0   │             │ SMB 3.0   │
   │ Encrypted │             │ Encrypted │             │ Encrypted │
   └───────────┘             └───────────┘             └───────────┘

Prerequisites

  1. Qumulo cluster with REST API access (port 8000)
  2. Admin credentials for the cluster

Usage

  1. Create a terraform.tfvars file:
cluster_endpoint = "https://cluster.example.com:8000"
cluster_username = "admin"
cluster_password = "cluster-admin-password"
  1. Initialize and apply:
terraform init -upgrade
terraform plan
terraform apply

Variables

Name Description Type Default
cluster_endpoint Qumulo cluster REST API endpoint string -
cluster_username Qumulo cluster admin username string "admin"
cluster_password Qumulo cluster admin password string -

Outputs

Name Description
smb_settings_encryption Current SMB session encryption setting
smb_settings_signing Whether SMB signing is required
smb_settings_dialects Supported SMB dialects

Configuration Examples

Basic (Preferred Encryption)

Compatible with most clients while improving security:

resource "qumulo_smb_settings" "basic" {
  connection_profile = "cluster1"

  session_encryption = "PREFERRED"
  signing_required   = true
}

Secure (SMB 3.x Only)

Maximum security for modern environments:

resource "qumulo_smb_settings" "secure" {
  connection_profile = "cluster1"

  session_encryption = "REQUIRED"
  signing_required   = true

  # SMB 3.0+ only (disables SMB 2.x)
  supported_dialects = [
    "SMB2_DIALECT_3_0",
    "SMB2_DIALECT_3_11"
  ]

  # Hide shares from unauthorized entities
  hide_shares_from_unauthorized_users = true
  hide_shares_from_unauthorized_hosts = true

  # Hide .snapshot directories
  snapshot_directory_mode = "HIDDEN"
}

Legacy Compatibility

Maximum compatibility for older clients (reduced security):

resource "qumulo_smb_settings" "legacy" {
  connection_profile = "cluster1"

  session_encryption = "NONE"
  signing_required   = false

  # All SMB dialects enabled
  supported_dialects = [
    "SMB2_DIALECT_2_002",
    "SMB2_DIALECT_2_1",
    "SMB2_DIALECT_3_0",
    "SMB2_DIALECT_3_11"
  ]

  hide_shares_from_unauthorized_users = false
  hide_shares_from_unauthorized_hosts = false
  snapshot_directory_mode             = "VISIBLE"
}

Multi-Cluster Management

Apply consistent settings across a cluster fleet:

variable "clusters" {
  type = map(object({
    endpoint = string
    username = string
    password = string
  }))
}

provider "qumulo" {
  connection_profiles = [
    for name, config in var.clusters : {
      name     = name
      endpoint = config.endpoint
      username = config.username
      password = config.password
    }
  ]
}

resource "qumulo_smb_settings" "fleet" {
  for_each = var.clusters

  connection_profile = each.key

  session_encryption                  = "PREFERRED"
  signing_required                    = true
  hide_shares_from_unauthorized_users = true
  snapshot_directory_mode             = "HIDDEN"
}

SMB Settings Reference

Session Encryption

Value Description
NONE No encryption (not recommended)
PREFERRED Encrypt if client supports it
REQUIRED Reject unencrypted connections

Supported Dialects

Dialect SMB Version Notes
SMB2_DIALECT_2_002 SMB 2.0 Legacy, no encryption support
SMB2_DIALECT_2_1 SMB 2.1 Legacy, limited features
SMB2_DIALECT_3_0 SMB 3.0 Encryption, multichannel
SMB2_DIALECT_3_11 SMB 3.1.1 Pre-authentication integrity

Snapshot Directory Mode

Value Description
VISIBLE .snapshot directories shown in listings
HIDDEN .snapshot directories not shown (still accessible)
DISABLED .snapshot directories inaccessible

Security Considerations

  1. Encryption: For sensitive data, use session_encryption = "REQUIRED" to ensure all traffic is encrypted.

  2. Signing: Enable signing_required = true to prevent man-in-the-middle attacks and packet tampering.

  3. Protocol Versions: Disable older SMB dialects (2.0, 2.1) when all clients support SMB 3.x. Older protocols have known vulnerabilities.

  4. Share Enumeration: Enable hide_shares_from_unauthorized_users to prevent information disclosure through share listings.

  5. Snapshot Access: Set snapshot_directory_mode = "HIDDEN" to reduce attack surface while maintaining access for recovery.

Full Configuration

# Example: Configuring SMB Server Settings on a Qumulo Cluster
#
# This example demonstrates how to configure global SMB server settings
# on a Qumulo cluster using the qumulo_smb_settings resource.
#
# SMB settings are global to the cluster and control:
# - Session encryption (NONE, PREFERRED, REQUIRED)
# - Supported SMB protocol versions (dialects)
# - Message signing requirements
# - Share visibility for unauthorized users/hosts
# - Snapshot directory visibility

terraform {
  required_providers {
    qumulo = {
      source  = "qumulo-terraform-registry.s3.us-east-1.amazonaws.com/qumulo/qumulo"
      version = "~> 1.0"
    }
  }
}

variable "cluster_endpoint" {
  description = "Qumulo cluster REST API endpoint (e.g., https://cluster:8000)"
  type        = string
}

variable "cluster_username" {
  description = "Qumulo cluster admin username"
  type        = string
  default     = "admin"
}

variable "cluster_password" {
  description = "Qumulo cluster admin password"
  type        = string
  sensitive   = true
}

# Define connection profile for the cluster
provider "qumulo" {
  connection_profiles = [
    {
      name                 = "cluster1"
      endpoint             = var.cluster_endpoint
      username             = var.cluster_username
      password             = var.cluster_password
      insecure_skip_verify = true # Required for clusters with self-signed certificates
    }
  ]
}

# -----------------------------------------------------------------------------
# Example 1: Basic SMB Settings with Preferred Encryption
# -----------------------------------------------------------------------------
# This configuration enables preferred encryption and signing for better
# security while maintaining compatibility with older clients.

resource "qumulo_smb_settings" "basic" {
  connection_profile = "cluster1"

  # Prefer encryption but allow unencrypted connections
  session_encryption = "PREFERRED"

  # Require message signing for integrity
  signing_required = true
}

# -----------------------------------------------------------------------------
# Example 2: Secure SMB Settings (SMB 3.x Only)
# -----------------------------------------------------------------------------
# This configuration enforces strict security by requiring encryption
# and limiting to modern SMB 3.x protocols only.

# resource "qumulo_smb_settings" "secure" {
#   connection_profile = "cluster1"
#
#   # Require encryption for all sessions
#   session_encryption = "REQUIRED"
#
#   # Only allow SMB 3.x dialects (disables SMB 2.x)
#   # SMB 3.0+ provides better security features including encryption
#   supported_dialects = [
#     "SMB2_DIALECT_3_0",
#     "SMB2_DIALECT_3_11"
#   ]
#
#   # Require message signing
#   signing_required = true
#
#   # Hide shares from users/hosts that don't have permission
#   # This prevents enumeration of share names by unauthorized entities
#   hide_shares_from_unauthorized_users = true
#   hide_shares_from_unauthorized_hosts = true
#
#   # Hide .snapshot directories from SMB clients
#   snapshot_directory_mode = "HIDDEN"
#
#   # Skip traverse checking for performance
#   # Only enable if your security model doesn't require directory-level ACLs
#   bypass_traverse_checking = false
# }

# -----------------------------------------------------------------------------
# Example 3: Multi-Cluster SMB Settings with for_each
# -----------------------------------------------------------------------------
# This demonstrates managing SMB settings across multiple clusters
# with consistent configuration.

# variable "clusters" {
#   description = "Map of cluster names to connection details"
#   type = map(object({
#     endpoint = string
#     username = string
#     password = string
#   }))
#   default = {}
# }
#
# # Define multiple connection profiles
# provider "qumulo" {
#   connection_profiles = [
#     for name, config in var.clusters : {
#       name     = name
#       endpoint = config.endpoint
#       username = config.username
#       password = config.password
#     }
#   ]
# }
#
# resource "qumulo_smb_settings" "multi_cluster" {
#   for_each = var.clusters
#
#   connection_profile = each.key
#
#   # Apply consistent settings across all clusters
#   session_encryption                  = "PREFERRED"
#   signing_required                    = true
#   hide_shares_from_unauthorized_users = true
#   snapshot_directory_mode             = "HIDDEN"
# }

# -----------------------------------------------------------------------------
# Example 4: Legacy Compatibility Mode
# -----------------------------------------------------------------------------
# This configuration maximizes compatibility with older SMB clients
# at the cost of reduced security. Use only when required.

# resource "qumulo_smb_settings" "legacy" {
#   connection_profile = "cluster1"
#
#   # No encryption requirement
#   session_encryption = "NONE"
#
#   # Enable all SMB dialects for maximum compatibility
#   supported_dialects = [
#     "SMB2_DIALECT_2_002",
#     "SMB2_DIALECT_2_1",
#     "SMB2_DIALECT_3_0",
#     "SMB2_DIALECT_3_11"
#   ]
#
#   # Don't require signing (reduces CPU overhead)
#   signing_required = false
#
#   # Show all shares (no access-based enumeration at server level)
#   hide_shares_from_unauthorized_users = false
#   hide_shares_from_unauthorized_hosts = false
#
#   # Make .snapshot directories visible
#   snapshot_directory_mode = "VISIBLE"
# }

# Outputs
output "smb_settings_encryption" {
  description = "Current SMB session encryption setting"
  value       = qumulo_smb_settings.basic.session_encryption
}

output "smb_settings_signing" {
  description = "Whether SMB signing is required"
  value       = qumulo_smb_settings.basic.signing_required
}

output "smb_settings_dialects" {
  description = "Supported SMB dialects"
  value       = qumulo_smb_settings.basic.supported_dialects
}