Steps for configuring OMPROUTE

OMPROUTE is a multiprotocol routing daemon capable of handling both OSPF and RIP interfaces concurrently.

Perform the following steps to configure OMPROUTE:

1. Create the OMPROUTE configuration file. The OMPROUTE configuration file provides information about the host's routing capabilities and TCP/IP interfaces. For more detail about the contents of this file, see Steps for configuring OSPF and RIP (IPv4 and IPv6). The following search order is used by OMPROUTE to locate the configuration data set or file:
   1. The MVS™ data set or z/OS® UNIX file that is specified on the OMPCFG DD statement in the OMPROUTE started procedure.
   2. If the environment variable, OMPROUTE_FILE, is defined, OMPROUTE uses the value as the name of an MVS data set or z/OS UNIX file to access the configuration data. The syntax for an MVS data set name is //'mvs.dataset.name'. The syntax for a z/OS UNIX file name is /dir/subdir/file.name.
   3. /etc/omproute.conf
   4. hlq.ETC.OMPROUTE.CONF
   Tip: If you are configuring a complex environment, you can use the following OMPROUTE configuration file features:

   • Group related statements into separate files and use the INCLUDE statement to include them in your OMPROUTE configuration.
   • Use MVS system symbols (such as &SYSCLONE, &SYSNAME, and &SYSPLEX). This feature reduces the number of OMPROUTE configuration files that must be maintained in a multisystem environment.

   A sample configuration file is provided in SEZAINST(EZAORCFG). The configuration files for TCPCS4, TCPCS6, TCPCS7, and TCPCS64 in the sample network are shown in Sample OMPROUTE configuration files. For a description of the syntax rules for the OMPROUTE configuration file and details on each of the configuration statements, see z/OS Communications Server: IP Configuration Reference.

2. Reserve the ports.
   • RIP protocol
     If the RIP protocol of OMPROUTE is going to be used, UDP port 520 should be reserved for OMPROUTE. If the IPv6 RIP protocol of OMPROUTE is going to be used, UDP port 521 should be reserved for OMPROUTE. This is done by adding the name of the member containing the OMPROUTE cataloged procedure to the PORT statement in PROFILE.TCPIP:

     PORT
         520 UDP OMPROUTE
         521 UDP OMPROUTE

     If you want to be able to start OMPROUTE from the z/OS shell, use the special name OMVS as follows:

      PORT
         520 UDP OMVS
         521 UDP OMVS

   • Autolog considerations for OMPROUTE when using the OSPF protocol

     If a procedure in the AUTOLOG list also has a PORT statement reserving a TCP or UDP port but does not have a listening connection on that port, TCP/IP periodically attempts to cancel that procedure and start it again.

     Therefore, if OMPROUTE is being started with AUTOLOG and only the OSPF or IPv6 OSPF protocol is being used (no RIP or IPv6 RIP protocol, so no listening connection on the RIP or IPv6 RIP UDP port), it is important to take one of the following actions:

     • Ensure that the RIP UDP port (520) and the IPv6 RIP UDP port (521) are not reserved by the PORT statement in the PROFILE.TCPIP.
     • Add the NOAUTOLOG parameter to the PORT statement in the PROFILE.TCPIP. For example,

       PORT
        520 UDP OMPROUTE NOAUTOLOG
        521 UDP OMPROUTE NOAUTOLOG

     Tip: When using only the OSPF or IPv6 OSPF protocol, the auto-start feature of AUTOLOG can be used as described. However, the monitoring and auto-restart features of AUTOLOG are unavailable due to AUTOLOG's dependence on listening to a TCP or UDP connection, which does not exist with OSPF and IPv6 OSPF.

     If you fail to take one of these actions, OMPROUTE will be periodically canceled and restarted by TCP/IP.

3. Update the resolver configuration file. The resolver configuration file contains keywords (DATASETPREFIX and TCPIPjobname) used by OMPROUTE. The value assigned to DATASETPREFIX will determine the high-level qualifier (hlq). The hlq is used in the search order for the OMPROUTE configuration file. If no DATASETPREFIX keyword is found, a default of TCPIP is used. The value assigned to TCPIPjobname will be used as the name of the TCP/IP stack with which OMPROUTE establishes a connection.

   For a description of the search order used by the resolver to locate the resolver configuration file, see Resolver configuration files.

4. Update the OMPROUTE cataloged procedure. If OMPROUTE is to be started by a procedure, create the cataloged procedure by copying the sample in SEZAINST(OMPROUTE) to your system or recognized PROCLIB. Specify OMPROUTE parameters and change the data set names to suit your local configuration.

   //*
   //* TCP/IP for MVS
   //* SMP/E Distribution Name: EZBORPRC
   //*
   //*        5650-ZOS Copyright IBM Corp. 1998, 2013
   //*        Licensed Materials - Property of IBM
   //*        This product contains "Restricted Materials of IBM"
   //*        All rights reserved.
   //*        US Government Users Restricted Rights -
   //*        Use, duplication or disclosure restricted by
   //*        GSA ADP Schedule Contract with IBM Corp.
   //*        See IBM Copyright Instructions.
   //*
   //OMPROUTE PROC
   //OMPROUTE EXEC PGM=OMPROUTE,REGION=10M,TIME=NOLIMIT,
   // PARM=('ENVAR("_CEE_ENVFILE_S=DD:STDENV")/')
   //*
   //* Example of start parameters to OMPROUTE:
   //*
   //* PARM=('ENVAR("_CEE_ENVFILE_S=DD:STDENV")/-t1 -6t1')
   //*
   //*        Provide environment variables to run with the
   //*        desired stack and configuration.  As an example,
   //*        the file specified by STDENV could have these
   //*        lines in it:
   //*
   //*           RESOLVER_CONFIG=//'SYS1.TCPPARMS(TCPDATA2)'
   //*           OMPROUTE_FILE=/u/usernnn/config.tcpcs2
   //*           OMPROUTE_DEBUG_FILE=/tmp/logs/omproute.debug
   //*           OMPROUTE_IPV6_DEBUG_FILE=/tmp/logs/omprout6.debug
   //*           OMPROUTE_DEBUG_FILE_CONTROL=1000,5
   //*
   //*        For information on the above environment variables,
   //*        refer to the IP CONFIGURATION GUIDE.
   //*
   //*   If you want to include comments in the data set or
   //*   z/OS UNIX file, specify the _CEE_ENVFILE_COMMENT
   //*   environment variable as the first environment variable
   //*   in the data set or file.  The value specified for
   //*   the _CEE_ENVFILE_COMMENT variable is the comment character.
   //*   For example, if you want to use the semicolon sign, ;, as
   //*   the comment character, specify this as the first
   //*   statement:
   //*     _CEE_ENVFILE_COMMENT=;
   //*
   //STDENV   DD PATH='/u/usernnn/envcs2',
   //         PATHOPTS=(ORDONLY)
   //*
   //*        The stdout stream may be redirected to a HFS file as
   //*        shown below.
   //*        The PATHOPTS OTRUNC option will clear the stdout file
   //*        every time OMPROUTE is started.  If you want to retain
   //*        previous stdout information, change it to OAPPEND.
   //*
   //SYSPRINT DD SYSOUT=*
   //*SYSPRINT DD PATH='/tmp/omproute.stdout',
   //*            PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
   //*            PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
   //*
   //*        The stderr stream may be redirected to a HFS file as
   //*        shown below.
   //*        The PATHOPTS OTRUNC option will clear the stderr file
   //*        every time OMPROUTE is started.  If you want to retain
   //*        previous stderr information, change it to OAPPEND.
   //*
   //SYSOUT   DD SYSOUT=*
   //*SYSOUT   DD PATH='/tmp/omproute.stderr',
   //*            PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
   //*            PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
   //*
   //CEEDUMP  DD SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=132)

5. Specify the RIP UDP port numbers in the SERVICES file or data set (if using the RIP or IPv6 RIP protocol). The services file contains the relationship between services and port numbers as described in z/OS Communications Server: IP Configuration Reference. The portion of the services file relevant to OMPROUTE is:

     route           520/udp         router omproute
     route           521/udp         ipv6rip ripng

   The file must exist for the RIP and IPv6 RIP protocols of OMPROUTE to operate.

   For a description of the search order used to locate the services file, see Configuration files for TCP/IP applications.

6. RACF authorize user IDs for starting OMPROUTE. To reduce risk of an unauthorized user starting OMPROUTE and affecting the contents of the routing table, users who start OMPROUTE must be RACF-authorized to the entity MVS.ROUTEMGR.OMPROUTE. To RACF-authorize, the following commands must be entered from a RACF user ID, substituting the authorized user ID on the ID(userid) parameter. The commands in this example are taken from SEZAINST(EZARACF).

     RDEFINE OPERCMDS (MVS.ROUTEMGR.OMPROUTE) UACC(NONE)
     PERMIT MVS.ROUTEMGR.OMPROUTE ACCESS(CONTROL) CLASS(OPERCMDS) ID(userid)
     SETROPTS RACLIST(OPERCMDS) REFRESH

   Rule: The user ID specified for OMPROUTE must have read/write permission to the directories where OMPROUTE reads and writes files. To determine the files that OMPROUTE reads and writes, see OMPROUTE environment variables in z/OS Communications Server: IP Configuration Reference.
7. Start syslogd. To write only the urgent OMPROUTE messages to the z/OS console, syslogd should be running while OMPROUTE is running. Syslogd sends the non-urgent messages to the z/OS UNIX file system message log.
8. Update the OMPROUTE environment variables (optional). The following environment variables are used by OMPROUTE and can be tailored to a particular installation:

   RESOLVER_CONFIG

   The RESOLVER_CONFIG variable is used by OMPROUTE to locate the resolver configuration file. For more information on OMPROUTE's use of the resolver configuration file, see step 3. For more information about the RESOLVER_CONFIG environment variable, see z/OS XL C⁄C++ environment variables for configuration files.

   OMPROUTE_FILE

   The OMPROUTE_FILE variable is used by OMPROUTE in the search order for the OMPROUTE configuration file. For details on the search order used for locating this configuration file, see step 1.

   OMPROUTE_DEBUG_FILE

   The OMPROUTE_DEBUG_FILE variable is used by OMPROUTE to override the debug output destination for IPv4 dynamic routing protocols and for processing common to both IPv4 and IPv6 routing protocols.

   Tip: When the OMPROUTE CTRACE with option DEBUGTRC (or option ALL) is active, debug output is written to CTRACE and not to the destination specified by this variable.

   For more information on using this environment variable, see OMPROUTE parameters.

   OMPROUTE_DEBUG_FILE_CONTROL

   The OMPROUTE_DEBUG_FILE_CONTROL variable is used by OMPROUTE to control the size and quantity of trace files created when the OMPROUTE_DEBUG_FILE or OMPROUTE_IPV6_DEBUG_FILE variable is specified. The syntax of this variable is:

   OMPROUTE_DEBUG_FILE_CONTROL=<size of file>,<num of files>

   The default values for <size of file> and <num of files> are 200 (KB) and 5 respectively. In general, these values are sufficient for most installations.

   If OMPROUTE_DEBUG_FILE and OMPROUTE_IPV6_DEBUG_FILE are both specified with different output destinations, the values specified on the OMPROUTE_DEBUG_FILE_CONTROL variable will apply to both the IPv4 debug files and the IPv6 debug files. The total number of files created in this environment would be <num of files> multiplied by 2.

   OMPROUTE_IPV6_DEBUG_FILE

   The OMPROUTE_IPV6_DEBUG_FILE variable is used by OMPROUTE to override the debug output destination for IPv6 dynamic routing protocols.

   Tip: When the OMPROUTE CTRACE with option DEBUGTRC (or option ALL) is active, debug output is written to CTRACE and not to the destination specified by this variable.

   For more information on using this environment variable, see OMPROUTE parameters.

   OMPROUTE_CTRACE_MEMBER

   The OMPROUTE_CTRACE_MEMBER variable is used by OMPROUTE to specify the name of the parmlib member containing CTRACE default settings. If not specified, the default value is CTIORA00. Use this environment variable to set different CTRACE options and buffer sizes for multiple OMPROUTE instances.

9. Create static routes (optional). OMPROUTE does not use the environment variable GATEWAYS_FILE to initialize static routes. To create IPv4 static routes, use the BEGINROUTES or GATEWAY statement in PROFILE.TCPIP. To create IPv6 static routes, use the BEGINROUTES statement in PROFILE.TCPIP. For information on the syntax of the GATEWAY and BEGINROUTES statements, see z/OS Communications Server: IP Configuration Reference.

   During initialization, OMPROUTE learns of static routes by reading the internal routing table set up by TCP/IP. If static routes are changed during execution by VARY TCPIP,,OBEYFILE command processing, OMPROUTE is dynamically notified of the changes by TCP/IP. OMPROUTE will advertise active static routes to other routers if allowed by configuration (for example, the IMPORT_STATIC_ROUTES parameter of the AS_BOUNDARY_ROUTING or IPV6_AS_BOUNDARY_ROUTING configuration statements).

   Static routes can be defined as replaceable or nonreplaceable, with nonreplaceable being the default.

   A nonreplaceable static route cannot be replaced or modified by OMPROUTE, even if a better dynamic route can be learned and even if the static route is not actually available (but a static route that is not available will not be advertised by OMPROUTE). Because of this, the use of nonreplaceable static routes with OMPROUTE is not recommended unless it is to provide routing over an interface over which no routing protocol is being communicated.

   A replaceable static route will be replaced by OMPROUTE if it dynamically learns a route to the destination. Any dynamically learned route will be considered more desirable than a replaceable static route. A replaceable static route should be considered as a last resort route, to be used by TCP/IP when no dynamic route to a destination can be found.

   For detailed information, see Use of static routing with OMPROUTE.

10. Configure OSPF authentication (optional, if using the IPv4 OSPF protocol). OMPROUTE supports defining the IPv4 OSPF authentication type by area or by interface. By default, all interfaces attached to an area use the type of authentication defined for that area on the AREA configuration statement, unless overridden on the OSPF_INTERFACE configuration statement. The values of authentication keys must be defined on OSPF_INTERFACE statements in any case. All routers which could become neighbors of each other must use the same authentication type and key, or OSPF communication between the routers will not be possible.

    Virtual links behave similarly to interfaces for authentication purposes. By default, a virtual link uses the same type of authentication that is specified for the backbone area unless overridden on the VIRTUAL_LINK configuration statement. When the authentication type is not NONE, the value of the authentication key must be specified on the VIRTUAL_LINK configuration statement. There is no requirement for a virtual link to have the same authentication key value as its underlying real interface.

    OSPF authentication does not protect the contents of an OSPF packet. These packets are not encrypted. However, it does provide verification that the packet is genuine.

    Tip: Unlike IPv4 OSPF, IPv6 OSPF does not provide its own, protocol-layer authentication. It relies instead on authentication provided by IPv6 IPSec.

    There are two methods of IPv4 OSPF authentication, password and MD5 cryptographic.

    Password authentication is very basic: an 8-byte password is appended to all OSPF packets and sent in the clear with the rest of the packet. If the sent password matches that defined by the packet receiver, the packet is accepted.

    MD5 authentication is more sophisticated. The combination of the OSPF packet and the MD5 key is summarized into a 16-byte message digest, which is appended to the packet and sent. The keys are never sent, only the message digests. The receiver then attempts to re-create the message digest from the combination of its defined key and the OSPF packet. If the digest is successfully re-created, the packet is accepted; otherwise it is rejected. MD5 authentication also contains a monotonic increasing counter to protect against replay attacks.

    If MD5 cryptographic authentication is being used, a 16-byte MD5 key must be defined on the OSPF_INTERFACE configuration statement. This key is defined as a hexadecimal string and may be obtained in several ways. One method for obtaining MD5 keys is provided in the pwtokey utility, which converts a password into an MD5 key. This UNIX System Services utility implements the algorithm defined in RFC 3414, User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3). Because OSPF does not support localization of keys, it is necessary only to provide a password to this utility to generate a single, 16-byte key. If multiple sites have this utility, MD5 keys can easily be generated from passwords, which are easier to remember and communicate than 16-byte hexadecimal strings.