Working with CLI helpers

apnscp 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, 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.

AddDomain

AddDomain creates a site from command-line. Multiple parameters can be provided to alter the services assigned to an account. Nexus within the Administrative panel is a frontend for this utility. admin_add_site is the backend API call for this command-line utility.

Basic usage

AddDomain -c siteinfo,domain=mydomain.com -c siteinfo,admin_user=myadmin

Creates a new domain named mydomain.com with an administrative user myadmin. The email address defaults to blackhole@apnscp.com and password is randomly generated.

Let's alter this and set an email address, which is used to contact the account owner whenever a Web App is updated or when the password is changed. Let's also prompt for a password. But first let's delete mydomain.com because domains must be unique per server.

DeleteDomain mydomain.com
AddDomain -c siteinfo,domain=mydomain.com -c siteinfo,admin_user=myadmin -c siteinfo,email=hello@apisnetworks.com -c auth,passwd=1

apnscp will prompt for a password and require confirmation. Email address will be set to hello@apisnetworks.com.

Tweaking services

apnscp includes a variety of services that can be enabled for an account. Some services must be enabled whereas others can be optionally enabled. Let's create an account that allows up to 2 additional users, disables MySQL, disables email, disables shell access, and disables addon domains. A single-user domain with limited access that may only upload files.

AddDomain -c siteinfo,domain=securedomain.com -c siteinfo,admin_user=secureuser -c users,enabled=0 -c users,max=3 -c mysql,enabled=0 -c mail,enabled=0 -c ssh,enabled=0 -c aliases,enabled=0

EditDomain

EditDomain is a helper to change account state without removing it. You can toggle services and make changes in-place in a non-destructive manner.

Rename domain

A simple, common situation is to alter the primary domain of an account. Simply changing the domain attribute under the siteinfo service will accomplish this.

EditDomain -c siteinfo,domain=newdomain.com mydomain.com

Changing password

Changing the password is another common operation:

EditDomain -c auth,tpasswd=newpasswd site12

A new password is set in plain-text, "newpasswd". The third password alternative is cpasswd, which is a crypt()'d password. An optimal crypted password may be generated with auth_crypt. Alternatively, cpcmd auth_crypt newpasswd may be used to create the crypted password or To note, EditDomain accepts either the primary domain of an account, an aliased domain of an account (addon domain), or the site identifier. Aliases are discussed next.

Aliases

Aliases are domains for which the primary responds. Any alias also serves as a valid authentication mechanism in the user@domain login mechanism. Any alias without a defined document root will serve content from /var/www/html, which is the document root for the primary domain.

EditDomain -c aliases,aliases=['foobar.com'] mydomain.com

aliases,aliases is dangerous! It is not an append-only operation, meaning that whatever aliases value is is what is attached, nothing more and nothing less. A safer option is aliases_add_domain, aliases_remove_domain part of the API, which adds or removes domains in a singular process. This is part of cpcmd discussed later on.

Listing options

AddDomain -h will list all available services. These services map to resources/templates/plans/.skeleton/, which infer support data from lib/Opcenter/Service/Validators/<Service Name>/<Service Value>.php. Augmenting services will be discussed in a later post.

Creating plans

New plans may be created using artisan

cd /usr/local/apnscp
./artisan opcenter:plan --new custom
# Set custom as the default plan going forward
./artisan opcenter:plan --default
# Show all plans
./artisan opcenter:plan --list

These plans can be customized and assigned to an account using -p, AddDomain -p custom -c siteinfo,domain=mydomain.com

DeleteDomain

Domains may be deleted using DeleteDomain. DeleteDomain accepts a list of arguments that may be either the site identifier, domain, aliased domain, or invoice (billing,invoice OR billing,parent_invoice service value). Invoices allow you to quickly group multiple accounts. Invoices are discussed briefly below.

SuspendDomain

Domains may be deactivated from the command-line using SuspendDomain. It accepts a list of arguments, which may be the site identifier, domain, aliased domain, or invoice.

A suspended domain revokes access to all services, except panel, as well as page access. Panel access may be overridden by setting [auth] => suspended_login to true in config.ini.

ActivateDomain

Likewise a domain may be activated by using ActivateDomain, for example

ActivateDomain apnscp-XYZ123

Where apnscp-XYZ123 is a billing invoice assigned to the account via -c billing,invoice=apnscp-XYX123

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

Easy, huh? 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 method. Quite simply, whatever you can do in the panel you can do too from the command-line or afar with Beacon.