open-webui-smb-tool/README.md

# Open WebUI SMB File Operations Tool

An Open WebUI Workspace Tool for controlled SMB2/SMB3 file access.

The tool allows an Open WebUI model to browse, read, create, update, copy, move, and delete files on an SMB share while keeping SMB connection details and permissions in per-user `UserValves`.

Administrator `Valves` provide global policy controls such as server/share allow-lists, maximum file sizes, and whether write, delete, directory, and recursive operations are permitted.

The implementation uses the Python `smbprotocol` package through its high-level `smbclient` API.

## Features

- SMB2/SMB3 access
- Per-user SMB server, share, username, password, and domain
- Optional SMB encryption
- Optional logical root directory inside a share
- Server and share allow-lists
- Path traversal protection
- Separate permissions for:
  - creating files
  - modifying existing files
  - deleting files/directories
  - directory operations
  - move/copy operations
- Administrator-controlled read/write/search limits
- Text and Base64 file reads/writes
- Chunked file reads using byte offsets
- Exact text replacement for safer file updates
- Recursive wildcard file search
- Open WebUI status reporting through `EventEmitter`
- SMB session/cache isolation between Open WebUI users

## Requirements

The tool declares:

```text
smbprotocol>=1.17.0
```

The Open WebUI runtime hosting the tool must be able to reach the SMB server, normally on TCP port `445`.

The SMB account must also have the filesystem/share permissions required for the operations you enable.

## Installation

Download or copy:

```text
open_webui_smb_file_operations.py
```

into Open WebUI as a Workspace Tool.

A typical workflow is:

1. Open **Workspace** in Open WebUI.
2. Open **Tools**.
3. Create a new Tool.
4. Paste the contents of `open_webui_smb_file_operations.py`.
5. Save the Tool.
6. Configure the administrator `Valves`.
7. Give the intended users access to the Tool.
8. Each user configures their own `UserValves`.
9. Use `test_connection` before enabling write operations.

The tool metadata specifies:

```text
required_open_webui_version: 0.6.3
requirements: smbprotocol>=1.17.0
```

Ensure the Open WebUI Python environment is able to install/use the declared dependency.

---

# Configuration

## Administrator Valves

`Valves` define the global policy for every user of the Tool.

### `enabled`

Default:

```text
true
```

Global on/off switch.

Setting this to `false` prevents SMB operations for all users.

### `allowed_server_patterns`

Default:

```text
*
```

Comma-separated `fnmatch` patterns controlling which SMB servers users may configure.

Examples:

```text
nas01
```

```text
nas01,fileserver01
```

```text
*.internal.example
```

```text
nas*,10.20.*
```

For a production installation it is recommended to replace `*` with the specific SMB servers Open WebUI is supposed to access.

Example:

```text
nas01.internal.example,nas02.internal.example
```

### `allowed_share_patterns`

Default:

```text
*
```

Comma-separated patterns controlling which SMB shares may be used.

Example:

```text
Documents,Engineering,Projects-*
```

A production configuration should normally restrict this rather than leaving it as `*`.

### `allow_create_files`

Default:

```text
true
```

Allows users to opt in to creating new files.

A user must additionally enable:

```text
allow_write_new_files
```

in their own `UserValves`.

### `allow_modify_files`

Default:

```text
true
```

Allows users to opt in to changing existing files.

This affects operations such as:

- overwriting files
- appending data
- text replacement
- replacing an existing copy/move destination

The user must additionally enable:

```text
allow_modify_existing_files
```

### `allow_delete_paths`

Default:

```text
false
```

Global delete permission.

Deletion is intentionally disabled by default.

To allow deletion, both of these must be enabled:

Administrator:

```text
allow_delete_paths = true
```

User:

```text
allow_delete_existing_paths = true
```

### `allow_directory_operations`

Default:

```text
true
```

Controls creation/manipulation of directories.

Users must additionally enable:

```text
allow_directory_operations
```

### `allow_move_copy`

Default:

```text
true
```

Allows users to opt in to copy and move operations.

Users must additionally enable:

```text
allow_move_copy_operations
```

### `allow_recursive_delete`

Default:

```text
false
```

Controls recursive directory deletion.

This is a separate administrator protection in addition to normal delete permissions.

Keeping this disabled is recommended unless recursive deletion is specifically required.

### `allow_alternate_data_streams`

Default:

```text
false
```

Controls whether `:` is permitted in relative SMB paths.

On Windows-compatible filesystems a colon can address an Alternate Data Stream.

Normally leave this disabled.

### `max_read_bytes`

Default:

```text
2097152
```

2 MiB.

Maximum amount returned by one `read_file` call.

Large files can be read in chunks using `offset`.

### `max_write_bytes`

Default:

```text
4194304
```

4 MiB.

Maximum payload accepted by a single write, append, or update operation.

### `max_list_entries`

Default:

```text
500
```

Maximum number of entries returned from a single directory listing.

### `max_search_results`

Default:

```text
200
```

Maximum results returned by `search_files`.

### `max_search_depth`

Default:

```text
8
```

Maximum recursive depth permitted for `search_files`.

---

# UserValves

Each user has their own SMB connection and permissions.

## `server`

SMB hostname or IP address.

Example:

```text
nas01.internal.example
```

Do not enter:

```text
smb://nas01/Documents
```

or:

```text
\\nas01\Documents
```

Only the server name/IP belongs here.

## `port`

Default:

```text
445
```

Normally this should remain `445`.

## `share`

SMB share name.

Example:

```text
Documents
```

For:

```text
\\nas01\Documents
```

configure:

```text
server = nas01
share  = Documents
```

## `username`

SMB username.

Example:

```text
openwebui
```

## `password`

Password for the SMB account.

The field is presented as a password input in Open WebUI.

## `domain`

Optional Windows/Active Directory domain.

Example:

```text
CORP
```

With:

```text
domain   = CORP
username = jdoe
```

authentication is performed as:

```text
CORP\jdoe
```

If the username already contains `\` or `@`, the tool leaves it unchanged.

Examples:

```text
CORP\jdoe
```

or:

```text
jdoe@example.com
```

## `root_path`

Optional directory inside the SMB share that becomes the logical filesystem root for this Tool.

Example:

```text
OpenWebUI
```

With:

```text
server    = nas01
share     = Documents
root_path = OpenWebUI
```

the actual SMB base becomes:

```text
\\nas01\Documents\OpenWebUI
```

The model only supplies paths relative to this location.

For example:

```text
projects/report.md
```

maps to:

```text
\\nas01\Documents\OpenWebUI\projects\report.md
```

Using `root_path` is strongly recommended because it limits the portion of the share exposed to the Tool.

## `encrypt`

Default:

```text
false
```

When enabled, the SMB connection requests SMB encryption.

The SMB server must support the required SMB3 encryption features.

Consider enabling this when SMB traffic crosses networks where confidentiality cannot otherwise be guaranteed.

## `connection_timeout`

Default:

```text
30
```

SMB connection timeout in seconds.

---

# User Write Permissions

All mutation permissions default to disabled for users.

This means the initial configuration is effectively read-only.

## `allow_write_new_files`

Allows creation of new files.

Requires administrator:

```text
allow_create_files = true
```

## `allow_modify_existing_files`

Allows changes to existing files.

This includes:

- overwrite
- append
- `update_file`
- replacing existing copy/move destinations

Requires administrator:

```text
allow_modify_files = true
```

## `allow_delete_existing_paths`

Allows deletion.

Requires administrator:

```text
allow_delete_paths = true
```

## `allow_directory_operations`

Allows directory creation and directory-related move/delete operations.

Requires administrator:

```text
allow_directory_operations = true
```

## `allow_move_copy_operations`

Allows copy and move operations.

Requires administrator:

```text
allow_move_copy = true
```

---

# Recommended Initial Configuration

For initial testing, keep the Tool read-only.

Administrator:

```text
enabled = true

allowed_server_patterns = nas01.internal.example
allowed_share_patterns = OpenWebUI

allow_create_files = true
allow_modify_files = true
allow_delete_paths = false
allow_directory_operations = true
allow_move_copy = true
allow_recursive_delete = false
allow_alternate_data_streams = false

max_read_bytes = 2097152
max_write_bytes = 4194304
max_list_entries = 500
max_search_results = 200
max_search_depth = 8
```

User:

```text
server = nas01.internal.example
port = 445
share = OpenWebUI
username = openwebui
password = <password>
domain =
root_path =
encrypt = true
connection_timeout = 30

allow_write_new_files = false
allow_modify_existing_files = false
allow_delete_existing_paths = false
allow_directory_operations = false
allow_move_copy_operations = false
```

Run:

```text
test_connection
```

before enabling any write permissions.

---

# Available Tool Functions

## `test_connection`

Tests:

- SMB connectivity
- authentication
- share access
- logical `root_path`

No credentials are returned in the result.

Example request:

```text
Test the SMB connection.
```

---

## `list_directory`

Lists files and directories.

Parameters include:

```text
path
pattern
include_hidden
```

Example:

```text
List the root directory.
```

Example:

```text
List all PDF files in Reports.
```

Equivalent tool arguments could be:

```text
path = Reports
pattern = *.pdf
```

The result includes:

- name
- relative path
- file/directory type
- size
- created time
- modified time
- accessed time

---

## `stat_path`

Returns metadata for a file or directory.

Example:

```text
Show information about Projects/report.md.
```

---

## `read_file`

Reads file data.

Supports:

- text
- configurable encoding
- Base64
- byte offset
- maximum byte count

Example:

```text
Read Notes/todo.txt.
```

For a binary file:

```text
Read image.png as Base64.
```

Large files can be processed incrementally:

```text
offset = 0
max_bytes = 1048576
```

followed by another call with:

```text
offset = 1048576
```

The administrator `max_read_bytes` always takes precedence.

---

## `search_files`

Recursively searches for filenames using wildcard patterns.

Examples:

```text
*.pdf
```

```text
report*
```

```text
*.csv
```

Parameters include:

```text
pattern
start_path
max_depth
include_directories
```

Example:

```text
Find all CSV files below Data.
```

---

## `write_file`

Creates a new file.

It can also overwrite an existing file when:

```text
overwrite = true
```

Creating a file requires:

```text
Valves.allow_create_files = true
UserValves.allow_write_new_files = true
```

Overwriting requires:

```text
Valves.allow_modify_files = true
UserValves.allow_modify_existing_files = true
```

Example:

```text
Create Notes/example.txt containing "Hello world".
```

By default:

```text
overwrite = false
```

which prevents accidental replacement of an existing file.

The operation also supports Base64 content for binary data.

---

## `append_file`

Appends text or binary data to a file.

Requires modification permission when the file exists.

Example:

```text
Append a line to Logs/manual.log.
```

A missing file can optionally be created using:

```text
create_if_missing = true
```

Creating the missing file additionally requires create permission.

---

## `update_file`

Performs exact text replacement in a text file.

This is useful when the model should make a small controlled change instead of rewriting the entire file.

Example:

Existing:

```text
server=old-server
port=445
```

Request:

```text
Replace "server=old-server" with "server=new-server".
```

The operation supports:

```text
replace_all
expected_replacements
```

`expected_replacements` can be used as an additional safety check.

For example:

```text
expected_replacements = 1
```

causes the operation to fail rather than modify the file if the requested replacement would affect a different number of occurrences.

For sensitive configuration files this is recommended.

---

## `make_directory`

Creates a directory.

Supports:

```text
parents
exist_ok
```

Example:

```text
Create Projects/2026/Reports and create missing parent folders.
```

This requires directory-operation permission.

---

## `copy_file`

Copies a file within the configured SMB share/root.

Example:

```text
Copy Templates/report.md to Projects/report.md.
```

If the destination already exists, replacement requires:

```text
overwrite = true
```

and modification permission.

---

## `move_path`

Moves or renames files and directories within the configured SMB share/root.

Example:

```text
Rename Drafts/report.md to Drafts/report-old.md.
```

or:

```text
Move Drafts/report.md to Published/report.md.
```

Directory moves require directory-operation permission.

---

## `delete_path`

Deletes a file or directory.

Deletion is disabled by default at both policy and user levels.

A normal file delete requires:

```text
Valves.allow_delete_paths = true
UserValves.allow_delete_existing_paths = true
```

Deleting an empty directory additionally requires directory operations.

Recursive directory deletion additionally requires:

```text
Valves.allow_recursive_delete = true
```

Example:

```text
Delete Temp/file.txt.
```

Recursive delete should only be enabled when there is a clear operational requirement.

---

# Path Security

All model-supplied paths are relative paths.

The Tool rejects:

- UNC paths
- absolute paths
- drive-letter paths
- `..` traversal
- Alternate Data Stream syntax unless explicitly enabled

For example, this is valid:

```text
Projects/Report.txt
```

These are rejected:

```text
..\..\secret.txt
```

```text
\\another-server\share\file.txt
```

```text
C:\Windows\file.txt
```

The configured SMB server/share cannot therefore be replaced through a normal file-operation argument.

The `root_path` setting provides an additional confinement boundary within the configured share.

---

# SMB Session Isolation

The Python `smbclient` implementation maintains a process-wide connection/session cache.

This matters in a multi-user Open WebUI instance because different users may configure different SMB credentials.

The Tool therefore:

1. serializes SMB access with a process-wide lock,
2. clears the `smbclient` connection cache before an operation,
3. registers only the current user's SMB session,
4. executes the operation,
5. clears the connection cache again afterward.

This prioritizes credential/session isolation over parallel SMB operation throughput.

If very high SMB concurrency is required, this design should be reviewed before changing the locking/session model.

---

# EventEmitter Status Reporting

All public operations use the included `EventEmitter`.

The Tool reports:

```text
in_progress
```

while an SMB operation is executing.

On completion it reports either:

```text
success
```

or:

```text
error
```

with:

```text
done = true
```

This provides visible operation status in Open WebUI while the model is working with the SMB share.

---

# Security Recommendations

## Use a dedicated SMB account

Do not use a personal administrator account.

Create an SMB/service account specifically for Open WebUI.

Give that account only the filesystem permissions required for the intended use.

For a read-only Tool, the SMB account itself should preferably also have read-only permissions.

Application-level permission controls should not be the only protection.

## Use a dedicated share or directory

Prefer:

```text
\\nas01\OpenWebUI
```

or configure:

```text
root_path = OpenWebUI
```

instead of exposing a broad company/user share.

## Restrict servers and shares

Avoid production settings such as:

```text
allowed_server_patterns = *
allowed_share_patterns = *
```

Prefer explicit values:

```text
allowed_server_patterns = nas01.internal.example
allowed_share_patterns = AI-Documents
```

## Keep delete disabled unless required

Recommended default:

```text
allow_delete_paths = false
allow_recursive_delete = false
```

## Keep Alternate Data Streams disabled

Recommended:

```text
allow_alternate_data_streams = false
```

## Use SMB encryption where appropriate

When supported by the server:

```text
encrypt = true
```

SMB encryption protects SMB payloads in transit.

## Protect stored credentials

`UserValves.password` contains an SMB credential.

Configure Open WebUI so sensitive Valve values are protected appropriately, and protect the Open WebUI database, backups, configuration, and secret keys.

Do not give Tool-administration access to users who should not be able to change its security policy.

## Use least privilege at both layers

There are two distinct permission layers:

1. SMB filesystem/share permissions
2. Tool `Valves` / `UserValves`

Configure both.

For example, if an account only needs read access, make it read-only on the SMB server even if the Tool's write switches are accidentally changed later.

---

# Suggested Permission Profiles

## Read-only

Administrator:

```text
allow_create_files = false
allow_modify_files = false
allow_delete_paths = false
allow_directory_operations = false
allow_move_copy = false
allow_recursive_delete = false
```

User mutation switches:

```text
false
```

Use for knowledge/document retrieval.

## Read + create

Administrator:

```text
allow_create_files = true
allow_modify_files = false
allow_delete_paths = false
```

User:

```text
allow_write_new_files = true
allow_modify_existing_files = false
allow_delete_existing_paths = false
```

Useful when the model may generate new reports but must never alter existing documents.

## Read + create + update

Administrator:

```text
allow_create_files = true
allow_modify_files = true
allow_delete_paths = false
```

User:

```text
allow_write_new_files = true
allow_modify_existing_files = true
allow_delete_existing_paths = false
```

This is a reasonable general-purpose document-management profile.

## Full file management

Administrator:

```text
allow_create_files = true
allow_modify_files = true
allow_delete_paths = true
allow_directory_operations = true
allow_move_copy = true
```

User:

```text
allow_write_new_files = true
allow_modify_existing_files = true
allow_delete_existing_paths = true
allow_directory_operations = true
allow_move_copy_operations = true
```

Consider leaving:

```text
allow_recursive_delete = false
```

unless recursive removal is truly needed.

---

# Example Open WebUI Prompts

Once the Tool is enabled for a model, typical prompts include:

```text
List the files in the Reports directory.
```

```text
Find all PDF files under Projects.
```

```text
Read Projects/README.md and summarize it.
```

```text
Create Notes/meeting.txt with the following notes...
```

```text
Change "server01" to "server02" in Config/application.conf.
Only make the change if there is exactly one occurrence.
```

```text
Copy Templates/monthly-report.md to Reports/2026-08.md.
```

```text
Move Drafts/report.md to Approved/report.md.
```

The language model decides which Tool function to call based on the function descriptions and parameters.

---

# Troubleshooting

## Connection refused or timeout

Verify:

- SMB server hostname/IP
- TCP port `445`
- routing between Open WebUI and the SMB server
- host firewall
- container/network firewall
- SMB service availability

If Open WebUI runs in Docker, test connectivity from the Open WebUI container/network rather than only from the Docker host.

## Authentication failure

Check:

- username
- password
- domain
- SMB account status
- server authentication policy

For Active Directory, try either:

```text
domain = CORP
username = jdoe
```

or configure the username directly as:

```text
CORP\jdoe
```

or, where supported:

```text
jdoe@example.com
```

## Access denied

Successful authentication does not imply filesystem access.

Check both:

- SMB share permissions
- underlying filesystem/NTFS permissions

Also verify that the corresponding Tool/UserValve mutation permission is enabled.

## Server not allowed

If the Tool reports that the server is not allowed, check:

```text
allowed_server_patterns
```

Example:

```text
nas01.internal.example
```

must match the user's:

```text
server
```

## Share not allowed

Check:

```text
allowed_share_patterns
```

against the configured:

```text
share
```

## Cannot create or modify files

Check both administrator and user controls.

Creating:

```text
Valves.allow_create_files
UserValves.allow_write_new_files
```

Modifying:

```text
Valves.allow_modify_files
UserValves.allow_modify_existing_files
```

The SMB account itself must also have write permission.

## Cannot delete files

Deletion requires:

```text
Valves.allow_delete_paths = true
UserValves.allow_delete_existing_paths = true
```

Recursive directory deletion additionally requires:

```text
Valves.allow_recursive_delete = true
```

## File is too large

Read and write operations are constrained by:

```text
max_read_bytes
max_write_bytes
```

Use chunked reads for large files.

For very large file transfer workloads, this Tool is intentionally not optimized as a bulk SMB transfer utility.

## Binary file cannot be decoded

Use:

```text
as_base64 = true
```

with `read_file`.

For binary writes, provide Base64 and use:

```text
content_is_base64 = true
```

## Update text was not found

`update_file` performs exact text replacement.

Whitespace, line endings, capitalization, and encoding therefore matter.

Read the relevant part of the file first and use the exact existing text.

---

# Limitations

- Operations are confined to one configured SMB server/share/root per user.
- Copy/move functions operate inside that configured logical SMB root.
- SMB operations are serialized to protect per-user session isolation.
- The Tool is intended for controlled model-driven file operations, not high-throughput file transfer.
- `update_file` performs exact text replacement rather than semantic document editing.
- Large files are constrained by administrator-configured limits.
- SMB permissions remain ultimately controlled by the SMB server and filesystem ACLs.
- The Tool cannot grant permissions that the configured SMB account does not possess.

---

# File Layout

A simple deployment/repository layout could be:

```text
open-webui-smb-tool/
├── open_webui_smb_file_operations.py
└── README.md
```

---

# Version

Tool version:

```text
0.1.0
```

Minimum declared Open WebUI version:

```text
0.6.3
```

Python dependency:

```text
smbprotocol>=1.17.0
```

---

# License

MIT