⚠

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 list --format json

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. An SMB1 client that fails to negotiate at all is expected on a default configuration — see below.
• 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)
sudo tsmb-cfg global update --log-level 5

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 — or, if the customer is on QUIC, the QUIC listener and its TLS certificate?
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 client. 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.

A saturated single core can also mean signing is being serialized rather than multichannel being absent — check the crypto_threads default covered in Common Issues before concluding it is a multichannel problem.

Clustered deployments: check network_interface_info

Clients discover the server's interfaces through the SMB2 FSCTL_QUERY_NETWORK_INTERFACE_INFO IOCTL. By default Fusion SMB derives that response per node, from that node's own listen parameters. Setting the network_interface_info global parameter replaces it with a static list — so in a cluster where every node shares one tsmb.conf, all nodes advertise the same interfaces instead of their own. That misdirects Multichannel- and RDMA-aware clients, and it is easy to miss because each node's configuration looks correct in isolation. If a clustered customer reports multichannel or failover behaving oddly, check whether network_interface_info is set.

SMB1 clients

SMB1 became selectable again as a dialects value in 3026.4.1, for legacy estates (typically Windows XP era) that cannot be upgraded. Two things matter when triaging it:

• It is off by default. SMB1 is excluded from the default dialect set and is not reached by a dialect_max range, so an SMB1 client is refused until an administrator names SMB1 explicitly in dialects. A failed SMB1 negotiation on a default configuration is correct behaviour, not a fault to chase — on the client it usually surfaces as a connection reset during protocol negotiation.
• Enabling it logs a warning. The server logs that a deprecated dialect with known security vulnerabilities is active. Finding that line tells you SMB1 was enabled deliberately or by misadventure — confirm which.

Known limits when SMB1 is enabled:

Limitation	Effect
Non-Unicode SMB1 was never supported	DOS and Windows 9x era clients may still fail
LMHash authentication not supported	Clients restricted to LM-only auth cannot connect
Shares with unknown users in permissions	Not supported over SMB1

SMB1 also requires NetBIOS to be enabled. The validated configuration is Windows XP clients using NTLM with local accounts (no AD, so no Kerberos).

Not in the public documentation yet

docs.tuxera.com still states that SMB1 support was discontinued. Until that is corrected, do not send a customer to the docs to confirm SMB1 behaviour — check with Tuxera.

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 on the client for capture when possible; fall back to tcpdump on servers without a GUI

SMB over QUIC changes what you can capture

As of 3026.4.0, QUIC is a third transport alongside TCP and RDMA, enabled by giving listen a QUIC_IPv4 / QUIC_IPv6 address family. QUIC traffic does not flow over TCP 445, so a port 445 filter captures nothing on a QUIC deployment. QUIC is also always TLS 1.3 encrypted, so the SMB payload is not readable in the capture the way a plain Direct TCP session is. Confirm which transport the customer is actually using — check the listen entries in tsmb-cfg global list — before planning a packet capture.

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 list --format json	Display current global configuration
tsmb-cfg share list	List configured shares
tsmb-cfg share list -n ShareName -l 2	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?