You are reading the documentation of FileRun 2026.4.0, which is not released yet. It is subject to change, so do not use it for planning. Go to the documentation of FileRun 2026.3.0

Updating to FileRun 2026.4🔗

What to do before and after updating an installation to FileRun 2026.4.0: the steps the update cannot do by itself, and the changes that affect a customized configuration, customized files and API clients.

Before updating🔗

• Make a full backup of the installation.
• The user details mapping of the OpenID Connect and OAuth2 authentication. The JSONPath selectors of the mapping are now read by the rules of the JSONPath standard (RFC 9535). The usual forms give the same value as before, such as $.email, $.name.given_name, $['custom:claim'], $.emails[0].value and $.groups[*]. A selector written in one of the forms below has to be changed. The corrected forms work in the earlier versions too, so change them before updating.
  • A name in brackets needs quotes: $[email] has to be $['email'].
  • A quoted name after a dot is refused: $.'custom:claim' has to be $['custom:claim'].
  • A position after a dot finds nothing: $.emails.0.value has to be $.emails[0].value.
  • A filter that compares with =, ===, !==, =~, in or nin is refused. A filter compares with ==, !=, <, <=, > and >=. The new functions match() and search() check a regular expression. The earlier versions do not know them, so a filter that uses them works only after the update.
  • .length and calculated positions such as [(@.length-1)] are no longer available. The last element is [-1].
  • A negative position that reaches before the start of a list, such as [-5] on a list of two, finds nothing. It found the first element.

After updating🔗

Thumbnails and previews🔗

FileRun no longer keeps the thumbnails and the document previews next to the files, in hidden .filerun.thumbnails and .filerun.cache folders. It keeps them in the installation folder, in system/data/temp/file_variants/Drive. The folders of the users hold only their files: a backup or a synchronization tool no longer copies the cache, and opening a folder no longer writes into it.

The old folders stay where they are after the update, hidden. FileRun no longer reads them, so each thumbnail is made again the first time it is viewed. A command line tool moves what is still valid of the old folders to the new location, and removes the rest:

1. From the root of the installation, run the tool with --dry-run. It prints every file it would move and remove, and changes nothing.

    1php cli.php 'Drive/!cli/variants/migrate_legacy' --dry-run
   

2. Run it again without --dry-run.

    1php cli.php 'Drive/!cli/variants/migrate_legacy'
   

3. At the end, it prints how many folders it read, how many thumbnails and previews it moved, how many files it removed, and how much space it moved and freed.

What the tool does:

• Without options, it processes the home folder of every account, the trash folder set by $config['path']['trash'], and the folders set by $config['path']['thumbnail_cache'] and $config['path']['preview_cache'], if any. For a folder outside the home folders, run it with --path=/full/disk/path. The other options are on Command line tools.
• It moves the thumbnails and the previews of the files that have not changed since they were made. It removes the cache of the files that no longer exist, of the files that changed, and of the earlier versions of files. When a thumbnail was already made again after the update, it keeps the new one.
• On a large installation it can run for a long time. A run that stops can be started again: it continues with what is left. It can also be run one account at a time with --username, or one folder at a time with --path.

Remarks:

• The cache now takes room on the disk of the installation folder. On a large photo library it can take many gigabytes. To keep it on another disk, set $config['Drive']['path']['file_variants'] in customizables/config.php before running the tool. See Advanced configuration.
• $config['path']['thumbnail_cache'] and $config['path']['preview_cache'] are no longer read. If you set one of them, remove it from customizables/config.php after the tool has run.
• With several web servers behind a load balancer, each server keeps its own thumbnails, unless $config['Drive']['path']['file_variants'] points to storage that they share.
• After restoring the database from a backup, delete the folder system/data/temp/file_variants, or the folder that the option names. The thumbnails are found through the database records of the files, and a restored database can give the record of one file to another file, which would then show the wrong thumbnail.

Configuration🔗

• The names of the activity log actions. An action is now named together with its application, such as Core.login or Drive.upload. The update renames the entries of the activity log, of its archive and of the e-mail notification rules. Where customizables/config.php names actions, change the names by hand. The names are listed on Activity log actions. The option that names actions this way is $config['system']['custom_event_scripts'].

• The options of the e-mail notifications about files moved. Move them in customizables/config.php, because an option left at the old place is ignored:

  • $config['app']['email_notification']['basic_actions'] becomes $config['Drive']['email_notification']['basic_actions'].
  • $config['app']['email_notification']['folder_based']['limit_actions'] becomes $config['Drive']['email_notification']['folder_based']['limit_actions'].

  Their values stay the same: the names of the actions without the application, such as receive_upload.

• Your own list of notified actions. If $config['Drive']['email_notification']['basic_actions'] is set, replace receive_copy and receive_move there with receive_file_copy_created: the two old names are never recorded, so a copy into a user's folder was never notified. The default list now also notifies about a file uploaded over an existing file or saved from an editor (receive_file_updated). Add it to your list if you want the same.

• $config['system']['http']['options']. The library that makes the outgoing HTTP requests (Guzzle) is at version 8. It checks the types of these options, and refuses cURL options that replace its own settings, such as the certificate check, the proxy or the timeout. HTTPS connections need TLS 1.2 or newer, a connection attempt waits at most 60 seconds, and only the redirects with the status 301, 302, 303, 307 or 308 are followed.

• E-mail sent through PHP's mail() function (no SMTP server set in the control panel). The e-mail library (PHPMailer) is at version 7. When the PHP setting sendmail_path already names an envelope sender with -f, that sender is now used.

Customized files🔗

• Translations. If you keep translation files under customizables/translations, the files inside a Core or a Drive folder of a language are no longer read. Move them one level up: for example, customizables/translations/german/Core/Basic.php becomes customizables/translations/german/Basic.php. One file gets a new name instead: Drive/Notifications.php becomes Notifications/Triggers.php. See Translating FileRun.
• Event scripts. The event scripts in customizables/events are named after the new action names: Core.login.php, Drive.upload.php and so on. Rename them. The catch-all event script receives the new name in $action.
• E-mail templates. Copies of the e-mail templates under customizables/emails are no longer read, whatever their language: the messages go out with the built-in templates. The messages are now translated, and written in the language of each user account, so a copy kept only to translate a message is no longer needed. To change the text of a message, override its translation under customizables/translations, in the section of the message: for example, customizables/translations/english/Email/Signup.php for the e-mail with the sign-in details. See E-mail notification system.

Permissions🔗

• The permission "User can make changes to files and folders" is split into eight separate permissions. The update gives all eight to every account and role that had the one, so nothing changes until an administrator edits them. Review the accounts and the roles that should have less.
• The Guest role can now be allowed to edit files, use collections and star files. These options are off after the update, so guests behave as before until an administrator enables them.
• Some permissions mean nothing without another one, such as sharing without downloading. They are now switched off when an account or a role is saved, and the update switches them off once in the stored accounts and roles. What the users can do stays the same, but the forms of the control panel and the API now show these permissions as off.
• Simple administrators can be allowed to administer the shared drives. The permission is off after the update. The superuser and the independent administrators can always administer them.
• In the control panel, the lists for picking users and groups (the members of a group, the notification rules, the user and role forms) are no longer limited by the Can interact with permission of the administrator who is signed in. An independent administrator still sees only the accounts it created.

Guest sign-in links🔗

The link that signs a guest in, sent in the share messages and shown when editing a guest account, has a new address. The links in the messages sent before the update no longer work. Send such a guest a new share message, or let them sign in with their username and password.

Files to remove by hand🔗

• On Linux installations whose trash folder is on another file system than the user files, an earlier version could leave files in the trash folder that have no record and are not shown in the trash. Remove them from the trash folder by hand.

API clients🔗

Every endpoint added and changed is listed on API changes in 2026.4.

• A write that the quota refuses is answered with the status 507 Insufficient Storage instead of 403, on every endpoint. The message in the answer is the same.
• The errors of the OAuth2 token endpoint no longer have the message field. Read error_description instead.
• A refresh token that is expired, revoked or issued to another application is answered with the invalid_grant error and the status 400, where it was invalid_request and 401. An expired or revoked authorization code is answered with invalid_grant too. A password grant with an empty username is refused with invalid_request.
• Core/!admin/users/info returns last_web_ui_access instead of last_access_date, with the same value. It also returns last_seen, the time of the last activity of any kind.
• The home folder path template of a role is named drive_homefolder_template by Core/!admin/roles/info, Core/!admin/roles/add and Core/!admin/roles/edit. The old name, homefolder, still works, and will be removed in a future version.
• In the answer of Core/!admin/users/edit_groups, add_to_group lists only the groups joined by the request, and the new remove_from_group lists the groups left.
• Core/users/search is for administrators only, and needs the admin scope. Any other account finds the people it can share with through the new endpoint Drive/users/search, which needs the share scope. It takes the same search parameter and answers in the same form. It lists only the accounts that the "Can interact with" permission of the account allows, and an account created by an independent administrator finds only the accounts of that administrator, whatever the permission names.
• The new endpoint Drive/files/copy copies a file or a folder. A name already taken at the destination is refused, unless overwrite is set. See Copying files or folders.
• Drive/files/move takes the overwrite parameter. Set to 1, a move onto an existing file replaces it, and a move onto an existing folder merges the two folders. A move refused because the name is taken carries conflicts, the item in the way. See Moving files or folders.
• Drive/files/extract and Drive/files/zip no longer require the permission to make changes. Being allowed to download the source and to upload into the target folder is enough to write new files. Extracting over a file that already exists requires that the account is allowed to delete that file and to upload into its folder, so an account with the editor share role on a folder, without the permission to delete, can no longer extract over existing files. Adding to an existing zip archive requires the permission to edit files.
• The user and role endpoints take and hand out the eight permissions that replace changes: edit_files, rename_move, delete_files, delete_folders, delete_permanently, collections, starring and write_metadata. Each file endpoint asks for the permission of its action: rename_move to rename and move, delete_files and delete_folders to delete and delete_files to open the trash and restore from it, delete_permanently to delete for good and to empty the trash, starring to star, and write_metadata to change tags and other metadata. See Add FileRun user accounts.
• changes is still accepted. It sets rename_move, delete_files, delete_folders and delete_permanently, except the ones the request sends itself. The user endpoints store a permission left out as off, so an account edited with only changes loses edit_files, collections, starring and write_metadata. Core/!admin/roles/info still hands out changes and readonly, and Core/account/info still hands out readOnly, worked out from rename_move, delete_files and delete_folders. Core/!admin/users/info no longer hands out readonly.
• Drive/files/lock and Drive/files/unlock require one of the permissions to edit files, to rename and move them, or to delete them. See Locking files.
• Drive/files/trash/empty takes an optional path, the trash of a shared drive to empty. See Managing the trash.
• The new endpoints under Drive/!admin/shared_drives create and manage the shared drives and their members, and the new permission admin_shared_drives lets a simple administrator use them. See Managing shared drives.
• The PHP API client library (apps/Drive/!classes/vendor/FileRun/API/Client) is no longer part of the installation package.

Settings that moved🔗

• The settings of the programs that make thumbnails and previews (Vips, ImageMagick, FFmpeg and LibreOffice) moved from Files → Settings → Thumbs and previews to Files → Settings → Advanced. The file types that each program is used with stay on Thumbs and previews.
• Files → Settings → Features has two new options under Access: WebDAV and Mobile and desktop apps. Both are on after the update.