Skip to content

External Storage

Gibran Khan edited this page Nov 18, 2026 · 2 revisions

External storage and custom firewall rules

Optional external files

In Applications, enable External files to connect Nextcloud to existing SFTP or HTTP/HTTPS storage. It is off by default, even when you select all apps. You can use it with any office choice, with or without Talk. SMB/CIFS and FTP/FTPS are not included as installer options.

After installation, open Administration settings → External storage in Nextcloud. Add your storage server, enter its credentials and choose who can access it. Only administrators can add these connections.

The installer checks that the External files app is enabled and only administrators can add storage. Test each connection yourself and back up external storage separately.

Network access

External files allows outbound TCP ports 22, 80 and 443 from the Nextcloud jail to LAN and Internet storage. Here, LAN means private IPv4 addresses in 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16, reached through the host's network interface.

The host and other managed networks remain protected. This adds no inbound access and no storage access for office or Talk services. Existing DNS and application connections stay unchanged.

Prefer SFTP or HTTPS for encrypted connections. SFTP uses SSH, usually on port 22; it is not FTP/FTPS. Other ports need custom rules as described below.

Administrator PF files

New installations have a separate PF anchor for each instance's custom Nextcloud outbound rules, whether or not External files is selected. Its file is /etc/pf.nextcloud-custom/INSTANCE.conf. The installer creates it with no active rules and preserves your edits. Older installations do not gain this feature automatically.

Custom rules can add outbound access. They cannot remove built-in allowances or bypass host and managed-network isolation. Keep edits in the custom file: changing /etc/pf.cloud-installer.conf or placing filters before the project's parent anchor makes installer verification fail.

Edit, validate and reload

Run these commands as root on the FreeBSD host. Replace cloud with the installed instance name. Keep the directory root-owned with mode 0700 and the file root-owned with mode 0600; symlinks and hardlinks are refused.

vi /etc/pf.nextcloud-custom/cloud.conf

Use one rule per line in this format:

# A particular HTTPS storage server on a nonstandard port
pass inet proto tcp to 192.168.50.10 port 8443 keep state (if-bound)
# A particular remote SFTP server
pass inet proto tcp to 198.51.100.20 port 2222 keep state (if-bound)

The second address is documentation-only; substitute your actual server. Only IPv4 TCP/UDP pass rules in this format are accepted. Use a numeric address or canonical network/prefix and a port from 1–65535 or inclusive range such as 50000:50100. Optional fields are quick, from any and TCP flags S/SA. keep state (if-bound) is required. The installer restricts the rules to this instance's Nextcloud jail and its outbound interfaces.

Files must be ASCII, at most 64 KiB and 256 rules. Blank lines and comments are allowed. Other PF syntax—including hostnames, any destinations, /0, port lists, macros, tables, includes, nested anchors, tags, routing overrides, NAT and inbound rules—is rejected. Use multiple lines for multiple ports or destinations.

Check PF syntax without applying changes:

pfctl -a nextcloudonfreebsd/admin-cloud -nf /etc/pf.nextcloud-custom/cloud.conf

Then use the installed helper to validate the supported rules and managed policy and reload the files:

active=/var/db/cloud-installer/network/active
/usr/local/bin/python3 -I -B "$active/firewall-watchdog.py" reload-custom "$active"

This checks all active custom files, then reloads all active instances' files one anchor at a time. Review all pending edits first. It refuses to run during an installer operation or while network recovery is pending. If a native PF load fails, earlier files may already be applied. Inspect the affected anchors, correct the files and retry the helper. Use this helper for reloads rather than loading files directly.

Inspect the live rules:

pfctl -a nextcloudonfreebsd/admin-cloud -P -sr

Remove an allowance by removing its line and running the helper again. To disable an instance's custom allowances, leave its file empty or comment-only. Keep the file in place. Reloads do not flush existing connections; old states may remain until expiry, so removing a rule may not stop an established transfer.

Persistence and recovery

  • Cold boot loads the files on disk before the parent PF policy. Missing or invalid files stop the managed startup checks.
  • Normal installer operations preserve the current live custom rules. Pending file edits take effect on an explicit reload or the next boot.
  • Network rollback restores the previous live custom rules captured for that operation, without reading or changing your files on disk.
  • Removing an instance removes its custom rules and keeps its file.

Testing note: native PF loading, reboot/recovery and real storage-connection checks are still pending.

Clone this wiki locally