How to: Activate InterWorx Control Panel License

Warning

Activating an InterWorx license, either via the web browser or the command line, can only be attempted once on a server. It is highly recommended to take a snapshot of the server before attempting to activate the license.

If there is an error when activating the license, the server can be reverted to the snapshot. Otherwise, starting over completely from a fresh OS install would be required.

Prerequisites

Note

Running the InterWorx license activation script within a Linux screen session is recommended. Screen creates a shell session that continues to stay active, even if there is network disruption. Detailed information on using screen can be found here.

To determine whether screen is installed on the system, run which screen. If screen is installed, the system will return /usr/bin/screen

If screen is not already installed, it can be installed by running yum install screen

To install InterWorx from within a screen session, type the word screen  at the command line. Then, run the InterWorx installation command.

If the session disconnects, log back in at the command line and typescreen -r. This will reconnect the screen session.

License Activation Script Overview

The license activation script performs the following tasks:

  1. Validates the license

  2. Syncs the license to the primary IP of the server

  3. Sets up PHP-CGI

  4. Sets up the internal InterWorx databases. These include internal databases for InterWorx, Horde, Roundcube, Spamassassin, FTP, and Vpopmail. The internal InterWorx databases are a completely independent MySQL instance from the system and user MySQL databases

  5. Sets the server hostname in InterWorx

  6. Writes the file /home/interworx/iworx.ini. This is the main configuration and settings file for InterWorx

  7. Prompts for the master NodeWorx user email and password. These are the login credentials for the master NodeWorx user. These credentials to not have to be the same as the ones for portal.interworx.com

  8. Sets up Vpopmail

  9. Sets up the DNS resolves for the IPs on the server

  10. Syncs the server IPs with NodeWorx

  11. Sets up default vhost information

  12. Creates the internal InterWorx cron jobs. More information on what the InterWorx cronjobs do can be found here

  13. Sets up Simscan

  14. Sets up the InterWorx firewall

  15. Changes the PHP mode to PHP-FPM

    • This task can take up to 15 minutes. The script appearing to hang during this task is expected

  16. Sets up the default Apache MPM

  17. Runs an initial InterWorx Fively cron

Activating the License from the CLI

Warning

Some VPS providers, such as Vultr, are changing the permissions of /etc/resolv.conf so that it no longer has write permissions, and it is immutable, so those permissions cannot be easily changed.

This may cause the activation script to hang, or stop after writing the iworx.ini, as checking the permissions on /etc/resolv.conf to make sure it is writable, and fixing those permissions if it is not, is part of that process.

If using Vultr, or another VPS service, it may be required to run the following commands before running the activation script:

chattr -i /etc/resolv.conf
chmod 644 /etc/resolv.conf

Interactive Activation

Using the interactive activation script, users will be prompted to submit the InterWorx License Key, as well as the email and password to be used for the master NodeWorx account.

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

  2. Run the goiworx.pex script:

    root@server# cd /usr/local/interworx/bin
root@server# ./goiworx.pex

  3. When prompted, enter the InterWorx License Key:

    +----------------------------------------------------------------------+
| Go! InterWorx |
+----------------------------------------------------------------------+
+----------------------------------------------------------------------+
| License Key Setup |
+----------------------------------------------------------------------+
 Please enter license key: INTERWORX_XXXXXXXXXX
 You entered 'INTERWORX_XXXXXXXXXX'.

  4. When prompted, enter the email and password to be used for the master NodeWorx user. This is the administrator account for the InterWorx Control Panel

    Note

    This email and password do not have to be the same as the login credentials for portal.interworx.com. These credentials are specifically what will be used to log into NodeWorx.

    It is also strongly recommended to set the master NodeWorx user password to something other than the root password of the server.

    +----------------------------------------------------------------------+
| Default NodeWorx User Setup |
+----------------------------------------------------------------------+
e-mail address: admin@yourbox.com
password: your-password
confirm : your-password

  5. Once the goiworx scripts ends, login to NodeWorx by navigating to https://[ip.ad.re.ss]:2443/nodeworx/, using the e-mail address and password set up in the previous step

Scripted Activation

The activation script can also be run in non-interactive mode.

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

  2. Run the goiworx.pex script with the following parameters:

~iworx/bin/goiworx.pex --key=LICENSE_KEY --email=EMAIL --password=PASSWORD --ignorechecks

Note

Make sure the above is all one line. Replace LICENSE_KEY, EMAIL, and PASSWORD with the corresponding information

Activating From the Browser

Warning

Some VPS providers, such as Vultr, are changing the permissions of /etc/resolv.conf so that it no longer has write permissions, and it is immutable, so those permissions cannot be easily changed.

This may cause the activation script to hang, or stop after writing the iworx.ini, as checking the permissions on /etc/resolv.conf to make sure it is writable, and fixing those permissions if it is not, is part of that process.

If using Vultr, or another VPS service, it may be required to run the following commands before activating from the browser:

chattr -i /etc/resolv.conf
chmod 644 /etc/resolv.conf

  1. Access NodeWorx from the browser by navigateing to https://ip.ad.dr.ess:2443/nodeworx

  2. Follow the prompts for the license key and an initial e-mail and password for the master NodeWorx user

    Note

    This email and password do not have to be the same as the login credentials for portal.interworx.com. These credentials are specifically what will be used to log into NodeWorx.

    It is also strongly recommended to set the master NodeWorx user password to something other than the root password of the server.

Troubleshooting

Activating Hangs or Stops after Writing iworx.ini

Some VPS providers, such as Vultr, are changing the permissions of /etc/resolv.conf so that it no longer has write permissions, and it is immutable, so those permissions cannot be easily changed.

This may cause the activation script to hang, or stop after writing the iworx.ini, as checking the permissions on /etc/resolv.conf to make sure it is writable, and fixing those permissions if it is not, is part of that process.

As the activation script can only be run once on the server, if this issue occurs, reverting to a prior snapshot, or wiping the the server, and re-installing InterWorx will be required.

Then run the following, before running the activation script:

chattr -i /etc/resolv.conf
chmod 644 /etc/resolv.conf

License Activation Errors

  • If license activation errors occur:

    • Make sure that the server time is correct

    • Make sure that license.interworx.com is resolvable and pingable from the server

  • When moving a license key from one server to another, the IP of the license key must be reset in the billing portal

    • Instructions on how to change the binding IP for an InterWorx License Key can be found here

  • Verify that port 2443 is open both out and inbound to the server