Learn how to import your existing TCP/IP profile into the Network Configuration Assistant
Starting with z/OS V2R2, the IBM Configuration Assistant for z/OS Communications Server, also known as the Network Configuration Assistant or NCA, can be used to produce TCP/IP profiles for z/OS Communications Server. You can use the panels, wizards, and helps to create a complete, syntactically correct TCP/IP profile with support for the full set of TCP/IP configuration statements and parameters.
The NCA can also be used to produce OBEY files for TCP/IP dynamic reconfiguration, by using the Change Set support that was delivered on z/OS V2R2 in APAR PI80101 and included in z/OS V2R3 and subsequent releases.
Starting with APAR PI97737 on z/OS V2R3 and in the base of z/OS V2R4 and subsequent releases, the NCA can also manage TCP/IP configurations for alternate locations to help you manage relocation of z/OS images for disaster recovery and planned outages.
With these functions, the NCA provides a rich, user-friendly set of functions for managing your TCP/IP configuration. However, you likely already have a complete TCP/IP configuration that you manage using ISPF editing of the MVS configuration data sets. How do you get started if you want to explore or migrate to using the NCA to manage your TCP/IP configuration? It would be tedious and error-prone to re-create your TCP/IP configuration from scratch in the GUI.
TCP/IP Profile Import Function
Starting z/OS V2R3, or z/OS V2R2 with APARs PI66143 and PI63449 applied, you can import your existing TCP/IP profiles into the Network Configuration Assistant. This function eliminates the need to re-create your TCP/IP configuration by hand in the NCA, giving you an accurate representation of your existing configuration within the NCA GUI and enabling you to begin working with your existing configuration right away. This import function supports configurations that use INCLUDE files and MVS system symbols.
How TCP/IP Profile Import Function Works
TCP/IP Profile import works in three major steps.
- Export a TCP/IP profile from z/OS Communications Server
- Read the exported configuration into the Network Configuration Assistant
- Fix any ambiguity or errors that result from the import
Exporting a TCP/IP profile from z/OS Communications Server: You export a profile from z/OS Communications Server by running the VARY TCPIP,,EXPORTPROFILE console command. You provide the name of the profile MVS data set as a parameter to the command. When it runs this command, z/OS Communications Server does not export its currently running configuration. It reads in the profile you specified on the command, checks the syntax, and exports it into a JSON file that the NCA can read. If there are syntax errors in the profile data set, the export will fail. If there are INCLUDE statements in the profile, the INCLUDE files are also read and exported, so that the export file will represent the complete TCP/IP configuration.
Because of this method of operation, you can use a TCP/IP stack to export any TCP/IP profile, unless the profile contains MVS system symbols. If the profile contains MVS systems symbols, you must export it from a TCP/IP stack that is running on the same image where the profile runs, so that correct MVS system symbol values can be exported with the configuration.
The JSON file created by running the VARY TCPIP,,EXPORTPROFILE command will reside in the z/OS UNIX file system in directory /var/exportprof. The name of the generated file is provided as a console message when the export completes.
Figure 1 VARY TCPIP,,EXPORTPROFILE example shows an example of execution of the VARY TCPIP,,EXPORTPROFILE command. The first red box shows the names of two include files that were found and read in. The second red box shows the name of the created export file, which can be found in z/OS UNIX directory /var/exportprof.
Reading the exported configuration into Network Configuration Assistant: To read the exported configuration into Network Configuration Assistant, navigate to the TCP/IP systems tree and select a TCP/IP stack that doesn’t yet have any configuration defined, then select Actions -> Manage Import of Formatted Configuration Data. If the stack already has TCP/IP configuration defined, it cannot import configuration. Selecting this option starts the TCP/IP profile import wizard. First, you specify the name and location of the export file created by z/OS Communications Server. The file can be on the local system or you can order NCA to retrieve it by using FTP, as show in Figure 2 TCP/IP profile import wizard, screen 1.
After you click Next, the export file is retrieved and read into the NCA. If there were include files, they will be converted to reusable configuration objects. On the next panel, you are asked to select which file is the base configuration, and to name the reusable configuration objects for the remaining files, as shown in Figure 3 TCP/IP profile import wizard, screen 2.
If you later import another configuration that uses the same include files, the NCA will recognize that and give you an opportunity to either reuse the already-created reusable configuration or create a new one. Also note that the NCA only preserves one level of INCLUDE files. This means that if an INCLUDE file includes another INCLUDE file, that file and all its INCLUDEs will be treated as a single reusable configuration object.
After you click Next on the second screen of the wizard, you see the import results.
Fixing ambiguity or errors that result from import: Because of the sophistication and variety of TCP/IP configuration, the NCA might not be able to completely resolve an import file. In addition, you might have errors in your TCP/IP configuration that you are ignoring that the NCA doesn’t ignore. You might import profiles in an order that doesn’t resolve all sysplex references at first. And finally, you might have symbol ambiguity to resolve.
When there are errors in the imported configuration, for example multiple IP interfaces with the same address or similar context errors that the syntax checker didn’t catch on export, the affected resources are marked incomplete with error messages in the NCA and you need to manually fix them. In the example in Figure 4 Example of imported duplicate interface errors, three interfaces were imported with the same IP address. You need to fix this manually by either deleting duplicate interfaces or changing their IP addresses to not be duplicates.
Another example of an error that may need fixing is symbol ambiguity. Because of the way the stack’s EXPORTPROFILE processing works, NCA must reverse engineer MVS system symbols into your configuration. If multiple symbols have the same value, NCA may not be able to resolve the ambiguity. In this case, the NCA marks the affected resources incomplete and inserts all possible symbol names into the field. You resolve the ambiguity by deleting the incorrect symbol representations and leaving the correct one. In the example shown in Figure 5 Imported symbol ambiguity, the symbols &GSKVOL. and &SYSR1. both have a value of “MVS220”. The NCA couldn’t unambiguously tell which, if any, symbol belongs in this field so it provided you with both symbol possibilities plus a constant. You resolve the ambiguity by deleting the two incorrect representations, leaving the correct one in place.
See a live demonstration of this import capability with a Q&A session.
Mike is a Senior Software Architect with Enterprise Network Solutions in IBM Systems, with over 20 years of experience in mainframe networking. His primary areas of expertise and responsibility are IP routing and connectivity, and the z/OS Configuration Assistant for Communications Server.