BQTCP/IP - A TCP/IP implementation for RSX Written by Johnny Billquist Date: 14 Sep 2024 Version: Y2.17 TABLE OF CONTENTS CHAPTER 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 1-1 1.1 EXAMPLE USAGE . . . . . . . . . . . . . . . . . 1-2 CHAPTER 2 THE BASIC TCP/IP IMPLEMENTATION . . . . . . . . . 2-1 2.1 INTERFACES . . . . . . . . . . . . . . . . . . . 2-1 2.2 IP / ICMP . . . . . . . . . . . . . . . . . . . 2-2 2.3 UDP . . . . . . . . . . . . . . . . . . . . . . 2-2 2.4 TCP . . . . . . . . . . . . . . . . . . . . . . 2-2 CHAPTER 3 INSTALLATION . . . . . . . . . . . . . . . . . . . 3-1 3.1 GUIDELINES ON INSTALLATION QUESTIONS . . . . . . 3-2 3.1.1 Interfaces . . . . . . . . . . . . . . . . . . 3-2 3.1.2 Additional information . . . . . . . . . . . . 3-3 3.2 HELP . . . . . . . . . . . . . . . . . . . . . . 3-3 3.3 CONFIGURATION . . . . . . . . . . . . . . . . . 3-3 3.3.1 Interfaces . . . . . . . . . . . . . . . . . . 3-4 3.3.1.1 Loopback . . . . . . . . . . . . . . . . . . 3-4 3.3.1.2 Ethernet . . . . . . . . . . . . . . . . . . 3-4 3.3.1.3 SLIP . . . . . . . . . . . . . . . . . . . . 3-5 3.3.1.4 DDCMP . . . . . . . . . . . . . . . . . . . 3-5 3.3.2 Additional information . . . . . . . . . . . . 3-5 CHAPTER 4 CONFIGURATION . . . . . . . . . . . . . . . . . . 4-1 4.1 LOGICAL NAMES . . . . . . . . . . . . . . . . . 4-1 4.2 FILES . . . . . . . . . . . . . . . . . . . . . 4-4 4.3 DHCP . . . . . . . . . . . . . . . . . . . . . . 4-5 CHAPTER 5 TOOLS . . . . . . . . . . . . . . . . . . . . . . 5-1 5.1 IFCONFIG . . . . . . . . . . . . . . . . . . . . 5-1 5.2 NETSTAT . . . . . . . . . . . . . . . . . . . . 5-1 5.3 PING . . . . . . . . . . . . . . . . . . . . . . 5-1 5.4 TRACERT . . . . . . . . . . . . . . . . . . . . 5-2 CHAPTER 6 DAEMONS . . . . . . . . . . . . . . . . . . . . . 6-1 6.1 LOGGING DIRECTORY PATH . . . . . . . . . . . . . 6-1 6.2 TCP . . . . . . . . . . . . . . . . . . . . . . 6-1 6.2.1 TELNET . . . . . . . . . . . . . . . . . . . . 6-1 6.2.2 FTPD . . . . . . . . . . . . . . . . . . . . . 6-2 6.2.2.1 Logical names . . . . . . . . . . . . . . . 6-2 6.2.2.2 Files . . . . . . . . . . . . . . . . . . . 6-3 6.2.2.3 Logging . . . . . . . . . . . . . . . . . . 6-3 6.2.2.4 Limitations on user access . . . . . . . . . 6-3 6.2.2.5 Known problems and limitations . . . . . . . 6-3 6.2.3 INETD . . . . . . . . . . . . . . . . . . . . 6-4 6.2.4 WWW . . . . . . . . . . . . . . . . . . . . . 6-4 6.2.4.1 Installation . . . . . . . . . . . . . . . . 6-4 6.2.4.2 Configuration . . . . . . . . . . . . . . . 6-5 6.2.4.2.1 PUBLIC.TXT . . . . . . . . . . . . . . . . 6-5 6.2.4.2.2 DEFAULT.TXT . . . . . . . . . . . . . . . 6-6 6.2.4.2.3 CONTENT.TXT . . . . . . . . . . . . . . . 6-6 6.2.4.2.4 400.HTM . . . . . . . . . . . . . . . . . 6-7 6.2.4.2.5 404.HTM . . . . . . . . . . . . . . . . . 6-7 6.2.4.2.6 405.HTM . . . . . . . . . . . . . . . . . 6-7 6.2.4.3 Operation . . . . . . . . . . . . . . . . . 6-7 6.2.4.4 Logging . . . . . . . . . . . . . . . . . . 6-7 6.2.4.5 Known problems and limitations . . . . . . . 6-8 6.2.4.6 Rebuilding . . . . . . . . . . . . . . . . . 6-8 6.2.4.7 Serving pages for users . . . . . . . . . . 6-8 6.2.4.8 Virtual hosts . . . . . . . . . . . . . . . 6-9 Page ii 6.2.5 MAIL . . . . . . . . . . . . . . . . . . . . . 6-9 6.3 UDP . . . . . . . . . . . . . . . . . . . . . . 6-9 6.3.1 DHCP . . . . . . . . . . . . . . . . . . . . . 6-9 6.3.2 TFTPD . . . . . . . . . . . . . . . . . . . . 6-10 6.3.3 RWHOD . . . . . . . . . . . . . . . . . . . . 6-10 CHAPTER 7 CLIENTS . . . . . . . . . . . . . . . . . . . . . 7-1 7.1 TCP . . . . . . . . . . . . . . . . . . . . . . 7-1 7.1.1 TELNET . . . . . . . . . . . . . . . . . . . . 7-1 7.1.2 FTP . . . . . . . . . . . . . . . . . . . . . 7-1 7.1.2.1 Building . . . . . . . . . . . . . . . . . . 7-1 7.1.2.2 Known issues and limitations . . . . . . . . 7-2 7.1.3 IRCBOT . . . . . . . . . . . . . . . . . . . . 7-2 7.1.3.1 Building . . . . . . . . . . . . . . . . . . 7-2 7.1.3.2 Configuration . . . . . . . . . . . . . . . 7-2 7.1.3.3 Operation . . . . . . . . . . . . . . . . . 7-2 7.1.4 IRC . . . . . . . . . . . . . . . . . . . . . 7-3 7.1.4.1 Building . . . . . . . . . . . . . . . . . . 7-3 7.1.4.2 Configuration . . . . . . . . . . . . . . . 7-3 7.1.5 LPT . . . . . . . . . . . . . . . . . . . . . 7-4 7.1.5.1 FORMS information . . . . . . . . . . . . . 7-4 7.1.5.2 Building . . . . . . . . . . . . . . . . . . 7-5 7.1.5.3 Printer control . . . . . . . . . . . . . . 7-6 7.1.5.4 Installation . . . . . . . . . . . . . . . . 7-7 7.1.6 LPQ . . . . . . . . . . . . . . . . . . . . . 7-7 7.1.7 MAIL . . . . . . . . . . . . . . . . . . . . . 7-7 7.1.8 TNC2 . . . . . . . . . . . . . . . . . . . . . 7-7 7.1.8.1 Installation . . . . . . . . . . . . . . . . 7-8 7.2 UDP . . . . . . . . . . . . . . . . . . . . . . 7-8 7.2.1 TFTP . . . . . . . . . . . . . . . . . . . . . 7-8 7.2.1.1 Building . . . . . . . . . . . . . . . . . . 7-9 7.2.1.2 Usage . . . . . . . . . . . . . . . . . . . 7-9 7.2.2 NTPDATE . . . . . . . . . . . . . . . . . . . 7-9 7.2.2.1 Building . . . . . . . . . . . . . . . . . . 7-9 7.2.2.2 Usage . . . . . . . . . . . . . . . . . . . 7-9 7.2.3 RWHOD . . . . . . . . . . . . . . . . . . . . 7-10 7.2.3.1 RUPTIME . . . . . . . . . . . . . . . . . . 7-10 7.2.3.2 RWHO . . . . . . . . . . . . . . . . . . . . 7-10 7.2.3.3 RPURGE . . . . . . . . . . . . . . . . . . . 7-11 7.2.4 DNS . . . . . . . . . . . . . . . . . . . . . 7-11 7.2.4.1 Usage . . . . . . . . . . . . . . . . . . . 7-11 CHAPTER 8 MAIL . . . . . . . . . . . . . . . . . . . . . . . 8-1 8.1 SUMMARY . . . . . . . . . . . . . . . . . . . . 8-1 8.2 MAIL READER DETAILS . . . . . . . . . . . . . . 8-3 8.2.1 Checking if there are any unread mails . . . . 8-3 8.2.2 Getting notified of new mails . . . . . . . . 8-3 8.2.2.1 Enabling mail notification . . . . . . . . . 8-3 8.2.2.2 Disabling mail notification . . . . . . . . 8-4 8.2.2.3 Checking if mail notification is enabled . . 8-4 8.3 MAIL DAEMON DETAILS . . . . . . . . . . . . . . 8-4 8.3.1 Logical names . . . . . . . . . . . . . . . . 8-4 8.3.2 Different protocols . . . . . . . . . . . . . 8-5 8.3.2.1 SMTP . . . . . . . . . . . . . . . . . . . . 8-5 8.3.2.2 MAIL11 . . . . . . . . . . . . . . . . . . . 8-5 8.3.2.3 Local . . . . . . . . . . . . . . . . . . . 8-5 8.3.3 Accepting mails for many machines . . . . . . 8-6 8.3.4 Mail queue . . . . . . . . . . . . . . . . . . 8-6 8.3.4.1 Creating/resetting the mail queue . . . . . 8-6 8.3.4.2 Examining the mail queue . . . . . . . . . . 8-6 8.3.5 Mail notification . . . . . . . . . . . . . . 8-7 8.3.5.1 Getting notified of new mails . . . . . . . 8-7 Page iii 8.3.5.1.1 Resetting the mail notification file . . . 8-7 8.3.5.1.2 Checking if mail notification is enabled . 8-7 8.3.6 Temporary mail files . . . . . . . . . . . . . 8-7 8.3.7 Mail alias file . . . . . . . . . . . . . . . 8-7 8.3.8 Mail host names . . . . . . . . . . . . . . . 8-8 8.3.9 Mail forwarding . . . . . . . . . . . . . . . 8-8 8.3.9.1 TCP/IP to TCP/IP . . . . . . . . . . . . . . 8-8 8.3.9.2 TCP/IP to DECnet . . . . . . . . . . . . . . 8-9 8.3.9.3 DECnet to DECnet . . . . . . . . . . . . . . 8-9 8.3.9.4 DECnet to TCP/IP . . . . . . . . . . . . . . 8-9 8.3.10 Blocking mails from certain sources . . . . . 8-9 8.3.11 Template files . . . . . . . . . . . . . . . 8-9 8.4 MAIL API DETAILS . . . . . . . . . . . . . . . . 8-9 8.5 INSTALLATION . . . . . . . . . . . . . . . . . . 8-10 8.6 UPDATING . . . . . . . . . . . . . . . . . . . . 8-10 8.7 MAIL PROCESSOR . . . . . . . . . . . . . . . . . 8-10 8.7.1 Controlling configuration options . . . . . . 8-10 8.7.2 Sending mail . . . . . . . . . . . . . . . . . 8-11 8.7.3 Reading mail . . . . . . . . . . . . . . . . . 8-11 CHAPTER 9 NAME RESOLUTION (DNS) . . . . . . . . . . . . . . 9-1 9.1 CACHING . . . . . . . . . . . . . . . . . . . . 9-1 9.2 LIBRARY ROUTINES . . . . . . . . . . . . . . . . 9-2 9.2.1 Ports . . . . . . . . . . . . . . . . . . . . 9-2 9.2.2 H2IP . . . . . . . . . . . . . . . . . . . . . 9-3 9.2.3 H2IPP . . . . . . . . . . . . . . . . . . . . 9-3 9.2.4 IP2H . . . . . . . . . . . . . . . . . . . . . 9-4 9.3 DIFFERENT RESOLUTION METHODS . . . . . . . . . . 9-4 9.3.1 Logical names . . . . . . . . . . . . . . . . 9-4 9.3.2 HOSTS file . . . . . . . . . . . . . . . . . . 9-5 9.3.3 DNS . . . . . . . . . . . . . . . . . . . . . 9-5 9.3.4 MDNS . . . . . . . . . . . . . . . . . . . . . 9-6 9.4 ADDITIONAL DETAILS ON THE RESOLVER ACP. . . . . 9-6 9.4.1 Some additional information on the QIO$ interface. . . . . . . . . . . . . . . . . . 9-7 9.5 COMMAND LINE TOOL . . . . . . . . . . . . . . . 9-7 CHAPTER 10 DECNET OVER IP . . . . . . . . . . . . . . . . . 10-1 10.1 PREPARATORY WORK . . . . . . . . . . . . . . . 10-1 10.2 NETGEN . . . . . . . . . . . . . . . . . . . . 10-1 10.3 AFTER NETGEN - IPNET . . . . . . . . . . . . . 10-4 10.4 CONFIGURING THE IP LINKS AFTER REBOOT . . . . . 10-4 10.5 MNC - MULTINET CONFIGURE TOOL . . . . . . . . . 10-5 10.6 UDP DETAILS . . . . . . . . . . . . . . . . . . 10-6 10.7 TCP DETAILS . . . . . . . . . . . . . . . . . . 10-6 10.7.1 TCP active links . . . . . . . . . . . . . . 10-6 10.7.2 TCP passive links . . . . . . . . . . . . . . 10-7 CHAPTER 11 INTERNET SPOOFING . . . . . . . . . . . . . . . . 11-1 11.1 DETECTION . . . . . . . . . . . . . . . . . . . 11-1 11.2 PREVENTION . . . . . . . . . . . . . . . . . . 11-2 11.3 STATUS INFORMATION . . . . . . . . . . . . . . 11-2 CHAPTER 12 DETAILED INFORMATION ON INTERFACES . . . . . . . 12-1 12.1 IP . . . . . . . . . . . . . . . . . . . . . . 12-1 12.1.1 QIO interface . . . . . . . . . . . . . . . . 12-1 12.1.1.1 IP.XMT . . . . . . . . . . . . . . . . . . 12-1 12.1.1.2 IP.RCV . . . . . . . . . . . . . . . . . . 12-1 12.1.1.3 IP.XER . . . . . . . . . . . . . . . . . . 12-1 12.1.1.4 IP.RER . . . . . . . . . . . . . . . . . . 12-2 12.1.1.5 IO.STA . . . . . . . . . . . . . . . . . . 12-2 12.1.1.6 IO.STO . . . . . . . . . . . . . . . . . . 12-2 Page iv 12.1.1.7 IO.RST . . . . . . . . . . . . . . . . . . 12-2 12.1.1.8 IO.XMT . . . . . . . . . . . . . . . . . . 12-2 12.1.1.9 IO.RCV . . . . . . . . . . . . . . . . . . 12-2 12.1.1.10 IO.ADR . . . . . . . . . . . . . . . . . . 12-3 12.1.1.11 IO.RMR . . . . . . . . . . . . . . . . . . 12-3 12.1.1.12 IO.GRT . . . . . . . . . . . . . . . . . . 12-3 12.1.1.13 IP.JMG . . . . . . . . . . . . . . . . . . 12-3 12.1.1.14 IP.LMG . . . . . . . . . . . . . . . . . . 12-3 12.1.1.15 IO.GML . . . . . . . . . . . . . . . . . . 12-3 12.2 UDP . . . . . . . . . . . . . . . . . . . . . . 12-4 12.2.1 QIO interface . . . . . . . . . . . . . . . . 12-4 12.2.1.1 IO.CEP . . . . . . . . . . . . . . . . . . 12-4 12.2.1.2 IO.CON . . . . . . . . . . . . . . . . . . 12-4 12.2.1.3 IO.ACC . . . . . . . . . . . . . . . . . . 12-4 12.2.1.4 IO.GCO . . . . . . . . . . . . . . . . . . 12-5 12.2.1.5 IO.CLN . . . . . . . . . . . . . . . . . . 12-5 12.2.1.6 IO.RCV . . . . . . . . . . . . . . . . . . 12-5 12.2.1.7 IO.XMT . . . . . . . . . . . . . . . . . . 12-5 12.2.1.8 IO.RSD . . . . . . . . . . . . . . . . . . 12-6 12.2.1.9 IO.WSD . . . . . . . . . . . . . . . . . . 12-6 12.2.1.10 IO.RAS . . . . . . . . . . . . . . . . . . 12-6 12.2.1.11 IO.RUN . . . . . . . . . . . . . . . . . . 12-7 12.2.1.12 IO.STP . . . . . . . . . . . . . . . . . . 12-7 12.2.1.13 IO.RST . . . . . . . . . . . . . . . . . . 12-7 12.2.1.14 IP.RCV . . . . . . . . . . . . . . . . . . 12-7 12.2.1.15 IP.RER . . . . . . . . . . . . . . . . . . 12-7 12.2.1.16 IO.CAN . . . . . . . . . . . . . . . . . . 12-7 12.2.1.17 IO.FLS . . . . . . . . . . . . . . . . . . 12-8 12.2.1.18 IO.TIM . . . . . . . . . . . . . . . . . . 12-8 12.2.1.19 IO.JMG . . . . . . . . . . . . . . . . . . 12-8 12.2.1.20 IO.LMG . . . . . . . . . . . . . . . . . . 12-8 12.3 TCP . . . . . . . . . . . . . . . . . . . . . . 12-8 12.3.1 TCP modes . . . . . . . . . . . . . . . . . 12-10 12.3.1.1 Raw mode . . . . . . . . . . . . . . . . 12-10 12.3.1.2 Text mode . . . . . . . . . . . . . . . . 12-11 12.3.1.3 CR padding . . . . . . . . . . . . . . . 12-11 12.3.1.4 Network virtual terminal mode . . . . . . 12-12 12.3.1.5 Automatic newline . . . . . . . . . . . . 12-12 12.3.1.6 Turn off buffering . . . . . . . . . . . 12-12 12.3.1.7 Latency modes . . . . . . . . . . . . . . 12-13 12.3.1.7.1 High throughput . . . . . . . . . . . . 12-13 12.3.1.7.2 No latency . . . . . . . . . . . . . . 12-13 12.3.1.7.3 High latency . . . . . . . . . . . . . 12-14 12.3.1.7.4 Low latency . . . . . . . . . . . . . . 12-14 12.3.1.8 Keep-alive . . . . . . . . . . . . . . . 12-14 12.3.1.9 Receive partial data . . . . . . . . . . 12-14 12.3.1.10 Transmit with PUSH . . . . . . . . . . . 12-15 12.3.1.11 Transmit with no blocking . . . . . . . 12-15 12.3.1.12 Push on read . . . . . . . . . . . . . . 12-15 12.3.1.13 Receive with no blocking . . . . . . . . 12-16 12.3.1.14 Send immediate ACK . . . . . . . . . . . 12-16 12.3.2 TCP PUSH . . . . . . . . . . . . . . . . . 12-16 12.3.3 TCP URGENT data . . . . . . . . . . . . . . 12-16 12.3.4 QIO interface . . . . . . . . . . . . . . . 12-17 12.3.4.1 IO.CEP . . . . . . . . . . . . . . . . . 12-17 12.3.4.2 IO.SCR . . . . . . . . . . . . . . . . . 12-17 12.3.4.3 IO.CON . . . . . . . . . . . . . . . . . 12-17 12.3.4.4 IO.ACC . . . . . . . . . . . . . . . . . 12-18 12.3.4.5 IO.LSN . . . . . . . . . . . . . . . . . 12-18 12.3.4.6 IO.REJ . . . . . . . . . . . . . . . . . 12-18 12.3.4.7 IO.RLB . . . . . . . . . . . . . . . . . 12-18 12.3.4.8 IO.RPB . . . . . . . . . . . . . . . . . 12-19 Page v 12.3.4.9 IO.RCV . . . . . . . . . . . . . . . . . 12-19 12.3.4.10 IO.RSD . . . . . . . . . . . . . . . . . 12-19 12.3.4.11 IO.WLB . . . . . . . . . . . . . . . . . 12-19 12.3.4.12 IO.WAL . . . . . . . . . . . . . . . . . 12-19 12.3.4.13 IO.WSD . . . . . . . . . . . . . . . . . 12-20 12.3.4.14 IO.GCO . . . . . . . . . . . . . . . . . 12-20 12.3.4.15 IO.CLN . . . . . . . . . . . . . . . . . 12-20 12.3.4.16 IO.RCV . . . . . . . . . . . . . . . . . 12-20 12.3.4.17 IO.XMT . . . . . . . . . . . . . . . . . 12-20 12.3.4.18 IO.RAS . . . . . . . . . . . . . . . . . 12-21 12.3.4.19 IO.RUN . . . . . . . . . . . . . . . . . 12-21 12.3.4.20 IO.STP . . . . . . . . . . . . . . . . . 12-21 12.3.4.21 IO.RST . . . . . . . . . . . . . . . . . 12-21 12.3.4.22 IP.RCV . . . . . . . . . . . . . . . . . 12-21 12.3.4.23 IP.RER . . . . . . . . . . . . . . . . . 12-21 12.3.4.24 IO.CAN . . . . . . . . . . . . . . . . . 12-21 12.3.4.25 IO.FLS . . . . . . . . . . . . . . . . . 12-22 12.3.4.26 IO.IFL . . . . . . . . . . . . . . . . . 12-22 12.3.4.27 IO.ADD . . . . . . . . . . . . . . . . . 12-22 12.3.4.28 IO.REM . . . . . . . . . . . . . . . . . 12-22 12.3.4.29 IO.RNT . . . . . . . . . . . . . . . . . 12-22 12.3.4.30 IO.OPS . . . . . . . . . . . . . . . . . 12-22 12.3.4.31 IO.OPG . . . . . . . . . . . . . . . . . 12-23 12.3.4.32 IO.TIM . . . . . . . . . . . . . . . . . 12-23 12.3.4.33 IO.SMT . . . . . . . . . . . . . . . . . 12-23 12.3.4.34 IO.TWT . . . . . . . . . . . . . . . . . 12-23 12.3.4.35 IO.QMX . . . . . . . . . . . . . . . . . 12-23 12.3.4.36 IO.CHR . . . . . . . . . . . . . . . . . 12-23 12.3.4.37 IO.RSZ . . . . . . . . . . . . . . . . . 12-24 12.3.4.38 IO.RSV . . . . . . . . . . . . . . . . . 12-24 12.3.4.39 IO.SXS . . . . . . . . . . . . . . . . . 12-24 12.3.4.40 IO.SRS . . . . . . . . . . . . . . . . . 12-24 12.3.4.41 IO.SSS . . . . . . . . . . . . . . . . . 12-24 CHAPTER 13 LIBRARIES . . . . . . . . . . . . . . . . . . . . 13-1 13.1 LB:[1,1]IPMAC.MLB . . . . . . . . . . . . . . . 13-1 13.1.1 IP$NFO . . . . . . . . . . . . . . . . . . . 13-1 13.1.2 UD$NFO . . . . . . . . . . . . . . . . . . . 13-1 13.1.3 TC$NFO . . . . . . . . . . . . . . . . . . . 13-1 13.1.4 .ADDR a,b,c,d . . . . . . . . . . . . . . . . 13-2 13.1.5 .SOCK ,n . . . . . . . . . . . . . . 13-2 13.2 LB:[1,1]IPLIB.OLB . . . . . . . . . . . . . . . 13-2 13.2.1 IP . . . . . . . . . . . . . . . . . . . . . 13-2 13.2.2 RESLIB . . . . . . . . . . . . . . . . . . . 13-2 13.2.2.1 H2IP . . . . . . . . . . . . . . . . . . . 13-3 13.2.2.2 H2IPP . . . . . . . . . . . . . . . . . . . 13-3 13.2.2.3 IP2H . . . . . . . . . . . . . . . . . . . 13-3 13.2.3 RESLUN . . . . . . . . . . . . . . . . . . . 13-4 13.2.4 RESEFN . . . . . . . . . . . . . . . . . . . 13-4 13.2.5 RESSYM . . . . . . . . . . . . . . . . . . . 13-4 13.2.6 TCPSYM . . . . . . . . . . . . . . . . . . . 13-4 13.2.7 UNOTIF . . . . . . . . . . . . . . . . . . . 13-4 CHAPTER 14 HLL LIBRARIES . . . . . . . . . . . . . . . . . . 14-1 14.1 BASIC+2 . . . . . . . . . . . . . . . . . . . . 14-1 14.1.1 General . . . . . . . . . . . . . . . . . . . 14-1 14.1.2 Network functions/routines . . . . . . . . . 14-1 14.1.2.1 TCP . . . . . . . . . . . . . . . . . . . . 14-1 14.1.2.2 UDP . . . . . . . . . . . . . . . . . . . . 14-2 14.1.2.3 SOCKET . . . . . . . . . . . . . . . . . . 14-2 14.1.2.4 CONNEC . . . . . . . . . . . . . . . . . . 14-3 14.1.2.5 LISTEN . . . . . . . . . . . . . . . . . . 14-3 Page vi 14.1.2.6 ACCEPT . . . . . . . . . . . . . . . . . . 14-3 14.1.2.7 CLOSE . . . . . . . . . . . . . . . . . . . 14-3 14.1.2.8 GEP . . . . . . . . . . . . . . . . . . . . 14-4 14.1.2.9 SFLG . . . . . . . . . . . . . . . . . . . 14-4 14.1.2.10 GFLG . . . . . . . . . . . . . . . . . . . 14-4 14.1.2.11 STMO . . . . . . . . . . . . . . . . . . . 14-4 14.1.2.12 SCHR . . . . . . . . . . . . . . . . . . . 14-5 14.1.2.13 PUSH . . . . . . . . . . . . . . . . . . . 14-5 14.1.2.14 SEND . . . . . . . . . . . . . . . . . . . 14-5 14.1.2.15 SENDTO . . . . . . . . . . . . . . . . . . 14-5 14.1.2.16 RECV . . . . . . . . . . . . . . . . . . . 14-5 14.1.2.17 RECVFR . . . . . . . . . . . . . . . . . . 14-6 14.1.3 Name resolution routines . . . . . . . . . . 14-6 14.1.3.1 HOST2I . . . . . . . . . . . . . . . . . . 14-6 14.1.3.2 IP2HOS . . . . . . . . . . . . . . . . . . 14-6 14.1.3.3 FINDMX . . . . . . . . . . . . . . . . . . 14-6 14.1.3.4 MXPREF . . . . . . . . . . . . . . . . . . 14-6 14.1.3.5 MXHOST . . . . . . . . . . . . . . . . . . 14-6 14.1.4 Other functions . . . . . . . . . . . . . . . 14-6 14.1.4.1 NOTIFY . . . . . . . . . . . . . . . . . . 14-6 14.2 PDP-11 C . . . . . . . . . . . . . . . . . . . 14-7 14.2.1 General . . . . . . . . . . . . . . . . . . . 14-7 14.2.2 Network functions/routines . . . . . . . . . 14-8 14.2.2.1 tcp . . . . . . . . . . . . . . . . . . . . 14-8 14.2.2.2 udp . . . . . . . . . . . . . . . . . . . . 14-8 14.2.2.3 socket . . . . . . . . . . . . . . . . . . 14-8 14.2.2.4 connect . . . . . . . . . . . . . . . . . . 14-9 14.2.2.5 listen . . . . . . . . . . . . . . . . . . 14-9 14.2.2.6 accept . . . . . . . . . . . . . . . . . . 14-9 14.2.2.7 close . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.8 gep . . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.9 sflg . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.10 gflg . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.11 stmo . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.12 schr . . . . . . . . . . . . . . . . . . . 14-9 14.2.2.13 push . . . . . . . . . . . . . . . . . . 14-10 14.2.2.14 iflush . . . . . . . . . . . . . . . . . 14-10 14.2.2.15 send . . . . . . . . . . . . . . . . . . 14-10 14.2.2.16 sendto . . . . . . . . . . . . . . . . . 14-10 14.2.2.17 recv . . . . . . . . . . . . . . . . . . 14-10 14.2.2.18 recvfrom . . . . . . . . . . . . . . . . 14-10 14.2.2.19 clrio . . . . . . . . . . . . . . . . . 14-10 14.2.3 Name resolution . . . . . . . . . . . . . . 14-10 14.2.3.1 host2ip . . . . . . . . . . . . . . . . . 14-11 14.2.3.2 ip2host . . . . . . . . . . . . . . . . . 14-11 14.2.3.3 mxhost . . . . . . . . . . . . . . . . . 14-11 14.2.4 Byte order handling . . . . . . . . . . . . 14-11 14.2.4.1 ntohs . . . . . . . . . . . . . . . . . . 14-11 14.2.4.2 ntohl . . . . . . . . . . . . . . . . . . 14-11 14.2.4.3 htons . . . . . . . . . . . . . . . . . . 14-11 14.2.4.4 htonl . . . . . . . . . . . . . . . . . . 14-11 14.2.5 Other functions . . . . . . . . . . . . . . 14-11 14.2.5.1 _isme . . . . . . . . . . . . . . . . . . 14-11 14.2.5.2 _notify . . . . . . . . . . . . . . . . . 14-12 14.3 FORTRAN-77 . . . . . . . . . . . . . . . . . 14-12 14.3.1 General . . . . . . . . . . . . . . . . . . 14-12 14.3.2 Network functions/routines . . . . . . . . 14-12 14.3.2.1 TCP . . . . . . . . . . . . . . . . . . . 14-13 14.3.2.2 UDP . . . . . . . . . . . . . . . . . . . 14-13 14.3.2.3 SOCKET . . . . . . . . . . . . . . . . . 14-13 14.3.2.4 CONNEC . . . . . . . . . . . . . . . . . 14-13 14.3.2.5 LISTEN . . . . . . . . . . . . . . . . . 14-14 Page vii 14.3.2.6 ACCEPT . . . . . . . . . . . . . . . . . 14-14 14.3.2.7 SCLOSE . . . . . . . . . . . . . . . . . 14-14 14.3.2.8 GEP . . . . . . . . . . . . . . . . . . . 14-14 14.3.2.9 PUSH . . . . . . . . . . . . . . . . . . 14-15 14.3.3 Name resolution routines . . . . . . . . . 14-15 14.3.3.1 HOST2I . . . . . . . . . . . . . . . . . 14-15 14.3.3.2 IP2HOS . . . . . . . . . . . . . . . . . 14-15 14.4 PASCAL . . . . . . . . . . . . . . . . . . . 14-16 14.4.1 General . . . . . . . . . . . . . . . . . . 14-16 14.4.1.1 Data types . . . . . . . . . . . . . . . 14-16 14.4.2 Network functions . . . . . . . . . . . . . 14-16 14.4.2.1 TCP . . . . . . . . . . . . . . . . . . . 14-16 14.4.2.2 ACCEPT . . . . . . . . . . . . . . . . . 14-17 14.4.2.3 CONNECT . . . . . . . . . . . . . . . . . 14-17 14.4.2.4 SCLOSE . . . . . . . . . . . . . . . . . 14-17 14.4.2.5 INFO . . . . . . . . . . . . . . . . . . 14-17 14.4.3 Name resolution . . . . . . . . . . . . . . 14-18 14.4.3.1 HOST2IP . . . . . . . . . . . . . . . . . 14-18 14.4.3.2 IP2HOST . . . . . . . . . . . . . . . . . 14-18 14.5 LISP . . . . . . . . . . . . . . . . . . . . 14-18 14.5.1 General . . . . . . . . . . . . . . . . . . 14-19 14.5.2 Daemons . . . . . . . . . . . . . . . . . . 14-19 14.5.3 Network functions . . . . . . . . . . . . . 14-19 14.5.3.1 neterr . . . . . . . . . . . . . . . . . 14-19 14.5.3.2 socket . . . . . . . . . . . . . . . . . 14-20 14.5.3.3 listen . . . . . . . . . . . . . . . . . 14-20 14.5.3.4 accept . . . . . . . . . . . . . . . . . 14-20 14.5.3.5 connect . . . . . . . . . . . . . . . . . 14-20 14.5.3.6 port . . . . . . . . . . . . . . . . . . 14-20 14.5.3.7 ip2host . . . . . . . . . . . . . . . . . 14-21 14.5.3.8 flush . . . . . . . . . . . . . . . . . . 14-21 14.5.4 System services . . . . . . . . . . . . . . 14-21 14.5.4.1 date . . . . . . . . . . . . . . . . . . 14-21 14.5.4.2 time . . . . . . . . . . . . . . . . . . 14-21 14.5.4.3 translate . . . . . . . . . . . . . . . . 14-22 CHAPTER 15 CGI PROGRAMMING . . . . . . . . . . . . . . . . . 15-1 15.1 IND . . . . . . . . . . . . . . . . . . . . . . 15-1 15.1.1 HEADER . . . . . . . . . . . . . . . . . . . 15-1 15.1.2 GETQP . . . . . . . . . . . . . . . . . . . . 15-1 15.1.3 GETQP2 . . . . . . . . . . . . . . . . . . . 15-1 15.1.4 COOKIE . . . . . . . . . . . . . . . . . . . 15-1 15.1.5 FRMINI . . . . . . . . . . . . . . . . . . . 15-1 15.1.6 FRMGET . . . . . . . . . . . . . . . . . . . 15-1 15.1.7 FRMEND . . . . . . . . . . . . . . . . . . . 15-1 15.1.8 URLDEC . . . . . . . . . . . . . . . . . . . 15-1 15.2 C . . . . . . . . . . . . . . . . . . . . . . . 15-2 15.3 BASIC+2 . . . . . . . . . . . . . . . . . . . . 15-2 CHAPTER 16 EXAMPLE PROGRAMS . . . . . . . . . . . . . . . . 16-1 16.1 INETD . . . . . . . . . . . . . . . . . . . . . 16-1 16.1.1 ECHO . . . . . . . . . . . . . . . . . . . . 16-1 16.1.2 SINK . . . . . . . . . . . . . . . . . . . . 16-1 16.1.3 DAYTIME . . . . . . . . . . . . . . . . . . . 16-1 16.1.4 QUOTD . . . . . . . . . . . . . . . . . . . . 16-2 16.2 HTTPD (CODE FOUND IN [HTTPD]) . . . . . . . . . 16-2 16.3 HTTPD2 (CODE FOUND IN [HTTPD]) . . . . . . . . 16-2 16.4 HTTPD3 (CODE FOUND IN [HTTPD]) . . . . . . . . 16-2 16.5 CGIDEMO . . . . . . . . . . . . . . . . . . . . 16-3 16.6 TCPTEST1 . . . . . . . . . . . . . . . . . . . 16-3 16.7 TCPTEST2 . . . . . . . . . . . . . . . . . . . 16-3 16.8 TCPTEST3 . . . . . . . . . . . . . . . . . . . 16-3 Page viii 16.9 TCPTEST4 . . . . . . . . . . . . . . . . . . . 16-3 16.10 TCPTEST5 . . . . . . . . . . . . . . . . . . . 16-4 16.11 TCPTEST6 . . . . . . . . . . . . . . . . . . . 16-4 16.12 TCPTEST7 . . . . . . . . . . . . . . . . . . . 16-4 16.13 TCPTEST8 . . . . . . . . . . . . . . . . . . . 16-4 16.14 TCPTEST9 . . . . . . . . . . . . . . . . . . . 16-4 16.15 TCPTEST10 . . . . . . . . . . . . . . . . . . 16-4 16.16 TCPTEST11 . . . . . . . . . . . . . . . . . . 16-5 16.17 TCPTEST12 . . . . . . . . . . . . . . . . . . 16-5 16.18 TCPTEST13 . . . . . . . . . . . . . . . . . . 16-5 16.19 TCPTEST14 . . . . . . . . . . . . . . . . . . 16-5 16.20 TCPSND . . . . . . . . . . . . . . . . . . . . 16-5 16.21 SEND . . . . . . . . . . . . . . . . . . . . . 16-5 16.22 ECHO . . . . . . . . . . . . . . . . . . . . . 16-6 16.23 SPAM . . . . . . . . . . . . . . . . . . . . . 16-6 16.24 UDPTEST . . . . . . . . . . . . . . . . . . . 16-6 CHAPTER 17 RMD PAGES . . . . . . . . . . . . . . . . . . . . 17-1 APPENDIX A BQTMAC . . . . . . . . . . . . . . . . . . . . . A-1 A.1 PUSH . . . . . . . . . . . . . . . . . . . . . . A-1 A.2 POP . . . . . . . . . . . . . . . . . . . . . . A-1 A.3 .MSG . . . . . . . . . . . . . . . . . . . . . . A-1 A.4 .IFMT . . . . . . . . . . . . . . . . . . . . . A-2 A.5 .FMT . . . . . . . . . . . . . . . . . . . . . . A-2 A.6 .PRINT . . . . . . . . . . . . . . . . . . . . . A-2 A.7 .PUT . . . . . . . . . . . . . . . . . . . . . . A-2 A.8 .EOS . . . . . . . . . . . . . . . . . . . . . . A-2 APPENDIX B BQTLIB . . . . . . . . . . . . . . . . . . . . . B-1 B.1 MACRO-11 . . . . . . . . . . . . . . . . . . . . B-1 B.1.1 FMT . . . . . . . . . . . . . . . . . . . . . B-1 B.1.2 GSA . . . . . . . . . . . . . . . . . . . . . B-1 B.1.3 HPW . . . . . . . . . . . . . . . . . . . . . B-1 B.1.4 PMATCH . . . . . . . . . . . . . . . . . . . . B-1 B.1.5 ALLOC . . . . . . . . . . . . . . . . . . . . B-1 B.1.6 FREE . . . . . . . . . . . . . . . . . . . . . B-1 B.1.7 MEMINI . . . . . . . . . . . . . . . . . . . . B-1 B.1.8 MEMUSE . . . . . . . . . . . . . . . . . . . . B-1 B.1.9 QTDOW . . . . . . . . . . . . . . . . . . . . B-1 B.1.10 QT2STR . . . . . . . . . . . . . . . . . . . B-2 B.1.11 STR2QT . . . . . . . . . . . . . . . . . . . B-2 B.1.12 STR2TM . . . . . . . . . . . . . . . . . . . B-2 B.1.13 TMOFF . . . . . . . . . . . . . . . . . . . . B-2 B.1.14 GETMSG . . . . . . . . . . . . . . . . . . . B-2 B.1.15 PUTMSG . . . . . . . . . . . . . . . . . . . B-2 B.1.16 SIGNAL . . . . . . . . . . . . . . . . . . . B-2 B.1.17 DAYADD . . . . . . . . . . . . . . . . . . . B-2 B.1.18 DAYS . . . . . . . . . . . . . . . . . . . . B-2 B.1.19 DDAYS . . . . . . . . . . . . . . . . . . . . B-2 B.1.20 DOW . . . . . . . . . . . . . . . . . . . . . B-2 B.1.21 ISLEAP . . . . . . . . . . . . . . . . . . . B-2 B.1.22 PARDAT . . . . . . . . . . . . . . . . . . . B-2 B.1.23 RDATE . . . . . . . . . . . . . . . . . . . . B-3 B.1.24 GETSAB . . . . . . . . . . . . . . . . . . . B-3 B.1.25 GETUAB . . . . . . . . . . . . . . . . . . . B-3 B.1.26 GETUCN . . . . . . . . . . . . . . . . . . . B-3 B.1.27 SYSNAM . . . . . . . . . . . . . . . . . . . B-3 B.1.28 UPTIME . . . . . . . . . . . . . . . . . . . B-3 B.1.29 USRIDL . . . . . . . . . . . . . . . . . . . B-3 B.1.30 RTIME . . . . . . . . . . . . . . . . . . . . B-3 B.1.31 UTIME . . . . . . . . . . . . . . . . . . . . B-3 Page ix B.1.32 CKNET . . . . . . . . . . . . . . . . . . . . B-3 B.1.33 GTHDIR . . . . . . . . . . . . . . . . . . . B-3 B.1.34 GTSID . . . . . . . . . . . . . . . . . . . . B-4 B.1.35 GTUIC . . . . . . . . . . . . . . . . . . . . B-4 B.1.36 GTFLG . . . . . . . . . . . . . . . . . . . . B-4 B.1.37 GTUNAM . . . . . . . . . . . . . . . . . . . B-4 B.1.38 VUSER . . . . . . . . . . . . . . . . . . . . B-5 B.1.39 VUSERL . . . . . . . . . . . . . . . . . . . B-6 B.1.40 VUSERN . . . . . . . . . . . . . . . . . . . B-6 B.1.41 VUSERSL . . . . . . . . . . . . . . . . . . . B-6 B.1.42 VUSERSN . . . . . . . . . . . . . . . . . . . B-6 B.1.43 TIPRV . . . . . . . . . . . . . . . . . . . . B-6 B.1.44 TILGI . . . . . . . . . . . . . . . . . . . . B-6 B.1.45 TIRMT . . . . . . . . . . . . . . . . . . . . B-7 B.1.46 CRC . . . . . . . . . . . . . . . . . . . . . B-7 B.2 BASIC+2 LIBRARY . . . . . . . . . . . . . . . . B-7 B.2.1 Quad time functions . . . . . . . . . . . . . B-7 B.2.1.1 QTSTR . . . . . . . . . . . . . . . . . . . B-7 B.2.1.2 STRQT . . . . . . . . . . . . . . . . . . . B-8 B.2.1.3 CMPQT . . . . . . . . . . . . . . . . . . . B-9 B.2.1.4 QTDIFF . . . . . . . . . . . . . . . . . . . B-9 B.2.1.5 QTIME . . . . . . . . . . . . . . . . . . . B-9 B.2.1.6 QTDOW . . . . . . . . . . . . . . . . . . . B-9 B.2.2 File information functions . . . . . . . . . . B-10 B.2.2.1 FTIME . . . . . . . . . . . . . . . . . . . B-10 B.2.2.2 FPRO . . . . . . . . . . . . . . . . . . . . B-10 B.2.3 User identification manipulation . . . . . . . B-10 B.2.3.1 BEPRIV . . . . . . . . . . . . . . . . . . . B-10 B.2.3.2 NOPRIV . . . . . . . . . . . . . . . . . . . B-10 B.2.4 RAD50 functions . . . . . . . . . . . . . . . B-11 B.2.4.1 TOR50 . . . . . . . . . . . . . . . . . . . B-11 B.2.4.2 FMR50 . . . . . . . . . . . . . . . . . . . B-11 B.2.5 Subprocess functions . . . . . . . . . . . . . B-11 B.2.5.1 CRSUB . . . . . . . . . . . . . . . . . . . B-11 B.2.5.2 CMD . . . . . . . . . . . . . . . . . . . . B-12 B.2.5.3 EXE . . . . . . . . . . . . . . . . . . . . B-12 B.2.5.4 WAITS . . . . . . . . . . . . . . . . . . . B-12 B.2.5.5 GETLIN . . . . . . . . . . . . . . . . . . . B-13 B.2.5.6 GETERL . . . . . . . . . . . . . . . . . . . B-13 B.2.5.7 PUTLIN . . . . . . . . . . . . . . . . . . . B-13 B.2.5.8 PUTEOF . . . . . . . . . . . . . . . . . . . B-13 B.2.5.9 DLSUB . . . . . . . . . . . . . . . . . . . B-14 B.2.5.10 GETESB . . . . . . . . . . . . . . . . . . B-14 B.2.6 Logical names . . . . . . . . . . . . . . . . B-14 B.2.6.1 TRNSLT . . . . . . . . . . . . . . . . . . . B-14 B.2.7 Multiread . . . . . . . . . . . . . . . . . . B-15 B.2.7.1 MINIT . . . . . . . . . . . . . . . . . . . B-15 B.2.7.2 MREAD . . . . . . . . . . . . . . . . . . . B-15 B.2.7.3 MEND . . . . . . . . . . . . . . . . . . . . B-15 B.2.7.4 MSG . . . . . . . . . . . . . . . . . . . . B-16 B.3 PDP-11 C LIBRARY . . . . . . . . . . . . . . . . B-16 B.3.1 Logical names . . . . . . . . . . . . . . . . B-16 B.3.1.1 trnslt . . . . . . . . . . . . . . . . . . . B-16 B.3.1.2 define . . . . . . . . . . . . . . . . . . . B-16 B.3.2 File information . . . . . . . . . . . . . . . B-17 B.3.2.1 fstat . . . . . . . . . . . . . . . . . . . B-17 B.3.2.2 stat . . . . . . . . . . . . . . . . . . . . B-17 B.3.2.3 umask . . . . . . . . . . . . . . . . . . . B-17 B.3.2.4 defmask . . . . . . . . . . . . . . . . . . B-18 B.3.3 User information . . . . . . . . . . . . . . . B-18 B.3.3.1 getuid . . . . . . . . . . . . . . . . . . . B-18 B.3.3.2 getgid . . . . . . . . . . . . . . . . . . . B-19 Page x B.3.3.3 getsid . . . . . . . . . . . . . . . . . . . B-19 B.3.3.4 isprv . . . . . . . . . . . . . . . . . . . B-19 B.3.3.5 isco . . . . . . . . . . . . . . . . . . . . B-19 B.3.3.6 username . . . . . . . . . . . . . . . . . . B-19 B.3.3.7 myuic . . . . . . . . . . . . . . . . . . . B-19 B.3.3.8 getterm . . . . . . . . . . . . . . . . . . B-19 B.3.4 Time zone handling . . . . . . . . . . . . . . B-20 B.3.4.1 tzset . . . . . . . . . . . . . . . . . . . B-20 B.3.5 String functions . . . . . . . . . . . . . . . B-20 B.3.5.1 strcasecmp . . . . . . . . . . . . . . . . . B-20 B.3.5.2 strncasecmp . . . . . . . . . . . . . . . . B-20 B.3.6 Quad time functions . . . . . . . . . . . . . B-20 B.3.6.1 qtnow . . . . . . . . . . . . . . . . . . . B-20 B.3.6.2 qtime . . . . . . . . . . . . . . . . . . . B-20 B.3.6.3 qtstr . . . . . . . . . . . . . . . . . . . B-21 B.3.6.4 strqt . . . . . . . . . . . . . . . . . . . B-21 B.3.6.5 qtadd . . . . . . . . . . . . . . . . . . . B-21 B.3.6.6 qtsub . . . . . . . . . . . . . . . . . . . B-21 B.3.6.7 qtdiff . . . . . . . . . . . . . . . . . . . B-22 B.3.6.8 t2qt . . . . . . . . . . . . . . . . . . . . B-22 B.3.6.9 qt2t . . . . . . . . . . . . . . . . . . . . B-22 B.3.7 User account information . . . . . . . . . . . B-22 B.3.7.1 acnt . . . . . . . . . . . . . . . . . . . . B-22 B.3.7.2 g_unam . . . . . . . . . . . . . . . . . . . B-22 B.3.7.3 g_fnam . . . . . . . . . . . . . . . . . . . B-23 B.3.7.4 g_lnam . . . . . . . . . . . . . . . . . . . B-23 B.3.7.5 g_hdir . . . . . . . . . . . . . . . . . . . B-23 B.3.7.6 g_uics . . . . . . . . . . . . . . . . . . . B-23 B.3.7.7 g_guic . . . . . . . . . . . . . . . . . . . B-23 B.3.7.8 g_sid . . . . . . . . . . . . . . . . . . . B-23 B.3.7.9 g_uflg . . . . . . . . . . . . . . . . . . . B-23 B.3.7.10 g_net . . . . . . . . . . . . . . . . . . . B-24 B.3.8 System calls . . . . . . . . . . . . . . . . . B-24 B.3.8.1 RCVDW . . . . . . . . . . . . . . . . . . . B-24 B.3.8.2 VSUN . . . . . . . . . . . . . . . . . . . . B-24 B.3.8.3 vread . . . . . . . . . . . . . . . . . . . B-24 B.3.9 Error information . . . . . . . . . . . . . . B-24 B.3.9.1 rsxerr . . . . . . . . . . . . . . . . . . . B-24 APPENDIX C RSX SPECIAL INFORMATION . . . . . . . . . . . . . C-1 C.1 ETHERNET HANGS FOR Q-BUS SYSTEMS WITH DECNET . . C-1 C.2 MODERN ETHERNET CONTROLLERS AND EMULATED PDP-11S . . . . . . . . . . . . . . . . . . . . C-2 C.3 TCP/IP WITHOUT DECNET . . . . . . . . . . . . . C-3 C.3.1 Performance issues with the XE: device driver . . . . . . . . . . . . . . . . . . . . C-4 C.4 DECNET OVER IP WITH A DECNET ENDNODE . . . . . . C-5 C.5 DETAILS ON FILE FORMATS AND HTTP AND FTP . . . . C-5 C.5.1 File formats . . . . . . . . . . . . . . . . . C-5 C.6 RSX PATCHES . . . . . . . . . . . . . . . . . . C-6 C.6.1 MCR/MCD patches . . . . . . . . . . . . . . . C-6 C.6.2 DCL patches . . . . . . . . . . . . . . . . . C-7 C.6.3 ACNT, PSW and SYSLOG patches . . . . . . . . . C-7 C.6.4 TT: patches . . . . . . . . . . . . . . . . . C-8 C.6.5 RMS patches . . . . . . . . . . . . . . . . . C-9 C.6.6 LAT patches . . . . . . . . . . . . . . . . . C-10 C.6.7 DECnet patches . . . . . . . . . . . . . . . . C-10 C.6.7.1 Functional problems . . . . . . . . . . . . C-10 C.6.7.2 DECnet performance . . . . . . . . . . . . . C-11 C.6.8 Automated process to install some of the patches . . . . . . . . . . . . . . . . . . . C-11 Page xi APPENDIX D TCP/IP PERFORMANCE TUNING . . . . . . . . . . . . D-1 D.1 DECNET COUNTERS . . . . . . . . . . . . . . . . D-1 D.1.1 System counters . . . . . . . . . . . . . . . D-1 D.1.2 Line counters . . . . . . . . . . . . . . . . D-1 D.2 ETHERNET INTERFACES . . . . . . . . . . . . . . D-2 D.3 ARP . . . . . . . . . . . . . . . . . . . . . . D-2 D.3.1 Timeout . . . . . . . . . . . . . . . . . . . D-4 D.3.2 Retries . . . . . . . . . . . . . . . . . . . D-4 D.3.3 Retry timeout . . . . . . . . . . . . . . . . D-4 D.3.4 Unresolved timeout . . . . . . . . . . . . . . D-4 D.3.5 Summary . . . . . . . . . . . . . . . . . . . D-4 D.4 IP . . . . . . . . . . . . . . . . . . . . . . . D-5 D.5 UDP . . . . . . . . . . . . . . . . . . . . . . D-5 D.6 TCP . . . . . . . . . . . . . . . . . . . . . . D-6 D.6.1 Minimum transmit timeout . . . . . . . . . . . D-6 D.6.2 Timeout wait period . . . . . . . . . . . . . D-6 D.6.3 Transmit buffer size . . . . . . . . . . . . . D-6 D.6.4 Receive buffer size . . . . . . . . . . . . . D-7 D.6.5 Transmit segment size . . . . . . . . . . . . D-7 D.7 DNS . . . . . . . . . . . . . . . . . . . . . . D-8 APPENDIX E UPDATING TCP/IP . . . . . . . . . . . . . . . . . E-1 E.1 EXAMPLE UPDATE . . . . . . . . . . . . . . . . . E-1 E.2 FUTHER THINGS TO CONSIDER WHEN UPDATING TCP/IP . E-4 APPENDIX F FILES . . . . . . . . . . . . . . . . . . . . . . F-1 APPENDIX G CREDITS . . . . . . . . . . . . . . . . . . . . . G-1 Page xii CHAPTER 1 INTRODUCTION BQTCP/IP is a TCP/IP implementation for RSX-11M-PLUS. It re- quires a system with split I/D space. It is configurable in how much memory it uses as all data is kept in a private memory area for TCP/IP. It implements the TCP/IP protocols through a number of device drivers in RSX. It works together with DECnet, but can also use the XE: standalone Ethernet device driver. It implements IP over Ethernet as well as a loopback inter- face. There is also a SLIP interface, as well as a DDCMP inter- face, but these have not had much testing. It implements ARP, IP, ICMP, IGMP, UDP and TCP. It follows RFC 1122 pretty completely, but no guarantees are made. This im- plementation is a hobby project that I started around 1993, and it has been through about five separate implementations up to this point. Much effort has been put into correct implementation, as well as trying to be fairly efficient, but most of the focus was on minimizing memory usage. Some effort has also gone into writing libraries to make it easy to use from different languages, but this is an ongoing effort, and suggestions on what to improve are most welcome. The distribution is partly in binary format i.e. executables. The reason for this is to make a distribution easier to manage. A binary distribution is pretty much a snapshot of what I have, which I do at a point where things are stable and working. In addition I have separate build files and libraries created for ease of build- ing the system for a user from this information. Some example applications and user level libraries are also provided, and come with full sources, to illustrate how to use the functions in different ways. There is also some limited documenta- tion of all the functions of the device drivers, but it might be incorrect sometimes. Let me know if you have questions or problems, and I'll try and fix and clarify things. One important basic idea is that the TCP/IP device drivers should appear as close to normal files as possible. As such, you should be able to access something like TC:"1.2.3.4";4711 to con- nect using TCP to IP address 1.2.3.4, at port 4711. This should work fine with any program that uses FCS. However, RMS is not able to do this. This is still a beta distribution, in which not all pieces are in place, or working. Known current problems are: o Documentation in places is still lacking some information and detail Page 1-1 INTRODUCTION o Installation and setup is a bit primitive and incomplete. 1.1 EXAMPLE USAGE Much of this document deals with how to use TCP/IP from a pro- gramming point of view, but there are several useful things that can be done without even writing your own programs. First of all, there are a number of clients provided that can be used for basic usage of TCP/IP. o TELNET - The TELNET client can be used for normal interac- tive terminal connections to remote systems. In addition, it can be used as a debugging tool, as it is able to con- nect to any port on a system, and not just the TELNET server port. o FTP - The FTP client can be used for transferring data to and from an RSX system. It can transfer text files as well as binary files. However, binary files received will be stored as variable length records with no further at- tributes. This is useful if you want files that are in a format not known to RSX. Typically jpeg images as well as all other types of unknown files will be stored like this. However, it is not a suitable format for most RSX files. There is also a BLOCK mode, which creates fixed length 512 byte records locally, which can be used when transferring task files. However, if transferring between two RSX systems, FTP will use a special mode which allows all types of files to be transferred correctly without any user intervention. o PIP - PIP can be used as a client for TCP/IP, essentially working in a similar way to netcat (a Unix tool to copy data to/from TCP/IP). Common ways to use PIP would be: . Copy data from a file to a remote destination: PIP TC:"remote";port=LB:[1,2]MCR.HLP . Show data on the terminal from a remote destination: PIP TI:=TC:;port . Copy data from a remote source to a local file: PIP EXAMPLE.TXT=TC:;port Note that when accessing TCP/IP through a program like PIP, there is a timeout of 30s on connections. If a con- nection has not been established in that time, the opera- tion times out and PIP exits with an error. Page 1-2 CHAPTER 2 THE BASIC TCP/IP IMPLEMENTATION 2.1 INTERFACES Each internet interface in BQTCP/IP is a seaparate device in RSX, with a name of IFn:. There are no special implications of the device number, it is just an enumeration of the devices. The cur- rent limit is 10 interfaces in the system, although only as many as you configure will actually be created at generation time. The interfaces are not ever meant to be used by user applica- tions directly, and they do only support a very limited set of functions that are very specific to BQTCP/IP. In addition, only privileged programs can ever even queue any I/O to the interface devices. If a program tries to issue I/O functions that actually pass through to the interface, it might cause all kind of havoc and sys- tem crashes. There is nothing meaningful to be had by directly using the interfaces, unless you really know what you are doing. The do- cumentation for the interfaces as such is something I can try to improve if someone wants to implement some new interface, but it's fairly low on my list of things to do, as the two most likely in- terfaces you might want to use already exist. Looking at the characteristics of an IF: device, CW2 and CW3 of the UCB holds the local IP address, while CW4 is the MTU of the interface. A little more detail on the UCB can be gleaned by looking at IFTAB.MAC. Interfaces essentially abstract away the layer below IP. As such, the IP level sends and receives packets from the interfaces. These packets have IP addresses as arguments, specifying where to deliver the packet. The interface supposedly knows how to directly deliver a packet to the given IP address, or else generate an er- ror. On packet reception, the interfaces deliver packets to the IP layer, including basic information about what the address was, and so on. This level of abstraction also means that interfaces like Ethernet keeps all ARP handling internally to the interface. In- terfaces might be able to do multicasting or not. Either way, they are expected to handle this without affecting IP. Note that the IP layer does not read from interfaces, but all data is pushed in both directions. The IP layer writes packets to the interfaces when it wants them transferred. The interfaces write packets to the IP layer when they are received. Each interface has the same basic information: ip address, netmask, broadcast address, acp, line name (device dependent on how it is used), mtu, flags and counters. PAGE 2-1 THE BASIC TCP/IP IMPLEMENTATION IP / ICMP 2.2 IP / ICMP IP and ICMP are both accessible through the IP: device, which implements raw IP access and ICMP access. Raw IP access is not really possible from user programs, but are meant for higher level protocols. The ICMP interface can be used in some limited ways by user programs, mostly for sending and receiving ICMP echo request packets (used by PING). Programs require to be privileged to talk to IP:. Looking at the UCB of the IP: device, CW4 is 8000., consider it as the MTU for the IP implementation. Packets up to that size are fragmented as needed when passed down to an interface. Larger packets than that are simply dropped. 2.3 UDP UDP is accessible through the UD: device. This device can be used by any program. However, creating an endpoint with a local port below 1024 does require that the program is privileged. Also, only one endpoint can ever exist at the same time for any local port. UDP is a packet based interface, so each read or write causes one packet to be sent or received. Excess bytes in the packets are lost if not read in the same operation. UDP will queue some amount of data for a port. Each opened port means that from an RSX point of view, the LUN will have context. A program cannot exit until the LUN has been closed, which is done automatically at task rundown. The UCB have CW4 set to 8000., which is the maximum size of a single UDP packet that can be handled. Finally, UD: also allows for settable timeouts on I/O, un- solicited ASTs when data arrives, and an additional user parameter to be passed in the AST. 2.4 TCP TCP is accessed through the TC: driver. TCP is a rather com- plex protocol, and the device driver implements a lot of things for the user program. Each local endpoint is identified by a port number. However, except for ports in the state of CLOSED, ACCEPT, LISTEN or DAEMON, the endpoint also has a remote address and port as a part of the identification. So several local endpoints may exist, using the same port number, as long as the remote endpoint differs. Endpoints for TCP can be in one of several states. The state of an endpoint decides which operations are allowed, and what the effects are of different type of packets on the endpoint. PAGE 2-2 THE BASIC TCP/IP IMPLEMENTATION TCP The states are: o CLOSED - The endpoint is closed o ACCEPT - The endpoint is waiting to accept a remote con- nection o SYN SENT - The endpoint has initiated a connection o SYN RECEIVED - The endpoint has received a remote connec- tion request o ESTABLISHED - The connection has been established o CLOSE WAIT - The remote end has closed the connection o FIN WAIT 1 - The local endpoint has been closed o FIN WAIT 2 - Waiting for the remote end to close o CLOSING - Both ends have closed o TIME WAIT - Endpoint is waiting for quiescent period o LAST ACK - Endpoint is waiting for the last ack from remote o LISTEN - The endpoint is listening for incoming connec- tions o DAEMON - The endpoint is a daemon (server) For endpoints in the ACCEPT, LISTEN or DAEMON state, addi- tional endpoints with the same port number can be created under certain circumstances. Just as with UDP, a program also requires to be privileged to create an endpoint with a local port number less than 1024. TCP is a stream connection oriented protocol. This means that data is sent as a sequence of bytes between two endpoints. Data might be sent in the same or different packets. Individual bytes might be returned in the same or different reads on the receiving side, independent of how they were sent. In order to make it easier to use TCP under RSX, you can, on a per endpoint basis, let TCP act in a line oriented fashion, meaning that it will write lines and append CR+LF at the end, using the same conventions as RSX in general. On reads, it will return all data up to the next CR+LF, which are stripped from the input, and the success code will be IS.CR. There are additional options that may be set on a TCP endpoint, which change how it processes read and write requests. PAGE 2-3 THE BASIC TCP/IP IMPLEMENTATION TCP In addition to this, TC: can do buffered input, meaning that reads will not block tasks from being checkpointed. Also, TC: buffers writes internally, so that unless the task is producing lots of data, writes will normally complete immediately, even though the data may not have been sent. Finally, TC: also allows for settable timeouts on I/O, un- solicited ASTs when data arrives, and an additional user parameter to be passed in the AST. Page 2-4 CHAPTER 3 INSTALLATION TCP/IP is distributed both as a tape image for use under the RSX VF: device driver, and as an RL02 disk image. The tape image needs to be extracted to a disk before instal- lation, after which the installation is identical to the disk dis- tribution. Usage of the tape image outside of RSX might be possible, but is not something that will be further explored in this document. The disk image will be easy to use both inside RSX by using the VF: device driver, and outside of RSX by either dumping the disk image into any existing disk that is 10M or larger, or connecting to an emulated disk in any of the existing PDP-11 emulators available. The disk image is a virtual RL02 disk, but will be usable through any disk which is at least the size of an RL02. The TCP/IP suite is installed by executing [IP]IPGEN.CMD and answering a set of questions. As a result, files will be created on the installation disk. The task files will also be copied to the system disk (LB:). After the IPGEN command file finishes, it optionally also runs through IPCONFIG, which is the configuration program for BQTCP. IPCONFIG can be run again at any time in order to change the configuration. It will default all questions with the previously selected values. After IPGEN and IPCONFIG have been completed, BQTCP may be brought up by running two scripts in the following order: o IPINS.CMD It is intended that IPINS.CMD should be invoked in STARTUP.CMD right after DECnet has started (or else anywhere early as soon as device drivers have been brought online). o IPAPPL.CMD It is intended to be invoked close to the end of the STARTUP.CMD, after all shared libraries and re- quired tasks have been installed and started. IPAPPL.CMD is where additional services that you want to start as a part of the TCP/IP services should be located. If you want to customize the actions of either of these scripts, it should not be done in these scripts, but in additional supporting scripts that you add. This allows IPINS.CMD and IPAPPL.CMD to normally be replaced at any update of BQTCP, there- fore any customization to these scripts will be lost at any update. Customization should instead be done in one of these scripts: Page 3-1 INSTALLATION o POSTIP.CMD This script is run at the end of IPINS.CMD, and this is the place where adjustments and tweaks to the basic TCP/IP configuration should be applied. At this point, no daemons or services have been started yet, beyond DNS. o PREAPPL.CMD This script is run at the beginning of IPAPPL.CMD, and this is the place to correct, update or add further information needed before various TCP/IP ser- vices and tools are started. o POSTAPPL.CMD This script is run at the end of IPAPPL.CMD, and this is the place to correct, update or add further services you want started as a part of the startup of BQTCP. Templates with example information and details are provided as POSTIP.NEW, PREAPPL.NEW and POSTAPPL.NEW. IPGEN.CMD can also, optionally, install all the help files provided with TCP/IP, and all the message files that are provided. The message files are typically template text files that are in- stalled under LB:[1,2]. In the case where you choose not to install the new files, they are still available for reference and comparision in the in- stallation disk, under the named directory [IP]. 3.1 GUIDELINES ON INSTALLATION QUESTIONS Most questions are pretty simple to answer, and require that you know a little bit about your environment and what setup you desire. First of all, if the installation is run several times from the same directory, the files from the previous installation are still around, and can be used for a new installation without having to answer all the questions anew. The installation also tries to handle if IPGEN is run from a different disk than the system disk. If there are any issues with this, please file a bug report with the author. 3.1.1 Interfaces IPGEN asks about the number of interfaces, with a default answer of 2. Typically, only the Ethernet and loopback interfaces are used, so 2 is the usual expected answer. There exists a few other interface types as well, and you could have more than one Ethernet. PAGE 3-2 INSTALLATION GUIDELINES ON INSTALLATION QUESTIONS Any questions or concerns about this should be directed to the author, who can give more details when or where required. 3.1.2 Additional information If DECnet over IP has been selected, IPGEN will also ask what UIC group number DECnet uses, and which device DECnet directories are located at. The typical defaults are group 5, and LB:. IPGEN also asks what files to install. In the initial instal- lation, you should install all files. But for future updates, it is usually enough to just install the binaries, and leave all the other files alone. IPGEN can also install some patches that fix some issues with RSX that are essential for BQTCP to work correctly. These patches are only required to be installed once but nothing is broken if they are installed multiple times. 3.2 HELP BQTCP/IP comes with some help files. If they are installed into the LB:[1,2] directory, they can be accessed by the normal HELP command. o IP.HLP HELP/IP will dislpay the top level help. o FTP.HLP HELP/IP FTP will display the top level help for FTP. This help file is also used by the HELP command from within FTP. 3.3 CONFIGURATION Configuration is done with a scipt named IPCONFIG.CMD. When BQTCP has been installed, it then requires a configura- tion to be able to start running. The first time IPGEN is run, you can optionally do the configuration already as a part of IPGEN. However, it is also possible to run IPCONFIG at any later time. If BQTCP is attempted to be brought up without IPCONFIG ever having been run, IPINS will optionally run IPCONFIG at that point, or else it will refuse to start BQTCP. If BQTCP has been configured, but information is missing from the configuration, IPINS will warn about this, but will optionally attempt to run with some assumed default values. (This can happen if the configuration was modified by a user by hand, or if new con- figuration values are added at a later point to the system.) PAGE 3-3 INSTALLATION CONFIGURATION If information is missing, and it is selected to not continue with the startup, it is also possible to just update the configura- tion with the missing/new values that been defined for the confi- guration. After such an update, the configuration would be complete, and the startup will then proceed to start TCP/IP. If TCP/IP is updated on a system, any new parameters will au- tomatically be prompted for at that point as well, in order to help in making the configuration complete. The IP pool is used for all functions within BQTCP, and if too little pool has been allocated, performance is degraded, or the lack of pool space might even cause some parts to become non-functional. The recommended value for the IP pool is 256 KB, which is enough for any normal setup. 3.3.1 Interfaces IPCONFIG will try to configure all interfaces defined during IPGEN. It will default all interfaces except the last one to be using Ethernet, and the last interface it will default to Loopback. 3.3.1.1 Loopback An interface without an ACP will always only work as a loop- back interface, so this is the correct value to use for a loopback interface. 3.3.1.2 Ethernet The Ethernet interface needs various configuration information provided by the user. Ethernet can use DHCP, but it is not re- quired to. DHCP can also be used for just selected appropriate networks. If DHCP is not used, then the IP address and network mask needs to be provided when running IPCONFIG. In addition to the IP configuration values, the Ethernet in- terface also needs to be told the line name of the line. Exactly what line name to use depends on a few things, but this needs to be set correctly for anything to work. If you are using DECnet, then the line name should be the line name used in DECnet for the Ethernet line. Typically "UNA-0" for a Unibus machine, or "QNA-0" for a Qbus machine. If you are using the RSX XE: device driver, then the line name is typically "UNA-0" if you have a DEUNA controller, and "LUA-0" if you have a DELUA controller. If you are running under some simulator like SimH, the distinction between DEUNA and DELUA PAGE 3-4 INSTALLATION CONFIGURATION might not matter, since it is used by the XE: device driver to just download the correct microcode to the controller, and a simu- lated system will most likely not simulate that functionality cor- rectly anyway, and just work without regard to the microcode download. 3.3.1.3 SLIP The SLIP ACP is named SLPACP, and the line value is then used to tell which serial line it should be using. 3.3.1.4 DDCMP BQTCP can communication over DDCMP links, if DECnet is in- stalled. Such links are available through the network communica- tions executive using the DLX API. DLXACP is the name of the ACP for these lines, and the line value should then be the DECnet line name for the line to use. 3.3.2 Additional information After providing information about the interfaces, there are also a few network and configuration generation questions. The network related questions might not be asked, if you have selected DHCP for the specific pieces of information. The address of the default router (gateway) is clearly needed for connectivity to the rest of the internet since that is how IP routing works generally. The IP address of your DNS server is needed for DNS lookup to work. It should be a proper IP address, and not a name. Unlike UN*X/Linux setup, you specify only one DNS server address. The default domain name is used in queries to the DNS server. If a hostname is given without any domain information, the default domain name is appended to the host name. Page 3-5 CHAPTER 4 CONFIGURATION At installation time, a few basic configuration questions are asked, such as how many interfaces to create. Everything except the numnber of interfaces can be changed later. The size of the IP pool is by default 256K, but can be changed to any suitable value before the pool is created. At startup, about 7.5K is used by various internal tables and initial buffers. All the rest is available for use at the protocol level. Each TCP connection, for example, uses 192B of IP pool. UDP connections do not use any pool at all. IP addresses, netmasks, ACPs, and line names can be changed on interfaces that are not up. Routing tables and ARP parameters can be changed any time. 4.1 LOGICAL NAMES BQTCP uses logical names for a lot of configuration details. This is a list of all the logical names, a short explanation for each of them, and how and where they are used along with suggested values. Some of these logical names can be overridden on a per user basis, while others are only meaningful as global logical names. o HOSTNAME This is the name of the machine. It can be used by programs that want to find the name of the local machine. o DNS$DOMAIN This is the domain name of the machine. It is used by the DNS part of the resolver, which appends the domain name to the host name queried if no domain name was given. It can be set by DHCP, or in the IPINS startup script. o DNS$SERVER This is the address of the DNS server(s). It is expected to be a numeric address, as DNS cannot be used to look up the DNS server. This logical name is intended to be used for adding specific DNS servers for the system. DNS servers given by DHCP are handled in a separate logi- cal name. Multiple DNS servers can be given, separated by commas. o DNS$SERVER$DHCP This is the address of the DNS server given by DHCP. It is used in addition to any servers given by DNS$SERVER. Multiple DNS servers can be defined by this logical name, separated by commas. o RESOLV$ORDER This is the order in which name resolution tries different methods for looking up host names and IP addresses. It is a comma separated string of keywords. PAGE 4-1 CONFIGURATION LOGICAL NAMES Valid keywords are "LOGICAL", "FILE", "DNS" and "MDNS". Typically, it would be "LOGICAL,DNS,FILE". o DHCP$IFx This is the DHCP configuration for each interface (where x is the unit number for the specific interface). It informs DHCP which parts of a DHCP configuration to ap- ply to the machine. It is a comma separated string of keywords. Valid keywords are "RTR", "DNS", "DOM" and "NTP" for example: ",RTR,DNS,DOM". There is no need for a comma before the first keyword, nor after the last, but it is allowed to have extra commas in the string. Note that "RTR" is the Gateway address. The values correspond to different DHCP options that can be provided by a DHCP server. And if the keyword is included in the logical name translation, the correspond- ing value is applied to the TCP/IP system. The values: o RTR - Default router o DNS - Domain name server o DOM - Domain name o NTP - NTP server o DHCP$IFn$SERVER This is the logical name DHCP creates for each interface to remember the server that provided the address used. o HOST$name This is the translation from hostname "name", and the corresponding string should be an IP address. o HOSTS This is the logical name that points to the HOSTS file, which should hold IP addresses and hostnames. o IP$n.n.n.n This is a reverse mapping from IP address to the corresponding hostname. o IP$LOG This is a logical name that points to the directory where logs from various daemons should be placed. Note that this is NOT required to exist. o NTP$HOST This is the host to which NTP should sync the clock. Used by NTPDAT(E). o IRC$HOST This is the host to connect to for IRC. o IRC$NICK This is the nickname to try and use when running IRC. It probably does not make sense to have a global logical for this. o IRC$CMD This logical gives a single command that you want to execute when starting IRC. PAGE 4-2 CONFIGURATION LOGICAL NAMES o IRCBOT$HOST This is the host that the IRCBOT daemon should connect to. o IRCBOT$NICK The nickname that the IRCBOT should use. o IRCBOT$CHANNEL The channel that the IRCBOT should join. o IRCBOT$COOKIE If set, the IRCBOT will respond to cookie requests. If not set, only a few basic functions will be provided by the IRC bot. o FTP$USER_name This logical name defines an anymous ftp user, with the username "name". The translated string is the directory where the ftp daemon serves files from. You can have any number of these anonymous users, and they all run under UIC [377,377]. Anonymous users cannot access any other directory than the one given by the logical name. o FTP$UPLOAD If this logical name is defined, then anonymous users can also upload files. Uploaded files are placed in the directory given by this logical name, and are not ac- cessible by anonymous users, unless you also have an anonymous user that have the same directory as their "home". o FTPD$TIMEOUT This logical name is used to set the session timeout in seconds for the FTP daemon. A value of less than 10 seconds is not accepted. The default value, if not defined, is 900 seconds. o SYS$UTC_OFFSET This logical name should hold the number of minutes east or west (west having negative numbers) of UTC that the system is. Services that present time use this logical name to adjust from local time to UTC time. o TFTPD$SPEC This logical name contains a list of switch values that defines how TFTPD is configured. o TELNET$WELCOME This logical name is used by the telnet server as the initial message printed out on connecting terminals. Alternatively, it can also be a command to be executed at the connected terminal. o TELNET$TERMINALS This logical name is used by the telnet server to find out how many terminals to create at startup. o TELNET$PORT This logical name is used by the telnet server to define which port it should listen on. If no logical name exists, or if the value is not a number, the telnet server will listen to port 23. This logical name can list several ports separated by commas. o TELNET$LOG This logical name, if defined, leads to the telnet server logging each connect and disconnect on the console. PAGE 4-3 CONFIGURATION LOGICAL NAMES o SYS$HTTP This logical name points to the directory where the CGI library is located. o HTTPD$ROOT This logical name points to where the confi- guration files for the WWW daemon is located. o $PRINTER This logical name tells the LPT spooler what kind of printer you have, and at what address it is located. o SPOOF$EXCLUDE This logical name is used to exclude certain addresses from being processed by the spoofer. o SMTP$RELAY This logical name is used by MAIL to deliver all mails over SMTP. If not defined, MAIL will try to connect to the actual destination using DNS to lookup pos- sible MX records. o SMTP$DOMAIN This logical name is used by MAIL for all out- going mails over SMTP. It is the domain name to place on mail addresses. If it is not defined, the fully qualified domain name of the host will be used. 4.2 FILES BQTCP uses a few special files. o LB:[1,2]WELCOME.TXT - A file that is printed out by the FTP server to the FTP client when the FTP client connects to the FTP server. o LB:[1,2]FTP.TXT - A file that is printed out by the FTP server to the FTP client when the client logs in to a normal acocunt. o FTP.TXT - A file in the "home" directory that is printed out by the FTP server to the FTP client when the client logs in to an anonymous account. o LB:[1,2]ANONYMOUS.TXT - A prototype file that can be used to setup FTP.TXT files for anonymous login, similar to LB:[1,2]FTP.TXT. o LB:[1,2]FTP.HLP - The help file used by the FTP client. o LB:[1,2]IP.HLP - The help file for most IP related tools. o HTTPD$ROOT:PUBLIC.TXT - The file used by WWW task to map URLs to files. o HTTPD$ROOT:DEFAULT.TXT - The file used by WWW task for per-user mapping when no user file exists. PAGE 4-4 CONFIGURATION FILES o HTTPD$ROOT:CONTENT.TXT - The file used by WWW task for mapping between file extensions and HTTPD content types. o LB:[1,6]RWHOD.DAT - The file used by the RWHOD server and clients to collect and show remote host information. 4.3 DHCP Ethernet interfaces can be configured using DHCP. DHCP can be run as one instance for all DHCP enabled inter- faces, or one DHCP task per interface. The choice is decided by examining the name under which the DHCP task is running. If the taskname starts with "IF", DHCP will operate on only one specific interface. The rest of the task name is then expected to be a number, which is the interface on which DHCP will be operating. If the taskname is anything else, DHCP will scan all interfaces, and configure all that are marked as DHCP enabled. For each DHCP-enabled interface, the DHCP client will try to configure the interface using DHCP. This means it will send out queries on the interface, and accept configurations from a DHCP server. When configuration data is received from a DHCP server, the DHCP client will selectively use some information in the reply to configure IP. The things that will be configured is further controller by a logical name of the form DHCP$IFn, where the n is a digit unique for each interface. The DHCP client may configure the following properties: 1. The interface address and network mask. 2. The default router (this is controlled by the RTR flag in the logical name) 3. The domain name server (this is controlled by the DNS flag in the logical name) 4. The default domain name (this is controlled by the DOM flag in the logical name) 5. The NTP server to use (this is controller by the NTP flag in the logical name) A typical DHCP$IF0 (for example) logical name would look like this: ",RTR,DNS,DOM" When DHCP is enabled, and an interface is being used for the default route, DHCP also creates logical names for the DNS service. DHCP uses the HOSTNAME to find out the name of the local machine, and creates HOST$name giving the IP address assigned, and IP$n.n.n.n giving the host name from the IP address. Thus, if the name resolver is set up to use logical names, any dynamic address PAGE 4-5 CONFIGURATION DHCP given by DHCP will then translate to the hostname of the machine for local use. DHCP will also, optionally define the DNS$SERVER$DHCP, DNS$DOMAIN and/or NTP$HOST logical names with information provided over DHCP. Note! There are some possible problems if several interfaces have DHCP enabled, as the broadcast address will be switching between interfaces as DHCP is running, and the routing entry for broadcast will end up being the last interface configured over DHCP. If this ever becomes a problem in actual usage, some solu- tion will need to be designed and implemented. Page 4-6 CHAPTER 5 TOOLS 5.1 IFCONFIG IFCONFIG is the primary tool for changing the configuration of the TCP/IP protocols. It has several commands for various tasks. Only privileged terminals can make the most use of IFCONFIG. See [IP]IFCONFIG.TXT for a summary of what commands IFCONFIG understands, or HELP/IP if the IP helpfile has been installed in the right place. 5.2 NETSTAT NETSTAT is a program to display network statistics. Switches: /PORTS List ports /STATS Show network statitics /IP Show IP related information /ICMP Show ICMP related information /IGMP Show IGMP related information /UDP Show UDP related information /TCP Show TCP related information /ALL Show all ports, and not just connected ones /NUMERIC Show IP addresses as numeric instead of using DNS Switches can be combined in all possible ways. Switches can also be considered to be in two groups. Protocol switches, and functions. For protocol switches, the default is /IP/ICMP/UDP/TCP, and the default function is /PORTS. 5.3 PING PING is a simple program to check network connectivity by sending ICMP ECHO REQUEST packets and reading replies. It understands the following switches: PAGE 5-1 TOOLS PING /COUNT=n /SIZE=n /NOFRAGMENT /NUMERIC /NOLOOPBACK 5.4 TRACERT TRACERT is a traceroute program that uses ICMP packets. It is normally installed with the name TRT. TRACERT understands the following switches: /MAXTTL=n /NUMERIC Page 5-2 CHAPTER 6 DAEMONS 6.1 LOGGING DIRECTORY PATH As a general principle, when daemons do logging, they will do it to the directory where the logical name IP$LOG: points to. 6.2 TCP BQTCP comes with the following TCP daemons: 6.2.1 TELNET The TELNET daemon services incoming TELNET connections. It uses a common region for communication with the TT: device driver, and this region is protected from access by normal users. However, because of the way the TT: device driver works under RSX, this common is dependent upon locations in the kernel that can move if the kernel is rebuilt, and it is not possible to build this common vectorized. So if the kernel changes, this common needs to be re- built, or else the system will likely crash when someone connects using telnet. Rebuilding the TELCOM common region is however easy. Just run TKB, giving TELCOM.CMD as the command file for it, and the region is rebuilt. The number of terminals created for telnet use is decided through a logical name. If the logical name does not exist, or if the name does not translate to a decimal or octal number, the default value of 10(8) terminals are created. In order to change this number, the system needs to be rebooted. The maximum number of terminals possible is 40(8). Logical names: TELNET$WELCOME The telnet daemon uses a logical name to find the message to print out to new connected terminals. If the logical name is not set, it will use a default mes- sage of "This is an RSX-11M-PLUS system.". If the translated string starts with an '@', the rest of the string is a command that will be executed on the terminal. Remember that the terminal is not logged in, so only com- mands that are allowed for logged out terminals makes sense to put here. Typically this would be a HELP com- mand, to display a longer welcome text. TELNET$TERMINALS The telnet daemon uses this logical name to find out how many terminals to create. PAGE 6-1 DAEMONS TCP TELNET$PORT The telnet daemon uses this logical name to find out which port it should listen to/on. Default is port 23. Several ports can be listed, separated by com- mas. TELNET$LOG This logical name, if defined, leads to the telnet server logging each connect and disconnect on the console. When the TELNET daemon is running, it keeps information about the current number of telnet sessions in R0, and the total number of telnet sessions in R1,R2, which can be viewed in RMD, or with the TAL command in MCR. 6.2.2 FTPD The FTP daemon serves FTP requests. It can handle text and binary files, as well as a special transfer mode for RSX and VMS files. Binary files are stored on RSX systems as variable length binary files, so it is not possible to transfer files like tasks. The file attributes will be wrong. If fixed length binary files need to be transferred, you can use the FTP client to retrieve the file instead, or use the special RSX or VMS transfer modes, which can transfer any kind of file across FTP. However, the RSX or VMS modes do not work when both machines are not RSX or VMS machines. Another option is to use a program that can encode binary files as text files, transfer the text file, and then decode the text file back into a binary file at the destination. The FTP daemon uses a couple of files and logical names for the configuration. 6.2.2.1 Logical names Logical names: FTP$USER_xxx are anonymous users (if any) allowed onto the system without giving a password. The will be restricted to only the directory that the logical name resolves to, and will use a UIC of [377,377]. FTP$UPLOAD If this logical name exists, and points to a valid directory, anonymous users are allowed to upload files. Uploaded files will be placed in this directory. If the logical name is not defined, anonymous users are not allowed to upload files. FTPD$TIMEOUT If set, this is the session timeout in seconds to use for the FTP daemon. A timeout of 0 means there is no timeout. The default is 900 seconds. PAGE 6-2 DAEMONS TCP 6.2.2.2 Files Files: LB:[1,2]WELCOME.TXT - A file that is printed out to the client when the client connects to the FTP server. LB:[1,2]FTP.TXT - A file that is printed out to the client when the client logs in to a normal account. FTP.TXT - A file that is printed out to the client when the client logs in as an anonymous user. The file should be in the same directory as the anonymous user accesses. There is a prototype file in the distribution, found at LB:[FTPD]ANONYMOUS.TXT that may be used and customised as desired. 6.2.2.3 Logging FTP also logs all logins, logouts and failed logins to CO:, the same way normal logins are done. The log will tell that it is an FTP entry, and will also include the IP address the connection originates. FTP also logs all transfers in IP$LOG:FTPD.LOG, if the path exists. 6.2.2.4 Limitations on user access If a normal user logs in, a check is made against the account- ing file for password. There is also checks that the account is not disabled or have expired. Finally, the account must be allowed to login remote and from network, or else FTP access is denied. 6.2.2.5 Known problems and limitations There are a number of known problems and limitations to the FTP server. Here is an attempt to list them. o The server does not understand a bunch of commands, such as CDUP, RMDIR, MKDIR, and extensions to the FTP protocol. o The documentation is lacking. o The communication can get out of sync between client and daemon, at which point you have to restart the session. PAGE 6-3 DAEMONS TCP These issues might be improved on in further releases. 6.2.3 INETD INETD is a server program designed to be able to provide all kinds of generic TCP services. When it starts, it looks at what port number it was started for, and if the port is known, it jumps to the handler for that service. If the port is unknown, the con- nection is rejected. INETD today has code to handle the following services: o ECHO o SINK o DAYTIME o QUOTD o IDENTD 6.2.4 WWW WWW is a web server written in BASIC+2. The code is in [HTTPD]*.B2S, and it can serve both static content and dyanmically generated content by running other tasks. The WWW task can be invoked in many ways, but the recommended method is to setup a TCP daemon socket. 6.2.4.1 Installation On a new system, you should start with copying the following files from the distribution to the file names listed below, and then you can start changing the content as you desire. 1. INDEX.SRC -> INDEX.TXT 2. DEFAULT.SRC -> DEFAULT.TXT 3. CONTENT.SRC -> CONTENT.TXT 4. 400.SRC -> 400.HTM 5. 404.SRC -> 404.HTM 6. 405.SRC -> 405.HTM In addition, the HTTPD$ROOT logical name needs to point to the directory where these files are set up. PAGE 6-4 DAEMONS TCP 6.2.4.2 Configuration As supplied, WWW is built to use the HTTPD$ROOT logical name to find where all configuration files are located. WWW uses several files for operation: 1. PUBLIC.TXT 2. DEFAULT.TXT 3. CONTENT.TXT 4. 400.HTM 5. 404.HTM 6. 405.HTM Each of these files are explained in detail in the following sections. 6.2.4.2.1 PUBLIC.TXT - PUBLIC.TXT is the initial file referred to in order to translate incoming URLs to filenames. PUBLIC.TXT contains lines in text form, and each line contains two values separated by whi- tespace. The first value is a URL to match (this should always start with a slash). This can be just an initial part of the requested URL, and it can also hold wildcards (*). If a requested URL matches that WWW should use. If the match ends with a wildcard, it will normally match everything, including URLs that contain addi- tional slashes, meaning you match a whole sub-tree of the served pages. If you only want the wildcard matching to match at the cur- rent level, append a dollar ($) after the wildcard. This dollar sign will not be matched against, but is the indication that the wildcard match should terminate at this level, and subtrees should not be matched. The second value gives the target. Targets can be filenames, programs, other files for continued matching, or redirects. The notation is: o Filenames A filename is a partial or full RSX filename specifi- cation. The default directory is the same as where the PUBLIC.TXT file is located. As a special case, if the match contains a wildcard, the filename can also contain a wildcard, and the corresponding part from the requested URL will be inserted in the filename at that point. PAGE 6-5 DAEMONS TCP o Programs to execute If the target starts with "GGI:", "MCR:", "DCL:", or "CLI:", the filename after the colon will instead be a line executed by the CLI in RSX. With CLI, the actual CLI will be the default CLI for the user. For CGI, the cli will be MCR. o A different file If the target starts with "@", the rest of the target is a new file that will be interpreted the same way as the PUBLIC.TXT file, and the rest of the URL beyond the cur- rent match will be used against this new file. o Redirects If the target starts with "->", the target will result in a redirect response, where the string after the "->" is the target that will be provided in the redirect response. 6.2.4.2.2 DEFAULT.TXT - When a requested URL starts with "/~", it is assumed that everything up to the next slash is a username. Usernames can be in the form "[uic]", "LASTNAME", "F.LASTNAME" or "SID". When a user is identified, WWW will try to access PUBLIC.TXT in that user's home directory instead of the global PUBLIC.TXT file. If the user do not have a PUBLIC.TXT file, the global DEFAULT.TXT file will be used instead. The format is identical to the PUBLIC.TXT file. 6.2.4.2.3 CONTENT.TXT - This file holds mappings between file extensions and the mime types that WWW should provide when serving information. There is a default CONTENT.SRC provided with the distribution, which gives mime types for a few typical file types. More can be added as re- quired. Provided types: . HTM - text/html . JPG - image/jpg . GIF - image/gif . ICO - image/vnd.microsoft.icon . PNG - image/png PAGE 6-6 DAEMONS TCP . PDF - application/pdf . * - text/plain 6.2.4.2.4 400.HTM - If a request results in a 400 (Bad request) response, WWW will try to also provide the content of 400.HTM as a part of the response, where you can customize how the error message is presented. 6.2.4.2.5 404.HTM - If a request results in a 404 (Target not found) response, WWW will try to also provide the content of 404.HTM as a part of the response, where you can customize how the error message is presented. 6.2.4.2.6 405.HTM - If a request results in a 405 (Method not allowed) response, WWW will try to also provide the content of 405.HTM as a part of the response, where you can customize how the error message is presented. 6.2.4.3 Operation The WWW daemon normally runs without any intervention. All accesses are logged, and daemons time out and exit after a while if no traffic arrives. However, with CGI scripts, the WWW daemons can get stuck if there are bugs, so it can be a good idea to keep an eye open for long standing WWW sockets, and related virtual termi- nals. Unstopping such processes are most easily done by just aborting the WWW daemon. WWW is installed with privileges, but drops the privileges when accessing files, as well as running under the UIC of the specific user. 6.2.4.4 Logging The HTTP daemon logs accesses under IP$LOG:ACCESS.LOG, and failed accesses under IP$LOG:ERROR.LOG, if IP$LOG: points to a valid directory. PAGE 6-7 DAEMONS TCP 6.2.4.5 Known problems and limitations This is a short list of known problems and limitations. o The documentation is lacking. o While possible to access files over DECnet, it might be slow. Proxy access is also complex. 6.2.4.6 Rebuilding There is a makefile in the source directory, which can be used to compile and task build the WWW daemon. WWW.OBJ can be built in two variants. This is controlled by the /VARIANT:n switch. Variant 0 creates a WWW server that can be run standalone. It tries to create a socket to listen to, and accepts a single connec- tion on that socket. This variant is useful if you want to debug and develop the code, as any output is done to the running termi- nal, and you have full control of the execution, and port numbers used. Variant 1 creates a WWW server that is usable as a daemon. It tries to open a TCP connection it should have inherited from a con- trolling process. This is a better solution for a daemon, but is not as easy to use for development. When WWW is built, a few configuration values are defined in WWW.INC. These include the default directory where WWW will find configuration files, as well as under which UIC it will run by default. 6.2.4.7 Serving pages for users WWW normally serves pages based on HTTPD$ROOT, where the PUBLIC.TXT and all other files are expected to be found. However, if the first element in the URI is a tilde (~), then the rest of the first element is taken as a user. Users can be identified either through LASTNAME, F.LASTNAME, DIRECTORY, UIC, or SID. The corresponding user is located in the accounts database, and the home directory of that user found. WWW then uses that home directory in order to access PUBLIC.TXT, and all subsequent file references are done relative to that home directory. In this situation, WWW also runs with the rights of that user, meaning only files that that user have access to can be accessed by the WWW server. PAGE 6-8 DAEMONS TCP 6.2.4.8 Virtual hosts WWW can also serve virtual hosts. This is done by matching the HOST keyword in the http request header. If there is a VHOST.TXT file in the HTTPD$ROOT directory, this file is searched through to matching host names. Valid lines contain at least one space, which separates the host from the target. The host field should exactly match the host header of the http request (this is matched case insensitive). If a match is found, the target part is then used for all further pro- cessing and serving of the http request. The target can be in one of two forms: 1. A directory. This directory will then be the default directory for all further lookups, meaning PUBLIC.TXT and the error files will be searched in this directory in- stead. 2. A hostname preceded by "->", which means the whole request will be redirected with the original URM, but with a new host name. The redirect results in a 301 response from the WWW server. 6.2.5 MAIL The MAIL daemon will actually communicate both over TCP and DECnet, using the smtp protocol for TCP, and the MAIL11 protocol for DECnet. See the separate chapter on MAIL for more information. 6.3 UDP BQTCP comes with the following UDP daemons: 6.3.1 DHCP The DHCP daemon is still actually a client, but it is intended to be run in the background, updating address and other information on a running system. If installed with the name of an interface, it will run at a regular interval to refresh the information on that interface. If installed with some other name it will run at a regular interval and refresh all interfaces. PAGE 6-9 DAEMONS UDP There is a configuration in a logical name for the DHCP daemon, and apart from that, there is nothing more you can do with it. 6.3.2 TFTPD The TFTPD daemon can serve files from RSX over UDP to TFTP clients. TFTP is a primitive protocol for file transfer, that does not allow much protection or performance. It is not recommended to use, except under rather specific circumstances. The TFTP daemon is configured through a logical name. 6.3.3 RWHOD The RWHOD daemon regularly broadcasts information about the RSX node over UDP to any other machines listening. The information include machine name, uptime, load, and logged in users. In addi- tion, the RWHOD daemon also receives such broadcases from all other hosts on the local network. RWHOD stores any incoming host infor- mation in LB:[1,6]RWHOD.DAT. Page 6-10 CHAPTER 7 CLIENTS 7.1 TCP The BQTCP disribution contains the following TCP clients: 7.1.1 TELNET TELNET is a simple telnet client. Code is in [IPAPPL]TELNET.MAC. 7.1.2 FTP FTP is a standard TCP/IP FTP program, which can be used to transfer files to and from a RSX system. The program can transfer text, binary and block data. The difference between binary and block data is how it is stored on the RSX system, where block data is stored in fixed length 512 byte records, while binary is stored in variable length records. This means that binary data from another system may be stored, and transferred back without being altered in any way while on RSX. However, some files, such as RSX11M tasks, really need to be fixed length 512 byte records. If the received data is not a multiple of 512 bytes in length, the last record will be padded with NULs. The FTP program will try to run initial commands from a file called FTPINI. This file has a default name of SYS$LOGIN:.INI, which means that if there is a logical name FTPINI, it will be used to find the init file. If no logical name exists, FTP will try to open and read SYS$LOGIN:FTPINI.INI for the initial commands. After the FTPINI file has been processed, FTP tries to open and process SY:FTP.INI, which means that a local initialization file can be used to override a more global init file. The FTP program has a brief HELP command which lists the com- mands the program currently implements and understands. More detailed help and information will be written later. The sources for the FTP client program are provided. 7.1.2.1 Building There is a makefile to rebuild FTP. FTP is written in MACRO-11. Code is in the named directory [FTP]. PAGE 7-1 CLIENTS TCP 7.1.2.2 Known issues and limitations The FTP client has a number of known issues and limitations. Here is an attempt at listing them. o It is not possible to abort an ongoing transfer graciously when connected to some target systems. It is not clear why some systems don't react properly to the abort. o Lots of commands are missing, such as CDUP, MKDIR, RMDIR, and various FTP protocol extensions. o The documentation requires improvement. It is hoped that these issues will be addressed over time. 7.1.3 IRCBOT IRCBOT is a silly IRC ROBOT written in BASIC+2, which can respond to IRC messages by sending cookies based on some simple rules. All the code is in [IRCBOT]*.B2S 7.1.3.1 Building There is a makefile that may be used to build IRCBOT. IRCBOT is written in BASIC+2, so the correct compiler must be installed on the system in order to rebuild IRCBOT. It has been tested on com- piler version V2.7. 7.1.3.2 Configuration All the configuration is in the source code, except for which host to connect to, which is controlled by a logical name. 7.1.3.3 Operation The IRCBOT can be started at any time on the system, and it will continue running until aborted. Any data received will be logged in IP$LOG:BOT.LOG. Note that this file can grow very large in a short time. PAGE 7-2 CLIENTS TCP 7.1.4 IRC IRC is a simple IRC client. IRC is a program to communicate between users over TCP/IP. It can be compared to PHONE, however it is slightly less interactive, but can have many more concurrent users, and it also has "rooms", where many people may communicate in groups. 7.1.4.1 Building Source files are in [IRC]. There is a makefile to build IRC. IRC is written in BASIC+2, so the correct compiler must be in- stalled on the system to rebuild the software. 7.1.4.2 Configuration IRC looks for four logical names: o IRC$HOST - The host to connect to. o IRC$PORT - The port to connect to. Default is 6667. o IRC$NICK - The nickname to use for the user. o IRC$CMD - An initial command to execute when starting up. The logical names can also be overridden by switches on the command line: o /HOST: - The host to connect to. o /PORT: - The port to connect to. o /NICK: - The nickname to use. o /CMD: - A command to execute. o /-CMD - Do not execute a command, even if a logical name existed. o /NOCMD - Same as /-CMD Finally, if some required information is not known when IRC starts, it will prompt for the missing information before it ac- tually starts connecting to a server. Once running, IRC understands a few built in commands, and can also pass commands to the IRC server. PAGE 7-3 CLIENTS TCP Commands always start with a colon (:) as the first character on the line. Current known (implemented) commands: o :J - Join a group o :M - Sends a message to a specific target o :S - Set a default target for messages o :N - Change the nickname o :Q - Quit Any other command is sent to the IRC server. Any line not starting with a colon is sent to the default target as a message. The first group joined becomes the default target until it is explicitly changed by a command. 7.1.5 LPT LPT is a client that works together with the QUEUE manager in order to implement a spooler for LPT capable printers connected through or using TCP/IP. 7.1.5.1 FORMS information The RSX printer queue system is a very complex and advanced system. One of the details used is a property named FORMS. FORMS are used to define different paper types, formats and layouts. In the most simple case, a spooler only has one FORM, and a print request also has only one FORM, and the file is only printed if the spooler form matches the print request form. Otherwise the print job is just left in the print queue. However, some printers are a bit more advanced, and can change their layout or paper through software control, and as such can service requests for different forms. The LPT spooler is designed to do this. In order to get this kind of functionality, the spooler needs to be installed with a special form. DEC reserved forms 124 to 127 for such a spooler. Normally, they were reserved for different types of printers, such as the LN01 or LN03. However, the LPT spooler uses this information to select what the default form for actual print jobs are. The actual printer type is retrieved from a logical name by LPT. PAGE 7-4 CLIENTS TCP The second part is that once a spooler is installed as one of these special spoolers then by default the queue manager thinks it can handle forms 3 to 7. A print request without an explicit form is printed using form 0 so such a request will then not be printed but only queued. The solution is to rebuild the queue manager, which can be done through the running of the explicit rebuilding of system pro- grams in the SYSGEN procedure (see the System Generation Manual for details on this). This will create the build files for QMG..., and in there are the symbols Q$LSPF and Q$HSPF, which may be changed to appropriate values (it is suggested forms 0 and 177). Once the queue manager have been rebuilt, installed and res- tarted, it will be possible to print with any number of different forms on the LPT spooler. The LPT spooler then makes use of the requested form to set up the printer in specific ways. The following table explains the relations between the spooled form, and the printed form. Printed form Spooled form 124 125 126 127 0 LH PH LF PF 1 PH LH PF LF 2 LF PF LH PH 3 PF LF PH LH The different abbreviations in the above table are explained in the following list: o L means landscape mode o P means portrait mode o H means half duplex (single sided output) o F means full duplex (double sided output) If the printer does not support full duplex, those forms be- comes equivalent to the half duplex equivalent forms. 7.1.5.2 Building Sources are found in the named directory [LPT]. There is a makefile to build the software. It is written in PDP-11 C, so the correct compiler (DEC PDP11 not the DECUS one) must be installed on the system in order to rebuild the client. PAGE 7-5 CLIENTS TCP 7.1.5.3 Printer control The LPT spooler can handle multiple types of printers, and can be installed and configured as different spoolers for different printers. The LPT spooler will find out which printer type, and whan ad- dress to connect to through a logical name in the form of $PRINTER. So if the spooler is installed as LPT, the logical name it will look for will be LPT$PRINTER. The logical name should translate to -
;. The printer types currently supported are: o ANSI A simple printer handler that uses normal ANSI se- quences to control the printer. The queue parameter is not used. o PCL A printer handler that uses the HP PCL language to control the printer. The default port connecting to is 9100. The queue parameter is not used. o LPR A printer handler to talks the LPR protocol to a printer server, which can either be a printer, or some machine that runs an LPR server. The default port connecting to is 515. The queue parameter is used to tell which printer queue to use at the remote server/printer. Adding new types is fairly straight forward and is most easily done by copying the ANSI.C file for the new printer type, and add this file to the list of the MAKEFILE., and then run MKE, which will recompile the spooler. The printer destination is either an IP address, or a name that can be looked up through the resolver. It can optionally also include a port number, but otherwise the port number default depends on the printer type selected. An example value for LPT$PRINTER could be "pcl-1.2.3.4" which would be a PCL printer at address 1.2.3.4. PAGE 7-6 CLIENTS TCP 7.1.5.4 Installation There is an example INS.CMD file located in the [LPT] direc- tory, which can be used as a source of how to install the spooler and configure it. In a real system it might make more sense to include these commands in LB:[1,2]QMGSTART.CMD. Remember to remove the original queue manager task from the system if it has been rebuilt, as QMGSTART will use the existing installed task otherwise, and not the rebuilt version. Either remove the QMG... task using VMR, and leave it that way for QMGSTART to then install the task, explicitly remove QMG... in QMGSTART before it tries to install it, or install the latest QMG... in VMR, so that it is already in place when QMGSTART is in- voked. 7.1.6 LPQ LPQ is a program to query remote printers using the LPR pro- tocol, and LPQ will show queued print jobs on the printer. If no argument is give, LPQ will show the queue for the host named by the LPT$PRINTER logical name. If an argument is given to LPQ, it will try to connect to this as a hostname, using the LPR protocol. 7.1.7 MAIL There is a mail client that can be used for both local mail, TCP/IP and DECnet. See the separate chapter on mail. 7.1.8 TNC2 TNC2 is a program included with the TELNET daemon, but TNC2 itself is a client program. It is suggested to be run as a part of the login scripts. TNC2 will check if the TI: terminal is a telnet terminal, or a LAT terminal, and if so, it will define a set of logical names for the session login logical table: o REMOTE will have the value "TELNET" or "LAT" o REMOTE$HOST will have the hostname of the remote host o REMOTE$ADDR will have the address of the remote host (not available if LAT) PAGE 7-7 CLIENTS TCP o REMOTE$PORT will have the remote port on the remote host Note that the actual content of these logical names will be different if the remote is a LAT or telnet client. 7.1.8.1 Installation In order for TNC2 to work, the terminal device driver needs to be updated with added functionality. This requires updating a cou- ple of files, and rebuilding the system (or at a minimum, the TTDRV task). The files, and required version of them are: o TTATT.MAC version 06.18 or newer o TTDAT.MAC version 06.13 or newer o TTSYM.MAC which includes TC.COL o UCBDF.MAC which includes S6.COL These files are included in the TCPIP distribution under the [TELNETD] directory. Copy TTATT and TTDAT over to [11,10], replace TTSYM in LB:[1,1]RSXMAC.SML, replace UCBDF in LB:[1,1]EXEMC.MLB and then re- build according to RSX documentation. Note! In addition, for LAT to be detected and handled, the patched version of LAT from the BQTCP distribution must be in- stalled. You can then add the following line to LB:[1,2]SYSLOGIN.CMD RUN LB:[IP]TNC2 7.2 UDP BQTCP comes with the following UDP clients: 7.2.1 TFTP The TFTP client can be used to transfer files from TFTP servers. PAGE 7-8 CLIENTS UDP 7.2.1.1 Building The sources are found in the named directory [TFTP]. There is a makefile to rebuild the software. TFTP is written in MACRO-11. 7.2.1.2 Usage The TFTP client understands the following commands: o GET o PUT o TEXT o BINARY o BLOCK Note that the TFTP client will understand RSX files when a RSX <-> RSX connection has been established. 7.2.2 NTPDATE NTPDATE is a client that can be used to set the time on the local system based on time provided by a NTP server. 7.2.2.1 Building Sources are found in the named directory [NTP]. There is a makefile to rebuild the program. NTPDATE is written in PDP-11 C, and the correct compiler must be installed on the system. 7.2.2.2 Usage NTPDATE can be run at any time, and uses a logical name (NTP$HOST) to find out the NTP server to connect to. Note that currently multiple servers are not implemented. NTPDATE understands a couple of switches/argument: o set - Set the system clock o -s - Same as "set" o debug - Print out some debug information PAGE 7-9 CLIENTS UDP o -d - Same as "debug" In addition, NTPDATE will recognize if it is run under the name NTPD, and will do less logging, and assume that the -s switch is set. This means that NTPDATE can be installed as NTPD, and then setup to run at regular intervals to keep the clock up to date. In this mode, NTPDATE will only adjust the clock if the absolute skew value is larger than 5 seconds. NTP provides time against a base of UTC. In order to get NTPDATE to match local time, the logical name SYS$UTC_OFFSET is used to define the offset from UTC in minutes. Negative values are west of UTC. For example, when DST (Daylight Saving Time) is in effect, and your usual timezone is Geneva, then the value would be "120". 7.2.3 RWHOD RWHOD itself is a daemon. See the appropriate section for the daemon. This section describes the client programs related to thr RWHOD system. These tasks are normally found in the directory [IP], and the sources can be found in [RWHOD]. 7.2.3.1 RUPTIME RUPTIME will show the uptime of other machines on the local network who are running an RWHO daemon. The task is usually in- stalled as ...RUP Usually only users who have been idle for less than one hour are counted. If any argument is given to RUPTIME, all users for a host will be counted. 7.2.3.2 RWHO RWHO will show all users logged in to any system on which an RWHO daemon is running. The task is usually installed as ...RWH Normally, RWHO will only list users that have been idle for less than one hour. If any argument is given to RWHO, all users for all hosts will be shown. PAGE 7-10 CLIENTS UDP 7.2.3.3 RPURGE RWHOD is storing hosts it has received data from in a file LB:[1,6]RWHOD.DAT. However, if no more data is received, the host will basically just be listed as down all the time. After it has been down for more than two weeks, it is not even shown unless all hosts are requested by RUPTIME. RPURGE is usually not installed on the system, but can be run whenever maintenance is to be done on LB:[1,6]RWHOD.DAT. It is possible to just delete the datafile, and restart RWHOD as a way of getting rid of stale data in the file. However, the RPURGE program can be used to selectively delete information from the RWHOD database as well. When run, it will show each host in RWHOD, along with some basic information about the host, and then ask if this entry should be deleted. Answer Y to have to host deleted. Anything else will leave the host in the database. 7.2.4 DNS DNS is a simple tool to do DNS lookups under RSX. 7.2.4.1 Usage DNS is used by giving as arguments the hostname to look up, and possibly a list of DNS servers to do the query against. If no DNS servers are given, the system default DNS servers are used. DNS understands a few switches: 1. -t Next argument is what type of DNS record to look for 2. -m No not use mDNS The types of records that can be looked up are: 1. a A record 2. adr Reverse lookup (basically using PTR records) 3. ns NS record 4. soa SOA record PAGE 7-11 CLIENTS UDP 5. cname CNAME record 6. ptr PTR record 7. hinfo HINFO record 8. mx MX record 9. txt TXT record Note that for all non-CNAME lookups, if the result gives a CNAME, DNS will then repeat the query using the CNAME instead. Page 7-12 CHAPTER 8 MAIL Mail is a complex system, which consists of both a daemon, and a client. In addition, it talks both SMTP (using TCP/IP) and MAIL11 (using DECnet). The correct configuration and operation of mail is not a trivial task, and should not be set up at all unless you really want or need it. There is always a risk that an incorrectly setup and configured mail daemon can be abused and misused by various people on the internet. The mail daemon provided with BQTCP is still a rather ex- perimental implementation, with lots of things missing, or done in a rather minimal way. There are plans to expand the mail func- tionality, but (as usual) no guarantees are made. That said, if any specific function or requirements are re- quested, there is always the possibility that they will be added. 8.1 SUMMARY The mail package in BQTCP consists of two task images. MAILD, which is the mail daemon, talking both SMTP over TCP/IP, and MAIL11 over DECnet. In addition it is also the task that handles local mail reception for distribution to anywhere. MAILRD, which is the mail client. This task can also be in- stalled with the name ...SEN, in which case, when it is invoked, it will immediately go to composing and sending a new mail, and ...NEW, in which case, when it is invoked, it will just report on the number of currently unread mails in the mailbox. The mail daemon (MAILD) is a very complex task, which does a lot of things. The task first of all checks if it is running with CO: as the controlling terminal, and if so, it considers itself to be running as a daemon, and will try to accept a connection from TCP/IP. If there is no request from TCP/IP, it will continue into checking if there is a connection request from DECnet. If that also fails, it then checks if there might be a local message submitted that it should process. If all of this fails, it will assume that it is just invoked to clean up old mails in the queue, and will proceed to try and deliver all the mails currently queued on the local machine. The delivery will work through all mails in order, and deliver both local, TCP/IP and DECnet mails. In this state, it also checks if the name the task is running under is "MAILN", in which case it will only try to deliver mails that are marked as new. This special mode is used to immediately try and forward mails that have just been received, without blocking the receiving task. So, in short, if the mail task is started with CO: as its terminal, and it finds that there is a TCP/IP connection request, PAGE 8-1 MAIL SUMMARY it will then try to talk as an SMTP server, and receive mails. Every time a mail has been received, it is placed in the mail queue, and MAILN is requested to run. MAILN will then pick up any newly received mails, and try to deliver them to their destination. The mail daemon should also be installed under a second name (default would be MAILD), and setup to run at a regular interval, to retry to deliver any mails that has not been delivered yet. For TCP/IP and DECnet use, the mail daemon needs to be in- stalled with a name with $$$ at the end, as is standard for known objects in DECnet, and server daemons in BQTCP. For local mail handling, the mail daemon needs to be installed with a name of MAI.... The MAIL API tries to communicate with this task name. The mail daemon should also be installed with a normal multi- user name (starting with ...) for command line use. The recom- mended name is "...MQM". If the mail daemon is invoked from a normal terminal, it will go into an interactive mail queue manage- ment mode, where the mail queue can be inspected and controlled. The mail daemon, when used on the command line, also under- stands many switches, which should be used for mail management. MAILD is installed under several different names, for dif- ferent purposes. The recommended names to install MAILD under are: o MAI$$$ This is the server name used by both DECnet and TCP/IP to receive mails from remote machines. o MAI... This is the server name used by local mail submis- sion. That is, mails originating on the local machine get into the mail system through this task. o MAILD This is the server name used for regular processing of the mail queue, as well as the task name used to submit locally generated mails. o MAILN This is the task that is used to immediately deliver mails. There can be multiple copies installed with different numbers, in order to possibly serve many new mails in parallel, which can be important if delivery of new mails to some destinations take a lot of time. In- stalled copies must start with number 0, and can go up to 9 as maximum. o ...MQM This is the name under which normal mail management is done. The second task is the mail client (MAILRD). The mail client program is used to read and write mails, and to control mail notifications. PAGE 8-2 MAIL SUMMARY The mail client program understands some switches, and in ad- dition also can work a bit differently based on which name it is invoked. The recommended names under which to install the mail client is: o ...MAI This is the name under which normal mail read- ing/writing/management is done. o ...SEN This is the name under which direct mail sending is done. o ...NEW This is a name that can be used for just checking if there are any new mails. 8.2 MAIL READER DETAILS MAIL can be read by starting the mail client, which usually is installed under the task name "MAI". Sending of mail can be accomplished directly from the CLI com- mand line using the task name "SEN". 8.2.1 Checking if there are any unread mails "MAIL -u" will show how many unread mails a user has. If the mail daemon have been installed as ...NEW, the "NEW" command can also be used to check for new mail. 8.2.2 Getting notified of new mails MAILD keeps a separate mail notification file to track which users want immediate notification of new mails. However, even if mail notification have been turned on for a user on a terminal, notifications will not be delivered if the ter- minal has been set to /NOBRO. 8.2.2.1 Enabling mail notification Any user who wants mail notifications on the current terminal when new mail arrives should give the command PAGE 8-3 MAIL MAIL READER DETAILS "MAIL -n+" to enable mail notification. If there are any unread mails when the command is given, the same output as for "MAIL -u" will also be printed. 8.2.2.2 Disabling mail notification Any user who does not want mail notification anymore on the current terminal when new mail arrives should give the command "MAIL -nx" to disable mail notification. This should also be added to LB:[1,2]SYSLOGOUT.CMD. 8.2.2.3 Checking if mail notification is enabled "MAIL -n" will report if notification is enabled or disabled for the current terminal. 8.3 MAIL DAEMON DETAILS When invoked from TCP/IP or DECnet, as well as when running to clean up the mail queue, the mail daemon does not have any way of modifying its behaviour (through command line switches). It does use some configuration details stored in the mail queue file to control the behaviour. 8.3.1 Logical names MAILD uses the MAILD$ logical name to find all configuration files. MAILD uses IP$LOG for writing a MAILD.LOG file. MAILD uses SMTP$RELAY to identify an SMTP relay host to use for all outgoing SMTP mail. MAILD uses SMTP$DOMAIN, if defined, as the domain name to put on the sender address when delivering mail using SMTP. Otherwise the hosts fully qualified domain name is used. MAILD expects the mail queue file and mail notification data- base to be located in LB:[1,7]. PAGE 8-4 MAIL MAIL DAEMON DETAILS 8.3.2 Different protocols MAILD can gateway mails between MAIL11 and SMTP, and also relay MAIL11 mails. It does not currently relay any mails in the SMTP domain. Internally, MAILD uses three interfaces: SMTP, MAIL11 and lo- cal. Local is where local mail are sent in to MAILD, and local mail delivered out of MAILD on the local machine. 8.3.2.1 SMTP For SMTP, MAILD will work as a normal TCP server, listening to whatever port is set up in TCP. When a mail comes in, MAILD will receive it, process it, and then pass it on to some outgoing inter- face. Outgoing mail is sent from a random local port, to a remote machine at port 25. MAILD also tries to make use of MX records in DNS if available, and falls back to the address of the destination if no MX record can be found. If SMTP$RELAY is defined, MAILD will instead try to contact the translated logical name using DNS MX lookup for the relay for all outgoing mail, no matter what the destination is. If SMTP$DOMAIN is defined, outgoing mail will have the sender address modified to include the translated value of this logical name appended. If this logical name is not defined, the fully qualified domain name of the host is used. 8.3.2.2 MAIL11 MAIL11 is using the known object 27 in DECnet, and will re- ceive and send out mails through this object. MAILD sends an iden- tification string as a part of the connection establishment, and looks for, logs, and uses any identification strings of remote mail programs. However, identification strings are not required. MAILD identifies itself as using MAIL11 protocol version 3, and is capable of handling the CC extension. 8.3.2.3 Local Local mail is sent by just running MAILRD from the command line, at which point it will prompt for the information required. When mail are received that is to a local user, the mail is placed in LB:[1,7]gggmmm.MBX for all the meta information, and PAGE 8-5 MAIL MAIL DAEMON DETAILS LB:[1,7]gggmmm.MBD for the mail body. As usual in RSX, 'ggg' is the UIC group number and 'mmm' the member number (both in octal). Local users are verified against LB:[0,0]RSX11.SYS, and both LASTNAME, and F.LASTNAME are recognized. In addition, the SID and the login directory is also possible to use as the user identifica- tion. MAILD also checks MAILD$:ALIASES.TXT before delivering any mails, so that addresses can actually translate to totally dif- ferent destinations, even on other machines. 8.3.3 Accepting mails for many machines MAILD by default accepts mails to local users if they are ad- dressed to the nodename as defined in DECnet, or the expansion of HOSTNAME.DNS$DOMAIN logical name combination for TCP. In addition to these two addresses, additional addresses can be listed in MAILD$:MYHOSTS.TXT. 8.3.4 Mail queue The mail queue file is found at LB:[1,7]:MAILQUEUE.DAT. This file keeps track of all queued mails which have not been delivered yet. In addition, all the basic mail configuration options are stored in this file. 8.3.4.1 Creating/resetting the mail queue Before MAILD can operate correctly, the mail queue needs to be created. This is done with the command "MQM -qz", which zeroes the mail queue. If, at any point, the mail queue would become cor- rupted, or you just want to delete everything in there, you can also run "MQM -qz". But remember, this irrevokably erases anything in the mail queue. 8.3.4.2 Examining the mail queue The mail queue can be examined with the command "MQM -q". Op- tionally, you can also add "-v" to this command, to get more de- tails. (The -q flag is actually optional.) PAGE 8-6 MAIL MAIL DAEMON DETAILS 8.3.5 Mail notification MAILD can notify users of newly arrived mail, as well as give information upon request if there are any unread mails. 8.3.5.1 Getting notified of new mails MAILD keeps a separate mail notification file to track which users want immediate notification of new mails. However, even if mail notification have been turned on for a user on a terminal, notifications will not be delivered if the ter- minal have been set to /NOBRO. 8.3.5.1.1 Resetting the mail notification file - The notification information is kept in MAILD$:MAILNOTE.DAT. This file can be deleted to remove all mail notification informa- tion. 8.3.5.1.2 Checking if mail notification is enabled - "MAI -nl" will report which terminals have mail notification enabled. 8.3.6 Temporary mail files All mails received are temprarily stored in the LB:[1,7]: directory, with file names that end on .TMP. They should automa- tically be deleted once a mail has been delivered, and should not be deleted explicitly, unless something has gone wrong somewhere. 8.3.7 Mail alias file The alias file is MAILD$:ALIASES.TXT The mail alias file is used whenever a mail is received that is destined for the local machine. At this point, the alias file is scanned. The format of this file is name, followed by a colon, and then a destination name. The local name can have a fairly free form, but cannot contain the colon character. The destination name can be a local name, which will be once more subjected to translation through the alias file, or a remote address, either over TCP/IP or DECnet. There is a limit of 10 translations of aliases, before the mail daemon gives up on the translation and returns an error. The translated name PAGE 8-7 MAIL MAIL DAEMON DETAILS can also start with "@", in which case the rest is a filename which will then be read and used as a substitution for the local name. Such a file can hold one or several addresses per line, separated by commas or newlines. 8.3.8 Mail host names The local hostnames file is MAILD$:MYHOSTS.TXT This file should hold any additional names for which this machine should accept mail. TCP/IP hostnames should start with an @-sign, while DECnet nodenames should end with a double colon (::). 8.3.9 Mail forwarding By default, MAILD will relay mails for MAIL11, since the MAIL11 protocol expects this behaviour by default. However, MAILD will normally not relay SMPT mails, since mail on TCP/IP is normally expected to directly deliver to the end destination. The most common exception to this is when a host is listed as an MX for a destination. MAILD will accept, and relay mails which have a different destination, if the host on which MAILD is running, is in the MX list for the final destination. In such case, MAILD will store the mail, and try and deliver it. In addition to these rules, MAILD can also act as relay for arbitrary hosts as well, through the MAILD$:RELAY.TXT file, which should list destination addresses, for which MAILD will accept and relay mails. (Not yet implemented.) 8.3.9.1 TCP/IP to TCP/IP MAILD normally does not relay mails received from TCP/IP which should be forwarded out on TCP/IP. There are two exceptions: 1. Mails which are destined to a host for which the current host (where MAILD is running) is listed in the MX list, will be accepted and forwarded. 2. Mails which are destined for a host listed in RELAY.TXT will be accepted and forwarded. PAGE 8-8 MAIL MAIL DAEMON DETAILS 8.3.9.2 TCP/IP to DECnet MAILD accepts mails from TCP/IP destined for any DECnet host, and will forward those mails as required. In this forwarding pro- cess, the SMTP mail headers will be stripped off. 8.3.9.3 DECnet to DECnet MAILD accepts mails from DECnet destined to DECnet, and will forward those mails as required. 8.3.9.4 DECnet to TCP/IP MAILD accepts mails from DECnet destined to TCP/IP, and will forward those mails as required. In this forwarding process, MAILD will create an SMTP mail header filled in with the basic informa- tion that MAILD has access to. 8.3.10 Blocking mails from certain sources MAILD usually accepts SMTP mails from anywhere. However, if some specific source is a problem, it can be blocked by listing the source in MAILD$:BLOCK.TXT. The matching is done between lines in BLOCK.TXT, which are as- sumed to be substrings to match against the envelope from line, which usually is in the form "user@domain.name>". Examples of some matching lines can be found in the template file BLOCK.NEW. 8.3.11 Template files Included with the distribution is an ALIASES.NEW, a MYHOSTS.NEW, BLOCK.NEW and a RELAY.NEW file, which may be used as templates for ALIASES.TXT, MYHOSTS.TXT, BLOCK.TXT and RELAY.TXT. 8.4 MAIL API DETAILS Work in progress. PAGE 8-9 MAIL INSTALLATION 8.5 INSTALLATION There is also an INS.NEW file, which may be used as a template for INS.CMD, which is a command file to be used to install and start MAILD at boot time. Invocation of INS.CMD should be placed in LB:[1,2]STARTUP.CMD, and appear after both DECnet and TCP/IP have been started successfully. The file LB:[1,2]SYSLOGOUT.CMD should probably be edited to include turning off mail notification for that terminal at logout. At the administrators discretion, LB:[1,2]SYSLOGIN.CMD can also be edited to always turn on mail notification when users log in. 8.6 UPDATING Most of the time, updating MAILD is purely a question of in- stalling the new executables. However, occasionally, the mail queue format might change, in which case the mail queue needs to be re-initialized. Doing this will also reset the mail id on the system. If it is desireable to retain the mail id state (so that all mails have unique ids), it is possible to add an argument when creating the mail queue, which is what the mail id should be initialized to. If the mailbox format changes, there is a separate program in- cluded - MBXUPD.TSK - which will be able to update the mailboxes. 8.7 MAIL PROCESSOR When the mail daemon is run on CO:, and there are no connec- tions requested either by TCP/IP or DECnet or through the local submit interface, then the mail daemon will be running as the mail processor. (Either with an arbitrary name, or when explicitly run as "MAILN" for the new mail delivery task.) When running as a processor, the mail daemon will create connections both through TCP/IP and DECnet, as well as deliver local mails. 8.7.1 Controlling configuration options Mail queue manager understands a number of switches. -q Show the mail queue -qz Initialize the mail queue -dn Debug network -di Debug TCP/IP daemon -dd Debug DECnet daemon -t Test PAGE 8-10 MAIL MAIL PROCESSOR -o List queue based on a specific key -x n Delete a mail queue entry -m n Set maximum mail age to n days (default is 5) -= n Set debug flag to value n -v More verbose output -r n Reset queue status of mail (also sets expiration to 4h from now) -h n Hold mail (it will not expire) Note that some of these switches are privileged, and normal users cannot use them. The mail reader understands the following switches. -v More verbose output -n Show the status of mail notification for terminal -n+ Enable mail notification for terminal -nx Disable mail notification for terminal -u Show unread mail information 8.7.2 Sending mail If mail is invoked with the command SEN(D), mail will try to send a mail. This command can take several arguments: SEND [] [TO] [] Note that message parameter has to be given, if you want to give a destination. If you do not want to actually type a message on the command line, you can give the message parameter as an empty string (""), and then you will be prompted for a message. If message starts with an @-sign, it is assumed to be a file that should be sent as the message. If the destination starts with an @-sign, it is assumed to be a file (with a default extension of .DIS), that contains one destination per line. Note that the SEND command is compatible with how the program PHONE works. 8.7.3 Reading mail If mail is invoked with a different name than SEN, on a normal terminal, it enters into an interactive mode, where MAIL prompts for commands, and can both read and send mail messages. See MAIL.HLP for more information on individual commands in interactive mode. Page 8-11 CHAPTER 9 NAME RESOLUTION (DNS) Name resolution in BQTCP/IP is done by a separate ACP, which works in connection with the TC: device. This means that all name resolution is in the end done through the QIO$ interface. However, a couple of library functions are also provided, which gaves a simpler interface for translating names to IP addresses, and the inverse. Host names are strings with a maximum length of 255(10) bytes. They can contain letters, digits and some special characters. This document will not go into details on what host names can look like, but will assume that the reader either knows, or else find this in- formation out from elsewhere e.g RFC1035. IP addresses are simply four byte binary data value. Sometimes an optional port number is coupled with the IP address, but the name resolution routines nor- mally do not look past the IP address. Host names are matched case insensitive, but it should be noted that a complete match is always required. The only exception is that a host name can either have or not have a trailing period, and both will match equally. I.e. a trailing dot is insignificant from a matching perspective. Name resolution may be done by several different methods. Each method has it's own special features and configurations. Ex- actly which method will be used, and in which order they will be attempted is decided by the logical name RESOLV$ORDER, which should translate to a string, with each method separated from the others by a comma. So, for example, if RESOLV$ORDER is defined as "LOGI- CAL,FILE,DNS", name resolution will first be tried through logical names, then through the HOSTS file, and finally by DNS query. The actual methods that exist are: o LOGICAL - Translate through logical names o FILE - Translate through a HOSTS file o DNS - Translate through DNS o MDNS - Translate through both DNS and mDNS Note that a global RESOLV$ORDER should be defined on the sys- tem, but any user can override this definition for their own usage, and the resolver ACP will use the logical names each user locally defines in preference to the global definitions. 9.1 CACHING The resolver ACP caches all results. However, it does not mix results from different methods, or different sources. So if user A defines a logical name translation, and provides a translation for the name FOO, it will not affect user B, if user B requests a file translation of the name FOO. Neither will user A affect user B, if PAGE 9-1 NAME RESOLUTION (DNS) CACHING both request a file translation of the name FOO and they use dif- ferent hosts files. But if two users request the same name, and use the same method, and the same source for the information, the result will be shared by the resolver ACP, meaning it will not look the result up twice, but will instead actually use the same data for all queries, reducing the load on the system. Exactly how long data is cached depends on the method. Additionally, if a resolver method results in several responses (currently only DNS supports this), all the results are cached, and they will be returned in a round-robin fashion from the cache on each call. 9.2 LIBRARY ROUTINES The library routines can be used to make translations between hostnames and IP addresses more conventient than using the QIO$ in- terface. 9.2.1 Ports Ports for UDP and TCP are not properly regarded as a part of host name. However, the library functions can handle port numbers as well, making the handling of ports more uniform in the system. The library routines for name resolutions are: o H2IP - Convert a host string into an IP address o H2IPP - Convert a host string into an IP address and port o IP2H - Convert an IP address into a host string These routines use RESLUN and RESEFN to communicate with the resolver. These are memory cells that should hold the required values. You can either define them as variables in most high level languages, or create a short MACRO-11 file that sets them up, if you have specific values you want to use. If they have not been defined in your code, default values will be set at link time. RESEFN defaults to event flag 1. RESLUN defaults to .USLU2, which is a value provided by TKB and guaranteed to not be used by the rest of the program. (Unless the program explicitly uses .USLU2 itself.) The routines do not need to use the same LUN as other traffic that talks TCP, but they may do so. The name resolution functions are stateless and do not affect the normal TCP data streams. The PAGE 9-2 NAME RESOLUTION (DNS) LIBRARY ROUTINES name resolution routines can also be used without a TCP connection estblished on the LUN. 9.2.2 H2IP H2IP will translate a host string into an IP address. It takes the arguments from the general registers: R0 - Pointer to string descriptor for name R1 - Pointer to IP address The string descriptor is a two word block, where the first word is the length of the host string, and the second word points to the actual string. R1 points to address where the resulting IP address should be written. Any error causes the routine to return with carry set. Host names may have trailing whitespace that is ignored, and the hostname is terminated at the colon character, if one is present. 9.2.3 H2IPP H2IP will translate a host string into an IP address and port. It takes the arguments from the general registers: R0 - Pointer to string descriptor for name R1 - Pointer to IP address and port The string descriptor is a two word block, where the first word is the length of the host string, and the second word points to the actual string. R1 points to address where the resulting IP address should be written. Any error causes the routine to return with carry set. Host names may have trailing whitespace that is ignored, and the hostname is terminated at the colon character, if one is present. If there is a colon, followed by a number, this is parsed as a port number, which is written to the word following the IP address. Thus: IPADDR: .blkb 4 RPORT: .word 0 where R1 would contain the address of IPADDR. PAGE 9-3 NAME RESOLUTION (DNS) LIBRARY ROUTINES 9.2.4 IP2H IP2H will translate an IP address into a host name. It takes the arguments from the general registers: R0 - Pointer to a string descriptor R1 - Pointer to an IP address R2 - Conversion flags The string descriptor is a two word block, where the first word holds the size of the memory area for the host name, and the second word points to the memory area where the host name should be written. R1 points to the IP address (a four byte location) to be converted. R2 is a bit field indicating what kind of translation is requested: Q.ADR (1) - Write IP address numerically Q.AAPP (2) - Append IP address within () after name Q.NADR (4) - If no match, write IP address numerically Q.NQM (8) - If no match, write '?' Q.WLD (16) - If address is 0.0.0.0, write '*' Q.PORT (32) - Append :n after the host. Q.NULL (64) - Append a NUL after the string (not counted) So, if a name translation is wanted, with an IP address within () after the name and if no match is found a '?' is inserted, you just combine Q.AAPP and Q.NQM, or put the value 10(10) in R2. If flags are 0, and no match is found, IP2H will return with carry set, and nothing is written in the buffer. On return, R2 will hold the actual length written into the output buffer. If Q.PORT is requested, the port number is assumed to follow in the word after the IP address. 9.3 DIFFERENT RESOLUTION METHODS 9.3.1 Logical names When the resolver uses logical names for address translation, there are two families of names used. One for host to IP transla- tions, and one for IP to host translations. The host to IP translations have logical names in the form of HOST$name and the translated name should be an IP address in text form. PAGE 9-4 NAME RESOLUTION (DNS) DIFFERENT RESOLUTION METHODS The IP to host translations have logical names in the form of IP$n.n.n.n and the translated name is a hostname to use. Logical name translations are not cached. 9.3.2 HOSTS file The HOSTS file searches for a file by the name HOSTS, so it is normally expected that a logical name maps to the HOSTS filename. In the HOSTS file, each line is assumed to start with an IP ad- dress, and then one or several host names that match the address. Each field on a line is separated from the other fields by whi- tespace, one or more spaces and/or TABs. For name to IP address translations, any of the names on the line is accepted, and if a match is found, the IP address is re- turned in binary form (a four octet set of values). For IP address to name translations, a random name from the matching set is returned, unless otherwise requested. File translations are cached for 1 hour. 9.3.3 DNS DNS translations are done through a DNS server. As such, they need to know which DNS server to use, and they can also have a default domain name that would be appended to any name not seen as a FQDN (fully-qualified domain name). The DNS server to use is defined by the logical name DNS$SERVER, which should translate to an IP address string. No names should be used for this information. The logical name can give multiple DNS servers, separated by commas. In addition to DNS$SERVER, there is the logical name DNS$SERVER$DHCP which is used by DHCP to define DNS servers that should be used according to the DHCP server. This can also be a list of servers, separated by commas. The DNS server use the com- bination of both of these logical names. The default domain name is defined by the logical name DNS$DOMAIN. If the string does not exist, no default domain name is used. The DNS method uses UDP to communicate with a DNS server. It sends queries, and receives responses. It currently requires a DNS server which can do recursive lookups. When a name to address query is performed, the address is checked for any periods. If no periods exist in the name, the default domain is appended, with a period if required, to the name, to form a fully qualified domain name (FQDN). PAGE 9-5 NAME RESOLUTION (DNS) DIFFERENT RESOLUTION METHODS If an address to name query is performed, the IP address is actually used to query for a PTR record in the IN-ADDR.ARPA domain. Of course, if a program wishes, it can form its own PTR queries through the QIO$ interface as well. A query has a timeout of 3 seconds, and is retried 3 times if needed, before the method fails (assuming no answer is received). When a response is received, it is verified and parsed, and if a result is found, it is returned in the proper form to the request- ing program. DNS responses are cached for as long as the DNS TTL record in- dicates, but with an upper limit of two hours. 9.3.4 MDNS The resolver is also capable of resolving and responding to mDNS queries. mDNS stands for multicast DNS, and is a technology for using DNS in a local network without having to run a normal DNS server. mDNS instead works by directly communicating between hosts, and each host is responsible for answering queries about itself. If the resolver is designed to use mDNS, it will do resolving slightly differently depending on the query. Any host name lookup for a host which ends in ".local" will not be sent to the normal DNS server, but will instead be sent to the local network using mDNS. Likewise, and query to ".254.169.in-addr.arpa." will also be queried on the local network using mDNS. The reason is that this network is the link local network, and the address shall never resolve in the normal DNS servers. The third set of names that are handled specially are the net- work local addresses, if the local network have some other address than 169.254. These might both be global and local, so the resolver cannot tell for sure which strategy to use. So the resolver will first try to query the normal DNS server. If that fails, it will revert to trying a mDNS query for the same network. The resolver will also respond to mDNS queries from other hosts on the local network. 9.4 ADDITIONAL DETAILS ON THE RESOLVER ACP. The TC: interface to the resolver actually handles numeric IP names to addresses without the help of the resolver ACP, thus translations from numeric hosts to IP addresses works even if the resolver ACP is not installed. PAGE 9-6 NAME RESOLUTION (DNS) ADDITIONAL DETAILS ON THE RESOLVER ACP. If the resolver ACP is installed, it is automatically started by the TC: driver when needed, so it should not be started manually. Installing it is enough. The resolver ACP must be in- stalled with a task name of "RESACP". If some other program is in- stalled with that name, the system will not work correctly. However, if no RESACP is found, TC: will just fail any operations that would have required the ACP to be installed. If the ACP is aborted, it will try to clean up current opera- tions in progress, but if that fails, pending I/O operations will be lost in limbo, and the requesting tasks stuck until a reboot. 9.4.1 Some additional information on the QIO$ interface. TC: uses a special function (IO.RSV) for name resolution. It takes six parameters: P1 - String pointer P2 - String length P3 - Destination pointer P4 - Destination length P5 - Function code,Timeout P6 - Entry # to return In addition to the IO.RSV function, it also handles the F11 I/O functions IO.FNA and IO.ENA. It will parse the F11 FNB parame- ter pointed at by P6, and place the result at the FID address pointed at by P1. Note that these functions handle both FNB R50 (RAD50) filenames of 9+3 characters and ANSI filenames of 14 characters. A special detail of these functions are that the filename version field of the FNB is actually placed in the output FID as the third word, while the IP address uses the first two words of the FID. This gives a resulting output of both IP address and port number, with the file version used as the port number. The output result is directly usable by other TC: functions that take an address and a port. Thus, a call to TC: with IO.FNA, fol- lowed by a call to TC: with IO.ACR, as done by FCS, can be done just like for something controlled by F11ACP. The entry # parameter can be used to iterate through all translations available, startng at 1. A value of 0 means that RESACP should return a random correct result. If the entry re- quested is higher then the number of available translations, a dif- ferent error will be returned, compared to a failed lookup. 9.5 COMMAND LINE TOOL There is a command line tool to do name resolution lookups, called DNS. Usage is: PAGE 9-7 NAME RESOLUTION (DNS) COMMAND LINE TOOL DNS [-m] [-t type] host [server] If -m is given, mDNS queries are sent. Types are: 1. adr - IP address for a name 2. ns - Nameserver information 3. soa - Source of authority information 4. cname - Canonical name informatio 5. ptr - Pointer information 6. hinfo - Host information 7. mx - Mail exchange information 8. txt - Text information Default is "adr" unless the host argument looks like an IP ad- dress, in which case a ptr lookup is going to be done on the name n.n.n.n.in-addr.arp. host is the hostname or address to look up. server is an optional server address to use for the lookup. This host needs to be an IP address. Note that the dns tool will try to explicitly follow cnames before the actual type requested, unless the requst is for the cname. Page 9-8 CHAPTER 10 DECNET OVER IP DECnet can use BQTCP as a transport layer for DECnet links. This is compatible with the Multinet software on VMS. Using this, DECnet will have lines and circuits that in the end cause data be be transferred using TCP or UDP to a remote machine, where it is delivered to the local DECnet network stack. The DECnet device driver module for BQTCP can handle at most 64 lines, but it is recommended to generate the system with a reasonable number of lines, based on actual links, since some DECnet resources are sized relative to the total number of lines existing. Some testing and experimentation might be required in order to get optimal performance. In order to use this feature, you need to install the DECnet related files during the IPGEN installation. Once this has been done, you need to run the DECnet NETGEN procedure to rebuild DECnet. The reason for this is that the number and type of lines in DECnet is decided at generation time, and cannot be changed in the existing system. It is also not possible to just do a partial NETGEN to only add additional device driver modules. 10.1 PREPARATORY WORK In order to use DECnet over IP, the IPGEN procedure must be run, and the DECnet files installed, before NETGEN can be run. 10.2 NETGEN The NETGEN procedure can add device driver modules for user written lines, but this is not documended in the DECnet manuals. When running NETGEN, you get to the section where you define the lines that you have. Here is where you will answer questions that are not in the standard DECnet documentation. The questions that require responses, and the proper answers for BQTCP lines, are documented below: 01.00 Device Driver Process name [=Done] [S R:0-3]: You should add the normal processes that you would otherwise list as usual at this question. The standard device driver processes are documented in the DECnet manu- als. In addition, you need to add the IP device driver process. For this, you answer "IP" to this question. 01.01 Do you have a user written IP Device Driver [D=N]? [Y/N]: PAGE 10-1 DECNET OVER IP NETGEN Since the IP device driver process is unknown to DECnet, you get this question, where you need to confirm that it was not an error on your part. Answer YES. After you answer yes to this question, you will see some information from NETGEN about files required for the installation to be successful. The IPGEN procedure should already have copied these files for you, so you should be good. 01.02 Is the IP a multiplexing device [D=N]? [Y/N]: The answer to this questions is YES. 01.03 Maximum number of lines per controller [D R:1.-64. D:8.]: You can choose whatever response you want at this question. This would be the theoretical maximum, and it is not important, except don't give a too small value, since a later question will ask how many lines you ac- tually want, and that will be limited to the maximum number that you answer here. 01.04 Is the IP a synchronous device [D=N]? [Y/N]: The answer is NO. 01.06 Is the IP a Direct Memory Access device [D=N]? [Y/N]: The answer is NO. 01.07 Does the IP Device Driver run at device priority[D=N]? [Y/N]: The answer is NO. 01.08 Does the IP need software Line Protocol support [D=N]? [Y/N]: The answer is NO. 01.09 Maintain network management counters for the IP [D=N]? [Y/N]: The answer is NO. 01.11 Does IP require a Unit CSR [D=N]? [Y/N]: The answer is NO. 01.13 Does IP require a seperate modem CSR [D=N]? [Y/N]: The answer is NO. PAGE 10-2 DECNET OVER IP NETGEN 02.00 How many IP controllers are there [D R:1.-16. D:1.]: The answer is 1. (x) 02.03 Will all the IP lines run at the same line speed [D=N]? [Y/N]: The answer is YES. 02.04 Line speed for the IP [D R:110.-9600. D:9600.]: The answer is 9600. 02.05 Will all IP lines run as FULL duplex lines [D=N]? [Y/N]: The answer is YES. 03.00 Number of lines used on IP-0 [D R:1.-8. D:1.]: Select as many lines that you plan to use. You might add a few extra ones for future expansion, but do not add unreasonable numbers. Note that the actual range avail- able for this question is based on your response question 01.03 (see above). 03.01 CSR address for IP-0 [O R:160000-177777 D:177777]: The answer is 177574. (*) 03.02 Vector address for IP-0 [O R:0-774 D:0]: The answer is 0. (+) 03.03 Device priority for IP-0 [O R:4-6 D:5]: The answer is 5. 03.04 UNIBUS run mask for IP-0 [D=CPA] [S]: This question only appears if you are running on a multiprocessor system. Any mask is ok. 04.02 Is IP-0-0 a DL11-E or equivalent device [D=N]? [Y/N]: ------ footnote ------ (x) You should only ever have one IP controller. (*) The CSR value is not actually important, but it needs to be a CSR where something gives a return value, as otherwise DECnet will not bring the line online. The value 177574 is a CSR for the MMU, and is harmless to read, so it is suitable. (+) The vector is not actually used, but DECnet will install one anyway, so it should not collide with any real device. 0 is a garbage vector when none is actually wanted. PAGE 10-3 DECNET OVER IP NETGEN The answer is NO. 04.05 Will IP-0-0 use modem signal monitoring [D=N]? [Y/N]: The answer is NO. 05.00 Is IP-0-0 multipoint [D=N]? [Y/N]: The answer is NO. The last three questions will be repeated for every line. Once this is complete, you have finished the required additional work for NETGEN to complete. 10.3 AFTER NETGEN - IPNET Once NETGEN has finished, you have a DECnet configuration with the IP device driver process included. However, the NETGEN pro- cedure will have created lines that do not properly reflect the IP device. So after NETGEN finishes, you should run [IPNET]IPNET.CMD, to adjust the DECnet installation. IPNET will patch CETAB.MAC to correctly define the IP lines. In addition, it will recompile CETAB, since some of this informa- tion is actually stored in binary form. IPNET only asks one question, which is what group number is used for DECnet. Everything else is automated, and if there are any problems, it should report them in an easly understood fashion. 10.4 CONFIGURING THE IP LINKS AFTER REBOOT Once the NETGEN and IPNET procedures have been run, you can reboot the system, and you should then have IP lines and circuits inside DECnet. In order to actually use these, you then need to configure the links themselves. The default cost of the IP circuits is 2. You might want to change this once you have rebooted. You can change it both in CFE and NCP, and you can also see the costs using MNC. There are two example configurations provided with the distri- bution to setup a configuration at boot. 1. INS.CMD This is a simple script that explicitly sets each line in the wanted state a boot time through direct commands, and it is not easy to use for any other purpose. PAGE 10-4 DECNET OVER IP CONFIGURING THE IP LINKS AFTER REBOOT It is easiest to do by copying the [IPNET]INS.NEW template to [IPNET]INS.CMD, edit it, and then in SYS- TARTUP.CMD, invoke [IPNET]INS.CMD after both DECnet and IP have been installed and started. 2. IPNCONFIG.CMD (+) This is a more advanced script that uses a configura- tion file, and can be used to update individual circuits at runtime. It is easiest to use by copying the [IPNET]IPNET.NEW file to [IPNET]IPNET.CFG and then edit IPNET.CFG to con- tain the correct information. At boot time, you only need to run [IPNET]IPNCONFIG.CMD from the appropriate place in SYS- TARTUP.CMD, and it takes care of starting the DECnet-over-IP links. 10.5 MNC - MULTINET CONFIGURE TOOL MNC is the tool to define the IP links. The name comes from the VMS Multinet TCP/IP stack, which the BQTCP IP links are compa- tible with. Only privileged users can run MNC, and it is only used for de- fining remote ends of links. The commands MNC understand are: o QUIT o LIST/SHOW Syntax: SHOW VERSION LIST LIST ALL LIST * LIST IP-0-n LIST IP-0-* Options: /NUMERIC o SET ------ footnote ------ (+) This script has been provided by Oleg Safiullin, and is in- cluded with his permission in the BQTCP distribution. PAGE 10-5 DECNET OVER IP MNC - MULTINET CONFIGURE TOOL Syntax: SET CIRCUIT IP-0-n [TCP] [TCA] [UDP] [PORT n] [HOST ] This sets the protocol and/or destination of the link. 10.6 UDP DETAILS UDP is not a very good transport for DECnet traffic. The mul- tinet tunnels appear as point-to-point links, and DECnet expects such links to be error free. UDP have no such guarantee, and UDP packets can be dropped, reordered, or even duplicated. The UDP links for DECnet do not implement any handling for this, but deliver such "bad" packets to DECnet for that application to deal with. This means that DECnet circuits can reset a lot, if the UDP traffic is seen as unreliable due to dropped or out of order packets etc. All UDP tunnels will use the same local port number. If the configuration has different local port numbers for different cir- cuits, the actual port that will be used is the one on the first circuit to be turned on (note, not necessarily established). Each remote end needs to be explicitly listed. Wildcarding of remote hosts or ports will not work. 10.7 TCP DETAILS TCP is a better transport protocol for multinet links, since TCP guarantees an error free connection. However, TCP also carries a much higher overhead that might impact performance. TCP links can be either active or passive. Active links will try to establish a connection with the remote end, while passive connections wait for a connection request from the remote end. Thus, a multinet link using TCP should always be between one pas- sive and one active end. 10.7.1 TCP active links TCP active links can specify a specific source port number, for the remote end to verify, or can set the local port to 0, which means that the connection will use a random local port. The remote end must be fully specified, with both a host and a port. PAGE 10-6 DECNET OVER IP TCP DETAILS 10.7.2 TCP passive links TCP passive links must specify a local port number. Each con- nection has either a unique local port number or shares the local port number between several links. If you have a mix of shared and unique local port numbers, it is important that you start a cicuit that uses the shared port first, as the first passive TCP circuit turned on defines which local port can be shared. For the remote destination, you can either specify host, and/or port, and if specified, they will be verified against incom- ing connections. Only matching incoming connections will be ac- cepted. If the host is 0.0.0.0, then any host matches. If the port is 0, then any port matches. Page 10-7 CHAPTER 11 INTERNET SPOOFING Internet spoofing is sometimes a problem that appears on the internet as a part of performing distributed denial of service at- tacks at a target. The method works by having lots of hosts send- ing packets to one specific target. Each originating system only do a few packets at a time, but the combined result at the target host can be millions of packets per second. As a part of hiding the actual attackers in this kind of situation, internet spoofing is used. Internet spoofing essentially just means that the at- tacker sends packets to third party hosts with a fake source IP ad- dress. The idea is that the third party machines will respond in some way to these faked packets received. The responses will be sent to the originating IP address, which is the victim. It is thus very hard to trace where the attack actually comes from, since the victim can only see the packets coming from the third party machines, that are unwilling and unknowing participants in the at- tack. BQTCP/IP tries to detect these kind of attacks, and protect against them by having a daemon that monitors suspect packets, and block hosts for limited amounts of time, if too many suspect packets arrive from a specific host. This kind of protection comes with the added problem that any legitimate traffic from that host will also be blocked while the attack is going on. But in general, this is not really a problem, since a host under such an attack is normally not able to perform much normal traffic anyway. 11.1 DETECTION In BQTCP/IP, both IP, UDP and TCP repots any suspect packets received to the SPOOF daemon. Exactly what is considered suspect packets can vary, but typical things would be for example receving a SYN packet, and then receiving an RST packet when responding to the SYN, using TCP. The SPOOF daemon will monitor if the rate of such packets are high enough to not just be a random glitch, but actually represent a pattern. If a host sends enough packets within a small time to trigger the SPOOF daemon to consider it to be an attack, the SPOOF daemon will enable filtering for that IP address, meaning no packets for that destination will be processed. TELNET and FTP also report suspicious activities to the SPOOF daemon. For these services, logging in with bad passwords, or repeated connections without logging in are considered suspicious. When a suspicious address is reported to SPOOF, it first checks if the address is covered by an exception, and if so, no action is ever taken. PAGE 11-1 INTERNET SPOOFING DETECTION Exceptions are: 1. The domain name resolver, which should never be blocked, and which is identified by the logical name DNS$SERVER. 2. Any address covered by SPOOF$EXCLUDE, which is a logical name that can cover an address, or a whole network by ap- pending the /n after the address, where n is the width of the network mask to apply (CIDR notation). If an address is not covered by an exception, SPOOF will start tracking the address, and block it if it becomes too abusive. SPOOF will also track networks to which an IP address belongs, and if multiple addresses within one network are being abusive, the whole network can be blocked. This is then handled just the same as the blocking of individual addresses. The network blocks SPOOF tries to associate an IP address are in CIDR notation: 1. /24 2. /21 3. /18 4. /16 11.2 PREVENTION If the SPOOF daemon has enabled filtering for an address, the IP layer will drop all packets matching that address. In addition to dropping the packets, IP also keeps counters for all filtered addresses, showing how many packets have been dropped. The SPOOF daemon regular checks these counters, and once they have been stable for more than one hour, SPOOF will enable the address again, so that normal traffic can resume. As normal traffic is allowed again for a specific address, the monitoring for suspect packets are also resumed for the address, so if an attack starts again, it will once again be blocked. 11.3 STATUS INFORMATION The SPOOF task keeps information about the current number of blocked hosts in R0, and the total number of blocked hosts over time in R1, so that they can be seen with RMD or TAL. Page 11-2 CHAPTER 12 DETAILED INFORMATION ON INTERFACES 12.1 IP The UCB of IP: holds the following values, which can be found useful: CW4 - is 8000. 12.1.1 QIO interface The QIO interface for the IP: device is not commonly used by any programs. The one exception being access to the ICMP echo re- quest/reply functions. There are also some control functions, which can be used from user level. All I/O to IP: requires that the task is privileged. Also, note that some functions are internal, and have function codes above 40(8), which means that they are not available through the QIO interface. Many functions do not have proper documentation at this time. If needed, better documentation will be written at some point. 12.1.1.1 IP.XMT Internal transmit function. Used by higher level protocols. 12.1.1.2 IP.RCV Internal receive function. Used by lower level interface drivers. 12.1.1.3 IP.XER Internal transmit error function. Used by higher level pro- tocols. PAGE 12-1 DETAILED INFORMATION ON INTERFACES IP 12.1.1.4 IP.RER Internal receive error function. User by lower level inter- face drivers. 12.1.1.5 IO.STA Start IP driver. 12.1.1.6 IO.STO Stop IP driver. 12.1.1.7 IO.RST Read statistics. P1 - Address of buffer P2 - Size of buffer IOSB+2 - Actual size returned 12.1.1.8 IO.XMT Transmit ICMP echo request packet. P1 - Address of data P2 - Size of data P3 - Address of parameter block (8 bytes) IOSB+2 - Actual size sent 12.1.1.9 IO.RCV Receive ICMP echo reply packet. P1 - Address of buffer P2 - Size of buffer P3 - Address of parameter block (8 bytes) IOSB+2 - Actual size received PAGE 12-2 DETAILED INFORMATION ON INTERFACES IP 12.1.1.10 IO.ADR Add route. P1 - Address of route information P2 - Size of route information IOSB+2 - Actual size processed 12.1.1.11 IO.RMR Remove route. P1 - Address of route information P2 - Size of route information IOSB+2 - Actual size processed 12.1.1.12 IO.GRT Get route. P1 - Address of route information P2 - Size of route information IOSB+2 - Actual size returned 12.1.1.13 IP.JMG Internal function to join multicast group. Used by higher level protocols. 12.1.1.14 IP.LMG Internal function to leave multicast group. Used by higher level protocols. 12.1.1.15 IO.GML Get multicast list. P1 - Address of buffer to receive list. P2 - Size of buffer IOSB+2 - Actual size returned The format of the list returned is, for each entry, one word with a count of how many users of this multicast address is cur- rently active, and four bytes containing the multicast address. PAGE 12-3 DETAILED INFORMATION ON INTERFACES IP As such, the length returned will always be a multiple of six. 12.2 UDP The UCB of UD: holds the following values, which can be found useful: CW4 - is 8000. 12.2.1 QIO interface The QIO interface to UD: have both some internal functions, which are not usable through the QIO interface, and some functions that are privileged. 12.2.1.1 IO.CEP Create endpoint. P1 - Port # P2 - Non-zero if not to use buffered I/O on receive IOSB+2 - created port # A remote endpoint is optional to specify. If the local port is specified as 0, a random port will be assigned. 12.2.1.2 IO.CON Connect endpoint P1 - Address of endpoint (6 bytes) P2 - Non-zero if not to use buffered I/O on receive P3 - User timeout IOSB+2 - Local port # If the endpoint have not been created, this call will also create it, with a random port number. 12.2.1.3 IO.ACC Accept connection P1 - Address of endpoint (6 bytes) P2 - Non-zero if not to use buffered I/O on receive P3 - User timeout PAGE 12-4 DETAILED INFORMATION ON INTERFACES UDP IOSB+2 - Local port # The endpoint address is optional. 12.2.1.4 IO.GCO Get connection info P1 - Address of buffer (E.SIZ bytes) P2 - Entry # (0 = own connection) 12.2.1.5 IO.CLN Close connection 12.2.1.6 IO.RCV Receive data P1 - Address of buffer P2 - Size of buffer P3 - Address of endpoint buffer (6 bytes) P4 - Timeout IOSB+2 - Actual size received The P3 parameter is optional. The timeout value of -1 is used in UDP to poll. If no data is available, the function will complete with IE.NDA. A timeout value of 0 means use default. The endpoint buffer, if given, is where the source address of the packet will be written to. Note that if the socket has been set to use I/O buffering, the receive is a buffered operation if possible. 12.2.1.7 IO.XMT Transmit data P1 - Address of buffer P2 - Size of buffer P3 - Endpoint buffer (6 bytes) P4 - TTL to use for packet IOSB+2 - Actual size written The P3 parameter is optional if the UDP port have been con- nected to a destination. PAGE 12-5 DETAILED INFORMATION ON INTERFACES UDP If no endpoint is given, data is sent to the connected ad- dress. However, if an endpoint is given in the call, the data will be sent to that specific address. If a TTL is not given, the system will use a default. 12.2.1.8 IO.RSD Special read function for privileged programs, that can read to arbitrary address in physical memory. P1 - Buffer map value (to be loaded in APR6) P2 - Buffer bias in APR6 space. P3 - Buffer length P4 - Source address buffer APR6 map P5 - Source address bias P6 - Timeout IOSB+2 - Actual size read See IO.RCV for other details. 12.2.1.9 IO.WSD Special write function for privileged code that can send data from anywhere in physical memory. P1 - Buffer mapping (APR6 value) P2 - Buffer APR6 bias address P3 - Buffer size P4 - Destination (relocatable address) P5 - TTL IOSB+2 - Actual size written See IO.SND for other details. 12.2.1.10 IO.RAS Setup receive AST notification P1 - AST address P2 - User parameter P3 - Mode flag/EFN If an AST notification have been set up, the address is called as an AST when there is data available. The user parameter is pushed on the stack before the AST is called, and needs to be removed by the AST routine before exiting the AST. The mode flag in UDP is used to decide if an AST should be generated for every packet, or only the first packet. A non-zero value means only the first packet should generate an AST. PAGE 12-6 DETAILED INFORMATION ON INTERFACES UDP The mode flag also is used as an EFN to be set whenever a user notification should be generated. Note that this means that if an EFN is desired, you will always also have the mode of only generat- ing a notification on the first packet. If a notification on first packet is desired, but no EFN should be set, a value greater than 64 can be given, since that is not a valid EFN. Also, if notification by EFN is used, the user task should normally wait for the EFN, clear it and then read out packets with a timeout of -1, and loop until IE.NDA error is returned, at which point the task can do a wait again. 12.2.1.11 IO.RUN Start protocol. 12.2.1.12 IO.STP Stop protocol. 12.2.1.13 IO.RST Read statistics. P1 - Address of statistics buffer P2 - Size of statistics buffer IOSB+2 - Size of returned data 12.2.1.14 IP.RCV Interal receive function from IP. 12.2.1.15 IP.RER Internal receive function from ICMP. 12.2.1.16 IO.CAN Cancel I/O. PAGE 12-7 DETAILED INFORMATION ON INTERFACES UDP 12.2.1.17 IO.FLS Flush I/O. 12.2.1.18 IO.TIM Set timeout P1 - New timeout (seocnds) IOSB+2 - Local port # 12.2.1.19 IO.JMG Join multicast group P1 - Address of multicast address 12.2.1.20 IO.LMG Leave multicast group P1 - Address of multicast address 12.3 TCP The UCB of TC: holds the following values, which can be found useful: CW2 - holds the number of currently open ports. CW3 - holds the base number for automatically assigned ports. CW4 - is 512. Writes for more that this size is supported (max 8000.) TC: server connections are used to just receive connect re- quests. When a connect is received, it can be examined on the server port, and then rejected, or accepted. It can also be ac- cepted on another LUN. It is also possible for a offspring task to accept a connection in this case, which can be used for services where each request is handled by a separate task. Documentation, example code and libraries for this is still somewhat lacking, but the HTTPD server can be used as a prototype for doing this, as well as the small test programs TCPTESTn. When running TCP services, there are several way of handling the service for a port. PAGE 12-8 DETAILED INFORMATION ON INTERFACES TCP They allow different level of control, complexity and features. This is a short list of the different ways to implement servers, and some pointers to additional reading. 1. All services handled by one task. This is in many ways the easiest way of serving a tcp port in RSX. A program can create a TCP endpoint, and put it in a server state. This port can be read from, and each time a connection request comes in, the read will re- turn the information about the remote end requesting a connection. The task can then either accept the connec- tion or reject it. Accepting can be done either on the same file as the server was set up, or on a different file number. If the same file number is used, then any addi- tional connection requests will be denied until a new server has been set up. If a different file is used for the accept, the original server file remains open and can receive additional connection requests, One example of this kind of program is TCPTEST3. 2. One server task gets the requests and spawns workers with tracking. This solution means that there is a small server task that has a port open, waiting for connection requests to arrive. When a connection comes, the task is notified (read or AST), and the task then requests a worker to be started who will handle the request. The worker will be an offspring task to the server, and is allowed to open the same port that the server task has open, and will in- herit the connection request from the server in order to serve it. When the worker finishes, the server task is notified of this, via EFN, AST and/or exit status block, so that the server can keep track of how many requests are cur- rently being served. TCPTEST4/5 is an example of this kind of solution. 3. One server task gets the requests and spawns workers without tracking. The server is similar to the previous one, in that is creates a server socket, and waits for incoming connce- tions. However, in this scenario the server spawns work- ers for each connection without making them offpsring tasks. The received connection request is passed on to the spawned task, and the server immediately forgets about it. In order to prevent spawned tasks to overwhelm the system, a limit is set on how many spawned tasks that are allowed. PAGE 12-9 DETAILED INFORMATION ON INTERFACES TCP HTTP3 is an example of this kind of solution. Note that both HTTP2 and HTTPD3 use the same offspring task (WWW$$$) to serve the request. 4. TCP port listener A TCP port listener is a service without an active task receiving the connection requests, Instead a worker task is spawned whenever there is a connection request on the port. This requires much less resources as there are no server task at all. However, only privileged users can create these kind of listeners. The worker task is similar to the worker tasks in the previous scenarios. 12.3.1 TCP modes TCP can work in a variety of modes, which are user settable. Here is a list of the modes, and what they mean/imply. All modes can be combined. 12.3.1.1 Raw mode If no mode at all is selected, the socket is in raw mode. In this mode, all data are read and written without any interpretation or processing. I/O details: Read: Read data until the buffer is full, or until an er- ror. There is a special mode read, in which a count and a special terminator is specified. This mode requires that the socket is in text mode. In this mode, reads terminate if the separator character is found, or if the count number of characters have been read. If the terminator is found, the next read will continue in the special mode, with the count being the remaining characters. Write: Write all data without any interpretation. In MACRO-11, writes can be done with IO.WLB or IO.WVB, which have the same effect. If IO.WAL is used, an unformatted write is always done, no matter what tcp op- tions are in effect. PAGE 12-10 DETAILED INFORMATION ON INTERFACES TCP However, if text mode is enabled, even a IO.WAL will interpret the VFC field, possibly adding a CR+LF after the write. If the high byte of a VFC is negative, an implicit push is done after a write. 12.3.1.2 Text mode Value: 1 MACRO-11: PU.TXT BASIC+2: TCPOPT_TXT C: TCPOPT_TXT FORTRAN-77: PUTXT Pascal: tbd Text mode. End of lines are indicated by CR+LF. NUL characters are discarded, both on input and output. Read: Reads will read until end of line. End of line is stripped from read. Return code is IS.CR. If buffer be- comes full, return code is instead IS.SUC. CR without following LF is passed "as is" in the read. NUL in input is discarded. Write: Writes append end of line indication based on VFC. NUL characters are discarded. (Also note that text mode writes also impact the CR padding option.) 12.3.1.3 CR padding Value: 2 MACRO-11: PU.CR BASIC+2: TCPOPT_CR C: TCPOPT_CR FORTRAN-77: PUCR Pascal: tbd Read: CR followed by NUL - strip NUL, just return CR. CR followed by anything else, return both chars. Write: PAGE 12-11 DETAILED INFORMATION ON INTERFACES TCP CR is padded by NUL character. If text mode is also enabled, the CR is not padded with a NUL if it is followed by LF. 12.3.1.4 Network virtual terminal mode Value: 4 MACRO-11: PU.NVT BASIC+2: TCPOPT_NVT C: TCPOPT_NVT FORTRAN-77: PUNVT Pascal: tbd Network virtual terminal mode means that a byte with the value 377(8) is interpreted special. Read: If 377 is followed by 377, return a single 377 in buffer. If 377 is followed by something else, terminate the read with IS.TMM. 377 is removed from the stream. Next char is stored in the high byte of the I/O status word. Write: Any 377 in stream gets doubled. 12.3.1.5 Automatic newline Value: 8 MACRO-11: PU.ANS BASIC+2: TCPOPT_ANS C: TCPOPT_ANS FORTRAN-77: PUANS Pascal: tbd Default to each write always append CR+LF 12.3.1.6 Turn off buffering Value: 16 MACRO-11: PU.BUF BASIC+2: tbd C: tbd FORTRAN-77: tbd Pascal: tbd PAGE 12-12 DETAILED INFORMATION ON INTERFACES TCP Turn off intermediate buffering. This only affects reads, as writes in TCP are always buffered and completes immediately. With reads buffered, any reads will turn into a buffered read. This allows the task to be checkpointed during the read, as the read will not lock down memory. There is some performance cost re- lated to this, as it requires and extra copy of the received data to actually copy it into task memory once the read has completed. 12.3.1.7 Latency modes TCP have the ability to buffer written data into larger packets to improve network utilization. This, however, affects latency, as data written might be delayed before it actually is sent. TCP will always immediately send packets if the amount of data available can fill a whole packet. TCP also always sends data right away if the PUSH function is invoked. TCP will ACK incoming data for every second packet. If only one packet arrives, it will also ACK that packet after a fast delay. If low latency has been selected, the ACKs will also be sent without delays. 12.3.1.7.1 High throughput - In this mode, data is always buffered until either a full packet is possible to send, or the PUSH function is invoked. Value: 32 MACRO-11: PU.HTR BASIC+2: TCPOPT_HITHR C: TCPOPT_HITHR FORTRAN-77: PUHTR Pascal: - 12.3.1.7.2 No latency - All writes immediately become transmits, meaning you can get very many small packets sent. Value: 64 MACRO-11: PU.NDY BASIC+2: TCPOPT_NOLAT C: TCPOPT_NOLAT FORTRAN-77: PUNLAT Pascal: tbd PAGE 12-13 DETAILED INFORMATION ON INTERFACES TCP 12.3.1.7.3 High latency - When data is written, it is buffered and a fast timer is started. When the fast timer expires, the data is sent. This will make several writes after each other be combined together into one send. Value: 32+64 MACRO-11: PU.HTR!PU.NDY BASIC+2: TCPOPT_HILAT C: TCPOPT_HILAT FORTRAN-77: PUHLAT Pascal: tbd 12.3.1.7.4 Low latency - If no data is currently waiting for an ACK, the data is im- mediately sent. However, if data is sent, waiting for an ACK, the new data written is buffered until an ACK for all outstanding data is received, or until a fast timer expires, at which point the data is sent anyway. (This is the standard nagle algorithm.) Value: 0 MACRO-11: - BASIC+2: TCPOPT_LOLAT C: TCPOPT_LOLAT FORTRAN-77: PULLAT Pascal: tbd 12.3.1.8 Keep-alive Value: 128 MACRO-11: PU.KAF BASIC+2: TCPOPT_KAF C: TCPOPT_KAF FORTRAN-77: PUKAF Pascal: tbd If enabled, TCP will send keep-alive probes on idle sockets. The default interval for the probes are 2 hours. 12.3.1.9 Receive partial data Value: 256 MACRO-11: PU.RXP BASIC+2: TCPOPT_RXP C: TCPOPT_RXP FORTRAN-77: PURXP Pascal: tbd PAGE 12-14 DETAILED INFORMATION ON INTERFACES TCP If enabled, TCP will return reads for partial data on unfort- matted connections. Basically, at read, all currently availabe data, up to the size of the receive buffer will be received. If read finished before filling up the whole buffer, the return status will be IS.SUC, but with the high byte set to 1. If no data at all is available, the read will block. 12.3.1.10 Transmit with PUSH Value: 512 MACRO-11: PU.TXP BASIC+2: TCPOPT_TXP C: TCPOPT_TXP FORTRAN-77: PUTXP Pascal: tbd If enabled, TCP will set PSH on all outgoing packets. This differs from doing an actual push in that data can still be buf- fered according to nagle. But once the data actually do go out, it will have the push bit set anyway, so that the remote end gets the data right away, if wanted. 12.3.1.11 Transmit with no blocking Value: 1024 MACRO-11: PU.NBL BASIC+2: - C: - FORTRAN-77: - Pascal: tbd If enabled, TCP will do writes as normal, as long as there is space in the transmission buffers. If there is no space, TCP will fail the write with a IE.DNR error, with the second word in the IOSB indicating how many bytes were actually written. 12.3.1.12 Push on read Value: 2048 MACRO-11: PU.POR BASIC+2: TCPOPT_POR C: TCPOPT_POR FORTRAN-77: PUPOR Pascal: tbd If enabled, TCP will do a push of the written data when a read is issued. In combination with the high throughput options, this can be a way to make efficient use of the network. PAGE 12-15 DETAILED INFORMATION ON INTERFACES TCP 12.3.1.13 Receive with no blocking Value: 4096 MACRO-11: PU.RBL BASIC+2: - C: - FORTRAN-77: - Pascal: tbd If enabled, TCP will do reads as normal, as long as there is data in the receive buffers. If there is no more data, TCP will fail the read with a IS.BLK error, with the second word in the IOSB indicating how many bytes were actually received. 12.3.1.14 Send immediate ACK Value: 8192 MACRO-11: PU.ACK BASIC+2: TCPOPTACK C: TCPOPTACK FORTRAN-77: PUACK Pascal: tbd If enabled, TCP will always immediately send ACK for any re- ceived data. 12.3.2 TCP PUSH The TCP ports can send data marked as push. This has the ef- fect of sending the data right away, without any further buffering, no matter what mode the socket is in. If any previous data has been sent on the port, but have been buffered, that data will also be sent immediately at the point when a push is requested. Tasks are not notified if data is received that has been pushed. Received data is delivered to the task based on the mode of the socket, and the I/O function requested. 12.3.3 TCP URGENT data The TCP sockets can send data marked as urgent. This is always done in combination with a PUSH, and the implication is that all currently buffered data also becomes marked as URGENT as well. Received URGENT data is handled the same as any other data. No special information or indication is passed on to programs about URGENT data. PAGE 12-16 DETAILED INFORMATION ON INTERFACES TCP 12.3.4 QIO interface The QIO interface to UD: have both some internal functions, which are not usable through the QIO interface, and some functions that are privileged. 12.3.4.1 IO.CEP Create endpoint. P1 - Port # P2 - Address of remote endpoint buffer (6 bytes) IOSB+2 - created port # If a port number is not specified, a random port number will be used. The P2 parameter is optional. 12.3.4.2 IO.SCR Son of create endpoint (inherit EP when executed) P1 - Port # IOSB+2 - opened port # The port number is optional. If a port number is not speci- fied, a random request queued for the current task will be picked up. It also means that a connection for any port local port number will be picked up, so the service can be running independent on which port it has been set up for. If no request has been queued for the task, the call will fail. If a port is specified, and no request have been queued with that specific local port number, the call will fail. 12.3.4.3 IO.CON Connect endpoint P1 - Address of endpoint (6 bytes) P2 - User flags P3 - User timeout P4 - User keepalive PAGE 12-17 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.4 IO.ACC Accept connection P1 - Address of endpoint (6 bytes) P2 - User flags P3 - User timeout P4 - User keepalive P1 is optional. 12.3.4.5 IO.LSN Setup endpoint as server P1 - Address of endpoint (6 bytes) P2 - Connection queue limit P1 is optional. If P2 is zero, a default value of 2 will be used. 12.3.4.6 IO.REJ Reject connection This call rejects the first connection queued for a port. This can be used in combination with reading from a listening port, will will read out the remote address of the first request queued, so that a connection request can be inspected before it is ac- cepted. And if wanted, it can then be rejected. Example using this can be found in TCPTEST14. 12.3.4.7 IO.RLB Read data. If data is read in binary mode, only finish when P2 number of bytes have been read, or when remote close connection. In the latter case, IOSB will return 401(8). P1 - Address of buffer P2 - Size of buffer P3 - Unblock AST (if 0) P4 - Timeout (0 = use default) IOSB+2 - Actual size of data read PAGE 12-18 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.8 IO.RPB Read forcing binary mode. Parameters otherwise same as IO.RLB. 12.3.4.9 IO.RCV Read with PUSH notifications. Same as IO.RLB, but can return early for binary mode, if either PUSH or FIN is received. In such case, returns with IOSB = 401(8). 12.3.4.10 IO.RSD Special read function for privileged programs, that can read to arbitrary address in physical memory. P1 - Buffer map value (to be loaded in APR6) P2 - Buffer bias in APR6 space. P3 - Buffer length P4 - Flags IOSB+2 - Actual size read 12.3.4.11 IO.WLB Write data. P1 - Address of buffer P2 - Size of buffer P3 - VFC control (Bit 15 forces push) (Bit 14+15 forces TCP URGENT and push) IOSB+2 - Actual number of bytes written The VFC control is only the low byte of P3. Understood values are only space, which appends CR+LF. Anything else is ignored, and nothing is appended. 12.3.4.12 IO.WAL Same as IO.WLB, with the exception that it is always an unfor- matted write, with no VFC handling (push and urgent data is still possible). PAGE 12-19 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.13 IO.WSD Special write function for privileged code that can send data from anywhere in physical memory. P1 - Buffer mapping (APR6 value) P2 - Buffer APR6 bias address P3 - Buffer size P4 - VFC control IOSB+2 - Actual size written 12.3.4.14 IO.GCO Get connection info P1 - Address of buffer (E.SIZ bytes) P2 - Entry # (0 = own connection) 12.3.4.15 IO.CLN Close connection 12.3.4.16 IO.RCV Receive data P1 - Address of buffer P2 - Size of buffer P3 - Unblock AST (if 0) P4 - Timeout (0 = use default) IOSB+2 - Actual size received A timeout value of 0 means use default. 12.3.4.17 IO.XMT Transmit data P1 - Address of buffer P2 - Size of buffer P3 - VFC IOSB+2 - Actual size written PAGE 12-20 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.18 IO.RAS Setup receive AST notification P1 - AST address P2 - User parameter If an AST notification have been set up, the address is called as an AST when there is data available. The user parameter is pushed on the stack before the AST is called, and needs to be removed by the AST routine before exiting the AST. 12.3.4.19 IO.RUN Start protocol. 12.3.4.20 IO.STP Stop protocol. 12.3.4.21 IO.RST Read statistics. P1 - Address of statistics buffer P2 - Size of statistics buffer IOSB+2 - Size of returned data 12.3.4.22 IP.RCV Internal receive function from IP. 12.3.4.23 IP.RER Internal receive function from ICMP. 12.3.4.24 IO.CAN Cancel I/O. PAGE 12-21 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.25 IO.FLS Flush I/O. 12.3.4.26 IO.IFL Flush input buffer (drop data). 12.3.4.27 IO.ADD Add a TCP port listener. P1 - Port # P2 - Task name (RAD50) P3 - Max connections 12.3.4.28 IO.REM Remove a TCP port listener. P1 - Port # 12.3.4.29 IO.RNT Run network task P1 - Task name (RAD50) P2 - EFN P3 - Exit status block P4 - AST address 12.3.4.30 IO.OPS Set user options P1 - User options P2 - User keepalive value IOSB+2 - old user options P2 can be 0 to have no change to the value, or -1 to set to default. PAGE 12-22 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.31 IO.OPG Get user options IOSB+2 - User options 12.3.4.32 IO.TIM Set timeout P1 - New timeout (seconds) 12.3.4.33 IO.SMT Set minimum transmit timeout P1 - New minimum timeout (milliseconds) IOSB+2 - Old timeout If new timeout is 0, the value is unchanged. 12.3.4.34 IO.TWT Set timeout wait period P1 - New timeout wait period (seconds) IOSB+2 - Old timeout If new timeout is 0, the value is unchanged. 12.3.4.35 IO.QMX Set syn queue maximum size P1 - New size (0 = no change) IOSB+2 - Old size 12.3.4.36 IO.CHR Set special mode (TCP) P1 - Separator character P2 - Max number of characters PAGE 12-23 DETAILED INFORMATION ON INTERFACES TCP 12.3.4.37 IO.RSZ Read input buffer size IOSB+2 - Size of input buffer 12.3.4.38 IO.RSV Call name resolved 12.3.4.39 IO.SXS Set transmit buffer size If argument is 0, buffer size is unchanged. If argument is negative, the buffer size is reset to default. On return, IOSB+2 holds old buffer size. 12.3.4.40 IO.SRS Set receive buffer size If argument is 0, buffer size is unchanged. If argument is negative, the buffer size is reset to default. On return, IOSB+2 holds old buffer size. 12.3.4.41 IO.SSS Set transmit segment buffer size If argument is 0, buffer size is unchanged. If argument is negative, the buffer size is reset to default. On return, IOSB+2 holds old buffer size. Page 12-24 CHAPTER 13 LIBRARIES The basic manipulation of TCP/IP in RSX is helped by two libraries. o LB:[1,1]IPMAC.MLB o LB:[1,1]IPLIB.OLB 13.1 LB:[1,1]IPMAC.MLB This library holds a set of macros meant to make it easier to code for TCP/IP from MACRO-11. The macros are: o IP$NFO o UD$NFO o TC$NFO o .ADDR o .SOCK 13.1.1 IP$NFO This macro defines the offsets for the various statistics that IP: can return. 13.1.2 UD$NFO This macro defines the offsets for the various statistics that UD: can return. 13.1.3 TC$NFO This macro defines the offsets for the various statistics that TC: can return. PAGE 13-1 LIBRARIES LB:[1,1]IPMAC.MLB 13.1.4 .ADDR a,b,c,d Creates a IP address in a usable form for I/O calls to TCP. The parameters are the four octets defining the IP address (all four must be present). 13.1.5 .SOCK ,n Create a socket structure for use with TCP or UDP. The is the IP address, within angle brackets. The address can optionally be skipped, in which case an address of 0.0.0.0 is used, which for local endpoint means it will use the appropriate local IP address. The parameter n is the port number. It should always be in native byte order. 13.2 LB:[1,1]IPLIB.OLB This IPLIB object library contains many functions and symbols needed to get a program interacting with TCP/IP correctly. 13.2.1 IP This object holds all symbols used by the TCP/IP drivers. Basically all the public IO functions usable by QIO$. 13.2.2 RESLIB This object holds the general host string to IP and IP to host string functions. Host strings are given by a string descriptor, which is a 2 word item. The first word is the length of the string, and the second word points to the string itself. For functions returning a string, the length should indicate the available length in which to place the resulting string. These functions return with carry set if an error occured. Hostname strings can be padded with spaces, and terminate at the colon character if one is found. PAGE 13-2 LIBRARIES LB:[1,1]IPLIB.OLB 13.2.2.1 H2IP Called to convert a hostname to an IP address. ----------------------------------- In: R0 - Points to host string name R1 - Points to memory where to place an IP address (see .ADDR) ----------------------------------- 13.2.2.2 H2IPP Called to convert a hostname to an IP address and port. ----------------------------------- In: R0 - Points to host and port string name R1 - Points to memory where to place a IP address (see .SOCK) ----------------------------------- 13.2.2.3 IP2H Called to convert an IP address into a string. ----------------------------------- In: R0 - Points to string descriptor R1 - Points to IP address R2 - Flags for conversion Out: R2 - Actual length of returned string (without NUL) ----------------------------------- The flags are: Q.ADR Write IP address without name translation Q.AAPP Append IP address within () after name Q.NADR If no match, write IP address Q.NQM If no match, write "?" instead Q.WLD If address is 0.0.0.0, write "*" instead Q.PORT Append :n for port number. Assumes port comes after address Q.NULL Append a NUL after the string The flags may be combined. PAGE 13-3 LIBRARIES LB:[1,1]IPLIB.OLB 13.2.3 RESLUN This module contains only a default definition for a LUN to use for name resolution in case where the task has not defined a RESLUN word itself. RESLUN should be a 16-bit word holding the LUN to use for name resolution. If the LUN specified is not assigned to TC:, the resolver library will reassign it to TC: when called. The default LUN is .USLU2, which is a LUN dynamically assigned at task build time to be a LUN not otherwise used by the program. 13.2.4 RESEFN This module contains only a default definition for a EFN to use for name resolution in the case where the task has not defined a RESEFN word itself. RESEFN should be a 16-bit word holding the event flags to use for name resolution. The default EFN is 1. 13.2.5 RESSYM The symbolic constants for use with RESLIB. 13.2.6 TCPSYM This object holds all symbols used by the TCP layer, such as option definitions, and the endpoint structure symbols. 13.2.7 UNOTIF This object holds the user level function to notify the spoof processor about potential abuse. To use this function, you place the LUN on which the connec- tion to the abuser is connected in R0, put a "cost" value in R1, and call $NOTI2. Example: . . . MOV #LUN,R0 MOV #1,R1 CALL $NOTI2 . . . PAGE 13-4 LIBRARIES LB:[1,1]IPLIB.OLB If the cost is set to zero, a default value is used. Page 13-5 CHAPTER 14 HLL LIBRARIES There are high level language libraries for BASIC+2, PDP-11 C, FORTRAN-77 and Lisp today. Other language libraries are currently in progress. 14.1 BASIC+2 In order to use the BASIC+2 IP functions you should: 1. %INCLUDE "LB:[1,1]INET.B2S" 2. Task build commands should include: 1. LB:[1,1]IPBP2.OLB 2. LB:[1,1]IPLIB.OLB 14.1.1 General BASIC+2 functions and routines normally produce results upon return. If any errors occur, the BASIC+2 program needs to have an error handler, or else the program will abort. BASIC+2 does not normally indicate errors through special return values. In addition to the functions, the BASIC+2 library makes one global variable visible that holds the network error in the case an error occurs. This global is NETERR and the value may be examined to get more specific information about the error that occurred. The value in NETERR is the actual I/O completion code from TCP or UDP, and as such, you need to refer to the error codes that QIO$ may return. 14.1.2 Network functions/routines The network functions are all related to communication with TCP or UDP. In addition to the library specific functions, you can use the normal BASIC PRINT/INPUT statements as well (LINPUT is the recommended function to read network data). 14.1.2.1 TCP TCP creates a TCP socket for use in BASIC+2. Format lport = TCP(chnl, port) chnl is the file number on which a tcp socket is to be created. port is the port number indicator (see the next paragraph for PAGE 14-1 HLL LIBRARIES BASIC+2 details). lport is the actual port number created. If port is 0, a free port will be assigned. If port is less than 1024, the program must be privileged, or else the port crea- tion fails. 14.1.2.2 UDP UDP creates a UDP socket for use from BASIC+2. Format lport = UDP(chnl, port) chnl is the file number on which an udp socket is to be created. port is the port number indicator (see the next paragraph for details). lport is the actual port number used in creation. If port is 0, a free port will be assigned. If port is less than 1024, the program must be privileged, or else the port crea- tion fails. 14.1.2.3 SOCKET SOCKET is a special case of the TCP function, and is used for when the program is started from a server, and is inheriting an endpoint that already exists. Format lport = SOCKET(chnl, port) chnl is the file number on which a tcp socket is to be created. port is the port number indicator (see the next paragraph for details). lport is the actual port number used in creation. If an endpoint with the port number specified does not already exist, queued for this task, the function will return with a local port of 0. If the port argument is 0, it will find whatever endpoint has been queued for the task, and attach to it, returning the actual local port that the endpoint uses. If no endpoint at all has been queued for the task, the function returns 0. PAGE 14-2 HLL LIBRARIES BASIC+2 14.1.2.4 CONNEC CONNEC will attempt to initiate a connection to a remote destination. Format CALL CONNEC(chnl, dst, tmo, flg) chnl is the file number on which a socket has previously been created. dst is a 6-character string (4 octets for IP4 address plus two bytes for port number), giving the remote IP address and port number to connect to. tmo is a timeout value in seconds. flg is the TCP option flags to use. For UDP, the value is ignored. 14.1.2.5 LISTEN LISTEN will set up an explicit listener endpoint, on which multiple connections can be accepted. Format CALL LISTEN(chnl) chnl is the file number on which a socket has been created. 14.1.2.6 ACCEPT ACCEPT will accept a connection request on a socket. Format CALL ACCEPT(chnl,src,tmo,flg) chnl is the file number on which a socket has been created. src is a string (minimum 6 bytes) into which ACCEPT will write the address and port of the remote end initiating the connection. tmo is the timeout on the socket flg are the TCP flags to use for the socket. This argument is ignored by UDP. 14.1.2.7 CLOSE CLOSE will initiate a close on a connection. Using the stan- dard BASIC CLOSE statement does not work. Format CALL CLOSE(chnl) PAGE 14-3 HLL LIBRARIES BASIC+2 chnl is the file number on which a socket is open. 14.1.2.8 GEP GEP (GetEndPoint) will return the remote end of an established connection. Format ep = GEP(chnl) chnl is the file number on which a socket is open. ep is assigned a 6 byte string giving the address and port of the remote end. 14.1.2.9 SFLG SFLG sets/changes the TCP flags on an existing connection. Format CALL SFLG(chnl,flg) chnl is the file number on which a socket is open. flg is the TCP flags to apply to the connection. 14.1.2.10 GFLG GFLG returns the current TCP flags on an existing connection. Format flg = GFLG(chnl) chnl is the file number on which a socket is open. flg is assigned the current flags value. 14.1.2.11 STMO STMO sets a new timeout value on an existing connection. Format CALL STMO(chnl, tmo) chnl is the file number on which a socket is open. tmo is the new timeout to use. PAGE 14-4 HLL LIBRARIES BASIC+2 14.1.2.12 SCHR SCHR sets a special character mode on an existing TCP socket. While the mode is in effect, the normal delimiters to terminate a read are disabled. Instead a special delimiter character is ac- tive, and a specified number of characters are accepted while in this mode. Format CALL SCHR(chnl, char, cnt) chnl is the file number on which a socket is open. char is the ASCII value of the character that is to be the special delimiter. cnt is the count of characters to read in this special mode. 14.1.2.13 PUSH PUSH will force a TCP push to be performed at that point. Format CALL PUSH(chnl) chnl is the file number on which a socket is open. 14.1.2.14 SEND tbd 14.1.2.15 SENDTO tbd 14.1.2.16 RECV RECV will do a receive on the channel, without any further in- terpretation of the data beyond what the TCP/IP mode says. (Unlike the various BASIC INPUT statements that add some additional inter- pretation.) Format str = RECV(chnl, len) chnl is the file number on which a socket is open. len is the maximum length acceptable to read. str is the string that will contain the read data. PAGE 14-5 HLL LIBRARIES BASIC+2 14.1.2.17 RECVFR tbd 14.1.3 Name resolution routines tbd 14.1.3.1 HOST2I tbd 14.1.3.2 IP2HOS tbd 14.1.3.3 FINDMX tbd 14.1.3.4 MXPREF tbd 14.1.3.5 MXHOST tbd 14.1.4 Other functions 14.1.4.1 NOTIFY tbd PAGE 14-6 HLL LIBRARIES PDP-11 C 14.2 PDP-11 C The C library is still in development, but may be used. It is written for the DEC PDP-11 C ANSI compiler, and will not work with the DECUS C compiler. C programs that wish to use TCP networking should: 1. #include 2. Task build commands to include: 1. LB:[1,1]IPC.OLB 2. LB:[1,1]IPLIB.OLB 14.2.1 General The PDP-11 C interface to the network is through a set of functions that slightly relate to the Unix API, but it is NOT com- patible. The goal has been to make an interface that is easier to use and needs less code. The API is in many cases focused around FILE handles, so that the stdio library functions may be used for the most part. However, there are times when the program needs to deal with socket addresses specifically. For this purpose a specific structure is defined: typedef struct { unsigned char addr[4]; } in_addr_t; typedef unsigned int in_port_t; struct sockaddr { in_addr_t s_addr; in_port_t s_port; }; This structure is not compatible with the Unix counterpart ei- ther but it should be pretty clear how to use it. Another structure defined is the mxhost structure that may be used by programs that want to resolve MX information from DNS. struct mxhost { int pref; char host[256]; }; In addition, there are two external variables that the C library makes available. 1. neterr 2. lport PAGE 14-7 HLL LIBRARIES PDP-11 C neterr holds the network error of the last operation re- quested. The C functions only return an indication that something failed, without any more details about why. neterr will hold the actual I/O error of the underlying operation. You should consult the possible error codes from QIO$ for more information. lport will hold the local port number of a created port. 14.2.2 Network functions/routines The network functions are all related to communication with TCP or UDP. In addition to the library specific functions you may use the normal C stdio functions as well. 14.2.2.1 tcp tcp creates a TCP socket for use from C. Format FILE *tcp(unsigned int port); 14.2.2.2 udp udp creates a UDP socket for use from C. Format FILE *udp(unsigned int port); 14.2.2.3 socket socket is a special case of the tcp function, and is used for when the program is started from a server, and is inheriting an endpoint that already exists. Format FILE *socket(unsigned int port); If an endpoint with the port number specified does not already exist, queued for this task, the function will return NULL. If the port argument is 0, it will find whatever endpoint has been queued for the task, and attach to it, returning a pointer to the actual FILE structure containing the local port that the endpoint uses. If no endpoint at all has been queued for the task, the function returns NULL. PAGE 14-8 HLL LIBRARIES PDP-11 C 14.2.2.4 connect tbd 14.2.2.5 listen tbd 14.2.2.6 accept tbd 14.2.2.7 close tbd 14.2.2.8 gep tbd 14.2.2.9 sflg tbd 14.2.2.10 gflg tbd 14.2.2.11 stmo tbd 14.2.2.12 schr tbd PAGE 14-9 HLL LIBRARIES PDP-11 C 14.2.2.13 push tbd 14.2.2.14 iflush tbd 14.2.2.15 send tbd 14.2.2.16 sendto tbd 14.2.2.17 recv tbd 14.2.2.18 recvfrom tbd 14.2.2.19 clrio extern void clrio(FILE *); This function is needed when switching from reading to writing or vice versa, as the C stdio library only allows reading or writ- ing to a file i.e. a single IO mode (read or write) when the opened without an intervening fseek call. Using this function al- lows you to both read and write without the inconvenience of an fseek call, or closing and re-opening an endpoint in the opposite mode. 14.2.3 Name resolution PAGE 14-10 HLL LIBRARIES PDP-11 C 14.2.3.1 host2ip TBD 14.2.3.2 ip2host TBD 14.2.3.3 mxhost TBD 14.2.4 Byte order handling 14.2.4.1 ntohs TBD 14.2.4.2 ntohl TBD 14.2.4.3 htons TBD 14.2.4.4 htonl 14.2.5 Other functions 14.2.5.1 _isme TBD PAGE 14-11 HLL LIBRARIES PDP-11 C 14.2.5.2 _notify _notify is used to notify the spoof filtering of a potential abuser. Format void _notify(FILE *, int); TBD 14.3 FORTRAN-77 In order to use the FORTRAN-77 IP functions you should: 1. INCLUDE 'LB:[1,1]INET/NOLIST' 2. Task build commands to include: 1. LB:[1,1]IPF77.OLB 2. LB:[1,1]IPLIB.OLB 14.3.1 General FORTAN-77 functions normally returns a success status on re- turn. A 0 means success, while any non-zero value means failure. Exceptions are TCP, UDP and SOCKET, which actually return the created local port number on success, and return 0 on error. In addition, the FORTRAN-77 library makes a global variable visible that holds the network error code in the case where an er- ror occurrs. This value may be examined to get more specific in- formation about an error. The value in NETERR is the actual I/O completion code from TCP or UDP, and as such, you need to refer to the error codes that QIO$ may return. 14.3.2 Network functions/routines The network functions are all related to communication with TCP or UDP. In addition to the library specific functions, you may use the normal FORTRAN-77 READ/WRITE statements as well. IP addresses can be stored in anything that can hold at least 6 bytes. For example a DOUBLE, a CHARACTER*6, or a 3 element array of INTEGER*2. PAGE 14-12 HLL LIBRARIES FORTRAN-77 14.3.2.1 TCP TCP creates a TCP socket for use from FORTRAN-77. Format NPORT = TCP(UNIT,PORT) 14.3.2.2 UDP UDP creates a UDP socket for use from FORTRAN-77. Format NPORT = UDP(UNIT,PORT) 14.3.2.3 SOCKET SOCKET is a special case of the TCP function, and is used for when the program is started from a server, and is inheriting an endpoint that already exists. Format NPORT = SOCKET(UNIT,PORT) If an endpoint with the port number specified does not already exist, queued for this task, the function will return 0. If the port argument is 0, it will find whatever endpoint has been queued for the task, and attach to it, returning the actual local port number that the endpoint uses. If no endpoint at all has been queued for the task, the function returns 0. 14.3.2.4 CONNEC CONNEC will attempt to establish a connection to a remote destination. Format ERR = CONNEC(UNIT,DST,TMO,FLG) UNIT is the UNIT number DST is the destination IP address TMO is the timeout value in seconds FLG is the TCP option flags to use. For UDP, the value is ig- nored. PAGE 14-13 HLL LIBRARIES FORTRAN-77 14.3.2.5 LISTEN LISTEN will set up an explicit listener endpoint, on which multiple connections can be accepted. Format ERR = LISTEN(UNIT) UNIT is the unit number on which a socket has been created. 14.3.2.6 ACCEPT ACCEPT will accept a connection request on a socket. Format ERR = ACCEPT(UNIT,SRC,TMO,FLG) UNIT is the unit number on which a socket has been created. SRC is the location into which ACCEPT will write the IP address and port of the remote end initiating the connection. TMO is the timeout on the socket. FLG are the TCP flags to use for the socket. This argument is ignored by UDP. 14.3.2.7 SCLOSE SCLOSE will initiate a close on a connection. Using the stan- dard FORTRAN-77 CLOSE statement will not work. Format CALL SCLOSE(UNIT) UNIT is the unit number on which a socket has been created. 14.3.2.8 GEP GEP will return the remote end of an established connection. Format CALL GEP(UNIT,EP) UNIT is the unit number on which a connection has been established. EP is the destination where the remote endpoint IP information will be written. PAGE 14-14 HLL LIBRARIES FORTRAN-77 14.3.2.9 PUSH PUSH will force a TCP push to be performed at that point. Format CALL PUSH(UNIT) UNIT is the unit number of an established connection. 14.3.3 Name resolution routines The name resolution routines are used to translate between IP addresses and host names. IP addresses are stored as 6 bytes of data. Normally, either a DOUBLE, or a CHARACTER*6 (or larger) are used to store these ad- dresses. Hosts are plain strings holding a hostname. It is allowed to have spaces after the end of the string (that will be ignored). Also, optionally, a port number can be added after a colon character. 14.3.3.1 HOST2I HOST2I will translate from a host string to an IP address. Format ERR = HOST2I(EP, STR, STRL, PORT) EP is an output IP address STR is the input string STRL is the size of the input string PORT is the default port number to use for the resulting IP ad- dress. 14.3.3.2 IP2HOS IP2HOS will translate from an IP address to a host string. Format ERR = IP2HOS(EP, FLG, STR, STRL) EP is an IP address FLG is the flags to be applied to the translation of the address STR is the output string where the result will be placed STRL is the size of the output string The FLG flags variable may have the following values: PAGE 14-15 HLL LIBRARIES FORTRAN-77 RADR Write IP address without translation RAAPP Append IP address within () after name RNADR If no match, return the IP address RNQM If no match, return a "?" hostname instead RWLD If address is 0.0.0.0, return "*" instead RPORT Append :n for a port number n 14.4 PASCAL The BQTCP library for Pascal is compatible with the Oregon Pascal-2 compiler. 14.4.1 General In order to use the functions, the Pascal source file should include: %INCLUDE PAS:INET; When task building a Pascal binary, in addition to all other libraries required, the following libraries should be included, be- fore the PASCAL runtime library: o LB:[1,1]IPPAS.OLB o LB:[1,1]IPLIB.OLB 14.4.1.1 Data types INET defines the type inaddr, which holds an ip address and port number that is needed by some functions. 14.4.2 Network functions 14.4.2.1 TCP The TCP function is used to open a TCP socket. TCP(VAR F: TEXT; PORT: INTEGER): INTEGER; F is a TEXT file, which will be used to access the TCP socket. PORT is the desired local port to open. If PORT is 0, a ran- dom port is assigned. The function will return the actual PORT opened, or 0 if there is an error. PAGE 14-16 HLL LIBRARIES PASCAL 14.4.2.2 ACCEPT ACCEPT will accept a connection request on a previously created tcp socket. ACCEPT(VAR F: TEXT): BOOLEAN; F is the previously created TCP socket. The function will return TRUE if the accept call succeeded, and FALSE if there is an error. 14.4.2.3 CONNECT CONNECT will try to establish a connection to a remote service using a previously created TCP socket. CONNECT(VAR F: TEXT; VAR DST: INADDR): BOOLEAN; F is the previously created TCP socket. DST is the destination to connect to. The function will return TRUE if the connect call succeeded, and FALSE if there is an error. 14.4.2.4 SCLOSE SCLOSE will close an existing tcp socket. The normal Pascal close call is not enough. SCLOSE(VAR F: TEXT); F is the previously created TCP socket. 14.4.2.5 INFO INFO will give information about the remote address connected to a socket. INFO(VAR F: TEXT; VAR ADDR: INADDR): INTEGER; F is the previously created TCP socket. ADDR is the variable into which to place the information about the remote end. The function will return the local port number for the TCP socket. PAGE 14-17 HLL LIBRARIES PASCAL 14.4.3 Name resolution 14.4.3.1 HOST2IP HOST2IP is used to translate from a host string to a inaddr address. HOST2IP(HOST: STRING; ADDR: INADDR): BOOLEAN; HOST is the host string to translate. ADDR is the destination variable to write the address to. The function will return TRUE if the translation succeeds, and FALSE if there is an error in the address translation. 14.4.3.2 IP2HOST IP2HOST will translate an address into a string. IP2HOST(VAR ADDR: INADDR; STRING: PACKED ARRAY[A..B: INTEGER] OF CHAR; FLAGS: RESFLAGS): INTEGER; ADDR is the address to translate. STRING is the destination string to write the translated ad- dress to. FLAG is the set of resolver flags to apply. The function will return the actual number of bytes in the resulting string. 14.5 LISP XLISP V1.7 exists for RSX, and has been extended to include support for communication over TCP/IP. Some example programs have been provided but more detailed do- cumentation is currently missing. Please send any questions to Johnny Billquist, as well as requests for documentation. PAGE 14-18 HLL LIBRARIES LISP 14.5.1 General LISP only has access to TCP communication. In general, socket objects in LISP work similar to file objects. Differences are that it is possible to both read and write to a socket, and there are a number of helper functions and special operations that only work on sockets. Apart from the socket objects, data is managed through the normal data types and lists that LISP manage and are used in a way that (hopefully) makes sense. 14.5.2 Daemons XLISP is aware if it has been started as a daemon from BQTCP, and in such a case, XLISP will redirect *standard-input* and *standard-output* to the socket, so all "normal" IO operations will in fact be done towards the socket. XLISP will then execute SYS$LISP:INET.LSP. A simple INET.LSP is provided with the distribution. This INET daemon will try to run P.LSP where is the port number that the connection was accepted on. So a daemon for port 8 would run SYS$LISP:P8.LSP. A program can see if it is running as a daemon by examining the result from (port), which will return nil if not running as a daemon. When running as a daemon, the *breakenable* atom is by default set to nil, essentially disabling debugging. Be aware that if *breakenable* is explicitly set to true, and there are any errors while running as a daemon, uncaught errors that would cause an exception will go to the traceback or debugging level and will then be accessible by the internet connection, pos- sibly compromising the system. The TCP connection accepted as a daemon will have flags PU.TXT, PU.CR and PU.KAF applied. In addition, the timeout will be 120s by default. 14.5.3 Network functions 14.5.3.1 neterr (neterr) Will return the latest network error result. PAGE 14-19 HLL LIBRARIES LISP 14.5.3.2 socket (socket [n]) Creates a socket object, optionally with a specific local (in- teger) port. Any errors are fatal. If no port number is given, or if the port number is 0, a ran- dom port will be used. Exactly which port was used can be found by the (port f) function. 14.5.3.3 listen (listen f) Sets up a socket f for server operation. 14.5.3.4 accept (accept f [tmo [flg]]) Tries to accept an incoming connection request on a socket f with an optional timeout, and optional flags. Default flags are PU.TXT|PU.CR!PU.TXP If an error occurs, the function returns nil, otherwise true. 14.5.3.5 connect (connect f dst [tmo [flg]]) Connect a socket f to a remote destination (string), with an optional timeout and user flags. Default flags are PU.TXT|PU.CR!PU.TXP If an error occurs, the function returns nil, otherwise true. 14.5.3.6 port (port [f]) This will return the port information of a socket f. The re- turned port information is a list of 6 integers: (lport n n n n rport) PAGE 14-20 HLL LIBRARIES LISP where lport is the local port number, n*4 is the remote ip ad- dress and rport is the remote port. If no argument is given, *standard-input* is used. If the argument is not a socket, the function returns nil. 14.5.3.7 ip2host (ip2host addr [flg]) ip2host will return a string for an address. The address should be a list with 5 integers: (n n n n port) where n*4 is the ip address, and port is the port number. flg is the translation format wanted, which defaults to RESHARD|RESPORT. 14.5.3.8 flush (flush [f]) will force flushing of buffered output on a file or a socket f. If no argument f is given, *standard-output* is used. 14.5.4 System services 14.5.4.1 date (date [n]) This will return a string with date and time for a value. If the argument n is not given, the integer for "right now" is used (see (time)). 14.5.4.2 time (time) This will return an integer giving the seconds since the start of the epoch. PAGE 14-21 HLL LIBRARIES LISP 14.5.4.3 translate (translate sym [flg]) translate will perform a logical name translation of the sym string, returning the equivalent string. If no translation exists, it will return an empty string. flg is an integer that can be used to supress searching of some logical tables. Page 14-22 CHAPTER 15 CGI PROGRAMMING A program that runs in the CGI environment will normally out- put text that will be provided to the web client. This text starts of when the http header is being output, so the CGI program needs to at some point output an empty line, after which the actual con- tent of the body is provided. By default, CGI responses are HTTP 200 code responses. However, if a CGI program first output string is a 3 digit number, followed by an optional string, this number, and the string, will instead be used as the HTTP response code. 15.1 IND tbd 15.1.1 HEADER 15.1.2 GETQP 15.1.3 GETQP2 15.1.4 COOKIE 15.1.5 FRMINI 15.1.6 FRMGET 15.1.7 FRMEND 15.1.8 URLDEC PAGE 15-1 CGI PROGRAMMING C 15.2 C tbd 15.3 BASIC+2 tbd Page 15-2 CHAPTER 16 EXAMPLE PROGRAMS This chapter contains a little information and documentation for the example programs that are provided along with the BQTCP/IP implementation. Unless otherwise stated, the code resides in [IPEXAMPLE]. 16.1 INETD INETD is a generic TCP server for a set of well known ser- vices. These are all provided by the same task, which sets up servers for all the ports, and then executes the services as needed. The generic server code is located in [IPAPPL]INETD.MAC, and each service has its own source file. o ECHO.MAC implements the TCP ECHO service. o SINK.MAC implements the TCP SINK service. o DAYTIME.MAC implements the TCP DAYTIME service. o QUOTD.MAC implements the TCP QUOTD service. o IDENTD.MAC implements the TCP IDENTD service. Note that, while this program works fine, there is a "better" INETD implementation under [IDNETD], which runs as a daemon. This example program runs by having an active task, that is listening on all these sockets (ports). 16.1.1 ECHO ECHO is a TCP echo service. It returns back whatever is sent to it. 16.1.2 SINK SINK is a TCP sink service. It just reads anything sent to it, and does nothing with it. Think of it as /dev/null or a NL: device for network traffic. 16.1.3 DAYTIME DAYTIME is a TCP daytime service. When something connects to it, it sends the current time to the remote end, and then closes. The time is not RFC compliant, but is only a local time string. PAGE 16-1 EXAMPLE PROGRAMS INETD 16.1.4 QUOTD QUOTD is the TCP quote of the day service. It runs the COO command in a virtual terminal, and sends the output to the remote end, and closes the connection when COO finishes. COO is expected to be a COOKIE program that just output some arbritrary text. 16.2 HTTPD (CODE FOUND IN [HTTPD]) HTTPD is an example of how you can have a small server daemon running that listens to a socket. It creates a server task upon receiving an incoming request, all by using RSX kernel routines for the task creation. The server task will have a parent/offspring relation to the server daemon, so that the server daemon will get notified when the server (offspring) task exits. 16.3 HTTPD2 (CODE FOUND IN [HTTPD]) HTTPD2 is another example of how you can have a small server daemon running that listens to a socket. It creates a server task upon receiving an incoming request, using the TC: IO function to create and run an offspring task. The server task will have a parent/offspring relation to the server daemon, so that the server daemon will get notified when the server task exits. Essentially, HTTPD and HTTPD2 work the same way, but HTTPD2 uses the TC: driver to do the task creation for it. 16.4 HTTPD3 (CODE FOUND IN [HTTPD]) HTTPD3 is yet another example of how you can have a small server daemon running that listens to a socket. It creates a server task upon receiving an incoming request, using the TC: IO function to create and run an offspring (child) task. The server task will not keep any information around about re- quested tasks, and will not know when the server task exits (con- trast this with HTTPD2). PAGE 16-2 EXAMPLE PROGRAMS CGIDEMO 16.5 CGIDEMO The directory [CGIDEMO] contains files that demonstrate a lit- tle more advanced CGI functions, such as GET and POST operations that receive and send data. In order to test this, you need to add the following line to your PUBLIC.TXT file: /cgidemo/* @lb:[cgidemo]public.txt 16.6 TCPTEST1 TCPTEST1 is a small example program that listens to a socket, accepts one connection, reads one line, sends it back, and then finishes. 16.7 TCPTEST2 TCPTEST2 is a small example program that creates a socket, connects to a service, sends a line of text to the remote system, reads a line of text from the remote system, and then finishes. 16.8 TCPTEST3 TCPTEST3 is a small example program that creates a socket and starts listening for incoming connections. All incoming connec- tions are served with AST routines, and several connections can be accepted in parallel. On each open socket, it tries to repeatedly read a line of text, and writes all received lines to the terminal. The main program itself does a STOP, and all the operation is done via ASTs. 16.9 TCPTEST4 TCPTEST4 is a program that creates a socket, reads lines of text from that socket, and prints those lines to the terminal. The difference between this program and TCPTEST1, is that this program is intended to be usable by being invoked by another pro- gram and to inherit a connection. This program is used by some of the other test programs listed below. PAGE 16-3 EXAMPLE PROGRAMS TCPTEST5 16.10 TCPTEST5 TCPTEST5 is an example of a server program that creates a socket that it listens on. When connection requests arrive, TCPTEST5 will spawn a TCPTEST4 task to handle each connection, us- ing MCR, issuing a "RUN TCPTEST4" command line. This allows the spawning of a new task that is not installed into the system but still get the offspring information setup. 16.11 TCPTEST6 TCPTEST6 is just a small program used to test that the TC: IO.KIL function works. 16.12 TCPTEST7 TCPTEST7 is a small test program to check that F11ACP I/O functions work using the TC: device. It tries to open a TCP socket for reading. It is otherwise identical to TCPTEST1. 16.13 TCPTEST8 TCPTEST8 is a variant of TCPTEST5, where the main program does not use AST notifications to detect new incoming connection re- quests, but instead does a read on the listening socket, which should return the remote address of any new incoming connection re- quest. 16.14 TCPTEST9 TCPTEST9 is a test program for daemon sockets. TCPTEST9 needs to be installed, and a daemon service defined in TCP. TCPTEST9 then starts up and accepts incoming connections and services them. It is otherwise similar to TCPTEST1. 16.15 TCPTEST10 TCPTEST10 sets up a listening socket to a specific remote destination, and tries to accept a connection, with a timeout. Otherwise the same as TCPTEST1. PAGE 16-4 EXAMPLE PROGRAMS TCPTEST11 16.16 TCPTEST11 TCPTEST11 tests the run task I/O function of TC:. It expects TCPTEST4 to be installed with a specific task name, and requests this task for every incoming connection. The requested task is setup as an offspring task, and TCPTEST11 will be notified whenever the server task exits, and this example keeps track of servers this way. 16.17 TCPTEST12 TCPTEST12 is the same as TCPTEST11, except the server tasks are not setup as offspring tasks. Thus, TCPTEST12 does not keep track of the server tasks. 16.18 TCPTEST13 TCPTEST13 is a program that just verifies that the correct er- rors are returned when trying to create multiple sockets for the same port. 16.19 TCPTEST14 TCPTEST14 is a simple program that opens a TCP socket, listen- ing for an incoming connection, and then rejects it. 16.20 TCPSND TCPSND is a simple test task to check the performance of data sending in TCP. It will try and send 1MB of data as quickly as possibly to a remote machine (as defined in the code). The data to be sent is just NULs, and the program times how long it takes. 16.21 SEND SEND is a simple test of UDP, sending a packet to a UDP ECHO server, and reading the response back. PAGE 16-5 EXAMPLE PROGRAMS ECHO 16.22 ECHO ECHO is a small UDP ECHO server that just sends received UDP packets back to the source. 16.23 SPAM SPAM sends a constant stream of UDP packets to a destination that is not expected to exist. 16.24 UDPTEST UDPTEST is a program that tests most parts of the UDP im- plementation in steps. Page 16-6 CHAPTER 17 RMD PAGES If you have installed DECnet, and also installed the addi- tional, unsupported DECnet RMD pages, TCP/IP extends the RMD pages to give you two more new pages in RMD to display TCP statistics and TCP ports. It also enables the display of open TCP connections of tasks displayed on the task page. The files reside in [IPRMD], and just running TKB @RMDBLD should create an RMD.TSK task in that directory that contains the additional pages. You may wish to "replace" the existing standard RMD task with the enhanced version. Page 17-1 APPENDIX A BQTMAC BQTMAC contains macros that other code might also want to use and would find useful. A.1 PUSH PUSH is a macro that pushes its arguments on the stack. It takes one argument, which can also be a list, and pushes all the values on the stack in the order that they were given. Example: PUSH PUSH R1 A.2 POP POP is a macro that pops values from the stack, and stores them. It takes one argument, which can also be a list. The values are popped from the stack and stored in the arguments in the order given. Exmaple: POP R1 POP A.3 .MSG .MSG is a macro that prints out a formatted message on a LUN. It takes two arguments. The first argument is a string, which is a format string as $EDMSG defines it. The second argument is a list of parameters, which are used as the argument block to the format string in the first argument. The message is written on the LUN given by TILUN, and it uses TIEFN as the event flag for the I/O. If TILUN is not specified in the program, it defaults to 5, and if TIEFN is not given, it also defaults to 5. LUN 5 is by default assigned to TI:, so invoking .MSG without any more definitions or setup should normally produce text on the terminal the task is assigned to. Example: PAGE A-1 BQTMAC .MSG .MSG <"Hello world. 1+2 is %D">,#1+2 Note that the .MSG macro terminates the local symbol block. If local symbols needs to be visible across a .MSG, .ENABL LSB is required. A.4 .IFMT .IFMT starts the creation of a formatted string. An optional argument specifies the address where the string will be created. If not given, a 132 byte buffer addressed as TIBUF is used. Once .IFMT has been invoked, R0 will be pointing to the next byte where text will be placed. R0 cannot be used for anything else. A.5 .FMT .FMT is a macro to copy a formatted string to where R0 is pointing to. .FMT takes two arguments. The first is a format string, as $EDMSG defines it. The second argument is a list of values that are used as the argument block to $EDMSG. See .MSG for more details. A.6 .PRINT .PRINT is a companion macro to .IFMT. .PRINT will print out the string created between .IFMT and .PRINT. As such, .PRINT as- sumes that R0 points to the end of the string and the argument given to .IFMT is the start of the same string. The string is printed to TILUN, using TIEFN for I/O. See .MSG for more details. A.7 .PUT .PUT is an alternative to .PRINT, which takes one argument. This argument is a function, which will be called with R0 pointing to the resulting string, and R1 will hold the length of the string. A.8 .EOS .EOS is an alternative to .PRINT, which just terminates the created string and stores the start address of the string in R0, and the length of the string in R1. Page A-2 APPENDIX B BQTLIB B.1 MACRO-11 LB:[1,1]BQTLIB.OLB BQTLIB is a library with common functions that can be used by many types of code. Since many parts of BQTCP uses BQTLIB, it is included in the BQTCP distribution, even though it is not stricly a part of BQTCP. BQTLIB has code that is called from the macros in BQTMAC. B.1.1 FMT B.1.2 GSA B.1.3 HPW B.1.4 PMATCH B.1.5 ALLOC B.1.6 FREE B.1.7 MEMINI B.1.8 MEMUSE B.1.9 QTDOW PAGE B-1 BQTLIB MACRO-11 B.1.10 QT2STR B.1.11 STR2QT B.1.12 STR2TM B.1.13 TMOFF B.1.14 GETMSG B.1.15 PUTMSG B.1.16 SIGNAL B.1.17 DAYADD B.1.18 DAYS B.1.19 DDAYS B.1.20 DOW B.1.21 ISLEAP B.1.22 PARDAT PAGE B-2 BQTLIB MACRO-11 B.1.23 RDATE B.1.24 GETSAB B.1.25 GETUAB B.1.26 GETUCN B.1.27 SYSNAM B.1.28 UPTIME B.1.29 USRIDL B.1.30 RTIME B.1.31 UTIME B.1.32 CKNET B.1.33 GTHDIR This routine will get the home directory of a user, given an account record. In: R0 Pointer where to write string R1 User record (as returned by VUSER) Out: R0 Updated to point after directory PAGE B-3 BQTLIB MACRO-11 B.1.34 GTSID This routine will get the binary SID, given an account record. In: R1 User record (as returned by VUSER) Out: R0 SID B.1.35 GTUIC This routine will get the binary UIC, given an account record. In: R1 User record (as returned by VUSER) Out: R0 UIC B.1.36 GTFLG This routine will get the user flags, given an account record. In: R1 User record (as returned by VUSER) Out: R0 User flags B.1.37 GTUNAM This routine will get the username, given an account record. In: R0 Pointer to buffer where to write username PAGE B-4 BQTLIB MACRO-11 R1 User record (as returned by VUSER) Out: R0 Updated to point after username B.1.38 VUSER This routine verify a user against the account information. It can be used for just reading out account information, but can also be used to verify the appropriate password for an account. In: R0 Pointer to username/UIC/SID/DIR ASCII string R1 Length of string pointed by R0 R2 Pointer to password string R3 Length of password string R4 Flags required on account R5 Memory area for return (A.LEN in size) Return: Carry clear - user found R0 - Number of matches R1 - Pointer to user record (same as R5 in) Carry set - user not found or password invalid If password length is negative, no checking for password is done. R0-R2 are destroyed by this function. The memory area gived by R5 can be reused for other things when not needed any more. PAGE B-5 BQTLIB MACRO-11 B.1.39 VUSERL This is a call to VUSER with R4 already set with the proper value to check for login allowed. Usage is the same as for VUSER, except R4 does not need to be set. B.1.40 VUSERN This is a call to VUSER with R4 already set with the proper value to check for network login allowed. Usage is the same as for VUSER, except R4 does not need to be set. B.1.41 VUSERSL Verify user with static memory allocation for login. This routine is the same as VUSERL, except that R5 have already been setup to point to a static allocated memory area, and thus R5 does not need to be set to anything before calling. B.1.42 VUSERSN Verify user with static memory allocation for network login. This routine is the same as VUSERN, except that R5 have already been setup to point to a static allocated memory area, and thus R5 does not need to be set to anything before calling. B.1.43 TIPRV Check if TI: is a privileged terminal. Returns with carry set if terminal is privileged. B.1.44 TILGI Check if TI: is a logged in terminal. Returns with carry set if terminal is logged in. PAGE B-6 BQTLIB MACRO-11 B.1.45 TIRMT Check if TI: is a remote terminal. Returns with carry set if terminal is remote. B.1.46 CRC CRC is a function that computes the CRC16-CCITT value of a memory area. In: R0 Pointer to memory area to calculate CRC on R1 Length of memory area Return: R0 Points past memory area R1 0 R2 CRC of memory area All other registers are unmodified. B.2 BASIC+2 LIBRARY LB:[1,1]BQTBP2.OLB LB:[1,1]BQTLIB.B2S B.2.1 Quad time functions Quad time functions are useful in many ways since they represent time in a way that can easily be manipulated. However, it is not a native format for BASIC+2, so these functions are provided to ease their handling. B.2.1.1 QTSTR QTSTR is an external string function to convert a quad time into a string. It takes two arguments: 1. STRING, giving the time stamp 2. WORD, giving the conversion wanted PAGE B-7 BQTLIB BASIC+2 LIBRARY The conversion word codes have the following functions: o 1 Date not wanted o 2 Time not wanted o 4 Time wanted in AM/PM form o 8 Seconds not wanted o 16 Weekday not wanted o 32 Current time wanted o 64 GMT wanted o 128 Timezone name wanted o 258 Timezone offset wanted If bit 32 is set, then no input time string is needed. The timezone flags will be documented later. The output format is in general "Www, DD Mmm YYYY HH:MM:SS +0000 TZ" where - Www, Day of week - DD, Day of month - Mmm, Month in usual three character DEC abbreviation - YYYY, Y2K compatible four digit year - HH, hour - MM, minute - SS, seconds for time - +0000, time offset to UTC - TZ, timezone B.2.1.2 STRQT STRQT is an external function that parses an input string and re- turns a quadtime. It takes one argument: 1. STRING, giving the time string It assumes the time is in GMT format, and will adjust to local time. Input formats understood match those that QTSTR produce. 1. Www, DD Mmm YYYY HH:MM:SS 2. Www, DD-Mmm-YYYY HH:MM:SS 3. Www DD Mmm HH:MM:SS YYYY Note that if only two digits are given for the year, it is in- ferred if it's in the 20th or 21st century. Month names can be in PAGE B-8 BQTLIB BASIC+2 LIBRARY any case. The weekday name is ignored, and just skipped over. See also QTSTR description. B.2.1.3 CMPQT CMPQT is an external function that compares two quad times, and re- turns a value based on the comparison. It takes two arguments: 1. STRING, giving the time1 string 2. STRING, giving the time2 string It returns: 1. -1 Time1 is less than Time2 2. 0 Time1 is equal to Time2 3. 1 Time1 is greater than Time2 B.2.1.4 QTDIFF QTDIFF is an external function that computes the difference in seconds between two quad times. The returned value is a long. If Time2 is greater than Time1, it returns a positive value. It takes two arguments: 1. STRING, giving the time1 string 2. STRING, giving the time2 string B.2.1.5 QTIME QTIME is an external string function which returns the current time. It does not take any arguments. B.2.1.6 QTDOW QTDOW is an external word function which returns the day of the week for a specific time. It takes one argument: 1. STRING, the quad time stamp from which to return the day of week Days are coded as: 0 Monday 1 Tuesday 2 Wednesday 3 Thursday 4 Friday 5 Saturday 6 Sunday PAGE B-9 BQTLIB BASIC+2 LIBRARY B.2.2 File information functions In order to get the extra information on files, they need to be opened in BASIC+2 adding the USEROPEN FINFO parameter. This al- lows BASIC+2 programs to access the last modification time, as well as the file protection of the last opened file. These functions also work on files opened over DECnet. B.2.2.1 FTIME FTIME is an external string function which returns the quad time of last modification for the last opened file. It takes no arguments. B.2.2.2 FPRO FPRO returns the file protection of the file as a longword. Only 16 bits are actually used, but using a longword allows the value to be treated as unsigned. B.2.3 User identification manipulation Sometimes there is a need to run a task as a specific user, and drop and regain privileges. B.2.3.1 BEPRIV BEPRIV enables the task privilege status, assuming it is allowed to do that. It also changes the protection UIC of the task to a specific UIC. It takes one argument. 1. WORD, the UIC to change to B.2.3.2 NOPRIV NOPRIV changes to a specific UIC and then drops task privileges. It takes one argument. 1. WORD, the UIC to change to PAGE B-10 BQTLIB BASIC+2 LIBRARY B.2.4 RAD50 functions B.2.4.1 TOR50 Convert ASCII to Radix50. Takes a string as an argument, where the string should be at least 3 characters, and converts the first three characters into a R50 word. Blanks are accepted in the input. No error checking is done. It takes one argument. 1. STRING, giving the three characters to convert. B.2.4.2 FMR50 Convert one R50 word into a string with three characters. The string must already have space for the three characters, and the first three characters of the string re replaced by the R50 ASCII characters. It takes two arguments. 1. WORD, the R50 value to convert. 2. STRING, where the result is placed. B.2.5 Subprocess functions This set of functions allow a BASIC+2 program to run another program and get output as well as feed input into that program. B.2.5.1 CRSUB X = CRSUB(lun,uic) Create a subprocess and possibly log it in. It takes two arguments. 1. WORD, a LUN to use for the subprocess communication 2. WORD, a UIC to use for the subprocess The function returns a word, which is the actual VT number the subprocess uses. It needs to be preserved and used in some other functions. If UIC is 0, the VT is not logged in, but instead is assumed to then run things with EXE, under the current UIC. PAGE B-11 BQTLIB BASIC+2 LIBRARY If the UIC is non-zero, the task needs to be privileged, in order to be able to log in the virtual terminal. B.2.5.2 CMD CALL CMD(id,CMD) Queue a command to MCR on the given VT number. It takes two arguments. 1. id, VT number (type WORD) 2. CMD, the command line to send to MCR (type STRING) B.2.5.3 EXE CALL EXE(id,EXE,CMD) Execute a specific command/task, with a given command line. It takes three arguments. 1. id, VT number (type WORD) 2. EXE, task name string (type STRING) 3. CMD, command line string to invoke the task (type STRING) B.2.5.4 WAITS X = WAITS Wait for subprocess event. The returned value will indicate what event(s) have happened. It is a bit-encoded value. SUBP_WRITE (1) - Subprocess has written data, please read it. SUBP_READ (2) - Subprocess is reading data, please provide data. SUBP_EXIT (4) - Subprocess task has exited. SUBP_ERR (8) - Subprocess has an error exit status. The SUBP_ERR bit should only be checked after SUBP_EXIT has been detected, as it is not meaningful before the task has exited. PAGE B-12 BQTLIB BASIC+2 LIBRARY B.2.5.5 GETLIN X = GETLIN(lun,str) Read a line from a subprocess. It takes two arguments. 1. lun, the LUN to read from (type WORD) 2. str, string where to place the line read (preallocated) (type STRING) The returned value (X) is the actual length of the string read. B.2.5.6 GETERL X = GETERL(lun,str) Read a line from a subprocess, and return an error completion to the subprocess write request. It takes two arguments. 1. lun, LUN to read from (type WORD) 2. str, string where to place the line read (preallocated) (type STRING) The returned value is the actual length of the string read (value of X). The error code for the subprocess is IE.DNR. B.2.5.7 PUTLIN CALL PUTLIN(lun,str) Writes a line to the subprocess. It takes two arguments. 1. lun, LUN to write string to (type WORD) 2. str, the line to write (type STRING) B.2.5.8 PUTEOF CALL PUTEOF(lun) PAGE B-13 BQTLIB BASIC+2 LIBRARY Sends an EOF to the subprocess. In the case where there is no more data to send, and the subprocess tries to read more, use PUTEOF to indicate that no more data is available. It takes one argument. 1. lun, LUN to send EOF on (type WORD). B.2.5.9 DLSUB CALL DLSUB(vt) Delete a subprocess. It takes one argument. 1. vt, VT number to delete (type WORD) B.2.5.10 GETESB X = GETESB Get the actual exit status of the last task that was run. This function can be used to find out more detail when WAITs have set SUBP_ERR. SUBP_ERR is set whenever the low 4 bits of the exit status of a task is greater than 1. B.2.6 Logical names These functions allow translation of logical names into strings. B.2.6.1 TRNSLT S = TRNSLT("logicalname") TRNSLT translates a logical name into its equivalent string. It returns the equivalent name as a string. It takes one argument. 1. "logicalname", a string giving the logical name to translate (type STRING) PAGE B-14 BQTLIB BASIC+2 LIBRARY B.2.7 Multiread These functions make it possible for BASIC+2 to read from several files simultaneously, in a way that resembles the use of the select() system call under UNIX/Linux. Currently it supports only reading from at most two channels at the same time. It works by doing parallel QIO$ calls to all channels, with IO.RLB. B.2.7.1 MINIT CALL MINIT(n,lun()) Initialize multi-I/O. It starts the read operation on all specified units. Unit 0 is a special case, which is assumed to be the owning terminal. It takes two arguments. 1. n, a count of how many LUNs to start reading from (type WORD) 2. lun(), an array of LUNs giving the actual LUNs to read from (type WORD ARRAY) B.2.7.2 MREAD L = MREAD(LEN,BUF) Reads from any of the LUNs previously set up with MINIT. It returns with the data from the first LUN which completes an I/O re- quest. It takes two arguments. 1. LEN, a variable into which the length read is stored (type WORD) 2. BUF, a preallocated buffer where to return the read string (type STRING) The function returns the LUN from which data was actually read, or -1 if some error occured. B.2.7.3 MEND CALL MEND Finish the I/O on all channels previously set up with MINIT. It takes no arguments. PAGE B-15 BQTLIB BASIC+2 LIBRARY B.2.7.4 MSG CALL MSG(string) Output a message on the terminal using IO.WAL!TF.WIR. It takes one argument. 1. string, the message to output (type STRING). B.3 PDP-11 C LIBRARY LB:[1,1]BQTC.OLB PDP11C$INCLUDE:BQTLIB.H PDP11C$INCLUDE:STAT.H B.3.1 Logical names These functions allow translation of logical names into strings. B.3.1.1 trnslt Translate logical name to equivalent string. If no transla- tion exists, returns an empty string. extern char *trnslt(char *lname, int table); Table inhibit mask (can be combination of the following): TRN_NOSYS Do not lookup in system table TRN_NOGRP Do not lookup in group table TRN_NOSES Do not lookup in session table TRN_NOTSK Do not lookup in task table B.3.1.2 define Define a logical name. extern int define(char *lname, char *ename, int table); Table: PAGE B-16 BQTLIB PDP-11 C LIBRARY TRN_SYS Define entry in system table TRN_GRP Define entry in group table TRN_SES Define entry in session table TRN_TSK Define entry in task table B.3.2 File information B.3.2.1 fstat int fstat(int fileno, struct stat *s); B.3.2.2 stat int stat(char *path, struct stat *s); B.3.2.3 umask mode_t umask(mode_t mode); Mode: S_IRWXS 0x000f S_IRSYS 0x0001 S_IWSYS 0x0002 S_IXSYS 0x0004 S_IDSYS 0x0008 S_IRWXU 0x00f0 S_IRUSR 0x0010 S_IWUSR 0x0020 S_IXUSR 0x0040 S_IDUSR 0x0080 S_IRWXG 0x0f00 S_IRGRP 0x0100 PAGE B-17 BQTLIB PDP-11 C LIBRARY S_IWGRP 0x0200 S_IXGRP 0x0400 S_IDGRP 0x0800 S_IRWXO 0xf000 S_IROTH 0x1000 S_IWOTH 0x2000 S_IXOTH 0x4000 S_IDOTH 0x8000 B.3.2.4 defmask void defmask(void); B.3.3 User information /* * Device structure. Holds device name in a way that matches * how various RSX libraries expect it. */ struct device { char nam[2]; unsigned char unit; unsigned char flags; }; typedef unsigned int mode_t; typedef unsigned int uid_t; typedef unsigned int gid_t; B.3.3.1 getuid Get uid of user. uid_t getuid(void); PAGE B-18 BQTLIB PDP-11 C LIBRARY B.3.3.2 getgid Get gid of user. gid_t getgid(void); B.3.3.3 getsid Get session id of user. char getsid(void); Pointer returned is to a statically allocated string. B.3.3.4 isprv True if terminal priv. int isprv(void); B.3.3.5 isco True if terminal is CO: int isco(void); B.3.3.6 username Get username. char *username(void); B.3.3.7 myuic Get protection UIC. unsigned int myuic(void); B.3.3.8 getterm Get own terminal. struct device *getterm(void); PAGE B-19 BQTLIB PDP-11 C LIBRARY B.3.4 Time zone handling B.3.4.1 tzset Set timezone. void tzset(void); B.3.5 String functions B.3.5.1 strcasecmp Compare two strings, ignoring case. int strcasecmp(char *s1, char *s2); B.3.5.2 strncasecmp Compare two strings with limit, ignoring case. int strncasecmp(char *s1, char *s2, int n); B.3.6 Quad time functions A quadtime is a time type that keeps time in 10ns increments since an epoch of 17-Nov-1858. B.3.6.1 qtnow Get current time. qtime_t *qtnow(qtime_t *); B.3.6.2 qtime Get current time. qtime_t *qtime(qtime_t *); PAGE B-20 BQTLIB PDP-11 C LIBRARY B.3.6.3 qtstr Get string from time. char *qtstr(qtime_t *t, int c); c is fields to include: QS_DATE Supress date QS_TIME Supress time QS_SEC Supress seconds QS_DOW Supress day of week QS_NOW String should be created from current time QS_GMT Time should be in GMT QS_TZ Time should include time zone QS_OFFSET Time should include TZ offset and time zone B.3.6.4 strqt Get time from string int strqt(qtime_t *qt, char *s); B.3.6.5 qtadd Add seconds to time qtime_t *qtadd(qtime_t *qt, long n); B.3.6.6 qtsub Sub seconds from time qtime_t *qtsub(qtime_t *qt, long n); PAGE B-21 BQTLIB PDP-11 C LIBRARY B.3.6.7 qtdiff Difference between two times in seconds long qtdiff(qtime_t *, qtime_t *); B.3.6.8 t2qt time_t to qtime_t qtime_t *t2qt(qtime_t *, time_t *); B.3.6.9 qt2t qtime_t to time_t time_t *qt2t(time_t *, qtime_t *); B.3.7 User account information Getting account information requires that a variable of the type "acnt_s" is provided to various functions. B.3.7.1 acnt Lookup account based on string. acnt_s *acnt(char *nam, char *pw, int *cnt); Returns a pointer to an account structure. Accounts are looked up based on the string nam, which might be a string with a UIC, last name, first initial and last name, session id, or direc- tory. pw is the password to do the matching on. cnt returns how many matches were found. If the number of matches is not 1, then the account structure should not be used. B.3.7.2 g_unam Get username after lookup. char *g_unam(acnt_s *, char *buf); PAGE B-22 BQTLIB PDP-11 C LIBRARY B.3.7.3 g_fnam Get first name after lookup. char *g_fnam(acnt_s *, char *buf); B.3.7.4 g_lnam Get last name after lookup. char *g_lnam(acnt_s *, char *buf); B.3.7.5 g_hdir Get home directory after lookup. char *g_hdir(acnt_s *, char *buf); B.3.7.6 g_uics Get UIC string after lookup. char *g_uics(acnt_s *, char *buf); B.3.7.7 g_guic Get UIC after lookup. unsigned int g_uic(acnt_s *); B.3.7.8 g_sid Get session ID after lookup. unsigned int g_sid(acnt_s *); B.3.7.9 g_uflg Get account flags. int g_uflg(acnt_s *); PAGE B-23 BQTLIB PDP-11 C LIBRARY B.3.7.10 g_net Check if network login allowed. int g_net(acnt_s *); B.3.8 System calls B.3.8.1 RCVDW Receive data with timeout int RCVDW(short *_task, short *_bufadr, short *_buflen, short *_tmo, short *_idsw); B.3.8.2 VSUN Variable send and unstop void VSUN(short *_task, short *_bufadr, short *_buflen, short *_efn, short *_ids); B.3.8.3 vread Read function using RSX QIO function. Similar to fgets, but handles things right also when other devices than TI: (for example VT). Returns non-zero on ok, and zero on eof. int vread(int lun, char *buf, int bfsiz); B.3.9 Error information B.3.9.1 rsxerr Get error string for error char * rsxerr(char *buf, int err, int flg, int typ); Types: ETYP_SYS System call PAGE B-24 BQTLIB PDP-11 C LIBRARY ETYP_IO IO ETYP_RMS RMS ETYP_BP2 BASIC+2 ETYP_NET DECnet ETYP_NRJ DECnet network rejection ETYP_C PDP-C Type (what to include, mask): EFLAG_TXT Text message EFLAG_ID ID EFLAG_SEV Severity EFLAG_FAC Facility Page B-25 APPENDIX C RSX SPECIAL INFORMATION This appendix describes special issues or problems that could be relevant for TCP/IP in relation to RSX (specifically RSX11M+ V4.6). C.1 ETHERNET HANGS FOR Q-BUS SYSTEMS WITH DECNET There is a firmware "bug" in the DELQA (and possibly DEQNA) controllers, which might cause the receive side of Ethernet to stop working. The reason for this is that if the buffers used for the DELQA are less than 1500 bytes, the DELQA firmware will use several buffers if large enough Ethernet frames are received. However, if there are not enough buffers free to receive the whole Ethernet packet, the controller will receive the first (several) fragments, but will then drop the final fragments, as it has run out of buffers to store the last fragments in. But in this case, the receiver also will not generate any interrupt, as it only generates the interrupt when the last fragment is received. The result of this is that the receiver stops receiving packets, and the driver is also not aware of the situation, and will not even read out already received packets, so no more free space is cleared out in the receive ring. This is documented behavior of the DELQA, and DECnet does not hit this problem, as the buffers set up by DECnet are large enough that they always will fit within one buffer. TCP/IP, however, normally uses a MTU of 1500 bytes on Ethernet, which is larger than the default for DECnet, which usually uses a maximum buffer size of 576 bytes. There are two solutions to this problem: 1. Increase buffer size to 1498 bytes Changing the DECnet configuration to actually use 1498 byte buffers allows the full IP packets to fit into a single DELQA buffer, and the problem then cannot occur. This can only be done in CFE, so any changes will only take effect after DECnet has restarted. The following commands in CFE will set the parameters correctly so that TCP/IP packets also fit within a single buffer. CFE> DEF SYSTEM LARGE BUFFER SIZE 1498 CFE> DEF EXEC SEGMENT BUFFER SIZE 576 The potential problem with this solution is that it also affects DECnet protocols. Some link layer handling PAGE C-1 RSX SPECIAL INFORMATION ETHERNET HANGS FOR Q-BUS SYSTEMS WITH DECNET in DECnet (in RSX) is based on the large buffer size, and if this don't match the segment buffer size, some systems can have problems establishing circuits. This has been observed with VMS in the same area when using DDCMP lines (Multinet over IP links are DDCMP lines). Note that you should not specify exactly 1500 bytes for the buffer size. If you do, DECnet link layer han- dling will actually use 1502 byte packets, since DECnet adds a 2 byte size field to any data in DECnet protocols. However, 1498 is enough to allow IP to use an MTU of 1500 without getting packets split into multiple buffers, as the DECnet packet layer adds 32 extra bytes to buffers to accomodate for interface overhead, so there is in fact room for 1530 bytes in one buffer if the buffer size specified is 1498. 2. Reduce the interface MTU The obvious other solution is to change the MTU of the interface in TCP/IP. The command to do this is simple: IFC> SET IFn: MTU 576 The problem with this is that it mainly affect outgo- ing packets, while the problem is on incoming packets. However, TCP declares MSS based on interface MTU, so for TCP traffic, this will help avoid the problem. But if you have lots of UDP traffic with large packets, the problem can still appear. To make it clear, changing the MTU does not prevent TCP/IP from receiving larger packets. It will still ac- cept up to 1500 byte packets, which is the limit on ethernet itself. C.2 MODERN ETHERNET CONTROLLERS AND EMULATED PDP-11S Modern Ethernet controllers have lots of features and func- tions to improve network performance. Unfortunately, a few of them will actually cause problems when used for a simulated PDP-11. This is not specifically an RSX problem. One feature in particular that can cause problems is TCP segment offloading. This hardware feature essentially means that upon receiving TCP packets, the Ethernet controller can actually gather several received packets, and coalesce them into one larger received packet for the network stack. In short, the controller repacks the received data into one, single larger IP packet that can exceed the MTU of the inter- face. When this happens with an emulated PDP-11, the Ethernet inter- face will see large packets, which a real DEC Ethernet controller PAGE C-2 RSX SPECIAL INFORMATION MODERN ETHERNET CONTROLLERS AND EMULATED PDP-11S would never accept. These appear the same as jumbo packets. Such packets will be silently dropped by the controller and this means that it appears as if you have lots of lost packets on an inter- face. TCP will eventually back down enough that packets get through, but the data rates are going to be ridicuously low. Under Linux, this can be solved by using the ethtool program to turn off tcp packet segment offloading. For example, ethtool -K eth1 tso off ufo off gro off lro off gso off would be an example of how to use this tool to turn off TCP segment offloading on eth1. (This command example actually turns off TCP segmentation offload, UDP fragmentation offload, generic receive offload, large receive offload and generic segmentation of- fload.) C.3 TCP/IP WITHOUT DECNET In many cases, a system will have both TCP/IP and DECnet, and they may co-exist. For this to work correctly, DECnet must be started before TCP/IP, and TCP/IP then uses the DECnet facilities to access Ethernet. This means that any Ethernet interface that DECnet works on is also possible to use from BQTCP/IP. If BQTCP/IP is going to run without DECnet, you need a device driver for the specific Ethernet controller installed in RSX, and that device driver must work in a similar way to the DECnet inter- face. For Unibus machines, there is such a device driver called XE:. If the XE: device driver is installed in the RSX system, and no DECnet is running, BQTCP/IP will detect this, and use the XE: device driver instead. No configuration change is needed. There is one known problem with the XE: device driver. It limits packets to 1498 bytes in size, since it reserves two bytes of the payload for an optional size field. TCP/IP does not use such a size field, but normally expects the MTU of Ethernet to be 1500, so the XE: device driver should be patched if it is to be used with TCP/IP. In LB:[11,10]XEDRV.MAC, locate the lines: ; ; Maximum transmit buffer size ; ; 1518.- ; XMTBSZ = 1518.-<6+6+2+2+4> ; Maximum transmit buffer size and remove one "+2" from that line. Then rebuild the driver, and all should be good. PAGE C-3 RSX SPECIAL INFORMATION TCP/IP WITHOUT DECNET BQTCP/IP should also be able to detect this problem, and back down the MTU of the interface, but this has not been properly tested and should be considered experimental for the time being. C.3.1 Performance issues with the XE: device driver There is a potential performance problem with the XE: device driver. This device driver only has about 5 Kbyte available for re- ceive buffers. BQTCP/IP can push data through at a fairly high rate, and this can overflow the receive buffers of the XE: device driver quite easily. If that happens, TCP will recover through timeouts, but such recovery means the average transfer rates drop significantly. If a system is useing the XE: device driver, and are noticing a very slow transfer rate on FTP for example, it will probably im- prove the situation significantly to actually reduce the size of the receive buffers for TCP connections, as that will reduce the number of packets a sending host can send to the receiver without getting window updates in between. The command for changing the size of the receive buffers is IFC> SET TCP DEFAULT RECEIVER BUFFER SIZE n IFC> SET TCP MAXIMUM RECEIVER BUFFER SIZE n Here n is recommended to be a multiple of 1460, and a value of 2920, 4380 or 5840 is probably the most optimal. Any such performance issues are only releated to receiving data. The XE: device driver has no problems in transmitting large amounts of data at a high rate. However, reducing the size of the receive buffer will have an additional impact on TCP performance, because TCP will try to use an MSS that allows up to four packets in flight. If the buffer size is 2920, the MSS will be 730, which means a lot more packets needs to be sent/received to transfer a specific amount of data. From that point of view, a larger buffer size is desireable. Experimentation is the best suggestion here. You want as large buffer as you can have without starting to get a lot of lost packets because of XE driver buffer overflow. Check transfer rates, packets received out of order, and other counters also on the sending side to detect if packets sent to your RSX host are suffering from severe packet loss. PAGE C-4 RSX SPECIAL INFORMATION DECNET OVER IP WITH A DECNET ENDNODE C.4 DECNET OVER IP WITH A DECNET ENDNODE This is possible to do in two ways. The thing to remember is that when BQTCP/IP is started it tries to communicate with the Ethernet device. It first tries using DECnet, and then the XE: device driver. If BQTCP/IP is started before DECnet, then BQTCP/IP will use the XE: device to communicate over Ethernet. If DECnet is started after that, and is an endnode with only the IP line, it should work using this line. It is also possible to have both DECnet with Ethernet and IP lines installed, and running as an endnode, and let BQTCP/IP com- municate over Ethernet, while DECnet only uses the IP line. This requires that the Ethernet circuit is not enabled in DECnet, but the Ethernet line is running. C.5 DETAILS ON FILE FORMATS AND HTTP AND FTP The web server can serve both HTTP/1.0 and HTTP/1.1. With HTTP/1.1, the web server also tries to figure out the file size for files. Since HTTP requires the file size to be absolutely correct, this can be costly with some file formats in RSX. More specifi- cally, files with variable record size cannot easily be computed, so the web server has to read through the file twice; once to find the actual file size, and a second time to actually send the file. However, fixed length record size file can be computed much faster. So, where possible, you should use fixed record length files, especially for large files. The same is also true for FTP, where there is a command SIZE, which should report the actual size of the file as it will be transferred over the network. In order to find the size for vari- able length record files, FTP then also have to read the whole file to compute this size. C.5.1 File formats There are some file formats commonly used that work well even if there is trailing random data at the end of the file. Such files can be stored as fixed record length files on RSX, even though that means some random data (padding) will be added. The recommendation, if you store such files in RSX, is to transfer them using FTP in BLOCK mode to the RSX system. File types that are known to have this propery are: o JPEG PAGE C-5 RSX SPECIAL INFORMATION DETAILS ON FILE FORMATS AND HTTP AND FTP o PDF C.6 RSX PATCHES RSX is a very mature system, and most issues have long been solved. However, once in a while, a bug pops up, or some new way of using RSX unearthes issues that have not been seen before. For this reason, BQTCP now also includes, as an optional step, some patches to RSX, where this is of general interest, or specifi- cally affects BQTCP. C.6.1 MCR/MCD patches There has been for a long time a latent bug in MCR/MCD which almost never gets triggered, and has to do with the situation where an IP11, IS, or ICR/ICR subsystem is installed in RSX. When any of these devices exists in RSX, the MCR REMOVE command calls the cor- responding device driver to also remove the task being removed from the device driver database. The problem is that this is done in a way that was broken many years ago, but is usually never found as the occurence of these devices is close to zero at this time. However, the IP11 device driver is called IP:, just like the IP device driver in BQTCP. So when BQTCP is installed, MCR thinks that there is an IP11, and tries to deregister any task removed. But since this code is very broken, the actions of MCR will instead actually corrupt the pool. BQTCP now ships with a new version of MCR/MCD, which optionally can be installed as a part of the BQTCP installation. This new version removes the functionality from the REMOVE command to deregister tasks from these devices. If anyone actually has any of these devices, be aware that RSX currently is broken, and that the BQTCP installation removes the bug in MCR, but instead potentially can cause an issue with these devices, if installed tasks have registered with the device, and then are REMOVED. If this ever is a problem for anyone, please contact me (Johnny Billquist) about potential solutions. Additional fixes included in this updated version of MCR are: 1. Correct SET /INQUIRE response parsing. 2. Bugfix for CBD /ALL command that can crash the system. 3. Improved output of the CBD command. 4. Bugfix for TAS command LBN printout. 5. Improve how ACD command sets up ACD commons. PAGE C-6 RSX SPECIAL INFORMATION RSX PATCHES 6. Improved ASN/DFL command to allow users to display logical names. 7. Allow the DISCONNECT command as a command on terminals not logged in. 8. Improved terminal type output from DEV command. 9. Change SET /NOPAR to a privileged command. 10. Correct CLQ time output. 11. Ability to show the remote end of LAT and telnet termi- nals. (This depends on patches also being applied to the terminal driver) 12. Adjustet format for DEV /LOG output. The files changed for these patches are: 1. MCR.TSK (08.35) 2. MCD.TSK (08.00) Just copy MCR.TSK and MCD.TSK into [3,54]. MCR can be removed and reinstalled on the running system, meaning the changes take ef- fect immediately. However, to make the changes permanent, and also install the patched MCD, the files needs to be installed into the system image using VMR. C.6.2 DCL patches The changes to MCR means that there are also some changes to some DCL commands. So a patched version of DCL is also provided. The files changed for these patches are: 1. DCL.TSK (06.01) Just copy DCL.TSK into [3,54] and install it. To make the change permanent, use VMR to install it into the system image. C.6.3 ACNT, PSW and SYSLOG patches ACNT is the program to handle accounts in RSX, and PSW is the program used by non-privileged users to change their own password. PAGE C-7 RSX SPECIAL INFORMATION RSX PATCHES The patches to these programs implement a new account attri- bute, which is whether the user is allowed to change his password or not. The patch also contains an Y2K fix published by Mentec. SYSLOG is a program that tracks resource accounting. Among other things, it also record the idle time for terminals. The patched version included here adds idle counting also for terminals that do not have a time limit, which allows for seeing how long any terminal have been idle. The ACNT/PSW patches can be installed by copying the following files into LB:[3,54]: 1. ACNTFSL.TSK (06.10) 2. PSWRES.TSK (03.03) 3. SYLRES.TSK (04.04) After copying the files over, VMR should be used to remove the old installed tasks, and install the new versions instead. The tasks can also be removed and reinstalled on the running system, meaning the changes take effect immediately. C.6.4 TT: patches The RSX terminal driver is probably the most complex device driver there is for RSX. As such, applying patches are not always simple. BQTCP contains a couple of patches/improvements to the TT: driver. These enable a couple of more attributes for terminals, as well as adding functionality to read out the connection of remote LAT and telnet terminals using the SF.GMC function with the TC.MAP subfunction. It also provides additional information to user ports hooked in to the TT: driver. The files included for these patches are: 1. TTSYM.MAC 2. UCBDF.MAC 3. TTATT.MAC (06.19) 4. TTDAT.MAC (06.13) 5. TTUS.MAC (01.10) PAGE C-8 RSX SPECIAL INFORMATION RSX PATCHES In order to apply these patches, the following steps are required: 1. Insert new symbols for the terminal functions in RSXMAC LBR LB:[1,1]RSXMAC.SML/RP=TTSYM.MAC 2. Insert new symbols in the UCB definitions in EXEMC LBR LB:[1,1]EXEMC.MLB/RP=UCBDF.MAC 3. Copy the new versions of TTATT, TTDAT and TTUS PIP LB:[11,10]/NV=TTATT.MAC,TTDAT.MAC,TTUS.MAC 4. Compile the new files MAC [11,24]TTATT,[11,34]TTATT=- [1,1]EXEMC/ML,[11,10]RSXMC,TTMAC,TTATT MAC [11,24]TTDAT,[11,34]TTDAT=- [1,1]EXEMC/ML,[11,10]RSXMC,TTMAC,TTATT MAC [11,24]TTUS,[11,34]TTUS=- [1,1]EXEMC/ML,[11,10]RSXMC,TTMAC,TTUS 5. Insert the new files into the terminal driver library LBR [1,24]TTDRV/RP=[11,24]TTATT,TTDAT,TTUS 6. Rebuild the terminal driver TKB @[200,200]TTDRVBLD 7. Generate a new system image using VMR (This is an example, your setup might require differ- ences to these commands) SET /DEF=[1,54] INS $VMR PIP RSX11M.SYS/NV/CO/BL:2050.=RSX11M.TSK VMR @SYSVMR 8. Boot and save the new system C.6.5 RMS patches Fixes to RMS solves: 1. Correct error in DAP library which cause file protection returned to be incorrect. 2. Adds missing DAPSLX.ODL PAGE C-9 RSX SPECIAL INFORMATION RSX PATCHES The RMS patches can be installed by copying the following files into LB:[1,1]: 1. DAPSLX.ODL 2. DAPRES.TSK 3. DAPRES.STB 4. RMSDAP.OLB C.6.6 LAT patches Fixes to LAT includes: 1. Added capability to read out remote end for interactive LAT terminal 2. Correct a memory leak in LAT which under special circum- stances cause large buffers to be permanently lost. In order to apply these fixes, copy the following files to your NETUIC, and reboot the system. 1. LAT.TSK 2. LAT.STB 3. LAT1.TSK 4. LAT1.STB C.6.7 DECnet patches C.6.7.1 Functional problems There are several components in DECnet with smaller bugs in them, that have been fixed. Here is a short summary: o NMVACP When requested to give a larher list of nodes, it could miss giving some out, because it didn't properly handle if some nodes only existed in the current running database. This could happen just becase a node was online and did some communication without having a nodename. o NTDEMO When listing nodes without a nodename, NTDEMO should show the node number, but because of a bug it just showed some random number instead. PAGE C-10 RSX SPECIAL INFORMATION RSX PATCHES o EPM The ethernet protocol manager didn't properly handle if there were multiple requests for adding the same ethernet multicast address. C.6.7.2 DECnet performance DECnet have performance problems when a really fast machine sends packets to a really slow machine. If the amount and size of buffers announced by the receiving machine is large (such as done by NFT and FAL), performance can go down to almost zero. The reason for this is that RSX do DECnet flow control on a per buffer basis, and not on a per packet basis. Which means that potentially several packets can be sent within the context of one buffer, which is the granularity of the flow control. In addition, DECnet by default only buffers up to 3 packets on the receive queue for a DECnet connection. So in extreme cases, lots of packets gets dropped, and retransmissions also have problems, so the timeouts increase to high numbers, and transfer rates drop. The simple solution is to just allow more packets to be buf- fered for a connection. BQTCP includes a modified ECL module, which is where this is controller. The limit have been lifted to 10 packets, which makes all tested programs work nicely. Any user can easily do this modification themselves as well, as this is a parameter controlled from the build file for ECL, which is processed during the NETGEN. The files affected, and to be installed in NETUIC are: 1. ECL.TSK 2. ECL.STB C.6.8 Automated process to install some of the patches BQTCP comes with a function to install most patches auotma- tically on a system. All patches not requiring a full SYSGEN can be installed with this procedure, and all that is required after- wards is a reboot. Patches not installed by the automated procedure: 1. TTDRV patches To invoke the automated patch procedure, simply run: PAGE C-11 RSX SPECIAL INFORMATION RSX PATCHES @[IP]IPGEN PATCH Page C-12 APPENDIX D TCP/IP PERFORMANCE TUNING This appendix tries to go through various aspects of the BQTCP/IP implementation with a viewpoint on performance, and how both configuration and program implementation can affect the per- formance of the network communications. Performance of TCP/IP is a rather complex topic, in which many different subsystems interact, and together they give the perceived performance of the system. Because of this, it can be very diffi- cult to understand which part is performing less than optimally, and where to change things when performance is less than expected. It can also be hard to understand what the actual performance should be. Performance is also complex because it has more than one dimension. Time (speed) is one aspect. Memory usage is another. D.1 DECNET COUNTERS DECnet keep several counters which can help detect potential bottlenecks. D.1.1 System counters The system counters are primarily telling if DECnet didn't have buffers. As any sent or received packet will also use DECnet buffers along the way, buffer allocation failures here would sug- gest that DECnet needs to be configured to have more buffers. D.1.2 Line counters The line counters tell about what is going on for a specific line. Most interesting counters here would be failure counters, as well as unrecognized frame destination, data overrun or buffer un- available. For some of those counters, remedies would be to increase buffers in DECnet, while for some, the number of outstanding re- ceives on the interface in BQTCP would the value to look at. PAGE D-1 TCP/IP PERFORMANCE TUNING ETHERNET INTERFACES D.2 ETHERNET INTERFACES Ethernet interfaces under RSX are able to do the basic func- tions of transmit and receive frames. However, they do not provide any buffering of received frames. If there is no outstanding read for the fram received, it is immediately discarded. In order for BQTCP to operate, it therefor have a number of outstanding receives always queued for the ethernet interface. The number of outstanding receives have impacts both on net- work performance and on memory use - both in IPPOOL and system pool. Each outstanding receive is an outstanding QIO request, which consumes some amount of system pool memory. This is not huge but it could be relevant on a system that do not have much free system pool to start with. Each outstanding receive also requires space in IPPOOL for one full sized ethernet packet, which is 1500 bytes. So the amount of memory consumed in IPPOOL is noticeable, but perhaps usually not critical. But do pay attention to if IPPOOL is getting full, and you get allocation failures in there. A related parameter that is important to this is the TCP tun- ing parameter "receive buffer size", because this affects how much data a remote TCP connection can send without getting an ack- nowledgement. The larger this value is, the more packets can come in rapid succession on a single socket. And that can be an issue if you do not have enough outstanding receives as some of the re- ceived packets might then get dropped. When the number of outstanding receives are changed, default values for the TCP receive and transmit buffer sizes are also com- puted and set. Things to look out for here are if you are seeing lots of packets out of order on reception, which would suggest that some packets are dropped. Also, line counters in DECnet for the cor- responding line have a counter for data overrun, which could be an indication that packets were dropped. D.3 ARP All communication (except broadcasts) on Ethernet need the ARP layer in order to actually send any packets out. The ARP layer is responsible for translating IP addresses to Ethernet MAC addresses. This translation is done for only the next hop for any communica- tion. As such, ARP has no understanding or involvement in end to end communication between machines that pass through intermediate IP gateways. PAGE D-2 TCP/IP PERFORMANCE TUNING ARP However, for communication over the local link layer, ARP always first needs to know how do translate the IP address to the Ethernet MAC address. In order to do this, ARP has a cache of MAC addresses, so that it does not have to do a full ARP resolve tran- saction over the Ethernet for every packet to be sent. ARP does the address translation. If the MAC address is in the cache, ARP can immediately provide this and no time is lost. However, if the required translation is not in the cache, the ARP layer needs to save the outgoing packet, while it tries to find the destination MAC address. All subsequent packets for the same next hop will also be saved while the ARP resoltion is in progress. This both takes memory and introduces a delay in communication. The translation/address resolution is done between the ARP modules on all machines attached to the Ethernet. One machine wants to send a packet, and thus needs to find the correct MAC ad- dress in order to be able to do the transmission. So the ARP mod- ule of that machine broadcasts an ARP request, saying that it wants to find the MAC (address) for a specific IP address. The machine that has this IP address will respond to the ARP request with an ARP response containing the corresponding MAC address. The response is only sent back to the machine that issued the ARP re- quest. This is possible since the ARP "packet" will have the source MAC as part of the header. If the machine sending the ARP request does not receive an ARP reply, it will retransmit the ARP request. All machines that receive the ARP request will also store the IP address and MAC address of the requestor in their caches, mean- ing that if any other machine wants to communicate with the transmitter of an ARP request they can do so right away as the nec- cesary information is already in the cache. The machine that the ARP request is addressed to will create the ARP reply. The addressed machine will also store the reques- tors translation in the local cache, so that if the actual packet to be sent results in a response packet being sent back, that machine has the address translation already in the cache. The machine that sent the original ARP request will, upon re- ceiving the ARP reply, store the translation in its ARP cache, and proceed to send the original packet now that there is an address translation from the IP address to an Ethernet MAC address. As the ARP request is a broadcast message, every machine on the same Ethernet segment will need to receive and process this message causing some general load on all machines every time an ARP request is sent. However, there is little to do unless the re- ceiver is the intended destination other than creating the ARP cache entries. PAGE D-3 TCP/IP PERFORMANCE TUNING ARP D.3.1 Timeout The ARP timeout defines how long a translation/MAC address can stay in the ARP cache after it has been created/updated. If new or updated information is received, the cache can be updated, and the timeout reset again. D.3.2 Retries If the ARP request does not result in a received ARP reply, the retry parameter defines how many times the ARP request should be sent before the destination should be declared as unreachable. D.3.3 Retry timeout When the ARP request is sent out, the requestor will wait for a specific time for an ARP reply to be received before retransmit- ting the ARP request. D.3.4 Unresolved timeout Once an IP address have been declared as unreachable, this is also stored in the ARP cache. The unresolved timeout specifies how long this entry remains in the ARP cache. Any attempts to communi- cate with that IP address during this timeout will immediately result in an error status being returned stating that the remote address is unreachable. Once the timeout has expired, any new attempt to communicate with that remote IP address will once more initiate the ARP request transaction. D.3.5 Summary Given the parameters described above, performance is affected by how long cache entries remain valid. The longer they remain valid, the less often ARP request/response exchanges are needed be- fore the actual data packets can be sent. However, the drawback of a long cache timeout is that if a system/interface were to change the MAC address, communication will not work until either the cache entry has timed out, or if the remote machine sends out an ARP re- quest causing the local ARP cache to be updated (or the cache entry is deleted manually). If a remote machine is down, then the number of retries as well as the timeout value affect how long before programs get in- formed that the communication cannot be established. PAGE D-4 TCP/IP PERFORMANCE TUNING ARP In addition, if a remote machine is down, the memory asso- ciated with the request is kept allocated until the ARP request times out, and all retries have been completed. Only after this is the memory released. And this is the memory for all packets to that destination, not only the first packet. D.4 IP There is very little to adjust at the IP level. Most programs never communicate directly, using IP. Most of the time, the only user of IP is UDP and TCP. However, PING, for example, is a pro- gram that communicates directly over IP. Performance wise, IP has one aspect that is good to be aware of, and that is packet size. IP (under BQTCP) can deal with packets up to 8000 bytes. However, if a packet is larger than the maximum transmission unit (MTU) of an interface, IP needs to fragment the packet into smaller parts that can be sent over the interface. This causes some extra overhead in that the packet needs to be reassembled at the receiving end. Individual fragments can be lost, which will cause the whole packet to be lost, as it can only be processed if all fragments are received. The fragment reassembly means that packets are kept in memory while the different fragments are received. This comes with a timeout, so that if too long a time passes without all fragments being received, all fragments will eventually be dropped. But this can cause both delays and memory usage, and is also the same for higher levels in the stack. D.5 UDP UDP is a protocol with very low overhead and very little func- tionality. Thus, there is not much that UDP does that affects per- formance. UDP has no configuration parameters to deal with. However, applications can potentially affect the performance based on how they use UDP. The size of packets to be sent affects performance based on the facts mentioned in the section on IP. Both IP and UDP also add some overhead to packets. IP has an overhead of 20 bytes, and UDP adds 8 bytes. So if an interface has an MTU of 1500 bytes, then a UDP packet with more than 1472 bytes will force IP to fragment the packet, with the ad- ded potential risks of packets not being received, and the time for splitting and reassembling the packets. PAGE D-5 TCP/IP PERFORMANCE TUNING TCP D.6 TCP TCP is a rather complex protocol, with a lot of functionality. Because of this, there is also more parameters that can be modified that may affect performance. D.6.1 Minimum transmit timeout The minimum transmit timeout sets a lower limit on the timeout before a packet is retransmitted if no acknowledgement is received. A short time is good in case the packet is lost since the ear- lier a lost packet may be retransmitted. However, a short timeout can accidentally cause a retransmit for a packet that was suc- cessfully transmitted, meaning an unneccesary retransmit, and du- plicated bytes being transmitted. If the network statistics counters indicate lots of re- transmits because of timeouts, then it might be that this timeout is too short. However, if lengthening the minimum transmit timeout does not reduce the rate of retransmits, then the problem is not that the minimum time is too short, and you can safely reduce this number. And this will, in turn improve efficiency, since lost packets will be retransmitted faster. While data is being transmitted, but have not yet have been acknowledged, the data still uses memory. If the minimum re- transmit time is high, it is likely that memory usage will be slightly higher on average, since lost packets will take a longer time before being retransmitted, and subsequently acknowledged. Only when the acknowledge has been received will the memory be released. D.6.2 Timeout wait period When a connection is closed, it will linger around for some time so that no accidental traffic could be confused between an old connection and a new connection. However, such lingering connec- tions use some memory. The timeout wait period defines how long such connections stay around. D.6.3 Transmit buffer size The transmit buffer size controls how much data an application can write to TCP, which TCP will buffer internally until it has been successfully transmitted. If this buffer is full, the appli- cation cannot write any more data, and the I/O requests will not complete. PAGE D-6 TCP/IP PERFORMANCE TUNING TCP The more data that can be buffered thus means the application can continue running and producing more data before blocking. More data ready to transmit means TCP can more efficiently deal with the data. However, the more data that can be buffered means the more memory used. Any application can change this value at runtime. However, there is a default value that is used when a connection is established. There is also a max value that applications cannot exceed. D.6.4 Receive buffer size The receive buffer size tells how much data TCP can receive for a socket before the remote side has to stop transmitting. Larger buffers mean more data can be received without blocking the remote end. And this means the remote end can continue producing data, prepareing it, and sending it over in an efficient manner that the receiving end can read and process when it wants to. But a larger receive buffer size means that more memory can be allocated by the connection. Any application can change this value at runtime. However, there is a default value that is used when a connection is established. There is also a maximum value that applications can- not exceed. D.6.5 Transmit segment size The transmit segment size controls how large a chunk of memory may be allocated by transmission to hold the data produced by the application. For each chunk, there is some overhead, so larger chunks means there is less overhead per byte. However, if the amount of data to transmit is usually small, then a larger transmit segment means a lot of memory allocated which are never used, and thus the memory efficiency lowers. If more data is produced than can fit in one segment, addi- tional segments are chained together, up to the maximum transmit buffer size. Any application can change this value at runtime. However, there is a default value that is used when a connection is established. There is also a maximum value that applications can- not exceed. PAGE D-7 TCP/IP PERFORMANCE TUNING DNS D.7 DNS Whenever any operation requires DNS lookups/translations, there is a potential delay for DNS resolution to be done. DNS uses a cache, so if a translation has recently been done, the results are reused without any new DNS resolution being performed. However, if DNS resolutions fail, there are timeouts, which can delay operations for a significant time. If connections are made towards explicit IP addresses, DNS resolution is never required, and such connections are therefore always faster and more predictable in time. As such, applications can try to keep DNS resolutions separate from explicit operations such as connection initiations. Page D-8 APPENDIX E UPDATING TCP/IP TCP/IP have been designed with an intent that updating should be simple, safe and straight forward. This appendix contains an example run of an update, as well as some general information about updating. E.1 EXAMPLE UPDATE This is an example of an update run of BQTCP/IP on an internet connected RSX system. >ftp mim.update.uu.se FTP V2.12 (c) 2014-2017 by Johnny Billquist Connecting to MIM.UPDATE.UU.SE... 220-============================================================= 220-Welcome. 220- 220-This is the ftp server at Mim.Update.UU.SE. 220- 220-This is a running RSX-11M-PLUS system. 220- 220-Contact Johnny Billquist (bqt@update.uu.se) for more informa- tion. 220-============================================================= 220 Welcome Username: ftp 230-+++++++++++++++++++++++++++++++++++++++++++++++ 230-This is the anonymous area for BQTCP for RSX. 230- 230-Note that BQTCP.TAP is an RSX virtual device 230-file, and can only be downloaded using the 230-RSX ftp client. 230- 230-Please contact bqt@update.uu.se if you have any questions. 230-+++++++++++++++++++++++++++++++++++++++++++++++ 230 Login successful. Remote system is RSX-11M-PLUS Switching to native mode! FTP>get bqtcp.tap 227 Entering passive mode. (130,238,19,212,250,67). 150 Sending file DU1:[FTP]BQTCP.TAP;939 Receiving file DU:[BQT]BQTCP.TAP;75 (Size 4.42 MB)... 100% 4.42 MB transferred in 32.02s (141 KB/s) 226 File done. FTP>^Z 221-Thank you for using this ftp service. Data traffic was 4.42 MB in 1 file. Total traffic was 4.42 MB in 1 transfer. 221 Closing connection. Connection closed. >vcp con bqtcp/tap VCP - Device VF0: (MU1:) has been assigned. PAGE E-1 UPDATING TCP/IP EXAMPLE UPDATE >mou mu1:/for >bru /bac:tcpip/noini/ufd/new mu1: du: BRU - Starting Tape 1 on MU1: BRU - End of Tape 1 on MU1: BRU - Completed >vcp dis mu1:/dmo DMO -- RT0: dismounted from MU1: *** Final dismount initiated *** >set /def=[ip] >@ipgen >; >; BQTCP/IP generation. X0.8 >; >; Started on 20-JAN-18 15:00:53 >; >* What is the device where the kit is [S D:"SY:"]: >SET /DEF=SY:[IP] >* Do you want to just update binaries? [Y/N D:Y]: >* Do you want to install the new HELP files? [Y/N D:N]: >* Do you want to install the new message files? [Y/N D:N]: >* Do you want to purge old files after generation? [Y/N D:Y]: >; >; Thank you. All questions have now been asked. >; >; >; Copy libraries >; >pip lb:[1,1]/nv=[lib]*.* >; >; Compiling and taskbuilding drivers >; >mac iftab=iftab >mac iptab=iptab >mac udtab=udtab >mac tctab=tctab >tkb @ifdrv >tkb @ipdrv >tkb @uddrv >tkb @tcdrv >; >; Copying drivers >; >pip lb:[1,54]/nv=[ip]ifdrv.tsk,.stb >pip lb:[1,54]/nv=[ip]ipdrv.tsk,.stb >pip lb:[1,54]/nv=[ip]uddrv.tsk,.stb >pip lb:[1,54]/nv=[ip]tcdrv.tsk,.stb >; >; Building TELNET common >; >TKB @TELCOM >; >; Copy basic tools >; >pip PAGE E-2 UPDATING TCP/IP EXAMPLE UPDATE lb:[ip]/nv=[ip]ifconfig.tsk,netstat,ping,tracert,ethacp,resacp,rmd >pip lb:[ip]/nv=[ip]dhcp.tsk,dhcpres,rwhod,tftpd,inetd,spoof,www,wwwres, ircbot >pip lb:[ip]/nv=[ip]ftpd.tsk,telnetd,telnet,tftp,irc,ircres,ftp,telcom,. stb >; >; Deleting old versions of files... >; >PIP LB:[1,54]IFDRV.*/PU,IPDRV.*,UDDRV.*,TCDRV.* >PIP LB:[1,1]IPMAC.MLB/PU,BQTMAC.MLB >PIP LB:[1,1]IPLIB.OLB/PU,IPBP2.OLB,IPC.OLB,IPF77.OLB >PIP LB:[1,1]BQTLIB.OLB/PU,BQTBP2.OLB,BQTC.OLB >PIP LB:[LIB]*.*/PU >PIP LB:[IP]*.*/PU >PIP LB:[IPAPPL]*.*/PU >PIP LB:[TELNETD]*.*/PU >PIP LB:[IPHLP]*.*/PU >PIP LB:[FTP]*.*/PU >PIP LB:[FTPD]*.*/PU >PIP LB:[MAILD]*.*/PU >PIP LB:[IPBP2]*.*/PU >PIP LB:[IPC]*.*/PU >PIP LB:[IPF77]*.*/PU >PIP LB:[DHCP]*.*/PU >PIP LB:[HTTP]*.*/PU >PIP LB:[HTTPD]*.*/PU >PIP LB:[CGIDEMO]*.*/PU >PIP LB:[INETD]*.*/PU >PIP LB:[IRCBOT]*.*/PU >PIP LB:[IRC]*.*/PU >PIP LB:[PCL]*.*/PU >PIP LB:[IPRMD]*.*/PU >PIP LB:[NTP]*.*/PU >PIP LB:[IPNET]*.*/PU >PIP LB:[MKE]*.*/PU >PIP LB:[IPEXAMPLE]*.*/PU >; >; Done >; >; Remember to add, change or update the information in LB:[1,2]HOSTS.TXT >; >; After DECnet has started (if DECnet is also installed on the machine), >; invokde [IP]IPINS.CMD to start TCP/IP. >; >; Edit [IP]IPAPPL.CMD, and invoke that at a later point in the >; startup, when all shared libraries and other requisits have been >; installed. >; >; Edit [IP]IPREM.CMD to customize the shutting down procedure, >; and remember to invoke this if needed from the standard shutup >; procedure. >; >SET /CLI=TI:MCR PAGE E-3 UPDATING TCP/IP EXAMPLE UPDATE >SET /DEF=[IP] >@ > E.2 FUTHER THINGS TO CONSIDER WHEN UPDATING TCP/IP In addition to running through the installation shown above, there are a couple of things to consider when doing an update. 1. The installation and startup scripts might have changed, so the new template files should be checked to see if there are any changes that should be done to the install and startup scripts used on the system. 2. The help files might have changed, in which case the new versions of those file should be installed. 3. The mail queue file might have changed, requiring that the mail queue file be reinitialized. In this situation, any pending mails to be delivered might be lost, so special care might need to be in place in order to know the ef- fects of an update. 4. The mail box file format might have changed requiring that a new mail box file be created. In this situation, the old mail box file is no longer accessible. So it might be a good idea to export any mails to a separate text file before doing the update. 5. Logical names for different subsystems might have changed, requiring that they be corrected before normal operation may be resumed on the new system. Page E-4 APPENDIX F FILES [LIB] The library files - IPMAC.MLB The IP macros library - IPLIB.OLB The IP object library - IPBP2.OLB The HLL library for BASIC+2 - IPC.OLB The HLL library for C - IPF77.OLB The HLL library for FORTRAN-77 - BQTMAC.MLB A library of random functions for MACRO-11 - BQTLIB.OBJ An object library companion to BQTMAC [IP] The basic IP subsystem [IPAPPL] Various IP applications [DHCP] The DHCP client sources [RWHOD] The RWHOD daemon and client sources [TELNETD] The TELNET server sources [FTP] The FTP client sources [FTPD] The FTP daemon sources [MAILD] The MAIL daemon sources [IPBP2] The BASIC+2 library sources [IPC] The C library sources [IPF77] The F77 library sources [INETD] The INETD server sources [HTTP] Support functions for the web server [HTTPD] The web server with sources [IRCBOT] The IRC robot sources [LPT] A LPT printer symbiont client with sources [NTP] The NTPDATE client with sources [IPNET] The files needed for DECnet over IP [IPRMD] Additional pages for RMD to support TCP [MKE] A tool for building programs. Supplied here, as some IP code uses this tool for building. [IPEXAMPLE] Various files from the TCP/IP development, which illustrates various interface bits, as well as being useful as templates if some specific functionality is wanted. [PATCHES] Files used for patching RSX-11M-PLUS itself. These files are not strictly a part of the BQTCP distribu- tion, but they provide a way of updating specific subsys- tems in RSX which might have bugs which affects how BQTCP works in general. Page F-1 APPENDIX G CREDITS I would like to just briefly mention a few people who have been very helpful in getting BQTCP/IP to the point where it is to- day. o Dave Carroll - for helping me out with a lot of details on RSX internals. o Brian McCarthy - for helping me out with how the RSX TT: device driver user port works. o Paul Konig - for helping me out with how DECnet over IP is done in Multinet. o Brian Schenkenberger - for providing information on the MAIL11 protocol. o Phil J. Fisher - for reviewing and improving the documen- tation. Page G-1