apnscp provides a variety of means to customize your environment. Each service is different and the means to configure it varies. Many services have files that are verboten, don't touch under any circumstance. They are periodically overwritten and the primary means to ensure what you run is what is developed.

Apache

⚠️ DO NOT TOUCH: /etc/httpd/conf/httpd.conf
Customization file: /etc/httpd/conf/httpd-custom.conf

Additionally, module configuration may be inserted in /etc/httpd/conf.d to load or modify existing modules. Per-site configuration is located in /etc/httpd/conf.d/siteXX or /etc/httpd/conf.d/siteXX.ssl for SSL-specific context. By convention customizations are placed in a file named custom in these directories. To get the site ID of a domain use the helper command, get_site_id.

After making changes, htrebuild will compile Apache's modular configuration followed by systemctl reload httpd to reload the web server.

Dovecot

⚠️ DO NOT TOUCH: /etc/dovecot/conf.d/apnscp.conf
Customization file: /etc/dovecot/local.conf

A few conflicting files in /etc/dovecot/conf.d are wiped as part of Bootstrapper. These files will always be removed if found:

  • 10-auth.conf
  • 10-mail.conf

Postfix

⚠️ DO NOT TOUCH: /etc/postfix/master.conf
Customization file: /etc/postfix/main.cf

Postfix does not provide a robust interface to extend its configuration. /etc/postfix/master.cf, which is the service definition for Postfix, may not be updated as it is replaced with package updates.

Pay special adherence to configuration variables in Bootstrapper. These are always overwritten during integrity check. To override these variables, create a special variable named postfix_custom_config in /root/apnscp-vars-runtime.yml. This is a dict that accepts any number of Postfix directives that takes precedence.

Sample

postfix_custom_config:
  disable_vrfy_command: no
  vmaildrop_destination_rate_delay: 15

MySQL

⚠️ DO NOT TOUCH: /etc/my.cnf.d/apnscp.conf
Customization file: /etc/my.cnf.d/*

PostgreSQL

⚠️ DO NOT TOUCH: n/a
Customization file: /var/lib/pgsql/<ver number>

PHP

⚠️ DO NOT TOUCH: /etc/php.ini (managed block)
Customization file: /etc/phpXX.d/*

apnscp uses a managed block in /etc/php.ini. Any directives within this block will always be overwritten. To override any values within this block, make changes in /etc/phpXX.d/ where XX is the version major/minor of PHP. Note this affects global PHP settings. To change settings per site look into php_value in either .htaccess or siteXX/custom mentioned above in Apache.

SpamAssassin

⚠️ DO NOT TOUCH: n/a
Customization file: /etc/mail/spamassassin/local.cf

rspamd

⚠️ DO NOT TOUCH: /etc/rspamd/local.d/*
Customization file: /etc/rspamd/override.d/*

For each file in local.d to override create a corresponding file in override.d/. This follows either UCL or JSON. When working with JSON, drop the leading + closing braces ("{", "}"). This is due to a parsing quirk of rspamd. An example of reconstituting to valid JSON is available in the Github repository.

Additionally rspamd Playbook variables may be overrode in a similar manner to Postfix. In /root/apnscp-vars.yml add:

rspamd_neural_custom_config:
  enabled: false
rspamd_actions_custom_config:
  add_header: 20

rspamd provides many configurables that don't require a direct override. Neural module for example is also conditionally enabled using rspamd_enable_neural_training. Be sure to refer back to defaults in mail/rspamd.

apnscp

⚠️ DO NOT TOUCH: /usr/local/apnscp/config/*
Customization file: /usr/local/apnscp/config/custom/*

apnscp supports overriding views, apps, modules, and configuration.

View overrides

All views may be copied into config/custom/resources/views/<path> from resources/views/<path>. Custom views take precedence, including all mail templates.

App overrides

Copy the app from apps/<name> to config/custom/apps/<name>.  Role menus, i.e. what is loaded when a corresponding user type logs in (admin, site, user) may be overridden as well. Menus are based on code under lib/html/templateconfig-<role>.php. Additional includes may be located under config/custom/templates/<role>.php. This is a sample extension for apnscp when a billing module is configured to allow clients direct access to manage billing:

config/custom/templates/site.php:

<?php

$templateClass->create_link(
        'Billing History',
        '/apps/billinghistory',
        cmd('billing_configured'),
        null,
        'account'
);

$templateClass->create_link(
        'Change Billing',
        '/apps/changebilling',
        cmd('billing_configured'),
        null,
        'account'
);

$templateClass->create_link(
        'Client Referrals',
        '/apps/referrals',
        cmd('billing_configured'),
        null,
        'account'
);

Global constants

Constants may be overrode or added to global scope via config/custom/constants.php:

<?php
        return [
                'BILLING_HOST_READ'   => $dbyaml['billing']['read']['host'],
                'BILLING_HOST_WRITE'  => $dbyaml['billing']['write']['host'],
                'BILLING_USER'        => $dbyaml['billing']['read']['user'],
                'BILLING_PASSWORD'    => $dbyaml['billing']['read']['password'],
                'BILLING_DB'          => $dbyaml['billing']['read']['database'],
                'BILLING_HOST_BACKUP' => $dbyaml['billing']['backup']['host'],
        ];

Themes

New themes may be created and placed under public/css/themes and public/images/themes. The default theme may be changed with cpcmd:

cpcmd config_set apnscp.config style theme newtheme

apnscp configuration

All configuration must be made to config/custom/config.ini. cpcmd provides a short-hand tool to edit this file.

# Show all configuration 
cpcmd config_get apnscp.config
# Set configuration
cpcmd config_set apnscp.config core fast_init true

Refer to config.ini that ships with apnscp for a list of configurables.

© 2019 Apis Networks. All Rights Reserved.