Follower Node Storage Policy Tutorial

What this page covers

This page explains how to use an already connected follower node as a storage policy backend: create a remote storage target, create a remote storage policy, configure policy group rules, bind users or teams, and verify real uploads and downloads.

If you have not connected the follower node to the primary node yet, start with Follower Nodes.
If you run follower nodes with Docker, start with Deploy a Follower Node with Docker.

When to Use It

Follower nodes are suitable for these scenarios:

• The primary node handles login, the admin console, sharing, and WebDAV, while real objects are written to another machine
• You have an extra storage machine at home, in the office, or in a server room
• You want to route large files or files from a specific team to an independent node
• You want a follower node to write to its own local disk or to S3 / MinIO that it can access

It is not a multi-primary cluster or automatic failover. The primary node is still the only control plane.

Choose transport according to your network

Follower nodes now have three transport modes:

• direct: the primary connects directly to the follower base_url
• reverse_tunnel: the follower actively connects to the primary, and base_url can stay empty
• auto: direct when base_url is set, reverse tunnel when it is empty

If the follower is behind NAT, CGNAT, or a private-only network and can only reach the primary outbound, choose reverse tunnel. Reverse tunnel is still under test and is suitable for relay_stream upload/download. If you need presigned, you still need direct transport, and browsers must also be able to reach the follower base_url.

First, Separate the Three Layers

Each layer is responsible for something different:

Layer	Responsibility	Entry
Follower node record	The primary node knows which follower node exists and how to access it	Admin -> Follower Nodes
Remote storage target	Whether the follower node writes received objects to local storage or S3	Admin -> Follower Nodes -> Node Details
remote storage policy	Which follower node is selected during upload	Admin -> Storage Policies
Policy group	Which users / teams / file sizes match this policy	Admin -> Policy Groups

Before creating a remote policy or switching policy groups, test the node connection from the primary. The connection test checks whether the primary and follower versions and upload capabilities are compatible. Upgrade the older node when the test reports an incompatibility.

1. Confirm the Follower Node Is Ready

In the primary node admin console, open:

Admin -> Follower Nodes

Confirm that the target node meets these conditions:

• Enrollment is complete
• It is enabled
• The transport mode matches the network topology
• If using direct transport, base_url is an address the primary node can access
• If using reverse tunnel, the tunnel status is online
• “Test Connection” succeeds
• The admin console reports a healthy node state

If base_url is empty, only reverse_tunnel or auto can carry remote traffic. A direct node must have an HTTP(S) address reachable by the primary. Before production, confirm that “Test Connection” passes with the current transport mode.

2. Create the Default Remote Storage Target

Open the target follower node details and find:

Remote Storage Targets

For the first setup, create a local remote storage target.

Example:

Field	Recommendation
Name	default-local
Driver	local
Base path	default
Default remote storage target	Enabled

The base path of a local remote storage target can only be a relative path.

It is ultimately placed under the follower node’s own:

server.follower.remote_storage_target_local_root

For example, if the follower node configuration is:

[server.follower]
remote_storage_target_local_root = "/data/remote-storage-targets"

And the remote storage target base path is:

default

Objects are ultimately written to:

/data/remote-storage-targets/default

Without a default remote storage target, a remote policy cannot actually write data

Successful enrollment only means the primary and follower identities are bound. Before receiving real objects, the follower node also needs an applied default remote storage target.

3. Choose local or s3 for the Remote Storage Target

Remote storage target	Best for	Notes
local	Follower node local disks or NAS-mounted directories	The base path must be relative and is restricted under the follower local target root directory
s3	Object storage that the follower node’s network can access	Credentials and endpoint are stored in the follower node remote storage target configuration

For the first integration, use local to prove the path from the primary node to the follower node.
After confirming it is stable, switch the follower remote storage target to s3 if needed.

4. Create a remote Storage Policy

Open:

Admin -> Storage Policies -> New Policy

Choose the driver type:

remote

Fill in:

Field	Recommendation
Name	A name that identifies the node, such as Remote Follower A
Follower node	Select the node you just connected and tested successfully
Single-file size limit	Set this according to the test scenario first; 0 means unlimited
Chunk size	Keep the default for the first setup
Upload mode	Use relay_stream for the first setup
Download mode	Use relay_stream for the first setup

Save it first, then run a connection test.

5. Choosing Upload and Download Modes

First Choice: relay_stream

Upload path:

Download path:

Advantages:

• The browser only needs to access the primary node
• The troubleshooting path is clear
• Works with both direct transport and reverse tunnel

Trade-off:

• The primary node still carries upload and download bandwidth

Advanced: presigned

During upload or download, the browser directly accesses a short-lived URL generated by the follower node.

Suitable when:

• You want to reduce bandwidth pressure on the primary node
• The remote node uses direct transport
• The browser can reliably access the follower node base_url
• The reverse proxy already exposes the follower node correctly

Before using it, confirm:

• The remote node transport is not reverse tunnel
• The follower node base_url is reachable from the browser
• The HTTPS certificate is trusted
• The reverse proxy does not intercept upload / download paths or required response headers
• The follower node remote storage target has been applied successfully
• The primary connection test confirms that the node supports browser-direct transfer

If the primary node can access the follower node, but user browsers cannot, do not use remote presigned. If the remote node uses reverse tunnel, also avoid presigned and use relay_stream instead.

A Tailscale / VPN Address Is Not a Public Address

If the follower base_url is a Tailscale IP, MagicDNS name, or an internal name that only resolves through split DNS, remote presigned is suitable only for tailnet / VPN users. After public users open the primary site, their browsers are still redirected to that follower address. If the public network cannot resolve or route to it, upload and download fail.

To let public users access these files, either give the follower a public HTTPS address, or set the remote policy upload/download mode to relay_stream so the primary relays the traffic. For topology trade-offs, see Follower Node Network Topologies.

Remote presigned requires the follower to allow browser cross-origin access. AsterDrive provides the required defaults. If nginx, Caddy, Traefik, or a CDN sits in front of the follower, confirm that it does not replace CORS rules or break large uploads, resumed downloads, and media previews.

6. Create a Test Policy Group

Do not directly modify the default policy group. Create a test policy group first:

Admin -> Policy Groups -> New Policy Group

Example:

Remote Test Group

Add a rule:

Field	Recommendation
Storage policy	The remote policy you just created
Priority	Keep the default or set it to match first
File size range	Cover all sizes for the first test

7. Bind a Test User or Team

Bind a User

Open:

Admin -> Users -> User Details

Change the test user’s policy group to Remote Test Group.

Bind a Team

Open:

Admin -> Teams -> Team Details

Change the test team’s policy group to Remote Test Group.

Team space uploads match the team policy group, not the individual user’s policy group.

8. Run a Real Acceptance Check

Log in as the test user and verify, in order:

1. Upload a small file
2. Upload a large file
3. Download the file
4. Create and open a share link
5. Delete the file, then restore it from the trash
6. If previews are enabled, open an image or PDF once
7. On the follower node, check whether objects appear in the remote storage target directory or object storage
8. Return to Admin -> Follower Nodes on the primary node and test the connection again, confirming that the node state is still normal

If all of these pass, then consider moving real users or teams to the remote policy group.

9. Route by Size to a Follower Node

A common pattern:

Configure multiple rules in the policy group, for example:

Rule	File size range	Storage policy
Small files	0 to 100 MiB	Local policy
Large files	Above 100 MiB	remote policy

After saving, upload small and large files separately and confirm that the matched storage policy is as expected.

10. Move Real Users or Teams

After confirming the test works, choose a migration method:

Scenario	Method
Only a few users should use the follower node	Bind policy groups one by one under Admin -> Users
A specific team should use the follower node	Bind a policy group under Admin -> Teams
New users should use the follower node by default	Set the remote policy group as the default policy group for new users
Gradual migration	Adjust bindings in batches while watching tasks, logs, and follower node health

Changing a policy group only affects future uploads. Old files are still read through their original storage policies.

11. Routine Maintenance

Check regularly:

• Whether the remote node connection test succeeds
• If reverse tunnel is used, whether the tunnel is online and has no recent errors
• Whether the admin console reports a healthy follower state
• Whether the default remote storage target is still applied
• Whether the follower local target root directory has enough disk space
• If the follower writes to S3, whether the S3 credentials are still valid
• Whether the remote policy group is still enabled
• Whether there have been recent errors related to remote uploads / downloads

The follower node’s local remote-storage-target directory is formal data and must be included in the backup strategy.

If the remote storage target is S3, handle it according to the backup and versioning strategy for object storage.

12. Common Issues

Primary Connection Test Fails

Check first:

• Whether the remote node transport mode is correct
• In direct mode, whether base_url is an address the primary can actually reach
• In reverse tunnel mode, whether the follower can reach the primary public_site_url, and whether proxies allow WebSocket and long-lived connections
• Whether the follower service is running
• Whether the follower is listening on an externally reachable address
• Whether the reverse proxy or firewall allows the traffic
• Whether the admin console reports a healthy node state
• Whether the connection test reports incompatible primary and follower versions

remote Policy Upload Fails

Check in this order:

1. Whether the remote node is enabled
2. Whether enrollment is complete
3. Whether an applied default remote storage target exists
4. Whether the follower local target root directory is writable
5. Whether policy group rules really match the remote policy
6. Whether the user or team quota is already full
7. Whether the primary and follower logs contain matching errors

presigned Fails but relay_stream Works

This usually means the path from primary to follower is fine, but the browser-to-follower path is not.

Check:

• Whether the remote node uses direct transport
• Whether the browser can access the follower base_url
• Whether the HTTPS certificate is trusted
• Whether the reverse proxy forwards upload/download paths
• Whether CORS on the follower or reverse proxy is correct
• Whether the reverse proxy interferes with large uploads, resumed downloads, or media previews
• Whether a company network or browser policy blocks the follower domain

Existing Files Suddenly Disappear

First confirm whether anyone recently changed:

• the remote node bound by the remote policy
• the follower remote storage target
• remote_storage_target_local_root
• the follower local directory
• the S3 endpoint / bucket / prefix used by the follower remote storage target

All of these fields decide where old objects live. Do not directly edit a real target that is already in use.