Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version

## Unreleased

- **The file tree over NFS.** Settings → NFS share serves the archive's folders and files (namespaces, collections,
topics and entities as folders, assets as files) read-only over NFS, to the networks you allow, showing what one
chosen account sees. Off until turned on; published on port 12049 of the host ([File shares](docs/file-shares.md)).

- **The graph as files over SMB.** Settings → SMB share serves the file tree read-only to Finder, Linux and (on port
445) Windows: each person signs in with a file access key and sees what the web app shows them, from the networks
an admin allows. Off by default; the SMB server (impacket) is fetched when it's turned on ([SMB share](docs/smb.md)).
Expand Down
4 changes: 4 additions & 0 deletions docker-compose.prod.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ x-backend: &backend
LENS_TUNNEL_ORIGIN: http://frontend:3000
# the web app's container (and the one running the tunnel): their X-Forwarded-For names the visitor, for throttles
LENS_TRUSTED_PROXY_HOSTS: frontend,backend,worker
LENS_NFS_PORT: ${LENS_NFS_PORT:-12049} # where the NFS share is published, for the mount command Settings shows
# the SMB share of the file tree (docs/smb.md): listens on 4445 in the container; LENS_SMB_PORT is where it's
# published, for the address Settings shows
LENS_SMB_LISTEN: 0.0.0.0
Expand Down Expand Up @@ -112,6 +113,9 @@ services:
- "${LENS_SENSOR_BIND:-${LENS_BIND:-127.0.0.1}}:${LENS_MQTT_PORT:-1883}:1883"
- "${LENS_SENSOR_BIND:-${LENS_BIND:-127.0.0.1}}:${LENS_SYSLOG_PORT:-5514}:5514/udp"
- "${LENS_SENSOR_BIND:-${LENS_BIND:-127.0.0.1}}:${LENS_SYSLOG_PORT:-5514}:5514/tcp"
# the file tree over NFS (docs/file-tree.md), served only once it's turned on in Settings → NFS share, and then
# only to the networks allowed there. 12049 on this machine so a host NFS server on 2049 is never in the way.
- "${LENS_SHARE_BIND:-${LENS_BIND:-127.0.0.1}}:${LENS_NFS_PORT:-12049}:2049"
# the file tree over SMB (docs/smb.md), served only once it's turned on in Settings → SMB share, and then only
# to the networks allowed there. 1445 on this machine so an SMB server the host runs on 445 is never in the way
# (Windows only connects to 445: install with LENS_SMB_PORT=445 for it; install.sh keeps it).
Expand Down
2 changes: 2 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ x-backend: &backend
SURREAL_URL: ws://surrealdb:8000
SURREAL_USER: ${SURREAL_USER:-root}
SURREAL_PASS: ${SURREAL_PASS:-root}
LENS_NFS_PORT: ${LENS_NFS_PORT:-12049}
ARCHIVE_CONFIG: /app/docker/archive.yaml
RUN_BACKGROUND: "false"
MAIL_SERVER: mail
Expand Down Expand Up @@ -91,6 +92,7 @@ services:
- "${LENS_SENSOR_BIND:-127.0.0.1}:${LENS_MQTT_PORT:-1883}:1883"
- "${LENS_SENSOR_BIND:-127.0.0.1}:${LENS_SYSLOG_PORT:-5514}:5514/udp"
- "${LENS_SENSOR_BIND:-127.0.0.1}:${LENS_SYSLOG_PORT:-5514}:5514/tcp"
- "${LENS_SHARE_BIND:-127.0.0.1}:${LENS_NFS_PORT:-12049}:2049" # the file tree over NFS, once turned on
- "${LENS_SHARE_BIND:-127.0.0.1}:${LENS_SMB_PORT:-1445}:4445" # the file tree over SMB, once turned on
# the graph as files over S3 and WebDAV (docs/file-tree.md), once File shares are on; LENS_S3_PORT / LENS_WEBDAV_PORT
- "${LENS_SHARE_BIND:-127.0.0.1}:${LENS_S3_PORT:-9555}:9555"
Expand Down
60 changes: 60 additions & 0 deletions docs/file-shares.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# NFS share

Lens can show the archive as folders and files ([the file tree](file-tree.md)) to other machines, so a file manager,
a media player or a script reads it like any other share: namespaces, collections, topics and entities are folders,
and assets are files inside them.

## NFS

Settings → NFS share → **Share the file tree over NFS**. It's off until you turn it on, and then a worker starts
serving within seconds. The share is **read-only**.

Mount it on Linux (Settings shows the command with your port filled in):

```sh
sudo mount -t nfs -o port=12049,mountport=12049,tcp,vers=3,ro <lens-machine>:/ /mnt/lens
```

On macOS: `sudo mount -t nfs -o port=12049,mountport=12049,tcp,vers=3,ro,resvport <lens-machine>:/ /Volumes/lens`.

| Setting | Default | What it does |
| --- | --- | --- |
| `nfs.enabled` | off | Serve the share |
| `nfs.account` | the first admin | Whose view of the tree the share shows: it holds exactly what that person sees in the web app |
| `nfs.allowed_networks` | private networks (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `fc00::/7`, `::1/128`) | Machines anywhere else are turned away before they read anything; changes apply without a restart |
| `nfs.port` | 2049 | The port inside Lens (with Docker, inside the worker container) |

With Docker, the worker container publishes the share on port **12049** of the host (`LENS_NFS_PORT` in `.env` picks
another), so an NFS server the host already runs on 2049 is never in the way. Like the web app, it's reachable from
this machine only unless `LENS_BIND=0.0.0.0` (what `install.sh` sets on a server); `LENS_SHARE_BIND` opens the share
on its own while the web app stays local.

### NFS has no login

NFS (version 3) trusts the network: there is no password, passkey or token. So Lens:

- serves nothing until an admin turns it on;
- serves it read-only, so nothing reaching the share can change the archive;
- shows one account's view (`nfs.account`), never more than that person may see; pick an account that sees only what
the share should show (a member of just the namespaces or collections to share), not an admin, when the network has
people who shouldn't see everything;
- turns away every client outside `nfs.allowed_networks`, and counts them in Settings.

Anyone on an allowed network can read the share, and an address on the local network can be spoofed, so list only your
own networks, and keep the port off the internet.

### How it works

A worker runs `rclone serve nfs --read-only` (rclone is in Lens's image already; MIT licensed) over Lens's own S3
server (a copy on 127.0.0.1 inside the worker, so the S3 share itself needn't be on), signed in with an S3 key
made for `nfs.account`, which is revoked when the share stops. rclone listens on 127.0.0.1 inside the container; a small
relay in Lens (`domain/share_relay.py`) holds the published port and hands rclone only the connections from allowed
networks. One worker serves it at a time (a lease on `app_service:nfs`), and Settings shows which one, whose view it
shows, how many connections it turned away, and rclone's last lines when something goes wrong. Agents read the same
state at `GET /api/v1/settings/nfs/status` and change it with `PUT /api/v1/settings/nfs`.

### Refine later

- NFS version 4 and Kerberos (sec=krb5) for a share with a real login.
- A share per namespace or collection, each with its own account and networks.
- Packaging for the Synology and QNAP compose files, which don't publish the port yet.
2 changes: 1 addition & 1 deletion docs/file-tree.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Lens without learning its API.
| --- | --- |
| The API (`GET /api/v1/tree`, `GET /api/v1/tree/file`) and the MCP tools `list_files` and `read_file` | built |
| An [S3 server](#s3) and a [WebDAV server](#webdav) (read-only, off until turned on) | built |
| An [NFS share](file-shares.md) (read-only, off until turned on, allowed networks only) | built |
| An [SMB share](smb.md) (read-only, off until turned on) | built |
| An NFS share | in progress |

Every way in serves the same tree, built by `app/domain/filetree.py`.

Expand Down
8 changes: 8 additions & 0 deletions fastapi_backend/app/api/v1/routes/admin.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
machine,
matterbridge,
monitoring,
nfs_share,
semantic,
settings,
smb_share,
Expand Down Expand Up @@ -54,6 +55,7 @@
LlmTestResult,
LocalLlmStatus,
MailTestResult,
NfsStatus,
Removed,
SemanticStatus,
SmbStatus,
Expand Down Expand Up @@ -180,6 +182,12 @@ def remove_local_model(user: AdminWriter, cfg: Cfg, db: Db, model: str = Query(.
return Removed(removed=removed)


@router.get("/settings/nfs/status")
def nfs_status(user: AdminReader, cfg: Cfg, db: Db) -> NfsStatus:
"""The file tree over NFS: whether it's serving, as whom, to which networks, and the command that mounts it."""
return NfsStatus.model_validate(nfs_share.status(db, cfg))


@router.get("/settings/smb/status")
def smb_status(user: AdminReader, cfg: Cfg, db: Db) -> SmbStatus:
"""The file tree over SMB (Settings › SMB share): whether it's serving, to which networks, and how to connect."""
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,7 @@ def platform_main(argv, config):
https,
jobs,
local_llm,
nfs_share,
notify,
passkeys,
routines,
Expand Down Expand Up @@ -387,6 +388,7 @@ def password():
tunnel.start(db, C, stop, name=wk.name, log=print) # and the Cloudflare tunnel, while it's on
https.start(db, C, stop, name=wk.name, log=print) # and HTTPS, where the ports are (LENS_HTTPS_LISTEN)
local_llm.start(db, C, stop, name=wk.name, log=print) # and the local chat model, while it's on
nfs_share.start(db, C, stop, name=wk.name, log=print) # and the file tree over NFS, while it's on
updates.start(db, C, stop, log=print) # and the daily check for a new release (docs/updates.md)
_stop_on_term()
try:
Expand Down
Loading
Loading