⚠

Auto-generated content — pending SME review

This content was auto-generated from Fusion SMB documentation and is pending SME review. Please verify accuracy before using in partner-facing contexts.

Troubleshooting Guide

A structured approach to diagnosing and resolving Fusion SMB issues. Use this guide as your starting framework when a customer reports a problem.

Diagnostic Methodology

Step 1: Gather Context

Before investigating the server, collect the following from the customer:

• Fusion SMB version — run tsmb-server -v to confirm. Check against the version lifecycle to verify the version is still supported.
• Symptom description — what the user observes (error messages, performance degradation, connection failures, etc.)
• When it started — timestamp of first occurrence, any recent changes (upgrades, configuration changes, network changes)
• Scope — does it affect all users or specific clients? All shares or a specific share? Intermittent or persistent?
• Client details — operating system, SMB client version, application in use

Step 2: Check Server Health

Use the CLI tools to assess the current server state:

# Check server is running and get version
tsmb-server -v

# Get current server statistics (sessions, connections)
tsmb-status stats --format json

# Review current configuration
tsmb-cfg global get

Key things to look for:

• Is the server process running? — If not, check system logs for crash messages.
• Are sessions being established? — An empty session list may indicate authentication or network issues.
• Connection dialect — Clients negotiating older dialects (SMB 2.0.2) may indicate compatibility problems.
• Signing and encryption flags — Mismatched security settings between client and server are a common cause of connection failures or performance issues.

Step 3: Review Logs

Check the Fusion SMB log file for errors or warnings:

# Default log location (depends on configuration)
# Check log_destination in tsmb.conf
grep -i "log_destination\|log_params\|log_level" /etc/tsmb.conf

# If logging to file, tail the log
tail -100 /var/log/tsmb.log

# For more verbose logging, temporarily increase log level
# (remember to revert after troubleshooting)
tsmb-cfg global set log_level 6

See Log Collection & Analysis for detailed guidance on configuring and interpreting logs.

Step 4: Isolate the Issue

Narrow down the problem domain:

Symptom Category	Likely Area	First Check
Connection refused / timeout	Network / service	Is tsmb-server running? Firewall rules? Port 445 open?
Authentication failure	AD / user database	Domain trust status, user account, Kerberos configuration
Permission denied on file access	ACLs / share config	Share permissions, filesystem ACLs, tsmb-acls --get
Slow performance	Network / signing / tuning / multichannel	SMB signing status, dialect negotiation, tsmb-status counters, single-core saturation check (see below)
Client disconnections	Stability / network	Log errors around disconnect time, network stability
Share not visible	Configuration	tsmb-cfg share list, access-based enumeration settings

Quick Multichannel Diagnostic

Single-core saturation check: During a performance issue, check CPU utilization on the server. If one core is 100% utilized while others are idle, the client is likely not using SMB Multichannel — all traffic is flowing through a single TCP connection on a single core. This is common with macOS clients (single-adapter limitation) or when multichannel is misconfigured. On Windows, verify multichannel with Get-SmbMultichannelConnection in PowerShell.

Step 4b: Capture Network Traffic (When Needed)

If the issue cannot be diagnosed from logs and server statistics alone — especially for application-specific behavior or protocol-level problems — capture SMB traffic with Wireshark or tcpdump:

# Capture SMB traffic on port 445 to a file
sudo tcpdump -i any -s 0 -w /tmp/smb-capture-$(date +%Y%m%d-%H%M%S).pcap port 445

Best practices for packet capture:

• Filter on TCP port 445 to capture only SMB traffic and keep the file manageable
• Unmount and remount the share on the client before starting the capture — this gives you a clean session setup to analyze
• Document the reproduction steps clearly so Tuxera Support can correlate the capture with the issue
• Use Wireshark for analysis when possible; fall back to tcpdump on servers without a GUI

When to Use Packet Capture

Packet capture is most valuable when you've validated performance with iperf/fio (network and storage are healthy) but the application still shows poor performance. The capture lets Tuxera Support analyze exactly what the application is doing on the wire — something that cannot be seen from logs alone.

Verify with Pre-Sales / PM

Aaron Kennedy's training sessions mention a Python data collection script he developed for bundling host info, logs, and diagnostics. Check if this tool is available for partner distribution.

Step 5: Apply Fix or Escalate

• If the issue matches a known problem, apply the documented solution.
• If the fix requires configuration changes, use tsmb-cfg for runtime changes or edit tsmb.conf for persistent changes.
• If the issue is not resolvable, escalate to Tuxera Support with the gathered diagnostic data.

Common Diagnostic Commands

Command	Purpose
tsmb-server -v	Check Fusion SMB version
tsmb-status stats --format json	View active sessions and connections
tsmb-cfg global get	Display current global configuration
tsmb-cfg share list	List configured shares
tsmb-cfg share get -n ShareName	Get details for a specific share
tsmb-acls --get /path/to/file	Check file ACLs
tsmb-passwd --list	List users in the file-backed user database
tsmb-privilege list	Show granted Windows privileges

When to Escalate

Escalate to Tuxera Support when:

• The issue involves a server crash or unexpected process termination
• You suspect a bug in Fusion SMB behavior (not a configuration issue)
• The issue persists after applying all known solutions
• The customer is running an End of Life version and needs upgrade guidance
• You need assistance interpreting complex log output or protocol traces

See Escalation Process for step-by-step instructions on filing a support case.

Reference: For full documentation on all CLI tools, configuration parameters, and advanced features, see the Fusion SMB Documentation.

✍Knowledge Check

1. What is the first step in the diagnostic methodology?

2. Which command shows current active sessions and connections?

3. If a client reports 'connection refused', what should you check first?