Apache mods-available Directory: Module Configuration and Enablement
Learn how Debian and Ubuntu organize Apache modules in mods-available and mods-enabled, and how to safely enable, disable, test, and verify modules.
What Is /etc/apache2/mods-available?
An Apache module is an extension that adds server capabilities or request-processing behavior. Examples include URL rewriting, SSL/TLS, proxying, authentication, compression, headers, and logging.
On Debian-family systems such as Debian and Ubuntu, Apache separates module definitions that are available from module definitions that are active:
| Path | Purpose | Typical contents | Whether Apache uses it as active configuration |
|---|---|---|---|
/etc/apache2/mods-available | Stores module definitions supplied by packages or created by administrators. | module.load files and optional module.conf files. | Not by itself. A definition normally becomes active through a link in mods-enabled. |
/etc/apache2/mods-enabled | Contains the module definitions currently selected for Apache. | Symbolic links pointing to files in mods-available. | Yes, when Apache's Debian configuration includes this directory. |
This layout is a Debian- and Ubuntu-packaging convention. It is not a universal requirement of Apache HTTP Server. Other operating systems and installation methods may use different directories and activation procedures.
For context, the same available/enabled pattern is also used for broader Apache configuration and virtual hosts. See Apache configuration files, conf-available, and sites-available.
Files Found in mods-available
Module file names usually follow a consistent base name. For example, a rewrite module may have:
/etc/apache2/mods-available/rewrite.load
/etc/apache2/mods-available/rewrite.confThe two common file types have different jobs:
| File pattern | Primary role | Typical directives or contents | Enablement behavior |
|---|---|---|---|
*.load | Loads a dynamic Apache module. | A LoadModule directive associating a module identifier with a shared object. | a2enmod creates an enabled link when the file is part of the module definition. |
*.conf | Provides supplemental module configuration. | Defaults, security settings, feature options, or other module-specific directives. | The file is linked when the module has accompanying configuration that should be active. |
A module commonly has both files, but this is not mandatory. Some modules have only a .load file. Others may need supplemental configuration without a separate loader file in a particular packaging arrangement. Some module behavior is configured elsewhere, so no module-specific .conf file is required.
Naming is normally consistent: files beginning with the same base name belong to the same module definition. Package-provided names should be treated as authoritative.
Understanding a .load File
A .load file conventionally contains one or more LoadModule directives. The directive loads a dynamic shared object, commonly a Linux .so file, and gives Apache the module identifier used by the server.
LoadModule example_module /path/to/mod_example.soThis is structural syntax only. In a real installation, use the module identifier and binary path supplied by the package. Do not guess or replace those values unless you have a specific packaging or build requirement.
Loading a module is not the same as configuring it. Loading makes the module's code available to Apache. Its directives still need to be placed in an appropriate configuration scope, such as a global configuration, virtual host, directory, or location context.
Understanding a .conf File
A module's .conf file contains directives needed or commonly used by that module. These directives can establish defaults, enable options, restrict behavior, or define security-related settings.
For example, a module configuration file might set a default feature or declare access restrictions. The exact directives depend on the module. A directive in such a file is meaningful only when the relevant module is loaded; otherwise Apache may report it as invalid or unknown.
How mods-enabled Works
/etc/apache2/mods-enabled is the active module configuration set. Its entries are normally symbolic links to corresponding files in mods-available.
rewrite.load -> ../mods-available/rewrite.load
rewrite.conf -> ../mods-available/rewrite.confThe Debian Apache configuration includes the enabled directory, so Apache reads the linked files during startup or reload. A file can therefore be available without being active.
| State | Meaning |
|---|---|
| Available | The module definition exists in mods-available. |
| Enabled | Relevant symbolic links exist in mods-enabled. |
| Loaded | Apache has successfully loaded the module into a running process, subject to configuration and build details. |
| Configured | Apache has applicable directives that use the module's features. |
These states are related but not identical. A module can be available but disabled, enabled but unable to load because of an error, loaded but unused by any site, or loaded and configured differently across virtual hosts.
Direct edits in mods-enabled are generally less maintainable because that directory is intended to contain activation links. Package updates and helper commands can change its contents. Use a2enmod and a2dismod for activation, and make local configuration changes in the applicable source or administrator-managed configuration location.
Inspecting Available and Enabled Modules
List the available definitions:
ls -l /etc/apache2/mods-available/Look for matching .load and .conf files. Read a particular definition before enabling it:
sudo sed -n '1,160p' /etc/apache2/mods-available/rewrite.load
sudo sed -n '1,200p' /etc/apache2/mods-available/rewrite.confInspect active links:
ls -l /etc/apache2/mods-enabled/The output should show link targets. A missing link means that the corresponding available definition is not selected through the normal Debian mechanism.
Enabling a Module with a2enmod
a2enmod is a Debian-family helper utility for activating a module by name. It manages the symbolic links under mods-enabled instead of requiring you to edit Apache include files manually.
sudo a2enmod rewriteThe command may report that the module was already enabled, create links for its .load and .conf files, or warn about dependencies. Review the output rather than assuming that every requested change succeeded.
A typical URL-rewriting workflow is:
sudo a2enmod rewrite
ls -l /etc/apache2/mods-enabled/ | grep rewrite
sudo apache2ctl configtest
sudo systemctl reload apache2
sudo apache2ctl -M | grep rewriteapache2ctl configtest should report Syntax OK before the reload. A reload applies configuration to new or reconfigured worker processes without the service interruption normally associated with a full restart.
Disabling a Module with a2dismod
a2dismod deactivates a module configuration. It removes the active symbolic links but preserves the source files in mods-available.
sudo a2dismod rewrite
ls -l /etc/apache2/mods-enabled/ | grep rewrite || true
sudo apache2ctl configtest
sudo systemctl reload apache2Before disabling a module, check virtual hosts and other configuration that may use its directives. For example, disabling a proxy, SSL, authentication, headers, or rewrite module can make existing site configuration invalid or change request handling.
Dependency warnings are important. A module may depend on another module, or a site may depend on the feature even when Apache's helper does not identify every application-level dependency. Correct the dependent configuration, enable the required module again, or test the affected site before completing the change.
Operational Verification
| Task | Command | Expected result | Follow-up verification |
|---|---|---|---|
| Enable a module | sudo a2enmod rewrite | Links are created in mods-enabled, or the command reports that they already exist. | ls -l /etc/apache2/mods-enabled/ |
| Disable a module | sudo a2dismod rewrite | Active links are removed while available files remain. | Run apache2ctl configtest and inspect dependent sites. |
| Test configuration | sudo apache2ctl configtest | Syntax OK, or an error identifying a file and line. | Fix the reported problem before reloading. |
| List loaded modules | sudo apache2ctl -M | Apache lists loaded modules, commonly distinguishing static and shared modules in the output. | Search for the expected module name. |
apache2ctl -M shows the modules known to the running Apache configuration. Some modules are compiled statically into Apache and cannot be disabled through a .load link. Dynamically loaded modules normally appear as shared modules after their LoadModule directive is processed.
Use the service-management command appropriate to the operating system. On Debian and Ubuntu installations managed by systemd, the usual command is:
sudo systemctl reload apache2If a reload fails, inspect the configuration-test output and, when necessary, the service logs. Do not repeatedly restart Apache while a known syntax error remains unresolved.
Practical Example: Enabling a Module with Supplemental Configuration
Suppose a package supplies both:
/etc/apache2/mods-available/example.load
/etc/apache2/mods-available/example.confRunning:
sudo a2enmod examplecan activate both files by creating links such as:
/etc/apache2/mods-enabled/example.load -> ../mods-available/example.load
/etc/apache2/mods-enabled/example.conf -> ../mods-available/example.confReview the .conf file before deployment. Its defaults may affect security, authentication, logging, compression, proxying, or request processing. Enabling the module loads its code and activates packaged configuration; it does not automatically guarantee that your virtual host has the correct site-specific settings.
Troubleshooting Module Problems
Apache Reports an Invalid or Unknown Directive
Likely causes include a disabled module, a missing module package or shared object, a misspelled directive, or use of the directive in an unsupported configuration context.
- Run
sudo apache2ctl configtestand note the file and line reported. - Identify which module supplies the directive.
- Check for the module's files in
/etc/apache2/mods-available. - Check for corresponding links in
/etc/apache2/mods-enabled. - Enable the required module if it is installed, then run the configuration test again.
- After a successful test, reload Apache and verify with
sudo apache2ctl -M.
The Module Is Enabled but Its Behavior Is Missing
- Confirm that the module appears in
sudo apache2ctl -M. - Check whether the module's
.conffile is enabled and whether its directives are appropriate. - Confirm that the relevant virtual host, directory, or location configuration uses the feature.
- Check permissions and other access controls that may prevent the behavior from applying.
- Run
sudo apache2ctl configtest, then reload Apache after correcting problems.
Apache Fails to Reload
A module-specific directive may be invalid, another configuration may depend on the disabled module, or an unrelated site or global configuration may contain a syntax error.
- Run
sudo apache2ctl configtestbefore attempting another reload. - Read the complete error, including the file and line number.
- Re-enable a required dependency or correct the reported directive.
- Review service logs if the syntax test does not explain the failure.
Manual Changes in mods-enabled Become Inconsistent
mods-enabled is intended primarily for symbolic links managed by the package layout and helper utilities. Inspect a link with:
ls -l /etc/apache2/mods-enabled/rewrite.loadMake source changes in the applicable available or administrator-managed configuration location, and use a2enmod or a2dismod to manage activation. Preserve package-managed files where possible so package upgrades remain predictable.
Safe Administration Practices
- Enable only modules required by deployed sites and features.
- Remember that module changes can affect security, authentication, request handling, logging, compression, proxying, SSL/TLS, and URL rewriting.
- Review package-provided
.loadand.conffiles before enabling unfamiliar functionality. - Avoid modifying package-managed definitions unless there is a clear operational reason. Put local policy in a suitable administrator-managed configuration location.
- Test changes in a controlled environment before applying them to production.
- Run
apache2ctl configtestbefore every reload or restart. - Keep a rollback plan: record the previous enabled state, know which command reverses the change, and preserve a working configuration.
Key Takeaways
/etc/apache2/mods-availableis a Debian-family packaging directory for Apache module load definitions and optional module-specific configuration..loadfiles normally containLoadModuledirectives..conffiles contain additional directives whose meaning depends on the relevant module being loaded./etc/apache2/mods-enabledcontains active symbolic links to available definitions.- Use
a2enmodanda2dismodinstead of manually editing enabled links. - Verify changes with
apache2ctl configtest, inspect loaded modules withapache2ctl -M, and reload Apache only after a successful test.
For related administration tasks, see the mods-enabled directory, Apache SSL configuration, reverse proxy configuration, and Apache access and error logs.