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
===================================
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
===================================
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 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:
|
||||||||||
2) |
Configure the IBM i SMTP Client to trust the newly imported CA certificates.
|
||||||||||
3) |
Assign a TLS certificate to the IBM i SMTP Client application in DCM.
|
||||||||||
4) |
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>') |
||||||||||
5) |
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) |
||||||||||
6) |
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) |
||||||||||
7) |
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)
|
||||||||||
8) | 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. |
Historical Number
519611543
Was this topic helpful?
Document Information
Modified date:
04 October 2023
UID
nas8N1018618