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" }
print 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.