| title |
|---|
Customizing ApisCP |
ApisCP 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.
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.
A placeholder page is created whenever an account, addon domain, or subdomain is created. Placeholders are always named "index.html" and reside in the respective document root. Content is generated from a Blade file, which allows for customization prior to rendering of the placeholder.
Copy /usr/local/apnscp/resources/templates/apache/placeholder.blade.php to /usr/local/apnscp/config/custom/resources/templates/apache/placeholder.blade.php creating parent directories as needed. index.html may not be updated once written.
All suspended accounts via SuspendDomain redirect to /var/www/html/suspend.html. A suspension page is not provided by default in ApisCP but may be created by the admin. Suspension rules may be modified by adjusting the rewrite rules.
Copy /usr/local/apnscp/resources/templates/apache/suspend-rules.blade.php to /usr/local/apnscp/config/custom/resources/templates/apache/suspend-rules.blade.php creating parent directories as needed.
A site once suspended will compile these rules into /etc/httpd/conf/siteXX/00-suspend. Rules will not be updated unless suspended again. admin:collect() provides a convenient way to do this.
yum install -y jq
cpcmd -o json admin:collect '[]' '[active:false]' | jq -r 'keys[]' | while read -r SITE ; do SuspendDomain $SITE ; done
Customization file: /etc/httpd/conf.d/evasive.conf or httpd-custom.conf
Alternatively consider the apache.evasive Scope, which provides error checking.
Customization file: /etc/httpd/modsecurity.d/ or httpd-custom.conf
Customization file: /etc/httpd/conf.d/pagespeed.conf or httpd-custom.conf
Customization file: /usr/local/apnscp/config/custom/*
ApisCP supports overriding views, apps, modules, and configuration. Modification is covered in detail in PROGRAMMING.md.
::: tip ApisCP was originally called APNSCP. Internally, in many places, the panel is still referred to as APNSCP. ApisCP is a bit easier to pronounce. :::
All views may be copied into config/custom/resources/views/<path> from resources/views/<path>. Custom views take precedence, including all mail templates. Overriding layout.blade.php allows customization to the skeleton of all apps in ApisCP.
::: warning Updating configuration first time
ApisCP compiles configuration on each start to provide the best possible performance. When creating resource overrides in config/custom/resources/view or config/custom/resources/templates the first time restart ApisCP so it knows to look in these directories. Prior to making this change, these locations are compiled out on boot.
systemctl restart apiscp
:::
A master layout named "layout" is provided in resources/views/. As with all templates suffixed "blade.php", it utilizes Blade. A theme-specific blade may override the master layout by creating an eponymous template in config/custom/resources/views/. For example, to override the "apnscp" theme, create a file named config/custom/resources/views/apnscp.blade.php. Inheritance is supported via @extends("layout") in addition to section injection.
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 ApisCP 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'
);Apps populated as part of ApisCP may be hidden or removed from view using hide() and remove() respectively. Application ID is the basename from the URI path, i.e. for /apps/foo the application ID is "foo" and likewise "quuz" is the application ID for /apps/quuz.
config/custom/templates/admin.php:
<?php
// remove Nexus app from admin
$templateClass->getApplicationFromId('nexus')->remove();
// allow Dashboard access, but remove from side menu
$templateClass->getApplicationFromId('dashboard')->hide();
// remove "foo" app. Note if this does not exist it is a no-op
$templateClass->getApplicationFromId('foo')->hide();
// alternatively to check if "foo" exists
if ($templateClass->getApplicationFromId('foo')->exists()) {
// do something
}New in 3.2.18
When working with custom configurations, it may be desired to reset all menu items. clear() empties all menu and statistics.
<?php
$templateClass->clear();
// create a DNS-only layout
$templateClass->create_link(
'Dashboard',
'/apps/dashboard',
true,
null,
''
);::: warning Dashboard required
/apps/dashboard must be a valid URI in all menus as this serves as the destination after login.
:::
New in 3.2.18
Per-plan menus may be used following the naming scheme ROLE-PLAN. For example, to use a custom menu layout for the plan "dns-only" that applies to Site Administrators, create the following file config/custom/templates/site-dns-only.php. If found, this menu will be used instead of config/custom/templates/site.php.
Plan-specific menus behave otherwise the same as a custom menu. To clear all menu items use clear().
<?php
$templateClass->clear();
// create a DNS-only layout
$templateClass->create_link(
'Dashboard',
'/apps/dashboard',
true,
null,
''
);
$templateClass->create_link(
'DNS Manager',
'/apps/dns',
true,
null,
''
);Any app that uses Blade templates (views/ directory) is eligible to override components of the template structure. Create the same structure in config/custom/apps/<name> as is in apps/<name>. For example to override apps/ssl/views/partials/certificate-detected.blade.php, copy that file to config/custom/apps/ssl/views/partials/certificate-detected.blade.php. ApisCP will load the view from this location first. It is advisable to copy the entire application over (App overrides) as application structure may change between releases.
Web Apps use a different set of locations for overrides. An app may be overrode by cloning the git repository into config/custom/ (see README.md bundled with each Web App) or by copying the respective file into config/custom/webapps/APP-NAME/views. For example, to override the options-install.blade.php template bundled with WordPress, the path would be config/custom/webapps/wordpress/views/options-install.blade.php.
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'],
];DNS is generated from a base template in resources/templates/dns. Presently mail and dns templates are supported. For each template to override copy the respective template to config/custom/resources/templates/dns/. Validate DNS template consistency via cpcmd dns:validate-template TEMPLATENAME.
New themes may be created and placed under public/css/themes and public/images/themes. The default theme may be changed with cpcmd:
cpcmd scope:set cp.config style theme newthemePer theme layouts may be set following the layout override mentioned above.
Grunt is used to build themes from the SDK. Some Sass knowledge is recommended. Bootstrap is also helpful to know but simple enough to learn as you go along. ApisCP is presently based on Bootstrap 4.0.
git clone https://github.com/apisnetworks/apnscp-bootstrap-sdk
pushd apnscp-bootstrap-sdk
npm install -D
env THEME=apnscp grunt watchNow changes may be made to the "apnscp" theme in scss/themes/apnscp. It will also be necessary to put either the panel in debug mode using the cp.debug scope or by flagging the session as debug. Session is encoded in the browser session as session.id. Use this value with misc:debug-session to selectively enable debugging for this session:
# Enable debugging on session LETceXuAZ9p1MW0yPd7n1b3Btk9t9Weh
env DEBUG=1 misc:debug-session LETceXuAZ9p1MW0yPd7n1b3Btk9t9WehIt's recommended to create a new theme by copying one of the existing themes. Default theme may be changed using cpcmd scope:set cp.config style theme NEWTHEME. Likewise run env THEME=NEWTHEME grunt to build a minified release of the theme prior to shipment. Debug sessions source non-minified assets.
All configuration must be made to config/custom/config.ini. cpcmd provides a short-hand tool to edit this file.
# Show all configuration
cpcmd scope:get cp.config
# Set configuration
cpcmd scope:set cp.config core fast_init trueRefer to config.ini that ships with ApisCP for a list of configurables.
All changes may be made to /usr/local/apnscp/config/httpd-custom.conf. After changing, restart ApisCP, systemctl restart apiscp
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
Customization file: /etc/fail2ban/.local, /etc/fail2ban/jail.d
Any file in fail2ban may be overridden with a corresponding .local file. It takes the same name as the source file, except it ends in .local.
See also
- MANUAL 0.8 (fail2ban.org) - covers configuration/override in detail
Customization file: /etc/haproxy/conf.d/*
Customization file: /etc/my.cnf.d/*
Additionally, configuration may be overrode in Bootstrapper using mysql_custom_config. These values are set in /etc/my.cnf.d/apnscp.cnf and may be substituted in lieu of a higher order override.
Create a special variable named mysql_custom_config in /root/apnscp-vars-runtime.yml. This is a dict that accepts any number of MySQL server directives that takes precedence.
Sample
mysql_custom_config:
# Disable max_join_size protection
max_join_size: -1Then run upcp -sb mysql/install to update configuration.
Customization file: /var/www/html/phpMyAdmin/config.local.inc.php
Create this customization file if it does not already exist.
<?php
// set custom configuration here
?>
Customization file: /etc/postfix/main.cf, /etc/postfix/master.d
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: 15postfix_custom_master_config works similarly to postfix_custom_config except it is a string applied to /etc/postfix/master.cf. Additionally, per-site configurations, such as transports, may be added in /etc/postfix/master.d. Configuration must end in .cf. Any file prefixed with siteXX- is considered affiliated with the designated site and will be removed on site deletion.
Do not assume these templates will be capable of Jinja templating in Ansible. Instead, the template must be statically generated at account creation/edit.
Sample
# Add SPF checking service, note this is for illustrative purposes and
# largely obviated by SpamAssassin and rspamd spam filters
postfix_custom_master_config: |-
policyd-spf unix - n n - 0 spawn
user=policyd-spf argv=/usr/bin/policyd-spf
Sample
# In /etc/postfix/master.d/site12.cf
# Add a custom smtp transport
mydomain.com-out unix - - n - - smtp
-o smtp_helo_name=mydomain.com
-o smtp_bind_address=64.22.68.2
Then to merge changes for both examples, run upcp -sb mail/configure-postfix.
Customization file: /var/lib/pgsql/<ver number>
Customization file: /etc/phpXX.d/*
ApisCP 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.
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: 20rspamd 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.
Customization file: /etc/mail/spamassassin/local.cf
Customization file: /etc/ssh/sshd_config
sshd_config may be modified. Do not edit the directives within # BEGIN ApisCP MANAGED BLOCK and # END ApisCP MANAGED BLOCK. Port and public key authentication may be modified with Scopes,
# Enable ssh daemon ports 22 and 58712
cpcmd config:set system.sshd-port '[58712,22]'
# Disallow password-based logins, public key only
cpcmd config:set system.sshd-pubkey-only true