Using the InterWorx CLI Utility

The InterWorx Control Panel offers a command-line utility, which allows server administrators and SiteWorx users the ability to perform InterWorx functions without having to log in to the web interface.

This utility can also be used to perform automated batch operations via shell scripts.

Contents

• Using the InterWorx CLI Utility

  • Overview of the InterWorx CLI Utility

  • Installing the InterWorx CLI Utility

  • Authentication

    • Credential-based Authentication

    • Unix User-Based Authentication

      • Access as the Root User

      • Access as a SiteWorx User

  • Using the CLI Utility in Interactive Mode

  • Using the CLI Utility in Non-Interactive Mode

Overview of the InterWorx CLI Utility

The CLI Utility is comprised of two commands: nodeworx and siteworx

• The nodeworx command is used to complete administrator and reseller functions that would normally be performed from the NodeWorx control panel

• The siteworx command is used to complete SiteWorx user functions on specific SiteWorx accounts that would normally be performed from the SiteWorx control panel

For example, the nodeworx command would be used to add a new reseller. Adding a new e-mail alias for a SiteWorx user would be accomplished by using the siteworx command.

Installing the InterWorx CLI Utility

The InterWorx CLI Utility is installed automatically as part of the InterWorx installation script.

However, if the utility happens to be uninstalled for some reason, it can easily be reinstalled from the CLI.

1. Log in to the server at the CLI as root, either via SSH or from the terminal

2. Run the following yum command:

   yum install interworx-cli
   

Authentication

Authentication is required to use the InterWorx CLI Utility. This can be achieved either by providing an NodeWorx or SiteWorx user’s email and password, or by authenticating based on the unix user.

Credential-based Authentication

1. Log in to the server at the CLI, either via SSH or from the terminal

2. Use the nodeworx command to access the NodeWorx utility, or siteworx to access the SiteWorx utility

3. Provide the email and password when prompted

   • The NodeWorx utility can only be accessed by the root user

   • If accessing the SiteWorx utility, there will also be a prompt to provide the domain

   [root@server ~]# nodeworx
   +--------------------------------------------------------------------+
   | NodeWorx Login |
   +--------------------------------------------------------------------+
   E-mail : admin@server.com
   Password [] :
   

   [root@server ~]# siteworx
   +--------------------------------------------------------------------+
   | SiteWorx Login |
   +--------------------------------------------------------------------+
   E-mail : client@siteworx-example.com
   Password [] :
   Domain : siteworx-example.com
   

Unix User-Based Authentication

It is also possible to authenticate based on the Unix user.

The root user may log into both the NodeWorx and SiteWorx utilities without requiring a password. SiteWorx users with shell access may only access the SiteWorx utility.

Note

It is recommended to use this method when writing shell scripts for automated NodeWorx and SiteWorx actions, as it bypasses the authentication prompt.

Access as the Root User

1. Log in to the server at the CLI as root, either via SSH or from the terminal

2. To access to the NodeWorx CLI Utility as the master NodeWorx user, use the nodeworx command with the -u flag

   [root@server ~]# nodeworx -u
   

3. To access the SiteWorx CLI Utility, use the siteworx command, with the -u flag. Specify the SiteWorx account to access with --login-domain

   [root@server ~]# siteworx -u --login_domain siteworx-example.com
   

Access as a SiteWorx User

1. Log in to the server at the CLI vis SSH as the SiteWorx unixuser

2. Use the siteworx command, with the -u flag

   [siteworx@server ~]$ siteworx -u
   

Using the CLI Utility in Interactive Mode

The CLI Utility provides the ability to browse and navigate the NodeWorx or SiteWorx menu via interactive prompts.

When accessing the utility, it will first present a list of Controllers. Each Controller is a section of InterWorx. The Controllers are exactly the same as the menu items in the NodeWorx or SiteWorx web interfaces, depending on which version of the CLI Utility is being accessed.

Note

This example will demonstrate how to suspend a SiteWorx account using the NodeWorx CLI Utility in Interactive Mode.

1. Log in to the server at the CLI as root, either via SSH or from the terminal

2. Using the command nodeworx -u, access the NodeWorx CLI

3. From the list of Controllers, choose the number that corresponds with SiteWorx: Accounts

   • In this example, the prompt number is 9. However, this may vary depending on what plugins may or may not be enabled in NodeWorx, which would add different menu items to the Controller list than seen, here

   [root@server ~]# nodeworx -u
   +--------------------------------------------------------------------+
   | Additional input is required |
   +--------------------------------------------------------------------+
   (1) Login / Logout
   (2) NodeWorx Home
   (3) NodeWorx: User Accounts
   (4) NodeWorx: Languages
   (5) NodeWorx: API Key
   (6) NodeWorx: Plugins
   (7) NodeWorx: Authentication
   (8) NodeWorx: Subscriptions
   (9) SiteWorx: Accounts
   (10) SiteWorx: Shell Users
   (11) SiteWorx: Packages
   (12) SiteWorx: Backup / Restore
   (13) SiteWorx: Import
   (14) Softaculous
   (15) Resellers: Accounts
   (16) Resellers: Packages
   (17) Resellers: Bandwidth History
   (18) System Services: Web Server
   (19) System Services: FTP Server
   (20) System Services: SSH Server
   (21) Mail Server: MTA Settings
   (22) Mail Server: SMTP Settings
   (23) Mail Server: SMTP2 Settings
   (24) Mail Server: Outbound SMTP Settings
   (25) Mail Server: MDA Settings
   (26) Mail Server: MSA Settings
   (27) Mail Server: Dovecot Settings
   (28) Mail Server: Spam Filtering
   (29) Mail Server: Virus Filtering
   (30) Mail Server: Mail Queue
   (31) MySQL Server: Overview
   (32) MySQL Server: Remote Servers
   (33) MySQL Server: PhpMyAdmin
   (34) DNS Server: Overview
   (35) DNS Server: Zones
   (36) DNS Server: Records
   (37) DNS Server: Synchronization
   (38) NFS Server: Overview
   (39) NFS Server: Exports
   (40) NFS Server: Mounts
   (41) Server: System Health
   (42) Server: Cron
   (43) Server: Firewall
   (44) Server: SSL Certificates
   (45) Server: Logs
   (46) Server: Settings
   (47) Server: Software Updates
   (48) Server: System Graphs
   (49) IP Management: System IPs
   (50) IP Management: IPv6 Pools
   (51) IP Management: Default Sites
   (52) Clustering: Setup
   (53) Remote Assistance
   Controller [none] :
   

4. The next menu is a list of Actions. Choose the number that corresponds with suspend

   • In this example, that number is 20, though, again, this may vary between servers

   Controller [none] : 9
   +--------------------------------------------------------------------+
   |                          Choose an Action                          |
   +--------------------------------------------------------------------+
   (1) queryDomain * Query the system for a domain information.
   (2) matchPackagesWithTemplates * Find existing package template names and match account packages to them.
   (3) listAccounts * List Siteworx accounts summary.
   (4) listDomainAccounts * List Siteworx accounts including master and secondary domain details.
   (5) queryDomainAccountDetails * Query domain account details.
   (6) search * Search siteworx accounts summary.
   (7) toggleFavorite * Toggle a "favorite" SiteWorx account.
   (8) siteworxLogin * Login to a given SiteWorx account.
   (9) deleteAccountOnNode * Delete a SiteWorx Account on this Cluster Node.
   (10) delete * Delete a SiteWorx Account.
   (11) setConfig * Set SiteWorx Level Config Data.
   (12) setDomainConfig * Set Domain Level Config Data.
   (13) deleteConfig * Delete SiteWorx Level Config Data.
   (14) deleteDomainConfig * Delete Domain Level Config Data.
   (15) queryConfig * Query SiteWorx Level Config Data.
   (16) queryDomainConfig * Query Domain Level Config Data.
   (17) listConfig * List all SiteWorx Level Config Data.
   (18) listDomainConfig * List all Domain Level Config Data.
   (19) add * Add a SiteWorx account.
   (20) suspend * Suspend a SiteWorx account.
   (21) unsuspend * Unsuspend a SiteWorx account.
   (22) suspendByUser * Suspend a SiteWorx account by unix user name.
   (23) unsuspendByUser * Unsuspend a SiteWorx account by unix user name.
   (24) ips * Displays IP information for a siteworx account.
   (25) addIp * Adds an IP to the list of available IPs for a SiteWorx account.
   (26) queryAvailableIps * Displays Ips that are available to a master siteworx account.
   (27) removeIp * Removes IPs from SiteWorx account.
   (28) editDomainIp * Edit the ip for a single domain.
   (29) changePhpVersion * Change the PHP version for the entire SiteWorx account, including all domains.
   (30) edit * Edit a SiteWorx account.
   (31) listMasterDomains * List master domains.
   (32) listFreeIps * List available ip addresses.
   (33) listDedicatedFreeIps * List available dedicated ip addresses.
   (34) listSharedFreeIps * List available shared ip addresses.
   (35) queryDomainInfo * Get info about a domain on the system. Can be used to see if a domain exists.
   (36) querySiteworxAccountDetails * Get all SiteWorx account properties of a given domain.
   (37) listBandwidthAndStorage * Lists bandwidth and storage usage for current billing period in megabytes.
   (38) listBandwidthAndStorageInMB * Lists bandwidth and storage usage for current billing period in megabytes.
   (39) listSiteworxAccounts * List SiteWorx accounts (id, status, domain).
   (40) querySiteworxAccounts * Query Siteworx accounts by specifying which properties you want returned.
   (41) syncVirtualHosts * Synchronize InterWorx and Apache vitrual host blocks.
   (42) syncServerAlias * Synchronize server aliases with InterWorx database.
   (43) listCurrentDomainBandwidthData * List bw data for all master and secondary domains for the active biling period.
   (44) queryAccountBandwidth * Query Siteworx Account bandwidth usage data for any billing period.
   (45) bulkdeactivate * Bulk deactivate SiteWorx accounts.
   (46) bulkactivate * Bulk activate SiteWorx Accounts.
   (47) queryIps * Displays the information available to the action "ips".
   (48) queryEdit * Displays the information available to the action "edit".
   (49) reroute * Action to re-route from the current controller to a different one.
   (50) win * Magic function - test for testing success mechanism.
   (51) fail * Magic function - test for failure mechanism.
   Action [none] :
   

5. From the list of domains, choose the domain to suspend

   • In this example, mywebsite.com will be suspended

   Action [none] : 20
   +--------------------------------------------------------------------+
   |                    Additional input is required                    |
   +--------------------------------------------------------------------+
   (1) iwtest.com
   (2) mywebsite.com
   (3) example.com
   (4) domain.com
   Domain [none] :
   

6. After selecting the domain to suspend, press [Enter] to launch the text editor to add a message describing the reason the account is suspended

7. Save and quit the text editor

   • The utility outputs the message that was added, and then automatically prompts for confirmation

8. Type yes and press [Enter] to confirm suspending the account

   Domain [none] : 2
   +--------------------------------------------------------------------+
   |                              Suspend                               |
   +--------------------------------------------------------------------+
   
   Confirm suspending of the following
   
   Domain : mywebsite.com
   Message : Press [Enter] to launch editor
   "/tmp/iw_cli_input_vsXpSF/message" 1L, 33C written
   Account suspended for nonpayment
   Suspend? [] : yes
   [root@server ~]#
   

Using the CLI Utility in Non-Interactive Mode

The InterWorx CLI Utility may be used in Non-Interactive mode, as well. This bypasses the menu prompts and provides the ability to specify the Controllers and Actions directly. This is especially useful when creating shell scripts to automate certain tasks.

Non-interactive InterWorx CLI commands must include a Controller, an Action, and any specific Arguments that are required to complete the task:

# Nodeworx
nodeworx [-u] [-v] [-n | -i] [-h] [ -c CONTROLLER ] [ -a ACTION ] [ARGUMENTS ]

# Siteworx
siteworx [-u] [--login_domain DOMAIN] [-v] [-n | -i] [-h] [ -c CONTROLLER ] [ -a ACTION ] [ ARGUMENTS ]

A simple way to identify the proper Controller, Action, and Arguments, is to access the CLI utility with the -h flag. This provides a list of options for each variable in the command.

Note

This example will demonstrate how to unsuspend a SiteWorx account using the NodeWorx CLU Utility in Non-interactive mode.

1. Log in to the server at the CLI as root, either via SSH or from the terminal

2. Using the command nodeworx -u -h, access the NodeWorx CLI

   [root@server ~]# nodeworx -u -h
   Usage: nodeworx.php [ options ]
   --help|-h                Display this help and exit
   --session-id <string>    Session ID for continuing a session
   --user-auth|-u           Authenticate by unixuser
   --interactive|-i         Render in interactive mode with a session
   --non-interactive|-n     Render in non-interactive mode for programming
   --verbose|-v             Outputs more verbose information in non-interactive mode
   --output-style|-o <word> default|json|pretty|yaml - default=tab delimited, json=compact json, pretty=human readable json, yaml=yaml
   --controller <string>    Index|Overview|Users|Lang|Apikey|Plugins|Twofactorauth|Notice|Siteworx|Shell|Packages|Backup|Import|Softaculous|Reseller|ResellerPackages|ResellerBandwidthhistory|Http|Ftp|Sshd|MailMta|MailSmtp|MailSmtp2|MailSend|MailMda|MailMsa|MailDovecot|MailSpam|MailVirus|MailQueue|Mysql|MysqlRemote|MysqlPhpmyadmin|Dns|DnsZone|DnsRecord|DnsSync|Nfs|NfsExport|NfsMount|Health|Cron|Firewall|Ssl|Logs|Settings|Updates|Rrd|Ip|Ipv6|IpSites|Cluster|Help
   [root@server ~]#
   

3. Identify the Controller that corresponds with the desired task. In this case, that is the SiteWorx Controller

4. Use the nodeworx -u -h command again, this time, adding -c Siteworx. This provides a list of potential Actions

   [root@server ~]# nodeworx -u -h -c Siteworx
   action : This input is required
   Usage: nodeworx.php Siteworx [ options ]
   --help|-h                Display this help and exit
   --session-id <string>    Session ID for continuing a session
   --user-auth|-u           Authenticate by unixuser
   --interactive|-i         Render in interactive mode with a session
   --non-interactive|-n     Render in non-interactive mode for programming
   --verbose|-v             Outputs more verbose information in non-interactive mode
   --output-style|-o <word> default|json|pretty|yaml - default=tab delimited, json=compact json, pretty=human readable json, yaml=yaml
   --controller <string>    Index|Overview|Users|Lang|Apikey|Plugins|Twofactorauth|Notice|Siteworx|Shell|Packages|Backup|Import|Softaculous|Reseller|ResellerPackages|ResellerBandwidthhistory|Http|Ftp|Sshd|MailMta|MailSmtp|MailSmtp2|MailSend|MailMda|MailMsa|MailDovecot|MailSpam|MailVirus|MailQueue|Mysql|MysqlRemote|MysqlPhpmyadmin|Dns|DnsZone|DnsRecord|DnsSync|Nfs|NfsExport|NfsMount|Health|Cron|Firewall|Ssl|Logs|Settings|Updates|Rrd|Ip|Ipv6|IpSites|Cluster|Help
   --action <string>        queryDomain|matchPackagesWithTemplates|listAccounts|listDomainAccounts|queryDomainAccountDetails|search|toggleFavorite|siteworxLogin|deleteAccountOnNode|delete|setConfig|setDomainConfig|deleteConfig|deleteDomainConfig|queryConfig|queryDomainConfig|listConfig|listDomainConfig|add|suspend|unsuspend|suspendByUser|unsuspendByUser|ips|addIp|queryAvailableIps|removeIp|editDomainIp|changePhpVersion|edit|listMasterDomains|listFreeIps|listDedicatedFreeIps|listSharedFreeIps|queryDomainInfo|querySiteworxAccountDetails|listBandwidthAndStorage|listBandwidthAndStorageInMB|listSiteworxAccounts|querySiteworxAccounts|syncVirtualHosts|syncServerAlias|listCurrentDomainBandwidthData|queryAccountBandwidth|bulkdeactivate|bulkactivate|queryIps|queryEdit|reroute|win|fail
   [root@server ~]#
   

5. Identify the required Action. In this case, that is the unsuspend Action

6. Use nodeworx -u -h -c Siteworx command, again, this time adding -a unsuspend. This provides a list of Arguments

   [root@server ~]# nodeworx -u -h -c Siteworx -a unsuspend
   Usage: nodeworx.php Siteworx unsuspend [ options ]
   --help|-h                Display this help and exit
   --session-id <string>    Session ID for continuing a session
   --user-auth|-u           Authenticate by unixuser
   --interactive|-i         Render in interactive mode with a session
   --non-interactive|-n     Render in non-interactive mode for programming
   --verbose|-v             Outputs more verbose information in non-interactive mode
   --output-style|-o <word> default|json|pretty|yaml - default=tab delimited, json=compact json, pretty=human readable json, yaml=yaml
   --domain <string>        iwtest.com|mywebsite.com|example.com|domain.com
   [root@server ~]#
   

7. Identify the required Arguments. In this case, all that is needed is to specify the domain to unsuspend with the --domain Argument

8. Run the full command, adding the --domain Argument, specifying the desired domain

   • As help items are no longer needed, do not use the -h flag

   • Add -n option to specify that the command should be run without any added prompting

   • This silently, non-interactively, unsuspends the specified SiteWorx account

   [root@server ~]# nodeworx -u -c Siteworx -a unsuspend --domain mywebsite.com -n
   [root@server ~]#
   

Note

It is also possible to identify the command to perform an action automatically by adding the -v flag when accessing the CLI Utility in interactive mode. After following all of the prompts, the full, non-interactive mode command that was run will be provided as the final output.

For example, adding the -v flag when accessing the NodeWorx utility to suspend an account, after following all of the prompts, the full command is provided, which can be used as a basis for further scripting:

[root@server ~]# nodeworx -u -v

{Controllers and Actions Removed}

Domain [none] : 2
+--------------------------------------------------------------------+
|                              Suspend                               |
+--------------------------------------------------------------------+

Confirm suspending of the following

Domain : mywebsite.com
Message : Press [Enter] to launch editor
"/tmp/iw_cli_input_CTxmUD/message" 1L, 33C written
Account suspended for nonpayment
Suspend? [] : yes

Success
Command executed: nodeworx -u -n -c Siteworx -a suspend --message Account suspended for nonpayment --domain mywebsite.com

[root@server ~]#