Skip to content

Latest commit

 

History

History
194 lines (126 loc) · 6.49 KB

CLI.md

File metadata and controls

194 lines (126 loc) · 6.49 KB
Raw
title
Helpers

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

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*"

misc:l is shorthand for this usage.

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 {{ $themeConfig.APNSCP_ROOT }}/bin/scripts. All scripts make use of the apnscp CLI framework and require invocation with apnscp_php to operate.

change_dns.php

Bulk change DNS for an account.

changelogparser.php

Summarize apnscp changes.

reissueAllCertificates.php

Perform a bulk reissue of all certificates. See SSL.md for further information.

transfersite.php

Migrate an ApisCP site between servers. See [Migrations](Migrations - server.md) for further information.

yum-post.php

Synchronize a system back into FST.

Build scripts

build/php/php.config

Build PHP for apnscp. To run, change into PHP source directory, then run:

{{ $themeConfig.APNSCP_ROOT }}/build/php/php.config

PHP will be built with apnscp module requirements.

build/httpd/apxs

General utility apxs wrapper to build modules specifically for apnscp. 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.