How To Configure the SMTP Client To Use SMTP Authentication with a SMTP Relay

Troubleshooting

Problem

This document discusses how to configure the IBM i SMTP Client to use SMTP Authentication and TLS when connecting to a SMTP Relay.

Environment

IBM i OS

Resolving The Problem

For more information on configuring the IBM i SMTP Client to relay email to Microsoft Office 365 or Google Mail (Gmail), refer to the IBM Technical document, "Configuration of the IBM i SMTP Client to Relay Email to Office365 and Gmail".

===================================
General SMTP authentication & TLS configuration instructions for the IBM i SMTP Client.

Prerequisites

In order to configure the IBM i SMTP Client for SMTP Authentication and TLS, the following prerequisites must exist. This document assumes the following:

- The IBM Digital Certificate Manager (DCM) *SYSTEM Certificate Store already exists
- The DCM Local certificate authority (CA) Certificate Store already exists

The following documents can help configure these items if they are not already configured:

How to create the *SYSTEM store in DCM
How to Create the Local Certificate Authority (CA) Store in DCM

Additional Notes:

If you would like to configure TLS between the IBM i and a remote mail relay WITHOUT providing authentication credentials, refer to the following documentation.

Configuring SSL Between IBM i and Remote Mail Router WITHOUT Authentication

===================================

Obtain the certificate authority (CA) certificates used by the SMTP Relay server you are connecting to.

Since SMTP Authentication on the IBM i OS requires a TLS encrypted connection, you will need to obtain the certificate authority (CA) certificates used by your SMTP Relay Server for TLS connections. You can either obtain these manually from your SMTP Relay Server administrator or use the QMGTOOLS GETSSL utility if you know the TCP/IP hostname or IP address of the SMTP Relay Server and the SSL/TLS port it listens on. For instructions on how to use the QMGTOOLS GETSSL utility, please refer to the following document.

**************************

NOTE: We will want to update QMGTOOLS first prior to using the utility:

We can then run the following commands from the IBM i command line:

ADDLIBLE QMGTOOLS

GO MG

Take an opt. 13 to check for an update and follow the prompts to automatically download and restore the updated library. If the system cannot connect to IBM please perform 'Method 3' from the following document to manually update the QMGTOOLS library:

https://www.ibm.com/support/pages/qmgtools-how-check-and-update-qmgtools

**************************

QMGTOOLS GETSSL Utility

Example (replace password with the DCM *SYSTEM store password):

QMGTOOLS/GETSSL IP(MYDOMAIN.OUTLOOK.COM) PORT(587) STRTLS(Y) SERVICE(SMTP) AUTOIMP(Y) STOREPWD(password)

Using the syntax above, the certificate will be retrieved and automatically imported into the DCM *SYSTEM store.

NOTE: If the application is unable to connect to the remote system, the CA certificates will need to be manually requested from the remote server.

We can then use the following instructions to import the CA certificates into the store:

https://www.ibm.com/docs/en/i/7.5?topic=dcm-importing-certificate

Configure the IBM i SMTP Client to trust the newly imported CA certificates.

a)	Open Digital Certificate Manager for i (http://systemname:2006/dcm or https://systemname:2007/dcm) and log into the GUI.
b)	Click 'Open Certificate Store' and sign into the *SYSTEM store.
c)	Click 'Manage Application Definitions', then type the following in the search bar on the right: smtp client The list of application IDs will be filtered to show the QIBM_QTMS_SMTP_CLIENT application ID tile.
d)	Click the + in the lower right corner of the tile, then click 'Update'.
e)	Scroll down and set 'Define the CA Trust List' to 'NO', then click 'Update' at the bottom of the screen.

Assign a TLS certificate to the IBM i SMTP Client application in DCM.

a)	In a web browser, execute the following URL to access the Digital Certificate Manager (DCM) application: http://systemname:2006/dcm or https://systemname:2007/dcm Sign in with your IBM i user profile/password.
b)	Click 'Open Certificate Store' and sign into the *SYSTEM store.
c)	Click the + in the lower right corner of the server certificate tile you would like to assign to the IBM i SMTP Client application, then click 'Assign'. If you would like to create a new certificate at this time, refer to the following document on how to create a self-signed certificate in DCM. How do I create a TLS server certificate issued by a local Certificate Authority?
d)	Check the box next to the QIBM_QTMS_SMTP_CLIENT application in the list.
e)	After checking the box next to the QIBM_QTMS_SMTP_CLIENT application, scroll down to the bottom of the page and click on the Replace button.

Set the SMTP Relay hostname for the "Forwarding Mailhub Server" SMTP Attribute by running the following command on the IBM i command line (replace <hostName> with the address of the remote mail router).

CHGSMTPA FWDHUBSVR('<hostName>')

Customize the Remote Port Value connected to by the IBM i SMTP Client when delivering emails.

Refer to the following IBM Technical document on how to configure the SMTP Client to deliver mail to a Mail Router/Fowarding Hub Server on a Port other than port 25.
How to Configure SMTP to Send Mail to a Mail Router that Listens on a Port Other Than Port 25

i.e.
ADDENVVAR ENVVAR(QIBM_SMTP_SERVER_PORT) VALUE('587') LEVEL(*SYS)

When using the *SMTP Email Directory Type, you will need to set the QIBM_SMTP_RLY_TLS_FIRST=YES_STARTTLS environment variable at the *SYS level.

You can check your current IBM i SMTP Email Directory Type value by prompting the CHGSMTPA CL command with an F4 and look for the Email Directory Type field and value. If the value *SMTP or *SMTPMSF is configured, you will also need to execute the ADDENVVAR command below. If the value is *SDD, do not add this environment variable and proceed to step 7.

ADDENVVAR ENVVAR(QIBM_SMTP_RLY_TLS_FIRST) VALUE(YES_STARTTLS) LEVEL(*SYS)

Configure the User name and User password values used to authenticate to your Forwarding Mailhub Server or SMTP Relay.

On the IBM i command line run the following command (use the following for the parameters):

Parameters:

HOSTNAME = Mail router address from 'Forwarding Mailhub Server' in CHGSMTPA

USERNAME/PASSWORD = Credentials to authenticate with the remote mail router

Command:

ADDSMTPLE TYPE(*HOSTAUTH) HOSTNAME(MailRouter) USERNAME(username) PASSWORD(password)

Once this is completed, restart the SMTP server with the following commands:

ENDTCPSVR SERVER(*SMTP)

STRTCPSVR SERVER(*SMTP)

Congratulations! You have successfully configured your IBM i SMTP Client to relay all email to the SMTP relay host specified on the "Forwarding Mailhub Server" SMTP Attribute using the SSL certificates and authentication credentials configured.

If you still experience email delivery issues with the IBM i SMTP Client after the above configuration has been completed successfully, an IBM i SMTP Client trace can be gathered using the instructions in the URL, http://www.ibm.com/support/docview.wss?uid=nas8N1012636, to help determine the cause of your email delivery failures. Locate the QTMSSTRC spool file with the largest amount of pages. The spool file should be for the SMTP Client Pre Start Job or SMTP Client Daemon. These spool files will indicate why the SMTP relay connection, authentication, or delivery of email was unsuccessful.

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CHfAAM","label":"Email and SMTP"},{"code":"a8m0z0000000CHRAA2","label":"Email and SMTP-\u003EOffice 365 SMTP Relay Setup"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.3.0;7.4.0;7.5.0"}]

Historical Number

519611543

Was this topic helpful?

Document Information

Modified date:
04 October 2023

UID

nas8N1018618

Tips