Skip to content

System Storage Usage Developer Guide

Ed Mozley edited this page Nov 18, 2026 · 1 revision

🛠️ System → Storage usage - Developer Guide

Added in 5.6.0 (#3003). For someone changing the page, or adding a new place FreeITSM keeps files.

System → Storage usage (system/storage-usage/) lists every folder FreeITSM keeps files in, with its path, how many files it holds, how much space they take and when the newest one landed. In Docker it also says whether each folder survives an update. Administrators only. Read only: nothing on it moves, creates or deletes anything.

It is deliberately not system/storage/. That address belongs to PR #361 - choosing where files are kept (server folder or S3) and moving them - and this page was built so that PR still merges cleanly. When it lands, the two should link to each other.

🚪 Adding a new place files are kept

You do not add it here. Add it to storagePersistenceDirectories() in includes/storage_persistence.php (with .gitignore, docker-compose.yml and tests/docker-storage-volumes.php, as that file says). This page starts from that list, so the folder appears here by itself.

Then give it a name: one line in STORAGE_TOP_KNOWN (includes/storage_inventory.php) and one string under system.storage_usage.what in each language. Until you do, the row still shows, labelled by its path.

A new subfolder of uploads/ goes in STORAGE_UPLOADS_KNOWN instead. One you forget is still listed - any folder found in uploads/ that is not known shows as itself, with the note FreeITSM does not know this folder.

📁 Files

File What it does
🟣 includes/storage_inventory.php storageInventory($conn) - the rows; storageFolderStats($path) - one folder's count
🟣 api/system/storage_stats.php One folder's figures, by row key. Administrators only
🟡 system/storage-usage/index.php The page: table drawn at once, figures fetched after
⚪ system/includes/areas.php The card (group health) and its storage_usage icon
⚪ system/help/storage-usage.php + _registry.php In-app help
⚪ lang/*/system.php storage_usage section, landing.storage_usage_*
🟢 tests/system-storage.php 30 checks

🧱 The list

foreach (storagePersistenceDirectories() as $d) {
    if ($d['rel'] === 'uploads') { /* one row per part of uploads/, plus unknown folders */ }
    elseif (!empty($d['critical'])) { /* the encryption key's folder */ }
    else $add(['what' => STORAGE_TOP_KNOWN[$rel] ?? null, 'name' => $rel, 'path' => $d['path']]);
}
  • uploads is split up, because it holds unrelated things: documents attached to records, Files, asset imports, report download links, archived API logs.
  • Files follows its own setting. The row's path is files_storage_root (Files → Settings → Storage) when one is set. When files_storage_driver is s3, the row says new files go to the bucket and that the bucket is not counted.
  • TRAP: the setting is read with filesSetting(), never filesStorageRoot(). That one calls uploadPrepareDir(), which creates the folder - not something a read-only page may do. The test checks that building the list creates nothing.
  • Each row has a key: the first 16 hex characters of the SHA-256 of its lower-cased path. It is stable between page load and count, and says nothing about the path.

🔢 Counting

The page draws every row at once, then asks storage_stats.php?key=... for each, three at a time, so one huge folder does not hold up the rest.

$it = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator($path, FilesystemIterator::SKIP_DOTS),
    RecursiveIteratorIterator::LEAVES_ONLY,
    RecursiveIteratorIterator::CATCH_GET_CHILD   // an unreadable subfolder is skipped, not fatal
);
  • The files FreeITSM drops in a folder to keep it private (.htaccess, web.config, index.html, index.php, .gitkeep, .gitignore) are not counted.
  • 8 seconds per folder, checked every 256 files. Past that it stops, returns complete: false, and the page shows at least on that row and on the total.
  • The endpoint calls session_write_close() before counting, so a slow folder does not lock the session for the analyst's other tabs.

🔒 Why the endpoint takes a key, not a path

storage_stats.php rebuilds the list and counts only a folder whose key matches (hash_equals). A path, or any key not on the list, is a 404. So even an administrator cannot use it to explore the server - it can only count what the page already shows. The test sends C:/Windows as the key to prove it.

🐳 Docker

Inside a container (storagePersistenceInContainer()), the table gains Survives an update, from storagePersistenceStatus($path) - the same answer the update warning uses (persisted / at_risk / missing / unknown). Everywhere else the column is not drawn.

📱 Phones

TRAP: mobile.css §34e makes every System table a white-space: nowrap sideways scroller, with a selector the page cannot outrank. This table carries a sentence (the notes), which by the same file's §11 makes it a card feed, so the page's own @media (max-width: 768px) block turns each row into a card - name, path, then Files: · Size: · Newest file: from data-label - and overrides §34e with !important. Desktop is untouched.

Not here (yet)

  • No Feature Bingo card. A read-only page leaves nothing to count, so there is no honest "done". Topology has none for the same reason.
  • Nothing in the database is counted - knowledge article pictures are embedded in the article - and nothing in S3. The page says so under the table.
  • Moving files: PR #361 and Storage series follow-ups.

Related: System · System page layout · Files storage - Developer Guide · Docker volumes - review

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally