VMware ESXi and vSphere Cluster Management

Apache magic File: MIME Type Detection by File Content

Learn how Apache's magic file and mod_mime_magic detect MIME types from file signatures, how to configure and test them, and how to edit them safely.

What the Apache magic file does

Apache's magic file is a text-based database of file signatures. Its rules help Apache infer a file's MIME type from bytes in the file instead of relying only on the filename extension.

A MIME type is a standardized media type label such as image/png, video/mpeg, or application/zip. Apache sends the selected type in the HTTP Content-Type response header. Browsers and other HTTP clients use that header to decide whether to display, play, parse, or download the resource.

Magic rules can identify many kinds of content, including MPEG video, images, archives, executables, documents, and other binary formats. Identification commonly depends on a recognizable sequence of bytes in the file header.

How mod_mime_magic fits into Apache

The mod_mime_magic module performs content-based detection. The relationship is:

• The magic file contains byte-pattern rules and the MIME types associated with those rules.
• mod_mime_magic reads the rules and tests files against them.
• MimeMagicFile tells Apache which magic data file to use.

The feature works only when the module is loaded and Apache has a valid MimeMagicFile path. Installing or editing a file alone does not activate content inspection.

Location and configuration

On Debian and Ubuntu installations, the common path is:

/etc/apache2/magic

Other installations may store the file under the Apache server configuration directory or use a system magic-data location. Do not assume that the Debian path applies everywhere. The active path is controlled by the MimeMagicFile directive.

<IfModule mime_magic_module>
    MimeMagicFile "/etc/apache2/magic"
</IfModule>

The directive belongs in an appropriate Apache server or virtual-host configuration context for the deployment. The path in the directive, not the filename you expect, determines which data Apache reads.

Useful Debian and Ubuntu checks

apachectl -M | grep mime_magic
grep -R "^[[:space:]]*MimeMagicFile" /etc/apache2

The first command checks whether the module appears to be loaded. The second searches for configured magic-file paths. Adjust the configuration directory on other operating systems.

If the module is supplied but not enabled on Debian or Ubuntu, the package may provide:

sudo a2enmod mime_magic

Use a2enmod only on systems that provide that helper. Module names, package layouts, and service-management commands vary by distribution.

Apache MIME type detection methods

Apache can obtain a response type from several sources. The method that applies depends on whether the request is for a static file, whether explicit rules exist, and whether an application generates the response.

Filename extensions and content signatures can disagree. Explicit Apache rules, application-generated headers, and other configuration such as AddType, ForceType, or file-matching rules can affect the final Content-Type. Investigate the complete request path rather than assuming that changing the magic file will change every response.

Magic file structure and matching concepts

A magic entry conceptually contains these parts:

1. A byte offset: the position at which Apache begins checking.
2. An expected byte sequence or another test applied at that position.
3. The result MIME type, such as video/mpeg.
4. Optional descriptive text for human readers or diagnostic output.

Many formats put identifying bytes near the beginning of the file, so rules often check the file header. The offset is important: a correct byte sequence at the wrong position does not identify the intended format.

Magic data can also contain comments and blank lines. Escaped values may be needed when a character has special meaning in the file syntax. Some rule sets support continuation tests: a later test is evaluated in relation to an earlier match to make identification increasingly specific. The exact syntax is format-sensitive, so preserve the existing syntax and formatting when making a local change.

# Conceptual layout only; consult the installed file's syntax
<offset>  <byte test>  <MIME type>  <optional description>

This is a layout illustration, not a complete production rule. Do not paste a made-up rule into a live file without checking the syntax used by the installed magic database and testing it with a controlled sample.

Safe administration workflow

1. Locate the active file. Search the Apache configuration for MimeMagicFile. If no directive is visible, determine how the installed module obtains its default data path.
2. Confirm module availability. Inspect loaded modules and the package's module configuration.
3. Back up the current file. Keep a rollback copy before changing a packaged file.
4. Document the reason. Record the format, signature source, offset, expected MIME type, and affected virtual hosts.
5. Edit with appropriate privileges. Use an approved editor and retain the existing comments and organization.
6. Validate before applying. Run Apache's configuration test. A malformed magic rule or related directive may prevent a reload.
7. Reload only after validation succeeds. Then test an actual HTTP response.

sudo cp /etc/apache2/magic /etc/apache2/magic.bak
sudo editor /etc/apache2/magic
sudo apachectl configtest
sudo systemctl reload apache2

On some systems the service is named httpd rather than apache2. A successful configuration test is necessary but does not prove that a rule matches the intended bytes.

Distribution package upgrades may replace or update packaged magic data. Keep local rules documented, maintain them through the site's configuration-management process when possible, and compare the file after upgrades.

Testing MIME detection

Test at the HTTP boundary because the response header is what the client receives. Use a known static file and inspect its headers:

curl -I https://example.test/path/to/file

Look for a line such as:

Content-Type: image/png

Compare Apache's result with local identification tooling when available:

file --mime-type /path/to/file

The local file utility and Apache's magic rules may use different databases, versions, or matching behavior. Treat the comparison as a diagnostic clue, not as a definitive expectation.

Three useful test cases

1. Correctly named file: Serve a genuine PNG named with .png. Confirm that the response has the intended image type and determine whether the result comes from extension mapping, content matching, or an explicit rule.
2. Misleading extension: Use a genuine PNG whose name has a generic or incorrect extension. Compare the HTTP result with the opening bytes and local identification. This demonstrates that extension and content-based classification can differ.
3. New custom signature: Create a controlled sample of an internal binary format, add a documented rule only after confirming a stable and sufficiently distinctive byte sequence, validate Apache, reload it, and request the sample with curl -I.

Adding a rule for an internal binary format

Before adding a custom rule, obtain a stable identifying sequence from the format specification or from several known-good files. Confirm its byte offset, length, and whether variable fields can occur in the tested region. Avoid a short or common sequence that could match unrelated files.

1. Collect multiple valid samples and inspect their initial bytes with a hex viewer or controlled byte dump.
2. Choose a distinctive signature and the correct offset.
3. Check for collisions with existing rules and decide whether a continuation test is needed for specificity.
4. Add one documented local rule while preserving valid syntax and nearby formatting.
5. Run sudo apachectl configtest.
6. Reload Apache only after the test succeeds.
7. Request the sample over HTTP and verify the Content-Type header.
8. Test a nonmatching file to ensure the rule is not overly broad.

If the internal format is uploaded by users, classification should be paired with upload controls, storage isolation, access controls, and safe download handling. A matching signature is not an authorization or malware decision.

Troubleshooting

An unexpected Content-Type is returned

• Inspect the actual response with curl -I.
• Check whether the filename extension is mapped by mod_mime.
• Confirm that mod_mime_magic is loaded.
• Locate every MimeMagicFile directive and verify that you edited the active file.
• Search server and virtual-host configuration for AddType, ForceType, file-matching rules, or other explicit type settings.
• Determine whether an application generated the response header.
• Compare the file's initial bytes with the expected offset and local MIME detection result.

Apache fails to reload

• Run sudo apachectl configtest and read the reported file and line.
• Review the Apache error log for path, permission, or parsing details.
• Check that the configured magic file exists and is readable by the Apache process.
• Restore the backup if necessary, then reintroduce changes incrementally.

A custom rule does not match

• The signature may be incorrect, too short, non-unique, or located at another offset.
• An earlier or more specific rule may match first.
• The request may be handled by an application rather than served as a static file.
• Apache may not have been reloaded after the edit.

Inspect the bytes with a hex viewer or controlled dump, test a minimal sample with the known header, confirm that the URL maps to the intended static file, validate and reload, and repeat the HTTP header test.

Operational and security considerations

Use the magic file only when extension mappings or application-level headers do not meet the requirement. Content inspection is an HTTP content-classification aid, not proof that an upload or served object is safe.

For untrusted uploads, prefer explicit handling: store them outside executable web paths where practical, set an intentional Content-Type, and use Content-Disposition when the desired behavior is download rather than inline rendering. Apply access controls and content validation separately from MIME detection.

Browsers may perform content sniffing, meaning they infer a type from data instead of fully trusting the declared header. Where appropriate, send:

X-Content-Type-Options: nosniff

This helps clients avoid certain unsafe type interpretations, but it does not replace correct server configuration, safe upload processing, or malware scanning.

Administration reference

Key points

• /etc/apache2/magic is common on Debian and Ubuntu, but MimeMagicFile determines the active path.
• mod_mime_magic reads signature rules; the magic file itself does not perform matching.
• mod_mime normally maps extensions, while magic matching examines file content.
• Explicit configuration and application-generated headers can change the final response type.
• Back up, document, validate, reload, and test every local change.
• Never treat a MIME match as a security validation mechanism.

For related configuration, see the Apache magic file reference.