Troubleshooting email in WHM

In this article we will go over the process used to investigate Email delivery issues on a WHM server. This can be helpful when a user is having issues receiving or sending Emails. The Mail Troubleshooter tool provided in WHM works by tracing the route an Email would take when sent to the provided Email address.

  1. With WHM opened in your browser, (a) type ‘Mail Troubleshooter’ into the search box. This will sort the menu options for you, (b) now find and click “Mail Troubleshooter”.
    troubleshoot-email-pt1
  2. Now on the Mail Troubleshooter page you should see a text box labeled as “Email to trace”. Enter the Email address you wish to trace here.
    troubleshoot-email-pt2
  3. Once you click Submit, you will be on the results page.
    troubleshoot-email-pt3

The example above shows a working configuration for a Gmail based email address. If the results show no errors the issue is likely related to improper Email client settings.
Below you will find an example of results showing errors, the issue here is that the domain has DNS problems and is not able to be resolved.

troubleshoot-email-pt4

EasyApache 4 & CLI based PHP utilities

With the release of EasyApache 4 in WHM 58 there are various changes to how PHP is managed. The most obvious being that EasyApache 4 brings support for installing multiple PHP versions alongside each other. However with multiple versions of PHP being installed on the server it’s easy to lose track of your command-line based PHP utilities and their PHP requirements.

Certain PHP packages like Composer, Drush, and WP-cli prefer to be run with the latest version of PHP. Unfortunately, having multiple PHP versions can mean not knowing which PHP will execute the utility when you call it directly. This article will detail a few methods to specify which PHP version should be used in instances like this.

Pre-flight Check:

  • These instructions are intended specifically for cPanel-based servers running WHM prior to version 58.
  • Command line access via SSH may be necessary to follow the examples.
  • The server will need to have EasyApache 4 active.
  • PHP 7 will be necessary to follow the provided examples.

Option #1: Directly Call the PHP Binary

The most basic option to workaround these issues is to directly call the PHP binary you need before executing the script. While this can be effective and will work as expected most of the time, certain utilities will not work when using this method.

You may want to attempt this method first and move on to Option #2 if this does not work as expected; generally though, this should work for executing basic PHP code.

/opt/cpanel/ea-php70/root/usr/bin/php someScript.php

The above command will specifically call the 7.0 version of PHP and will execute the someScript.php file within that version of PHP. If they are also installed on the server, the alternative PHP versions can be found at:

  • /opt/cpanel/ea-php55/root/usr/bin/php
  • /opt/cpanel/ea-php56/root/usr/bin/php
  • /opt/cpanel/ea-php70/root/usr/bin/php

Option #2: Use scl to Specify PHP Versions

As mentioned, certain PHP utilities are not provided as basic PHP files and are stored in the PHAR format. These utilities will not execute properly with the above method for specifying the PHP version. For these types of utilities you will need to specify the PHP version using a command called `scl`.

This command is a utility that allows running software in an environment packaged as a ‘Software Collection’. To be brief a ‘Software Collection’ is a way of defining an alternate location to a certain software. Fortunately, WHM provides predefined collections for the various versions of PHP supported by EasyApache 4.

The syntax of this command is as follows:

scl enable {SoftwareCollection} '{CommandToRun}'

Where you replace {SoftwareCollection} with the needed collection [ea-php55, ea-php56, or ea-php70], and you replace {CommandToRun} with the command, utility, or script you need to run.

A good way to highlight this is to review the difference in the following outputs:

root@noms [~]# php -v

PHP 5.6.25 (cli) (built: Aug 25 2016 17:00:38)
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
with the ionCube PHP Loader v4.7.5, Copyright (c) 2002-2014, by ionCube Ltd., and
with Zend Guard Loader v3.3, Copyright (c) 1998-2014, by Zend Technologies
with Zend OPcache v7.0.4-dev, Copyright (c) 1999-2015, by Zend Technologies

root@noms [~]# scl enable ea-php70 'php -v'

PHP 7.0.10 (cli) (built: Aug 25 2016 18:04:55) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
with Zend OPcache v7.0.10, Copyright (c) 1999-2016, by Zend Technologies

As you can see when calling PHP by itself we get the default version, but when using scl we explicitly called the PHP 7.0 collection and get results to match.

Example #1: Executing a utility [Composer]:

root@noms [~]# scl enable ea-php70 'composer --version'

Composer version 1.2.0 2016-07-19 01:28:52

Example #2: Running a PHP script:

root@noms [~]# scl enable ea-php70 './someScript.php'

With these key tips and tricks you should now be equipped with the necessary tools to run CLI utilities on a server using EasyApache 4. If you have any questions or are not comfortable making these changes yourself, please feel free to contact Heroic Support®.

How to Replace PHP GeoIP with MaxMindDB

Depending on the site or application, looking up geographic information related to an IP address can be a pretty common action. When doing IP geolocation in PHP usually the PHP GeoIP extension would be used to facilitate the retrieval of this information. Unfortunately, this particular plugin is no longer actively supported and has not been updated in a number of years.

With the go-to PHP extension of IP geolocation effectively being deprecated, new projects should begin to use the replacement options that are now provided by MaxMind. However, unlike the original GeoIP, which was shipped as a native PHP extension, the new solutions are provided as PHP-based library packages.

Pre-Flight Check

  • Basic familiarity with PHP coding is necessary to utilize Composer packages.
  • Command line access via SSH may be necessary to follow this tutorial.
  • Composer, Curl, funzip must be available on the server.

Step #1: What are my options now?

As mentioned previously, the new options are no longer provided as native PHP extensions, but rather they come as Composer-based PHP packages. The new options provided by MaxMind are either: GeoIP2-php or DB-Reader-php.

Both of the options provide the ability of IP geolocation with subtle differences; in a sense the GeoIP2-php package is an addition built on top of the DB-Reader-php package, it offers all the same features as DB-Reader-php with the addition of API access.

Additionally, it is important to note that only the DB-Reader option is provided without any additional costs. With the new options MaxMind now charges a subscription fee in order to access their APIs.

Generally for most use-cases the necessary features will be provided by the DB-Reader-php package, as such this article will focus on this option.

Step #2: Get started with MaxMind DB-Reader!

As mentioned in the pre-flight check, Composer will be required in order to follow these steps. If you do not have Composer setup on the server please feel free to review our Composer series here: ‘What is Composer?’.

To acquire the necessary DB-Reader package you will want to start by changing directory so that you are in the root folder of your domain (for this example we will just assume this is `public_html`), then you will run the following command:

[public_html] $ composer require maxmind-db/reader:~1.0

Running this command will download the package files into the current folder, as described in our Composer series. This will create a vendor folder if this is the first time using Composer in this site/project.

Next you will require the actual MaxMind database files which contain the geolocation data. To get these files you will execute the following commands:

[public_html] $ funzip <(curl -L http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.mmdb.gz) > ./GeoLite2-Country.mmdb
[public_html] $ funzip <(curl -L http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz) > ./GeoLite2-City.mmdb

With the above commands executed you should now have the necessary components to do Geolocation using the DB-Reader plugin. All that’s left is to implement it in your code.

Step #3: Looking up your first IP

In order to ensure the geolocation features are working properly you may want to do a quick test. First we’ll confirm you have all the right pieces by running the following command:

$ ls -lah

You should see a file structure similar to this:

-rw-rw-r-- 1 someuser someuser 63 Aug 11 17:03 composer.json
-rw-rw-r-- 1 someuser someuser 2.4K Aug 11 17:03 composer.lock
-rw-rw-r-- 1 someuser someuser 73M Aug 11 17:04 GeoLite2-City.mmdb
-rw-rw-r-- 1 someuser someuser 19M Aug 11 17:04 GeoLite2-Country.mmdb
drwxrwxr-x 4 someuser someuser 4.0K Aug 11 17:03 vendor/

Now you are ready to do a quick test, you can do so by creating an index.php file with the following content:

<?php
require_once 'vendor/autoload.php';

use MaxMind\Db\Reader;
$ipAddress = '8.8.8.8';
$databaseFile = './GeoLite2-City.mmdb';

$reader = new Reader($databaseFile);

print_r($reader->get($ipAddress));

$reader->close();

This index file will simply do a quick test to ensure that the database file is being loaded, an IP can be checked, and the results are being provided. The test will be looking up the geographic information related to Google’s DNS server at 8.8.8.8.

Geo-location results for Google's 8.8.8.8 DNS server via MaxMind
Geo-location results for Google’s 8.8.8.8 DNS server via MaxMind

Having followed the directions correctly you should see output similar to the image above when loading the test index page.

How to Disable MySQL Strict Mode

MySQL’s, and MariaDB’s, strict mode controls how invalid or missing values in data changing queries are handled; this includes INSERT, UPDATE, and CREATE TABLE statements. With MySQL strict mode enabled, which is the default state, invalid or missing data may cause warnings or errors when attempting to process the query.

When strict mode is disabled the same query would have its invalid, or missing, values adjusted and would produce a simple warning. This may seem like the preferred result, however with strict mode disabled certain actions may cause unexpected results; for instance, when the value being inserted exceeds the maximum character limit it will be truncated to fit the limit.

There are various reasons why MySQL’s strict mode may need to be disabled, however the most common is when a server is running WHMCS — this is a requirement of that tool.

Pre-Flight Check

  • These instructions are intended specifically for disabling MySQL strict mode on a managed Liquid Web server with cPanel.
  • The server should be running either MySQL 5.6/5.7 or MariaDB 10.x
  • Command line and root level access via SSH will be necessary to follow this tutorial.

Step #1: Make Backups, Always!

Whenever modifying files on a server it’s always best practice to take some form of a backup beforehand. This ensures you have a way to revert changes if something goes awry; it’s also beneficial because it helps track when and what changes were made.

While logged into SSH with the root user, do the following:

cp -a /usr/my.cnf{,.strict.bak}
cp -a /etc/my.cnf{,.strict.bak}

The above command uses ‘BASH brace expansion’ in order to make a backup copy of the file in its original directory.

Step #2: Disable MySQL Strict Mode

Depending on the server and the current configurations you may need to edit one, or both, of the following files on the server. Generally, the relevant configuration lines are only in one of them, however, it could be in either one without causing issues; so generally it’s best to check both.

To edit the files, you will open the file with your favorite command line editor. In this example, we use ‘vim’.

vim /usr/my.cnf
vim /etc/my.cnf

In vim, you can press “a” or “i” to enter text insertion mode; pressing the escape key (Esc) on your keyboard returns you to command mode. For a refresher on editing files with vim, see our New User Tutorial: Overview of the Vim Text Editor.

Within each file above you will be looking for a line with the following content:

sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES

If you find a line similar to the above that is setting the `sql_mode` variable then you will need to replace it with the following line to disable MySQL strict mode.

sql_mode=""

Once this adjustment has been made, or you’ve confirmed the file does not need to be adjusted you will then save and close the file.

Step #3: Restart the MySQL Service

Finally, to make these changes effective you will need to restart the MySQL service as it will only read the configuration files when it initially loads up. In order to force MySQL to use the new configuration files you will do the following:

For CentOS 7 servers:
systemctl restart mysql

For CentOS 6 and prior:
/etc/init.d/mysql restart

After issuing this command on the server the MySQL service will be restarted and will load the changes made. If all the directions were followed and completed, then MySQL strict mode should now be disabled.

To verify that the process was completed properly you can run the following:

mysql -e "SELECT @@sql_mode;"

The output may look similar to the following:

+--------------------------------------------+
| @@sql_mode
+--------------------------------------------+
| NO_AUTO_CREATE_USER
+--------------------------------------------+

If you have any questions or are not comfortable making these changes yourself, please feel free to contact Heroic Support®.

How To Modify an Existing Email Account in Thunderbird

How to Set up Email in Thunderbird
I. How To Set Up a New Email Account in Thunderbird
II. How To Modify an Existing Email Account in Thunderbird
III. How To Subscribe to IMAP Folders in Thunderbird

Pre-Flight Check

  • These instructions are intended specifically for setting up an email account in Mozilla Thunderbird 38.3.0 on Mac OS X 10.11.1.
  • While the steps should be similar across platforms and operating systems, they may not necessarily apply to older versions of Thunderbird.
  • For help with general email account settings, see How to Set up Any Email Client.

You can edit an email account that already has been configured in Thunderbird, for example should you decide to switch between non-SSL and SSL settings or change the server’s connection port. You change the connection type between standard (non-SSL) and secure (SSL) by changing the hostname and port for the incoming and outgoing servers.

Note: You cannot edit an existing email account to switch its account type from POP3 to IMAP or vice versa. To change the account type, you must add a new account of the desired type (POP3 or IMAP). Adding a new account with a different connection type should not require you to delete the old one in most mail clients.

To avoid data loss, please use caution any time you change an email account’s connection type or delete an email account. Removing an email account from a mail client also will remove all messages associated with it on the device and, specifically in the case of POP accounts that are not configured to retain mail on the server, there may be no way to recover those messages. If you have any doubt or questions, please feel free to contact Heroic Support® for guidance.

Step #1: Edit Incoming Server Settings

  1. To edit the incoming server, select your email address in the left pane and then click on View settings for this account in the main window.
  2. In the account settings window, click on Server Settings to update the Server Name and Port.incomingedit
    • Server Name
      • SSL settings will use the server’s hostname (e.g., host.yourdomainname.com)
      • Standard non-SSL settings will use the domain name (yourdomainname.com or mail.yourdomainname.com).
    • Port
      • SSL settings will use Port 993 for IMAP and Port 995 for POP3.
      • Standard non-SSL settings will use Port 143 for IMAP and Port 110 for POP3.

Step #2: Edit Outgoing Server Settings

  1. To edit the outgoing server settings, click on Outgoing Server (SMTP) in the left pane, select your outgoing server and click the Edit button.editoutgoing
  2. You can edit the server name and port in the popup window.out2
    • Server Name
      • SSL settings will use the server’s hostname (e.g., host.yourdomainname.com)
      • Standard non-SSL settings will use the domain name (yourdomainname.com or mail.yourdomainname.com).
    • Port
      • SSL settings will use Port 465.
      • Standard non-SSL settings will use Port 587 (depending on your server configuration, you may be able to use Port 25 as well).
  3. Click on the OK button to save the outgoing server settings, then click on OK once more to exit the settings menu and begin using your email account with the new settings.

 

How To Set Up a New Email Account in Thunderbird

How to Set up Email in Thunderbird

Pre-Flight Check

  • These instructions are intended specifically for setting up an email account in Mozilla Thunderbird 38.3.0 on Mac OS X 10.11.1.
  • While the steps should be similar across platforms and operating systems, they may not necessarily apply to older versions of Thunderbird.
  • For help with general email account settings, see How to Set up Any Email Client.

Step #1: Create the AccountCreate a new account in Thunderbird

  1. From Thunderbird’s main screen, select Email under the Create a new account section, or use the main menu to pull down to File -> New -> Existing Mail Account.
  2. On the window that pops up, select Skip this and use my existing email to proceed to the Mail Account Setup screen.
  3. Here you will enter some basic information about the account:
    • mailacctsetup1sYour name should be your name as you want it to appear in emails that you send.
    • Email address should simply be the email address you’re setting up.
    • Password is the email account’s password.
  4. Select Continue. Thunderbird now will attempt to discover the settings for your account automatically. If autoconfigure is not successful, you will need to configure the account manually.

Step #2: Set Account Type

manualconfig

  1. Select your account type, IMAP or POP3. For its ability to keep email in sync across multiple devices (desktop, laptop, phones and tablets), IMAP generally is recommended.
  2. Now click on the Manual config button to expand the settings window and set your connection type.

Step #3: Set Connection Method

  1. Fill out the Account Information fields using the instructions below as a guide.
  2. Click Done to complete the setup process.
  3. If you’re using standard (non-SSL) connection settings or are using secure (SSL) connection settings and have an SSL certificate installed on your mailserver, that’s all you’ll need to do set up the account. If you’re using SSL connection settings and are using the server’s self-signed SSL certificate, you will have one more step to complete.

newmailaccntsetup

Standard (non-SSL) settings

  • Server hostname column: Enter your domain name (e.g., mail.yourdomainname.com or yourdomainname.com) on both the Incoming and Outgoing rows.
  • Port column:
    • Incoming: For an IMAP connection, select “143”; For POP3, select “110”.
    • Outgoing: Select “25” or “587”
  • SSL column: Select “STARTTLS” on both the Incoming and Outgoing rows.
  • Authentication: This should be set to “Normal password” on both the Incoming and Outgoing rows.
  • Username: Your full email address, not just the part before the “@” symbol, on both the Incoming and Outgoing rows.
Note: If you accidentally set the SSL fields to “None”, you will see a warning popup notifying you of the security risks associated with foregoing any form of encryption. You should click on the Change Settings button to go back and change both SSL fields to “STARTTLS”, or configure a secure (SSL) connection.

Secure (SSL) Settings

  • Server hostname column: Enter your server’s hostname (e.g., host.yourdomainname.com) on both the Incoming and Outgoing rows.
  • Port column:
    • Incoming: For an IMAP connection, select “993”; For POP3, select “995”.
    • Outgoing (SMTP): Select “465”.
  • SSL: This should be set to “SSL/TLS” for both the Incoming and Outgoing rows.
  • Authentication: This should be set to “Normal password” on both the Incoming and Outgoing rows.
  • Username: This is your full email address, not just the part before the “@” symbol, for both the Incoming and Outgoing rows.

 

Step #4: Security Certificate

  1. ssl1If your server has a self-signed (free) SSL certificate installed on the mailserver and you attempt to make a secure connection using Thunderbird, you should see a warning in a popup window such as the one on the right.
  2. If that is the case, you will need to click the Confirm Security Exception button to accept the certificate and complete the setup process.
  3. If you choose, you also may check the box to Permanently store this exception so that you don’t need to continue to accept the certificate each time Thunderbird connects to your server.
Note: A self-signed certificate uses the same level of encryption as a verified certificate, except that it is you who are verifying your server’s identity, rather than a third party. However, if you would prefer to use a third-party verified SSL certificate to cover core services (cPanel/WHM, POP3, IMAP, SMTP and FTP) on your server, you can find instructions for ordering and installing an SSL certificate at Install an SSL certificate on a Domain using cPanel, and you’ll find a guide to installing your certificate on email and other core server services at Installing Service SSLs in cPanel. Should you find that you need any assistance, please feel free to contact a Heroic Support® technician who can assist with obtaining and installing an SSL from the vendor of your choice.

 

How to Subscribe to IMAP Folders in Thunderbird

How to Set up Email in Thunderbird

Pre-Flight Check

  • These instructions are intended specifically for setting up an email account in Mozilla Thunderbird 38.3.0 on Mac OS X 10.11.1.
  • While the steps should be similar across platforms and operating systems, they may not necessarily apply to older versions of Thunderbird.
  • For help with general email account settings, see How to Set up Any Email Client.

When connecting to your email server using the IMAP protocol, you have the ability to choose the specific mail folders to which you wish to subscribe.

Step #1: Open IMAP Folder Subscriptions

  1. Right-click on your email account’s Inbox in Thunderbird and then select Subscribe from the menu list.
    Subscribe to IMAP folders in Thunderbird
  2. In the Folder List window, you will see a list of all the email folders in your account on the server. Folders to which you already are subscribed will appear with a check mark.

Step #2: Manage IMAP Folder Subscriptions

  1. You can manage your folder subscriptions by clicking on the folder name in the Folder List window and then using the Subscribe or Unsubscribe buttons on the right.
    Subscribe or unsubscribe from the Thunderbird Folder List
  2. Once you’ve finished making changes, click the OK button. It may take a few moments for the folder list to update in your Mail pane.
Note: When subscribing to filtered mail folders such as Spam or Junk, all the mail coming into those folders on the server also will be downloaded and synced to your selected local mail client as well. If you are using a metered Internet connection or have limited bandwidth, please be aware that the transfer of email does count toward your data usage. If you typically receive a large volume of such filtered mail, subscribing to spam and junk folders is not recommended. Please feel free to contact Heroic Support® if you need assistance filtering unwanted incoming mail.

How To Set Up a New Email Account on an iPhone or iPad in iOS 9

How to Set up Email on an iPhone or iPad in iOS 9
I. How To Set Up a New Email Account on an iPhone or iPad in iOS 9
II. How To Modify an Existing Email Account on an iPhone or iPad in iOS 9

Pre-Flight Check

  • These instructions are intended specifically for setting up POP3/IMAP email on an iPhone or iPad running iOS 9.
  • If these instructions don’t quite work for you, check-out our tutorial How to Set up Any Email Client.

Step #1: Launch Settings

If you have re-arranged your home screen and Settings is not readily visible, you may swipe right and begin typing “Settings” into Spotlight to launch the app.

Step #2: Add the Email Account

iosadd1In the Settings app, navigate to Mail, Contacts, Calendars, and then click on Add Account.

Step #3: Select the Account Type

On the Add Account screen, select the last option, Other.

iosadd2

Step #4: Configure General Account Settings

iosadd3Fill out the requested information on the New Account screen and tap the Next button in the top-right corner of the screen once complete:

  • Name should be your name as you want it to appear in emails that you send.
  • Email should be your full email address.
  • Password is the email account’s password.
  • Description is the name you want displayed for the account in your Mail app

Step #5: Configure Advanced Account Settings

iosadd4The information from the previous screen will be pre-filled here, but you will need to fill in the rest now. Please note that, despite what the empty fields may suggest, none of the fields here are optional.

  • Account Type
    • Tap on IMAP or POP in the top field to select the account type.
    • Generally, IMAP is recommended on mobile devices due to its ability to keep email in sync across multiple devices (desktop, laptop, phones and tablets).
  • Incoming Mail Server
    • If you are using non-SSL settings, the Host Name will be mail.yourdomainname.com.
    • If you are using SSL settings, the Host Name will need to be set to the server’s hostname (host.yourdomainname.com).
  • User Name is your full email address.
  • Password is the email account’s password.
  • Outgoing Mail Server
    • If you are using non-SSL settings, the Host Name will be mail.yourdomainname.com.
    • If you are using SSL settings, the Host Name will need to be set to the server’s hostname (host.yourdomainname.com).
  • User Name is your full email address.
  • Password is the email account’s password.

If you chose POP as the account type, tap Save; If you chose IMAP, tap Next.

Accept SSL Certificate if Needed

  • iosssl2If you elected to use a non-SSL (standard) connection (using mail.yourdomainname.com instead of the server’s host name), you should a “Cannot Connect Using SSL” Alert Notification, and you will need to tap Yes to proceed with the account setup.
  • If you chose to use a secure (SSL) connection and your server has a self-signed (free) SSL certificate installed on the mail server, you will see a “Not Trusted” Alert Notification. You will need to tap on Trust in the upper-right corner to continue.
Note: A self-signed certificate uses the same level of encryption as a verified certificate, except that it is you who are verifying your server’s identity, rather than a third party. However, if you would prefer to use a third-party verified SSL certificate to cover core services (cPanel/WHM, POP3, IMAP, SMTP and FTP) on your server, you can find instructions for ordering and installing an SSL certificate at Install an SSL certificate on a Domain using cPanel, and you’ll find a guide to installing your certificate on email and other core server services at Installing Service SSLs in cPanel. Should you find that you need any assistance, please feel free to contact a Heroic Support® technician who can assist with obtaining and installing an SSL from the vendor of your choice.

Step #6: Enable the Account

  1. Verify that the switch next to Mail is toggled on.
  2. Tap Save.
  3. You’re now ready to start using your email address with iOS 9.