Protocols
Configure the NFS, SMB, MCP, SFTP and WebDAV gateways. Manage the users that connect through them.
| Protocol | Default | Edition |
|---|---|---|
| NFSv4 | On | All |
| SMB 3 | On | All |
| NFSv3 | Off | Enterprise, High Performance |
| MCP | Off | Enterprise, High Performance |
| SFTP | Off | Enterprise, High Performance |
| WebDAV | Off | Enterprise, High Performance |
Licensed protocols switch on automatically when your license includes them. See Licensing.
NFS
BlixtFS’s NFS gateway is based on NFS-Ganesha. The export root is /, which
lists a directory for each enabled cloud provider, and for any other provider a
client has named. See
Provider directories.
protocol:
nfs:
root_squash: false # map remote root to nobody
sec_type: sys # AUTH_SYS
threads: 0 # auto: 16 per core, at most 512
attributes_expiration_seconds: 0
| Setting | Flag | Meaning |
|---|---|---|
protocol.nfs.root_squash |
--nfs_root_squash |
Map the client’s root user to an unprivileged user. |
protocol.nfs.manage_gids |
--nfs_manage_gids |
Resolve group membership on the server instead of trusting the client’s list. |
protocol.nfs.threads |
--nfs_threads |
Worker threads in the NFS server. 0 (the default) is 16 per available core, at most 512. In a container, the available cores are its CPU limit, or the GOMAXPROCS environment variable when set. |
protocol.nfs.attributes_expiration_seconds |
--nfs_attributes_expiration_seconds |
How long the NFS server caches file attributes. |
--nfs4=false |
Turn NFSv4 off. |
NFSv3 uses port 2050 (mountd), 4045 (lock manager), as well as other ports. It therefore requires host networking in Docker.
SMB
BlixtFS’s SMB gateway is Samba with a BlixtFS module. It serves one share,
bfs, and speaks SMB 3.1 with UNIX permission.
Active Directory integration is in development. Please contact us if you need it.
Users
SMB clients sign in with a user name and password stored on the server. The simplest setup is a single shared account, created each time the server starts:
protocol:
smb:
default_user: alice
Pass the password in the environment or on the command line, not in the file:
docker run ... blixtfs/standard:latest --config /data/config.yaml \
--smb_default_password "$SMB_PASSWORD"
Changing the password and restarting replaces the old one.
To turn SMB off, pass --smb=false, or set protocol.smb.enabled: false.
SFTP
With a license that includes SFTP, the gateway listens on port 2222 for the
user bfs, with public-key authentication only.
Add authorised keys to /home/bfs/.ssh/authorized_keys inside the container.
The easiest way is to mount a file:
docker run ... \
-p 2222:2222 \
-v /srv/blixt/authorized_keys:/home/bfs/.ssh/authorized_keys:ro \
blixtfs/enterprise:2.11.0 --config /data/config.yaml
| Setting | Default |
|---|---|
protocol.sftp.port |
2222 |
protocol.sftp.user |
bfs |
protocol.sftp.authorized_keys |
/home/bfs/.ssh/authorized_keys |
protocol.sftp.host_key_path |
/etc/ssh/ssh_host_ed25519_key |
Mount a persistent host key if clients shouldn’t see a new host key each time the container is recreated.
WebDAV
With a license that includes WebDAV, the gateway listens on port 8080. Change
the port with --webdav_port.
MCP
The MCP server allows AI agents to read and modify files. On a single node server it starts with BlixtFS and listens on port 8090, on loopback only. To connect an agent, see Connecting clients.
Access from other machines
To serve agents on other machines, set a bearer token in MCP_TOKEN and make
the server public. A public MCP server refuses to start without a token, which
must be 32 to 128 hexadecimal characters:
export MCP_TOKEN="$(openssl rand -hex 32)"
docker run ... \
-p 8090:8090 \
-e MCP_TOKEN \
blixtfs/enterprise:2.11.0 --config /data/config.yaml --mcp_public
Agents send the token as Authorization: Bearer <token>.
Set it on each host that runs the MCP server. The connection is not encrypted:
only expose the MCP server on a network you trust.
A request from a web page carries an Origin header. The request is refused unless
that origin is listed in protocol.mcp.allowed_origins. Agents that are not
running in a browser send no Origin header and are not affected.
Allowing writes
Agents can only read by default. To let them change files, turn read-only off
and name the write tools they may use: any of write_file, move and
delete.
protocol:
mcp:
read_only: false
write_tools: [write_file, move]
A read-only bucket refuses every write tool, regardless of MCP server settings.
Audit log
Every tool call and resource read is written to the audit log as one JSON
line: who made it, the tool and path, the result and how long it took. No file
content is logged. The log goes to standard error, or to the file named by
protocol.mcp.audit_path.
protocol.mcp.log_requests adds every argument of each call to the log, each
cut to log_requests_max_bytes. Use it for debugging only: an argument can be
a file’s content.
Limits
Each caller is limited separately in each bucket. A call over the request rate is refused at once; a read over the byte rate waits up to 10 seconds, and is then refused.
protocol:
mcp:
limits:
requests_per_second: 20
read_bytes_per_second: 50000000
max_read_bytes: 262144 # per read_file call
max_write_bytes: 16777216 # per write_file call
search:
max_files: 10000
max_bytes: 536870912
max_matches: 200
max_file_bytes: 8388608
Sizes are in bytes. These are the defaults.
Settings
| Setting | Flag | Default | Meaning |
|---|---|---|---|
protocol.mcp.port |
--mcp_port |
8090 |
The port agents connect to. |
protocol.mcp.public |
--mcp_public |
false |
Listen on every interface instead of loopback only. |
protocol.mcp.allowed_origins |
none | Web page origins allowed to connect. | |
protocol.mcp.read_only |
--mcp_read_only |
true |
Serve only the read tools. |
protocol.mcp.write_tools |
none | Write tools to serve when read-only is off. | |
protocol.mcp.audit_path |
--mcp_audit_path |
stderr |
Where the audit log goes: stderr or a file. |
protocol.mcp.log_requests |
--mcp_log_requests |
false |
Add every call’s arguments to the audit log. |
protocol.mcp.log_requests_max_bytes |
1048576 |
Longest argument logged in full. | |
protocol.mcp.monitoring_port |
--mcp_monitoring_port |
4733 |
Where the bfs_mcp_* metrics are served, when your license includes monitoring. |
Ownership of files
Every bucket has a default owner, group, file mode and directory mode. Files written by other tools, which record none of these, show the defaults, and so do files BlixtFS wrote with the default values. A new bucket takes its defaults from the settings below.
Desktop apps (MacOS and Windows) default to the user and group ids of the user.
filesystem:
default_uid: 0
default_gid: 0
default_file_mode: 0644
default_directory_mode: 0755
Without them, the user and group are the ones BlixtFS runs as, and the modes
are 0644 and 0755. A bucket’s uid, gid, file_mode and dir_mode
attributes set its own defaults, and also change them for a bucket that
already exists. See
Default owner and permissions.