Customizing Apache

I wish to customize the main Apache configuration and not lose the changes

If you make customized changes to your /etc/httpd/conf/httpd.conf file, CustomBuild will overwrite these changes as soon as it rebuilds Apache.

There are 3 ways of making your customizations stick:

1. The "official" way would be to use the CustomBuild custom directory method:

mkdir -p /usr/local/directadmin/custombuild/custom/ap2/conf/extra
# Copy files that need customizations from /usr/local/directadmin/custombuild/configure/ap2/conf/extra to /usr/local/directadmin/custombuild/custom/ap2/conf/extra

and then edit your configs in the custom/ap2/conf/ directory as needed. The custom path overrides the default, and won't be overwritten. Your customized files will be used for the config rewrites, so you just need to remember to make your changes in the custom path.

If you make changes to the custom files, you can test what result you'll get by typing:

da build rewrite_confs

2. If you only need to add extra Apache config code to the system, but don't need to remove any existing code, the best way is to add your changes to /etc/httpd/conf/extra/httpd-includes.conf as this file will not be touched by CustomBuild or DirectAdmin.

If the httpd-includes.conf doesn't exist, DA will 'touch' it so that it does exist.

CUSTOM HTTPD TEMPLATES: Starting point

DirectAdmin offers a huge variety of ways to customize your User's VirtualHost entries.
This guide will help you pick which method to use depending on what you need it to do.
Should you know what you want to use, enter the info here:
Username:
Domain:
Subdomain:
Template Name: See #1 for options
Server Type: or: cust_nginx, cust_openlitespeed
Token Name: or: CUSTOM1, CUSTOM2, etc.

Outlined below are the major sections to consider when deciding which method to use:

1. Raw Templates

These are located in /usr/local/directadmin/data/templates/. We typically discourage relying on custom versions of these in case we make important changes to them, in which case you wouldn't inherit these changes. In some cases, you will need to use a custom copy, but only if none of the options below work for you. The 4 templates typically in question would be:

    #Apache 2.x
    virtual_host2.conf
    virtual_host2_secure.conf
    virtual_host2_sub.conf
    virtual_host2_secure_sub.conf

    #Nginx
    nginx_server.conf
    nginx_server_secure.conf
    nginx_server_sub.conf
    nginx_server_secure_sub.conf

    #OpenLiteSpeed
    openlitespeed_vhost.conf #combined for all 4

2. Per-Domain with the CUSTOM tokens via Custom Httpd Config

This Admin Level area lets you insert code into any CUSTOM or CUSTOM# token point for all VirtualHosts in that domain, including http and https for both domains and subdomains.

This method is used only when you want to change a setting just for this domain.

This GUI tool saves files to disk (depending on the token name), e.g.,

"/usr/local/directadmin/data/users/fred/domains/fred.com.cust_httpd"     #CUSTOM
"/usr/local/directadmin/data/users/fred/domains/fred.com.cust_httpd.1"   #CUSTOM1
... #CUSTOM2, etc.

3. Tokens for Global, Per-User, Per-Domain

This tool is used to insert token variables where applicable. You're not saving a file for each CUSTOM token name, but you can create the mentioned file below to preload some tokens. This will allow you to set tokens before any other CUSTOM tokens are set (it's not for code itself, just for setting variables). Continue with this guide on how to set a token with the |?TOKENNAME=value| syntax. Token variables can be used within a value, e.g.,

|?TOKENNAME=value of 'OTHERTOKEN'|

These files are available to load in your custom tokens of various levels:

"/usr/local/directadmin/data/admin/global_httpd_tokens.conf" #global
"/usr/local/directadmin/data/users/fred/user.httpd_tokens" #per user
"/usr/local/directadmin/data/users/fred/domains/fred.com.httpd_tokens" #per domain
"/usr/local/directadmin/data/users/fred/domains/fred.com.sub.httpd_tokens" #per subdomain

Note that "httpd_tokens" is the name used, regardless of server type (httpd/nginx/litespeed/openlitespeed).

This is independent of the template name, so these tokens will be loaded into all of the 4 virtual_host2*.conf templates mentioned above.

4. Global VirtualHost Pre/Post

These templates depend on the "Template Name" above, so preset that if you're trying to sort out which to use.

Using these files will write the given code into the User's httpd.conf either before or after, outside of the VirtualHost tag, for any use of the given template file.

Paths can be either:

"/usr/local/directadmin/data/templates/custom/virtual_host2.conf.pre"
"/usr/local/directadmin/data/templates/custom/virtual_host2.conf.post"

This might be handy if you want to insert a https://webmail.domain.com VirtualHost (e.g., you'd use the /usr/local/directadmin/data/templates/custom/virtual_host2_secure.conf.post, so it only gets added once per domain, and only for https).

5. Global Token name per file, pre/post

Similar to the global CUSTOM tokens, this lets you control only which template it goes with. Your code will be inserted either before or after any use of the given CUSTOM* tokens. For example, if you use the pre variant, this code is inserted before say, per-domain CUSTOM inserted code. Possible files might be:

"/usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.pre"
"/usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.post"

6. Global CUSTOM token, regardless of filename

This one is related to the global tokens, except you can use this for actual code as it's injected in a specific order. Applies to all template files. Possible files include:

"/usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.pre"
"/usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.post"
"/usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.1.pre"
"/usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.1.post"
... CUSTOM.2.pre ... etc.

Take note regarding how the numbered tokens have a dot between CUSTOM and the number.

---

Note: for almost all areas, you can use if-then-else syntax and set variables which carry forward within that template.

Custom HTTPD templates: read order

Knowing the order in which all of the templates are being loaded in can help you to determine when your tokens will be available.

For this guide, we'll refer to Apache/httpd. If you're running Nginx or OpenLiteSpeed, the guide still applies, but changes in the template names may also apply. More on the different names in this guide.

1. Loaded once before each VirtualHost is added:

    CUSTOM_DOMAIN_ITEM_*

2.

    WEBSERVER, DOMAIN, SSL_TEMPLATE, SPACE_HTTP2, IP, PROXY_IP, HAVE_NGINX_PROXY, PORT_8080, PORT_8081, PROXY_BUFFERING,
    LISTENERS, IF_MODULE_LITESPEED_OPEN, IF_MODULE_LITESPEED_OPEN, IF_MODULE_LITESPEED_CLOSE, IP1|2.., MULTI_IP, HOME, USERHOME, PACKAGE,
    REALUSER, ADMIN, CERT, KEY, HOSTNAME, OPEN_BASEDIR, OPEN_BASEDIR_ENABLED, PHP_MAIL_LOG_ENABLED, CREATOR, BANDWIDTH, QUOTA,
    PORT_80, PORT_443, APACHELOGDIR

3.

    CB_VERSION, PHP1_RELEASE, PHP2_RELEASE, LSPHP1_RELEASE, LSPHP2_RELEASE, HAVE_PHP1_FPM, HAVE_PHP2_FPM, HAVE_PHP1_FCGI, HAVE_PHP2_FCGI,
    HAVE_PHP_FCGI, HAVE_RUID2, HAVE_MOD_SECURITY, HAVE_USERDIR_ACCESS, RUID2_AND_MOD_SECURITY,
    (MODSEC_AUDIT_DIR, NGINX_MOD_SECURITY_ENABLE)|NGINX_MOD_SECURITY_ENABLE, USE_HOSTNAME_FOR_ALIAS, HAVE_SUEXEC_PER_DIR, SUSPENDED_REASON,
    CLI, HAVE_PHP1_CLI, HAVE_PHP2_CLI, SUPHP, HAVE_PHP1_SUPHP, HAVE_PHP2_SUPHP, USECANONICALNAME, CAROOT

4.

    HANDLERS, MIMETYPES, USER, GROUP, SECURE_ACCESS_GROUP, (OLS)SSLPROTOCOL, SDOCROOT, SUSPENDED, CGI, PHP, SUB, FORCE_SSL_REDIRECT

5. Tokens TOK=value, not templates:

    /usr/local/directadmin/data/admin/global_httpd_tokens.conf
    /usr/local/directadmin/data/users/fred/user.httpd_tokens
    /usr/local/directadmin/data/users/fred/domains/domain.com.httpd_tokens
    /usr/local/directadmin/data/users/fred/domains/domain.com.sub.httpd_tokens

6. VirtualHost pre, where virtual_host2.conf would be whichever template file is used for this VH. Fully tokenized template.

    /usr/local/directadmin/data/templates/custom/virtual_host2.conf.pre

7.

    /usr/local/directadmin/data/templates/cust_httpd.CUSTOM.pre
    /usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.pre
    /usr/local/directadmin/data/users/fred/domains/domain.com.cust_httpd
    /usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.post
    /usr/local/directadmin/data/templates/cust_httpd.CUSTOM.post

added to CUSTOM.

8. For each custom token, 1 through 8 (we'll use 1 for the example):

    /usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.1.pre
    /usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.1.pre
    /usr/local/directadmin/data/users/fred/domains/domain.com.cust_httpd.CUSTOM.1
    /usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.1.post
    /usr/local/directadmin/data/templates/custom/virtual_host2.conf.CUSTOM.1.post

added to CUSTOM1

9.

    PROTECTED_DIRECTORIES, CONTEXTS, REALMS, NGINX_REDIRECTS, OPENLITESPEED_REDIRECTS, HOTLINK_PROTECTION, EXTRA_LOCATIONS, LOCATION_INSERT, NGINX_PHP_CONF

10. If exists:

/usr/local/directadmin/data/templates/custom/virtual_host2.conf

else:

/usr/local/directadmin/data/templates/virtual_host2.conf

Using a token that does not exist yet

Since the above order does matter, if you're using a token which has not yet been fixed, (as of DirectAdmin 1.61.0) a change has been done such that any unknown TOKEN will be swapped with |TOKEN|, which will be inserted into its final token location inside the template file by the tokenizer. So at that point, it should be known and properly filled, instead of being left as TOKEN in the template.

Using a custom VirtualHost template

If you wish to change the setup of the VirtualHosts for all domains, you can do so by creating your own custom templates.

cd /usr/local/directadmin/data/templates
cp virtual_host2*.conf custom
cd custom

Once you've copied the 4 VirtualHost files (or just the ones you want) to the custom directory, you can then edit the new files you've just copied. DirectAdmin will always check for the custom file before going to the default ones. Failure to copy the virtual_host2*.conf files to the custom directory before modifying them will result in a loss of all changes when DirectAdmin updates itself (because the files are overwritten). Note that there are actually 8 virtual_host files, but you only need to worry about the 4 that apply to you. The files with the 2 in them are for Apache 2.x.

Inside the virtual_host*.conf files, you'll find code that is similar to httpd.conf code, but contains what are known as tokens. These tokens are what will be replaced with specific user data for each domain created.

TOKENNAME	DESCRIPTION
DOMAIN	the name of the domain. e.g., domain.com
IP	the IP address associated with that domain. eg: 12.34.56.78
HOME	The users home directory. e.g., /home/gary
ADMIN	The email address of the server admin. webmaster@domain.com
HOSTNAME	The hostname of the server. e.g., server.domain.com
PHP	ON or OFF, if PHP is enabled or not
CGI	The whole httpd.conf line used to add the Script-Alias
HANDLERS	httpd.conf code holding all Apache handlers
MIMETYPE	httpd.conf code holding all Apache Mime Types
USER	the username
GROUP	the user's group name (99% of the time, it's the same as the USER)
DOCROOT	The DocumentRoot of the VirtualHost. This is the path that Apache will use to access the data when the ServerName (domain.com) is requested
SUB	the subdomain name (for the virtual_host_*sub.conf file) e.g., sub
CUSTOM	custom httpd.conf code to be inserted if the domain.com.cust_httpd file exists. (See Adding custom httpd.conf code the VirtualHost of one domain)
CAROOT	The whole httpd.conf line used to load in the SSLCACertificateFile directive
CERT	The path of the certificate to be used for the domain
CREATOR	The username of the account that created the User account who owns this domain
KEY	The path of the certificate to be used for the domain

The top of the templates should contain |?CGI=...| and |?DOCROOT=...|. These lines are where the data for the CGI and DOCROOT tokens are set. If CGI is not enabled, this line will be ignored and the CGI token will be empty. If the domain is suspended, the DOCROOT will be filled with the path of the suspended page. The CAROOT token will be empty unless the User has added a valid CARootCertificate through DA.

You can use tokens when assigning a value to CGI or DOCROOT, just use 'TOKEN' instead of |TOKEN|.

Once you are happy with your new virtual_host*.conf files, they'll need to be used in the real httpd.conf files. You can trigger DirectAdmin to rewrite all User httpd.conf files by running:

echo "action=rewrite&value=httpd" >> /usr/local/directadmin/data/task.queue

The command will be added the the task queue, which is checked once per minute, so it may be a few minutes before all httpd.conf files have been rewritten. *Note: the main /etc/httpd/conf/httpd.conf file is overwritten whenever CustomBuild rebuilds Apache, so any custom changes you make in this file will be not retained. Depending on the changes you intend to make, you may consider using the file /etc/httpd/conf/extra/httpd-includes.conf, as it is not overwritten during a rebuild.

Note that you can also use if-then-else statements if you don't want all settings to be global. Example, say you want a custom item added, only for 1 domain:

|*if DOMAIN="domain.com"|
#custom item for just this domain
|*endif|

See the if-then-else link for more info on what else you can do with this basic scripting tool.

You can also run actual scripts with database queries, etc., (that is, if you wanted using the scripting portion of the templates).
More info on that here: http://www.directadmin.com/features.php?id=756

Adding custom httpd.conf code to the VirtualHost

DirectAdmin allows the Admin to insert extra httpd.conf code that a User may require. To access the control page for this functionality, go to Admin Panel -> Admin Settings -> Customize Httpd Configurations.

Once you see the list of domains, click the domain you wish to insert the extra httpd.conf code for.

At the bottom of the page, you'll see the current httpd.conf for that User. It will contain all VirtualHosts for all domains, subdomains and redirects. Any changes made by this page will only affect the VirtualHosts for the domain in question, not the other domains owned by that user. If all domains need the changes, then you would repeat this process for each domain.

The top textarea is where you will paste the custom httpd.conf code you wish to insert. The code you write will be inserted into the |CUSTOM| token for all VirtualHosts for this domain. You can edit the templates as needed if you require to move the |CUSTOM| token to a different position in the VirtualHost.

All tokens that are available for the VirtualHost will be available with this feature. You can also set any token you wish. For example, if you with to change the DocumentRoot for a domain, you can paste:

|?DOCROOT=/new/path/you/want|

Note that this new DocumentRoot will be used for all DocumentRoots for this domain, including https connections and subdomains, so it may not be a desired effect.

Another common use is to add another ServerAlias. This allows another domain to be used to access the exact same content. To accomplish this, you would write:

ServerAlias newdomain.com www.newdomain.com

to get newdomain.com and www.newdomain.com to point to the original domain for the VirtualHost. You will also have to make sure that newdomain.com and www.newdomain.com both resolve to the same IP as stored in |IP|.

---

Note, the above example will set the DOCROOT token into all 4 templates, so this will also apply to all subdomains, which may not be desired.

To only make the DOCROOT apply to the domain, and not to the subdomain, add an if, e.g.,

|*if !SUB|
|?DOCROOT=/new/path/you/want|
|*endif|

How to use different ciphers with Apache

With the ever evolving needs for security, good encryption cipher lists can change regularly. Also, the needs of those connecting to a given server may be different from box to box, e.g.,

• Some servers require the maximum standards of security.
• Some clients have old browsers which cannot use modern ciphers.
• Some API scripts cannot use modern ciphers.

Etc., so each case might be different.

To use different ciphers with Apache 2.x and CustomBuild, you can use the "custom" folder method to manage your own cipher lists and SSL rules.

If you wanted a more secure list of ciphers, you could run the following:

cd /usr/local/directadmin/custombuild
mkdir -p custom/ap2/conf/extra
cp configure/ap2/conf/extra/httpd-ssl.conf custom/ap2/conf/extra/httpd-ssl.conf

which then lets you edit /usr/local/directadmin/custombuild/custom/ap2/conf/extra/httpd-ssl.conf for changes such as:

SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1

SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK

SSLHonorCipherOrder On

SSLCompression off

Note: the SSLCipherSuite list is all one long line. Also note that the recommended ciphers and protocols update very often, so you'll want to make sure to check set these accordingly.

This tool is very useful to get a good list for your scenario: Mozilla's SSL Config Generator

Once you've created the custom httpd-ssl.conf as desired, you can then install it with:

da build rewrite_confs

To disable TLSv1.1 and only allow TLSv1.2 and TLSv1.3 on OpenLiteSpeed:

echo '|?SSLPROTOCOL=24|' >> /usr/local/directadmin/data/templates/custom/openlitespeed_vhost.conf.CUSTOM.pre
/usr/local/directadmin/custombuild/build rewrite_confs

---

There is another way to set up ciphers per Apache/Nginx/OpenLiteSpeed/LiteSpeed/ProFTPD/Pure-FTPd. One may choose to just use the ssl_configuration option in CustomBuild. The settings reflect the Modern, Intermediate, or Old configuration per https://ssl-config.mozilla.org/. By default, this is set to Intermediate.

To switch to Old, for example:

da build set ssl_configuration old
da build rewrite_confs

Be informed that 'Modern' means to support TLS 1.3 only while CentOS7 / Debian 8 does not have it. Old OS's support TLSv1.3 by default in LiteSpeed/OpenLiteSpeed only.

Adding custom modules to Apache for CustomBuild

If you want to add any extra modules to Apache in CustomBuild, they'll need to be compiled in. Any module that needs to be compiled in will have a --with- type flag which will need to be used. The To add this flag, run the following:

cd /usr/local/directadmin/custombuild
mkdir -p custom/ap2
cp configure/ap2/configure.apache custom/ap2/configure.apache
vi custom/ap2/configure.apache

Add your --with-module line to the end of the file, and make sure the \ character exists at the end of all lines except the last one. Then build Apache:

da build clean
da build apache

Then restart Apache:

systemctl restart httpd

If you run into problems, you may also need to recompile PHP as well:

da build php

Then restart Apache again.

How to modify the open_basedir setting for one domain