Make SFTP external storage timeout configurable

It would be useful to make the timeout used by the SFTP External Storage backend configurable per mount.

Currently the SFTP storage creates the phpseclib client without specifying a timeout:

$this->client = new \phpseclib\Net\SFTP($this->host, $this->port);

phpseclib therefore uses its default timeout of 10 seconds.

This can be too short for SFTP external storage located over the Internet, especially when several users are accessing the same remote storage and background jobs are also reading files.

Real-world use case

My setup is:

• Nextcloud Server 33.0.7
• Standard PHP installation on a web server
• files_external using SFTP
• Remote storage is a Synology NAS at another physical location
• The NAS is behind a router/NAT and SFTP is exposed through a dedicated forwarded port
• 4 Nextcloud users can upload files to this external storage
• Android clients use automatic photo/video upload to this SFTP external storage
• Previews are disabled for this external storage

Uploads to normal Nextcloud local storage work quickly and reliably.

However, when uploading a large batch of files to the SFTP external storage, uploads work initially and then start failing intermittently.

The Android client sometimes reports the error as:

You don't have permission to upload to this folder

The permissions on the SFTP server are correct.

At the same time, Nextcloud logs errors such as:

GenericFileException
issue while running UpdateSingleMetadata

and:

fopen(sftpread://.../IMG-20260812-WA0001.jpg):
Failed to open stream:
"OCA\Files_External\Lib\Storage\SFTPReadStream::stream_open" call failed

The Synology SFTP logs do not show permission errors. They show normal uploads, downloads, moves, logins and logouts.

The problem is particularly noticeable while Nextcloud cron/background jobs are running and accessing files already stored on the SFTP mount.

Test performed

As a diagnostic test I changed:

$this->client = new \phpseclib\Net\SFTP($this->host, $this->port);

to:

$this->client = new \phpseclib\Net\SFTP($this->host, $this->port, 60);

With the default 10-second timeout, a batch of approximately 270 photo/video uploads would start producing intermittent failures after roughly 30-50 files.

With the timeout changed to 60 seconds, the same workload became substantially more stable and the files continued uploading successfully.

At one point the Android client displayed "waiting for server", but instead of failing after approximately 10 seconds, the operation recovered and uploads continued.

This strongly suggests that the fixed 10-second timeout is too short for some legitimate remote SFTP configurations.

Why this would be useful

SFTP external storage is often used precisely when the remote storage is not on the same LAN as the Nextcloud server.

Typical configurations may include:

• NAS devices at remote locations
• SFTP servers behind NAT
• WAN or VPN connections
• higher-latency connections
• multiple concurrent users
• simultaneous uploads and background metadata jobs
• temporary network or storage load spikes

A response taking more than 10 seconds does not necessarily mean that the SFTP storage is unavailable.

In these environments, a hardcoded/default 10-second timeout can turn temporary latency into failed file operations.

It may also result in misleading errors being propagated to clients, such as permission-related upload errors, even though the SFTP permissions are correct.

Suggested solution

Add an optional Timeout setting to the SFTP External Storage configuration.

For example:

Host: example.com
Port: 2222
Root: /data
Timeout: 60

The existing value of 10 seconds could remain the default, preserving the current behaviour for existing installations.

Conceptually, the storage implementation could use something similar to:

$timeout = isset($parameters['timeout'])
    ? (int)$parameters['timeout']
    : 10;

$this->client = new \phpseclib\Net\SFTP(
    $this->host,
    $this->port,
    $timeout
);

The SFTP backend definition could expose the value as an optional parameter alongside Host, Port and Root.

Expected behaviour

Administrators should be able to choose an appropriate SFTP timeout for each external storage mount without modifying Nextcloud source files.

For example:

• 10 seconds — current/default behaviour
• 30 seconds — remote server with moderate latency
• 60 seconds — NAS over the Internet
• higher values where required by the administrator

Benefits

This would:

• preserve the current default behaviour;
• avoid source-code modifications that are overwritten by Nextcloud updates;
• improve reliability for remote SFTP storage;
• make SFTP external storage more suitable for WAN/NAS environments;
• reduce intermittent failures caused by temporary latency;
• give administrators control over a parameter already supported by phpseclib.

In my case, simply increasing the phpseclib SFTP timeout from 10 to 60 seconds appears to have resolved almost all of the intermittent upload failures.

Start by locating the SFTP external storage implementation and its backend definition, then trace how mount parameters are passed into the phpseclib SFTP client. Add an optional per-mount timeout while preserving the 10-second default, and verify that the setting is exposed alongside Host, Port, and Root and works for new and existing mounts.