====== openmediavault-filemanager plugin For OMV8 ======

\\
{{ :omvextras_logo4.jpg?400 |}}
\\
\\
===== Summary =====

The **openmediavault-filemanager** plugin is a native file manager for openmediavault 8. It is built entirely on the openmediavault workbench (the regular web interface), so there is no Docker container, no separate application and no iframe. Files are browsed, edited and managed in the same tables and dialogs as the rest of openmediavault.

Features:
  * Browse shared folders as a list (with a ''..'' row) or as a lazy-loading tree. The current location is shown in the breadcrumb.
  * Recursive search by name with wildcards.
  * Create folders and empty files, rename, copy and move (also between shared folders).
  * Change permissions and owner, optionally recursively.
  * Edit text files in the built-in code editor.
  * Upload files of any size, download single files, and download folders or several items as one ZIP archive.
  * Preview images, PDFs, audio, video and text files in a new browser tab.
  * Compress to ZIP or tar.gz and extract archives.
  * Properties (type, MIME type, owner, mode, ACLs, recursive size) and checksums (MD5, SHA-1, SHA-256, SHA-512).
  * Trash compatible with the Samba recycle bin, with restore.
  * Audit log of every change.
  * Optional access for non-administrative users based on the shared folder privileges.

\\
===== Support =====

Questions about the plugin should be posted in the [[https://forum.openmediavault.org/index.php?board/29-omv-extras/|omv-extras section of the openmediavault forum]].

Bugs and feature requests can be reported on the [[https://github.com/OpenMediaVault-Plugin-Developers/openmediavault-filemanager/issues|GitHub issue tracker]].

\\
===== Prerequisites =====

  * openmediavault 8 with omv-extras installed.
  * At least one **shared folder** (**Storage | Shared Folders**). The file manager only works inside shared folders; it can not browse the rest of the file system.

\\
===== Installation =====

  * Go to **System | Plugins**.
  * Search for **openmediavault-filemanager**, select it and click the **Install** button.
  * When the installation is finished, reload the web interface (F5 or Ctrl+Shift+R).

The plugin is now available under **Services | File Manager**.

\\
===== Settings =====

**Services | File Manager | Settings**

^ Setting ^ Default ^ Description ^
| Enabled | on | Turns the file manager on or off. |
| Read-only | off | Only allow browsing, previewing and downloading. All actions that change files are refused. |
| Shared folders | (none) | The shared folders available in the file manager. Select none to make **all** shared folders available. |
| Show hidden files | on | Show files and folders whose name starts with a dot. |
| Editor size limit | 2 | Maximum size in MiB (1 - 64) of files that can be opened in the editor. |
| Use trash | on | Move deleted items to the ''.recycle'' folder of the shared folder instead of deleting them permanently. |
| Audit log | on | Log every change (who, what, where) to the system journal. |
| Allow access (non-administrative users) | off | Let users that log in to the web interface browse the shared folders according to their shared folder privileges. See [[#non-administrative_users|Non-administrative users]]. |

Click **Save** after changing settings. No **Apply** is needed.

\\
===== Usage =====

==== Shared folders ====

**Services | File Manager | Shared folders** lists the shared folders available in the file manager, with their comment and your access (**Read/Write** or **Read-only**).

  * Click the name of a shared folder (or select it and click **Open**) to browse it as a list.
  * **Browse as tree** shows the shared folder as an expandable tree. Folders are loaded when they are expanded.
  * **Upload files** uploads files to the top level of the shared folder.
  * **Search** searches the whole shared folder.
  * **Trash** opens or empties the trash of the shared folder.
  * The link icon **Docs** opens this page.

==== Browsing ====

The list view shows the type, name, size, modification time and permissions of every item. The **Owner** and **Link target** columns are hidden by default and can be shown with the column chooser of the table.

  * Click a **folder** name to open it. The ''..'' row goes up one level; at the top level it leads back to the list of shared folders.
  * Click a **file** name to open it in a new browser tab. Files the browser can not show are downloaded instead.
  * The breadcrumb at the top shows the shared folder and the current location.
  * The search field of the table only filters the items of the current folder. Use the **Search** button for a recursive search.

Symbolic links are shown with their target. Links that point to a missing target are shown as **Broken link**.

==== Toolbar actions ====

Select one or more items and use the toolbar buttons. Buttons that do not apply to the selection are disabled.

^ Action ^ Description ^
| Open | Opens the selected folder. |
| Edit | Opens the selected text file in the editor. See [[#editing_files|Editing files]]. |
| Preview | Shows the selected image, PDF, audio, video or text file in a new browser tab. Other files are downloaded. |
| Download | Downloads a single file as is. A folder or several selected items are downloaded as one ZIP archive. |
| Create | **Upload files**, **New folder** or **New file** (empty) in the current folder. |
| Rename | Renames the selected item. |
| Copy or move | **Copy to ...** or **Move to ...** another folder, also in another shared folder. Existing items at the destination are skipped unless **Overwrite existing items** is checked. Leave **Folder** empty for the top level of the shared folder. |
| Archive | **Compress ...** the selected items to a ZIP or tar.gz archive, or **Extract** the selected archive. |
| Permissions | **Change permissions ...** (octal mode, e.g. ''0775'' or ''0664'') or **Change owner ...** (owner and group), optionally recursive. Administrators only. |
| Properties | Shows type, MIME type, size (recursive for folders), owner, mode and ACLs. |
| Checksum | Calculates the MD5, SHA-1, SHA-256 or SHA-512 checksum of one or more files. |
| Search | Searches the current folder and its subfolders. |
| Trash | **Restore** the selected items from the trash, **Open trash** or **Empty trash**. |
| Delete | Moves the selected items to the trash (or deletes them if the trash is disabled). Asks for confirmation. |
| Delete permanently | Deletes the selected items without using the trash. This can not be undone. |

Long running actions (copy, move, compress, extract, recursive permission/owner changes, checksums) run in a progress dialog that shows the output. Items that fail are listed at the end; the other items are still processed.

==== New files and folders ====

New files and folders (created, uploaded, copied, extracted) inherit the owner, group and mode of the folder they are created in instead of being owned by root. This keeps them accessible over SMB, NFS and other services the same way as the rest of the shared folder.

==== Editing files ====

Text files up to the **Editor size limit** can be edited in the code editor.

  * Binary files and files that are not UTF-8 encoded are refused.
  * Saving is atomic: the file is written to a temporary file and then replaces the original, keeping its owner, mode and ACLs.
  * If the file was changed by someone else after it was opened in the editor, saving is refused so that changes are not overwritten. Reopen the file and make the change again.

==== Uploading ====

**Upload files** opens an upload page in a new browser tab. Select or drop one or more files there.

  * Files are sent in chunks, so there is no size limit from the web server.
  * Partially uploaded files carry the suffix ''.fmpart'' until they are complete. Abandoned partial files are removed automatically after 24 hours.
  * Close the upload tab when done and reload the folder view to see the new files.

==== Previewing ====

Previews open in a new browser tab. The type is chosen by the file extension:

^ Kind ^ Extensions ^
| Image | png, jpg, jpeg, gif, webp, bmp, avif, ico |
| Video | mp4, m4v, webm, ogv, mov |
| Audio | mp3, ogg, oga, opus, wav, flac, m4a, aac |
| PDF | pdf |
| Text | txt, log, md, csv, json, yaml, xml, ini, conf, sh, py, ... |

Whether a video or audio file actually plays depends on the codecs the browser supports. All other files are downloaded.

==== Archives ====

**Compress** creates a ZIP or gzipped tar archive (''.tar.gz'') of the selected items in the current folder. All selected items must be in the same folder. Symbolic links are stored as links in tar archives.

**Extract** supports these formats:
  * ''.zip''
  * ''.tar''
  * ''.tar.gz'' / ''.tgz''
  * ''.tar.bz2'' / ''.tbz'' / ''.tbz2''
  * ''.tar.xz'' / ''.txz''
  * ''.tar.zst'' / ''.tzst''

The archive is always extracted into a **new folder** next to it, named after the archive. If that name is taken, a number is appended, e.g. ''photos (1)''. Existing files are never overwritten.

==== Search ====

The search finds files and folders whose name contains the search text, case-insensitive. The wildcards ''*'' (any characters) and ''?'' (one character) are supported, e.g. ''*.mkv'' or ''IMG_20??''. At most 1000 results are shown. Search from the list of shared folders to search a whole shared folder, or from a folder to search only that folder and its subfolders.

\\
===== Trash =====

When **Use trash** is enabled, deleted items are moved to ''.recycle/<user>/<original path>'' inside the shared folder. This is the same layout the Samba recycle bin uses (''.recycle/%U'' with keeptree), so items deleted with the file manager and items deleted over SMB with the recycle bin enabled end up in the same place.

  * **Open trash** shows the ''.recycle'' folder of the shared folder.
  * Select items in the trash and use **Trash | Restore** to move them back to their original location. Restoring fails if an item with the same name already exists there.
  * **Empty trash** permanently deletes all items in the trash of the shared folder after confirmation.
  * **Delete permanently** skips the trash.

The trash is not emptied automatically. Empty it regularly or delete old items from it, otherwise it keeps using space on the drive.

\\
===== Non-administrative users =====

When **Allow access** is enabled, users that are allowed to log in to the openmediavault web interface get a **File Manager** entry in their navigation.

  * Users only see the shared folders for which they have **Read-only** or **Read/Write** privileges in **Storage | Shared Folders | Permissions** (or via one of their groups). A user privilege takes precedence over group privileges; a group set to **No access** denies access.
  * Like with SMB, the file system permissions and ACLs apply as well. Commands run as the user, with their groups, not as root. A user can only open, change or delete what they could also access over SMB.
  * Uploading and all other changes require **Read/Write** privileges and the global **Read-only** setting must be off.
  * Changing permissions and owners is restricted to administrators.
  * The **Shared folders** setting also limits what users can see.

Note that a user must be able to log in to the web interface for this to work. See the openmediavault documentation on users and the web interface for details.

\\
===== Audit log =====

When **Audit log** is enabled, every change (create, upload, rename, copy, move, delete, restore, edit, permission and owner change, compress, extract, empty trash, settings change) as well as downloads and previews are written to the system journal with the user, the action and the affected path.

The log can be viewed under **Diagnostics | System Logs**, by selecting **File Manager** from the log type dropdown.

\\
===== Troubleshooting =====

  * **"The file manager is disabled."** - Enable it in **Services | File Manager | Settings**.
  * **"The file manager is not available for non-administrative users."** - Enable **Allow access** in the settings.
  * **"The shared folder is not available ..."** - The shared folder is not selected in the **Shared folders** setting.
  * **"Permission denied: ..."** - For non-administrative users, the file system permissions or ACLs do not allow the action. Check the permissions with **Properties**, or use the **openmediavault-resetperms** plugin to reset the permissions of the shared folder.
  * **"... is a binary file ..." / "... is not UTF-8 encoded ..."** - The editor only supports UTF-8 text files. Download the file and edit it locally.
  * **"The file is larger than ... MiB ..."** - Increase the **Editor size limit** or download the file.
  * **"... was changed by someone else ..."** - The file was modified after it was opened in the editor. Reopen it and make the change again.
  * **New items do not appear** - Reload the folder view after uploading in the other browser tab.
  * **A video preview does not play** - The browser does not support the codec of the file. Download it and play it locally.

\\
===== Uninstall =====

  * Go to **System | Plugins**, select **openmediavault-filemanager** and click the **Remove** button.

Removing the plugin does not touch any files in the shared folders. The ''.recycle'' folders stay in place and can be deleted manually or over SMB if they are not needed anymore.