SMB / Samba Folder Sharing

1. Overview

PowerFolder Server includes an embedded SMB file server that allows users to access their folders directly from Windows Explorer, macOS Finder, or any SMB-compatible client. Files accessed via SMB are subject to the same permissions, quota, and synchronization rules as files managed through the PowerFolder client or web interface.

The SMB server uses SMB1 (NT LM 0.12) protocol over TCP (port 445 by default). Authentication is handled by PowerFolder's own user database — users log in with their PowerFolder credentials.

How it worksWhen a user connects via SMB, they see their PowerFolder folders as subdirectories under a single share called PowerFolder. Each folder maps to the user's assigned PowerFolder folders based on their account permissions. Files created or modified via SMB are automatically synchronized to other connected clients.

2. Requirements

PowerFolder Server 27.2 or later
Java 21 or later
Port 445 (or configured alternative) available and not blocked by firewall
SMB1 client support enabled on connecting machines (see Connecting Clients)

3. Enabling SMB

Via Web Admin Panel

Log in to the PowerFolder admin panel
Navigate to Preferences → Network → SMB File Sharing
Set Enable SMB to true
Optionally adjust the port and domain
Restart PowerFolder Server for changes to take effect

Via Configuration File

Add the following to PowerFolder.config:

smb.enabled=true
smb.port=445
smb.domain=POWERFOLDER

Then restart the server.

Restart RequiredChanging smb.enabled or smb.port requires a server restart. Other SMB settings can be changed at runtime.

4. Configuration Reference

Property	Default	Description

Property	Default	Description
`smb.enabled` restart	`false`	Enables or disables the embedded SMB server.
`smb.port` restart	`445`	TCP port for SMB connections. Standard SMB port is 445.
`smb.domain`	`POWERFOLDER`	SMB domain/workgroup name advertised to clients.
`smb.audit.enabled`	`true`	Enables audit logging of SMB file operations.
`smb.audit.level`	`WRITE_ONLY`	Audit level: `WRITE_ONLY` (create/modify/delete) or `ALL` (includes reads).
`smb.dir.cache.ttl`	`5000`	Directory listing cache TTL in milliseconds.
`smb.share.cache.ttl`	`60000`	Share/folder mapping cache TTL in milliseconds.
`smb.threads.max`	`64`	Maximum number of SMB worker threads.

The server name advertised to SMB clients is derived from the web.title setting, sanitized to a valid NetBIOS name (max 15 characters, alphanumeric and hyphens only, uppercased). If the title cannot be sanitized, it defaults to POWERFOLDER.

5. Port Configuration

Default Port (445)

Port 445 is the standard SMB port. On Linux, binding to port 445 requires root privileges or the CAP_NET_BIND_SERVICE capability. On Windows, port 445 is typically occupied by the built-in Windows SMB server.

Automatic Fallback

If the default port 445 is unavailable, the server automatically falls back to port 8445. This only occurs when using the default port — if you explicitly configure a custom port and it is unavailable, the server will not start.

Windows Port Forwarding

When running on Windows with the fallback port, clients cannot directly connect to a non-standard SMB port. Set up port forwarding to redirect port 445 to the fallback port:

# Run as Administrator
netsh interface portproxy add v4tov4 listenport=445 listenaddress=127.0.0.1 connectport=8445 connectaddress=127.0.0.1

To remove the port forwarding:

netsh interface portproxy delete v4tov4 listenport=445 listenaddress=127.0.0.1

Linux: Using a Non-Standard Port

If you run the server on a non-standard port (e.g. 8445), use iptables to redirect:

iptables -t nat -A PREROUTING -p tcp --dport 445 -j REDIRECT --to-port 8445

Bind Address

By default, the SMB server listens on all interfaces. To restrict it to a specific interface, set net.bindaddress in the PowerFolder configuration. This setting is shared with the main PowerFolder server.

6. Security Considerations

Important: Plaintext PasswordsThe SMB server uses SMB1 with plaintext password authentication. Passwords are transmitted unencrypted over the network. This is a fundamental limitation of the current implementation — PowerFolder stores passwords as salted hashes and cannot perform NTLM challenge-response authentication.

Recommended Deployment

VPN: Always deploy behind a VPN when users connect from untrusted networks.
Trusted LAN only: If no VPN is available, restrict SMB access to trusted local networks.
Firewall: Block port 445 (or your configured SMB port) from the public internet.
Bind address: Bind to a specific internal interface rather than all interfaces.

Authentication

Users authenticate with their PowerFolder username and password. Authentication is delegated to PowerFolder's SecurityManager — the same credentials used for the web interface work for SMB. Failed login attempts are logged.

Guest/anonymous access is not supported. A valid PowerFolder account is always required.

7. Connecting Clients

Windows

Enable SMB1 on Windows 10/11SMB1 client is disabled by default on modern Windows. To enable it:

OpenControl Panel → Programs → Turn Windows features on or off
ExpandSMB 1.0/CIFS File Sharing Support
CheckSMB 1.0/CIFS Client
Click OK and restart Windows

Additionally, enable insecure guest logons (required for plaintext password auth):

# Run as Administrator - enable plaintext passwords
reg add HKLM\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters /v AllowInsecureGuestAuth /t REG_DWORD /d 1 /f
reg add HKLM\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters /v EnablePlainTextPassword /t REG_DWORD /d 1 /f

Connect via Windows Explorer:

\\server-address\PowerFolder

Enter your PowerFolder username and password when prompted.

macOS

Open Finder
Press Cmd+K (Go → Connect to Server)
Enter: smb://server-address/PowerFolder
Select Registered User and enter your PowerFolder credentials

Linux

# Mount via command line
mount -t cifs //server-address/PowerFolder /mnt/powerfolder \
  -o username=your_user,password=your_pass,vers=1.0
# Or using smbclient
smbclient //server-address/PowerFolder -U your_user

Add vers=1.0 to force SMB1 protocol.

8. Permissions & Quota

Folder Access

When a user connects via SMB, they see only the PowerFolder folders they have been granted access to. Each folder appears as a subdirectory under the PowerFolder share:

\\server\PowerFolder\
  ├── Project Documents      (read-write)
  ├── Team Photos            (read-only)
  └── Shared Resources       (read-write)

The following PowerFolder permission levels apply:

Permission	SMB Access

Permission	SMB Access
Owner	Full read/write access
Read/Write	Full read/write access
Read Only	Read-only access (write operations are denied)
No Access	Folder is not visible

Storage Quota

Storage quotas are enforced for SMB operations. If a write would exceed the folder owner's storage quota, the operation fails with a "disk full" error. Quota is checked on file creation, during writes, and on file close.

File Synchronization

Files created or modified via SMB are automatically detected and synchronized to other PowerFolder clients. Temporary files (prefixed with ~$ or ~, or ending with .tmp) are excluded from synchronization to avoid syncing intermediate editor files.

The following files are hidden from SMB directory listings:

desktop.ini, Thumbs.db, .DS_Store
.pf (PowerFolder system directory)
Any file starting with . (dot files)

9. Audit Logging

SMB file operations are logged through PowerFolder's audit system when smb.audit.enabled=true.

Audit Level	Logged Operations

Audit Level	Logged Operations
`WRITE_ONLY` (default)	File create, modify, delete, rename, directory create/delete
`ALL`	All operations including file reads and directory listings

Audit entries include the username, remote IP address, operation type, and file path.

10. Performance Tuning

Thread Pool

The SMB server uses a thread pool with 25 core threads and up to 50 maximum threads by default. For servers with many concurrent SMB users, increase smb.threads.max.

Memory Pools

The server pre-allocates memory buffers for SMB packet processing:

Buffer Size	Initial	Maximum

Buffer Size	Initial	Maximum
256 bytes	20	100
4 KB	20	50
16 KB	5	50
64 KB	5	50

Caching

Directory cache (smb.dir.cache.ttl): Controls how long directory listings are cached. Lower values mean more responsive listings but higher I/O. Default: 5 seconds.
Share cache (smb.share.cache.ttl): Controls how long folder-to-share mappings are cached. Default: 60 seconds. If folder permissions change, users may need to wait up to this duration before seeing updated shares.

11. Troubleshooting

Server won't start

Symptom	Cause	Solution

Symptom	Cause	Solution
Port already in use	Another process (e.g. Windows SMB, Samba) is using port 445	Use a different port or stop the conflicting service. The server will auto-fallback to 8445 if using default port.
Permission denied on port 445	Linux: binding to ports <1024 requires root	Run as root, use `setcap`, or configure a higher port with iptables redirect.
SMB server is disabled	`smb.enabled` is not set to `true`	Set `smb.enabled=true` and restart.

Client can't connect

Symptom	Cause	Solution

Symptom	Cause	Solution
Connection refused	Firewall blocking port, server not running	Check firewall rules. Verify server started (check logs for "SMB server started on port").
Protocol negotiation failed	Client does not support SMB1	Enable SMB1 client support (see Connecting Clients).
Login failed / access denied	Wrong credentials or plaintext auth not enabled on client	Verify credentials work on web interface. Enable `EnablePlainTextPassword` on Windows clients.
No folders visible	User has no folder permissions	Grant folder permissions to the user in the admin panel.

File operations fail

Symptom	Cause	Solution

Symptom	Cause	Solution
Disk full error	User/folder owner has exceeded storage quota	Increase the storage quota or free up space.
Access denied on write	User has read-only permission on the folder	Grant read-write or owner permission.
Cross-share move error	Attempting to move files between different PowerFolder folders via SMB	Copy instead of move, or move within the same folder.

Checking Server Status

The server logs its status on startup:

INFO: SMB server started on port 445 (bind: 10.0.0.1) server: POWERFOLDER

Active session count is available through the management API.

12. Limitations

SMB1 only: SMB2 and SMB3 protocols are not supported. Modern Windows and macOS have SMB1 disabled by default and require manual re-enablement.
Plaintext passwords: NTLM challenge-response authentication is not supported. Passwords are sent in cleartext. Always use VPN or trusted networks.
No oplocks/leases: Opportunistic locking is not supported. This may result in slower performance for applications that rely on client-side caching.
No cross-folder moves: Moving files between different PowerFolder folders via SMB is not supported. Use copy-and-delete instead.
Single share: All folders are exposed under a single PowerFolder share. Individual shares per folder are not configurable.
NetBIOS name limit: The server name is limited to 15 characters (NetBIOS restriction). Only alphanumeric characters and hyphens are allowed; other characters are stripped.

Need Help?Check the server logs for detailed error messages. SMB-related log entries are prefixed with the SMBServerManager, FolderDiskInterface, or AccountAuthenticator component names. Contact PowerFolder support if issues persist.