Skip to content

refactor: Move external storage file name encoding to external storage chapter #13787

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
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

refactor: Move external storage file name encoding to external storage chapter #13787

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ed8ef90
docs(admin): Move external storage encoding to main ext st. ch.
joshtrichards Oct 10, 2025
3416597
chore: drop ext. sto. file enc. from troubleshooting chapter (moved)
joshtrichards Oct 10, 2025
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
120 changes: 76 additions & 44 deletions admin_manual/configuration_files/external_storage_configuration_gui.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,47 @@
==================================
Configuring External Storage (GUI)
==================================
================
External Storage
================

The External Storage Support application enables you to mount external storage
services and devices as secondary Nextcloud storage devices. You may also allow
users to mount their own external storage services.

For configuration of external storages via occ command, see :ref:`occ documentation <files_external_label>`.
Enabling
--------

Enabling External Storage Support
---------------------------------

The External storage support application is enabled on your Apps page.
External Storage Support is provided by a bundled (automatically installed) app. It is
disabled by default, so to use this feature you simply need to enable it under
**Apps**.

.. figure:: external_storage/images/enable-app.png
:alt: Enable external storage on your Apps page.

Storage configuration
---------------------
Configuring
-----------

To access the settings for configuring external storage mounts, click your Profile icon
in the top right and select **Settings** from the dropdown. On the left side, under
**Administration**, select **External Storage**.

To access the settings for configuring external storage mounts, click on your Profile icon
in the top right and select settings from the dropdown. On the left side under Administration
select External Storage.
.. note::
External storage can also be configured via the occ command. See :ref:`occ
documentation <files_external_label>`.

To create a new external storage mount, select an available backend from the
dropdown **Add storage**. Each backend has different required options, which
**Add storage** dropdown. Each backend has different required options, which
are configured in the configuration fields.

.. figure:: external_storage/images/add_storage.png

Each backend may also accept multiple authentication methods. These are selected
with the dropdown under **Authentication**. Different backends support different
authentication mechanisms; some specific to the backend, others are more
authentication mechanisms; some are specific to the backend, while others are more
generic. See :doc:`external_storage/auth_mechanisms` for more detailed
information.

When you select an authentication mechanism, the configuration fields change as
appropriate for the mechanism. The SFTP backend, for one example, supports
**username and password**, **Log-in credentials, save in session**, and **RSA
appropriate for the chosen mechanism. For example, the SFTP backend supports
**Username and password**, **Log-in credentials, save in session**, and **RSA
public key**.

.. figure:: external_storage/images/auth_mechanism.png
Expand All @@ -52,41 +56,40 @@ re-check your configuration and network availability.
If there is an error on the storage, it will be marked as unavailable for ten
minutes. To re-check it, click the colored icon or reload your Admin page.

Usage of variables for mount paths
Usage of Variables for Mount Paths
----------------------------------

The external storage mounting mechanism accepts variables in the mount path.

Use ``$user`` for automatic substitution with the logged in user's username.
Use ``$user`` for automatic substitution with the logged-in user's username.

Use ``$home`` for automatic substitution with a configurable home directory variable
(requires LDAP, see :ref:`LDAP_Special_Attributes` in the LDAP configuration documentation for details)
(requires LDAP; see :ref:`LDAP_Special_Attributes` in the LDAP configuration documentation for details).

In the following example, the mount point for a logged in user "alice" would substitute
In the following example, the mount point for a logged-in user "alice" would resolve
to ``/opt/userDirectories/alice/myPictures``.

.. figure:: external_storage/images/externalStorages_variables.png
:alt: External storage user variable substitution


User and group permissions
User and Group Permissions
--------------------------

A storage configured in a user's Personal settings is available only to the user
that created it. A storage configured in the Admin settings is available to
all users by default, and it can be restricted to specific users and groups in
A storage configured in a user's personal settings is available only to the user
who created it. A storage configured in the Admin settings is available to
all users by default, but it can be restricted to specific users and groups in
the **Available for** field.

.. figure:: external_storage/images/applicable.png
:alt: User and groups selector

.. _external_storage_mount_options_label:

Mount options
Mount Options
-------------

The Overflow menu (three dots) exposes the settings and trashcan. Click the trashcan to delete the
mountpoint. The settings button allows you to configure each storage mount
The overflow menu (three dots) exposes the settings and trashcan icons. Click the trashcan to delete the
mount point. The settings button allows you to configure each storage mount
individually with the following options:

* Encryption
Expand All @@ -99,23 +102,23 @@ individually with the following options:
The **Encryption** checkbox is visible only when the Encryption app is enabled. Note that server-side
encryption is not available for other Nextcloud servers used as external storage.

**Enable Sharing** allows the Nextcloud admin to enable or disable sharing on individual mountpoints.
When sharing is disabled the shares are retained internally, so that you can re-enable sharing
**Enable Sharing** allows the Nextcloud admin to enable or disable sharing on individual mount points.
When sharing is disabled, the shares are retained internally so that you can re-enable sharing
and the previous shares become available again. Sharing is disabled by default.

.. figure:: external_storage/images/mount_options.png
:alt: Additional mount options exposed on mouseover.

Using self-signed certificates
Using Self-Signed Certificates
------------------------------

When using self-signed certificates for external storage mounts the certificate
When using self-signed certificates for external storage mounts, the certificate
must be imported into the personal settings of the user. Please refer to
`Nextcloud HTTPS External Mount
<https://ownclouden.blogspot.de/2014/11/owncloud-https-external-mount.html>`_
for more information.

Available storage backends
Available Storage Backends
--------------------------

The following backends are provided by the external storages app.
Expand All @@ -133,9 +136,9 @@ The following backends are provided by the external storages app.
external_storage/webdav

.. note:: A non-blocking or correctly configured SELinux setup is needed
for these backends to work. Please refer to the :ref:`selinux-config-label`.
for these backends to work. Please refer to :ref:`selinux-config-label`.

Allow users to mount external Storage
Allow Users to Mount External Storage
-------------------------------------

Check **Enable User External Storage** to allow your users to mount their own
Expand All @@ -146,19 +149,48 @@ on your network!
.. figure:: external_storage/images/user_mounts.png
:alt: Checkboxes to allow users to mount external storage services.

Adding files to external storages
---------------------------------
Adding Files
------------

We recommend configuring the background job **Webcron** or
**Cron** (see :doc:`../configuration_server/background_jobs_configuration`)
to enable Nextcloud to automatically detect files added to your external
storages.

Nextcloud may not always be able to find out what has been
changed remotely (files changed without going through Nextcloud), especially
when it's very deep in the folder hierarchy of the external storage.
Nextcloud may not always be able to detect changes made remotely (files changed without going through Nextcloud), especially
when files are located deep in the folder hierarchy of the external storage.

You might need to setup a cron job that runs ``sudo -E -u www-data php occ files:scan --all``
(or replace ``--all`` with the user name, see also :doc:`../occ_command`)
to trigger a rescan of the user's files periodically (for example every 15 minutes), which includes
You might need to set up a cron job that runs ``sudo -E -u www-data php occ files:scan --all``
(or replace ``--all`` with the username; see also :doc:`../occ_command`)
to trigger a rescan of the user's files periodically (for example, every 15 minutes), which includes
the mounted external storage.

.. _trouble-file-encoding-ext-storages:

Troubleshooting File Name Encoding
----------------------------------

.. TODO: This should be reviewed by a knowledgeable party at a future date to determine if any changes are relevant with the HFS+ to APFS migration in macOS.

When using external storage, it can happen that some files with special characters will not
appear in the file listing, or they will appear but not be accessible.

When this happens, please run the :ref:`files scanner<occ_files_scan_label>`, for example::

sudo -E -u www-data php occ files:scan --all

If the scanner reports an encoding issue on the affected file, please enable Mac encoding
compatibility in the :ref:`mount options<external_storage_mount_options_label>`
and then :ref:`rescan the external storage<occ_files_scan_label>`.

.. note::
This mode comes with a performance impact because Nextcloud will always try both encodings when detecting files
on external storages.

Mac computers use the NFD Unicode normalization for file names, which is different from NFC, the one used
by other operating systems. Mac users might upload files directly to the external storage using NFD-normalized
file names. When uploading through Nextcloud, file names will always be normalized to the NFC standard for consistency.

It is recommended to let Nextcloud use external storages exclusively to avoid such issues.

See also the `technical explanation about NFC vs NFD normalizations <https://www.win.tue.nl/~aeb/linux/uc/nfc_vs_nfd.html>`_.
27 changes: 0 additions & 27 deletions admin_manual/issues/general_troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,33 +341,6 @@ Users' Federated Cloud IDs not updated after a domain name change
| ``occ dav:sync-system-addressbook``
| ``occ federation:sync-addressbooks``

.. _trouble-file-encoding-ext-storages:

Troubleshooting file encoding on external storages
--------------------------------------------------

When using external storage, it can happen that some files with special characters will not
appear in the file listing, or they will appear and not be accessible.

When this happens, please run the :ref:`files scanner<occ_files_scan_label>`, for example with::

sudo -E -u www-data php occ files:scan --all

If the scanner tells about an encoding issue on the affected file, please enable Mac encoding compatibility in the :ref:`mount options<external_storage_mount_options_label>`
and then :ref:`rescan the external storage<occ_files_scan_label>`.

.. note::
This mode comes with a performance impact because Nextcloud will always try both encodings when detecting files
on external storages.

Mac computers are using the NFD Unicode Normalization for file names which is different than NFC, the one used
by other operating systems. Mac users might upload files directly to the external storage using NFD normalized
file names. When uploading through Nextcloud, file names will always be normalized to the NFC standard for consistency.

It is recommended to let Nextcloud use external storages exclusively to avoid such issues.

See also `technical explanation about NFC vs NFD normalizations <https://www.win.tue.nl/~aeb/linux/uc/nfc_vs_nfd.html>`_.

Troubleshooting contacts & calendar
-----------------------------------

Expand Down