ApisCP provides a variety of command-line helpers that allow you to interact with your accounts. For example, you may want to put the panel in headless mode (opens new window), which disables web-based access, automate account management, or even too run a command as another site.
All helpers live under /usr/local/apnscp/bin. All commands except for cpcmd must be run as root. sudo su - is a quick way to become root if you aren't already.
TIP
*Domain binaries: AddDomain, EditDomain, DeleteDomain, ActivateDomain, and SuspendDomain are covered in Plans.md. ImportDomain and ExportDomain are covered in Migrations.md. This document covers other helpers.
# cpcmd
cpcmd is the single most important command in your arsenal. As root, it allows you to run a command within any authentication context – any. Need to add a domain to mysite.com named blog-site.com?
cpcmd -d mysite.com aliases_add_domain blog-site.com /var/www/blog-site.com
cpcmd -d mysite.com aliases_synchronize_changes
DETAILS
This adds a new domain named blog-site.com with the document root /var/www/blog-site.com, then updates the web server configuration. Alternatively, aliases_remove_domain blog-site.com would remove the domain from the account.
Now let's configure Let's Encrypt for the addon domain and install Wordpress.
cpcmd -d mysite.com letsencrypt_append blog-site.com
cpcmd -d mysite.com wordpress_install blog-site.com
And that's it!
What about removing a vacation auto-responder for a secondary user named sam?
cpcmd -d mysite.com -u sam email_remove_vacation
That's it!
Let's collect a web app inventory as the server admin of a new site, mydomain.com, then update them as necessary:
cpcmd admin_locate_webapps 'mydomain.com'
cpcmd admin_update_webapps '[site:mydomain.com]'
Any command in the panel has a corresponding API (opens new window) method. Quite simply, whatever you can do in the panel you can do too from the command-line or afar with Beacon (opens new window).
# Alternate invocation
Commands may also be written in a clear form separating the module from the function by a colon and replacing function underscores ("_") with hypens ("-"). The above admin command thus becomes:
cpcmd admin:locate-webapps 'mydomain.com'
# Listing all commands
misc:list-commands(string $filter = '') lists commands available to the current role. "filter" is any glob-style patern. For example, to see all admin commands available to the admin:
misc:list-commands "admin:*"
To see all commands containing "pass" for the Site Administrator of site1,
misc:list-commands "*pass*"
Both cpcmd misc:l and cpcmd -l are shorthand usage for this command.
# Introspecting commands
misc:info(string $filter = '') displays command information including its signature, documentation, return type, and parameter documentation. It behaves similarly to misc:list-commands.
misc:i is shorthand for this usage.
# Arbitrary execution/interactive mode
cpcmd -r creates an execution context after ApisCP has been loaded. It may be used to interact with panel state as a one-liner.
# Load Laravel configuration, get contents from config/laravel/mail.php
cpcmd -r '$app = app("config"); var_dump($app["mail"]);'
cpcmd --interactive is similar to one-liner mode (-r), but launches an interactive shell. State is not maintained in between invocations.
cpcmd --interactive
# now in shell
var_dump(app('config')['mail']);
echo $c->commom_whoami(), "\n";
$i = 0;
# This will not work...
echo ++$i;
# Input/output types
cpcmd uses a custom parser for input and displays output in Yaml or as a string depending upon return type complexity. Both features may be controlled using -i and -o flags respectively. Each accepts a transform format.
# Input formats
| Type | Example |
|---|---|
| cli | [foo:bar] |
| json | {"foo":"bar"} |
| serialize | a:1:{s:3:"foo";s:3:"bar";} |
TIP
serialize is useful when working with objects. Variable types will not be lost on ingestion. json is the fastest format. cli is a simple representation for complex data types.
# Output formats
| Type | Example |
|---|---|
| cli | [foo:bar] |
| json | {"foo":"bar"} |
| serialize | a:1:{s:3:"foo";s:3:"bar";} |
| yaml | foo: bar |
| var_dump | array(1) { ["foo"]=> string(3) "bar" } |
Array ( [foo] => bar ) |
TIP
When working with serialized output in a shell pipeline, wrap output in xargs -d otherwise quotes will be lost while evaluating arguments in bash.
cpcmd -o serialize common:whoami | xargs -d$'\n' env DEBUG=1 cpcmd -i serialize test:backend-collector
# get_config
Get service metadata from site identifier (domain, site id, site).
# Example
get_config domain.com siteinfo email
# get_site
Get site name from domain or site id. Same as "site" + get_site_id
# get_site_id
Get internal site ID from domain or site. Returns 1 on failure otherwise 0.
# Example
get_site_id example.com
[[ $? -ne 0 ]] && echo "example.com doesn't exist"
# Scripts
All ApisCP scripts are available under /usr/local/apnscp/bin/scripts. All scripts make use of the ApisCP CLI framework and require invocation with apnscp_php to operate.
# backup_dbs.php
Perform bulk database backups. This can be manually invoked before a system backup to ensure a fresh export of databases.
# ban_spam.sh
Blocks any IP addresses with more than 100 open connections to a server.
# changelogparser.php
Summarize ApisCP changes from git log.
# change_dns.php
Bulk change DNS for an account. IPs may be changed for a single domain by specifying -d DOMAIN or for all accounts for which DNS is enabled by specifying --all.
cd /usr/local/apnscp/bin/scripts
# Reduce TTL for all domains to 15 seconds
./change_dns.php --all --ttl=15
# For all IPs that match "site:ip-address" change the IP to 45.12.23.4
./change_dns.php -d site1 --new=45.12.23.4
# Command above is equivalent to...
./change_dns.php -d site1 --old="$(cpcmd -d site1 site:ip-address)"--new=45.12.23.4
# Change IP address for all sites that match old IP address 1.2.3.4. If changed, set a TTL value of 2 hours
./change_dns.php --all --old=1.2.3.4 --new=3.4.5.6 --ttl=7200
This is a simpler version of bulk DNS boilerplate.
# mapCheck.php
Map helper.
# metricscron.php
Metrics compression/rollover helper.
# platformScrub.php
Wrapper for monthly invocation of upcp -sb.
# reissueAllCertificates.php
Perform a bulk reissue of all certificates. See SSL.md for further information.
# storagelog.sh
Periodic storage logging.
# transfersite.php
Migrate an ApisCP site between servers. See [Migrations](Migrations - server.md) for further information.
# uidCheck.php
Similar to mapCheck.php, scans a system for inconsistencies in UID/GID attached to accounts.
# yum-post.php
Synchronize packages into FST.
# Build scripts
# build/php/php.config
Build PHP for ApisCP. To run, change into PHP source directory, then run:
/usr/local/apnscp/build/php/php.config
PHP will be built with ApisCP module requirements.
# build/httpd/apxs
General utility apxs wrapper to build modules specifically for ApisCP. Installed modules will be placed under sys/httpd/private/modules. Unless the module conflicts with global Apache instance, modules can be used from sys/httpd/modules, which is a symlink to /usr/lib64/httpd/modules.