Skip to content

docs(configuration): document plugin access to the local network #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jannefleischer wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(configuration): document plugin access to the local network #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions docs/configuration/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,13 @@ a built-in **Plugins** tab with a plugin manager, where individual users can add
plugins for their own session without server access. This is useful for testing
a plugin before deploying it for everyone.

## Plugins that access the local network

Some plugins send requests directly from the user's browser to a service on the
internal network, for example an AI plugin using a local Ollama instance.
Chromium-based browsers and Firefox (since version 153) block these requests unless
the server explicitly allows it. See [Plugin access to the local network](server.md#plugin-access-to-the-local-network).

## Removing a plugin

Remove the plugin's folder and re-register so the editors stop loading it.
Expand Down
31 changes: 31 additions & 0 deletions docs/configuration/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ sudo supervisorctl restart all
| RabbitMQ | `rabbitmq.url` |
| WOPI | `wopi.enable` |
| Allow private-IP requests | `services.CoAuthoring.request-filtering-agent.allowPrivateIPAddress` |
| Allow local network access for plugins | `security.allowLocalNetworkAccessIframes` |

## Docker

Expand Down Expand Up @@ -231,6 +232,36 @@ These control how the Document Server fetches documents from storage such as Nex
| `ADMINPANEL_ENABLED` | `false` | Start the administration panel service |
| `EXAMPLE_ENABLED` | `false` | Start the bundled example application at `/example/`. Do not enable it on a public instance |

#### Plugin access to the local network

| Variable | Default | Description |
|---|---|---|
| `ALLOW_LOCAL_NETWORK_ACCESS_IFRAMES` | `false` | Allow plugins to send requests from the user's browser to private network addresses, for example an AI plugin talking to an internal Ollama instance |

Chromium-based browsers (Chrome, Edge, Brave, Opera, …) and Firefox (since version 153)
block requests from a web page to private network addresses (RFC 1918 ranges,
`localhost`) unless every iframe on the way delegates the `local-network` /
`loopback-network` permission. Plugins run in iframes inside the editor iframe, so
by default such requests fail in the browser, even when CORS is configured correctly
on the target. See Chrome's [announcement of Local Network Access](https://developer.chrome.com/blog/local-network-access), the
[Local Network Access specification](https://wicg.github.io/local-network-access/#permissions) and Firefox's
[documentation of the `network.lna.*` preferences](https://support.mozilla.org/en-US/kb/control-personal-device-local-network-permissions-firefox) for details.

With `ALLOW_LOCAL_NETWORK_ACCESS_IFRAMES=true`, the plugin iframes delegate this
permission. The browser then applies its normal checks, including a permission
prompt for the user. Integrations such as Nextcloud or Seafile need no changes.

!!! warning "Plugins can reach your internal network"
When enabled, any installed plugin can send requests from the user's browser
to hosts on the user's local network, including services that are not
reachable from the internet. Only enable it if you need it, and only install
plugins you trust.

!!! note "Browser support"
The setting works in Chromium-based browsers and in Firefox 153 and later.
Safari does not support it yet; WebKit is implementing it
([WebKit#72725](https://github.com/WebKit/WebKit/pull/72725), [#74003](https://github.com/WebKit/WebKit/pull/74003), [#74740](https://github.com/WebKit/WebKit/pull/74740)).

### Size limits

Four variables limit file sizes, and they apply to two independent paths through the
Expand Down