TCP/IP Planning and Customization - z/VM

TCP/IP Planning and Customization - z/VM
z/VM™
TCP/IP Level 430
Planning and Customization
Version 4 Release 3.0
SC24-6019-01
z/VM™
TCP/IP Level 430
Planning and Customization
Version 4 Release 3.0
SC24-6019-01
Note:
Before using this information and the product it supports, read the information under “Notices” on page 659.
Second Edition (May 2002)
| This edition applies to Version 4, Release 3, Modification 0 of IBM® z/VM (product number 5739-A03) and to all
| subsequent releases and modifications until otherwise indicated in new editions.
| This edition replaces SC24-6019–00.
© Copyright International Business Machines Corporation 1987, 2002. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
|
|
|
|
|
|
Preface . . . . . . . . . . . . . . . .
Who Should Read This Book . . . . . . . .
What You Should Know before Reading This Book
What This Book Contains . . . . . . . . . .
How the Term “internet” Is Used in This Book . .
Understanding Syntax Diagrams . . . . . . .
Where to Find More Information . . . . . . .
PDF Links to Other Books . . . . . . . .
How to Send Your Comments to IBM . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xix
xix
xix
xix
xxi
xxi
. . . . . . . . . . . xxiv
. . . . . . . . . . . xxiv
. . . . . . . . . . . xxiv
Summary of Changes . . . . . . . . . . . . . . . . . . . . . xxvii
Second Edition for z/VM Version 4 (May 2002) . . . . . . . . . . . . xxvii
TCP/IP Stack Performance . . . . . . . . . . . . . . . . . . . xxvii
TCP/IP Device Support . . . . . . . . . . . . . . . . . . . . xxvii
TCP/IP Stack Vulnerability Reduction . . . . . . . . . . . . . . . xxvii
TCP/IP Dynamic Stack Configuration [4.3.0] . . . . . . . . . . . . xxviii
First Edition for z/VM Version 4 (October 2001) . . . . . . . . . . . . xxviii
IMAP Support . . . . . . . . . . . . . . . . . . . . . . . xxviii
HiperSockets Support . . . . . . . . . . . . . . . . . . . . xxviii
TCP/IP Stack Performance and Reliability Improvement . . . . . . . . xxviii
Migration Consideration Changes . . . . . . . . . . . . . . . . xxviii
First Edition for z/VM Version 3 (February 2001) . . . . . . . . . . . . xxix
Native Queued Direct I/O Support . . . . . . . . . . . . . . . . xxix
Open Shortest Path First (OSPF) Protocol . . . . . . . . . . . . . xxix
IP Multicast Support . . . . . . . . . . . . . . . . . . . . . xxix
Secure Socket Layer (SSL) Support . . . . . . . . . . . . . . . xxix
VM NFS Client Support . . . . . . . . . . . . . . . . . . . . xxx
FTP Web Browser Support . . . . . . . . . . . . . . . . . . . xxx
Other Changes . . . . . . . . . . . . . . . . . . . . . . . xxx
Second Edition for VM/ESA® (July 1999) . . . . . . . . . . . . . . . xxx
RouteD Support . . . . . . . . . . . . . . . . . . . . . . . xxx
Native ATM Support . . . . . . . . . . . . . . . . . . . . . xxxi
FTP Server Enhancements . . . . . . . . . . . . . . . . . . . xxxi
SMTP Server Enhancements . . . . . . . . . . . . . . . . . . xxxi
VMNFS Server Enhancements . . . . . . . . . . . . . . . . . xxxi
Other Changes . . . . . . . . . . . . . . . . . . . . . . . xxxi
Chapter 1. Planning Considerations . . . .
Introducing TCP/IP . . . . . . . . . . .
Connectivity and Gateway Functions . . .
Server Functions. . . . . . . . . . .
Client Functions . . . . . . . . . . .
Network Status/Management Functions . .
Application Programming Interfaces. . . .
Migration Information and Resources . . . .
Implications of Assigning Different Server Virtual
Server Naming Restrictions . . . . . . .
Accommodating Changed Server Names. .
Multiple Server Instance Restrictions . . .
Mutually Exclusive Servers . . . . . . .
Publication References . . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Machine Names.
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
1
1
2
4
4
5
5
6
6
6
8
9
9
Chapter 2. System Requirements for TCP/IP . . . . . . . . . . . . . 11
© Copyright IBM Corp. 1987, 2002
iii
z/VM Device Definition Considerations
Hardware Environment . . . . . .
Network Attachments. . . . . . .
Software Environment . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
11
12
Parameters
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
15
15
15
15
16
17
18
19
20
20
20
21
21
21
22
22
22
23
23
24
25
25
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
27
27
27
28
29
Chapter 5. General TCP/IP Server Configuration . .
Virtual Machine Definitions . . . . . . . . . . .
Required Virtual Machines. . . . . . . . . . .
Optional Virtual Machines . . . . . . . . . . .
Methods of Server Configuration . . . . . . . . .
The DTCPARMS File . . . . . . . . . . . .
Configuring the DTCPARMS File . . . . . . . .
Customizing Servers . . . . . . . . . . . . .
Automatic Generation of Selected Startup Parameters
Adding New Servers and Server Classes . . . . .
Duplicating and Running Existing Servers . . . . .
Server Profile Exits . . . . . . . . . . . . .
Global Profile Exit . . . . . . . . . . . . . .
Customizing Server-specific Exits . . . . . . . .
GCS Servers . . . . . . . . . . . . . . .
TCP/IP Configuration File Overview . . . . . . . .
Starting and Stopping TCP/IP Servers . . . . . . .
Stopping TCP/IP Servers . . . . . . . . . . .
Starting TCP/IP Servers . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
31
31
32
33
34
34
38
39
39
40
41
43
43
44
44
46
47
47
Chapter 3. Defining the TCP/IP System
Configuring the TCPIP DATA File . . .
Statement Syntax . . . . . . . . .
ATSIGN Statement . . . . . . .
DOMAINLOOKUP Statement. . . .
DOMAINORIGIN Statement . . . .
DOMAINSEARCH Statement. . . .
HOSTNAME Statement . . . . . .
NSINTERADDR Statement . . . .
NSPORTADDR Statement. . . . .
RESOLVERTIMEOUT Statement . .
RESOLVERUDPRETRIES Statement
RESOLVEVIA Statement . . . . .
SMTPSERVERID Statement . . . .
TCPIPUSERID Statement . . . . .
TRACE RESOLVER Statement . . .
UFTSERVERID Statement . . . .
USERDATA Statement . . . . . .
VMFILETYPE Statement . . . . .
VMFILETYPEDEFAULT Statement .
Testing the TCP/IP System Configuration
HOMETEST Command . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 4. Configuring the HOSTS LOCAL File
Statement Syntax . . . . . . . . . . . .
HOST Statement . . . . . . . . . . .
NET Statement . . . . . . . . . . . .
Building the Hosts Local Site Table . . . . .
|
|
|
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 6. Configuring the BOOTP Server . . . . . . . . . . . . . . 49
Step 1: Update PROFILE TCPIP . . . . . . . . . . . . . . . . . . 49
iv
z/VM: TCP/IP Planning and Customization
Step 2: Update the DTCPARMS File . . . .
Step 3: Customize the ETC BOOTPTAB File .
BOOTPD Command . . . . . . . . . .
Dynamic Server Operation . . . . . . .
BOOTPD Subcommands . . . . . . . .
CMS Subcommand . . . . . . . . .
CONFIG Subcommand . . . . . . . .
EXCLUDE Subcommand . . . . . . .
EXIT Subcommand . . . . . . . . .
FORWARD Subcommand . . . . . . .
HELP Subcommand . . . . . . . . .
INCLUDE Subcommand . . . . . . .
LURK Subcommand . . . . . . . . .
QUIT Subcommand . . . . . . . . .
RELOAD Subcommand. . . . . . . .
STAYUP Subcommand . . . . . . . .
STOP Subcommand . . . . . . . . .
TRACE Subcommand . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
49
50
50
52
52
52
53
55
56
56
58
59
60
60
60
62
62
62
Chapter 7. Configuring the DHCP Server . .
Step 1: Update PROFILE TCPIP . . . . . .
Step 2: Update the DTCPARMS File for DHCPD
Step 3: Configure the ETC DHCPTAB File . . .
DHCPD Command . . . . . . . . . . .
Machine File Overview . . . . . . . . . .
Statement Precedence Order . . . . . .
Step 4: Construct a DHCPD Machine File . . .
Global Information. . . . . . . . . . .
Subnet Related Data. . . . . . . . . .
DHCPD Machine Statements. . . . . . . .
Machine File Format . . . . . . . . . .
{ (left brace) Statement . . . . . . . . . .
} (right brace) Statement . . . . . . . . .
Balance: Statement . . . . . . . . . . .
BootStrapServer Statement . . . . . . . .
CLASS Statement. . . . . . . . . . . .
CLIENT Statement . . . . . . . . . . .
DefineOptions Statement . . . . . . . . .
InOrder: Statement . . . . . . . . . . .
LeaseExpireInterval Statement . . . . . . .
LeaseTimeDefault Statement. . . . . . . .
OPTION Statement . . . . . . . . . . .
PingTime Statement . . . . . . . . . . .
ReservedTime Statement . . . . . . . . .
SUBNET Statement . . . . . . . . . . .
SupportBootP Statement . . . . . . . . .
SupportUnlistedClients Statement . . . . . .
UsedIPAddressExpireInterval Statement . . .
VENDOR Statement . . . . . . . . . . .
DHCP Options . . . . . . . . . . . . .
Dynamic Server Operation . . . . . . . .
DHCPD Subcommands . . . . . . . . .
CMS Subcommand . . . . . . . . . .
CONFIG Subcommand . . . . . . . .
DELETE Subcommand . . . . . . . .
EXCLUDE Subcommand . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
65
65
66
66
66
68
70
71
71
75
80
80
82
82
82
83
83
84
86
86
87
88
88
91
91
92
94
94
95
96
97
112
112
112
113
115
116
Contents
v
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
EXIT Subcommand . . .
FORWARD Subcommand
HELP Subcommand . .
INCLUDE Subcommand .
LURK Subcommand . .
QUIT Subcommand. . .
RELOAD Subcommand .
SHOW Subcommand . .
STATUS Subcommand .
STAYUP Subcommand .
STOP Subcommand . .
TRACE Subcommand . .
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
117
117
119
120
120
121
121
122
125
127
127
128
Chapter 8. Configuring the DNS Server . .
DNS Server Overview . . . . . . . . . .
Primary Versus Caching-Only Name Servers
Host Name Resolution . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . .
Step 2: Update the DTCPARMS File . . . .
NSMAIN Command. . . . . . . . . .
Step 3: Customize the NSMAIN DATA File . .
DNS Configuration File Statements . . . . .
CACHINGONLY Statement . . . . . . .
CHECKORIGIN Statement . . . . . . .
DATABASEQUERYCACHE Statement . . .
DOMAINNAMEPORT Statement . . . . .
FORWARDERS Statement . . . . . . .
HOSTNAMECASE Statement . . . . . .
INTERMEDIARYQUERYCACHE Statement .
INVERSEQUERYCACHE Statement . . .
LRUTIME Statement . . . . . . . . .
MSGNOH Statement . . . . . . . . .
NEGATIVECACHING Statement . . . . .
NORECURSION Statement . . . . . . .
PRIMARY Statement . . . . . . . . .
ROOTCACHE Statement. . . . . . . .
SECONDARY Statement . . . . . . . .
SMSGUSERFILE Statement . . . . . .
STANDARDQUERYCACHE Statement . .
TRACE Statement . . . . . . . . . .
UDPONLY Statement . . . . . . . . .
UDPRETRYINTERVAL Statement . . . .
Prepare the DB2 Database . . . . . . .
Define the DB2 Database . . . . . . .
Resource Records . . . . . . . . . .
Create a MASTER DATA File . . . . . .
Install the Name Server Database . . . .
Insert Data in the Database . . . . . . .
Dynamic Server Operation . . . . . . . .
SMSG Interface to the DNS Server . . . . .
SMSG CLOSECON Command . . . . .
SMSG COMMIT Command . . . . . . .
SMSG DUMP Command . . . . . . . .
SMSG FLIPTABLE Command . . . . . .
SMSG HELP Command . . . . . . . .
SMSG HINTS Command. . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
129
129
130
130
132
133
133
133
134
134
135
135
135
136
136
137
137
137
137
137
138
138
139
140
141
142
142
145
145
145
146
146
147
148
149
151
151
151
151
151
152
152
152
z/VM: TCP/IP Planning and Customization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
SMSG LEVEL Command. . . . .
SMSG LIST Command . . . . .
SMSG PURGE Command . . . .
SMSG REFRESH Command . . .
SMSG STATS Command. . . . .
SMSG STORAGE Command . . .
SMSG TRACE Command . . . .
SMSG VMDUMP Command . . .
Rebuilding the Name Server Modules
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
153
153
155
155
156
156
156
159
159
Chapter 9. Configuring the FTP Server . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . .
Step 2: Update the DTCPARMS File . . . . . . .
SRVRFTP Command . . . . . . . . . . . .
Step 3: Establish FTP Server Machine Authorizations .
Step 4: Customize the SRVRFTP CONFIG File . . .
FTP Server Configuration File Statements . . . . .
ANONYMOU Statement . . . . . . . . . . .
AUTOTRANS Statement . . . . . . . . . . .
DONTREDIRECT Statement . . . . . . . . .
FTAUDIT Statement . . . . . . . . . . . .
FTCHKCMD Statement . . . . . . . . . . .
FTCHKDIR Statement . . . . . . . . . . . .
INACTIVE Statement . . . . . . . . . . . .
LISTFORMAT Statement . . . . . . . . . . .
LOADDBCSTABLE Statement . . . . . . . . .
PORT Statement. . . . . . . . . . . . . .
RACF Statement. . . . . . . . . . . . . .
RDR Statement . . . . . . . . . . . . . .
TIMESTAMP Statement . . . . . . . . . . .
TRACE Statement . . . . . . . . . . . . .
Step 5: Configure Automatic File Translation (Optional).
Step 6: Customize FTP Server Exits (Optional) . . .
Using the FTP Welcome Banner . . . . . . . .
Using the FTP Server Exit . . . . . . . . . .
Using the CHKIPADR Exit . . . . . . . . . .
CHKIPADR Input. . . . . . . . . . . . . .
CHKIPADR Output . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . .
Dynamic Server Operation . . . . . . . . . . .
SMSG Interface to the FTP Server . . . . . . . .
Providing Web Browser FTP Support . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
161
161
161
162
162
163
163
163
164
164
165
165
165
165
166
166
167
168
168
169
169
170
171
171
171
172
173
173
173
174
175
177
Chapter 10. Configuring the IMAP Server . . . . . . . . . . . . .
Understanding IMAP . . . . . . . . . . . . . . . . . . . . .
Configuration Steps for the IMAP Server . . . . . . . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . . . . . . . . . .
Step 2: Update the DTCPARMS File . . . . . . . . . . . . . . .
IMAPMAIN Command . . . . . . . . . . . . . . . . . . . .
Step 3: Update the System (CP) Directory for the IMAP Server and Establish
Authorizations . . . . . . . . . . . . . . . . . . . . . . .
Step 4: Set Up the IMAP Mailstore SFS File Pool Server and update it’s
System (CP) Directory Entry . . . . . . . . . . . . . . . . .
Step 5: Update the $SERVER$ NAMES file . . . . . . . . . . . . .
Step 6: Customize the IMAP Configuration file . . . . . . . . . . . .
IMAP Server Configuration Statements . . . . . . . . . . . . . .
.
.
.
.
.
.
179
179
179
180
180
180
. 181
.
.
.
.
182
182
183
183
Contents
vii
BADFILEID Statement. . . . . . . . . . . .
ENROLLDEFAULTS Statement . . . . . . . .
FILEPOOLID Statement . . . . . . . . . . .
IDLETIMEOUT Statement . . . . . . . . . .
MAILORIGINID Statement . . . . . . . . . .
PORT Statement. . . . . . . . . . . . . .
READERTHREADS Statement . . . . . . . .
TIMESTAMP Statement . . . . . . . . . . .
TRACE Statement . . . . . . . . . . . . .
Step 7: Set Up SMTP to Route Mail to the IMAP server
Step 8: Enroll new Users into the IMAP Mailstore. . .
Dynamic Server Operation . . . . . . . . . . .
IMAP Server Administration Commands . . . . .
IMAPADM ALERT Command . . . . . . . . .
IMAPADM CP Command. . . . . . . . . . .
IMAPADM DELETE Command . . . . . . . .
IMAPADM ENROLL Command . . . . . . . .
IMAPADM HELP Command. . . . . . . . . .
IMAPADM MODIFY Command . . . . . . . .
IMAPADM SHUTDOWN Command . . . . . . .
IMAPADM STARTRDR Command . . . . . . .
IMAPADM STATS Command . . . . . . . . .
IMAPADM TRACE Command . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
183
183
184
184
185
185
186
186
186
187
187
187
188
188
189
189
189
190
190
191
191
191
192
Chapter 11. Configuring the Kerberos Server . . . . . . .
Kerberos Name Structures . . . . . . . . . . . . . . .
Configuring the Authentication and Remote Administration Servers
Step 1: Update PROFILE TCPIP . . . . . . . . . . . .
Step 2: Update ETC SERVICES . . . . . . . . . . . .
Step 3: Update DTCPARMS for the Authentication Server . .
Step 4: Update DTCPARMS for the Administration Server . .
Step 5: Create and Update the Kerberos System Files . . . .
Step 6: Build the Kerberos Database . . . . . . . . . .
Step 7: Store the Master Password . . . . . . . . . . .
Step 8: Start the Kerberos Servers . . . . . . . . . . .
Setting Up a Kerberos Service or Client Application . . . . . .
Setting Up a Kerberos Service Application . . . . . . . .
Setting Up a Client Application. . . . . . . . . . . . .
Verifying the Kerberos Configuration . . . . . . . . . . .
Step 1: Set Up the Environment . . . . . . . . . . . .
Step 2: Register the Sample Service and the User . . . . .
Step 3: Generate the Key File for the Sample Service . . . .
Step 4: Transfer the Key File to the Server . . . . . . . .
Step 5: Start the Sample Server . . . . . . . . . . . .
Step 6: Get the Initial Ticket. . . . . . . . . . . . . .
Step 7: Run the Sample Client Program . . . . . . . . .
Administrative Commands for the Kerberos Database . . . . .
EXT_SRVT Command. . . . . . . . . . . . . . . . .
KADMIN Command. . . . . . . . . . . . . . . . . .
KDB_DEST Command . . . . . . . . . . . . . . . .
KDB_EDIT Command . . . . . . . . . . . . . . . . .
KDB_INIT Command . . . . . . . . . . . . . . . . .
KDB_UTIL Command . . . . . . . . . . . . . . . . .
KSTASH Command. . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
193
193
194
194
194
195
195
195
197
197
197
198
198
199
199
200
200
201
201
202
202
202
203
203
204
205
206
207
208
209
Chapter 12. Configuring the LPD Server . . . . . . . . . . . . . . 211
viii
z/VM: TCP/IP Planning and Customization
Step 1: Update PROFILE TCPIP . . . .
Step 2: Update the DTCPARMS File . .
LPD Command . . . . . . . . .
Step 3: Customize the LPD CONFIG File.
Defining LP Services . . . . . . . .
LPD Configuration File Statements . . .
DEBUG Statement . . . . . . . .
OBEY Statement. . . . . . . . .
SMTP Statement. . . . . . . . .
SERVICE Statement . . . . . . .
Type of Service Statements . . . . . .
LOCAL Statement . . . . . . . .
REMOTE Statement . . . . . . .
RSCS Statement. . . . . . . . .
Optional Service Statements . . . . .
EXIT Statement . . . . . . . . .
FAILEDJOB Statement . . . . . .
FILTERS Statement . . . . . . .
LINESIZE Statement . . . . . . .
PAGESIZE Statement . . . . . . .
RACF Statement. . . . . . . . .
TRANSLATETABLE Statement . . .
Dynamic Server Operation . . . . . .
SMSG Interface to the LPD Server . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
211
211
212
212
213
213
213
213
214
214
214
215
215
215
217
217
217
218
219
219
219
220
220
220
Chapter 13. Configuring the MPROUTE Server. . .
Understanding MPROUTE . . . . . . . . . . .
Open Shortest Path First (OSPF). . . . . . . .
Routing Information Protocol (RIP) . . . . . . .
Configuration Steps for the MPROUTE Server . . . .
Step 1: Update PROFILE TCPIP . . . . . . . .
Step 2: Update the ETC SERVICES file . . . . .
Step 3: Create the MPROUTE Configuration File . .
Step 4: Update the DTCPARMS File (Optional) . .
MPROUTE Command . . . . . . . . . . . . .
Dynamic Server Operation . . . . . . . . . . .
SMSG Interface to the MPROUTE Server . . . . .
OSPF Configuration Statements . . . . . . . . .
AREA Statement . . . . . . . . . . . . . .
COMPARISON Statement . . . . . . . . . .
OSPF_INTERFACE Statement . . . . . . . .
VIRTUAL_LINK Statement . . . . . . . . . .
ROUTERID Statement . . . . . . . . . . .
AS_BOUNDARY_ROUTING Statement . . . . .
RANGE Statement . . . . . . . . . . . . .
DEMAND_CIRCUIT Statement . . . . . . . .
RIP Configuration Statements . . . . . . . . . .
ORIGINATE_RIP_DEFAULT Statement . . . . .
RIP_INTERFACE Statement . . . . . . . . .
ACCEPT_RIP_ROUTE Statement . . . . . . .
Common Configuration Statements for RIP and OSPF .
DEFAULT_ROUTE Statement . . . . . . . . .
INTERFACE Statement . . . . . . . . . . .
OSPF Routing Summary . . . . . . . . . . . .
Designated Router . . . . . . . . . . . . .
Configuring OSPF . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
223
223
224
225
226
227
227
228
228
229
229
230
230
231
232
232
237
238
239
240
241
241
241
242
246
246
246
247
249
250
251
Contents
ix
OSPF Router IDs . . . . . . . . . . .
Define Backbone and Attached OSPF Areas . .
Define OSPF Interfaces . . . . . . . . . .
OSPF Domain Topology . . . . . . . . .
Costs for OSPF Links . . . . . . . . . .
Changing the Cost of OSPF Links . . . . .
Interactions Between Neighbor Routers . . .
Set Non-Broadcast Network Interface Parameters
Configuring Wide Area Subnetworks . . . . .
Configuring Point-to-Multipoint Subnetworks. .
Configuring NBMA Subnetworks . . . . . .
Enabling Autonomous System Boundary Routing .
Configuring OSPF over ATM . . . . . . . .
Configuring OSPF Over Native ATM . . . . .
Other Configuration Tasks . . . . . . . . .
Setting Virtual Links . . . . . . . . . .
Configuring for Routing Protocol Comparisons .
Demand Circuit . . . . . . . . . . . .
Request Hello Suppression . . . . . . . .
PP_Poll_Interval . . . . . . . . . . . .
Converting from RIP to OSPF . . . . . . . .
x
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
251
251
254
254
255
255
255
256
256
257
257
258
258
258
259
259
259
260
260
260
261
Chapter 14. Configuring the NDB Servers . . . . . . . .
Step 1: Define Additional NDB Agent Servers (Optional) . . . .
Step 2: Update PROFILE TCPIP . . . . . . . . . . . . .
Step 3: Update the DTCPARMS File . . . . . . . . . . .
NDB Port Manager . . . . . . . . . . . . . . . . .
NDB Agent Servers . . . . . . . . . . . . . . . . .
PORTSRVS Command . . . . . . . . . . . . . . . .
PORTCLNT Command . . . . . . . . . . . . . . . .
Step 4: Provide NDB Agents Access to DB2 Server for VSE & VM
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
263
263
264
264
264
264
264
265
265
Chapter 15. Configuring the NFS Server . . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . . . . . .
Step 2: Update the DTCPARMS File . . . . . . . . . . .
VMNFS Command . . . . . . . . . . . . . . . . .
Using an External Security Manager . . . . . . . . . .
Step 3: Establish NFS Server Machine Authorizations . . . . .
Step 4: Customize the VMNFS CONFIG File . . . . . . . .
NFS Configuration File Statements . . . . . . . . . . . .
Syntax Rules . . . . . . . . . . . . . . . . . . .
DUMPMOUNT Statement . . . . . . . . . . . . . . .
EXPORT Statement . . . . . . . . . . . . . . . . .
EXPORTONLY Statement . . . . . . . . . . . . . . .
MAXTCPUSERS Statement. . . . . . . . . . . . . . .
PCNFSD Statement . . . . . . . . . . . . . . . . .
VMFILETYPE Statement . . . . . . . . . . . . . . . .
Step 5: Configure NFS Server File Translation Support (Optional).
Step 6: Verify NFS Server Operations . . . . . . . . . . .
Step 7: Advanced Configuration Considerations . . . . . . .
NFS Server Exits . . . . . . . . . . . . . . . . .
Managing Translation Tables . . . . . . . . . . . . .
Allowing Access to Migrated SFS and BFS Files . . . . . .
Managing Data Transfer Operations. . . . . . . . . . .
Managing File Handle Operations . . . . . . . . . . .
Using Additional Security Capabilities . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
267
267
267
268
269
269
269
270
270
271
271
273
273
274
275
275
276
277
277
282
282
283
284
285
z/VM: TCP/IP Planning and Customization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Dynamic Server Operation . . . . . . . . . . . . . . . . . . . . 286
SMSG Interface to the NFS Server . . . . . . . . . . . . . . . . . 287
Chapter 16. Configuring the Portmapper
Step 1: Update PROFILE TCPIP . . . .
Step 2: Update the DTCPARMS File . .
PORTMAP Command . . . . . . .
Step 3: Verify Portmapper Services . . .
Server
. . .
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
289
289
289
290
290
Chapter 17. Configuring the REXEC Server . . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . . . . . . .
Step 2: Update the DTCPARMS File . . . . . . . . . . . .
Step 3: Define Additional Anonymous REXEC Agent Virtual Machines
(Optional) . . . . . . . . . . . . . . . . . . . . .
Using an External Security Manager . . . . . . . . . . . .
REXECD Command . . . . . . . . . . . . . . . . . .
Additional REXEC Considerations . . . . . . . . . . . . .
How the REXEC Server Uses Secondary Virtual Machines . . .
Anonymous REXEC Client Processing. . . . . . . . . . .
User’s Own Virtual Machines . . . . . . . . . . . . . .
Usage Notes . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
292
292
292
293
293
293
294
294
Chapter 18. Configuring the ROUTED Server . . . . . . . .
Understanding RouteD . . . . . . . . . . . . . . . . .
Routing Information Protocol . . . . . . . . . . . . . .
RIP Version 2 . . . . . . . . . . . . . . . . . . . .
ATM Network Considerations . . . . . . . . . . . . . .
RIP Routes . . . . . . . . . . . . . . . . . . . . . .
RouteD RIP Route Types . . . . . . . . . . . . . . .
RouteD RIP Route Summary . . . . . . . . . . . . . .
RIP Input/Output Filters . . . . . . . . . . . . . . . .
Configuration Process . . . . . . . . . . . . . . . . . .
Step 1: Create the RouteD Configuration File (ROUTED CONFIG)
Step 2: Specify Configuration Statements in PROFILE TCPIP . .
Step 3: Update the ETC SERVICES file . . . . . . . . . .
Step 4: Update the DTCPARMS File (Optional) . . . . . . .
Step 5: Create the ETC GATEWAYS File (Optional) . . . . . .
ROUTED Command . . . . . . . . . . . . . . . . . .
Configuration Examples . . . . . . . . . . . . . . . . .
Configuring a Passive Route . . . . . . . . . . . . . .
Configuring an External Route . . . . . . . . . . . . . .
Configuring an Active Gateway . . . . . . . . . . . . .
Configuring a Point-to-Point Link . . . . . . . . . . . . .
Configuring a Default Route. . . . . . . . . . . . . . .
Configuring Multiple Subnets with the Same IP Address . . . .
Configuring RouteD with VIPA . . . . . . . . . . . . . .
Configuring RouteD to Split Traffic with VIPA . . . . . . . .
Configuring a Backup TCP/IP Stack with VIPA . . . . . . . .
Restoring a Primary TCP/IP Stack with VIPA . . . . . . . .
Using the SMSG Interface to RouteD . . . . . . . . . . .
RouteD SMSG Command . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
295
295
295
296
297
297
297
299
299
299
300
301
302
302
302
309
311
311
312
313
313
314
314
315
316
319
319
319
319
Chapter 19. Configuring the RSCS Print
Configuring a TN3270E Printer . . . .
Configuring an RSCS LPR Link . . . .
RSCSTCP CONFIG Configuration File.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
323
323
323
323
Contents
xi
Server
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . 291
. . . . 291
. . . . 291
Configuring a Non-Postscript Printer . . .
Available EPARMs for Non-Postscript Printers
Configuring a Postscript Printer . . . . .
Available EPARMs for Postscript Printers . .
Configuring an RSCS LPD Link . . . . . .
Available EPARMs for LPD Links . . . . .
Configuring an RSCS TN3270E Printer Link. .
TAG Command for a TN3270E printer . . . .
xii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
324
325
327
328
332
333
336
341
Chapter 20. Configuring the SMTP Server . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . . . . . .
Step 2: Update the System (CP) Directory for the SMTP Server .
Step 3: Update the DTCPARMS File . . . . . . . . . . .
SMTP Command . . . . . . . . . . . . . . . . .
Step 4: Update the TCPIP DATA File for Domain Name Resolution
Step 5: Customize the SMTP CONFIG File . . . . . . . . .
Step 6: Additional SMTP Server Considerations . . . . . . .
Use of MX Records. . . . . . . . . . . . . . . . .
Local versus Non-local Mail Recipients . . . . . . . . .
SMTP Server Configuration File Statements. . . . . . . . .
ALTRSCSDOMAIN Statement . . . . . . . . . . . . .
ALTTCPHOSTNAME Statement . . . . . . . . . . . .
BADSPOOLFILEID Statement . . . . . . . . . . . . .
DBCS Statement. . . . . . . . . . . . . . . . . .
FILESPERCONN Statement . . . . . . . . . . . . .
FINISHOPEN Statement . . . . . . . . . . . . . . .
FORWARDMAIL Statement . . . . . . . . . . . . . .
GATEWAY Statement . . . . . . . . . . . . . . . .
INACTIVE Statement . . . . . . . . . . . . . . . .
IPMAILERADDRESS Statement . . . . . . . . . . . .
LOCALFORMAT Statement . . . . . . . . . . . . . .
LOG Statement . . . . . . . . . . . . . . . . . .
MAILER Statement . . . . . . . . . . . . . . . . .
MAILHOPCOUNT Statement . . . . . . . . . . . . .
MAXCONNPERSITE Statement . . . . . . . . . . . .
MAXMAILBYTES Statement . . . . . . . . . . . . .
NOLOG Statement . . . . . . . . . . . . . . . . .
ONDISKFULL Statement . . . . . . . . . . . . . . .
OUTBOUNDOPENLIMIT Statement . . . . . . . . . . .
PORT Statement. . . . . . . . . . . . . . . . . .
POSTMASTER Statement . . . . . . . . . . . . . .
RCPTRESPONSEDELAY Statement . . . . . . . . . .
RESOLVERRETRYINT Statement . . . . . . . . . . .
RESTRICT Statement . . . . . . . . . . . . . . . .
RETRYAGE Statement . . . . . . . . . . . . . . .
RETRYINT Statement . . . . . . . . . . . . . . . .
REWRITE822HEADER Statement . . . . . . . . . . .
RSCSDOMAIN Statement . . . . . . . . . . . . . .
RSCSFORMAT Statement . . . . . . . . . . . . . .
SECURE Statement . . . . . . . . . . . . . . . .
SMSGAUTHLIST Statement . . . . . . . . . . . . .
SMTPCMDS Statement . . . . . . . . . . . . . . .
SOURCEROUTES Statement . . . . . . . . . . . . .
SUPRESSNOTIFICATION Statement . . . . . . . . . .
TEMPERRORRETRIES Statement . . . . . . . . . . .
TRACE Statement . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
345
345
345
346
346
346
347
347
347
348
348
350
350
350
351
352
353
353
354
355
355
356
356
357
358
359
359
359
360
361
361
361
362
363
363
364
364
365
365
366
366
367
367
370
371
371
372
z/VM: TCP/IP Planning and Customization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
VERIFYCLIENT Statement . . . . . . . . .
VERIFYCLIENTDELAY Statement . . . . . .
WARNINGAGE Statement . . . . . . . . .
8BITMIME Statement . . . . . . . . . . .
Step 7: Advanced Configuration Considerations . .
SMTP Server Exits . . . . . . . . . . . .
Configuring a TCP/IP-to-RSCS Mail Gateway . . .
Operands . . . . . . . . . . . . . . .
Configuring a TCP/IP-to-RSCS Secure Mail Gateway
Creating an SMTP Security Table . . . . . .
Operands . . . . . . . . . . . . . . .
Defining Nicknames and Mailing Lists . . . . . .
Customizing SMTP Mail Headers. . . . . . . .
The SMTP RULES File . . . . . . . . . .
Format of the Field Definition Section . . . . .
Format of the Rule Definition Section . . . . .
Syntax Convention of the SMTP Rules . . . .
Predefined Keywords within the SMTP Rules . . .
Default SMTP Rules . . . . . . . . . . . .
SMTP Non-Secure Gateway Configuration Defaults
SMTP Secure Gateway Configuration Defaults. .
Examples of Header Rewrite Rules . . . . . . .
Dynamic Server Operation . . . . . . . . . .
SMSG Interface to the SMTP Server . . . . .
General User SMSG Commands . . . . . . . .
Privileged User SMSG Commands . . . . . . .
Privileged User SMSG FORWARDMAIL Command .
Privileged User SMSG LISTMAIL Command . . .
Mail States . . . . . . . . . . . . . . . .
Privileged User SMSG MAILINFO Command . . .
General Envelope Information . . . . . . . . .
Privileged User SMSG PURGE Command . . . .
Privileged User SMSG REFRESH Command . . .
Privileged User SMSG REPROCESS Command . .
Privileged User SMSG SMTPCMDS Command . .
Privileged User SMSG SOURCEROUTES Command
Privileged User SMSG TRACE Command . . . .
Privileged User SMSG VERIFYCLIENT Command .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
372
374
374
375
375
375
376
376
377
378
378
380
381
382
382
384
384
386
388
388
388
389
390
390
390
391
392
393
394
395
395
397
398
398
399
402
404
405
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
Status
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
409
409
409
410
410
412
412
412
413
414
. . . . .
. . . . .
. . . . .
and SNMPD
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
417
417
418
419
420
420
Chapter 21. Configuring the SNALINK Server . . .
Install the SNALNKA Virtual Machine . . . . . . .
Step 1: Give SNALNKA Access to GCS . . . . .
Step 2: Define SNALINK Applications in VM/VTAM .
Step 3: Customize SNALNKA GCS . . . . . . .
Operating SNALINK . . . . . . . . . . . . .
Restart a Session . . . . . . . . . . . . .
Sample Console . . . . . . . . . . . . . .
Determine SNA Session Status by SNA IUCV Device
Define SNA IUCV Links . . . . . . . . . . .
Chapter 22. Configuring the SNMP Servers . .
SNMP Overview . . . . . . . . . . . . .
Step 1: Update PROFILE TCPIP . . . . . . .
Step 2: Update the DTCPARMS File for SNMPQE
SNMP Query Engine . . . . . . . . . . .
Step 3: Define the MIB Data File . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
xiii
Step 4: Configure the SNMP/NetView Interface
SNMPIUCV. . . . . . . . . . . . .
SNMP Command Processor . . . . . .
SNMP Messages . . . . . . . . . .
SNMPIUCV Initialization Parameters . . .
Configure the SNMP Daemon . . . . . .
TRAP Destination file . . . . . . . . . .
PW SRC File . . . . . . . . . . . .
Installation Steps. . . . . . . . . . . .
SNMP Command Processor and SNMPIUCV
SNMP Daemon . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
NetView
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
422
422
422
422
423
424
424
425
427
427
428
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
429
429
430
431
431
433
433
433
433
434
434
434
438
439
439
440
441
441
446
446
446
447
448
448
450
Chapter 24. Configuring the TCP/IP Server . .
TCPIP Virtual Machine Configuration Process . .
Step 1: Update the DTCPARMS File . . . .
Step 2: Create an Initial Configuration File . .
TCP/IP Configuration Statements. . . . . .
Summary of TCP/IP Configuration Statements .
ACBPOOLSIZE Statement . . . . . . . . .
ADDRESSTRANSLATIONPOOLSIZE Statement .
ARPAGE Statement . . . . . . . . . . .
ASSORTEDPARMS Statement . . . . . . .
ATMARPSERVER Statement . . . . . . . .
ATMLIS Statement . . . . . . . . . . . .
ATMPVC Statement . . . . . . . . . . .
AUTOLOG Statement . . . . . . . . . . .
BLOCK Statement . . . . . . . . . . . .
BSDROUTINGPARMS Statement . . . . . .
CCBPOOLSIZE Statement . . . . . . . . .
DATABUFFERLIMITS Statement . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
453
453
453
453
465
466
468
469
470
470
475
476
477
477
478
479
482
483
Chapter 23. Configuring the SSL Server .
Overview of an SSL Session . . . . . .
Step 1: Update PROFILE TCPIP . . . . .
Step 2: Update the DTCPARMS File . . .
VMSSL Command . . . . . . . . .
Step 3: Update ETC SERVICES . . . . .
Step 4: Set Up the Certificate Database . .
Step 4a: Start the SSL Server . . . . .
Step 4b: Populate the Certificate Database
Step 4c: Designate the Secure Ports . .
Dynamic Server Operation . . . . . . .
Certificate Database Administration . . .
SSL Server Administration . . . . . .
SSL Server Administration Commands . . .
SSLADMIN DELETE Command . . . . .
SSLADMIN EXPORT Command . . . . .
SSLADMIN LOG Command. . . . . . .
SSLADMIN QUERY Command . . . . .
SSLADMIN REGENERATE Command. . .
SSLADMIN REMOVE Command . . . . .
SSLADMIN REQUEST Command . . . .
SSLADMIN SELF Command . . . . . .
SSLADMIN STOP Command . . . . . .
SSLADMIN STORE Command . . . . .
SSLADMIN TRACE/NOTRACE Command .
xiv
z/VM: TCP/IP Planning and Customization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
on
.
|
|
|
|
DATABUFFERPOOLSIZE Statement . . . . . . . . . . . .
DEVICE and LINK Statement — ATM Devices . . . . . . . . .
DEVICE and LINK Statement — CTC Devices . . . . . . . . .
DEVICE and LINK Statement — HiperSockets Connection . . . .
DEVICE and LINK Statement — HYPERchannel A220 Devices . .
DEVICE and LINK Statement — Integrated Communication Adapters
DEVICE and LINK Statement — Local IUCV Connections . . . .
DEVICE and LINK Statement — Remote IUCV Connections . . .
DEVICE and LINK Statement — LCS Devices . . . . . . . . .
DEVICE and LINK Statement — Offload Hosts . . . . . . . .
DEVICE and LINK Statement — OSD Devices. . . . . . . . .
DEVICE and LINK Statement — RISC System/6000 IP Connections
DEVICE and LINK Statement — SNA LU0 Links . . . . . . . .
DEVICE and LINK Statement — Virtual Devices (VIPA) . . . . .
DEVICE and LINK Statement — X.25 NPSI Connections . . . . .
ENVELOPEPOOLSIZE Statement . . . . . . . . . . . . .
FILE Statement . . . . . . . . . . . . . . . . . . . .
FIXEDPAGESTORAGEPOOL . . . . . . . . . . . . . . .
GATEWAY Statement . . . . . . . . . . . . . . . . . .
HOME Statement . . . . . . . . . . . . . . . . . . .
INFORM Statement. . . . . . . . . . . . . . . . . . .
INTERNALCLIENTPARMS Statement . . . . . . . . . . . .
IPROUTEPOOLSIZE Statement . . . . . . . . . . . . . .
KEEPALIVEOPTIONS Statement. . . . . . . . . . . . . .
LARGEENVELOPEPOOLSIZE Statement . . . . . . . . . .
LESSTRACE Statement . . . . . . . . . . . . . . . . .
MAXRESTART Statement . . . . . . . . . . . . . . . .
MONITORRECORDS Statement . . . . . . . . . . . . . .
MORETRACE Statement. . . . . . . . . . . . . . . . .
NOSCREEN Statement . . . . . . . . . . . . . . . . .
NOTRACE Statement . . . . . . . . . . . . . . . . . .
OBEY Statement. . . . . . . . . . . . . . . . . . . .
PENDINGCONNECTIONLIMIT Statement . . . . . . . . . .
PERMIT Statement . . . . . . . . . . . . . . . . . . .
PORT Statement. . . . . . . . . . . . . . . . . . . .
PRIMARYINTERFACE Statement . . . . . . . . . . . . .
RCBPOOLSIZE Statement . . . . . . . . . . . . . . . .
RESTRICT Statement . . . . . . . . . . . . . . . . . .
SCBPOOLSIZE Statement . . . . . . . . . . . . . . . .
SCREEN Statement . . . . . . . . . . . . . . . . . .
SKCBPOOLSIZE Statement . . . . . . . . . . . . . . .
SMALLDATABUFFERPOOLSIZE Statement. . . . . . . . . .
START Statement . . . . . . . . . . . . . . . . . . .
STOP Statement . . . . . . . . . . . . . . . . . . . .
SYSCONTACT Statement . . . . . . . . . . . . . . . .
SYSLOCATION Statement . . . . . . . . . . . . . . . .
TCBPOOLSIZE Statement . . . . . . . . . . . . . . . .
TIMESTAMP Statement . . . . . . . . . . . . . . . . .
TINYDATABUFFERPOOLSIZE Statement . . . . . . . . . .
TN3270E Statement . . . . . . . . . . . . . . . . . .
TRACE Statement . . . . . . . . . . . . . . . . . . .
TRACEONLY Statement . . . . . . . . . . . . . . . . .
TRANSLATE Statement . . . . . . . . . . . . . . . . .
UCBPOOLSIZE Statement . . . . . . . . . . . . . . . .
Changing the TCP/IP Configuration with the IFCONFIG Command .
IFCONFIG Command . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
484
485
486
487
489
490
493
494
495
498
501
505
507
508
509
511
512
512
514
523
526
527
532
533
533
535
535
536
537
538
538
539
540
541
542
544
545
546
547
548
548
549
550
550
551
551
552
553
553
554
555
556
557
559
560
560
xv
Changing the TCP/IP Configuration with the OBEYFILE Command . . . . . 571
OBEYFILE Command . . . . . . . . . . . . . . . . . . . . . . 571
Starting and Stopping TCP/IP Services . . . . . . . . . . . . . . . 573
xvi
Chapter 25. Configuring the TFTP Server . . . . .
Step 1: Update PROFILE TCPIP . . . . . . . . .
MTU Considerations . . . . . . . . . . . .
Step 2: Update the DTCPARMS File . . . . . . .
TFTPD Command . . . . . . . . . . . . .
Step 3: Additional TFTPD Configuration Considerations
Restricting TFTP Access to Files . . . . . . . .
Changing the TFTP Server BFS Directory Default .
Controlling TFTP Server Data Translation . . . .
Collecting TFTP Server Monitor Data . . . . . .
Step 4: Create the TFTPD PERMLIST Data File . . .
Step 5: Create the TFTPD USERLIST Data File . . .
Dynamic Server Operation . . . . . . . . . . .
TFTPD Subcommands . . . . . . . . . . . .
CACHE Subcommand . . . . . . . . . . . . .
CLIENTS Subcommand . . . . . . . . . . . .
CMS Subcommand . . . . . . . . . . . . . .
CREATION Subcommand . . . . . . . . . . .
DROPFILE Subcommand . . . . . . . . . . .
EXIT Subcommand . . . . . . . . . . . . . .
HELP Subcommand . . . . . . . . . . . . .
LIGHT Subcommand . . . . . . . . . . . . .
LOADPERM Subcommand . . . . . . . . . . .
LOADUSER Subcommand . . . . . . . . . . .
QUIT Subcommand. . . . . . . . . . . . . .
STAYUP Subcommand . . . . . . . . . . . .
STOP Subcommand . . . . . . . . . . . . .
TRACE Subcommand . . . . . . . . . . . . .
XFERMODE Subcommand . . . . . . . . . . .
TFTPD File Access Control . . . . . . . . . . .
TFTP Server APPLDATA Monitor Records . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
575
575
575
576
576
578
578
578
578
578
578
579
579
580
580
581
582
583
584
584
585
585
585
586
586
587
587
587
588
588
589
Chapter 26. Configuring the UFT Server . .
Step 1: Update PROFILE TCPIP . . . . . .
Step 2: Update the DTCPARMS File . . . .
UFTD Command. . . . . . . . . . . .
Step 3: Update the TCPIP DATA File . . . .
Step 4: Customize the UFTD CONFIG File . .
UFT Configuration File Statements . . . . .
IDENTIFY Statement . . . . . . . . . .
MAXFILEBYTES Statement. . . . . . . .
NSLOOKUP Statement . . . . . . . . .
PORT Statement. . . . . . . . . . . .
TRACE Statement . . . . . . . . . . .
TRANSLATE Statement . . . . . . . . .
UFTCMDS EXIT Statement . . . . . . . .
Step 5: Advanced Configuration Considerations
DNS Lookup Exit . . . . . . . . . .
Protocol Commands Exit . . . . . . . .
Dynamic Server Operation . . . . . . . .
UFTD Subcommands . . . . . . . . . .
IDENTIFY Subcommand . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
593
593
593
593
594
594
594
594
595
595
596
597
597
598
599
599
600
601
601
601
z/VM: TCP/IP Planning and Customization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
NSLOOKUP Subcommand . . .
QUERY Subcommand. . . . .
QUIT Subcommand. . . . . .
STOP Subcommand . . . . .
TRACE Subcommand . . . . .
UFTCMDS EXIT Subcommand .
UFT Clients and Servers for Other
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
Platforms
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
602
603
603
603
604
605
606
Chapter 27. Configuring the RSCS UFT Client . . . .
Step 1: Update the RSCSTCP CONFIG Configuration File
UFT Client LINKDEFINE and PARM Statements . . .
Operands . . . . . . . . . . . . . . . . .
Step 2: Update the RSCSUFT CONFIG Configuration File
Step 3: Update the TCPIP DATA File . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
607
607
607
608
608
609
Chapter 28. Configuring the X.25 Interface .
Installing the X.25 Interface . . . . . . . .
Step 1: Give X25IPI Access to GCS. . . .
Step 2: Define X25IPI to VM/VTAM . . . .
Step 3: Customize the X25IPI CONFIG File .
Step 4: Customize X25IPI GCS . . . . .
X25IPI Commands . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
611
611
611
611
616
617
618
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 29. X Window System Graphical Data Display Manager Support
621
X Window System GDDM Support . . . . . . . . . . . . . . . . . 621
X Window System GDDM Interface Files . . . . . . . . . . . . . . 621
Installing the X Window System GDDM Interface . . . . . . . . . . . 621
Chapter 30. Using Translation Tables . .
Character Sets and Code Pages . . . . .
TCP/IP Translation Table Files . . . . . .
Translation Table Search Order . . . . .
Special Telnet Requirements . . . . .
IBM-Supplied Translation Tables . . . . .
Customizing SBCS Translation Tables . . .
Syntax Rules for SBCS Translation Tables
Customizing DBCS Translation Tables . . .
DBCS Translation Table . . . . . . .
Syntax Rules for DBCS Translation Tables
Sample DBCS Translation Tables . . .
Converting Translation Tables to Binary . .
The CONVXLAT Command . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
623
623
624
624
625
626
628
629
629
629
630
630
632
632
Chapter 31. Testing and Verification .
Loopback Testing . . . . . . . .
TCP/IP Checksum Testing . . . . .
CHECKSUM Statement . . . . .
NOCHECKSUM Statement . . . .
TCP/IP Datagram Dropping . . . . .
DROP Statement . . . . . . .
NODROP Statement . . . . . .
SEED Statement. . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
635
635
635
635
635
636
636
636
637
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 32. Using Source Code Libraries. . . . . . . . . . . . . . 639
VMFASM EXEC, VMFHASM EXEC, and VMFHLASM EXEC . . . . . . . 639
VMFPAS EXEC . . . . . . . . . . . . . . . . . . . . . . . . 639
Contents
xvii
VMFC EXEC . . . .
TCPTXT EXEC . . .
TCPLOAD EXEC . .
TCPCOMP EXEC . .
Special Considerations
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Appendix A. Using TCP/IP with an External
Security Interfaces . . . . . . . . . .
Server Initialization . . . . . . . . .
Client Authentication . . . . . . . .
Resource Access . . . . . . . . .
The DTCPARMS File . . . . . . . .
Minidisk Security . . . . . . . . . . .
Using TCP/IP with RACF. . . . . . . .
FTPPERM and NFSPERM . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Security
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
640
641
641
643
643
Manager
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
645
645
646
646
646
647
648
648
649
Appendix B. Related Protocol Specifications . . . . . . . . . . . . 651
Appendix C. Abbreviations and Acronyms . . . . . . . . . . . . . 655
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Programming Interface Information . . . . . . . . . . . . . . . . . 660
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 661
Glossary
. . . . . . . . . . . . . . . . . . . . . . . . . . 663
Bibliography . . . . . . . . . . .
z/VM Internet Library . . . . . . . .
VM Collection CD-ROM . . . . . . .
z/VM Base Publications . . . . . . .
Evaluation . . . . . . . . . . .
Installation and Service . . . . . .
Planning and Administration. . . . .
Customization . . . . . . . . . .
Operation . . . . . . . . . . .
Application Programming. . . . . .
End Use . . . . . . . . . . . .
Diagnosis . . . . . . . . . . .
Publications for z/VM Additional Facilities .
DFSMS/VM® . . . . . . . . . .
Language Environment® . . . . . .
OSA/SF . . . . . . . . . . . .
TCP/IP for z/VM . . . . . . . . .
Publications for z/VM Optional Features .
DirMaint™ . . . . . . . . . . .
PRF . . . . . . . . . . . . .
RTM . . . . . . . . . . . . .
RACF® for VM . . . . . . . . .
Other TCP/IP Related Publications . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
681
681
681
681
681
681
681
681
681
681
682
682
682
682
682
682
683
683
683
683
683
683
683
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
xviii
z/VM: TCP/IP Planning and Customization
Preface
TCP/IP Planning and Customization describes how to plan the installation and
perform the configuration of the IBM Transmission Control Protocol/Internet Protocol
(TCP/IP Level 430) for z/VM.
This book describes how to define and configure the virtual machines, servers, and
applications available in TCP/IP. This book also describes how to customize and
tune TCP/IP for your specific needs.
Who Should Read This Book
This book is intended for system administrators to help in planning for TCP/IP
networks on a z/VM host, and in customizing TCP/IP to their systems.
What You Should Know before Reading This Book
This book assumes that you are familiar with z/VM and its components, Control
Program (CP) and the Conversational Monitor System (CMS).
What This Book Contains
This book describes all applications available with TCP/IP Level 430; however, your
organization may use only some of these functions.
Chapter 1, “Planning Considerations” on page 1, describes how to plan the
installation and customization of TCP/IP Level 430.
Chapter 2, “System Requirements for TCP/IP” on page 11, describes the hardware,
software, storage, and library requirements needed to install TCP/IP.
Chapter 3, “Defining the TCP/IP System Parameters” on page 15, describes the
syntax for the configuration commands used in the TCPIP DATA file.
Chapter 4, “Configuring the HOSTS LOCAL File” on page 27, describes how to
specify local host entries in the TCP/IP host site table.
Chapter 5, “General TCP/IP Server Configuration” on page 31, describes virtual
machine definitions and methods of customizing servers for use with TCP/IP.
Chapter 6, “Configuring the BOOTP Server” on page 49, describes how to configure
the BOOTPD Virtual Machine.
Chapter 7, “Configuring the DHCP Server” on page 65, describes how to configure
the DHCPD Virtual Machine.
Chapter 8, “Configuring the DNS Server” on page 129 describes the configuration
parameters, how to define the DB2 for VM database, and how to install the
database.
Chapter 9, “Configuring the FTP Server” on page 161, describes how to configure
the FTP server and how to use the options available when configuring the server.
© Copyright IBM Corp. 1987, 2002
xix
Chapter 10, “Configuring the IMAP Server” on page 179, describes how to configure
the IMAP Virtual Machine.
Chapter 11, “Configuring the Kerberos Server” on page 193, describes how to
configure the Kerberos authentication and administration servers, describes the
administration functions and commands, and provides a list of the messages
produced by the server.
Chapter 12, “Configuring the LPD Server” on page 211, describes how to configure
the LPSERVE Virtual Machine.
Chapter 13, “Configuring the MPROUTE Server” on page 223, explains the
MPROUTE use of the OSPF protocol and configuration parameters.
Chapter 14, “Configuring the NDB Servers” on page 263, describes how to
configure the Network Database (NDB) System.
Chapter 15, “Configuring the NFS Server” on page 267, describes how to configure
the VMNFS Virtual Machine.
Chapter 16, “Configuring the Portmapper Server” on page 289, describes how to
configure the PORTMAP Virtual Machine.
Chapter 17, “Configuring the REXEC Server” on page 291, describes how to
configure the REXECD Virtual Machine.
Chapter 18, “Configuring the ROUTED Server” on page 295 gives a brief description
of the Routing Information Protocol (RIP) and describes the files used in configuring
the RouteD server.
Chapter 19, “Configuring the RSCS Print Server” on page 323, describes how to
configure the RSCS printer server.
Chapter 20, “Configuring the SMTP Server” on page 345, describes the syntax of
the configuration statements used in setting up the Simple Mail Transfer Protocol
(SMTP) server.
Chapter 21, “Configuring the SNALINK Server” on page 409, describes how to
configure and operate the SNA LU type 0 Virtual Machine.
Chapter 22, “Configuring the SNMP Servers” on page 417, describes how to
configure the SNMPQE and SNMPD Virtual Machines.
Chapter 23, “Configuring the SSL Server” on page 429, describes how to configure
the Secure Socket Layer (SSL) server, how to set up the certificate database, and
how to do certificate database and SSL server administration.
Chapter 24, “Configuring the TCP/IP Server” on page 453, describes the syntax of
TCP/IP protocol stack configuration statements.
Chapter 25, “Configuring the TFTP Server” on page 575, describes how to configure
the TFTPD Virtual Machine.
Chapter 26, “Configuring the UFT Server” on page 593, describes an asynchronous
UFT support.
xx
z/VM: TCP/IP Planning and Customization
Chapter 27, “Configuring the RSCS UFT Client” on page 607, describes how to
configure the UFT server.
Chapter 28, “Configuring the X.25 Interface” on page 611, describes how to
configure the X25IPI interface.
Chapter 29, “X Window System Graphical Data Display Manager Support” on
page 621, describes how to install the interface for X Window System GDDM®
support.
Chapter 30, “Using Translation Tables” on page 623, describes how to customize
the translation tables supplied with TCP/IP.
Chapter 31, “Testing and Verification” on page 635, describes how to test and debug
TCP/IP.
Chapter 32, “Using Source Code Libraries” on page 639, describes how to maintain
the source code libraries for TCP/IP.
Appendix A, “Using TCP/IP with an External Security Manager” on page 645, shows
how RACF® offers effective user verification, resource authorization, and logging
capabilities for TCP/IP.
Appendix B, “Related Protocol Specifications” on page 651, contains a list of some
of the Related Protocol Specifications used in TCP/IP.
Appendix C, “Abbreviations and Acronyms” on page 655, lists the abbreviations and
acronyms that are used throughout this book.
This book also includes a glossary, a bibliography, and an index.
How the Term “internet” Is Used in This Book
In this book, an internet is a logical collection of networks supported by routers,
gateways, bridges, hosts, and various layers of protocols, which permit the network
to function as a large, virtual network.
Note: The term “internet” is used as a generic term for a TCP/IP network, and
should not be confused with the Internet, which consists of large national
backbone networks (such as MILNET, NSFNet, and CREN) and a myriad of
regional and local campus networks worldwide.
Understanding Syntax Diagrams
This section describes how to read the syntax diagrams in this book.
Getting Started: To read a syntax diagram, follow the path of the line. Read from
left to right and top to bottom.
v The ─── symbol indicates the beginning of a syntax diagram.
v The ─── symbol, at the end of a line, indicates that the syntax diagram
continues on the next line.
v The ─── symbol, at the beginning of a line, indicates that a syntax diagram
continues from the previous line.
v The ─── symbol indicates the end of a syntax diagram.
Preface
xxi
Syntax items (for example, a keyword or variable) may be:
v Directly on the line (required)
v Above the line (default)
v Below the line (optional).
Syntax Diagram Description
Example
Abbreviations:
Uppercase letters denote the
shortest acceptable abbreviation. If
an item appears entirely in
uppercase letters, it cannot be
abbreviated.
KEYWOrd
You can type the item in uppercase
letters, lowercase letters, or any
combination.
In this example, you can enter
KEYWO, KEYWOR, or KEYWORD
in any combination of uppercase
and lowercase letters.
Symbols:
You must code these symbols
exactly as they appear in the
syntax diagram.
*
Asterisk
:
Colon
,
Comma
=
Equal Sign
-
Hyphen
()
Parentheses
.
Period
Variables:
Highlighted lowercase items (like
this) denote variables.
KEYWOrd var_name
repeat
In this example, var_name
represents a variable you must
specify when you code the
KEYWORD command.
Repetition:
An arrow returning to the left
means that the item can be
repeated.
xxii
z/VM: TCP/IP Planning and Customization
Syntax Diagram Description
A character within the arrow means
you must separate repeated items
with that character.
A footnote (1) by the arrow
references a limit that tells how
many times the item can be
repeated.
Example
,
repeat
(1)
repeat
Notes:
1
Specify repeat up to 5 times.
Required Choices:
When two or more items are in a
stack and one of them is on the
line, you must specify one item.
A
B
C
In this example, you must choose
A, B, or C.
Optional Choice:
When an item is below the line, the
item is optional. In this example,
you can choose A or nothing at all.
When two or more items are in a
stack below the line, all of them are
optional. In this example, you can
choose A, B, C, or nothing at all.
A
A
B
C
Defaults:
Defaults are above the line. The
system uses the default unless you override it. You can override the
default by coding an option from
the stack below the line.
A
B
C
In this example, A is the default.
You can override A by choosing B
or C.
Preface
xxiii
Syntax Diagram Description
Example
Repeatable Choices:
A stack of items followed by an
arrow returning to the left means
that you can select more than one
item or, in some cases, repeat a
single item.
A
B
C
In this example, you can choose
any combination of A, B, or C.
Syntax Fragments:
Some diagrams, because of their
length, must fragment the syntax.
The fragment name appears
between vertical bars in the
diagram. The expanded fragment
appears in the diagram after a
heading with the same fragment
name.
A Fragment
A Fragment:
A
B
C
In this example, the fragment is
named “A Fragment.”
Where to Find More Information
Appendix C, “Abbreviations and Acronyms” on page 655, lists the abbreviations and
acronyms that are used throughout this book.
The “Glossary” on page 663, defines terms used throughout this book that are
associated with TCP/IP communication in an internet environment.
For more information about related publications, see the books listed in the
“Bibliography” on page 681.
|
PDF Links to Other Books
The PDF version of this book provides links to other IBM books by file name. The
name of the PDF file for an IBM book is unique and identifies the book and its
edition. The book links provided in this book are for the editions (PDF file names)
that were current when this PDF file was generated. Newer editions of some books
(with different file names) may exist. A PDF link from this book to another book
works only when a PDF file with the requested file name resides in the same
directory as this book.
|
|
|
|
|
|
|
How to Send Your Comments to IBM
Your feedback is important in helping us to provide the most accurate and
high-quality information. If you have comments about this book or any other VM
documentation, send your comments to us using one of the following methods. Be
sure to include the name of the book, the publication number (including the suffix),
and the page, section title, or topic you are commenting on.
v Visit the z/VM web site at:
http://www.ibm.com/eserver/zseries/zvm/
xxiv
z/VM: TCP/IP Planning and Customization
There you will find the feedback page where you can enter and submit your
comments.
v Send your comments by electronic mail to one of the following addresses:
Internet:
[email protected]
™
GDLVME(PUBRCF)
IBMLink :
v Fill out the Readers’ Comments form at the back of this book and return it by
mail, by fax (1–607–752–2327), or by giving it to an IBM representative. If the
form is missing, you can mail your comments to the following address:
IBM Corporation
Information Development
Department G60G
1701 North Street
Endicott, New York 13760-5553
USA
Preface
xxv
xxvi
z/VM: TCP/IP Planning and Customization
Summary of Changes
This section describes the technical changes made in this edition of the book and in
previous editions. For your convenience, the changes made in this edition are
identified in the text by a vertical bar (|) in the left margin. This edition may also
include minor corrections and editorial changes that are not identified.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Second Edition for z/VM Version 4 (May 2002)
This edition contains updates for the General Availability of TCP/IP Level 430.
TCP/IP Stack Performance
A new option EQUALCOSTMULTIPATH on the ASSORTEDPARMS statement has
been added. This allows the stack to take advantage of the equal-cost multipath
feature enabling load balance. This improves the performance of the z/VM TCP/IP
stack by optimizing high-use paths.
TCP/IP Device Support
UNICAST and MULTICAST options have been added to the LINK statement for a
HiperSockets Connection. Broadcast will be enabled for OSD devices that have
broadcast capability.
TCP/IP Stack Vulnerability Reduction
Function has been added to improve the performance and reliability of the TCP/IP
stack by preventing more Denial-of-Service (DoS) attacks. These attacks include:
v Kiss-of-Death (KOD) — an IGMP based attack that depletes the stack’s large
envelopes
v KOX — a version of the KOD attack that also has source IP address spoofing
v Stream — an attack in which TCP packets are sent to the stack with no header
flags set
v R4P3D — an augmented version of the Stream attack
v Blat — a version of the Land attack that also has the URG flag turned on in the
TCP header and has the ability to incrementally spoof the source IP address
v SynFlood — an attack in which the initiator floods the TCP/IP stack with SYN
packets that have spoofed source IP addresses, resulting in the server never
receiving the final ACKs needed to complete the three-way handshake in the
connection process.
Not receiving the final ACK results in a half-open connection. A new TCP/IP
configuration statement, PENDINGCONNECTIONLIMIT, has been added and can
be used to define the maximum number of half-open connections that are
allowed at any given time.
The Smurf DoS attack has also been updated to address three variants of the
attack. Smurf is a DoS attack in which an ICMP Echo Request is sent to a
broadcast or multicast address. The three variants are:
v Smurf-IC — where ″IC″ denotes that incoming packets are using the TCP/IP
stack to launch an attack
v Smurf-OB — where ″OB″ denotes that an outbound ICMP Echo Request
matched the description of a Smurf attack
v Smurf-RP — where ″RP″ denotes that ICMP Echo Reply packets being received
by the stack do not match any Echo Requests that were sent.
© Copyright IBM Corp. 1987, 2002
xxvii
|
TCP/IP Dynamic Stack Configuration [4.3.0]
|
|
|
|
Authorized users now can define, change or display the TCP/IP configuration
dynamically. These changes are temporary and are discarded when the z/VM
TCP/IP stack virtual machine is restarted. This support involves the following
commands:
|
|
|
IFCONFIG
Added with z/VM 4.3.0; refer to “IFCONFIG Command” on page 560 for
more information.
|
|
|
|
NETSTAT DEVLINKS
Updated to display additional information about the devices and links
defined for the TCPIP virtual machine; refer to z/VM: TCP/IP Level 430
User’s Guide for more information.
|
|
|
|
QUERY (Real Device)
Updated with a new operand, ID, which displays the sense ID information
returned by a device and its control unit; refer to z/VM: CP Command and
Utility Reference for more information.
|
|
|
The IFCONFIG command can also be used to generate syntactically-correct
configuration statements for inclusion in the PROFILE TCPIP file in order to make
permanent changes to the network configuration.
First Edition for z/VM Version 4 (October 2001)
This edition contains updates for the General Availability of TCP/IP Level 420.
IMAP Support
A new Chapter, ″Configuring the IMAP Server″ chapter has been added in support
of the Internet Message Access Protocol (IMAP) protocol. In addition to new
configuration statements, several administrative commands have been added to
help manage the IMAP server.
HiperSockets Support
As an extension to the Queued Direct I/O Hardware Facility, HiperSockets provides
a way for programs to communicate within the same logical partition (LPAR) or
across any logical partition within the same Central Electronics Complex (CEC)
using traditional TCP/IP socket connections. A new HiperSockets DEVICE and LINK
statement has been added.
TCP/IP Stack Performance and Reliability Improvement
Function has been added to improve the performance and reliability of the TCP/IP
stack by preventing some Denial of Service attacks. These attacks include: ICMP
Echo Request packets sent to IP broadcast or multicast addresses (Smurf), UDP
Echo Request packets sent to IP broadcast or multicast addresses (Fraggle), and
ICMP Echo Request packets that are too large (Ping-o-Death). A new process,
DENIALOFSERVICE, has been added to the TCP/IP trace function.
DENIALOFSERVICE provides data about the type of attack detected.
Migration Consideration Changes
The migration section in Chapter 1 has been modified. The name is now “Migration
Information and Resources” and contains pointers where the user can access the
latest information on this subject.
xxviii
z/VM: TCP/IP Planning and Customization
First Edition for z/VM Version 3 (February 2001)
This edition contains updates for the General Availability of z/VM 3.1.0.
Native Queued Direct I/O Support
Native Queued Direct I/O support allows TCP/IP to support the microcode that
provides the high speed GigaBit Ethernet Adapter, which utilizes the Queued Direct
I/O Hardware Facility (QDIO). The following have been added:
v A DEVICE statement, used to specify the name and address of the device that
will use the QDIO facility.
v The FIXEDPAGESTORAGEPOOL configuration statement that is used to set the
initial number of Fixed Page Storage Blocks.
v Several new Process names that are valid for the TRACE, LESSTRACE,
MORETRACE, and NOTRACE statements.
Open Shortest Path First (OSPF) Protocol
A new chapter has been added, ″Configuring the MRPOUTE Server″. This chapter
describes how to configure MPROUTE, and also describes the implementation of
the Open Shortest Path First (OSPF) protocol. This chapter also contains several
new OSPF and RIP configuration statements, descriptions, and parameters.
The ″Using OSPF″ section describes the protocol features, as well as supported
network types. It details the setting of OSPF interface types and required tasks on
configuring the OSPF protocol.
IP Multicast Support
IP Multicast support provides the ability to send an IP datagram to a group of hosts
that are members of a single multicast group, and the ability for members of a
multicast group to receive multicast datagrams. The ability to specify multicast
options on sockets is also available. The following changes include:
v A new usage note added to the GATEWAY statement enabling multicast routes to
be specified using a host syntax
v A new usage note added to the TRANSLATE statement enabling a token ring link
to be configured to broadcast multicast datagrams instead of using the functional
MAC address
v Updates to the dest_addr operand, and updates and additions to the usage notes
of the BSDROUTINGPARMS statement
v Updates to a usage note of the OBEYFILE command
v Updates to RouteD to handle IP multicasting for RIPv2 packets. Four new
operands were added to the ROUTED config statement for SMSG support:
CONFIG, RECONFIG, RGATEWAYS, and DGATEWAYS.
Secure Socket Layer (SSL) Support
SSL support provides secure (encrypted) communication between a remote client
and a VM TCP/IP server. Any VM server that listens on a secure port can
participate in an SSL connection with any external client that supports SSL
according to RFC 2246. Under SSL protocol, the server is always authenticated and
must provide a certificate to prove its identity. An installation identifies the ports that
are secure and obtains the certificates to be used, but no changes to VM servers
are required to use the SSL support.
Summary of Changes
xxix
The processing for SSL support is provided by a new SSL server. The SSL server
manages the certificate database and handles the encryption and decryption of
data. The PORT statement has been enhanced to allow the designation of secure
ports. A new SSLADMIN command interface provides certificate database and SSL
server administration functions.
VM NFS Client Support
VM NFS Client support allows BFS users and applications transparent access to
data on remote systems with NFS servers supporting SUN NFS V2 or V3 protocols,
or both. With the necessary NFS server support, the VM NFS Client can access the
data on that system.
The remote data accessed by an NFS client is mounted on the CMS BFS structure
in a single virtual machine. A mount is issued to CMS to attach the remote file
system to mount point on the CMS BFS structure. Once mounted, the remote file
system is accessible using interfaces currently available on z/VM. This new function
has added the following:
v A VMFILETYPE statement, used to specify the translation and line values for a
file extension (file type)
v A VMFILETYPEDEFAULT statement, used to specify the translation and line
values for file extensions (file types) that do not have VMFILETYPE statements.
See the z/VM: OpenExtensions Command Reference for more information about
the VM NFS Client.
FTP Web Browser Support
The FTP server has been enhanced to better accommodate web browser and
graphical FTP clients. The changes and new function include:
v The ability to provide UNIX®-format list information in response to client DIR
subcommand requests
v The ability to perform automatic EBCDIC-ASCII data translation for transferred
files, based on file types (or, file extensions)
v The FTP server now makes use of a server-specific configuration file for its
startup information, so that configuration is more consistent with other TCP/IP
servers.
Other Changes
v The chapter ″Configuring the Standard X Client″ was removed; this support is no
longer provided.
v The chapter ″Configuring the NCS Servers″ was removed; this support is no
longer provided.
Second Edition for VM/ESA® (July 1999)
This edition contains updates for the General Availability of VM/ESA 2.4.0.
RouteD Support
RouteD has been updated to provide the following enhancements:
v RIP Version 2 - This is an extension of the RIP Version 1 protocol.
v Compatibility with OS/390® RouteD
v Variable Subnetting
xxx
z/VM: TCP/IP Planning and Customization
v Virtual IP Addressing (VIPA)
Native ATM Support
Native ATM support has been added, which enables TCP/IP to use an Open
Systems Adapter configured to support Native ATM.
FTP Server Enhancements
The following enhancements have been made to the FTP Server:
v The VM Special Message Facility (SMSG) is available to provide an interface to
communicate with the VM FTP server virtual machine.
v Support has been added for an FTP welcome banner, which displays a site-spec
message when connecting to the FTP server or displays a user-specific message
when a login occurs.
v A new start-up parameter will enable FTP reader file support, allowing users to
STOR files to the virtual reader of a VM user ID.
v New start-up parameters will enable the FTP User Exits.
SMTP Server Enhancements
The following enhancements have been made to the SMTP server:
v The processing framework for SMTP service extensions has been added; this
framework includes support for the 8BITMIME and SIZE service extensions.
v New SMTP configuration statements, 8BITMIME and SOURCEROUTES, are
supported to facilitate 8-bit MIME support and mail source route handling.
VMNFS Server Enhancements
The following enhancements have been made for the VMNFS server machine:
v Several new records have been added, which can be defined in the VMNFS
CONFIG file for configuring the Network File System: DUMPMOUNT, EXPORT,
EXPORTONLY, MAXTCPUSERS, PCNFSD, VMFILETYPE and
VMFILETYPEDEFAULT.
v The VM Special Message Facility (SMSG) is available to provide an interface to
communicate with the VM NFS service machine.
|
|
v New start-up parameters allow you to restrict the server to the Version 2 NFS
level and UDP communications.
v You can configure whether mounts should be restricted to exported file systems
only, and whether or not the server should provide a list of mounted file systems.
v The new exit VMNFSSMG was added, which screens all SMSG requests.
v The VMNFSMON exit was improved to handle new MOUNT options.
Other Changes
v New DOMAINLOOKUP and DOMAINSEARCH configuration statements have
been added to the TCPIP DATA file to support more flexible host name resolution
processing.
v ATMARPSERVER, ATMLIS, and ATMPVD statements, and ATM-specific device
and link statements are now supported for TCP/IP server configuration.
v The Telnet Session Connection Exit and Telnet Printer Management Exit
appendices were moved from this book into the z/VM: TCP/IP Level 430
Programmer’s Reference.
v Chapter 25, ″Configuring the RSCS UFT Client″ is a new chapter that describe
how to configure an asynchronous UFT client.
Summary of Changes
xxxi
v Chapters 3, 4, and 5 from TCP/IP Function Level 310 have been consolidated
into a new chapter.
xxxii
z/VM: TCP/IP Planning and Customization
Chapter 1. Planning Considerations
This chapter provides an introduction to the Transmission Control Protocol/Internet
Protocol, TCP/IP, and describes the planning and preparation that you should
consider before TCP/IP Level 430 is on your system.
Introducing TCP/IP
Transmission Control Protocol/Internet Protocol can be characterized as belonging
to one of the following categories:
v Connectivity and gateway functions, which handle the physical interfaces and
routing of data.
v Server functions, which provide a service to a client (that is, send or transfer a
file).
v Client functions, which request a certain service from a server anywhere in the
network.
v Network status/management functions, which detect and solve network problems.
v Application Programming Interfaces, which allow you to write your own
client/server applications.
TCP/IP is used to build an interconnection between networks (or internet) through
universal communication services. To be able to communicate between networks,
addresses are assigned to each host on the network. This is called the IP address.
Using this IP address, TCP/IP protocols can communicate between networks and
hosts. For example, 9.76.22.1 is an IP address. Each IP address can also have an
associated Domain Name or nickname. The Domain Name is an alternative
method of referring to an IP address. For example the Domain Name
VMHOST.RALEIGH.IBM.COM could be used to refer to the IP address 9.76.22.1.
Connectivity and Gateway Functions
The following are connectivity and gateway functions that may be used to
communicate with other networks either internal or external to your network. Each
form of communication is followed by a brief explanation:
v X.25 - An interface consisting of a data terminal equipment (DTE) and a data
circuit-terminating equipment (DCE) in communication over a link using the
procedures described in the CITT Recommendation X.25.
v Point-to-Point - The Point-to-Point function of TCP/IP serves three main
components: a method for encapsulating datagrams over serial lines; an
extensible Link Control Protocol to configure and test data-link connections; and
a method for establishing different network-layer protocols or Network Control
Protocols (NCP). They include CTC and IUCV connections.
v SNALINK - A function of TCP/IP products for z/VM and z/OS that allows the use
of an SNA routing network to transfer data using the TCP/IP protocols. Data can
be received, sent and routed to other systems using SNALINK.
v Token-Ring Network - A ring network that allows unidirectional data
transmission between data stations. Using a token passing procedure, data is
sent and returned to the transmitting station.
v Ethernet Network - A 10-Mbps baseband local area network that allows multiple
stations to access the transmission medium at will without prior coordination,
avoids contention by using carrier sense and deference, and resolves contention
by using collision detection and transmission. Ethernet uses carrier sense
multiple access with collision detection.
© Copyright IBM Corp. 1987, 2002
1
Planning Considerations
v Fiber Distributed Data Interface - TCP/IP for VM supports Fiber Distributed
Data Interface (FDDI) communications. There are two types of connections that
can be defined. Dual Attached Stations (Class A) which are connected to both a
primary and secondary ring and are capable of redirecting traffic from one ring to
the other. The second, Single Attached Stations (Class B) which are connected
to a single ring and are attached to a Dual Attach Concentrator. FDDI is also
know as IEEE 802.5.
v ATM - IP over native ATM enables TCP/IP to send data across an ATM network
over ATM virtual circuits. Support extends beyond LAN emulation; native
definition of ATM addresses does not require definition of LAN addresses. VM
TCP/IP uses the IBM S/390® Open Systems Adapter (OSA-2) to enable this
support. IP data over both "best effort" Switched Virtual Circuits (SVCs) and "best
effort" Permanent Virtual Circuits (PVCs) is supported.
Server Functions
Following are the server functions and a description of each. These functions may
be used to provide shared services to workstations over a network.
v BOOTPD - The BOOTP virtual machine (daemon) responds to client requests for
boot information using information contained in a BOOTP machine file.
v DHCPD - The DHCP daemon (DHCPD server) responds to client requests for
boot information using information contained in a DHCP machine file. This
information includes the IP address of the client, the IP address of the TFTP
daemon and information about the files to request from the TFTP daemon.
v DNS - The DNS ( Domain Name System ), commonly referred to as simply a
name server, maps a host name to an internet address or an internet address to
a host name.
v FTP - The File Transfer Protocol virtual machine (FTPSERVE) serves client
requests from the TCPIP virtual machine through VMCF communication. The
FTP server allows you to transfer files between your local host and a foreign host
that supports TCP/IP. When invoked, FTP establishes a connection to a foreign
host’s FTP server. After you have identified yourself to the foreign FTP server,
you can retrieve information about the foreign server, list files, transfer files,
delete files, rename files and execute CMS commands.
v IMAP - The Internet Message Access Protocol (IMAP) server provides mail
clients the ability to access electronic mail and to manage remote message
folders (mailboxes) as if they were local. This service is based on RFC 2060.
v KERBEROS - The KERBEROS authentication server provides a way for
authenticated users to prove their identity to other servers in a network.
v LPD - The Line Printer Daemon virtual machine (LPSERVE) serves client
requests to print a file. The LPSERVE server looks for the printer specified by the
client (LPR) and attempts to print the document. The printer itself is not
dedicated to TCP/IP, it may receive output from other sources as well. The
LPSERVE server supports three types of printer connections:
– Local Printers
– Remote RSCS printers (RSCS connected)
– Remote TCP/IP printers (TCP/IP connected)
The local printers are physically attached to the VM system. Any printer available
through the RSCS network however, can be accessed with the remote RSCS
printer support. This printer might be attached to an OS/390 system without a
TCP/IP connection. Any printer controlled by another LPD server can be made
available to a VM TCP/IP user.
2
z/VM: TCP/IP Planning and Customization
Planning Considerations
v MPROUTE - The MPROUTE server provides an alternative to the static TCP/IP
gateway definitions. MPROUTE implements the OSPF protocol described in RFC
1583 (OSPF Version 2) and the RIP protocols described in RFC 1058 (RIP
Version 1) and in RFC 1723 (RIP Version 2).
v NAMESRV - The Domain Name Server (NAMESRV) serves to resolve domain
names, aliases for clients and provides commands for querying name servers
from a CMS user ID. Name servers manage two kinds of data which can be
stored in either local data files (HOSTS LOCAL) or in DB2® Server for VSE &
VM (formerly known as SQL/DS™ databases). The first kind of data is held in
sets called zones; each zone is the complete database. The second kind of data
is cached data, which is acquired by a local resolver.
v NDB - The Network Database server uses the Remote Procedure Call (RPC)
protocol to allow interoperability among a variety of workstation users and a host
relational database system. It provides access to a mainframe relational
database from workstations and allows users to issue SQL statements
interactively, or embed SQL statements within an application program.
v NFS - The Network File System virtual machine (VMNFS) allows a client system
to access CMS minidisks, SFS directories, and BFS directories as if they were
local to the client. VMNFS allows users to execute programs, and to create and
edit files. The VMNFS virtual machine requires access to the IBM Language
Environment® runtime library during execution.
v Port Mapper - The Port Mapper (PORTMAP) server application is used to map
program numbers and various numbers to RPC programs that request
information. The PORTMAP server only knows about RPC programs on the local
host system. The calling application contacts PORTMAP on the destination host
to obtain the correct port number of a specific remote program.
v ROUTED - The routing daemon (RouteD) is a server that implements the
Routing Information Protocol (RIP). It provides an alternative to static TCP/IP
gateway definitions.
v REXEC - The Remote Execution virtual machine (REXECD) sends a single
command to a remote system for execution. The remote system name, user ID,
password and command string can all be passed as parameters. The REXECD
server can log on, execute the command and log off. REXECD can also be used
for network management purposes. Procedures to start and stop TCP/IP devices
(physical links) can be initialized using the REXEC command and the OBEYFILE
command.
v SMTP - The Simple Mail Transfer Protocol virtual machine (SMTP) operates as a
mail gateway between TCP/IP network sites and RSCS network sites. This
means, for example, OfficeVision® users can exchange mail with UNIX®
workstations through the VM TCP/IP SMTP gateway. The SMTP server allows
you to create custom mail headers (RFC822), provides an interface which allows
the querying of SMTP mail delivery queues and provides a set of privileged
commands for system administrator tasks. SMTP can be configured to use either
a domain name server or the local site tables.
v SNALINK - The SNALINK ( SNA Network Link ) virtual machine provides an
interface between the TCPIP virtual machine’s SNAIUCV driver and the SNA
network.
v SNMP - SNMP is an architecture that allows you to manage an internet
environment. You can use SNMP to manage elements such as gateways,
routers, and hosts on the network.
v SSL - The Secure Socket Layer (SSL) server, which runs in the SSLSERV virtual
machine, provides processing support for secure (encrypted) communication
between remote clients and VM TCP/IP servers that listen on secure ports. The
Chapter 1. Planning Considerations
3
Planning Considerations
SSL server manages the database in which the server authentication certificates
are stored. The TCP/IP (stack) server routes requests for secure ports to the SSL
server. The SSL server, representing the requested application server,
participates in the handshake with the client in which the cryptographic
parameters are established for the session. The SSL server then handles all the
encryption and decryption of data.
v TELNET - The Teletypewriter Network (TELNET) feature is part of the TCPIP
virtual machine. The TELNET protocol provides a standardized interface, through
which a program on one host (the TELNET client) may access the resources of
another host (the TELNET server) as though the client were a local terminal
connected to the server. TELNET provides interactive access to local and remote
hosts, support for TN3270 and TN3270E, but does not support graphics.
v TFTPD - The TFTP daemon (TFTPD server) transfers files between the Byte File
System (BFS) and TFTP clients. TFTPD supports access to files maintained in a
BFS directory structure that is mounted.
v UFTD - The UFT daemon (UFTD server) accepts unsolicited file transfer
requests to receive files from remote clients for local users.
Client Functions
v FTP - The FTP client sends requests to the FTP server virtual machine.
v LPR - the LPR command is used to communicate with the LPSERVE server to
submit commands and documents to be printed.
v NFS - The NFS client allows a remote file system to be logically included as a
component of a Byte File System.
|
|
v NOTE - The NOTE command (provided with CMS) allows users to send mail
throughout the local network and to external network sites.
v NSLOOKUP - The NSLOOKUP command is used to query names and allows
you to locate information about network nodes, examine the content of a name
server database and establish the accessibility of name servers.
v REXEC - The REXEC client in VM/CMS issues requests to execute commands
on other network systems.
v SENDFILE - The SENDFILE command (provided with CMS) allows users to
send files throughout the local network and to external network sites.
v TELNET - The TELNET client allows you to log on from any VM/CMS terminal to
either local or remote networks that are operating TCP/IP.
v TFTP - The TFTP application is used to transfer files among personal computers.
TFTP allows files to be sent and received but does not provide any password
protection or directory capability.
Network Status/Management Functions
v NETSTAT - The NETSTAT command displays the network status of the local
host, TCP/IP connections, network clients, routers, devices and the TELNET
server. NETSTAT will provide information on active TCP connections, all TCP/IP
servers on the local host, devices, links and IP routing tables.
v OBEYFILE - The OBEYFILE command allows you to execute the TCP/IP
configuration statements while TCP/IP is running, thus allowing updates to occur
without halting TCP/IP operations. Primarily, OBEYFILE is used to change the
TCP/IP system temporarily while TCP/IP is running.
v PING - The PING command tests the connection to any TCP/IP host.
v MPROUTE - The Multiple Protocol ROUTE (MPROUTE) virtual machine
implements the OSPF and Routing Information (RIP) protocols providing an
4
z/VM: TCP/IP Planning and Customization
Planning Considerations
alternative to the use of static TCP/IP gateway definitions. When properly
configured , the VM host running with MPROUTE becomes an active OSPF
and/or RIP router in a TCP/IP network.
The Open Shortest Path first protocol (OSPF) is an Interior Gateway Protocol. It
distributes routing information between routers that belong to a single
autonomous system; that is, a group of routers that all use a common routing
protocol.
v ROUTED - The Routing Information Protocol (RIP) creates and maintains
network routing tables. RIP arranges to have gateways and routers periodically
broadcast their routing tables to neighbors. This protocol is most useful as an
Interior Gateway Protocol.
v SNMP - The Simple Network Management Protocol (SNMP) virtual machine
allows you to manage your TCP/IP network. SNMP is an internet standard that
defines a set of functions that may be used to monitor and control network
elements. The SNMP server (or agent) responds to commands issued by the
client (or monitor).
Application Programming Interfaces
v KERBEROS - The Kerberos Authentication and Authorization system is an
encryption-based security system that provides mutual authentication between
users and servers in a network environment. The VM Kerberos System relies
upon two virtual machines. VMKERB which runs the authentication server and
ADMSERV which runs the Kerberos database remote administration server.
v RPC - The Remote Procedure Call is an application programming interface (API)
for developing distributed applications. It allows programs to call subroutines that
are executed at a remote system. The caller program (client) sends a call
message to the server, and waits for a reply message. In order to send a
message the caller must know the exact port number used by the RPC program.
To get this port number, the caller sends a request to the PORTMAP server on
the remote host to retrieve the port information for the desired program.
v SNMP DPI - The Simple Network Management Protocol Daemon (SNMPD) is a
server that communicates management information between network
management stations and agents in the network. The SNMP Distributed
Programming Interface (DPI) allows users to manipulate the information or MIB
variables for each layer in the TCP/IP protocol.
v Sockets - The Sockets API provides a simplified procedure to transfer
information and to communicate between applications. The socket interface is
designed to provide applications with a network interface that hides the details of
the physical network.
v X Window System - The X WINDOW SYSTEM is one of the most widely used
Graphical User Interfaces (GUI) or bitmapped- window display systems. It is
supported by all major workstation vendors and is used by thousands of users
worldwide. An interface, Graphical Data Display Manager (GDDM®), is provided
and permits graphics display output from the IBM GDDM to be displayed on
workstations that support the X Windows™ System.
Migration Information and Resources
Information about TCP/IP changes and enhancements that can (or will) affect
migration to the current level of TCP/IP for z/VM can be obtained through the
following resources:
v TCP/IP for z/VM, Level 430 Program Directory
v http://www.ibm.com/s390/vm/related/tcpip/
Chapter 1. Planning Considerations
5
Planning Considerations
Note: TCP/IP is supported on associated releases of CP and CMS only.
Implications of Assigning Different Server Virtual Machine Names
In general, the amount of customization required to install TCP/IP or to configure a
protocol server can be minimized by using IBM-supplied, default virtual machine
names (user IDs).
If non-default server machine names must be used in your environment (for
example, to conform to local site naming standards), this might be accommodated
by duplicating existing servers, and using an updated SYSTEM DTCPARMS file in
conjunction with a global server exit that provides common server processing.
However, for some environments it may be necessary to modify various TCP/IP
configuration files and product executables to accommodate specific user ID
changes. The information that follows is provided to assist you with making changes
of this nature.
Server Naming Restrictions
The name of the Domain Name System (DNS) server virtual machine cannot be
changed, due to customization and build processing requirements that are
associated with this server implementation. If it is used in your environment, the
DNS virtual machine user ID (name) must remain NAMESRV.
Accommodating Changed Server Names
If you elect to change the server user ID (or, name) for any of the TCP/IP virtual
machines that provide services in your environment, certain modifications must be
made. As you use the configuration steps provided later in this publication, ensure
the following changes are made to account for server naming differences:
1. Create a SYSTEM DTCPARMS file that identifies and further defines each
TCP/IP protocol server that is used in your environment. Model your server
definitions after those in the definition section of the supplied IBM DTCPARMS
file.
2. Update the TCP/IP server configuration file (PROFILE TCPIP, or its equivalent)
to reflect any server name changes. Statements within this file that are likely to
be affected by name-related changes are:
v AUTOLOG
v OBEY
v PORT
3. When the user ID of the TCP/IP server is changed from the default of TCPIP,
one or more of the following changes will be required, depending on your
environment:
v Modify the TCPIPUSERID statement within the TCPIP DATA file to reflect the
correct TCP/IP server virtual machine user ID. For example:
TCPIPUSERID TCPIPA1
v For the RSCS UFT client or RSCS Print Server, include the TCPIP= operand
as part of any PARM statements that correspond to LPD or UFT link
definitions. This operand allows you to identify the TCP/IP server machine
that is in use. For example:
...
LINKDEFINE LPD TYPE LPD
PARM LPD EXIT=LPDXMANY TCPIP=TCPIPA1
...
6
z/VM: TCP/IP Planning and Customization
Planning Considerations
Configuration files that may require such additions are:
– RSCSLPD CONFIG
– RSCSLPR CONFIG
– RSCSLPRP CONFIG
– RSCSTCP CONFIG
– RSCSUFT CONFIG
v For the TFTPD server, specify the SVMNAME operand as a TFTPD
command option, in order to identify the TCP/IP virtual machine that is in use.
For example:
SVMNAME TCPIPA1
v For the SNALINK server, modify the
TcpUserid
variable assignment within the SNALNKA GCS file, to reflect the user ID of
the TCP/IP virtual machine. For example:
...
TcpUserid = ’TCPIPA1’
...
/* Userid of TCP/IP stack */
4. When the user ID of the Simple Mail Transfer Protocol (SMTP) server is
changed from the default of SMTP, one or more of the following changes will be
required, depending on your environment:
v Modify the SMTPSERVERID statement within the TCPIP DATA file to reflect
the correct SMTP server virtual machine user ID. For example:
SMTPSERVERID SMTPA1
v For the LPD server, modify the SMTP statement within the LPD configuration
file (LPD CONFIG), to reflect the correct SMTP server virtual machine user
ID. For example:
SMTP SMTPA1
5. If RACF is active on the system on which TCP/IP is installed, and:
v you elect to use a different name for the File Transfer Protocol (FTP) server
or the Network File System (NFS) server, or
v you elect to use multiple FTP or NFS servers,
any modified or additional server names must be identified (or made available
for reference) whenever the FTPPERM or NFSPERM execs are used to
establish authorization for these servers to act on a users’ behalf. For more
information see Appendix A, “Using TCP/IP with an External Security Manager”
on page 645.
6. By default, the TCPMAINT user ID is designated as the owner of the various
TCP/IP resources that are placed into production in your environment. As such,
this user ID often serves as the focal point for administering TCP/IP protocol
servers and services. When a different user ID is used as the TCP/IP resource
owner, one or more of the following changes may be required, depending on
your environment:
v Update the TCP/IP server configuration file (PROFILE TCPIP, or its
equivalent) to account for the changed TCP/IP administrative user ID.
Statements within this file that are likely to be affected by such changes are:
– INFORM
– OBEY
Chapter 1. Planning Considerations
7
Planning Considerations
v Update the SYSTEM DTCPARMS file to include appropriate :Owner tags to
identify your administrative user ID for each protocol server used in your
environment. For example:
:owner.TCPADMIN
v For the DNS server, modify the VALIDUSR EXEC (if used) to identify the
administrative user ID that is in use. For example:
...
/* TCPMAINT authorization */
Call Value thisnode’.TCPADMIN’,!authuser
...
v For the LPD server, modify the OBEY statement within the LPD configuration
file (LPD CONFIG), to reflect the correct administrative user ID. For example:
OBEY TCPADMIN
v For the SMTP server, the TCPMAINT user ID is assumed as the effective
user ID for the statements that follow (when these statements are omitted
from the SMTP server configuration file, SMTP CONFIG):
– BADSPOOLFILEID
– POSTMASTER
In addition, the supplied sample SMTP configuration file includes these
statements, for which the TCPMAINT user ID has been specified:
– ONDISKFULL
– SMSGAUTHLIST
Customize these statements, as required, to reflect the administrative user ID
that is in use.
v For the NFS server, update the VMNFSCMS exit exec (if used) to identify the
correct administrative user ID. For example:
...
if origin = "TCPADMIN" then signal good
...
v For the SNALINK and X25IPI servers, modify the TCPROFIL GCS profile
(which is shared among these servers) to identify the administrative user ID
that should receive console logs. For example:
...
"CP SPOOL CONS START TO TCPADMIN"
...
7. When the SNMP Query Engine server name is changed, the SNMPQE
statement within the SNMPARMS NCCFLST file must be updated to reflect this
change. For example:
...
SNMPQE
...
SNMPQEA1
* Userid of the SNMP Query Engine
Multiple Server Instance Restrictions
For a given VM TCP/IP host, multiple TCP/IP server machines may be defined and
used for nearly all protocol server classes, as required. However, there are several
servers for which the use of multiple server instances is not supported (nor
recommended). Servers to which this restriction applies (that is, for which only one
instance should be employed) are:
v DNS server (NAMESRV)
v MPROUTE server (MPROUTE)
v ROUTED server (ROUTED)
8
z/VM: TCP/IP Planning and Customization
Planning Considerations
v SSL server (SSLSERV)*
* Only one instance should be used for a given TCP/IP server
The restriction against multiple instances for these servers stems from the nature of
the protocol service that each provides.
Note: The TCP/IP stack may not explicitly prevent using multiple instances of the
listed servers. However, be aware that the result of doing so is
unpredictable.
Mutually Exclusive Servers
As improvements and additional TCP/IP support functions are incorporated within
TCP/IP for z/VM, additional servers may be introduced that provide services which
are similar to those provided by an existing server. In some cases, the services
offered by a newer server may surpass or otherwise overlap those provided by an
existing server. When this occurs, certain TCP/IP protocol servers may then
become mutually exclusive with respect to use. TCP/IP servers to which this
situation applies are:
v BOOTP server (BOOTPD) or DHCP server (DHCPD)
v ROUTED server (ROUTED) or MPROUTE server (MPROUTE)
v LPD server (LPSERVE) or RSCS LPD print server
When you install and configure TCP/IP for z/VM, determine which of these protocol
servers best addresses the requirements of your environment, and then employ
only that server.
Publication References
Additional TCP/IP, z/VM, and VMSES/E product information can be obtained in the
following publications:
v z/VM: TCP/IP Level 430 Programmer’s Reference
v z/VM: TCP/IP Level 430 User’s Guide
v z/VM: TCP/IP Level 430 Messages and Codes
v z/VM: TCP/IP Level 430 Diagnosis Guide
Chapter 1. Planning Considerations
9
Planning Considerations
10
z/VM: TCP/IP Planning and Customization
Chapter 2. System Requirements for TCP/IP
This chapter identifies the system requirements for TCP/IP for z/VM.
z/VM Device Definition Considerations
Most network devices do not require definition in the system configuration file or
HCPRIO. Device attributes are determined dynamically through the device
initialization process. For more information on when and how devices are defined
for z/VM, see z/VM: CP Planning and Administration.
Hardware Environment
TCP/IP for z/VM operates on any IBM S/390 or z/Architecture processor supported
by z/VM (or any compatible processor). For information about supported
processors, see z/VM: General Information.
TCP/IP also requires a 3270-equivalent workstation for TCP/IP administration.
Network Attachments
TCP/IP for z/VM requires a network processor and associated components for
attachments to the teleprocessing network. The following are possible network
attachments that you may have installed or plan to install that work in conjunction
with TCP/IP.
Open System Adapter 2 (OSA-2)
The IBM S/390 Open Systems Adapter (OSA) is an integrated hardware feature
that allows the S/390 host platform to provide industry-standard connectivity to
clients on directly-attached local area networks (LANs) or, via attachment to an
asynchronous transfer mode (ATM) switch, to clients in an ATM-based network. The
OSA-2 supports direct attachments to Fast (100Mb) Ethernet and IBM Token Ring
LANs.
IBM 3172 Interconnect Controller
The IBM 3172 Interconnect Controller with the IBM Interconnect Controller Program
Version 3 (5621-425), or any equivalent device that communicates with the host
using the LAN Channel Station (LCS) protocol, is supported. One or more IBM
Token Ring, Ethernet, or FDDI adapters must be installed.
Open System Adapter-Express (OSA-Express)
TCP/IP provides support for the OSA-Express, an integrated hardware feature
providing fully integrated native systems connectivity to a Local Area Network (LAN)
from a S/390 processor. Beginning with the IBM Generation 5 CMOS family of
processors, a new type of I/O called the Queued Direct I/O Hardware Facility
(QDIO) is available. QDIO allows the TCP/IP stack to directly exchange data with
an I/O device without performing traditional S/390 I/O instructions. Data transfer is
initiated and performed by referencing main storage directly via a set of data
queues by both the I/O device and the TCP/IP stack. Once the TCP/IP stack
establishes and activates the data queues, there is minimal processor intervention
required to perform the direct exchange of data.
© Copyright IBM Corp. 1987, 2002
11
System Requirements
CLAW Channel Driver
Common Link Access to Workstations (CLAW) is a continuously executing,
full-duplex channel program designed to minimize host interrupts while maximizing
channel utilization. The channel commands used within CLAW allow S/390
applications, such as TCP/IP, to monitor the progress of a long channel program
and modify it as it is running. In a S/390 processor with minimal CPU activity,
CLAW is driven primarily by I/O interrupts, as typical S/390 devices would be. As
the system load becomes heavier, CLAW is more often able to append new I/O
requests to the already-active channel program — thus avoiding the overhead of
interrupts and “Start Subchannel” requests at a time when it can least afford it.
Therefore, CLAW provides better support of a direct hardware link between a S/390
channel and a workstation.
IBM 37xx Communications Controller Interface
The IBM 37xx Communications Controller Interface requires a 3720, 3725, or 3745
communication controller. The minimum IBM 37xx Communication Controller
Software required to support the X.25 interface is:
v One of the following:
– X.25 NPSI Version 3 (5688-035) Release 4 or later, for the 3745 or 3720
– X.25 NPSI Version 2 (5688-719), for the 3725
v One of the following:
– ACF/VTAM® for VM/ESA Version 4 (5654-010)
– ACF/NCP Version 5 Release 3 or later (5668-738)
– ACF/NCP Version 6 (5648-063).
HYPERchannel A220 Processor Adapter 42990007
TCP/IP supports the HYPERchannel Series A and B devices. In addition, TCP/IP
supports HYPERchannel Series DX devices provided they function as Series A and
B devices. For more information, see the appropriate Networking Systems
Corporation documentation.
Channel-to-Channel Support
Channel-to-Channel connections are supported using the IBM 3088 Multi-system
Channel Communication Unit. TCP/IP supports direct connection to another VM
TCP/IP, MVS, OS/390, z/OS, or Linux for S/390 using the IBM 3088.
IUCV
The CP IUCV Service may be used to connect TCP/IP service machines on the
same VM host. IUCV may also be used to connect VM TCP/IP to Linux for S/390.
Software Environment
TCP/IP Level 430 requires:
v z/VM Version 4 Release 3.0 (TCP/IP for z/VM cannot be used with previous
levels of CP and CMS)
v Language Environment supplied with z/VM Version 4 Release 3.0 (previous
levels of Language Environment cannot be used.)
12
z/VM: TCP/IP Planning and Customization
System Requirements
To develop programs in Pascal or to modify TCP/IP Pascal components, use the
IBM VS Pascal Version 1 Release 2, Compiler and Library (5668-767).
Note: The Pascal run-time library is included with TCP/IP.
To develop applications in the C programming language, or to modify TCP/IP C
components, the following is required:
v IBM C for VM/ESA Compiler, Version 3 (5654-033) Release 1
Language Environment has been used to build the C components that provide the
following TCP/IP services:
v
v
v
v
v
v
v
v
Kerberos Servers
Domain Name Server
NDB Servers
NFS Client and Servers
PortMapper Server
REXEC Daemon
Sockets Applications Programming Interface
SNMP Query Engine
v SNMP Agent
v RouteD Server
v Network Data Base Server
v MPROUTE Server
v IMAP Server
TCP/IP Level 430 exploits a subset of RSCS Version 3 Release 2 function that is
available with z/VM Version 4 Release 3.0. This subset provides enhanced printing
support through RSCS LPR and LPD functions, along with TN3270E protocol
support for printer sessions. This is the only intended or implied use of this subset
of the RSCS product. Customers requiring the use of other RSCS functions must
have or acquire an RSCS Version 3 Release 2 license.
If you are running a primary or secondary name server, you need DB2 Server for
VSE & VM Version 6 (5648-A70) or DB2 Server for VSE & VM Version 7
(5697-F42). You do not need DB2 Server for VSE & VM if you are running a
caching-only name server.
If the IBM Graphical Data Display Manager (GDDM) is to be run through the X
Window System, the TCP/IP X Window System GDDM interface (GDDMXD) must
be installed.
If you intend to install the CMS X Window System, you need:
v IBM C for VM/ESA Compiler Version 3 (5654-033)
The X Window System GDDM support requires one of the following:
v GDDM/VM Version 2.3 (5684-007) with APAR PN77393 applied
v GDDM/VM Version 3.1 (5684-168) with APAR PN77392 applied or later
Note: The X Window System server must be running Version 11.
For more information about GDDMXD, see Chapter 29, “X Window System
Graphical Data Display Manager Support” on page 621.
Chapter 2. System Requirements for TCP/IP
13
System Requirements
If the IBM 3172 Support is to be used, the IBM 3172 Interconnect Controller
Program Version 3 (5621-425) is required.
If the Network Data Base Server is to be used, the following is required:
v DB2 Server for VSE & VM Version 6 (5648-A70) or DB2 Server for VSE & VM
Version 7 (5697-F42) running on the VM system.
v For the client workstation, AIX® Version 3 for RISC System/6000® (RS/6000®) or
later, or a SunOS system for Sun workstations.
v For the server on VM, a CMS virtual machine with Class B privilege.
For SNAlink LU0 interface support, ACF/VTAM for VM/ESA Version 4 (5654-010) is
required.
For X.25 interface support, the following is required:
v X.25 NPSI Version 3 (5688-035) Release 4 or later, for the 3745 or 3720
v X.25 NPSI Version 2 (5886-719), for the 3725
v Corresponding levels of ACF/VTAM and ACF/NCP that support NPSI
To link two TCP/IP virtual machines using the VM/Pass-Through Facility (PVM):
v The connections may be linked using the the PVM IUCF peer-to-peer connection
facility. The PVM virtual machines on the nodes running TCP/IP must be at PVM
Version 2 (5684-100).
14
z/VM: TCP/IP Planning and Customization
Chapter 3. Defining the TCP/IP System Parameters
This chapter describes how to define the system parameters that are required by
the TCP/IP client programs.
Configuring the TCPIP DATA File
The TCPIP DATA file defines system parameters used by TCP/IP client applications.
It is used to specify configuration information for single or multiple host systems.
For example, if you have multiple versions of TCP/IP installed with a unique set of
server virtual machine names for each version, you can specify which TCP/IP
product to use in this file. It also allows you to specify:
v Host name of the VM host
v User ID of the TCPIP virtual machine
v Domain origin of the host
v Output trace
v Name server specifications
– Name server addresses and default loopback address
– Foreign port of the name server
– Number of seconds resolver should wait while trying to communicate with the
name server
– Number of seconds between connection attempts
– Communication method between resolver and name server
A sample TCP/IP DATA file is shipped as TCPIP SDATA on the TCPMAINT 592
disk. It should be copied to TCPIP DATA (on the same disk) and customized.
Change the configuration statements in the TCPIP DATA file to define the client
parameters. You can specify configuration information for single or multiple systems
in a single file, the TCPIP DATA file.
You can specify an optional system_name before each configuration statement. The
configuration statement is in effect if the system_name matches the name of the
system determined by the CMS IDENTIFY command. The configuration statement
is ignored if the system_name does not match the name of the system determined
by the CMS IDENTIFY command. The configuration statement is in effect on every
system if a system_name has not been specified.
Statement Syntax
Within TCPIP DATA, blanks and record boundaries are used to delimit tokens. All
characters to the right of (and including) a semicolon are treated as comments.
This section describes the syntax of the configuration statements for the TCPIP
DATA file.
ATSIGN Statement
The ATSIGN statement specifies an alternate hexadecimal value to be used for the
“at sign” (@) character. An alternate definition for this character is required only
when your site is using code pages in which the EBCDIC @ character is not
defined as X'7C'. If this statement is not specified, only the X'7C' value will be in
effect.
© Copyright IBM Corp. 1987, 2002
15
Defining System Parameters
The alternate definition you provide is only used by the SMTP server and by certain
CMS commands (such as SENDFILE) that process files directed to this server. The
alternate value must match the @ EBCDIC codepoint defined by the national code
page in use.
The supplied definition is used (in addition to the X'7C' default) to correctly map the
EBCDIC @ value to its ASCII equivalent (X'40') when internet address information
is processed. This ensures that internet addresses are properly handled for mail
that is inbound to, or outbound from, your site.
ATSIGN
X’7C’
X’xx’
Operands
X’xx’
Specifies the hexadecimal value used to define the @ character; xx is a
hexadecimal character specification.
For example, in Finnish/Swedish code page 278, the @ character is defined as the
hexadecimal X'EC'. When this codepage is in use the ATSIGN statement should be
specified as:
ATSIGN X’EC’
Additionally, the appropriate translate table (for example, 02780819 TCPXLBIN)
must be available for use by the SMTP virtual machine, as file SMTP TCPXLBIN.
Usage Notes
v Modifications to the @ character through the TCPIP DATA file ATSIGN statement
cannot be used by installations that make use of RFC 822 header rewrite rules.
The processing of rules defined in the SMTP RULES file is table driven; the logic
to support @ character redefinition within these tables has not been incorporated
in this release of TCP/IP.
v The ATSIGN statement should not be used to account for differences or
problems that arise with the symbol used for the virtual console delete character
function (the system default symbol for this function is the @ character). The CP
TERMINAL CHARDEL command should instead be used to resolve character
deletion problems when the @ character is used.
DOMAINLOOKUP Statement
The DOMAINLOOKUP statement specifies what methods are used to resolve host
names and in what order these methods are used. By default, name resolution is
attempted by asking a question of each name server and then checking for the
answer in the HOSTS SITEINFO file. The resolution is complete when the first
answer is found. The DOMAINLOOKUP statement can be used to instruct the
resolver to use only name servers to resolve host names, or to attempt to find an
answer in the HOSTS SITEINFO file before any name servers are contacted.
16
z/VM: TCP/IP Planning and Customization
Defining System Parameters
DOMAINLOOKUP DNS
DOMAINLOOKUP FILES
DOMAINLOOKUP DNSONLY
DOMAINLOOKUP FILESONLY
Operands
DNS
Use both the name servers specified by the NSINTERADDR statements and
the HOSTS SITEINFO file to perform host name resolution. Name servers are
used before the HOSTS SITEINFO file.
FILES
Use both the HOSTS SITEINFO file and the name servers specified by the
NSINTERADDR statements to perform host name resolution. The content of the
HOSTS SITEINFO file is used before any name servers.
DNSONLY
Use only the name servers specified by the NSINTERADDR statements to
perform host name resolution.
FILESONLY
Use only the HOSTS SITEINFO file to perform host name resolution.
When both the name servers and the HOSTS SITEINFO file are used for searches
and the resolver is required to ask more than one question to obtain an answer,
each question is asked of each name server, in turn with the HOSTS SITEINFO file
being consulted last (assuming the default DNS specification is in use). In other
words, the HOSTS SITEINFO file is consulted after the first question has been
asked of all name servers. Refer to the “DOMAINSEARCH Statement” on page 18
for more detail about name resolution.
DOMAINORIGIN Statement
The DOMAINORIGIN statement specifies the domain that is appended to the name
in the HOSTNAME statement to form the full host name for a system. Case
translation is not performed on the domain origin. The DOMAINORIGIN
configuration statement must be customized at each site.
The domain provided on the DOMAINORIGIN statement is also used as a
DOMAINSEARCH value for the purposes of host name resolution. The rules that
govern how host name resolution is performed are described in the
“DOMAINSEARCH Statement” on page 18.
DOMAINORIGIN domain
Operands
domain
Specifies the domain origin that is appended to the host name when the
Chapter 3. Defining the TCP/IP System Parameters
17
Defining System Parameters
complete local host name is formed. The domain value is also used as a
domain for host name resolution, as if it were specified in a DOMAINSEARCH
statement.
DOMAINSEARCH Statement
The DOMAINSEARCH statement specifies a domain to be used when host names
are resolved. Multiple DOMAINSEARCH statements can be used. Case translation
is not performed on the domain name provided. Currently, name resolution
throughout the internet is case independent.
The order of the statements encountered in the TCPIP DATA file is the order they
will be used during host name resolution. Any DOMAINSEARCH configuration
statements must be customized at each site. Note that the domain specified for the
DOMAINORIGIN statement is also used for host name resolution, as if it appeared
in a DOMAINSEARCH statement.
DOMAINSEARCH domain
Operands
domain
Specifies a domain to be added to the list of domains to be used when host
name resolution is performed.
Host name resolution is a process that attempts to obtain an IP address for a given
host. By convention, host names are considered to be composed of two parts —
the host portion and a domain portion.
It is common for a local environment to make use of more than one domain name.
For example, the misery.movie.edu domain and the comedy.movie.edu domain
might both be in use. Assume that when you want to resolve the host tootsie, you
would like both domains to be searched when name resolution is performed. This
can be accomplished by specifying each domain on a DOMAINSEARCH statement.
Note that if one of these domains is already specified on the DOMAINORIGIN
statement, a DOMAINSEARCH statement for that domain is not required.
The resolver will actually ask multiple questions of the specified name servers until
it gets an answer, at which time it ends the resolution process. For example, if the
host tootsie exists in more than one of the domains defined for the
DOMAINORIGIN and DOMAINSEARCH statements, the host address returned will
be that for the domain defined first in the TCPIP DATA file. To avoid the chance of
getting an address from a domain that is not desired, a fully-qualified host name,
such as tootsie.comedy.movie.edu. should be specified when TCP/IP services are
used.
The nature of the name you attempt to resolve can also affect the way the search is
done. If the name you provide is followed by a period (.), that name (with the trailing
period removed) is assumed to be fully qualified already, and the domains from the
DOMAINSEARCH and DOMAINORIGIN statements are not used. If the name
contains (but does not end with) a period, it is presumed this name may already be
fully qualified; the name, as provided, is used for the search before trying any
names created by appending the domains from the DOMAINSEARCH and
DOMAINORIGIN statements. If the name does not contain a period, it is presumed
18
z/VM: TCP/IP Planning and Customization
Defining System Parameters
to not be fully qualified, so names created by appending the domains from the
DOMAINSEARCH and DOMAINORIGIN statements are tried. If none of these
names result in an answer, the name, as originally specified, is tried as a final
attempt.
Examples
The examples that follow attempt to illustrate how the input name and the content
of the TCPIP DATA file are used to resolve a name. Assume the TCPIP DATA file
contains these definitions:
DomainSearch
DomainOrigin
DomainSearch
DomainSearch
tragedy.movie.edu
comedy.movie.edu
suspense.movie.edu
movie.edu
If one issues this PING command:
ping tootsie
these questions are sent to the name server:
tootsie.tragedy.movie.edu
tootsie.comedy.movie.edu (this question is answered)
For this command:
ping tootsie.comedy
these questions are sent to the name server:
tootsie.comedy
tootsie.comedy.tragedy.movie.edu
tootsie.comedy.comedy.movie.edu
tootsie.comedy.suspense.movie.edu
tootsie.comedy.movie.edu (this question is answered)
If this command is issued:
ping tootsie.comedy.
the questions sent to the name server are:
tootsie.comedy
(the search fails)
Finally, if this PING is performed:
ping junk
these questions are sent to the name server:
junk.tragedy.movie.edu
junk.comedy.movie.edu
junk.suspense.movie.edu
junk.movie.edu
junk
(the search fails)
HOSTNAME Statement
The HOSTNAME statement specifies the TCP host name of this VM host. The fully
qualified domain name for the host is formed by concatenating this host name with
the domain origin (specified by the DOMAINORIGIN configuration statement). Case
translation is not performed on the host name. If the host name is not specified, the
default host name is the node name returned by the CMS IDENTIFY command.
Chapter 3. Defining the TCP/IP System Parameters
19
Defining System Parameters
HOSTNAME hostname
Operands
hostname
Specifies the TCP host name of the VM host.
NSINTERADDR Statement
The NSINTERADDR statement defines the internet address of a name server in
dotted-decimal format. This parameter can be repeated, without limit, to specify the
internet addresses of alternative name servers. Connections to the name servers
are attempted in the order they appear in this configuration file. If NSINTERADDR
statements are not coded in the TCPIP DATA file, the resolver looks up all domain
names in the site hosts table see, Chapter 4, “Configuring the HOSTS LOCAL File”
on page 27, the resolver does not attempt to use a name server.
NSINTERADDR internet_address
Operands
internet_address
Specifies the internet address of a name server.
NSPORTADDR Statement
The NSPORTADDR statement specifies the port of the name server.
NSPORTADDR 53
NSPORTADDR nsportaddr
Operands
nsportaddr
Specifies the port of the name server. The range is 1 through 65 535. The
default is port 53.
RESOLVERTIMEOUT Statement
The RESOLVERTIMEOUT statement specifies the number of seconds the resolver
waits while trying to communicate with the name server.
20
RESOLVERTIMEOUT 30
RESOLVERTIMEOUT timeoutvalue
z/VM: TCP/IP Planning and Customization
Defining System Parameters
Operands
timeoutvalue
Indicates the number of seconds the resolver waits until a response is received.
The default open time-out is 30 seconds.
RESOLVERUDPRETRIES Statement
The RESOLVERUDPRETRIES statement specifies the number of times the resolver
should try to connect to the name server when using UDP datagrams.
RESOLVERUDPRETRIES 1
RESOLVERUDPRETRIES limit
Operands
limit
Indicates the maximum number of times the resolver should try to connect to
the name server. The default is 1.
RESOLVEVIA Statement
The RESOLVEVIA statement specifies the protocol used by the resolver to
communicate with the name server.
RESOLVEVIA UDP
RESOLVEVIA TCP
Operands
TCP
Specifies that the protocol is TCP.
UDP
Specifies that the protocol is UDP. The default protocol is UDP.
SMTPSERVERID Statement
The SMTPSERVERID statement identifies the virtual machine that provides SMTP
services, if one exists.
SMTPSERVERID user_id
AT node_id
Operands
user_id
Specifies the user ID of the SMTP server virtual machine for either the local
system, or for a network gateway system.
Chapter 3. Defining the TCP/IP System Parameters
21
Defining System Parameters
AT node_id
Specifies the RSCS node ID of the location of the SMTP server gateway. The
local node is used when a node ID is not specified.
Usage Notes
Multiple SMTPSERVERID statements can be specified to identify multiple SMTP
servers in your environment. However, only the first instance is used by those CMS
functions that use the SMTPSERVERID definition to determine a user ID to which
SMTP-destined data should be directed.
TCPIPUSERID Statement
The TCPIPUSERID statement specifies the user ID of the TCPIP virtual machine.
TCPIPUSERID TCPIP
TCPIPUSERID user_id
Operands
user_id
Specifies the user ID of the TCPIP virtual machine. TCPIP is the default user
ID.
TRACE RESOLVER Statement
If specified, the TRACE RESOLVER statement causes a complete trace of all
queries to and responses from the name server to be written to the user’s console.
The TRACE RESOLVER statement should be used for debugging purposes only.
TRACE RESOLVER
Operands
The TRACE RESOLVER statement has no operands.
UFTSERVERID Statement
The UFTSERVERID statement identifies the virtual machine that provides UFT
services, if one exists.
UFTSERVERID user_id
Operands
user_id
Specifies the user ID of the UFT server virtual machine for the local system. A
user ID of * has special meaning and indicates the RSCS virtual machine ID
that is returned in the IDENTIFY command should be used.
22
z/VM: TCP/IP Planning and Customization
Defining System Parameters
Usage Notes
Multiple UFTSERVERID statements can be specified to identify multiple UFT
servers in your environment. However, the CMS SENDFILE command assumes the
first instance defines the UFTASYNC UFT server.
USERDATA Statement
The USERDATA statement marks the beginning of user-defined parameters that are
defined in the TCPIP DATA file.
USERDATA
ENDUSERDATA
parameter
Operands
parameter
Specifies an arbitrary, user-defined value.
Any parameters on the USERDATA statement are ignored by TCP/IP clients that
are included as part of the TCP/IP for VM feature.
VMFILETYPE Statement
The VMFILETYPE statement defines translation and line values to be associated
with a specific file extension (file type). These values are used by the NFS client, as
well as the FTP and NFS servers, when a file with this extension is processed.
VMFILETYPE
extension
,TRANSLATE=NO
,TRANSLATE=
(1)
YES
NO
,LINES=NONE
,LINES=
(1)
NL
NONE
CMS
(2)
Notes:
1
Default when no VMFILETYPEDEFAULT statement exists.
2
Used by only the NFS server.
Note: Do not include intervening spaces with the TRANSLATE= or LINES=
parameters when these are specified.
Operands
extension
Defines a file type extension for which translation and line values are being
defined; extension is a required parameter. The specified file type can begin or
end with an asterisk (*) to “wildcard” that file type.
TRANSLATE=YES
TRANSLATE=NO
Indicates whether EBCDIC-ASCII translation is performed when files with the
Chapter 3. Defining the TCP/IP System Parameters
23
Defining System Parameters
specified extension are processed. Specify TRANSLATE=YES if EBCDIC-ASCII
translation is to be performed, or TRANSLATE=NO if translation should not be
performed.
The TRANSLATE= parameter is optional. If this parameter is omitted, the
default established by the VMFILETYPEDEFAULT statement is used; if no such
statement exists, TRANSLATE=NO is assumed.
LINES=NL
LINES=NONE
LINES=CMS
Indicates whether line feed characters are inserted at CMS record boundaries
when files with the specified extension are processed. This parameter is used
by only the NFS server.
Specify LINES=NL, if line feed characters are to be inserted at CMS record
boundaries.
If LINES=NONE is specified, no line feed characters are inserted.
To maintain CMS file format, specify LINES=CMS. When CMS variable-length
record files are processed, a binary, unsigned, two-byte length field is visible at
the beginning of CMS records.
The LINES= parameter is optional. If this parameter is omitted, the default
established by the VMFILETYPEDEFAULT statement is used; if no such
statement exists, LINES=NONE is assumed.
Usage Notes
When the VM NFS client, NFS server, or FTP server compares the filetype of a file
being processed with those defined by a VMFILETYPE statement, case (upper or
lower) is ignored. For example, BIN is considered to be equivalent to Bin.
VMFILETYPEDEFAULT Statement
The VMFILETYPEDEFAULT statement defines translation and line values to be
applied to file extensions for which no VMFILETYPE statements are defined. These
default values are used by the NFS client, as well as the FTP and NFS servers,
when such files are processed.
VMFILETYPEDEFAULT TRANSLATE=NO,LINES=NONE
VMFILETYPEDEFAULT
TRANSLATE=NO
TRANSLATE=
YES
NO
,
(1)
LINES=NONE
LINES=
NL
NONE
CMS
(2)
Notes:
1
Required only when following another parameter.
2
Used by only the NFS server.
Note: Do not include intervening spaces with the TRANSLATE= or LINES=
parameters when these are specified.
24
z/VM: TCP/IP Planning and Customization
Defining System Parameters
Operands
TRANSLATE=YES
TRANSLATE=NO
TRANSLATE=NO
Indicates whether EBCDIC-ASCII translation is performed when a file is
processed. Specify TRANSLATE=YES if EBCDIC-ASCII translation is to be
performed, or TRANSLATE=NO if translation should not be performed.
The TRANSLATE= parameter is optional. If this parameter is omitted,
TRANSLATE=NO is assumed.
LINES=NL
LINES=NONE
LINES=CMS
Indicates whether line feed characters are inserted at CMS record boundaries
when files are processed. This parameter is used by only the NFS server.
Specify LINES=NL if line feed characters are to be inserted at CMS record
boundaries.
If LINES=NONE is specified, no line feed characters are inserted.
To maintain CMS file format, specify LINES=CMS. When CMS variable-length
record files are processed, a binary, unsigned, two-byte length field is visible at
the beginning of CMS records.
The LINES= parameter is optional. If this parameter is omitted, LINES=NONE
is assumed.
Testing the TCP/IP System Configuration
HOMETEST Command
The HOMETEST command can test the system configuration including
HOSTNAME, DOMAINORIGIN, and NSINTERADDR, which are defined in the
TCPIP DATA file.
HOMETEST
HOMETEST verifies that the host tables or name server, depending on the
NSINTERADDR statement, can resolve the fully qualified domain name (defined by
HOSTNAME and DOMAINORIGIN statements) for your site. In addition, the internet
addresses corresponding to your site HOSTNAME are checked against the HOME
list. This is defined in the PROFILE TCPIP file. A warning message is issued if any
addresses are missing from the HOME list.
Note: Verify that the TCPIP virtual machine has been started before you use the
HOMETEST statement.
Chapter 3. Defining the TCP/IP System Parameters
25
Defining System Parameters
26
z/VM: TCP/IP Planning and Customization
Chapter 4. Configuring the HOSTS LOCAL File
A HOSTS LOCAL file contains descriptions of local host entries in the HOSTS
format. Any domain name or IP address specified in this file is accessible for use on
your network. The HOSTS LOCAL file is used to create the site table. The site table
enables name resolution and reverse name resolution without using a domain name
server.
A sample file, HOSTS SLOCAL, is supplied with the TCP/IP distribution tapes on
the TCPMAINT 592 disk. You can copy the file to the TCPMAINT 198 disk and
customize it for use at your site. Each site is unique and requires customized
statements.
For example, the NETSTAT and TRACERTE commands use the site tables for
inverse name resolution rather than the domain name server. You must still create
the HOSTS ADDRINFO and HOSTS SITEINFO files for NETSTAT to execute
correctly. These files only need to be created once. They do not have to contain all
the hosts in the internet, nor do they have to be updated regularly.
Statement Syntax
|
|
|
The HOSTS LOCAL file can contain two types of entries:
v Host Statement
v Network Statement
|
|
|
One line of the HOSTS LOCAL file is used for each distinct host and ends with four
colons. Each line has three essential fields, separated by colons:
v The keyword HOST or NET
|
|
v A comma-separated list of internet addresses for that host
v A comma-separated list of fully qualified names for that host.
|
Host entries also have three optional fields.
For example, if you have two local hosts, LOCAL1 (internet addresses 192.6.77.4
and 192.8.4.1) and LOCAL2 (with an alias LOCALB and internet address
192.6.77.2), append the following lines to the HOSTS LOCAL file:
HOST :192.6.77.4, 192.8.4.1 :LOCAL1 ::::
HOST : 192.6.77.2 : LOCAL2, LOCALB ::::
Note: The maximum length for a host allowed in the HOST tables is 24 characters.
Names longer than this limit are truncated without warning. However, the
name server does not have a maximum character length.
HOST Statement
The HOST statement specifies the address and network name of a host that is
accessible to TCP/IP.
© Copyright IBM Corp. 1987, 2002
27
HOSTS LOCAL File
,
,
HOST : ip_addr , :
alt_addr
hostname nickname
:
:
cputype
protocols
:
opsys
::::
Parameter
Description
ip_addr
Specifies the internet address of the host.
alt_addr
Specifies the alternative internet address of the host.
hostname
Specifies the fully qualified name of the host. The name can be a
maximum of 24 characters and can include the minus sign (−) and
a period (.). Periods can only be used to delimit components of a
domain name. No blank or space characters are allowed. The
hostname is not case sensitive. The first character must be an
alpha character and the last character cannot be a minus or period.
nickname
Specifies the fully qualified nickname of the host.
cputype
Specifies the machine type or processor type.
|
opsys
Specifies the operating system of the host.
|
protocols
Specifies the protocols that are supported by the host.
NET Statement
The NET statement specifies the address and network name of the local network
that is accessible to TCP/IP.
|
,
NET : ip_addr 28
alt_addr
:
netname ::::
Parameter
Description
ip_addr
Specifies the internet address of the network.
alt_addr
Specifies the alternative internet address of the network.
netname
Specifies the fully qualified name of the network. The name can be
a maximum of 24 characters and can include the minus sign (−)
and a period (.). Periods can only be used to delimit components of
a domain name. No blank or space characters are allowed. The
netname is not case sensitive. The first character must be an alpha
character and the last character cannot be a minus or period.
z/VM: TCP/IP Planning and Customization
HOSTS LOCAL File
Building the Hosts Local Site Table
When you initially create or make changes to your HOSTS LOCAL file, you must
generate and install new HOSTS SITEINFO and HOSTS ADDRINFO files. These
files cause the fastest look-up by creating a hash table of all entries in the HOSTS
LOCAL file.
The following steps describe how to generate the HOSTS SITEINFO and HOSTS
ADDRINFO files.
1. Log on as TCPMAINT.
2. Modify the HOSTS LOCAL file on TCPMAINT 198. If this is the first time you
are modifying the HOSTS LOCAL file, you can copy the sample file, HOSTS
SLOCAL, from TCPMAINT 592 to TCPMAINT 198.
Note: The HOSTS LOCAL table may not contain more than 199,200 site
names or 69,500 IP addresses. Sites that require more entries should
consider using Domain Name Server (DNS) services.
3. Run the MAKESITE program to produce the HOSTS SITEINFO and HOSTS
ADDRINFO files from the newly modified HOSTS LOCAL file. The virtual
machine size required to process a HOSTS LOCAL file with the maximum
entries must be large enough to allocate approximately 15M of contiguous
storage.
MAKESITE
A
fm
WARN
Parameter
Description
fm
The file mode at which the HOSTS SITEINFO and HOSTS
ADDRINFO files are to be created. A is the default.
WARN
Indicates that additional warning messages should be presented
during processing, as warranted. Output files are produced at
file mode A when this operand is used.
Note: If you are processing the maximum number of entries, it is recommended
that you have defined a large virtual machine, 64M. This can take a
significant amount of time (up to two hours) to complete this task.
4. If the HOSTS SITEINFO and HOSTS ADDRINFO files exist on the TCPMAINT
592 disk, rename them, for example, to HOSTS SITEOLD and HOSTS
ADDROLD. These files are currently accessed by other TCPIP users on the
system, and should not be deleted immediately.
5. Copy the new HOSTS ADDRINFO and HOSTS SITEINFO files from your A disk
to the TCPMAINT 592 disk.
Note: The NET statement is not used by IBM-provided TCP/IP applications. It
is provided for those applications that use the getnetent() socket call.
6. Run the TESTSITE program to test the correctness of the HOSTS SITEINFO
file. This step is optional.
Chapter 4. Configuring the HOSTS LOCAL File
29
HOSTS LOCAL File
TESTSITE
When prompted for a name, enter the name you want to verify. When you have
checked all the names in question, enter QUIT.
30
z/VM: TCP/IP Planning and Customization
Chapter 5. General TCP/IP Server Configuration
This chapter describes the virtual machines and methods of server configuration for
TCP/IP.
Virtual Machine Definitions
This section describes the virtual machines that are necessary to provide basic and
optional TCP/IP services. The virtual machines listed here comprise a set of
“default” TCP/IP virtual machines that are defined as part of the z/VM system when
it is installed.
Additional or differently-named virtual machines can be defined for your system to
provide (or augment) the function provided by the “default” servers discussed in this
section. For more information about defining such virtual machines and any
applicable machine-specific requirements, see the TCP/IP for z/VM, Level 430
Program Directory.
While various TCP/IP virtual machines have specific definition requirements, all
TCP/IP servers must maintain links the following minidisks, to allow for correct
operation:
Table 1. Required TCP/IP Server Minidisk Links
Minidisk
Description
TCPMAINT 592
Client-code disk
TCPMAINT 591
Server-code disk
TCPMAINT 198
Configuration file, or customization disk
Note that much of the installation process for TCP/IP is completed as part of the
installation of z/VM itself, so the “default” TCP/IP virtual machines described in this
section, and the minidisk (or, DASD) resources they require, will have already been
defined for your system. Thus, the directory definitions (supplied with z/VM) for the
“default” TCP/IP virtual machines include links for the minidisks listed in Table 1.
Similarly, most commonly-used configuration files have been placed on the
appropriate (production) minidisks and have been suitably named for use. However,
these “production” configuration files must still be customized for your environment.
These files are discussed further in “TCP/IP Configuration File Overview” on
page 44.
Required Virtual Machines
The following virtual machines are required to provide basic TCP/IP services:
Table 2. Required Virtual Machines
Machine
Function
4TCPIP30
Maintains the TCP/IP system. Installation and service resources are
owned by this user ID.
TCPIP
Provides TCP/IP communication services. The Telnet server is
implemented as an ″internal client″ within the TCPIP virtual machine.
TCPMAINT
Owns TCP/IP production resources — the 198, 591, and 592 disks.
© Copyright IBM Corp. 1987, 2002
31
General TCP/IP Server Configuration
Optional Virtual Machines
The following table lists optional virtual machines; these servers provide optional
TCP/IP services:
Table 3. Optional Virtual Machines
32
Machine
Function
ADMSERV
The Kerberos administration server.
193
BOOTPD
Responds to client requests for boot
information contained in a BOOTP
machine file.
49
DHCPD
Responds to client requests for boot
information using information contained
in a DHCP machine file.
65
FTPSERVE
Provides File Transfer Protocol (FTP)
server support for controlled access to
files on the local VM host.
161
IMAP
Provides mail clients with access to
mail and mailboxes residing in an IMAP
Mailstore.
179
LPSERVE
Provides Line Printer Daemon (LPD)
support.
211
MPROUTE
The MPROUTE Server implements the
OSPF protocol (OSPF Version 2)
and/or the Routing Information Protocol
(RIP) Version 2, and provides an
alternative to static gateway definitions.
223
NAMESRV
The Domain Name server.
129
NDBPMGR
If an installation is going to run Network
Database (NDB), you must install one
NDBPMGR virtual machine and at least
one NDBSRVn virtual machine, which
is described in the next section.
NDBPMGR is the NDB Port Manager
virtual machine that coordinates the
NDBSRVn virtual machines.
263
NDBSRVn
If an installation is going to run Network
Database (NDB), you must install at
least one NDBSRVn virtual machine
and one NDBPMGR virtual machine,
which is described in the previous
section. NDBSRVn is the NDB server
virtual machine that runs an SQL
application by passing the database
commands to SQL/DS.®
263
PORTMAP
Runs the Portmapper function for RPC
on systems that support the Network
File System protocol.
289
REXECD
The virtual machine for the REXECD
server. It provides a remote execution
service machine for TCP/IP hosts that
support the REXEC client.
291
z/VM: TCP/IP Planning and Customization
Page
General TCP/IP Server Configuration
Table 3. Optional Virtual Machines (continued)
Machine
Function
Page
ROUTED
The RouteD Server implements the
Routing Information Protocol (RIP)
Version 1 and Version 2, and provides
an alternative to static gateway
definitions.
295
RXAGENTn
The agent virtual machines used by
REXECD to execute commands from
anonymous rexec clients.
291
SMTP
The virtual machine for the SMTP
server. It receives mail over a TCP/IP
network connection or from its virtual
reader, and then sends that mail
through the TCP/IP or RSCS network,
according to the mail destinations.
345
SNALNKA
Provides SNA LU 0 connections
between multiple hosts.
409
SNMPD
The SNMP Agent virtual machine.
417
SNMPQE
The SNMP Query Engine virtual
machine.
417
SSLSERV
The virtual machine for the SSL server.
(The SSL server runs on a
specially-configured Linux operating
system that runs in the SSLSERV
virtual machine.)
429
TFTPD
Transfers files between the BFS (Byte
File System) and TFTP clients. TFTPD
supports access to files maintained in a
BFS directory structure that is mounted
during initialization.
575
UFTD
Implements the Unsolicited File
Transfer (UFT) server.
593
VMKERB
The Kerberos Authentication server.
193
VMNFS
Implements the Network File System
(NFS) server.
267
X25IPI
Runs a VTAM® application,
Communication and Transmission
Control Program (CTCP), which
communicates to X.25 Network Control
Program Packet Switching Interface
(NPSI) through the DATE interface.
This application allows internetworking
between TCP/IP hosts using the X.25
protocol through the IBM 37xx
communication controller.
611
Methods of Server Configuration
This section describes server configuration methods that allow you to add servers
and server classes or modify the characteristics of a specific TCP/IP server virtual
machine. Duplication of existing servers is also described. Configuration changes
such as these are generally accomplished using the DTCPARMS file, described in
Chapter 5. General TCP/IP Server Configuration
33
General TCP/IP Server Configuration
“The DTCPARMS File”. Note that the DTCPARMS file is used only to configure
CMS servers; GCS servers are configured using a userid GCS file, as explained in
“GCS Servers” on page 44.
In general, the DTCPARMS file allows you to define operational aspects for TCP/IP
servers that are related to their operation within a z/VM environment, such as
ensuring the correct run-time environment or virtual machine attributes.
Protocol- or application-specific configuration support is provided through one or
more server-specific configuration files. These files are listed in summary form in
“TCP/IP Configuration File Overview” on page 44.
The DTCPARMS File
Configuration of each server is controlled by a set of files with a file type of
DTCPARMS. These files may contain two types of information:
1. Server class names that define the application protocols available for all server
virtual machines.
2. Individual server user IDs and their associated server class, as well as the
operational characteristics of the server (security, devices, parameters, etc.).
The TCP/IP server initialization program searches for server definitions in a
hierarchical fashion. The following table lists the DTCPARMS files in the order that
they are searched, along with a description of each file.
Table 4. DTCPARMS File Search
File
Purpose
userid DTCPARMS
May be used for servers that do not require configuration by the
TCP/IP administrator, such as a test server. This file will most
likely be found on a server’s file mode A.
nodeid DTCPARMS
This is useful for shared-DASD configurations. The node ID used
is the node ID returned by the CMS IDENTIFY command. This
file should be kept on the TCPMAINT 198 disk.
SYSTEM DTCPARMS
Most server configurations should be kept in this file on the
TCPMAINT 198 disk.
IBM DTCPARMS
Server classes provided by IBM, as well as the default server
configurations, are in this file. This file is on TCPMAINT 591 and
should never be modified because it will be replaced when
service is applied or when a new release is installed. Any
modifications you make should be placed in SYSTEM
DTCPARMS.
Entries for individual servers do not have to be in the same file as the server class
they reference. For example, the server entry for user ID FTPSERVE may be in
SYSTEM DTCPARMS, but its server class, ftp, may be in IBM DTCPARMS.
In addition to the DTCPARMS files, server configuration information can be
provided by server profile exits. See “Server Profile Exits” on page 41 for
information.
Configuring the DTCPARMS File
Before configuring the DTCPARMS file, you should be familiar with the format,
usage information, and tags used in this file. This information is described in the
following sections.
34
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
DTCPARMS File Format
The DTCPARMS file uses a format similar to CMS NAMES files and is maintained
using XEDIT. Two types of entries comprise this file — server definitions that
identify specific server virtual machines, and class definitions that define specific
attributes to support the application protocol used by a given server.
The following sample entries define the configuration for the TCPIP virtual machine:
:Nick.TCPIP
:Nick.stack
:Type.server :Class.stack
:Type.class
:Name.TCP/IP Stack
:Command.TCPIP
:Runtime.PASCAL
:Diskwarn.YES
:Authlog.AUTHLOG FILE A
The :Nick.TCPIP entry defines the TCPIP user ID as a server entry type; this server
is an instance of the stack server class. The :Nick.Stack entry defines the
attributes and characteristics of this class.
When entries are defined or modified, keep the following in mind:
v Entries consist of tags and tag values.
v Entries that define a server using a :Type.Server definition must also include a
:Class. tag and value to identify the class to which that server belongs.
v Tags defined as part of a server entry will be used for only that server instance
(that is, the specific virtual machine user ID identified by the :Nick. tag).
v Tags defined as part of a class entry will be used for all servers of that class
(unless overriding tags are defined as part of a server entry that references the
class).
v If multiple tags have the same name, the last one is used.
v Uppercase and lowercase characters can be used interchangeably for tags and
most of their values.
v All tags do not apply to all servers.
v Any tag not recognized is ignored without warning.
v Every entry must include either a :Type.Server or a :Type.Class definition.
|
v Values cannot start with a colon, end with a period, or otherwise have the syntax
of a tag.
DTCPARMS Tags
The following table lists DTCPARMS file tags that can be used when configuring
servers. Descriptions of these tags are also included.
Table 5. DTCPARMS Tags for Configuring Servers
Tag
Description
:Anonymous.YES
:Anonymous.NO
A value of YES will enable access to the server without requiring a
VM user ID and password.
The default is NO.
Applies to the nfs, ftp, rexec, and ndb classes only.
Chapter 5. General TCP/IP Server Configuration
35
General TCP/IP Server Configuration
Table 5. DTCPARMS Tags for Configuring Servers (continued)
Tag
Description
:Attach.raddr (option), raddr AS vaddr (option),
raddr1-raddr2 (option)
A list of real addresses to be attached to this server. This server
must have IBM privilege class A. Devices may be specified
individually or as a range. Multiple devices or ranges must be
separated by commas. Virtual address may be specified for a real
address (not an address range) by appending "AS" followed by the
virtual address.
(option) can be specified as either:
v REQuired: indicates that raddr is a required device. If a problem
is encountered during the attach of this device, server initialization
is terminated. This is the default.
v OPTional: indicates that raddr is an optional device. If a problem
is encountered during the attach of this device, an error message
is displayed and server initialization continues.
If option is specified, it must be enclosed within parentheses
Example: :attach.1500 AS 500, 400-403 (req), 800-803
Applies to the stack class only.
:Class.server_class
Identifies the TCP/IP application protocol used by this server. Select
from IBM-provided values or specify a protocol that has been defined
by a :type.class entry.
IBM-provided values: stack, rip, mproute, ftp, smtp, dns, rexec,
rexec_agent, lpd, snmp, snmpqe, bootp, tftp, dhcp, portmapper,
kerberos, kadmin, nfs, ndb, ndb_agent, uftd, ssl, imap.
:Command.command
The command to run for this server.
:CSLibs.csllib-list
CSL libraries to be added to those implicitly defined by :runtime.
:DB2_Database.dbname
Identifies the DB2® database used by this server. SQLINIT will be
issued for this database as well as a SET LANGUAGE (ADD ARI
USER.
Should be accompanied by the :vmlink. tag to access the DB2 run
disk.
For the dns class, do not specify a value for this tag if the domain
name server is running in caching-only mode, which is the default.
:Diskwarn.nn%
:Diskwarn.nn%-fm
:Diskwarn.YES
:Diskwarn.YES-fm
:Diskwarn.NO
A warning is issued if less than nn% of read/write space is available
on the indicated file mode. A value of YES only verifies that the file
mode is accessed read/write.
The percent sign is optional.
The default is NO. If no file mode is specified, file mode A is the
default.
:ESM_Enable.YES
:ESM_Enable.NO
The External Security Manager (ESM) will be used to authenticate
and authorize access to resources managed by this server.
The default is NO.
:ESM_Racroute.YES
:ESM_Racroute.NO
:ESM_Racroute.command
The command to be used for initialization and termination of a
RACROUTE environment. A value of YES causes the command
RPIUCMS to be used. A value of NO indicates that no initialization of
the RACROUTE environment is to be performed.
The default is NO.
36
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
Table 5. DTCPARMS Tags for Configuring Servers (continued)
Tag
Description
:ESM_Validate.YES
:ESM_Validate.NO
:ESM_Validate.filename
The name of a module to be used to validate user IDs and
passwords supplied by clients. This module is preloaded into
memory for improved performance. A value of YES causes RPIVAL
MODULE to be used. A value of NO prevents loading of any module
- RPIVAL module will be read from disk if :ESM_Enable.YES is
specified.
The default is NO.
:Exit.exec-name
The name of an exec to be run according to the rules defined in
“Server Profile Exits” on page 41. The output from this exec
overrides any specification returned by the global exit, TCPRUNXT
EXEC.
:For.userid
The VM user ID of the rexecd server on whose behalf this server will
do work.
There is no default.
Applies to the rexecd_agent class only.
:Loadlibs.loadlib-list
CMS LOADLIBs to be added to those implicitly defined by :runtime.
:Memory.nnnnK
:Memory.nnnnM
The minimum virtual storage size required to run server. If the virtual
machine is not large enough, an attempt will be made to define more
storage and re-IPL CMS.
If not specified, no check is performed.
:Mount.bfs-pathname
The fully-qualified Byte File System directory to be mounted as the
root directory.
Applies to the tftp class only.
Values defined for this tag can be case sensitive.
:Name.description
Provides a description of the server to be displayed when the server
is started.
Mix cased values for this tag can be preserved.
:Nick.userid
:Nick.class_name
For :type.server, the VM user ID for this TCP/IP server.
For :type.class, an arbitrary name to be referenced by a :class. tag.
:Owner.userid
User ID to receive the console log. If an invalid user ID is specified,
the log will be kept in the server’s virtual reader.
The default is TCPMAINT.
:Parms.parameters
Defines startup parameters to be passed to the server. Parameters
should be specified as defined by the syntax of the command
associated with this server.
Parameters that affect the security characteristics of a server are
automatically generated through the use of the :Anonymous. and
:ESM_Enable. tags. Therefore, these parameters should not be
specified using the :Parms. tag. See “Automatic Generation of
Selected Startup Parameters” on page 39 for more information about
parameters to which this applies.
Parameters provided through the use of the :Parms. tag may
override those that are generated automatically.
Chapter 5. General TCP/IP Server Configuration
37
General TCP/IP Server Configuration
Table 5. DTCPARMS Tags for Configuring Servers (continued)
Tag
Description
:Runtime.C
:Runtime.PASCAL
C establishes the Language Environment for VM and MVS
(SCEERUN LOADLIB).
PASCAL establishes the VS PASCAL Release 2 runtime
environment (TCPRTLIB LOADLIB).
If this tag is not specified, a specific runtime language environment is
not established.
:Stack.userid
If specified, the user ID is compared to that given in the TCPIP
DATA file. If it does not match, the server will not start.
:Type.class
:Type.server
Class identifies this entry as an application protocol definition.
Server identifies this entry as a server definition.
:vctc.vaddr1 [TO] userid vaddr2, ...
Defines a virtual channel-to-channel device and couples it to the
indicated virtual machine and address. The TO operand is optional.
Example: :vctc.200 to tcpip2 300, 201 tcpip2 301
Applies to the stack class only.
:VMLink.vmlink-specification
VMLINK-format nicknames, minidisks, or SFS directories to be
accessed. See the z/VM: CMS Command and Utility Reference for
information about VMLINK.
Example: :vmlink.* 195 tcpmaint 298 <298 G> (nonames
Customizing Servers
This section shows examples of ways to use the DTCPARMS file to customize
servers.
v The following entry attaches devices 620 through 623 to the TCPIP server, and
will issue a warning when file mode A is at least 90% full:
:Nick.TCPIP :Type.server :Class.stack
:Attach.620-623
:Diskwarn.90
v The following entry identifies the SQL1 DB2 database to be used by the
NAMESRV server.
:Nick.NAMESRV
:Type.server :Class.dns
:DB2_Database.SQL1
:VMlink.DB2DISK
:Parms.MYDNB DATA M
v The following entry specifies that RPIVAL module will be used when validating
user IDs and passwords supplied by clients for the REXECD server:
:Nick.REXECD
:Type.server :Class.rexec
:ESM_Validate.RPIVAL
v REXECD agent virtual machines can easily be defined through replicating
existing servers. They only need to be described once. REXECD startup will
automatically identify all of the agents to be used. The following entry identifies
the RXAGENT2 VM user ID that will handle anonymous REXEC requests for the
REXECD server:
:Nick.RXAGENT2
:type.server
:For.REXECD
:class.rexec_agent
v The following entry specifies for the FTPSERVE server:
– Do not issue a warning when the A-disk is read-only.
38
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
– The RPIVAL module will be used to validate user IDs and passwords supplied
by clients.
– The RPIUCMS command will be used for initializing and terminating a
RACROUTE environment.
– The server name, FTP server, will be displayed when the server is started.
:Nick.FTPSERVE :Type.server :Class.ftp
:Diskwarn.NO
:ESM_Validate.RPIVAL
:ESM_Racroute.RPIUCMS
:Name.FTP Server
Automatic Generation of Selected Startup Parameters
For certain IBM-supplied server classes, all parameters related to the use of an
external security manager (ESM) or anonymous user/login support are automatically
generated during the server initialization process.
The server classes, default server IDs, startup parameters, and tags/values that
affect this processing are listed in Table 6. For the servers listed in this table, the
parameters indicated should be omitted from any :Parms. tag definitions used for
those servers; the tags and values shown should be used instead, to allow these
parameters to be generated during server initialization.
Note: Failure to use the tags listed in Table 6 may result in incorrect or insecure
operation of the identified servers.
Table 6. Server Parameters Generated at Initialization
Server
Class
Default
Server ID
Generated
Parameter
Controlling DTCPARMS Tag/Value
rexec
REXECD
-r
-s
:ESM_Enable.YES
:Anonymous.YES¹
nfs
VMNFS
R
N
:ESM_Enable.YES
:Anonymous.YES
ftp
FTPSERVE
RACF
ANONYMOU
:ESM_Enable.YES
:Anonymous.YES
ndb_agent
NDBSRVnn
-r
:ESM_Enable.YES
Note¹: For the -s parameter to be generated as a startup parameter for an REXEC server,
the following conditions must be met:
v At least one DTCPARMS file entry must be present that defines a server of the
rexecd_agent class.
v Each REXEC agent server entry must define its agent virtual machine to be a server for a
particular REXEC server, through an appropriate :For.userid definition.
v The REXEC server entry (or the rexec class entry it references) must include an
:Anonymous.YES entry.
Adding New Servers and Server Classes
Suppose you wish to add a POP server. The TCP/IP startup code does not know
how to start a POP server because a POP server class is not provided by IBM.
Here is an example of an entry that can be included in a DTCPARMS file to define
the new server class of POPV3 and add the new POP server:
:Nick.POPV3
:Runtime.C
:Command.POP3
:Type.Class
Chapter 5. General TCP/IP Server Configuration
39
General TCP/IP Server Configuration
:Name.Post Office Protocol Server Version 3
:Nick.POP
:Class.POPV3
:Type.Server
Duplicating and Running Existing Servers
TCP/IP allows you to run more than one server of a given class, in the event such
a need arises. Use the following steps to duplicate an existing server:
Server Duplication Steps
1. Update the CP directory to define the additional server, and define any
minidisks it requires.
2. Copy the TCPROFILE EXEC to 191 minidisk defined for the new server.
3. Update the DTCPARMS file to identify the additional server(s).
4. Update PROFILE TCPIP, as required for your installation.
For any additional server virtual machines that you define, it is recommended that
you:
v maintain any naming conventions used for that server class
v model your CP directory entries after that supplied for the virtual machine your
are duplicating.
If necessary, consult the TCP/IP for z/VM, Level 430 Program Directory for specific
DASD storage and user ID requirements that may be applicable to the virtual
machine in question.
For example, assume you want to define two additional FTP servers, named
FTPSERV2 and FTPSERVX, where FTPSERV2 will make use of the same ports as
the existing FTPSERVE server, and FTPSERVX will make use of ports 1020 and
1021. After these servers and their required resources have been defined on your
system, you need to identify these servers in the DTCPARMS file. The following
statements will accomplish this, specifying that the existing ftp server class be used
for both servers:
:Nick.FTPSERV2
:Nick.FTPSERVX
:type.server
:type.server
:class.ftp
:class.ftp :parms.port 1021
To allow the new servers to be managed by the TCP/IP stack, and to allow them to
use the required ports, the PORT and AUTOLOG statements in the PROFILE
TCPIP configuration file must be updated, as follows:
AUTOLOG
FTPSERVE
FTPSERV2
FTPSERVX
PORT
21
21
1021
20
20
1020
0
0
0
FTPSERVE
FTPSERV2
FTPSERVX
FTPSERVE NOAUTOLOG
FTPSERV2 NOAUTOLOG
FTPSERVX NOAUTOLOG
Note that existing entries for the FTPSERVE server are maintained.
40
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
This configuration allows only the FTPSERVE and FTPSERV2 servers to listen on
the well-known FTP ports 20 and 21; ports 1020 and 1021 are similarly reserved for
the FTPSERVX server. Because the FTP servers only listen on port 20 and 1020
intermittently, the NOAUTOLOG operands shown prevent the stack from monitoring.
|
Server Profile Exits
|
|
|
|
|
|
Occasionally you may find that more customizing is required for a specific server
than can be provided by DTCPARMS file entries. When this need arises, a server
profile exit can be used. This exit is a REXX exec that you create, which receives
information about a server as its initialization progresses. Based on this information,
the exit may specify alternative configuration values to be used or modify some
aspects of the server runtime environment.
|
|
Use the DTCPARMS file :Exit. tag to identify your server profile exit, and to
determine the server with which it is to be used.
|
|
|
|
|
Notes:
1. When a server profile exit and the global server exit (discussed later) are both
in use, the server profile exit is called after the global exit for a given exit point.
2. Server profile exits are not applicable to GCS-based servers (such as the
SNALINK server).
|
|
|
|
Input
|
|
|
|
For each exit invocation, an upper case keyword that indicates the nature (or, type)
of the current exit point is provided. Depending on this keyword, one or more
additional values may be provided. Each exit point keyword, and any applicable
values, are described here:
|
|
|
|
|
|
|
|
SETUP class
The server class (as defined by a DTCPARMS file :Class. tag) has been
identified, but no commands have been issued. The console has been
spooled to the owning user ID for the server virtual machine (as determined
by an applicable :Owner. DTCPARMS tag), or to the default owning user ID,
TCPMAINT. Use the SETUP exit point to:
v Access additional minidisks needed by the server, or otherwise change
the CMS search order
v Return overriding DTCPARMS values
|
The information provided to the server profile exit is character data, passed as a
command line argument. This data can be retrieved using either the REXX ARG(1)
function call or the PARSE ARG statement.
For SETUP processing, any DTCPARMS tagged value can be changed.
|
|
|
|
|
|
|
BEGIN class command
The server of the indicated class will be started with the command
indicated. This exit call is made after the runtime environment has been
established, immediately before the server program command is issued. For
BEGIN processing, only these DTCPARMS tagged values can be modified:
|
|
END class return_code command
The server program has ended with the indicated return code.
|
|
|
|
ADMIN
:Command :Parms :Exit
A configuration problem that is under system administrative control has
been encountered. An explanatory error message has been displayed on
the server console.
Chapter 5. General TCP/IP Server Configuration
41
General TCP/IP Server Configuration
|
|
|
|
|
ERROR return_code command
The server cannot be started due to the failure of a needed CP or CMS
command. The failing command and its return code are passed as
additional parameters. An error message has been displayed on the server
console.
|
|
|
|
Output
|
|
Return Codes: For SETUP and BEGIN exit calls, the following return codes have
meaning:
|
0
Server initialization is to continue.
|
|
4
Server initialization is to be cancelled. The server virtual machine is to
remain logged on.
|
|
other
For all other return codes, server initialization is cancelled, and the server
virtual machine is logged off if it is running disconnected.
|
|
Return codes provided upon completion for other types of exit calls are ignored by
the initialization program.
|
|
|
DTCPARMS Override Values: When the server exit returns control with a return
code of zero (either directly, or by default) overrides to DTCPARMS file values are
accepted by the initialization program for these exit points:
|
|
SETUP
|
|
|
BEGIN
|
|
Note: DTCPARMS overrides provided upon completion for other types of
processing are ignored by the initialization program.
|
|
|
|
|
|
Examples
|
|
The examples that follow illustrate different methods of returning DTCPARMS
override values.
|
|
|
|
|
In this example, assume the server profile exit incorporates logic for
accommodating certain External Security Manager (ESM) requirements. After
having been called for SETUP processing, the exit determines appropriate
DTCPARMS values to return, for which this statement is used:
|
|
Here, no return code has been specified as part of the RETURN expression, so the
initialization program will assume a return code of zero. The server will be started
Server profile exit return codes must be specified as the first token of any
expression specified for a REXX RETURN or EXIT statement. If no return code is
given, the server initialization program assumes a return code of zero (0).
any DTCPARMS tagged value can be changed.
Only these DTCPARMS tagged values can be modified:
:Command :Parms :Exit
Because server profile exits are intended to accommodate unique installation
requirements, a sample exit of this type is not provided as part of TCP/IP for z/VM.
However, the sample global profile exit (discussed in the next section) can be used
as a guide for developing such an exit, since it utilizes the same input and output
conventions just described.
RETURN ":ESM_Enable.YES :ESM_Validate.VALIDATE"
42
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
|
|
|
using the indicated DTCPARMS file values — in place of any previously defined
:ESM_Enable. and :ESM_Validate. values, but in addition to those defined by other
DTCPARMS file tags.
|
|
|
|
|
|
For this next example, assume the server profile exit is used to facilitate testing of a
newly acquired (or modified) MODULE file, for use by the FTP server machine. For
testing purposes the module is maintained with a unique name, as is its
corresponding configuration file. For a BEGIN processing call, the exit might use
this RETURN statement :
|
|
|
In this case, the return code of 0 is specified as the first token of the RETURN
expression. Server startup will continue, using the specified command and
parameters as overrides to any previously defined :Command. and :Parms. values.
|
RETURN "0:Command.SRVFTPX1 :Parms.SRVFTPX1 TESTCFG *"
Global Profile Exit
|
|
|
|
To accommodate processing requirements that are common to all servers or a
group of similar servers, the global profile exit (TCPRUNXT EXEC) can be used.
This global server exit utilizes the same inputs and outputs as those defined for
locally developed server profile exits.
|
|
|
The TCPRUNXT EXEC, if it exits, is automatically invoked by the server
initialization program; this exit does not need to be identified within a DTCPARMS
file.
|
|
|
|
|
Notes:
|
|
|
Within the global profile exit, the REXX USERID() function — in addition to the
class argument passed to the exit — may prove useful for identifying when a
specific server is being initialized.
|
|
|
|
|
Global Profile Exit Sample
|
1. When both a server profile exit and the global server exit are in use, the server
profile exit is called after the global exit for a given exit point.
2. The global profile exit is not applicable to GCS-based servers (such as the
SNALINK server).
A sample global profile exit is provided as TCPRUNXT SEXEC on the TCPMAINT
591 minidisk. Your customized exit should be maintained on the TCPMAINT 198
minidisk, with a file type of EXEC. For more information about the supplied global
server exit, review the content of the TCPRUNXT SEXEC file.
Customizing Server-specific Exits
|
|
|
|
|
In addition to the server profile exits just described, several server-specific exits are
provided (in sample form) that can be used with certain TCP/IP servers. In general,
the exits listed in Table 7 allow you to customize various operational aspects for a
given server, to better control how its services are provided by your installation, or
to identify a set of users who are authorized to manage a particular server.
|
Table 7. TCP/IP Server-specific Exits
|
TCP/IP Server
Supported Exits
|
TCP/IP Stack
SCEXIT
|
DNS
VALIDUSER
|
FTP
FTPEXIT
PMEXIT
CHKIPADR
Chapter 5. General TCP/IP Server Configuration
43
General TCP/IP Server Configuration
|
Table 7. TCP/IP Server-specific Exits (continued)
|
TCP/IP Server
Supported Exits
|
NFS
VMNFSCMS
VMNFSMON
VMNFSSMG
|
SMTP
SMTOCMDX
SMTPFWDX
SMTPVERX
|
|
UFT
FTPEXIT
CHKIPADR
|
|
|
|
|
|
|
|
When the server exits listed in Table 7 on page 43 are customized to meet the
needs of your installation, note that commands which make use of TCP/IP services
should not be used within any of those exits. Examples of programs and functions
that should not be utilized are:
v PING, NSLOOKUP, REXEC
v TCP/IP- oriented CMS PIPE stages and Rexx Sockets APIs
v Local or third-party applications that use TCP/IP socket interfaces or other
services
|
|
|
|
|
For the TCP/IP stack server, doing so creates a situation where the stack is
required to provide TCP/IP services to itself, at which point internal interrupt
handling and blocking issues then arise. For other TCP/IP servers, similar problems
can result, not just with VMCF or IUCV communication interrupt handling, but also
with TCP/IP connection management.
|
|
|
Attempts to make use of a secondary TCP/IP ″worker″ stack to provide the desired
information will also encounter the same problems just described, regardless of the
servers involved.
|
|
|
|
|
|
Care must be taken to ensure that all commands or programs invoked within a
TCP/IP server exit do not adversely affect the operation of that server. This includes
not just TCP/IP-oriented commands, but those which can cause CMS storage
management changes, extended wait conditions, or that otherwise adversely affect
server performance. Without such care, unpredictable results or other operational
errors can and may occur.
GCS Servers
GCS servers use a userid GCS file, and if customization is needed, you should
modify this file on TCPMAINT 198 at installation. GCS servers, like CMS servers,
will display a prompt if the console is connected. The reply is "REPLY nn" to start or
"REPLY nn X" to cancel.
TCP/IP Configuration File Overview
This section presents a table that lists the various TCP/IP configuration files that
may be referenced by either TCP/IP clients, a specific TCP/IP server, or both. For
each configuration file, Table 8 on page 45 lists each (production) configuration file,
its sample counterpart (if one is supplied by IBM), the minidisk where the sample
file resides, and a reference to the chapter that provides details about the content
and use of that file.
The first five files listed in Table 8 are necessary to provide basic TCP/IP services
for most environments. The first file, IBM DTCPARMS, contains server configuration
definitions. The next two files, PROFILE TCPIP and HOSTS LOCAL, are
configuration files for the TCPIP server virtual machine. The next two files, TCPIP
DATA and ETC SERVICES, need to be accessible to all TCP/IP servers,
applications, and users; these files contain information that is (or may be)
44
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
referenced by all users. ETC GATEWAYS contains routing information for distant
networks and hosts. The remaining files are for various server virtual machines that
you might have installed. Most sites will need to create the PROFILE TCPIP,
HOSTS LOCAL and TCPIP DATA configuration files.
Table 8. Configuration Files and Minidisk Location Summary
Production
Configuration File
IBM-Supplied Sample
File
Disk
Reference Location
IBM DTCPARMS
none
591
Chapter 5, “General TCP/IP
Server Configuration” on
page 31
PROFILE TCPIP
PROFILE STCPIP
591
Chapter 24, “Configuring the
TCP/IP Server” on page 453
HOSTS LOCAL
HOSTS SLOCAL
592
Chapter 4, “Configuring the
HOSTS LOCAL File” on
page 27
TCPIP DATA
TCPIP SDATA
592
Chapter 3, “Defining the TCP/IP
System Parameters” on
page 15
ETC SERVICES
ETC SAMPSERV
592
None; refer to comments within
the supplied file.
IMAP CONFIG
IMAP SCONFIG
591
Chapter 10, “Configuring the
IMAP Server” on page 179
ROUTED CONFIG
ROUTED SCONFIG
591
Chapter 18, “Configuring the
ROUTED Server” on page 295
ETC GATEWAYS
none
-
Chapter 18, “Configuring the
ROUTED Server” on page 295
NSMAIN DATA
NSMAIN SDATA
591
Chapter 8, “Configuring the
DNS Server” on page 129
MASTER DATA
none
-
Chapter 8, “Configuring the
DNS Server” on page 129
MPROUTE CONFIG
MPROUTE SCONFIG
591
Chapter 13, “Configuring the
MPROUTE Server” on
page 223
SRVRFTP CONFIG
SRVRFTP SCONFIG
591
Chapter 9, “Configuring the FTP
Server” on page 161
LPD CONFIG
LPD SCONFIG
591
Chapter 12, “Configuring the
LPD Server” on page 211
RSCSTCP CONFIG
RSCSTCP SCONFIG
591
Chapter 19, “Configuring the
RSCS Print Server” on
page 323
RSCSLPD CONFIG
RSCSLPD SCONFIG
591
Chapter 19, “Configuring the
RSCS Print Server” on
page 323
RSCSLPR CONFIG
RSCSLPR SCONFIG
591
Chapter 19, “Configuring the
RSCS Print Server” on
page 323
RSCSLPRP CONFIG
RSCSLPRP SCONFIG
591
Chapter 19, “Configuring the
RSCS Print Server” on
page 323
SMTP CONFIG
SMTP SCONFIG
591
Chapter 20, “Configuring the
SMTP Server” on page 345
Chapter 5. General TCP/IP Server Configuration
45
General TCP/IP Server Configuration
Table 8. Configuration Files and Minidisk Location Summary (continued)
Production
Configuration File
IBM-Supplied Sample
File
Disk
Reference Location
SMTP RULES
none
-
Chapter 20, “Configuring the
SMTP Server” on page 345
UFTD CONFIG
UFTD SCONFIG
591
Chapter 26, “Configuring the
UFT Server” on page 593
VMNFS CONFIG
VMNFS SCONFIG
591
Chapter 15, “Configuring the
NFS Server” on page 267
PW SRC
none
-
Chapter 22, “Configuring the
SNMP Servers” on page 417
SNMPTRAP DEST
none
-
Chapter 22, “Configuring the
SNMP Servers” on page 417
X25IPI CONFIG
X25IPI SCONFIG
591
Chapter 28, “Configuring the
X.25 Interface” on page 611
As mentioned previously, most commonly-used configuration files are copied to the
appropriate (production) minidisks, and are suitably named for use when z/VM is
installed.
Should you need to customize a specific configuration file, note the following:
v IBM-supplied end-user sample files are supplied on the TCPMAINT 592 minidisk.
When such a file is customized, the sample file should be copied to this same
disk (TCPMAINT 592) as its production file name and type; changes should then
be made to the production configuration file.
v IBM-supplied server-related sample files are supplied on the TCPMAINT 591
minidisk. When such a file is customized, the sample file should be copied to the
configuration disk (TCPMAINT 198) as its production file name and type;
changes should then be made to the file on the configuration disk.
Notes:
1. For optional TCP/IP services, you need to configure only those files referenced
by the TCP/IP servers you plan to use.
2. Because the PW SRC file contains passwords, you should control access to
these files if security is a concern.
Starting and Stopping TCP/IP Servers
The services provided or managed by a specific TCP/IP server virtual machine can
often be stopped (and to a lesser extent, started or altered) by using a
server-specific interface that provides support for dynamic operations. The TCP/IP
servers that support dynamic operations in some manner are listed here:
v TCP/IP stack, via the NETSTAT and OBEYFILE commands
v RouteD server, via an SMSG command interface
v MPROUTE server, via an SMSG command interface
v
v
v
v
v
46
DNS server, via an SMSG command interface
BOOTP server via console commands
FTP server, via an SMSG command interface
IMAP server, via its IMAPMAIN and IMAP Administration command interface
LPD server, via an SMSG command interface
z/VM: TCP/IP Planning and Customization
General TCP/IP Server Configuration
v
v
v
v
NFS server, via an SMSG command interface
SMTP server, via an SMSG command interface
SSL server, via its associated SSLADMIN command interface
UFT server, via console commands.
For detailed information about dynamic operational support for these servers, refer
to the respective server configuration chapters.
Stopping TCP/IP Servers
When it is necessary to stop a specific TCP/IP server for which there is no dynamic
control interface (or no ″stop″ or ″shutdown″ command is available), use the
following procedure:
1. Log on to the server to be stopped.
2. Enter the #CP EXTERNAL command to initiate the shutdown of the server. In some
cases, other prompts may be issued to determine if the shutdown of the service
machine should continue; the text of these prompts varies somewhat from
server to server. Also, you should allow sufficient time for the shutdown to
complete before issuing additional commands.
If you receive the message:
DMSHDE744R
interrupt
CODE=0040,
Enter a 1
Unexpected external interrupt detected,
status consists of:
CPUID=0000, PARAMETER=00000000.
for ABEND or a 2 for RESUME:
enter 1. You will return to the CMS command line.
You can now manipulate any files that may have been created while the server was
running.
|
|
|
|
|
|
|
Note: The #CP EXTERNAL command should not be used to stop MPROUTE, RouteD
or the SSL servers. The command to stop MPROUTE and RouteD is #CP
SMSG * SHUTDOWN. For information on the MPROUTE server, see Chapter 13,
“Configuring the MPROUTE Server” on page 223. For more information on
stopping the RouteD server, see “Using the SMSG Interface to RouteD” on
page 319. The command to stop the SSL server is SSLADMIN STOP. For more
information, see “SSLADMIN STOP Command” on page 448.
Starting TCP/IP Servers
Individual TCP/IP servers can be started as needed by using the CP XAUTOLOG
command, or by logging on to a server and executing its PROFILE exec and then
providing appropriate responses to any prompts that are issued. Starting servers in
this way may prove useful when initially configuring TCP/IP services or diagnosing
problems.
Chapter 5. General TCP/IP Server Configuration
47
48
z/VM: TCP/IP Planning and Customization
Chapter 6. Configuring the BOOTP Server
The BOOTP server (daemon) responds to client requests for boot information using
data maintained in a BOOTP machine file. This data includes the IP address of the
client, the IP address of the TFTP daemon and information about the files to
request from the TFTP daemon.
To configure the BOOTP server, you must perform the following steps:
BOOTP Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the BOOTP server.
3. Customize the ETC BOOTPTAB file.
Dynamic Server Operation
The BOOTP server provides a console subcommand interface that allows you to
perform various server administration tasks. For more information see “Dynamic
Server Operation” on page 52.
Step 1: Update PROFILE TCPIP
Include the BOOTP server virtual machine user ID in the AUTOLOG statement of
the TCPIP server configuration file. The BOOTP server is then automatically started
when TCPIP is initialized. The IBM default user ID for this server is BOOTPD. Verify
that the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
BOOTPD
0
The BOOTP server requires that port UDP 67 be reserved for it. Verify that the
following statement has been added to your TCPIP server configuration file as well:
PORT
67 UDP BOOTPD
; BOOTP Server
Step 2: Update the DTCPARMS File
When the BOOTP server is started, the TCP/IP server initialization program
searches specific DTCPARMS files for configuration definitions that apply to this
server. Tags that affect the BOOTP server are:
:Nick.BOOTPD
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the BOOTP server if you:
v Change the parameters passed to the BOOTPD command.
© Copyright IBM Corp. 1987, 2002
49
BOOTP Server
If no parameters are specified on the :Parms. tag of the DTCPARMS file,
the BOOTP server is initialized with the following parameters:
MACHINE ETC BOOTPTAB *
Step 3: Customize the ETC BOOTPTAB File
The BOOTP server searches the ETC BOOTPTAB file for information when it
attempts to satisfy BOOT requests generated by BOOTP clients on the network.
Before you use the BOOTP server, you need to customize the ETC BOOTPTAB file
with information about the BOOTP clients (such as IBM Network Stations) that will
be used in your environment.
A sample configuration file is provided as BOOTP SAMPLE on the TCPMAINT 591
disk. Your customized ETC BOOTPTAB file should be copied to the TCPMAINT 198
minidisk as ETC BOOTPTAB. See the comments within the ETC BOOTPTAB file
for detailed information about how to specify entries within this file.
BOOTPD Command
BOOTP services are initiated using the BOOTPD command:
BOOTPD
MACHINE ETC BOOTPTAB *
MACHINE fn
BOOTPTAB*
CONFIG fn
BOOTPTAB*
ft
(1)
(1)
*
fm
ft
(1)
(1)
(1)
*
fm
(
LURK
STAYUP
TRACE
Notes:
1
If filemode is specified as an “*” or is defaulted, the first file in the search
order that matches filename and filetype is used.
Specify BOOTPD command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
MACHINE
Indicates that the file specification that follows specifies a file containing client
information.
50
z/VM: TCP/IP Planning and Customization
BOOTP Server
fn The file name of the file to load.
ft
The file type of the file to load.
fm The file mode of the file to load.
CONFIG
Indicates that the file specification that follows specifies a file containing
configuration information. This information lists adapters on the host which
should be monitored and those that should not. Also, whether forwarding of
BOOT requests should occur and when and where they should be sent.
LURK
Indicates that the BOOTP daemon should never respond to a client request. It
should only listen.
STAYUP
Indicates that the BOOTP daemon should continue to operate across VM
TCP/IP failures.
TRACE
Indicates that the BOOTP daemon should display debug information as
requests are processed.
Usage Notes
v MACHINE and CONFIG are reserved keywords. They may not be used as file
names or file types.
v The defaults for the BOOTPD command when no operands or options are
specified are:
– “ETC BOOTPTAB *” is the machine file,
– LURK mode is disabled,
– STAYUP mode is disabled,
– TRACE mode is disabled,
– No configuration file is used; thus, the BOOTP daemon will listen to BOOT
requests received on any IP address.
v The configuration file is composed of blank lines, comment lines, and
configuration statements. Configuration statements have the same function and
syntax as the BOOTPD EXCLUDE, FORWARD, and INCLUDE subcommands.
The format of the configuration file is:
– One line per statement.
– Blank lines are ignored.
– Comment lines are ignored. Comment lines are lines where the first non-blank
character is an asterisk (*) or pound symbol (#)..
v The machine file is composed of blank lines, comment lines, entry lines for the
clients, and tag control lines used to decipher the entry lines. The format and
content of this file is described further by comments within the BOOTPTAB
SAMPLE file.
v A machine file (table) must exist for the BOOTP server to initialize and operate.
This file is required because it provides the BOOTP daemon with information
necessary to satisfy client BOOT requests.
However, there are cases when a BOOTP daemon may not need a functional
machine file. One example is the case when the BOOTP server in question acts
as a gateway and forwards all requests to another server. In this case, a
machine file which contains only blank lines or comment lines may be used for
the gateway server.
Chapter 6. Configuring the BOOTP Server
51
BOOTP Server
v STAYUP is needed only when the TCP/IP stack machine does not contain an
AUTOLOG entry for the virtual machine running BOOTP.
Dynamic Server Operation
Some configuration attributes (such as tracing and client request handling) can be
changed during server execution using the BOOTPD subcommands described in
the next section. In addition, certain server activities can be queried or changed by
subcommands. Any subcommand not understood by the BOOTP server is assumed
to be a CMS command and is passed to the CMS command line for execution.
Issue BOOTPD subcommands at the BOOTP server console.
BOOTPD Subcommands
The BOOTPD subcommands are listed in Table 9. This table provides the shortest
abbreviation, a description, and a
page reference for more information for each BOOTPD subcommand.
Table 9. BOOTPD Subcommands
Minimum
Subcommand Abbreviation Description
CMS
CMS
Passes a command to CMS for execution.
52
CONFIG
CONFIG
Displays configuration information.
53
EXCLUDE
EXCLUDE
Identifies adapter addresses for which BOOT
requests should be ignored.
55
EXIT
EXIT
Stops the BOOTPD server and its processing. EXIT is
equivalent to QUIT and STOP.
56
FORWARD
FORWARD
Controls the forwarding of BOOT requests to another
BOOTPD server.
56
HELP
HELP
Displays a summary of BOOTPD subcommands.
58
INCLUDE
INCLUDE
Identifies adapter addresses for which BOOT
requests should be handled.
59
LURK
LURK
Toggles the LURK mode of the BOOTPD server.
60
QUIT
QUIT
Stops the BOOTPD server and its processing. QUIT
is equivalent to EXIT and STOP.
60
RELOAD
RELOAD
Reloads BOOTPD machine and configuration files.
60
STAYUP
STAYUP
Toggles the STAYUP mode of the BOOTPD server.
62
STOP
STOP
Stops the BOOTPD server and its processing. STOP
is equivalent to EXIT and QUIT.
62
TRACE
TRACE
Toggles the TRACE mode of the BOOTPD server.
62
CMS Subcommand
Use the CMS subcommand to issue a command to CMS.
52
Page
z/VM: TCP/IP Planning and Customization
BOOTP Server
CMS
cms_command
Operands
cms_command
The CMS command to be issued.
Usage Notes
v Do not issue any CMS command that would take considerable time to execute
(for example, XEDIT). While the CMS command executes, the server does not
respond to requests.
v The CMS keyword is usually not required because the daemon will pass any
command string that is not recognized as a BOOTPD subcommand to CMS. The
CMS keyword is used to identify CMS commands which would normally be
interpreted as a BOOTPD subcommand, for example, TRACE.
v After completion of any command, the following ready prompt is displayed:
BOOTPD Ready;
or
BOOTPD Ready (rc);
if the return code (rc) is not zero.
CONFIG Subcommand
Use the CONFIG subcommand to display configuration information.
CONFIG
Usage Notes
v This subcommand causes the BOOTP daemon to query the current TCP/IP
configuration of the host where the BOOTP daemon is running, to determine the
IP addresses defined for that host. Any included adapter that is not in the defined
IP address list will be automatically excluded as the result of this subcommand’s
operation, whether or not the subcommand completes successfully.
v This subcommand produces a multiple line response which indicates the status
of settings, table files used, included and excluded adapter addresses, and
forwards that are active or could be activated. This output is discussed below, in
sections, for clarity of meaning.
Lurk=l Stayup=s Trace=t
Machine Table=filespec
Configuration Table=filespec
This section indicates the status of the LURK, STAYUP, and TRACE settings,
along with the file specifications for the machine and configuration table files
used by the server.
Chapter 6. Configuring the BOOTP Server
53
BOOTP Server
l
is 1 if LURK mode is on; 0 if LURK mode is off.
s
is 1 if STAYUP mode is on; 0 if STAYUP mode is off.
t
is 1 if TRACE mode is on; 0 if TRACE mode is off.
filespec
is the file name, file type and file mode of the file that is in use.
Included Addresses:
Adapter adpaddr reqtype
This section indicates the IP addresses of adapters for which the BOOTP
daemon will process requests. One “Adapter” line is displayed for each adapter
that the BOOTP daemon will handle. If there are no included addresses, “NONE”
is displayed instead of the “Adapter” line(s).
adpaddr
is the IP address of an adapter on the host system.
reqtype
is the type of request that will be handled. Possible values are:
CLIENTS
for BOOT requests broadcast by clients to the host.
GATEWAYS
for BOOT requests forwarded by a BOOTP daemon on
behalf of a client.
ANY
for any client or gateway forwarded requests.
Excluded Addresses:
Adapter adpaddr reqtype
This section indicates the IP addresses of adapters the BOOTP daemon should
ignore. If there are no excluded addresses, “NONE” is displayed instead of the
“Adapter” line(s).
adpaddr
is the IP address of the adapter.
reqtype
is the type of request that will be excluded. Possible values are:
CLIENTS
for BOOT requests broadcast by clients to the host.
GATEWAYS
for BOOT requests forwarded by a BOOTP daemon on
behalf of a client.
ANY
for any client or gateway forwarded requests.
Forwards:
Adapter adpaddr -> toaddr frequency actflag
Gateway gateaddr -> toaddr frequency
This section indicates whether BOOT request forwarding has been specified for:
– requests received on specific adapters, or
– requests forwarded by a specific gateway.
adpaddr
is the IP address of the adapter.
54
z/VM: TCP/IP Planning and Customization
BOOTP Server
gateaddr
is a gateway IP address. The gateway IP address is the address of an
adapter on which a request is initially received, but is then forwarded.
toaddr
is the IP address of a host that is running another BOOTP daemon which
should receive forwarded requests.
frequency
is an indication of when forwarding should occur for the specified adapter or
gateway. This value can be either:
ALWAYS
indicating that any request on the adapter or forwarded by
the gateway should always be forwarded.
UNKNOWN
indicating that forwarding should occur only for requests on
the given adapter, or forwarded by a gateway, when they
cannot be handled using this daemon’s machine file.
actflag
indicates the status of the adapter for which the forward has been specified.
This value can be either:
INCLUDED
indicating that the adapter is included in the configuration
and handles both client and gateway-forwarded requests.
EXCLUDED
indicating that the adapter is excluded from the configuration
(for example, no forwarding will occur until the adapter is
included in the configuration).
PARTIAL
indicating that some BOOT requests received on the adapter
will not be handled. This can occur if the EXCLUDE or
INCLUDE subcommand resulted in some BOOT requests not
being handled. For example, gateway forwarded requests
received over a specific adapter may be excluded, while
client requests may be included. For more information about
how to control request handling see “INCLUDE
Subcommand” on page 59 and “EXCLUDE Subcommand”.
EXCLUDE Subcommand
Use the EXCLUDE subcommand to specify an adapter address to ignore. You can
specify additional operands to indicate whether all requests received across a
specific adapter should be ignored, or whether only client BOOT requests or
gateway-forwarded requests should be ignored.
EXCLUDE
ADApter ipaddr
SUBnet netaddr
ALL
ANY
CLIents
GATeways
ANY
Operands
ADApter ipaddr
The IP address of the adapter on the host system that should be ignored.
Chapter 6. Configuring the BOOTP Server
55
BOOTP Server
SUBNET netaddr
The address of a subnet that should be ignored. Any host adapter address that
is part of the specified subnet is ignored; netaddr may be any address valid for
the subnet.
ALL
Indicates that all adapters should be ignored.
ANY
Indicates that any request that is received on the specified adapters (or
adapters associated with a subnet, or “ALL”) should be ignored. This is the
default.
CLIents
Indicates that only client BOOT requests that are received on the specified
adapters (or adapters associated with a subnet, or “ALL”) should be ignored.
GATeways
Indicates that gateway-forwarded requests that are received on the specified
adapters (or adapters associated with a subnet, or “ALL”) should be ignored.
Usage Notes
v The opposite of the EXCLUDE subcommand is the INCLUDE subcommand. Any
values set by the EXCLUDE subcommand may be reset by the INCLUDE
subcommand.
v This subcommand causes the BOOTP daemon to query the current TCP/IP
configuration of the host where the BOOTP daemon is running, to determine the
IP addresses defined for that host. Any included adapter that is not in the defined
IP address list will be automatically excluded as the result of this subcommand’s
operation, whether or not the subcommand completes successfully.
EXIT Subcommand
Use the EXIT subcommand to stop the BOOTP daemon. This subcommand is
equivalent to the QUIT and STOP subcommands.
EXIT
Operands
The EXIT subcommand has no operands.
FORWARD Subcommand
Use the FORWARD subcommand to specify BOOT requests that should be
forwarded to another BOOTP daemon at another IP address. Requests are selected
based upon the adapter on which they are received or the gateway from which they
were forwarded.
FORWARD
56
ADApter ipaddr
SUBnet netaddr
GATeway gateaddr
ALL
z/VM: TCP/IP Planning and Customization
TO
toipaddr
ALWAYS
ALWays
UNKnown
NEVer
BOOTP Server
Operands
ADApter ipaddr
Indicates that BOOT requests received over the specified IP address should be
forwarded. The IP address is the address of an adapter on the host system that
would receive the request.
SUBnet netaddr
Indicates that BOOT requests received over the IP addresses that are part of
the specified subnet should be forwarded; netaddr may be any address valid for
the subnet.
GATeway gateaddr
Indicates that BOOT requests that were forwarded by a gateway at the
specified IP address should be forwarded.
ALL
Indicates that all IP adapter addresses should be handled as forwarding
addresses.
TO toipaddr
Indicates the IP address to which the BOOT request should be forwarded.
ALWAYS
Indicates that BOOT requests that pass the selection criteria (for example, on
the specified adapter or from the specified gateway) should always be
forwarded. This is the default.
UNKNOWN
Indicates that BOOT requests that pass the selection criteria (for example, on
the specified adapter or from the specified gateway) but cannot be handled
using this daemon’s machine file should be forwarded. Requests for clients that
are in the machine file are not forwarded.
NEVER
Indicates that BOOT requests that pass the selection criteria (for example, on
the specified adapter or from the specified gateway) should never be forwarded.
This cancels the forwarding that may have been previously specified for the
BOOT requests that match the criteria.
Usage Notes
v Forwarding applies only to requests that are not excluded by the EXCLUDE
subcommand.
v Forwarding specified for a gateway takes precedence over forwarding specified
for an adapter.
v A hop count is maintained in the BOOT request. This hop count is incremented
each time a BOOTP daemon forwards the request. BOOTPD will not forward a
request whose hop count is three or more.
v The BOOT request contains a server name field. This field allows the client to
specify the host name of a BOOTP daemon which should process the request. If
the target BOOTP daemon is not the receiving server, and the address of the
server is not on the same cable as the adapter that received the request, then
the request will be forwarded.
Normally, a request is not forwarded to a target BOOTP daemon when the target
daemon is on the same cable as the adapter of the BOOTP daemon that
receives the original request. Such forwarding is not done because it’s assumed
that the target daemon would have heard this same request.
Chapter 6. Configuring the BOOTP Server
57
BOOTP Server
However, you can override this and force a request to be sent to such a target
daemon. If a FORWARD to a specific IP address is defined for a receiving
adapter, requests will always be forwarded to the BOOTP daemon at that IP
address.
v Requests that are forwarded by a gateway contain a gateway IP address. The
BOOTP server specifies this gateway IP address as the address of the adapter
which receives the original request. This allows the BOOTP daemon, which
ultimately builds the response packet for the requesting client, to send that
packet to the correct gateway; that gateway then sends the response packet to
the client.
Only the BOOTP daemon that initially hears the client request acts as the
gateway; subsequent forwarding of the request by other BOOTP daemons does
not change the gateway IP address.
v Forwarding is useful if you wish to centralize your machine files on a specific
host and have other BOOTP daemons forward their received requests to the
central site for processing. When you set up forwarding in this manner, you must
take into account the increased load on the central server and the time required
to forward requests. If the interval to respond to a client request is too long, that
client may then retransmit its requests, and increase the network load.
The following is a simple example of forwarding to central sites. The
configuration consists of four hosts that run VM BOOTP daemons:
VMSAT1, VMSAT2
Satellite VM hosts running BOOTP daemons connected to
subnets with clients that submit BOOT requests.
VMMAIN
Main VM host running BOOTP for responding to BOOT requests
from VMSAT1 and VMSAT2.
VMCENT
Central Master VM HOST containing a master machine file.
In this example, requests received by the VMSAT1 or VMSAT2 are automatically
routed to VMMAIN. This allows VMSAT1 and VMSAT2 to run BOOTP daemons
which do not maintain a functional machine file. A FORWARD statement would
appear in the configuration files for VMSAT1 and VMSAT2 as:
FORWARD ALL TO xxx.xxx.xxx.xxx ALWAYS
where xxx.xxx.xxx.xxx is the IP address of VMMAIN.
Normally, all requests are satisfied by VMMAIN. If VMMAIN cannot handle a
request, that request is forwarded to VMCENT, which runs a BOOTP daemon
with the master table file for VMMAIN and other VMMAIN-type hosts. The
FORWARD statement would appear in the VMMAIN configuration file as:
FORWARD ALL TO yyy.yyy.yyy.yyy UNKNOWN
where yyy.yyy.yyy.yyy is the IP address of VMCENT.
v This subcommand causes the BOOTP daemon to query the current TCP/IP
configuration of the host where the BOOTP daemon is running, to determine the
IP addresses defined for that host. Any included adapter that is not in the defined
IP address list will be automatically excluded as the result of this subcommand’s
operation, whether or not the subcommand completes successfully.
HELP Subcommand
Use the HELP subcommand to display a brief description of available
subcommands.
58
z/VM: TCP/IP Planning and Customization
BOOTP Server
HELP
Operands
The HELP subcommand has no operands.
INCLUDE Subcommand
Use the INCLUDE subcommand to specify the adapter address or address of
BOOTP forwarding daemons for which requests should be handled.
INCLUDE
ADApter ipaddr
SUBnet netaddr
ALL
ANY
CLIents
GATeways
ANY
Operands
ADApter ipaddr
The IP address of the adapter on the host system for which requests should be
handled.
SUBnet netaddr
The address of a subnet for which requests should be handled. Any host
adapter address that is part of the specified subnet is handled; netaddr may be
any address valid for the subnet.
ALL
Indicates that requests from all adapters should be handled.
ANY
Indicates that any request that is received on the specified adapters (or
adapters associated with a subnet, or “ALL”) should be handled. This is the
default.
CLIents
Indicates that only client BOOT requests that are received on the specified
adapters (or adapters associated with a subnet, or “ALL”) should be handled.
GATeways
Indicates that gateway-forwarded requests that are received on the specified
adapters (or adapters associated with a subnet, or “ALL”) should be handled.
Usage Notes
v The opposite of the INCLUDE subcommand is the EXCLUDE subcommand. Any
values set by the INCLUDE subcommand may be reset by the EXCLUDE
subcommand.
v This subcommand causes the BOOTP daemon to query the current TCP/IP
configuration of the host where the BOOTP daemon is running, to determine the
IP addresses defined for that host. Any included adapter that is not in the defined
IP address list will be automatically excluded as the result of this subcommand’s
operation, whether or not the subcommand completes successfully.
Chapter 6. Configuring the BOOTP Server
59
BOOTP Server
LURK Subcommand
Use the LURK subcommand to toggle the LURK mode in the BOOTP daemon. If
the daemon is already operating in LURK mode, it will resume answering requests
from clients. If the daemon is not operating in LURK mode, it will begin to listen for,
but not will not respond to, client requests.
LURK
Operands
The LURK subcommand has no operands.
Usage Notes
v The following is displayed upon completion of this subcommand:
LURK is now l
where l is 0 if LURK mode is off; 1 if LURK mode is on.
QUIT Subcommand
Use the QUIT subcommand to stop the BOOTP daemon. This subcommand is
equivalent to the EXIT and STOP subcommands.
QUIT
Operands
The QUIT subcommand has no operands.
RELOAD Subcommand
Use the RELOAD subcommand to reload the machine or configuration table.
60
z/VM: TCP/IP Planning and Customization
BOOTP Server
RELOAD
MACHINE
MACHINE
ETC
BOOTPTAB
CNFBOOTPTAB*
filename
(1)
(1)
ETCBOOTPTAB*
filename
CONFIG
*
BOOTPTAB *
(1)
(1)
*
filemode
filetype
(1)
BOOTPTAB *
filetype
(1)
*
(1)
filemode
Notes:
1
If filemode is specified as an asterisk '*' or is defaulted, the first file in the
search order that matches filename and filetype is used.
Operands
MACHINE
Indicates that the file to be loaded is a machine file that contains client
information.
CONFIG
Indicates that the file to be loaded is a configuration file.
filename
The file name of the machine or configuration file to load.
filetype
The file type of the file to load.
filemode
The file mode of the file to load.
Usage Notes
v MACHINE and CONFIG are reserved keywords. They may not be used as file
names or file types.
v The configuration file is composed of blank lines, comment lines, and
configuration statements. Configuration statements have the same function and
syntax as the BOOTPD EXCLUDE, FORWARD, and INCLUDE subcommands.
The format of the configuration file is:
– One line per statement.
– Blank lines are ignored.
– Comment lines are ignored. Comment lines are lines where the first non-blank
character is an asterisk (*) or pound symbol (#).
Chapter 6. Configuring the BOOTP Server
61
BOOTP Server
v The machine file is composed of blank lines, comment lines, entry lines for the
clients, and tag control lines used to decipher the entry lines. The format and
content of this file is described further by comments within the BOOTPTAB
SAMPLE file.
v When a configuration file is processed, all adapters are assumed to be included
and no forwarding exists until specified otherwise by configuration file statements.
v If the machine file is successfully loaded, the following response is displayed:
fn ft fm loaded in secs seconds.
Table reloaded from fn ft fm
BOOTPD Ready;
where fn, ft, and fm are the respective file name, file type and file mode of the
loaded file, and secs is the time required to load the file.
STAYUP Subcommand
Use the STAYUP subcommand to toggle the STAYUP mode in the BOOTP
daemon. If the daemon is already operating in STAYUP mode, it will cease
operating in this mode and will end processing if a subsequent TCP/IP failure
occurs. If the daemon is not operating in STAYUP mode, it will begin to ensure
processing will not end if a subsequent TCP/IP failure occurs.
STAYUP
Operands
The STAYUP subcommand has no operands.
Usage Notes
v This subcommand is needed only when the TCP/IP stack machine does not
contain an AUTOLOG entry for the virtual machine running BOOTPD.
v The following is displayed upon completion of the subcommand:
STAYUP is now s
where s is 0 if STAYUP mode is off; 1 if STAYUP mode is on.
STOP Subcommand
Use the STOP subcommand to stop the BOOTP daemon. This subcommand is
equivalent to the EXIT and QUIT subcommands.
STOP
Operands
The STOP subcommand has no operands.
TRACE Subcommand
Use the TRACE subcommand to toggle the TRACE mode in the BOOTP daemon. If
the daemon is already operating in TRACE mode, it will cease displaying debug
information as it processes requests. If the daemon is not operating in TRACE
mode, it will display debug information as it processes requests.
62
z/VM: TCP/IP Planning and Customization
BOOTP Server
TRACE
Operands
The TRACE subcommand has no operands.
Usage Notes
v The following is displayed upon completion of this subcommand:
TRACE is now t
where t is 0 if TRACE mode is off; 1 if TRACE mode is on.
v See the TCP/IP Diagnosis Guide for a description of BOOTP server trace output.
Chapter 6. Configuring the BOOTP Server
63
BOOTP Server
64
z/VM: TCP/IP Planning and Customization
Chapter 7. Configuring the DHCP Server
The DHCP daemon (the DHCPD server) responds to client requests for boot
information using information contained in a DHCP machine file. This information
includes the IP address of the client, the IP address of the TFTP daemon and
information about the files to request from the TFTP daemon.
Unlike the BootP daemon, each client (with its assigned IP address) that is serviced
by the DCHP deamon does not need to be listed in a machine file. IP addresses
may be allocated:
Dynamically
An IP address is temporarily assigned to the client for a specified
period of time. The "lease" on the address must be renewed prior to
the end of the specified lease if the client wishes to keep using the
IP address.
Automatically An IP address is permanently assigned to a client from the list of
available addresses.
Manually
A specific IP address (specified in the machine file) is assigned to
the client.
To configure the DHCPD virtual machine, you must perform the following steps:
DHCPD Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for DHCPD.
3. Configure the ETC DHCPTAB file.
4. Construct a DHCPD machine file.
Step 1: Update PROFILE TCPIP
Include the DHCP server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The DHCP server is then automatically started
when TCPIP is initialized. The IBM default user ID for this server is DHCPD. Verify
that the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
DHCPD 0
The DHCPD server listens on port 67. Verify that the following statement is added
to your TCPIP server configuration file as well:
PORT
67 UDP DHCPD
; DHCPD; Server
The DHCPD; server uses raw IP functions. Verify that the following statement is
added to your TCPIP server configuration file:
OBEY
DHCPD
ENDOBEY
© Copyright IBM Corp. 1987, 2002
65
DHCP Server
Step 2: Update the DTCPARMS File for DHCPD
When the DHCP server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the DHCP server are:
:Nick. DHCPD
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the DHCP server if you change
the parameters passed to the DHCPD command.
If no parameters are specified on the :Parms. tag in the DTCPARMS file, the
DHCP server is initialized with the following parameters:
MACHINE ETC DHCPTAB *
Step 3: Configure the ETC DHCPTAB File
The DHCPD server searches the ETC DHCPTAB file for information when it
attempts to satisfy DHCP requests generated by BootP or DHCP clients on the
network. Before you use the DHCPD; server, you need to customize the ETC
DHCPTAB file with information about the IBM Network Stations that will be used in
your environment. See “Step 4: Construct a DHCPD Machine File” on page 71 for
detailed information about how to specify entries within this file. The customized
ETC DHCPTAB file should remain on the TCPMAINT 198 minidisk.
DHCPD Command
DHCP services are initiated using the DHCPD command:
66
z/VM: TCP/IP Planning and Customization
DHCP Server
DHCPD
MACHINE ETC DHCPTAB *
MACHINE fn
DHCPTAB *
DHCPTAB *
ft
(1)
(1)
*
fm
ft
CONFIG fn
(1)
(1)
(1)
*
fm
(
LURK
STAYUP
TRACE
Notes:
1
If filemode is specified as an asterisk "*" or is defaulted, the first file in the
search order that matches filename and filetype is used.
Specify DHCPD command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
MACHINE
indicates that the file specification that follows specifies a file containing client
information.
fn is the file name of the file to load.
ft
is the file type of the file to load.
fm is the file mode of the file to load.
CONFIG
indicates that the file specification that follows specifies a file containing
configuration information. This information lists adapters on the host which
should be monitored and those that should not. Also, whether forwarding of
BootP/DHCP requests should occur, and when and where they should be sent.
LURK
indicates that the DHCP daemon should never respond to a client request. It
should only listen.
STAYUP
indicates that the DHCP daemon should continue to operate across VM TCP/IP
failures.
TRACE
indicates that the DHCP daemon should display debug information as requests
are processed.
Chapter 7. Configuring the DHCP Server
67
DHCP Server
Usage Notes
v The DHCP server saves information on the addresses that are in use and the
clients that are using them in a file on the daemon’s A-disk. This file, DHCPD
BINDINFO, is read at server initialization and is updated as the status of
supported clients and addresses changes over time.
A work file, DHCPDWRK BINDINFO, is maintained in addition to the DHCPD
BINDINFO file. Neither of these files should be changed by the user.
v MACHINE and CONFIG are reserved keywords. They may not be used as file
names or file types.
v The defaults for the DHCPD command when no operands or options are
specified are:
– "ETC DHCPTAB *" is the machine file,
– LURK mode is disabled,
– STAYUP mode is disabled,
– TRACE mode is disabled,
– No configuration file is used; thus, the DHCP daemon will listen for BootP and
DHCP requests received on any IP address.
v The configuration file is composed of blank lines, comment lines, and
configuration statements. Configuration statements have the same function and
syntax as the DHCPD EXCLUDE, FORWARD, and INCLUDE subcommands.
The format of the configuration file is:
– One line per statement.
– Blank lines are ignored.
– Comment lines are ignored. Comment lines are lines where column one is an
asterisk (*) or pound symbol (#).
v The machine file is composed of blank lines, comment lines, entry lines for the
clients, and tag control lines used to decipher the entry lines. The format and
content of this file is described further in the section “DHCPD Machine
Statements” on page 80.
v A machine file (table) must exist for the DHCP server to initialize and operate.
This file is required because it provides the DHCP daemon with information
necessary to satisfy client BootP/DHCP requests.
However, there are cases when a DHCP daemon may not need a functional
machine file. For example, when the DHCP server in question acts as a gateway
and forwards all requests to another server. Here, a machine file which contains
only blank lines or comment lines may be used for the gateway server.
v STAYUP is needed only when the TCP/IP machine does not contain an entry for
the virtual machine running DHCPD.
Machine File Overview
The DHCP server provides machine information to clients based on statements
contained in the server’s machine file and based on information provided by the
client. The server’s machine file defines the policy for allocating IP addresses and
other configuration parameters. The file is a ″map″ that the server uses to
determine what information should be provided to the requesting client.
Before you start the DHCP server, you must have created the machine file. Once
the DHCP server program is running, you can also make dynamic changes to the
configuration by modifying the machine file and using the RELOAD subcommand to
68
z/VM: TCP/IP Planning and Customization
DHCP Server
update the machine information. For more information on the RELOAD
subcommand, see “RELOAD Subcommand” on page 121.
You create a hierarchy of machine parameters for a DHCP-supported network by
specifying some configuration values that are served globally to all clients, while
other configuration values are served only to certain clients. Serving different
configuration information to clients is often based on network location, equipment
vendor, or user characteristics.
Depending on your configuration, you can specify subnets, classes, vendors, and
clients to provide configuration information to different groups of clients:
v When defined globally, client, vendor or class options are available to DHCP
clients regardless of their network location.
Parameters specified for a subnet, class, or client are considered local to the
subnet, class, or client. A client defined within a subnet inherits both the global
options and the options defined for that subnet. If a parameter is specified in
more than one level in the network hierarchy, the lowest level (which is the most
specific) is used.
v Use the Subnet statement to specify configuration parameters for one subnet for
a specific location in your network or enterprise. The task of configuring subnets
also requires you to set lease time and other options for clients using the subnet.
v Use the Class statement to configure DHCP classes to provide unique
configuration information from the server to clients that identify themselves as
belonging to that class. For example, a group of clients that all use a shared
printer could comprise a Class.
v Use a Vendor statement to provide unique configuration information to clients
that identify themselves as using a specific vendor’s equipment or software.
Specially-defined options may be served to these clients.
v Use a Client statement in the DHCP server configuration file to serve specified
options to a specific client or to exclude that client from service. You can also use
a Client statement to exclude IP addresses from service.
The concept of scoped statements in DHCP machine file is shown by the following:
option A 1
option B 2
option C 3
client k
{
}
subnet y
{
client m
{
option E 11
option H 12
}
class Q
{
option G
option F 9
}
}
option C 6
option E 5
Chapter 7. Configuring the DHCP Server
69
DHCP Server
subnet z
{
option F 7
}
class x
{
option E 1
}
In this example:
v Options A, B, and C are global and are inherited by all clients in the network
unless overridden by a value for the same option at a lower level in the network.
Client K is a specific client specified at the global level.
v Clients that are specifically defined under a subnet, such as client M, must be
located in that subnet in order to be served. Client M must indicate it is in subnet
Y in order to be served.
v Clients that are not specifically defined will automatically fall into a specific
location in the hierarchy based on their current network location.
v Option G is served only to clients that belong to class Q in subnet Y.
v Option E, with a value of 11, and option H, with a value of 12, are served only to
client M in subnet Y.
v Option C is defined in two places. For all clients in subnet Y, the value of option
C is 6. For all other clients, the value of option C is 3.
v Option F is also defined in two places. For all clients of class Q in subnet Y, the
value of option F is 9. For all clients in subnet Z, the value of option F is 7. For
other clients, option F is not defined.
v Class X options are served to any client that requests class X. Class Q options
are served only to clients in subnet Y that request class Q.
v Option E is defined in three places. For clients not in subnet Y that request to be
in class X, the value of option E is defined as the value 1. For the remaining
clients in subnet Y except client M, the value of option E is 5 because a Subnet
statement is considered more specific than a global Class statement. For client
M, the value of option E is 11, because a CLIENT statement is considered more
specific than a Subnet statement.
v For clients in subnet Z that do not request class X, option E is undefined.
Statement Precedence Order
As the server searches the machine file for statements related to the client request,
it constructs an order of precedence that is used to determine which parameter to
select when a parameter is specified at more than one level.
v Statements which are most specific have the highest precedence.
v Statements specified outside braces are considered global and are used for all
addresses served by this server—unless the statement is overridden at a
lower-scoped level.
v Parameters specified within braces under a statement, such as a Subnet
statement, are considered local and apply only to clients within the hierarchical
level defined by that statement.
v Parameters scoped at a client level take precedence over all other parameters at
that level (global or subnet).
v Parameters in a subnet take precedence over parameters in a class unless the
class is scoped within the subnet.
70
z/VM: TCP/IP Planning and Customization
DHCP Server
v Parameters scoped at a class level take precedence over global parameters.
– If a client is specified at both a global level and a subnet level, then the
subnet level client parameters take precedence over the global level client
parameters.
– If a class is specified at both a global level and a subnet level, then the
subnet level class parameters take precedence over the global level class
parameters.
v Vendor statements always have a global scope.
For example, if option 1 is specified as both a class option at the global level and
as a subnet level option, then the class level option is used because it is more
specific to the client’s environment.
Step 4: Construct a DHCPD Machine File
The machine file defines the information that will be returned to clients as
configuration parameters and determines how addresses are to be assigned. It is
important for you to layout the information in the simplest manner possible. This
section will walk you through the construction of a machine file in a step by step
manner. For the sake of a robust example, we will override most of the statement
defaults in order to discuss them and construct a large sample machine file. In your
case, you will probably be able to rely on the defaults.
Global Information
Certain information is global to all clients that are being serviced or relates to the
overall operation of the server. This information should be determined first and
placed at the global level.
Ping Time
Before assigning an IP address to a client for the first time, DHCPD will issue an
ICMP Echo Request to that address (in other words, PING it). The amount of time it
will wait for a response before assigning that address is determined by the
PingTime statement. If the DHCPD server receives a response from a machine
actively using the address, then it knows that there is a problem and it cannot
reissue the address. The default is one second. If more time is needed within your
environment for a ping response to reach your DHCPD server, then add the
PingTime statement.
One way to determine whether your installation will need more time is to use the
TCP/IP PING command to sample the ping response times for the addresses that
will be supported. By choosing addresses of active machines already on the target
subnets you can determine how long it takes them to respond and thereby
determine an appropriate time interval.
For our example, the default time of 1 second is too small so a new PingTime of 2
seconds is set.
PingTime 2 SEC
Reserved Address Time
If the client requests boot parameters using DHCP protocol, then it expects that it
could receive multiple offers of addresses if there is more than one DHCP server
listening. Generally, the client will wait a specified period of time to receive all
DHCP offers, then select one. Because there is the possibility that another server
might be selected and our DHCPD server might not see the accept packet
(because of an error somewhere), DCHP needs to know how long to reserve an IP
Chapter 7. Configuring the DHCP Server
71
DHCP Server
address before putting it back into the address pool for reuse. The ReservedTime
statement lets you change the time the server will wait before giving up on an offer
and reusing the address. In our case, assume that our clients have been set to
respond to an offer in one minute instead of the default of five minutes.
ReservedTime 1 minute
Setting the Lease Duration
DHCPD can reserve addresses either indefinitely or for a particular lease time.
Indefinite leases are used primarily for BootP clients, because these clients do not
support the concept of leasing an address for a specified period of time. Specific
lease intervals are used for most DHCP clients. The clients are provided an address
for a specified period of time, and may extend the lease during their lease time.
For our example, the default lease period of 24 hours is too long. We have a limited
number of addresses that must be reused as one shift of users leaves for the day,
and another takes over, using different hardware. Therefore, we want a lease time
default of 9 hours. The LeaseTimeDefault statement allows us to set that lease
interval.
LeaseTimeDefault 9 hours
Setting Wait Time Before Reusing an Expired Lease
When a lease on an address expires, it is best to let the server wait a period of
time before returning the address to the address pool, because it is possible that
the client might have been delayed in requesting to extend the lease. The
UsedIPAddressExpireInterval statement lets you tailor how long the server will wait
before returning an address to the address pool for reuse. For our example, the
default of 30 seconds is too short; double it to one minute.
UsedIPAddressExpireInterval 1 minute
Setting How Often to Check Addresses
DHCPD does not maintain individual timers for each IP address that it has
allocated. Instead, it periodically checks the status of all addresses that are being
leased. This checking covers IP addresses with active leases, reserved leases and
IP addresses whose leases have expired and are waiting to return to the address
pool. The default interval for checking lease statuses is one minute. For our
example, assume that we do not want the inherent overhead of checking leases
every minute and instead use 15 minutes as the interval. Since we only check the
leases every 15 minutes, it is possible for a lease to expire at 1 minute into the
interval and we will not handle it until the check that is done 14 minutes later. With
our example server, this is not a problem; we are going to accept a delay in
handling leases and obtain a benefit of less virtual processor usage. The
LeaseExpireInterval statement lets us set this interval.
LeaseExpireInterval 15 seconds
Supporting BootP Requests
By default, DHCPD supports BootP requests. You may at some time choose that
only DHCP requests are supported, so all addresses are served as leased
addresses instead of allowing BootP clients to obtain indefinite leases on
addresses. The SupportBootP statement lets you control whether BootP requests
are supported. In order to aid in maintenance of our machine file, we will add the
statement so that anyone looking at the file at a later time will easily know that
BootP requests are supported by the server.
SupportBootP yes
72
z/VM: TCP/IP Planning and Customization
DHCP Server
Supporting Requests from Unlisted Clients
By default, DHCPD will support any client which submits a request. You may wish
to require that the client be specified in the machine file in order to be served an
address. In our example, we will specify the SupportUnlistedClients statement with
the "no" operand.
SupportUnlistedClients no
Specifying the Next Server to Use in the Boot Process
The clients that receive the response from the DHCP server need to know the IP
address of the next server to contact in the boot process. Normally, this is the
address of a TFTP server that would deliver the boot image to the client.
Use the BootStrapServer statement to specify the IP address of the next server.
This statement may be specified at the global, class, subnet or client levels. For our
example, all clients are served by the same server, so specify the information at the
global level.
BootStrapServer 9.100.40.75
Defining New Configuration Options
Over time, it is possible that new configuration options will be defined, and others
considered. To simplify adding support for a client that requires a new option, a
statement to define options is supported. In our example, one of our clients needs
option 181 which is a list of IP addresses for machines that receive datagrams from
the client machine. Since the server does not recognize option 181, we could code
the option as a hexadecimal value,
option 181 hex 0964320109643202
Or, we could use the DefineOptions statement to define the required option, then
use this newly defined option later within the machine file.
DefineOptions
{
option 181 ipalist
}
The DefineOptions statement must precede the first Option statement. The Option
definition statements are surrounded by a line which contains a left brace ({) and a
line containing a right brace (}). The braces indicate that the lines which they
surround are part of the DefineOptions level.
Global Options
There will be some options that you wish to serve to all clients supported by your
DHCPD server, regardless of the subnet on which they reside. These options are
defined at the global level of the machine file.
In our case, all of our clients receive the address of the RFC 868 Time Server and
the time offset for our area. The Option statement lets you specify the option value.
#################################################################
# Time Server data:
#
#
option 2 -> offset of the time server from UTC in seconds
#
#
option 4 -> IP address of an RFC 868 time server
#
#################################################################
option 2
-18000
option 4
9.100.40.75
All of the subnets that this server supports use the same Name Server, Domain
Name and Domain Name Server, so we want to specify this information at the
global level.
Chapter 7. Configuring the DHCP Server
73
DHCP Server
#################################################################
# Options related to all subnets served by this server.
#
#
option 5 -> Name Server IP addresses
#
#
option 6 -> Domain Name Server IP addresses
#
#
option 15 -> Domain Name
#
#################################################################
option 5
9.100.25.252
option 6
9.100.25.252
option 15 endicott.ibm.com
Specifying Option 43 Vendor Data
Some clients receive additional option data that is not architected by the DHCP
RFCs. Only the manner in constructing the data is architected. This data is
transmitted to the client using option 43. The data for the option is in the form of a
one byte option number from 1 to 254, followed by a one byte field indicating the
length of the data, followed by the data itself.
DHCPD provides the appropriate option 43 data to clients on a vendor-specific
basis. This is done by matching option 60 (Vendor Class Identifier) data provided by
the client with a vendor string, specified as part of a Vendor statement in the
machine file. In our example, we have one type of client which uses vendor data;
that client specifies option 60 with the string "IBMSPG 1.0.0".
#################################################################
# Vendor "IBMSPG 1.0.0" returns option 43.
#
#################################################################
Vendor "IBMSPG 1.0.0"
{
option 1 "DEBUG ON"
option 2 hex 05
}
For our example client, we have defined two options to be returned as option 43
data. We specified option 1 as data to be translated to ASCII; option 2 as a
hexadecimal value. Note that the normal rules for handling option values do not
apply at the vendor level; the data is assumed to be either ASCII or hexadecimal.
The left brace ({) and right brace (}) statements signify these options belong to the
preceding Vendor statement (at the vendor level). We chose to code the data to be
returned using two Option statements, to make this information more readily
apparent. We also could have defined this data through the use of a single "option
43" statement. If this was done, we would have used the "hex" operand, and
specified both options — and their associated values — as a single hexadecimal
value.
Specifying Global Class Data
Some clients specify option 77 on their request. This option specifies an ASCII
string which is the name of the client class; DHCPD compares this string to the
values specified on Class statements. These statements indicate a level under
which additional options may be specified to be returned to the client. In our
example, we recognize a single class, ″IBM Network Station″™. This class needs
additional information to enable it to configure.
#################################################################
# IBM Network Station manager data:
#
#
option 67 -> Name of the boot file for the client to request#
#################################################################
class "IBM Network Station"
{
option 67 /QIBM/ProdData/NetworkStation/kernel
}
74
z/VM: TCP/IP Planning and Customization
DHCP Server
Specifying Global Client Data
You may need to specify options that are unique to a particular client, and do not
depend on the subnet to which that client is attached. The Client statement lets you
identify such clients and options that apply to them.
The Client statement that follows identifies a client machine that may be served
when it is attached to any subnet supported by this server. The first two operands
of the Client statement identify the client hardware type and MAC address; the third
operand indicates that this client may be served any available address. The left ({)
and right (}) braces then create a client level specific to this client; any option data
that follows the left brace will be served to only the previously identified client. In
our example, Option 12 is used to assign the host name of BIGSHOT to the client.
#################################################################
# Globally defined Clients
#
#################################################################
client 6 0000E5E8DC61 any
{
option 12 BIGSHOT
}
Our next Client statement identifies a client machine that may be served only when
it is attached to the subnet which supports address 9.100.58.240. The first two
operands on the Client statement identify the client by specifying a hardware type of
0, and through an ASCII value (STEVE’S MACHINE), a client identifier; this value
will be provided by the client (through the use of option 61) when it issues a boot
request. The third operand indicates this client may be served only address
9.100.48.240; if this address is not already allocated, it will be reserved for this
specific client. As before, the left ({) and right braces (}) are used to define client
level information that is unique to the preceding client. In this case, Option 12
assigns the host name of STEVIEG to the client. Option 181 was previously defined
by the DefineOptions statement and is used here.
client 0 "STEVE’S MACHINE" 9.100.58.240
{
option 12 STEVIEG
option 181 9.100.57.110
}
Usually, it is better to specify clients using only their hardware type and machine
address, because this allows for improved performance when client information is
located. Also, restricting a client to a specific hardware address removes flexibility in
assigning addresses by DCHPD, and requires the DHCPD administrator to update
the machine file when the machine moves to a different subnet.
Specifying the IP address to assign to a client removes some of the flexibility
provided by the DHCPD server. The specified address can be used only by the
client; no other client may use the address. It is recommended that you let the
DHCPD server choose the address from its pool of available addresses, because
this allows the possibility of address sharing. For example, one user might use an
address and free it up in time for the address to be given to another user.
Subnet Related Data
Once you have determined and specified global information for the server, you now
have to layout the information unique to the various subnets that the server is
supporting. The Subnet statements, which we will discuss shortly, identify the
subnets and the pools of addresses that they will serve. Again, left ({) and right (})
braces will be used to group Option, and other statements, with specific Subnet
statements.
Chapter 7. Configuring the DHCP Server
75
DHCP Server
Our example DHCPD server will service the following environment: two floors of a
building where four subnets are defined. Two of these subnets are directly attached
to the machine running the VM system; activity for the other two subnets will be
forwarded by BOOTPD relay agents. This example is based on an actual test
environment, where only the IP addresses changed.
Table 10. DHCPD Machine File - Example Subnet Environment
Subnet Address
9.100.57.0
9.100.58.0
9.100.48.0
9.100.176.0
Subnet Information
Subnet Mask:
255.255.255.0
Routers:
9.100.57.253
DHCP Controlled Addresses:
9.100.57.43-9.100.57.99,
excluding 9.100.57.50,
9.100.57.60 and 9.100.57.85.
Additional Requirements:
None
Subnet Mask:
255.255.255.0
Routers:
9.100.58.253
DHCP Controlled Addresses:
9.100.58.103
Additional Requirements:
A specific machine of hardware
type 6, MAC address
0000E5E78650 is never
allowed to be attached to this
subnet.
Subnet Mask:
255.255.255.0
Routers:
9.100.48.253
DHCP Controlled Addresses:
9.100.48.200-9.100.48.245
Additional Requirements:
Machines of a specific class,
″IBM Network Station″, must
be allocated IP addresses
between 9.100.48.200 and
9.100.48.230.
Subnet Mask:
255.255.255.0
Routers:
9.100.176.1
DHCP Controlled Addresses:
9.100.176.20-9.100.176.35
9.100.176.100-9.100.176.105
Additional Requirements:
None
For subnet 9.100.57.0, a large range of addresses have been set aside for the
DHCP server to administer. Within that range of addresses there are three
addresses that are still in use by non-DHCP/BootP protocol machines. We could
code 4 sets of subnet statements for
v
v
v
v
9.100.57.43-9.100.57.49
9.100.57.51-9.100.57.59
9.100.57.61-9.100.57.84
9.100.57.86-9.100.57.99.
Instead it will be more straightforward to code a single subnet statement and
exclude the addresses which DHCP should not handle. The subnet statement
76
z/VM: TCP/IP Planning and Customization
DHCP Server
identifies the subnet address, the subnet mask, and the range of addresses that
DHCP allocates for that subnet statement. Either within the subnet level or at the
global level, Client statements may be specified to further restrict the range. The
hardware type of zero and identifier of zero indicate that the Client statement is
excluding an address.
#################################################################
# Subnet 9.100.57.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.57.0 255.255.255.0 9.100.57.43-9.100.57.99
{
client 0 0 9.100.57.50
client 0 0 9.100.57.60
client 0 0 9.100.57.85
Along with specifying the addresses to allocate and the subnet mask to return to
the requesting clients, we need to indicate the address of a router that is used by
this subnet. We will also specify a closing right brace (}) to indicate the completion
of the subnet level.
option 3 9.100.57.253
}
For subnet 9.100.58.0, only one address is available for allocation by DHCP. Also, a
specific client machine may never be allowed to attach to this subnet.
#################################################################
# Subnet 9.100.58.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.58.0 255.255.255.0 9.100.58.103-9.100.58.103
{
option 3 9.100.58.253
client 6 0000E5E78650 none
}
For subnet 9.100.48.0, 46 IP addresses are available for allocation by the server,
but 31 are reserved for a specific class of machine (IBM Network Station). In this
case, we only need to specify a Class statement with an IP address range, because
for these machines, we previously specified a similar Class statement at the global
level; that statement provides related options for all machines of this class.
#################################################################
# Subnet 9.100.48.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.48.0 255.255.255.0 9.100.48.200-9.100.48.245
{
option 3 9.100.48.253
class "IBM Network Station" 9.100.48.200-9.100.48.230
}
For subnet 9.100.176.0, 22 addresses are available in two address ranges.
Because the available address ranges are grouped at different ends of the total
subnet address range, we will create two groups of subnet statements, instead of a
Chapter 7. Configuring the DHCP Server
77
DHCP Server
single range with many Client statements to exclude unwanted addresses. We will
also code, at the global level, a BALANCE: statement so that DHCPD will attempt
to alternately use the two subnet statements to satisfy requests. The Balance:
statement contains a label that is specified on both subnet statements, in our case
"sub176". Without the balance statement, all addresses would be chosen from the
first range of addresses before the second range was used.
Balance: sub176
#################################################################
# Subnet 9.100.176.0, addresses 20-35
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.176.0 255.255.255.0 9.100.176.20-9.100.176.35 label:sub176
{
option 3 9.100.176.1
}
#################################################################
# Subnet 9.100.176.0, addresses 200-230
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.176.0 255.255.255.0 9.100.176.200-9.100.176.230 label:sub176
{
option 3 9.100.176.1
}
This completes the machine file. The following example shows the completed file
with the Balance: statement moved to the beginning of the file.
Balance: sub176
PingTime 2 SEC
ReservedTime 1 minute
LeaseTimeDefault 9 hours
UsedIPAddressExpireInterval 1 minute
LeaseExpireInterval 15 seconds
SupportBootP yes
SupportUnlistedClients no
BootStrapServer 9.100.40.75
DefineOptions
{
option 181 ipalist
}
#################################################################
# Time Server data:
#
#
option 2 -> offset of the time server from UTC in seconds
#
#
option 4 -> IP address of an RFC 868 time server
#
#################################################################
option 2
-18000
option 4
9.100.40.75
#################################################################
# Options related to all subnets served by this server.
#
#
option 5 -> Name Server IP addresses
#
#
option 6 -> Domain Name Server IP addresses
#
#
option 15 -> Domain Name
#
#################################################################
option 5
9.100.25.252
option 6
9.100.25.252
78
z/VM: TCP/IP Planning and Customization
DHCP Server
option 15
endicott.ibm.com
#################################################################
# Vendor "IBMSPG 1.0.0" returns option 43.
#
#################################################################
Vendor "IBMSPG 1.0.0"
{
option 1 "DEBUG ON"
option 2 hex 05
}
#################################################################
# IBM Network Station manager data:
#
#
option 67 -> Name of the boot file for the client to request#
#################################################################
class "IBM Network Station"
{
option 67 /QIBM/ProdData/NetworkStation/kernel
}
#################################################################
# Globally defined Clients
#
#################################################################
client 6 0000E5E8DC61 any
{
option 12 BIGSHOT
}
client 0 "STEVE’S MACHINE" 9.100.58.240
{
option 12 STEVIEG
option 181 9.100.57.110
}
#################################################################
# Subnet 9.100.57.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.57.0 255.255.255.0 9.100.57.43-9.100.57.99
{
client 0 0 9.100.57.50
client 0 0 9.100.57.60
client 0 0 9.100.57.85
option 3 9.100.57.253
}
#################################################################
# Subnet 9.100.58.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.58.0 255.255.255.0 9.100.58.103-9.100.58.103
{
option 3 9.100.58.253
client 6 0000E5E78650 none
}
#################################################################
# Subnet 9.100.48.0
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
Chapter 7. Configuring the DHCP Server
79
DHCP Server
#
as an option.)
#
#################################################################
Subnet 9.100.48.0 255.255.255.0 9.100.48.200-9.100.48.245
{
option 3 9.100.48.253
class "IBM Network Station" 9.100.48.200-9.100.48.230
}
#################################################################
# Subnet 9.100.176.0, addresses 20-35
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.176.0 255.255.255.0 9.100.176.20-9.100.176.35 label:sub176
{
option 3 9.100.176.1
}
#################################################################
# Subnet 9.100.176.0, addresses 200-230
#
#
option 3 -> Router IP addresses
#
#
option 1 -> subnet mask (This option is generated by the
#
#
SUBNET statement. It should not be specified
#
#
as an option.)
#
#################################################################
Subnet 9.100.176.0 255.255.255.0 9.100.176.200-9.100.176.230 label:sub176
{
option 3 9.100.176.1
}
DHCPD Machine Statements
The DHCP server provides machine information to clients based on statements
contained in the server’s machine file and based on information provided by the
client. The server’s machine file defines the policy for allocating IP addresses and
other configuration parameters. The file is a ″map″ that the server uses to
determine what information should be provided to the requesting client.
Machine File Format
In the DHCP machine file:
v Comments must begin with a pound sign (#), semi-colon (;) or asterisk (*) in
column 1.
v Text strings that include spaces must be surrounded by single (') or double
quotes (").
v Parameters to the right of a left parenthesis are ignored. They are supported for
compatibility with other IBM DHCP servers.
v A continuation character (\) at the end of a line indicates the information is
continued on the next line.
v Braces are used to specify statements that are scoped within other statements.
v
v
v
v
80
Class statements may appear at the global level or scoped within a subnet.
Client statements may appear at the global level or scoped within a subnet.
Subnet statements may appear only at the global level.
Keywords are not case sensitive. Capitalization patterns used in this
documentation are not required in the configuration file.
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 11. DHCPD Machine File Statements
Statement
Minimum
Abbreviation
{
{
Indicates the start of a level. Statements which
follow the left brace are related to the previous
statement.
82
}
}
Indicates the end of a level.
82
Balance:
BALANCE:
Specifies subnet groups from which addresses
should be assigned in an alternating manner.
82
BootStrapServer
BSS
Specifies the IP address of the next server to
contact in the boot strap process. Normally, this
will be the address of the TFTP server which
delivers the boot image.
83
Class
CLASS
Identifies a user defined class (specified by the
client using option 77) and a range of addresses to
assign to the class.
83
Client
CLIENT
Identifies a client by an ID, which may be followed
by additional options. Can also be used to identify
an IP address that should not be used within a
range of addresses.
84
DefineOptions
DEFOPTS
Defines (or redefines) the values allowed on
Option statements.
86
InOrder:
INORDER:
Specifies which subnet groups should be
processed in the order of priority.
86
LeaseExpireInterval
LEI
Specifies the interval at which the lease condition
of all addresses in the address pool is examined.
87
LeaseTimeDefault
LTD
Specifies the default lease duration for the leases
issued by this server.
88
Option
OPTION
Defines options to be passed to the client. Also,
within the DefineOptions level, you can define (or
redefine) how the option values are handled.
88
PingTime
PT
Specifies a time interval that the server will wait for
a response to a ping (ICMP Echo Request).
91
ReservedTime
RT
Specifies the maximum amount of time the server
holds an offered address in reserve while waiting
for a response from the client.
91
Subnet
SUBNET
Specifies configuration parameters for an address
pool administered by a server. An address pool is
a range of IP addresses to be leased to clients.
92
SupportBootP
SB
Specifies whether DHCPD responds to requests
from BootP clients.
94
SupportUnlistedClients
SUC
Controls whether DHCPD will respond to clients
that are not listed (by client ID) in the machine file.
94
UsedIPAddressExpireInterval
UIPEI
Specifies the amount of time that an IP address,
whose lease has expired, will be held before being
returned to the available address pool for possible
reassignment to another client.
95
Vendor
VENDOR
Specifies an option 43 value to be returned to
clients that specify an option 60 value that
matches the vendor name.
96
Description
Page
Chapter 7. Configuring the DHCP Server
81
DHCP Server
{ (left brace) Statement
Use the left brace statement to indicate the start of a level. Statements which follow
the left brace are related to the previous Vendor, Subnet, Class, Client, or
DefineOptions statement.
{
Usage Notes
v The left brace must be the first non-comment statement in the file or the first
non-comment statement to follow a Vendor, Subnet, Class, Client or
DefineOptions statement.
} (right brace) Statement
Use the right brace statement to indicate the end of a level.
}
Balance: Statement
Use the Balance: statement to specify subnet groups from which addresses should
be assigned in an alternating manner.
BALANCE: labelname
Operands
labelname
is a label (a string of 1 to 64 alphanumeric characters) that identifies the subnet
group.
Usage Notes
v The Balance: statement should be specified at the global level only.
v When the Balance: statement is used, DHCP provides the first IP address from
the subnet that is first in the priority list, and subsequent IP addresses from each
lesser-priority subnet, repeating the cycle until addresses are exhausted equally
from all subnets.
The following is an example of Balance: processing of a subnet group. IP
addresses are exhausted equally in WIRE1/3 and WIRE1/5: The priority values
of "3" and "5" need not be consecutive. There is no other subnet statement for
WIRE1 with a priority of 1, 2 or 4.
balance: WIRE1
subnet 9.67.49.0 255.255.255.0 9.67.49.1:9.67.49.100 label:WIRE1/3
subnet 9.67.48.0 255.255.255.0 9.67.48.1:9.67.48.50 label:WIRE1/5
82
z/VM: TCP/IP Planning and Customization
DHCP Server
v If a label for a subnet group is specified on Subnet statements but not on a
Balance: or InOrder: statement, then the label on the subnet has no effect.
Clients are allocated addresses for the subnet on which they broadcast the
request.
For more information on the format of the Subnet statement, see “SUBNET
Statement” on page 92.
BootStrapServer Statement
Use the BootStrapServer statement to specify the IP address of the next server to
contact in the boot strap process. Normally, this is the address of the TFTP server
from which the client will obtain the boot image after it completes the BootP/DHCP
process of acquiring an IP address and basic configuration.
BOOTSTRAPSERVER
BSS
ipaddr
Operands
ipaddr
is an IP address, specified in dotted-decimal notation, which specifies the
address of the next server to contact after completion of the BootP/DHCP
protocol step.
Usage Notes
v The BootStrapServer statement may be specified at the global, subnet, class,
and client levels only.
v The Boot Strap Server address is returned to the client in the "siaddr" field of
BootP and DHCP replies. If the BootStrapServer is not specified in the machine
table for the selected response, then the primary host IP address for the host
running the DHCPD server is used.
CLASS Statement
Use the Class statement to identify a user-defined group of clients.
CLASS class_name
range
Operands
class_name
is the user-defined label that identifies the class. The client specifies the class
name using option 77. The class name is an ASCII string of up to 255
characters (for example, "accounting"). If the class name contains spaces, it
must be surrounded by single (') or double (") quotes.
range
is a range of addresses. Enter addresses in dotted-decimal notation, beginning
Chapter 7. Configuring the DHCP Server
83
DHCP Server
with the lower end of the range, followed by a hyphen, then the upper end of
the range, with no spaces between. For example, 9.17.32.1-9.17.32.128.
At a global level, a class cannot have a range. A range is only allowed when a
class is defined within a subnet. By default, is no range is associated with the
class. The range must be a subset of the subnet range.
Usage Notes
v The Class statement should be specified at the global level or subnet level.
v When a Class statement is specified at a Subnet level, the CLASS (and related
options) will be used only if:
– The client specified the class with option 77
– The client is on the subnet to which the class belongs
– When an IP address range is specified on the Class statement, then an IP
address must be available in the range in order for the Class statement to be
used.
If an IP address has already been indicated on a matching Client statement, that
address must be used and must be within the range of addresses listed on the
Class statement.
v IP addresses specified on the range operand are removed from the general pool
of addresses used for the subnet. They will be allocated only to clients that
belong to the class. This range can be further restricted by Client statements
which specify addresses within the CLASS range.
v A client that requests an IP address from a class which has exhausted its range
is offered an IP address from the subnet range, if available. The client is not
offered the options associated with the exhausted class.
v To assign configuration parameters such as a lease time for all clients in a class,
follow the Class statement with Option statements surrounded by braces.
CLIENT Statement
Use the Client statement to identify a client by an ID, or identify an IP address that
should be excluded from a range of available addresses.
CLIENT hw_type clientID
ipaddr
ANY
NONE
Operands
hw_type
is the hardware type of the client computer, or 0. The valid client types are
defined in STD 2, RFC 1700.
hw_type
1
2
3
4
5
6
84
z/VM: TCP/IP Planning and Customization
Client hardware
ethernet ether
ethernet3 ether3
ax.25
pronet
chaos
token-ring tr
DHCP Server
7
8
9
10
11
12
13
14
15
16
17
18
arcnet
hyperchannel
lanstar
autonet
localtalk
localnet
ultra_link
smds
frame_relay
atm
ieee802
fddi
clientID
is the hexadecimal MAC address or a name which identifies the client. If a
name is specified then:
v hwtype must be 0
v If the name contains blanks, then it must be enclosed in single or double
quotes.
ipaddr
is an IP address, specified in dotted-decimal notation.
ANY
indicates that the server may choose an address from its pool of available
addresses.
NONE
indicates that no response is to be returned to client BootP/DHCP requests.
Usage Notes
v The Client statement may be specified at the global level or subnet level only.
v If the Option statement identifies a client (instead of excluding an address), then
it may be followed by left brace ({) and right brace (}) statements, which identify
additional statements associated with the Client statement. Option statements are
specified within these enclosing braces to associate options with the client. For
example:
client 6 0000E5E8DC60 any
{
option 12 ADAM
}
v If the Client statement is being used to restrict an IP address from the list of
available addresses, both the hwtype and clientid should be 0. For example:
client 0 0 9.100.25.110
While the Client statement can be used to exclude an IP address, a better
solution for excluding many IP addresses is to specify a subnet with a range of
IP addresses that are never served to clients. For example, the following Subnet
statement does not include the first nine addresses on the subnet. These nine
addresses are not to be used.
subnet 9.100.25.0 255.255.255.0 9.100.25.10-9.100.25.254
v The Client statement may be specified at the global level to exclude the client
from service by the server, or at a subnet level to exclude a client from service
on a particular subnet (address pool). For example:
client 6 10005aa4b9ab none
Chapter 7. Configuring the DHCP Server
85
DHCP Server
v An IP address restricted to a specific client by the ipaddr operand is removed
from the general pool of addresses used for a subnet. It will be allocated only to
the specified client.
DefineOptions Statement
Use the DefineOptions statement to identify a group of options whose processing is
being redefined. This allows you to define how the value specified for an option is
handled.
DEFINEOPTIONS
DEFOPTS
Usage Notes
v The DefineOptions statement should be specified at the global level only and
must precede all Option statements.
v It may be easier to use the DefineOptions statement to define an unrecognized
option than coding the value in ASCII or hexadecimal. For example, if a new
option (for example 190) is used by the client to contain a series of 32 bit signed
time offsets: 18000, 12000, and 3000, you could code it in hex as follows:
190 hex 0000465000002ee000000bb8
or you could define the options and specify the 190 option values as decimal
numbers.
DefineOptions
{
option 190 lsint(4,*,*)
}
option 190
18000 12000 3000
InOrder: Statement
Use the InOrder: statement to specify subnet groups from which addresses should
be assigned based on subnet priorities.
INORDER: labelname
Operands
labelname
is the labelname associated with a subnet group.
Usage Notes
v The InOrder: statement should be specified at the global level only.
v When the InOrder: statement is used, the subnets that belong to a listed group
are processed in the order established by the priority assigned to each subnet.
The subnet address pool with the highest priority within a group is completely
86
z/VM: TCP/IP Planning and Customization
DHCP Server
exhausted before the subnet address pool with the next highest priority is used.
For more information on the Subnet statement, see “SUBNET Statement” on
page 92.
The following is an example of InOrder: processing of subnet group WIRE3.
Requests for subnet group WIRE3 exhaust addresses in subnet 9.67.50.0
(WIRE3/1) first, followed by subnet 9.67.51.0 (WIRE3/2), and then 9.67.50.0
(WIRE3/3), which has the same subnet address as WIRE3/1, but specifies a
higher address range:
inOrder: WIRE3
subnet 9.67.51.0 255.255.255.0 9.67.51.1-9.67.51.50 label:WIRE3/2
subnet 9.67.50.0 255.255.255.0 9.67.50.1-9.67.50.50 label:WIRE3/1
subnet 9.67.50.0 255.255.255.0 9.67.50.51-9.67.50.100 label:WIRE3/3
v If a label for a subnet group is specified on Subnet statements but not on a
Balance: or InOrder: statement, then the label on the subnet has no effect.
Clients are allocated addresses for the subnet on which they broadcast the
request.
LeaseExpireInterval Statement
Use the LeaseExpireInterval statement to specify the interval at which the lease
condition of all addresses in the address pool is examined.
LEASEEXPIREINTERVAL
LEI
time
MINutes
SEConds
MINutes
HOUrs
Operands
time
is the amount of time to wait between checking all addresses for expired
leases.
The value must be a positive whole number (Base 10) or "-1" (which means
infinity). If this statement is not specified, the LeaseExpireInterval defaults to 1
minute. The minimum time value must be equal to at least 15 seconds. The
maximum time value must be no more than 12 hours.
SEConds
indicates the time value is in units of seconds.
MINutes
indicates the time value is in units of minutes.
HOURs
indicates the time value is in units of hours.
Usage Notes
v The LeaseExpireInterval statement should be specified at the global level only
and therefore, is used for all addresses supported by this server.
v The value specified should be less than the value for LeaseTimeDefault to
ensure that expired leases are returned to the pool in a timely manner.
Chapter 7. Configuring the DHCP Server
87
DHCP Server
LeaseTimeDefault Statement
Use the LeaseTimeDefault statement to specify the default lease duration for the
leases issued by this server.
LEASETIMEDEFAULT
LTD
time
MINutes
SEConds
MINutes
HOURs
DAYs
MONths
YEArs
Operands
time
is the default lease duration.
The value must be a positive whole number (Base 10) or "-1" (which means
infinity). If this statement is not specified, the LeaseTimeDefault defaults to 24
hours. The minimum time value must be equal to at least 180 seconds.
SEConds
indicates the time value is in units of seconds.
MINutes
indicates the time value is in units of minutes.
HOUrs
indicates the time value is in units of hours.
DAYs
indicates the time value is in units of days.
MONths
indicates the time value is in units of months.
YEArs
indicates the time value is in units of years.
Usage Notes
v The LeaseTimeDefault statement should be specified at the global level only and
therefore, is used for all addresses supported by this server.
v The LeaseTimeDefault may be overridden within the machine file using option
51.
OPTION Statement
Use the Option statement to define options to be passed to the client. Also, within
the DefineOptions level, you can define (or redefine) option values.
Note: See “DHCP Options” on page 97 for a list of defined option names and
option numbers.
88
z/VM: TCP/IP Planning and Customization
DHCP Server
OPTION option_number option_value
Operands
option_number
is a number from 1 through 254.
option_value
is an option value appropriate for the specified option. When an Option
statement is present with a DefineOptions level, the value indicates how the
option should be handled when used later in the machine file. In a
DefineOptions level, the option values can be:
ASCII
indicates that the option value will be an ASCII string. A provided value can
be either a single, blank delimited word, or a string (which may contain
blanks), that begins with a single or double quote and ends with the same
quote. The character string is translated from EBCDIC to ASCII before its
use.
The data may also be specified as a hexadecimal string which is not
translated. See the HEX value description that follows for information about
how to specify values as hexadecimal strings.
IPADDR
indicates that the allowed option value is an address specified in
dotted-decimal notation (e.g. 9.100.25.100)
IPALIST
indicates that the allowed option value is a list of IP addresses in
dotted-decimal notation, separated by blanks.
HEX
indicates that the allowed option value is a single blank delimited word that
is comprised of EBCDIC character pairs (0-1 and A-F) which represent a
hexadecimal byte of data.
UINT(blen,min,max)
indicates that the allowed option value is an unsigned whole number.
v blen is the length, in octets, of the converted value that will be sent to the
client.
v min is the minimum value allowed for the number. An "*" indicates that
the number is the smallest number that can fit in the space allowed for
the converted value.
v max is the maximum value allowed for the number. An "*" indicates that
the number is the largest number that can fit in the space allowed for the
converted value.
SINT(blen,min,max)
indicates that the allowed option value is signed whole number.
v blen is the length, in octets, of the converted value that will be sent to the
client.
Chapter 7. Configuring the DHCP Server
89
DHCP Server
v min is the minimum value allowed for the number. An "*" indicates that
the number is the smallest number that can fit in the space allowed for
the converted value.
v max is the maximum value allowed for the number. An "*" indicates that
the number is the largest number that can fit in the space allowed for the
converted value.
LSINT(blen,min,max)
indicates that the allowed option value is a list of signed whole numbers,
separated by blanks.
v blen is the length, in octets, of the converted value for each number that
will be sent to the client.
v min is the minimum value allowed for a number. An "*" indicates that the
number is the smallest number that can fit in the space allowed for the
converted value.
v max is the maximum value allowed for a number. An "*" indicates that
the number is the largest number that can fit in the space allowed for the
converted value.
LUINT(blen,min,max)
indicates that the allowed option value is a list of signed whole numbers,
separated by blanks.
v blen is the length, in octets, of the converted value for each number that
will be sent to the client.
v min is the minimum value allowed for a number. An "*" indicates that the
number is the smallest number that can fit in the space allowed for the
converted value.
v max is the maximum value allowed for a number. An "*" indicates that
the number is the largest number that can fit in the space allowed for the
converted value.
Usage Notes
v The Option statement may be specified at the global, subnet, class, client,
vendor or DefineOptions level only.
v The following options should not be specified or redefined within the machine file;
they control DHCP processing.
43
Vendor specific information
52
Option overload
53
DHCP message type
54
Server identifier
55
Parameter request list
56
Message
57
Maximum DHCP message size
60
Class identifier
61
Client identifier
77
Client class
v If an option is not defined, then its value is treated as a character string or, if the
HEX operand is specified, as hexadecimal data.
v It may be easier to use the DefineOptions statement to define an unrecognized
option than coding the value in ASCII or hexadecimal. For example, if a new
option (for example 190) is used by the client to contain a series of 32 bit signed
time offsets: 18000, 12000, and 3000, you could code it in hex as follows:
190 hex 0000465000002ee000000bb8
90
z/VM: TCP/IP Planning and Customization
DHCP Server
or you could define the options and specify the 190 option values as decimal
numbers.
DefineOptions
{
option 190 lsint(4,*,*)
}
option 190
18000 12000 3000
v See “DHCP Options” on page 97 for a description of the recognized option
numbers and the option values which may be specified.
PingTime Statement
Use the PingTime statement to specify a time interval that the server will wait for a
response to a ping (ICMP Echo Request). The server pings an IP address before it
is assigned, to make sure that address is not already in use.
PINGTIME
PT
time
SEConds
SEConds
Operands
time
is the number of seconds to wait for the response to a ping. The value must be
a whole number (Base 10) between 1 and 30. If this statement is not specified,
the PingTime defaults to 1 second.
SEConds
indicates that the time value is seconds.
Usage Notes
v The PingTime statement should be specified at the global level only and
therefore, is used for all addresses supported by this server.
ReservedTime Statement
Use the ReservedTime statement to specify the maximum amount of time the
server holds an offered address in reserve, while waiting for a response from the
client.
ReservedTime
RT
time
MINutes
SEConds
MINutes
HOUrs
DAYs
MONths
YEArs
Chapter 7. Configuring the DHCP Server
91
DHCP Server
Operands
time
is the amount of time to wait for a response from a client that has been offered
an address.
The value must be a positive whole number (Base 10), or "-1" (which means
infinity). If this statement is not specified, the ReservedTime defaults to 5
minutes. The minimum time value must be equal to at least 30 seconds.
SEConds
indicates the time value is in units of seconds.
MINutes
indicates the time value is in units of minutes.
HOUrs
indicates the time value is in units of hours.
DAYs
indicates the time value is in units of days.
MONths
indicates the time value is in units of months.
YEArs
indicates the time value is in units of years.
Usage Notes
v The ReservedTime statement should be specified at the global level only and
therefore, is used for all addresses issued by this server.
SUBNET Statement
Use the Subnet statement to specify configuration parameters for an address pool
administered by a server. An address pool is a range of IP addresses to be leased
to clients. The task of configuring subnets also allows you to set lease time and
other options for clients that use the address pool. Lease time and other options
can be inherited from a global level.
SUBNET subnet_address
( comments
subnet_mask
range
label:labelname
/priority
Operands
subnet_address
is the address of this subnet, specified in dotted-decimal notation (for example,
9.67.48.0).
subnet_mask
is the mask for the subnet, in dotted-decimal notation or in integer format. A
subnet mask divides the subnet address into a subnet portion and a host
portion. If no value is entered for the subnet mask, the default is the class mask
appropriate for an A, B, or C class network.
92
z/VM: TCP/IP Planning and Customization
DHCP Server
A subnet mask can be expressed either in dotted-decimal notation, or as an
integer between 8 and 31. For example, the subnet mask 255.255.240.0 is
expressed in dotted-decimal notation. For subnet 9.67.48.0, this mask implies
an address range from 9.67.48.001 to 9.67.63.254. The equivalent integer
format for this mask is 20; the value 20 is the total number of 1s present when
the mask is expressed in binary, as 11111111.11111111.11110000.00000000.
Default subnet masks include:
v Class A network - 255.0.0.0
v Class B network - 255.255.0.0
v Class C network - 255.255.255.0
range
is a range of addresses to be administered to this subnet. Enter the addresses
in dotted-decimal notation, beginning with the lower end of the range, followed
by a hyphen, then the upper end of the range, with no spaces between. For
example, 9.67.48.1-9.67.48.128. If more than one subnet has the same subnet
address and mask, their ranges should not overlap.
labelname
is a label (a string of 1 to 64 alphanumeric characters) that identifies the subnet
group.
priority
is the priority that this subnet is used in relation to other subnets which share
the same label.
comments
anything after the left parenthesis is treated as a comment and ignored by the
server. This allows compatibility with other IBM DHCP servers.
Usage Notes
v The Subnet statement should be specified at the global level only.
v IP addresses specified on the range operand may be restricted from general use
in the subnet by CLASS and CLIENT statements that specify IP addresses. The
restricted addresses will be allocated only to clients that belong to the related
class or client.
v When an address range is specified, do not include the address of the subnet
and the address used for broadcast messages. For example, if the subnet
address is 9.67.96.0 and the subnet mask is 255.255.240.0, do not include
9.67.96.0 and 9.67.111.255 in the range of addresses.
v Use the Client statement to exclude an IP address from a range of addresses
that is administered by the DHCP server. For example, exclude an address that
has been permanently assigned to a host. For more information on Client
statements, see “CLIENT Statement” on page 84.
v To identify which subnets are grouped together on the same wire, more than one
subnet can have the same identifier. For example, the five subnet statements
that follow are part of two different groups, labelled as WIRE1 (9.67.48.0 and
9.67.49.0) and WIRE3 (9.67.50.0 and 9.67.51.0). Specifying a label for a subnet
group has no affect unless that label is then specified on an InOrder: or Balance:
statement. If not specified on one of these two statements, a label is ignored
during processing, and clients are allocated addresses for the subnet on which
they broadcast their request.
The order in which addresses are selected from subnet statements is determined
by the priority associated with each subnet statement. Although second in the
sequence of statements for subnet group WIRE3, the address pool for subnet
Chapter 7. Configuring the DHCP Server
93
DHCP Server
9.67.50.0 (addresses 1-50) is used before the address pool for subnet 9.67.51.0
— which is defined first in the WIRE3 statement sequence. The address pool for
subnet 9.67.50.0 (addresses 51-100) will be used last for the WIRE3 subnet
group.
For subnet group WIRE1 (which is listed on the Balance: statement), the
assigned priority values have less of an affect on the selection of addresses,
because the server will alternate among the members of this group as it attempts
to allocate addresses. In this case, the priority values determine only the order in
which the list of groups is traversed. Here, an attempt is made to select an
address from 9.67.49.0, then 9.67.48.0, then 9.67.49.0, and so on.
InOrder: WIRE3
Balance: WIRE1
subnet 9.67.49.0
subnet 9.67.48.0
subnet 9.67.51.0
subnet 9.67.50.0
subnet 9.67.50.0
255.255.255.0
255.255.255.0
255.255.255.0
255.255.255.0
255.255.255.0
9.67.49.1-9.67.49.100 label:WIRE1/3
9.67.48.1-9.67.48.50 label:WIRE1/5
9.67.51.1-9.67.51.50 label:WIRE3/2
9.67.50.1-9.67.50.50 label:WIRE3/1
9.67.50.51-9.67.50.100 label:WIRE3/3
SupportBootP Statement
Use the SupportBootP statement to specify whether DHCPD responds to requests
from BootP clients.
SUPPORTBOOTP
SB
YES
NO
Operands
YES
indicates that BootP clients should be supported. This is the default if the
statement is not specified.
NO
indicates that BootP clients should not be supported.
Usage Notes
v The SupportBootP statement should be specified at the global level only and
therefore, is used for all BootP requests received by this server.
v If DHCPD previously supported BootP clients and has been reconfigured to not
support BootP clients, the address binding for any BootP clients that was
established before the reconfiguration will be maintained until the BootP client
sends another request (when it is restarting). At that time, the server will not
respond, and the binding will be removed.
SupportUnlistedClients Statement
Use the SupportUnlistedClients statement to control whether DHCPD will respond
to clients that are not listed (by client ID) in the machine file.
94
z/VM: TCP/IP Planning and Customization
DHCP Server
SUPPORTUNLISTEDCLIENTS
SUC
YES
NO
Operands
YES
indicates that clients not listed (by client ID) in the machine file should be
supported.
NO
indicates that only clients listed (by client ID) in the machine file should be
supported.
Usage Notes
v The SupportUnlistedClients statement should be specified at the global level only
and therefore, is used for all requests received by this server.
v This statement can be used to limit access to addresses managed by this DHCP
server. Listing the client IDs for all acceptable clients may be time consuming.
v If the SupportUnlistedClients statement is not specified, the default is ’YES’ —
unlisted clients are supported.
UsedIPAddressExpireInterval Statement
Use the UsedIPAddressExpireInterval statement to specify the amount of time to
retain an IP address whose lease has expired, before that address is returned to
the available address pool for possible reassignment to another client. This allows
the client that last used an address to again request it — within the specified time
interval — and have that address reassigned to it.
USEDIPADDRESSEXPIREINTERVAL
UIPEI
time
MINutes
SEConds
MINutes
HOUrs
DAYs
MONths
YEArs
Operands
time
is the amount of time to wait before an IP address, whose lease has expired, is
returned to the pool of available addresses.
The value must be a positive whole number (Base 10), or "-1" (which means
infinity). If this statement is omitted, the UsedIPAddressExpireInterval defaults to
30 seconds.
SEConds
indicates the time value is in units of seconds.
Chapter 7. Configuring the DHCP Server
95
DHCP Server
MINutes
indicates the time value is in units of minutes.
HOUrs
indicates the time value is in units of hours.
DAYs
indicates the time value is in units of days.
MONths
indicates the time value is in units of months.
YEArs
indicates the time value is in units of years.
Usage Notes
v The UsedIPAddressExpireInterval statement should be specified at the global
level only and therefore, is used for all addresses supported by this server.
VENDOR Statement
Use the Vendor statement to specify an option 43 value to be returned to clients
that specify an option 60 value that matches the vendor name.
VENDOR vendor_name
HEX hexvalue
Operands
vendor_name
is the user-defined label that identifies the vendor. The client transmits this label
using option 60. The vendor name is an ASCII string of up to 255 characters
(for example, "IBM"). If the vendor name contains spaces, it must be
surrounded by single (') or double quotes (").
HEX
indicates that option 43 data follows this keyword.
hexvalue
is an EBCDIC representation of the hexadecimal value to be returned to the
client in option 43.
Usage Notes
v The Vendor statement should be specified at the global level only.
v The Vendor statement may be followed by a pair of braces that delimit the
options particular to this vendor. Within these braces, the usual option value
encoding and decoding rules do not apply. An option 43 value will be constructed
from the specified options in the form of an option number, followed by the length
of the data for that option, and the option data.
The value for each option must be specified either as an EBCDIC string, or in
hexadecimal form, by specifying the HEX keyword followed by the EBCDIC
representation of the hexadecimal value.
For example
96
z/VM: TCP/IP Planning and Customization
DHCP Server
VENDOR IBM
{
OPTION 1 1
OPTION 15 HEX F1
}
would create an option 43 value of (shown in hex):
0101300F01F1
Note: The value of 1 for option 1 is ’30’ which is the ASCII value for the
character ’1’.
You could also specify the value on the Vendor statement using the hex keyword,
as follows:
VENDOR IBM hex 0101300F01F1
DHCP Options
The following table lists the option names, their numbers, and the locations of
additional information.
Table 12. DHCP Option Names and Numbers
Name
Number
Page
All Subnets are local
27
104
ARP Cache Timeout
35
105
Boot File name
67
110
Boot File Size
13
102
Broadcast Address
28
104
Client Class
77
111
Client Identifier
61
109
Cookie Server
8
101
Default Finger Server
73
111
Default Internet Relay Chat (IRC) Server
74
111
Default IP Time-to-live
23
103
Default World Wide Web (WWW) Server
72
111
DHCP Message Type
53
108
Domain Name
15
102
Domain Name Server
6
100
Ethernet Encapsulation
36
105
Extension Path
18
102
Host Name
12
101
Impress Server
10
101
Interface MTU
26
104
IP Address Lease Time
51
107
IP Forwarding Enable/Disable
19
102
Log Server
7
101
LPR Server
9
101
Mask Supplier
30
104
Chapter 7. Configuring the DHCP Server
97
DHCP Server
Table 12. DHCP Option Names and Numbers (continued)
Name
98
Number
Page
Maximum Datagram Reassembly Size
22
103
Maximum DHCP Message Size
57
109
Merit Dump File
14
102
Message
56
108
Mobile IP Home Agent
68
110
Name Server
5
100
NetBIOS over TCP/IP Datagram Distribution Server
45
107
NetBIOS over TCP/IP Name Server
44
106
NetBIOS over TCP/IP Node Type
46
107
NetBIOS over TCP/IP Scope
47
107
Network Information Servers
41
106
Network Information Service Domain
40
106
Network Information Service+ Domain
64
109
Network Information Service+ Servers
65
109
Network News Transport Protocol (NNTP) Server
71
110
Network Time Protocol Servers
42
106
Non-Local Source Routing Enable/Disable
20
103
Option Overload
52
108
Parameter Request List
55
108
Path MTU Aging Timeout
24
103
Path MTU Plateau Table
25
103
Perform Mask Discovery
29
104
Perform Router Discovery
31
104
Policy Filter
21
103
Post Office Protocol (POP3) Server
70
110
Rebinding (T2) Time Value
59
109
Renewal (T1) Time Value
58
109
Requested IP address
50
107
Resource Location Server
11
101
Root Path
17
102
Router Address
3
100
Router Solicitation Address
32
105
Server Identifier
54
108
Simple Mail Transport Protocol (SMTP) Server
69
110
Static Route
33
105
StreetTalk Directory Assistance (STDA) Server
76
111
StreetTalk Server
75
111
Subnet Mask
1
100
Swap Server
16
102
TCP Default TTL
37
105
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 12. DHCP Option Names and Numbers (continued)
Name
Number
Page
TCP Keepalive Interval
38
106
TCP Keepalive Garbage
39
106
TFTP Server Name
66
110
Time Offset
2
100
Time Server
4
100
Trailer Encapsulation
34
105
Vendor Class Identifier
60
109
Vendor Specific Information
43
106
X Window System Display Manager
49
107
X Window System Font Server
48
107
Table 14 on page 100 lists the DHCP option numbers, their description and the type
of data which may be entered in the machine file for the option on the Option
statement.
The following table lists the complex datatypes that appear in Table 14 on page 100.
Table 13. DHCP Option Datatype Formats
Datatype
Format
Character string
A single blank delimited word, or a string (which may contain
blanks), that begins with a single or double quote and ends
with the same quote. The character string is translated from
EBCDIC to ASCII before its use.
Hexadecimal string
"HEX" followed by a single blank delimited word containing
pairs of EBCDIC characters (0-1, and A-F) which represent a
hexadecimal byte of data. The data is assumed to represent
ASCII or OCTET values and is not translated from EBCDIC
to ASCII as character strings are translated.
IP Address
Dotted-decimal notation (for example, 9.100.25.100)
IP Address List
List of IP addresses separated by blanks
IP Address Pair
Two IP addresses in dotted-decimal notation which are
separated by blanks.
IP Address Pair List
List of IP address pairs. All addresses are separated from
each other by blanks.
Signed Integer
A single blank delimited word that begins with a sign (+ or −).
If a sign is not specified, "+" is the default.
Unsigned Integer
A single blank delimited word that does not begin with a sign
and denotes a positive value.
List of Signed Integers
A list of blank delimited numbers that begin with a sign (+ or
−). If a sign is not specified, "+" is the default.
List of Unsigned Integers
A list of blank delimited numbers that do not begin with a
sign and denote a positive value.
Chapter 7. Configuring the DHCP Server
99
DHCP Server
Table 14. DHCP Options
Option Number
1
Option Information
Name: SUBNET MASK
Description: Specifies the client’s subnet mask per RFC 950.
Datatype:
2
IP address
Name: Time Offset
Description: Specifies the offset of the client’s subnet in seconds
from Coordinated Universal Time (UTC).
Datatype:
Signed Integer
Minimum
-2,147,483,647
Maximum
2,147,483,647
Notes:
1. A positive offset indicates a location east of the zero meridian and
a negative offset indicates a location west of the zero meridian.
3
Name: Router Addresses
Description: Specifies a list of IP address for routers on the client’s
subnet.
Datatype:
IP Address List
Notes:
1. Routers should be listed in order of preference.
4
Name: Time Server
Description: Specifies a list of RFC 868 time servers available to the
client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
5
Name: Name Server
Description: Specifies a list of IEN 116 name servers available to the
client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
6
Name: Domain Name Server
Description: Specifies a list of Domain Name System (STD 13, RFC
1035) name servers available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
100
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 14. DHCP Options (continued)
Option Number
7
Option Information
Name: Log Server
Description: Specifies a list of MIT-LCS UDP log servers available to
the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
8
Name: Cookie Server
Description: Specifies a list of RFC 865 cookie servers available to
the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
9
Name: LPR Server
Description: Specifies a list of RFC 1179 line printer servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
10
Name: Impress Server
Description: Specifies a list of IMAGEN Impress servers available to
the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
11
Name: Resource Location Server
Description: Specifies a list of RFC 886 Resource Location servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
12
Name: Host Name
Description: Specifies the name of the client.
Datatype:
Character string or hexadecimal string
Notes:
1. The name may or may not be qualified with the local domain. If
the Domain Name option is specified then this option must not
include the local domain name as part of the character string.
2. See RFC 1035 for character set restrictions.
Chapter 7. Configuring the DHCP Server
101
DHCP Server
Table 14. DHCP Options (continued)
Option Number
13
Option Information
Name: Boot File Size
Description: Specifies the length (in 512 octet blocks) of the default
boot image for the client.
14
Datatype:
Unsigned Integer
Maximum
65,535
Name: Merit Dump File
Description: Specifies the path name of a file to which the client’s
core image should be dumped in the event the client crashes.
Datatype:
15
Character string or hexadecimal string
Name: Domain Name
Description: Specifies the domain name that the client should use
when resolving host names via the Domain Name System.
Datatype:
Character string or hexadecimal string
Notes:
1. See the Host Name option for information on specifying these
options together.
16
Name: Swap Server
Description: Specifies the IP address of the client’s swap server.
Datatype:
17
IP Address
Name: Root Path
Description: Specifies the path name that contains the client’s root
disk.
Datatype:
18
Character string or hexadecimal string
Name: Extensions Path
Description: Specifies a file, retrievable using TFTP, that contains
information which can be interpreted in the same way as the 64 octet
vendor-extension field within the BOOTP response.
Datatype:
Character string or hexadecimal string
Notes:
1. The file length of the specified file is constrained only by the host
file system that contains the file.
2. All references to option 18 (this option) within the file are ignored
by the client.
19
Name: IP Forwarding Enable/Disable
Description: Specifies whether the client should configure its IP layer
for packet forwarding. A value of 0 means disable IP forwarding, and
a value of 1 means enable IP forwarding.
Datatype:
102
z/VM: TCP/IP Planning and Customization
Integer, 0, or 1
DHCP Server
Table 14. DHCP Options (continued)
Option Number
20
Option Information
Name: Non-Local Source Routine Enable/Disable
Description: Specifies whether a client should configure its IP layer
to allow forwarding of datagrams with non-local source routes. A value
of 0 means that forwarding of such datagrams are not allowed, and a
value of 1 means that forwarding is allowed.
Datatype:
21
Integer, 0, or 1
Name: Policy Filter
Description: Specifies policy filters for non-local source routing. The
filters consist of a list of IP addresses and masks which specify
destination/ mask pairs with which to filter incoming source routes.
Any source routed datagram whose next hop address does not match
one of the filters will be discarded by the client.
Datatype:
22
IP Address Pair List
Name: Maximum Datagram Reassembly Size
Description: Specifies the maximum size datagram that the client
should be prepared to reassemble.
23
Datatype:
Unsigned Integer
Minimum
576
Maximum
65,535
Name: Default IP Time-to-live
Description: Specifies the default time-to-live that the client should
use on outgoing datagrams.
24
Datatype:
Unsigned integer
Minimum
1
Maximum
255
Name: Path MTU Aging Timeout
Description: Specifies the timeout (in seconds) to use, when aging
Path MTU values discovered by the mechanism defined in RFC 1191.
25
Datatype:
Unsigned integer
Maximum
4,294,967,295
Name: Path MTU Plateau Table
Description: Specifies a table of MTU sizes to use when performing
Path MTU Discovery as defined in RFC 1191. The table is formatted
as a list of 16-bit unsigned integers, ordered from smallest to largest.
Datatype:
List of unsigned integers
Minimum
68
Maximum
65,535
Chapter 7. Configuring the DHCP Server
103
DHCP Server
Table 14. DHCP Options (continued)
Option Number
26
Option Information
Name: Interface MTU
Description: Specifies the MTU to use on this interface.
27
Datatype:
Unsigned integer
Minimum
68
Maximum
65,535
Name: All Subnets are Local
Description: Specifies whether the client may assume that all
subnets of the IP network use the same MTU as the subnet of that
network to which the client is directly connected.
A value of 1 means that all subnets share the same MTU. A value of
0 means that the client should assume that some subnets of the
directly connected network may have smaller MTUs.
Datatype:
28
Integer, 0, or 1
Name: Broadcast Address
Description: Specifies the broadcast address in use on the client’s
subnet.
Datatype:
IP Address
Notes:
Legal values for broadcast addresses are specified in STD 3, RFC
1122.
29
Name: Perform Mask Discovery
Description: Specifies whether the client should perform subnet
mask discovery using ICMP. A value of 0 indicates that the client
should not perform mask discovery. A value of 1 means that the client
should perform mask discovery.
Datatype:
30
Integer, 0, or 1
Name: Mask Supplier
Description: Specifies whether the client should respond to subnet
mask requests using ICMP. A value of 0 indicates that the client
should not respond. A value of 1 means that the client should
respond.
Datatype:
31
Integer, 0, or 1
Name: Perform Router Discovery
Description: Specifies whether the client should solicit routers using
the Router Discover mechanism defined in RFC 1256. A value of 0
indicates that the client should not perform router discovery. A value
of 1 means that the client should perform router discovery.
Datatype:
104
z/VM: TCP/IP Planning and Customization
Integer, 0, or 1
DHCP Server
Table 14. DHCP Options (continued)
Option Number
32
Option Information
Name: Router Solicitation Address
Description: Specifies the IP address to which the client should
transmit router solicitation requests.
Datatype:
33
IP Address
Name: Static Route
Description: Specifies a list of static routes that the client should
install in its routing cache. The routes consist of pairs of IP
addresses. The first address is the destination address, and the
second address is the router for the destination.
Datatype:
IP Address Pair List
Notes:
1. If multiple routes to the same destination are specified, they
should be listed in descending order of priority.
2. The default route (0.0.0.0) is an illegal destination for a static
route.
34
Name: Trailer Encapsulation
Description: Specifies whether the client should negotiate the use of
trailers (RFC 893) when using the ARP protocol. A value of 0
indicates that the client should not attempt to use trailers. A value of 1
means that the client should attempt to use trailers.
Datatype:
35
Integer, 0, or 1
Name: ARP Cache Timeout
Description: Specifies the timeout in seconds for ARP cache entries.
36
Datatype:
Unsigned Integer
Maximum
4,294,967,295
Name: Ethernet Encapsulation
Description: Specifies whether the client should use Ethernet Version
2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the interface
is an Ethernet. A value of 0 indicates that the client should use RFC
894 encapsulation. A value of 1 indicates that the client should use
RFC 1042 encapsulation.
Datatype:
37
Integer, 0, or 1
Name: TCP Default TTL
Description: Specifies the default TTL that the client should use
when sending TCP segments.
Datatype:
Unsigned integer
Maximum
255
Chapter 7. Configuring the DHCP Server
105
DHCP Server
Table 14. DHCP Options (continued)
Option Number
38
Option Information
Name: TCP Keepalive Interval
Description: Specifies the interval (in seconds) that a TCP client
should wait before sending a keepalive message on a TCP
connection. A value of zero indicates that the client should not
generate keepalive messages on connections unless specifically
requested to do so by an application.
39
Datatype:
Unsigned Integer
Maximum
4,294,967,295
Name: TCP Keepalive Garbage
Description: Specifies whether the client should send TCP keepalive
messages with an octet of garbage for compatibility with older
implementations. A value of 0 indicates that a garbage octet should
not be sent. A value of 1 indicates that a garbage octet should be
sent.
Datatype:
40
Integer, 0, or 1
Name: Network Information Service Domain
Description: Specifies the name of the client’s NIS domain.
Datatype:
41
Character string or hexadecimal string
Name: Network Information Servers
Description: Specifies a list of IP addresses indicating NIS servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
42
Name: Network Time Protocol Servers
Description: Specifies a list of IP addresses indicating NTP servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
43
Name: Vendor Specific Information
Description: Specifies hexadecimal data to return to the client. This
information is vendor specific.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the Vendor statement only.
44
Name: NetBIOS over TCP/IP Name Server
Description: Specifies a list of RFC 1001/1002 NBNS name servers.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
106
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 14. DHCP Options (continued)
Option Number
45
Option Information
Name: NetBIOS over TCP/IP Datagram Distribution Server
Description: Specifies a list of RFC 1001/1002 NBDD servers.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
46
Name: NetBIOS over TCP/IP Node Type
Description: Specifies the client type.
Datatype:
47
Integer, 1, 2, 4 or 8
Name: NetBIOS over TCP/IP Scope
Description: Specifies the NetBIOS over TCP/IP scope parameter for
the client as specified in RFC 1001/1002.
Datatype:
48
Character string or hexadecimal string
Name: X Window System Font Server
Description: Specifies a list of X Window System Font Servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
49
Name: X Window System Display Manager
Description: Specifies a list of IP address of systems that are
running the X Window System Display Manager and are available to
the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
50
Name: Network Information Service+ Domain
Description: Specifies the name of the client’s NIS+ domain.
Datatype:
51
Character string or hexadecimal string
Name: IP Address Lease Time
Description: Specifies maximum default lease time in seconds. This
option is used in a server reply (DHCPOFFER) to specify the lease
time the server is willing to offer.
Datatype:
Unsigned integer
Maximum
4,294,967,295
Notes:
1. This option overrides the lease time specified by the DHCPD
LEASETIMEDEFAULT statement.
Chapter 7. Configuring the DHCP Server
107
DHCP Server
Table 14. DHCP Options (continued)
Option Number
52
Option Information
Name: Option Overload
Description: Specifies which fields are being overloaded to carry
DHCP options. A DHCP server inserts this option if the returned
parameters will exceed the usual space allowed for options.
1
means that the ’file’ field is used to hold options.
2
means that the ’sname’ field is used to hold options.
3
means that both the ’file’ and ’sname’ field are used
to hold options.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the server to control processing.
53
Name: DHCP Message Type
Description: Specifies the type of DHCP message being sent.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the server and the client to control processing.
54
Name: Server Identifier
Description: Specifies the IP address of the DHCP server. DHCP
Servers use this option to distinguish their DHCPOFFER responses
from other servers’ responses. DHCP clients use the contents of this
option as the destination address for any DHCP message unicast to
the server. They also use this option to indicate which server’s offer is
being accepted.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the server and the client to control processing.
55
Name: Parameter Request List
Description: Specifies a list of options requested by the client and
the order which the client would like them to appear.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the server and the client to control processing.
56
Name: Message
Description: Specifies an error message to be passed between the
client and the server.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the server and the client to control processing.
108
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 14. DHCP Options (continued)
Option Number
57
Option Information
Name: Maximum DHCP Message Size
Description: Specifies the maximum length DHCP message that the
client is willing to receive.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the client to control processing.
58
Name: Renewal (T1) Time Value
Description: Specifies the time interval (in seconds) from address
assignment until the client transitions to the renewing state.
59
Datatype:
Unsigned Integer
Maximum
4,294,967,295
Name: Rebinding (T2) Time Value
Description: Specifies the time interval (in seconds) from address
assignment until the client transitions to the rebinding state.
60
Datatype:
Unsigned Integer
Maximum
4,294,967,295
Name: Vendor Class
Description: Specifies a string which identifies the class of vendor.
This information is compared to the value specified on the Vendor
machine statement as the vendor name.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the client to control processing.
61
Name: Client Identifier
Description: Specifies a unique identifier for the client.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the client to control processing.
64
Name: Network Information Service+ Domain
Description: Specifies the name of the client’s NIS+ domain.
Datatype:
65
Character string or hexadecimal string
Name: Network Information Service+ Servers
Description: Specifies a list of IP addresses indicating NIS+ servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be specified in order of preference.
Chapter 7. Configuring the DHCP Server
109
DHCP Server
Table 14. DHCP Options (continued)
Option Number
66
Option Information
Name: TFTP Server Name
Description: Specifies the name of the TFTP server which the client
should use.
Datatype:
Character string or hexadecimal string
Notes:
1. This value is passed to the client in the 'sname' field or as an
option, if option overloading occurs. See option 52 for information
on overloading.
67
Name: Bootfile name
Description: Specifies the name of the bootfile for the client to
request.
Datatype:
Character string or hexadecimal string
Notes:
1. This value is passed to the client in the 'file' field or as an option,
if option overloading occurs. See option 52 for information on
overloading.
68
Name: Mobile IP Home Agent
Description: Specifies a list of IP addresses indicating mobile IP
home agents available to the client.
Datatype:
IP Address List
Notes:
1. Agents should be listed in order of preference.
2. A 0 may be specified instead of an IP address list to indicate that
no home agents are available.
69
Name: Simple Mail Transport Protocol (SMTP) Server
Description: Specifies a list of IP addresses indicating SMTP servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
70
Name: Post Office Protocol (POP3) Server
Description: Specifies a list of IP addresses indicating POP3 servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
71
Name: Network News Transport Protocol (NNTP) Server
Description: Specifies a list of IP addresses indicating NNTP servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
110
z/VM: TCP/IP Planning and Customization
DHCP Server
Table 14. DHCP Options (continued)
Option Number
72
Option Information
Name: Default World Wide Web (WWW) Server
Description: Specifies a list of IP addresses indicating WWW servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
73
Name: Default Finger Server
Description: Specifies a list of IP addresses indicating Finger servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
74
Name: Default Internet Relay Chat (IRC) Server
Description: Specifies a list of IP addresses indicating IRC servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
75
Name: StreetTalk Server
Description: Specifies a list of IP addresses indicating StreetTalk
servers available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
76
Name: StreetTalk Directory Assistance (STDA) Server
Description: Specifies a list of IP addresses indicating STDA servers
available to the client.
Datatype:
IP Address List
Notes:
1. Servers should be listed in order of preference.
77
Name: Client Class
Description: Specifies a character string which identifies the client’s
class. Option 77 is compared to the class_name value specified on
the machine file Class statement.
Notes:
RESTRICTED. This option may not be specified. It is generated by
the client to control processing.
Chapter 7. Configuring the DHCP Server
111
DHCP Server
Dynamic Server Operation
Some configuration attributes (such as tracing and client request handling) can be
changed during server execution using the DHCPD subcommands described in the
next section. In addition, certain server activities can be queried or changed by
subcommands. Any subcommand not understood by DHCP is assumed to be a
CMS command and is passed to the CMS command line for execution.
Issue DHCPD subcommands at the DHCP server console.
DHCPD Subcommands
The DHCPD subcommands are listed in Table 15. This table provides the shortest
abbreviation, a description, and a page reference for more information for each
DHCPD subcommand.
Table 15. DHCPD Subcommands
Minimum
Subcommand Abbreviation Description
CMS
CMS
Passes a command to CMS for execution.
112
CONFIG
CONFIG
Displays configuration information.
113
DELETE
DELETE
Deletes an IP address lease that has been allocated
to a client.
115
EXCLUDE
EXCLUDE
Identifies adapter addresses for which BootP/DHCP
requests should be ignored.
116
EXIT
EXIT
Stops the DHCP server and its processing. EXIT is
equivalent to QUIT and STOP.
117
FORWARD
FORWARD
Controls the forwarding of BootP/DHCP requests to
another DHCP server.
117
HELP
HELP
Displays a summary of DHCPD subcommands.
119
INCLUDE
INCLUDE
Identifies adapter addresses for which BootP/DHCP
requests should be handled.
120
LURK
LURK
Toggles the LURK mode of the DHCP server.
120
QUIT
QUIT
Stops the DHCP server and its processing. QUIT is
equivalent to EXIT and STOP.
121
RELOAD
RELOAD
Reloads DHCPD machine and configuration files.
121
SHOW
SHOW
Displays the information which would be returned to a
client that specified parameters similar to the ones
specified on the subcommand.
122
STATUS
STATUS
Displays the status of an IP address, Client or
Subnet’s addresses.
125
STAYUP
STAYUP
Toggles the STAYUP mode of the DHCP server.
127
STOP
STOP
Stops the DHCP server and its processing. STOP is
equivalent to EXIT and QUIT.
127
TRACE
TRACE
Toggles the TRACE mode of the DHCP server.
128
CMS Subcommand
Use the CMS subcommand to issue a command to CMS.
112
Page
z/VM: TCP/IP Planning and Customization
DHCP Server
CMS
cms_command
Operands
cms_command
is the CMS command to be issued.
Usage Notes
v Do not issue any CMS command that would take considerable time to execute
(for example, XEDIT). While the CMS command executes, the server does not
respond to requests.
v The CMS keyword is usually not required because the daemon will pass any
command string that is not recognized as a DHCPD subcommand to CMS. The
CMS keyword is used to identify CMS commands which would normally be
interpreted as a DHCPD subcommand, for example, TRACE.
Examples
v After completion of any command, the following ready prompt is displayed:
DHCPD Ready;
or
DHCPD Ready (rc);
if the return code (rc) is not zero.
CONFIG Subcommand
Use the CONFIG subcommand to display configuration information.
CONFIG
Usage Notes
v The CONFIG subcommand causes the DHCP daemon to query the current
TCP/IP configuration of the host where the DHCP daemon is running, to
determine the IP addresses defined for that host. Any included adapter that is not
in the defined IP address list will be automatically excluded as the result of this
subcommand’s operation, whether the subcommand completes successfully or
not.
Examples
v The CONFIG subcommand produces a multiple line response which indicates the
status of settings, table files used, included and excluded adapter addresses, and
forwards that are active or could be activated. This output is discussed below, in
sections, for clarity of meaning.
Chapter 7. Configuring the DHCP Server
113
DHCP Server
Lurk=l Stayup=s Trace=t
Machine Table=filespec
Configuration Table=filespec
This section indicates the status of the LURK, STAYUP, and TRACE settings,
along with the file specifications for the machine and configuration table files
used by the server.
l
is 1 if LURK mode is on; 0 if LURK mode is off.
s
is 1 if STAYUP mode is on; 0 if STAYUP mode is off.
t
is 1 if TRACE mode is on; 0 if TRACE mode is off.
filespec
is the file name, file type and file mode of the file that is in use.
Included Addresses:
Adapter adpaddr reqtype
This section indicates the IP addresses of adapters for which the DHCP daemon
will process requests. One "Adapter" line is displayed for each adapter that the
DHCP daemon will handle. If there are no included addresses, "NONE" is
displayed instead of the "Adapter" line(s).
adpaddr
is the IP address of an adapter.
reqtype
is the type of request that will be handled. Possible values are:
CLIENTS
for BootP/DHCP requests broadcast by clients to the host.
GATEWAYS
for BootP/DHCP requests forwarded by a DHCP daemon on
behalf of a client.
ANY
for any client or gateway forwarded requests.
Excluded Addresses:
Adapter adpaddr reqtype
This section indicates the IP addresses of adapters the DHCP daemon should
ignore. If there are no excluded addresses, "NONE" is displayed instead of the
"Adapter" line(s).
adpaddr
is the IP address of the adapter.
reqtype
is the type of request that will be excluded. Possible values are:
114
CLIENTS
for BootP/DHCP requests broadcast by clients to the host.
GATEWAYS
for BootP/DHCP requests forwarded by a DHCP daemon on
behalf of a client.
ANY
for any client or gateway forwarded requests.
z/VM: TCP/IP Planning and Customization
DHCP Server
Forwards:
Adapter adpaddr -> toaddr frequency actflag
Gateway gateaddr -> toaddr frequency
This section indicates whether BootP/DHCP request forwarding has been
specified for:
– requests received on specific adapters, or
– requests forwarded by a specific gateway.
adpaddr
is the IP address of the adapter.
gateaddr
is a gateway IP address. The gateway IP address is the address of an
adapter on which a request is initially received, but is then forwarded.
toaddr
is the IP address of a host that is running another DHCP daemon which
should receive forwarded requests.
frequency
is an indication of when forwarding should occur for the specified adapter or
gateway. ALWAYS indicates that any request on the adapter or forwarded by
the gateway should always be forwarded.
actflag
indicates the status of the adapter for which the forward has been specified.
This value can be either:
INCLUDED
indicating that the adapter is included in the configuration
and handles both client and gateway-forwarded requests.
EXCLUDED
indicating that the adapter is excluded from the configuration
(for example, no forwarding will occur until the adapter is
included in the configuration).
PARTIAL
indicating that some BootP/DHCP requests received on the
adapter will not be handled. This can occur if the EXCLUDE
or INCLUDE subcommand resulted in some BootP/DHCP
requests not being handled. For example, gateway forwarded
requests received over a specific adapter may be excluded,
while client requests may be included. For more information
about how to control request handling see “INCLUDE
Subcommand” on page 59 and “EXCLUDE Subcommand” on
page 55.
DELETE Subcommand
Use the DELETE subcommand to remove an active lease for an IP address that
has been given to a client.
DELETE LEASE
ADDress ipaddr
CLIent hwtype clientid
Operands
LEASE
indicates that a lease is being deleted.
Chapter 7. Configuring the DHCP Server
115
DHCP Server
ADDress
indicates that the operand that follows is the IP address whose lease is to be
deleted.
ipaddr
is an IP address specified in dotted-decimal notation.
CLIent
indicates that the operands that follow identify the client that is associated with
the IP address whose lease will be deleted.
hwtype
is the hardware type of the client computer, or 0. The valid client types are
defined in STD 2, RFC 1700.
hwtype
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Client hardware
ethernet ether
ethernet3 ether3
ax.25
pronet
chaos
token-ring tr
arcnet
hyperchannel
lanstar
autonet
localtalk
localnet
ultra_link
smds
frame_relay
atm
ieee802
fddi
clientID
is the hexadecimal MAC address or a name which identifies the client. If a
name is specified then:
v hwtype must be 0
v If the name contains blanks, then it must be enclosed in single or double
quotes.
Usage Notes
v The DELETE subcommand is useful when you determine that an assigned lease
is no longer being used and you wish to make the address available for
reassignment. For example, a lease will become available when a BootP client,
which has a permanent lease on an address, moves to a different subnet.
EXCLUDE Subcommand
Use the EXCLUDE subcommand to specify an adapter address to ignore. You can
specify additional operands to indicate whether all requests received across a
specific adapter should be ignored, or whether only client BootP/DHCP requests or
gateway-forwarded requests should be ignored.
116
z/VM: TCP/IP Planning and Customization
DHCP Server
EXCLUDE
ADApter ipaddr
ALL
ANY
CLIents
GATeways
ANY
Operands
ADApter ipaddr
indicates the IP address of the adapter on the host system that should be
ignored.
ALL
indicates that all adapters should be ignored.
ANY
indicates that any request that is received on the specified adapters (or "ALL")
should be ignored. This is the default.
CLIents
indicates that only client BootP/DHCP requests that are received on the
specified adapters (or "ALL") should be ignored.
GATeways
indicates that gateway-forwarded requests that are received on the specified
adapters (or "ALL") should be ignored.
Usage Notes
v The opposite of the EXCLUDE subcommand is the INCLUDE subcommand. Any
values set by the EXCLUDE subcommand may be reset by the INCLUDE
subcommand.
v The EXCLUDE subcommand causes the DHCP daemon to query the current
TCP/IP configuration of the host where the DHCP daemon is running, to
determine the IP addresses defined for that host. Any included adapter that is not
in the defined IP address list will be automatically excluded as the result of this
subcommand’s operation, whether the subcommand completes successfully or
not.
EXIT Subcommand
Use the EXIT subcommand to stop the DHCP daemon. This subcommand is
equivalent to the QUIT and STOP subcommands.
EXIT
Operands
The EXIT subcommand has no operands.
FORWARD Subcommand
Use the FORWARD subcommand to specify BootP/DHCP requests that should be
forwarded to another DHCP daemon at another IP address. Requests are selected
Chapter 7. Configuring the DHCP Server
117
DHCP Server
on the basis of the adapter on which they are received or the gateway from which
they were forwarded.
FORWARD
ADApter ipaddr
GATeway gateaddr
ALL
TO
toipaddr
ALWAYS
ALWays
NEVer
Operands
ADApter ipaddr
indicates that BootP/DHCP requests received over the specified IP address
should be forwarded. The IP address is the address of an adapter on the host
system that would receive the request.
GATeway gateaddr
indicates that BootP/DHCP requests that were forwarded by a gateway at the
specified IP address should be forwarded.
ALL
indicates that all IP adapter addresses should be handled as forwarding
addresses.
TO toipaddr
indicates the IP address to which the BootP/DHCP request should be
forwarded.
ALWAYS
indicates that BootP/DHCP requests that pass the selection criteria (for
example, on the specified adapter or from the specified gateway) should always
be forwarded. This is the default.
NEVER
indicates that BootP/DHCP requests that pass the selection criteria (for
example, on the specified adapter or from the specified gateway) should never
be forwarded. This cancels the forwarding that may have been previously
specified for the BootP/DHCP requests that match the criteria.
Usage Notes
v Forwarding applies only to requests that are not excluded by the EXCLUDE
subcommand.
v Forwarding specified for a gateway takes precedence over forwarding specified
for an adapter.
v A hop count is maintained in the BOOT request. This hop count is incremented
each time a DHCP daemon forwards the request. The DHCP server will not
forward a request whose hop count is three or more.
v The BOOT request contains a server name field. This field allows the client to
specify the host name of a DHCP daemon which should process the request. If
the target DHCP daemon is not the receiving server, and the address of the
server is not on the same cable as the adapter that received the request, then
the request will be forwarded.
Normally, a request is not forwarded to a target DHCP daemon when the target
daemon is on the same cable as the adapter of the DHCP daemon that receives
the original request. Such forwarding is not done because it is assumed that the
target daemon would have heard this same request.
118
z/VM: TCP/IP Planning and Customization
DHCP Server
However, you can override this and force a request to be sent to such a target
daemon. If a FORWARD to a specific IP address is defined for a receiving
adapter, requests will always be forwarded to the DHCP daemon at that IP
address.
v Requests that are forwarded by a gateway contain a gateway IP address. The
DHCP server specifies this gateway IP address as the address of the adapter
which receives the original request. This allows the DHCP daemon, which
ultimately builds the response packet for the requesting client, to send that
packet to the correct gateway; that gateway then sends the response packet to
the client.
Only the DHCP daemon that initially hears the client request acts as the
gateway; subsequent forwarding of the request by other DHCP daemons does
not change the gateway IP address.
v Forwarding is useful if you wish to centralize your machine files on a specific
host and have other DHCP daemons forward their received requests to the
central site for processing. When you set up forwarding in this manner, you must
take into account the increased load on the central server and the time required
to forward requests. If the interval to respond to a client request is too long, that
client may then retransmit its requests, and increase the network load.
The following is a simple example of forwarding to central sites. The
configuration consists of three hosts that run VM DHCP daemons:
VMSAT1, VMSAT2
Satellite VM hosts running DHCP daemons connected to subnets
with clients that submit BootP/DHCP requests.
VMMAIN
Main VM host running DHCP for responding to BootP/DHCP
requests from VMSAT1 and VMSAT2.
In this example, requests received by the VMSAT1 or VMSAT2 are automatically
routed to VMMAIN. This allows VMSAT1 and VMSAT2 to run DHCP daemons
which do not maintain a functional machine file. A Forward statement would
appear in the configuration files for VMSAT1 and VMSAT2 as:
FORWARD ALL TO xxx.xxx.xxx.xxx ALWAYS
where xxx.xxx.xxx.xxx is the IP address of VMMAIN.
v The FORWARD subcommand causes the DHCP daemon to query the current
TCP/IP configuration of the host where the DHCP daemon is running, to
determine the IP addresses defined for that host. Any included adapter that is not
in the defined IP address list will be automatically excluded as the result of this
subcommand’s operation, whether the subcommand completes successfully or
not.
HELP Subcommand
Use the HELP subcommand to display a brief description of available
subcommands.
HELP
Operands
The HELP subcommand has no operands.
Chapter 7. Configuring the DHCP Server
119
DHCP Server
INCLUDE Subcommand
Use the INCLUDE subcommand to specify the adapter address or address of
DHCP forwarding daemons for which requests should be handled.
INCLUDE
ADApter ipaddr
ALL
ANY
CLIents
GATeways
ANY
Operands
ADApter ipaddr
indicates the IP address of the adapter on the host system for which requests
should be handled.
ALL
indicates that requests from all adapters should be handled.
ANY
indicates that any request that is received on the specified adapters (or "ALL")
should be handled. This is the default.
CLIents
indicates that only client BootP/DHCP requests that are received on the
specified adapters (or "ALL") should be handled.
GATeways
indicates that gateway-forwarded requests that are received on the specified
adapters (or "ALL") should be handled.
Usage Notes
v The opposite of the INCLUDE subcommand is the EXCLUDE subcommand. Any
values set by the INCLUDE subcommand may be reset by the EXCLUDE
subcommand.
v The INCLUDE subcommand causes the DHCP daemon to query the current
TCP/IP configuration of the host where the DHCP daemon is running, to
determine the IP addresses defined for that host. Any included adapter that is not
in the defined IP address list will be automatically excluded as the result of this
subcommand’s operation, whether the subcommand completes successfully or
not.
LURK Subcommand
Use the LURK subcommand to toggle the LURK mode in the DHCP daemon. If the
daemon is already operating in LURK mode, it will resume answering requests from
clients. If the daemon is not operating in LURK mode, it will begin to listen for, but
not will not respond to, client requests.
LURK
120
z/VM: TCP/IP Planning and Customization
DHCP Server
Examples
1. The following is displayed on completion of this subcommand:
LURK is now l
where l is 0 if LURK mode is off; 1 if LURK mode is on.
QUIT Subcommand
Use the QUIT subcommand to stop the DHCP daemon. This subcommand is
equivalent to the EXIT and STOP subcommands.
QUIT
Operands
The QUIT subcommand has no operands.
RELOAD Subcommand
Use the RELOAD subcommand to reload the machine or configuration table file.
RELOAD
MACHINE ETC DHCPTAB *
MACHINE
ETC DHCPTAB *
fn
DHCPTAB *
fm
CNF DHCPTAB *
fn
DHCPTAB *
ft
*
(1)
(1)
(1)
*
ft
CONFIG
(1)
(1)
(1)
(1)
fm
Notes:
1
If filemode is specified as an asterisk "*" or is defaulted, the first file in the
search order that matches filename and filetype is used.
Operands
MACHINE
indicates that the file to be loaded is a machine file that contains client
information.
Chapter 7. Configuring the DHCP Server
121
DHCP Server
fn is the file name of the file to load.
ft
is the file type of the file to load.
fm is the file mode of the file to load.
CONFIG
indicates that the file to be loaded is a configuration file.
Usage Notes
v MACHINE and CONFIG are reserved keywords. They may not be used as file
names or file types.
v The configuration file is composed of blank lines, comment lines, and
configuration statements. Configuration statements have the same function and
syntax as the DHCPD EXCLUDE, FORWARD, and INCLUDE subcommands.
The format of the configuration file is:
– One line per statement.
– Blank lines are ignored.
– Comment lines are ignored. Comment lines are lines where the first non-blank
character is an "*", "#", or ";".
v The machine file is composed of blank lines, comment lines, entry lines for the
clients, and tag control lines used to decipher the entry lines. The format and
content of this file is described in the section “DHCPD Machine Statements” on
page 80.
v When a configuration file is processed, all adapters are assumed to be included
and no forwarding exists until specified otherwise by configuration file statements.
Examples
If the machine file is successfully loaded, the following response is displayed:
fn ft fm loaded in secs seconds.
Table reloaded from fn ft fm
DHCPD Ready;
where fn, ft, and fm are the respective file name, file type and file mode of the
loaded file, and secs is the time required to load the file.
SHOW Subcommand
Use the SHOW subcommand to display information which would be returned to a
client that specified parameters similar to those specified with the SHOW
subcommand.
SHOW
ALL
REQuest (1)
ADDress ipaddr
CLIent hwtype clientid
CLAss class_name
VENdor vendor_name
Notes:
1
122
Each keyword string may be specified only once.
z/VM: TCP/IP Planning and Customization
DHCP Server
Operands
ALL
indicates that the current client and configuration settings in the machine file
should be displayed.
REQuest
indicates that the operands which follow identify the client BootP/DHCP request.
The output of this command should show the options and addresses that would
be used if a client provided a request specifying specific client related options.
ADDress
indicates that the operand which follows is an IP address from which the
request would have been received. This can be the subnet address or a valid
address on the subnet.
ipaddr
is an IP address specified in dotted-decimal notation.
CLIent
indicates that the two operands which follow specify a client ID.
hwtype
is the hardware type of the client computer, or 0. The valid client types are
defined in STD 2, RFC 1700.
hwtype
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Client hardware
ethernet ether
ethernet3 ether3
ax.25
pronet
chaos
token-ring tr
arcnet
hyperchannel
lanstar
autonet
localtalk
localnet
ultra_link
smds
frame_relay
atm
ieee802
fddi
clientid
is the hexadecimal MAC address or a name which identifies the client. If a
name is specified then:
v hwtype must be 0
v If the name contains blanks, then it must be enclosed in single or double
quotes.
CLAss
indicates that the operand that follows specifies a class name.
class_name
is the user-defined label that identifies the class. The client would specify the
class name using option 77. The class name is an ASCII string of up to 255
Chapter 7. Configuring the DHCP Server
123
DHCP Server
characters (for example, "accounting"). If the class name contains spaces, it
must be surrounded by a pair of single quotes (') or a pair of double quotes (").
VENdor
indicates that the operand which follows specifies a vendor name.
vendor_name
is the user-defined label that identifies the vendor. The client would transmit this
label using option 60. The vendor name is an ASCII string of up to 255
characters (for example, "IBM"). If the vendor name contains spaces, it must be
surrounded by a pair of single quotes (') or a pair of double quotes (").
Examples
1. If the "ALL" operand is specified, then output similar to the following is
displayed:
SHOW ALL
GLOBAL DATA
Boot Strap Server: 9.100.48.75
Support BootP: Yes
Support Unlisted Clients: No
Lease Expire Interval: 1 MINUTES
Lease Time Default: -1
Ping Time: 1 SECONDS
Reserved Time: 5 MINUTES
Used IP Expire Interval: 30 SECONDS
OPTION 4: 9.100.48.50
VENDOR: IBM Network Station
OPTION 43: /
CLIENT: 6 0000e580fca8
IP ADDRESS: ANY
OPTION 4: 9.100.48.75
CLASS: IBMNSM 1.0.0
OPTION 67: /QIBM/ProdData/NetworkStation/kernel
SUBNET 9.100.57.0
SUBNET MASK: 255.255.255.0
RANGE: 9.100.57.1 - 9.100.57.99
OPTION 3: 9.100.57.253
OPTION 5: 9.100.25.252
OPTION 6: 9.100.25.252
OPTION 15: ibm.com
CLASS: IBMNSM 1.0.1
OPTION 67: /QIBM/ProdData/NetworkStation/me
SUBNET 9.100.57.0
SUBNET MASK: 255.255.255.0
RANGE: 9.100.57.100 - 9.100.57.140
OPTION 3: 9.100.57.253
OPTION 5: 9.100.25.252
OPTION 6: 9.100.25.252
OPTION 15: ibm.com
CLASS: IBMNSM 1.0.1
OPTION 67: /QIBM/ProdData/NetworkStation/altme
The Option lines in the output indicate the configuration options that are defined
in the machine file. These options are sent to the client in the DHCP and BootP
replies.
2. If the "REQUEST" operand is specified, then the response to a similar request
(information that is the same as the specified operands) is shown. If there is
more than one possible response then all of them are shown. This example
uses the same machine file as the previous SHOW ALL example. In this
example, the request would generate two possible responses; one from subnet
9.100.57.0 with address pool 9.100.57.1 to 9.100.57.99, and another from the
same subnet with address pool 9.100.57.100 to 9.100.57.140.
124
z/VM: TCP/IP Planning and Customization
DHCP Server
SHOW REQUEST CLIENT 6 0000e580fca8 CLASS "IBMNSM 1.0.1"
SUBNET 9.100.57.0
IP ADDRESS: 9.100.57.1 - 9.100.57.99
Boot Strap Server: 9.100.48.75
OPTION 3: 9.100.57.253
OPTION 4: 9.100.48.75
OPTION 5: 9.100.25.252
OPTION 6: 9.100.25.252
OPTION 15: ibm.com
OPTION 67: /QIBM/ProdData/NetworkStation/me
SUBNET 9.100.57.0
IP ADDRESS: 9.100.57.100 - 9.100.57.140
Boot Strap Server: 9.100.48.75
OPTION 3: 9.100.57.253
OPTION 4: 9.100.48.75
OPTION 5: 9.100.25.252
OPTION 6: 9.100.25.252
OPTION 15: ibm.com
OPTION 67: /QIBM/ProdData/NetworkStation/altme
Note: The IP addresses shown do not denote currently available addresses but
indicate the addresses which belong to the pool.
3. If the specified request will not be processed because an appropriate definition
does not exist for the client in the machine file, the response will indicate this.
This example uses the same machine file as the previous SHOW ALL example.
In this example, address 9.200.55.55 does not correspond to any defined
address pool.
SHOW REQUEST ADDRESS 9.200.55.55
NO RESPONSE POSSIBLE
Usage Notes
v Addresses shown in the output of this command are possible IP addresses that
might be used. They do not indicate whether the address is available. It is
probable that many addresses may be currently leased out. To find the status of
an address or a set of addresses, use the STATUS subcommand. See “STATUS
Subcommand” for more information on the STATUS subcommand.
STATUS Subcommand
Use the STATUS subcommand to display the status of an IP address, Client, or
Subnet’s addresses.
STATUS
CLIent hwtype clientid
ADDress ipaddr
SUBnet ipaddr
Operands
CLIent
indicates that the two operands which follow specify a client ID. The status of
the IP address currently leased to the client should be shown.
hwtype
is the hardware type of the client computer, or 0. The valid client types are
defined in STD 2, RFC 1700.
hwtype
1
Client hardware
ethernet ether
Chapter 7. Configuring the DHCP Server
125
DHCP Server
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
ethernet3 ether3
ax.25
pronet
chaos
token-ring tr
arcnet
hyperchannel
lanstar
autonet
localtalk
localnet
ultra_link
smds
frame_relay
atm
ieee802
fddi
clientid
is the hexadecimal MAC address or a name which identifies the client. If a
name is specified then:
v hwtype must be 0
v If the name contains blanks, then it must be enclosed in single or double
quotes.
ADDress
indicates that the operand which follows is an IP address whose status should
be shown.
ipaddr
is an IP address specified in dotted-decimal notation.
SUBnet
indicates that the operand which follows is an IP address of a subnet. The
status of the IP addresses associated with the subnet should be shown.
Examples
1. If a specific address is being queried by either the CLIENT or ADDRESS
operand, then the following would be shown:
v If the address is available for reassignment:
STATUS ADDRESS 9.100.57.110
9.100.57.110
AVAILABLE
v If the lease for this address has expired, but the address is waiting to reenter
the available pool:
STATUS ADDRESS 9.100.57.111
9.100.57.111
EXPIRED. HELD UNTIL 23:59:00 ON 24 DECEMBER 1997
TO: 0 BEACH
v If an address is currently leased to a client:
STATUS ADDRESS 9.100.57.112
9.100.57.112
IN USE UNTIL 23:59:00 ON 24 DECEMBER 1997
TO: 0 STEVEGESSNER
v If an address is permanently leased to a client:
STATUS ADDRESS 9.100.57.113
9.100.57.113
IN USE PERMANENTLY
TO: 0 ADAMGESSNER
v If an address is being pinged before a DHCP response is sent:
126
z/VM: TCP/IP Planning and Customization
DHCP Server
STATUS ADDRESS 9.100.57.114
9.100.57.114
WAITING FOR ICMP REPLY BEFORE BEING OFFERED
TO: 0 PAULAGESSNER
v If an address is being offered to a client:
9.100.57.115
BEING OFFERED
TO: 0 MARK
v If an address was excluded or not specified in the machine file:
STATUS ADDRESS 9.100.57.100
9.100.57.110
EXCLUDED
2. If a pool of addresses is being queried, then the output will provide information
for each IP address that belongs to the pool, and which is not excluded. In the
following example, subnet 9.100.57.0 has 6 addresses defined from 110 to 115.
STATUS SUBNET 9.100.57.0
9.100.57.110
AVAILABLE
9.100.57.111
EXPIRED. HELD UNTIL 23:59:00 ON 24 DECEMBER 1997
TO: 0 BEACH
9.100.57.112
IN USE UNTIL 23:59:00 ON 24 DECEMBER 1997
TO: 0 STEVEGESSNER
9.100.57.113
IN USE PERMANENTLY
TO: 0 ADAMGESSNER
9.100.57.114
WAITING FOR ICMP REPLY BEFORE BEING OFFERED
TO: 0 PAULAGESSNER
9.100.57.115
BEING OFFERED
TO: 0 MARK
STAYUP Subcommand
Use the STAYUP subcommand to toggle the STAYUP mode in the DHCP daemon.
If the daemon is already operating in STAYUP mode, it will cease operating in this
mode and will end processing if a subsequent TCP/IP failure occurs. If the daemon
is not operating in STAYUP mode, it will begin to ensure processing will not end if a
subsequent TCP/IP failure occurs.
STAYUP
Examples
1. The following is displayed on completion of the subcommand:
STAYUP is now s
where s is 0 if STAYUP mode is off; 1 if STAYUP mode is on.
Usage Notes
v The STAYUP subcommand is needed only when the TCP/IP machine does not
contain an entry for the virtual machine running DHCPD.
STOP Subcommand
Use the STOP subcommand to stop the DHCP daemon. This subcommand is
equivalent to the EXIT and QUIT subcommands.
STOP
Chapter 7. Configuring the DHCP Server
127
DHCP Server
Operands
The STOP subcommand has no operands.
TRACE Subcommand
Use the TRACE subcommand to toggle the TRACE mode in the DHCP daemon. If
the daemon is already operating in TRACE mode, it will cease displaying debug
information as it processes requests. If the daemon is not operating in TRACE
mode, it will display debug information as it processes requests.
TRACE
Examples
1. The following is displayed on completion of this subcommand:
TRACE is now t
where t is 0 if TRACE mode is off; 1 if TRACE mode is on.
2. See TCP/IP Programmer’s Reference for a description of DHCP server trace
output.
128
z/VM: TCP/IP Planning and Customization
Chapter 8. Configuring the DNS Server
The Domain Name System (DNS) server — commonly referred to as simply a
name server — maps a host name to an internet address or an internet address to
a host name. To configure the DNS server virtual machine, you must perform the
following steps:
DNS Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the DNS server.
3. Determine the type of DNS server to configure. The section titled “DNS
Server Overview” may help in this determination.
v Configure a Caching-Only name server:
a. Customize the DNS server configuration file to include a
CACHINGONLY statement.
b. Identify one or more remote name servers using cache file resource
records.
v Configure a Primary name server:
a. Customize the DNS server configuration file to include PRIMARY
and SECONDARY statements.
b. Prepare the DB2 Server for VSE & VM database.
c. Define the DB2 database.
d. Define the appropriate resource records for your installation.
e. Create a MASTER DATA file.
f. Install the name server database.
Dynamic Server Operation
The DNS server provides a VM Special Message (SMSG) interface that allows you
to perform server administration tasks through a set of privileged commands. For
more information see “Dynamic Server Operation” on page 151.
DNS Server Overview
A Domain Name System (DNS) server maps a host name to an internet address or
an internet address to a host name. The domain name server (or more simply, the
name server) is like a telephone book that contains a person’s name, address, and
telephone number. For each host, the name server can maintain internet addresses,
nicknames, mailing information, and available well-known services (for example,
DNS, SMTP, FTP, or Telnet). This information is maintained through the use of
resource records.
When a client needs to communicate with another host, the client uses either the
internet address of the remote host or sends a query to the Domain Name System
(DNS) for host name resolution.
However, before the name server can resolve a query, it must be supplied with
resource records that either define a zone, or identify a different (remote) name
© Copyright IBM Corp. 1987, 2002
129
DNS Server
server that can provide the information required for a response. For information
about resource record format, see “Resource Records” on page 146.
Primary Versus Caching-Only Name Servers
If a name server maintains local data and has authority for the zone defined by this
data, it is called a primary name server. If a name server zone transfers a zone
from a remote primary name server, it is called a secondary name server. Once a
secondary name server receives zone data, it has authority for that zone. The
secondary name server then periodically refreshes this zone data based on values
defined in the zone’s authority record.
For more information about primary and secondary zones, see RFC 1034 and
1035.
A name server that does not have authority for any zone is called a caching-only
name server. To respond to queries, a caching-only name server must communicate
with a remote name server in the internet that has access to zone data.
The TCP/IP domain name server can be configured to run as a primary, secondary,
or caching-only server. Both primary and secondary name servers store zone data
in DB2 tables. To set up a name server that does not use DB2, configure the
domain name server as a caching-only name server. The caching-only name server
uses a CMS file to define the host names and internet addresses for the remote
name servers. For more information, see “CACHINGONLY Statement” on page 134.
The manner in which the name server operates is controlled by statements defined
in a DNS configuration file. This file is described in more detail in “DNS
Configuration File Statements” on page 134.
Host Name Resolution
TCP/IP applications have a resolver routine compiled into their code that resolves
host names into internet addresses. This code accesses a name server, site tables,
or both, depending on your configuration. You can change the configuration in the
TCPIP DATA file. For information about the TCPIP DATA file, see Chapter 3,
“Defining the TCP/IP System Parameters” on page 15.
The VM resolver accesses the site tables only in the following cases:
v You have not defined a name server in the TCPIP DATA file.
v The name server either does not respond, or the name server responds with an
unknown host error. The only exception is SMTP, which never uses the site tables
if it is configured to use a name server.
The VM name server has three main locations for retrieving data: cache memory, a
DB2 database, or other name servers.
The name server caches query answers in one of its four caches. All future queries
are answered directly from the cache without referencing the DB2 database or
another name server. Records remain active in the cache, based on the time-to-live
(TTL) field for each of the records. If a cache becomes full, the least recently used
entry is deleted, if it has been in the cache for the number of seconds specified
using the LRUTIME statement. For more information, see “LRUTIME Statement” on
page 137.
130
z/VM: TCP/IP Planning and Customization
DNS Server
If the name server has authority for the query’s zone, the name server consults its
DB2 database for the query answer. This answer is then sent back to the resolver
and cached for future queries.
The name server communicates with other name servers to query records outside
its zone, to answer queries about zones for which it has authority, and to transfer
zones both to and from other name servers. To contact other name servers, the
addresses of these name servers must be made available. This information is held
in a root cache file. The name of this file is supplied on the CACHINGONLY
statement or the ROOTCACHE statement in the name server configuration file. A
sample root cache file is supplied and is named NSMAIN SCACHE.
If this name server is behind a firewall, it may not be able to directly contact the
other name servers it would like to in order to process its questions. In that case, a
FORWARDERS statement can be used to define to this name server the addresses
of any firewall name servers or other name servers that can access name servers
outside the firewall.
Figure 1 on page 132 illustrates the domain name resolution process.
Chapter 8. Configuring the DNS Server
131
DNS Server
Figure 1. VM Domain Name Resolution
Step 1: Update PROFILE TCPIP
Include the DNS server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The DNS server is then automatically started when
TCPIP is initialized. The IBM default user ID for this server is NAMESRV. Verify that
the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
NAMESRV
0
The name server requires ports TCP 53 and UDP 53 to be reserved for it. Verify
that the following statements have been added to your TCPIP server configuration
file as well:
PORT
53 TCP NAMESRV
53 UDP NAMESRV
132
z/VM: TCP/IP Planning and Customization
;
;
DNS Server
DNS Server
DNS Server
Step 2: Update the DTCPARMS File
When the DNS server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the name server are:
:nick.NAMESRV
:PARMS.
:DB2_DATABASE.
If more customizing is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the name server if you:
v Use a configuration file other than NSMAIN DATA.
v Configure a primary name server and need to identify a DB2 database to
be referenced.
NSMAIN Command
DNS services are initiated using the NSMAIN command:
NSMAIN
NSMAIN
filename
DATA
filetype
A
filemode
Specify NSMAIN command operands as :Parms. tag start-up parameters in your
DTCPARMS file.
Operands
filename
The file name of the DNS server configuration file. The default file name is
NSMAIN.
filetype
The file type of the configuration file. The default file type is DATA.
filemode
The file mode of the configuration file. The default file mode is A.
Step 3: Customize the NSMAIN DATA File
The NSMAIN DATA configuration file, NSMAIN DATA, defines how the DNS server
is to operate. This file allows you to specify:
v Internet addresses
v Nicknames for fully qualified domain names
v Mailing information
v DB2 tables
v Trace options
Chapter 8. Configuring the DNS Server
133
DNS Server
See “DNS Configuration File Statements” for detailed information about how to
specify entries within this file. A sample DNS configuration file is provided as
NSMAIN DATA on the TCPMAINT 591 disk. Your customized DNS configuration file
should be copied to the TCPMAINT 198 minidisk and renamed to match what is
specified in the NSMAIN command (the default name is NSMAIN DATA).
DNS Configuration File Statements
This section describes the statements used to configure the Domain Name Server.
CACHINGONLY Statement
The CACHINGONLY statement specifies the name server is to operate in
caching-only mode. The file specified by this statement contains information (type
NS and A resource records) necessary to communicate with remote name servers.
These remote name servers are usually internet or intranet root name servers.
CACHINGONLY
NSMAIN
filename
CACHE
filetype
*
filemode
Operands
filename
The file name of the cache file that contains the resource records to be used.
filetype
The file type of the cache file.
filemode
The file mode of the cache file.
Examples
To use a cache file named MYCACHE DNSINFO, specify the following in the DNS
server configuration file:
CACHINGONLY MYCACHE DNSINFO
The content of the MYCACHE DNSINFO file might be:
EDU
TERP.UMD.EDU
.
C.NYSER.NET
608400 IN NS TERP.UMD.EDU
608400 IN A 128.8.10.90
608400 IN NS C.NYSER.NET
608400 IN A 192.33.4.12
In this example, queries for the EDU domain are sent to TERP.UMD.EDU (IP
address 128.8.10.90). All other queries initially go to the root server, C.NYSER.NET
(IP address 192.33.4.12).
Note: A sample cache file is provided on the TCPMAINT 591 disk as NSMAIN
SCACHE. If needed, this file should be copied to the TCPMAINT 198
minidisk, customized, and renamed to match the file name and type
134
z/VM: TCP/IP Planning and Customization
DNS Server
specified by the CACHINGONLY statement in the DNS server configuration
file (the provided NSMAIN SDATA sample specifies NSMAIN CACHE).
Usage Notes
1. You must create the cache file named by the CACHINGONLY statement, and
add the information required for the caching-only name server to communicate
with the root name server(s). The information in this file a combination of name
server (type NS) resource records and their corresponding (type A) IP address
resource records.
2. Record types other than NS and A, such as MX or CNAME, should not be
specified in the cache file. If such records are present, they will be ignored.
3. If your data resides in a DB2 table, this statement should not be used. Instead,
use the ROOTCACHE statement to provide root name server data when the
name server is operating as a PRIMARY or SECONDARY name server.
4. If you have either PRIMARY or SECONDARY statements in the configuration
file, as well as a CACHINGONLY statement, the name server will not start.
5. The time to live (TTL) field of resource records specified in the cache file is
ignored when these records are processed.
6. For more information about resource records, see the TCP/IP User’s Guide or a
suitable Domain Name System reference.
7. When the caching-only name server receives a query, it will look for a response
in its cache. If found, that response is returned to the client requestor. If not
found, the query will be forwarded, as needed, to a remote name server listed in
the cache file.
When a query response arrives at the caching-only name server, it is cached
and returned to the client. This response will remain in the cache for as long as
the time-to-live (TTL) field in the response dictates.
CHECKORIGIN Statement
Some resolvers incorrectly implement search lists (see note below) causing a
duplicate domain origin to be appended to the query name. The CHECKORIGIN
statement causes the name server to check the query name for a duplicate of the
last label. This option was created for the instances when the Name Server is being
bombarded with these queries. The statement is supplied as a single token in the
name server configuration file that is processed by the NSMAIN command (default
name: NSMAIN Data). The CHECKORIGIN statement has no parameters. No
duplicate checking is performed if CHECKORIGIN does not appear in the file.
CHECKORIGIN
Note: A description of search lists can be found in RFC 1123, section 6 1.4.3.
DATABASEQUERYCACHE Statement
The DATABASEQUERYCACHE statement is no longer used. If it is present in the
configuration file, it is ignored.
DOMAINNAMEPORT Statement
The DOMAINNAMEPORT statement changes the port number that the name server
uses. This parameter should be changed only for debugging purposes.
Chapter 8. Configuring the DNS Server
135
DNS Server
DOMAINNAMEPORT 53
DOMAINNAMEPORT port_number
Operands
port_number
An integer in the range of 1 through 65 535 that specifies the port number that
the name server uses for all TCP and UDP communications. The default port
number is 53.
FORWARDERS Statement
Use the FORWARDERS statement when the name server is behind a firewall that
prevents the name server from contacting other name servers. This statement
directs the name server to send any question that it can’t answer to the name
server(s) at the IP address(es) specified. These name servers should be recursive.
FORWARDERS internet_address
Operands
internet_address
Specifies the internet address of a remote name server that should handle
questions when this name server doesn’t know the answer. This could be a
nearby recursive name server or a firewall name server. If multiple name
servers can be specified, there will be less chance of failure should one of the
name servers not be available.
HOSTNAMECASE Statement
The HOSTNAMECASE statement defines the case to which the host names in all
queries are translated in order to match the contents of the name server DB2
database. The contents of the DB2 Server for VSE & VM database are assumed to
be in the case specified by this statement. If they are not, the name server will not
operate correctly.
Note: This statement pertains only to DB2 database queries.
HOSTNAMECASE
UPPER
LOWER
Operands
UPPER
Specifies that the data in the DB2 database is in UPPER case.
136
z/VM: TCP/IP Planning and Customization
DNS Server
LOWER
Specifies that the data in the DB2 database is in LOWER case.
INTERMEDIARYQUERYCACHE Statement
The INTERMEDIARYQUERYCACHE statement is no longer used. If it is present in
the configuration file, it is ignored.
INVERSEQUERYCACHE Statement
The INVERSEQUERYCACHE statement is no longer used. If it is present in the
configuration file, it is ignored.
LRUTIME Statement
The LRUTIME statement specifies the amount of time a record must be in the
cache before it can be replaced by a new cache entry.
The name server uses a least recently used (LRU) algorithm to replace entries in a
full cache.
LRUTIME 300
LRUTIME seconds
Operands
seconds
The number of seconds after which cache entries should be replaced. The
default time is 300 seconds (5 minutes).
MSGNOH Statement
The MSGNOH statement specifies that the name server use the CP MSGNOH
command to reply to an SMSG command. Otherwise, the name server uses the CP
MSG command.
Note: The CP MSGNOH command is a privileged command. Ensure that your
name server is authorized to issue this command if you are using the MSGNOH
statement.
MSGNOH
The MSGNOH statement has no operands.
NEGATIVECACHING Statement
The NEGATIVECACHING statement specifies that the VM name server caches
negative queries.
Negative caching prevents the name server from repeatedly searching for
nonexistent resource records. The VM name server caches queries that do not
contain answers, but have an SOA resource record in the additional section. The
query response remains in the cache for the time specified in the minimum
Chapter 8. Configuring the DNS Server
137
DNS Server
time-to-live (TTL) field of the SOA record. Subsequent queries for the same entry
return the negative query response from the cache.
NEGATIVECACHING
Operands
The NEGATIVECACHING statement has no operands.
NORECURSION Statement
The NORECURSION statement forces the name server to respond with either the
query answer (if available) or with the remote name server host name and the
corresponding internet address.
Normally, the name server does recursion by querying remote name servers for
information outside the local domain.
NORECURSION
Operands
The NORECURSION statement has no operands.
PRIMARY Statement
The PRIMARY statement identifies a local zone for which the name server is
responsible, as well as the name of a DB2 table where data about this zone is
maintained.
PRIMARY zone_name SQLbasetable
Operands
zone_name
The name of the local zone.
SQLbasetable
The name of the DB2 base table where zone data is maintained.
When declaring PRIMARY statements, you must establish separate SQL tables for
a parent domain (for example, ibm.com) and its subdomains (for example,
watson.ibm.com). Multiple subdomains can exist in the same table, as long as none
of their own subdomains are contained within that table. Violating this rule may
result in zone transfer errors.
To define authoritative tables for different local servers, each SQL base table must
be unique. You would add lines to the name server initialization file as follows:
PRIMARY ibm.com
PRIMARY watson.ibm.com
PRIMARY endicott.ibm.com
138
z/VM: TCP/IP Planning and Customization
ibm
watson
endicott
DNS Server
These statements create two different tables for each of the three SQL base tables
(ibm0, ibm1, watson0, watson1, endicott0, and endicott1).
To define multiple domains in the same SQL base table, you would add the
following lines to the name server initialization file:
PRIMARY ibm.com
PRIMARY watson.ibm.com
PRIMARY endicott.ibm.com
ibm
otheribm
otheribm
This establishes four tables (ibm0, ibm1, otheribm0, and otheribm1), with the latter
two domains both defined in the second pair. The parent domain is placed in a
separate SQL base table to prevent zone transfer errors.
Before starting a name server that uses the PRIMARY statement, you must execute
the NSTABLE MODULE, with the file name and file type of the DNS server
configuration file specified as parameters.
The NSTABLE MODULE creates two tables in the name server’s dbspace using the
SQLbasetable specified in the PRIMARY statement. The name server switches
between the two tables. Queries are answered from one table until an SMSG
FLIPTABLE command is received. For more information, see “SMSG FLIPTABLE
Command” on page 152. At this point, the table name in the remark statement of
the system.syscatalog is updated. The name server must be able to process
queries from the old zone until the new zone is completely updated.
Also, before starting a name server that uses the PRIMARY statement, you must
load the tables with data. The recommended way to do this is to use the
NSDBLOAD MODULE.
ROOTCACHE Statement
The ROOTCACHE statement specifies the name of the file that contains information
(type NS and A resource records) necessary to communicate with remote name
servers. These remote name servers are usually internet or intranet root name
servers.
ROOTCACHE
NSMAIN
filename
CACHE
filetype
*
filemode
Operands
filename
Specifies the file name of the cache file that contains the resource records to be
used.
filetype
Specifies the file type of the cache file.
filemode
Specifies the file mode of the cache file.
Chapter 8. Configuring the DNS Server
139
DNS Server
Examples: To use a cache file named MYCACHE DNSINFO, specify the following
in the DNS server configuration file:
ROOTCACHE MYCACHE DNSINFO
The content of the MYCACHE DNSINFO file might be:
EDU
TERP.UMD.EDU
.
C.NYSER.NET
608400 IN NS TERP.UMD.EDU
608400 IN A 128.8.10.90
608400 IN NS C.NYSER.NET
608400 IN A 192.33.4.12
In this example, queries for the EDU domain are sent to TERP.UMD.EDU (IP
address 128.8.10.90). All other queries initially go to the root server, C.NYSER.NET
(IP address 192.33.4.12).
Note: A sample cache file is provided on the TCPMAINT 591 disk as NSMAIN
SCACHE. If needed, this file should be copied to the TCPMAINT 198
minidisk, customized, and renamed to match the file name and type
specified by the ROOTCACHE statement in the DNS server configuration file
(the NSMAIN SDATA sample provided specifies NSMAIN CACHE).
Usage Notes
1. You must create the cache file named by the ROOTCACHE statement, and add
the information required for the only name server to communicate with the root
name server(s). The information in this file a combination of name server (type
NS) resource records and their corresponding IP (type A) address resource
records.
2. Record types other than NS and A, such as MX or CNAME, should not be
specified in the cache file. If such records are present, they will be ignored.
3. The time to live (TTL) field of resource records specified in the cache file is
ignored when these records are processed.
4. For more information about resource records, see the TCP/IP User’s Guide or a
suitable Domain Name System reference.
5. When the name server receives a query, it will look for a response in its cache.
If found, that response is returned to the client requestor. If not found, the query
will be forwarded, as needed, to a remote name server. If the name server has
no better idea who to ask for an answer, it will use a name server listed in the
cache file.
When a query response is returned to the name server, it is cached and
returned to the client. This response will remain in the cache for as long as the
time-to-live (TTL) field in the response dictates.
SECONDARY Statement
The SECONDARY statement identifies a zone for which information will be
transferred from a remote location, as well as the name of a DB2 table where this
zone data is maintained.
SECONDARY zone_name SQLbasetable internet_address
Operands
zone_name
The name of the zone to transfer.
140
z/VM: TCP/IP Planning and Customization
DNS Server
SQLbasetable
The name of the DB2 base table where transferred zone data is maintained.
internet_address
The internet address of the remote name server from which zone data is
transferred.
For example, to zone transfer the raleigh.ibm.com and phoenix.ibm.com zones, the
following lines are added to the DNS server configuration file:
SECONDARY raleigh.ibm.com
SECONDARY phoenix.ibm.com
raleigh
phoenix
9.67.43.126
9.4.1.2
Before starting a name server that uses the SECONDARY statement, you must
execute NSTABLE MODULE, with the file name and file type of the DNS server
configuration file as parameters.
The NSTABLE MODULE creates two tables in the name server’s dbspace using the
SQLbasetable specified in the SECONDARY statement. The name server switches
between the two tables. Queries are answered from one table until a new zone is
completely received in the other table. At this point, the table name in the remark
statement of the system.syscatalog is updated. The name server must be able to
process queries from the old zone until the new zone is completely received.
The table specified in a SECONDARY statement is loaded by the name server, via
the network, from the name server at the address specified by the internet_address.
SMSGUSERFILE Statement
The SMSGUSERFILE statement specifies the name of an exec used to verify
whether a user ID is authorized for a particular name server SMSG command. The
authorization exec is passed the following arguments, in order:
v the node ID of the system from which the SMSG command originated
v the user ID that issued the SMSG command
v the SMSG command
Although the authorization exec has a node parameter, there is currently no support
for SMSG command processing from remote nodes. The parameter exists to
maintain interface compatibility across releases.
The authorization exec, if used, must return a value of 0 if the user is allowed to
perform the SMSG command, and should return a 1 if the user is not to be allowed
to perform the command. The HELP, LIST, and STATS commands are commonly
accepted as the only SMSG commands that are not privileged. For information
about SMSG commands, see “SMSG Interface to the DNS Server” on page 151.
SMSGUSERFILE
VALIDUSR
filename
Operands
filename
The file name of the verification exec. The first exec of this name found in the
CMS search order is used. The default file name is VALIDUSR.
Chapter 8. Configuring the DNS Server
141
DNS Server
A sample verification file is shipped as VALIDUSR SEXEC on the TCPMAINT 591
disk. If needed, this file should be copied to the TCPMAINT 198 disk, customized,
and renamed to match what is specified in the DNS server configuration file. (The
provided NSMAIN SDATA sample specifies VALIDUSR).
Usage Notes
1. If the SMSGUSERFILE statement is omitted, SMSG authorization will still be
attempted, using the VALIDUSR default.
2. The authorization exec can be changed while the name server is running. The
name server refreshes its access to all file modes before it calls the
authorization exec. It will have access to any updates made to the file.
3. If no SMSG authorization exec exists, all SMSG command requests will be
rejected. In this case the following message will be displayed on the name
server console for each SMSG request:
DMSEXT072E Error in EXEC file VALIDUSR, line 0 - not found
4. Prior to customizing the user verification exit described in this section, ensure
that you have reviewed the exit limitations and customization recommendations
presented in “Customizing Server-specific Exits” on page 43.
|
|
|
STANDARDQUERYCACHE Statement
The STANDARDQUERYCACHE statement allows the specification of the number of
standard queries and answers to be managed by the cache.
The query and the resulting answer are stored in a cache. Query answers that are
cached do not access the DB2 database and are not sent to remote name servers.
This results in faster responses to the client.
STANDARDQUERYCACHE 3000
STANDARDQUERYCACHE queries
Operands
queries
An integer value that represents the number of standard queries and answers
to be managed by the cache. The default is 3000. A cache size of 1000 to 5000
entries is recommended to improve performance. The cache size is dynamically
reduced if the server runs low on memory.
TRACE Statement
The TRACE statement establishes the set of trace categories for internal name
server tracing. Name server trace output is displayed on the name server console.
Most of the trace categories are for special diagnostic situations. The [NO] form of
the trace category turns that specific trace category off. Thus, specifying TRACE
ALL NOSUB NOSTOR NOMORE would enable all trace categories except storage
and subroutine tracing, and would disable the trace points that require the MORE
trace category.
142
z/VM: TCP/IP Planning and Customization
DNS Server
TRACE ALL
END
[NO]AUth
[NO]CAche
[NO]DBG
[NO]DBG2
[NO]INit
[NO]IUcv
[NO]MOre
[NO]NOtice
[NO]PArms
[NO]PKTIn
[NO]PKTOut
[NO]QUeue
[NO]SQl
[NO]STorage
[NO]SUbroutines
[NO]TCp
[NO]TYpe
[NO]UDp
[NO]UTl
[NO]ZOne
Operands
ALL
All trace categories are enabled. This results in extensive console tracing.
END
All trace categories are disabled.
AUth
NOAUth
Enables or disables console tracing of authority determination.
CAche
NOCAche
Enables or disables console tracing of caching activities.
DBG
NODBG
Enables or disables console tracing in special diagnostic circumstances.
DBG2
NODBG2
Enables or disables console tracing in special diagnostic circumstances.
INit
NOINit
Enables or disables console tracing of initialization activities.
IUcv
NOIUcv
Enables or disables console tracing of IUCV activity.
MOre
Chapter 8. Configuring the DNS Server
143
DNS Server
NOMOre
Enables or disables additional trace points that are normally skipped because of
the large amount of trace data displayed.
NOtice
NONOtice
Enables or disables console tracing of TCP/IP message notifications.
PArms
NOPArms
Enables or disables console tracing of input parameters to most subroutines.
PKTIn
NOPKTIn
Enables or disables console tracing of most inbound DNS messages received.
PKTOut
NOPKTOut
Enables or disables console tracing of most inbound DNS messages sent to
other hosts.
QUeue
NOQUeue
Enables or disables console tracing of questions asked of this name server and
questions and answers related to those questions.
SQl
NOSQl
Enables or disables console tracing of various activities involving the DB2
database.
STorage
NOSTorage
Enables or disables console tracing of storage usage.
SUbroutines
NOSUbroutines
Enables or disables console tracing of each subroutine executed. Some utility
subroutines are instead traced with the UTl trace.
STorage
NOSTorage
Enables or disables console tracing of storage usage.
TCp
NOTCp
Enables or disables console tracing of activities using the TCP protocol.
UDp
NOUDp
Enables or disables console tracing of activities using the UDP protocol.
UTl
NOUTl
Enables or disables console tracing of input parameters to and results from
many utility subroutines.
ZOne
NOZOne
Enables or disables console tracing of zone transfer requests, and zone
transferring of local zones.
144
z/VM: TCP/IP Planning and Customization
DNS Server
UDPONLY Statement
The UDPONLY statement instructs the name server to perform recursive name
resolution to remote name servers using only the UDP protocol. Without this
statement, the name server attempts to communicate with remote name servers
using UDP, and if that fails, it tries again using the TCP protocol. The use of
UDPONLY is not recommended.
UDPONLY
Operands
The UDPONLY statement has no operands.
UDPRETRYINTERVAL Statement
The UDPRETRYINTERVAL statement instructs the name server to wait a specified
amount of time before attempting to communicate with another authoritative name
server.
The name server attempts to communicate with remote name servers using UDP. If
a remote name server fails to respond, the name server attempts to communicate
with another remote name server.
UDPRETRYINTERVAL 5
UDPRETRYINTERVAL seconds
Operands
seconds
The number of seconds to wait before sending the query to the next remote
name server. The default is 5 seconds.
Prepare the DB2 Database
The NSPREP EXEC has been included to prepare your DB2 database for the new
name server. This EXEC allows access to the DB2 database by the name server
programs, which have been written using the SQL/DS Version 3 Release 5, or DB2
Server for VSE & VM Version 5 Release 1 C language interface.
NSPREP
NSPREP preprocesses the following source files (with file types CSQL or ASMSQL)
into your DB2 database.
File
Description
NSACQ
Acquires a database space (dbspace). The default number of pages
is 5120.
NSTABLE
Creates two tables for each primary and secondary domain defined
in the initialization file.
Chapter 8. Configuring the DNS Server
145
DNS Server
NSDBLOAD
Creates resource records defining a domain from a master file. The
resource records are then inserted into a DB2 table.
NSDBSQL
Contains a subroutine of the NSMAIN MODULE. It uses the
assembler DB2 interface. (This file type is ASMSQL.)
NSPREP also pre-processes the NSAXSUB1, NSINSERT, and NSSQL files.
Invoke NSPREP within the DNS server virtual machine.
Define the DB2 Database
The name server’s DB2 database should be defined with the help of the DB2
database administrator. The DB2 Server for VSE & VM database administrator must
acquire a dbspace for the name server by executing the NSACQ MODULE.
Note: DB2 Version 3 Release 5, or DB2 Server for VSE & VM Version 5 Release 1
or later, is required if you are using a DB2 database.
The types of SQL commands that the name server generates for each query type
are:
Query Type
Command
Standard
SELECT * FROM sqltable WHERE TYPE=? AND CLASS=? - AND
NAME=?
Inverse
SELECT NAME, TTL FROM sqltable WHERE TYPE=? AND CLASS=? AND RDATA=?
Database
SELECT RDATA FROM sqltable WHERE TYPE=? AND - NAME=?
Database Update
UPDATE sqltable SET RDATA=? WHERE TYPE=? AND - NAME=?
Note: Completion queries are no longer supported.
Resource Records
After setting up the database as described in “Define the DB2 Database”, you must
load the data into the SQL table. These data entries are called resource records.
NSDBLOAD MODULE can assist you in inserting the data into the table. The
following is the format of a resource record that is used as input for the NSDBLOAD
MODULE.
name
ttl
class
recordtype recorddata
Operands
name
The location in the dbspace for the resource record, such as the owner. If a
resource record line starts with a blank, it is loaded into the location specified
by the most recent location specifier. The location specifier is relative to an
origin provided on the $ORIGIN record.
ttl
146
The time-to-live (TTL) field, which is optional. This field is expressed as a
z/VM: TCP/IP Planning and Customization
DNS Server
decimal number. If it is omitted, the ttl default value is specified in the Start of
Authority (SOA) record. TTL specifies, in seconds, how long the data remains in
the cache.
class
The class of the data.
recordtype
The type of the data. This field describes the kind of data that exists in the next
field, recorddata.
The following record types are recognized:
A
Address
NS
Name Server
CNAME
Canonical Name (nickname, alias)
SOA
Start of Authority
WKS
Well Known Services
PRT
Domain Name Pointer
HINFO
Host Information
MINFO
Mailbox Information
MX
Mail Exchanger
TYPE97
Database Update Authority
TXT
Text String
recorddata
Depends on the values of the resource record class and type. The fields that
make up the record data, are usually expressed as decimal numbers or as
domain names.
Create a MASTER DATA File
MASTER DATA files are text files that contain resource records in text form. For
more information about resource records, see “Resource Records” on page 146.
MASTER DATA files, stored on TCPMAINT 198, are used to define a zone because
the contents of a zone can be expressed as a list of resource records. MASTER
DATA files can also be used to list the contents of a cache.
The format of these files is a sequence of entries. Entries are line-oriented, but you
can use parentheses to continue a list across a line boundary, and text literals can
contain Carriage Return Line Feeds (CRLF) within the text. You can use any
combination of tabs and spaces as a delimiter between the items that make up an
entry. You can end any line with a comment. The comment starts with a semicolon
(;). You can use blank lines, with or without comments, anywhere in the file.
Two control entries are defined:
Entry
Definition
$ORIGIN
Followed by a domain name, and resets the current origin for
relative domain names to the stated name.
$INCLUDE
Inserts the named file into the current file, and can specify a
domain name that sets the relative domain name origin for the
included file. The use of $INCLUDE is optional.
For a complete description of master files, see RFC 1034 and RFC 1035.
Some characters have special meanings:
Character
Description
Chapter 8. Configuring the DNS Server
147
DNS Server
@
A free-standing @ denotes the current origin.
v
One free-standing dot represents the null domain name of the root.
\X
X is any character other than a digit. Use \X to quote this character
so that its special meaning does not apply, as in a mail box
specification, or an SOA record. For example, you can use a
backslash followed by a dot (\.) to place a dot character in a label.
()
Parentheses group the data that crosses a line. Line terminations
are not recognized within parentheses.
;
A semicolon begins a comment. The remainder of the line is
ignored.
Each zone must contain an SOA and NS resource record. The following is an
example of a master domain file:
;The following $ORIGIN record will be (IBM.COM.) appended to any
;name that does not end in a dot until the next $ORIGIN record.
;************************************************************************
;
Authoritative for Domain IBM.COM
;************************************************************************
$origin IBM.COM.
; THE ORIGIN FOR ALL NAMES
ibm.com. IN SOA yktvmx.watson.ibm.com. zohar.yktvmx.watson.ibm.com. (
091690
;serial number for data
21600
;refresh value for secondary NS (in secs)
3600
;retry value for secondary NS (in secs)
360000
;expire data when refresh not available (secs)
86400 )
;minimum time to live value (secs)
ibm.com. IN
NS
yktvmx.watson.ibm.com.
ibm.com. IN
NS
aides.watson.ibm.com.
ibm.com. IN
NS
vmn.almaden.ibm.com.
$include ibm data a
;File contain hosts addresses
The following is an example of an IBM data file:
raleigh.ibm.com.
ralvmm.raleigh.ibm.com.
;
watson.ibm.com.
yktvmx.watson.ibm.com.
IN
IN
NS
A
ralvmm.raleigh.ibm.com.
9.67.43.126
IN
IN
NS
A
yktvmx.watson.ibm.com.
129.34.128.246
The DNS defines a special domain called in-addr.arpa to translate internet
addresses to domain names. An in-addr.arpa name is composed of the reverse
octet order of an IP address concatenated with the in-addr.arpa string.
Install the Name Server Database
At this point, your DB2 database virtual machine has been created. To acquire a
dbspace in the database, log on to the name server virtual machine, and execute
the NSACQ MODULE. The NSACQ MODULE issues the SQL ACQUIRE DBSPACE
command. The name server must have the authority granted to execute the
NSACQ command. The authority can be acquired by granting the name server
Database Administrator (DBA) authority.
NSACQ
148
TCPDBA
dbname
z/VM: TCP/IP Planning and Customization
TCPSPACE
dbspace
5120
npages
DNS Server
Operands
dbname
The name of the DB2 database set up for the name server by the database
administrator. The default is TCPDBA.
dbspace
The name of the database space set up for the name server. The default is
TCPSPACE.
npages
The size of the database machine. For example, you can choose 128, 256,
512, 1024, 2048, 5120, or 12 800. The default is 5120.
Insert Data in the Database
You must insert the resource records that define a zone into separate DB2 tables.
To update a zone without shutting down the name server, you need two tables for
each zone. Each of these tables contains the following fields:
NAME
CLASS
TYPE
TTL
RDATA
varchar (150)
smallint
smallint
integer
varchar (250)
For each primary zone, add a line to the name server configuration file containing
the zone origin and base name (17 characters maximum) of the DB2 table. For
each secondary zone, add a line to the name server configuration file containing the
zone origin, the base name of the DB2 table to use, and the internet address of the
remote name server. For example:
primary
secondary
watson.ibm.com.
raleigh.ibm.com.
watson
raleigh
9.67.43.100
After defining the primary and secondary zones in the configuration file, executing
NSTABLE creates two DB2 tables by appending a 0 and 1 to the base name for
each primary and secondary zone defined. The following tables are defined for the
previous example:
watson0 watson1 raleigh0 raleigh1
NSTABLE
NSMAIN
filename
DATA
filetype
A
filemode
Operands
filename
The file name of the DNS server configuration file that includes the PRIMARY
and SECONDARY statements which identify the DB2 base table names that
NSTABLE should construct. The default file name is NSMAIN.
filetype
The file type of the name server configuration file. The default file type is DATA.
Chapter 8. Configuring the DNS Server
149
DNS Server
filemode
The file mode of the name server configuration file. The default file mode is A.
When your database table is constructed, use the NSDBLOAD MODULE to load
your database. NSDBLOAD reads the master data file you specify and creates a
CMS file. The CMS file is read and the entries are loaded into the database.
After the name server is configured and running, you can use NSDBLOAD from
another user to update the database. This user should have DB2 authority and be
able to access the name server tables.
Once the tables are loaded from this user, an SMSG FLIPTABLE command can be
issued to make the name server switch to the updated table. This eliminates the
need to shutdown the name server for updates.
NSDBLOAD
SQLtablename
NSMAIN
output_filename
MASTER
input_filename
DATA
input_filetype
A
input_filemode
HOSTINFO
output_filetype
A
output_filemode
Operands
SQLtablename
The name of the DB2 table. If you use the base name for the table,
NSDBLOAD will attempt to determine which table the name server is currently
using and update the other table. If it cannot determine which table is in use, it
will update the table that ends with a zero (0)— (for example, watson0 or
raleigh0). You can use the full table name (for example, watson0, raleigh1)
and that table will be updated.
input_filename
The file name of the master data file written in resource record format. The
default file name is MASTER.
input_filetype
The file type of the master data file. The default file type is DATA.
input_filemode
The file mode of the master data file. The default file mode is A.
output_filename
The file name of the master data file. The default file name is NSMAIN.
output_filetype
The file type of the master data file. The default file type is HOSTINFO.
output_filemode
The file mode of the master data file. The default file mode is A.
150
z/VM: TCP/IP Planning and Customization
DNS Server
Dynamic Server Operation
The VM Special Message Facility (SMSG) command provides an interactive
interface to the DNS server to:
v obtain information about the name server
v diagnose name server problems using trace facilities
v purge cache entries
v change DB2 for VM tables
v close the name server console log.
See the “SMSGUSERFILE Statement” on page 141 for information on controlling
authorization to issue SMSG commands to the name server.
SMSG Interface to the DNS Server
The various SMSG commands and operands supported by the name server are
presented throughout the remainder of this section.
SMSG CLOSECON Command
The SMSG CLOSECON command causes the name server virtual machine to issue
the command CP SPOOL CONSOLE CLOSE. The name server console is spooled to the
owner identified in the DTCPARMS file.
SMSG server_id CLosecon
Operands
server_id
The user ID of the name server virtual machine.
SMSG COMMIT Command
The SMSG COMMIT command forces a commit of all DB2 transactions and
releases the link to SQL.
SMSG server_id COmmit
Operands
server_id
The user ID of the name server virtual machine.
SMSG DUMP Command
The SMSG DUMP command has been replaced by the SMSG STORAGE
command. The SMSG DUMP command may be removed in a future release. It will
accept the parameters of the SMSG STORAGE command and behave like the
SMSG STORAGE command. This behavior is different than the behavior of the old
SMSG DUMP command.
Chapter 8. Configuring the DNS Server
151
DNS Server
SMSG FLIPTABLE Command
The SMSG FLIPTABLE command informs the name server that new zone data
appears in a DB2 table. Two DB2 tables are defined for each primary zone.
NSDBLOAD can change the zone data in the DB2 table that the name server is not
using. After the new data is in the DB2 table, you can issue an SMSG FLIPTABLE
command to force the name server to use the updated DB2 table.
SMSG server_id FLiptable tablename
Operands
server_id
The user ID of the name server virtual machine.
tablename
The name of the table to flip. This is the base table name, and not the DB2
table name for example, (watson, not watson0 or watson1).
SMSG HELP Command
The SMSG HELP command lists the SMSG commands supported by the name
server.
SMSG server_id HElp
Operands
server_id
The user ID of the name server virtual machine.
SMSG HINTS Command
The SMSG HINTS command allows you to display the addresses of the name
servers that this name server will use when it does not know the answer to a
question. The data comes from the FORWARDERS statement, if one is present in
the configuration file. If a FORWARDERS statement is not present, the data comes
from the contents of the file specified in the CACHINGONLY or ROOTCACHE
statement.
SMSG server_id HInts
Short
Long
Operands
server_id
The user ID of the name server virtual machine.
Short
Indicates that only the IP addresses of the remote name servers are to be
displayed.
152
z/VM: TCP/IP Planning and Customization
DNS Server
Long
Indicates the IP addresses and the names of the remote name servers are to
be displayed.
Usage Notes
1. If a FORWARDERS statement from the configuration file is in effect, all
parameters on the SMSG HINTS command are ignored and only the IP
addresses of the remote name servers will be displayed.
SMSG LEVEL Command
The SMSG LEVEL command allows you to display the service level of the name
server and its component parts. The overall service level is provided in the
response. The component part service information is directed to the name server
console, and it can be obtained using the SMSG CLOSECON command. Output
from a LISTFILE NSMAIN * * command is also included. This can be used to obtain
the date and time of the NSMAIN MODULE in use and to ensure you are executing
the intend level. If default configuration file names (NSMAIN DATA, NSMAIN
CACHE) are in use, these will also be displayed by the LISTFILE command.
SMSG server_id LEvel
Operands
server_id
The user ID of the name server virtual machine.
For example, if you enter SMSG NAMESRV LEVEL, the following information is
displayed.
SMSG NAMESRV LEVEL
VM TCP/IP Name Server Level nnn, service level PQ12345
SMSG LIST Command
The SMSG LIST command allows you to display the contents of the current name
server caches.
SMSG server_id LIst
STandard
NScache
INverse
DBase
ALL
Operands
server_id
The user ID of the name server virtual machine.
Chapter 8. Configuring the DNS Server
153
DNS Server
NScache
This cache is no longer used. This operand is now ignored, but is accepted to
maintain compatibility with prior levels of TCP/IP for VM.
STandard
Lists the contents of the standard cache. This is the default. This operand is
now ignored, but is accepted to maintain compatibility with prior levels of
TCP/IP for VM.
INverse
This cache is no longer used. This operand is now ignored, but is accepted to
maintain compatibility with prior levels of TCP/IP for VM.
DBase
This cache is no longer used. This operand is now ignored, but is accepted to
maintain compatibility with prior levels of TCP/IP for VM.
ALL
Lists the contents of all caches. Because the standard query cache is the only
cache used, the parameter is equivalent to specifying STANDARD.
For example, if you enter SMSG NAMESRV LIST ALL, the following information is
displayed:
---------------------------------------------------Type Class Used Orig.TTL Rem.TTL Entry
Using standard query cache
A
IN
0 136347 130364 image.eimg.com
A
IN
0
86400
86235 -open
A
IN
0
86400
85244 -LOBO
A
IN
0
43200
42089 [email protected]
PTR IN
3
85802
57746 3.9.244.9.in-addr.arpa
PTR IN
6
58298
56641 3.240.139.9.in-addr.arpa
A
IN
0
13056
6760 cnbcads.cnbc.com
A
IN
0
53561
43990 c.realtor.com
A
IN
6 9999999 9756054 dukhat.torolab.ibm.com
A
IN
1
21600
13120 -DS.INTERNIC.NET.ENDICOTT.IBM.COM
The following is a description of the fields that appear in the LIST command
response:
Type
The resource record type.
Class
The resource record class.
Used
The number of times the record was returned from the cache.
Orig.TTL
The original value of the time-to-live field.
Rem.TTL
The remaining time that the record remains in the queue
Entry
The resource record name. Entries that are preceded by a negative sign (-) are
cached negative queries. Negative entries indicate that the entity does not exist.
If a query comes in for that entity, we will not forward the question to the name
server for that domain, but will respond indicating that the entity does not exist.
Negative entries are generated only when the NEGATIVECACHING statement
154
z/VM: TCP/IP Planning and Customization
DNS Server
has been specified in the configuration file. For more information, see
“NEGATIVECACHING Statement” on page 137.
SMSG PURGE Command
The SMSG PURGE command purges one or all entries from all maintained caches.
SMSG server_id PUrge
entry_name
ALL
Operands
server_id
The user ID of the name server virtual machine.
entry_name
A specific cache entry for which all occurrences should be purged from all
caches.
ALL
Purges the contents of all caches.
SMSG REFRESH Command
The SMSG REFRESH command instructs the name server to immediately refresh
the zone data contained in a DB2 table. This is used for a table for which the name
server is acting as a secondary name server. It will cause the name server to
attempt to contact the name server at the IP address specified on its associated
SECONDARY configuration statement and reload the table with the zone data from
that name server. It is useful when it is discovered that the primary name server
has been updated and the data at our name server is obsolete.
SMSG server_id REfresh
zone_name
ALL
Operands
server_id
The user ID of the name server virtual machine.
zone_name
The name of the zone (ibm.com, to take an example from the sample
configuration file) that should be refreshed. The zone_name must match the
zone_name from a SECONDARY statement to have any effect. If the
zone_name is not valid, no error message will be issued, but the command will
not have any effect.
ALL
Causes the name server to refresh all zones for which it is acting as a
secondary name server.
Chapter 8. Configuring the DNS Server
155
DNS Server
SMSG STATS Command
The SMSG STATS command returns useful information about the name server,
such as start time, number of queries received, and size of cache.
SMSG server_id STAts
Operands
server_id
The user ID of the name server virtual machine.
For example, if you enter SMSG NAMESRV STATS, the following information is
displayed.
SMSG NAMESRV STATS
NS start time:
Mon Oct 1 06:30:16
---------------------------------------------------Total number of queries: 1632
Answers from cache:
435
(27%)
Size of cache:
150 used: 6
SMSG STORAGE Command
The SMSG STORAGE command dumps the internal storage management chain to
the name server console. The data can then be recovered using the SMSG
CLOSECON command.
SMSG server_id STorage Dump
Operands
server_id
The user ID of the name server virtual machine.
Dump
Causes the internal storage management chain to be displayed on the name
server console. If the Dump keyword is missing, no action is taken.
SMSG TRACE Command
The SMSG TRACE command starts or stops server tracing. The [NO] form of a
trace category turns that specific trace category off.
Tracing is used primarily for problem diagnosis. The output from QUEUE tracing
can also be useful in monitoring what hosts are using your name server and what
other hosts they are attempting to access.
156
z/VM: TCP/IP Planning and Customization
DNS Server
SMSG server_id TRace ALL
END
[NO]AUth
[NO]CAche
[NO]DBG
[NO]DBG2
[NO]INit
[NO]IUcv
[NO]MOre
[NO]NOtice
[NO]PArms
[NO]PKTIN
[NO]PKTOUt
[NO]QUeue
[NO]SQl
[NO]STorage
[NO]SUbroutines
[NO]TCp
[NO]TYpe
[NO]UDp
[NO]UTl
[NO]ZOne
Operands
server_id
The user ID of the name server virtual machine.
ALL
All trace categories are enabled. This results in extensive console tracing.
END
All trace categories are disabled.
AUth
NOAUth
Enables or disables console tracing of authority determination.
CAche
NOCAche
Enables or disables console tracing of caching activities.
DBG
NODBG
Enables or disables console tracing in special diagnostic circumstances.
DBG2
NODBG2
Enables or disables console tracing in special diagnostic circumstances.
INit
NOINit
Enables or disables console tracing of initialization activities.
IUcv
Chapter 8. Configuring the DNS Server
157
DNS Server
NOIUcv
Enables or disables console tracing of IUCV activity.
MOre
NOMOre
Enables or disables additional trace points that are normally skipped because of
the large amount of trace data displayed.
NOtice
NONOtice
Enables or disables console tracing of TCP/IP message notifications.
PArms
NOPArms
Enables or disables console tracing of input parameters to most subroutines.
PKTIn
NOPKTIn
Enables or disables console tracing of most inbound DNS messages received.
PKTOut
NOPKTOut
Enables or disables console tracing of most inbound DNS messages sent to
other hosts.
QUeue
NOQUeue
Enables or disables console tracing of questions asked of this name server and
questions and answers related to those questions.
SQl
NOSQl
Enables or disables console tracing of various activities involving the DB2
database.
STorage
NOSTorage
Enables or disables console tracing of storage usage.
SUbroutines
NOSUbroutines
Enables or disables console tracing of each subroutine executed. Some utility
subroutines are instead traced with the UTl trace.
STorage
NOSTorage
Enables or disables console tracing of storage usage.
TCp
NOTCp
Enables or disables console tracing of activities using the TCP protocol.
UDp
NOUDp
Enables or disables console tracing of activities using the UDP protocol.
UTl
NOUTl
Enables or disables console tracing of input parameters to and results from
many utility subroutines.
ZOne
158
z/VM: TCP/IP Planning and Customization
DNS Server
NOZOne
Enables or disables console tracing of zone transfer requests, and zone
transferring of local zones.
SMSG VMDUMP Command
The SMSG VMDUMP command allows you to cause the name server to take a
CMS DUMP if an abend occurs. It also allows you to take a DUMP immediately.
SMSG server_id VMDump
ON
OFF
NOW
Operands
server_id
The user ID of the name server virtual machine.
ON
Specifies that the name server should take a dump if the abend handler is
entered.
OFF
Specifies that the name server should NOT take a dump if the abend handler is
entered.
NOW
Specifies that the name server should take a dump right now. Execution
continues after the dump is taken.
Rebuilding the Name Server Modules
To compile the name server ASMSQL and CSQL files, you must have a Database
Administrator issue the following command:
grant connect to server_id identified by sqldbapw
where server_id is the user ID of the name server virtual machine.
If you do not want to use the password SQLDBAPW, you must issue the GRANT
command with a password of your choice and modify the TCPOBJCT EXEC to
reflect the new password.
Chapter 8. Configuring the DNS Server
159
160
z/VM: TCP/IP Planning and Customization
Chapter 9. Configuring the FTP Server
The File Transfer Protocol (FTP) virtual machine serves client requests to transfer
files between TCP/IP hosts to or from your VM host. To configure the FTP server,
you must perform the following steps:
FTP Server Configuration Steps
1. Update the TCP/IP server configuration file.
2. Update the DTCPARMS file for the FTP server.
3. Establish FTP server machine authorizations.
4. Customize the SRVRFTP CONFIG file.
5. Configure Automatic File Translation. (Optional)
6. Customize FTP server exits. (Optional)
Dynamic Server Operation
The FTP server provides a VM Special Message (SMSG) interface that allows you
to perform server administration tasks through a set of privileged commands. For
more information, see “SMSG Interface to the FTP Server” on page 175.
Step 1: Update PROFILE TCPIP
Include the FTP server virtual machine in the AUTOLOG statement of the TCPIP
server configuration file. The FTP server is then started automatically when TCPIP
is initialized. The IBM default user ID for this server is FTPSERVE. Verify that the
following statements have been added to PROFILE TCPIP:
AUTOLOG
FTPSERVE 0
The FTP server requires that ports TCP 20 and TCP 21 be reserved for it. Verify
that the following statements have been added to your TCPIP server configuration
file as well:
PORT
20 TCP FTPSERVE NOAUTOLOG
21 TCP FTPSERVE
; FTP Server
; FTP Server
Step 2: Update the DTCPARMS File
When the FTP server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the FTP server are:
:Nick.FTPSERVE
:Anonymous.
:ESM_Enable.
:ESM_Validate.
:ESM_Racroute.
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
© Copyright IBM Corp. 1987, 2002
161
FTP Server
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the FTP server if you:
v use a configuration file other than SRVRFTP CONFIG
v provide anonymous FTP support
v use an ESM for client authorization and access control.
SRVRFTP Command
FTP services are initiated using the SRVRFTP command:
SRVRFTP
SRVRFTP
filename
(
CONFIG
filetype
ANONYMOU
RACF
*
filemode
Specify SRVRFTP command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
filename
The file name of the FTP server configuration file. The default file name is
SRVRFTP.
filetype
The file type of the configuration file. The default file type is CONFIG.
filemode
The file mode of the configuration file. The default file mode is an asterisk (*).
ANONYMOU
Directs the FTP server to allow a client to login with a user name (ID) of either
″anonymous″ or ″anonymou″ without requiring a logon password. This operand
is automatically supplied when an Anonymous.YES entry is specified in the
DTCPARMS file.
RACF
Directs the FTP server to rely upon an External Security Manager (ESM) to
validate passwords and to control access to minidisks. This operand is
automatically supplied when an ESM_Enable.YES entry is specified in the
DTCPARMS file.
Step 3: Establish FTP Server Machine Authorizations
In order for FTP clients to access files or directories in the CMS Shared File
System (SFS), the FTP server must have SFS file pool administrator authority. Each
FTP server that will provide such access must be listed on the ADMIN statement in
the SFS file pool server’s DMSPARMS file. For details on SFS file pool
configuration and administrator authority, see the z/VM SFS and CRR Planning,
Administration, and Operation book.
162
z/VM: TCP/IP Planning and Customization
FTP Server
In order for FTP clients to access files and directories in the Byte File System
(BFS), the FTP server must be defined as a POSIX “superuser”. To allow this
capability, the following statement must be included in the CP directory:
POSIXINFO UID 0 GID 0
See z/VM: OpenExtensions User’s Guide and z/VM: CP Planning and
Administration for more information about configuring the FTP server in this manner.
The CP directory entry for the FTP server must include an OPTION DIAG 88
statement and the server must have class B privileges, regardless of whether an
External Security Manager (ESM) is in use.
If FTP virtual reader support is enabled, the FTP server virtual machine must also
have class D privileges.
The FTP server can use an external security manager (ESM) to authenticate FTP
clients and to control access to z/VM resources. To use an ESM, specify
:ESM_Enable.Yes in the DTCPARMS file. For more information, see Appendix A,
“Using TCP/IP with an External Security Manager” on page 645.
Step 4: Customize the SRVRFTP CONFIG File
The FTP configuration file, SRVRFTP CONFIG, defines how the FTP server is to
operate and what services and types of access it provides. See “FTP Server
Configuration File Statements” for detailed information about how to specify entries
within this file. A sample FTP configuration file is shipped with TCP/IP Level 430 as
SRVRFTP SCONFIG on the TCPMAINT 591 disk. Your customized SRVRFTP
CONFIG file should be stored on the TCPMAINT 198 minidisk.
FTP Server Configuration File Statements
Within the configuration file, blanks and record boundaries are used to delimit
tokens. All characters to the right of, and including a semicolon are treated as a
comment.
ANONYMOU Statement
The ANONYMOU statement directs the FTP server to allow a client to login with a
user name (ID) of either “anonymous” or “anonymou” without requiring a logon
password.
Note: The recommended method for enabling anonymous FTP support is to
specify an :Anonymous.YES entry in the DTCPARMS file instead of using the
ANONYMOU configuration statement.
ANONYMOU
Operands
The ANONYMOU statement has no operands.
Usage Notes
v For installations that make use of External Security Manager (ESM) (those for
which an :ESM_Enable.YES entry has been specified in the DTCPARMS file, and
Chapter 9. Configuring the FTP Server
163
FTP Server
which may make use of the FTP server RACF configuration statement), the user
ID ANONYMOU must be defined to the ESM that is in use.
v The user ID ANONYMOU must be enrolled in any SFS file pool for which
anonymous access is to be allowed.
v It is not necessary for the ANONYMOU user ID to be defined in the CP directory
when anonymous FTP support is enabled.
AUTOTRANS Statement
The AUTOTRANS statement specifies whether automatic file translation is
performed by default when files are transferred using the Image transfer type.
AUTOTRANS OFF
AUTOTRANS ON
Operands
ON
Specifies that automatic file translation should be enabled as the default when
an FTP session is established.
OFF
Specifies that automatic file translation should be disabled as the default when
an FTP session is established.
The specified default translation setting is applied to all Image transfers that are
requested by clients unless:
v The CHKIPADR exit has been configured to select a specific translation setting
when a user logs in
v the automatic translation setting is changed during an FTP session by a client via
the AUTOTRANS operand of the SITE subcommand.
DONTREDIRECT Statement
The DONTREDIRECT statement restricts an FTP client to establishing data
connections with only the local system. This prevents a client from using the FTP
server to mount an “FTP bounce” attack, but violates the File Transfer Protocol RFC
(RFC 959) which allows a data connection to be established between two remote
systems.
No applications that exploit this capability are known to exist. However, if you
activate this option, you should be aware of the potential limitation it imposes on
legitimate applications of FTP.
DONTREDIRECT
Operands
The DONTREDIRECT statement has no operands.
164
z/VM: TCP/IP Planning and Customization
FTP Server
FTAUDIT Statement
The FTAUDIT statement causes the FTP server exit (FTPEXIT) to be loaded during
initialization and enables audit processing.
For audit processing, this exit is called for every transfer of data (bytes) over a
connection; this includes data associated with files, as well as data returned in
response to LIST, DIR or similar subcommands. Events such as login and logout
(that is, the USER and QUIT subcommands) will also be audited.
FTAUDIT
Operands
The FTAUDIT statement has no operands.
FTCHKCMD Statement
The FTCHKCMD statement causes the FTP server exit (FTPEXIT) to be loaded
during initialization and enables general command exit processing.
The FTP exit is called to perform command validation for every received FTP
subcommand. The server command exit can be used to perform additional
validation of a supplied user ID, IP address, or the subcommand itself. If
appropriate, the exit can then indicate the supplied subcommand should be
rejected, with an exit-defined message returned to the user.
FTCHKCMD
Operands
The FTCHKCMD statement has no operands.
FTCHKDIR Statement
The FTCHKDIR statement causes the FTP server exit (FTPEXIT) to be loaded
during initialization and enables CD command exit processing.
The exit is called to validate FTP directory changes, allowing greater control over
access to system resources by providing the capability to selectively honor or
refuse a client CD (Change Directory) request.
FTCHKDIR
Operands
The FTCHKDIR statement has no operands.
INACTIVE Statement
The INACTIVE statement sets the inactivity time-out the FTP server should apply to
connections, once they are established. The FTP server closes connections found
to be inactive for the specified amount of time.
Chapter 9. Configuring the FTP Server
165
FTP Server
INACTIVE 300
INACTIVE seconds
Operands
seconds
The number of seconds of inactivity after which the FTP server will close a
connection. Specify seconds as an integer between 1 and 1,048,576. The
default inactivity time-out is 300 seconds (5 minutes).
LISTFORMAT Statement
The LISTFORMAT statement sets the format default for list information supplied by
the FTP server when it responds to client DIR (or, LIST) requests. If this statement
is not specified, the default format is VM.
LISTFORMAT VM
LISTFORMAT
VM
UNIX
Operands
VM
Specifies that VM-format lists should be supplied by default when responding to
client DIR (or, LIST) requests.
UNIX
Specifies that UNIX-format lists should be supplied by default when responding
to client DIR (or, LIST) requests.
The specified format default is applied to all LIST responses supplied to clients
unless:
v The CHKIPADR exit has been configured to select a specific format default when
a user logs in
v the list format is changed during an FTP session by a client via the
LISTFORMAT operand of the SITE subcommand.
For detailed information about VM-format and Unix-format responses, see the
TCP/IP User’s Guide.
LOADDBCSTABLE Statement
The LOADDBCSTABLE statement identifies DBCS translate tables that are to be
loaded when the FTP server is initialized. By using multiple LOADDBCSTABLE
statements, any number of translate tables may be selected ranging from none to
all supported DBCS translate tables.
166
z/VM: TCP/IP Planning and Customization
FTP Server
LOADDBCSTABLE
EUCKANJI
HANGEUL
JIS78KJ
JIS83KJ
KSC5601
SJISKANJI
TCHINESE
Operands
EUCKANJI
Indicates that the Extended Unix Code Kanji DBCS translation table should be
loaded from the TCPKJBIN binary translate table file.
HANGEUL
Indicates that the Hangeul DBCS translation table should be loaded from the
TCPHGBIN binary translate table file.
JIS78KJ
Indicates that the JIS 1978 Kanji DBCS translation table should be loaded from
the TCPKJBIN binary translate table file.
JIS83KJ
Indicates that the JIS 1983 Kanji DBCS translation table should be loaded from
the TCPKJBIN binary translate table file.
KSC5601
Indicates that the Korean Standard Code KSC-5601 DBCS translation table
should be loaded from the TCPHGBIN binary translate table file.
SJISKANJI
Indicates that the Shift JIS Kanji DBCS translation table should be loaded from
the TCPKJBIN binary translate table file.
TCHINESE
Indicates that the Traditional Chinese (5550) DBCS translation table should be
loaded from the TCPCHBIN binary translate table file.
Usage Notes
v Additional virtual storage may need to be defined for the FTP server if a large
number of translate tables are loaded concurrently.
v The IBMKANJI transfer type does not require any translate table to be loaded.
For more information on loading and customizing DBCS translate tables, see
“Customizing DBCS Translation Tables” on page 629.
PORT Statement
The PORT statement causes the FTP server to listen on a specified TCP
connection port. By convention, port number 21 is usually reserved (in the TCPIP
server configuration file) for the FTP server to accept FTP connection requests.
Chapter 9. Configuring the FTP Server
167
FTP Server
PORT 21
PORT port_number
Operands
port_number
An integer in the range of 1 through 65,534 that specifies the port number to
which the FTP server listens. The default is port 21.
RACF Statement
The RACF statement directs the FTP server to rely upon an External Security
Manager (ESM) to validate passwords and to control access to minidisks.
Note: The recommended method for enabling the use of an ESM is to specify an
:ESM_Enable.YES entry in the DTCPARMS file instead of using the RACF
configuration statement.
For more information about using an external security manager, see Appendix A,
“Using TCP/IP with an External Security Manager” on page 645.
RACF
The RACF statement has no operands.
Usage Notes
When this statement is used, an :ESM_Enable.YES entry must also be included in
the DTCPARMS file to allow ESM-specific initialization processing to be performed.
RDR Statement
The RDR statement enables FTP server reader file support, which allows files to be
transferred to a VM user’s virtual reader.
RDR filemode
Operands
filemode
The file mode of the resource to be used to temporarily store file before they
are sent to a virtual reader. Any of the following resources may be used for this
purpose:
v a minidisk
v a temporary minidisk
v a virtual disk
v an SFS directory.
168
z/VM: TCP/IP Planning and Customization
FTP Server
Usage Notes
v When FTP reader file support is enabled, users are allowed to STOR files to a
virtual reader of a VM user ID. To allow users to issue DELETE and DIR/LS
commands against a reader directory, the FTP server virtual machine must have
class D privileges. (Class D is required for the CP PURGE userid RDR spoolid
and CP QUERY RDR userid commands.)
v The FTP reader file support may be disabled by the FTP general command exit
or the CD command exit.
v An SFS directory cannot be used for both temporary RDR file storage and as a
substitute for the FTP server ″A″ disk. The FTP server requires a minidisk to be
accessed at file mode A for proper operation.
For example, assume you choose to use the FTP server "root" SFS directory in
file pool MYFPOOL1 as the storage area for files directed to a user’s virtual reader.
The following DTCPARMS entry (added to the appropriate FTP server or class
definition) will configure the FTP server to acquire this resource with file mode F:
:nick.FTPSERVE
:vmlink. .DIR MYFPOOL1:FTPSERVE. <* F>
Additionally, a corresponding RDR F statement must be included in the FTP
server configuration file. File mode F is used here to ensure the
MYFPOOL1:FTPSERVE. directory is accessed in the CMS search order after the
TCP/IP configuration, client-code, and server-code minidisks.
TIMESTAMP Statement
The TIMESTAMP statement specifies whether timestamps should be shown in front
of any FTP message.
TIMESTAMP ON
TIMESTAMP
ON
OFF
Operands
ON
Specifies that timestamps should be shown in front of FTP messages.
OFF
Specifies that timestamps should not be shown in front of FTP messages.
TRACE Statement
The TRACE statement enables FTP server tracing, which describes major actions
such as beginning a dialog with a new client. Trace information can be directed to
either the FILE DEBUGTRA file on the FTP server 191 minidisk or to the FTP
server console.
Chapter 9. Configuring the FTP Server
169
FTP Server
TRACE
CONSOLE
CONSOLE
FILE
Operands
CONSOLE
Specifies that trace information should be directed to the FTP server console.
This is the default.
FILE
Specifies that trace information should be directed to the FILE DEBUGTRA file
on the FTP server 191 minidisk.
Step 5: Configure Automatic File Translation (Optional)
By default, the z/VM FTP server transfers files in accordance with the transfer mode
and type settings specified by a client. However, when web browser FTP clients are
used to interact with this server, automatic file translation (performed by the FTP
server on a default basis) is recommended.
When such translation is enabled, the server performs automatic EBCDIC-ASCII
translation, based on a file extension (or with respect to CMS files, the file type) of
a file that is transferred using the Image transfer type. This can simplify FTP
operations for various users and clients, and may be necessary to accommodate
certain types of clients — web browser and graphical FTP clients, for example —
since many of these clients often default to using a transfer type of Image (or,
binary) and do not offer a way for users to specify a different file transfer type.
To enable default automatic file translation:
1. Specify the AUTOTRANS ON statement in the FTP server configuration file.
2. Customize the TCPIP DATA file to include the appropriate VMFILETYPE and
VMFILETYPEDEFAULT statements. The FTP server relies upon these
statements to control the manner in which file translation is performed for
specific file extensions, as well as those that are “unknown” or not recognized.
For detailed information about how to specify these statements, see Chapter 3,
“Defining the TCP/IP System Parameters” on page 15.
Notes:
1. The VMFILETYPE statement determines whether EBCDIC-ASCII translation
occurs for a specific file, based on the extension of that file.
2. File extensions that are not dealt with through a specific VMFILETYPE
statement are considered as “unknown” (that is, are not recognized). The
translation performed for such files (if any) is controlled by the
VMFILETYPEDEFAULT statement. If the VMFILETYPEDEFAULT statement is
not used, unknown file extensions default to a transfer type of Image and no
translation is performed.
3. The FTP server ignores the LINES operand of the VMFILETYPE and
VMFILETYPEDEFAULT statements. For additional information about automatic
file translation, see the TCP/IP User’s Guide.
170
z/VM: TCP/IP Planning and Customization
FTP Server
Step 6: Customize FTP Server Exits (Optional)
The FTP server exits are described in the following sections.
|
|
|
Prior to customizing the server exits described in this section, ensure that you have
reviewed the exit limitations and customization recommendations presented in
“Customizing Server-specific Exits” on page 43.
Using the FTP Welcome Banner
The FTP server can display a site specific message when users establish a
connection to the FTP server. The contents of file "FTP BANNER" will be displayed,
if the file exists. When this file exists, the first such file found in the CMS search
order is used. You may also wish to have one of several different banners displayed
after the user name and login password (for other than anonymous user) validation.
This is handled in the CHKIPADR Exit.
Using the FTP Server Exit
The FTP server exit, FTPEXIT ASSEMBLE, can be called by the FTP server to
allow greater control over how FTP commands received by this server are
processed and to allow for auditing of FTP logins, logouts, and file transfers. The
FTP exit is enabled using the FTAUDIT, FTCHKCMD, and FTCHKDIR configuration
file statements or by using privileged SMSG commands to enable or disable the exit
processes.
For audit processing (FTAUDIT enabled), the FTP exit will be called for login,
logout, and data transfer events that are initiated using these FTP subcommands:
APPEND, GET, PUT, DIR and LS. Information passed to the exit may be used to
generate user login/logout reports and to keep track of files (and bytes) transferred
in and out through the FTP server.
When the FTP server exit is enabled for general command exit processing
(FTCHKCMD enabled), the FTP exit will be called to perform command validation
for every received FTP command. The general command exit can be used to
perform additional security checking and then take an appropriate action, such as:
v Reject commands from a particular IP address or user ID
v Reject a subset of commands for anonymous users
v Reject transfer requests for specific files
v Reject all store (APPE, STOR, STOU) commands supplied by users.
With the FTP exit enabled for CD command exit processing (FTCHKDIR enabled),
the exit can validate FTP directory changes and provide greater control over access
to system resources by selectively honoring or refusing a client change directory
request. The exit is called when an FTP client provides one of the following
commands:
v CWD or CD, to change the working directory
v CDUP, to change the working directory to the parent directory
v PASS, provided a default directory is defined in CHKIPADR EXEC for the user
that supplies this command
v USER, for an anonymous login for which a default directory is defined in
CHKIPADR EXEC
v APPE, DELE, LIST, NLST, RETR, SIZE, STOR, or STOU commands that involve
an explicit change in directory.
Chapter 9. Configuring the FTP Server
171
FTP Server
Sample FTPEXIT exec and assemble routines are supplied as softcopy files
(FTPEXIT SEXEC and FTPEXIT SAMPASM, respectively) on the TCPMAINT 591
minidisk. Refer to the TCP/IP Programmer’s Reference for details about FTPEXIT
parameter list and parameter descriptions.
Using the CHKIPADR Exit
The CHKIPADR exit provides a means for controlling several aspects of FTP server
processing at the time an FTP connection is initiated by the user. This capability is
provided through the CHKIPADR EXEC, which is invoked by the server each time a
user logs in. This exec may be used to:
v Permit or deny client access to FTP services
v Permit anonymous user login for users other than ANONYMOU
v Select a default working directory
v Select a “welcome” message, or banner
v Select a default file list format
v Select default automatic file translation
Decisions concerning these actions can be made based on the VM user ID,
LOGON BY user ID, or client IP address associated with an FTP connection as it is
attempted.
Providing Anonymous Login Support
Anonymous user login can be accommodated for user names other than
ANONYMOU or ANONYMOUS (for which a corresponding ANONYMOU VM user
ID is required). Anonymous login is permitted for user names other than
ANONYMOU when return code 20 is received from CHKIPADR EXEC and when
the :Anonymous.YES tag is specified in the DTCPARMS file. Anonymous users are
not prompted to provide a login password.
Establishing a Default Working Directory
When a user logs in using FTP, the 191 minidisk associated with that user ID is
established as a working directory, by default. However, an alternate working
directory may be selected for a user when a connection is established. The
alternate working directory specified may be a:
v minidisk
v Shared File System (SFS) directory
v Byte File System (BFS) directory
v virtual reader (RDR).
Providing a User-Specific Banner
A welcome message or banner can be specified for a user or group of users when
a connection is accepted. Such a banner could be used to provide special
instructions or supply current file/directory status information. The banner file type
must be BANNER. The contents of the file will be displayed following user login
validation. Banners specified in CHKIPADR EXEC are displayed in addition to the
default FTP BANNER file, which is displayed at connection time.
Establishing a Default File List Format
A default file list format may be selected for a user or group of users when a
connection is accepted. The selected format determines how responses to client
DIR or LIST commands are initially presented. The z/VM FTP server can provide
either VM-format or Unix-format file lists. The desired format default must be
indicated when control is returned to the FTP server.
Note: Since many web browsers use anonymous FTP during implicit FTP
transactions, a Unix-format list default is recommended for anonymous FTP
clients.
172
z/VM: TCP/IP Planning and Customization
FTP Server
Establishing Automatic File Translation Defaults
The default setting for automatic file translation, based on file extension, can be
turned on or off for specific users. For detailed information, see “Step 5: Configure
Automatic File Translation (Optional)” on page 170. The desired default setting must
be indicated when control is returned to the FTP server.
Note: Since many web browsers use anonymous FTP during implicit FTP
transactions (and, often perform only binary file transfers), default automatic
file translation is recommended for anonymous FTP clients.
CHKIPADR Input
Operands are provided to the CHKIPADR EXEC at invocation, based on the
following syntax:
CHKIPADR userid ipaddress byuserid
Operands
userid
Specifies, in uppercase, the user ID that the FTP server will use for security
checking.
ipaddress
Specifies, in dotted decimal notation, the IP address that the FTP server will
use for security checking.
byuserid
Specifies, in uppercase, the LOGON BY user ID if the FTP client issued a
USER subcommand that included the userid/BY/byuserid operands; otherwise
this field will contain a hyphen (-).
CHKIPADR Output
These are the return codes for the CHKIPADR EXEC:
0
User ID/IP Address is authorized
4
User ID is not authorized
8
IP Address is not authorized
12
User ID is not authorized and no error message will be sent user.
20
Anonymous user, no password required
Program stack contents upon exit may contain in any order:
v Default working directory
v Banner file name, prefixed by the keyword BANNER
v Translation default (ON or OFF), prefixed by the keyword AUTOTRANS
v List format (VM or UNIX), prefixed by the keyword LISTFORMAT
Example
The CHKIPADR code sample that follows causes the FTP server to perform the
following actions when the user TERI initiates an FTP connection:
1. allow anonymous login (that is, TERI is not prompted for a login password)
2. establish the “server1:teri:ftp” SFS directory as the default working directory
3. initially respond to DIR commands using UNIX-format file lists
Chapter 9. Configuring the FTP Server
173
FTP Server
4. enable automatic file translation for Image file transfers
5. display the content of a WELCOME BANNER file, if it exists.
/* Sample processing clause for FTP user "Teri" */
When (Userid = ’TERI’)
Then Do
Queue ’server1:teri.ftp’
Queue ’banner welcome’
Queue ’listformat unix’
Queue ’autotrans on’
status = 20
End
When user TERI issues an FTP command to connect to the
VMSYS1.ENDICOTT.IBM.COM host, the following responses might be produced:
ftp vmsys1
VM TCP/IP FTP Level 330
Connecting to VMSYS1 9.130.48.64
220-............................................
.
.
. This is the contents of FTP BANNER
.
.
.
............................................
FTPSERV2 IBM VM Level 330 at VMSYS1.ENDICOTT.IBM.COM, 13:56:24 EST
2000-03-26
220 Connection will close if idle for more than 5 minutes.
USER (identify yourself to the host):
teri
>>>USER teri
230-............................................
.
.
. This is the contents of WELCOME BANNER .
.
.
............................................
230 TERI logged in; working directory = SERVER1:TERI.FTP
Command:
Dynamic Server Operation
The VM Special Message Facility (SMSG) command provides an interactive
interface to the FTP server to perform privileged system administration tasks, such
as:
v enabling and disabling the Trace function
v querying user data
v dropping connections
v querying minidisks and directories held by the FTP server
v enabling, disabling, and querying the FTP User Exits
v setting the default list format supplied by the server
v enabling and disabling default automatic file translation.
Notes:
1. Privileged SMSG commands are accepted only from users that have been
included in the OBEY list of the TCPIP server configuration file.
2. Command responses are returned to the originator of the SMSG command
through the use of CP MSG commands.
174
z/VM: TCP/IP Planning and Customization
FTP Server
SMSG Interface to the FTP Server
SMSG server_id
process_name
AUTOTrans
ON
OFF
ON
OFF
CLosecon
DRop conn_num
FTPEXIT
RELOAD
Help
LISTFormat
VM
UNIX
*
Query
user_id
process_name
ACCESSED
AUTOTrans
LISTFormat
RDRmode
RDRmode
fm
OFF
REBoot
REFresh VMFiletype
RELease fm
SHutdown
TIMEstamp
ON
OFF
ON CONsole
TRace
CONsole
ON
FIle
OFF
Operands
process_name ON | OFF
Enables or disables the audit exit, the command exit or the CD command exit.
Process_name may be FTAUDIT, FTCHKCMD, FTCHKDIR or FTPEXIT. If
FTPEXIT is specified, all FTP exits will be enabled or disabled.
AUTOTrans ON | OFF
Determines whether automatic file translation is performed by default when files
are transferred using the Image transfer type. Specify ON if automatic file
translation should be enabled as the default when an FTP session is
established, or OFF if the default should be to not attempt such translation. If
neither ON or OFF is specified, ON is the default.
The specified default translation setting is applied to all Image transfers
requested by clients unless:
v the CHKIPADR exit has been configured to select a specific translation
setting when a user logs in
Chapter 9. Configuring the FTP Server
175
FTP Server
v the automatic translation setting is changed during an FTP session by a
client via the AUTOTRANS operand of the SITE subcommand.
For more information about automatic file translation, see “Step 5: Configure
Automatic File Translation (Optional)” on page 170.
CLosecon
Closes the FTP server console log and sends it to the :Owner. identified in the
DTCPARMS file.
server_id
Specifies the user ID of the FTP server virtual machine.
DRop conn_num
Indicates the FTP server is to drop the specified connection.
FTPEXIT RELOAD
Reloads the FTP exit routine.
Help
Provides brief help about SMSG commands supported by the FTP server.
LISTFormat VM | UNIX
Sets the format default for list information supplied by the server when it
responds to client DIR (or, LIST) requests. Specify VM for VM-format lists to be
supplied by default, or UNIX if the default should be Unix-format lists. The
specified format default is applied to all LIST responses, unless:
v the CHKIPADR exit has been configured to select a specific format default
when a user logs in
v the list format is changed during an FTP session by a client via the
LISTFORMAT operand of the SITE subcommand.
For detailed information about VM-format and Unix-format responses, see the
TCP/IP User’s Guide.
Query user_id
Returns user data for the specified user or if user_id is omitted or is an (*),
returns data for all current FTP users.
Query process_name
Queries the settings for the process_name specified. Process_name may be
FTAUDIT, FTCHKCMD, FTCHKDIR or FTPEXIT. If FTPEXIT is specified, all
FTP exit settings will be displayed.
Query ACCESSED
Returns CMS QUERY ACCESSED command output.
Query AUTOTRANS
Returns the setting (ON or OFF) that is in effect for the automatic file translation
default.
Query LISTFormat
Returns the setting (VM or UNIX) that is in effect for the list format default.
Query RDRmode
Returns the file mode of the resource used to temporarily store files before they
are sent to a virtual reader.
RDRmode fm
Sets the filemode of the resource to be used to temporarily store files before
they are sent to a virtual reader. This enables the FTP server PUT support to a
virtual reader. This filemode cannot be changed if the FTP server is currently
176
z/VM: TCP/IP Planning and Customization
FTP Server
processing a PUT to a reader directory. The file mode specified must be a
accessed filemode to which the FTP server has Read/Write privileges.
RDRmode OFF
Disables the FTP server PUT support to a virtual reader. PUT to reader support
cannot be disabled while the FTP server is processing a PUT to a reader
directory.
REBoot
Causes the FTP server to Initial Program Load (IPL) CMS.
REFresh VMFiletype
Causes the FTP server to replace existing automatic file translation information
with that defined by current VMFILETYPE and VMFILETYPEDEFAULT
definitions in the TCPIP DATA file.
RELease fm
Indicates the FTP server is to issue a CMS RELEASE command for the
specified file mode.
SHutdown
Initiates FTP server shutdown processing (in the same manner as the #CP
EXTERNAL command) and additionally logs off the server.
TIMEstamp ON
Specifies that timestamps should be shown in front of FTP messages.
TIMEstamp OFF
Specifies that timestamps should not be shown in front of FTP messages.
TRace OFF
Disables server tracing.
TRace ON CONsole
Enables server tracing and directs trace information to the FTP server console
log.
TRace ON FIle
Enables server tracing and directs trace information to the FILE DEBUGTRA file
on the FTP server 191 minidisk. If the trace file already exists, its previous
contents are deleted.
Providing Web Browser FTP Support
By default, the z/VM FTP server responds to client LIST requests using VM-format
lists. However, when web browser FTP clients are used to interact with this server,
the use of a Unix-format list default is recommended. If VM-format file lists are
supplied to such a client, that client may not correctly display or manage the
supplied directory and file information, which may lead to limited or adversely
affected FTP processing capabilities.
Default Unix-format lists are also recommended when graphical FTP clients are in
use — again because these clients are generally Unix-based, and thus expect
Unix-like information to be presented. Also, many such clients do not offer a way for
users to affect file transfer operations through specific FTP subcommands; this
precludes the selection of a response format.
In addition, automatic file translation may need to be enabled on a default basis, to
allow for correct file translations when web browser and graphical FTP clients are in
use. This is because many such browsers often default to using a transfer type of
Image (or, binary) and do not offer a way for users to specify a different file
Chapter 9. Configuring the FTP Server
177
FTP Server
transfer type. See “Step 5: Configure Automatic File Translation (Optional)” on
page 170 for more information about this topic.
178
z/VM: TCP/IP Planning and Customization
Chapter 10. Configuring the IMAP Server
Understanding IMAP
The Internet Message Access Protocol (IMAP) server, based on RFC 2060, permits
a ″client″ email program to access remote message folders called ″mailboxes″, as if
they were local. For example, email stored on an IMAP server can be manipulated
from a desktop computer from a remote location, a workstation at the office, or a
notebook computer while traveling, without the need to transfer messages or files
back and forth between these computers.
The widely used Post Office Protocol (POP) works best when one has only a single
computer, since it was designed to support offline message access, whereby
messages are downloaded and then deleted from the mail server. This mode of
access is not compatible with access from multiple computers since it tends to
distribute messages across all of the computers used for mail access. Unless all of
those machines share a common file system, the offline mode of access that POP
was designed to support effectively ties the user to one computer for message
storage and manipulation.
Some key aspects of IMAP are:
v Full compatibility with Internet messaging standards such as MIME
v Allow message access and management from more than one computer
v Client software needs no knowledge about the server’s file format
Configuration Steps for the IMAP Server
To configure the IMAP server, you must perform the following steps:
IMAP Server Configuration Steps
1. Update the TCPIP server configuration file (PROFILE TCPIP).
2. Update the DTCPARMS file for the IMAP server.
3. Update the System (CP) directory for the IMAP server and establish
Authorizations.
4. Set Up the IMAP Mailstore SFS File Pool Server and update it’s System
(CP) Directory Entry.
5. Update the $SERVER$ NAMES file.
6. Customize the IMAP Configuration file.
7. Set Up SMTP to Route Mail to the IMAP Server.
8. Enroll new users into the IMAP Mailstore
Dynamic Server Operation
The IMAP server provides an IMAP command interface that allows you to perform
server administration tasks through a set of privileged commands. For more
information see “Dynamic Server Operation” on page 187.
© Copyright IBM Corp. 1987, 2002
179
IMAP Server
Step 1: Update PROFILE TCPIP
Include the IMAP server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The IMAP server is then started automatically when
TCPIP is initialized. The IBM default user ID for this server is IMAP. Verify that the
following statement has been added to the PROFILE TCPIP file:
AUTOLOG
IMAP 0
;
IMAP Server
Note: If you do not want the IMAP server automatically started, do not include the
AUTOLOG statement in the file.
The IMAP server requires that port TCP 143 be reserved for it. Verify that the
following statements have been added to your TCPIP server configuration file as
well:
PORT
143 TCP IMAP
;
IMAP Server - administration
Step 2: Update the DTCPARMS File
When the IMAP server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the IMAP server are:
:Nick.imap
:Type.server
:Class.imap
:Nick.imap
:Type.class
:ESM_Enable.
:ESM_Validate.
:ESM_Racroute.
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
Note: You should modify the DTCPARMS file for the IMAP server if you:
v Use a configuration file other than IMAP Config.
v Use an External Security Manager (ESM) for client authorization and
access control.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
IMAPMAIN Command
The IMAP services are initiated using the IMAPMAIN command:
IMAPMAIN
IMAP
filename
(
CONFIG
filetype
ESM
*
filemode
Specify IMAPMAIN command operands as :Parms. tag start-up parameters in your
DTCPARMS file.
180
z/VM: TCP/IP Planning and Customization
IMAP Server
Operands
filename
The file name of the IMAP server configuration file. The default file name is
IMAP.
filetype
The file type of the configuration file. The default file type is CONFIG.
filemode
The file mode of the configuration file. The default file mode is an asterisk(*).
ESM
Directs the IMAP server to rely upon an External Security Manager (ESM) to
validate IMAP client passwords. This operand is automatically supplied when an
ESM_Enable.YES entry is specified in the DTCPARMS file.
Usage Notes
1. If an alternate configuration file is not given, the IMAP server will first search all
accessed disks for a configuration file with the file name matching the IMAP
server user ID and the file type CONFIG. If that is not found, the IMAP server
searches all accessed disks for IMAP CONFIG.
2. DTCPARMS file changes become effective only when the IMAP server is
restarted.
Step 3: Update the System (CP) Directory for the IMAP Server and
Establish Authorizations
There are some required CP directory statements that must be coded when setting
up the IMAP server virtual machine. Below is an example of these entries along
with an explanation of their use.
IUCV *SPL
IUCV ANY or IUCV sfs_server_id
IUCV ALLOW
OPTION MAXCONN 2000
OPTION DIAG88
v The IMAP virtual machine must be authorized to use the *SPL system service in
order to asynchronously read in mail as it arrives in the server’s reader. This
must be added for each IMAP server.
v To establish a connection with the Mailstore server, a directory entry of either
IUCV ANY or IUCV sfs_server_id (where sfs_server_id is the MAILSTORE
server ID) must be included.
v The IMAP server must also have SFS admin authority to the SFS filepool. For
data integrity reasons, an IUCV ALLOW statement should not be coded in the
IMAP mailstore SFS server’s directory entry. To do so would be to allow IMAP
users to directly connect to the SFS server, possibly corrupting the file structure
or data residing in the filepool. Should it be necessary to allow other users
access to the IMAP SFS server, their CP directories should contain an IUCV
sfs_server_id statement.
v The IUCV ALLOW entry is required for enabling the IMAP server for incoming
APPC/VM conversations. These ″conversations″ can be initiated by any IMAP
administrators that have been listed in the CMS private resource registration file
($SERVER$ NAMES) which use the queue-based administrative interface that is
provided in the IMAPADM EXEC.
Chapter 10. Configuring the IMAP Server
181
IMAP Server
v
The required OPTION MAXCONN 2000 directory statement allows for up to
2000 IUCV connections to the IMAP mailstore. If you expect to have more than
2000 concurrent connections, you should increment the MAXCONN value to
match the expected number of concurrent connections. This number should be
the same for the IMAP server and the IMAP mailstore SFS server.
v The CP directory entry for the IMAP server must include an OPTION DIAG88
statement. This will allow the IMAP server to use DIAGNOSE X'88 to validate
user authorization, regardless of whether an External Security Manager (ESM) is
in use.
The IMAP server can use an external security manager (ESM) to authenticate
IMAP clients and to control access to z/VM resources. To use an ESM, specify
:ESM_Enable.Yes in the DTCPARMS file. For more information see Appendix A,
“Using TCP/IP with an External Security Manager” on page 645.
See Chapter 5, “General TCP/IP Server Configuration” on page 31 for further
information on virtual machine definitions. If necessary, consult the TCP/IP
Program Directory for specific DASD storage and user ID requirements that may
be applicable to the IMAP virtual machines.
Step 4: Set Up the IMAP Mailstore SFS File Pool Server and update it’s
System (CP) Directory Entry
The IMAP mailstore is a CMS Shared File System (SFS) file pool server. It is
recommended that this server be a dedicated SFS Mailstore server. Its default
name is IMAP. For details on SFS file pool setup and configuration, see z/VM: CMS
File Pool Planning, Administration, and Operation.
There are some required CP directory statements that must be coded when setting
up the IMAP Mailstore virtual machine. Below is an example of these entries along
with an explanation of their use.
IUCV *IDENT RESANY
OPTION MAXCONN 2000 APPLMON
v The IUCV *IDENT directory statement identifies the IMAP Mailstore SFS server
as a resource owner.
v The OPTION MAXCONN 2000 APPLMON entry will allow up to 2000 APPC
connections to be made to the server. If you expect to have more than 2000
concurrent connections, you should increment the MAXCONN value to match the
expected number of concurrent connections. The MAXCONN values should be
equal for both the mailstore and IMAP servers.
Note: In addition to the above, the IMAP server must be listed on the ADMIN
statement in the Mailstore SFS file pool server’s DMSPARMS file. This will
give the IMAP server authority to access the mailstore SFS server.
ADMIN IMAP
For additional details on SFS file pool administrator authority or on the
DMSPARMS file see z/VM: CMS File Pool Planning, Administration, and
Operation.
Step 5: Update the $SERVER$ NAMES file
The $SERVER$ NAMES file (otherwise known as a private resource registration
file) must be updated and should be on an accessed IMAP virtual machine disk.
Specifically, this file lists any virtual machines that will be using the queue-based
administrative interface (IMAPADM EXEC) to issue commands to the IMAP server
182
z/VM: TCP/IP Planning and Customization
IMAP Server
such as when issuing an IMAPADM ENROLL command to enroll a new user ID.
This private resource registration file has the following format:
:nick.VMIPC
:list.user1 user2 user3...
A sample of this file is shipped as TCPVMIPC SAMPNAME on the TCPMAINT 591
disk and should be copied over to the TCPMAINT 198 disk as $SERVER$ NAMES
when TCP/IP is put into production.
Step 6: Customize the IMAP Configuration file
The IMAP Configuration file defines how the IMAP server is to operate and what
services it provides. See “IMAP Server Configuration Statements” for detailed
information about how to specify entries within this file. A sample of this
configuration file is shipped as IMAP SCONFIG on the TCPMAINT 591 disk. It
should be copied to TCPMAINT 198, customized, and renamed to IMAP CONFIG.
IMAP Server Configuration Statements
This section describes the statements used to configure the IMAP Server.
Within the configuration file, blanks and record boundaries are used to delimit
tokens. All characters to the right of, and including a semicolon are treated as a
comment.
BADFILEID Statement
The BADFILEID statement specifies the user ID to which reader files are
transferred to when the IMAP server cannot deliver them.
BADFILEID userid
Operands
userid
Specifies the user ID to which the IMAP server transfers undeliverable reader
files.
Usage Notes
1. This statement is required and must be specified in the IMAP configuration file.
There is no default for this statement.
2. The IMAP server tags spool files transferred to the BADFILEID with a reason
code to explain why the mail could not be delivered. For more information on
IMAP spool file reason codes see TCP/IP Diagnosis Guide.
ENROLLDEFAULTS Statement
The ENROLLDEFAULTS statement identifies the defaults that will be used when a
new user is enrolled in the IMAP mailstore using the administrative interface
ENROLL command. These defaults are used when the number of blocks and/or
storage group parameters are not provided on an ENROLL command.
Chapter 10. Configuring the IMAP Server
183
IMAP Server
ENROLLDEFAULTS 100 2
ENROLLDEFAULTS blocks storage_group
Operands
blocks
Specifies the default number of blocks to be allocated for a new user. The
minimum value for blocks is 1 and the maximum is 100000. The default is 100
blocks.
storage_group
Specifies the default storage group for a new user to be enrolled in. The
minimum value for storage_group is 2 and the maximum is 32767. The default
is storage group 2.
FILEPOOLID Statement
The FILEPOOLID statement specifies the file pool ID that contatins the IMAP
mailstore.
FILEPOOLID filepoolid
Operands
filepoolid
Specifies the file pool ID that contains the IMAP mailstore. This file pool ID is
contained in the start-up parameter file (DMSPARMS) for the IMAP mailstore
SFS server virtual machine.
Usage Notes
1. This statement is required and must be specified in the IMAP configuration file.
There is no default for this statement.
IDLETIMEOUT Statement
The IDLETIMEOUT statement identifies the amount of time an unauthenticated
connection and an authenticated connection can remain idle (have no activity)
before timing out.
IDLETIMEOUT 60 86400
IDLETIMEOUT unauth_secs auth_secs
Operands
unauth_secs
Specifies the number of seconds that an unauthenticated connection can
184
z/VM: TCP/IP Planning and Customization
IMAP Server
remain idle (have no activity) before timing out. The minimum value for
unauth_secs is 1 and the maximum is 86400. The default value is 60 seconds.
auth_secs
Specifies the number of seconds that an authenticated connection can remain
idle (have no activity) before timing out. The minimum value for auth_secs is
1800 (specified by RFC2060) and the maximum is 86400. The default value is
86400 seconds.
Usage Notes
1. A connection is considered to be authenticated after a successful LOGIN
command is received at the server.
MAILORIGINID Statement
The MAILORIGINID statement specifies the SMTP user IDs from whom mail
arriving in the reader of the IMAP server must originate. Mail that arrives at the
IMAP server that did not originate from a valid user ID is transferred to the user ID
specified in the BADFILEID statement.
MAILORIGINID SMTP
MAILORIGINID userid
Operands
userid
Specifies a user ID from whom mail arriving in the reader of the IMAP server
must originate. Up to 32 user IDs may be specified. If there is no
MAILORIGINID statement, the IMAP server will first default to the
SMTPSERVERID given in the TCPIP DATA file. If there is no SMTPSERVERID,
the default user ID is SMTP.
PORT Statement
The PORT statement causes the IMAP server to listen on a specified TCP
connection port. By convention, port number 143 is usually reserved (in the TCPIP
server configuration file) for the IMAP server to accept IMAP connection requests.
PORT 143
PORT port_number
Operands
port_number
Specifies the port number to which the IMAP server listens. The port number
may be an integer in the range of 1 through 65535. The default is port 143.
Chapter 10. Configuring the IMAP Server
185
IMAP Server
READERTHREADS Statement
The READERTHREADS statement specifies how many threads will be used by the
IMAP server to process incoming reader files.
READERTHREADS 1
READERTHREADS threads
Operands
threads
Specifies the number of threads that the IMAP server will create to process
incoming reader files. The minimum value for threads is 1 and the maximum is
100. The default is one thread.
TIMESTAMP Statement
The TIMESTAMP statement specifies whether or not messages written to the IMAP
server console will be prefixed with a time stamp.
TIMESTAMP ON
TIMESTAMP OFF
Operands
ON
Specifies that messages written to the IMAP server console will be prefixed with
a time stamp. This is the default.
OFF
Specifies that messages written to the IMAP server console will not be prefixed
with a time stamp.
TRACE Statement
The TRACE statement identifies which type of tracing should be active when the
IMAP server is started. Separate TRACE statements may be used to activate
different types of tracing.
TRACE
ALL
CODEFLOW
SOCKLIBCALLS
SOCKETIO
ipaddr
Operands
ALL
Specifies that all tracing types (CODEFLOW, SOCKLIBCALLS, and SOCKETIO
for all IP addresses) should be active when the IMAP server is initialized.
186
z/VM: TCP/IP Planning and Customization
IMAP Server
CODEFLOW
Specifies that module entry/exit tracing should be active when the IMAP server
is initialized.
SOCKLIBCALLS
Specifies that socket library call tracing should be active when the IMAP server
is initialized.
SOCKETIO
Specifies that tracing of all data sent or received on a socket should be active
when the IMAP server is initialized.
ipaddr
Specifies an IP address for which socket I/O tracing should be active when the
IMAP server is initialized. Socket I/O tracing may be active for all IP addresses
or just one IP address.
Step 7: Set Up SMTP to Route Mail to the IMAP server
All incoming mail must come via SMTP: therefore the SMTP server should be
configured to route local mail to the IMAP server. The following steps outline what is
necessary to accomplish this:
v Update the existing SMTP CONFIG file to include the following MAILER
statement:
MAILER userid IMAP
where userid is the userid of the IMAP server.
Once the mail arrives at the IMAP server, the determination is made as to whether
the mail is intended for a registered IMAP user. If it is, the IMAP server will place
the new mail in the user’s INBOX. If the mail is not for a registered IMAP user, then
it is transferred directly to the user’s virtual reader. If the mail cannot be received
into the IMAP mailstore or transferred to the user’s reader, then the spool file is
transferred to the user ID specified in the BADFILEID configuration file statement.
Step 8: Enroll new Users into the IMAP Mailstore
To enroll new users into the IMAP Mailstore simply issue the ENROLL command for
each user. For details on this command’s syntax see “IMAPADM ENROLL
Command” on page 189.
Dynamic Server Operation
IMAP services are administered through a queue based command interface by
using the IMAPADM EXEC. As an example, an administrator could enroll user
JONES1 with the following ENROLL command:
IMAPADM server_id ENROLL JONES1
No special or unique CP directory entries are necessary for the user ID(s) that will
be used to issue administrative commands and to enroll IMAP users. However as
explained in “Step 5: Update the $SERVER$ NAMES file” on page 182, these user
ID(s) must be added to the $SERVER$ NAMES file. For example, if the users
ADMIN1 and ADMIN2 require authorization to use the IMAP administrative
interface, the following VMIPC entry would be used in the $SERVER$ NAMES file:
:nick.VMIPC
:list.ADMIN1 ADMIN2
Chapter 10. Configuring the IMAP Server
187
IMAP Server
IMAP Server Administration Commands
This section describes how to perform various IMAP server administration tasks,
such as enrolling or deleting users or stopping the server.
The IMAPADM EXEC file (provided on the TCPMAINT 592 disk) is used to
communicate with the IMAP server’s administrative interface. This file must be
placed on a disk available to the user ID from which you will issue administrative
commands.
Note: The IMAP server must be running and TCPMAINT 592 must be accessed
before you can issue any of these commands. If the server has not been
autologged, you can start it manually. See “Starting and Stopping TCP/IP
Servers” on page 46.
Starting the Server
The IMAP services are initiated through the IMAPMAIN command. The IMAP
server, however, can be started in the same manner as other TCP/IP servers. For
more information, see “Starting and Stopping TCP/IP Servers” on page 46.
Stopping the Server
To stop the IMAP server, issue the IMAPADM server_id SHUTDOWN command:
imapadm server_id shutdown
Tracing Server Activities
To begin tracing IMAP server activities when the server starts, use the TRACE
operand on the IMAPADM administrative command.
For information about trace output, see the z/VM: TCP/IP Level 430 Diagnosis
Guide.
IMAPADM ALERT Command
The IMAPADM ALERT command specifies alert text that is forwarded to each client
on their next transaction. If no text is given, the current alert is cleared.
IMAPADM server_id ALERT
CLEAR
text
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
CLEAR
Specifies that the current alert should be cleared so that no alert will be active.
text
Specifies the alert text that will be forwarded to each client on their next
transaction.
Usage Notes
1. The alert text will be provided once to every client connection for as long as the
alert remains in effect (until the server is recycled or the alert is cleared).
188
z/VM: TCP/IP Planning and Customization
IMAP Server
IMAPADM CP Command
The IMAPADM CP command causes the given CP command to be executed on the
IMAP server virtual machine. The reply to this administrative command is the return
code of the CP command executed.
IMAPADM server_id CP command
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
command
Specifies the CP command to be executed on the IMAP server virtual machine.
IMAPADM DELETE Command
The IMAPADM DELETE command deletes the given user from the IMAP mailstore.
All files and directories are deleted, including the user’s root directory.
IMAPADM server_id DELETE userid
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
userid
Specifies the user ID to be deleted from the IMAP mailstore.
Usage Notes
1. Deleting users is done synchronously on the IMAP server, so bulk deletes
should not be done at a peak time for client use since their response will be
impacted.
IMAPADM ENROLL Command
The IMAPADM ENROLL command enrolls the given user into the IMAP mailstore.
The IMAP server creates the INBOX directory automatically, and a MAILBOX
INDEX file is created in the user’s root directory to contain a list of the user’s
folders.
IMAPADM server_id ENROLL userid
blocks
storage_group
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
Chapter 10. Configuring the IMAP Server
189
IMAP Server
userid
Specifies the user ID to be enrolled in the IMAP mailstore.
blocks
Specifies the number of blocks to allocate for the new user. The minimum value
for blocks is 0 and the maximum is 2147483647. The default for blocks is the
number of blocks specified in the ENROLLDEFAULTS configuration file
statement.
storage_group
Specifies the storage group for the new user to be enrolled in. The minimum
value for storage_group is 2 and the maximum is 32767. The default for
storage_group is the storage group specified in the ENROLLDEFAULTS
configuration file statement.
Usage Notes
1. Enrolling users is done synchronously on the IMAP server, so bulk enrolls
should not be done at a peak time for client use since their response will be
impacted.
IMAPADM HELP Command
The IMAPADM HELP command displays a list of the available IMAP administrative
interface commands.
IMAPADM server_id
HELP
?
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
IMAPADM MODIFY Command
The IMAPADM MODIFY command changes the storage allocation for a user ID in
the IMAP mailstore.
IMAPADM server_id MODIFY userid
+blocks
-blocks
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
userid
Specifies the user ID whose storage allocation in the IMAP mailstore is to be
changed.
+blocks
−blocks
Indicates the number of blocks to be added to or subtracted from the file space
allocation for the specified user in the mailstore. The value of blocks can range
from 1 through 2147483647.
190
z/VM: TCP/IP Planning and Customization
IMAP Server
IMAPADM SHUTDOWN Command
The IMAPADM SHUTDOWN command initiates IMAP server shutdown processing.
IMAPADM server_id SHUTDOWN
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
Usage Notes
1. If the IMAP server is disconnected, the server will additionally be logged off;
otherwise the server will remain logged on.
IMAPADM STARTRDR Command
The IMAPADM STARTRDR command causes the IMAP server to create an
additional thread for processing incoming reader files.
IMAPADM server_id STARTRDR
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
IMAPADM STATS Command
The IMAPADM STATS command displays IMAP server statistics. These statistics
include the following:
v
v
v
v
v
a
a
a
a
a
count
count
count
count
count
of
of
of
of
of
each IMAP protocol command issued
new mail accepted
new mail rejected
connections accepted
connections rejected
IMAPADM server_id STATS
RESET
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
RESET
Specifies that the IMAP server is to reset IMAP server counts to zero after the
display of current statistics.
Chapter 10. Configuring the IMAP Server
191
IMAP Server
IMAPADM TRACE Command
The IMAPADM TRACE command enables, disables, or queries IMAP server tracing.
IMAPADM server_id TRACE
QUERY
ALL
CODEFLOW
SOCKLIBCALLS
SOCKETIO
ipaddr
ON
OFF
Operands
server_id
Specifies the user ID of the IMAP server virtual machine.
QUERY
Queries the current IMAP server trace settings.
ALL ON|OFF
Enables or disables all IMAP server tracing, which includes CODEFLOW,
SOCKLIBCALLS, and SOCKETIO tracing.
CODEFLOW ON|OFF
Enables or disables module entry/exit tracing.
SOCKLIBCALLS ON|OFF
Enables or disables socket library call tracing.
SOCKETIO ON|OFF
Enables or disables tracing of all data sent or received on a socket. If no IP
address is given, all IP addresses will be traced.
ipaddr
Specifies an IP address for which socket I/O tracing will be active. Socket I/O
tracing can be active for all IP addresses or just one IP address.
192
z/VM: TCP/IP Planning and Customization
Chapter 11. Configuring the Kerberos Server
This chapter describes how to configure and customize the Kerberos Authentication
System for TCP/IP.
The Kerberos system in TCP/IP consists of the following:
v Kerberos database
v Kerberos authentication server
v Remote database administrator server
v Local database administrator utilities
v Remote database administrator utility
v Client utilities.
The Kerberos authentication server provides a way for authenticated users to prove
their identity to other servers in a network. The authentication server uses the
Kerberos database to verify that the client making the request is, in fact, the client
named in the request. The authentication server runs in the VMKERB virtual
machine.
The Kerberos remote database administration server allows you to modify the
Kerberos database remotely using the KADMIN command. The Kerberos
administration server runs in the ADMSERV virtual machine.
Local Kerberos database functions, such as creating or deleting the database, are
performed by stopping the administration server and issuing the necessary
commands at the CMS command line.
All changes made to the Kerberos database are made by the ADMSERV virtual
machine because the database resides on a CMS minidisk and only one virtual
machine can have write access to the minidisk at any one time. The authentication
server accesses the Kerberos database in read mode.
Utilities available to Kerberos clients are described in TCP/IP User’s Guide.
For more information, about the application programming interface, see TCP/IP
Programmer’s Reference.
Kerberos Name Structures
Before you customize your Kerberos Authentication System, you should be familiar
with the structure of a Kerberos name. A Kerberos name consists of the following
three parts.
Name
Description
principal name
Specifies the unique name of a user (client) or
service.
instance
Indicates a label that is used to distinguish among
the variations of the principal name. An instance
allows for the possibility that the same client or
service can exist in several forms that require
distinct authentication.
© Copyright IBM Corp. 1987, 2002
193
Kerberos Server
For users, an instance can provide different
identifiers for different privileges. For example, the
admin instance provides special privileges to the
users assigned to it.
For services, an instance usually specifies the host
name of the machine that provides the service.
realm
Specifies the name of an administrative entity. The
realm identifies each independent Kerberos site.
The principal name and instance are qualified by
the realm to which they belong, and are unique only
within that realm. The realm is commonly the
domain name.
Note: You must express the realm as a name
rather than an address number. For
example, use real.endicott.ibm.com rather
than 9.130.0.0.
Configuring the Authentication and Remote Administration Servers
Kerberos Servers Configuration Steps:
1. Update PROFILE TCPIP
2. Define the Kerberos services in ETC SERVICES
3.
4.
5.
6.
7.
Update DTCPARMS for the authentication server
Update DTCPARMS for the remote database administration
Create and update the Kerberos system files
Build the Kerberos database
Store the master key
8. Start the Kerberos servers
Step 1: Update PROFILE TCPIP
Include VMKERB and ADMSERV in the AUTOLOG statement to automatically start
the VMKERB and ADMSERV virtual machines when TCPIP is invoked. Verify that
the following statements have been added to PROFILE TCPIP.
AUTOLOG
VMKERB
ADMSERV
0
0
Kerberos requires that ports 750 and 751 be reserved for it. Port 750 is used by the
authentication server. Port 751 is used by the administration server. The following
port entries must be in PROFILE TCPIP:
PORT
750
750
751
751
TCP
UDP
TCP
UDP
VMKERB
VMKERB
ADMSERV
ADMSERV
Step 2: Update ETC SERVICES
Before you set up the Kerberos system, you must define the Kerberos services.
Verify that the following lines have been added to the ETC SERVICES file on the
client code disk, TCPMAINT 592:
194
z/VM: TCP/IP Planning and Customization
Kerberos Server
kerberos
kerberos
kerberos_master
kerberos_master
sample
sample
750/tcp
750/udp
751/tcp
751/udp
906/udp
906/tcp
You should compare this list to the port assignments in the PROFILE TCPIP file to
ensure that there are no conflicts with any other service.
The entries for service sample enable you to run the Kerberos verification programs.
Step 3: Update DTCPARMS for the Authentication Server
The default TCP/IP configuration runs the Kerberos authentication server in the
VMKERB virtual machine. The TCP/IP server initialization program searches for the
configuration definitions for each server.
Note: You should modify the DTCPARMS file for the authentication server if you:
v Change the parameters passed to the VMKERB command.
v Change the user ID of the virtual machine that receives the VMKERB
console log.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Step 4: Update DTCPARMS for the Administration Server
The default TCP/IP configuration runs the Kerberos administration server in the
ADMSERV virtual machine. The DTCPARMS file searches for the server
configuration definitions for each server.
Note: You should modify the DTCPARMS file for the administration server if you:
v Change the parameters passed to the ADM_SERV command.
v Change the user ID of the virtual machine that receives the ADM_SERV
console log.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used. For more information about the DTCPARMS file,
customizing servers, and server profile exits, see Chapter 5, “General TCP/IP
Server Configuration” on page 31.
Step 5: Create and Update the Kerberos System Files
This step describes the files that you must create and update for the Kerberos
system.
Kerberos Configuration File
The Kerberos configuration file KRB CONF identifies hosts that are running the
Kerberos authentication server.
The format of the file is:
realm
realm host_name
realm host_name admin server
Chapter 11. Configuring the Kerberos Server
195
Kerberos Server
The contents of the KRB CONF file are case-sensitive.
Some examples of the file format are:
univ.educ.chem
univ.other.dept joanpc
univ.educ.math chrispc admin server
The first line defines the local realm to which this VM host belongs. Each
subsequent line specifies a remote realm and the host where the Kerberos server is
running in that realm.
In our example, the third line lists admin server to indicate that the host provides a
remote administration database server. The host_name that you specify must also
be defined in your Domain Name Server or in the HOSTS LOCAL file.
The KRB CONF file must be made available to client applications. A sample of this
configuration file is provided as KRB SCONFIG on the TCPMAINT 592 minidisk.
Your customized configuration file should be copied and maintained on this same
minidisk with a file identifier of KRB CONF.
Note: You cannot use dotted decimal IP addresses, such as 9.130.57.21, in the
KRB CONF file.
Kerberos Remote Administrator Authorization Files
To authorize the remote database administrator to add, view, or modify database
entries, you must create several remote administrator authorization files. These
files, and their corresponding sample equivalents, are:
[email protected] ADD
Lists remote administrators that may add new
principals. This file is provided in sample form as
[email protected] SAMPAUTH.
[email protected] GET
Lists remote administrators that may view principal
entries. This file is provided in sample form as
[email protected] SAMPAUTH.
[email protected] MOD
Lists remote administrators that may change a
principal’s password. This file is provided in sample
form as [email protected] SAMPAUTH.
The sample authorization files are provided on the TCPMAINT 591 minidisk.
However, your customized authorization files must be accessed by the remote
database administration server (ADMSERV); copy and maintain your customized
files on the ADMSERV 191 disk.
Your Kerberos principal name must be in these files if you want to use the KADMIN
command to remotely administer the Kerberos databases. Without an entry in one
of these files, you will only be able to change your admin instance password.
The format of these files is:
administrator’[email protected]
The instance must be admin and realm is usually the domain name. The contents
of these files are case-sensitive.
These files can contain multiple entries in the same format.
Example: [email protected]
196
z/VM: TCP/IP Planning and Customization
Kerberos Server
Step 6: Build the Kerberos Database
You must enter Kerberos commands from the ADMSERV user ID to create and use
the Kerberos database before you can start the Kerberos remote administration
server and Kerberos authentication server.
Follow these steps to create the Kerberos database:
1. Issue the KDB_INIT command to create and initialize the Kerberos database
files.
2. The system prompts you for the local realm.
At the realm prompt, enter the name of the realm where the Kerberos database
resides. This is the local realm specified in the first line of the KRB CONF file.
The default is YOUR_KRB.RE.ALM.
3. The system prompts you for the master key.
4. At the prompt, enter the master key.
You need the master key to manage the Kerberos database. If the Kerberos
database file already exists, the system indicates that the file already exists.
Use KDB_DEST to destroy the existing database file. See “KDB_DEST
Command” on page 205 for more information.
KDB_INIT will create two database files:
v PRINCPL DAT
v PRINCPL IDX
See “KDB_INIT Command” on page 207 for more information.
Step 7: Store the Master Password
The following steps describe how to store the master key so that the Kerberos
authentication server will not have to prompt you for the master password.
1. Issue the KSTASH command.
The system prompts you for the master password.
2. Enter the master password at the password prompt.
See “KSTASH Command” on page 209 for more information.
Step 8: Start the Kerberos Servers
This section describes how to start the following Kerberos servers:
v Authentication server
v Remote database administration server.
Start the Kerberos Authentication Server
Autolog or log on user ID VMKERB. The Kerberos server will start.
Maintaining the Log: When the authentication server starts, it creates a log file
called KERBEROS LOG. All transactions to the Kerberos authentication server are
recorded in this file. Because Kerberos appends to the file continuously, you should
periodically monitor the size of the KERBEROS LOG file, erasing or editing the log
if necessary.
Start-Up Parameters: You can use these options when starting the Kerberos
Authentication Server:
−a max age
Set the max age (in seconds). Max age must be between one hour
(3600 seconds) and three days (259200 seconds).
Chapter 11. Configuring the Kerberos Server
197
Kerberos Server
−l filename
Specifies an alternate log file (default is KERBEROS LOG).
−m
Run manually; prompt for master key.
−n
Don’t check the max age.
−r real m
Specify a real m name.
−s
Set parameters to save server defaults.
Stopping the Authentication Server: The authentication server must be stopped
manually using the HX command.
Start the Kerberos Remote Administration Server
Autolog or log on user ID ADMSERV. The remote administration server will start.
Once the remote database administration server is started, you can use the
KADMIN command on a remote host to add, retrieve, or modify the Kerberos
database. See “KADMIN Command” on page 204 for more information about the
KADMIN command.
Maintaining the Log: When the remote database administration server starts, it
creates a log file called ADM_SERV SYSLOG. All transactions to this server are
recorded in this file. Because Kerberos appends to the file continuously, you should
periodically monitor the size of the ADM_SERV SYSLOG file, erasing or editing the
log if necessary.
Start-Up Parameters: You can use these options when starting the Kerberos
Remote Administration Server:
−d database_name
Specifies an alternate dtatbase.
−f filename
Specify an alternate syslog file (default is
ADMSERV SYSLOG).
−h
Operand usage help.
−n
Run manually; prompts for master key.
−r real m
specify a real m name.
Stopping the Remote Database Administration Server: The remote database
authentication server must be stopped manually using the HX command.
Setting Up a Kerberos Service or Client Application
Kerberos services and client applications can be developed by referencing the
[email protected] and [email protected] programs, which are provided on the client code
disk, TCPMAINT 592.
Setting Up a Kerberos Service Application
Use the following steps to set up a service application that uses Kerberos functions:
1. Register the service with the Kerberos database locally using KDB_EDIT or
remotely using the KADMIN function. The service name is used as the principal
and the host name where the service is running is used as the instance. For
example, a Kerberos-enabled FTP server on the host chrispc would be
registered as:
ftp.chrispc
198
z/VM: TCP/IP Planning and Customization
Kerberos Server
You should also provide a password for the service you register. This password
is converted to the key for the service.
2. After you register all the services provided by the same host, enter the
command:
EXT_SRVT host_name
For example, EXT_SRVT chrispc generates the CHRISPC SRVTAB file. The
server’s keys will be stored in this file.
3. Transfer the key file to the host providing the services (chrispc in our example).
v If the host providing the services is VM, copy the key file to the client code
disk, TCPMAINT 592, as ETC SRVTAB.
v If the host providing the services is MVS, copy the key file to
service_id.ETC.SRVTAB,
v If the host providing the services is OS/2®, DOS, UNIX, or AIX, copy the key
file to SRVTAB in the ETC directory.
4. Define the service name and assign port numbers in the ETC SERVICES file on
the client code disk, TCPMAINT 592.
5. Start the service program on the host providing the service.
Setting Up a Client Application
The following steps describe how to set up a client application that uses Kerberos
functions:
1. The database administrator should register the client with the Kerberos
database locally using KDB_EDIT or remotely using the KADMIN function.
2. Verify that the KRB CONF file on the client code disk, TCPMAINT 592, contains
a valid entry. For more information see “Step 5: Create and Update the
Kerberos System Files” on page 195.
3. Issue the KINIT command to get an initial ticket. The ticket is saved in the TMP
TKT0 file.
4. Start the Kerberos client application.
Use the KLIST command to see the ticket in the client’s ticket file. The TMP TKT0
file contains tickets used by client applications for different servers.
You can use the KDESTROY command to delete the ticket file.
See TCP/IP User’s Guide for the format and description of the parameters of the
KINIT, KLIST, and KDESTROY commands.
Verifying the Kerberos Configuration
TCP/IP Level 430 provides a sample application client program (SAMPLE_C) and a
sample application server program (SAMPLE_S) that can be used to verify your
Kerberos installation and configuration.
This section shows an example of how to set up, run, and verify a Kerberos
system.
Chapter 11. Configuring the Kerberos Server
199
Kerberos Server
Steps to verify Kerberos:
1. Set up the environment
2. Register the sample service and the user
3. Generate the key file for the sample service
4. Transfer the service key file to the server
5. Start the sample server
6. Get the initial ticket
7. Run the sample client program
Two additional user IDs are required on your VM system for verification of
Kerberos. One user ID will run the sample server, the other the sample client. Both
must have access to the client code disk, TCPMAINT 592, and have the C
language runtime library globaled.
In this example, the name vm_host is used to represent the name of your VM host.
Step 1: Set Up the Environment
Follow steps 1 through 8 in the configuration process.
Start the Kerberos authentication server as described in “Start the Kerberos
Authentication Server” on page 197.
Note: If you fail to start the authentication server, error messages will be seen in
the output to the console.
Step 2: Register the Sample Service and the User
The following steps describe how to register the sample service and user with
Kerberos. The sample client program assumes that the service instance name is
the name of the host that is running the sample service application.
Log on to ADMSERV, stop the remote administration server if it is running, and
issue the KDB_EDIT command. The prompts and responses are in Table 16 on
page 201.
200
z/VM: TCP/IP Planning and Customization
Kerberos Server
Table 16. Adding a Service and a Client to the Kerberos Database
Prompt
Response
Enter Kerberos master key:
krbpass
Principal name:
sample
Instance:
vm_host
<not found>, Create [ y ] ?
<enter>
New Password:
sam
Verifying, please re-enter New Password:
sam
Expiration date?
<enter>
Max ticket lifetime?
<enter>
Attributes?
<enter>
Edit O.K.
Principal name:
user1
Instance:
<enter>
<not found>, Create [ y ] ?
<enter>
New Password:
use
Verifying, please re-enter New Password:
use
Expiration date?
<enter>
Max ticket lifetime?
<enter>
Attributes?
<enter>
Edit O.K.
Principal name:
<enter>
See “KDB_EDIT Command” on page 206 for more information about the KDB_EDIT
command.
Note: Service refers to the host name on which SAMPLE_S is to be run.
Step 3: Generate the Key File for the Sample Service
The following steps describe how to generate the key file for the sample service.
1. On the ADMSERV user ID, enter EXT_SRVT vm_host
The system prompts you for a password.
2. Enter krbpass at the password prompt.
3. A key file vm_host SRVTAB is created that contains the keys for all services
that use Kerberos on your VM system.
See “EXT_SRVT Command” on page 203 for more information about the
EXT_SRVT command.
Step 4: Transfer the Key File to the Server
Copy the vm_host SRVTAB to the client code disk, TCPMAINT 592, as ETC
SRVTAB.
Chapter 11. Configuring the Kerberos Server
201
Kerberos Server
Step 5: Start the Sample Server
The following describes how to start the sample server, SAMPLE_S.
1. Log on to the sample server user ID.
2. Access the client code disk, TCPMAINT 592.
3. Global the C runtime library.
4. Run SAMPLE_S to start the sample Kerberos service application.
Note: SAMPLE_S will run until stopped with HX.
Step 6: Get the Initial Ticket
The following steps describe how you get the initial ticket from the Kerberos
authentication server.
1. Log on to the sample client user ID.
2. Access the client code disk, TCPMAINT 592.
3. Global the C runtime library.
4. Issue the KINIT command to get the initial ticket.
The system prompts you for your Kerberos name.
5. Enter user1 at the Kerberos name prompt.
The system prompts you for a password.
6. Enter use at the password prompt.
If the KINIT command is successful, the TMP TKT0 ticket file is created. If the
KINIT command is not successful an error message is issued.
You can use the KLIST command to view the initial ticket.
See the TCP/IP User’s Guide for the format and description of the parameters of
the KINIT and KLIST commands.
Step 7: Run the Sample Client Program
To start the sample Kerberos client program, enter
SAMPLE_C vm_host 100
on the sample client user ID.
If all parts of your Kerberos system (environment, Kerberos database, Kerberos
authentication server, and client and service applications) are set up correctly, a
message is displayed as a return from the SAMPLE_S program. The following is an
example of the message that might be displayed:
The server says:
You are [email protected] (local name
user1), at address 9.67.43.74, version VERSION X, cksum 100.
202
z/VM: TCP/IP Planning and Customization
Kerberos Server
Administrative Commands for the Kerberos Database
Table 17 shows the Kerberos commands you can use to create and administer a
Kerberos database.
Table 17. Summary of Kerberos Database Commands
Command
Description
Page
EXT_SRVT
Generates key files for specified instances from ADMSERV user ID
203
KADMIN
Adds, retrieves, or modifies the Kerberos database remotely from
any ID
204
KDB_DEST
Erases Kerberos database files from ADMSERV user ID
205
KDB_EDIT
Registers users to the Kerberos database from ADMSERV user ID
206
KDB_INIT
Builds and formats the Kerberos database from ADMSERV user ID
207
KDB_UTIL
Loads or dumps the Kerberos database from ADMSERV user ID
208
KSTASH
Stores the master key
209
EXT_SRVT Command
Use the EXT_SRVT command to generate a key file for instances.
A key file contains all the service keys associated with the servers running with the
same instance. An instance is usually the host name where the services are
provided. The service keys in the key files are used by the servers to verify whether
a ticket presented by a user is legal.
You should rename this file and send it to a server. It contains a copy of the service
keys and is used for authentication of a client’s request by the remote server.
EXT_SRVT instance
Operands
instance
The host name for which a key file is to be generated.
Examples
The system searches through the Kerberos database entries for each of the
specified instances. For example, if you enter EXT_SRVT INST1, the system
searches through the Kerberos database entries for the specified instance of INST1.
When the system finds INST1, a key file INST1 SRVTAB is generated.
Chapter 11. Configuring the Kerberos Server
203
Kerberos Server
EXT_SRVTINST1 INST2
Enter Kerberos master key. <krb_pw>
Current Kerberos master key version is
Master Key entered. BEWARE!
generating INST1 SRVTAB
generating INST2 SRVTAB
Usage Notes
v Multiple instances can be specified on the same command line to generate
multiple key files.
v You can use the KLIST -srvtab command to see the contents of a key file. See
TCP/IP User’s Guide for the usage of the KLIST command.
v Copy each instance SRVTAB key file to the corresponding instance’s host, and
rename the key file as required by the host. See “Setting Up a Kerberos Service
Application” on page 198 for more information on the required naming.
v If the instance name is longer than eight characters, the file name of the
SRVTAB file generated is the first eight characters of the instance name. If the
instance name results in a file name that is not valid for CMS, the file name TMP
is used.
KADMIN Command
Use the KADMIN command to add, get, or modify a Kerberos database.
You can only use this command for a Kerberos user with instance as null. In
addition, as a remote administrator with instance as admin, you can change your
own password.
KADMIN
−m
−r real m
−u admin_name
Operands
−m
Allows multiple administrative requests to be serviced with only one
entry of the administration password.
−r real m
Specify a real m name.
−u admin_name
Specify an admin name.
Examples
After issuing the KADMIN command, you will be prompted for your user ID. When
you enter the administrator’s principal_name, the following message is displayed:
Welcome to the Kerberos Administration Program, Version X
Type help if you need it.
admin:
At the admin: prompt, you can enter ? to list the available subcommands.
204
z/VM: TCP/IP Planning and Customization
Kerberos Server
Usage Notes
v In order to use the KADMIN command you must:
1. Have the remote administration server, ADMSERV, running on the machine
that contains the Kerberos database when you issue the command.
2. Register the remote Kerberos administrator, although no special user ID
name is required for running KADMIN. You can register with the Kerberos
database using KDB_EDIT from the ADMSERV user ID. Make the Kerberos
instance be admin.
3. Have your Kerberos name in the remote administrator authorization files to
perform the corresponding database operations.
v You can use the following subcommands once you are in the Kerberos
Administration program. Commands which examine or modify the Kerberos
database require that you enter your admin instance password at the Admin
password prompt.
add_new_key principal_name
ank principal_name
Registers principal_name with the Kerberos database.
change_admin_password
cap
Changes your admin instance password.
change_password principal_name
cpw principal_name
Changes the Kerberos password for principal_name.
exit
Ends the KADMIN session with the Kerberos database.
Alternatively, you can use the quit subcommand.
get_entry principal_name
get principal_name
Displays the entry for principal_name from the Kerberos
database.
HELP command name
Displays help messages for KADMIN. If you enter this
subcommand without an argument, a general help message is
displayed.
list_requests
lr
?
quit
Displays a list of possible subcommands.
Ends the KADMIN session with the Kerberos database.
Alternatively, you can use the exit subcommand.
Context
v “Kerberos Remote Administrator Authorization Files” on page 196
v “KDB_EDIT Command” on page 206
KDB_DEST Command
Use the KDB_DEST command to erase the PRINCPL DAT and PRINCPL IDX files.
Chapter 11. Configuring the Kerberos Server
205
Kerberos Server
KDB_DEST
Operands
The KDB_DEST command has no operands.
KDB_EDIT Command
Use the KDB_EDIT command to register users and services to the Kerberos
database.
The system prompts you for the Kerberos master key and for information about the
user and service that you want to add.
KDB_EDIT
Operands
The KDP_EDIT command has no operands.
Examples
This example shows how to register a Kerberos user or service using the
KDB_EDIT command. After issuing the KDB_EDIT command:
1. The system prompts you for the Kerberos master key.
Opening database...
Enter Kerberos master:password:<krb_pw>
Enter the valid master key at the master key prompt.
2. The system prompts you for the principal name.
Enter the user name or service name at the principal name prompt.
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Previous or default values are in [brackets]
enter return to leave the same, or new value.
Principal name: <username>
3. The system prompts you for the instance.
Instance: <enter>
v If you are registering a
v If you are registering a
v If you are registering a
host where the service
206
z/VM: TCP/IP Planning and Customization
user, enter a null instance.
remote administrator, enter admin.
service, at the instance prompt, enter the name of the
resides.
Kerberos Server
The system asks for more information, depending on whether the user or the
service already exists in the database.
If the user or the service already exists in the database, the system asks you if
you want to change the password.
<Not found>, Create [ y ] ? <y>
Principal: username, Instance: , kdc_key_ver: 1
password: <userpassword>
Verifying, please reenter
New Password: <userpassword>
If the user or the service does not exist in the database, the system prompts
you for the expiration date, ticket lifetime for the user or services, and the
attribute.
Principal’s new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2020-01-01 ] ? <enter>
Max ticket lifetime (*5 minutes) [ 255 ] ? <enter>
Attributes [ 0 ] ? <enter>
Defaults are provided for these prompts. If you want to use the default values,
enter a null character. Otherwise, enter the desired value.
To enter a null character, just press the ENTER key.
The following message is displayed if the user or service is registered:
Edit O.K.
Principle name: <username>
4. The system prompts you for the next entry.
Enter a null character at the principal name prompt to exit the registration
process or repeat the process to register the next Kerberos user name or
Kerberos service name that you want to establish.
You must inform the user of the Kerberos name and password that you assign to
that user.
Usage Notes
An instance is usually the host name where the services are provided. A user’s
instance and a service’s instance are usually specified by the following rules:
v A user’s instance is optional. Users with privileges (for example, the remote
system administrator) should register with an instance of admin. Users without
privileges have an instance of null.
v A service’s instance is usually the host name where the service is running.
Context
v “KDB_UTIL Command” on page 208
KDB_INIT Command
Use the KDB_INIT command to create and format the Kerberos database.
Chapter 11. Configuring the Kerberos Server
207
Kerberos Server
KDB_INIT
Operands
The KDP_INIT command has no operands.
Examples
After issuing the KDB_INIT command, the system will prompt you for the local
realm. At the realm prompt, enter the name of the realm where the Kerberos
database resides. This is the local realm specified in the first line of the KRB CONF
file. The default is YOUR_KRB.RE.ALM.
Then the system will prompt you for the master key. At the prompt, enter the master
key.
Usage Notes
KDB_INIT creates two database files:
v PRINCPL DAT
v PRINCPL IDX
KDB_UTIL Command
Use the KDB_UTIL to dump or load the Kerberos database, or to change the
Kerberos database master password.
KDB_UTIL
dump
load
new_master_key
filename.filetype
Operands
dump
Dump the contents of the Kerberos database to filename filetype A. The master
password is contained within the file, so this file must be kept private.
load
The contents of an existing Kerberos database are replaced with the contents
of filename filetype with the exception of the default entry which is saved from
the existing database.
new_master_key
Changes the master password associated with an existing Kerberos database
dump file filename filetype.
filename.filetype
Specifies the name of the file into which the database is dumped or from which
the database is loaded, or that is to have its associated master password
changed.
208
z/VM: TCP/IP Planning and Customization
Kerberos Server
Examples
The following example uses the KDB_UTIL command to examine the contents of a
database containing a single principal, alan. The database was dumped to a file
named MYKERB DB with the command:
KDB_UTIL dump mykerb.db
The file MYKERB DB contains the following five records:
alan * 255 1 1 0 d742e777 820b480b 200001010459 199605281730 * *
changepw kerberos 255 1 1 0 fe3ac96d e518e3d3
200001010459 199605281726 db_creation *
default * 255 1 1 0 0 0 200001010459 199605281726 db_creation *
krbtgt endicott.ibm.com 255 1 1 0 19cc03b dbeaf5db
200001010459 199605281726 db_creation *
K M 255 1 1 0 b84c136f 51d511c 200001010459 199605281726 db_creation *
Note: Each line is a database entry. The four lines that contain the string
db_creation must not be deleted.
A modified version of the file may be reloaded with the command:
KDB_UTIL load mykerb.db
To change the master password associated with the file, use the command:
KDB_UTIL new_master_key mykerb.db
Usage Notes
v You can edit the dumped file using a system editor to delete entries from the
database. Certain information on each record is encrypted, so you cannot add or
change any records; you must use KDB_EDIT instead. After deleting records, the
database may be reloaded using the KDB_UTIL load function.
v The master password specified when the Kerberos authentication or
administration server is started must the same as the master password that is
associated with the loaded database file.
v To
1.
2.
3.
4.
5.
change the master password of the current Kerberos database:
Dump the database using KDB_UTIL dump
Change the master password using KDB_UTIL new_master_key
Reload the database using KDB_UTIL load
Store the new master password using KSTASH
Restart the Kerberos servers
KSTASH Command
Use the KSTASH command to create the ETC K file. This file is needed if you do
not want to enter the Kerberos master password manually and do not want to place
the master password in clear text in a Kerberos authentication or administration
server profile exit.
KSTASH
Operands
The KSTASH command has no operands.
Chapter 11. Configuring the Kerberos Server
209
Kerberos Server
Usage Notes
You will be prompted for the Kerberos master key. The master key is
case-sensitive.
210
z/VM: TCP/IP Planning and Customization
Chapter 12. Configuring the LPD Server
The line printer daemon (LPD) virtual machine serves client requests to print a file.
To configure the LPD server virtual machine, you must perform the following steps:
LPD Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the LPD server.
3. Customize the LPD CONFIG file.
Dynamic Server Operation
The LPD server provides a VM Special Message (SMSG) interface that allows you
to perform server administration tasks through a set of privileged commands. For
more information see “SMSG Interface to the LPD Server” on page 220.
Step 1: Update PROFILE TCPIP
Include the LPD server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The LPD server is then automatically started when
TCPIP is initialized. The IBM default user ID for this server is LPSERVE. Verify that
the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
LPSERVE
0
The LPD server requires port TCP 515 to be reserved for it. Verify that the following
statement has been added to your TCPIP server configuration file as well:
PORT
515
TCP LPSERVE
; LPD Server
Step 2: Update the DTCPARMS File
When the LPD server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the LPD server are:
:Nick.LPSERVE
:Parms.
:ESM_Enable.
:ESM_Validate.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the LPD server if you:
v Use a configuration file other than LPD CONFIG.
v Activate tracing using the TYPE and TRACE parameters.
v Want to display the version identifier.
© Copyright IBM Corp. 1987, 2002
211
LPD Server
LPD Command
LPD services are initiated using the LPD command:
LPD
(
LPD
filename
CONFIG
filetype
*
filemode
TRACE
TYPE
VERSION
Specify LPD command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
filename
The file name of the LPD server configuration file. The default file name is LPD.
filetype
The file type of the configuration file. The default file type is CONFIG.
filemode
The file mode of the configuration file. The default file mode is *.
TRACE
Causes a detailed trace of activities within the server to be recorded in the
server console. Detailed tracing can also be activated by including the DEBUG
statement in the LPD configuration file, or through use of the TRACE ON
SMSG command.
TYPE
Causes a minimal trace of activities within the server to be recorded in the
server console. Only significant events, such as the receipt of a job for printing,
are recorded.
Note: The TRACE OFF SMSG command can be used to terminate event recording
activated by the TRACE and TYPE operands.
VERSION
Causes LPD program version information to be written to the LPD server
console.
If VERSION is the only operand specified, the LPD command terminates
immediately after program version information is displayed.
Step 3: Customize the LPD CONFIG File
The LPD configuration file, LPD CONFIG, defines the services (printers and
punches) supported and used by the LPD server. See “LPD Configuration File
Statements” on page 213 for detailed information about how to specify entries within
this file. A sample configuration file is provided as LPD SCONFIG on the
212
z/VM: TCP/IP Planning and Customization
LPD Server
TCPMAINT 591 disk. Your customized LPD configuration file should be copied to
the TCPMAINT 198 minidisk as LPD CONFIG.
Defining LP Services
Use the following statements to define LPD services. Each service description
begins with a SERVICE statement that must be followed by either a LOCAL,
REMOTE, or RSCS type of service statement.
Additional service attributes can be defined using the statements described in
“Optional Service Statements” on page 217.
LPD Configuration File Statements
Specify LPD server parameters in the LPD configuration file as described in this
section. Keep in mind the following when configuration statements are specified:
v Tokens are delimited by blanks and record boundaries.
v All characters to the right of, and including, a semicolon are treated as
comments.
v Case is significant for the service, remote and filters statements.
DEBUG Statement
The DEBUG statement causes a detailed trace of activities within the server to be
recorded in the server console.
DEBUG
The DEBUG statement has no operands.
Note: The TRACE OFF SMSG command can be used to terminate event recording
activated by the DEBUG statement.
OBEY Statement
The OBEY statement identifies virtual machine user IDs that are authorized to use
the SMSG interface to the LPD server.
OBEY user_id
Operands
user_id
A user ID authorized to use the SMSG interface.
The number of user IDs that can be specified is limited only by the record
length of the configuration file and the amount of virtual storage available in the
Chapter 12. Configuring the LPD Server
213
LPD Server
LPD server virtual machine for construction of the applicable table. The OBEY
statement may be repeated if necessary.
SMTP Statement
The SMTP statement identifies the SMTP server virtual machine defined for the
local z/VM host. This statement is used in conjunction with the FAILEDJOB service
statement. When an attempted print job fails and the FAILEDJOB MAIL statement is
defined for a service, the LPSERVE virtual machine will generate a notice of the
failure and send this notice to the user ID identified by the SMTP statement; this
SMTP server then forwards this notice to the user that submitted the print request.
SMTP server_id
Operands
server_id
The user ID of the SMTP virtual machine. If this statement is omitted, the
default is SMTP.
SERVICE Statement
The SERVICE statement specifies a service for which connections are accepted
and acknowledged.
SERVICE name
PRINTER
PUNCH
NONE
Operands
name
The name of the service. The service name must be 1 to 8 characters in length.
Only characters that are permitted in CMS file names are valid. This value is
case sensitive.
PRINTER
Indicates that the service is a printer.
PUNCH
Indicates that the service is a punch device.
NONE
Not currently in use.
Type of Service Statements
The LOCAL, REMOTE, and RSCS statements described in this section are used to
identify the manner in which files directed to the LPD server are processed. One of
these type of service statements must be defined for each SERVICE statement that
is included in the LPD server configuration file.
214
z/VM: TCP/IP Planning and Customization
LPD Server
LOCAL Statement
The LOCAL statement specifies that files sent to the corresponding service are
written to the local z/VM printer or punch.
LOCAL
CLASS=A
CLASS=class
SPOOL=options
TAG=tagtext
Operands
CLASS=class
Defines a spool print class. Valid values are A-Z and 0-9.
TAG=tagtext
Defines information you want to associate with the specified spool file, such as
locid, userid, and priority options. Do not include DEV or FILE operands as part
of the tagtext. If specified, TAG=tagtext must be the last operand present for
this configuration statement.
SPOOL=options
Defines operands for the CP SPOOL command. Any valid CP SPOOL
command option may be specified. If specified, SPOOL=options must be the
last operand present for this configuration statement.
Note: No case translation is performed on the values associated with the above
operands. These operands and values are processed without modification,
with respect to case. For more information on controlling LPD services from
another operating system, see the TCP/IP User’s Guide.
REMOTE Statement
The REMOTE statement specifies that files sent to the corresponding service are
forwarded to a specified remote printer.
REMOTE [email protected]
Operands
[email protected]
A destination printer at a specified internet node host.
The printer portion of this operand is case sensitive.
RSCS Statement
The RSCS statement specifies that files sent to the corresponding service are
delivered to RSCS.
Chapter 12. Configuring the LPD Server
215
LPD Server
RSCS
CLASS=A
CLASS=class
DEST=localid IDENTIFIER=SYSTEM PRIORITY=50
TAG=tagtext
DEST=localid
DEST=node
IDENTIFIER=SYSTEM
PRIORITY=50
IDENTIFIER=identinfo
PRIORITY=nn
SPOOL=options
OTHERS=tagoptions
Operands
CLASS=class
Defines a spool print class. Valid values are A-Z and 0-9.
DEST=node
Defines the NJE (RSCS) node name assigned to a printer, punch or host. If no
value is specified, the default is the local system.
TAG=tagtext
Defines information you want to associate with the specified spool file, such as
locid, userid, and priority options. Do not include DEv or FIle operands as part
of the tagtext. If specified, TAG=tagtext must be the last operand present for
this configuration statement.
IDENTIFIER=SYSTEM
When node represents a host, SYSTEM indicates the supplied file is to be
printed or punched using any available device. Otherwise, the file is directed to
the specific printer or punch.
IDENTIFIER=identinfo
Provides information about where (on the destination node) the supplied file is
to be directed. Identifier information identinfo can be specified using one of the
following:
JOB
indicates the supplied file is to be submitted to host node for subsequent
interpretation and execution. JOB is usually used to submit JCL to an MVS
or VSE host.
userid
Indicates the supplied file is to be sent to the specified user ID (userid) at
host node.
linkid
indicates the supplied file is to be directed to the specified link (linkid) at
remote host node. Use this form when the specified link name is not known
to the local host.
PRIORITY=nn
Defines a specific RSCS transmission priority where nn is a decimal number in
the range 0-99. This operand is applicable only to RSCS links that use
priority-based queuing.
SPOOL=options
Defines operands for the CP SPOOL command. Any valid CP SPOOL
216
z/VM: TCP/IP Planning and Customization
LPD Server
command option may be specified. If specified, SPOOL=options must be the
last operand present for this configuration statement.
OTHERS=tagoptions
Defines any RSCS link, system, or user option recognized for the link type. If
specified, OTHERS=tagoptions must be the last operand present for this
configuration statement.
Note: No case translation is performed on the values associated with the above
operands. These operands and values are processed without modification,
with respect to case. For more information on controlling LPD services from
other systems, see the TCP/IP User’s Guide.
Optional Service Statements
Use the following statements to define general LPD service attributes.
EXIT Statement
The EXIT statement identifies an exit EXEC to run after spooling and tagging
operations but before a virtual device is detached.
Two parameters are passed to the specified EXEC:
1. The virtual address of the spooled unit record device.
2. The three digit job number assigned to the print job submitted by the LPR client.
The job number is used as part of the control and data files associated with the
print job.
EXIT
START
END
filename
Operands
START
Indicates the exit EXEC is to be invoked after spooling and tagging, but before
closing processing.
END
Indicates that the exit EXEC is to be invoked after closing processing but before
the virtual device is detached.
filename
The name of the exit EXEC to be invoked.
FAILEDJOB Statement
The FAILEDJOB statement controls error notification handling for failed jobs (print
requests). When a job fails, an error notification can be sent to the submitter of the
print request, or the failure can be handled without notice. The failed job is
discarded regardless of whether a notification is sent.
Chapter 12. Configuring the LPD Server
217
LPD Server
FAILEDJOB
MAIL
DISCARD
Operands
MAIL
Causes an error notification to be sent (using SMTP services) to the submitter
of the print job.
DISCARD
Causes failed jobs to be discarded without notice.
Usage Notes
v When the FAILEDJOB statement is used with the LOCAL or RSCS statements,
the default operand in effect is MAIL.
v When the FAILEDJOB statement is used with the REMOTE statement, the
default operand in effect is DISCARD.
FILTERS Statement
The FILTERS statement can be used to control the type of printing or punching
allowed for a specific LPD service. Filter operands are case sensitive.
FILTERS
f
l
p
r
lASf
Operands
f
Paginates a file using a page size, and truncates lines that exceed a specified
maximum length.
l
Prints a file leaving control characters intact.
p
Paginates a file and adds a title, date, and page numbers.
r
Prints a file, interpreting the first character of each line as FORTRAN (ASA)
carriage control.
lASf
Forces an LPD service to treat all files that include the l filter specification to
use the f filter instead. Case is significant for this operand. Use of this option
implicitly defines the l and f filters as being supported by the corresponding
service.
Most printer services can accommodate all, or a combination of, the FILTERS
statement operands. However, you may want to specify only l for punch devices.
218
z/VM: TCP/IP Planning and Customization
LPD Server
LINESIZE Statement
The LINESIZE statement specifies the line length to be applied when a filter is used
to paginate a file. This statement only applies to services that are designated as
either LOCAL or RSCS.
LINESIZE 132
LINESIZE length
Operands
length
The character length of lines on a page; lines greater than this length are
truncated. The default is 132. LINESIZE length values that fall within a certain
range of values result in various virtual printer devices being defined for print
operations, as follows:
Length Range
0-132
133-150
151-204
205+
Printer Device
1403
3211
3800
VAFP
PAGESIZE Statement
The PAGESIZE statement specifies the page length to be applied when a filer is
used to paginate a file. This statement applies only to services that are designated
as either LOCAL or RSCS.
PAGESIZE
60
lines
Operands
lines
The number of lines on a page. The default is 60.
RACF Statement
The RACF statement requires that users of the designated service provide their VM
user ID and password as job description information supplied as part of their print
request. It is not necessary to use an external security manager such as RACF with
this option. See Appendix A, “Using TCP/IP with an External Security Manager” on
page 645 for more information on using LPD with an external security manager.
RACF
Chapter 12. Configuring the LPD Server
219
LPD Server
The RACF statement has no operands.
Note: Job description information is provided by the JOB option of the VM LPR
command or the -J option of the Unix lpr command. For more information,
see the section about controlling LPD services from other systems in the
TCP/IP User’s Guide.
TRANSLATETABLE Statement
Specifies a translation table to be used for a specific print service. XLATETABLE is
accepted as a synonym for this statement.
TRANSLATEtable tablename
Operands
tablename
The file name of a translation table file to be used for EBCDIC to ASCII data
translations; the file type for this file must be TCPXLBIN.
Note: If this statement is not specified, an attempt will be made to use the default
translation table.
See Chapter 30, “Using Translation Tables” on page 623 for more information on
translation tables.
Dynamic Server Operation
The VM Special Message Facility (SMSG) command provides an interface to the
LPD server to:
v have CP commands executed while the server remains in operation.
v obtain information about jobs waiting to be printed.
v activate or deactivate server tracing.
Notes:
1. Responses to commands are not sent back to the originator of an SMSG
command sent to the LPD server.
2. SMSG commands are accepted only from users specified in the OBEY
statement of the LPD configuration file.
SMSG Interface to the LPD Server
SMSG server_id
CP command
PRINT WORK
TRACE
ON
OFF
Operands
server_id
The user ID of the LPD server virtual machine.
220
z/VM: TCP/IP Planning and Customization
LPD Server
CP command
Causes the specified command to be issued using a DIAGnose X'08' interface.
If the command is not valid or fails, a record of the operating system response
and the failing return code is written to the server console.
PRINT WORK
Displays the current list of jobs waiting to be printed to the console. The list is
prefaced by the string:
Work Queue start
and terminated by the string:
Work Queue end
TRACE ON
Activates full tracing of the processing within the LPD server virtual machine.
Trace output is written to the server console.
TRACE OFF
Deactivates tracing. This command terminates all tracing, regardless of the
means used to establish tracing. This command also turns off the minimal
tracing activated by the TYPE option of the LPD command.
Chapter 12. Configuring the LPD Server
221
LPD Server
222
z/VM: TCP/IP Planning and Customization
Chapter 13. Configuring the MPROUTE Server
This Chapter describes how to configure the Multiple Protocol Routing (MPROUTE)
server. Before presenting the details of the configuration process it is important to
explain MPROUTE’s use of the OPEN Shortest Path First (OSPF) protocol and the
Routing Information Protocol (RIP). This information will help you decide if this
application is suitable for your network and, if so, whether the OSPF or RIP protocol
(or both) is best suited for you.
Understanding MPROUTE
MPROUTE implements the OSPF protocol described in RFC 1583 (OSPF Version
2) and the RIP protocols described in RFC 1058 (RIP Version 1) and in RFC 1723
(RIP Version 2). It provides an alternative to the static TCP/IP gateway definitions.
When configured properly, the VM TCP/IP host running with MPROUTE becomes
an active OSPF and/or RIP router in a TCP/IP network. Either (or both) of these
routing protocols can be used to dynamically maintain the host routing table. For
example, MPROUTE can determine that a new route has been created, that a route
is temporarily unavailable, or that a more efficient route exists. If both OSPF and
RIP protocols are used simultaneously, OSPF routes will be preferred over RIP
routes to the same destination.
MPROUTE has the following characteristics:
v A one-to-one relationship exists between an instance of MPROUTE and a
TCP/IP stack.
v MPROUTE and RouteD cannot run on the same stack concurrently.
|
|
|
v All dynamic routes are deleted from the routing table upon initialization of
MPROUTE.
v MPROUTE allows the generation of multiple, equal-cost routes to a destination,
thus providing load splitting support. For OSPF and RIP, up to four equal-cost
multipath routes are allowed.
v ICMP Redirects are ignored when MPROUTE is active.
v Unlike RouteD, MPROUTE does not make use of the BsdRoutingParms
configuration statement. Instead, the Maximum Transmission Unit (MTU), subnet
mask, and destination address parameters are configured via the
OSPF_Interface, RIP_Interface, and Interface statements in the MPROUTE
configuration file. Any BsdRountingParms that have been specified in the
TCPIP configuration file will be overwritten by MPROUTE.
v MPROUTE uses the virtual machine console for its logging and tracing.
v If OSPF and/or RIP is to be used on a particular interface, then the
OSPF_Interface or RIP_Interface configuration statement must be configured.
v Interfaces which are not to be involved in the communication of the RIP or OSPF
protocol (such as VIPA interfaces) must be configured to MPROUTE via the
Interface configuration statement (unless it is a non-point-to-point interface and
all default values specified on the Interface statement are acceptable).
v MPROUTE supports Virtual IP Addressing (VIPA) to handle network interface
failures by switching to alternate paths. The virtual routes are included in the
OSPF and RIP advertisements to adjacent routers. Adjacent routers learn about
virtual routes from the advertisements and can use them to reach the
destinations at the VM host.
© Copyright IBM Corp. 1987, 2002
223
MPROUTE Server
Use of static routes (defined via the GATEWAY TCP/IP configuration statement)
along with MPROUTE is not recommended. These static routes may interfere with
the discovery of a better route to the destination as well as inhibit the ability to
switch to another route if the destination should become unreachable via the static
route.
MPROUTE works best without static routes. If, however, static routes must be
defined, all static routes will be considered to be of equal-cost and static routes will
not be replaced by OSPF or RIP routes. Use extreme care when working with static
routes and MPROUTE. Set IMPORT_STATIC_ROUTES to YES on the
AS_Boundary Routing configuration statement or set SEND_STATIC_ROUTES to
YES on the RIP_Interface configuration statement if you wish for the static routes
to be advertised to other routers.
For details on the statements in the MPROUTE configuration file, see the “OSPF
Configuration Statements” on page 230.
Various commands can be issued to the MPROUTE server by using the SMSG
interface. For details on MPROUTE’s SMSG interface see “SMSG Interface to the
MPROUTE Server” on page 230.
Open Shortest Path First (OSPF)
OSPF is classified as an Interior Gateway Protocol (IGP) that distributes routing
information within a single Autonomous System (AS). The OSPF protocol is a
routing protocol designed expressly for the TCP/IP internet environment, including
explicit support for IP subnetting and the tagging of externally-derived routing
information.
OSPF provides support for equal-cost multipath, permits the authentication of
routing updates, and utilizes IP multicast when sending/receiving the updates. An
area routing capability is provided, enabling an additional level of routing protection
and a reduction in routing protocol traffic.
|
|
OSPF is a dynamic routing protocol. It quickly detects topological changes in the
AS (such as router interface failures) and calculates new routes during a period of
convergence. This period of convergence is short and involves a minimum of
routing traffic.
In a link-state routing protocol, each router maintains a database describing the
Autonomous System’s topology. Each participating router has an identical database.
Each individual piece of this database is a particular router’s local state (e.g., the
router’s usable interfaces and reachable neighbors). The router distributes its local
state throughout the Autonomous System by propagation.
From the topological database, each OSPF router constructs a tree of shortest
paths with itself as root. This shortest-path tree gives the route to each destination
in the Autonomous System. Externally derived routing information appears on the
tree as leaves. The metric is a non–negative integer, where the lower the number,
the greater the preference. When several equal-cost routes to a destination exist,
traffic is distributed among them.
|
OSPF allows sets of networks to be grouped together. Such a grouping is called an
area. The topology of an area is hidden from the other areas in the Autonomous
System. This information hiding enables a significant reduction in routing traffic.
224
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Also, routing within the area is determined only by the area’s own topology, lending
the area protection from bad routing data. An area is a generalization of an IP
subnetted network.
OSPF enables the flexible configuration of IP subnets. Each route distributed by
OSPF has a destination and mask. Two different subnets of the same IP network
number may have different sizes (i.e., different masks). This is commonly referred
to as variable length subnetting. A packet is routed to the best (i.e., longest or most
specific) match. Host routes are considered to be subnets whose masks are ″all
ones″.
OSPF can be configured such that all OSPF protocol exchanges are authenticated.
This means that only trusted routers can participate in the Autonomous System’s
routing. A single authentication scheme is configured for each area. This enables
some areas to use authentication while others do not.
Externally derived routing data (e.g., routes learned from the Routing Information
Protocol (RIP)) is passed transparently throughout the Autonomous System. This
externally derived data is kept separate from the OSPF protocol’s link state data.
Each external route can also be tagged by the advertising router, enabling the
passing of additional information between routers on the boundaries of the
Autonomous System.
Routing Information Protocol (RIP)
RIP is an Interior Gateway Protocol (IGP) designed to manage a relatively small
network. IGPs are used to manage the routing information of a single autonomous
system, or a single piece of the TCP/IP network. RIP is an IGP based on the
Bellman-Ford or the distance-vector algorithm. RIP has many limitations and is not
suited for every TCP/IP environment. Before using the RIP function in MPROUTE,
read RFCs 1058 and 1723 to decide if RIP can be used to manage the routing
tables of your network. See Appendix B, “Related Protocol Specifications” on
page 651 for more information about how you can obtain information on RFCs.
RIP uses the number of hops, or hop count, to determine the best possible route to
a host or network. The term hop count is also referred to as the metric. A gateway
is defined as zero hops from its directly connected networks, one hop from
networks that can be reached through one gateway, and so on. In RIP, a hop count
of 16 means the destination cannot be reached. This limits the longest path in the
network that can be managed by RIP to 15 gateways.
A RIP router broadcasts routing information to its directly connected networks every
30 seconds. It receives updates from neighboring RIP routers periodically and uses
the information contained in these updates to maintain the routing table. If an
update has not been received from a neighboring RIP router in 180 seconds, a RIP
router assumes that the neighboring RIP router is down and sets all routes through
that router to a metric of 16 (infinity). If an update has still not been received from
the neighboring RIP router after another 120 seconds, the RIP router deletes from
the routing table all of the routes through that neighboring RIP router.
RIP Version 2 is an extension of RIP Version 1 and provides the following features:
v Route Tags to provide EGP-RIP and BGP-RIP interactions
The route tags are used to separate ″internal″ RIP routes (routes for networks
within the RIP routing domain) from ″external″ RIP routes, which may have been
Chapter 13. Configuring the MPROUTE Server
225
MPROUTE Server
imported from an EGP (external gateway protocol) or another IGP. MPROUTE
will not generate route tags, but will preserve them in received routes and
readvertise them when necessary.
v Variable subnetting support
Variable length subnet masks are included in routing information so that
dynamically added routes to destinations outside subnetworks or networks can
be reached.
v Immediate Next Hop for shorter paths
Next hop IP addresses, whenever applicable, are being included in the routing
information to eliminate packets being routed through extra hops in the network.
MPROUTE will not generate immediate next hops, but will preserve them if they
are included in the RIP packets.
v Multicasting to reduce load on hosts
IP multicast address 224.0.0.9 is reserved for RIP Version 2 packets. This is
used to reduce unnecessary processing of packets by hosts which are not
listening for RIP Version 2 messages. This support is dependent on interfaces
that are multicast-capable.
v Authentication for routing update security
Authentication keys can be configured for inclusion in outgoing RIP Version 2
packets. Incoming RIP Version 2 packets are checked against the configured
keys.
v Configuration for RIP Version 1 and RIP Version 2 packets
Configuration parameters allow for controlling which version of RIP packets are
to be sent or received over each interface.
v Supernetting support
The supernetting feature is part of Classless InterDomain Routing (CIDR).
Supernetting provides a way to combine multiple network routes into fewer
supernet routes, thus reducing the number of routes in the routing table and in
advertisements.
Note: When sending and receiving Rip packets, either Rip Version 1 or Rip Version
2 can be enabled on an interface; both versions cannot be enabled at the
same time.
Configuration Steps for the MPROUTE Server
MPROUTE Server Configuration Steps
1. Update the TCPIP server configuration file, (PROFILE TCPIP).
2. Update the ETC SERVICES file.
3. Create the MPROUTE configuration file, (MPROUTE CONFIG).
4. Update the DTCPARMS file for the MPROUTE server (Optional).
Dynamic Server Operation
The MPROUTE server provides a VM Special Message (SMSG) interface that
allows you to perform server administration tasks through a set of privileged
commands. For more information see “SMSG Interface to the MPROUTE Server”
on page 230.
226
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Step 1: Update PROFILE TCPIP
|
The name of the MPROUTE server must be included in the OBEY Statement
because of its dependence on the Raw Sockets. In the ASSORTEDPARMS
Statement, you should insure that the IGNOREREDIRECT, VARSUBNETTING, and
EQUALCOSTMULTIPATH Operands are specified. Also include the MPROUTE
server virtual machine user ID in the AUTOLOG statement of the TCPIP server
configuration file. The MPROUTE server is then automatically started when TCPIP
is initialized. The IBM default user ID for this server is MPROUTE. Verify that the
following statement has been added to the PROFILE TCPIP file:
AUTOLOG
MPROUTE
0
If the RIP protocol of MPROUTE is going to be used, UDP port 520 should be
reserved for MPROUTE. Verify that the following statements have been added to
your TCPIP server configuration file as well:
PORT
520 UDP MPROUTE
;
MPROUTE Server
Autolog Considerations for MPROUTE
If a server 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 will
periodically attempt to cancel and then restart that server. Therefore, if MPROUTE
is being started with AUTOLOG and only the OSPF protocol is being used (no RIP
protocol, and therefore no listening connection on the RIP UDP port), you must do
one of the following:
v Ensure that the RIP UDP port (520) is not reserved by the PORT statement in
the TCPIP server configuration file.
v Add the NOAUTOLOG parameter to the PORT statement in the TCPIP server
configuration file. For example,
PORT
520 UDP MPROUTE NOAUTOLOG
Note: When using only the OSPF protocol, the auto-start feature of AUTOLOG can
be used as described above. However, the monitoring and auto-restart
features of AUTOLOG are unavailable due to AUTOLOG’s dependence on a
listening TCP or UDP connection, which does not exist with OSPF.
If you fail to take one of the above actions, MPROUTE will be periodically cancelled
and restarted by TCP/IP.
Step 2: Update the ETC SERVICES file
The ETC SERVICES file contains the relationship between services and port
numbers. If the RIP protocol of MPROUTE is going to be used, ensure that the
following line is added to the ETC SERVICES file:
router
520/udp
route MPROUTE
Note: In the above example, the default well–known port (520) is used.
You should compare the port number configured in the ETC SERVICES file to the
port number configured for the MPROUTE server in the PROFILE TCPIP file to
ensure that the port numbers are the same.
Chapter 13. Configuring the MPROUTE Server
227
MPROUTE Server
Step 3: Create the MPROUTE Configuration File
The MPROUTE configuration file contains the OSPF and/or RIP configuration
definitions. Please refer to the complete list of allowable OSPF and/or RIP
configuration statements (“OSPF Configuration Statements” on page 230 ) when
preparing the MPROUTE configuration file. A sample of this configuration file is
shipped as MPROUTE SCONFIG on TCPMAINT 591. It should be copied to
TCPMAINT 198, customized, and renamed to MPROUTE CONFIG.
Syntax Rules
Statements in the MPROUTE configuration file have the following syntax:
type tag=value
type=value
type
Specifies what is to be configured.
tag=value
Specifies a parameter and its associated value.
type=value
Used for statements that have only a single parameter.
The following are the syntax rules for the MPROUTE configuration statements:
v Types, tags, and values can be specified in mixed case.
v Every configuration statement must end with a semicolon.
v Blanks and comments are supported. Comments are identified by a semicolon in
any column. Comments cannot appear within a configuration statement.
v Statements may begin in any column.
Step 4: Update the DTCPARMS File (Optional)
When the MPROUTE server is started, the TCP/IP server initialization program
searches specific DTCPARMS files for configuration definitions that apply to this
server. Tags that affect the name server are:
:nick.MPROUTE
:PARMS.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the MPROUTE server if you need
to specify any of the MPROUTE server input parameters. See the
“MPROUTE Command” on page 229 for a complete list.
228
z/VM: TCP/IP Planning and Customization
MPROUTE Server
MPROUTE Command
The MPROUTE command is used to accept the command line parameters listed
below. These parameters are valid when starting the program from either the CMS
command line or through DTCPARMS.
MPROUTE parms
Operands
parms
Any one or more of the following parameters separated by a space.
-tn (where n is a supported trace level)
This option specifies the external tracing level. It is intended for general use
and provides information on the operation of the routing application. This
option can be used for many purposes, such as debugging a configuration,
education on the operation of the routing application, verification of
testcases, and so on. The following levels are supported:
1 = Informational messages
2 = Formatted packet trace
-dn (where n is a supported debug level)
This option specifies the internal debugging level. It is intended for service
or developers, and provides internal debugging information needed for
debugging problems. The following levels are supported:
1
2
3
4
=
=
=
=
Internal debugging messages
Unformatted hex packet trace
Function entry/exit trace
Task add/run
For –t and –d the above option levels are treated as cumulative; that is, level 2
includes level 1. For example, -t2 provides formatted packet trace and informational
messages.
Usage Notes
1. For more information on the trace and troubleshooting problems with the
MPROUTE server, see the “Activating MPROUTE Trace and Debug” section of
the TCP/IP Diagnosis Guide.
Dynamic Server Operation
The VM Special Message Facility (SMSG) command provides an interactive
interface to the MPROUTE virtual machine to perform privileged system
administration tasks, such as:
v shutting down the server
v changing the cost of the interface
v displaying valid SMSG command options
Privileged users are specified in the OBEY list of the TCPIP server configuration
file.
Chapter 13. Configuring the MPROUTE Server
229
MPROUTE Server
Note: Command responses are returned to the originator of the command through
CP MSG commands.
SMSG Interface to the MPROUTE Server
SMSG server_id
HELP
OSPF WEIGHT NAME=name COST=cost
SHUTDOWN
Operands
server_id
Specifies the user ID of the MPROUTE server virtual machine.
HELP
Provides a list of valid SMSG commands accepted by MPROUTE.
OSPF WEIGHT NAME=name COST=cost
The cost of an OSPF interface can be dynamically changed using the
NAME/COST operand. The new cost is propagated throughout the OSPF
routing domain, and modifies the routing immediately. The cost of the interface
reverts to its configured value whenever the router is restarted. To make the
cost change permanent, you must reconfigure the appropriate OSPF interface
in the MPROUTE configuration file.
SHUTDOWN
Stops the MPROUTE server that is running in the target virtual machine. The
#CP EXTERNAL command cannot be used for shutdown.
1. An example using the SHUTDOWN SMSG command from another virtual
machine to stop the MPROUTE server running in the MPROUTE1 virtual
machine follows:
smsg mproute1 shutdown
Ready;
12:37:10 * MSG FROM MPROUTE1 : SHUTDOWN
2. This example is using the SHUTDOWN SMSG command to stop the
MPROUTE server from the actual server (MPROUTE1) virtual machine:
CP SMSG * SHUTDOWN
DTCRTD6020I SMSG Command: MPROUTED Server termination initiated
13:39:02 * MSG FROM MPROUTED1 : SHUTDOWN
DTCRUN1014I Server ended normally at 13:39:04 on 3 Mar 2000 (Friday)
For more detailed information on using the SMSG interface for diagnosing and
troubleshooting problems with the MPROUTE server, see the TCP/IP Diagnosis
Guide.
OSPF Configuration Statements
This section contains descriptions of the OSPF configuration statements:
v AREA
v COMPARISON
v OSPF_INTERFACE
v VIRTUAL_LINK
v ROUTERID
v AS_BOUNDARY_ROUTING
230
z/VM: TCP/IP Planning and Customization
MPROUTE Server
v RANGE
v DEMAND_CIRCUIT
Note: Statements with only optional operands must have at least one operand
coded, even if all operands have defaults.
AREA Statement
Sets the parameters for an OSPF area. If no areas are defined, the router software
assumes that all the router’s directly attached networks belong to the backbone
area (area ID 0.0.0.0).
Area
Area_Number=0.0.0.0
Area_Number=ospf_area_address
Authentication_Type=None
Stub_Area=NO
Authentication_Type=security_scheme
Stub_Area=YES
Stub_Default_Cost=1
Import_Summaries=YES
Stub_Default_Cost=cost
Import_Summaries=NO
Operands
Area_Number=ospf_area_address
Specifies the OSPF area address in dotted decimal.
Area ID 0.0.0.0 is reserved for the backbone. The backbone is responsible for
summarizing the Autonomous System of each area to every other area. All
inter-area traffic must pass through the backbone; non backbone areas cannot
exchange packets directly.
Authentication_Type=security_scheme
Specifies the security scheme to be used in the area. Valid values for
authentication types are ″Password″, which indicates a simple password; or
″None″, which indicates that no authentication is necessary to pass packets.
Stub_Area
Specifies whether or not this area is a stub area. Valid values are YES or NO.
If you specify Stub_area=YES, the area does not receive any AS external link
advertisements, reducing the size of your database and decreasing memory
usage for routers in the stub area. You cannot configure virtual links through a
stub area. You cannot configure a router within the stub area as an AS
boundary router.
You cannot configure the backbone as a stub area. External routing in stub
areas is based on a default route. Each border area router attaching to a stub
area originates a default route for this purpose. The cost of this default route is
also configurable with the AREA statement.
Stub_Default_Cost=cost
Specifies the cost OSPF associates with the default route to its border area
router. Valid values are 1 to 65535.
Chapter 13. Configuring the MPROUTE Server
231
MPROUTE Server
Import_Summaries
Determines whether this stub area will import a routing summary from a
neighbor area. Valid values are YES or NO.
COMPARISON Statement
Tells the router where external routes fit in the OSPF hierarchy. OSPF supports two
types of external metrics. Type 1 external metrics are equivalent to the link state
metric. Type 2 external metrics are greater than the cost of any path internal to the
AS. Use of type 2 external metrics assumes that routing between autonomous
systems is the major cost of routing a packet and eliminates the need for
conversion of external costs to internal link state metrics.
Comparison=Type2
Comparison=Type1
Operands
Comparison=Typex
Compare to type 1 or 2 externals. Valid values are Type1 (or 1) or Type2 (or 2).
OSPF_INTERFACE Statement
Sets the OSPF parameters for the router’s network interfaces. This statement will
need to be replicated in the config file for each IP interface over which OSPF will
operate.
232
z/VM: TCP/IP Planning and Customization
MPROUTE Server
OSPF_Interface IP_address=ip_address Name=interface_name
Subnet_mask=subnet_mask
Destination_Addr=address
Attaches_To_Area=0.0.0.0
MTU=576
Attaches_To_Area=area
MTU=size
Retransmission_Interval=5
Transmission_Delay=1
Retransmission_Interval=frequency
Transmission_Delay=delay
Router_Priority=1
Hello_Interval=10
Router_Priority=priority
Hello_Interval=interval
Dead_Router_Interval=40
Cost0=1
Subnet=NO
Dead_Router_Interval=interval
Cost0=cost
Subnet=YES
Authentication_Key=nulls
Demand_Circuit=NO
Authentication_Key=″password″
Demand_Circuit=YES
Hello_Suppression=Allow
PP_Poll_Interval=60
Hello_Suppression=value
PP_Poll_Interval=interval
Parallel_OSPF=Backup
Parallel_OSPF=value
Non_Broadcast=NO
NB_Poll_Interval=120
Non_Broadcast=YES
NB_Poll_Interval=interval
DR_Neighbor=ip_address
No_DR_Neighbor=ip_address
Max_Xmit_Time=120
Min_Xmit_Time=0.5
Max_Xmit_Time=max_time
Min_Xmit_Time=min_time
RT_Gain=0.125
Variance_Gain=0.25
Variance_Mult=2
RT_Gain=rtgain
Variance_Gain=vgain
Variance_Mult=mult
Delay_Acks=NO
Delay_Acks=YES
Operands
IP_address=ip_address
Specifies the IP address of the local interface to be configured for OSPF.
Chapter 13. Configuring the MPROUTE Server
233
MPROUTE Server
This parameter can be a valid IP address that is configured on the system or it
can be specified with asterisks (*) as wild cards. The valid wildcard
specifications are below. The result of coding a wild card value is that all
configured interfaces whose IP address matches the wild card will be
configured as OSPF interfaces. Configured interface IP addresses will be
matched against possible wild cards in the order they appear below with x.y.z.*
being the best match, x.y.*.* being 2nd best, and so forth.
x.y.z.*
x.y.*.*
x.*.*.*
*.*.*.* - Same as ALL
ALL
- Same as *.*.*.*
Name=interface_name
Specifies the name of the interface that must match the link name coded for the
corresponding IP address on the HOME statement in the TCP/IP profile. This
parameter is ignored on wildcard interface definitions.
Subnet_Mask=subnet_mask
Specifies the subnet mask of the network this interface attaches to.
Destination_Add=address
Specifies the IP address of the host at the remote end of this interface. This
parameter is only valid for point-to-point links. If this parameter is not specified
for a point-to-point link, a route to the host at the remote end of the interface
will not be added to the TCP/IP route table until OSPF communication is
established with that host. A subnet route for the interface will be added at
MPROUTE initialization independent of whether this parameter is specified.
Attaches_To_Area=area
Indicates the OSPF area to which this interface attaches. Valid values are
0.0.0.0 (the backbone), or any area defined by the AREA statement.
MTU=size
Specifies the mtu size for OSPF to add to the routing table for routes that take
this interface. Valid values are 0 to 65535.
Retransmission_Interval=frequency
Sets the frequency (in seconds) of retransmitting link-state update packets,
link-state request packets, and database description packets. Valid values are
from 1 to 65535 seconds.
If this parameter is set too low, needless retransmissions will occur that could
affect performance and interfere with neighbor adjacency establishment. It
should be set to a higher value for a slower machine.
Transmission_Delay=delay
Specifies an estimate of the number of seconds it takes to transmit link-state
information over the interface. Each link-state advertisement has a lifetime of 1
hour. As each link-state advertisement is sent to a particular interface, it is aged
by this configured transmission delay. Valid values are 1 to 65535 seconds.
Router_Priority=priority
Specifies the designated router to be used for broadcast and non-broadcast
multiaccess networks, with the highest priority router being elected. For
point-to-point links, this value should be 0 , which means that this router must
not be elected the designated router for its network. Valid values are 0 to 255.
234
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Hello_Interval=interval
Indicates how often (in seconds) OSPF will send out over this interface. This
value must be the same for all routers attached to a common network. Valid
values are 1 to 255 seconds.
Dead_Router_Interval=interval
Specifies the interval in seconds, after not having received an OSPF Hello, that
the neighbor is declared to be down. This value must be larger than the hello
interval. Setting this value too close to the Hello_Interval can result in the
collapse of adjacencies. A value of four times Hello_Interval is recommended.
This value must be the same for all routers attached to a common network.
Valid values are 2 to 65535.
Cost0=cost
Specifies the shortest path to be used to a destination. Valid values are 1 to
65535.
Subnet
For an interface to a point-to-point serial line, enables the advertisement of a
stub route to the subnet that represents the serial line rather than the host route
for the other router’s address. Valid values are YES or NO.
Authentication_Key=″password″
Specifies the password for the OSPF routers attached to the network. Coded
when Authentication_Type=Password on the AREA statement for the area to
which this interface attaches is used. This value must be the same for all
routers attached to a common network. Valid values are any 8 characters from
code page 1047 coded within double quotes or any hex string which begins
with ″0x″.
Demand_Circuit
Specifies whether the Link State Advertisements (LSAs) transmitted over this
interface will expire. This is required if they will not be refreshed over this
interface. Only LSA’s with real changes will be advertised. Valid values are YES
or NO.
Hello_Suppression=value
Specifies the hello_suppression value. Meaningful only if Demand_Circuit is
coded YES. Allows you to configure the interface to request Hello suppression.
This parameter is useful for point-to-point and point-to-multipoint interfaces.
Valid values are ALLOW, REQUEST, or DISABLE.
If either or both sides specify DISABLE, hello suppression is disabled. If both
specify ALLOW, hello suppression is disabled. If one specifies ALLOW and the
other REQUEST, or if both specify REQUEST, hello suppression is enabled.
PP_Poll_Interval=interval
Specifies how often (in seconds) OSPF will try to reestablish a connection when
the point-to-point line is down because there was a failure to transmit data but
the interface is still available. This parameter is meaningful only if
Demand_Circuit is coded YES and Hello_Supression has been enabled. Valid
values are 0-65535.
Parallel_OSPF=value
Indicates whether the OSPF interface is primary or backup when more than one
OSPF interface is defined to the same subnet. Only one of these interfaces can
be configured as primary, meaning that it will be the interface to carry the OSPF
protocol traffic between MPROUTE and the subnet. Failure of the primary
interface results in automatic switching of OSPF traffic to one of the backup
Chapter 13. Configuring the MPROUTE Server
235
MPROUTE Server
interfaces. If none of the interfaces to the common subnet are configured as
primary, a primary interface will be selected by MPROUTE. Valid values are
″Backup″ or ″Primary″.
Non_Broadcast
If the router is connected to a nonbroadcast, multiaccess (NBMA) network, such
as X.25, Frame Relay, Hyperchannel, or ATM networks, coding a
Non_Broadcast helps the router discover its neighbors. This configuration is
only necessary if the router will be eligible to become the designated router of
the NBMA network. In addition to coding this parameter, each neighbor must be
configured with the DR_NEIGHBOR parameter, for those neighbors that are
eligible to become the designated router, and NO_DR_NEIGHBOR for those
neighbors that are not eligible to become the designated router. This statement
is ignored when this OSPF interface is coded as a wildcard. Valid values are
YES or NO.
NB_Poll_Interval=interval
Specifies how often (in seconds) Hello packets are sent to neighbors that are
inactive. You must set this poll interval consistently across all interfaces that
attach to the same network for OSPF to function correctly. This statement is
only valid when Non_Broadcast is coded as YES. Valid values are 1 to 65535.
DR_Neighbor=ip_address
Defines which routers within the non-broadcast network can become a
designated router. If the OSPF protocol communicates with one or more routers
over a non_broadcast network interface, MPROUTE must know the IP
addresses of the other routers (neighbors) with which it needs to communicate.
For non-broadcast network interfaces, there is no underlying signaling that
allows the stack to learn the required IP addresses. As a result, the neighbor
addresses must be configured to MPROUTE with this parameter. Multiple
DR_Neighbor statements may be coded on an OSPF_interface statement as
necessary. The value of the ip_address must be a valid IP address.
No_DR_Neighbor=ip_address
Defines which routers within the non-broadcast network cannot become a
designated router. If the OSPF protocol communicates with one or more routers
over a non_broadcast network interface, MPROUTE must know the IP
addresses of the other routers (neighbors) with which it needs to communicate.
For non-broadcast network interfaces, there is no underlying signaling that
allows the stack to learn the required IP addresses. As a result, the neighbor
addresses must be configured to MPROUTE with this parameter. Multiple
No_DR_Neighbor statements may be coded on an OSPF_interface statement
as necessary. The value of the ip_address must be a valid IP address.
Max_Xmit_Time=max_time
Specifies the maximum retransmit time (in seconds) to add to the routing table
for routes that take this interface. This value is used in the TCP/IP
re-transmission time-out calculation to determine how long to wait for an
acknowledgment before resending a packet. Valid values are 0 to 999.990
seconds.
Min_Xmit_Time=min_time
Specifies the minimum retransmit time (in seconds) to add to the routing table
for routes that take this interface. This value is used in the TCP/IP
re-transmission time-out calculation to determine how long to wait for an
acknowledgment before resending a packet. Valid values are 0 to 999.990
seconds.
236
z/VM: TCP/IP Planning and Customization
MPROUTE Server
RT_Gain=rtgain
Indicates the round trip gain value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Gain=vgain
Indicates the variance gain value to add to the routing table for routes that take
this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Mult=mult
Indicates the variance multiplier value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 99.990.
Delay_Acks
Specifies the delay acknowledgments value to add to the routing table for
routes that take this interface. Specifying YES delays transmission of
acknowledgments when a packet is received with the PUSH bit on in the TCP
header. Specifying NO results in acknowledgments being returned immediately.
Valid values are YES and NO.
VIRTUAL_LINK Statement
Configures virtual links between any two area border routers. To maintain backbone
connectivity you must have all of your backbone routers interconnected either by
permanent or virtual links. Virtual links are considered to be separate router
interfaces connecting to the backbone area. Therefore, you are asked to specify
many of the interface parameters when configuring a virtual link.
Virtual links can be configured between any two backbone routers that have an
interface to a common non-backbone area. Virtual links are used to maintain
backbone connectivity and must be configured at both endpoints.
Note: OSPF virtual links are not to be confused with virtual links which are part of
Virtual IP Address support (VIPA).
Virtual_Link Virtual_Endpoint_RouterID=id
Links_Transit_Area=0.0.0.1
Retransmission_Interval=10
Links_Transit_Area=area
Retransmission_Interval=frequency
Transmission_Delay=5
Hello_Interval=30
Transmission_Delay=delay
Hello_Interval=interval
Dead_Router_Interval=180
Authentication_Key=nulls
Dead_Router_Interval=interval
Authentication_Key=″password″
Chapter 13. Configuring the MPROUTE Server
237
MPROUTE Server
Operands
Virtual_Endpoint_RouterID=id
Indicates the router ID of the virtual neighbor (other endpoint). Router IDs are
entered in the same form as IP addresses.
Links_Transit_Area=area
Specifies the non-backbone, non-stub area through which the virtual link is
configured. Virtual links can be configured between any two area border routers
that have an interface to a common non-backbone and non-stub area. Virtual
links must be configured in each of the link’s two endpoints. Valid values are
0.0.0.1 to 255.255.255.255.
Retransmission_Interval=frequency
Specifies how often (in seconds) of retransmitting the link-state update packets,
link-state request packets, and database description packets. Valid values are
from 1 to 65535 seconds.
If this parameter is set too low, needless retransmissions will occur that could
affect performance and interfere with neighbor adjacency establishment. It
should be set to a higher value for a slower machine.
Transmission_Delay=delay
Specifies an estimate of the number of seconds that it takes to transmit
link-state information over the interface. Each link-state advertisement has a
finite lifetime of 1 hour. As each link-state advertisement is sent to a particular
interface, it is aged by this configured transmission delay. Valid values are 1 to
65535 seconds.
Hello_Interval=interval
Specifies the number of seconds between OSPF Hello packets being sent out
this interface. Valid values are 1 to 255 seconds. The hello interval should be
set higher than the same value used on the intervening, actual, OSPF
interfaces.
Dead_Router_Interval=interval
Specifies the interval in seconds, after not having received an OSPF Hello, that
the neighbor is declared to be down. This value must be larger than the hello
interval. Valid values are 2 to 65535. The dead router interval should be set
higher than the same value used on the intervening, actual, OSPF interfaces.
Authentication_Key=″password″
Specifies the password for the virtual links transit area. Valid values are any 8
characters from code page 1047 coded within double quotes or any hex string
that begins with ″0x″.
ROUTERID Statement
Every router in an OSPF routing domain must be assigned a unique 32-bit router
ID. The value used for the OSPF router ID is chosen as follows:
v If the RouterID statement is specified, the value configured is used as an OSPF
router ID. This value must be one of the stack’s configured interface IP network
addresses.
v If the RouterID is not configured, one of the OSPF interface addresses will be
used as the OSPF router ID.
238
z/VM: TCP/IP Planning and Customization
MPROUTE Server
RouterID=id
Operands
RouterID id
Specifies the ID, which is one of the TCP/IP stack’s configured interface IP
network addresses, in dotted decimal form.
AS_BOUNDARY_ROUTING Statement
Enables the AS boundary routing capability which allows you to import routes
learned from other methods (RIP, statically configured, and direct routes) into the
OSPF domain. This statement must be coded even if the only route you want to
import is the default route (destination 0.0.0.0). All routes are imported with their
cost equal to their routing table cost. They are all imported as either Type 1 or Type
2 external routes, depending on what was coded on the Comparison statement.
The metric type used when importing routes determines how the imported cost is
viewed by the OSPF domain. When comparing Type 2 metrics, only the external
cost is considered in picking the best route. When comparing Type 1 metrics, the
external and internal costs of the route are combined before making the
comparison.
AS_Boundary_Routing
Import_RIP_Routes=NO
Import_RIP_Routes=YES
Import_Static_Routes=NO
Import_Direct_Routes=NO
Import_Static_Routes=YES
Import_Direct_Routes=YES
Import_Subnet_Routes=YES
Originate_Default_Route=NO
Import_Subnet_Routes=NO
Originate_Default_Route=YES
Originate_as_Type=2
Default_Route_Cost=1
Originate_as_Type=1
Default_Route_Cost=cost
Default_Forwarding_Address=address
Operands
Import_RIP_Routes
Specifies whether RIP routes will be imported into the OSPF routing domain.
Valid values are YES or NO.
Import_Static_Routes
Specifies whether static routes (routes defined to the TCP/IP stack using the
GATEWAY statement) will be imported into the OSPF routing domain. Valid
values are YES or NO.
Chapter 13. Configuring the MPROUTE Server
239
MPROUTE Server
Import_Direct_Routes
Specifies whether direct routes will be imported into the OSPF routing domain.
Valid values are YES or NO.
Import_Subnet_Routes
Independent of the RIP, static, and direct routes you may choose to import, you
can also configure whether or not to import subnet routes into the OSPF
domain. Valid values are YES or NO.
Originate_Default_Route
Specifies whether OSPF should advertise this router as a default router. Valid
values are YES or NO.
Originate_as_Type
Specifies the external type assigned to the default route. Valid values are 1 or
2.
Default_Route_Cost=cost
Specifies the cost that OSPF associates with the default route. Valid values are
0 to 16777215.
Default_Forwarding_Address=address
Specifies the forwarding address that will be used in the imported default route.
RANGE Statement
Adds ranges to OSPF areas. OSPF areas can be defined in terms of address
ranges. External to the area, a single route is advertised for each address range.
For example, if an OSPF area were to consist of all subnets of the class B network
128.185.0.0, it would be defined as consisting of a single address range. The
address range would be specified as an address of 128.185.0.0 together with a
mask of 255.255.0.0. Outside of the area, the entire subnetted network would be
advertised as a single route to network 128.185.0.0.
Ranges can be defined to control which routes are advertised external to an area.
There are two choices:
v When OSPF is configured to advertise the range, a single inter-area route is
advertised for the range if at least one component route of the range is active
within the area.
v When OSPF is configured not to advertise the range, no inter-area routes are
advertised for routes that fall within the range.
Ranges cannot be used for areas that serve as transit areas for virtual links. Also,
when ranges are defined for an area, OSPF will not function correctly if the area is
partitioned but is connected by the backbone.
Range IP_address=address Subnet_Mask=mask
240
Advertise=YES
Advertise=NO
z/VM: TCP/IP Planning and Customization
Area_Number=0.0.0.0
Area_Number=area
MPROUTE Server
Operands
IP_Address=address
Specifies common subnet portion of IP addresses in this range. Valid values are
valid IP network addresses in dotted decimal form.
Subnet_Mask=mask
Specifies the subnet mask with respect to the network range defined in
IP_Address.
Area_Number=area
Specifies the area number for which to add this range. Valid values are any
defined areas in dotted decimal form.
Advertise
Specifies whether this range will be advertised to other areas. Valid values are
YES or NO.
DEMAND_CIRCUIT Statement
Demand circuits are a usage-sensitive connection, such as the X.25 protocol.
Coding this global statement with a YES enables demand circuits. Demand circuit
parameters can then be coded on the OSPF_Interface statement.
Demand_Circuit=YES
Demand_Circuit=NO
Operands
Demand_Circuit
Valid values are YES or NO.
RIP Configuration Statements
This section contains descriptions of the RIP configuration statements:
v ORIGINATE_RIP_DEFAULT
v RIP_INTERFACE
v ACCEPT_RIP_ROUTE
ORIGINATE_RIP_DEFAULT Statement
Indicates under what conditions RIP will support Default route (destination/mask
0.0.0.0/0.0.0.0) generation.
Originate_RIP_Default
Condition=Always
Cost=1
Condition=condition
Cost=cost
Operands
Condition=condition
Indicates the condition for when RIP is to advertise this route as a default route.
Valid values are:
v Always: Always originate RIP default.
Chapter 13. Configuring the MPROUTE Server
241
MPROUTE Server
v OSPF: Originate RIP default if OSPF routes are available.
v Never: Never advertise this route as a default route.
Cost=cost
Specifies the cost that RIP will advertise with the default route that it originates.
Valid values are 1 to 16.
RIP_INTERFACE Statement
Configures the RIP parameters for each IP interface. This statement will need to be
replicated in the config file for each IP interface over which RIP will operate.
242
z/VM: TCP/IP Planning and Customization
MPROUTE Server
RIP_Interface IP_address=ip_address Name=interface_name
MTU=576
Subnet_mask=subnet_mask
Destination_Addr=address
Receive_RIP=YES
Receive_Dynamic_Nets=YES
Receive_RIP=NO
Receive_Dynamic_Nets=NO
MTU=size
Receive_Dynamic_Hosts=NO
Receive_Dynamic_Subnets=NO
Receive_Dynamic_Hosts=YES
Send_RIP=YES
Send_Default_Routes=NO
Send_Net_Routes=YES
Send_RIP=NO
Send_Default_Routes=YES
Send_Net_Routes=NO
Send_Subnet_Routes=YES
Send_Static_Routes=NO
Send_Subnet_Routes=NO
Send_Static_Routes=YES
Send_Host_Routes=NO
Send_Poisoned_Reverse_Routes=YES
Send_Host_Routes=YES
Send_Poisoned_Reverse_Routes=NO
Out_Metric=0
In_Metric=metric
Out_Metric=metric
RipV1_Routes=NO
Authentication_Key=nulls
RipV2=YES
RipV1_Routes=YES
Authentication_Key=key
Max_Xmit_Time=120
Max_Xmit_Time=max_time
Min_Xmit_Time=0.5
RT_Gain=0.125
Variance_Gain=0.25
Min_Xmit_Time=min_time
RT_Gain=rtgain
Variance_Gain=vgain
Variance_Mult=2
Delay_Acks=NO
Variance_Mult=mult
Delay_Acks=YES
RipV2=NO
Neighbor=ip_address
Receive_Dynamic_Subnets=YES
In_Metric=1
Operands
IP_address=ip_address
Specifies the IP address of interface to be configured for RIP.
The IP address can be a valid IP address that is configured on the system or it
can be specified with asterisks (*) as wild cards. The valid wildcard
specifications are below. The result of coding a wild card value are that all
configured interfaces whose IP address matches the wild card will be
Chapter 13. Configuring the MPROUTE Server
243
MPROUTE Server
configured as RIP interfaces. Configured interface IP address will be matched
against possible wild cards in the order they appear below with x.y.z.* being the
best match, x.y.*.* being 2nd best, and so forth.
x.y.z.*
x.y.*.*
x.*.*.*
*.*.*.* - Same as ALL
ALL
- Same as *.*.*.*
Name=interface name
Specifies the name of the interface. This must match the link name coded for
the corresponding IP address on the HOME statement in the TCP/IP profile.
This parameter is ignored on wildcard interface definitions.
Subnet_Mask=mask
Specifies the subnet mask for the associated interface IP address in dotted
decimal form.
Destination_Addr=address
Specifies the IP address in dotted decimal form of the host at the remote end of
this interface.
This parameter is only valid for point-to-point links and is a required parameter
for RIPV1 point-to-point links. If this parameter is not specified for a RIPV2
point-to-point link, a route to the host at the remote end of the interface will not
be added to the TCP/IP route table. A subnet route for the interface will be
added at MPROUTE initialization independent of whether this parameter is
specified.
MTU=size
Specifies the mtu size for RIP to add to the routing table for routes that take
this interface. Valid values are 0 to 65535.
Receive_RIP
Specifies whether to learn any RIP routes on this interface. Valid values are
YES or NO. Note that when this parameter is coded as NO, only routes
explicitly allowed via the Accept_RIP_Route configuration statement will be
accepted on this interface.
Receive_Dynamic_Nets
Specifies whether to learn routes for networks over this interface. If this is not
set, only nets explicitly allowed via the Accept_RIP_Route configuration
statement will be accepted on this interface. Valid values are YES or NO.
Receive_Dynamic_Subnets
Specifies whether to learn routes for subnets over this interface. If this is not
set, only subnets explicitly allowed via the Accept_RIP_Route configuration
statement will be accepted on this interface. Valid values are YES or NO.
Receive_Dynamic_Hosts
Specifies whether to learn routes for hosts over this interface. If this is not set,
only hosts explicitly allowed via the Accept_RIP_Route configuration statement
will be accepted on this interface. Valid values are YES or NO.
Send_RIP
Specifies whether RIP advertisements will be broadcast over this interface.
Valid values are YES or NO.
Send_Default_Routes
Specifies whether the default route (destination 0.0.0.0), if it is available in RIP
responses, will be sent from this IP source address. Valid values are YES or
NO.
244
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Send_Net_Routes
Specifies whether all network level routes in RIP responses will be sent from
this IP address. Valid values are YES or NO.
Send_Subnet_Routes
Specifies whether appropriate subnet-level routes in RIP responses will be sent
from this IP address. In this context an appropriate subnet is one that meets
RFC 1058 subnet advertisement constraints: - Natural Net must be the same as
the IP source’s natural net - Subnet mask must be the same - Valid values are
YES or NO.
Send_Static_Routes
Specifies whether static and direct routes in RIP responses will be sent from
this IP source address. Valid values are YES or NO.
Send_Host_Routes
Specifies whether host routes in RIP responses will be sent from this IP source
address. In this context, a host route is one with a mask of 255.255.255.255.
Valid values are YES or NO.
Send_Poisoned_Reverse_Routes
Specifies whether poisoned reverse routes over the interface will be
corresponding to the next hop. A poison reverse route is one with an infinite
metric (i.e. 16). Valid values are YES or NO.
In_Metric=inmetric
Specifies the value of the metric to be added to RIP routes received over this
interface prior to installation in the routing table. Valid values are 1 to 15.
Out_Metric=outmetric
Specifies the value of the metric to be added to RIP routes advertised over this
interface. Valid values are 0 to 15.
RipV2
Specifies whether RIP V2 will be enabled on this link. Valid values are YES or
NO.
RipV1_Routes
Specifies whether RIP V1 routes will be advertised on this RIP V2 link. Valid
values are YES or NO.
|
|
|
|
|
Authentication_Key=key
Specifies the RIP V2 authentication key. The specified key value may be an
alphanumeric string (of up to 16 characters, chosen from translation code page
1047) that is enclosed within double quotes, or any hex string that begins with
“0x”. Code pages are described in Chapter 30, “Using Translation Tables” on
page 623.
Neighbor=ip_address
Multiple neighbor statements can be coded on a RIP_Interface statement to
indicate adjacent RIP routers. This should be used when the interface is not
point-to-point, does not support broadcast, and does not support multicast. The
value can be any valid IP address.
Max_Xmit_Time=max_time
Specifies the maximum retransmit time to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 999.990 seconds.
Min_Xmit_Time=min_time
Specifies the minimum retransmit time to add to the routing table for routes that
Chapter 13. Configuring the MPROUTE Server
245
MPROUTE Server
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 99.990 seconds.
RT_Gain=rtgain
Specifies the round trip gain value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Gain=vgain
Specifies the variance gain value to add to the routing table for routes that take
this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Mult=mult
Specifies the variance multiplier value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 99.990.
Delay_Acks
The delay acknowledgments value to add to the routing table for routes that
take this interface. Specifying YES delays transmission of acknowledgments
when a packet is received with the PUSH bit on in the TCP header. Specifying
NO results in acknowledgments being returned immediately. Valid values are
YES and NO.
ACCEPT_RIP_ROUTE Statement
Allows a RIP network, subnet, or host route to be accepted independently of
whether the interface it was received on has the corresponding reception parameter
enabled (network, subnet, or host). Routes added in this manner can be thought of
as a list of exception conditions.
Accept_RIP_Route IP_address=ip_address
Operands
IP_address=ip_address
Specifies the destination route to be unconditionally accepted.
Common Configuration Statements for RIP and OSPF
This section contains descriptions of the Common configuration statements:
v DEFAULT_ROUTE
v INTERFACE
DEFAULT_ROUTE Statement
Allows the default route to be specified to MPROUTE. Default routes are created
using any of the following:
v GATEWAY statement
v Default_Route statement
v Originate_RIP_Default statement
v Learned by routing protocol
246
z/VM: TCP/IP Planning and Customization
MPROUTE Server
The Send_Default_Routes keyword on the RIP_Interface statement indicates
whether or not to advertise the default route.
Default_Route Name=interface_name Next_Hop=ip_address
Operands
Name=interface name
Specifies the name of the interface. This name must match the link name coded
for the corresponding IP address on the HOME statement in the TCP/IP profile.
Valid values are any 16 characters.
Next_Hop=ip_address
Specifies the IP address of the next hop.
INTERFACE Statement
Allows certain values to be specified for interfaces that are neither OSPF nor RIP
interfaces. Each interface that is neither an OSPF nor a RIP interface should be
configured to MPROUTE via the INTERFACE statement, unless it is a
non-point-to-point interface and the default values for for Subnet Mask and MTU are
acceptable for that interface. The default value for MTU is 576. The following table
lists the defaults for the subnet Mask:
Class Address
First Octet
Default Subnet Mask
A
(0-127)
255.0.0.0
B
(128-191)
255.255.0.0
C
(192-223)
255.255.255.0
Interface IP_address=ip_address Name=interface_name Subnet_Mask=mask
Destination_Addr=address
MTU=576
Max_Xmit_Time=120
MTU=size
Max_Xmit_Time=max_time
Min_Xmit_Time=0.5
RT_Gain=0.125
Variance_Gain=0.25
Min_Xmit_Time=min_time
RT_Gain=rtgain
Variance_Gain=vgain
Variance_Mult=2
Delay_Acks=NO
Variance_Mult=mult
Delay_Acks=YES
Operands
IP_address=ip_address
Specifies the IP address, which can be configured on the system or it can be
specified with asterisks (*) as wild cards. The valid wildcard specifications are
below. The result of coding a wild card value is that all configured interfaces
whose IP address matches the wild card will be configured as interfaces.
Chapter 13. Configuring the MPROUTE Server
247
MPROUTE Server
Configured interface IP address will be matched against possible wild cards in
the order they appear below with x.y.z.* being the best match, x.y.*.* being 2nd
best, and so forth.
x.y.z.*
x.y.*.*
x.*.*.*
*.*.*.* - Same as ALL
ALL
- Same as *.*.*.*
Name=interface_name
Specifies the name of the interface. This name must match the link name coded
for the corresponding IP address on the HOME statement in the TCP/IP profile.
Valid values are any 16 characters.
Subnet_Mask=mask
Specifies the subnet mask for the associated interface’s IP address.
Destination_Addr=address
Specifies the IP address of the host at the remote end of this interface. This
parameter is only valid for point-to-point links. If this parameter is not specified
for a point-to-point link, a route to the host at the remote end of the interface
will not be added to the TCP/IP route table. A subnet route for the interface will
be added at MPROUTE initialization independent of whether this parameter is
specified.
MTU=size
Specifies the mtu size for MPROUTE to add to the routing table for routes that
take this interface. Valid values are 0 to 65535.
Max_Xmit_Time=max_time
Specifies the maximum retransmit time to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 999.990.
Min_Xmit_Time=min_time
Specifies the minimum retransmit time to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 99.990.
RT_Gain=rtgain
Specifies the round trip gain value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Gain=vgain
Specifies the variance gain value to add to the routing table for routes that take
this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 1.0.
Variance_Mult=mult
Specifies the variance multiplier value to add to the routing table for routes that
take this interface. This value is used in the TCP/IP re-transmission time-out
calculation to determine how long to wait for an acknowledgment before
resending a packet. Valid values are 0 to 99.990.
Delay_Acks
Specifies the delay acknowledgments value to add to the routing table for
248
z/VM: TCP/IP Planning and Customization
MPROUTE Server
routes that take this interface. Specifying YES delays transmission of
acknowledgments when a packet is received with the PUSH bit on in the TCP
header. Specifying NO results in acknowledgments being returned immediately.
Valid values are YES and NO.
OSPF Routing Summary
When a router is initialized, it uses the Hello Protocol to send Hello packets to its
neighbors, and they in turn send their packets to the router. On broadcast and
point-to-point networks, the router dynamically detects its neighboring routers by
sending the Hello packets to the multicast address ALLSPFRouters (224.0.0.5);. On
non-broadcast networks you must configure information to help the router discover
its neighbors. On all multi-access networks (broadcast and non-broadcast), the
Hello Protocol also elects a designated router for the network.
Note: Native ATM networks allow IP to use the network as a Non-Broadcast MultiAccess network. Thus, OSPF should be configured assuming non-broadcast.
If you are using LAN Emulation, the network is treated as a broadcast
network, and you should configure OSPF accordingly.
The router then attempts to form adjacencies with its neighbors to synchronize their
topological databases. Adjacencies control the distribution (sending and receiving)
of the routing protocol packets as well as the distribution of the topological database
updates. On a multi-access network, the designated router determines which
routers become adjacent.
A router periodically advertises its status or link state to its adjacencies. Link state
advertisements (LSAs) flood throughout an area, ensuring that all routers have
exactly the same topological database. This database is a collection of the link state
advertisements received from each router belonging to an area. From the
information in this database, each router can calculate a shortest path tree with
itself designated as the root. Then the shortest path tree generates the routing
table.
OSPF includes the following features:
v Least-Cost Routing. Allows you to configure path costs based on any
combination of network parameters. For example, bandwidth, delay, and dollar
cost.
v No limitations to the routing metric. While RIP restricts the routing metric to 16
hops, OSPF has no restriction.
v Area Routing. Decreases the resources (memory and network bandwidth)
consumed by the protocol and provides an additional level of routing protection.
v Variable-Length Subnet Masks. Allows you to break an IP address into
variable-size subnets, conserving IP address space.
v Routing Authentication. Provides additional routing security.
OSPF supports the following physical network types:
v Point-to-Point. Networks that use a communication line to join a single pair of
routers. A 56-Kbps serial line, or channel-to channel that connects two routers is
an example of a point-to-point network.
v Broadcast. Networks that support more than two attached routers and are
capable of addressing a single physical message to all attached routers. A
token-ring network is an example of a broadcast network. Emulated LANs over
ATM treat the ATM network as a broadcast network.
Chapter 13. Configuring the MPROUTE Server
249
MPROUTE Server
v Non-Broadcast Multi-Access (NBMA). Networks that support more than two
attached routers but have no broadcast capabilities. An X.25 Public Data Network
is an example of a non-broadcast network. For OSPF to function correctly, this
network requires extra configuration information about other OSPF routers
attached to the non-broadcast network. ATM Native treats the ATM interface as a
Non-Broadcast Multiple Access (NBMA) interface.
v Point-to-Multipoint. Networks that support more than two attached routers, have
no broadcast capabilities, and are not fully meshed. A frame relay network
without PVC between all the attached routers is an example of a
Point-to-Multipoint network. Like non-broadcast networks, extra configuration
information about other OSPF routers attached to the network is required.
Designated Router
Every broadcast or non-broadcast multi-access network has a designated router
that performs two main functions for the routing protocol: it originates network link
advertisements and it becomes adjacent to all other routers on the network.
When a designated router originates network link advertisements, it lists all the
routers, including itself, currently attached to the network. The link ID for this
advertisement is the IP interface address of the designated router. By using the
subnet/network mask, the designated router obtains the IP network number.
The designated router becomes adjacent to all other routers and is tasked with
synchronizing the link state databases on the broadcast network.
The OSPF Hello protocol elects the designated router after determining the router’s
priority from the priority router field of the Hello packet. When a router’s interface
first becomes functional, it checks to see if the network currently has a designated
router. If it does, it accepts that designated router regardless of that router’s priority,
otherwise, it declares itself the designated router. If the router declares itself the
designated router at the same time that another router does, the router with the
higher router priority becomes the designated router. If both router priorities are
equal, the one with the higher router ID is elected.
Once the designated router is elected, it becomes the end-point for many
adjacencies. On a broadcast network, this optimizes the flooding procedure by
allowing the designated router to multicast its Link State Update packets to the
address ALLSPFRouters (224.0.0.5) rather than sending separate packets over
each adjacency.
250
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Configuring OSPF
OSPF Configuration Steps
The following steps outline the tasks required to get the OSPF protocol up and
running. The sections that follow explain each step in detail, including
examples.
Before your router can run the OSPF protocol, you must:
1. Set the OSPF router ID. (See “OSPF Router IDs”.)
2. Define OSPF areas attached to the router. If no OSPF areas are defined,
a single backbone area is assumed. (See “Define Backbone and Attached
OSPF Areas”.)
3. Define the router’s OSPF network interfaces. Set the cost of sending a
packet out on each interface, along with a collection of the OSPF
operating parameters. (See “Define OSPF Interfaces” on page 254.)
4. If the router interfaces to non-broadcast networks (X.25, Frame-Relay or
ATM Native), set additional interface parameters. (See “Set Non-Broadcast
Network Interface Parameters” on page 256 and “Configuring Wide Area
Subnetworks” on page 256.)
5. If you want the router to import routes learned from other routing protocols
running on this router (for example, RIP), enable AS boundary routing. In
addition, you must define whether routes are imported as Type 2 or Type 1
externals. (See “Enabling Autonomous System Boundary Routing” on
page 258.)
OSPF Router IDs
Every router in an OSPF routing domain must be assigned a unique 32-bit router
ID. Choose the value used for the OSPF router ID as follows:
v If you use the ROUTERID configuration statement, the value configured is used
as the OSPF router ID. The value must be one of the stack’s configured interface
IP addresses.
v If the ROUTERID configuration statement is not used, one of the OSPF interface
addresses will be used as the OSPF router ID.
Define Backbone and Attached OSPF Areas
Figure 2 on page 252 shows a sample diagram of the structure of an OSPF routing
domain. One division is between IP subnetworks within the OSPF domain and IP
subnetworks external to the OSPF domain. The subnetworks included within the
OSPF domain are subdivided into regions called areas. OSPF areas are collections
of contiguous IP subnetworks. The function of areas is to reduce the OSPF
overhead required to find routes to destinations in a different area. Overhead is
reduced both because less information is exchanged between routers and because
fewer CPU cycles are required for a less complex route table calculation.
Every OSPF routing domain must have at least a backbone area. The backbone is
always identified by area number 0.0.0.0. For small OSPF networks, the backbone
is the only area required. For larger networks with multiple areas, the backbone
provides a core that connects the areas. Unlike other areas, the backbone’s
subnets can be physically separate. In this case, logical connectivity of the
backbone is maintained by configuring virtual links between backbone routers
across intervening non-backbone transit areas.
Chapter 13. Configuring the MPROUTE Server
251
MPROUTE Server
Routers that attach to more than one area function as area border routers. All area
border routers are part of the backbone, so a border router must either attach
directly to a backbone IP subnet or be connected to another backbone router over a
virtual link. In addition, there must be a collection of backbone subnetworks and
virtual links that connects all of the backbone routers.
Figure 2. OSPF Areas
252
z/VM: TCP/IP Planning and Customization
MPROUTE Server
The information and algorithms used by OSPF to calculate routes vary according to
whether the destination IP subnetwork is within the same area, in a different area
within the same domain, or external to the OSPF domain. Every router maintains a
complete map of all links within its area. All router to multi-access network, network
to multi-access router, and router to router links are included in the map. A shortest
path first algorithm is used to calculate the best routes to destinations within the
area from this map. Routes between areas are calculated from summary
advertisements originated by area border routers for IP subnetworks, IP subnetwork
ranges, and autonomous system external (ASE) boundary routers located in other
areas of the OSPF domain. External routes are calculated from ASE advertisements
that are originally from ASE boundary routers, and propagated throughout the
OSPF routing domain.
The backbone is responsible for distributing inter-area routing information. The
backbone area consists of any of the following:
v Networks belonging to Area 0.0.0.0
v Routers attached to those networks
v Routers belonging to multiple areas
v Configured virtual links
Use the AREA configuration statement to define areas to which a router attaches. If
you do not use the AREA statement, the default is that all OSPF interfaces attach to
the backbone.
When area border routers are configured, parameters on the AREA and RANGE
configuration statements can be used to control what OSPF route information
crosses the area boundary.
One option is to use the AREA statement to define an area as a stub. OSPF ASE
advertisements are never flooded into stub areas. In addition, the AREA statement
has an option to suppress origination into the stub of summary advertisements for
inter-area routes. Area border routers advertise default routes into stub areas.
Traffic within the stub destined for unknown IP subnets is forwarded to the area
border router. The border router uses its more complete routing information to
forward the traffic on an appropriate path toward its destination. An area cannot be
configured as a stub if it is used as a transit area for virtual links.
In summary, you may define an area as a stub when:
1. There is no requirement for the area to handle transit backbone traffic.
2. It is acceptable for area routers to use an area-border-router-generated default
for traffic destined outside the AS.
3. There is no requirement for area routers to be AS boundary routers (OSPF
routers that advertise routes from external sources as AS external
advertisements).
In this case, only the area border routers and backbone routers will have to
calculate and maintain AS external routes.
The other option is to use IP subnet address ranges to limit the number of summary
advertisements that are used for inter-area advertisements of an area’s subnets. A
range is defined by an IP address and an address mask. Subnets are considered to
fall within the range if the subnet IP address and the range IP address match after
the range mask has been applied to both addresses.
When a range is added for an area at an area border router, the border router
suppresses summary advertisements for subnets in the areas that are included in
Chapter 13. Configuring the MPROUTE Server
253
MPROUTE Server
the range. The suppressed advertisements would have been originated into the
other areas to which the border router attaches. Instead, the area border router may
originate a single summary advertisement for the range or no advertisement at all,
depending on the option chosen with the RANGE configuration statement.
Note that if the range is not advertised, there will be no inter-area routes for any
destination that falls within the range. Also note that ranges cannot be used for
areas that are used as transit areas by virtual links.
Define OSPF Interfaces
OSPF interfaces are a subset of the IP interfaces defined to the TCP/IP stack. The
parameters configured for OSPF interfaces determine the topology of the OSPF
domain, the routes that will be chosen through the domain, and the characteristics
of the interaction between directly connected OSPF routers. The OSPF_Interface
configuration statement is used to define an OSPF interface and to specify its
characteristics.
OSPF Domain Topology
The definition of the topology of an OSPF domain depends on a definition of which
routers are directly connected across some physical media or subnetwork
technology and the area to which those connections are a part. The basic case is
for all routers attached to a physical subnetwork to be directly connected, but it is
possible to define multiple IP subnetworks over a single physical subnetwork. In
that case, OSPF will consider routers to be directly connected only when they have
OSPF interfaces attached to the same IP subnetwork. It is also possible to have
cases where routers attached to the same subnetwork do not have a direct link
layer connection.
For LAN media, directly connected OSPF routers are determined from the IP
subnetwork and physical media associated with an OSPF interface. The IP address,
along with the subnet mask, defined with the OSPF_Interface configuration
statement, determine the IP subnetwork to which the OSPF interface attaches. The
net index associated with the IP interface determines the physical subnetwork to
which the OSPF interface attaches. The broadcast capability of LANs allows OSPF
to use multicast Hello messages to discover other routers that have interfaces
attached to the same IP subnetwork.
LANs can be used to connect an OSPF router with IP hosts. In this case, it is still
necessary to define an OSPF interface to any IP subnetwork that is defined for the
LAN. Otherwise, OSPF will not generate routes with those IP subnetworks as
destinations. To prevent OSPF Hello traffic on these LANs without other attached
routers, the network can be defined as a non-broadcast multi-access network. The
router priority should also be set to zero because no designated router is required.
The requirements for configuring OSPF interfaces that attach to serial lines vary
with the lower layer technology.
For point-to-point lines, only one other router is accessible over the interface, so the
directly connected router can be determined without additional configuration.
For subnetwork technologies like Frame Relay, ATM, and X.25 that support
connections to multiple routers over a single serial line, the configuration of the
OSPF interfaces is similar to that for a LAN, but because directly connected routers
are not discovered dynamically for these subnetwork technologies, additional
254
z/VM: TCP/IP Planning and Customization
MPROUTE Server
configuration is required to specify directly connected neighbors. For more
information on the required configuration, see “Configuring Wide Area Subnetworks”
on page 256.
Costs for OSPF Links
OSPF calculates routes by finding the least-cost path to a destination. The cost of
each path is the sum of the costs for the different links in the path.
Correctly configuring the costs according to the desirability of using interfaces for
data traffic is critical for obtaining the desired routes through an OSPF domain. The
factors that make individual links more or less desirable may vary in different
networks, but the most common goal is to choose routes with the least delay and
the most capacity. In general, this policy can be achieved by making the cost of a
link inversely proportional to the bandwidth of the media used for the physical
subnetwork.
A recommended approach is to use a cost of one for the highest bandwidth
technology. For example, use the value 1 as the cost for an interface running
155 Mbps ATM.
Table 18. Sample Costs for OSPF Links
Interface Bandwidth
Cost
155 Mbps ATM
Ethernet
16 Mbps Token-Ring
4 Mbps Token-Ring
serial line
Emulated Token-Ring (See note.)
Emulated Ethernet (See note.)
1
10
6
25
Cost based on bandwidth
1
1
Note: An Emulated Token Ring or Ethernet will run at the interface speed (for
example, 155 Mbps), and should be configured with a cost of 1.
ATM can attach to networks at a slower rate than the maximum line speed. For
example, if the router has a port that is capable of 155 Mbps, and a router connects
to it with 25 Mbps, that link will still be treated as a cost of 1. The OSPF weighting
is on an interface basis.
Changing the Cost of OSPF Links
The cost of an OSPF interface can be dynamically changed using an SMSG
command. This new cost is propagated quickly throughout the OSPF routing
domain, and modifies the routing immediately.
The cost of the interface will revert to its configured value whenever the router is
restarted. To make the cost change permanent, you must reconfigure the
appropriate OSPF interface in the configuration file.
Interactions Between Neighbor Routers
A number of the values configured with the OSPF_Interface configuration statement
are used to specify parameters that control the interaction of directly connected
routers. They include:
v Retransmission interval
v Transmission delay
Chapter 13. Configuring the MPROUTE Server
255
MPROUTE Server
v
v
v
v
v
v
v
Router priority
Hello interval
Dead router interval
Demand Circuit
Hello Suppression
Poll Interval
Authentication key
In most cases, the default values can be used.
Notes:
1. The Hello interval, the dead router interval, and the authentication key must
have the same value for all OSPF routers that attach to the same IP
subnetwork. If the values are not the same, routers will fail to form direct
connections (adjacencies).
2. OSPF routers within the same IP subnetwork must be configured as boundary
routers (using the AS_BOUNDARY_ROUTING statement for MPROUTE and
using a corresponding configuration option on the adjacent OSPF router) or the
routers will fail to form direct connections and therefore fail to exchange routing
tables.
Set Non-Broadcast Network Interface Parameters
If the router is connected to a non-broadcast, multi-access network, such as an
X.25 PDN, you have to configure the following parameters to help the router
discover its OSPF neighbors. This configuration is necessary only if the router will
be eligible to become designated router of the non-broadcast network.
First configure the Non_Broadcast and NB_Poll_Interval parameters on the
OSPF_Interface configuration statement.
Then configure the IP addresses of all other OSPF routers that will be attached to
the non-broadcast network. For each router configured, you must also specify its
eligibility to become the designated router. Use the DR_Neighbor parameter for
neighbors that are eligible to become the designated router. Use the
No_DR_Neighbor parameter for neighbors that are not eligible to become the
designated router.
Setting non-broadcast can also be used to force a network without any other OSPF
routers to be advertised. The router priority for the interface should be set to zero
and no neighbors should be defined.
Configuring Wide Area Subnetworks
Frame Relay, ATM Native, and X.25 allow direct connections between multiple
routers over a single serial line. Additional configuration is required for OSPF
interfaces that attach to this kind of network. Because OSPF protocol messages are
sent directly to specific neighbors on these networks, configuration is used instead
of dynamic discovery to determine neighbor relationships and router roles.
Note: The configurations described in this section do not apply to point-to-point
networks.
OSPF can assume either of two patterns for the direct connections between routers
across these subnetworks:
v Point-to-Multipoint
256
z/VM: TCP/IP Planning and Customization
MPROUTE Server
v Non-broadcast multi-access (NBMA)
The key factor that distinguishes these two patterns is whether or not there is a
direct connection between all pairs of routers that attach to the subnetwork (full
mesh connectivity) or whether some of the routers are only connected through
multi-hop paths with other routers as intermediates (partial mesh connectivity).
Non-broadcast multi-access (NBMA) requires full mesh connectivity while
point-to-multipoint requires only partial mesh connectivity.
Point-to-multipoint is the default choice because it works for both full mesh
connectivity and partial mesh connectivity. But when full mesh connectivity is
available, NBMA is a more efficient solution.
Configuring Point-to-Multipoint Subnetworks
Point-to-multipoint can be configured more easily than NBMA because there are no
designated routers, but neighbor relationships must be configured for all pairs of
routers that will exchange data traffic directly across the point-to-multipoint subnet.
Each pair of directly connected routers will exchange Hello messages, so one side
can discover the other through these messages. The router configured to send the
first Hello message, however, must have the IP address of its neighbor configured
using the No_DR_Neighbor parameter on the OSPF_Interface statement.
It is important to remember that OSPF will not calculate the correct routes if some
of the routers attached to a subnetwork represent it as NBMA and others represent
it as point-to-multipoint. Therefore, never set Non_Broadcast=YES on the
OSPF_Interface statement for any interface to a point-to-multipoint network.
Configuring NBMA Subnetworks
For NBMA IP subnetworks, some subset of the attached OSPF routers are
configured to be eligible to be the designated router (DR). Each router eligible to be
the DR periodically sends Hello messages to all other routers eligible to be the DR.
These messages are used in the protocol to elect a DR and a backup DR. Both the
DR and the backup DR periodically exchange Hello messages with all other OSPF
routers that are attached to the NBMA IP subnetwork. Also, the flow of OSPF route
information across the NBMA IP subnetwork is only between each of the attached
routers and the DR or backup DR.
Select NBMA by setting Non_Broadcast=YES on the OSPF_Interface statement for
interfaces that attach to an NBMA subnetwork. This must be used for all interfaces
that attach to the NBMA network.
The configuration required for an OSPF router that attaches to an NBMA
subnetwork depends on whether or not that router is eligible to become the DR.
v For a router not eligible to become a DR, the Router_Priority parameter on the
OSPF_Interface statement must be set to 0.
v For a router eligible to become a DR, the OSPF_Interface statement must be
used to set the router priority to a nonzero value and the DR_Neighbor and
No_DR_Neighbor parameters must be used to identify all of the OSPF routers
with interfaces attached to the NBMA subnetwork and to indicate which of them
are eligible to become DR.
Chapter 13. Configuring the MPROUTE Server
257
MPROUTE Server
Note: In a star configuration, use the DR_Neighbor and No_DR_Neighbor
parameters at the hub (neighbors at the remote site do not need to be
configured).
Enabling Autonomous System Boundary Routing
To import routes learned from other protocols (for example, RIP) into the OSPF
domain, use the AS_Boundary_Routing configuration statement. You must do this
even if the only route you want to import is the default route (destination 0.0.0.0).
When enabling AS boundary routing, you must specify which external routes you
want to import. You can choose to import, or not to import, routes belonging to the
following categories.
v RIP routes
v Static routes
v Direct routes
For example, you could choose to import direct routes, but not RIP or static routes.
Independent of the above external categories, you can also configure whether or
not to import subnet routes into the OSPF domain. This configuration item defaults
to ENABLED (subnets are imported).
The metric type used in importing routes determines how the imported cost is
viewed by the OSPF domain. When comparing two type 2 metrics, only the external
cost is considered in picking the best route. When comparing two type 1 metrics,
the external and internal costs of the route are combined before making the
comparison. See “Configuring for Routing Protocol Comparisons” on page 259 for
an explanation of metric types.
Configuring OSPF over ATM
The options for configuring OSPF over an ATM subnetwork depend on whether
LAN Emulation or ATM Native is being used for the IP layer. In the case of LAN
Emulation, OSPF is configured in the same way as for a real LAN. For Native ATM,
the OSPF configuration options are the same as for Wide Area Subnetworks. See
“Configuring Wide Area Subnetworks” on page 256. Both NBMA and
Point-to-Multipoint configurations are supported.
Configuring OSPF Over Native ATM
OSPF over ATM Native requires the following configuration steps:
1. Use the OSPF_Interface statement for the ATM interface. Set the OSPF
parameters including Designated-Router(DR) eligibility.
2. Set Non_Broadcast=YES on the OSPF_Interface statement for the ATM
interface. This also needs to be set on all interfaces on every router that is
connected to an ATM Native Logical IP subnet (LIS).
3. Use the DR_Neighbor and No_DR_Neighbor parameters of the OSPF_Interface
statement to define the other routers on the Logical IP Subnet (LIS) that you
wish to share OSPF routing information with.
Note: All routers that are eligible to be Designated Routers (DRs) need to be
configured with the neighbor information. Only one router in every Logical
258
z/VM: TCP/IP Planning and Customization
MPROUTE Server
IP Subnet needs to be DR; however, if other routers are also configured
to be DR-eligible, the Logical IP Subnet is more capable of recovering
when an outage occurs.
Other Configuration Tasks
Setting Virtual Links
To maintain backbone connectivity, you must have all of your backbone routers
interconnected either by permanent or virtual links. You can configure virtual links
between any two area border routers that share a common non-backbone and
non-stub area. Virtual links are considered to be separate router interfaces
connecting to the backbone area. Therefore, you are asked to also specify many of
the interface parameters when configuring a virtual link.
Virtual links must be configured in each of the link’s two end-points. Note that you
must enter OSPF router IDs in the same form as IP addresses.
No cost is configured for a virtual link because the cost is the OSPF intra-area cost
between the virtual link end-points through the transit area.
Configuring for Routing Protocol Comparisons
If you use a routing protocol in addition to OSPF, or when you change your routing
protocol to OSPF, you must set the Routing Protocol Comparison.
OSPF routing in an AS occurs on these three levels: intra-area, inter-area, and
exterior.
Intra-area routing occurs when a packet’s source and destination address reside in
the same area. Information that is about other areas does not affect this type of
routing.
Inter-area routing occurs when the packet’s source and destination addresses
reside in different areas of the same AS. OSPF does inter-area routing by dividing
the path into three contiguous pieces: an intra-area path from source to an area
border router; a backbone path between the source and destination areas; and then
another intra-area path to the destination. You can visualize this high-level of routing
as a star topology with the backbone as hub and each of the areas as a spoke.
Exterior routes are paths to networks that lie outside the AS. These routes originate
either from routing protocols, such as RIP, or from static routes entered by the
network administrator. The exterior routing information provided by RIP does not
interfere with the internal routing information provided by the OSPF protocol.
AS boundary routers can import exterior routes into the OSPF routing domain.
OSPF represents these routes as AS external link advertisements.
OSPF imports external routes in separate levels. The first level, called type 1
routes, is used when the external metric is comparable to the OSPF metric (for
example, they might both use delay in milliseconds). The second level, called
external type 2 routes, assumes that the external cost is greater than the cost of
any internal OSPF (link-state) path.
Imported external routes are tagged with 32 bits of information. In a router, this
32-bit field indicates the AS number from which the route was received. This
Chapter 13. Configuring the MPROUTE Server
259
MPROUTE Server
enables more intelligent behavior when determining whether to re-advertise the
external information to other autonomous systems.
OSPF has a 4-level routing hierarchy (see Figure 3). The COMPARISON
configuration statement tells the router where the RIP/static routes fit in the OSPF
hierarchy. The two lower levels consist of the OSPF internal routes. OSPF
intra-area and inter-area routes take precedence over information obtained from any
other sources, all of which are located on a single level.
Figure 3. OSPF Routing Hierarchy
To put the RIP/static routes on the same level as OSPF external type 1 routes, set
the comparison to 1. To put the RIP/static routes on the same level as OSPF
external type 2 routes, set the comparison to 2. The default setting is 2.
For example, suppose the comparison is set to 2. In this case, when RIP routes are
imported into the OSPF domain, they will be imported as type 2 externals. All OSPF
external type 1 routes override received RIP routes, regardless of metric. However,
if the RIP routes have a smaller cost, the RIP routes override OSPF external type 2
routes. The comparison values for all of your OSPF routers must match. If the
comparison values set for the routers are inconsistent, your routing will not function
correctly.
Demand Circuit
A demand circuit can be configured for any interface. There is no dependence on
physical media or the model used by OSPF for the route calculation. When the
demand circuit is configured and there are no compatibility problems:
v Only Link State Advertisements (LSAs) with real changes will be advertised over
the interface. Normally, OSPF’s reliable flooding algorithm causes LSAs to be
refreshed with a new instance every 30 minutes even if topology changes have
occurred.
v The DoNotAge bit will be set for LSAs flooded over the interface. This is required
since they will not be refreshed over the interface.
Request Hello Suppression
This is an additional parameter that you can use to configure an interface to request
Hello suppression. This parameter will have value for point-to-point and
point-to-multipoint interfaces.
PP_Poll_Interval
If Demand Circuit and Hello Suppression are configured for an interface, the
PP_Poll_Interval parameter of the OSPF_Interface statement will be used by OSPF
to try to reestablish a connection when a point-to-point line is down because there
was a failure to transmit data but the network still appears to be operational.
260
z/VM: TCP/IP Planning and Customization
MPROUTE Server
Converting from RIP to OSPF
To convert your Autonomous System from RIP to OSPF, install OSPF one router at
a time, leaving RIP running. Gradually, all your internal routes will shift from being
learned via RIP to being learned by OSPF (OSPF routes have precedence over
RIP routes). If you want to have your routes look exactly as they did under RIP (in
order to check that the conversion is working correctly) use hop count as your
OSPF metric. Do this by setting the cost of each OSPF interface to 1.
After installing OSPF on your routers, turn on AS boundary routing in all those
routers that still need to learn routes via other protocols (BGP, RIP, and statically
configured routes). The number of these AS boundary routers should be kept to a
minimum.
Finally, you can disable the receiving of RIP information on all those routers that are
not AS boundary routers.
Chapter 13. Configuring the MPROUTE Server
261
262
z/VM: TCP/IP Planning and Customization
Chapter 14. Configuring the NDB Servers
This chapter describes how to configure the Network Database (NDB) system,
which consists of:
v The NDB Port Manager server
v One or more NDB agent servers
v The NDB client.
Note: TCP/IP for DOS, OS/2, AIX on the RISC System/6000, or Sun
Microsystems must be installed before, or in conjunction with, the NDB
client.
The NDB Port Manager, one NDB agent server, and NDB client source code are
installed with TCP/IP.
To configure the NDB system for your installation, you must perform the following
steps:
NBD System Configuration Steps
1. Define additional NDB agent servers. (Optional)
2. Update PROFILE TCPIP.
3. Update the DTCPARMS file for the NDB Port Manager and NDB agent
servers.
4. Provide NDB agents access to DB2 Server for VSE & VM.
Step 1: Define Additional NDB Agent Servers (Optional)
To run NDB, your installation must have one NDB Port Manager virtual machine
and at least one NDB agent server defined. The default TCP/IP installation
environment includes one NDB Port Manager and one NDB agent, named
NDBPMGR and NDBSRV01, respectively.
With NDB, each NDB client makes a one-to-one connection with an NDB agent for
each unit of work (UOW) performed. Thus, having more NDB agents available
allows more clients to simultaneously access the database. Up to 20 NDB agents
can be defined for use with a given TCP/IP server.
For any additional NDB agents that you define, it is recommended that you:
v maintain the NDBSRVnn naming convention
v model your CP directory entries after that supplied for the NDBSRV01 virtual
machine.
See Chapter 5, “General TCP/IP Server Configuration” on page 31 for more
information about duplicating existing servers. If necessary, consult the TCP/IP for
z/VM, Level 430 Program Directory for specific DASD storage and user ID
requirements that may be applicable to these virtual machines.
© Copyright IBM Corp. 1987, 2002
263
NDB Servers
Step 2: Update PROFILE TCPIP
Include the various NDB server virtual machines in the AUTOLOG statement of the
TCPIP configuration file. These servers are then started automatically when TCPIP
is initialized. Add a separate line for the NDP Port Manager and one each for the
NDB agents you employ. Verify that the following statements have been added to
the PROFILE TCPIP file:
AUTOLOG
NDBPMGR 0
NDBSRV01 0
NDBSRV02 0
.
.
.
NDBSRV20 0
; NDB Port Manager
; NDB Agent 1
; NDB Agent 2
; NDB Agent 20
Note: The NDB Port Manager virtual machine must be logged on before any NDB
agents.
Step 3: Update the DTCPARMS File
NDB Port Manager
When the NDB Port Manager is started, the TCP/IP server initialization program
searches specific DTCPARMS files for configuration definitions that apply to this
server. Tags that affect the NDB Port Manager are:
:Nick.NDBPMGR
NDB Agent Servers
Up to 20 NDB agents (named NDBSRV01 through NDBSRV20, by convention) can
be used with a given TCP/IP server. When these agents are started, the TCP/IP
server initialization program searches specific DTCPARMS files for configuration
definitions that apply to these servers. Tags that affect the NDB agent servers are:
:Nick.NDBSRVnn
:ESM_Enable.
:ESM_Validate.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the NDB servers if you:
v Use an ESM to authenticate and authorize access to resources managed
by the server.
v Use the RPIVAL or another module for validating user IDs and passwords.
PORTSRVS Command
The PORTSRVS command is used to initialize the NDB Port Manager:
PORTSRVS
264
z/VM: TCP/IP Planning and Customization
NDB Servers
The PORTSRVS command has no operands.
PORTCLNT Command
The PORTCLNT command is used to initialize the NDB agent servers:
PORTCLNT
-r
Specify PORTCLNT command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
-r
Specifies that the RPIVAL command is to be used to validate user IDs and
passwords. It is recommended that you do not specify this option using the
:Parms. tag, but instead specify :ESM_Enable.YES in the DTCPARMS file. For
more information on using an external security manager, see Appendix A,
“Using TCP/IP with an External Security Manager” on page 645.
Step 4: Provide NDB Agents Access to DB2 Server for VSE & VM
NDB uses the DBUTIL2 program to interface with DB2. The DB2-internal
representation of DBUTIL2 is shipped with TCP/IP as DBUTIL2 ACC_OUT and
contains a DB2 access module.
The access module must be loaded by the user ID that built the module. The
module included with TCP/IP was built by TCPMAINT and must be loaded by
TCPMAINT. The procedure to load or reload the access module is:
1. Log on to TCPMAINT and issue the following command:
ndbinit tcpmaint
2. Contact the DB2 Database Administrator for your installation to issue the
following DB2 command. This SQL command allows you to execute the
DBUTIL2 program. The DB2 command syntax is:
grant run on tcpmaint.dbutil2 to public
The NDB agent servers require access to the tables in the DB2 database to allow
NDB clients to issue DB2 commands against these tables. The NDB agent user ID
is passed to DB2 for processing a unit of work. Ask your DB2 Database
Administrator or the owner of the tables to which the NDB clients need access, to
issue the following DB2 command:
grant privilege on table to user_id
where privilege specifies any of the DB2 table privileges such as select, update
and all; table specifies the table in the DB2 database that an NDB client accesses;
and user_id specifies the user ID of one or more NDB agent servers. All NDB
agents should be granted identical privileges because a one-to-one connection is
created between an NDB client and an NDB agent for a given unit of work (UOW),
and the NDB client cannot control which NDB agent is used for that UOW.
Chapter 14. Configuring the NDB Servers
265
NDB Servers
Before using the NDB agents the first time, initialize them for using DB2. This can
be done by logging onto each NDB agent server and issuing the following
commands:
set lang (add ari user
SQLINIT dbname(dbname)
where dbname is the desired DB2 database.
For more information about DB2 commands and granting privileges on tables in
DB2, see the DB2 Server for VSE & VM: SQL Reference.
266
z/VM: TCP/IP Planning and Customization
Chapter 15. Configuring the NFS Server
The NFS server implements the Network File System (NFS), as well as PCNFSD
user ID authentication function. To configure the NFS server, you must perform the
following steps:
NFS Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the NFS server.
3. Establish NFS server machine authorizations.
4. Customize the VMNFS CONFIG file.
5. Configure NFS server file translation support. (Optional)
6. Verify NFS server operations.
7. Perform advanced NFS server configuration, if needed.
Dynamic Server Operation
The NFS server provides a VM Special Message (SMSG) interface that allows you
to perform server administration tasks through a set of privileged commands. For
more information, see “Dynamic Server Operation” on page 286.
Step 1: Update PROFILE TCPIP
Include the NFS server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The NFS server is then started automatically when
TCPIP is initialized. The IBM default user ID for this server is VMNFS. Verify that
the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
VMNFS 0
The NFS server requires that ports TCP 2049 and UDP 2049 be reserved for it.
Verify that the following statements have been added to your TCPIP server
configuration file as well:
PORT
2049 UDP VMNFS
; NFS Server
2049 TCP VMNFS NOAUTOLOG ; NFS Server
Step 2: Update the DTCPARMS File
When the NFS server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the NFS server are:
:Nick.VMNFS
:ESM_Enable.
:ESM_Validate.
:ESM_Racroute.
:Anonymous.
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
© Copyright IBM Corp. 1987, 2002
267
NFS Server
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the NFS server if you:
v Enable access to the server without requiring a VM user ID and password
(anonymous access).
v Use an External Security Manager (ESM) for client authentication and
minidisk access control.
v Access an SFS directory where trace information will be written using the
SMSG TWRITE command.
v Change the CMS SET RECALL setting for the NFS server virtual machine
to allow access to migrated SFS and BFS files.
VMNFS Command
NFS services are initiated using the VMNFS command:
VMNFS
D
G
R
A
V
U
N
M nnn
B nnn
Specify VMNFS command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
268
D
A debug flag that causes messages to be sent to the console. This operand
also causes a log file to be generated as if the (G) operand were specified.
G
Causes a binary output file named VMNFS LOG A1 to be generated that
contains a record of all RPC requests received and replies sent. Any existing
log file is erased when the NFS server is started.
R
Indicates an external security manager (ESM) is to be used for access control.
It is recommended that you specify :ESM_Enable.YES in the DTCPARMS file
instead of providing this operand as a :Parms. tag startup parameter.
A
Causes Autolink access control to be used for mount requests.
V
Forces the NFS server to accept only Version 2 (RFC 1094) requests.
U
Forces the NFS server to accept only UDP connections. TCP connections are
not permitted.
N
Indicates that ANONYMOUS mounts are permitted. It is recommended that you
z/VM: TCP/IP Planning and Customization
NFS Server
do not specify this operand as a :Parms. tag startup parameter, but instead
specify :Anonymous.YES in the DTCPARMS file.
M nnn
Sets the trace mask to nnn, where where nnn is a decimal number. The default
trace mask is zero. For information about using trace masks to diagnose NFS
server problems, consult the TCP/IP Diagnosis Guide.
B nnn
Sets the number of disk blocks, where nnn is a decimal number. The default
number of disk blocks is 256.
Using an External Security Manager
The NFS server can use an external security manager (ESM) to authenticate NFS
clients and to control access to minidisks by specifying :ESM_Enable.Yes in the
DTCPARMS file. For more information, see Appendix A, “Using TCP/IP with an
External Security Manager” on page 645.
External Security Managers can protect SFS and BFS resources. However, that
protection occurs in the file pool server machine, not in the NFS server. See z/VM:
CMS File Pool Planning, Administration, and Operation for more information.
Step 3: Establish NFS Server Machine Authorizations
The system (CP) directory entry for the NFS server virtual machine must have
OPTION DIAG88 and privilege class B specified.
For NFS clients to access files or directories in the CMS Shared File System (SFS),
the NFS server must have SFS file pool administrator authority. Each NFS server
that will provide such access must be listed on the ADMIN statement in the SFS file
pool server’s DMSPARMS file. For details on SFS file pool configuration and
administrator authority, see z/VM SFS and CRR Planning, Administration, and
Operation.
For NFS clients to access files and directories in the Byte File System (BFS), the
NFS server must have connect authority to the file pool, and the NFS server must
be defined as a POSIX "superuser". To allow this capability, the following
statements must be included in the CP directory entry for the NFS server virtual
machine:
POSIXINFO UID 0 GID 0
POSIXOPT QUERYDB ALLOW
See z/VM: OpenExtensions User’s Guide and z/VM: CP Planning and
Administration for more information about configuring the NFS server in this
manner.
Step 4: Customize the VMNFS CONFIG File
The NFS server configuration file, VMNFS CONFIG, contains configuration
parameters for the NFS server. The statements used in this file specify:
v whether the PCNFSD function is available on the NFS server.
v whether NFS clients can request a list of all mounted file systems.
v the definition of the export list.
v whether NFS clients can mount other than what is defined in the export list.
Chapter 15. Configuring the NFS Server
269
NFS Server
v how many NFS clients using the TCP transport protocol can be concurrently
handled by the NFS server.
See “NFS Configuration File Statements” for detailed information about how to
specify entries within this file.
NFS Configuration File Statements
NFS configuration file statements are processed when the NFS server is started. If
you change one of these statements while the NFS server is in operation, the
change will not be effective until the NFS server is restarted or an SMSG M
REFRESH CONFIG is issued to the NFS server.
If the VMNFS CONFIG file cannot be found or cannot be opened, NFS server
initialization continues, using the following default values:
v when the lines=ext or trans=ext keywords are used on a MOUNT, the default
file extension values used are as defined by the TCPIP DATA file. See the
Chapter 3, “Defining the TCP/IP System Parameters” on page 15 for detailed
information.
v the PCNFSD function is available on the VMNFS server
v NFS clients can obtain the list of all currently mounted file systems.
v There are no items in the export list.
v The maximum number of concurrent NFS clients using the TCP transport
protocol is 50.
If the VMNFS CONFIG file cannot be read, the NFS server terminates with an error
message.
Syntax Rules
The following syntax rules apply to statements specified in the NFS configuration
file:
v Keywords (eg. EXPORT, etc.) are treated as if they were entered in uppercase.
v Variable operands are treated as if they were entered in uppercase except for
EXPORT records, for which these operands are case sensitive.
v Configuration statements must begin and end on the same line.
v All comments must be preceded by a semicolon (;). A comment may follow a
complete keyword and data specification on a record, or it may occupy a
complete record.
v Blank records may be used to improve readability.
270
z/VM: TCP/IP Planning and Customization
NFS Server
DUMPMOUNT Statement
The DUMPMOUNT statement determines whether the NFS server should make
available to clients a list of all mounted file systems.
DUMPMOUNT YES
DUMPMOUNT NO
Operands
YES
Indicates the list of all mounted file systems is to be made available to clients.
This is the default if a DUMPMOUNT statement is not specified in the NFS
configuration file.
NO
Indicates the list of all mounted file systems is not to be made available to
clients.
Usage Notes
1. An NFS client requests the list of mounted file systems from the VMNFS server
by sending a MNTPROC_DUMP request. If DUMPMOUNT YES is configured, the
MNTPROC_DUMP reply contains the requested information.
2. DUMPMOUNT YES may make available to NFS clients the names of the SFS
and BFS directories in your file pools. If you do not want to make this
information available to any NFS client who can connect to your NFS server,
specify DUMPMOUNT NO in the NFS server configuration file.
3. The information returned in a MNTPROC_DUMP reply includes resources actively in
use by the VMNFS server. SFS and BFS directories are considered active if
used within 15 minutes. A minidisk is considered active as long as the NFS
server has that minidisk linked.
EXPORT Statement
The EXPORT statement defines an entry to be added to the NFS “export list”,
which consists of all EXPORT statements defined in the NFS configuration file. An
NFS client can obtain the export list by using the OPENVM SHOWMOUNT command.
EXPORT export_name
mount_string
Each EXPORT statement consists of a symbolic name that will be presented to
NFS clients, optionally followed by the string that will be used when the NFS server
receives a mount with a symbolic name.
Chapter 15. Configuring the NFS Server
271
NFS Server
Operands
export_name
The file system name that an NFS client can use to mount the mount_string
(specified as the next operand). The export_name operand is case sensitive
and is treated by the NFS client as a file system path name.
mount_string
An optional parameter. The mount_string identifies the file system to be
mounted and any mount options that are to be substituted when the NFS server
receives a mount request for export_name. The mount_string must be a
syntactically valid mount command; that is, the object to be mounted (minidisk,
SFS or BFS directory) followed by any options for the mount.
To assist in producing a valid mount_string the NFS server will recognize and
process the following keywords within a mount_string:
%USERID
Causes the user ID that was specified on a call to the PCNFSD
or on the userid= parameter of the MOUNTPW procedure to be
substituted in place of the %USERID keyword.
%FSROOT
Causes the FSROOT parameter of the POSIXINFO CP
directory statement to be substituted in place of the %FSROOT
keyword. The user ID specified on a call to the PCNFSD or on
the userid= parameter of the MOUNTPW procedure will be
used to look up the VM CP directory entry.
%IWDIR
Causes the IWDIR parameter of the POSIXINFO CP directory
statement to be substituted in place of the %IWDIR keyword.
The user ID specified on a call to the PCNFSD or on the
userid= parameter of the MOUNTPW procedure will be used to
look up the VM CP directory entry.
Usage Notes
1. If the EXPORTONLY YES statement is specified, then only the export list
defined by the EXPORT records in the NFS configuration file can be mounted
by NFS clients.
2. If an EXPORT statement does not specify the mount_string parameter, then the
export_name must be a syntactically valid mount command with options, if any.
3. Due to operating system-specific conventions for displaying path names to files,
it is recommended that an export_name consist of path name components that
are eight or less characters. For example, use /PC/Your/SFS/In/FPCOOL as
opposed to PC/Your_SFS_In_FPCOOL.
4. For examples of EXPORT statements, consult the sample NFS configuration
file, VMNFS SCONFIG.
5. To export BFS directories whose names include spaces, place the mount_string
within double quotation marks(″). An export name can also include spaces if it is
surrounded by double quotation marks. Keep in mind that some NFS clients
require special syntax to mount an alias with quotes and/or spaces. For
example, one client requires the following syntax to mount the directory named
“my directory” to mydir:
mount gd3vm0:\"my\directory\" mydir
6. The NFS server ignores any export entries that have aliases which have already
been used by another export entry. Initial slashes (/) are interpreted as being
nonexistent, so the aliases “/alias” and “alias” are considered equivalent.
272
z/VM: TCP/IP Planning and Customization
NFS Server
EXPORTONLY Statement
The EXPORTONLY statement restricts the file systems that can be mounted by
NFS clients to the list of EXPORT records defined in the NFS configuration file.
EXPORTONLY NO
EXPORTONLY YES
Operands
NO
Indicates there are no restrictions on the file systems that can be mounted by
an NFS client. In this case the export list augments what can be mounted. This
is the default if the EXPORTONLY statement is not specified in the NFS
configuration file.
YES
Indicates that NFS clients can mount only those file systems which are
identified by EXPORT statements within the NFS configuration file.
Usage Notes
1. If EXPORTONLY YES is specified but no EXPORT records are defined, and:
v the NFS server is being initialized with this configuration, the server
terminates with an error message.
v this configuration is put into place using an SMSG M REFRESH CONFIG
command, then the NFS server will not allow any new mounts. However, the
use of previously mounted file systems remains unaffected. A warning
message is displayed on the server console indicating that the NFS server is
in this state. To resume handling new mount requests, a new NFS
configuration file should be reloaded in which either EXPORTONLY NO or an
export list is defined.
MAXTCPUSERS Statement
The MAXTCPUSERS statement specifies the maximum number of NFS clients
using the TCP transport protocol that can be concurrently supported by the NFS
server.
MAXTCPUSERS 50
MAXTCPUSERS maxtcpusers_value
Operands
maxtcpusers_value
Defines the value to be used. If a MAXTCPUSERS statement is not specified in
Chapter 15. Configuring the NFS Server
273
NFS Server
the NFS configuration file, the NFS server defaults to supporting 50 concurrent
NFS clients that use the TCP transport protocol.
Usage Notes
1. The SMSG M REFRESH CONFIG command cannot be used to put a new
maxtcpusers_value into effect while the NFS server is in operation. To activate
the new value, the NFS server must be stopped and restarted.
2. For installations whose NFS clients are configured to use the TCP transport
protocol, the default maxtcpusers_value may need to be increased. Otherwise,
some of these users may be unable to access the NFS server. They may
experience errors indicating connections were refused or not allowed. Since it
may be difficult to determine how many users rely on use of the TCP transport
protocol, it may be desirable to initially configure an arbitrarily large
maxtcpusers_value and then revise this value over time.
To assist in tuning the maxtcpusers_value, an SMSG M QUERY CONFIG
command can be used to query the maxtcpusers_value currently in effect and
the current number of NFS clients using TCP transport protocol. Note that
values returned in the response reflect the current instance of the NFS server
since it was started or restarted. For more information about this SMSG
command, see the chapter, "Using the Network File System Commands", in the
TCP/IP User’s Guide.
3. The MAXTCPUSERS value used by the NFS server may be lower than the
maxtcpusers_value specified. Message DTCNFS1553I is displayed on the VM
NFS server console during its initialization to indicate this has occurred. There
are two reasons why this can occur:
v The NFS server requires a small number of socket connections for its use.
Therefore, if maxtcpusers_value prevents the NFS server from obtaining
these connections, MAXTCPUSERS will be set to a lower value.
v The number of socket interface control blocks (SKCBs) specified with the
SKCBPOOLSIZE statement in the TCPIP server configuration file may need
to be increased in order for the desired maxtcpusers_value to be used.
PCNFSD Statement
The PCNFSD statement specifies whether PCNFSD support is to be made
available by the NFS server.
PCNFSD YES 300
PCNFSD
YES
NO
300
lifetime
Operands
YES
Indicates that PCNFSD support is made available by the NFS server. The
default is PCNFSD YES 300, which causes PCNFSD information to be
discarded after 5 minutes (300 seconds). Specifying PCNFSD YES removes the
274
z/VM: TCP/IP Planning and Customization
NFS Server
need for a user ID and password to be supplied on mountpw and mount
requests that are submitted by clients that have PCNFSD support.
NO
Indicates that PCNFSD support is to not be made available by the NFS server.
lifetime
The number of seconds the NFS server should keep PCNFSD information
active after a PCNFSD request is received from an NFS client. The default is
300 seconds (5 minutes). After the specified lifetime, the PCNFSD information
is discarded.
VMFILETYPE Statement
The VMFILETYPE statement is supported within the NFS server configuration file
only to maintain compatibility with prior levels of TCP/IP for z/VM. File extension
support should be configured through use of an equivalent VMFILETYPE statement
within the TCPIP DATA file.
For detailed information about VMFILETYPE operands, see Chapter 3, “Defining the
TCP/IP System Parameters” on page 15.
Note: The syntax for a VMFILETYPE statement within the TCPIP DATA file differs
slightly compared to that for the NFS server configuration file.
Step 5: Configure NFS Server File Translation Support (Optional)
By default, the NFS server does not manipulate the file data it processed in
response to client requests — that is, no EBCDIC-ASCII data translation is
performed and line feed characters are not inserted at CMS record boundaries
when files are processed. However, the NFS server can be configured to perform
these actions for specific types of files, based on a file extension (or with respect to
CMS files, the file type) of a file that is referenced. This can simplify NFS operations
for various users and clients, and may even be necessary to accommodate certain
NFS clients.
To configure file translation support for the NFS server, customize the TCPIP DATA
file to include the appropriate VMFILETYPE and VMFILETYPEDEFAULT
statements. The NFS server relies upon these statements to control the manner in
which file translation and line feed processing are performed for specific file
extensions, as well as those that are “unknown” or not recognized. For detailed
information about how to specify these statements, see Chapter 3, “Defining the
TCP/IP System Parameters” on page 15.
Notes:
1. The VMFILETYPE statement determines whether EBCDIC-ASCII translation
occurs for a specific file and whether line feed characters are inserted at CMS
record boundaries, based on the extension of that file.
2. File extensions that are not dealt with through a specific VMFILETYPE
statement are considered as “unknown” (that is, are not recognized). The
translation performed for such files (if any) is controlled by the
VMFILETYPEDEFAULT statement. If the VMFILETYPEDEFAULT statement is
not used, no translation is performed and no line feed characters are inserted at
CMS record boundaries.
Chapter 15. Configuring the NFS Server
275
NFS Server
3. Case (upper or lower) is not significant when the NFS server compares the
filetype (extension) supplied in an NFS request with those on filetype
VMFILETYPE statements. For example, BIN is considered to be equivalent to
Bin.
For additional information about how NFS clients can make use of file translation,
see the TCP/IP User’s Guide.
Step 6: Verify NFS Server Operations
After the NFS server has successfully initialized, use the steps that follow to verify
that the server is configured and running correctly:
1. From another system, issue a PING command against the z/VM host to verify
that network connectivity has been established. For example:
ping vmsys1.endicott.ibm.com
2. Issue an RPCINFO command to verify that the Portmapper server is up and
running. The RPCINFO command can be issued from any platform that
supports this command. For a z/VM host, the RPCINFO command format is as
follows:
rpcinfo -p server_name
For example:
rpcinfo -p vmsys1.endicott.ibm.com
The Portmapper service should respond with a list of programs, versions,
protocols, and port numbers. This response should be similar to the following:
rpcinfo -p vmsys1
program vers proto
port
100000
2
udp
111
100000
2
tcp
111
100005
1
udp
2049
100005
3
udp
2049
100005
1
tcp
2049
100005
3
tcp
2049
100003
2
udp
2049
100003
3
udp
2049
100003
2
tcp
2049
100003
3
tcp
2049
150001
1
udp
2049
150001
2
udp
2049
Ready; T=0.04/0.08 16:38:21
portmapper
portmapper
mountd
mountd
mountd
mountd
nfs
nfs
nfs
nfs
pcnfsd
pcnfsd
If a similar response is not returned, start the Portmapper server or have this
done by the appropriate system administration personnel.
3. If your users mount using the NFS Version 3 or TCP transport protocol, verify
that the output from the RPCINFO -p command lists 3 in the vers column and
tcp in the proto column for both the mountd and nfs programs.
4. Verify that the mountd, pcnfsd, portmapper, and nfs services are operating
correctly on your VM system by entering the following VM RPCINFO
commands:
rpcinfo
rpcinfo
rpcinfo
rpcinfo
-u
-u
-u
-u
host_name
host_name
host_name
host_name
mount
pcnfsd
portmapper
nfs
If these services are running on the VM system, the following responses are
returned:
276
z/VM: TCP/IP Planning and Customization
NFS Server
Ready; T=0.02/0.06 16:45:36
* See if mount is running
rpcinfo -u vmsys1 mount
program 100005 version 1 ready and waiting
program 100005 version 2 ready and waiting
program 100005 version 3 ready and waiting
Ready; T=0.04/0.08 16:45:49
* See if portmapper is running
rpcinfo -u vmsys1 portmapper
program 100000 version 2 ready and waiting
Ready; T=0.04/0.08 16:46:40
* See if nfs is running
rpcinfo -u vmsys1 nfs
program 100003 version 2 ready and waiting
program 100003 version 3 ready and waiting
Ready; T=0.04/0.08 16:47:27
* See if pcnfsd is running
rpcinfo -u vmsys1 pcnfsd
program 150001 version 1 ready and waiting
program 150001 version 2 ready and waiting
Ready; T=0.04/0.08 16:47:53
5. Test the NFS server by issuing a mount request from a remote client. If the NFS
server terminates with a return code of 101 or 102, a request to allocate a
control block (101), or a disk block (102) buffer failed.
6. Verify the correct VMNFS CONFIG file is in effect and that this file has been
customized as intended. To do this, issue the following command:
server_id m query config
to the NFS server from an appropriately authorized user ID, such as
TCPMAINT. The response for this command can be reviewed to verify that the
EXPORTONLY statement has been correctly specified to allow or disallow users
from performing mounts. A sample SMSG QUERY CONFIG command response
follows:
smsg vmnfs m query config
Ready; T=0.01/0.01 16:39:54
16:39:54 * MSG FROM VMNFS
16:39:54 * MSG FROM VMNFS
16:39:54 * MSG FROM VMNFS
16:39:54 * MSG FROM VMNFS
16:39:54 * MSG FROM VMNFS
16:39:54 * MSG FROM VMNFS
:
:
:
:
:
:
M
M
M
M
M
M
Exportonly no, Anonymous yes, Dumpmount yes, Security CP
PCNFSD yes, time out after 300 seconds
UDP V3 buffer sizes: 8192 read, 8192 write, 8192 preferred.
TCP V3 buffer sizes: 65536 read, 65536 write, 32768 preferred.
Maximum TCP clients: 50.
No NFS clients are currently using TCP.
Step 7: Advanced Configuration Considerations
Before you complete the NFS server configuration process, you may want to review
the information in the following sections to determine if additional NFS configuration
is appropriate or necessary for your installation.
|
|
|
Prior to customizing the server exits described in this section, ensure that you have
reviewed the exit limitations and customization recommendations presented in
“Customizing Server-specific Exits” on page 43.
NFS Server Exits
Several server exits are supported for use with the NFS server that allow for greater
control over client mount requests, as well as client and administrative interaction
with the server. These exits are described in more detail in the sections that follow.
Chapter 15. Configuring the NFS Server
277
NFS Server
CMS Command Exit
The CMS command exit (VMNFSCMS EXEC) provides authorization and execution
control over CMS commands issued to the NFS server through the SMSG interface.
For example, CMS commands similar to the following might be issued by the
TCPMAINT user ID to obtain the NFS server console spool file while the server is
operating:
cp smsg vmnfs m1 cms cp sp con to tcpmaint
cp smsg vmnfs m2 cms cp clse con
cp smsg vmnfs m3 cms identify
Keep in mind the following when the CMS command exit is customized:
Notes:
1. Any security guidelines or authorization controls established for your site should
be incorporated within the exit before it is activated.
2. Consideration should also be given to traditional security issues when this exit is
modified and enabled. For example, the NFS server requires the use of
privileged commands that are denied to general users, and may have access to
files that contain passwords (such as the VMNFS HISTORY file). Measures
should be taken to ensure areas such as these are properly addressed.
3. Care should be taken so that commands or programs that may adversely affect
the NFS server are not permitted. For example, a command that overlays the
VMNFS MODULE or that causes CMS storage management changes should be
restricted from use. Likewise, a program that uses TCP/IP services — even if it
does not create a storage conflict — is likely to cause operational problems.
4. The NFS server utilizes the first command exit found in its CMS search order. If
a CMS command exit is not available to the NFS server, it rejects all SMSG
CMS commands.
CMS Command Exit Input: For each SMSG CMS command that it receives, the
NFS server stores values pertinent to that command in several GLOBALV variables
(maintained in the GLOBALV group VMNFS) which can be referenced within the
CMS command exit. These variables, and a description of the value each may
have, are listed here:
278
Variable
Description
ORIGIN_NODE
The name of the original sending host, if the SMSG
is delivered through RSCS. An asterisk (*) is
supplied if the command is not from RSCS.
ORIGIN_USERID
The virtual machine that originated the SMSG
command, if the SMSG is delivered through RSCS.
An asterisk (*) is supplied if the command is not
from RSCS.
REPLY_TAG
The replytag supplied to the NFS server for this
SMSG command.
VERB
The CMS operand of the SMSG command. For this
exit, ’CMS’ is a constant that does not change.
ARGS
The CMS command arguments supplied with the
SMSG CMS command.
SMSG
The complete, unmodified SMSG command text.
z/VM: TCP/IP Planning and Customization
NFS Server
The following are passed to the CMS command exit as command line arguments:
Argument
1
Value
Format
CMS command arguments as supplied with the SMSG
CMS command.
Character
Return Codes: The NFS server does make use of the return code established by
this exit. However, a nonzero return code will cause an informational message and
a list of GLOBALV variables and values to be displayed at the NFS server console.
CMS Command Exit Sample: A sample CMS command exit is provided as
VMNFSCMS SEXEC on the TCPMAINT 198 minidisk. Your customized exit should
be maintained on this same minidisk, with a file type of EXEC. For more information
about the supplied CMS command exit, review the content of the VMNFSCMS
SEXEC file.
Mount Monitor Exit
The mount monitor exit (VMNFSMON EXEC) provides the ability to monitor or
control all client mount requests. The monitor exit allows these requests to be
accepted or rejected based on information about the requesting user or client, such
as the client host IP address. In addition, the monitor exit may modify certain mount
string values supplied by a client before mount processing is completed.
Keep in mind the following when the mount monitor exit is customized:
Notes:
1. The NFS server utilizes the first mount monitor exit found in its CMS search
order. If a mount monitor exit is not available to the NFS server, it processes all
mount requests based only on client-supplied mount parameters.
Mount Monitor Exit Input: For each mount request that it receives, the NFS
server stores values pertinent to that request in several GLOBALV variables
(maintained in the GLOBALV group VMNFS) which can be referenced within the
mount monitor exit. These variables, and a description of the value each may have,
are listed here:
Variable
Description
ACCOUNT
The account identification string provided with the
mount request via the account= operand.
CLIENT
The IP address (in dotted-decimal format) of the
NFS client host system that issued the mount
request. For example: 9.130.48.134
FILESYSTEM
The minidisk, SFS, or BFS resource to be mounted
through this mount request. For example,
ELWOOD.191 might be supplied for a minidisk mount
request, whereas FPCOOL:ELWOOD. might be supplied
for an SFS mount, and
/../VMBFS:FPCOOL:ROOT/home/elwood/. might be
supplied for a BFS request.
LINKPASSWORD
The minidisk link password supplied with a minidisk
mount request, via the mdiskpw= operand. For SFS
and BFS mount requests, the LINKPASSWORD
value is not applicable and is not defined.
RECORD
A decimal value that corresponds to the presence
Chapter 15. Configuring the NFS Server
279
NFS Server
of trans=, lines=, and record= operands in the
mount request. Possible RECORD variable values
follow:
TYPE
280
RECORD Value
Associated Mount
Operands
136
trans=ext and
lines=ext
132
trans=ext and
lines=nl
130
trans=ext and
lines=CMS
129
trans=ext and
lines=none
72
trans=yes and
lines=ext
68
trans=yes and
lines=nl
66
either (trans=yes
and lines=CMS) or
(record=text)
65
trans=yes and
lines=none
40
trans=no and
lines=ext
36
trans=no and
lines=nl
34
either (trans=no
and lines=CMS) or
(record=binary)
33
trans=no and
lines=none
A decimal value that corresponds to the type of
mount request. Possible TYPE variable values
follow:
TYPE Value
Mount Type
17
Read-write mount request
18
Read-only mount request
USERID
The logon user ID specified with the mount request
via the userid= operand, or through a PCNFSD
request.
BYUSERID
The LOGONBY user ID specified with the mount
request via the by= operand.
z/VM: TCP/IP Planning and Customization
NFS Server
Values for the ACCOUNT, FILESYSTEM and LINKPASSWORD variables can be
modified within the mount monitor exit. Changes to values maintained by these
GLOBALV variables are then used by the NFS server when the monitor exit returns
processing control.
Note: If the FILESYSTEM value is altered, the type of file system that was
specified by the requesting client must be maintained. For example, if
FILESYSTEM originally represents a minidisk, any changed value must
continue to represent a minidisk — an SFS or BFS directory cannot be
substituted in such a case.
No command line arguments are passed to the mount monitor exit.
Return Codes: The NFS server recognizes the following exit return codes:
Return Code
0
nonzero
Meaning
Continue and process the mount request
Deny the mount request and return ″not authorized″ status to the client
Mount Monitor Exit Sample: A sample mount monitor exit is provided as
VMNFSMON SEXEC on the TCPMAINT 198 minidisk. Your customized exit should
be maintained on this same minidisk, with a file type of EXEC. For more information
about the supplied mount monitor exit, review the content of the VMNFSMON
SEXEC file.
SMSG Authorization Exit
The SMSG authorization exit (VMNFSSMG EXEC) provides the ability to control the
acceptance and processing of SMSG commands issued to the NFS server, based
on the type and purpose of an SMSG command, as well as the originator of the
command.
Keep in mind the following when the SMSG authorization exit is customized:
Notes:
1. Any security guidelines or authorization controls established for your site should
be incorporated within the exit before it is activated.
2. The NFS server utilizes the first SMSG authorization exit found in its CMS
search order. If an SMSG authorization exit is not available to the NFS server, it
accepts and processes all SMSG commands (with SMSG CMS command
processing controlled by the CMS command exit, or lack thereof).
SMSG Authorization Exit Input: For each SMSG command that it receives, the
NFS server invokes the SMSG authorization exit, with the following passed as
command line arguments:
Argument
1
2
3
Value
Format
User ID that originated the SMSG command
Node ID from which the SMSG command was issued
Text of the supplied SMSG
Character
Character
Character
Chapter 15. Configuring the NFS Server
281
NFS Server
Return Codes: The NFS server recognizes the following exit return codes:
Return Code
0
nonzero
Meaning
Accept and process the supplied SMSG command.
Do not process the supplied command — the originating user ID is not
authorized.
SMSG Authorization Exit Sample: A sample SMSG authorization exit is provided
as VMNFSSMG SEXEC on the TCPMAINT 198 minidisk. Your customized exit
should be maintained on this same minidisk, with a file type of EXEC. For more
information about the supplied SMSG authorization exit, review the content of the
VMNFSSMG SEXEC file.
Managing Translation Tables
Many different translation tables can be made available to clients, in order to
facilitate the proper ASCII/EBCDIC translation of data. The specific translation table
to be used in processing data for a given client is specified as part of its MOUNT
request, through use of the xlate=tablename operand. If the corresponding
tablename TCPXLBIN file is present in the search order for the NFS server, that
translation table is then used; if such a file is not available, the mount attempt fails.
See Chapter 30, “Using Translation Tables” on page 623 for more information about
using translation tables.
A maximum of 255 translation tables can be accommodated by the NFS server. If
this maximum is exceeded, a notification message is displayed at the NFS server
console and an I/O error is returned to any client that requests the use of a
translation table which is not already active.
The mapping of translation tables currently in use by the NFS server can be
″refreshed″ through the following actions:
1. Stop the NFS server
2. Erase the VMNFS TRANSLAT file that resides on the server 191 minidisk.
3. Restart the NFS server.
Notes:
1. Do not attempt to directly modify the VMNFS TRANSLAT file, as this can
corrupt its content.
2. When the translation table mapping is refreshed in this manner, the VMNFS
HISTORY file is also refreshed. This secondary action invalidates all current file
handles and causes a ″stale handle″ notification to be returned to any client that
attempts to use a previously-mounted file system. Thus, clients must remount
any file systems that have been in use when this type of refresh operation is
performed.
Allowing Access to Migrated SFS and BFS Files
By default, the CMS SET RECALL setting for the NFS server virtual machine is
OFF, which indicates that a reference to data within an SFS or BFS file that is in
migrated status (that is, has been moved to DFSMS/VM storage) will not cause that
data to be implicitly recalled. With respect to the NFS server, the CMS SET
RECALL OFF setting causes an NFSERR_IO error to be returned to a client when
such a reference is made.
282
z/VM: TCP/IP Planning and Customization
NFS Server
If you wish to change this setting to prevent clients from encountering this error, you
must create a server profile exit for the NFS server. Within the NFS server exit,
include the SET RECALL ON command in the BEGIN processing section of the
exit. In addition, the DTCPARMS file must include an :exit. tag that identifies the
NFS server profile exit.
Note: When the SET RECALL setting is changed to ON, NFS clients may
encounter long delays when requests and references are made for data that
is maintained in migrated files.
Managing Data Transfer Operations
Depending on the NFS protocol that is used by a client, it is possible to perform
some customization that can affect how data transfer operations are completed by
the NFS server.
If NFS version 2 protocol is used by a client, the NFS server uses a maximum of
8192 bytes for READ and WRITE data transfer operations when requests are
satisfied. This is a limitation imposed by the NFS version 2 protocol specification
that applies to both the UDP and TCP transport protocols.
For the NFS version 3 protocol, the NFS server uses data buffer values that are
defined for the TCP/IP stack to determine its maximum and preferred READ and
WRITE data transfer sizes. The UDP values used by the NFS server are based on
the LARGEENVELOPEPOOLSIZE lrg_env_size value that is specified in the
TCP/IP sever configuration file. The TCP values used are based on the
DATABUFFERPOOLSIZE buffer_size value (up to a maximum of 65,536 bytes) that
is defined within this same file. For both UDP and TCP, the actual data transfer
sizes used by the NFS server may be slightly less than their corresponding TCP/IP
server configuration values, due to the inclusion of RPC header information that is
required on all data transfers.
When NFS version 3 protocol is in use, NFS clients can determine the maximum
and preferred READ and WRITE data transfer sizes that have been established for
the NFS server (and which govern its capabilities). This information can then be
used by clients to help determine the data transfer sizes they should specify when
requests are made of the NFS server.
Adjusting TCP/IP Data Buffers
To determine the NFS version 3 maximum and preferred data sizes that are
currently in use by the NFS server, issue the following SMSG command from an
appropriately authorized user ID, such as TCPMAINT:
smsg server_id m query config
A sample response for this command follows, in which the UDP maximum and
preferred READ and WRITE data transfer sizes are each 8784 bytes, while for TCP
they are 7784 bytes:
NFS server - VM TCP/IP Level 3A0
Exportonly no, Anonymous yes, Dumpmount yes, Security ESM
PCNFSD yes, time out after 300 seconds
UDP V3 buffer sizes: 8784 read, 8784 write, 8784 preferred.
TCP V3 buffer sizes: 7784 read, 7784 write, 7784 preferred.
Maximum TCP clients: 50.
No NFS clients are currently using TCP.
If the data transfer sizes in use are not satisfactory, the following steps can be used
to change their values:
Chapter 15. Configuring the NFS Server
283
NFS Server
1. Stop the TCP/IP server.
2. Modify the appropriate values for the LARGEENVELOPEPOOLSIZE and
DATABUFFERPOOLSIZE statements in the TCP/IP server configuration file.
3. Restart the TCP/IP server.
4. Restart the NFS server.
5. Issue the SMSG previously cited SMSG command to verify the new data
transfer sizes are in effect.
Keep in mind the following when you consider whether to change data transfer size
values:
1. Changes to LARGEENVELOPEPOOLSIZE and DATABUFFERPOOLSIZE
statement values affect all TCP/IP users, not just the NFS server.
2. Current users of TCP/IP services will be affected when the TCP/IP and NFS
servers are stopped and restarted.
3. Additional virtual storage may need to be defined for the TCP/IP server virtual
machine when larger envelope or data buffer sizes are specified.
Managing File Handle Operations
File Handle Overview
A file handle is a data structure used by NFS to identify a particular file that is to be
used. File handles are generated by the NFS server in response to client requests,
such as MOUNT and LOOKUP FILE. A client saves this file handle, and returns it
when it issues subsequent requests (for example, READ FILE) that pertain to a
given file. The data present in a file handle is meaningless to the client system.
For a VM minidisk, file-level control mechanisms do not exist — only disk-level
access controls are present. If a minidisk can be mounted, all files on that minidisk
are accessible to a client. Put another way, the file handle returned for a minidisk
MOUNT represents the capability to access any file on the mounted disk. By
comparison, the VM Shared File System (SFS) and Byte File System (BFS) include
inherent file and directory-level control mechanisms. Thus, the file handles returned
to clients when these file systems are referenced are provide file-level control.
The VMNFS HISTORY File
Because the 32-bytes that comprise a file handle are not adequate for identifying
VM files, the NFS server maintains information about the file handles it distributes
to clients within a file on its 191 minidisk — the VMNFS HISTORY file. Each file
handle generated by the server is associated with record within this file. If a file
handle received by the server designates a file that is not immediately known, the
appropriate record from this history file is retrieved so that information needed to
satisfy a request (such as minidisk link and control block structure information) can
be obtained.
Note: Be aware that the VMNFS HISTORY file contains passwords. Therefore,
access restrictions appropriate for your installation should be placed on the
NFS server 191 minidisk.
Managing the VMNFS HISTORY File
Based on how NFS services are used within your environment (and due to system
management operations that may affect the NFS server), actions may at times be
necessary to manage certain aspects of the VMNFS HISTORY file.
Accommodating a Large User Population: Within the VMNFS HISTORY file,
one record is used for each distinct VM user ID that accesses a minidisk, and one
284
z/VM: TCP/IP Planning and Customization
NFS Server
record is used for each distinct VM user ID that accesses one or more SFS or BFS
directories in a given file pool. Because of this, the VMNFS HISTORY file may need
to be enlarged to accommodate installations that have a large number of users. If
this is necessary, the VMNFS HISTORY file must be increased to include additional
records, all of which must contain only binary zeros. This can be done by
appending the VMNFS HSITORY file that resides on the TCPMAINT 591 minidisk to
the active history file present on the NFS server 191 minidisk. For example,
assuming that one is logged on to the NFS server user ID and the TCPMAINT 591
minidisk is accessed at file mode E, the command:
copyfile vmnfs history e = = a (append
will add an additional 640 records to the active file on the NFS server A-disk.
Accommodating System Management and Similar Changes: On rare
occasions a file pool administrator may find it necessary to recreate (FILESERV
GENERATE) and reload all of the data maintained by a file pool server. However,
this action can create problems if NFS clients attempt to use file handles that were
created prior to the generation of a file pool, since file handles contain encoded
pointers to the objects within a file pool. For example, after a FILESERV
GENERATE operation, it is likely that a previously existing file pointer now points to
a different file, or even to a directory. For this reason, it is necessary to ensure that
all NFS-mounted SFS directories are unmounted before any file pools that contain
those directories are (re)generated.
One method of forcing all mounted SFS directories to be unmounted is to stop the
NFS server and erase the existing VMNFS HISTORY file. However, this approach
also forces any mounted BFS directories or CMS minidisks to be unmounted.
Note: It is recommended that the VMNFS HISTORY file be erased whenever a
new TCP/IP Function Level is installed.
Managing Old and Invalid File Handles: Once a file handle has been generated,
it has no intrinsic life span, so it is valid indefinitely. However, a simple way of
ensuring that file handles have a limited life span is to stop the NFS server and
erase the active VMNFS HISTORY file at regular intervals. This forces clients to
remount referenced file systems in order to receive new, valid file handles.
Notes:
1. When the VMNFS HISTORY file is erased, the VMNFS TRANSLAT file is also
refreshed when the NFS server is again initialized.
2. There is no security exposure due to attempts to use old file handles;
unauthorized access to data continues to be restricted such cases.
Using Additional Security Capabilities
File Handle Encryption (NFSFHCIP ASSEMBLE File)
To guard against the possibility that a client has modified or devised a file handle to
gain unauthorized access to a file, the NFS server has the ability to encrypt all file
handles. When enabled, each file handle that is generated by the NFS server in
response to a client request is encrypted before it is provided to the client. When a
file handle is returned to the NFS server, it is decoded to obtain the original
structure that identifies the associated file. If the server detects a tampered
encryption, the decoding process generates an invalid file handle and rejects the
accompanying request.
Chapter 15. Configuring the NFS Server
285
NFS Server
Note: File data is not encrypted by the NFS protocol, and the NFS server does not
have such capabilities. If data encryption is necessary for your environment,
this must be performed independent of NFS server operations.
The NFSFHCIP ASSEMBLE file (Network File System File Handle Cryptographic
Interface Program) can be used to invoke a cipher routine in order to encode and
decode a file handle. As supplied, this file will default to invoking a cipher program
named IPSASM, for which a corresponding IPSASM TEXT file must exist. A
different cryptographic routine can be used in place of the IPSASM routine, though
this may require minor changes to NFSFHCIP; for more information, see “Source
Code Modifications”.
Minidisk Link Monitoring (NFSBADPW C File)
When a client minidisk mount request is processed, an internal NFS server routine
(NFSBADPW) is called after an attempt has been made to link the requested
minidisk; this routine is called regardless of whether this link attempt succeeds or
fails. As supplied with TCP/IP, this routine simply issues a message which contains
details about the link failure to the NFS server console.
If additional action is desired or necessary when a link failure occurs (such as
logging data in a disk file or informing the system operator or another user of a
failure), the NFSBADPW routine can be updated or replaced, through modification
of the NFSBADPW C program source file.
Source Code Modifications
To make use of the security capabilities described in the previous sections, source
code modifications are necessary which then require the NFS server program
(VMNFS MODULE) to be rebuilt.
If file handle encryption is to be used by the NFS server, the following modifications
are required:
1. Modify the NFSFHCIP ASSEMBLE file to employ suitable calling conventions for
the encryption program that is to be used.
2. If necessary, modify the TCPBLC91 EXEC (the VMSES/E build list that is used
to build the VMNFS MODULE). Changes to this build list will be required if the
cipher routine text file (supplied with the encryption program in use) is not
named, or cannot be renamed to, IPSASM TEXT. In such a case, the IPSASM
TEXT entry within the TCPBLC91 EXEC must be changed to reflect the proper
name.
If the NFSBADPW C file is to be updated or replaced, this file must be suitably
modified and compiled, and the VMNFS MODULE must then be rebuilt.
For more information about making these modifications and rebuilding the VMNFS
MODULE within the VMSES/E environment, see the TCP/IP for z/VM, Level 430
Program Directory, beginning with the appendix that discusses VMNFS code
modifications.
Dynamic Server Operation
The VM Special Message Facility (SMSG) command provides an interactive
interface to the NFS server to:
v modify NFS server configuration attributes
v obtain various types of information about server operations and client mounts
v instruct the server to perform certain actions.
286
z/VM: TCP/IP Planning and Customization
NFS Server
Note: The NFS server SMSG authorization exit can be used to control the
acceptance and processing of SMSG commands issued to the NFS server.
For more information, see “SMSG Authorization Exit” on page 281.
For detailed information about user-oriented SMSG commands that are supported
by the NFS server, see the section titled SMSG Interface to VMNFS in the TCP/IP
User’s Guide.
SMSG Interface to the NFS Server
SMSG
server_id
replytag
Options
Options:
Refresh
CONFIG
CMS arg
TWRITE
SMSG command operands are parsed by the NFS server as blank-delimited
tokens, and case is not significant. Any tokens present after those recognized by
the NFS server are considered to be comments and are ignored.
Operands
server_id
The user ID of the NFS server virtual machine, usually VMNFS.
replytag
A character string that associates the supplied SMSG command Option with a
server response; the replytag prefaces each message issued by the NFS server
in response to the given command. Any characters (other than blank and null
characters) can be used to form a replytag, and case is not significant.
The replytag also indicates how the NFS server is to deliver its response to a
particular SMSG command. The last character of replytag has special meaning
and is interpreted by the server as follows:
The following describes how the last character of replytag is interpreted.
s
respond using the CP SMSG command.
m
respond using the CP MSG command.
n
send no response.
If the replytag does not end with one of these characters, the NFS server
chooses a response mode.
Chapter 15. Configuring the NFS Server
287
NFS Server
Refresh CONFIG
Directs the NFS server to replace existing configuration information with that
defined by current definitions in the NFS server configuration file (VMNFS
CONFIG).
Notes:
1. Except for the MAXTCPUSERS statement, all records within the NFS
configuration file are used to update NFS server configuration parameters. If
a supported configuration statement is not present within this file, the default
for that statement is used. For example, if the PCNFSD statement is
omitted, the default value of YES is used.
2. The NFS server configuration file typically resides on the TCPMAINT 198
minidisk. For changes to this file to become effective, the NFS server must
reaccess this minidisk prior to receipt of an SMSG REFRESH CONFIG
command. A reaccess of the TCPMAINT 198 minidisk can be accomplished
by issuing an appropriate SMSG CMS command to the NFS server, such
as:
smsg server_id m access 198 d
3. If changes are made to the NFS configuration file and the SMSG REFRESH
CONFIG command is not used, those changes become effective when the
NFS server is again initialized.
CMS command_arguments
Directs the NFS server to pass the supplied command_arguments to CMS for
execution. Note that all commands are processed under control of the
VMNFSCMS CMS command exit.
TWRITE
Causes trace tables to be written to file TRACEV FILE on the server A-disk.
288
z/VM: TCP/IP Planning and Customization
Chapter 16. Configuring the Portmapper Server
The Portmapper (PORTMAP) server application is used to map program numbers
and various numbers to RPC programs that request information. To configure the
Portmapper server virtual machine, you must perform the following steps:
Portmapper Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the Portmapper server.
3. Verify Portmapper services.
Step 1: Update PROFILE TCPIP
Include the Portmapper server virtual machine user ID in the AUTOLOG statement
of the TCPIP server configuration file. The Portmapper server is then automatically
started when TCPIP is initialized. The IBM default user ID for this server is
PORTMAP. Verify that the following statement has been added to the PROFILE
TCPIP file:
AUTOLOG
PORTMAP
0
Note: If your system is using the Network File System (NFS) server, the
Portmapper server must be started before the NFS server. If the NFS server
does not receive a response from a Portmapper request, it waits a period of
time for the Portmapper server to complete initialization,then tries again.
The Portmapper server requires port UDP 111 to be reserved for it. Verify that the
following statement has been added to your TCPIP server configuration file as well:
PORT
111 UDP PORTMAP
; Portmapper Server
Step 2: Update the DTCPARMS File
When the Portmapper server is started, the TCP/IP server initialization program
searches specific DTCPARMS files for configuration definitions that apply to this
server. Tags that affect the Portmapper server are:
:Nick.PORTMAP
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the Portmapper server if you
change the user ID of the virtual machine that receives the Portmapper
console output.
© Copyright IBM Corp. 1987, 2002
289
Portmapper Server
PORTMAP Command
Portmapper services are initiated using the PORTMAP command:
PORTMAP
-d
Specify PORTMAP command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
-d Turns on debug tracing. Trace information is directed to the Portmapper server
console.
Step 3: Verify Portmapper Services
To verify that Portmapper services are available:
1. If necessary, link and access the TCPMAINT 592 client code disk.
2. Issue the following command:
rpcinfo -p loopback
At a minimum, the response to this command should include the following:
program vers proto
100000
2
upd
100000
2
tcp
290
z/VM: TCP/IP Planning and Customization
port
111 portmapper
111 portmapper
Chapter 17. Configuring the REXEC Server
The REXEC server implements the Remote Execution Command protocol
(REXEC). To configure the REXEC server virtual machine, you must perform the
following steps:
REXEC Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for the REXEC server.
3. Define additional REXEC agent virtual machines. (Optional)
Step 1: Update PROFILE TCPIP
Include the REXEC server virtual machine user ID in the AUTOLOG statement of
the TCPIP server configuration file. The REXEC server is then automatically started
when TCPIP is initialized. The IBM default user ID for this server is REXECD. Verify
that the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
REXECD
0
The REXEC server requires that TCP port 512 be reserved for it. Verify that the
following statements have been added to your TCPIP server configuration file as
well:
PORT
512 TCP REXECD
514 TCP REXECD
; REXEC Server
; REXEC Server
To allow the REXEC server to manage its agent virtual machines, it must be
included in the OBEY list in PROFILE TCPIP. Verify that the following statements
are added to PROFILE TCPIP:
OBEY
REXECD
ENDOBEY
For more information about the OBEY list, see “OBEY Statement” on page 539.
Step 2: Update the DTCPARMS File
When the REXEC server is started, the TCP/IP server initialization program
searches specific DTCPARMS files for configuration definitions that apply to this
server. Tags that affect the REXEC server are:
:Nick.REXECD
:Parms.
:Anonymous.
:ESM_Enable.
:ESM_Validate.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
© Copyright IBM Corp. 1987, 2002
291
REXEC Server
Note: You should modify the DTCPARMS file for the REXEC server if you:
v Run the server with an External Security Manager (ESM), such as RACF.
v Choose to enable anonymous rexec capabilities.
v Override default command parameters for this server.
Step 3: Define Additional Anonymous REXEC Agent Virtual Machines
(Optional)
To provide support for anonymous REXEC client requests, at least one REXEC
agent virtual machine must be defined for your installation. The default TCP/IP
installation environment includes one such agent virtual machine, named
RXAGENT1.
Because anonymous REXEC requests are processed using only these agent virtual
machines, the REXEC server can respond to such requests more readily when
more than one agent machine is available.
For any additional REXEC agent machines that you define, it is recommended that
you:
v maintain the RXAGENTn naming convention
v model your CP directory entries after that supplied for the RXAGENT1 virtual
machine.
See Chapter 5, “General TCP/IP Server Configuration” on page 31 for more
information about duplicating existing servers. If necessary, consult the TCP/IP
Function Level 320 Program Directory for specific DASD storage and user ID
requirements that may be applicable to these virtual machines.
Using an External Security Manager
The REXEC server can be configured such that client authentication will be under
the control of an external security manager (ESM), such as RACF. For more
information on using an ESM, see Appendix A, “Using TCP/IP with an External
Security Manager” on page 645.
REXECD Command
REXEC services are initiated using the REXECD command:
REXECD
-?
-t 240
-t
-d
-r
-s
-e 512
timeout
-e
-h 514
port
agent_id
-h
port
Specify REXECD command operands as :Parms. tag startup parameters in your
DTCPARMS file.
292
z/VM: TCP/IP Planning and Customization
REXEC Server
Operands
-? Displays all options supported by the REXECD command.
-d Turns on debug tracing.
-r
Indicates an external security manager is used to validate VM user IDs and
passwords supplied by REXEC clients. It is recommended that you do not
specify this option using the :Parms. tag, but instead specify :ESM_Enable.YES in
the DTCPARMS file. For more information on using an external security
manager, see Appendix A, “Using TCP/IP with an External Security Manager”
on page 645.
-s agent_id
Identifies the agent_id virtual machine as a member of the anonymous client
agent server pool. Repeat this parameter to identify any additional agent
machines that will be used. It is recommended that you do not specify this
parameter using the :Parms. tag, but instead specify :Anonymous.YES in the
DTCPARMS file.
All agents must have :Class.rexec_agent and :For.rexecd (the user ID of the
REXEC server) specified in the DTCPARMS file. A default agent virtual
machine, RXAGENT1, is defined in this file.
See “Anonymous REXEC Client Processing” for more information on how
agents are used.
-t timeout
Sets idle time-out. This option specifies the time (in seconds) in which a
connection closes if there is no activity. The default time-out is 240 seconds.
-e port
Sets the REXEC port. The default REXEC port is 512.
-h port
Sets the RSH port. The default RSH port is 514.
Additional REXEC Considerations
The sections that follow provide information about operational and processing
characteristics inherent to the z/VM REXEC server implementation, which may help
with the administration and use of REXEC services within a given environment.
How the REXEC Server Uses Secondary Virtual Machines
The REXEC server uses secondary virtual machines (agents) to execute
commands passed from each ANONYMOUS or GUEST client. This allows the
REXEC server to better service multiple REXEC requests, as the multiple agents
accessible to the REXEC server help simulate a multitasking environment.
Additionally, a user’s own virtual machine can be used to process REXEC
commands; when this is done, the user machine is managed somewhat differently
than an agent machine.
Anonymous REXEC Client Processing
If :Anonymous.YES is specified in the DTCPARMS file, the REXEC server will
maintain a “pool” of agent virtual machines to handle REXEC clients that log in as
“anonymous” or “guest”. When the REXEC server is started, there is a short delay
(approximately 30 seconds) during which all agents in the pool are made ready;
during this time, REXEC clients that attempt to use anonymous services will receive
Chapter 17. Configuring the REXEC Server
293
REXEC Server
an indication that no agents are available. Once the agents are ready (logged on),
the REXEC server can accept anonymous REXEC requests.
When an anonymous REXEC command is received, the command is sent to an
available agent. That agent issues the command and returns the command
response to the REXEC server, which then sends the response back to the REXEC
client. When the transaction is complete, the agent is returned to the pool of
available agents.
Agents are reinitialized by the REXEC server when:
v the REXEC server is itself reinitialized.
v an agent is determined to be inoperable, due to a problem in processing a
command (that is, it does not return command output within the defined timeout
period).
User’s Own Virtual Machines
When a user’s own virtual machine is used to execute an REXEC-supplied
command, that machine is autologged by the REXEC server (by the XAUTOLOG
command) after the supplied user and password have been authenticated. The
given command is then processed in a manner similar to those supplied to an
anonymous agent machine. However, after the command has completed, the user’s
virtual machine is logged off, rather than returned to the anonymous agent pool.
Usage Notes
v All agent virtual machines (RXAGENTn machines) must use the REXEC server’s
PROFILE EXEC to function properly.
v Because the REXEC server and the agent or user virtual machines communicate
using CP messages, the Single Console Image Facility (SCIF) may not be used
to monitor the REXEC server, agent, or user consoles.
For more information about using REXEC commands with agent and user
machines, and restrictions on their use, see the TCP/IP User’s Guide, specifically
the chapter that deals with using the remote execution protocol.
294
z/VM: TCP/IP Planning and Customization
Chapter 18. Configuring the ROUTED Server
This chapter describes how to configure the RouteD server. It explains RouteD’s
use of the Routing Information Protocol (RIP) to help you decide if this server is
suitable for your network. It also describes configuring RouteD Virtual IP Addressing
(VIPA), which gives you the ability to route around interface, device, and network
failures. Examples for various configurations are given.
Note: This chapter uses the term “gateway” rather than the more precise term
“router” in accordance with the established Routing Information Protocol
standards.
Understanding RouteD
The routing daemon is a server that implements the Routing Information Protocol
(RIP). It provides an alternative to static TCP/IP gateway definitions. When
configured properly, the z/VM host running with RouteD becomes an active RIP
router in a TCP/IP network. The RouteD server dynamically creates and maintains
the network routing tables using RIP, which eliminates the need to manually
configure and maintain a routing table. RIP defines how gateways and routers
periodically broadcast their routing tables to adjacent nodes. This is what enables
the RouteD server to update the host routing table. For example, the RouteD server
can determine if a new route has been created, if a route is temporarily unavailable,
or if a more efficient route exists for a given destination.
Routing Information Protocol
The Routing Information Protocol (RIP), as specified in RFC 1058 (RIP version 1)
and RFC 1723 (RIP version 2), is an Interior Gateway Protocol (IGP) designed to
manage a relatively small network. IGPs are used to manage the routing
information of a single autonomous system, or a single piece of the TCP/IP
network. RIP has many limitations and is not suited for every TCP/IP environment.
Before installing the RouteD server, read RFCs 1058 and 1723 to decide if RIP can
be used to manage the routing tables of your network.
RIP uses the number of hops, or hop count, to determine the best possible route to
a host or network. The term hop count is also referred to as the metric. A gateway
is zero hops away from directly connected networks, one hop away from networks
that can be reached through one gateway, and so on. In RIP, a hop count of 16
means infinity, or that the destination cannot be reached. This limits the longest
path in the network that can be managed by RIP to 15 gateways.
The RouteD server broadcasts routing information to the gateway’s directly
connected networks every 30 seconds. The server receives updates from
neighboring gateways periodically and uses this information to update the routing
tables. If an update is not received from a gateway for 180 seconds (3 minutes),
RouteD assumes the gateway is down and sets all the routes through that gateway
to a metric of 16 (infinity). If an update is not received from such a gateway in after
an additional 120 seconds (2 minutes), RouteD deletes all routes known through
that gateway.
During the intervals specified by the interface.scan.interval and interface.poll.interval
values on the OPTIONS statement, RouteD checks to determine if a local interface
is up or down by scanning the TCP/IP interface tables. It also checks to see if an
interface has been added or reactivated.
© Copyright IBM Corp. 1987, 2002
295
ROUTED Server
For networks that are not point-to-point, such as Token-Ring and Ethernet, RouteD
receives its own broadcasted packets over the interfaces, provided that the
interfaces are active. Other networks, such as point-to-point links, cannot be
managed by RouteD unless a RouteD server is running on the host on the other
end of the link. If the other host is not running RouteD, the RouteD server does not
receive updates over the link and deletes all the routes over the point-to-point link,
as described earlier. For more information, see “Configuring a Passive Route” on
page 311.
RouteD requires routers on interfaces that do not support broadcasting (for
example, the CTC interface) to be active gateways, since it uses link-level
broadcasting to send routing updates. For more information on how to manage CTC
networks, see “Active RIP Routes” on page 298. The RouteD server never sends
routing updates to the CTC network, because it uses link-level broadcasting to send
routing updates.
ROUTED does not support equal-cost multipath routing. If equal-cost multipath
support was enabled by coding the EQUALCOSTMULTIPATH operand on the
ASSORTEDPARMS statement, the support will be disabled when the ROUTED
server is started. However, MPROUTE does support this. For more information,
refer to Chapter 13, “Configuring the MPROUTE Server” on page 223.
|
|
|
|
|
RIP Version 2
RIP Version 2 is an extension of RIP Version 1 and provides the following features:
Route Tag
The Route Tag field is used to hold an attribute that is assigned to a route
and must be preserved and readvertised with the route. The route tag field
may be used to propagate information about a route that was acquired from
an EGP (Exterior Gateway Protocol). RouteD does not generate route tags,
but will preserve them in received routes and readvertise them when
necessary.
Variable Subnetting
Variable-length subnet masks are included in routing information so that
dynamically-added routes to destinations outside subnetworks or networks
are reachable.
Next Hop
The purpose of the Next Hop field is to eliminate routing packets through
extra hops in the network. An address in the next hop field indicates an
“immediate” next hop, as opposed to the current multi-hop route. RouteD
does not generate immediate next hops, but will preserve them if they are
included in RIP packets.
Multicast for RIP-2 Packets
An IP multicast address 224.0.0.9 is reserved for RIP-2 packets. RouteD
supports sending and receiving multicasted RIP Version 2 packets on this
address.
Authentication of RIP-2 Packets for Routing Update Security
Authentication uses passwords that can be configured to be included in
outgoing RIP-2 packets for authentication by adjacent routers as routing
update security. Likewise, incoming RIP-2 packets are checked against a
local authentication password. Any outgoing or incoming RIP-1 packets are
not authenticated. For maximum security, configure RouteD so that it will
296
z/VM: TCP/IP Planning and Customization
ROUTED Server
supply and receive RIP-2 packets only and supply an authentication
password. The authentication passwords are configurable on per-interface
(router) basis.
Routing Control
Routing controls are provided to selectively control which versions of RIP
packets are to be sent or received over network interfaces. The switches
should be set based on the routing capabilities of the network and are
configurable on a per-interface (router) basis.
Supernetting Support
Supernetting is part of Classless InterDomain Routing (CIDR) function. It
provides a way to combine multiple network routes into fewer “supernet”
routes. This means that the number of network routes in the routing tables
becomes smaller for advertisements. Supernet routes are received and sent
in RIP-2 messages. If local supernet routes are defined for RouteD, they
will be advertised to adjacent routers. Local supernet routes are generated
by RouteD for interfaces with subnet masks that are less than the value of
the network class mask in value.
ATM Network Considerations
RouteD supports ATM network interfaces as gateways if the interface to the IP
network is operating in ATM LAN Emulation mode. In this case, the ATM network
interface is treated as a LAN network interface by RouteD. However, RouteD
cannot be used to manage ATM network interfaces operating in native mode. In this
case, static routes to the ATM network must be configured via the GATEWAY
statement in PROFILE TCPIP. See “GATEWAY Statement” on page 514 for more
information on how to add static routes for ATM networks. Also, to prevent RouteD
from adding or deleting routes to the ATM network through other interfaces, it is
necessary to add blocking statements in the Routed gateways file for all other
interfaces on the VM system. All IP subnet addresses in the ATM network should be
blocked for all gateways on the VM system. For more information on blocking
routes, see “RIP Input/Output Filters” on page 299.
RIP Routes
TCP/IP routes that are added and maintained by RouteD are known as RIP routes.
Only RouteD (or a similar application) can add or delete RIP routes. Furthermore, if
RouteD is terminated, RIP routes are not deleted. To help maintain the integrity of
the routing table, at initialization, RouteD deletes all RIP routes from the stack
routing table and then adds RIP routes based on BSDROUTINGPARMS settings
and the optional ETC GATEWAYS file.
RouteD RIP Route Types
RouteD supports four types of RIP Routes:
v Passive
v Permanent
v External
v Active
These route types are used to instruct RouteD on how to support gateways defined
in the ETC GATEWAYS file.
Passive RIP Routes
Passive RIP routes are known by both TCP/IP and RouteD. Information about
passive routes is put in TCP/IP’s and RouteD’s routing tables. A passive entry in
Chapter 18. Configuring the ROUTED Server
297
ROUTED Server
RouteD’s routing table is used as a place holder to prevent a route from being
propagated and from being overwritten by a competing RIP route. With the
exception of directly-connected passive routes, passive routes are not propagated;
they are known only by this router. Using passive routes can create routing loops,
therefore they need to be created carefully.
Defining passive routes such as these should be avoided:
A to C is via B.
B to C is via A.
Passive routes should be used when adding routes where the target host or
network is not running RIP. Passive routes should also be used when adding a
default route, because this is the only way to prevent a route from timing out.
Permanent Routes
Permanent routes are like passive routes except that they are propagated to other
networks. This may be necessary in certain configurations, such as when a
destination cannot propagate its own routing information. However, because it is
possible to create routing loops and because recoverability is poor, permanent
routes should be used with care. Passive routes should be used instead of
permanent routes, whenever possible.
External RIP Routes
External RIP routes are known by RouteD but not by TCP/IP. External routes are
managed by other protocols such as the External Gateway Protocol (EGP). The
RouteD server needs to know not to interfere with these routes and not to delete
them.
An external entry exists in RouteD’s routing tables as a place holder to prevent a
route from being overwritten by a competing RIP route. External routes are not
propagated. RouteD does not manage external routes. Therefore, RouteD only
knows that there is an existing route to a host or network and one that is not known
to TCP/IP.
External routes should be used when the local host is running with some type of
non-RIP routing protocol that dynamically changes the TCP/IP routing tables. The
foreign host does not need to run any routing protocol, since the only concern is
how to route traffic from the local host to the foreign host, and how to prevent
multiple routing protocols from interfering with each other.
Active RIP Routes
An active RIP route is treated as a network interface.
Active gateways are routers that are running RIP but are reached by a medium that
does not allow broadcasting and is not point-to-point. RouteD normally requires that
routers be reachable via broadcast addresses or via a point-to-point link. If the
interface is neither, then an active gateway entry can add the gateway to RouteD’s
interface list. RouteD will treat the active gateway as a network interface. Note that
the active gateway must be directly connected.
Active routes should be used when the foreign router is reachable over a
non-broadcast, non-point-to-point network and is directly connected to the local
host.
RouteD will communicate with active routers by point-to-point transmissions to the
gateway address. Routes are not added to neither RouteD nor the TCP/IP routing
298
z/VM: TCP/IP Planning and Customization
ROUTED Server
table immediately. They are added and propagated normally when route
advertisements arrive from an active gateway. The only effect of an active gateway
statement is to bypass the requirement for broadcast communication on true
point-to-point links. Interfaces that are not broadcast, not point-to-point, and are not
active gateways are assumed to be loopback interfaces to the local host. Also,
while a route to an active gateway might time out, the interface entry is never
removed. If transmissions resume, then the new routes will still be available to the
active gateways.
RouteD RIP Route Summary
Table 19. RouteD Gateway Summary
Propagated?
1
Known by
TCP/IP?
Known by
RouteD?
Timeout?
Yes
Yes
No
Passive
No
Permanent
Yes
Yes
Yes
No
External
No
No
Yes
No
Active
Yes
Yes
Yes
Yes
RIP Input/Output Filters
The RIP input/output filters provide routing table manipulation and routing control.
The filters are provided by RouteD and consist of:
1. Route Blocking (or NoReceiving)
2. Route Forwarding (Unconditional and Conditional)
3. Route Receiving (Unconditional and Conditional)
4.
5.
6.
7.
8.
9.
Route NoForwarding
Interface Broadcasting Switch
Interface RIP Switch
Default Route Only Broadcasting Switch
Virtual Route Only Broadcasting Switch
Default and Virtual Routes Only Broadcasting Switch
10. Local (directly-connected) Routes Only Broadcasting Switch
11. Triggered Updates Only Broadcasting Switch
12. Gateway NoReceiving
For more information on these RIP input/output filters, see the RouteD procedure
parameters in “ROUTED Command” on page 309 and the options statement in
“Step 5: Create the ETC GATEWAYS File (Optional)” on page 302.
Configuration Process
The steps to configure RouteD are as follows:
1. Create the RouteD configuration file.
2. Update PORT, BSDROUTINGPARMS, and GATEWAY statements in the TCPIP
profile.
1. Except directly-connected passive routes. Directly-connected passive routes are propagated to other network interfaces for network
connectivity. A directly-connected passive route is one whose gateway address is one of the local interfaces in the HOME list or is
one of the offload interfaces.
Chapter 18. Configuring the ROUTED Server
299
ROUTED Server
3. Update the ETC SERVICES file.
4. Update the DTCPARMS file (Optional).
5. Configure the ETC GATEWAYS file (Optional).
Note: If a default route is to be defined to a destination gateway or router,
configure a default route in this ETC GATEWAYS file.
Step 1: Create the RouteD Configuration File (ROUTED CONFIG)
RouteD supports sending and receiving both RIP version 1 and RIP version 2
packets. A new configuration file determines the mode of operation. A sample of this
configuration file is shipped as ROUTED SCONFIG on TCPMAINT 591. It should be
copied to TCPMAINT 198, customized, and renamed to ROUTED CONFIG.
Configuration Note: In the absence of a ROUTED CONFIG file, the server will
use the default settings;
v RIP_SUPPLY_CONTROL: RIP1
v RIP_RECEIVE_CONTROL: ANY
v RIP2_AUTHENTICATION_KEY:
(no key is defined)
Syntax Rules
The following is a list of syntax rules for the RouteD config file:
v Keywords (for example, RIP_SUPPLY_CONTROL) are treated as if they were
entered in all capital letters.
v Blank records may be used to improve readability.
v Configuration statements must start and end on the same line.
v All comments must be preceded by a ; (semicolon). A comment may follow a
complete keyword and data specification on a record, or it may occupy a
complete record.
Following are the options that can be included in the ROUTED CONFIG file:
RIP_SUPPLY_CONTROL:
RIP_RECEIVE_CONTROL:
RIP1
RIP2B
RIP2M
RIP2
NONE
ANY
RIP1
RIP2
NONE
RIP2_AUTHENTICATION_KEY:
authentication_key
RIP_SUPPLY_CONTROL:
A constant. Specifies that the keyword following will be used as the RIP supply
control for all interfaces. Possible supply controls are as follows:
300
RIP1
Unicast/Broadcast RIP Version 1 packets (Default)
RIP2B
Unicast/Broadcast RIP Version 2 packets.
z/VM: TCP/IP Planning and Customization
ROUTED Server
Note: Care must be taken when using the RIP2B option since
host route misinterpretations by adjacent routers running
RIP Version 1 can occur.
RIP2M
Multicast RIP Version 2/Broadcast RIP Version 1 packets
(Migration)
RIP2
Multicast RIP Version 2 packets
NONE
Disable sending RIP packets
RIP_RECEIVE_CONTROL:
A constant. Specifies that the keyword following will be used as the RIP receive
control for all interfaces. Possible receive controls are as follows:
RIP1
Receive RIP Version 1 packets
RIP2
Receive RIP Version 2 packets
ANY
Receive any RIP Version 1 and 2 packets (Default)
NONE
Disable receiving RIP packets
RIP2_AUTHENTICATION_KEY:
A constant. The value that follows is the authentication key.
authentication key
Specifies a plain text password containing up to 16 characters. The
authentication key is used on a server-wide basis and can contain mixed case
and blank characters. The key will be used to authenticate RIP Version 2
packets and be included in the broadcasts for authentication by adjacent routers
running RIP Version 2. A null key (no key is specified) indicates that
authentication is disabled. For maximum security, set RIP_SUPPLY_CONTROL
and RIP_RECEIVE_CONTROL to RIP2. This will discard RIP1 and
unauthenticated RIP2 packets.
Step 2: Specify Configuration Statements in PROFILE TCPIP
You should include ROUTED in the AUTOLOG statement of the PROFILE TCPIP
configuration file as a startup procedure. The ROUTED server is then automatically
started when you initiate TCPIP. Verify that the following statements have been
added to the PROFILE TCPIP file:
AUTOLOG
ROUTED
0
In the PORT statement, you must reserve port 520 UDP for ROUTED. Verify that
the following statements have been added to the PROFILE TCPIP:
PORT
520 UDP ROUTED
Use the OBEY statement to include the ROUTED user ID in the OBEY list. This
allows the RouteD server to change routing information. Verify that the following
statements have been added to the PROFILE TCPIP. Your OBEY statement can list
other privileged users, depending on your configuration.
OBEY
ROUTED
ENDOBEY
The GATEWAY and BSDROUTINGPARMS statements are used to configure
routing information in the PROFILE TCPIP configuration file. The GATEWAY
statement is used to configure static routes. The BSDROUTINGPARMS statement
is used to define the characteristics of each virtual and physical link. Routes can be
Chapter 18. Configuring the ROUTED Server
301
ROUTED Server
added with the GATEWAY statement, but are not added to RouteD’s internal routing
tables. These routes are not broadcast to other RIP servers. The GATEWAY
statement describes static routes to be added to the routing table. If RouteD is
running, then routes can still be defined using the GATEWAY statement, but these
routes are not used by RouteD and are not advertised using RIP. If you need to add
routes to gateways that do not support RouteD, use the ETC GATEWAYS file. If
you are not using RouteD, then do not use the BSDROUTINGPARMS statement to
configure routes.
Code the following on the ASSORTEDPARMS statement in PROFILE TCPIP:
ASSORTEDPARMS
IGNOREREDIRECT
SOURCEVIPA
ENDASSORTEDPARMS
Do not specify the no forwarding (NOFWD) option. To enable variable subnetting,
add the VARSUBNETTING option. If RouteD will be used to either send or receive
RIP version 2 packets, the VARSUBNETTING option must be specified in the
TCPIP profile. See “ASSORTEDPARMS Statement” on page 470 for descriptions
and examples.
Note: The specification of the VARSUBNETTING option requires that the
ASSORTEDPARMS statement be placed before the Gateway and
BSDRoutingParms statements.
Step 3: Update the ETC SERVICES file
The ETC SERVICES file contains the relationship between services and port
numbers. The file must exist for ROUTED to run. Ensure that the following line is
added to the ETC SERVICES file:
router
520/udp
route routed
Note: In the above example, the default well-known port (520) is used.
You should compare the port number configured in the ETC SERVICES file to the
port number configured for the ROUTED server in the PROFILE TCPIP file to
ensure that the port numbers are the same.
Step 4: Update the DTCPARMS File (Optional)
The TCP/IP server initialization program searches for the configuration definitions
for each server. The tags that will directly affect the ROUTED virtual machine are:
:Nick.ROUTED
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used. For more information about the DTCPARMS file,
customizing servers, and server profile exits, see Chapter 5, “General TCP/IP
Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the RouteD server if you need to
specify any of the RouteD server input parameters. See “ROUTED
Command” on page 309 for a complete list.
Step 5: Create the ETC GATEWAYS File (Optional)
The RouteD server queries the network and dynamically builds routing tables from
routing information transmitted by other routers that are directly connected to the
302
z/VM: TCP/IP Planning and Customization
ROUTED Server
network. The ETC GATEWAYS file is used to identify networks or hosts that are not
on a directly connected network, but are still accessible through other gateways.
The ETC GATEWAYS file is stored on TCPMAINT 198, which the RouteD server
reads when it starts.
Note: The ETC GATEWAYS file is not related to the GATEWAY statement used in
PROFILE TCPIP.
Passive Routes
Passive routes are not propagated; they are known only by the local host. Routes
to the gateway are maintained in the local routing tables indefinitely and are local
only to this ROUTED server.
You should use passive routes when the host or network is not running RIP, but you
want to add a route to RIP. Passive routes should also be used when adding a
default route, because this ensures that the route does not time out.
Permanent Routes
Permanent routes are like passive routes except they are propagated to other
networks. This may be necessary in certain configurations, such as when a
destination cannot propagate its routing information. However, because it is possible
to create routing loops and because recoverability is poor, permanent routes should
be used with care. Passive routes should be used instead.
External Routes
External routes are routes that should never be added to the routing table. They are
not propagated. The ROUTED server discards any routes for this destination that it
receives from other RouteD servers. An external entry exists in RouteD’s tables to
prevent the route from being overwritten by a competing RIP route.
You may need the external gateway statement for security purposes to prevent your
RouteD server from adding certain routes. External routes should be used when the
local machine is running some type of non-RIP routing protocol that dynamically
changes TCPIP’s routing tables.
Active Routes
Active gateways are routers that are running RIP, but are reached through a
medium that does not allow broadcasting and is not point-to-point, such as
HyperChannel. RouteD normally requires that routers be reachable through
broadcast addresses, or through a point-to-point link. If the interface is neither, then
an active route entry can add the gateway to RouteD’s interface list. Note that the
active gateway must be directly connected.
Active routes should be used when the foreign router is reachable over a
non-broadcast and non-point-to-point network, and is directly connected to the local
machine.
RouteD will communicate with active routes by point-to-point transmissions to the
gateway address. Routes are not added to neither RouteD’s nor TCPIP’s tables
immediately, but when route advertisements arrive from the active gateway, they will
be added and propagate as normal. The sole effect of an active gateway statement
is to bypass the requirement for broadcast communication or true point-to-point
links. Note that non-broadcast, non-point-to-point interfaces that are NOT active
gateways are assumed to be loopback interfaces to the local machine. Also note
that while a route to an active gateway may timeout, the interface entry is never
removed. If transmissions resume, the new routes will still be to active gateways.
Chapter 18. Configuring the ROUTED Server
303
ROUTED Server
Syntax Rules
v Keywords can be specified in mixed case.
v Blanks and comments are supported in the ETC GATEWAYS file. Comments are
identified by a semicolon in column 1.
v The ETC GATEWAYS definitions are comprised of a routing statement or
OPTION statement, or both. The following describes the syntax for the routing
statement. The description of the syntax for the OPTION statement is described
on page 306.
The syntax for the routing statement for the ETC GATEWAYS file follows:
net
host
active
Routing Details
passive
permanent
external
active
mask
subnetmask
Routing Details:
name1 gateway
name2
=
metric hop count
net
Indicates the route goes to a network.
host
Indicates the route goes to a specific host.
active
Indicates the route to the gateway will be treated as a network interface. Active
gateways are routers that are running RIP, but can only be reached through a
network that does not allow broadcasting and is not point-to-point.
name1
Can be either a symbolic name or the IP address of the destination network or
host. If an IP address is specified, it must be in the standard dotted decimal
notation. All numbers will be interpreted as decimal values only. name1 must be
specified as “active” if this is for an active gateway. The last entry in the file
must specify an active gateway.
gateway
A constant. The parameters that follow this keyword identify the gateway or
router for this destination.
name2
Indicates either a symbolic name or the IP address of the gateway router for
this destination, or an equals sign (=) to indicate that the gateway is the same
as the destination network specified by name1. If an IP address is specified, it
must be in the standard dotted decimal notation. All numbers will be interpreted
as decimal values only.
metric
A constant. The value that follows this keyword is the hop count to the
destination host or network.
304
z/VM: TCP/IP Planning and Customization
ROUTED Server
hop count
The hop count to this destination. This number is an integer from 0 to 15.
passive
A passive gateway does not exchange routing information. Information about
the passive gateway is maintained in the local routing tables indefinitely and is
only local to this RouteD server. Passive gateway entries are not included in
any routing information that is transmitted. Directly connected passive routes
are included in routing information that is transmitted.
permanent
A permanent gateway exchanges passive type routing information through
RouteD. This may be necessary in certain configurations where a destination
cannot propagate its own routing information.
external
An external gateway parameter indicates that entries for this destination should
never be added to the routing table. The RouteD server discards any routes for
this destination that it receives from other routers. Only the destination field is
significant. The gateway and metric fields are ignored.
active
Active gateways are treated as network interfaces. Active gateways are routers
that are running RIP, but can only be reached through a network that does not
allow broadcasting and is not point-to-point.
mask
A constant. The value that follows this keyword is the subnet mask for the
route.
subnetmask
A bit mask (expressed in dotted-decimal form) defining the subnetwork mask for
a network route. The bits must be contiguous in the network portion of the
subnetmask. If the subnetmask is not specified, RouteD will default the
subnetwork mask to an interface subnetwork mask that matches the route’s
network. If there is no interface match, the network class mask for the route is
used.
Note: For more information on passive, external, and active gateways, see
“RouteD RIP Route Types” on page 297.
The following example shows the contents of an ETC GATEWAYS file containing
multiple entries:
net
host
host
active
net
acmenet
vm3.ibm.com
bad.host
active
0.0.0.0
gateway
gateway
gateway
gateway
gateway
gateway.acme.com metric 5 passive
9.67.43.126
metric 6 passive
xxx
metric 1 external
9.3.1.110
metric 3 active
9.67.112.1
metric 1 passive
In the first entry, the route indicates that acmenet can be reached through the
gateway gateway.acme.com, which is 5 hops away.
In the second entry, the route indicates that vm3.ibm.com can be reached through
the gateway 9.67.43.126, which is 6 hops away.
In the third entry, the external gateway parameter indicates that routes for the host
bad.host should not be added to the routing tables, and routes received from other
RouteD servers for bad.host should not be accepted.
Chapter 18. Configuring the ROUTED Server
305
ROUTED Server
The fourth entry shows an active gateway.
The fifth entry shows a default route to the destination gateway 9.67.112.1.
The syntax for the OPTIONS statement for the ETC GATEWAYS file follows:
OPTIONS
gateway ip_addr
block
noreceive
none
interface.poll.interval timer_value
interface.scan.interval timer_value
interface name ip_addr block destination
interface name ip_addr forward destination fmask fmask
interface name ip_addr forward.cond destination fmask fmask
interface name ip_addr noforward destination fmask fmask
interface name ip_addr none
interface name ip_addr noreceive destination fmask fmask
interface name ip_addr passive
interface name ip_addr ripon
interface name ip_addr ripoff
interface name ip_addr receive destination fmask fmask
interface name ip_addr receive.cond destination fmask fmask
interface name ip_addr supply off
interface name ip_addr supply on
interface name ip_addr key
authentication_key
interface name ip_addr nokey
interface name ip_addr supply.control
RIP1
RIP2B
RIP2M
RIP2
NONE
interface name ip_addr receive.control
RIP1
RIP2
ANY
NONE
gateway
A constant. The value that follows this keyword identifies the gateway or router.
ip_addr
Specifies the internet address of the interface associated with the
interface name. When the none suboption is specified for the gateway
option, ip_addr can be specified as an asterisk (*) to signify all internet
addresses or all gateway addresses.
block For the gateway option, specifies that routing table broadcasts from this
gateway are to be ignored. This option is provided as a RIP input filter.
noreceive
See description for block.
none
For the gateway option, specifies that any RIP filter options for this
gateway are to be turned off or reset. If ip_addr is specified as an
asterisk (*), all gateway entries with gateway options will be cleared.
interface.poll.interval
Specifies the time interval in seconds for the interface poll interval. RouteD uses
this timer value to check existing interfaces for up/down status only. Triggered
306
z/VM: TCP/IP Planning and Customization
ROUTED Server
updates are issued during interface outages to inform adjacent routers of
unreachable routes so that alternative routes can be discovered.
timer_value
The range is from 15 to 180 seconds, in multiples of 15 seconds. The
default is 30 seconds.
interface.scan.interval
Specifies the time interval in seconds for the interface scan interval. RouteD
uses this timer value to rescan existing interfaces for up/down status, new
interfaces, and new HOME lists. New interfaces and HOME lists are
dynamically added with the OBEYFILE command.
timer_value
The range is from 30 to 180 seconds in multiples of 30 seconds. The
default is 60 seconds.
interface
A constant
name
Specifies the name of the interface, as used in the HOME list. When
the none suboption is specified for the interface option, name can be
specified as an asterisk (*) to signify all internet addresses or all
gateway addresses.
ip_addr
Specifies the internet address of the interface associated with the
interface name. When the none suboption is specified for the interface
option, ip_addr can be specified as an asterisk (*) to signify all internet
addresses or all gateway addresses.
block For the interface option, specifies that the destination route in the
received broadcasts for this interface is to be ignored. This option is
provided as a RIP input filter.
destination
Specifies the destination route in network, subnetwork, or host format. A
specification of an asterisk (*) indicates that all destination routes to be
used with the noforward and noreceive options. This serves as a
″blackhole″ filter option that can be used to filter out all routes
broadcast over an interface and allow routes with specified forward and
receive filter to be used.
fmask Specifies an optional filter mask that can be used to apply the filter to
multiple routes in just a single options statement. The fmask is NOT a
subnet mask; it is merely used to filter out multiple routes in a single
options statement.
forward
Specifies that the destination route in the routing table broadcasts is to
be forwarded to this interface only. This option is provided as a RIP
output filter and can be used for inbound and outbound traffic splitting.
forward.cond
Specifies that the destination route in the routing table broadcasts is to
be forwarded to this interface only when the interface is active. In case
of an interface outage, RouteD will include the destination route in the
routing table broadcasts to other active interfaces. This option is
provided as a RIP output filter and can be used for inbound and
outbound traffic splitting.
Chapter 18. Configuring the ROUTED Server
307
ROUTED Server
noforward
Specifies that the destination route in the routing table is not to be
forwarded. This option is provided as a RIP output filter.
passive
Same as ripoff.
receive
Specifies that the destination route is to be received over this interface
only. If it is received over any other interface, the route is discarded.
This option is provided as a RIP input filter.
receive.cond
Specifies that the destination route is to be received over this interface
only when the interface is active. In case of an interface outage,
RouteD will include the destination route in the routing table broadcasts
to other active interfaces. This option is provided as a RIP input filter.
ripoff
Specifies that RIP is disabled for this interface. RouteD will not
broadcast and will ignore routing updates. This option is provided as a
RIP input and output filter.
ripon
Specifies that RIP is enabled for the interface. This is the default for all
interfaces. This option should be used when RIP has been previously
disabled for an interface with the ripoff option, but is now required to be
enabled for that interface.
supply off
Specifies that broadcasting is disabled for this interface. RouteD will not
broadcast, but continues to receive routing updates. This option is
provided as a RIP output filter.
supply on
Specifies that broadcasting is enabled for this interface. This option is
provided as a RIP output filter.
none
For the interface option, specifies that any RIP filter options for this
interface are to be turned off or reset. If ip_addr is specified as an
asterisk (*), all gateway entries with gateway options will be cleared.
authentication_key
An authentication key containing up to 16 characters to be used for this
interface, which is used to override the RouteD config file setting. The
key will start with the first character and end at the last character in the
string on the line. A null key (no key is specified) indicates that
authentication is disabled for the interface.
nokey Specifies that authentication is disabled for this interface, even though
the router-wide specification from the RouteD config file is defined.
supply.control
A constant. Specifies that the keyword following is to be used as the
RIP supply control for this interface and is used to override the RouteD
profile setting. Possible supply controls are as follows:
RIP1
Unicast/Broadcast RIP Version 1 packets (Default)
RIP2B
Unicast/Broadcast RIP Version 2 packets.
Note: For more information about using RIP2B, see
Usage Note Number 5 on page 309
308
z/VM: TCP/IP Planning and Customization
ROUTED Server
RIP2M
Unicast RIP Version 2/Broadcast RIP Version 1 packets
(Migration)
RIP2
Unicast RIP Version 2 packets
NONE
Disable sending RIP packets
receive.control
A constant. Specifies that the variable following is to be used as the
RIP receive control for this interface and is used to override the RouteD
profile setting. Possible receive controls are as follows:
RIP1
Receive RIP Version 1 packets
RIP2
Receive RIP Version 2 packets
ANY
Receive any RIP Version 1 and 2 packets (Default)
NONE
Disable receiving RIP packets
The following example shows the options entries of an ETC GATEWAYS file:
options
options
options
options
options
options
options
options
options
options
options
options
options
options
options
options
options
gateway 9.2.1.4 noreceive
gateway 9.2.1.4 none
gateway * none
interface.poll.interval 15
interface.scan.interval 90
interface ETH1 10.1.1.1 passive
interface ETH1 10.1.1.1 supply off
interface ETH1 10.1.1.1 receive.control rip2
interface ETH1 10.1.1.1 key
interface CTC0 9.67.114.22 key "shredder"
interface ETH1 10.1.1.1 none
interface * * none
interface TR1 9.67.112.25 block 9.1.0.0
interface TR1 9.67.112.25 supply.control rip1
interface TR1 9.67.112.25 forward 11.0.0.0
interface TR1 9.67.112.25 forward.cond 12.0.0.0
interface tr1 9.1.1.1 forward 9.2.0.0 fmask 255.255.0.0
v Any route that matches 9.2.x.x will be forwarded over the tr1 interface and
filtered out on all other interfaces.
Usage Notes
1. The NORECEIVE filter is a replacement for the BLOCK filter.
2. The FORWARD filters are used to control which routes are advertised over
which interfaces.
3. The RECEIVE filters are used to control which routes are accepted over which
interfaces.
4. NONE is used to clear all filters for a given interface.
5. Care must be taken when using the RIP2B option since host route
misinterpretations by adjacent routers running RIP Version 1 can occur.
ROUTED Command
The RouteD command is used to accept the command line parameters listed below.
These parameters are valid when starting the program from either the CMS
command line or through DTCPARMS.
Chapter 18. Configuring the ROUTED Server
309
ROUTED Server
ROUTED parms
Operands
parms
Any one or more of the following parameters separated by a space. The [q]
form of an operand deactivates the function associated with that operand.
-f
Flush all indirect routes known by RouteD from IP routing tables.
-fh
Flush all indirect host routes known by RouteD from IP routing tables.
-g[q]
Enables the default router. When this option is specified, RouteD will add a
default route to its routing information, and broadcast it over all local
interfaces. If the adjacent routers add the default route to their routing
tables, RouteD will receive all unknown packets from them and funnel them
to a destination router, provided that a default route is defined. If you use
this option, you should define a default route to a destination router in the
gateways file. See “Configuring a Default Route” on page 314.
Note: Do not use this option if default routes are to be learned dynamically
from adjacent routers.
-h[q]
Include host routes, in addition to network routes, for the broadcasts.
Adjacent routers should support Host Route Broadcasting to prevent
NETWORK UNREACHABLE problems from occurring.
-hv[q]
Include only virtual host routes, in addition to network routes, for the
broadcasts. Adjacent routers should support Host Route Broadcasting, or
network or subnetwork portions of VIPA addresses must be unique for each
TCP/IP image.
-q Suppresses broadcasting of routing information.
-s[q]
Forces RouteD to supply routing information, regardless of whether it is
acting as an internetwork router. This is the default if multiple network
interfaces are present or if a point-to-point link is used.
-sd[q]
Supplies default route only. When this option is specified, the -g parameter
is set internally. This option is provided as a RIP output filter.
-sdv[q]
-svd[q]
Supplies (broadcasts) virtual routes and default routes only. See parameter
descriptions for -sv and -sd. This option is provided as a RIP output filter.
-shv[q]
310
z/VM: TCP/IP Planning and Customization
ROUTED Server
-svh[q]
Supplies (broadcasts) virtual (network and host) routes. This option is
provided as a RIP output filter.
-sl[q]
Supplies local (directly-connected) routes only. This option is provided as a
RIP output filter.
-st[q]
Supplies triggered updates only. This is similar to the -q parameter, except
that RouteD will supply network unreachable routing information during
interface outages so that adjacent routers can recover by switching to
different routes, rather than relying on three-minute timeouts. This option is
provided as a RIP output filter.
-sv[q]
Supplies virtual routes only. Recommended usage is when multiple network
adapters in a TCPIP stack are in the same network; otherwise, network
connectivity problems will occur. This option is provided as a RIP output
filter.
Usage Notes
1. For information on the trace and debug options supported by the RouteD server,
see the “Activating RouteD Trace and Debug” section of the TCP/IP Diagnosis
Guide.
2. Many of these commands and parameters may be enabled or disabled without
restarting the RouteD server. See “Using the SMSG Interface to RouteD” on
page 319 for information on modifying RouteD operational characteristics.
Configuration Examples
This section contains examples for configuring the RouteD server. The following
example illustrates a RouteD configuration.
Figure 4. RouteD Configuration Example
Configuring a Passive Route
In Figure 4, assume that your z/VM server is host1 and is running a RouteD server.
The other two hosts, host2 and host3, are not running a RIP server. Your RouteD
server does not learn a route to host3, because host2 is not running a RIP server.
Your RouteD server sends routing updates to host3 over the link to host2 but never
Chapter 18. Configuring the ROUTED Server
311
ROUTED Server
receives a routing update from host2. After 180 seconds, your RouteD server
deletes the route to host2. This problem is inherent to the RIP protocol and cannot
be prevented.
To solve the problem, you should add a passive route to this host in the gateways
file. Host1 will maintain this route in its local routing tables indefinitely (no timeout).
You can use either of the following gateway statements:
host
host3
gateway
host2
metric 2
passive
host
192.10.10.2
gateway
192.10.20.2
metric 2
passive
Similarly, if host2 is not running a RIP server, you can define a directly-connected
passive route to it as follows:
host
host2
gateway
host1
metric 1
passive
A directly-connected passive route is one whose gateway address or name is one
of the local interfaces in the HOME list or is one of the offload interfaces.
Assume that your z/VM server is now host2 and is running a RouteD server. host1
is also running a RIP server, but host3 is not. Your RouteD server sends routing
information updates to host3 over the link to host3 but never receives a routing
update from host3. After 180 seconds, your RouteD server deletes the route to
host3.
You should add a passive route to this host as follows:
host
host3
gateway
host2
metric 1
passive
host1 cannot reach host3 unless a passive routing entry is added to host1. For
example:
host
host3
gateway
host2
metric
2
passive
or
host
192.10.10.2
gateway
192.10.20.2
metric
2
passive
Configuring an External Route
In Figure 4 on page 311, assume that your z/VM server is again host1, which is
running a RouteD server. The other two hosts, host2 and host3, are also running
RIP servers. Your RouteD server normally learns a route to host3 from host2,
because host2 is running a RIP server. You might not want host1 to route to host3
for security reasons. For example, a university might want to prevent student hosts
from routing to administrative hosts.
To prevent your RouteD server on host1 from adding a route to host3, add an
external route to the gateways file. You can use either of the following gateway
statements:
host
host3
gateway
host2
metric 2
external
host
192.10.10.2
gateway
192.10.20.2
metric 2
external
This place holder entry will keep RouteD from adding and propagating the route to
this destination host3.
312
z/VM: TCP/IP Planning and Customization
ROUTED Server
Configuring an Active Gateway
155.80.10
Host1
.2
.1
Device1
.3
Router 1
Router 2
LAN
Figure 5. Configuring an Active Gateway
As shown in Figure 5, your z/VM server is host1, which is running a RouteD server,
and device1 is a network interface device that does not support link-level
broadcasting, or one that does not support ARP processing (for example,
HYPERchannel). Also, host1 is channel-connected to device1 as a hyperchannel
device, and there are routers router1 and router2 on the local area network.
Because the IP addresses for router1 and router2 are unknown by host1, they
must be manually configured in host1 for RouteD to communicate with them.
Configuring active gateways for router1 and router2 as remote network interfaces
enables RouteD to send RIP updates to them. Include the following definitions in
the PROFILE TCPIP for host1, router1 and router2:
1. Specify DEVICE and LINK statements for the hyperchannel. For example:
DEVICE HYPER1 HCH CE2
LINK
HYPER1A HCH 2
HYPER1A
2. Add the TRANSLATE statement for the remote routers on the local area
network attached to the hyperchannel device.
TRANSLATE 155.80.10.2 HCH HYPER1A
TRANSLATE 155.80.10.3 HCH HYPER1A
3. Add the hyperchannel link to the HOME statement for assignment of a local IP
address.
HOME
155.80.10.1
HYPER1A
4. Add the hyperchannel link to the BSDROUTINGPARMS statement.
BSDROUTINGPARMS false
HYPER1A 16384 0
255.255.240.0
ENDBSDROUTINGPARMS
0
5. Define an active gateways for the remote routers in the ETC GATEWAYS file.
active
active
active
active
gateway
gateway
155.80.10.2
155.80.10.3
metric
metric
1
1
active
active
Given these active gateway addresses, RouteD will use them as the destinations
for RIP updates to the remote routers. In addition, RouteD will continue to receive
RIP updates from the active gateways over the hyperchannel device.
Configuring a Point-to-Point Link
The RouteD server can manage point-to-point links, as long as there are RIP
services at both ends of the links. If a host router at the other end of a link is not
running a RIP server, then passive or permanent routing must be configured in the
RouteD ETC GATEWAYS file for the link. See “Configuring a Passive Route” on
page 311.
Chapter 18. Configuring the ROUTED Server
313
ROUTED Server
Configuring a Default Route
A default route is typically used on a gateway or router to an internet, or on a
gateway or router that uses another routing protocol and whose routes are not
reported to other local gateways or routers.
To configure a route to a default destination, add a default route using the passive
route definition in the ETC GATEWAYS file. For example, if the default destination
router has a gateway address 9.67.112.1, add the following entry to the ETC
GATEWAYS file:
net
0.0.0.0
gateway
9.67.112.1
metric
1
passive
Only one default route to a destination gateway or router can be specified. RouteD
currently does not support multiple default routes.
Configuring Multiple Subnets with the Same IP Address
It is possible for a network topology to include different internal subnets that each
have the same IP subnet address (for example, the two 140.48.96 subnets,
Subnet(A) and Subnet(B) in Figure 6 on page 315). This topology can lead to
routing ambiguity; however, the RouteD server is able to recognize this topology
and dynamically build the routing table entries that are required to direct traffic
throughout such a network.
For such a topology, ″network unreachable″ conditions may arise when attempts
are made to connect to certain hosts before RouteD has fully initialized its routing
tables (which typically requires four to five minutes). For the network shown in
Figure 6 on page 315, this might occur if an attempt is made to connect (or simply
ping) from Host A to either Host D or Host C, which in either case, requires routing
through one of the identically addressed 140.48.96 subnets. However, the
unreachable subnet will become reachable once RouteD has initialized its routing
tables.
To avoid such problems, define one of the duplicated subnet addresses to have a
different subnet address that makes use of variable subnetting. For instance,
change Subnet(B) in this sample network to have a subnet address of
140.48.96.64. This will alleviate subnetting ambiguity during RouteD initialization
and will ensure that both subnet networks are reachable. Subnetting values for this
revised network are listed in Table 20 on page 315.
314
z/VM: TCP/IP Planning and Customization
ROUTED Server
Host D
140.48.96.51
Subnet(A) 140.48.96
140.48.96.52
Internet
140.48.32.2
Host A
140.48.32.1
Subnet(C) 140.48.32
Host B
140.48.96.66
140.48.96
Subnet(B)
140.48.96.65
Host C
Figure 6. Configuring Multiple Subnets with the Same IP Address
Table 20. Configuring Multiple Subnets with the Same IP Address
HOST
HOST A
IP ADDRESS
SUBNET MASK
SUBNET ID
HOST ID
140.48.32.2
255.255.255.0
140.48.32
2
140.48.96.66
255.255.255.192
140.48.96.64
2
140.48.32.1
255.255.255.0
140.48.32
1
140.48.96.52
255.255.255.0
140.48.96
52
HOST C
140.48.96.65
255.255.255.192
140.48.96.64
1
HOST D
140.48.96.51
255.255.255.0
140.48.96
51
HOST B
Representative HOME and BSDROUTINGPARMS statements for Host A’s TCP/IP
configuration for this (revised) sample network are provided here:
HOME
140.48.32.2
140.48.96.66
TR2
TR1
BSDROUTINGPARMS FALSE
; Link Name MTU
Metric
; --------- ----- ------TR2
2000
0
TR1
2000
0
ENDBSDROUTINGPARMS
Subnet Mask
Destination Address
--------------- ------------------255.255.255.0
0
255.255.255.192
0
Configuring RouteD with VIPA
Using RouteD with VIPA gives you the ability to route around interface, device, and
network failures.
Assume that you want to configure a VIPA address in a z/VM TCP/IP stack as in
Figure 7 on page 317. Here are the configuration steps:
1. Configure the DEVICE, LINK, HOME, ASSORTEDPARMS statements for a
VIPA address as described in “Configuring VIPA” on page 459. The assigned
VIPA address is 9.1.1.1, and the link name is “VIPA”.
2. Update the BSDROUTINGPARMS statement in PROFILE TCPIP for the VIPA
link, in addition to the physical links:
Chapter 18. Configuring the ROUTED Server
315
ROUTED Server
BSDROUTINGPARMS true
.
.
VIPA
DEFAULTSIZE
.
.
ENDBSDROUTINGPARMS
0
255.255.255.252 0
Note: the subnet mask is associated with the VIPA link. The subnet mask must
be assigned such that the VIPA interface is networked, subnetted, or
supernetted. See the subnet mask parameter in “BSDROUTINGPARMS
Statement” on page 479.
For more information on configuration options with VIPA, see the following topics:
v “Virtual IP Addressing (VIPA)” on page 457
v “Configuring VIPA” on page 459
v “Using VIPA to Backup or Restore a TCP/IP Stack” on page 460
v “Configuring RouteD to Split Traffic with VIPA”
Configuring RouteD to Split Traffic with VIPA
The purpose of splitting traffic is to reduce traffic load on network interfaces by
controlling the inbound and outbound traffic. The following techniques can be used
to produce traffic splitting effects with fault tolerance benefits:
v Using Interface Metric and VIPA To Split Inbound/Outbound Traffic
When there are multiple network interfaces to the same network configuration,
split inbound/outbound traffic can be achieved by setting the metric on the
primary interface one higher than on the secondary interface(s). From routing
updates, an adjacent router uses the gateway of a secondary interface to reach
the destination VIPA on the z/VM server, because the route to the gateway has a
smaller metric. The primary interface is used for outbound traffic, and a
secondary interface is used for inbound traffic. The traffic splitting will function as
long as the primary and at least one secondary interfaces are active. For
information on configuring an interface metric, see “BSDROUTINGPARMS
Statement” on page 479. An OBEYFILE command can be used for the
BSDROUTINGPARMS statement to update an interface metric for a link. For an
example of configuring a virtual device, see “Configuring RouteD with VIPA” on
page 315.
316
z/VM: TCP/IP Planning and Customization
ROUTED Server
HOME
VIPA
9.1.1.1
TR1
9.2.1.1
TR2
9.2.1.2
ETH1
9.3.1.1
ETH2
9.3.1.2
VM TCP/IP
VIPA
9.1.1.1
Device Drivers
Device2
Device1
TR1
TR2
9.2.1.1
ETH2
ETH1
.2
9.3.1.1
9.3.1.2
LAN2
LAN1
9.3.1.3
9.2.1.3
Router2
Router1
Dest
Gateway
9.1.1.1 9.3.1.2
9.1.1.0 9.3.1.2
10.1.1.2
Selected host route path
Selected network route path
10.1.1.1
Host
Dest
Gateway
9.1.1.1 9.2.1.1
9.1.1.0 9.2.1.1
Selected host route path
Selected network route path
Figure 7. Single VIPA Configuration. Sample configuration showing primary/multiple network
interfaces to the same LAN, VIPAs, and inbound/outbound traffic splitting.
Chapter 18. Configuring the ROUTED Server
317
ROUTED Server
HOME
VIPA1
VIPA2
VCTC
ETH1
ETH2
VM
TCP/IP
TCP/IP
9.4.1.1
HOME
VIPA1
VCTC
TR1
VIPA1
9.2.1.1
VIPA1
9.1.1.1
9.1.1.1
9.4.1.1
9.5.1.1
9.4.1.2
9.2.1.1
9.3.1.1
9.4.1.2
9.6.1.1
9.6.1.2
BSDROUTINGPARMS
2000 0
VIPA1
2000 0
VIPA2
2000 0
VTC
1500 0
ETH1
1500 0
ETH2
VIPA2
9.3.1.1
Device Drivers
BSDROUTINGPARMS
VIPA1 2000 0 255.255.0.0 0
VCTC 2000 0 255.255.0.0 9.4.1.2
2000 0 255.255.0.0 0
TR1
255.255.0.0
255.255.0.0
255.255.0.0
255.255.0.0
255.255.0.0
0
0
9.4.1.1
0
0
ETC.GATEWAYS
interface ETH1 9.6.1.1 forward.cond 9.2.0.0
interface ETH2 9.6.1.2 forward.cond 9.3.0.0
ETC.GATEWAYS
(none)
Device1
TR1
Domain Name Server
9.1.1.1
FTP
TELNET
9.2.1.1
APPLx
9.3.1.1
Device2
ETH1
ETH2
9.5.1.1
9.6.1.1
9.6.1.2
LAN2
LAN1
Dest Gateway Metric
9.1
9.5.1.1
1
9.2
9.6.1.1
1
9.3
9.6.1.2
1
.3
.3
Router
.4
Host
Uses 9.1.1.1 for FTP
Uses 9.2.1.1 for TELNET
Uses 9.3.1.1 for APPLx
To other networks...
Figure 8. Multiple VIPA Configuration. Sample configuration showing primary/multiple network interfaces to the same
LAN, VIPAs and inbound/outbound traffic splitting.
v Using Route Forwarding and VIPA to Split Session Traffic
With multiple VIPAs in one TCP/IP stack as shown in Figure 8, a VIPA can be
assigned to a particular interface so that the VIPA can be reserved for session
traffic (for example, FTP or TELNET). This is accomplished by using the route
forwarding option in RouteD. From routing updates, an adjacent router will have
multiple gateways to reach the VIPAs on the z/VM server. The adjacent router
will use one gateway to reach one VIPA reserved for one type of session traffic
and the other gateway to reach another VIPA reserved for another type of
session traffic on the z/VM server. For fault tolerance, it is recommended that the
conditional option of route forwarding be used. For information on route
forwarding, see the options statement in “Step 5: Create the ETC GATEWAYS
File (Optional)” on page 302. For an example of configuring a virtual device, see
“Configuring RouteD with VIPA” on page 315.
318
z/VM: TCP/IP Planning and Customization
ROUTED Server
Configuring a Backup TCP/IP Stack with VIPA
To configure an backup z/VM TCP/IP stack with the primary z/VM TCP/IP stack’s
VIPA address, do the following after a primary z/VM TCP/IP stack is down:
v If RouteD is running on the backup z/VM TCP/IP stack, issue an OBEYFILE
command to:
1. Add a new VIPA device and link.
2. Add new HOME and BSDROUTINGPARMS statements for the new VIPA link.
The HOME statement will have the primary z/VM TCP/IP stack’s VIPA
address. Ensure that the HOME and BSDROUTINGPARMS statements are
included in the same OBEYFILE command.
v If RouteD is not running on the backup z/VM TCP/IP stack, start it and add the
new VIPA device and link, HOME and BSDROUTINGPARMS statements using
the OBEYFILE command.
Restoring a Primary TCP/IP Stack with VIPA
To restore a VIPA address to the primary z/VM TCP/IP stack after it is no longer
needed on the backup, do the following:
v If RouteD is running on the backup z/VM TCP/IP stack, issue an OBEYFILE
command to add a new HOME statement with the primary z/VM TCP/IP stack’s
VIPA address removed. Otherwise, issue an OBEYFILE command to add a new
HOME statement with the primary VIPA address removed, and start RouteD. It is
not necessary to add a new BSDROUTINGPARMS statement.
v Start RouteD on the primary z/VM TCP/IP stack after ensuring that the VIPA
device and link, HOME, and BSDROUTINGPARMS statements are defined for
the VIPA address that was temporarily reassigned to the backup z/VM TCP/IP
stack.
Using the SMSG Interface to RouteD
The VM Special Message Facility (SMSG) command provides an interface for
authorized users to modify RouteD operational characteristics, display routing
information, and obtain diagnostic information.
v Authorized users are defined in the OBEY list. See the OBEY statement in
Chapter 24, “Configuring the TCP/IP Server” on page 453 for more information on
defining authorized users.
v For more information on obtaining diagnostic information, see the section
“Activating RouteD Trace and Debug” section in the TCP/IP Diagnosis Guide.
SMSG command responses are returned to the originator of the command.
RouteD SMSG Command
Use the SMSG command to enable or disable RouteD command parameters that
may or may not have been specified at server initialization or on a previous SMSG
command.
Chapter 18. Configuring the ROUTED Server
319
ROUTED Server
SMSG server_id
HELP
PARMS parms
CONFIG
RECONFIG
RGATEWAYS
DGATEWAYS
SHUTDOWN
Operands
server_id
Specifies the user ID of the virtual machine running the VM RouteD server.
HELP
Provides a list of valid SMSG commands accepted by RouteD.
PARMS
Followed by one or more parameters separated by a space. The [q] form of an
operand deactivates the function associated with that operand.
-f
Flush all indirect routes known by RouteD from IP routing tables.
-fh
Flush all indirect host routes known by RouteD from IP routing tables.
-g[q]
Enables the default router. When this option is specified, RouteD will add a
default route to its routing information, and broadcast it over all local
interfaces. If the adjacent routers add the default route to their routing
tables, RouteD will receive all unknown packets from them and funnel them
to a destination router, provided that a default route is defined. If you use
this option, you should define a default route to a destination router in the
gateways file. See “Configuring a Default Route” on page 314.
Note: Do not use this option if default routes are to be learned dynamically
from adjacent routers.
-h[q]
Include host routes, in addition to network routes, for the broadcasts.
Adjacent routers should support Host Route Broadcasting to prevent
NETWORK UNREACHABLE problems from occurring.
-hv[q]
Include only virtual host routes, in addition to network routes, for the
broadcasts. Adjacent routers should support Host Route Broadcasting, or
network or subnetwork portions of VIPA addresses must be unique for each
TCP/IP image.
-q Suppresses broadcasting of routing information.
-s[q]
Forces RouteD to supply routing information, regardless of whether it is
acting as an internetwork router. This is the default if multiple network
interfaces are present or if a point-to-point link is used.
320
z/VM: TCP/IP Planning and Customization
ROUTED Server
-sd[q]
Supplies default route only. When this option is specified, the -g parameter
is set internally. This option is provided as a RIP output filter.
-sdv[q]
-svd[q]
Supplies (broadcasts) virtual routes and default routes only. See parameter
descriptions for -sv and -sd. This option is provided as a RIP output filter.
-shv[q]
-svh[q]
Supplies (broadcasts) virtual (network and host) routes. This option is
provided as a RIP output filter.
-sl[q]
Supplies local (directly-connected) routes only. This option is provided as a
RIP output filter.
-st[q]
Supplies triggered updates only. This is similar to the -q parameter, except
that RouteD will supply network unreachable routing information during
interface outages so that adjacent routers can recover by switching to
different routes, rather than relying on three-minute timeouts. This option is
provided as a RIP output filter.
-sv[q]
Supplies virtual routes only. Recommended usage is when multiple network
adapters in a TCPIP stack are in the same network; otherwise, network
connectivity problems will occur. This option is provided as a RIP output
filter.
CONFIG
Reread the RouteD configuration file.
RECONFIG
Performs dynamic reconfiguration of interfaces and local routes when the
interface parameters have changed after an OBEYFILE command has been
issued for a file containing modified HOME and BSDROUTINGPARMS
statements. Issue this command for RouteD after an OBEYFILE command has
been issued to reflect dynamic changes made.
RGATEWAYS
Reread the ETC GATEWAYS file.
DGATEWAYS
Reread the ETC GATEWAYS file and delete all routes listed.
SHUTDOWN
Stops the RouteD server that is running in the target virtual machine.
Examples
1. The following SMSG command passes parameters to a RouteD server running
in the ROUTED2 virtual machine.
smsg routed2 parms -h -s -sl
Ready;
09:02:26 * MSG FROM ROUTED2 : PARMS -H -S -SL
2. Using the SHUTDOWN SMSG command from another virtual machine to stop
the RouteD server running in the ROUTED2 virtual machine.
smsg routed2 shutdown
Ready;
14:47:12 * MSG FROM ROUTED2 : SHUTDOWN
Chapter 18. Configuring the ROUTED Server
321
ROUTED Server
3. Using the SHUTDOWN SMSG command to stop the RouteD server from the
actual server (ROUTED2) virtual machine.
CP SMSG * SHUTDOWN
DTCRTD6020I SMSG Command: RouteD Server termination initiated
15:39:04 * MSG FROM ROUTED2 : SHUTDOWN
DTCRUN1014I Server ended normally at 15:39:04 on 1 Apr 1999 (Thursday)
322
z/VM: TCP/IP Planning and Customization
Chapter 19. Configuring the RSCS Print Server
Instead of LPSERVE, the RSCS server may be chosen to provide an enhanced
level of TCP/IP print support, including LPR and LPD.
Using RSCS provides end users with the following:
v Deferred (asynchronous) printing. The user’s CMS session is not left idle waiting
to print a file.
v TN3270E printer sessions, providing workstation print capabilities when LPD is
not installed or available on the workstation.
v Enhanced error recovery. RSCS will periodically attempt to retransmit a print file
in the event of a TCP/IP network or remote printer failure.
v Enhanced QUERY capabilities. RSCS commands are available to the end user to
determine the status of their print request, complementing the existing LPQ and
LPRM commands.
v The ability for workstation users to use LPR to print on any printer owned by the
VM system. When an RSCS Version 3 Release 2 license is acquired, this
capability is extended to any printer or user anywhere in the RSCS network.
In addition to the advantages provided to end users, it enables the integration of
TCP/IP printing into an existing RSCS printer network and its associated
management.
Configuring a TN3270E Printer
The TN3270E protocol supported by TCP/IP provides for the creation of 3270
printer sessions in addition to traditional display sessions. To make this capability
available, the following steps must be performed:
1. An arbitrary name, called the ″LU name″ must be defined in the TN3270E
control statement in the PROFILE TCPIP file. This statement assigns a virtual
line address to the printer session.
2. The TN3270E Printer Management exit must be enabled by the TN3270EEXIT
parameter of the INTERNALCLIENTPARMS statement in the PROFILE TCPIP
file. See “INTERNALCLIENTPARMS Statement” on page 527.
3. An RSCS TN3270E link must be defined that has a line address that matches
the line address defined in step 1. While not required, you may find
administration and problem determination easier if the LU name is the same as
the associated RSCS link name. The sample TN3270E Printer Management exit
assumes the LU name and RSCS link names match.
4. The user must have the ″LU name″ configured in their TN3270E-capable
emulator.
Configuring an RSCS LPR Link
To configure an RSCS LPR link, you will need to add LINKDEFINE and PARM
configuration file statements in the RSCSTCP CONFIG file. Different options must
be used depending on whether the printer is postscript or non-postscript.
RSCSTCP CONFIG Configuration File
The RSCSTCP CONFIG configuration file contains statements you can use to
define your RSCS network. This file is read during initialization of the RSCS virtual
machine. If this file is not found, RSCS initialization will fail. This file is the main
© Copyright IBM Corp. 1987, 2002
323
RSCS Print Server
configuration file for the RSCS server and will be stored on the TCP/IP
Customization minidisk, TCPMAINT 198. It allows you to specify:
v The name of your local RSCS node if you wish it to be different from the system
network ID
v LPR-type links for use with non-postscript printers
v LPR-type links for use with postscript printers
v LPD-type links for use as a local daemon
v TN3270E-type links for use with telnet attached 3287–1 printers
v UFT-type link for use as a local asynchronous UFT client
Two LPR links have been defined in the RSCSTCP CONFIG sample RSCS
configuration file on TCPMAINT’s 198 minidisk with the following linkid:
v LPR, which is to be used with non-postscript printers
v LPRP, which is to be used with postscript printers
Configuring a Non-Postscript Printer
This section describes the LINKDEFINE and PARM statements necessary in the
RSCSTCP CONFIG file for defining an LPR link for use with non-postscript printers.
The LINKDEFINE statement defines the default attributes of a single RSCS link.
These link attributes apply to the link when it is started.
LINKDEFine LPR AST FOrm * TYPE LPR
Include as many statements as needed; they are optional. LINKDEFINE statements
can be placed anywhere in the configuration file after the LOCAL statement (if this
statement exists).
The LPR keyword is in the linkid position. The linkid is a 1- to 8-character name of
an LPR link that connects your local RSCS server to a remote line printer daemon
(LPD) in a TCP/IP network. The LINK DEFINE statement must come before the
PARM statement.
PARM LPR EXIT=LPRXONE EParm='value' ITO=0
324
PORT=515
HOSTDafn=name
z/VM: TCP/IP Planning and Customization
PORT=portid
USer=Yes
TCPID=TCPIP
TCPID=tcpip
HOSTName=name
RSCS Print Server
Parameter
Description
EParm='value'
value is a character string up to 239 bytes in length
and enclosed in single quotation marks (' '). For
additional information see “Available EPARMs for
Non-Postscript Printers”.
PORT=portid
Specifies the port number to use when connecting
to a remote host. The default is well known port
515.
TCPID=tcpip
Specifies the name of the TCP/IP server; the
default name is TCPIP.
HOSTDafn=name
Specifies a 1- to 8-character name which should be
used as the host name portion of the control and
data file names. A control or data file name is used
within the ’Receive control file’ and ’Receive data
file’ subcommands of the daemon ’Receive job’
command. The name should start with ″cfa″ (control
file) or ″dfa″ (data file), followed by a three-digit job
number, followed by the host name that has
constructed the control/data file, as described in
RFC 1179. RSCS defaults to using the link name
for the host name portion of the file name if this
parameter is not specified. Some daemons will not
accept any name, other than the host name. This
parameter allows you to specify the host name.
HOSTName=name
Specifies a 1- to 200-character fully qualified name
of the remote host.
Available EPARMs for Non-Postscript Printers
The RSCS LPRXONE exit routine performs function for a non-postscript printer. It
also performs simple translation of data to ASCII. The following EPARM values can
be used to configure the LPRXONE exit behavior. Note that because the EPARM
parameter is limited to 239 bytes of data, these options may be useful for only small
amounts of data.
Parameter
Description
FF=
Determines how printer form-feeds are performed.
TOP
Form-feed is sent in the front of the file
Bottom
Form-feed is sent after the file; this is the default.
None
FIlter=f
A form-feed is not sent.
Specifies the printer filter used in the control file sent to the daemon
if a filter is not specified by the user when the LPR command is
issued; the default is f. One EBCDIC character is passed. If it is
uppercase alphabetic, it will be translated to lowercase. No other
validation is performed. This maintains consistency with RFC1179.
Prefix=hex_string
Optionally specifies a hexadecimal string to be sent in front of each
file if a prefix string is not passed by the user when the LPR
command is issued; this string is not translated. This string can be
Chapter 19. Configuring the RSCS Print Server
325
RSCS Print Server
used to pass printer specific setup values. Up to 200 bytes of data
can be specified. By default, a prefix string is not sent with each
file.
Sep=
Indicates if a separator page will be printed for each file.
Yes
Prints a separator page; this is the default. The origin user
ID and node ID and distribution information are printed in
large characters; other file information is printed in small
characters in the Times-Bold font.
No
Does not print a separator page
Host
Sends the L control file record to request that the remote
host produce the separator page.
SUFfix= hex_string
Optionally specifies a hexadecimal string to be sent after each file if
a suffix string is not passed by the user when the LPR command is
issued; this string is not translated. This string can be used to reset
the printer upon print completion. Up to 200 bytes of data can be
specified. By default, a suffix string is not sent with each file.
Config=LPR
Causes the LPRXONE exit to read the RSCSLPR CONFIG sample
configuration file located on TCPMAINT’s 198 minidisk. The
configuration file can contain translation tables to override the
tables used within the exit.
An * in column one denotes a comment line. Any line that does not
have an * in column one will be interpreted as a configuration entry.
All entries must be capitalized.
The following configuration records are supported:
ASCII=
Provide a table for translating ASCII control
characters, overriding the default used by the exit.
LPRXONE uses this translation table when files are
already in ASCII and the user ID field of the TAG is
set to ’ASCIIC’. Up to 512 hexadecimal (0-9, A-F)
characters may be specified on multiple ASCII=
records to replace the 256-byte translation table.
DOMAINAME=
Specifies a domain name, up to 255 characters, to
be appended after the host name of the ’H’ control
file record. A period (.) will be inserted between the
host name and domain name. This record can be
used to add a domain name after the host name,
which by default is the node name where the file
originated or as specified in the HOSTNAME=
record.
HOSTNAME= Used to specify a host name, up to 255 characters,
for the ’H’ control file record, overriding the default,
which is the node name where the file originated.
TOASCII=
326
z/VM: TCP/IP Planning and Customization
Provide a table for EBCDIC to ASCII translation,
overriding the default used by the exit. Up to 512
hexadecimal (0-9, A-F) characters may be specified
on multiple TOASCII= records to replace the
256-byte translation table.
RSCS Print Server
TOASCIIC=
Provide a table for EBCDIC to ASCII translation of
the LPR control file, overriding the default used by
the exit. Up to 512 hexadecimal (0-9, A-F)
characters may be specified on multiple
TOASCIIC= records to replace the 256-byte
translation table.
USERNAME= Specifies a user name, up to 32 characters, for the
’P’ control file record, overriding the default name
used by the exit, which is the user name of the file
originator. This record can be used to cause all
error messages to be sent to a central location.
A sample EPARM follows:
EPARM=’C=LPR S=N FF=N’
Configuring a Postscript Printer
This section describes the LINKDEFINE and PARM statements necessary in the
RSCSTCP CONFIG file for defining an LPR link for use with postscript printers.
The LINKDEFINE statement defines the default attributes of a single RSCS link.
These link attributes apply to the link when it is started.
LINKDEFine LPRP AST FOrm * TYPE LPR
Include as many statements as needed; they are optional. LINKDEFINE statements
can be placed anywhere in the configuration file after the LOCAL statement (if this
statement exists).
The LPRP keyword is in the linkid position. The linkid is a 1- to 8-character name of
an LPR link that connects your local RSCS server to a remote line printer daemon
(LPD) in a TCP/IP network. The LINK DEFINE statement must come before the
PARM statement.
PARM LPRP EXIT=LPRXPSE EParm='value' ITO=0
PORT=515
HOSTDafn=name
Parameter
PORT=portid
USer=Yes
TCPID=TCPIP
TCPID=tcpip
HOSTName=name
Description
EParm='value' value is a character string up to 239 bytes in length and enclosed in
single quotation marks (' '). For additional information see
“Available EPARMs for Postscript Printers” on page 328.
PORT=portid
Specifies the port number to use when connecting to a remote host.
The default is well known port 515
Chapter 19. Configuring the RSCS Print Server
327
RSCS Print Server
TCPID=tcpip
Specifies the name of the TCP/IP server; the default name is
TCPIP.
HOSTDafn=name
Specifies a 1- to 8-character name that should be used as the host
name portion of the control and data file names. A control or data
file name is used within the ’Receive control file’ and ’Receive data
file’ subcommands of the daemon ’Receive job’ command. The
name should start with ″cfa″ (control file) or ″dfa″ (data file),
followed by a three-digit job number, followed by the host name that
has constructed the control/data file, as described in RFC 1179.
RSCS defaults to using the link name for the host name portion of
the file name if this parameter is not specified. Some daemons will
not accept any name, other than the host name. This parameter
allows you to specify the host name.
HOSTName=name
Specifies a 1-to 200-character fully qualified name of the remote
host.
Available EPARMs for Postscript Printers
The RSCS LPRXPSE exit routine performs functions for a postscript printer. This
exit routine assumes that the remote printer is PostScript only, or that it will switch
into PostScript mode when it receives a “%!PS” string following an EOT character. It
also performs simple translation of data to ASCII. The following EPARM values can
be used to configure the LPRXPSE exit behavior. Note that because the EPARM
parameter is limited to 239 bytes of data, these options may be useful for only small
amounts of data.
Ehandler=
Determines if a PostScript error handler will be downloaded to the
printer the first time a file is sent to the printer after the link is
started. This error handler enables any errors to be printed, so the
information will not be lost.
Yes
The error handler is downloaded; this is the default.
No
The error handler is not downloaded.
EOT=
FIlter=f
Yes
EOT characters will be inserted after the separator page,
data file, and trailer page; this is the default.
No
EOT characters will not be inserted.
Specifies the printer filter used in the control file sent to the daemon
if a filter is not specified by the user when the LPR command is
issued; the default is f. One EBCDIC character is passed. If it is
uppercase alphabetic, it will be translated to lowercase. No other
validation is performed. This maintains consistency with RFC1179.
FOrm=OrFnFsLs
Specifies the default form to use when printing plain text files and
when a form has not been specified on the LPR command.
The following can be used for OrFnFsLs and shows the defaults.
Or
File orientation:
PO
Portrait (default)
LA
Landscape
Fn
Font name code
CB
Courier-Bold
CI
Courier-Oblique
328
z/VM: TCP/IP Planning and Customization
RSCS Print Server
Fs
Ls
CP
Courier (default)
CX
Courier-BoldOblique
HB
Helvetica-Bold
HP
Helvetica
HI
Helvetica-Oblique
HX
Helvetica-BoldOblique
SP
Symbol
TB
Times-Bold
TI
Times-Italic
TP
Times-Roman
TX
Times-BoldItalic
Font size, 04 thru 99; the default is 11 for portrait and 10 for
landscape orientation
Additional leading size, 0.0 - 9.9, added to font size to give
leading; the default is 09 for portrait and 12 for landscape
Prefix= hex_string
Optionally specifies a hexadecimal string to be sent in front of each
file if a prefix string is not passed by the user when the LPR
command is issued; this string is not translated. This string can be
used to pass printer specific setup values. Up to 200 bytes of data
can be specified. By default, a prefix string is not sent with each
file.
Sep=
Indicates if a separator page will be printed for each file.
Yes
Prints a separator page; this is the default. The origin user ID
and node ID and distribution information are printed in large
characters; other file information is printed in small characters in
the Times-Bold font.
No
Does not print a separator page
Host
Sends the L control file record to request that the remote host
produce the separator page.
SUFfix= hex_string
Optionally specifies a hexadecimal string to be sent after each file if
a suffix string is not passed by the user when the LPR command is
issued; this string is not translated. This string can be used to reset
the printer upon print completion. Up to 200 bytes of data can be
specified. By default, a suffix string is not sent with each file.
Trailer=
Indicates if a trailer page will be printed
Yes
Prints a trailer page after the file. It is identical to the header
page with the addition of a count of the bytes in the file.
No
Trailer page is not printed; this is the default.
Config=LPRP
Causes the LPRXPSE exit to read the RSCSLPRP CONFIG
sample configuration file located on TCPMAINT’s 198 minidisk.
This configuration file is used to supply the following:
v To override the default translate table.
Chapter 19. Configuring the RSCS Print Server
329
RSCS Print Server
v To override the postscript program sent to the printer when
printing plain text files.
v Additional font names used when printing plain text files.
An * in column one denotes a comment line. Any line that does not
have an * in column one will be interpreted as a configuration entry.
All entries must be capitalized.
The following configuration records are supported:
DOMAINAME=
Specifies a domain name, up to 255 characters, to
be appended after the host name of the ’H’ control
file record. A period (.) will be inserted between the
host name and domain name. This record can be
used to add a domain name after the host name,
which by default is the node name where the file
originated or as specified in the HOSTNAME=
record.
HOSTNAME= Used to specify a host name, up to 255 characters,
for the ’H’ control file record, overriding the default,
which is the node name where the file originated.
FONT=
Provides a 2-character font abbreviation followed by
a 32-character font name. There should be no
blanks between the abbreviation and full font name.
Multiple records can be provided for supplying as
many additional fonts as required. The abbreviation
should be unique on each FONT= record. The fonts
must be installed on the printer. The current
available font names are:
2-Character
Abbreviation
CB
CI
CP
CX
HB
HP
HI
HX
SP
TB
TI
TP
TX
PSCRIPT=
32-Character
Font Name
Courier-Bold
Courier-Oblique
Courier (exit default)
Courier-BoldOblique
Helvetica-Bold
Helvetica
Helvetica-Oblique
Helvetica-BoldOblique
Symbol
Times-Bold
Times-Italic
Times-Roman
Times-BoldItalic
Provide a replacement postscript program to be
used when printing a plain text file. The postscript
program must be enclosed within quotes. Anything
after the ending quote will be ignored allowing for
comments.
For example:
PSCRIPT=’this is line one’ comment for line one
PSCRIPT=’this is line two’
330
z/VM: TCP/IP Planning and Customization
RSCS Print Server
Multiple PSCRIPT= records can be provided in
order to supply the entire program. LPRXPSE will
add a carriage return (X’0A’) after each record, and
will translate the record from EBCDIC to ASCII.
Note: When replacing the postscript program, the
ability to tailor the file orientation, font name,
font size, and additional leading size through
a FORM is lost. The supplied postscript
program must define all of these attributes.
TOASCII=
Provide a table for EBCDIC to ASCII translation,
overriding the default used by the exit. Up to 512
hexadecimal (0-9, A-F) characters may be specified
on multiple TOASCII= records to replace the
256-byte translation table.
TOASCIIC=
Provide a table for EBCDIC to ASCII translation of
the LPR control file, overriding the default used by
the exit. Up to 512 hexadecimal (0-9, A-F)
characters may be specified on multiple
TOASCIIC= records to replace the 256-byte
translation table.
USERNAME= Specifies a user name, up to 32 characters, for the
’P’ control file record, overriding the default name
used by the exit, which is the user name of the file
originator. This record can be used to cause all
error messages to be sent to a central location.
The following is a sample EPARM:
EPARM=’C=LPRP S=N T=N’
Form Parameter of LPR Command When Printing to PostScript
When printing to postscript printers, you can also specify the following values on the
FORM=OrFnFsLs operand of the LPR command.
Or
File orientation:
PO
Portrait
LA
Landscape
Fn
Font name code
CB
Courier-Bold
CI
Courier-Oblique
CP
Courier
CX
Courier-BoldOblique
HB
Helvetica-Bold
HP
Helvetica
HI
Helvetica-Oblique
HX
Helvetica-BoldOblique
SP
Symbol
TB
Times-Bold
TI
Times-Italic
TP
Times-Roman
TX
Times-BoldItalic
Fs
Font size, 04 thru 99.
Ls
Additional leading size, 0.0 - 9.9, added to font size to give leading.
Chapter 19. Configuring the RSCS Print Server
331
RSCS Print Server
Configuring an RSCS LPD Link
The RSCSLPD CONFIG configuration file contains statements you can use to
customize an RSCS LPD-type link. This file is read during link initialization. If this
file is not found, the link initialization will fail. This file will be stored on the TCP/IP
Customization minidisk, TCPMAINT 198. It allows you to specify:
v A replacement ASCII to EBCDIC translation table
v A replacement EBCDIC to ASCII translation table
v Definitions to be used while receiving a file for a particular printer queue name.
The definitions which may be defined are
– a queue name
– logical record length
– number of lines per page
– spool file class
– spool file form
– job name
– PSF destination
– whether or not to paginate
– whether or not to translate
– destination user ID
– destination node ID
– TCPXLBIN translation table to use for ASCII to EBCDIC translations
To configure an RSCS LPD link, you will need to add LINKDEFINE and PARM
configuration file statements in the RSCSTCP CONFIG file. One LPD link has been
defined in the RSCSTCP CONFIG sample RSCS configuration file on TCPMAINT’s
198 minidisk.
This section describes the LINKDEFINE and PARM statements necessary in the
RSCSTCP CONFIG file for defining an LPD link.
LINKDEFine LPD TYPE LPD
The LINKDEFINE statement defines the default attributes of a single RSCS link.
These link attributes apply to the link when it is started.
Include as many statements as needed; they are optional. LINKDEFINE statements
can be placed anywhere in the configuration file after the LOCAL statement (if this
statement exists).
The LPD keyword is in the linkid position. The linkid is a 1- to 8-character name of
an LPD link that will act as a gateway accepting print data streams from the TCP/IP
environment.
332
z/VM: TCP/IP Planning and Customization
RSCS Print Server
TCPID=TCPIP
PARM LPD EXIT=LPDXMANY
EParm='value'
PORT=515
Timeout=60
PORT=portid
Timeout=nnn
Parameter
TCPID=tcpip
Description
EParm='value' value is a character string up to 239 bytes in length and enclosed in
single quotation marks (' '). For additional information see
“Available EPARMs for LPD Links”.
TCPID=tcpip
Specifies the name of the TCPIP server; The default name is
TCPIP.
PORT=portid
Specifies the port number to use when listening on the local host.
The default is well known port 515.
Timeout=nnn
Specifies the amount of time in seconds RSCS will wait for data
when receiving from a TCP/IP line print router prior to breaking the
socket connection; the default is 60. After the LPD link driver breaks
this connection, it will remain operational waiting for another line
print router to connect.
Available EPARMs for LPD Links
The RSCS LPDXMANY exit routine performs functions to support a single LPD
printer queue. Multiple LPD link drivers can be defined using this exit. It also
performs simple translation of data to EBCDIC.
The spool file created will be of type VAFP. A record width up to 1280 characters
will be supported. Any records received with a width greater than 1280 characters
will be split into multiple records. The CMS receive command will create a file with
a record length of 204. Any data in a record past 204 will be truncated. CP will also
truncate the data with a record length greater than 204 if the spool file is destined
to a CP system printer.
Printer job commands received from the line print router contain a queue name of
the form [email protected] or userid%nodeid. The following examples show how the
LPDXMANY routine parses this queue name, and how the provided information
affects a created spool file.
[email protected]
Will set the node ID to MAINE and the user ID to
KERRY. The file will be sent to user KERRY at
node MAINE.
KERRY%MAINE
Will set the node ID to MAINE and the user ID to
KERRY. The file will be sent to user KERRY at
node MAINE.
[email protected]
Will set the node ID to the local node name and the
user ID to KERRY. The file will be spooled to user
KERRY on the local system.
KERRY%
Will set the node ID to the local node name and the
Chapter 19. Configuring the RSCS Print Server
333
RSCS Print Server
user ID to KERRY. The file will be spooled to user
KERRY on the local system.
@LASER1
Will set the node ID to LASER1 and the user ID to
SYSTEM causing the file to be sent to the network
node LASER1.
%LASER2
Will set the node ID to LASER2 and the user ID to
SYSTEM causing the file to be sent to the network
node LASER2.
LASER3
Will set the node ID to LASER3 and the user ID to
SYSTEM causing the file to be sent to the network
node LASER3.
Note: The LPDXMANY routine will limit the length of the user ID and node ID fields
to 8 characters. Any extra data in those operand fields will be discarded.
The following EPARM values can be used to configure the LPDXMANY exit
behavior. Note that because the EPARM parameter is limited to 239 bytes of data,
these options may be useful for only small amounts of data.
Parameter
Description
Config=LPD
Causes the LPDXMANY exit to read the RSCSLPD CONFIG
sample configuration file located on TCPMAINT’s 198 minidisk. This
configuration file is used to supply the following:
v Translation table to override the one used by the exit.
v Supply overrides for processing when a file is received from a
remote LPR command based on the printer queue name.
An * in column one denotes a comment line. Any line that does not
have an * in column one will be interpreted as a configuration entry.
All entries must be capitalized.
The following configuration records are supported:
TOASCII=
Provide a table for EBCDIC to ASCII translation, overriding the
default used by the exit. Up to 512 hexadecimal (0-9, A-F)
characters may be specified on multiple TOASCII= records to
replace the 256-byte translation table.
TOEBCDIC=
Provide a table for ASCII to EBCDIC translation, overriding the
default used by the exit. Up to 512 hexadecimal (0-9, A-F)
characters may be specified on multiple TOEBCDIC= records to
replace the 256-byte translation table.
queuename
Provide the ability to override defaults used by LPDXMANY on a
printer queue name basis when receiving a file from a remote host.
Multiple, unique, printer queue name records can be specified.
Format of Printer Queue Name Records
The layout of the printer queue name records is as follows:
v Each queue name option is separated by one or more blanks.
v The parameters are not column dependent.
v One record per line, continuation is not supported.
v Each parameter IS position dependent.
334
z/VM: TCP/IP Planning and Customization
RSCS Print Server
v An * can be used in a position (other than for the printer queue name) to tell
LPDXMANY to use the existing default.
v The printer queue name will be parsed into user ID and node ID as follows:
<[email protected]>nodeid
<userid%>nodeid
nodeid
user ID will be set to SYSTEM.
@nodeid
user ID will be set to SYSTEM.
%nodeid
user ID will be set to SYSTEM.
[email protected]
node ID will be set to local node name.
userid%
node ID will be set to local node name.
NONEOFTHEABOVE
node ID and user ID MUST be set within record.
The user ID and node ID parsed from the printer queue name can be overridden
within the record. If both are overridden, the printer queue name is not parsed. If
neither are overridden, the printer queue name is parsed into user ID and node
ID which must be valid (either of which can still be overridden within).
queuename ppos lpage class forms jobn dest
pagination translation userid nodeid tcpxlbin
DEFAULT ppos lpage class forms jobn dest
pagination translation userid nodeid tcpxlbin
Parameter
Description
queuename
is a printer queue name up to 32 characters. A queuename of
DEFAULT can be used to define parameters for any printer queue
not defined by a configuration file record. When a printer queue
name arrives, LPDXMANY first looks for a configuration record of
that name. If this is not found, LPDXMANY will look for a
configuration record using DEFAULT; if this is not found, it will use
existing LPDXMANY defaults.
ppos
is the logical record length 1-1280; the default is 255.
lpage
is the number of lines per page 1-99; the default is 66.
class
is the 1-character spool file class; the default is blank.
forms
is the 1- to 8-character spool file form; the default is blank.
jobn
is the 1- to 8-character job name; the default is SYSTEM.
dest
is the 1- to 8-character PSF destination; the default is blank. When
using a PSF destination, LPDXMANY will set the user ID field of the
tag to SYSTEM.
pagination
is either PAGE or NOPAGE; the default is NOPAGE. This
parameter determines how pagination is performed:
PAGE will cause LPDXMANY to always paginate, regardless of the
print filter.
NOPAGE will cause LPDXMANY to paginate only as defined by the
control file filters 'f' or 'p'. To be effective, the control file must be
received prior to the data file to be printed.
translation
is either ASISCC, NOTRAN or TRAN; the default is TRAN.
Translation determines if the data file is translated prior to spooling.
userid
is the 1-to 8-character user ID that will receive the spooled file.
nodeid
is the one- to eight-character destination
Chapter 19. Configuring the RSCS Print Server
335
RSCS Print Server
tcpxlbin
is the file name of a TCP/IP TCPXLBIN translate table to be used
for this printer queue name.
QUEUENAME examples:
[email protected] 1280 50 * STDN * * * ASISCC ASCII
DEFAULT 255 66 * * SYSTEM * NOPAGE TRAN *
The first example would allow a file to be received without translation, and spooled
to an LPR link. ASCII tells the LPRXONE exits that the file is already in ASCII and
to send it unaltered to the remote daemon.
The second example would allow a file to be spooled to the system printer.
The following is a sample EPARM:
EPARM=’C=LPD’
Configuring an RSCS TN3270E Printer Link
To configure an RSCS TN3270E printer link, you will need to add LINKDEFINE and
PARM configuration file statements in the RSCSTCP CONFIG file. You must define
one TN3270E printer link for each printer LUNAME defined within the TCPIP
configuration file.
This section describes the LINKDEFINE and PARM statements necessary in the
RSCSTCP CONFIG file for defining an TN3270E printer link. The linkid may match
the LUNAME; however, the line address must match the virtual address defined in
the TCPIP configuration file.
LINKDEFine linkid AST LINE vaddr TYPE TN3270E
The LINKDEFINE statement defines the default attributes of a single RSCS link.
These link attributes apply to the link when it is started.
Include as many statements as needed; they are optional. LINKDEFINE statements
can be placed anywhere in the configuration file after the LOCAL statement (if this
statement exists).
You can specify multiple LINKDEFINE statements for the same link. If you specify
more than one LINKDEFINE statement with the same linkid, RSCS uses the
attribute from the last LINKDEFINE statement.
336
z/VM: TCP/IP Planning and Customization
RSCS Print Server
PARM linkid
COMP=No
Buff=nnnn
COMP=Yes
EPC=No
EPC=Yes
FEATure=
Ppos=132
SEP=No
Ppos=nnn
SEP=
VFC=No
(3)
VFC=Yes
(1)
Buff=1920
AT
DA
DBCS
DBCSAT
VM
Yes
CR=Yes
(2)
Lpage=66
OVP=Yes
Lpage=nn
OVP=No
TRans=
CR=No
APL
APL2
ASISCC
DBCS
DBCSAPL
DBCSAPL2
DBCSTEXT
TEXT
XNL=No
PRTWtm=10
PRTRet=1
MSG=Yes
XNL=Yes
PRTWtm=nnn
PRTRet=nnn
MSG=No
Notes:
1
Specify NO for locally attached printers.
2
CR has no meaning unless VFC=YES is also specified.
3
Generally it is recommended to specify VFC=YES.
linkid
Is the 1- to 8-character name of the link that connects your local RSCS system
to a TN3270E attached printer. Before you can specify a PARM statement for a
link, you must specify a LINKDEFINE (or LINK) statement with the same link ID.
Buff=1920
Buff=nnnn
Is the buffer size of the 3287–1 printer. The following buffer sizes are valid: 480,
960, 1920, 2560, 3440, and 3564. The correct buffer size has to be specified to
match the buffer size on the printer being used. If this keyword is omitted, the
buffer size defaults to 1920.
COMP=Yes
COMP=No
Specifies that the link will perform blank compression. If omitted, the default is
to not compress.
CR=Yes
CR=No
Specifies if a carriage return (CR) should be sent after a forms feed (FF) when
VFC=YES is specified. CR has no meaning unless VFC=YES is also specified.
If omitted, the default is NO.
EPC=Yes
Chapter 19. Configuring the RSCS Print Server
337
RSCS Print Server
EPC=No
Specifies if Early Print Complete should be used by the line driver. If omitted,
the default is NO.
FEATure=
Specifies that the printer has the following features:
AT
APL/Text feature
DA
Data Analysis-APL feature
DBCS
Double-Byte Character Set feature
DBCSAT
AT and DBCS features
Lpage=66
Lpage=nn
Specifies the number of lines per page on the type of form inserted in the 3270
printer. The value may be from 0 to 99. A value of 0 specifies that no page
ejects will be done when a page eject is read in the file. If this keyword is
omitted, the length of a page defaults to 66.
Note: This value is used by RSCS only to determine the current vertical
position on a page while printing a file. Any actual page ejects are
determined by Skip-to-Channel-1 CCWs within the file. If there are no
Skip-to-Channel-1 CCWs in the file, no page ejects are done, except
between files. The actual number of lines contained in the file between
consecutive Skip-to-Channel-1 CCWs must be equal to or less than this
value.
OVP=Yes
OVP=No
Specifies if the link will allow overprinting to occur (such as underscored words
or overstruck characters for highlighting). If omitted, the default is to allow
overprinting. Specify NO for those printers that do not support the 3270 CR
(Carriage Return) order.
Ppos=132
Ppos=nnn
Specifies the maximum number of print positions available on the 3270 printer.
This value may be between 1 and 220, depending on the actual printer. Consult
the Component Description manual for the specific printer to determine this
value. If omitted, the number of print positions defaults to 132.
PPOS is a hardware maximum determined by the number of characters the
printer can print on each line, independent of the size of the form used in the
printer. Each printer has its own PPOS value. If the PPOS value you specify
does not match the printer’s PPOS value, some types of printed output
(including separator pages) will not print correctly.
SEP=
Specifies if a separator page will be inserted before each print file and sent
across the link.
Yes
For RSCS-style separator pages.
No
For no separator pages. This is the default.
VM
For VM-style separator pages.
338
z/VM: TCP/IP Planning and Customization
RSCS Print Server
TRans=
Specifies the default translation mode for files being transmitted to a printer
having the DA, AT, DBCS, or DBCSAT feature, or specifies that unprintable
characters should not be translated into blanks (the ASISCC operand).
Specifying TRANS tells RSCS that all files may contain the special characters
you are indicating and tells RSCS to translate these special characters
accordingly. However, the default translation mode you specify on TRANS can
be overridden by using the PRT option of the CP TAG command.
APL
If RSCS detects internally represented EBCDIC special APL characters in a
file, RSCS will translate those characters into the appropriate two-byte I/O
interface codes.
APL2®
If RSCS detects internally represented EBCDIC special APL2 character in a
file, RSCS will translate those characters into the appropriate two-byte I/O
interface codes.
This mode is only valid when FEATURE is set to DBCSAT or AT. If
TRANS=APL2 is specified with any other FEATURE setting, it is marked as
an incorrect combination and an error message is created.
ASISCC
RSCS will not translate unprintable characters into blanks. This lets the user
pass SCS orders to the remote printer.
TRANS=ASISCC means no translation occurs as a default. If a file needs
translation, then override this using the TAG command (assuming you used
the correct setting for the FEATURE operand of the START command.)
If the FEATURE option is not specified, only ASISCC, GRAPH, GRAF or
NOTR can be used on the TAG PRT command.
Note: TRANS=ASISCC can be specified without a FEATURE option.
DBCS
RSCS will verify double-byte EBCDIC character strings delimited by SO/SI
(shift-out/shift-in) characters for valid DBCS syntax before transmitting a file.
DBCSAPL
RSCS will translate internally represented EBCDIC special APL characters
into the appropriate two-byte I/O interface codes and will verify all
double-byte EBCDIC character strings delimited by SO/SI (shift-out/shift-in)
characters for valid DBCS syntax before transmitting a file.
DBCSAPL2
All files containing internally represented EBCDIC special APL2 characters
are translated to the appropriate two-byte I/O interface codes. This mode is
only valid when FEATURE is set to DBCSAT. If TRANS=DBCSAPL2 is
specified with any other FEATURE setting, it is marked as an incorrect
combination and an error message is created.
DBCSTEXT
RSCS will translate internally represented EBCDIC special TEXT characters
into the appropriate two-byte I/O interface codes and will verify double-byte
EBCDIC character strings delimited by SO/SI (shift-out/shift-in) characters
for valid DBCS syntax before transmitting a file.
Chapter 19. Configuring the RSCS Print Server
339
RSCS Print Server
Text
RSCS will translate internally represented EBCDIC special TEXT characters
into the appropriate two-byte I/O interface codes.
VFC=No
VFC=Yes
Specifies that the printer has the vertical forms control feature. When YES is
specified, the page length must be set manually on the printer and the LPAGE
value must match that setting. If omitted, the default is no vertical forms control,
and vertical spacing is achieved through multiple New Line orders. YES is valid
only for those printers that also support the 3270 CR (Carriage Return) order.
Note: Generally, it is recommend you specify VFC=YES. If users send GDDM
or IPDS™ graphic files to this printer, you must specify VFC=YES to
ensure that the pages align correctly.
XNL=No
XNL=Yes
Specifies that the link is to include an extra NL (New Line) order after each line
that is as long as the maximum number of print positions. Specify YES for
those printers that do not generate an extra new line function for a maximum
length line.
PRTWtm
The time, in seconds (1-600), between recovery attempts due to an unattached
device. If not specified, the default is 10 seconds.
PRTRet
The number of hours (1-100) the link will attempt error recovery due to an
unattached device before terminating. If not specified, the default is 1 hour.
MSG=Yes
MSG=No
Specifies if RSCS will allow the TN3270E-type link to dequeue messages
destined for transmission to the printer.
The following notes explain the use of the PARM statement for a TN3270E Type
link:
1. When you define a form name (using the FORM statement), you can define the
following characteristics:
v Separator page style
v Line length
v Page length
If you specify a form name when starting a link, be aware that the form name
characteristics always override any SEP, PPOS, and LPAGE specifications.
2. If you specify an incorrect combination of TRANS and FEATURE settings, the
SCO receives error message 807E and the link is deactivated.
Table 21. Correct Combinations for TRANS and FEATURE Settings
TRans=
APL
FEATure= DA
X
APL2
TEXT
DBCS
DBCSAPL
340
z/VM: TCP/IP Planning and Customization
X
FEATure= AT
FEATure=
DBCS
FEATure=
DBCSAT
X
X
X
X
X
X
X
X
X
RSCS Print Server
Table 21. Correct Combinations for TRANS and FEATURE Settings (continued)
TRans=
FEATure= DA
FEATure= AT
FEATure=
DBCS
FEATure=
DBCSAT
DBCSAPL2
X
DBCSTEXT
X
ASISCC
X
X
X
X
Note: If APL, APL2, or TEXT is specified for the TRANS operand, and the
FEATURE operand is set to DBCSAT, then there is no DBCS translation
of the file, only APL, APL2, or TEXT. The DBCS translation will only
occur with APL, APL2, or TEXT translation when the TRANS setting is
DBCSAPL, DBCSAPL2, or DBCSTEXT.
Note: TRANS=ASISCC does not require the FEATURE operand to be
specified.
TAG Command for a TN3270E printer
The options for a TAG command to a TN3270E printer are described in the
following sections. RSCS processes all the options until it meets a left parenthesis
or the end of the command.
Do not include an option more than once in the same TAG command. If you do,
RSCS uses the last value specified. For example, if you specify the following PRT
options on a TAG command to a TN3270E printer, the value of PRT will be
DBCSTEXT:
tag dev ... prt=asiscc ... prt=dbcstext
The following is a syntax diagram of the TAG command:
TAg
DEv
00E
nodeid
linkid
50
TN3270E Link Options
TN3270E Link Options:
PRT=
APL
APL2
ASISCC
DBCS
DBCSAPL
DBCSAPL2
DBCSTEXT
GRAF
GRAPH
NOTR
TEXT
PRMODE=
SOSI2
Chapter 19. Configuring the RSCS Print Server
341
RSCS Print Server
nodeid
Specifies the destination node ID for output created by the virtual device. You
must specify SYSTEM if you also specify DEST on the SPOOL command, to
allow DEST to have effect.
linkid
Identifies the virtual machine link ID, the directly attached workstation, or the
directly attached TN3270E printer link ID at the destination node (nodeid) that is
to receive the output generated by the virtual device.
If the link ID is omitted or specified as SYSTEM, the file will be transferred to
the system printer or punch. You must specify a link ID (or SYSTEM) if you also
specify a priority. You must specify SYSTEM if you also specify DEST on the
SPOOL command, to allow DEST to have effect.
PRT=
Overrides any translation mode (TRANS) specification of APL, APL2*, TEXT, or
DBCS on the RSCS START command for TN3270E-type links. If no APL-,
TEXT-, or DBCS-related PARM operands were specified when the link was
started, PRT is ignored, except for NOTR, GRAF, GRAPH, or ASISCC.
If PRT is not specified, the START PARM or OPARM (if specified) TRANS
setting is the default translation used for the file.
Alternatively, PRT can be used to identify a GDDM (Graphical Data Display
Manager) spool file.
The PRT can have the following values
APL
Specifies that internally represented EBCDIC special APL characters will be
translated to the appropriate two-byte I/O interface codes.
APL2
All files containing internally represented EBCDIC special APL2 characters
are translated to the appropriate two-byte I/O interface codes. This mode is
only valid when FEATURE is set to DBCSAT or AT. If PRT=APL2 is
specified with any other FEATURE setting, it is marked as an incorrect
combination and an error message is created.
ASISCC
RSCS will not translate unprintable characters in files into blanks. This lets
the user pass 3270 orders to the remote printer.
DBCS
Specifies that the file contains Double-Byte Character Set (DBCS) data.
DBCSAPL
Specifies that all files containing internally represented EBCDIC special APL
characters are to be translated to the appropriate two-byte I/O interface
codes and all double-byte EBCDIC character strings delimited by SO/SI
(shift-out/shift-in) characters will be verified for valid DBCS syntax before
being transmitted.
DBCSAPL2
Specifies that all files containing internally represented EBCDIC special
APL2 characters are to be translated to the appropriate two-byte I/O
interface codes and all double-byte EBCDIC character strings delimited by
SO/SI (shift-out/shift-in) characters will be verified for valid DBCS syntax
before being transmitted.
342
z/VM: TCP/IP Planning and Customization
RSCS Print Server
This mode is only valid when FEATURE is set to DBCSAT. If
PRT=DBCSAPL2 is specified with any other FEATURE setting, it is marked
as an incorrect combination and an error message is created.
DBCSTEXT
Specifies that all files containing internally represented EBCDIC special text
characters are to be translated to the appropriate two-byte I/O interface
codes and all double-byte EBCDIC character strings delimited by SO/SI
(shift-out/shift-in) characters will be verified for valid DBCS syntax before
being transmitted.
GRAPH
GRAF
Means that the file contains GDDM (Graphical Data Display Manager)
output records. For translation to occur the file must be in punch format.
NOTR
Means that the internally represented EBCDIC special APL, APL2, or TEXT
characters are not to be translated to the two byte I/O interface codes for
this file. Only 3270 translation will occur for the removal of 3270 control
characters.
TEXT
Specifies that internally represented EBCDIC special text characters will be
translated to the appropriate two-byte I/O interface codes.
PRMODE=
Specifies if a blank character should print before and after a DBCS character.
PRMODE=SOSI2 for TN3270E will result in the SO and SI being replaced with
an SA order for DBCS and a reset and will occupy no space in the output line.
When PRMODE is not specified, then the SO, SI will occupy 1 position in an
output line.
SOSI2
Does not print a blank before and after a DBCS character string.
Chapter 19. Configuring the RSCS Print Server
343
RSCS Print Server
344
z/VM: TCP/IP Planning and Customization
Chapter 20. Configuring the SMTP Server
The Simple Mail Transfer Protocol (SMTP) server virtual machine can be configured
to:
v operate as either an “open” or a secure mail gateway between TCP/IP network
users, and users located on an RSCS network that is attached to the local host.
This allows, for example, OfficeVision users to exchange mail with UNIX users
through the VM TCP/IP SMTP gateway.
v direct mail to a mailer server virtual machine, or to a specific remote SMTP
server for processing.
v process mail using mail aliases, forwarding, and distribution lists defined in an
SMTP NAMES file.
v change mail header addresses and specify header address transformations.
To configure the SMTP server, you must perform the following steps:
SMTP Server Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the system (CP) directory for the SMTP server.
3.
4.
5.
6.
Update the DTCPARMS file for the SMTP server.
Update the TCPIP DATA file for domain name resolution.
Customize the SMTP CONFIG file.
Perform advanced SMTP server configuration, if needed.
Dynamic System Operation
The SMTP server provides a VM Special Message (SMSG) interface that allows
you to perform server administration tasks through a set of privileged commands.
For more information, see “Dynamic Server Operation” on page 390.
Step 1: Update PROFILE TCPIP
Include the SMTP server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The SMTP server is then automatically started
when TCPIP is initialized. The IBM default user ID for this server is SMTP. Verify
that the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
SMTP
0
The SMTP server requires that port TCP 25 be reserved for it. Verify that the
following statement has been added to your TCPIP server configuration file as well:
PORT
25 TCP SMTP
; SMTP Server
Step 2: Update the System (CP) Directory for the SMTP Server
The SMTP virtual machine must be authorized to use the *SPL system service for
reading spool files. To use this service, the following CP directory statement must
be added for each SMTP server:
IUCV *SPL
© Copyright IBM Corp. 1987, 2002
345
SMTP Server
Step 3: Update the DTCPARMS File
When the SMTP server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the SMTP server are:
:nick.SMTP
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the SMTP server if you use a
configuration file other than SMTP CONFIG.
SMTP Command
SMTP services are initiated using the SMTP command:
SMTP
SMTP
CONFIG
filename
filetype
*
filemode
Specify SMTP command operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
filename
The file name of the SMTP server configuration file. The default file name is
SMTP.
filetype
The file type of the configuration file. The default file type is CONFIG.
filemode
The file mode of the configuration file. The default file mode is *.
Step 4: Update the TCPIP DATA File for Domain Name Resolution
You can configure the SMTP server to use either a domain name server or the local
site tables for host and domain name resolution. To use a domain name server,
configure the TCPIP DATA file to define the internet address of one or more name
servers using NSINTERADDR statements. For more information, see Chapter 3,
“Defining the TCP/IP System Parameters” on page 15. If the TCPIP DATA file does
not identify any name servers, local site tables are used. However, if the SMTP
server is configured to use name servers, SMTP does not use these site tables.
To obtain detailed information about how the SMTP server resolves a particular host
name (for debugging purposes), you can use the SMTP TRACE RESOLVER
configuration file statement or SMSG command; these are described in more detail
on pages 372 and 405.
346
z/VM: TCP/IP Planning and Customization
SMTP Server
When SMTP uses a name server, it asks for the MX records for the host to which it
is trying to connect. If such MX records are unavailable, the A records for the host
are used. For more information about MX records, see “Use of MX Records” or
RFC 974, Mail Routing and the Domain System.
Step 5: Customize the SMTP CONFIG File
The SMTP configuration file, SMTP CONFIG, defines how the SMTP server is to
operate, and what services it provides. See “SMTP Server Configuration File
Statements” on page 348 for detailed information about how to specify entries within
this file. A sample SMTP configuration file is provided as SMTP SCONFIG on the
TCPMAINT 591 disk. Your customized SMTP configuration file should be copied to
the TCPMAINT 198 minidisk as SMTP CONFIG. Table 22 on page 348 provides a
summary of the configuration statements.
Step 6: Additional SMTP Server Considerations
Before you configure the SMTP server using the statements described in “Step 5:
Customize the SMTP CONFIG File” on page 347, you may want to review the
information in the following sections:
v “Configuring a TCP/IP-to-RSCS Mail Gateway” on page 376
v “Configuring a TCP/IP-to-RSCS Secure Mail Gateway” on page 377
v “Defining Nicknames and Mailing Lists” on page 380
These sections discuss additional configuration steps and files that are necessary
for the SMTP server to run correctly when configured as a mail gateway, or to
process mail using mail aliases or forwarding and distribution lists.
The sections that follow provide information about how MX records defined within
the Domain Name System and the classification of a mail recipient can affect SMTP
server operations.
Use of MX Records
MX records are a type of resource record used in the Domain Name System. For
more information about MX and Resource records, see “Resource Records” on
page 146. MX records direct the SMTP server to deliver mail to alternative hosts.
They are obtained from a domain name server. If SMTP is configured to not use a
name server, MX records are not used.
For example, if SMTP wants to send mail to [email protected], it checks the name
server for MX records and finds the following:
HOST
HOST
HOST
MX
MX
MX
0
5
10
HOST
HOST-BACKUP1
HOST-BACKUP2
SMTP delivers the mail to the record (host) that has the lowest count; in this
example, mail is delivered directly to HOST. If HOST cannot receive the mail, SMTP
tries to deliver it to HOST-BACKUP1. If HOST-BACKUP1 cannot receive the mail, it then
tries to deliver it to HOST-BACKUP2. If none of these hosts can receive the mail,
SMTP stores the mail and queues it for later delivery, at which time this delivery
process is repeated.
If SMTP does not find MX records for a host, it delivers mail to only the primary
host.
Chapter 20. Configuring the SMTP Server
347
SMTP Server
Local versus Non-local Mail Recipients
When SMTP processes a piece of mail, it determines whether the recipient of that
mail is a local or a non-local user, to allow proper handling of that mail. For
example, the result of this determination can affect the mail forwarding processing
performed by SMTP.
When a recipient is determined to be a local user, the z/VM SMTP server then
handles the delivery of that mail itself, possibly through the use of a local mailer, or
other network services. SMTP considers a user to be a local user if that user is
either:
v a user ID on the local z/VM system
v defined in its SMTP NAMES file, through either a mail alias, a mail forwarding
entry, or a mail distribution list
v a user located on an RSCS network that is attached to the local host (applies
only to SMTP mail gateway configurations)
If these criteria do not apply to the mail recipient, SMTP considers that user to be a
non-local user, and will take necessary actions to process that user’s mail.
SMTP Server Configuration File Statements
Table 22 provides a summary of the configuration file statements. Keep in mind the
following when configuration statements are specified:
v Tokens are delimited by blanks and record boundaries.
v All characters to the right of, and including, a semicolon are treated as
comments.
Table 22. SMTP CONFIG Configuration Statements
Statement
Description
ALTRSCSDOMAIN
Specifies an alternative domain name of the RSCS network, if SMTP is
running as a mail gateway.
350
ALTTCPHOSTNAME
Specifies an additional host name for the local host. Mail received for this
host name is accepted and delivered locally.
350
BADSPOOLFILEID
Specifies the user ID on the local system where SMTP transfers
unreadable spool files and looping mail.
350
DBCS
Specifies that SMTP should perform DBCS code conversion on mail.
351
FILESPERCONN
Specifies the number of files (notes) at which another connection will be
opened to a remote host.
352
FINISHOPEN
Specifies the SMTP wait time for connection.
353
FORWARDMAIL
Specifies whether or not to forward mail to non-local users, or identifies a
user exit to control mail forwarding.
353
GATEWAY
Specifies operation of SMTP as a gateway.
354
INACTIVE
Specifies the SMTP wait time before closing an inactive connection.
355
IPMAILERADDRESS
Specifies the address on which SMTP queues mail when it cannot resolve
the recipient’s address.
355
LOCALFORMAT
Specifies the spool file format for local host mail delivery.
356
LOG
Directs SMTP to log all SMTP traffic.
356
MAILER
Identifies a virtual machine to receive mail for various classes of mail
recipients.
357
348
z/VM: TCP/IP Planning and Customization
Page
SMTP Server
Table 22. SMTP CONFIG Configuration Statements (continued)
Statement
Description
Page
MAILHOPCOUNT
Specifies a limiting value that is used by SMTP to detect a mail delivery
loop condition and then cease delivery attempts for a mail item.
358
MAXCONNPERSITE
Specifies the maximum number of connections that can be opened to a
remote host concurrently.
359
MAXMAILBYTES
Specifies the maximum size of mail that is accepted over TCP/IP
connections.
359
NOLOG
Turns off logging of mail transactions.
359
ONDISKFULL
Specifies a set of CP commands for SMTP to execute when specified
SMTP 191 disk-full thresholds are crossed.
360
OUTBOUNDOPENLIMIT
Specifies a limit on the maximum number of simultaneous TCP/IP
connections over which SMTP actively delivers mail.
361
PORT
Specifies an alternative port number for SMTP server during testing.
361
POSTMASTER
Specifies the address (or addresses) for mail addressed to the postmaster
at the local host.
361
RCPTRESPONSEDELAY
Specifies the amount of time the SMTP server delays responding to the
RCPT commands.
362
RESOLVERRETRYINT
Specifies the number of minutes SMTP waits between attempts to resolve
domain names.
363
RESTRICT
Specifies addresses of users who are not allowed to use SMTP mail
services.
363
RETRYAGE
Specifies the number of days after which mail is returned as undeliverable.
364
RETRYINT
Specifies the number of minutes between attempts to send mail to an
inactive TCP/IP host.
364
REWRITE822HEADER
Specifies whether SMTP should rewrite the RFC 822 headers of mail
arriving from the RSCS side of the mail gateway.
365
RSCSDOMAIN
Specifies the domain name of the RSCS network (if SMTP is running as a
mail gateway).
365
RSCSFORMAT
Specifies the spool file format for mail delivered to recipients on the RSCS
network.
366
SECURE
Specifies that SMTP operates as a secure mail gateway between TCP/IP
network sites and RSCS network sites.
366
SMSGAUTHLIST
Specifies the addresses of users authorized to issue privileged SMTP
SMSG commands.
367
SMTPCMDS
Defines the characteristics of the SMTP command user exit and indicates
whether or not the exit is to be enabled (on) or disabled (off) when the
server completes initialization.
367
SOURCEROUTES
Specifies whether or not SMTP will honor source routes.
370
SUPRESSNOTIFICATION
Specifies that SMTP should not send a notification to the mail sender
when mail delivery is successful.
371
TEMPERRORRETRIES
Specifies the number of times SMTP tries to redeliver mail to a host with a
temporary problem.
371
TRACE
Specifies which type of tracing should be enabled during server
initialization.
372
VERIFYCLIENT
Specifies whether or not client verification is to be performed. Client
verification can be performed using the built-in client verification function or
through a user exit.
372
Chapter 20. Configuring the SMTP Server
349
SMTP Server
Table 22. SMTP CONFIG Configuration Statements (continued)
Statement
Description
Page
VERIFYCLIENTDELAY
Specifies the amount of time (in seconds) that SMTP will wait for the
domain name system to respond during client verification.
374
WARNINGAGE
Specifies the number of days after which a copy of the mail is returned to
the sender.
374
8BITMIME
Specifies the file name of the translation table to be used for 8-bit MIME
support.
375
ALTRSCSDOMAIN Statement
The ALTRSCSDOMAIN statement specifies an alternate domain name for an RSCS
network (if SMTP is configured to operate as a mail gateway). This alternate
domain name is used in the same manner, but in addition to any domain name
defined using the RSCSDOMAIN statement. Only one ALTRSCSDOMAIN statement
can be specified within the SMTP configuration file.
ALTRSCSDOMAIN domain
Operands
domain
The alternate domain name of the RSCS network. The alternative RSCS
domain name is a string of 1 to 64 alphanumeric characters.
ALTTCPHOSTNAME Statement
The ALTTCPHOSTNAME statement specifies an alternate fully qualified host name
by which SMTP knows the local host. Mail sent to users at hostname are treated as
if they were local users.
ALTTCPHOSTNAME hostname
Operands
hostname
The alternate TCP/IP host name of this host.
BADSPOOLFILEID Statement
The BADSPOOLFILEID statement specifies the user ID on the local system where
SMTP transfers unreadable spool files and looping mail. You can specify the
BADSPOOLFILEID statement only once.
350
z/VM: TCP/IP Planning and Customization
SMTP Server
BADSPOOLFILEID TCPMAINT
BADSPOOLFILEID user_id
Operands
user_id
The user ID on the local system to which bad spool files and looping mail are
delivered; user_id should be a maximum of 8 characters. The default is
TCPMAINT.
DBCS Statement
The DBCS statement specifies that SMTP is to perform DBCS code conversion on
processed mail. The parameters of the DBCS statement determine which
translation table should be used in the conversion.
The following example shows the format of the DBCS statement.
DBCS
JIS78KJ
JIS83KJ
SJISKANJI
EUCKANJI
IBMKANJI
HANGEUL
KSC5601
TCHINESE
ASCII
JISROMAN
Operands
JIS78KJ
Indicates IBM Kanji to JIS 1978 Kanji conversion is to be performed. The JIS
1978 Shift-Out codes are ESC, $, and @. SMTP will load the JIS78KJ DBCS
translation table from the TCPKJBIN binary translate table file.
JIS83KJ
Indicates IBM Kanji to JIS 1983 Kanji conversion is to be performed. The JIS
1983 Shift-Out codes are ESC, $, and B. SMTP will load the JIS83KJ DBCS
translation table from the TCPKJBIN binary translate table file.
ASCII
Indicates mail is to be shifted in ASCII code from JIS Kanji code. The ASCII
Shift-In codes are ESC, (, and B.
JISROMAN
Indicates mail is to be shifted in JISRoman code from JIS Kanji code. The
JISRoman Shift-In codes are ESC, (, and J.
SJISKANJI
Indicates IBM Kanji to Shift-JIS Kanji conversion is to be performed. SMTP will
load the SJISKANJI DBCS translation table from the TCPKJBIN binary translate
table file.
Chapter 20. Configuring the SMTP Server
351
SMTP Server
EUCKANJI
Indicates IBM Kanji to Extended UNIX Code Kanji conversion is to be
performed. SMTP will load the EUCKANJI DBCS translation table from the
TCPKJBIN binary translate table file.
IBMKANJI
Indicates IBM (EBCDIC) Kanji conversion is to be used. This option causes no
conversion to be performed on the body of the mail; it may be used for sending
and receiving mail in EBCDIC. If this option is selected, other SMTP servers on
the same network should all be configured to perform IBMKANJI conversions. If
IBMKANJI is specified, and LOCALFORMAT or RSCSFORMAT is set to
PUNCH, then mail received in ASCII may be folded to inconsistent record
lengths. LOCALFORMAT and RSCSFORMAT should be set to NETDATA in this
case.
Indicates IBMKANJI transfer type does not require any translate table to be
loaded.
HANGEUL
Indicates IBM Hangeul to Hangeul PC code conversion is to be performed.
SMTP will load the HANGEUL DBCS translation table from the TCPHGBIN
binary translate table file.
KSC5601
Indicates IBM Hangeul to KSC-5601 PC code conversion is to be performed.
SMTP will load the KSC5601 DBCS translation table from the TCPHGBIN
binary translate table file.
TCHINESE
Indicates IBM Traditional Chinese to Traditional Chinese 5550 PC code
conversion is to be performed. SMTP will load the TCHINESE (5550) DBCS
translation table from the TCPCHBIN binary translate table file.
The SBCS translation table, STANDARD TCPXLBIN, will be used to convert mail
headers, with the body of the mail being converted using a DBCS translation table
from SMTP TCPKJBIN, SMTP TCPHGBIN, or SMTP TCPCHBIN. If SMTP
TCPKJBIN, SMTP TCPHGBIN, or SMTP TCPCHBIN, cannot be found, then SMTP
will use STANDARD TCPKJBIN, STANDARD TCPHGBIN, or STANDARD
TCPCHBIN.
DBCS conversion is performed only on outgoing and incoming mail to and from
TCP/IP-connected hosts. Mail spooled to SMTP for the local host is delivered
directly, without any DBCS code conversion.
Note: For more information on loading and customizing DBCS translate tables, see
“Customizing DBCS Translation Tables” on page 629.
FILESPERCONN Statement
The FILESPERCONN statement specifies the number of files (notes) backed up to
a remote host at which another connection will be opened to help deliver mail. A
new connection will be opened every FILESPERCONN files backed up to a remote
host up to the maximum value specified in the MAXCONNPERSITE configuration
file statement.
352
z/VM: TCP/IP Planning and Customization
SMTP Server
FILESPERCONN 5
FILESPERCONN files
Operands
files
An integer in the range of 1 through 1,000 indicating the number of files at
which another connection will be opened to a remote host. The default is 5 files.
FINISHOPEN Statement
The FINISHOPEN statement specifies the number of seconds SMTP waits while
trying to establish a connection to a foreign site. After the specified number of
seconds, SMTP aborts the connection.
FINISHOPEN 120
FINISHOPEN seconds
Operands
seconds
An integer in the range of 1 through 86,400 (24 hours) indicating the number of
seconds to wait for a connection to open. The default FINISHOPEN time-out is
120 seconds.
FORWARDMAIL Statement
The FORWARDMAIL statement is used to indicate whether or not to forward mail to
non-local users, or to identify a user exit to be used to control mail forwarding. For
information on using the mail forwarding exit, see the TCP/IP Programmer’s
Reference.
FORWARDMAIL YES ENDFORWARDMAIL
FORWARDMAIL
NO
EXIT
SMTPFWDX EXEC
exitname
EXEC
ON
ENDFORWARDMAIL
OFF
TEXT
Operands
YES
Indicates mail forwarding is to be performed; this is the default.
Chapter 20. Configuring the SMTP Server
353
SMTP Server
NO
Indicates that no mail forwarding is to be performed. When SMTP determines
that the recipient is not on the local system, the RCPT TO: command will be
rejected.
EXIT
Indicates a mail forwarding exit routine is being defined.
exitname
The name of the exit routine associated with this command; the default exit
name is SMTPFWDX.
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC; this is the default.
TEXT
Indicates the exit routine name specified on this command is the name of a text
deck.
ON
Indicates the specified exit (being defined with this command) is to be enabled
(turned on).
OFF
Indicates the specified exit (being defined with this command) is to be disabled
(turned off).
Examples
v The following SMTP configuration file entry will enable the mail forwarding exit
routine SMTPFWDX EXEC.
ForwardMail
exit smtpfwdx exec on
EndForwardMail
When this entry is processed, the following text is displayed during server
initialization:
Forward Mail
: Exit SMTPFWDX EXEC ON
v This next entry defines the mail forwarding exit routine SMTPFWDX TEXT, but
disables its use once SMTP server initialization is complete. Thus, mail
forwarding will be allowed and performed.
ForwardMail
exit smtpfwdx text off
EndForwardMail
When this entry is processed, the following text is displayed during server
initialization:
Forward Mail
: Yes (Exit SMTPFWDX TEXT OFF)
GATEWAY Statement
The GATEWAY statement specifies that SMTP is to operate as a mail gateway
between TCP/IP network sites and RSCS network sites (provided the host system
is connected to both a TCP/IP network and an RSCS network).
If GATEWAY is specified, SMTP accepts mail addressed to users on RSCS hosts
defined in the SMTPRSCS HOSTINFO file. For more information about setting up a
354
z/VM: TCP/IP Planning and Customization
SMTP Server
gateway node, see “Configuring a TCP/IP-to-RSCS Mail Gateway” on page 376. If
GATEWAY is not specified, SMTP rejects all mail that arrives from RSCS.
GATEWAY
Operands
The GATEWAY statement has no operands.
INACTIVE Statement
The INACTIVE statement specifies the period of inactivity (in seconds) after which
SMTP considers a connection to be broken (that is, unusable). After the specified
amount of inactive time, SMTP closes the connection.
INACTIVE 180
INACTIVE seconds
Operands
seconds
An integer, in the range of 1 through 86,400 (24 hours), that specifies the
number of seconds after which SMTP considers a connection to be broken. The
default INACTIVE time-out period is 180 seconds.
IPMAILERADDRESS Statement
The IPMAILERADDRESS statement specifies an IP address to which SMTP
queues mail when it cannot resolve a mail recipient address.
Note: The IPMAILERADDRESS statement and the UNKNOWN parameter of the
MAILER statement are mutually exclusive. The SMTP server will not initialize
if both are specified in the SMTP configuration file.
IPMAILERADDRESS is useful when your VM system does not have full connectivity
to or knowledge of other networks. It allows you to direct mail to a different SMTP
server that may be able to deliver mail to requested hosts that reside on these
other networks.
IPMAILERADDRESS
ip_address
LIST ip_address
ENDIPMAILERADDRESS
Chapter 20. Configuring the SMTP Server
355
SMTP Server
Operands
ip_address
The dotted-decimal internet address of the host to which SMTP is to direct mail
when it cannot resolve a mail recipient address.
LIST
Indicates that a list of IP addresses will be given to which SMTP will direct a
piece of mail when it cannot resolve a mail recipient address. SMTP will attempt
to direct the mail to the first IP address in the list. If unable to connect to that
address, SMTP will proceed through the list sequentially until the mail is
redirected or the list is exhausted.
LOCALFORMAT Statement
The LOCALFORMAT statement specifies the spool file format for mail delivered to
recipients on the local host. The default format is NETDATA.
For PUNCH format:
v The spool file is in CMS PUNCH NOHEADER format.
v Records are folded to 80 or fewer characters in length.
v Spool file class M is used.
v The file name is the first 8 characters of the user ID of the sender.
v The file type is MAIL.
For NETDATA format:
v The spool file is in NETDATA format.
v Records can be longer than 80 characters.
v Spool file class A is used.
v The file name is the first 8 characters of the user ID of the sender.
v The file type is NOTE.
LOCALFORMAT NETDATA
LOCALFORMAT PUNCH
Operands
PUNCH
Indicates that records are folded to 80 or fewer characters in length.
NETDATA
Indicates that records can be longer than 80 characters and arrive as
MESSAGE-type records. The default format is NETDATA.
LOG Statement
The LOG statement specifies that SMTP is to log information about all SMTP traffic.
The origin, sender, and recipients of each piece of mail are written to the log as
mail is received and delivered. To turn off logging, use the NOLOG statement.
356
z/VM: TCP/IP Planning and Customization
SMTP Server
LOG DISK
LOG SPOOL
Operands
DISK
Indicates that log information is to be appended to the SMTP log file; DISK is
the default.
SPOOL
Indicates that log information is to be written to the console.
MAILER Statement
The MAILER statement identifies a virtual machine to receive mail for various
classes of mail recipients. There are three possible formats that the MAILER virtual
machine will accept. If PUNCH or NETDATA format is specified, then the MAILER
virtual machine must exist on the local node or a node on the RSCS network and it
must accept batch SMTP format spool files. If IMAP is specified for the format then
the MAILER virtual machine is an IMAP server and it must exist on the local node.
For IMAP, all local mail will be punched to the IMAP server.
MAILER
user_id
[email protected]_id
PUNCH
NETDATA
IMAP
Options
Options:
SOURCEROUTES
NOSOURCEROUTES
LOCAL
NOLOCAL
RSCS
NORSCS
UNKNOWN
NOUNKNOWN
Operands
user_id
The user ID of a MAILER virtual machine; this machine is presumed to reside
on the local RSCS node.
[email protected]_id
The user ID and RSCS node of a MAILER virtual machine.
PUNCH
Indicates that the remote MAILER virtual machine can accept only PUNCH
format spool files. BSMTP header records longer than 80 characters are split,
and an EBCDIC newline character (X'15') is placed in column 80 to indicate that
the record is continued. Records within the body of the mail longer than 80
characters are split across multiple PUNCH records.
Chapter 20. Configuring the SMTP Server
357
SMTP Server
NETDATA
Indicates that the MAILER virtual machine accepts NETDATA format spool files.
The NETDATA protocol automatically handles records longer than 80
characters.
IMAP
Indicates that the MAILER virtual machine is an IMAP server. This server must
reside on the local node and all mail that is destined for local recipients will be
punched over to the IMAP server in NETDATA format. The IMAP server will
handle the proper delivery of the mail by either placing it into an IMAP mailstore
(for registered IMAP users) or transferring it directly to the local userid (for
non-registered users).
SOURCEROUTES
Indicates that the MAILER virtual machine accepts BSMTP header addresses
with source routes.
NOSOURCEROUTES
Indicates that the MAILER virtual machine does not accept source routes in the
BSMTP header addresses.
LOCAL
Indicates that mail for local recipients is spooled to the MAILER virtual machine.
NOLOCAL
Indicates that mail for local recipients is spooled directly to the recipients.
RSCS
Indicates that mail for recipients on the RSCS network is spooled to the
MAILER virtual machine.
NORSCS
Indicates that mail for recipients on the RSCS network is spooled directly to the
recipients.
UNKNOWN
Indicates that mail for recipients on an unknown host is spooled to the MAILER
virtual machine.
NOUNKNOWN
Indicates that mail for recipients on unknown hosts is returned to the sender as
undeliverable.
MAILHOPCOUNT Statement
The MAILHOPCOUNT statement is used by SMTP to detect a mail delivery loop
condition between itself and another mail server. When this condition arises, SMTP
ceases delivery attempts for a mail item.
MAILHOPCOUNT
25
rcv_limit
Operands
rcv_limit
An integer in the range of 5 to 300 that specifies the maximum number of
Received lines that can exist within the header section of a given mail item. The
default is 25.
358
z/VM: TCP/IP Planning and Customization
SMTP Server
When the Received lines present the header section of a given mail item
matches the specified rcv_limit value, SMTP considers the delivery process for
that piece of mail to be in a loop and stops its attempts to deliver that mail item.
The mail item in question (and its corresponding ADDRFILE file) are renamed
and saved by SMPT at file mode A.
MAXCONNPERSITE Statement
The MAXCONNPERSITE statement specifies the maximum number of connections
that can be opened concurrently to one remote host.
MAXCONNPERSITE 10
MAXCONNPERSITE conns
Operands
conns
An integer in the range of 1 through 256 indicating the maximum number of
concurrent connections that can be opened to a remote host. The default is 10
connections.
MAXMAILBYTES Statement
The MAXMAILBYTES statement specifies the maximum size, in bytes, of mail that
is accepted over a TCP connection.
MAXMAILBYTES 524288
MAXMAILBYTES bytes
Operands
bytes
The maximum number of bytes to accept. Mail larger than this size that arrives
over a TCP connection is rejected. The limits for this statement are 1 and
2,147,483,647. The default byte size is 524,288.
NOLOG Statement
The NOLOG statement turns off the logging of information about SMTP traffic. For
more information, see “LOG Statement” on page 356.
NOLOG
Operands
The NOLOG statement has no operands.
Chapter 20. Configuring the SMTP Server
359
SMTP Server
ONDISKFULL Statement
The ONDISKFULL statement specifies a set of CP commands (such as CP MSG or
CP SMSG) for SMTP to execute when specified SMTP 191 disk-full thresholds are
crossed.
ONDISKFULL threshold
ACTIONS BEGINactionEND
ENDACTIONS
Operands
threshold
The disk-full percentages for which actions should be performed. Positive
numbers cause the actions to execute when the SMTP 191 minidisk percentage
exceeds the percent specified. Negative numbers cause the actions to execute
when the minidisk utilization drops below the percent specified.
action
A CP command that is to be issued when a threshold condition is crossed. To
simplify the issuing of informational messages, the special keyword
*MESSAGE* can be included as part of the action string. This will cause one
of the following text strings (as warranted) to be substituted in place of
*MESSAGE*:
date time SMTPserver_id at SMTPnode_id - Disk Above nn Percent Full
or
date time SMTPserver_id at SMTPnode_id - Disk Below nn Percent Full
There is no limit on the number of BEGIN action END statements that you can
specify. All commands are converted to uppercase, and extra blanks are removed.
The CP command output for all action commands is suppressed, although nonzero
command return codes will be reported. The ENDACTIONS statement ends the
ONDISKFULL statement.
In the following example, the ONDISKFULL statement causes messages to be sent
to two users (MATT at ENDICOTT and TCPMAINT on the local system) when the
SMTP 191 minidisk exceeds 40, 50, 60, 70, 80, and 90 percent full. Messages are
also sent when the disk full percentage decreases below these same thresholds.
;
; On Disk Full Actions
;
ONDISKFULL 40 50 60 70 80 90 -90 -80 -70 -60 -50 -40 ACTIONS
BEGIN CP SMSG RSCS MSG ENDICOTT MATT *MESSAGE* END
BEGIN CP MSG TCPMAINT *MESSAGE* END
ENDACTIONS
;
For the above statements, the message that follows would be received by user
MATT at ENDICOTT when the 191 minidisk of the SMTP server at WATSON
exceeds 50 percent full:
From WATSON(SMTP): 03/17/99 21:54 SMTP at WATSON - Disk Above 50 Percent Full
360
z/VM: TCP/IP Planning and Customization
SMTP Server
whereas the TCPMAINT user (on the local WATSON system) would receive this
message:
03/17/99 21:54 SMTP at WATSON - Disk Above 50 Percent Full
OUTBOUNDOPENLIMIT Statement
The OUTBOUNDOPENLIMIT statement specifies the limit on the maximum number
of simultaneous TCP connections over which SMTP can actively deliver mail. By
default, SMTP operates with no limits, and opens as many TCP connections as
necessary to ensure the fastest possible delivery of mail. The
OUTBOUNDOPENLIMIT statement should be specified only if there are limited TCP
resources on the system and SMTP is using an unfair portion of these resources.
OUTBOUNDOPENLIMIT connections
Operands
connections
A number in the range of 1 to the maximum number of TCP connections
available on your system. If connections is out of range, no limit is imposed.
PORT Statement
The PORT statement causes SMTP to listen on a specified TCP connection port.
By convention, port number 25 is usually reserved (in the TCPIP server
configuration file) for the SMTP server to accept incoming mail requests.
PORT 25
PORT port_number
Operands
port_number
An integer in the range of 1 through 65,535 that specifies the port number to
which SMTP listens. The default is port 25.
POSTMASTER Statement
The POSTMASTER statement identifies the user that should receive mail sent to
the “postmaster” of the system where the SMTP server runs. A postmaster is
generally responsible for managing the mail system for a site. As such, other users
in the internet community might send mail to the postmaster, to report mail
problems they believe are associated with that site, or to have mail routed to a
recipient (either local or in a different domain) for which the correct address is not
known.
Chapter 20. Configuring the SMTP Server
361
SMTP Server
POSTMASTER TCPMAINT
POSTMASTER
user_id
[email protected]
Operands
user_id
A user ID on the local system to which mail addressed to “postmaster” should
be delivered; the default is TCPMAINT.
[email protected]
A user ID and host name to which mail addressed to “postmaster” should be
delivered. The supplied user_id and hostname values may identify either a user
ID on a specific RSCS node, or an internet user and host name.
Notes:
1. If a POSTMASTER statement is not specified, the default value, TCPMAINT, will
be used.
2. If SMTP is not operating as a secure mail gateway between TCP/IP and RSCS
network sites, multiple POSTMASTER statements can be specified. When this
is done, code a separate POSTMASTER statement for each user that should
receive mail addressed to “postmaster”. No limit is imposed on the number of
POSTMASTER statements that can be coded.
3. If SMTP is operating as a secure mail gateway between TCP/IP and RSCS
network sites, only one POSTMASTER statement can be specified. Additionally,
user_id must be a user ID defined for the local system.
RCPTRESPONSEDELAY Statement
The RCPTRESPONSEDELAY statement specifies the amount of time the SMTP
server delays its response to a RCPT TO: command (supplied by a remote STMP
“sender” host) while host domain resolution of a mail recipient is being performed. If
SMTP does not receive a domain name server (DNS) response within the specified
period, it assumes the host resolution is successful and does the following:
v Sends a 250 OK response to the “sender” SMTP host
v Queues the mail locally, so that asynchronous resolution of the mail recipient can
be performed.
If SMTP later determines that the recipient address cannot be resolved, the queued
mail is returned to the sender.
RCPTRESPONSEDELAY 60
RCPTRESPONSEDELAY seconds
Note: When the client sends multiple commands (including the RCPT command)
without waiting for the response from the SMTP server, the SMTP server
362
z/VM: TCP/IP Planning and Customization
SMTP Server
responds immediately to the RCPT command with the 250 OK message.
The RCPTRESPONSEDELAY value will be ignored.
Operands
seconds
The number of seconds SMTP waits before responding to the RCPT TO:
command. The range is 0 through 86,400 (24 hours). The default is 60
seconds.
RESOLVERRETRYINT Statement
The RESOLVERRETRYINT statement specifies the interval (in minutes) the SMTP
server should wait between attempts to resolve a host domain name.
RESOLVERRETRYINT 20
RESOLVERRETRYINT minutes
Operands
minutes
An integer in the range of 1 to 1439 (24 hours - 1 minute) that specifies the
number of minutes SMTP should wait between successive attempts to resolve a
host domain name. The default is 20 minutes.
RESTRICT Statement
The RESTRICT statement identifies users who may not send mail through this
SMTP server. If SMTP receives a spool file from a restricted user, the spool file is
purged, returned to the sender or transferred to a third party, depending on the
options specified.
In addition, SMTP rejects any MAIL FROM: or RCPT TO: commands whose
destinations are restricted users.
SMTP rejects only addresses that are in the restrict list; it does not check for
aliases. For example, you can restrict [email protected] If host2 is an alias for host1,
mail for [email protected] is not rejected, unless [email protected] is also in the restrict list.
RESTRICT
PURGE
RETURN
TRANSFERTO transfer_id
[email protected]_id
ENDRESTRICT
Note: The RESTRICT statement cannot be used if the SMTP virtual machine is
running as a secure gateway. Either remove or comment out the
RESTRICT statements from the SMTP CONFIG file.
Operands
PURGE
Indicates that spool files from restricted users are to be purged.
Chapter 20. Configuring the SMTP Server
363
SMTP Server
RETURN
Indicates that spool files from restricted users are to be returned to each
respective user.
TRANSFERTO
Indicates that spool files from restricted users are to be transferred to a specific
user ID.
transfer_id
The user ID to which the spool file is transferred.
[email protected]_id
The user ID and node ID of a restricted user. This parameter can be repeated,
and can include an asterisk (*) to act as a wildcard.
The ENDRESTRICT statement ends the RESTRICT statement.
RETRYAGE Statement
The RETRYAGE statement specifies the amount of time after which SMTP returns
mail as undeliverable. SMTP tries to deliver mail to an inactive site at intervals
determined by the RETRYINT statement. After the amount of time specified by the
RETRYAGE statement has passed, SMTP returns the mail to the sender with a
note that lists the recipients to which the mail could not be delivered.
RETRYAGE 3 D
RETRYAGE duration
D
H
M
Operands
duration
The amount of time (specified in days, hours, or minutes) over which SMTP is
to attempt delivery of a piece of mail. If duration is specified in days, the range
is 0 through 365; when it is given in hours, the range is 0 through 8760 (365
days). When duration is specified in minutes, the range is 0 through 525600
(365 days). The default is 3 days.
D
Indicates that duration is specified in days. This is the default.
H
Indicates that duration is specified hours.
M Indicates that duration is specified in minutes.
RETRYINT Statement
The RETRYINT statement specifies the number of minutes SMTP should wait
between attempts to deliver mail to a TCP/IP host that is inactive (that is, not
responsive to connection attempts).
364
z/VM: TCP/IP Planning and Customization
SMTP Server
RETRYINT 20
RETRYINT minutes
Operands
minutes
An integer in the range of 0 to 1440 (24 hours) that specifies the number of
minutes SMTP should wait between mail delivery attempts to an inactive host.
The default is 20 minutes.
REWRITE822HEADER Statement
The REWRITE822HEADER statement specifies the direction to SMTP to rewrite or
print the RFC 822 headers of mail arriving from the RSCS side of the mail gateway.
REWRITE822HEADER YES NOPRINT
REWRITE822HEADER
YES
NO
PRINT
NOPRINT
Operands
YES
Indicates that SMTP should rewrite the RFC 822 mail headers. The YES
parameter with NOPRINT is the default. SMTP uses a set of default header
rewriting rules. For more information to customize the rewriting rules, see
“Customizing SMTP Mail Headers” on page 381.
NO
Indicates that SMTP should not rewrite the RFC 822 mail headers. This is not
recommended unless all mail user agents sending mail to SMTP create RFC
822 mail headers with fully qualified domain addresses that are valid on the
internet.
PRINT
Indicates that SMTP should print the RFC 822 header rewriting rules to the
console.
NOPRINT
Indicates that SMTP should not print the RFC 822 header rewriting rules to the
console.
RSCSDOMAIN Statement
The RSCSDOMAIN statement specifies the domain name of the RSCS network (if
SMTP is running as a mail gateway). The RSCS domain name is used to rewrite
the header fields of mail passing from RSCS network senders to TCP/IP network
recipients.
Chapter 20. Configuring the SMTP Server
365
SMTP Server
If TCP/IP network senders qualify an RSCS network recipient’s host name with a
domain name that matches either the RSCS domain name (defined using this
statement) or an alternate RSCS domain name (defined by the ALTRSCSDOMAIN
statement), SMTP accepts and attempts local delivery of the supplied mail, due to
use of the GATEWAY configuration statement and presence of SMTPRSCS
HOSTINFO data. If this delivery attempt fails, the mail is rejected due to an
unknown host condition.
If TCP/IP network senders do not qualify the network recipient’s host name with an
RSCS domain name, SMTP attempts to resolve the given host via DNS services. If
a resolved destination cannot be obtained, SMTP then attempts local delivery, as
described in the previous paragraph.
Note: SMTP considers the RSCS domain name BITNET to be a synonym for
NETNORTH, EARN, and EARNET.
RSCSDOMAIN RSCS_domain_name
Operands
RSCS_domain_name
A domain name, specified as a string of alphanumeric characters. For example,
BITNET, VNET, and vnet.ibm.com are all valid RSCS domain names. The default
RSCS domain name is a null string.
RSCSFORMAT Statement
The RSCSFORMAT statement specifies the spool file format for mail delivered to
recipients on the RSCS network. This statement is valid only in GATEWAY mode.
RSCSFORMAT NETDATA
RSCSFORMAT PUNCH
Operands
PUNCH
Indicates that records are folded up to 80 characters in length or fewer.
NETDATA
Indicates that records can be longer than 80 characters and arrive as
MESSAGE-type records. The default format is NETDATA.
SECURE Statement
The SECURE statement specifies SMTP operates as a secure mail gateway
between TCP/IP network sites and RSCS network sites. Mail is accepted by RSCS
only if the user ID and node ID are included in the SMTP SECTABLE file. See
“Configuring a TCP/IP-to-RSCS Secure Mail Gateway” on page 377 for more
information.
366
z/VM: TCP/IP Planning and Customization
SMTP Server
SECURE
Operands
The SECURE statement has no operands.
SMSGAUTHLIST Statement
The SMSGAUTHLIST statement identifies the local and RSCS users authorized to
issue privileged SMTP SMSG commands. Any VM user can issue the general
usage SMTP SMSG commands, but only those users specified in the
SMSGAUTHLIST statement can issue the privileged commands. Privileged SMTP
SMSG commands allow the shutting down or rebooting of SMTP, the enabling or
disabling of various SMTP trace/debug options, and the closing of SMTP’s console.
SMSGAUTHLIST user_id
ENDSMSGAUTHLIST
Operands
user_id
The address of a local user ID authorized to issue privileged SMTP SMSG
commands.
The user_id parameter can be repeated. The ENDSMSGAUTHLIST statement ends
the SMSGAUTHLIST statement.
For more information about the SMSG interface to SMTP, see the “Privileged User
SMSG Commands” on page 391.
SMTPCMDS Statement
The SMTPCMDS statement is used to define the characteristics of the SMTP
command user exit and to indicate whether or not the exit is to be enabled (turned
on) or disabled (turned off) when the server completes initialization. For information
on using the SMTP command exit, see the TCP/IP Programmer’s Reference.
Chapter 20. Configuring the SMTP Server
367
SMTP Server
SMTPCMDS EXIT
SMTPCMDX EXEC
exitname
EXEC
ON
Options
OFF
ENDSMTPCMDS
TEXT
Options:
FOR
ADD
DELETE
HELO
EHLO
MAIL
RCPT
DATA
EOD
VRFY
EXPN
RSET
PUNCH
ALL
Operands
exitname
The name of the exit routine associated with this command; the default exit
name is SMTPCMDX.
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC; this is the default.
TEXT
Indicates the exit routine name specified on this command is the name of a text
deck.
FOR
Precedes the exact list of commands for which the exit is being defined.
ADD
Precedes the list of commands that are to be added to this exit definition.
DELETE
Precedes the list of commands that are to be deleted from this exit definition.
HELO
Indicates the exit routine is to be turned on or off for the HELO command.
EHLO
Indicates the exit routine is to be turned on or off for the EHLO command.
MAIL
Indicates the exit routine is to be turned on or off for the MAIL FROM:
command.
RCPT
Indicates the exit routine is to be turned on or off for the RCPT TO: command.
DATA
Indicates the exit routine is to be turned on or off for the DATA command.
368
z/VM: TCP/IP Planning and Customization
SMTP Server
EOD
Indicates the exit routine is to be turned on or off when the “end of data”
condition is reached; that is, when a period (.) is received by the SMTP server
after a DATA command.
VRFY
Indicates the exit routine is to be turned on or off for the VRFY command.
EXPN
Indicates the exit routine is to be turned on or off for the EXPN command.
RSET
Indicates the exit routine is to be turned on or off for the RSET command.
PUNCH
Indicates the exit routine is to be turned on or off for PUNCH processing. If the
exit is enabled for this condition, it will be called when SMTP is ready to punch
local mail (mail on the same node or RSCS network) to its destination.
ALL
Indicates the exit routine is to be turned on or off for all SMTP commands for
which user exit capability is provided.
ON
Indicates the specified exit is being enabled (turned on) for a particular
command or set of commands.
OFF
Indicates the specified exit is being disabled (turned off) for a particular
command or set of commands.
Examples
v The following SMTP configuration file entry will enable the SMTP command exit
routine SMTPCMDX EXEC; exit processing will be performed for only the VRFY
and EXPN commands.
SmtpCmds
exit smtpcmdx exec for vrfy expn on
EndSmtpCmds
When this entry is processed, the following text is displayed during server
initialization:
SMTP Command Exit
- defined for
: SMTPCMDX EXEC ON
: VRFY EXPN
v This next entry defines the SMTP command exit routine MYEXIT TEXT for only
the HELO command, but disables its use once SMTP server initialization is
complete.
SmtpCmds
exit myexit text for helo off
EndSmtpCmds
When this entry is processed, the following text is displayed during server
initialization:
SMTP Command Exit
- defined for
: MYEXIT TEXT OFF
: HELO
Chapter 20. Configuring the SMTP Server
369
SMTP Server
SOURCEROUTES Statement
The SOURCEROUTES statement specifies whether the SMTP server will honor
source routes. Source routes may be present on the MAIL FROM: or RCPT TO:
commands processed by SMTP. With this statement, you may specify which source
routes are honored.
A source route is a path that contains a routing list of hosts and a destination
mailbox. The list of hosts is the route — information about how the mail is to arrive
at its final destination; the mail is passed from one host in this list to the next until it
is delivered to the intended recipient.
The specification that follows is an example of a source route:
<@HOST1,@HOST2,@HOST3:[email protected]>
The list of hosts is HOST1, HOST2 and HOST3, and the destination is
[email protected]
If this sample source route is included with a RCPT TO: command, and is honored
by SMTP, the mail will be sent to HOST1, then to HOST2, then to HOST3 and
finally to [email protected] When source routes are not honored, mail is sent directly
to [email protected]; the list of hosts is ignored.
If this sample source route is included with a MAIL FROM: command and source
routes are honored, SMTP will include its host name (for example, VMHOST1) in the
path information, and will supply the following path for its MAIL FROM: command:
<@HOST1,@HOST2,@HOST3,@VMHOST1:[email protected]>
If such source routes are not honored, the list of hosts is removed from the mail
routing path. In addition, SMTP will not add its host name to the path information.
SOURCEROUTES YES
SOURCEROUTES
RCPTTO
MAILFROM
BOTH
NO
Operands
YES
Indicates that source routes on the MAIL FROM: and RCPT TO: commands
received from clients will be honored when mail is forwarded by SMTP. For the
previous sample source route, SMTP will send the mail to HOST1 for further
processing by HOST1. This is the default.
NO
Indicates that source routing is not to be honored. By default, only source
routes for the RCPT TO: command will be ignored. The RCPTTO, MAILFROM
or BOTH parameter can be specified with this parameter to select specific
source routes to be ignored by SMTP.
Note: The NO parameter does not cause mail containing source routes to be
rejected.
370
z/VM: TCP/IP Planning and Customization
SMTP Server
RCPTTO
Indicates that source routing is not to be honored for the RCPT TO: command.
This is the default when NO is in effect. For the RCPT TO: command, any host
list will be ignored and only the destination host will be used. The mail
recipient(s) will not see the host list that was ignored.
For the previous sample source route, SMTP will send the mail directly to
[email protected]; the HOST1, HOST2 and HOST3 hosts will be ignored.
MAILFROM
Indicates that source routing is not to be honored for the MAIL FROM:
command. When this parameter is used, the list of hosts will be removed from
the mail routing path. In addition, SMTP will not add its host name to the path
information. The mail recipient(s) will not see the host list that was ignored.
For the previous sample source route, SMTP will supply the following MAIL
FROM: command when mail is forwarded:
MAIL FROM: <[email protected]>
BOTH
Indicates that source routing is not to be honored for either of the RCPT TO: or
the MAIL FROM: commands. Source routing information for these commands
will be ignored as previously described.
SUPRESSNOTIFICATION Statement
The SUPRESSNOTIFICATION statement specifies that SMTP should not send a
notification to the mail sender when mail delivery is successful. A notification will still
be sent to the mail sender if mail delivery is unsuccessful.
SUPRESSNOTIFICATION
Operands
The SUPRESSNOTIFICATION statement has no operands.
TEMPERRORRETRIES Statement
The TEMPERRORRETRIES statement specifies the number of times SMTP tries to
redeliver mail to a host with a temporary problem. Temporary problems include
network congestion, network connectivity, or a broken remote mail server.
TEMPERRORRETRIES 0
TEMPERRORRETRIES retries
Operands
retries
The number of times mail delivery to a host with a temporary problem is retried.
The default is 0, meaning that mail delivery is retried for the amount of time
specified in the RETRYAGE statement. If retries is greater than 0, mail delivery
is retried for that number of times. If delivery is still unsuccessful, the mail is
Chapter 20. Configuring the SMTP Server
371
SMTP Server
returned to the sender. Change the default only when remote mail servers
repeatedly terminate abnormally or hang SMTP mail transactions.
TRACE Statement
The TRACE statement specifies which type of tracing should be enabled during
server initialization.
TRACE
ALL
CODEFLOW
CONN
DEBUG
NOTICE
RESOLVER
SPL
Operands
ALL
Initiates tracing of all types.
CODEFLOW
Initiates tracing of SMTP code flow.
CONN
Initiates tracing of connection activity.
DEBUG
Initiates tracing of all commands and replies, and their associated connection
number (this same information was previously captured using the DEBUG
configuration option provided with prior releases).
NOTICE
Initiates tracing of all TCP/IP notification events that are received by the SMTP
virtual machine.
RESOLVER
Initiates resolver tracing. The same information can be produced by adding the
TRACE RESOLVER statement to the TCPIP DATA file that is read by the
SMTP server virtual machine at initialization.
SPL
Initiates tracing of *SPL IUCV execution.
VERIFYCLIENT Statement
The VERIFYCLIENT statement is used to indicate to the SMTP server whether or
not client verification is to be performed. Client verification can be performed using
the built-in client verification function (VERIFYCLIENT YES) or using a user exit
(VERIFYCLIENT EXIT). For information on using the client verification exit, see the
TCP/IP Programmer’s Reference.
372
z/VM: TCP/IP Planning and Customization
SMTP Server
VERIFYCLIENT NO ENDVERIFYCLIENT
VERIFYCLIENT
YES
EXIT
SMTPVERX EXEC
exitname
EXEC
ON
ENDVERIFYCLIENT
OFF
TEXT
Operands
NO
Indicates that no client verification is to be performed; this is the default.
YES
Indicates verification of the client name specified on the HELO or EHLO
command is to be performed using the built-in client verification function.
EXIT
Indicates a client verification exit routine is being defined.
exitname
Indicates the name of the exit routine associated with this command; the default
exit name is SMTPVERX.
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC; this is the default.
TEXT
Indicates the exit routine name specified on this command is the name of the
text deck.
ON
Indicates the specified exit (being defined with this command) is to be enabled
(on).
OFF
Indicates the specified exit (being defined with this command) is to be disabled
(off).
Examples
v The following configuration file entry will enable the client verification exit routine
SMTPVERX EXEC; this exit will perform all verification.
VerifyClient
exit smtpverx exec on
EndVerifyClient
When this entry is processed, the following text is displayed during server
initialization:
Client Verification
: Exit SMTPVERX EXEC ON
v This next entry defines the client verification exit routine SMTPVERX TEXT, but
disables its use once SMTP server initialization is complete. Thus, client
verification will not occur.
VerifyClient
exit smtpverx text off
EndVerifyClient
Chapter 20. Configuring the SMTP Server
373
SMTP Server
When this entry is processed, the following text is displayed during server
initialization:
Client Verification
: No (Exit SMTPVERX TEXT OFF)
VERIFYCLIENTDELAY Statement
The VERIFYCLIENTDELAY statement specifies the amount of time (in seconds)
that SMTP will wait for the domain name system to respond during client
verification. The default is 10 seconds.
If the client cannot be verified within the timeout, the mail item will be treated as if
verification were not active. No comment is inserted into the mail header.
VERIFYCLIENTDELAY 10
VERIFYCLIENTDELAY seconds
Operands
seconds
The number of seconds SMTP will wait for the domain name system to respond
during client verification. The range is 0 through 86,400 seconds (24 hours).
The default is 10 seconds.
WARNINGAGE Statement
The WARNINGAGE statement specifies the amount of time after which a copy of
the mail is returned to the sender. The copy of the mail includes a header from
SMTP that indicates the mail has been undeliverable for WARNINGAGE amount of
time and that SMTP will continue to retry delivery of the mail for RETRYAGE
amount of time.
WARNINGAGE 1 D
WARNINGAGE duration
D
H
M
Operands
duration
The amount of time (specified in days, hours, or minutes) over which SMTP is
to attempt delivery of a piece of mail before sending a non-delivery warning to
the sender. If duration is specified in days, the range is 0 through 365; when it
is given in hours, the range is 0 through 8760 (365 days). When duration is
specified in minutes, the range is 0 through 525600 (365 days). The default is 1
day.
374
D
Indicates that duration is specified in days. This is the default.
H
Indicates that duration is specified in hours.
z/VM: TCP/IP Planning and Customization
SMTP Server
M Indicates that duration is specified in minutes.
When the RETRYAGE and the WARNINGAGE are equal, a warning is not issued to
the sender. The warning is only issued if the WARNINGAGE is less than the
RETRYAGE.
8BITMIME Statement
The 8BITMIME statement specifies the file name of the translation table to be used
for 8-bit MIME support; the file type of this file must be TCPXLBIN. The translation
table specified on this statement will be used only for 8-bit MIME support. Thus, if
this statement is not specified, 8-bit MIME will not be supported.
8BITMIME filename
Operands
filename
The file name of the translation table to be used for 8-bit MIME support.
See Chapter 30, “Using Translation Tables” on page 623 for more information.
Note: Changing the 8-bit MIME translation table could affect mail for which delivery
is pending. When SMTP is restarted, notes that require 8-bit MIME support
and are destined for non-RSCS network recipients will be processed using
the new translation table.
Step 7: Advanced Configuration Considerations
Before you complete the SMTP servers configuration process, you may want to
review the information in the following sections, in addition to the server exit
information that follows:
v “Configuring a TCP/IP-to-RSCS Mail Gateway” on page 376
v “Configuring a TCP/IP-to-RSCS Secure Mail Gateway” on page 377
v “Defining Nicknames and Mailing Lists” on page 380
v “Customizing SMTP Mail Headers” on page 381
SMTP Server Exits
Several SMTP server exits are supported that allow for greater control over each
piece of mail that is processed by the SMTP server. These exits are:
v the client verification exit, which might be used to reject mail from a particular
host, designate certain trusted cites as “verified” but perform validation on all
others, or control which users can use a particular SMTP server.
v the mail forwarding exit, which could be used to disallow forwarding of mail from
a known sender of “junk” mail, intercept mail from specific clients and forward
that mail to a local VM user ID for further analysis, or restrict the ability to
forward mail to a particular set of hosts.
v the SMTP command exit, which allows control over specific SMTP commands.
This exit might be used to reject particular SMTP commands, handle the delivery
of local mail in a specific manner, or screen and reject mail based on content.
Chapter 20. Configuring the SMTP Server
375
SMTP Server
Prior to customizing any of these server exits, ensure that you have reviewed the
exit limitations and customization recommendations presented in “Customizing
Server-specific Exits” on page 43.
|
|
|
For more information on how to effectively use the exit routines mentioned above,
see z/VM: TCP/IP Level 430 Programmer’s Reference, SC24-6021.
Configuring a TCP/IP-to-RSCS Mail Gateway
You can configure the SMTP virtual machine with the GATEWAY option to run as a
mail gateway between TCP/IP network users and users located on an RSCS
network attached to the local host. Figure 9 shows the SMTP virtual machine
configured as a mail gateway.
B
RSCS
A
C
D
TCP/IP Network
RSCS
E
Figure 9. The SMTP Virtual Machine Configured as a Mail Gateway
Host
Description
A
The local VM host, running both TCP/IP and RSCS.
B and C
The hosts attached to host A through an RSCS network.
D and E
The hosts attached to host A through a TCP/IP network.
Users on hosts A, B, and C can send mail or files to users on TCP/IP hosts D and
E using the CMS NOTE or SENDFILE commands, or using OfficeVision/VM™. For
more information, see the TCP/IP User’s Guide. The following steps describe how
to configure a TCP/IP-to-RSCS mail gateway.
1. Update the SMTP configuration file to include the GATEWAY, RSCSDOMAIN,
and RSCSFORMAT statements. Specify the GATEWAY, RSCSDOMAIN, and
RSCSFORMAT options in the configuration file.
2. Enter the SMTPRSCS command, using the following format:
SMTPRSCS filename filetype filemode
Operands
filename filetype filemode
The file identifier of the RSCS configuration file, for example, RSCS CONFIG A.
The command requires a file name, file type and file mode.
This command creates the RSCS host table file, SMTPRSCS HOSTINFO. After the
file is created, copy it to an SMTP server visible minidisk, such as TCPMAINT 198.
376
z/VM: TCP/IP Planning and Customization
SMTP Server
Note: If the local system’s RSCS configuration file does not explicitly specify all of
your RSCS network’s nodes (for example, if it uses a default ROUTE *
statement), you should either obtain the RSCS configuration file that does
contain all of the RSCS network nodes and use that file as the SMTPRSCS
command input, or create a local RSCS configuration file with ROUTE
statements that do identify all of your RSCS network’s nodes and use that as
input to the SMTPRSCS command.
In order for an SMTP to RSCS gateway to work correctly, the SMTPRSCS
HOSTINFO file must contain all RSCS nodes that SMTP mail could be
destined for.
Perform the following on each RSCS node that sends mail through the SMTP
virtual machine on a remote gateway node.
1. For each system running z/VM 4.3.0 or higher, place a TCPIP DATA file on each
non-gateway VM system, on visible file space (for example the 190 disk). This
DATA file must contain a SMTPSERVERID statement that identifies the user ID
and RSCS node of your SMTP gateway. Copy the SMTPQUEU EXEC to each
system on user visible file space as well.
2. For each non-gateway system running VM at a level prior to z/VM 4.3.0, if you
have a previously defined SMTP mail gateway, and you installed the necessary
files on the non-gateway VM systems, then no action is necessary on those
systems.
If you never installed the TCP/IP specific NOTE and SENDFILE functions on the
non-gateway VM systems, then you need to do the following:
a. Download the Mail Gateway package, MAILGATE VMARC. The URL
www.ibm.com/s390/vm/related/tcpip (the VM TCP/IP home page) provides
access to this package and instructions on how to extract files from the
VMARC archive. Once the individual files are extracted, use the instructions
to install and configure the gateway code (in the MAILGATE README file).
The code you install is part of VM TCP/IP 2.4.0 (the NOTE and SENDFILE
functions).
b. Copy the SMTPQUEU EXEC to each VM system.
c. Copy the gateway’s SMTPRSCS HOSTINFO file to each system. See the
SMTPRSCS command above (step 2 on page 376) for details on creating
this file.
Configuring a TCP/IP-to-RSCS Secure Mail Gateway
The SMTP virtual machine can be configured with the SECURE statement to run as
a secure mail gateway between TCP/IP network users and users located on an
RSCS network attached to the local host. For information about how to set up a
mail gateway, see “Configuring a TCP/IP-to-RSCS Mail Gateway” on page 376.
To enable the SMTP Secure Gateway mode, you must add the SECURE statement
to the SMTP CONFIG file. When operating in Secure Gateway mode, only those
RSCS addresses in the SMTP Security Table are authorized to send or receive
mail. In addition, source routing is disabled to prevent the gateway from relaying
mail to unauthorized users.
SMTP rejects mail to or from an unauthorized RSCS user. If the mail is from the
TCP/IP network, SMTP rejects the RCPT TO: command with the error 550 User is
not a registered gateway user. If the mail is from the RSCS network, SMTP
rejects the MAIL FROM: command with the error 550 User is not a registered
Chapter 20. Configuring the SMTP Server
377
SMTP Server
gateway user, and includes the file SECURITY MEMO as an explanation. For more
information, see the examples of rejected mail and the sample SECURITY MEMO
file on page 379.
Creating an SMTP Security Table
Create a file called SMTP SECTABLE that contains a list of RSCS users who are
authorized to use the gateway. This file can have either fixed or variable length
records of up to 255 characters in length. Records whose first non-blank character
is an asterisk (*) are treated as comments and are ignored. The following example
shows the format of the security table.
RSCS_user_id RSCS_node_id
nickname primary_nick? primary_mbox?
Operands
RSCS_user_id
The RSCS user ID of the authorized user.
RSCS_node_id
The RSCS node ID of the authorized user.
nickname
The name by which the RSCS user is known on the TCP/IP side of the
gateway.
primary_nick?
A primary nickname indicator, specified as Y or N. If Y, then mail addressed to
[email protected] is automatically forwarded to RSCS_user_id at
RSCS_node_id. Each nickname can only have one primary_nick record set to
Y.
primary_mbox?
A primary mailbox indicator, Y or N. If Y, then mail from RSCS_user_id at
RSCS_node_id is converted to [email protected] before it is sent to the
TCP/IP recipient. Each RSCS_user_id, RSCS_node_id pair can have only one
primary_mbox? record.
A sample security table file is supplied on the TCPMAINT 591 disk as SMTPSECT
SAMPTABL. Your customized table should be stored on the TCPMAINT 198 disk as
file SMTP SECTABLE.
The following is an example of an SMTP SECTABLE security table.
* Records for Jane Doe, within IBM
JDOE
ALMADEN
JDOE
AUSTIN
* Records for John Smith, within IBM
SMITH RALEIGH
JOHNNY Y N
SMITH YORKTOWN JOHNNY N Y
SMITH DALLAS
JOHNNY N N
SMITH RALEIGH
JSMITH Y Y
For example, mail sent from the following RSCS network addresses through the
SMTP gateway is rewritten to the following TCP/IP network addresses. Assume the
host name of the gateway is SMTP-GATEWAY.IBM.COM.
378
z/VM: TCP/IP Planning and Customization
SMTP Server
RSCS Address
TCP/IP Address
------------------------------------------------------------------------JDOE
JDOE
SMITH
SMITH
SMITH
at
at
at
at
at
ALMADEN
AUSTIN
RALEIGH
YORKTOWN
DALLAS
JDOE%[email protected]
JDOE%[email protected]
[email protected]
[email protected]
JOHNNY%[email protected]
Mail sent from the TCP/IP network to the following TCP/IP network addresses, is
forwarded to the following RSCS network addresses. Assume the host name of the
gateway is smtp-gateway.ibm.com.
TCP/IP Address
RSCS Address
------------------------------------------------------------------------JDOE%[email protected]
JDOE%[email protected]
[email protected]
[email protected]
MITH%[email protected]
JDOE
JDOE
SMITH
SMITH
SMITH
at
at
at
at
at
ALMADEN
AUSTIN
RALEIGH
RALEIGH
DALLAS
A sample security memo file is supplied on the TCPMAINT 591 disk as
SMTPMEMO SAMPLE. Your customized memo should be stored on the
TCPMAINT 198 disk as file SECURITY MEMO. The supplied sample memo file
contains the following text:
The mail you sent to this SMTP gateway cannot be delivered because
you are not a registered user of this gateway. Contact your local
administrator for instructions on how to be authorized to use this
SMTP gateway.
The following is an example of rejected mail that was sent to an unregistered RSCS
user.
Date: Fri, 9 Oct 92 10:55:59 EST
From: [email protected]
To: [email protected]
Subject: Undeliverable Mail
VM1.ACME.COM unable to deliver following mail to recipient(s):
<[email protected]>
VM1.ACME.COM received negative reply from host:
SMTP-GATEWAY
550 User ’[email protected]’ is not a registered gateway user
** Text of Mail follows **
Date: Fri, 9 Oct 92 10:55:56 EDT
From: <[email protected]>
To:
<[email protected]>
Subject: Lunch
Matt,
Do you have time to meet for lunch next week?
shipment of ACME iron birdseed.
I want to discuss the
Daniel
The following is an example of rejected mail that was sent from an unregistered
RSCS user.
Date: Fri, 9 Oct 92 11:35:18 EST
From: <[email protected]>
To: <[email protected]>
Subject: Undeliverable Mail
Chapter 20. Configuring the SMTP Server
379
SMTP Server
Unable to deliver mail to some/all recipients.
550 MAIL FROM:<[email protected]>
550-User ’[email protected]’ is not a registered gateway user.
550550-The mail you sent to this SMTP gateway cannot be delivered because
550-you are not a registered user of this gateway. Contact your local
550-administrator for instructions on how to be authorized to use this
550-SMTP gateway.
** Text of Mail follows **
HELO SMTP-GATEWAY.IBM.COM
MAIL FROM:<[email protected]>
RCPT TO:<[email protected]>
DATA
Date: Fri, 9 Oct 92 11:34:17 EST
From: <[email protected]>
To:
<[email protected]>
Subject: Awaiting your message
Daniel,
When are you going to contact me about the iron birdseed and giant
electromagnet that I ordered? I would like to meet with you soon.
Matt
·
QUIT
Defining Nicknames and Mailing Lists
You can use the SMTP NAMES file to set up mail aliases, forwarding, and
distribution lists. The following example illustrates the use of the SMTP NAMES file.
v Mail Aliases
The entry:
:nick.brat :userid.BART
in the SMTP NAMES file on a TCP/IP host ourvm.our.edu causes all mail
addressed to [email protected] to be delivered to user ID BART on that host.
brat becomes a mail alias for BART.
v Mail Forwarding
The entry:
:nick.homer :userid.HOMER :node.NEWVM
in the SMTP NAMES file on TCP/IP host ourvm.our.edu (also known as OURVM
on an RSCS network), causes all mail addressed to [email protected] to be
forwarded to HOMER at NEWVM on the RSCS network.
v Mail Distribution Lists
The entry:
:nick.princes
:list.hal charles hamlet charming
andrew at buc.acme.com albert at win.ibm.com
in the SMTP NAMES file on TCP/IP host ourvm.our.edu causes all mail
addressed to [email protected] to be sent to each recipient in the
distribution list. Entries in the list can be addresses of recipients, or nicknames
(defined in SMTP NAMES) of recipients.
380
z/VM: TCP/IP Planning and Customization
SMTP Server
Note: The nickname label may not be the same as any of the user IDs that are in
the list defined by that nickname. Ensure that the nickname label is not used
as one of the list entries.
Customizing SMTP Mail Headers
Electronic mail has a standardized syntax for text messages that are sent across
networks. The standard syntax is described in RFC 822. Messages have an
envelope and content. Fields in the envelope are in a rigid format and referred to as
headers. Envelopes contain all necessary information to accomplish transmission
and delivery of the message content.
The RFC 822 standard does not dictate the internal formats used at specific sites.
IBM TCP/IP Level 430 allows specific sites to customize the SMTP mail headers
with the REWRITE822HEADER statement.
You can use the REWRITE822HEADER statement to control the way SMTP
performs a rewrite of the RFC 822 mail headers. Mail headers are passed from the
local system or RSCS network to the TCP/IP network. Mail headers passing from
the TCP/IP network to the local system or RSCS network are not affected. Mail
envelope headers are also not affected. Only the addresses under certain RFC 822
header fields can be subject to the header rewriting rules.
The header fields affected by the REWRITE822HEADER statement are:
Fields
Description
From
The originator of the message.
Resent-From
The person that forwarded the message.
Reply-To
Provides a mechanism for indicating any mailboxes
to which responses are to be sent.
Resent-Reply-To
The person to whom you should forward the reply.
Return-Path
Contains definitive information about the address
and route back to the originator of the message.
This field is added by the mail transport service at
the time of final delivery.
Sender
The authenticated identity of the AGENT that sent
the message. An AGENT can be a person, system,
or process.
Resent-Sender
The authenticated identity of the AGENT that has
resent the message.
To
Contains the identity of the primary recipient of the
message.
Cc
Contains the identity of the secondary
(informational) recipients of the message.
Bcc
Contains the identity of additional recipients of the
message. The content of this field is not included in
copies sent to the primary and secondary recipients
of the message but included in the originator’s
copy.
Chapter 20. Configuring the SMTP Server
381
SMTP Server
The SMTP RULES File
The SMTP RULES file contains the rewrite rules for the header addresses. You can
create the SMTP RULES file during the configuration of the SMTP server to
customize the address transformations to the needs of a particular site. Store the
SMTP RULES file on TCPMAINT 198.
The SMTP RULES file consists of the following two sections:
FIELD DEFINITION
Contains the names of all header fields whose addresses are to be
rewritten.
RULES DEFINITION
Contains the rewrite rules for the header fields.
In creating the SMTP RULES file, you must follow several syntactical conventions.
The conventions are:
v The file statements are free-format. Tokens can be separated by an arbitrary
number of spaces, and statements can span an arbitrary number of lines.
However, you must terminate every statement with a semicolon (;).
v A character string appearing within single quotes ('...') is case-insensitive. For
example, 'abc' represents 'abc', 'Abc', 'ABC', and so on. The use of character
strings is illustrated in the following sections.
v A character string appearing within double-quotes ("...") is case sensitive. For
example, "abc" only represents "abc". It does not represent "Abc", "ABC", and so
forth.
Special characters, such as @ and %, are treated the same whether enclosed by
single quotes or double-quotes.
v Double-hyphens ("--") are used to begin a comment. The comment extends to
the end of the line.
The following sections describe the components of the SMTP RULES file.
Format of the Field Definition Section
The field definition section is the first section in any SMTP RULES file. It defines
any applicable alias fields, and it is introduced by the following heading:
Field Definition Section
This section allows similar fields to be grouped under an alias or common name.
This name, or alias, is used to represent the field list. You can define an arbitrary
number of aliases representing a set of field lists.
An alias name can be any alphanumeric sequence of characters that is not a
predefined keyword within the SMTP rules (see below). However, the alias name
DefaultFields is treated specially by the SMTP configuration interpreter. If
DefaultFields is defined, and if a rule is written that does not specify an associated
field alias, the rules interpreter assumes that DefaultFields is the associated field
alias.
The alias definition within this section is of the following form:
alias_name = alias_definition; optional comment
where alias_name is the name of the alias and alias_definition is an expression
describing which fields are to be grouped under this alias. This expression can be
as simple as a single field name. For example:
382
z/VM: TCP/IP Planning and Customization
SMTP Server
MyAlias = ’To’;
The aliases can be a list or set of field names. The field names ’To’ ’From’ ’Cc’
’Bcc’, in the following example, are part of a set of field names referenced by the
alias MyAlias.
MyAlias = ’To’ ’From’ ’Cc’ ’Bcc’ ; -- first list of fields
You can combine field names and previously defined aliases to create a new alias.
In the following example, the set of field names defined as MyAlias and the field
names in the new alias YourAlias are combined to form a third set. The new alias
TheirAlias is the union of both aliases and contain the fields of MyAlias and
YourAlias.
MyAlias
= ’To’ ’From’ ’Cc’ ’Bcc’;
YourAlias = ’Errors-To’ ’Warnings-To’;
TheirAlias = MyAlias YourAlias;
In the previous example, TheirAlias is an alias that represents the following fields.
TheirAlias: ’To’ ’From’ ’Cc’ ’Bcc’ ’Errors-To’ ’Warnings-To’
You can perform the following set algebra operations on set members of the alias to
create a subset of the initial alias.
v Union operations
v Difference operations
v Intersection operations.
Union and Difference Operations: You can add or omit certain field names to a
new alias of field names by using a minus sign to omit set members and an
optional plus sign to include another field name. In the mathematics of sets, when
you add together two or more sets, they form a union. When set members are
omitted, the remaining set is created by the difference operation. In the following
example HerAlias and HisAlias are defined. The alias HisAlias is created from the
union of TheirAlias, HerAlias, and the omission of Warning-To and Bcc from the
following sets.
HerAlias
HisAlias
= ’Reply-To’ ’Sender’;
= TheirAlias - ’Warnings-To’ - ’Bcc’ + HerAlias;
In the previous example, HisAlias is an alias that represents following fields.
HisAlias: ’To’ ’From’ ’Cc’ ’Errors-To’ ’Reply-To’ ’Sender’
Intersection Operations: In addition to the union and difference operations
previously shown, a field definition can include an intersection operation. When the
intersection operation is applied to two field expressions, the resulting set contains
the fields common to both. In the following example, MyAlias and YourAlias are
defined. The alias OurAlias is created from the intersection of MyAlias and
YourAlias. The asterisk (*) is the intersection operator.
MyAlias
= ’Bcc’ ’Cc’ ’From’ ’Reply-To’;
YourAlias = ’Resent-From’ ’Cc’ ’Sender’ ’To’ ’Bcc’;
OurAlias
= MyAlias * YourAlias; -- the intersection
In the previous example, OurAlias represents the following fields.
OurAlias: ’Bcc’ ’Cc’
In the following complex example, TheirAlias is created from the intersection of
YourAlias with the sum of MyAlias plus Resent-From.
TheirAlias = (MyAlias + ’Resent-From’) * YourAlias;
Chapter 20. Configuring the SMTP Server
383
SMTP Server
In the previous example, TheirAlias represents the following fields.
TheirAlias: ’Bcc’ ’Cc’ ’Resent-From’
The parentheses within the definition of TheirAlias perform the same functions as
in algebra. Field expressions are evaluated from left to right, but the intersection
operation has greater priority than union and difference operations. If parentheses
were not used in the definition of TheirAlias, the result would be:
TheirAlias: ’Bcc’ ’Cc’ ’From’ ’Reply-To’ ’Resent-From’
Format of the Rule Definition Section
The rule definition section is the next section in any SMTP RULES file. It contains
the header rewriting rules that define the intended address transformations, and it is
introduced by the following heading.
Rule Definition Section
The rewrite rules are given using a simple, free-format pattern matching language.
The basic form of each rule is:
alias :before-address-pattern => after-address-pattern;
The alias name alias is an optional name representing the fields for which the rule
is applicable. If the alias name alias: is omitted from this part of the rules, then
DefaultFields is assumed.
The sequence of tokens that define how a particular type of address is to be
recognized is the before-address-pattern portion of the rules definition. The
sequence of tokens that define how the address is to appear after the address has
been rewritten is the after-address-pattern portion of the rules definition. The
following example is the rule for converting host names.
A ’@’ RSCSHostName => A ’@’ TCPHostName; -- convert host names
In the previous example, A ’@’ RSCSHostName is the before-address-pattern portion
of this rule, and A ’@’ TCPHostName is the after-address-pattern portion. This rule
specifies that the address to be rewritten has an arbitrary local name (A), an at-sign,
and the RSCS host name (RSCSHostName) of the current site. The rule also specifies
that the rewritten address must contain the same arbitrary local name (A), an
at-sign, and the current site’s TCP host name TCPHostName.
Syntax Convention of the SMTP Rules
The previous example of the rewriting rules shows that you must follow several
syntactical conventions. The conventions are:
v Some keywords have special meaning to the rules interpreter. For example,
RSCSHostName keyword means the RSCS host name of the present system, and
TCPHostName keyword means the TCP host name of the present system. For
more information about valid keywords, see “Predefined Keywords within the
SMTP Rules” on page 386. Some keywords, such as TCPHostName, have single
values. Other keywords, such as AltTCPHostName and AnyDomainName, can have
many possible values. To avoid ambiguity, any keyword that can have multiple
values, and is used in the after-address-pattern of a given rule, must appear
exactly once within the before-address-pattern of that rule. The following rule
example shows a valid syntax:
A ’@’ AltTCPHostName ’.’ AltTCPHostName =>
A ’%’ TCPHostName ’@’ TCPHostName;
384
z/VM: TCP/IP Planning and Customization
SMTP Server
The following two rules have invalid syntax because the first keyword
AltTCPHostName must be rewritten to a keyword with specific values. The
AltTCPHostName is attempting to be rewritten to the same AltTCPHostName but
with unknown values and becomes invalid.
A ’@’ AltTCPHostName ’.’ AltTCPHostName =>
A ’%’ AltTCPHostName ’@’ TCPHostName;
A ’@’ TCPHostName => A ’@’ AltTCPHostName;
Any rule whose before-address-pattern includes a keyword that has a null value
is ignored during the header rewriting. Thus, if there is no AltRSCSDomain defined
in the system configuration file, no rule that includes AltRSCSDomain in the
before-address-pattern is considered during the header rewriting.
v Alphanumeric identifiers that are not within apostrophes or double-quotes, and
that are not predefined keywords, are considered wildcards in the rule statement.
Wildcards represent an arbitrary (non-null) sequence of characters. The identifier
A, in the previous rule example, is a wildcard. Thus, if host were the RSCS host
name for the current site, and if tcphost were the TCP host name for the current
site, the previous rule example recognizes [email protected] and [email protected] as candidates
for address rewriting, and rewrites them as [email protected] and [email protected]
respectively. To avoid ambiguity, no two wildcards are allowed in a row, and the
same wildcard cannot be used more than once, within the before-address-pattern
of a given rule. The following rules have valid syntax:
A ’@’ B TCPHostName
=> A ’%’ B ’@’ TCPHostName;
A ’%’ B ’@’ RSCSHostName => A B ’@’ TCPHostName;
The following rules have invalid syntax because the first rule has two wildcards in
a row A and B. The second rule has the same wildcard A repeated:
A B ’@’ TCPHostName
=> A A ’%’ B ’@’ TCPHostName;
A ’%’ A ’@’ RSCSHostName => A ’@’ TCPHostName;
v A character string appearing within apostrophes or double-quotes tells the rules
interpreter where a particular string is to appear within a header address. In the
previous rule example, the ’@’ string in the before-address-pattern tells the rules
interpreter that an at-sign must appear between the arbitrary character string and
the RSCS host name. The ’@’ string in the after-address-pattern tells the rules
interpreter that the address must be rewritten so an at-sign appears between the
arbitrary string and the TCP host name. As previously mentioned, apostrophes
denote case-insensitive strings, and double-quotes denote case-sensitive strings.
v The character sequence "=>", with no spaces between the characters separates
the before-address-pattern from the after-address-pattern.
v The order in which the rules are specified is important; the first rule encountered
whose before-address-pattern matches the current address is the rule to dictate
the address transformation. Once a matching rule has been found for an
address, no other rule is considered.
In addition to the rules themselves, there is the capability for some simple logic to
decide at system configuration time which rules within the file should become
active. These conditions are specified in the form of an IF-THEN-ELSE statement
as shown in the following example.
IF cond THEN
statement list
ELSE
statement list
ENDIF
Chapter 20. Configuring the SMTP Server
385
SMTP Server
A statement list can consist of any number of rules or nested IF statements, or
both. Each IF statement, regardless of whether it is nested, must be terminated by
an ENDIF keyword. As with IF statements in other languages, the ELSE clause is
optional. There are only two conditions recognized by an IF statement:
v IF predefined keyword = ’character string’ THEN
v IF predefined keyword CONTAINS ’character string’ THEN ... ENDIF
The conditional operators = and CONTAINS can be prefixed by the word NOT to
invert the conditions.
The predefined keyword must be a keyword that resolves to a single value at
system configuration time. The character string in the first condition can be null. A
character string cannot span more than one line.
The following is an example of the use of IF statements.
IF RSCSDomain = ’’ THEN
A ’@’ AnyRSCSHostName => A ’%’ AnyRSCSHostName ’@’ TCPHostName;
ELSE
A ’@’ RSCSHostName ’.’ RSCSDomain
=> A ’@’ TCPHostName;
A ’@’ RSCSHostName ’.’ AltRSCSDomain => A ’@’ TCPHostName;
IF RSCSDomain CONTAINS ’.’ THEN
A ’@’ AnyRSCSHostName
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
ELSE
A ’@’ AnyRSCSHostName
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
ENDIF
ENDIF
Predefined Keywords within the SMTP Rules
You can use the following predefined keywords to define the header rewriting rules.
386
Keyword
Definition
TCPHostName
Matches the TCP host name of the system as
defined by the concatenation of the HOSTNAME
and DOMAINORIGIN statements in the TCPIP
DATA file.
TCPHostNameDomain
Matches the domain portion of the TCP host name
of the system as defined by the DOMAINORIGIN
statement in the TCPIP DATA file. For example, if
the TCP host name was vm1.acme.com, the value of
TCPHostNameDomain is acme.com.
ShortTCPHostName
Matches the first portion of the TCP host name of
the system, as defined by the HOSTNAME
statement in the TCPIP DATA file. For example, if
the TCP host name was vm1.acme.com, the value of
ShortTCPHostName is vm1.
AltTCPHostName
Matches any alternative TCP host name of the
z/VM: TCP/IP Planning and Customization
SMTP Server
system, as defined by ALTTCPHOSTNAME
statements in the SMTP CONFIG file
RSCSHostName
Matches the RSCS host name of the system from
the CMS IDENTIFY command. NJEHostName is a
synonym for RSCSHostName.
AnyRSCSHostName
Matches any (unqualified) RSCS host name defined
in the SMTPRSCS HOSTINFO file.
AnyNJEHostName is a synonym for
AnyRSCSHostName.
RSCSDomain
Matches the domain name of the RSCS network as
defined by the RSCSDOMAIN statement in the
SMTP CONFIG file. NJEDomain is a synonym for
RSCSDomain.
AltRSCSDomain
Matches the alternative domain name of the RSCS
network as defined by the ALTRSCSDOMAIN
statement in the SMTP CONFIG file. AltNJEDomain
is a synonym for AltRSCSDomain.
AnyDomainName
Matches any fully qualified domain name. Any host
name with a period (.) is considered to be a fully
qualified domain name.
SecureNickAddr
Matches an address of the form
[email protected]_node_id, where
RSCS_user_id, and RSCS_node_id are defined
with a nickname in the SMTP SECTABLE file.
Note: This matches only user and node IDs that
are defined with nicknames.
When SecureNickAddr is specified in the
before-address-pattern of a rule, SMTP
automatically associates the keyword
SecureNickName with the corresponding nickname.
This allows SecureNickName to be specified in the
after-address-pattern.
SecureNickName
Matches a nickname defined in the SMTP
SECTABLE file. When SecureNickName is
specified in the before-address-pattern of a rule,
SMTP automatically associates the keyword
SecureNickAddr with the corresponding
[email protected]_node_id. This allows
SecureNickAddr to be specified in the
after-address-pattern.
The predefined keywords defined previously can consist of any combination of
uppercase and lowercase characters; the rules interpreter does not distinguish
between them.
The secure keywords are only valid when SMTP is configured to be a secure
gateway.
Chapter 20. Configuring the SMTP Server
387
SMTP Server
Default SMTP Rules
If the SMTP RULES file does not exist, SMTP uses a default set of rules. The
default set used depends on whether SMTP is configured as a secure gateway.
SMTP Non-Secure Gateway Configuration Defaults
If SMTP is not configured as a secure gateway, SMTP uses the following default:
Field Definition Section
DefaultFields = ’Bcc’ ’Cc’ ’From’ ’Reply-To’ ’Resent-From’
’Resent-Reply-To’ ’Resent-Sender’ ’Return-Path’
’Sender’ ’To’;
Rule Definition Section
A ’@’ RSCSHostName => A ’@’ TCPHostName;
IF RSCSDomain = ’’ THEN
A ’@’ AnyRSCSHostName => A ’%’ AnyRSCSHostName ’@’ TCPHostName;
ELSE
A ’@’ RSCSHostName ’.’ RSCSDomain
=> A ’@’ TCPHostName;
A ’@’ RSCSHostName ’.’ AltRSCSDomain => A ’@’ TCPHostName;
IF RSCSDomain CONTAINS ’.’ THEN
A ’@’ AnyRSCSHostName
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
ELSE
A ’@’ AnyRSCSHostName
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
ENDIF
ENDIF
A
A
A
A
A
’@’
’@’
’@’
’@’
’@’
TCPHostName
ShortTCPHostName
AltTCPHostName
AnyDomainName
B
=>
=>
=>
=>
=>
A
A
A
A
A
’@’
’@’
’@’
’@’
’@’
TCPHostName;
TCPHostName;
TCPHostName;
AnyDomainName;
B ’.’ TCPHostNameDomain;
SMTP Secure Gateway Configuration Defaults
If SMTP is configured as a secure gateway, SMTP uses the following default:
Field Definition Section
DefaultFields = ’Bcc’ ’Cc’ ’From’ ’Reply-To’ ’Resent-From’
’Resent-Reply-To’ ’Resent-Sender’ ’Return-Path’
’Sender’ ’To’;
Rule Definition Section
SecureNickAddr
=> SecureNickName ’@’ TCPHostName;
A ’@’ RSCSHostName => A ’@’ TCPHostName;
IF RSCSDomain NOT = ’’ THEN
SecureNickAddr ’.’ RSCSDomain
=> SecureNickName ’@’ TCPHostName;
SecureNickAddr ’.’ AltRSCSDomain => SecureNickName ’@’ TCPHostName;
A ’@’ RSCSHostName ’.’ RSCSDomain
=> A ’@’ TCPHostName;
388
z/VM: TCP/IP Planning and Customization
SMTP Server
A ’@’ RSCSHostName ’.’ AltRSCSDomain => A ’@’ TCPHostName;
IF RSCSDomain CONTAINS ’.’ THEN
A ’@’ AnyRSCSHostName
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’@’ AnyRSCSHostName ’.’ RSCSDomain;
ELSE
A ’@’ AnyRSCSHostName
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ RSCSDomain
=>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
A ’%’ AnyRSCSHostName ’.’ RSCSDomain ’@’ TCPHostName;
ENDIF
ENDIF
A
A
A
A
A
’@’
’@’
’@’
’@’
’@’
TCPHostName
ShortTCPHostName
AltTCPHostName
AnyDomainName
B
=>
=>
=>
=>
=>
A
A
A
A
A
’@’
’@’
’@’
’@’
’@’
TCPHostName;
TCPHostName;
TCPHostName;
AnyDomainName;
B ’.’ TCPHostNameDomain;
Examples of Header Rewrite Rules
The following are examples of how the default header rewriting rules affect an
SMTP mail header. The example site is not a secure gateway and is configured as
shown in the following example.
TCPHostName
ShortTCPHostName
AltTCPHostName
RSCSHostName
RSCSDomain
AltRSCSDomain
=
=
=
=
=
=
vm1.acme.com
vm1
seeds.acme.com
vm1
acmenet
centralnet
In addition, assume that the following are known to be other RSCS hosts:
bird
iron
Then the following header:
From: [email protected] (Brendan Beeper)
To: "Jenny Bird" <[email protected]>
Cc: [email protected], [email protected],
[email protected]
Subject: New Ore
Sender: "Mailing List" <[email protected]>
Bcc: [email protected]
is rewritten as:
From: [email protected] (Brendan Beeper)
To: "Jenny Bird" <def%[email protected]>
Cc: ghi%[email protected], [email protected],
[email protected]
Subject: New Ore
Sender: "Mailing List" <owner%[email protected]>
Bcc: lmno%[email protected]
If you change the rule before the two ENDIFs to:
A ’@’ AnyRSCSHostName ’.’ AltRSCSDomain =>
’<@’ TCPHostName ’:’ A ’@’ AnyRSCSHostName ’.’ RSCSDomain ’>’;
Chapter 20. Configuring the SMTP Server
389
SMTP Server
then the original Bcc field within our header is rewritten as:
Bcc: <@vm1.acme.com:[email protected]>
Note: Do not make the change shown in the previous example; it is intended only
as a demonstration of the capabilities of the pattern-matching language.
Dynamic Server Operation
The VM Special Message (SMSG) command provides an interactive interface to the
SMTP server to:
v perform general user tasks such as querying the SMTP mail delivery queues and
operating statistics of the SMTP server.
v perform privileged system administration tasks, such as rebooting or shutting
down the SMTP server and enabling or disabling various tracing and debugging
options.
Notes:
1. Privileged SMSG commands are accepted only from users that have been
included on the SMTP server SMSGAUTHLIST configuration statement.
2. Command responses are returned to the originator of an SMSG command
through the use of CP MSG commands (or CP MSGNOH commands if the
SMTP server is running with CP privilege class B).
SMSG Interface to the SMTP Server
The various SMSG commands and operands supported by the name server are
presented throughout the remainder of this section, with general-user commands
presented separately from those that are available to only privileged users.
General User SMSG Commands
Use the SMSG command for general user queries for the mail delivery queues and
the operating statistics of the SMTP server.
SMSG server_id
HElp
QUeues
STats
Operands
server_id
The user ID of the SMTP server virtual machine.
HElp
Provides a list of valid SMSG commands accepted by SMTP.
QUeues
Provides a list of mail queued on the various SMTP mail delivery queues.
STats
Provides operating statistics about the SMTP server.
390
z/VM: TCP/IP Planning and Customization
SMTP Server
Privileged User SMSG Commands
The privileged SMTP SMSG commands allow system administrators to perform
SMTP administration tasks, such as rebooting or shutting down the SMTP server,
controlling tracing activity, or altering specific aspects of SMTP server operation.
Only the most basic privileged SMSG commands are discussed here; the remaining
SMSG commands are discussed in the sections listed in table Table 23.
SMSG server_id
HElp
CLosecon
REboot
SHutdown
Privileged user SMSG commands are accepted only from users specified with the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
HElp
Provides brief help about SMSG commands supported by the SMTP server.
CLosecon
Closes the SMTP server’s console log and sends it to the :Owner. identified in
the DTCPARMS file.
REboot
Causes SMTP to Initial Program Load (IPL) CMS.
SHutdown
Initiates SMTP server shutdown processing (in the same manner as the #CP
EXTERNAL command) and additionally logs off the server.
Table 23 summarizes the additional privileged user SMTP SMSG commands.
Table 23. Privileged SMTP SMSG Commands
Command
Description
Page
SMSG
FORWARDMAIL
Enables or disables mail forwarding, or identifies a user
exit to be used to control mail forwarding.
392
SMSG LISTMAIL
Displays the number of pieces of mail or a list of mail
currently being processed by the SMTP server.
393
SMSG MAILINFO
Displays general envelope information for a given piece of
mail.
395
SMSG PURGE
Purges a single piece of mail.
397
SMSG REFRESH
Refresh SMTP security or nickname table information.
398
SMSG REPROCESS
Causes a piece of mail to be reprocessed.
398
SMSG SMTPCMDS
Defines the characteristics of the SMTP command user
exit.
399
SMSG
SOURCEROUTES
Specifies whether or not the SMTP server is to honor
source routes.
402
Chapter 20. Configuring the SMTP Server
391
SMTP Server
Table 23. Privileged SMTP SMSG Commands (continued)
Command
Description
Page
SMSG TRACE
Controls the tracing activity performed by the SMTP
server.
404
SMSG
VERIFYCLIENT
Specifies whether or not client verification is to be
performed.
405
Privileged User SMSG FORWARDMAIL Command
The FORWARDMAIL command is used to enable or disable mail forwarding, to
identify a user exit to be used to control such activity, and to query the current
FORWARDMAIL setting. For information on using the mail forwarding exit, see the
TCP/IP Programmer’s Reference.
SMSG
server_id FORWARDmail
YES
NO
EXIT
SMTPFWDX EXEC
exitname
EXIT RELOAD
QUERY
EXEC
ON
OFF
TEXT
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
YES
Indicates mail forwarding is to be performed.
NO
Indicates that no mail forwarding is to be performed. When the SMTP server
determines the recipient is not on the local system, the RCPT TO: command
will be rejected.
EXIT
Indicates a mail forwarding exit routine is being turned on or off by this
command.
exitname
The name of the exit routine associated with this command (the default exit
routine name for FORWARDMAIL is SMTPFWDX).
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC (this is the default).
TEXT
Indicates the exit routine name specified on this command is the name of a text
deck.
ON
Indicates the specified exit is being enabled (turned on).
392
z/VM: TCP/IP Planning and Customization
SMTP Server
OFF
Indicates the specified exit is being disabled (turned off).
RELOAD
Forces the exit routine to be reloaded the next time it is executed. If the exit
routine is a REXX exec, it will be EXECLOADed into storage the next time it is
executed.
QUERY
Returns current FORWARDMAIL settings; the returned response indicates
whether mail forwarding is enabled or disabled. If an exit has been defined, the
name of the exit is included in the response. Sample responses for several
settings are shown in Table 24.
Table 24. Mail Forwarding Exit - Sample Queries
Mail Forwarding Setting
Response from Query
Mail Forwarding ON
* From SMTP: FORWARDMAIL is set to YES
Mail Forwarding OFF
* From SMTP: FORWARDMAIL is set to NO
Exit SMTPFWDX TEXT enabled
* From SMTP: FORWARDMAIL exit SMTPFWDX TEXT ON
Exit SMTPFWDX TEXT disabled
* From SMTP: FORWARDMAIL is set to YES (Exit
SMTPFWDX TEXT OFF)
Examples
v The command that follows will enable the mail forwarding exit routine
SMTPFWDX EXEC.
smsg smtp forwardmail exit smtpfwdx exec on
The following response is displayed:
* From SMTP: FORWARDMAIL exit SMTPFWDX EXEC ON
v This next command will enable mail forwarding, and at the same time disable
any mail forwarding exit that is currently in use.
smsg smtp forwardmail yes
The following response is displayed:
* From SMTP: FORWARDMAIL is set to YES
v This last command will query the current mail forwarding setting.
smsg smtp forwardmail query
The following response is displayed:
* From SMTP: FORWARDMAIL is set to YES (Exit SMTPFWDX EXEC OFF)
Privileged User SMSG LISTMAIL Command
The LISTMAIL command provides the number of pieces of mail and/or a list of mail
currently being processed by the SMTP server. The list will be sorted from the
oldest to the newest piece of mail and will contain the following information for each
piece of mail: mail ID, sender ID, Total Recipients, and Mail State.
Chapter 20. Configuring the SMTP Server
393
SMTP Server
SMSG server_id LISTMail
COUNT
number
ALL
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
COUNT
Displays a count of the number of pieces of mail currently being processed by
the SMTP server. COUNT is the default.
number
The number of pieces of mail to display in the list, starting with the oldest piece
of mail.
ALL
Indicates that all mail will be displayed in the list, starting with the oldest piece
of mail.
Mail States
Mail can be in one or more of the following mail states:
Receiving
Mail envelope and text are currently being received by the SMTP server.
Resolving
Mail name server resolution is currently being processed.
Spooling
Mail is currently queued up for local delivery.
Waiting to Send
Mail is currently queued up for delivery to a remote host. There is currently no
open connection.
Sending
Mail is currently queued up on an open connection to be sent to a remote host.
The mail at the head of the queue is actively communicating with the remote
host.
Waiting to Retry
Mail is currently queued up to be delivered to a remote host again because an
earlier delivery attempt was unsuccessful.
Holding
Mail is currently waiting for operator intervention because local delivery was
unsuccessful.
Note: Mail will remain in the Holding state until a REPROCESS, PURGE,
REBOOT, or SHUTDOWN command is issued.
394
z/VM: TCP/IP Planning and Customization
SMTP Server
Examples
sm smtp listm
Ready; T=0.01/0.01 15:42:05
* From SMTP3: Total pieces of mail in process: 5
sm smtp listm count
Ready; T=0.01/0.01 15:42:50
* From SMTP3: Total pieces of mail in process: 5
sm smtp listm 3
Ready; T=0.01/0.01 15:43:22
* From SMTP3: Total pieces of mail in process: 5
* From SMTP3: Number requested: 3
* From SMTP3:
* From SMTP3:
* From SMTP3: mail Id
Sender (first 25 chars)
* From SMTP3: -------- ------------------------* From SMTP3: 1
[email protected]
* From SMTP3: 2
[email protected]
* From SMTP3: 3
[email protected]
Total
Rcpts
------8
12
3
sm smtp listm all
Ready; T=0.01/0.01 15:44:01
* From SMTP3: Total pieces of mail in process: 5
* From SMTP3: Number requested: 5
* From SMTP3:
* From SMTP3:
* From SMTP3: mail Id
Sender (first 25 chars)
* From SMTP3: -------- ------------------------* From SMTP3: 1
[email protected]
* From SMTP3: 2
[email protected]
* From SMTP3: 3
[email protected]
* From SMTP3: 5
[email protected]
* From SMTP3: 7
[email protected]
Total
Rcpts
------8
12
3
1
14
Mail
State
-----Waiting to Retry
Waiting to Send
Sending
Mail
State
-----Waiting to Retry
Waiting to Send
Sending
Receiving+Resolving
Receiving
Privileged User SMSG MAILINFO Command
The MAILINFO command provides general envelope information for a given piece
of mail.
SMSG server_id MAILInfo mailid
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
mailid
The mail ID of the piece of mail for which mail information is to be displayed.
The mail ID for a piece of mail may be obtained by using the SMSG LISTMAIL
command.
General Envelope Information
The MAILINFO command provides the following general envelope information for a
given piece of mail:
Chapter 20. Configuring the SMTP Server
395
SMTP Server
Total Rcpts
The total number of recipients for the piece of mail.
Unresolved Rcpts
The total number of unresolved recipients for the piece of mail.
Remaining Rcpts
The total number of remaining recipients for the piece of mail.
Date Received
The date the mail was received by the SMTP server.
Time Received
The time the mail was received by the SMTP server.
Mail Size
The size of the mail in bytes.
Sender ID
The user ID of the original sender of the mail.
The following four Batch File fields are provided for a given piece of mail only if the
mail was generated as the result of another virtual machine having sent a Batch
SMTP (BSMTP) file to the SMTP server virtual machine:
Note:
Source User ID
The user ID of the virtual machine from which the Batch SMTP file was
spooled.
Source Node ID
The node ID of the virtual machine from which the Batch SMTP file was
spooled.
Source Spool ID
The spool ID of the Batch SMTP file on the virtual machine that sent the
file to SMTP.
Current Spool ID
The spool ID of the Batch SMTP file on the SMTP server virtual
machine.
The following general envelope information may or may not be provided, as
this information is dependent upon the status of the mail:
Sender Domain
The host domain of the original sender of the mail.
Mail From String
The sender path address specified with the SMTP MAIL FROM:
command for this piece of mail.
Rcpt ID
The user ID of the recipient of the mail.
Rcpt Domain
The host domain of the recipient of the mail.
Rcpt To String
The recipient path address specified with the SMTP RCPT TO:
command for this piece of mail.
396
z/VM: TCP/IP Planning and Customization
SMTP Server
IP Address
The resolved recipient IP address.
Rcpt Domain, Rcpt ID, Rcpt To String, and IP address will be given for each
recipient of the mail.
Examples
sm smtp mailinf 3
Ready; T=0.01/0.01 15:44:01
* From SMTP3: Mail Information
* From SMTP3: ---------------* From SMTP3: Total Rcpts
:
* From SMTP3: Unresolved Rcpts
:
* From SMTP3: Remaining Rcpts
:
* From SMTP3: Date Received
:
* From SMTP3: Time Received
:
* From SMTP3: Mail Size (bytes) :
* From SMTP3: Sender ID
:
* From SMTP3: Sender Domain
:
* From SMTP3: Mail From String
:
* From SMTP3:
* From SMTP3: Batch File
* From SMTP3:
Source User ID
:
* From SMTP3:
Source Node ID
:
* From SMTP3:
Source Spool ID :
* From SMTP3:
Current Spool ID :
* From SMTP3:
* From SMTP3: Remaining Recipients
* From SMTP3:
Rcpt ID
:
* From SMTP3:
Rcpt Domain
:
* From SMTP3:
Rcpt To String
:
* From SMTP3:
IP Addresses
:
* From SMTP3:
* From SMTP3:
Rcpt ID
:
* From SMTP3:
Rcpt Domain
:
* From SMTP3:
Rcpt To String
:
* From SMTP3:
IP Addresses
:
* From SMTP3:
:
* From SMTP3:
* From SMTP3:
Rcpt ID
:
* From SMTP3:
Rcpt Domain
:
* From SMTP3:
Rcpt To String
:
* From SMTP3:
IP Addresses
:
3
0
3
01/01/99
15:41:52
212
USER
VM
<[email protected]>
USER
VM
1008
0004
user5
vm1.acme.com
<[email protected]>
1.234.56.78
user4
vm1.acme.com
<[email protected]>
12.567.8.90
9.876.54.32
teri
vm1.acme.com
<[email protected]>
123.456.78.9
Privileged User SMSG PURGE Command
The PURGE command allows an authorized user to purge error mail, provided it is
in one of these mail states: Waiting to Send, Waiting to Retry, Spooling, Sending,
and/or Holding.
The original sender of the purged mail will be notified of this action through error
mail.
Note: Mail that is actively communicating with a remote host cannot be purged; in
this case, the mail must finish communicating with the remote host before
the PURGE command may be issued.
Chapter 20. Configuring the SMTP Server
397
SMTP Server
SMSG server_id PUrge mailid
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
mailid
The mail ID of the piece of mail to be purged. The Mail ID of a piece of mail
may be obtained by using the LISTMAIL command.
Examples
sm smtp pu 1
Ready; T=0.01/0.01 15:46:38
Privileged User SMSG REFRESH Command
The REFRESH command allows an authorized user to refresh SMTP security table
or nickname table information by dynamically reading the SMTP SECTABLE or
SMTP NAMES file.
SMSG server_id REFresh
NAMES
SECTABLE
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
NAMES
Indicates that SMTP nickname table information should be refreshed by
dynamically reading the SMTP NAMES file. The SMTP server must not be
configured as a secure mail gateway.
SECTABLE
Indicates that SMTP security table information should be refreshed by
dynamically reading the SMTP SECTABLE file. The SMTP server must be
configured as a secure mail gateway.
Privileged User SMSG REPROCESS Command
The REPROCESS command allows an authorized user to force a piece of mail to
be reprocessed, provided it is in one of these mail states: Waiting to Send, Waiting
to Retry, Spooling, Sending, and/or Holding.
398
z/VM: TCP/IP Planning and Customization
SMTP Server
Note: Mail that is actively communicating with a remote host cannot be
reprocessed; in this case, the mail must finish communicating with the
remote host before the REPROCESS command may be issued.
The REPROCESS command may be useful when a particular piece of mail cannot
be delivered for some period of time, during which the IP addresses in the mail
have become old or obsolete. With REPROCESS, the recipient addresses for the
mail will be newly resolved and delivery of the mail will again be attempted.
SMSG server_id REProcess mailid
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
mailid
The mail ID of the piece of mail to be processed again. The Mail ID of a piece
of mail may be obtained by using the LISTMAIL command.
Examples
sm smtp reprocess 1
Ready; T=0.01/0.01 15:45:22
* From SMTP3: Mail Id 1 is being reprocessed.
Privileged User SMSG SMTPCMDS Command
The SMTPCMDS command is used to define the characteristics of the SMTP
command user exit, to query those characteristics, and to indicate whether or not
the exit is to be called by setting it on or off. For information on using the SMTP
command exit, see the TCP/IP Programmer’s Reference.
Chapter 20. Configuring the SMTP Server
399
SMTP Server
SMSG
server_id
SMTPCMDS
EXIT
SMTPCMDS Options
EXIT RELOAD
QUERY
SMTPCMDS Options:
SMTPCMDX EXEC
exitname
ON
EXEC
TEXT
OFF
FOR
ADD
DELETE
HELO
EHLO
MAIL
RCPT
DATA
EOD
VRFY
EXPN
RSET
PUNCH
ALL
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
exitname
The name of the exit routine associated with this command (the default exit
routine name for SMTPCMDS is SMTPCMDX).
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC (this is the default).
TEXT
Indicates the exit routine name specified on this command is the name of a text
deck.
FOR
Precedes the exact list of commands for which the exit is being defined.
ADD
Precedes the list of commands that are to be added to this exit definition.
DELETE
Precedes the list of commands that are to be deleted from this exit definition.
HELO
Indicates the exit routine is to be turned on or off for the HELO command.
EHLO
Indicates the exit routine is to be turned on or off for the EHLO command.
MAIL
Indicates the exit routine is to be turned on or off for the MAIL FROM:
command.
400
z/VM: TCP/IP Planning and Customization
SMTP Server
RCPT
Indicates the exit routine is to be turned on or off for the RCPT TO: command.
DATA
Indicates the exit routine is to be turned on or off for the DATA command.
EOD
Indicates the exit routine is to be turned on or off when the “end of data”
condition is reached; that is, when a period (.) is received by the SMTP server
after a DATA command.
VRFY
Indicates the exit routine is to be turned on or off for the VRFY command.
EXPN
Indicates the exit routine is to be turned on or off for the EXPN command.
RSET
Indicates the exit routine is to be turned on or off for the RSET command.
PUNCH
Indicates the exit routine is to be turned on or off for PUNCH processing. If the
exit is enabled for this condition, it will be called when the SMTP server is ready
to punch local mail (mail on the same node or RSCS network) to its destination.
ALL
Indicates the exit routine is to be turned on or off for all of the SMTP commands
for which user exit capability is provided.
ON
Indicates the specified exit is being enabled (turned on) for a particular
command or set of commands.
OFF
Indicates the specified exit is being disabled (turned off) for a particular
command or set of commands.
RELOAD
Forces the exit routine to be reloaded the next time it is executed. If the exit
routine is a REXX exec, it will be EXECLOADed into storage the next time it is
executed.
QUERY
Returns current SMTPCMDS exit settings. The returned response indicates
whether the command exit is enabled or disabled. If an exit has been defined,
the name of the exit is included in the response. The commands associated
with the current exit state are indicated as well. Sample responses for several
settings are shown in Table 25.
Table 25. SMTP Command Exit - Sample Queries
SMTP Command Exit Setting
Response from Query
Exit not defined
* From SMTP: SMTPCMDS exit not defined
Exit SMTPCMDX EXEC enabled
for HELO, VRFY, and EXPN
* From SMTP: SMTPCMDS exit SMTPCMDX EXEC ON *
From SMTP: SMTPCMDX defined for HELO VRFY EXPN
Exit SMTPCMDX EXEC disabled
* From SMTP: SMTPCMDS exit SMTPCMDX EXEC OFF *
From SMTP: SMTPCMDX defined for HELO VRFY EXPN
Chapter 20. Configuring the SMTP Server
401
SMTP Server
Examples
v The command that follows will enable the SMTP command exit routine
SMTPCMDX EXEC for the SMTP HELO command:
smsg smtp smtpcmds exit for helo
The following response is displayed:
* From SMTP: SMTPCMDS exit SMTPCMDX EXEC ON
* From SMTP: SMTPCMDX defined for HELO
v The next command will add the SMTP commands VRFY and EXPN to the
previous exit definition:
smsg smtp smtpcmds exit add vrfy expn
The following response is displayed:
* From SMTP: SMTPCMDS exit SMTPCMDX EXEC ON
* From SMTP: SMTPCMDX defined for HELO VRFY EXPN
v Lastly, the command that follows will disable the SMTP commands exit:
smsg smtp smtpcmds exit off
The following response is displayed:
* From SMTP: SMTPCMDS exit SMTPCMDX EXEC OFF
* From SMTP: SMTPCMDX defined for HELO VRFY EXPN
Privileged User SMSG SOURCEROUTES Command
The SOURCEROUTES command is used to specify whether the SMTP server will
honor source routes, and to query the current SOURCEROUTES setting.
A source route is a path that contains a routing list of hosts and a destination
mailbox. The list of hosts is the route — information about how the mail is to arrive
at its final destination; the mail is passed from one host in this list to the next until it
is delivered to the intended recipient.
The specification that follows is an example of a source route:
<@HOST1,@HOST2,@HOST3:[email protected]>
The list of hosts is HOST1, HOST2 and HOST3, and the destination is
[email protected]
If this sample source route is included with a RCPT TO: command, and is honored
by SMTP, the mail will be sent to HOST1, then to HOST2, then to HOST3 and
finally to [email protected] When source routes are not honored, mail is sent directly
to [email protected]; the list of hosts is ignored.
If this sample source route is included with a MAIL FROM: command and source
routes are honored, the SMTP server will include its host name (for example,
VMHOST1) in the path information, and will supply the following path for its MAIL
FROM: command:
<@HOST1,@HOST2,@HOST3,@VMHOST1:[email protected]>
If such source routes are not honored, the list of hosts is removed from the mail
routing path. In addition, the SMTP server will not add its host name to the path
information.
402
z/VM: TCP/IP Planning and Customization
SMTP Server
SMSG server_id SOURCEroutes
RCPTTO
MAILFROM
BOTH
QUERY
YES
NO
Operands
server_id
The user ID of the SMTP server virtual machine.
YES
Indicates that client-supplied source routes on the MAIL FROM: command, the
RCPT TO: command, or both will be honored when mail is forwarded by the
SMTP server. The RCPT TO, MAIL FROM or BOTH parameter determines the
specific source routes honored by the SMTP server.
NO
Indicates that client-supplied source routes on the MAIL FROM: command, the
RCPT TO: command, or both are not to be honored when mail is forwarded by
the SMTP server. The RCPT TO, MAIL FROM or BOTH parameter determines
the specific source routes ignored by the SMTP server.
Note: The NO parameter does not cause mail containing source routes to be
rejected.
RCPTTO
Indicates the processing of source routes supplied with the RCPT TO:
command is to be affected. When this parameter is used and NO is specified,
any host list will be ignored and only the destination host will be used. The mail
recipient(s) will not see the host list that was ignored.
For the previous sample source route, the SMTP server will send the mail
directly to [email protected]; the HOST1, HOST2 and HOST3 hosts will be
ignored.
When used with the YES parameter, source routes will be honored.
MAILFROM
Indicates the processing of source routes supplied with the MAIL FROM:
command is to be affected. When this parameter is used and NO is specified,
the list of hosts will be removed from the mail routing path. In addition, the
SMTP server will not add its host name to the path information. The mail
recipient(s) will not see the host list that was ignored.
For the previous sample source route, the SMTP server will supply the following
MAIL FROM: command when mail is forwarded:
MAILFROM: <[email protected]>
When used with the YES parameter, source routes will be honored, with the
SMTP server host name included as part of the path information.
BOTH
Indicates the handling of source routes supplied for both the RCPT TO: or the
MAIL FROM: commands is to be affected. Source routing information for these
commands will be processed as previously described.
Chapter 20. Configuring the SMTP Server
403
SMTP Server
QUERY
Displays the current SOURCEROUTES setting. The returned response
indicates whether or not source routes will be honored.
Examples
v The command that follows will disable source routes for the RCPT TO:
command. Source routes will not be honored and will be ignored.
smsg smtp sourceroutes rcptto no
The following response is displayed:
* From SMTP: RCPTTO SOURCEROUTES is set to NO
Privileged User SMSG TRACE Command
SMSG server_id TRACE
QUERY
ALL
CONN
NOCONN
DEBUG
NODEBUG
NOTICE
NONOTICE
RESOLVER
NORESOLVER
CODEFLOW
NOCODEFLOW
SPL
NOSPL
END
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
QUERY
Reports the tracing activities that are currently in effect.
ALL
Initiates tracing of all types.
CONN
Initiates tracing of connection activity.
NOCONN
Terminates tracing of connection activity.
DEBUG
Initiates tracing of all commands and replies and their associated connection
numbers (this is the same information that was captured using the old DEBUG
configuration option).
404
z/VM: TCP/IP Planning and Customization
SMTP Server
NODEBUG
Terminates tracing of commands and replies.
NOTICE
Initiates tracing of all TCP/IP notification events that are received by the SMTP
server.
NONOTICE
Terminates tracing of TCP/IP notification events.
RESOLVER
Initiates resolver tracing. This is the same as adding the TRACE RESOLVER
statement to the TCPIP DATA file that is read by the SMTP server at
initialization.
NORESOLVER
Terminates resolver tracing.
CODEFLOW
Initiates tracing of SMTP program code flow.
NOCODEFLOW
Terminates code flow tracing.
SPL
Initiates tracing of *SPL IUCV execution.
NOSPL
Terminates *SPL IUCV tracing.
END
Terminates all tracing activity.
Privileged User SMSG VERIFYCLIENT Command
The VERIFYCLIENT command is used to indicate whether or not client verification
is to be performed, and to query VERIFYCLIENT settings. Client verification can be
performed using the built-in client verification function (VERIFYCLIENT YES), or
using a user exit (VERIFYCLIENT EXIT). For information on using the client
verification exit, see the TCP/IP Programmer’s Reference.
SMSG
server_id
VERIFYclient
NO
YES
EXIT
SMTPVERX EXEC
exitname
EXIT RELOAD
QUERY
EXEC
ON
OFF
TEXT
Privileged user SMSG commands are accepted only from users specified in the
SMSGAUTHLIST configuration statement.
Operands
server_id
The user ID of the SMTP server virtual machine.
Chapter 20. Configuring the SMTP Server
405
SMTP Server
NO
Indicates no client verification is to be performed.
YES
Indicates verification of the client name specified on the HELO or EHLO
command is to be performed using the built-in client verification function.
EXIT
Indicates a client verification exit routine is being turned on or off by this
command.
exitname
The name of the exit routine associated with this command (the default exit
routine name is SMTPVERX).
EXEC
Indicates the exit routine name specified on this command is the name of an
EXEC (this is the default).
TEXT
Indicates the exit routine name specified on this command is the name of a text
deck.
ON
Indicates the specified exit is being enabled (turned on).
OFF
Indicates the specified exit is being disabled (turned off).
RELOAD
Forces the exit routine to be reloaded the next time it is executed. If the exit
routine is a REXX exec, then it will be EXECLOADed into storage the next time
it is executed.
QUERY
Returns current VERIFYCLIENT settings; the returned response indicates
whether client verification is enabled (on) or disabled (off).. If an exit has been
defined, the name of the exit is included in the response. Sample responses for
several settings are shown in Table 26.
Table 26. Client Verification Exit - Sample Queries
Client Verification Setting
Response from Query
Built-in function ON
* From SMTP: VERIFYCLIENT is set to YES
Built-in function OFF
* From SMTP: VERIFYCLIENT is set to NO
Exit SMTPVERX TEXT enabled
* From SMTP: VERIFYCLIENT exit SMTPVERX TEXT ON
Exit SMTPVERX TEXT disabled
* From SMTP: VERIFYCLIENT is set to NO (Exit
SMTPVERX TEXT OFF)
Examples
v The command that follows will enable the client verification exit routine
SMTPVERX EXEC; client verification will be performed by this exit routine.
smsg smtp verifyclient exit smtpverx exec on
The following response is displayed:
* From SMTP: VERIFYCLIENT exit SMTPVERX EXEC ON
v This next command will disable all client verification; no client verification is
performed.
406
z/VM: TCP/IP Planning and Customization
SMTP Server
smsg smtp verifyclient no
The following response is displayed:
* From SMTP: VERIFYCLIENT is set to NO
v This last command will query the current client verification setting.
smsg smtp verifyclient query
The following response is displayed:
* From SMTP: VERIFYCLIENT is set to NO (Exit SMTPVERX EXEC OFF)
Chapter 20. Configuring the SMTP Server
407
SMTP Server
408
z/VM: TCP/IP Planning and Customization
Chapter 21. Configuring the SNALINK Server
Figure 10 shows the SNALNKA virtual machine interfaces between the TCPIP
virtual machine’s SNAIUCV driver and the customer’s SNA network. The SNALINK
application running in the SNALNKA virtual machine communicates with one or
more instances of SNALINK at remote nodes, using the SNA LU type 0 protocol.
VM
TCPIP
#1
VM
SNALINK
IUCV
SNALINK
SNA LU0
#1
#2
TCPIP
IUCV
#2
SNA LU0
MVS
SNALINK
#3
TCPIP
IUCV
#3
Figure 10. SNALINK Communications
Each SNALINK virtual machine can communicate with up to six other SNALINK
machines simultaneously.
Install the SNALNKA Virtual Machine
After defining the SNALNKA virtual machine:
1. Give SNALNKA access to Group Control System (GCS).
2. Define the SNALINK application in the VM/VTAM definition files.
3. Customize the SNALNKA GCS file.
Notes:
1. In the TCPIP and SNALNKA virtual machine directory entries, MAXCONN
should be greater than MaxSession.
2. If there are more than two SNA sessions, increase virtual machine storage by
130 Kb over and above the default storage size of 2Mb.
Step 1: Give SNALNKA Access to GCS
The SNALINK application must run in an authorized member of the GCS group.
The SNALNKA user ID can be authorized in one of two ways:
1. Re-build GCS, with SNALNKA defined on an AUTHUSER statement in the GCS
configuration file, or by using the GROUP exec.
© Copyright IBM Corp. 1987, 2002
409
SNALINK Server
2. The CONFIG AUTHUSER ADD SNALNKA command may be issued from the
GCS recovery machine console or profile.
Authorization to IPL the GCS named saved system is required. The CP directory
entry for SNALNKA must have NAMESAVE GCS in it.
Step 2: Define SNALINK Applications in VM/VTAM
When operating in dual mode, SNALINK opens two SNA sessions for each remote
logical unit (LU) with which it communicates, one for sending and one for receiving.
You may have to specify pacing values. Consult your VTAM network administrator
for further details. When operating in single mode, SNALINK opens one duplex
session.
SNALINK provides its own BIND parameters, so it does not assume or require any
particular LOGMODE entries.
In the VTAM APPL definition, the EAS value should be two times the number of
MaxSession. Specify AUTHEXIT=YES rather than NO.
SNALINK Installation Considerations
Figure 11 is an example of a typical APPL statement for SNALINK.
VM2LUS APPL ACBNAME=VM2LUS,
AUTH=(ACQ,VPACE),
AUTHEXIT=YES,
EAS=12,
PARSESS=YES,
SONSCIP=YES,
VPACING=0
X
X
X
X
X
X
Figure 11. APPL Statement for SNALINK
Step 3: Customize SNALNKA GCS
Figure 12 on page 411 shows the content of a sample SNALNKA GCS file (supplied
on the TCPMAINT 591 as file SNALNKA SAMPGCS). Your customized file should
be stored on the TCPMAINT 198 disk as file SNALNKA GCS. Within your
customized file, update the TcpipUserid, LocalLuName, and MaxRuCode variable
assignments to reflect appropriate values for your environment. In addition, add a
CP SPOOL CONSOLE statement to your SNALNKA GCS file if a user ID other than
TCPMAINT is to receive the console log. If additional SNALink servers are required,
copy the SNALNKA GCS file to TCPMAINT 198, appropriately naming each copied
file as userid GCS.
410
z/VM: TCP/IP Planning and Customization
SNALINK Server
/**/
TcpUserid
LocalLuName
MaxRuCode
MaxSession
Retry
ConnectMode
= ’TCPIP’
= ’VM1LU’
= ’C7’
= ’6’
= ’0015’
=’SINGLE’
/* Userid of TCP/IP stack
*/
/* Must be defined to VTAM
*/
/* X’C7’ = (12 x 2**7) = 1536 bytes*/
/* Expressed in HHMM format
*/
/* Use SINGLE for 3745 NCST session*/
’GLOBAL LOADLIB SNALINK’
’LOADCMD SNALINK SNALINK’
’SNALINK’ TcpUserid LocalLuName MaxRuCode MaxSession Retry ConnectMode
Exit rc
Figure 12. Sample SNALNKA GCS File
Parameter
Description
DEBUG
DEBUG is a prefix parameter and must be the first parameter in the
list, if specified. DEBUG enables detailed tracing into an internal
buffer. The DEBUG parameter should be specified only if the user
is instructed to do so by the Support Center since there is no direct
access to the trace table that is created. (The table is a data area
internal to the SNALINK executable module and is accessible only
by dumping the appropriate portion of the virtual storage of the
SNALNKA virtual machine).
TcpipUserid
Identifies, to GCS, the user ID assigned to the TCPIP virtual
machine. This variable should be changed only if your TCPIP virtual
machine has been named something other than TCPIP.
LocalLuName Identifies, to GCS, the LU name used on the ACBNAME parameter
of the APPL statement in the VTAM definition in Figure 11 on
page 410.
MaxRuCode
Specifies the maximum request or response unit (RU) in
hexadecimal. This parameter is optional. Set MaxRuCode to specify
the maximum RU size that SNALINK sends. The value is of the
formX'MN', where M is between 8 and F, and N is between 0 and F.
The corresponding maximum RU size is M2n (M multiplied by 2 to
the power of n). Use the largest size that works on your SNA
network to provide the best performance and the least overhead.
For more information about this parameter, see theVTAM
Programming manual.
MaxSession
Specifies the maximum number of sessions; a decimal value from 1
to 9999. The default value is 6. To use different values for
MaxSession, you also have to specify the MaxRuCode.
Retry
Specifies the delay time for VTAM to retry sense codes and has the
following format:
HHMM
Where: HH = Hours 0-24 MM = Minutes 0-59
For example:
0005 is a 5 minute delay
0200 is a 2 hour delay
1030 is a 10 hour and 30 minute delay
Chapter 21. Configuring the SNALINK Server
411
SNALINK Server
The default delay is 15 minutes and the maximum retry is 24 hours.
To use a different retry interval, specify both MaxRuSize and
MaxSession.
ConnectMode Defines the SNALINK communication session mode. The
ConnectMode can have the values of SINGLE, DUAL, or be
omitted. If the parameter is omitted, the ConnectMode defaults to
DUAL. If the ConnectMode is set to SINGLE, SNALINK creates a
single duplex session. If DUAL is specified, SNALINK creates two
sessions, a send session and a receive session. Like MaxSession
and Retry, if ConnectMode is to be specified you must specify the
previous parameters.
SINGLE must be used for NCST sessions in the Network Control
Program (NCP) for 3745-type communication controllers.
Operating SNALINK
SNALINK is not started automatically when TCP/IP for VM is installed. Like other
applications that run in the GCS environment, the SNALNKA virtual machine needs
to be autologged by an appropriate resource, as is done for other machines in the
GCS group, such as the VTAM or RSCS machines.
To stop SNALINK, enter the following on the SNALNKA virtual console:
REPLY 0 X
Restart a Session
If necessary, you can immediately retry a session that is waiting for the retry delay
to expire by stopping and starting the connection using the OBEYFILE command.
Sample Console
The example shown in Figure 13 and the accompanying information illustrate
SNALink operation. The line number notations have been added for clarity; they do
not appear in the console output.
Line
Line
Line
Line
Line
Line
Line
Line
Line
Line
Line
Line
Line
1
2
3
4
5
6
7
8
9
10
11
12
13
Line
Line
Line
Line
14
15
15
16
Ready;
S (595) R/O
A (191) R/W
C (591) R/O
92275 173617
|
92275 173617
|
92275 173617
|
92275 173617
|
00 REPLY X TO SHUT DOWN
92275 173620 VM3LUS
|
92275 173620 VM3LUS
|
92275 173621 VM3LUS
|
92275 173621 VM3LUS
|
r 0 x
|
Ready;
92275 173629
|
92275 173629 VM3LUS
|
92275 173629 VM3LUS
|
92275 173629 VM3LUS
|
Ready;
Using a SINGLE LU0 session
Init complete, APPLID VM2LUS, TCPIP id TCPIP2
Maximum RU size is 00008000
Max Sessions 6 : Retry Interval 0030
IUCV path 00000001 pending
Sending SNA BIND request
SNA session established
Accepting IUCV path 00000001
Shutdown requested
Received WTOR reply, shutting down
RECEIVE CHECK err. R15 00000004 R0 00000010 RTNCD 00000010
RECEIVE sense: SSENSEI,SSENSMI,USENSEI: 00000000
RECEIVE shows RESPOND 00000000 CONTROL 00800000 RH 00000000
Figure 13. Sample Console File
412
z/VM: TCP/IP Planning and Customization
SNALINK Server
The following is the description of the Sample Console File.
Line Number
Description
Lines 1, 2, and 3:
Specifies the minidisk connections with access
rights for SNALINK operations.
Lines 4 through 7:
Displays startup information from the command line
parameters, which are customized in the sample
console. The maximum RU size is displayed in
hexadecimal, as are all other numbers except for
the time stamp. The time stamp on each message
is in the form YYDDD HHMMSS.
Line 8:
Issues a WTOR macro at startup. A reply is
interpreted as a request to shut down.
Line 9:
Specifies the TCPIP virtual machine, TCPIP2, issues
an IUCV CONNECT to establish a session with the
remote LU VM3LUS. Remote LU VM3LUS is higher in
collating sequence than the local LU name VM2LUS,
so SNALINK takes the passive role in connecting to
VM3LUS. This means that it waits for VM3LUS to
establish a session.
Line 10:
Sends a BIND request to VM3LUS.
Line 11:
Indicates that the BIND request was accepted and
SNALINK has established the SNA session.
Lines 12:
Establishment of the SNA session causes SNALINK
to accept the corresponding IUCV path.
Line 13:
Indicates that the operator has issued a reply to the
WTOR, causing SNALINK to shut down. All IUCV
paths and SNA sessions are terminated.
Lines 14 through 16:
Indicates that VM3LUS has terminated its sessions,
which results in various error messages.
Determine SNA Session Status by SNA IUCV Device Status
The IUCV connect protocol between TCP/IP and SNALINK causes the status of the
SNAIUCV device, reported by NETSTAT DEVLINKS, to reflect the status of the
SNA sessions to the remote LU.
Status Reported
Explanation
Issued connect
Passive side: SNALINK is waiting for a remote LU
to establish a session.
Active side: SNALINK is trying to establish a
session with a remote LU.
Will retry connect
Last session was terminated, or last session
attempt failed. SNAIUCV driver retries the
connection within 30 seconds.
Connected
SNA send session is established. Under normal
conditions this also means a receive session is
established or will be established soon, and
communication between the two LUs is possible.
Chapter 21. Configuring the SNALINK Server
413
SNALINK Server
Sending message
As in Connected. In addition, there is an IUCV
SEND currently outstanding.
Define SNA IUCV Links
SNA IUCV links are point-to-point, unlike any other supported device.
The IUCV link constitutes a separate network, even though the IUCV link includes
only two hosts. You have to assign a unique network or subnetwork number to each
end of the IUCV link. The IUCV link does not need its own network or subnetwork
number if the link is connecting two hosts that have unique network or subnetwork
numbers attached to them and you are not running ROUTED or SNMP.
For example, consider the following scenario:
v Hosts A and B are connected by SNA IUCV
v Host A is also connected to a Token-Ring whose address is 193.1.1
v Host B is also connected to a Token-Ring whose address is 193.1.2
v Host A’s home address on its Token-Ring is 193.1.1.1
v Host B’s home address on its Token-Ring is 193.1.2.1
SNA
Host A
Host B
193.1.1.1
193.1.2.1
193.1.1
193.1.2
Figure 14. SNA Type 0 IUCV Links
Host A’s PROFILE TCPIP could contain:
home
193.1.1.1
193.1.1.1
gateway
* Network
193.1.1
193.1.2
tr1
snaiucv1
First hop
=
=
Link
Packet size
tr1
2000
snaiucv1
2000
Subnet mask
0
0
Host B’s PROFILE TCPIP could contain:
home
193.1.2.1
193.1.2.1
gateway
* Network
193.1.2
193.1.1
414
tr1
snaiucv1
z/VM: TCP/IP Planning and Customization
First hop
=
=
Link
Packet size
tr1
2000
snaiucv1
2000
Subnet mask
0
0
SNALINK Server
The SNA IUCV link does not have its own home address. Hosts A and B are
addressed by their Token-Ring home addresses, even if the packets reach them
through the SNA IUCV link.
If host B had no other network attached to it, you would have to assign a separate
(sub)network number to the SNA IUCV link. Even in this case, host A does not need
a separate home address for its SNA link, because it can be addressed by its
Token-Ring home address. Host B’s only home address is the home address for the
SNA link.
Chapter 21. Configuring the SNALINK Server
415
416
z/VM: TCP/IP Planning and Customization
Chapter 22. Configuring the SNMP Servers
This chapter describes how to configure the Simple Network Management Protocol
(SNMP) virtual machines. To monitor a TCP/IP VM network from your VM system,
you must use NetView® for z/VM.
SNMP Overview
SNMP is an architecture that allows you to manage an internet environment. You
can use SNMP to manage elements such as gateways, routers, and hosts on the
network. Network management stations act as clients to run the management
applications that monitor the network. Network elements act as servers and contain
management agents, which perform the management functions required. SNMP
provides the communication between these elements and stations to send and
receive information about an internet’s resources.
The MIB consists of information about these resources and elements. The MIB is
referred to as a database, but it actually exists as counters and temporary storage
areas on most of the servers. Data in the MIB is designed according to international
standards for internet management and defined according to the International
Standard Organization (ISO) Abstract Syntax Notation 1 (ASN.1). IBM has extended
the standard MIB by defining enterprise-specific MIB variables for the 3172
Interconnect Controller. For more information about the MIB, see RFC 1155.
More functions are available by using the SNMP daemon Distributed Program
Interface (DPI). The DPI permits end users to dynamically add, delete, or replace
management variables in the MIB without requiring the recompile of the local SNMP
agent. DPI also allows you to generate customized TRAPs. For more information
about the SNMP DPI, see TCP/IP Programmer’s Reference.
TCP/IP network management operates at the application level from one or more
hosts within an internet. Each participating host or gateway runs a server program
to support the SNMP functions. A NetView operator acting as a network manager
invokes client software at the local host computer, which has a specified client
server. The client contacts a command processor or query engine and sends
queries to obtain information or send commands to vary conditions for a particular
managed entity such as a gateway or host TCP/IP link. Only authenticated
managers can participate in this process. Figure 15 on page 418 illustrates the VM
implementation of SNMP with NetView.
© Copyright IBM Corp. 1987, 2002
417
SNMP Servers
DAEMON
CLIENT
User ID = NETVIEW
User ID = SNMPQE
User ID = TCPIP
User ID = SNMPD
SNMP CMD PROC
SQESRV
SNMPD
TASK=SNMPIUCV
SOCKET Interface
SOCKET I/F
GCS
VM
CMS
IUCV
IUCV
INTERNET
Figure 15. Overview of NetView SNMP Support
The following steps describe how the SNMP command is processed.
1. The NetView operator or CLIST issues an SNMP command.
2.
3.
4.
5.
The SNMP command is validated by the SNMP Command Processor.
The Command Processor passes the request to the SNMPIUCV task.
The SNMPIUCV task passes the request to the SNMP Query Engine.
The SNMP Query Engine validates the request, converts the MIB variable to
ASN.1 format if necessary, builds the SNMP request and sends it to the SNMP
daemon.
6. The SNMP Query Engine receives a response from the SNMP daemon.
7. The SNMP Query Engine decodes the response and sends it to the NetView
SNMPIUCV task.
8. The SNMPIUCV task sends the response as a multi-line message to the
requesting operator or authorized receiver.
SNMP Configuration Steps
1. Update the TCPIP server configuration file.
2. Update the DTCPARMS file for SNMPQE and SNMPD.
Step 1: Update PROFILE TCPIP
Include SNMPQE and SNMPD in the AUTOLOG statement to automatically start
the SNMPQE and SNMPD virtual machines when TCPIP is invoked. Verify that the
following statements have been added to PROFILE TCPIP.
AUTOLOG
SNMPQE 0
SNMPD 0
418
z/VM: TCP/IP Planning and Customization
; SNMP Query Engine
; SNMP daemon
SNMP Servers
SNMP requires that port UDP 161 be reserved for all messages sent to the VM
agent, and that port UDP 162 be reserved for SNMP messages that report TRAPs.
Verify that the following statements have been added to PROFILE TCPIP.
PORT
161 UDP SNMPD
162 UDP SNMPQE
; SNMP daemon port for SNMP messages
; SNMP Client port for receipt of TRAPs
The SNMP Query Engine and agent use raw sockets for the DPI interface and the
SNMP PING function. To allow the SNMP Query Engine (SNMPQE) and the SNMP
daemon (SNMPD) to create RAW sockets, add SNMPQE and SNMPD to the OBEY
list in the PROFILE TCPIP file. Verify that the following statements have been
added to PROFILE TCPIP.
OBEY
SNMPQE SNMPD
For more information on the OBEY list, see “OBEY Statement” on page 539.
The MIB II variable sysContac identifies the contact person for this managed node.
Define the contact person for this node using the SYSCONTACT statement, as
shown in the following example:
SYSCONTACT
Andrew Ford, extension 1234
ENDSYSCONTACT
The MIB II variable sysLocation identifies the physical location of this managed
node. Define the physical location of this node using the SYSLOCATION statement,
as shown in the following example.
SYSLOCATION
690 Market street, bldg 100
3rd floor, room 398
ENDSYSLOCATION
If IBM enterprise specific variables are to be retrieved from an attached 3172, add
the optional NETMAN keyword to the appropriate DEVICE statement as shown in
the following example.
device lcs1 lcs 9e0 netman
Step 2: Update the DTCPARMS File for SNMPQE and SNMPD
When the SNMPQE or SNMPD server is started, the TCP/IP server initialization
program searches specific DTCPARMS files for configuration definitions that apply
to this server. Tags that affect the SNMP servers are:
:Nick.SNMPQE
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the SNMPQE and SNMPD
servers if you:
v Activate and specify the level of tracing needed.
v Require a trace of IUCV communication to be done.
Chapter 22. Configuring the SNMP Servers
419
SNMP Servers
SNMP Query Engine
The SNMP Query Engine is a separate VM user ID that runs the SQESERV
MODULE. The Query Engine requires access to the MIB_DESC DATA file, which
contains the MIB variable descriptions. A sample MIB data file is supplied on the
TCPMAINT 591 disk as MIB_DESC SDATA. Your customized file should be stored
on the TCPMAINT 198 disk as file MIB_DESC DATA.
SQESERV
-d
trace_level
-h
hostname
-it
Specify SQESERV operands as :Parms. tag startup parameters in your
DTCPARMS file.
Operands
-d trace_level
Specifies the level of tracing to be run. Valid values for the trace level are:
0
No tracing (default)
1
Display errors
2
In addition to errors, also displays SNMP Query Engine protocol
packets sent and received
3
In addition to SNMPQE packets and errors, also displays the SNMP
packets sent and received
-h hostname
Specifies the IP address to bind to, so that SQESERV accepts only connections
through that IP address. This parameter is useful if multiple IP addresses exist
for a single host and you want to restrict access from one side.
-it Specifies that a trace of IUCV communication is to be done. Used for
debugging only the socket layer in a user’s application. It can result in a very
large amount of output.
Step 3: Define the MIB Data File
The Management Information Base (MIB) data file, MIB_DESC DATA, defines the
short names for MIB variables. Short names are the character representation for the
ASN.1 variable names. For example, sysUpTime is the short name for
1.3.6.1.2.1.1.3.0 (the MIB variable that stores the time since the MIB object was last
restarted). Short names are generally shown as a combination of upper and
lowercase characters, though SNMP for VM ignores these case distinctions.
Variable names must always be in ASN.1 language when they are sent to an SNMP
daemon. You can always use ASN.1 language to specify the variable names in an
enterprise-specific tree (assuming that the agent supports them). You can use these
short names to specify the MIB variables.
When you issue an SNMP GET, GETNEXT, or SET command, and specify the
variable name in ASN.1 notation, the SNMP Query Engine uses that name and
sends it in the SNMP packet to the agent. When you issue an SNMP GET,
GETNEXT, or SET command, and specify the short name for the variable (for
420
z/VM: TCP/IP Planning and Customization
SNMP Servers
example, sysDescr), the SNMP Query Engine looks for that name in the MIB_DESC
DATA file and uses the ASN.1 name specified in the file when it sends the SNMP
packet to the agent.
The distributed MIB_DESC DATA file contains the text names as defined in
RFC 1156. In addition to these, the following variables have been added:
v MIB-II variables from RFC 1158
v IBM 3172 Enterprise Specific MIB variables and some IBM-defined variables in
the enterprise-specific branch of the MIB
The SNMPQE virtual machine must be able to access the MIB_DESC DATA file.
You can change the short names in the MIB_DESC DATA file to the equivalent in
your national language. You can also leave the current names and add the
equivalent names in your national language. However, the SNMP MIBVNAME
function returns only the first entry found in the file that satisfies the search. In
addition, all enterprise-specific variables used by hosts in your network should be
added to this file.
Entries in the file do not need to be in a specific sequence. Each name starts on a
new line. The following shows the line format.
short_name asn.1_name type time_to_live
Each variable on the line is separated by either one or more spaces or tabs. An
asterisk (*) in column 1 indicates that the line is a comment line.
Figure 16 is an example of an MIB_DESC DATA line with a sysDescr variable
translated in Dutch and a few enterprise variables added (in this example, company
ABC received 1.3.6.1.4.1.42 as the ASN.1 number for their enterprise). A sample
MIB_DESC DATA file is shipped on TCPMAINT 591. It should be copied to
TCPMAINT 198 and customized.
*-------------------------------------------------------------*
* MIB Variable name | ASN.1 notation
| Type
| TTL *
*-------------------------------------------------------------*
sysDescr
1.3.6.1.2.1.1.1.
display
900
* Following is Dutch name for sysDescr
systeemBeschrijving 1.3.6.1.2.1.1.1.
display
900
...
other entries
...
* Following are enterprise specific variables for company ABC
ABCInfoPhone
1.3.6.1.4.1.42.1.1
display
900
ABCInfoAddress
1.3.6.1.4.1.42.1.2
display
900
Figure 16. Sample MIB_DESC DATA Line
The TTL field contains the number of seconds that a variable lives in the Query
Engine’s internal cache. If there are multiple requests for the same variable within
the TTL period, the variable value is obtained from the cache, and unnecessary
network traffic is avoided.
You can define multiple short names or text names for the same variable, as shown
with the Dutch translation of the sysDescr variable. In this case, the SNMP Query
Engine returns the first value in the table on an SNMP MIBVNAME request. In
Figure 16, the SNMP Query Engine would return sysDescr and not
systeemBeschrijving. The name returned is in mixed case.
Chapter 22. Configuring the SNMP Servers
421
SNMP Servers
When the SNMP Query Engine receives a short name or text name in a GET,
GETNEXT, or SET request, it compares the name against the entries in the
MIB_DESC DATA file. This comparison is not case-sensitive. For example, a
request for SYSDESCR, SysDescr, or sysDescr matches the sysDescr entry with an
ASN.1 notation of 1.3.6.1.2.1.1.1..
When the SNMP Query Engine receives an SNMP response, it looks up the
variable in the MIB_DESC DATA table Type field for information about translating
the value into displayable characters. The information contained in the Type field is
case-sensitive and must be specified in lowercase.
Step 4: Configure the SNMP/NetView Interface
This section describes how to configure the SNMP/NetView Interface.
SNMPIUCV
SNMPIUCV is the NetView optional task that handles IUCV communication with the
SNMP Query Engine. You need to add the following TASK statement for
SNMPIUCV to the DSIDMN NCCFLST file.
TASK
MOD=SNMPIUCV,TSKID=SNMPIUCV,PRI=5,INIT=Y
This statement causes SNMPIUCV to start automatically when NetView is started. If
you use INIT=N in the TASK statement for SNMPIUCV, a NetView operator can start
the SNMPIUCV task by entering the following:
START TASK=SNMPIUCV
The SNMPIUCV task tries to connect through IUCV to the SNMP Query Engine. If
this fails, it retries the connect as specified in the SNMPARMS NCCFLST file, see
“SNMPIUCV Initialization Parameters” on page 423, the default is every 60
seconds.
SNMP Command Processor
SNMP is the command processor that allows NetView operators and CLISTs to
issue SNMP commands. You should add the following statement to the DSICMD
NCCFLST file.
SNMP
CMDMDL
MOD=SNMP,ECHO=Y,TYPE=R,RES=N
RES=Y to make the command resident in memory to improve performance.
After the SNMPIUCV task is started, you can issue the SNMP command. The
SNMP command passes a request to the SNMPIUCV task to forward to SNMPQE.
The return code represents a request number that is associated with the request.
The responses are returned asynchronously and contain this request number. The
operator or CLIST must use the request number to correlate the response to the
request.
SNMP Messages
The SNMP messages reside in the DSISNMnn NCCFLST files, which are shipped
on the server code disk, TCPMAINT 591 (nn indicates the number of the message).
The valid message files are DSISNM00 through DSISNM05, DSISNM10,
DSISNM12, and DSISNM99. These files should reside on a disk that the NetView
user ID can access.
422
z/VM: TCP/IP Planning and Customization
SNMP Servers
SNMPIUCV Initialization Parameters
SNMPIUCV reads the SNMPARMS NCCFLST file at startup. This file contains the
initialization parameters for SNMP and is shipped on the server code disk,
TCPMAINT 591. You should place the SNMPARMS NCCFLST file on any disk that
can be accessed by the NetView virtual machine.
The following example shows the parameters and the default values of the
SNMPARMS NCCFLST file.
*
*
*
SNMPARMS NCCFLST
SNMPQE
SNMPQERT
SNMPRCNT
SNMPRITO
SNMPRETO
SNMPMMLL
SNMPQE
60
2
10
2
80
*
*
*
*
*
*
Userid of SNMP Query Engine
Retry timer (seconds) for IUCV CONNECT
Retry count for sending SNMP requests
Retry initial timeout (10ths of a second)
Retry backoff exponent (1=linear, 2=exponential)
Line length for Multiline Messages 38/44
You can change the parameters in the SNMPARMS NCCFLST file. The following
describes each of the keywords and parameters:
Parameter
Description
SNMPQE name
Specifies the virtual machine of the SNMP Query
Engine. The default is SNMPQE. If you change the
name of the SNMP Query Engine virtual machine to
something other than SNMPQE, you must also
change this parameter to match. This value is case
sensitive.
SNMPQERT seconds
Specifies the retry timer (seconds) for IUCV
CONNECT. When SNMPIUCV is started, it tries to
connect to the SNMP Query Engine. If the
connection fails or breaks, SNMPIUCV retries a
connect every n seconds, as specified by this
parameter. The valid range of values is 0 to 9999.
The default is 60 seconds.
SNMPRCNT number
Indicates the retry count for sending SNMP
requests. This is the number of times the SNMP
Query Engine resends an SNMP PDU when no
response was received. If no response was
received after all retries have been exhausted, the
SNMP Query Engine returns a no response error
for the SNMP request. The valid range of values is
0 to 255. The default is 2.
If the request being sent by the SNMP Query
Engine contains an invalid community name, no
response is received. This causes the SNMP Query
Engine to resend the request until the retry count is
exhausted. The agent generates multiple
authenticationFailure traps, one for the initial
request and one for each retry.
SNMPRITO tenths_seconds
Specifies the time-out value for the request in
tenths of a second. After sending an SNMP request
to an agent, the SNMP Query Engine waits the
specified time for a reply. If no reply is received
within the specified time limit, the SNMP Query
Chapter 22. Configuring the SNMP Servers
423
SNMP Servers
Engine resends the request the number of times
specified by SNMPRCNT. If no replies have been
received after all retries have been exhausted, the
SNMP Query Engine returns a NO RESPONSE
error to NetView. The valid range of values is 0 to
255. The default is 10 tenths of a second.
SNMPRETO exp
Indicates the retry back-off exponent. Specifies
whether the time-out value between retries of an
SNMP request is calculated linearly or
exponentially. The valid values are 1 (linear) or 2
(exponential). The default is 2.
For example, if the retry time-out was 1 second,
SNMPRETO of 1 causes a new retry to be sent at
constant one second intervals until all retries have
been sent. SNMPRETO of 2 causes the first retry
to be sent after one second, the second retry 2
seconds later, the third retry 4 seconds later, and so
on until all retries have been sent.
SNMPMMLL length
Indicates the line length for multiline messages 38
through 44. The maximum length is 255. A value of
80 allows the complete text to appear on an 80
character-wide screen. The default length is 80
characters.
Configure the SNMP Daemon
This section describes how to configure the SNMP daemon.
SNMPD
-d trace_level
Operands
-d trace_level
Specifies the level of tracing to be started. Valid values for trace_level are:
0
No tracing (default)
1
Trace snmpd internals
2
Trace external changes from egp
3
Trace incoming requests
4
Trace outgoing responses
5
Trace all levels
TRAP Destination file
TRAPs are unsolicited messages that are sent by an SNMP daemon to an SNMP
network management station. An SNMP TRAP contains information about a
significant network event. The management application running at the management
station interprets the TRAP information sent by the SNMP daemon.
The following TRAPs are generated by an SNMP daemon in TCP/IP.
v COLD_START
424
z/VM: TCP/IP Planning and Customization
SNMP Servers
v AUTHENTICATION_FAILURE
v LINK_UP
v LINK_DOWN
Note: The SNMP daemon Distributed Program Interface (DPI) allows external
processes (which can be running on another host) to generate TRAPs. This
can allow for support of other types of TRAPs. For more information about
SNMP DPI, see TCP/IP Programmer’s Reference.
To use TRAPs, create a file called SNMPTRAP DEST. This file defines a list of
managers to which TRAPs are sent. The following describes how to set up
SNMPTRAP DEST.
1. Create a file called SNMPTRAP DEST. This file must be on a disk accessible to
the SNMP agent, such as TCPMAINT 198.
2. The SNMPTRAP DEST file has a list of managers who are to receive the
TRAPs, and identifies the protocol used to send TRAPs. The format of an entry
in the file is:
manager UDP
The manager is the host that the TRAP is to be sent to. This can be a host
name, or it can be the IP address of the host. The protocol must be UDP. There
should be one entry in the file for each host to which you want to send traps.
3. A SNMPTRAP DEST file might contain the following:
124.34.216.1 UDP
Host1
UDP
4. Comments and sequence numbers are not allowed in the SNMPTRAP DEST
file.
PW SRC File
SNMP agents are accessed by remote network management stations. These
network management stations can be located anywhere in the internet. With the
exception of TCP/IP, the network management stations do not have to be directly
linked to the host running the SNMP agent.
To allow network management stations to send inquires to the SNMP agent, you
must create a file called PW SRC, which defines a list of community names and IP
addresses that can use the services of the SNMP agent.
The community names reside in a master file. This file should be created and kept
at a secure location, accessible only to a system administrator and the SNMP
daemon.
The following describes how to create a community name file.
1. Create the PW SRC file on the TCPMAINT 198 minidisk accessible to the
SNMP daemon.
Note: Since the PW SRC file can contain passwords, you should control
access to this file if security is a concern.
2. The PW SRC file has a list of community names that can use the services of
the SNMP daemon. The format of an entry in this file is:
community_name network_addr network_mask priv_mask
Chapter 22. Configuring the SNMP Servers
425
SNMP Servers
The community_name can be up to 15 characters in length. This value can
contain both upper and lower case letters, however it is case sensitive. In any
requests received by the SNMP agent, the community_name must match the
community_name specified in PW SRC exactly, including correct case.
Note: The priv_mask can be used to start or stop tracing of events in the
SNMP agent. If priv_mask is omitted, the following default mask is
assumed:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
3. The following shows a sample PW SRC file containing multiple entries.
* This is a sample PW SRC file. First we see some sample entries.
* NetView on the mainframe passes Uppercase community names from the
* command line, that is why we have the NVTEST entry as a sample.
*
* community_name netw_addr netw_mask
priv_mask
*
public
0.0.0.0
0.0.0.0
monitor
0.0.0.0
0.0.0.0
NVTEST
0.0.0.0
0.0.0.0
password1
0.0.0.0
0.0.0.0
password2
9.0.0.0
255.0.0.0
password3
9.132.2.4
255.255.255.255
*-----------------------------------------------------------*
* The following community names will turn tracing within the
* agent on/off when a packet arrives with such a community_name.
* This is achieved by specifying an appropriate priv_mask
*
*
/-------> bit 0 (trace on or off)
*
|/------> bit 1 (trace SNMP responses)
*
||/-----> bit 2 (trace SNMP requests)
*
|||/----> bit 3 (trace external)
*
||||/---> bit 4 (trace internal)
*
|||||/--> bit 5 (trace DPI)
*
|||||/--> bit 6 (trace DPI internals)
*
||||||/-> bit 7 (reserved)
*
|||||||
bit 31 (last bit)
*
vvvvvvv
v
* Here, string xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
* is used by the agent to grant access and turn tracing on/off.
* The string represents bits in a 32 bit integer.
* The last bit (if not set to s) means you have access.
* Bit zero turns tracing on (if set to s) or off (if set to x)
* Bits 1-7 specify which tracing is turned on or off.
*
debug_reply
0.0.0.0 0.0.0.0 ssxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_reply_off 0.0.0.0 0.0.0.0 xsxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_req
0.0.0.0 0.0.0.0 sxsxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_req_off
0.0.0.0 0.0.0.0 xxsxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_ext
0.0.0.0 0.0.0.0 sxxsxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_ext_off
0.0.0.0 0.0.0.0 xxxsxxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_int
0.0.0.0 0.0.0.0 sxxxsxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_int_off
0.0.0.0 0.0.0.0 xxxxsxxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_dpi
0.0.0.0 0.0.0.0 sxxxxsxxxxxxxxxxxxxxxxxxxxxxxxxs
debug_dpi_int
0.0.0.0 0.0.0.0 sxxxxxsxxxxxxxxxxxxxxxxxxxxxxxxs
debug_all_dpi
0.0.0.0 0.0.0.0 sxxxxssxxxxxxxxxxxxxxxxxxxxxxxxs
debug_dpi_off
0.0.0.0 0.0.0.0 xxxxxssxxxxxxxxxxxxxxxxxxxxxxxxs
debug_all
0.0.0.0 0.0.0.0 sssssssxxxxxxxxxxxxxxxxxxxxxxxxs
debug_all_off
0.0.0.0 0.0.0.0 xssssssxxxxxxxxxxxxxxxxxxxxxxxxs
debug_off
0.0.0.0 0.0.0.0 xssssssxxxxxxxxxxxxxxxxxxxxxxxxs
4. Comments and sequence numbers are not allowed in the PW SRC file.
426
z/VM: TCP/IP Planning and Customization
SNMP Servers
The IP address of an incoming SNMP request is ANDed with the first network mask
in the PW SRC file. If the result matches the corresponding network address, the
community names are compared. If the names match the request is accepted,
unless the privilege mask does not specify ’s’ in the last position. If the network
address or community names do not match, the search continues until all entries
have been tested.
If a request from IP address 9.34.22.122 with community name password2 is
received, IP address 9.34.22.122 is ANDed with 255.0.0.0 because that is the first
entry found in the table. The first four entries are skipped (the community name
does not match.) The result is 9.0.0.0, which equals the specified network address
for c_name1. If this incoming request has specified a community name of password2,
then the request is accepted. In password3, only requests from host 9.132.2.4 are
accepted, providing that the community names match.
If the IP address ANDed with the network mask does not match a desired_network,
or if the community_names do not match, an AUTHENTICATION_FAILURE TRAP is
sent, provided that a destination entry exists in the SNMPTRAP DEST file.
A desired_network and network mask of all zeros allows anyone with the correct
community_name to make requests.
Installation Steps
SNMP requires NetView as the client of the local host.
SNMP Command Processor and SNMPIUCV on NetView
This section describes how to install the SNMP Command Processor and
SNMPIUCV.
1. If necessary, move the SNMPLIB LOADLIB to the NetView 191 disk or any
other disk to which NetView has access, from the server code disk, TCPMAINT
591, where the file was shipped.
2. Add this load library to the GLOBAL LOADLIB statement in the NetView start-up
procedure. This file has a file type of GCS. For example, the following is a
typical GLOBAL command.
GLOBAL LOADLIB STATMON NLDM NPDA PROPMX USER
Now change it to:
GLOBAL LOADLIB STATMON NLDM NPDA PROPMX SNMPLIB USER
As an alternative, you can add the SNMP and SNMPIUCV load modules to the
USER LOADLIB.
3. Add a TASK statement to the DSIDMN NCCFLST file.
TASK
MOD=SNMPIUCV,TSKID=SNMPIUCV,PRI=5,INIT=Y
If you code INIT=N on the TASK statement for SNMPIUCV, the NetView
operator must start the task manually with the following command.
START TASK=SNMPIUCV
4. Add the following statement to the DSICMD NCCFLST file.
SNMP
CMDMDL
MOD=SNMP,ECHO=Y,TYPE=R,RES=N
If you issue many SNMP commands, you can use RES=Y to make the command
processor resident.
Chapter 22. Configuring the SNMP Servers
427
SNMP Servers
5. If necessary, put all the DSISNMnn NCCFLST files on the NetView 191 disk (or
a disk accessible to NetView) from the server code disk, TCPMAINT 591, where
the files were shipped. These are the externalized messages.
6. If necessary, put the SNMPARMS NCCFLST file on the NetView 191 disk or
any other disk to which NetView has access, from the server code disk,
TCPMAINT 591, where the file was shipped. These are the SNMP startup
parameters. You can change these parameters if the default values are not
acceptable. For more information, see “SNMPIUCV Initialization Parameters” on
page 423.
SNMP Daemon
This section describes how to install the SNMP agent.
1. Ensure that the TCPIP DATA file and, optionally, the HOSTS ADDRINFO and
HOSTS SITEINFO files are on a disk accessible to the SNMPD virtual machine.
2. Ensure that the SNMPTRAP DEST file (see “TRAP Destination file” on
page 424), and the PW SRC file (see “PW SRC File” on page 425) are on a
disk accessed by SNMPD.
3. Update the DTCPARMS file. For more information, see “Step 2: Update the
DTCPARMS File for SNMPQE and SNMPD” on page 419.
4. Add SNMPD to the AUTOLOG, PORT, and OBEY statements in the PROFILE
TCPIP file. For more information, see “Step 1: Update PROFILE TCPIP” on
page 418.
5. Add the SYSCONTACT and SYSLOCATION statements in the PROFILE TCPIP
file. For more information, see “Step 1: Update PROFILE TCPIP” on page 418.
6. If IBM Enterprise-specific MIB variables are to be obtained from an attached
3172, add the optional NETMAN keyword to the DEVICE statement for the
3172.
428
z/VM: TCP/IP Planning and Customization
Chapter 23. Configuring the SSL Server
The Secure Socket Layer (SSL) server provides the processing that allows secure
(encrypted) communication between a remote client and a TCP/IP server (in this
context, known as the application server). The application server must be listening
on a port identified as SECURE by your installation, and the remote client must
support the SSL protocol according to RFC 2246.
Under SSL protocol, the application server is always authenticated. To participate in
an SSL session, an application server must provide a certificate to prove its identity.
Server certificates are issued by Certifying Authorities (CAs), each of which
establishes its own identity by providing a CA certificate. Server certificates and CA
certificates are stored in a certificate database managed by the SSL server.
No changes to an application server are necessary to participate in SSL. The
application server does not perform any data encryption or decryption; this is
handled by the SSL server.
The SSL server runs on the Linux operating system, which runs as a guest in the
SSL server virtual machine. Thus, a suitably configured Linux kernel and file system
must be installed on your z/VM system. Detailed information about Linux
requirements and preparation for use by the SSL server are available at the TCP/IP
Feature home page on the World Wide Web.
To configure the SSL server, you must perform the following steps:
SSL Server Configuration Steps
1. Update the PROFILE TCPIP file.
2. Update the DTCPARMS file for the SSL server.
3. Update the ETC SERVICES file.
4. Set up the certificate database.
Dynamic Server Operation
The SSL server provides an SSLADMIN command interface that allows you to
perform certificate database administration and server administration tasks. See
“Dynamic Server Operation” on page 434.
Overview of an SSL Session
An SSL session consists of the following general processing steps:
1. Connect
A remote client sends a connection request for an application server. If the
application server is listening on a secure port, the TCP/IP (stack) server sends
this request to the SSL server. The TCP/IP server also sends a label that
identifies the certificate to be used for the secure connection, as well as the
socket addresses of the client and the application server. The SSL server
accepts the connection from the client and sends a connection request to the
application server.
The SSL session is maintained as two separate connections: the connection
from the remote client to the SSL server, and the connection from the SSL
© Copyright IBM Corp. 1987, 2002
429
SSL Server
server to the application server. The intervention of the SSL server is
transparent to the client and the application server; to them, it seems that they
are communicating directly with each other.
2. Handshake
After its connection request is accepted, the client initiates a handshake protocol
to produce the cryptographic parameters for the session. The SSL server
(representing the application server) responds to the handshake and sends the
application server’s certificate to the client.
Clients that make use of SSL services generally have the certificates associated
with the Well Known CAs in their certificate databases. The client compares the
“signature” on the application server’s certificate with the appropriate CA
certificates to verify the authenticity of the server.
The client and the SSL server then agree on a protocol version, select
cryptographic algorithms (known as cipher suites), and use asymmetric
(public-key) encryption techniques to generate shared secrets. From the shared
secrets, the SSL server and the client generate the symmetric (private) keys to
be used for the encryption and decryption of data sent on the connection.
3. Data transmission
When the handshake completes, the client sends encrypted data over the
network. The SSL server receives the encrypted data from the client, decrypts it,
and sends it to the application server. The application server responds by
sending unencrypted data to the SSL server. The SSL server receives the
unencrypted data from the application server, encrypts it, and sends it to the
client.
4. Close
When a close request is received from either the client or the application server,
the SSL server sends a close request to the other party and cleans up the
connection.
Step 1: Update PROFILE TCPIP
Include the SSL server virtual machine user ID in the AUTOLOG statement of the
TCPIP server configuration file. The SSL server is then started automatically when
TCPIP is initialized. The IBM default user ID for this server is SSLSERV. Verify that
the following statement has been added to the PROFILE TCPIP file:
AUTOLOG
SSLSERV
0
;
SSL Server
Note: If you do not want the SSL server automatically started, do not include the
AUTOLOG statement in the file.
The IBM-supplied PROFILE STCPIP file contains the following statement to reserve
TCP port 9999 for the SSL server:
PORT
9999 TCP SSLSERV
;
SSL Server - administration
Verify that a port statement for the SSL server is included in your TCPIP server
configuration file and that this port matches the SSL administration port defined in
the ETC SERVICES file. See “Step 3: Update ETC SERVICES” on page 433.
Use the OBEY statement to list the privileged users (such as TCPMAINT) who can
issue SSLADMIN commands to administer the SSL server. Verify that an OBEY
statement is included in your TCPIP server configuration file:
430
z/VM: TCP/IP Planning and Customization
SSL Server
OBEY
TCPMAINT
ENDOBEY
Step 2: Update the DTCPARMS File
When the SSL server is started, the TCP/IP server initialization program searches
specific DTCPARMS files for configuration definitions that apply to this server. Tags
that affect the SSL server are:
:Nick.SSLSERV
:Nick.ssl
:Type.server
:Class.ssl
:Type.class
:Name.SSL daemon
:Command.VMSSL
:Diskwarn.YES
:Parms.
If more customization is needed than what is available in the DTCPARMS file, a
server profile exit can be used.
For more information about the DTCPARMS file, customizing servers, and server
profile exits, see Chapter 5, “General TCP/IP Server Configuration” on page 31.
Note: You should modify the DTCPARMS file for the SSL server if you want to
override the default VMSSL command operands.
VMSSL Command
VMSSL services are initiated using the VMSSL command:
VMSSL
MAXUSERS 100
CACHESIZE 512
CACHELIFE 24
MAXUSERS maxusers
CACHESIZE cachesize
CACHELIFE cachelife
EXEMPT cipher_suite
NOTRACE
TRACE
NORMAL
CONNECTIONS
FLOW
ALL
NODATA
DATA
ip_address
:port
ip_address:port
Specify VMSSL command operands as :Parms tag start-up parameters in your
DTCPARMS file.
Operands
MAXUSERS maxusers
specifies the maximum number of concurrent secure sessions to be supported.
The default is 100.
CACHESIZE cachesize
specifies the maximum number of cache entries the SSL server is to maintain.
Each entry is the result of a handshake agreement between the SSL server and
a client. The minimum cachesize is 0, the maximum is 4095, and the default is
512.
Chapter 23. Configuring the SSL Server
431
SSL Server
CACHELIFE cachelife
specifies the number of hours that a cache entry is valid, after which the entry
expires and can no longer be used. The minimum cachelife is 0 and the
maximum is 24, which is also the default.
EXEMPT cipher_suite
specifies a cipher suite that should not be used by the SSL server. The
possible values for cipher_suite are:
Value
Type of Encryption
RC4_128_MD5
Stream cipher, 128-bit key size, MD5 hash
RC4_128_SHA
Stream cipher, 128-bit key size, SHA hash
DES_56_SHA
Block cipher, 56-bit key size, SHA hash
RC4_56_SHA
Stream cipher, 56-bit key size, SHA hash
RC4_40_MD5
Stream cipher, 40-bit key size, MD5 hash
RC2_40_MD5
Block cipher, 40-bit key size, MD5 hash
NULL
No encryption
NOTRACE
specifies that all tracing is turned off. This is the default.
TRACE
specifies that tracing is to be performed.
NORMAL
specifies that a trace entry is recorded to indicate a successful connection. This
is the default if TRACE is specified.
CONNECTIONS
specifies that a trace entry is recorded for connection state changes and
handshake results.
NODATA
specifies that no data is displayed for send and receive trace entries. This is the
default if CONNECTIONS is specified.
DATA
specifies that the first 20 bytes of data are displayed for send and receive trace
entries.
FLOW
specifies that flow of control and system activity are traced.
ALL
specifies that tracing is done for all connections. This is the default if TRACE is
specified.
ip_address
specifies that tracing is done only for activity associated with this IP address.
:port
specifies that tracing is done only for activity associated with this port.
Usage Notes
1. DTCPARMS file changes become effective only when the SSL server is
restarted.
2. If the MAXUSERS limit is reached, new connection requests for a secure port
are rejected.
432
z/VM: TCP/IP Planning and Customization
SSL Server
3. If the CACHESIZE limit is reached, new entries are not saved in cache.
4. For information about adjusting the CACHESIZE and CACHELIFE settings, see
“Using the Server Cache” on page 438.
5. Cipher suite NULL provides no security. Exempting all the cipher suites except
NULL means that no data is encrypted.
6. The SSL server will not start if all the cipher suites are exempted.
7. All IP addresses must be specified in dotted decimal format. If you want to
include a port number with an IP address, use the format: ip_address:port.
8. Certain informational messages are always displayed at the SSL server console
for:
v SSLADMIN commands
v Potential security breaches, such as a message digest not matching the
message during the handshake
9. For information about trace output, see the z/VM: TCP/IP Level 430 Diagnosis
Guide.
Step 3: Update ETC SERVICES
The ETC SERVICES file lists the Well Known Port Numbers as listed in RFC 1700,
along with IBM overrides and extensions. The IBM-supplied ETC SERVICES file
contains the following statement in the extensions section to define TCP port 9999
for SSL administration:
ssladmin
9999/tcp
# administration port
Verify that a similar statement is included in your ETC SERVICES file and that the
port matches the port reserved for the SSL server in the PROFILE TCPIP file. See
“Step 1: Update PROFILE TCPIP” on page 430.
Step 4: Set Up the Certificate Database
The following steps describe how to set up the certificate database. After you
complete these steps, you are ready to receive connection requests for your secure
servers.
Step 4a: Start the SSL Server
The SSL server must be running and TCPMAINT 591 must be accessed before you
can issue SSLADMIN commands. If the server has not been autologged, you can
start it manually. See “Starting and Stopping TCP/IP Servers” on page 46.
Starting the SSL server the first time creates the certificate database. The database
is preloaded with some Well Known CA certificates. To see what certificates are
preloaded, issue the SSLADMIN QUERY command:
ssladmin query certificate *
Step 4b: Populate the Certificate Database
You need to obtain certificates for the application servers that will be designated as
SECURE (listening on secure ports). When an SSL connection is established, the
client expects to receive a server certificate during the handshake that authenticates
the application server. The server certificate contains information about the
application server, such as its fully-qualified name and its public key. The certificate
is generally signed by a CA.
Chapter 23. Configuring the SSL Server
433
SSL Server
Before populating the certificate database with real certificates, you may wish to
conduct some tests of the SSL environment. There is a type of certificate called a
self-signed certificate that you can create for this purpose. See “Creating a
Self-Signed Certificate” on page 436.
To begin populating the certificate database with real certificates:
1. Create a certificate request for each secure server. See “Requesting a Server
Certificate” on page 435.
2. When the CA returns the server certificate, store it in the certificate database.
See “Storing a Certificate in the Database” on page 436.
Step 4c: Designate the Secure Ports
You must update the TCP/IP server configuration file to designate your secure ports
and to associate those ports with the certificates you have stored in the certificate
database.
To designate a secure port for a TCP/IP server, you must include the SECURE
operand on the PORT statement that reserves that port for the server. For more
information, see “PORT Statement” on page 542. When a port is designated as
SECURE, a connection request from a client to the server that listens on that port is
routed by TCPIP to the SSL server. If SECURE is not specified, the port is
considered not secure, and connection requests do not involve SSL processing.
In addition to the SECURE operand, the PORT statement for a secure port must
include the label of the server certificate to be used for secure connections to that
port.
Note: For testing purposes, you can specify the label of a self-signed certificate
instead of a server certificate.
To verify that a certificate with this label resides in the certificate database, issue
the SSLADMIN QUERY command:
ssladmin query certificate label
After you designate the secure ports in the TCP/IP server configuration file, you
must activate these changes in one of the following ways:
v To make the changes permanent, you must restart the TCP/IP (stack) server.
v To activate the changes dynamically, use the OBEYFILE command. For more
information, see “OBEYFILE Command” on page 571.
Dynamic Server Operation
The SSL server provides an SSLADMIN command interface that allows you to
perform certificate database administration and server administration tasks. Detailed
descriptions of the SSLADMIN commands available for use are provided later,
beginning with the “SSLADMIN DELETE Command” on page 439.
|
|
|
Certificate Database Administration
This section describes how to do various certificate database administration tasks,
such as requesting a server certificate and storing a certificate in the database. It
also describes the contents of the X509INFO file, which provides input for some
SSLADMIN commands.
434
z/VM: TCP/IP Planning and Customization
SSL Server
Notes:
1. The SSL server must be running and TCPMAINT 591 must be accessed before
you can issue SSLADMIN commands.
2. The SSLADMIN commands work with a copy of the certificate database on disk.
Starting the SSL server loads the certificate database from disk into memory.
When you make changes to the certificate database, such as storing or deleting
a certificate, those changes do not go into effect until you restart the SSL server
to load the updated certificate database into memory.
X509INFO File
The label X509INFO file is a CMS file that you create to specify information used as
input when requesting a certificate for an application server (SSLADMIN REQUEST
or SSLADMIN SELF command). The file name of this file will be used as the label
that is associated with the certificate request, and later the certificate itself, in the
certificate database. You will specify this label on the PORT statements in the
TCP/IP configuration file that define the secure ports for this application server.
The format of an X509INFO file is:
Common common_name
Organization organization
Unit unit
Locality city
State state
Country country
Each keyword and value pair must be specified on a separate line. If the first
nonblank character in a line is an asterisk (*), the line is treated as a comment.
Blank lines and unidentified keywords are ignored.
Note: A forward slash (/) is not allowed on any line in the X509INFO file. A
backward slash (\) is treated as an escape character.
Certain lines in this file are required and others may be optional (as determined by
the CA). The lines specify the following information:
Common
(Required) Fully-qualified domain name of the application server.
Organization
(Required) Organization that owns the domain name.
Unit
(Optional) Division within the organization.
Locality
(Optional) City in which the organization is located.
State
(Optional) State in which the organization is located.
Country
(Required) Two-character ISO-format code identifying the country in
which the organization is located.
If this line is omitted, or if the keyword is specified without a value,
the value defaults to US.
Requesting a Server Certificate
An application server cannot participate in an SSL session unless a certificate for
the server is in the certificate database. When an SSL session is being established,
the SSL server sends the server certificate to the client (on behalf of the application
server) during the handshake.
To obtain a server certificate:
1. Create a label X509INFO file containing information about the application
server.
Chapter 23. Configuring the SSL Server
435
SSL Server
See “X509INFO File” on page 435 for information about the structure of this file.
Consult with the CA you intend to use about what information they require in the
certificate request and for instructions on how to send the certificate request.
2. Issue the SSLADMIN REQUEST command to create the certificate request:
ssladmin request label keysize fm
For more information, see “SSLADMIN REQUEST Command” on page 446.
3. Send the certificate request to the CA.
Storing a Certificate in the Database
In response to a certificate request, the CA returns a server certificate that you must
store in the certificate database. The CA may also send one or more CA
certificates. You must store the CA certificates in the certificate database before you
store the server certificate, because the CA certificates are used to verify the server
certificate. If the CA returns only one certificate, it may be a server certificate or it
may be a certificate chain consisting of a server certificate and one or more CA
certificates.
To store a certificate in the certificate database:
1. Receive the certificate into a CMS file with a file type of X509CERT.
If the CA returns more than one certificate, receive each certificate into a distinct
X509CERT file.
2. Issue the SSLADMIN STORE command to store the certificate in the certificate
database, specifying the file name of the X509CERT file that contains the
certificate to be stored:
v If you have received any separate CA certificates, issue the SSLADMIN
STORE command with the CA operand for each CA certificate, giving each
CA certificate a unique label:
ssladmin store fn ca label
Note: The label is case-sensitive and cannot exceed 200 characters.
v After you have stored all the CA certificates, or if you have received only one
certificate from the CA, issue the SSLADMIN STORE command with the
SERVER operand to store the server certificate:
ssladmin store fn server
The server certificate is given the label associated with the corresponding
certificate request that already resides in the certificate database. If the
certificate being stored is actually a certificate chain, the SSL server stores
each CA certificate with a label based on the certificate owner’s common
name and organization and then stores the server certificate.
For more information, see “SSLADMIN STORE Command” on page 448.
To see what CA certificates have been stored and under what names, issue the
SSLADMIN QUERY command:
ssladmin query cert *
3. Restart the SSL server to load the updated certificate database into memory.
Creating a Self-Signed Certificate
For testing purposes, you can create a self-signed certificate that serves as both a
server certificate and a CA certificate. Because the certificate is signed with the
application server’s private key instead of by a CA, it has no real security or
authentication value.
436
z/VM: TCP/IP Planning and Customization
SSL Server
To create a self-signed certificate:
1. Create a label X509INFO file containing information about the application
server.
See “X509INFO File” on page 435 for information about the structure of this file.
2. Issue the SSLADMIN SELF command to create the self-signed certificate:
ssladmin self label keysize fm
For more information, see “SSLADMIN SELF Command” on page 447.
The self-signed certificate is automatically stored in the certificate database.
3. Send the self-signed certificate to the client.
The client must have a copy of the self-signed certificate before it sends a
connection request to initiate a test of the SSL environment. During the
handshake, the SSL server sends the same self-signed certificate to the client
as a server certificate. Because the self-signed certificate is not signed by a CA,
the client cannot use a real CA certificate to verify it. Therefore, the client uses
the previously-sent self-signed certificate as a CA certificate to verify the
self-signed certificate sent during the handshake.
Consult the documentation for the client application in use for information on
how that client handles self-signed certificates.
4. Designate a secure port for testing purposes. For instructions, see “Step 4c:
Designate the Secure Ports” on page 434. Make sure that the certificate label
you specify on the PORT statement is the label of the self-signed certificate.
5. Restart the SSL server to load the updated certificate database into memory.
Now you are ready to receive a test connection request from the client.
Getting a Copy of a Certificate from the Database
Certificates and certificate requests cannot be examined once they are stored in the
certificate database. To get a copy of a certificate or certificate request from the
database and store it in a CMS file, issue one of the following SSLADMIN EXPORT
commands:
ssladmin export fn fm certificate label
ssladmin export fn fm request label
For more information, see “SSLADMIN EXPORT Command” on page 440.
Deleting a Certificate or Request from the Database
If you want to remove a certificate or certificate request from the certificate
database, use the SSLADMIN DELETE command. For more information, see
“SSLADMIN DELETE Command” on page 439.
For example, suppose you created a self-signed certificate for testing, and now you
want to send a certificate request to a CA for that same server. You probably want
to use the same X509INFO input file. However, if you want to use the same label
(the file name of the X509INFO file) for the certificate request, you must first delete
the self-signed certificate from the database, because all labels in the database
must be unique:
ssladmin delete certificate label
Remember to enter the label exactly as it is specified in the certificate database. If
you are not sure how it is specified in the database, use the SSLADMIN QUERY
command to get a list of all the labels:
ssladmin query certificate *
Chapter 23. Configuring the SSL Server
437
SSL Server
Note: The deleted certificate or certificate request remains active until you restart
the SSL server to load the updated database into memory.
Rebuilding the Certificate Database
The objects in the certificate database are protected by a random internal
password. You do not need to use or know this internal password to perform
certificate database administration tasks. However, if you feel that the security of
the database has been compromised, you can rebuild the database and force the
generation of a new random password. Issue the SSLADMIN REGENERATE
command:
ssladmin regenerate
SSL Server Administration
This section describes how to do various SSL server administration tasks, such as
starting or stopping the server and turning tracing on or off.
Note: The SSL server must be running and TCPMAINT 591 must be accessed
before you can issue SSLADMIN commands.
Starting the Server
The SSL server can be started in the same manner as other TCP/IP servers. For
more information, see “Starting and Stopping TCP/IP Servers” on page 46.
Stopping the Server
To stop the SSL server, issue the SSLADMIN STOP command:
ssladmin stop
Using the Server Cache
It is possible to reuse the security parameters that were negotiated with a client
during a previous secure session. Resuming a previously negotiated session cuts
down on network traffic and CPU time and is therefore desirable. Resumption of a
session can be initiated only by the client.
If the client wishes to resume a session, the client supplies the session ID to be
resumed. If the SSL server finds this ID in the cache, it returns the same session ID
to the client. Each side sends an encrypted message as a test. If this test is
successful, no further negotiations are needed, and data flow begins.
If the SSL server cannot find the requested session ID in the cache, the entry may
have expired (exceeded the CACHELIFE setting), or the entry was not put into the
cache because the cache was full (exceeded the CACHESIZE setting). These
settings are controlled by VMSSL operands.
You can check on the SSL server cache usage by issuing the SSLADMIN QUERY
CACHE command. If the response from the command shows a large number of
new sessions and a small number of resumed sessions, you might consider
increasing the CACHELIFE or CACHESIZE setting, or both.
Tracing Server Activities
To begin tracing SSL server activities when the server starts, use the TRACE
operand on the VMSSL command:
v You can specify TRACE as a VMSSL startup parameter in the DTCPARMS file.
Tracing will begin each time the server is autologged until you modify the
DTCPARMS file again to remove the TRACE startup parameter. See “Step 2:
Update the DTCPARMS File” on page 431.
438
z/VM: TCP/IP Planning and Customization
SSL Server
v You can specify TRACE on the VMSSL command when manually starting the
server while logged on to the SSL server virtual machine. See “VMSSL
Command” on page 431.
To dynamically start or stop tracing SSL server activities while the SSL server is
running, use the SSLADMIN TRACE/NOTRACE command. See “SSLADMIN
TRACE/NOTRACE Command” on page 450.
For information about trace output, see the z/VM: TCP/IP Level 430 Diagnosis
Guide.
SSL Server Administration Commands
Table 27 provides a summary of the SSL administration commands.
Table 27. SSL Administration Commands
Command
Description
Page
SSLADMIN DELETE
Removes a certificate or certificate request from the certificate database.
439
SSLADMIN EXPORT
Retrieves a certificate or certificate request from the certificate database
and store it in a CMS file.
440
SSLADMIN LOG
Obtains the message log from the SSL server. The message log contains
all messages written by the SSL server, as well as any output generated
by the SSLADMIN TRACE command.
441
SSLADMIN QUERY
Displays information about the SSL server, or about certificates or
certificate requests in the certificate database.
441
SSLADMIN REGENERATE
Rebuilds the certificate database. A new random internal password is
generated and all the objects in the certificate database are
password-encoded with this new password.
446
SSLADMIN REMOVE
Deletes the certificate database. For example, you might want to refresh
the database after testing. A new certificate database is immediately
created, preloaded with some Well Known CA certificates.
446
SSLADMIN REQUEST
Creates a certificate request for an application server.
446
SSLADMIN SELF
Creates a self-signed certificate.
447
SSLADMIN STOP
Shuts down the SSL server.
448
SSLADMIN STORE
Stores a server certificate or CA certificate in the certificate database.
448
SSLADMIN
TRACE/NOTRACE
Starts or stops tracing SSL server activities while the server is running.
450
SSLADMIN DELETE Command
Use the SSLADMIN DELETE command to remove a certificate or certificate request
from the certificate database.
SSLadmin DELete
CERTificate
REQuest
label
Operands
CERTificate
indicates that you are deleting a certificate.
Chapter 23. Configuring the SSL Server
439
SSL Server
REQuest
indicates that you are deleting a certificate request.
label
is the label associated with this certificate or certificate request in the certificate
database.
Usage Notes
1. You must enter the label of the certificate or certificate request exactly as it is
specified in the certificate database. Labels are case sensitive and may have
imbedded blanks. Use the SSLADMIN QUERY command to determine how the
label is specified in the certificate database.
2. The deleted certificate or certificate request remains active until you restart the
SSL server to load the updated certificate database into memory.
SSLADMIN EXPORT Command
Use the SSLADMIN EXPORT command to retrieve a certificate or certificate
request from the certificate database and store it in a CMS file.
SSLadmin EXPORT fn
fm
CERTificate
label
REQuest
Operands
fn is the name to be used as the file name of the CMS file where the certificate or
certificate request is stored:
v A certificate is stored in a file named fn X509CERT.
v A certificate request is stored in a file named fn CERTREQ.
fm is the file mode of the read/write disk or directory where the output file is to be
written. If fm is not specified, the output file is written to the first read/write disk
or directory in the CMS search order.
CERTificate
indicates that you are retrieving a certificate.
REQuest
indicates that you are retrieving a certificate request.
label
is the label associated with this certificate in the certificate database.
Usage Notes
1. If you are retrieving a certificate, the fn X509CERT file must not already exist on
any accessed disk or directory.
2. If you are retrieving a certificate request, the fn CERTREQ file must not already
exist on any accessed disk or directory.
3. The certificate or certificate request is stored in Base64-encoded format.
4. You must enter the label of the certificate or certificate request exactly as it is
specified in the certificate database. Labels are case sensitive and may have
440
z/VM: TCP/IP Planning and Customization
SSL Server
imbedded blanks. Use the SSLADMIN QUERY command to determine how the
label is specified in the certificate database.
SSLADMIN LOG Command
Use the SSLADMIN LOG command to obtain the message log from the SSL server.
The message log contains all messages written by the SSL server, as well as any
output generated by the SSLADMIN TRACE command.
SSLadmin LOG
Usage Notes
1. The output is written to a file, SSLADMIN OUTPUT, on the first read/write disk
or directory in the CMS search order.
2. If the file SSLADMIN OUTPUT already exists, it is overwritten.
SSLADMIN QUERY Command
Use the SSLADMIN QUERY command to display information about the SSL server,
or about certificates or certificate requests in the certificate database.
SSLadmin
Query STATus
Query
STATus
CACHE
CERTificate
REQuest
SESSions
*
label
Operands
STATus
requests information about SSL server status. This is the default.
CACHE
requests information about SSL server cache usage.
CERTificate
requests information about certificates in the certificate database..
REQuest
requests information about certificate requests in the certificate database.
label
is the label associated with a specific certificate or certificate request you want
information about.
Specifying an asterisk (*) instead of a label retrieves a list of the labels of all the
certificates or certificate requests contained in the certificate database. This is
the default.
Chapter 23. Configuring the SSL Server
441
SSL Server
SESSions
requests information about secure sessions.
Example
SSLADMIN QUERY STATUS
When you request information about SSL server status, an information block is
returned like this example:
Maximum number of sessions: 100
Number of active sessions: 4
Administration port: 9999
Cipher_suites included: RC4_40_MD5 RC2_40_MD5 NULL
Cipher_suites exempted: RC4_128_MD5 RC4_128_SHA DES_56_SHA RC4_56_SHA
Trace Settings:
Normal: OFF
Connections: ON
Data: ON
Flow: OFF
Address: 255.255.255.255:0
Connection: 0
The fields in this block supply the following information:
Maximum number of sessions
Maximum number of secure sessions the SSL server supports.
Number of active sessions
Current number of secure sessions.
Administration port
SSL administration port being used.
Cipher_suites included
Cipher suites the SSL server is allowed to use.
Cipher_suites exempted
Cipher suites the SSL server is not allowed to use.
Trace settings
Current SSL trace settings.
Note: The Data setting (shown in the example) is displayed only when the
setting for Connections is ON.
Example
SSLADMIN QUERY CACHE
When you request information about SSL server cache usage, an information block
is returned like this example:
Cache entry life: 24
Total number of cache elements:
Number of new sessions: 3
Number of resumed sessions: 1
20
The fields in this block supply the following information:
Cache entry life
Number of hours that an entry can exist in the cache before it expires and
can no longer be used.
442
z/VM: TCP/IP Planning and Customization
SSL Server
Total number of cache entries
Maximum number of entries allowed in the cache.
Number of new sessions
Total number of secure sessions based on new handshake agreements
between the SSL server and clients (that is, not resumed from cache
entries) since the SSL server was started.
Number of resumed sessions
Total number of secure sessions resumed from cache entries since the SSL
server was started.
Note: If this response shows a large number of new sessions and a small number
or resumed sessions, you might consider increasing the CACHELIFE or
CACHESIZE setting (VMSSL operands). For more information, see “Using
the Server Cache” on page 438.
Example
SSLADMIN QUERY CERTIFICATE label
When you request information about a specific certificate, an information block is
returned like this example:
Certificate information:
Label:
Version:
Serial number:
Issued by:
Belongs to:
Effective dates:
Type:
Key Size:
MYCERT
3
123458493939
Class 1 Public Primary Certification Authority
VeriSign, Inc.
US
GDLVM7.ENDICOTT.IBM.COM
IBM Corporation
US
Aug 14 1999 to Aug 13 2000
Server
512
The fields in this block supply the following information:
Label Label associated with the certificate in the certificate database.
Version
X509 certificate version.
Serial number
Identifying number assigned to the certificate by the issuer.
Issued by
Information about the organization that signed the certificate.
Belongs to
Information about the entity that is validated by the certificate.
Effective dates
Period during which the certificate is valid.
Type
Type of certificate: Server or CA.
Note: A self-signed certificate is identified as a server certificate.
Chapter 23. Configuring the SSL Server
443
SSL Server
Key Size
Number of bits in the public key.
Example
SSLADMIN QUERY CERTIFICATE *
When you request a list of the labels of all the certificates in the certificate
database, the list is returned like this example:
Labels are:
1
2
3
4
5
6
7
8
9
10
11
—
—
—
—
—
—
—
—
—
—
—
MYCERT
Thawte Personal Premium CA
Thawte Personal Freemail CA
Thawte Personal Basic CA
Thawte Premium Server CA
Thawte Server CA
Verisign Test CA Root Certificate
RSA Secure Server Certification Authority
Verisign Class 1 Public Primary Certification Authority
Verisign Class 2 Public Primary Certification Authority
Verisign Class 3 Public Primary Certification Authority
Disk usage 2%:
156 used
9044 available (1k-blocks)
The returned list includes the labels for server certificates, CA certificates, and
self-signed certificates. The Disk usage line following the list indicates the current
usage of the certificate database.
Note: Labels are case-sensitive and must be specified exactly as displayed,
including imbedded blanks, in other SSLADMIN commands (such as
SSLADMIN QUERY CERTIFICATE label).
Example
SSLADMIN QUERY REQUEST label
When you request information about a specific certificate request, an information
block is returned like this example:
Certificate request information:
Label:
Belongs to:
Key Size:
MYREQ
GDLVM7.ENDICOTT.IBM.COM
IBM Corporation
US
512
The fields in this block supply the following information:
Label Label associated with the certificate request in the certificate database.
Belongs to
Information about the entity that is validated by the certificate.
Key Size
Number of bits in the public key.
Example
SSLADMIN QUERY REQUEST *
444
z/VM: TCP/IP Planning and Customization
SSL Server
When you request a list of the labels of all the certificate requests in the certificate
database, the list is returned like this example:
Labels are:
1
— MYREQ
Disk usage 2%:
156 used
9044 available (1k-blocks)
The Disk usage line following the list indicates the current usage of the certificate
database.
Note: Labels are case-sensitive and must be specified exactly as displayed,
including imbedded blanks, in other SSLADMIN commands (such as
SSLADMIN QUERY REQUEST label).
Example
SSLADMIN QUERY SESSIONS
When you request information about secure sessions, an information block is
returned like this example:
Client_Socket_Address
--------------------9.130.57.82:2505
9.130.57.82:2510
9.130.57.82:2516
9.130.57.82:2509
Server_Socket_Address
--------------------9.130.249.45:423
9.130.249.45:423
9.130.249.45:423
9.130.249.45:423
Cipher
-----RC4_40_MD5
RC4_40_MD5
RC4_40_MD5
RC4_40_MD5
Label
----MAJCERT2
MAJCERT2
MAJCERT2
MAJCERT2
Each line in the information block represents a secure session. A secure session
consists of two connections: the connection between the remote client and the SSL
server, and the connection between the SSL server and the application server. The
fields in this block supply the following information:
Client_Socket_Address
Address of the remote client in the secure session.
Server_Socket_Address
Address of the application server in the secure session.
Cipher
Cipher suite used for encrypted transmissions between the client and the
SSL server.
Label Label of the certificate used to authenticate the application server.
Usage Notes
1. Information about the certificate database returned by this command does not
reflect changes to the certificate database on disk that have not been loaded
into memory. Restarting the SSL server loads the certificate database from disk
into memory.
Chapter 23. Configuring the SSL Server
445
SSL Server
SSLADMIN REGENERATE Command
Use the SSLADMIN REGENERATE command to rebuild the certificate database. A
new random internal password is generated and all the objects in the certificate
database are password-encoded with this new password.
SSLadmin REGENerate
SSLADMIN REMOVE Command
Use the SSLADMIN REMOVE command to delete the certificate database. For
example, you might want to refresh the database after testing. A new certificate
database is immediately created, preloaded with some Well Known CA certificates.
SSLadmin REMOVE
Usage Notes
1. Certificates and certificate requests in the old (removed) certificate database
remain active until you restart the SSL server to load the new database into
memory.
SSLADMIN REQUEST Command
Use the SSLADMIN REQUEST command to create a certificate request for an
application server. As input to the command, you must provide information about
the application server in a CMS file called label X509INFO. The file name of this file
will be used as the label associated with the certificate request, and later the
certificate itself, in the certificate database. For information about the contents of an
X509INFO file, see “X509INFO File” on page 435.
A public/private key pair is created when the certificate request is generated. The
request contains information, including the public key, that identifies the requestor,
and the request is digitally signed with the private key.
The SSLADMIN REQUEST command stores the certificate request in the certificate
database and saves a copy of the request in a CMS file called label CERTREQ.
SSLadmin REQuest label keysize
fm
Operands
label
is the file name of the X509INFO input file. All accessed disks and directories
are searched. This name will also be used as the file name of the CERTREQ
output file.
446
z/VM: TCP/IP Planning and Customization
SSL Server
keysize
is the size, in bits, of the public and private keys that are created. The valid
values are 512 or 1024.
fm is the file mode of the read/write disk or directory where the output file is to be
written.
If fm is not specified:
v If the disk or directory containing the X509INFO input file is accessed
read/write, the CERTREQ file is written to that disk.
v If the disk or directory containing the X509INFO input file is a read-only
extension of a read/write disk or directory, the CERTREQ file is written to that
read/write disk or directory.
v Otherwise, the CERTREQ file is written to the first read/write disk or directory
in the CMS search order.
Usage Notes
1. Consult with the CA about what information they require in the certificate
request and for instructions on how to send the certificate request.
2. The label CERTREQ file must not already exist on any accessed disk or
directory, and label must not already exist as a certificate label in the certificate
database.
3. The certificate request is stored in the CERTREQ file in Base64-encoded
format.
4. Because label is a CMS file name, it is automatically uppercased, and the
corresponding certificate request label is therefore uppercased in the certificate
database.
SSLADMIN SELF Command
Use the SSLADMIN SELF command to create a self-signed certificate. Used
primarily for testing purposes, a self-signed certificate is both a server certificate
and a CA certificate. Because the certificate is signed with the server’s private key
instead of by a CA, it has no real security or authentication value.
As input to the command, you must provide information about the application server
in a CMS file called label X509INFO. The file name of this file will be used as the
label associated with this certificate in the certificate database. For information
about the contents of an X509INFO file, see “X509INFO File” on page 435.
The SSLADMIN SELF command stores the certificate in the certificate database
and saves a copy of the certificate in a CMS file called label X509CERT.
SSLadmin SELF label keysize
fm
Operands
label
is the file name of the X509INFO input file. All accessed disks and directories
are searched. This name will also be used as the file name of the X509CERT
output file.
Chapter 23. Configuring the SSL Server
447
SSL Server
keysize
is the size, in bits, of the public and private keys that are created. The valid
values are 512 or 1024.
fm is the file mode of the read/write disk on which the output file is to be written.
If fm is not specified:
v If the disk or directory containing the X509INFO input file is accessed
read/write, the X509CERT file is written to that disk.
v If the disk or directory containing the X509INFO input file is a read-only
extension of a read/write disk or directory, the X509CERT file is written to
that read/write disk or directory.
v Otherwise, the X509CERT file is written to the first read/write disk or
directory in the CMS search order.
Usage Notes
1. The label X509CERT file must not already exist on any accessed disk or
directory, and label must not already exist as a certificate label in the certificate
database.
2. The certificate is stored in the X509CERT file in Base64-encoded format.
3. Because label is a CMS file name, it is automatically uppercased, and the
corresponding certificate label is therefore uppercased in the certificate
database.
4. Clients that make use of SSL services generally have the certificates associated
with the Well Known CAs in their certificate databases. The clients use those
CA certificates to verify the server certificates sent during the handshake. When
you create a self-signed certificate, you need to send that certificate to the client
so the client can use it to verify the your server certificate. For more information,
see “Creating a Self-Signed Certificate” on page 436.
5. You cannot use the self-signed certificate until the SSL server is restarted to
load the updated certificate database into memory.
SSLADMIN STOP Command
Use the SSLADMIN STOP command to shut down the SSL server.
SSLadmin STOP
Usage Notes
1. When the shutdown is complete, a disabled wait PSW is loaded. It is then safe
to restart the server.
SSLADMIN STORE Command
Use the SSLADMIN STORE command to store a server certificate or CA certificate
in the certificate database. You must first receive the certificate into a CMS file with
a file type of X509CERT before you issue the SSLADMIN STORE command. The
file name of the X509CERT file for a server certificate must match the
corresponding certificate request in the certificate database.
448
z/VM: TCP/IP Planning and Customization
SSL Server
SSLadmin STORE fn
SERver
CA label
Operands
fn is the file name of the X509CERT input file. All accessed disks and directories
are searched.
SERver
indicates that you are storing a server certificate. This is the default.
CA
indicates that you are storing a CA certificate.
label
is the label to be associated with this CA certificate in the certificate database.
This label can be any unique string up to 200 characters. It cannot begin or end
with a blank, but it may contain imbedded blanks. It is case-sensitive.
Usage Notes
1. In response to a single certificate request, the CA may return one or more CA
certificates along with the server certificate. Receive each certificate into a
distinct X509CERT file. Because the CA certificates are used to verify the server
certificate, you must issue the SSLADMIN STORE command with the CA
operand to store each CA certificate with a unique label before you can issue
the SSLADMIN STORE command with the SERVER operand to store the server
certificate.
2. When you store a CA certificate, label must not already exist as a label in the
certificate database.
3. If the CA returns only one certificate, it may be a server certificate or it may be
a certificate chain. A certificate chain consists of a server certificate plus one or
more CA certificates. After receiving the certificate into the X509CERT file, issue
the SSLADMIN STORE command with the SERVER operand. If the certificate is
actually a certificate chain, each CA certificate is stored with a label based on
the certificate owner’s common name and organization.
4. When a server certificate is stored, it is given the label associated with the
corresponding certificate request in the certificate database.
5. You cannot use a certificate you have stored until the SSL server is restarted to
load the updated certificate database into memory.
Chapter 23. Configuring the SSL Server
449
SSL Server
SSLADMIN TRACE/NOTRACE Command
Use the SSLADMIN TRACE/NOTRACE command to start or stop tracing SSL
server activities while the server is running.
SSLadmin
TRACE
NORMal
CONNections
NOTRACE
FLOW
ALL
NODATA
DATA
ip_address
:port
ip_address:port
connection_number
Operands
TRACE
specifies that tracing is to be performed.
NORMAL
specifies that a trace entry is recorded to indicate a successful connection. This
is the default if TRACE is specified.
CONNECTIONS
specifies that a trace entry is recorded for connection state changes and
handshake results.
NODATA
specifies that no data is displayed for send and receive trace entries. This is the
default if CONNECTIONS is specified.
DATA
specifies that the first 20 bytes of data are displayed for send and receive trace
entries.
FLOW
specifies that flow of control and system activity are traced.
ALL
specifies that tracing is done for all connections. This is the default if TRACE is
specified.
ip_address
specifies that tracing is done only for activity associated with this IP address.
:port
specifies that tracing is done only for activity associated with this port.
connection_number
specifies that tracing is done only for activity associated with this connection
number.
NOTRACE
specifies that all tracing is turned off.
Usage Notes
1. For information about trace output, see the z/VM: TCP/IP Level 430 Diagnosis
Guide.
450
z/VM: TCP/IP Planning and Customization
SSL Server
2. This command turns tracing on or off for the current SSL server session only. If
TRACE is specified as a VMSSL startup parameter in your DTCPARMS file, and
you issue SSLADMIN NOTRACE to turn tracing off, tracing begins again each
time the SSL server is restarted.
Chapter 23. Configuring the SSL Server
451
SSL Server
452
z/VM: TCP/IP Planning and Customization
Chapter 24. Configuring the TCP/IP Server
The TCPIP virtual machine provides the primary TCP/IP service called the stack.
The stack supports the application programming interfaces and controls the network
interfaces.
|
This chapter describes the statements and commands used to configure the TCP/IP
stack. It also explains how you can dynamically change the configuration using the
IFCONFIG or OBEYFILE commands, as well as how to start and stop the TCP/IP
stack.
To enable basic TCP/IP services, you must perform three activities.
Configuration Steps:
1. Configure the TCPIP virtual machine.
2. Define client system parameters in the TCPIP DATA file.
3. Create a site host table.
Client system parameters are explained in Chapter 3, “Defining the TCP/IP System
Parameters” on page 15. The site host table is described in Chapter 4, “Configuring
the HOSTS LOCAL File” on page 27.
TCPIP Virtual Machine Configuration Process
To configure the TCPIP virtual machine, perform the following activities:
TCPIP Virtual Machine Configuration Steps:
1. Update the DTCPARMS file.
2. Create an initial configuration file.
Step 1: Update the DTCPARMS File
Change the DTCPARMS file to modify the run-time environment for the TCP/IP
stack. You do not have to alter this file unless you want to change either the
standard search order for the TCPIP server or the user ID of the virtual machine
that receives its console log. See “Configuring the DTCPARMS File” on page 34 for
more information about updating and configuring the DTCPARMS file.
Step 2: Create an Initial Configuration File
When the TCPIP virtual machine is started, TCP/IP operation and configuration
parameters are read from an initial configuration file. TCP/IP first searches for file
node_name TCPIP, where node_name is the system node name returned by the CMS
IDENTIFY command. If this file is not found, TCP/IP uses file PROFILE TCPIP
instead.
To customize your system, specify system operation, Telnet, and network
parameters in this file, using the configuration statements listed in Table 29 on
page 466. Complete statement syntax and descriptions are in alphabetical order in
“TCP/IP Configuration Statements” on page 465.
© Copyright IBM Corp. 1987, 2002
453
TCP/IP Server
You can also put many of these statements in a separate file and process it with the
OBEYFILE command to dynamically change the TCP/IP configuration. For more
information about OBEYFILE, see “Changing the TCP/IP Configuration with the
OBEYFILE Command” on page 571. A sample initial configuration file is provided as
PROFILE STCPIP. You can copy it from the server code disk, TCPMAINT 591, to
TCPMAINT 198 and rename it to PROFILE TCPIP or node_name TCPIP. Then you can
modify it to fit your requirements.
Routing Statements
TCP/IP supports static and dynamic routing. You can define static routes for your IP
host using the GATEWAY statement in PROFILE TCPIP. You can also use the
BSDROUTINGPARMS statement to configure RouteD to implement the Routing
Information Protocol (RIPv1 and RIPv2) for dynamic routing. The functions of the
GATEWAY and BSDROUTINGPARMS statements in PROFILE TCPIP are different
in these two environments. Keep the following general rules and recommendations
in mind when configuring RouteD:
v Use the GATEWAY statement in PROFILE TCPIP to define any routes that will
not be used for dynamic routing (static routes). Using static routing is not
recommended, since it prevents routes from being updated dynamically in
response to network topology changes.
v If adjacent routers are not running RIP, define passive routes for them in the
RouteD ETC GATEWAYS file so that RouteD does not modify them; these PASSIVE
routes are then treated as static.
v Use the BSDROUTINGPARMS statement in PROFILE TCPIP to define the
characteristics of each link used for dynamic routing.
If an interface is defined in both the GATEWAY and BSDROUTINGPARMS
statements then RouteD will override any routes that are defined in a GATEWAY
statement.
|
|
|
MPROUTE is yet another way of providing dynamic routing implementing the OSPF
v2 and RIPv1 and RIPv2 protocols. When configuring MPROUTE keep the following
in mind:
v MPROUTE makes use of its own configuration file. Unlike RouteD, MPROUTE
does not make use of the BsdRoutingParms, or GATEWAY configuration
statements. The MTU, subnet mask, and destination address parameters are
configured using the OSPF_Interface, RIP_Interface, and Interface statements
within the MPROUTE configuration file.
Network vs. Host Routing: It is not recommended that you put multiple VM hosts
with more than 1 hop count in the same subnet. This causes router confusion in
selecting which path to choose to reach the destination. This confusion can be
removed by using the -h parameter which enables RouteD to include host routes in
the RIP updates. Another solution for this configuration is with static routes
(GATEWAY statement) and not use RouteD. With the additional host route
information in the RIP updates, the router (9.130.3.10) will use the host routes to
reach the destinations, even though only one subnet route is being assigned to one
of the interfaces.
454
z/VM: TCP/IP Planning and Customization
TCP/IP Server
Rest of
the world
via TR
R0
9.130.3.10
H1
9.130.3.12
H3
9.130.3.15
H2
9.130.3.13
H4
9.130.3.13
Figure 17. Host routing under single subnet.
The recommended practice for configurations involving destinations that are more
than one hop count away from the source is to assign different subnets for each
interface. For example,
R1
9.130.4.12
H1
9.130.4.15
9.130.4.11
Rest of
the world
via TR
R0
9.130.3.10
9.130.5.12
R2
9.130.5.13
H2
9.130.5.14
Figure 18. Subnet assignment for destinations beyond a single hop.
Because VM hosts (routers R1 and R2) are intermediate, they must be assigned
different subnets (or networks). Notice that we have to assign new IP addresses
9.130.4.11 and 9.130.5.12 on R0 to define 9.130.4.x and 9.130.5.x subnets. This is
necessary after expanding the network to reach other hosts. That is, assume that
the original configuration is:
Rest of
the world
via TR
R0
9.130.3.10
H10
9.130.3.12
H20
9.130.3.13
Figure 19. Basic host routing configuration.
This configuration is valid because VM hosts H10 and H20 are not routers, but
hosts at end points from router R0. Now, when H1 and H2 are added to the
configuration, H10 and H20 are no longer hosts by definition, but are routers.
Therefore, in this case, you should assign different subnets to each routing interface
as illustrated in Figure 18.
You can add more hosts in each subnet as long as those hosts do not become
routers. For example, hosts H01, H10, and H21 are added to the configuration
within their subnets:
Chapter 24. Configuring the TCP/IP Server
455
TCP/IP Server
H10
9.130.4.9
H01
9.130.3.9
Rest of
the world
via TR
9.130.4.11
R0
9.130.3.10
R1
9.130.4.12
H11
9.130.4.15
9.130.5.12
R2
9.130.5.13
H20
9.130.5.14
H21
9.130.5.9
Figure 20. Adding hosts to subnetted interfaces.
A good reason for using different subnets for each routing interface is that routers
communicate using network–specific routes, not host–specific routes. According to
the RFCs for RIP, host—specific routing is optional. For this reason, there is no
guarantee that routers in the network will communicate using host routes. That is,
there are routers (for example, Wellfleet, Proteon) that will ignore host routes in the
RIP broadcasts and rely on network–specific routes only. IP addresses, as well as
their subnet masks, must be used with care when defining RIP networks. In
addition, the -h parameter for advertising host routes in RouteD must be used
carefully, and the network configuration must be planned with the assurance that
the adjacent routers will accept the host routes.
Multicast Support
There are three methods that exist for sending data in a network environment:
1. Unicasting
2. Broadcasting
3. Multicasting
In unicasting, a datagram is sent to each host that requests it. A disadvantage of
this is that the number of hosts is limited by the bandwidth on the sender. In
broadcasting, copies of a message are sent to all hosts in the network, whether
they request it or not. A disadvantage to this is that the hosts must be members of
a single subnet.
In multicasting, a message is sent to multiple selected hosts in a group known as a
multicast group. Multicasting provides the following advantages:
v Only one copy of a multicast message is sent over any link in the network;
copies of a message are only made when paths diverge at a router.
v The sending server does not need to maintain a list of recipients because all
hosts in a multicast group are identified by a single IP-destination address.
v Membership in a multicast group is dynamic:
–
–
–
–
456
Hosts can join or leave at any time
A host can be a member of more than one group at a time
The location of hosts within a network is unrestricted
The number of members in a multicast group is unlimited. When hosts join,
you do not need to increase bandwidth.
z/VM: TCP/IP Planning and Customization
TCP/IP Server
v For applications that support IP multicast, a single group address can have
multiple data streams on different port numbers on different sockets, in one or
more applications. Multiple applications can share a single group address on a
port.
v Multicasting reduces the load on the sending server, which no longer has to
support multiple sequential or concurrent unicast sessions.
Note: TCP/IP contains host support of multicast, but not router support. Host
support is based on implementation of the RFC 112 standard.
To implement multicasting in your applications:
v Use the C setsockopt() and getsockopt() calls to implement multicast functions.
For information on these calls, refer to the z/VM: TCP/IP Level 430
Programmer’s Reference.
v Use the GATEWAY statement in the PROFILE TCPIP configuration file to specify
static routes for multicast datagrams. At a minimum, you should define a default
multicast route.
Multiple Interface Network Support
TCP/IP supports multiple interfaces and IP addresses on the same network,
providing redundant paths to other hosts or routers on directly-attached networks.
When you configure multiple interfaces to the same network, one of them provides
the primary path to hosts and routers on that network; the others are secondary
paths.
In general, the interface used for traffic originating at your VM host is the one that
provides the first active route to a destination, according to the IP routing table. If
the destination route is not available, the interface that provides the first active
default route is used. Furthermore, the home IP address of the selected interface is
used as the local address for an application socket if SOURCEVIPA is not enabled
and the socket is not bound to a specific local IP address.
If RouteD is in use and more than one directly-attached network interfaces is
defined, the first link for a given home address is used as the primary source for
routing outbound traffic to the local network, if that interface is functioning. All other
interfaces on a directly-attached network are used for secondary routing in the
event of an interface failure.
Notes:
1. The first primary path can be specified in the PRIMARYINTERFACE statement.
On remaining interfaces, the first link for each defined network or subnetwork in
the list of home addresses is the primary one.
2. If no PRIMARYINTERFACE statement is configured, the first link specified for
each defined network or subnetwork in the list of home addresses is the primary
one.
Virtual IP Addressing (VIPA)
Virtual IP Addressing (VIPA) frees other hosts from depending on a particular
physical network interface for communication with a z/VM TCP/IP stack. Without
VIPA, other hosts are bound to one of the VM host’s home IP addresses and,
therefore, to a particular physical network interface (for example, a device or
adapter). If that interface fails, the associated connections are terminated. VIPA
provides an IP address that is associated with a z/VM TCP/IP stack but not with a
specific physical network interface. This allows hosts that connect to the z/VM
Chapter 24. Configuring the TCP/IP Server
457
TCP/IP Server
TCP/IP stack to send data on whatever paths are selected by the routing protocols;
thus, VIPA provides tolerance of physical network interface hardware failures.
To achieve network interface independence, VIPA relies on a virtual device2 and a
virtual IP address. The virtual device is always active and never experiences a
failure. A virtual IP address is the home address for a virtual device, which has no
associated physical network interface. Inbound packets whose destination is a
virtual IP address can be routed through any of the real physical network interfaces
used by a z/VM TCP/IP stack. Failure of one physical network interface is handled
by routing inbound traffic to another active physical network interface. Similarly,
outbound packets can be routed around physical network interface outages,
assuming an additional physical network interface provides an alternate path to the
final destination.
Dynamic routing protocols may