Merge pull request #13098 from nextcloud/feat/document-wcf

feat(admin): document Windows compatible filenames

Author: susnux

admin_manual/configuration_files/images/files-windows-compatibility.png

@@ -21,3 +21,4 @@ File sharing and management
     file_versioning
     trashbin_configuration
     file_conversion
+    windows_compatible_filenames

admin_manual/configuration_files/index.rst

@@ -0,0 +1,75 @@
+.. _windows_compatible_filenames:
+
+============================
+Windows compatible filenames
+============================
+
+.. note::
+
+    This feature was introduced in Nextcloud 31.
+
+By default Nextcloud supports all filenames which are valid on the underlying server.
+As Nextcloud runs only on POSIX compatible operating systems (Linux),
+this means that Nextcloud supports also filenames not valid on Microsoft Windows systems.
+
+If your users use Windows and use the Nextcloud Desktop clients to synchronize their work
+to their computer they might encounter files created in the web interface, or on a Linux
+machine, which cannot be synchronized as the filename is not valid.
+
+To solve this issue it is possible to enforce filenames only valid on Windows,
+this for example forbids characters like ``*`` from filenames
+or filenames like ``AUX.txt`` (on Windows ``AUX`` is a reserved name and cannot be used).
+
+.. note::
+
+	Enabling this setting will not enforce case-insensitivity
+	as modern Windows systems support case-sensitive filenames.
+
+Enabling Windows compatible filenames
+-------------------------------------
+
+This feature can be enabled either by using the web interface
+or by using an ``occ`` command.
+
+.. note::
+
+	This feature works by setting a predefined set of system configuration settings.
+	So after enabling this the ``config.php`` will be adjusted, which also means enabling
+	this feature requires a writable configuration.
+
+Using the web interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The setting is provided in the **Administration settings** under **Basic settings**.
+Within the **Files compatibility** section the Windows compatibility can be enabled.
+
+.. figure:: images/files-windows-compatibility.png
+   :alt: Enforce windows compatibility checkbox on the Administration - Basic settings - Files compatibility page.
+
+Using the occ command
+^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    This command was introduced in Nextcloud 32.
+
+To quickly enable or disable the feature an :ref:`occ command <occ_files_windows_filenames>` is provided.
+
+Consequences
+------------
+
+After enabling Windows compatible filenames users cannot create or modify files
+with invalid filenames. But they can still delete or rename those files (to valid names).
+
+This works by setting a pre-defined set of configuration settings:
+
+- ``forbidden_filename_basenames`` will be set to names reserved on Windows.
+- ``forbidden_filename_characters`` will be set to characters not valid for filenames on Windows.
+- ``forbidden_filename_extensions`` will be set to strings not allowed as trailing parts, like a trailing dot or spaces.
+
+Sanitizing invalid filenames
+----------------------------
+
+After enabling the feature the users have to manually adjust all invalid filenames
+to be able to keep working with them.
+As an alternative Nextcloud provides the :ref:`occ files:sanitize-filenames <occ_files_sanitize_filenames>` command to automatically rename all invalid files.

admin_manual/configuration_files/windows_compatible_filenames.rst

@@ -974,6 +974,36 @@ This command attempts to repair such entries by querying for entries where the p
 doesn't match the expected path based on it's parent path and filename and resets it's
 path to the expected one.
 
+.. _occ_files_sanitize_filenames:
+
+Sanitize filenames
+^^^^^^^^^^^^^^^^^^
+
+This command allows to automatically rename files not matching the current file naming constraints,
+for example after enabling the :ref:`Windows compatible filenames <windows_compatible_filenames>`::
+
+ Usage:
+   files:sanitize-filenames [options] [--] [<user_id>...]
+
+ Arguments:
+   user_id                                 Limit filename sanitizing to files given user(s) have access to
+
+ Options:
+      --dry-run                            Do not actually rename any files but just check filenames.
+  -c, --char-replacement=CHAR-REPLACEMENT  Replacement for invalid character (by default space, underscore or dash is used)
+
+When running this command without parameters it will scan all files of all users
+for filenames not comply with the current filename constraints and try to automatically
+rename those files.
+Invalid characters will be replaced by default with either a space, underscore, or dash
+depending on which characters are allowed.
+If your constraints forbid all of them, then you have to provide an character replacement
+yourself by specifying the ``--char-replacement`` option.
+
+The ``--dry-run`` option allows to perform the sanitizing without the actual renaming,
+this is useful for estimating the execution time and to get an overview on what renaming
+actions will be performed.
+
 Transfer
 ^^^^^^^^
 
@@ -1028,6 +1058,21 @@ See `user documentation <https://docs.nextcloud.com/server/latest/user_manual/en
 
 .. TODO ON RELEASE: Update version number above on release
 
+.. _occ_files_windows_filenames:
+
+Toggle Windows compatibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command ``occ files:windows-compatible-filenames`` can be used to toggle
+enforcing :ref:`Windows compatible filenames <windows_compatible_filenames>`::
+
+ Usage:
+   files:windows-compatible-filenames [options]
+
+ Options:
+       --enable                  enable enforcing windows compatible filenames
+       --disable                 disable enforcing windows compatible filenames
+
 .. _occ_sharing_label:
 
 Files Sharing

admin_manual/occ_command.rst

@@ -52,6 +52,7 @@
     'admin-trusted-domains'   => '/admin_manual/installation/installation_wizard.html#trusted-domains',
     'admin-update'            => '/admin_manual/maintenance/update.html',
     'admin-warnings'          => '/admin_manual/configuration_server/security_setup_warnings.html',
+    'admin-windows-compatible-filenames' => '/admin_manual/configuration_files/windows_compatible_filenames.html',
     'admin-workflowengine'    => '/admin_manual/file_workflows/index.html',
 
     'developer-manual'        => '/developer_manual',