Our documentation is getting an overhaul! We would like your input! Click here to take a look at the beta launch of our new documentation site! Only cPanel & WHM version 82 documentation exists on our beta at this time. 84 will be added to the new site soon! Leave your feedback here: https://go.cpanel.net/docsfeedback
Guide to Perl in cPanel - Apache Configuration - Developer Documentation - cPanel Documentation
Child pages
  • Guide to Perl in cPanel - Apache Configuration
Skip to end of metadata
Go to start of metadata

Overview

Important

This document only applies to systems that run cPanel & WHM version 84 or higher. 

You can customize your Apache configuration with the Cpanel::EA4::Conf class. 

Customize your Apache configuration

Warning:

  • You must use Perl to perform these actions.
  • Do not edit the /etc/cpanel/ea4/ea4.conf file manually. This may cause unexpected behavior. The Cpanel::EA4::Conf class provides data validation. If you edit the JSON directly, you may cause server malfunctions. 

In cPanel & WHM version  84, we introduced the Cpanel::EA4::Conf class. This class allows third-party integrators to set the contents of the /etc/cpanel/ea4/ea4.conf file. This file consolidates all of your server's options into a single JSON file. This file also replaces the /var/cpanel/conf/apache/local and /var/cpanel/conf/apache/main files. 

Use the class

To use this class, write a Perl script that utilizes the class's methods and then call your customizations in your template. 

Your code might resemble the following example:

use Cpanel::EA4::Conf ();

    my $ea4cnf = Cpanel::EA4::Conf->instance();
    $ea4cnf->directoryindex($new_value);
    $ea4cnf->save;

For the above example, you would use the following in your template:

[% ea4conf.directoryindex %]

Methods

You can use the following methods in your Perl scripts with this class:

MethodDescription
new()

Returns a new EA4::Conf object. You can use any configuration directive that is not read only. Your script might resemble the following example:

Cpanel::EA4::Conf->new(directoryindex => $new_value)->save;
instance()

Returns a new EA4::Conf object. This method allows you to create multiple instances. This is the preferred method and allows you to avoid using a global variable. Your script might resemble the following example:

sub foo {
my $ec = Cpanel::EA4::Conf->instance();
…
}

sub bar {
my $ec = Cpanel::EA4::Conf->instance();
…
}

Note:

You can also use the same arguments that the new() method uses. 

warn_unsaved()

Returns a warning if unsaved changes exist. This method only accepts an argument of 0 or 1.

conf_attrs()Returns an array reference of the directives that you can configure.
save()

Save the current values to the /etc/cpanel/ea4/ea4.conf JSON file.

as_hr()Returns the configuration object in a hash reference.
as_distiller_hr()

Returns the configuration object in a hash that the distiller can use. This method does not accept an argument.

Note:

This method only exists to support older servers. We will remove this method in cPanel & WHM version 86.

save_from_hr($hr)

Writes the known configurations in the $hr hash reference to an object, and then saves the object.

is_dirty()

Returns a true value if any configuration directive exists. This method does not accept an argument.

local_attrs()

Returns a hash reference of local attributes. Use this method to update arbitrary configuration data. Your code might resemble the following example:

my $e4c = Cpanel::EA4::Conf->instance();
$e4c->local_attrs->{foo} = 42;
$e4c->local_attrs->{bar} = "oh hai";
delete $e4c->local_attrs->{baz};
$e4c->save;

In your custom template, you would use the following entries:

[% ea4conf.local_attrs.foo %]
[% ea4conf.local_attrs.bar %]

Configuration directives

This class includes several directives that you can configure.

To retrieve a value, your code might resemble the following example:

my $directoryindex = $conf_obj->directoryindex;


To set the value of a directive, your code might resemble the following example:

$conf_obj->directoryindex("index.js index.html");


You can set the following directives with this class:

Note:

Except where specified, you can set all of the following directives in the Global Configuration section of WHM's Apache Configuration interface (WHM >> Home >> Service Configuration >> Apache Configuration). 

DirectiveDescriptionArguments
directoryindex

Sets the files that the server returns when a URL does not refer to a specific file. 

Note:

You can also set this directive in the DirectoryIndex Priority section of WHM's Apache Configuration interface (WHM >> Home  >> Service Configuration >> Apache Configuration).

A space-separated string
extendedstatus

Shows more details about incoming requests.

  • On
  • Off
fileetagDetermines the amount of information that Apache provides to visitors who request a file via HTTP.
  • All
  • None
  • INode MTime
  • INode Size
  • MTime Size
  • INode MTime Size
keepaliveEnables or disable persistent HTTP connections.
  • On
  • Off
keepalivetimeoutThe number of seconds that Apache waits for another request before it closes a connection.An integer greater than 0, in seconds
logformat_combinedThe Apache log file's format, including the referrer and user agent strings.A string.
logformat_commonThe Apache log file's format.A string.
loglevelThe verbosity of the error log.
  • emerg
  • alert
  • crit
  • error
  • warn
  • notice
  • info
  • debug
maxrequestworkers Sets the limit on the number of simultaneous requests that Apache serves.An integer greater than 0.
maxkeepaliverequestsThe number of requests that a persistent connection allows.An integer greater than 0.
maxconnectionsperchildThe number of requests that an individual child server process can handle.An integer greater than 0.
maxspareserversSets the maximum number of idle child server processes. An integer greater than 0.
minspareserversSets the minimum number of idle child server processes.An integer greater than 0.
rlimit_cpu_hardMaximum number of CPU seconds a process can use.An integer greater than 0.
rlimit_cpu_softMaximum number of CPU seconds a process can use.An integer greater than 0.
rlimit_mem_hard

Maximum number of bytes seconds a process can use.

Note:

You can also set this directive in the Memory Usage Restrictions section of WHM's Apache Configuration interface (WHM >> Home  >> Service Configuration >> Apache Configuration).

An integer greater than 0 or a blank string.
rlimit_mem_soft

Maximum number of bytes seconds a process can use.

Note:

You can also set this directive in the Memory Usage Restrictions section of WHM's Apache Configuration interface (WHM >> Home  >> Service Configuration >> Apache Configuration).

An integer greater than 0 or a blank string.
root_optionsSets options that pertain to the root (/) directory.

A space-separated list that contains one or more of the following strings:

  • ExecCGI
  • FollowSymLinks
  • Includes
  • IncludesNOEXEC
  • Indexes
  • MultiViews
  • SymLinksIfOwnerMatch
serverlimitThe maximum configured value for the MaxRequestWorkers directive for the lifetime of the Apache process.An integer greater than 0.
servernameThe default server name. This value is read-only and you cannot change it with this class.None.
serveradminThe server administrator's email address. This value is read-only and you cannot change it with this class. None.
serversignatureWhether the server information appears in error results and other information that the server generates.
  • On
  • Off
  • Email
servertokensThe amount of information that Apache provides to visitors in Server HTTP response headers.
  • ProductOnly
  • Minimal
  • OS
  • Full
sslciphersuiteSets the OpenSSL ciphers that Apache uses.

A string of colon-separated ciphers.

sslprotocolThe SSL and TLS protocols that the client and server negotiate during the SSL/TLS handshake phase.A space-separated string of protocols.
startserversThe number of child server processes that Apache creates when it starts.An integer greater than 0.
symlink_protectEnables the Symlink Protection patch. This improves Apache's ability to detect a race condition.
  • On
  • Off
timeoutThe amount of time, in seconds, that Apache waits for an event before the request fails.An integer between 3 and 604800.
traceenableAllows or disallows TRACE requests.
  • On
  • Off
  • Extended

Customize your Apache configuration in the user interface

The WHM interface provides several ways to customize your Apache configuration: 

  • cPanel & WHM sets several Apache directives by default. These directives affect the whole server. To change these directives, use the Global Configuration section of WHM's Apache Configuration interface (WHM >> Home >> Service Configuration >> Apache Configuration).
  • To modify the Apache configuration's include files through WHM, use the Include Editor section of WHM's Apache Configuration interface (WHM >> Home  >> Service Configuration >> Apache Configuration).

We provide several other ways to customize your system. You can also create custom configurations with the following actions: 

For more information, read our Advanced Apache Configuration documentation.