↑↓ to navigate ↵ to open Esc to close Search by Algolia

Maintenance

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.

Important

Some of these steps have to be done before installing the update. Follow the general steps of Updating FileRun as well.

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.
  • 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 servers where crash dumps are enabled, a program that FileRun runs (LibreOffice, FFmpeg, ImageMagick and the others) and that crashed left its crash dump file (core.<number>) in the installation folder, where the web server could send it to anyone who asked for its name. Such a file holds the memory of the program, which can include the database password. The programs now run inside the temporary folder. Delete the crash dump files that are already in the installation folder.
  • 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

  • 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.
  • The fullPath detail of Drive/files/browse, the absolute path of an item on the server, is answered to administrator accounts only.
  • 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 user and role endpoints accept and hand out the new permission names. changes is still accepted, and readonly and readOnly are still handed out, but move to the new names: an edit that sends only changes leaves the other new permissions of the account off.
  • 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.