Apache HTTP Server course

Apache conf-enabled Directory: Enabling and Disabling Global Configuration Files

Learn how Debian and Ubuntu Apache use conf-available and conf-enabled, plus a2enconf, a2disconf, configtest, reload, and restart.

On Debian-family systems such as Debian and Ubuntu, /etc/apache2/conf-enabled/ is the activation directory for global Apache configuration snippets. It normally contains symbolic links to selected files in /etc/apache2/conf-available/.

This arrangement separates configuration content from activation. A snippet can remain available without being active, and disabling it usually removes only its enabled link rather than deleting the source file.

What the conf-enabled Directory Does

A configuration snippet is a focused Apache configuration file that supplies settings for a feature or shared behavior. A global snippet can affect the Apache server broadly rather than only one virtual host.

The directory /etc/apache2/conf-enabled/ represents the globally active snippets in a typical Debian-style Apache installation. Its entries are normally symbolic links, not separate configuration copies.

A symbolic link is a filesystem reference that points to another file or directory. In this case, a link in conf-enabled points to a source file in conf-available. The Debian Apache main configuration include structure is set up to read the enabled configuration entries, so the presence of the link controls whether the corresponding snippet is included.

/etc/apache2/conf-available/serve-cgi-bin.conf
/etc/apache2/conf-enabled/serve-cgi-bin.conf -> ../conf-available/serve-cgi-bin.conf

The exact include statements can vary by package version, but the operating principle is the same: Apache loads the selected files exposed through the enabled directory.

conf-available Versus conf-enabled

/etc/apache2/conf-available/ stores available global configuration snippet files. A file may exist there without being loaded by Apache.

/etc/apache2/conf-enabled/ is the activation layer. It contains links for the available snippets that should be included. Removing an enabled link normally leaves the source file in conf-available, ready for later use.

Apache Configuration Directories and Their Roles

Location: /etc/apache2/conf-available | Contents: Available global snippets | Purpose: Store source configuration files | Loaded as enabled configuration: Not by itself

Location: /etc/apache2/conf-enabled | Contents: Links to selected global snippets | Purpose: Activate global snippets | Loaded as enabled configuration: Yes, through the main include structure

Location: /etc/apache2/sites-available | Contents: Virtual-host configuration files | Purpose: Store available site definitions | Loaded as enabled configuration: Only when linked through sites-enabled

Location: /etc/apache2/sites-enabled | Contents: Links to selected virtual-host files | Purpose: Activate site definitions | Loaded as enabled configuration: Yes, through the site include structure

Location: /etc/apache2/mods-available | Contents: Module configuration files | Purpose: Store available module configuration | Loaded as enabled configuration: Only when the module is enabled through mods-enabled

Location: /etc/apache2/mods-enabled | Contents: Links to enabled module configuration | Purpose: Activate module configuration | Loaded as enabled configuration: Yes, through the module include structure

Inspecting Available and Enabled Snippets

List the source files in conf-available:

ls -l /etc/apache2/conf-available/

List the enabled entries. The -l option reveals symbolic-link targets:

ls -l /etc/apache2/conf-enabled/

To determine whether a particular snippet is active, look for its corresponding entry under conf-enabled and inspect where the link points. Do not assume that a file in conf-available is loaded.

Enabling a Configuration with a2enconf

a2enconf is a Debian-family helper command for enabling a named global configuration snippet. The name generally refers to a file in /etc/apache2/conf-available/.

sudo a2enconf serve-cgi-bin.conf

When successful, the command creates an enabled symbolic link for the requested configuration. It does not usually copy the source file into conf-enabled.

After enabling a snippet, test the complete Apache configuration before asking the running service to use it:

sudo apache2ctl configtest

If the test succeeds, apply the change with a reload or restart:

sudo systemctl reload apache2
sudo systemctl restart apache2

A reload applies updated configuration without a full stop-and-start cycle. A restart performs a full service stop and start and may be needed when a complete restart is required.

Disabling a Configuration with a2disconf

a2disconf deactivates a named global configuration snippet by removing its enabled symbolic link.

sudo a2disconf serve-cgi-bin.conf

The source file in conf-available remains available. You can enable it again later with a2enconf.

sudo apache2ctl configtest
sudo systemctl reload apache2

As with enabling, the filesystem change is not necessarily reflected in the running Apache process until a successful reload or restart applies the configuration.

Configuration Management Commands

Command: a2enconf name.conf | Action: Enable a global snippet | Filesystem effect: Creates a link in conf-enabled | Follow-up: Run apache2ctl configtest, then reload or restart

Command: a2disconf name.conf | Action: Disable a global snippet | Filesystem effect: Removes its link from conf-enabled | Follow-up: Test, then reload or restart

Command: apache2ctl configtest | Action: Test Apache configuration syntax | Filesystem effect: None | Follow-up: Apply changes only after a successful test

Command: systemctl reload apache2 | Action: Apply configuration without a full stop/start cycle | Filesystem effect: None | Follow-up: Check service status if behavior is unexpected

Command: systemctl restart apache2 | Action: Fully stop and start Apache | Filesystem effect: None | Follow-up: Check service status and logs

Enable, Disable, and Delete Compared

Operation: Enable with a2enconf | conf-available file: Preserved | conf-enabled link: Created | Result: The snippet becomes selected for inclusion after Apache reloads or restarts

Operation: Disable with a2disconf | conf-available file: Preserved | conf-enabled link: Removed | Result: The snippet is no longer selected for inclusion after Apache reloads or restarts

Operation: Delete the source configuration file | conf-available file: Removed | conf-enabled link: May become broken or be removed separately | Result: The snippet is no longer safely available for re-enablement

Directly creating or removing symbolic links is technically possible, but the helper commands are preferred because they follow the package layout and provide useful validation and error messages. Keep configuration content in conf-available and use the enabled directory as the activation layer.

Example Lifecycle: serve-cgi-bin.conf

serve-cgi-bin.conf is a useful example of a global snippet commonly associated with CGI-bin handling. The exact feature behavior depends on the directives, modules, paths, and other Apache configuration on the system.

1. Confirm the source file exists

ls -l /etc/apache2/conf-available/serve-cgi-bin.conf

2. Check whether it is enabled

ls -l /etc/apache2/conf-enabled/

Look for an entry named serve-cgi-bin.conf whose target points to the file in conf-available.

3. Disable the snippet

sudo a2disconf serve-cgi-bin.conf

4. Verify that the link is absent

ls -l /etc/apache2/conf-enabled/

The source file should still be present, while the corresponding enabled link should no longer appear.

5. Validate and apply the change

sudo apache2ctl configtest
sudo systemctl reload apache2

After Apache applies the change, features governed by the snippet may stop operating or may no longer be available through the affected configuration.

6. Enable it again

sudo a2enconf serve-cgi-bin.conf
ls -l /etc/apache2/conf-enabled/
sudo apache2ctl configtest
sudo systemctl reload apache2

The enabled symbolic link should return and point to the intended source file. After the reload succeeds, the related CGI-bin behavior can resume, subject to the rest of the Apache setup.

Safely Applying Apache Configuration Changes

  1. Inspect the intended source file and enabled link. Confirm that the snippet exists and that the activation state is what you expect.
  2. Test the complete configuration. Run sudo apache2ctl configtest, not just a check of the changed file. Apache must parse the complete set of enabled configuration.
  3. Apply a valid change. Prefer sudo systemctl reload apache2 for ordinary configuration changes. Use restart when a full service restart is required.
  4. Check the service and logs. If the result is unexpected, run sudo systemctl status apache2 and inspect the Apache error output.

Syntax errors, missing modules, unavailable paths, missing certificates, missing included files, and conflicting directives can prevent a changed configuration from loading. A configuration test that fails should be corrected before reloading or restarting.

Troubleshooting

a2enconf says the configuration does not exist

  • List /etc/apache2/conf-available/ and check the spelling.
  • Use the exact filename expected by the helper command, such as serve-cgi-bin.conf.
  • Confirm that the operating system uses the Debian-style Apache package layout.

The enabled state changed, but server behavior did not

  • Apache may not have been reloaded or restarted.
  • Another configuration may override the setting.
  • The feature may actually depend on a module, virtual-host file, or another global snippet.
  • Run apache2ctl configtest, reload Apache, and inspect related enabled sites, modules, and snippets.

Apache fails to reload after enabling a snippet

  • Run sudo apache2ctl configtest to identify syntax errors.
  • Check sudo systemctl status apache2 and Apache error output.
  • Look for unavailable modules, paths, certificates, included files, or conflicting directives.
  • If necessary, disable the recently enabled snippet, correct its dependencies, and test again.

The expected link is missing

  • Confirm that the source exists under conf-available.
  • Re-enable it with sudo a2enconf name.conf.
  • Check the command output, directory permissions, and whether the command was run with administrative privileges.

Manual changes cause inconsistent behavior

The enabled directory is intended to be a symbolic-link activation layer, not the primary location for configuration content. Keep the source file in conf-available, use a2enconf and a2disconf, and use ls -l to inspect links without accidentally changing their targets.

Distribution and Configuration Scope

The conf-available and conf-enabled directories manage global Apache snippets. They are different from site-specific virtual-host configuration in sites-available and sites-enabled, and different from module activation in mods-available and mods-enabled.

For related directory concepts, see Apache conf-available, sites-available, sites-enabled, mods-available, and mods-enabled. For the main configuration structure, see the Apache2 conf file.