Add 'docs/' from commit '29d15352'

git-subtree-dir: docs
git-subtree-mainline: 7fcc8f03
git-subtree-split: 29d15352

docs/.gitignore

+DS_Store
+.idea
+.vuepress/dist

docs/.vuepress/config.js

+module.exports = {
+  plugins: [
+    '@vuepress/active-header-links',
+    '@vuepress/back-to-top',
+    [
+      '@vuepress/pwa', {
+        serviceWorker: true,
+        updatePopup: true
+      }
+    ],
+    'alias',
+    [
+      'vuepress-plugin-clean-urls', {
+        normalSuffix: '/',
+        indexSuffix: '/',
+        notFoundPath: '/404.html',
+      }
+    ],
+    '@vuepress/medium-zoom'
+  ],
+  markdown: {
+    extendMarkdown: md => {
+      md.use(require('markdown-it-deflist'))
+    }
+  },
+  patterns: [
+    '*.md',
+    'admin/**/*.vue',
+    'admin/**/*.md'
+  ],
+  // config for Service Worker
+  serviceWorker: {
+    updatePopup: {
+      message: "New content is available.",
+      buttonText: "Refresh"
+    }
+  },
+  redirectionMapping: {
+    "GLOSSARY": "glossary"
+  },
+  title: "ApisCP Documentation",
+  description: "ApisCP · modern hosting platform",
+  head: [
+    [
+      "link",
+      {
+        rel: "stylesheet",
+        href: "https://fonts.googleapis.com/icon?family=Material+Icons"
+      }
+    ],
+    [
+      "link",
+      {
+        rel: "icon",
+        href: "/favicon.ico"
+      }
+    ],
+  ],
+  themeConfig: {
+    logo: 'https://apiscp.com/images/logo-inv.svg',
+    // lastUpdated: 'Last updated',
+    repo: 'https://github.com/apisnetworks/apnscp-docs',
+    docsDir: "",
+    editLinks: true,
+    editLinkText: 'Help us improve this article!',
+    nav: [
+      {
+        text: "Home",
+        link: "/"
+      },
+      {
+        text: "Getting Started",
+        link: "/install"
+      },
+      {
+        text: "Administration",
+        link: "/admin/CLI"
+      },
+      {
+        text: "Customizing",
+        link: "/admin/Customizing"
+      },
+      {
+        text: "Learn More",
+        items: [
+          {
+            text: "Changelog",
+            link: "https://gitlab.com/apisnetworks/apnscp/-/commits/master"
+          },
+          {
+            text: "Buy Now",
+            link: "https://my.apiscp.com"
+          }
+        ]
+      }
+    ],
+    sidebarDepth: 1,
+    sidebar: {
+      "/": [
+        {
+          title: "Preface",
+          collapsable: true,
+          children: [
+            "CONVENTIONS",
+            "SECURITY",
+            "admin/Mass hosting"
+          ]
+        },
+        {
+          title: "Getting Started",
+          collapsable: false,
+          children: [
+            "INSTALL",
+            "UPGRADING",
+            "LICENSE",
+            "FIREWALL",
+
+          ]
+        },
+        {
+          title: "Administration",
+          collapsable: false,
+          children: [
+            "admin/CLI",
+            "admin/Scopes",
+
+            "admin/Plans",
+            "admin/Backups",
+
+            "admin/Migrations",
+
+            "admin/Filesystem",
+
+            "admin/DNS",
+            "admin/NAT",
+
+            "admin/SSL",
+            "admin/Monitoring",
+
+            "admin/Smtp",
+            "admin/LDA",
+            "admin/Filtering",
+
+            "admin/Evasive",
+            "admin/PHP-FPM",
+
+            "admin/Webapps",
+            "admin/Fortification",
+
+            "admin/Troubleshooting",
+
+            "admin/Maps",
+            "DEBUGGING",
+          ]
+        },
+        {
+          title: "Extending",
+          collapsable: true,
+          children: [
+            "admin/Customizing",
+            "admin/Billing integration",
+            "admin/Hooks",
+            "PROGRAMMING"
+          ]
+        },
+        {
+          title: "Appendix",
+          collapsible: true,
+          children: [
+            "AUTHORS",
+            "admin/Tuneables",
+            "admin/Scopes-list",
+            "RELEASE-3.1",
+            "GLOSSARY"
+          ]
+        }
+      ]
+    }
+  }
+};

docs/.vuepress/styles/index.styl

+img.logo {
+  background: radial-gradient(#118975, #1ba791);
+  border-radius: 5px;
+}
+
+header.navbar {
+  background: #f0f5f4;
+  .links {
+    background: transparent;
+  }
+}
+
+

docs/AUTHORS.md

+---
+title: Authors
+alias: authors
+---
+
+apnscp is comprised of several components. Any component under vendor/ is 
+copyright the respective author. All software that is modified under GPL 
+is available under https://github.com/apisnetworks.
+
+Code under different locations has different licenses:
+- lib/modules
+  * Artistic 2.0
+- lib/HTTP
+  * BSD
+- lib/Util/Process
+  * MIT
+- resources/playbooks
+  * MIT 
+- build/bootstrap/apnscp-bootstrap-jdk
+  * MIT
+- build/bootstrap/apnscp-bootstrap-sdk
+  * MIT
+- apnscp root 
+  * apnscp Proprietary License (refer to LICENSE)
+  
+
+All unlicensed content is assumed to be licensed under apnscp's proprietary license unless specified.

docs/CONVENTIONS.md

+# Conventions
+
+Multiple components of ApisCP are referenced with different markup.
+
+* *[section]* => *option*: config.ini settings
+* *Class\Subclass*: typically in changelogs, provides visibility of at least two levels corresponding to class
+* *group*.*name*: configuration [scopes](docs/Scopes.md)
+* *service*,*value*: service configuration (e.g. siteinfo,email)
+* *role*/*subrole*: [Bootstrapper](https://github.com/apisnetworks/apnscp-playbooks) tasks, correspond to `roles/` directory
+* *module*: typically in changelogs (italicized outside), module name (`lib/modules`)
+* *Word Word*: applications within ApisCP's front-end (`apps/`, see `lib/Template/` for name => directory mapping)
+* *siteXX*: site identifier. See [DEBUGGING.md](DEBUGGING.md) for information on determining this value
+* *siteXX/path* (also *siteXX/fst/path*): refers to account root in /home/virtual/siteXX/fst/*path*
+* *siteXX/shadow/path*: similar to account root, but refers to data-only layer in /home/virtual/siteXX/shadow/*path*
+* *siteXX/info/path*: account metadata location, refers to /home/virtual/siteXX/info/*path*

docs/DEBUGGING.md

+# Debugging
+
+ApisCP may emit debugging information when **debug mode** is enabled. You can enable debugging on a per-request basis, or globally using *cp.debug* [Scope](admin/Scopes.md). Backtraces (code pathways) can be enabled by setting *[core]* => *debug_backtrace_qualifier*. Backtraces give context around how an error occurred, making them invaluable for debugging.
+
+`cpcmd scope:set cp.debug true` enables debugging mode globally. 
+
+`cpcmd scope:set cp.config core debug_backtrace_qualifier -1` enables backtraces for all reporting classes (fatal, error, warning. info, deprecated, and debug) as well as exceptions. Increasing verbosity levels inherit lower levels. **Backtraces are mandatory** when reporting issues.
+
+The following table is only relevant when panel debugging is enabled.
+
+| Level | Features                                   |
+| ----- | ------------------------------------------ |
+| 0     | Disabled, no backtraces                    |
+| 1     | Errors - error()                           |
+| 2     | Warnings - warn()                          |
+| 3     | Informative remarks - info()               |
+| 4     | Deprecated - deprecated_fn(), deprecated() |
+| -1    | All  above classes + debug()               |
+
+![UI Visibility](./images/debugging-ex-visibility.png)
+
+`env DEBUG=1 cpcmd common:whoami` executes the [whoami](https://api.apiscp.com/class-Common_Module.html#_whoami) method in common module. This method simply returns the current username. A special module [test](https://api.apiscp.com/class-Test_Module.html) is available in debug mode to facilitate development. Only this request operates in debug mode ensuring appropriate isolation in a production environment. 
+
+```bash
+# env DEBUG=1 cpcmd test:benchmark common_whoami
+benchmark common_whoami
+time: 0.01 sec (1000 rounds; 0.0051 ms each; 195429.32 per second)
+
+0.0051169395446777
+
+# env DEBUG=0 cpcmd test:benchmark common_whoami
+ERROR   : test_benchmark: command does not exist
+----------------------------------------
+MESSAGE SUMMARY
+Reporter level: ERROR
+----------------------------------------
+ERROR: test_benchmark: command does not exist
+```
+
+When in debug mode, housekeeping and cron services are disabled as well as job runner. Housekeeping/cron tasks may not be invoked traditionally. Job runner invocation is covered under [Jobs](#jobs).
+
+## Targeted frontend debug
+`misc:debug-session(string $id, bool $mode = true)` enables debugging for a frontend session (DAV, UI, SOAP). Session identifier may be retrieved from a browser session by accessing the `session.id` property. `session.debug` encodes whether debug mode is enabled.
+
+```bash
+# Enable debugging for active session aE2...JL9r in browser
+env DEBUG=1 cpcmd misc:debug-session aE2uNGVkvpathoXqhofnsKDDXGNBJL9r true
+```
+
+## Log locations
+
+ApisCP logs messages in a few places. Respective services use their preferred logging locations. This table summarizes common services and their log locations. 
+
+All locations are within /var/log unless noted. siteXX is shorthand for /home/virtual/siteXX/fst/. siteXX is the site ID identifier that can be resolved using `get_site_id domain.com`. "..." following siteXX is short-hand for /var/log thus *siteXX ... log* indicates /home/virtual/siteXX/fst/var/log/log. CP_ROOT is the panel home, typically either /usr/local/apnscp or /usr/local/apiscp. Words fully capitalized are symbolic.
+
+| Service                   | Location                   | Remarks                                                      |
+| ------------------------- | -------------------------- | ------------------------------------------------------------ |
+| Apache                    | httpd/error_log            | HTTP startup                                                 |
+| Apache per-site           | siteXX ... httpd/error_log | Per-site error logs, FPM connectivity                        |
+| PHP-FPM                   | siteXX ... php-fpm/POOL    | Per-site PHP errors, notices                                 |
+| Mail (**all** excl. auth) | maillog                    | SMTP prefixed "postfix". IMAP/POP3 "dovecot". Local delivery "maildrop". Excludes authentication. |
+| Mail auth | secure             | Rejections from invalid passwords via PAM |
+| FTP                       | vsftpd.log                 |                                                              |
+| MySQL                     | /var/lib/mysql/mysqld.log  |                                                              |
+| PostgreSQL                | /var/lib/pgsql/X/data/log/ | Circular buffer by day-of-week. X is version major, 11, 10, etc. |
+| SSH                       | secure                     | SSH login attempts, successes                                |
+| crond                     | cron                       | Periodic services via Dev > Task Scheduler and /etc/cron.d   |
+| fail2ban (Rampart) | fail2ban.log | "Found" is log match. "Unban" automatic expiry. |
+| ApisCP frontend | CP_ROOT/storage/logs/error_log | Same logging as Apache |
+| ApisCP backend | CP_ROOT/storage/logs/start.log | Errors originating from backend |
+| Passenger (launcher) | /.socket/passenger/logs | Launcher issues for Python, Ruby, and Node apps |
+| Passenger (app) | APPROOT/log | Per-application messages. APPROOT is one directory down from document root. |
+
+### Automated email reporting
+
+ApisCP can be configured to forward a copy of unhandled errors (PHP notices/errors and exceptions) to an email address. Set [core] => bug_report in config.ini. This should be used by developers only, as it generates false positives that are encountered during typical operation.
+
+```bash
+cpcmd scope:set cp.config core bug_report email+bugs@domain.com
+```
+
+Given the volume generated, plus-address notation or a separate email address is recommended to facilitate mail filtering by your SMTP provider.
+
+## Backend
+
+You can start the backend broker from the command-line in the foreground. It handles elevation requests from the frontend via the [query()](PROGRAMMING.md#invocation-flow) function in the API.
+
+To enable debugging, run:
+
+```bash
+systemctl stop apiscp
+cd /usr/local/apnscp/bin
+env DEBUG=1 ./apnscpd -f restart
+```
+When debugging is active, the following tasks are disabled: cron, housekeeping, jobs.
+
+## PHP-FPM status
+
+FPM pools are grouped by site ID identifier and name. By default, one pool is created named after the primary domain. `php:pools()` lists active pools for a site. 
+
+`php:pool-status(string $pool = '')` provides the internal PHP-FPM pool status as reported by systemd's notify feature. These values are real-time metrics as seen by the pool manager.
+
+`php:pool-info(string $pool = '')` reports service information from systemd. This command is equivalent to *systemctl show POOLNAME*. *StatusText* is the plaintext value of php:pool-status.
+
+## Jobs
+
+Laravel Horizon is used for jobs unless `has_low_memory` is enabled (via Bootstrapping or *[cron]* => *low_memory* is set in config.ini). Horizon can be manually launched using:
+
+`./artisan horizon`
+
+`misc:get-job-queue()` reports the pending work queue. Pending jobs may be processed using `./artisan queue:work`. An optional flag, --once, processes these jobs singularly.
+
+```bash
+# Disable job runner, housekeeping, and cron to prevent jobs from starting
+cpcmd scope:set cp.debug true
+systemctl restart apiscp
+
+# Validate the queue is empty
+cpcmd misc:get-job-queue
+# Jobify a command
+cpcmd misc:jobify 'common_whoami'
+# Validate the queue has 1 job
+cpcmd misc:get-job-queue
+# Run first job in queue, enable verbose output
+./artisan queue:work --once -vvv
+# Validate queue is now empty
+cpcmd misc:get-job-queue
+```
+
+*Jobs are unavailable when the panel is in debug mode unless Horizon has been manually started.*
+
+## Web App installation
+
+Web Apps engaged through the UI are dispatched to a job runner, and may also be installed using API commands. Each app maps to a module named after itself, and follows a common interface:
+
+`NAME:install(string $hostname, string $path = '', array $options = [])`
+
+| Web App   | Module    |
+| --------- | --------- |
+| Discourse | discourse |
+| Drupal    | drupal    |
+| Ghost     | ghost     |
+| Joomla!   | joomla    |
+| Laravel   | laravel   |
+| Magento   | magento   |
+| NextCloud | nextcloud |
+| WordPress | wordpress |
+
+Applications support both generalized options and specific options. The following are common options found in Web > Web Apps:
+
+| Name       | Type   | Remarks                   |
+| ---------- | ------ | ------------------------- |
+| version    | string | Version number            |
+| ssl        | bool   | Enable SSL                |
+| user       | string | Optional username of      |
+| autoupdate | bool   | Enable automatic updates  |
+
+*Jobs are unavailable when the panel is in debug mode unless Horizon has been manually started.*
+
+## Command listing
+`misc:list-commands(string $filter = '')` is a role-aware helper that displays available commands. Used in conjunction with [cpcmd](admin/CLI.md#cpcmd), it provides a convenient interface to filter available commands.
+
+```bash
+# Show commands available to Appliance Administrator ("admin" username)
+cpcmd misc:list-commands
+# Show commands available to site1 Site Administrator
+cpcmd -d site1 misc:list-commands
+# Show commands available to site1 in the "ghost" module
+cpcmd -d site1 misc:list-commands 'ghost:*'
+# "l" is an alias and equivalent to the above command
+cpcmd -d site1 misc:l 'ghost:*'
+```
+
+### Introspection
+`misc:command-info(string $filter = '')` provides verbose information about the command, including its method signature and documentation. This can be used to explain what parameters an API command anticipates. Method usage is similar to `list-commands`:
+
+```bash
+# Show signature for ghost:install as Site Administrator
+cpcmd -d site1 misc:command-info ghost:install
+# Show command signature for all commands in "admin" module
+cpcmd misc:command-info 'admin:*'
+# "i" is an alias and equivalent ot the above command
+cpcmd misc:i 'admin:*'
+```
+
+## User preferences
+Preferences are stored in siteXX/info/USER. `common:load-preferences()` is a convenient interface to show these preferences. 
+
+`common:get-user-preferences(string $user)` allows for a Site Administrator access to a user's preferences. 
+
+`YAML_INLINE` is an environment variable that controls array folding depth. Increasing folding depth improves readability. The default value is *2*.
+
+```bash
+# Show Appliance Administrator's preferences
+cpcmd common:load-preferences
+# Show preferences for site1's Site Administrator
+cpcmd -d site1 common:load-preferences
+# Show preferences for user "foobar" on site1
+cpcmd -d site1 -u foobar common:load-preferences
+# The following command is equivalent
+cpcmd -d site1 common:get-user-preferences foobar
+# Use YAML_INLINE=n to expand collapsed fields
+env YAML_INLINE=4 cpcmd -d site1 common:load-preferences
+```
+
+`common:purge-preferences()` will purge the active user's preferences. This may be useful to gauge API interaction or to reset a role to a clean state. `purge-preferences` may only be invoked in debug mode.
+
+```bash
+# Get current user preferences
+cpcmd common:load-preferences
+# Purge all preferences
+env DEBUG=1 cpcmd common:purge-preferences
+# Preferences for active role is now empty
+cpcmd common:load-preferences
+```
+
+## Connecting to Redis 
+
+Redis manages caching and job queues over a UNIX domain socket. Database 1 is assigned to ApisCP, 2 to jobs, and 3 to rspamd (if utilized), with a decreasing priority assigned to each. Do not issue the `FLUSHALL` command as this will purge rspamd logical replication from PostgreSQL.
+
+```bash
+redis-cli -s /usr/local/apnscp/storage/run/redis.sock
+# Show memory usage
+info memory
+# Show stored keys
+keys *
+```
+
+## API bypasses
+
+You may bypass API permissions by using a surrogate module. This allows for rapid prototyping of individual API methods which may otherwise be restricted. Surrogates are covered in detail in [PROGRAMMING.md](PROGRAMMING.md).
+```bash
+<?php declare(strict_types=1);
+
+	class Dns_Module_Surrogate extends Dns_Module {
+		public function __construct() {
+			parent::__construct();
+			// ensure we always win permissions
+			$this->exportedFunctions = ['*' => PRIVILEGE_ALL];
+		}
+		
+		public function t() {
+			return $this->_cron();
+		}
+	} 
+```
+
+You can now interact with the _cron method from the command-line instead of being restricted by API accessibility rules.
+
+```bash
+env DEBUG=1 cpcmd dns:t
+```
+
+Be careful with this approach. All cross-module calls inherit the current role. This means that you may try calling an API method intended for PRIVILEGE_SITE, as PRIVILEGE_ADMIN. Unless permissions are overwritten with a surrogate, cross-module violations are still blocked.

docs/FIREWALL.md

+# Firewall
+
+ApisCP utilizes [firewalld](https://firewalld.org/) for its firewall. Rampart is a module that serves as a wrapper for [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page), a brute-force deterrent that blocks threats through firewalld. These two components act in tandem to keep your server secure while exercising some intelligence. Rampart is for ephemeral blocks that automatically expire after a fixed duration (see [network/setup-firewall](https://github.com/apisnetworks/apnscp-playbooks/tree/master/roles/network/setup-firewall)) whereas a separate firewalld permanent whitelist/blacklist is provided.
+
+During installation, ApisCP will detect the connected IP address and whitelist it to avoid triggering a block by fail2ban, for example if you forget your password multiple times. If your IP address changes or you setup ApisCP from behind a proxy, then you can easily update the whitelist with `cpcmd`
+
+```bash
+cpcmd scope:set rampart.whitelist
+```
+
+To view active whitelists use [scope:get](https://api.apiscp.com/class-Config_Module.html#_get):
+
+```bash
+cpcmd scope:get rampart.whitelist
+```
+
+Whitelists may be IP address (64.22.68.1) or CIDR hosts (64.22.68.1/24). rampart.whitelist is an append-only operations. Edit /etc/fail2ban/jail.conf by hand to remove old IP addresses.
+
+## Whitelisting access
+
+ApisCP restricts access to all ports except for well-known services (HTTP, FTP, mail, SSH) and optional services (CP, user daemons). A second whitelist, which allows access to blocked ports as well as overrides Rampart can be set using `cpcmd rampart:whitelist`:
+
+```bash
+cpcmd rampart:whitelist 192.168.0.1/24
+```
+
+These entries are permanent.
+
+## Blacklisting
+
+Likewise a blacklist exists to block addresses that are not blocked by Rampart's adaptive firewall. 
+
+```bash
+cpcmd rampart:blacklist 192.168.0.10
+```
+
+Blacklists are lower priority than whitelist and Rampart blocks.
+
+## Unbanning IP addresses
+
+All IP addresses automatically unban from Rampart after a fixed duration. To manually unban an address from Rampart use cpcmd:
+
+```bash
+# Ban 192.168.0.4 in recidive, which is a long-term ban > 1 week
+cpcmd rampart:ban 192.168.0.4 recidive
+# Validate which jails 192.168.0.4 is present in
+cpcmd rampart:is-banned 192.168.0.4
+# Unban 192.168.0.4 from all jails
+cpcmd rampart:unban 192.168.0.4
+```
+
+Permanent blacklist and whitelist entries can be removed with firewall-cmd
+
+```bash
+# Add 192.168.0.4 to the permanent whitelist
+cpcmd rampart:whitelist 192.168.0.4
+# Show all whitelist entries
+ipset list whitelist
+# Remove 192.168.0.4 from whitelist
+cpcmd rampart:whitelist 192.168.0.4 remove
+```
+

docs/GLOSSARY.md

+---
+title: Glossary
+alias: glossary
+---
+
+[Account metadata]
+: *Metadata* about an account that resides in *siteXX/info*. Examples of metadata include the primary domain, admin username, bandwidth allotment
+
+{:#Bandwidth}
+: Amount of transfer (inbound and outbound) that an account registers over a period. Bandwidth is in bytes unless a *unit* prefix is specified.
+
+{:#Billing invoice}
+: an identifier that relates an account or set of accounts to a common billing entity. Billing invoices are stored in billing,invoice account metadata.
+
+{:#Byte}
+: An indivisible unit comprised of 8 bits.
+
+{:#Command-line}
+: Direct server access accessed over terminal. SSH and embedded terminal (KVM) are used to access this mode.
+
+{:#Metadata}
+: data about data. A common example of this is account metadata that lives in siteXX/info for each account.
+
+{:#siteXX}
+: An expression that refers to /home/virtual/siteXX where siteXX is the *site identifier* of an account.
+
+{:#Site identifier}
+: internal marker for sites, which is defined on account creation. Site identifier index begins at 1 and the next largest value is assigned. Site identifiers do not change unless the account is deleted, then recreated. Examples: site12, site1, site999999999. Site identifiers may be determined by domain using `get_site_id domain.com` from the command-line.
+
+{:#Site ID identifier}