Moodle File Subsystem Architecture: Requirements, Design, and Operational Safeguards

Problem & Takeaway

Moodle must accept user uploads, enforce limits, keep files safe, and let plugins plug into storage without touching core code. The core file API and a thin file_storage abstraction give a minimal, secure, and extensible design. Understanding the trust boundaries and operational checks lets you audit, troubleshoot, and evolve the system.

1. Requirements

• Secure storage of untrusted uploads.
• Enforce per‑context size limits and site‑wide maximum.
• Serve files via a URL that respects capabilities.
• Support versioning and plugin‑driven backends (e.g., AWS S3).
• Maintain compatibility with existing plugins that rely on the file API.

2. Minimal Suitable Design

Moodle’s file system is built around a single public entry point: pluginfile.php (or file.php in older releases). All uploads go through lib/filelib.php, which creates a file_record and hands it to the file_storage class. The storage class resolves the physical path, checks permissions, and streams the file. Key points:

• Thin controller: pluginfile.php validates the request, loads the record, and delegates to file_storage::get_file().
• Abstraction layer: file_storage implements get_file(), save_file(), and delete_file(). Backends are pluggable via file_storage_{backend} classes.
• Path resolution: The file is stored in $CFG->dataroot/filedir with a hashed path that hides the original filename.
• Versioning: When a file is re‑uploaded, a new file_record is created; the old record is marked isobsolete, preserving history for rollbacks or audit.

3. Trust & Data Boundaries

Uploaded files are untrusted input. Trust boundaries are enforced at two stages:

1. Upload validation: file_upload() checks MIME type, runs virus‑scan hooks, and applies size limits. Only after passing these checks does the file reach file_storage::save_file().
2. Serving protection: pluginfile.php performs a capability check against the file’s context. If the user lacks moodle/file:download, the request is denied even if the file exists on disk.

Files are stored outside the web root or are served through pluginfile.php, preventing direct URL access and execution. Any plugin that writes to the filesystem bypassing the API breaks this boundary and must be audited.

4. Operational Checks

Routine health checks keep the file subsystem in sync:

• Quota & cleanup: php admin/cli/check_file_usage.php compares the files table to physical files, reporting orphaned records.
• Cron job: cron.php runs file_storage::clean_orphaned_files() to delete stale data.
• Health logs: Enable debugging and watch for MISSING_FILE or STORAGE_BACKEND_UNAVAILABLE warnings.

# Check file usage
php admin/cli/check_file_usage.php --dataroot=/var/moodledata

Expected output: counts of database records vs. physical files; any discrepancy triggers an alert.

5. Failure Modes & Design‑Change Conditions

• Backend outage: If the storage backend (e.g., S3) is unreachable, file_storage returns a 503 error; the request is logged with STORAGE_BACKEND_UNAVAILABLE.
• Permission drift: If the web server grants read access to $CFG->dataroot/filedir, a user could download files directly, bypassing capability checks. This forces a redesign to enforce script‑only serving.
• Plugin mis‑behaviour: A third‑party plugin writing files outside the API will bypass validation; if discovered, the plugin must be refactored to use file_storage::save_file().
• Version upgrade: Moving from Moodle 3.8 to 3.9 introduces the external storage plugin interface; failing to migrate plugins can break file access.

6. Practical Example: Enabling AWS S3 Storage

Assume you want to offload user uploads to S3 while keeping the API unchanged.

1. Install the local_s3 plugin (or any S3 storage plugin). The plugin registers a new backend class file_storage_s3.
2. Edit $CFG->filebase in config.php to point to the S3 bucket:

   $CFG->filebase = 's3://my-moodle-bucket';
   

3. Configure AWS credentials in config.php or via environment variables.
4. Run php admin/cli/upgrade.php to apply any schema changes.
5. Verify that new uploads are stored in S3 by checking the bucket’s object list.

Operational check: run php admin/cli/check_file_usage.php after uploading a file. The command should report no orphaned files, confirming that the backend is correctly reporting file sizes and paths.

7. Checklist for Auditing the File Subsystem

Check	Tool/Command	Expected Result
Validate MIME and size limits	Upload via UI and inspect debug logs for INVALID_FILE_TYPE or FILE_TOO_BIG	No upload passes if limits are exceeded
Capability enforcement	Attempt to download a file as a role without moodle/file:download	403 Forbidden response
Storage backend health	Simulate S3 outage (disable network)	503 Service Unavailable and error log entry
Orphaned file detection	php admin/cli/check_file_usage.php	Zero mismatches reported

Conclusion

By keeping the file API as a thin, well‑defined interface and delegating storage to pluggable backends, Moodle achieves security, flexibility, and maintainability. Regular operational checks and clear trust boundaries protect against accidental exposure or data loss. When extending storage or upgrading Moodle, review the design change conditions to avoid breaking the file subsystem’s integrity.