diff --git a/admin_manual/configuration_files/images/files-windows-compatibility.png b/admin_manual/configuration_files/images/files-windows-compatibility.png new file mode 100644 index 000000000..5d2aa2144 Binary files /dev/null and b/admin_manual/configuration_files/images/files-windows-compatibility.png differ diff --git a/admin_manual/configuration_files/index.rst b/admin_manual/configuration_files/index.rst index f21f79392..375c888d5 100644 --- a/admin_manual/configuration_files/index.rst +++ b/admin_manual/configuration_files/index.rst @@ -21,3 +21,4 @@ File sharing and management file_versioning trashbin_configuration file_conversion + windows_compatible_filenames diff --git a/admin_manual/configuration_files/windows_compatible_filenames.rst b/admin_manual/configuration_files/windows_compatible_filenames.rst new file mode 100644 index 000000000..b43923feb --- /dev/null +++ b/admin_manual/configuration_files/windows_compatible_filenames.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 ` 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 ` command to automatically rename all invalid files. diff --git a/admin_manual/occ_command.rst b/admin_manual/occ_command.rst index 36d96e3aa..7805f6fd0 100644 --- a/admin_manual/occ_command.rst +++ b/admin_manual/occ_command.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 `:: + + Usage: + files:sanitize-filenames [options] [--] [...] + + 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 `:: + + Usage: + files:windows-compatible-filenames [options] + + Options: + --enable enable enforcing windows compatible filenames + --disable disable enforcing windows compatible filenames + .. _occ_sharing_label: Files Sharing diff --git a/go.php b/go.php index c8ac2f4fa..24f3667d1 100644 --- a/go.php +++ b/go.php @@ -52,6 +52,7 @@ $mapping = array( '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',