SMB Provider

The SMB provider uses SMB/CIFS network file shares for storing files. SMB is ideal for cluster deployments in Windows/Active Directory environments or when using existing network-attached storage (NAS) systems.

Overview

• Provider Name: SMB
• Supports: File Storage only
• Configuration File: provider-smb.json
• Use Case: Windows environments, NAS integration, cluster file storage with existing SMB infrastructure
• Protocol: SMB 2.x/3.x, CIFS

Features

• ✓ Native Windows file sharing protocol
• ✓ Integration with Active Directory
• ✓ Cluster-ready with shared network storage
• ✓ Works with NAS devices (Synology, QNAP, etc.)
• ✓ Support for SMB 2.x and SMB 3.x
• ✓ Encryption support (SMB 3.0+)
• ✗ Requires SMB server or NAS
• ✗ Network latency considerations

Prerequisites

• SMB/CIFS file server or NAS device
• Network connectivity from webPDF Server to SMB server
• SMB credentials (username/password) or domain authentication
• Appropriate share permissions configured

Configuration

provider.json

{
  "fileStorage": {
    "name": "SMB",
    "checks": {
      "enabled": true,
      "interval": 15000
    }
  }
}

provider-smb.json

Configuration file for SMB file storage:

{
  "url": "smb://fileserver.example.com/webpdf-share/",
  "domain": "EXAMPLE",
  "username": "webpdf-service",
  "password": "secure-password",
  "settings": {
    "smbVersion": "SMB3",
    "timeout": "30000"
  }
}

Configuration Attributes

Required Attributes

Attribute	Type	Description	Example
url	string	SMB share URL in UNC format	smb://server/share/path/
username	string	SMB username	webpdf-service
password	string	SMB password	secure-password

Optional Attributes

Attribute	Type	Description	Default
domain	string	Windows domain name (for AD authentication)	""
settings	object	Additional SMB client settings	{}

Settings Object

Additional SMB configuration options:

Setting	Type	Description	Default
smbVersion	string	SMB protocol version (SMB2, SMB3)	SMB3
timeout	string	Connection timeout in milliseconds	30000
enableDfs	string	Enable DFS support	false
signRequired	string	Require SMB signing	false

URL Formats

Basic SMB URL

smb://server-hostname/share-name/path/

Example:

smb://fileserver.example.com/webpdf-files/

With IP Address

smb://192.168.1.100/webpdf-share/

With Port

smb://fileserver.example.com:445/webpdf-share/

UNC Path Conversion

Windows UNC paths must be converted to SMB URL format:

UNC Path	SMB URL
\\server\share	smb://server/share/
\\server\share\folder	smb://server/share/folder/
\\192.168.1.100\data	smb://192.168.1.100/data/

tip

Always include trailing slash in SMB URLs to indicate directory paths.

Authentication Methods

Domain Authentication (Active Directory)

{
  "url": "smb://fileserver.example.com/webpdf-share/",
  "domain": "EXAMPLE",
  "username": "webpdf-service",
  "password": "secure-password"
}

Local Authentication (Workgroup)

{
  "url": "smb://fileserver.example.com/webpdf-share/",
  "domain": "",
  "username": "localuser",
  "password": "secure-password"
}

NAS Device Authentication

{
  "url": "smb://nas.local/webpdf/",
  "domain": "",
  "username": "webpdf",
  "password": "nas-password"
}

Environment Variables

# SMB file storage
WEBPDF_SMB_FILE_STORAGE_SETTINGS_URL=smb://fileserver.example.com/webpdf-share/
WEBPDF_SMB_FILE_STORAGE_SETTINGS_DOMAIN=EXAMPLE
WEBPDF_SMB_FILE_STORAGE_SETTINGS_USERNAME=webpdf-service
WEBPDF_SMB_FILE_STORAGE_SETTINGS_PASSWORD=secure-password

Health Checks

Health checks verify connectivity to the SMB share:

{
  "fileStorage": {
    "name": "SMB",
    "checks": {
      "enabled": true,
      "interval": 15000
    }
  }
}

• enabled: Enable health checks (recommended: true)
• interval: Check interval in milliseconds (recommended: 15000 - 30000)

Health checks perform:

1. Connection test to SMB server
2. Authentication verification
3. Share access validation
4. Read/write permission check

Security Considerations

Authentication Security

1. Domain Accounts – Use dedicated service accounts with minimal privileges
2. Strong Passwords – Enforce complex password policies
3. Account Lockout – Configure lockout policies to prevent brute force
4. Credential Storage – Use environment variables or secure vaults

Network Security

1. SMB Signing – Enable to prevent man-in-the-middle attacks
2. SMB Encryption – Use SMB 3.0+ with encryption enabled
3. Firewall Rules – Restrict SMB ports (445, 139) to trusted networks
4. VPN/Private Network – Avoid exposing SMB over internet

SMB 3.0 Encryption

{
  "settings": {
    "smbVersion": "SMB3",
    "encryptData": "true"
  }
}

warning

Never store SMB passwords in configuration files. Use environment variables or secure configuration management. Consider using domain service accounts with managed passwords.

Share Permissions

Recommended NTFS Permissions

For webPDF service account:

• Share Permissions: Full Control
• NTFS Permissions:
  • Modify, Read & Execute, List Folder Contents, Read, Write
  • Applied to: This folder, subfolders, and files

Windows Share Configuration

# Create share
New-SmbShare -Name "webpdf-share" -Path "D:\webpdf-files" -FullAccess "EXAMPLE\webpdf-service"

# Set NTFS permissions
$acl = Get-Acl "D:\webpdf-files"
$permission = "EXAMPLE\webpdf-service","Modify","ContainerInherit,ObjectInherit","None","Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule $permission
$acl.SetAccessRule($accessRule)
Set-Acl "D:\webpdf-files" $acl

Linux Samba Configuration

# /etc/samba/smb.conf
[webpdf-share]
   path = /srv/samba/webpdf
   browseable = yes
   read only = no
   valid users = webpdf-service
   create mask = 0664
   directory mask = 0775

High Availability

DFS (Distributed File System)

Use DFS for redundancy and load balancing:

{
  "url": "smb://dfs-namespace.example.com/webpdf/",
  "domain": "EXAMPLE",
  "username": "webpdf-service",
  "password": "secure-password",
  "settings": {
    "enableDfs": "true"
  }
}

NAS High Availability

1. RAID Configuration – Use RAID 5/6/10 for disk redundancy
2. NAS Clustering – Active-passive or active-active configurations
3. Replication – Real-time or scheduled replication to secondary NAS
4. Backup – Regular snapshots and off-site backups

Performance Tuning

SMB Server Optimization

Windows Server:

# Enable SMB Multichannel
Set-SmbServerConfiguration -EnableMultiChannel $true

# Optimize SMB credits
Set-SmbServerConfiguration -MaxChannelPerSession 32

# Enable large MTU
Set-NetAdapterAdvancedProperty -Name "Ethernet" -DisplayName "Jumbo Packet" -DisplayValue "9014 Bytes"

Network Optimization

1. Use SMB Multichannel – Multiple network paths for bandwidth aggregation
2. Enable Jumbo Frames – MTU 9000 for better throughput
3. Dedicate Network – Separate storage network from general traffic
4. Use SMB Direct – RDMA for high-performance scenarios

Client Configuration

{
  "settings": {
    "smbVersion": "SMB3",
    "timeout": "30000",
    "bufferSize": "65536",
    "socketTimeout": "60000"
  }
}

Monitoring

SMB Server Monitoring (Windows)

# Active connections
Get-SmbSession

# Open files
Get-SmbOpenFile

# Share statistics
Get-SmbShare | Get-SmbShareAccess

Performance Counters

Monitor these metrics:

• SMB Server response time
• Network throughput
• Active connections
• File operations per second
• Error rate

Troubleshooting

Cannot Connect to SMB Share

1. Test network connectivity: ping fileserver.example.com
2. Test SMB port: telnet fileserver.example.com 445
3. Verify credentials with manual connection
4. Check Windows Event Logs (Security, System)
5. Review SMB server logs

Permission Denied

1. Verify share permissions: Get-SmbShareAccess
2. Check NTFS permissions on server
3. Confirm user account is not locked
4. Verify domain membership (for domain accounts)
5. Check file/folder ownership

Slow Performance

1. Check network latency: ping -n 100 fileserver.example.com
2. Monitor SMB server CPU/Memory
3. Review disk I/O on storage
4. Check for antivirus interference
5. Verify SMB version (prefer SMB 3.0+)
6. Consider SMB Multichannel

Authentication Failures

1. Verify username format: DOMAIN\username or username@domain.com
2. Check password is correct and not expired
3. Confirm account is not disabled
4. Review domain controller logs
5. Test with domain admin account to isolate issue

Troubleshooting Common Issues

SMB Version Negotiation

Force specific SMB version:

{
  "settings": {
    "smbVersion": "SMB3",
    "smbMinVersion": "SMB2"
  }
}

Connection Timeouts

Increase timeouts for slow networks:

{
  "settings": {
    "timeout": "60000",
    "socketTimeout": "120000"
  }
}

Character Encoding Issues

Ensure proper encoding for international characters:

{
  "settings": {
    "encoding": "UTF-8"
  }
}

Examples

Basic SMB Setup (Workgroup)

{
  "url": "smb://192.168.1.100/webpdf-share/",
  "domain": "",
  "username": "webpdf",
  "password": "secure-password"
}

Active Directory Domain

{
  "url": "smb://fileserver.example.com/webpdf-share/",
  "domain": "EXAMPLE",
  "username": "webpdf-service",
  "password": "domain-password"
}

Synology NAS

{
  "url": "smb://synology.local/webpdf/",
  "domain": "",
  "username": "webpdf-user",
  "password": "nas-password",
  "settings": {
    "smbVersion": "SMB3"
  }
}

High-Security Configuration

{
  "url": "smb://fileserver.example.com/webpdf-secure/",
  "domain": "EXAMPLE",
  "username": "webpdf-service",
  "password": "strong-password",
  "settings": {
    "smbVersion": "SMB3",
    "encryptData": "true",
    "signRequired": "true",
    "timeout": "30000"
  }
}