IBM Support

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 SSL/TLS when connecting to a SMTP Relay.

Environment

IBM i OS

Resolving The Problem

Since the IBM i OS does not support the dynamic use of multiple authentication credentials based on the sender's e-mail address, Option 1 in the Microsoft TechDoc, How to set up a multifunction device or application to send email using Office 365, will NOT function with the IBM i OS.  Please refer to the "Limitations of SMTP client submission" section under Option 1 in this document for more information.

After the Office 365 configuration steps have been completed using the information above, the "Forwarding Mailhub Server" (FWDHUBSVR) SMTP Attribute will need to be changed to your specific Office 365 domain's MX endpoint host name using the CHGSMTPA FWDHUBSVR(<MX endpoint host>) CL command to complete the set up process. The change to the "Forwarding Mailhub Server" SMTP Attribute is dynamic and will take affect immediately after the CHGSMTPA FWDHUBSVR(<MX endpoint host>) CL command is executed.

If you wish to configure SSL/TLS communications between the IBM i SMTP Client and Microsoft Office365 SMTP Connector, refer to the document, Configuring SSL Between IBM i and Remote Mail Router WITHOUT Authentication, to configure SSL/TLS communications when authentication with the SMTP relay is not used.

If you experience e-mail delivery issues through Office 365 from 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 e-mail delivery failures.

Any additional assistance with this configuration process would fall outside of the scope of the IBM Software Maintenance Agreement (SWMA) support contract and would require a per hour billable IBM i Customized Services consulting contract. Please contact IBM Support for further information.

===================================
General IBM i SMTP authentication configuration instructions for non-Office365 SMTP relays.


Additional Notes:

If you would like to configure SSL/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

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

1) 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 SSL/TLS encrypted connection, you will need to obtain the Certificate Authority (CA) certificates used by your SMTP Relay Server for SSL/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 Host Name 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.

QMGTOOLS GETSSL Utility

Example:
QMGTOOLS/GETSSL IP(MYDOMAIN.OUTLOOK.COM) PORT(587) STRTLS(Y)

The SSL/TLS certificates will be placed in the /tmp directory with the nomenclature, <user>_sslchainXX.cer, where XX is the order number of the certificate. This is important since it helps you identify which CA certificate should be imported first, second, etc. into DCM.

i.e. /tmp/QSECOFR-sslchain01.cer
2) Import your SMTP Relay CA certificates into DCM.
 
a) In a web browser, execute the following URL to access the Digital Certificate Manager (DCM) application:
http://systemname:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0


(Replace systemname with the TCP/IP Host Name or IP address of your IBM i server)
b) Click on the "Select a Certificate Store" button.

c) Select the radio button next to the *SYSTEM certificate store and click the Continue button.



If you don't see the *SYSTEM certificate store, then you will need to refer to the document, How to Create the *SYSTEM Store in DCM, to create the *SYSTEM certificate store first.
d) Enter the *SYSTEM certificate store password and click the Continue button.



If you cannot remember the password to the *SYSTEM certificate store, you can click on the Reset Password button to change the password. After changing the password, you would enter the new password and click the Continue button to sign into the *SYSTEM certificate store. If you cannot successfully reset the password, please open a Service Request (PMR) with IBM here or call 1-800-IBM-SERV.
e) After authenticating to the *SYSTEM certificate store successfully, the page should refresh and display the Current Certificate Store information as shown below.

f) On the left-hand, vertical menu, click on Fast Path and then click on Work with CA Certificates.

g) Scroll to the bottom of the Work with CA Certificates page and click the Import button.

h) Input the IFS path to the CA certificate you would like to import in the Import file field and press the Continue button.
i) Specify a certificate label name to uniquely identify the certificate in the *SYSTEM certificate store.

The certificate label name must be unique and cannot already be used by another certificate in the certificate store. IBM recommends the certificate label be set to the Common Name of the certificate.

j) If the CA certificate imports successfully, the screen will be refreshed with a message highlighted in green stating, "The certificate has been imported", as seen below.

k) Repeat steps 2f - 2j for any additional CA certificates in the SSL/TLS certificate chain.
3) Configure the IBM i SMTP Client to trust the newly imported CA certificates.

 
a) On the left-hand, vertical menu, click on Manage Applications and then click on Define CA Trust list.

b) Select the radio button next to Client and click on the Continue button.
c) Select the radio button next to IBM i TCP/IP SMTP Client and click the Define CA Trust List button.

NOTE: If you don't see the IBM i TCP/IP SMTP Client application in the list, this indicates the SMTP Client application is configured NOT to use a CA Trust List. As a result, please proceed to Step 4.

4) Assign a SSL/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:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0


(Replace systemname with the TCP/IP Host Name or IP address of your IBM i server)
b) Click on the "Select a Certificate Store" button.

c) Select the radio button next to the *SYSTEM certificate store and click the Continue button.



If you don't see the *SYSTEM certificate store, then you will need to refer to the document, How to Create the *SYSTEM Store in DCM, to create the *SYSTEM certificate store first.
d) Enter the *SYSTEM certificate store password and click the Continue button.



If you cannot remember the password to the *SYSTEM certificate store, you can click on the Reset Password button to change the password. After changing the password, you would enter the new password and click the Continue button to sign into the *SYSTEM certificate store.
e) After authenticating to the *SYSTEM certificate store successfully, the page should refresh and display the Current Certificate Store information as shown below.

f) On the left-hand, vertical menu, click on Fast Path and then click on Work with Server and Client Certificates.

g)
h) After selecting the certificate you would like to use, click on the Assign to Applications button at the bottom of the table.

i) Check the box next to the IBM i TCP/IP SMTP Client application in the list.



Make sure you are select the SMTP Client application!!!
j) After checking the box next to the IBM i TCP/IP SMTP Client application, scroll down to the bottom of the page and click on the Continue button.
h) The page will refresh and the following message will be displayed. Click the OK button to complete the certificate assignment process.

5) Set the SMTP Relay Host Name for the "Forwarding Mailhub Server" SMTP Attribute.

CHGSMTPA FWDHUBSVR('<hostName>')
6) Customize the Remote Port Value connected to by the IBM i SMTP Client when delivering e-mails.

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)
7) Configure the User name and User password values used to authenticate to your Forwarding Mailhub Server or SMTP Relay.

IBM Navigator for i web application
a) Open a web browser and go to the URL, http:// :2004/ibm/console OR https:// :2005/ibm/console, to display the IBM Navigator for i web application.

If you do not see a log-in page appear, execute the following CL commands to ensure the ADMIN server is started and working properly:

ENDTCPSVR *HTTP HTTPSVR(*ADMIN)
STRTCPSVR *HTTP HTTPSVR(*ADMIN)

If you continue to experience issues accessing the IBM Navigator for i web application, please open a Service Request (PMR) with IBM here or call 1-800-IBM-SERV.
b) Enter your IBM i User ID and password to authenticate. Click the Log in button to continue.

c) Click on Network -> Servers -> TCP/IP Servers in the left-hand, vertical menu. This will open up the TCP/IP Servers tab.

d) Locate the SMTP Server, right-click on it, and select Properties. This will open the SMTP Properties.

e) Click on the Authentication section in the SMTP Properties view.

f) Under Logon information for relay server:, click on the Add button.

g) Enter in the same Host Name value that is specified for the Forwarding Mailhub Server SMTP Attribute you customized in step 5. Then, enter the user name and password for the credentials required to authenticate to the SMTP relay. Click the OK button when complete to add and save the host logon information.

h) After clicking the OK button, you should now see the Host Name and User Name you just added. Click the OK button at the bottom of the SMTP Properties view to accept the SMTP properties changes. You will be prompted to restart the SMTP Server application.

i) On the TCP/IP Servers tab with all the TCP/IP servers listed, right-click on SMTP and click on Stop.



Click the OK button to close the informational message.

j) On the TCP/IP Servers tab with all the TCP/IP servers listed, right-click on SMTP and click on Start

.

Click the OK button to close the informational message.


IBM i Access for Windows (System i Navigator)

1. Open i5/OS Navigator and go to Network>Servers>TCP/IP. Right click on SMTP and select Properties:

i5 Navigator

2. From the General tab, add the name of the mail hub that the i5 will authenticate to. The command line equivalent is as follows:

CHGSMTPA FWDHUBSVR(MAILHUB)


SMTP Properties mailhub

3. In the Logon information for relay server, click the Add button and add the host name for the mailhub, user name, and password that is used to authenticate to that mailhub. The command line equivalent is as follows:

ADDSMTPLE TYPE(*HOSTAUTH) HOSTNAME(MAILHUB) USERNAME(kswan) PASSWORD()

Add host logon information

4. Once this is all completed, restart the SMTP server either from the Navigator screen or with the following commands:

ENDTCPSVR *SMTP
STRTCPSVR *SMTP
8) Congratulations! You have successfully configured your IBM i SMTP Client to relay all e-mail to the SMTP relay host specified on the "Fowarding Mailhub Server" SMTP Attribute using the SSL certificates and authentication credentials configured.

If you still experience e-mail 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 e-mail 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, and/or delivery of e-mail was unsuccessful.

Cross reference information
Product Component Platform Version Edition
IBM i 7.2
IBM i 7.1
IBM i 7.3

Historical Number

519611543

Document information

More support for: IBM i

Component: IBM TCP/IP Connectivity Utilities for i (5770TC1)

Software version: 7.1, 7.2, 7.3

Operating system(s): IBM i

Reference #: N1018618

Modified date: 13 March 2019