diff options
Diffstat (limited to 'contrib/bind/doc/notes/irp.txt')
| -rw-r--r-- | contrib/bind/doc/notes/irp.txt | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/contrib/bind/doc/notes/irp.txt b/contrib/bind/doc/notes/irp.txt new file mode 100644 index 0000000..f2b59e2 --- /dev/null +++ b/contrib/bind/doc/notes/irp.txt @@ -0,0 +1,521 @@ +IRP Commands + +This document describes version 1 of IRP. + +IRP is a text-based command/response protocol like NNTP or SMTP. + +1.0 Response types: textual and status. + +1.1 Textual responses + +Textual responses are sent after a status response which indicates the text +will follow. The text is a series of CR-LF terminated lines. On the last line a +single period ``.'' will appear. If a normal text line starts with a period +then this will be doubled before sending. + +There is no maximum line length for responses. Commands have a maximum line +length of 1024 characters. + +The lines that make up the transmitted data are divided into fields. The fields +are spearated by the colon character ``:'', except in one case (for host data) +where the at-sign ``@'' is used instead. Some fields, such as alias names for +hosts, can have multiple values, and these values are separated by commas. + +Most transmission of data requires no special character changes. The field +separators and subfield separators don't normally appear in the data. However +in one case they can (network names). So to avoid trouble, all ``special'' +characters found in any data fields are encoded in URL-encoding form. That is +they are replaced with the 3-character sequence ``%xx'', where xx is the +hexidecimal value of the ascii-code for the chatacter. i,e, ``:'' becomes +``%58'', ``,'' becomes ``%44'' and ``%'' becomes ``%37''. + +For version 1 of IRP the set of special characters for purposes of encoding, +is: + + `,', '%', ':', '@' + +In a couple cases (password structure and group structure), there may be +encrypted passwords as part of the data. If the client is a privileged user +that the server can verify (e.g. through the use of SunOS doors(2)), then the +encrypted password will be sent back to the client. If the client is not +privileged the password will be replaced with the string ``*''. + + +1.2 Status responses. + +Status responses follow a numbering pattern similar to NNTP. + + 1xx - Informative message + 2xx - Command ok + 3xx - Command ok so far, send the rest of it. + 4xx - Command was correct, but couldn't be performed for + some reason. + 5xx - Command unimplemented, or incorrect, or a serious + program error occurred. + + The next digit in the code indicates the function response category. + + x0x - Connection, setup, and miscellaneous messages + x1x - Host lookup + x2x - Network lookup + x3x - User lookup + x4x - Group lookup + x5x - Service lookup + x6x - Protocol lookup + x7x - Netgroup lookup + x8x - Misc. Information Lookup + x9x - Debugging output + + The final digit in the code indicates whether textual data follows + + xx0 - No textual data follows. + xx1 - Textual data follows. + +2.0 Connection Establishment + + When the client connects to the server, the server will issue a welcome + banner. If the server will accetp commands, then the banner will start with + a status code indicating this, followed by a version number of the protocol + it accepts. Other words may come on the line afterwards to indicate to + humans the state of the server, + + If the server wont accept commands then it will issue a banner indicating + that and will then drop the connection. + +2.1 Responses + + 200 1 Ready to go. ; note: The server handles version 1 of the protocol + 200 2 Ready ; note: The server handles version 2 of the protocol + 400 Sorry. Down to due to nightly backups. + +3.0 Commands + +3.1 The HOST commands + +3.1.1 GETHOSTBYNAME hostname +3.1.2 GETHOSTBYNAME2 hostname address-family +3.1.2 GETHOSTBYADDR address address-family +3.1.3 GETHOSTENT + + Returns a textual response containing the information for the given host(s) + (a struct hostent) encoded in an ascii format. gethostbyaddr and + gethostbyname look up a specific host. GETHOSTENT returns the contents + of the /etc/hosts file. The GETHOSTENT command is optional may not be + supported by the server. The address-family paramater is the value + "AF_INET" or "AF_INET6" + +{ XXX GETHOSTENT is optional as the gethostent(3) call isn't always available } + +3.1.4 Responses + + 210 No such host + 211 Host found + + If the hostname given as the command argument doesn't exist, then the 210 + response will be returned. If the host is successfully looked up, then the + 211 response is sent and a textual message is sent after. The textual + message contains the host information encoded in an ascii form. The fields + of the host data are separated by at-signs. Fields that have multiple values + (like the aliases field) have their sub values separated by commas. + + hostname@aliases@address-type@address-length@address-list@ + + - hostname is the FQDN of the host. + + - aliases is a comma separated list of FQDNs for the host aliases. + + - address-type is either the strings "AF_INET" or "AF_INET6" + + - address-length is the length of each address in bytes (after conversion + back to binary form). + + - address-list is a comma separated list of dotted IPv4 if IPv6 addresses. + +{ XXX if we're going to include TTLs where should they go? Perhaps the +address-list field should be "addr/ttl,addr/ttl,..." } + + For example: + + C: GETHOSTBYNAME gw.downtown.vix.com + + S: 210 No such host. + + C: GETHOSTBYNAME gw.home.vix.com + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + . + + C: GETHOSTBYNAME2 gw.home.vix.com AF_INET6 + gw.home.vix.com@@AF_INET6@ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255@ + . + + C: GETHOSTBYADDR 192.5.5.1 + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + . + + C: GETHOSTENT + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + data.pa.vix.com@@AF_INET@4@204.152.184.37@ + . + + +3.2 The USER commands. + +3.2.1 GETPWNAM username +3.2.2 GETPWUID uid +3.2.3 GETPWENT + + Returns a textual response with the user information (a struct passwd) + enocoded in an ascii format. The optional GETPWENT command transmits the + entire /etc/password file + +{ XXX It's optional only cause it doesn't seem right to spit the password out +to whoever wants it, even with encrypted passwords not being sent } + +3.2.4 Reponses + + 230 No such user + 231 User found + + If the username or uid given as the command argument doesn't exist, then + the 230 response will be returned. If the user is successfully looked up, + then the 231 response is sent and a textual message is sent after. The + textual message contains the user information encoded in an ascii form. The + fields of the user data are separated by colons. The format is very similar + to the /etc/password format (see passwd(5)) + + username:password:uid:gid:class:change:expire:gecos:home_dir:shell: + + - username is the user's login name + + - password User's encrypted password (or the string "*" if the client is + unprivileged) + + - uid User's numeric id. + + - gid User's numeric login group id. + + - class User's general classification (a string) + + - change Password change time (integer seconds from epoch) + + - expire Account expiration time (integer seconds from epoch) + + - gecos General information about the user. + + - home_dir User's home directory. + + - shell User's login shell. + + For example. Client being a non-privileged user: + + C: GETPWNAM brister + + S: 231 User found + brister:*:1364:100:James Brister:/udir/brister:/bin/csh: + . + + C: GETPWUID 6 + games:*:7:13:Games Pseudo-user:/usr/games:nologin + . + + S: GETPWENT + root:*:0:0:System Administrator:/root:/bin/csh + postmast:*:4:4:Postmaster:/:/nologin + daemon:*:1:1:System Daemon:/:nologin + sys:*:2:2:Operating System:/tmp:nologin + bin:*:3:7:BSDI Software:/usr/bsdi:nologin + operator:*:5:5:System Operator:/usr/opr:/bin/csh + uucp:*:6:6:UNIX-to-UNIX Copy:/var/spool/uucppublic:/usr/libexec/uucico + . + + If a priviled user looks up a username: + + C: GETPWNAM www + + S: 231 User found + www:WZajcgFCaAd8s:51:84::0:0:WWW-server:/var/www:/bin/sh + . + +3.3 The NETWORK commands + +3.3.1 GETNETBYNAME network +3.3.2 GETNETBYADDR dotted-ip-address address-family +3.3.4 GETNETENT + + Returns a textual response with the network information (an IRS struct + nwent, *not* a struct netent) enocoded in an ascii format. The optionally + supported GETNETENT command transmits the entire /etc/networks file + +{ XXX should it be optional? } + +3.2.4 Reponses + + 220 No such network + 221 Netork found + + If the network given as the command argument doesn't exist, then the 220 + response will be returned. If the network is successfully looked up, then + the 221 response is sent and a textual message is sent after. The textual + message contains the network information encoded in an ascii form. The fields + of the network data are separated by colons. + + network-name:aliases:address-type:address-length:network-address: + + - network-name is the name of the network + + - aliases is a comma separated list of aliases for the network + + - address-type is ``AF_INET'' or ``AF_INET6''. + + - address-length is the number of bits the following network address uses. + + - address is the network address in a dotted ascii format. AF_INET address + are padded with 0 bits to the full 32 bits before conversion to ascii for + transmission. AF_INET6 addresses are padded to the full 128 bits with 0 + bits before conversion. + + For example: + + C: GETNETBYNAME vixie-net + + S: 221 Network found + vixie-net::AF_INET:24:192.5.5.0: + . + + C: GETNETBYADDR 10.0.0.1 + + S: 221 Network found + private-net:home-net,upstairs-net:AF_INET:8:10.0.0.0: + . + + C: GETNETENT + + S: 221 OK + vixie-net::AF_INET:24:192.5.5.0: + private-net:home-net,upstairs-net:AF_INET:8:10.0.0.0: + lookback-net::AF_INET:8:127.0.0.0 + . + +3.4 The GROUP commands + +3.4.1 GETGRNAM group +3.4.2 GETGRGID gid +3.4.3 GETGRENT + + Returns a textual response with the group information (a struct group) + enocoded in an ascii format. The optionally supported GETGRENT command + transmits the entire /etc/group file. + +3.4.4 Reponses + + 240 No such group + 241 Group found + + If the group given as the command argument doesn't exist, then the 240 + response will be returned. If the group is successfully looked up, then + the 241 response is sent and a textual message is sent after. The textual + message contains the group information encoded in an ascii form. The fields + of the group data are separated by colons. + + group-name:group-password:group-gid:group-members: + + - group-name is the name of the group. + + - group-password is the group's password. This will be correct if the + client has appropriate privileges (see discussion above on the USER + commands). Otherwise it will be the string ``*'' + + - group-gid is the numeric id for the group + + - group-members is a comma separated list of usernames for all the members + of the group. + + For example: + + C: GETGRNAM wheel + + S: 241 Group found + wheel:*:0:root,brister,nathalie,tester: + + C: GETGRGID 20 + + S: 241 Group found + staff:*:20:root,brister: + + C: GETGRENT + + S: 241 OK + wheel:*:0:root,brister,nathalie,tester: + daemon:*:1:daemon: + kmem:*:2:root: + sys:*:3:root: + tty:*:4:root: + operator:*:5:root: + uucp:*:6:brister: + bin:*:7:: + news:*:8:brister: + utmp:*:12:: + games:*:13:: + mail:*:14:: + staff:*:20:root,brister: + . + +3.5 The SERVICE commands + +3.5.1 GETSERVBYNAME name protocol +3.5.2 GETSERVBYPORT port protocol +3.5.3 GETSERVENT + + Returns a textual response with the service information (a struct servent) + enocoded in an ascii format. The optionally supported GETSERVENT command + transmits the entire /etc/services file. + +3.5.4 Reponses + + 250 No such service + 251 Group found + + If the group given as the command argument doesn't exist, then the 250 + response will be returned. If the service is successfully looked up, then + the 251 response is sent and a textual message is sent after. The textual + message contains the service information encoded in an ascii form. The fields + of the service data are separated by colons. + + service-name:aliases:port-number:protocol: + + - The service name is the offical name of the services. + + - aliases is a comma separated list of aliases for the service. + + - port-number is the decimal number of the port used for the service. + + - protocol is the name of the protocol the service operates under. Usually + either ``TCP'' or ``UCP'' + + For example: + + C: GETSERVBYNAME nntp tcp + + S: 251 Service found + nntp:readnews,untp:119:tcp: + . + + C: GETSERVBYPORT 514 udp + syslog::514:ucp: + . + + C: GETSERVENT + 251 OK + tcpmux::1:tcp: + echo::7:tcp: + echo::7:udp: + discard:sink,null:9:tcp: + discard:sink,null:9:udp: + systat:users:11:tcp: + systat:users:11:udp: + daytime::13:tcp: + daytime::13:udp: + netstat::15:tcp: + qotd:quote:17:tcp: + qotd:quote:17:udp: + . + +3.6 The PROTOCOL commands + +3.6.1 GETPROTOBYNAME protocol-name +3.6.2 GETPROTOBYNUMBER protocol-number +3.6.3 GETPROTOENT + + Returns a textual response with the protocol information (a struct protoent) + enocoded in an ascii format. The optionally supported GETPROTOENT command + transmits the entire /etc/protocols file. + +3.6.4 Reponses + + 260 No such protocol + 261 Protocol found + + If the protocol given as the command argument doesn't exist, then the 260 + response will be returned. If the service is successfully looked up, then + the 261 response is sent and a textual message is sent after. The textual + message contains the protocol information encoded in an ascii form. The fields + of the protocol data are separated by colons. + + protocol-name:aliases:protocol-number: + + - protocol-name is the offical name of the protocol + + - aliases is a comma separated list of aliases for the protocol + + - protocol-nunber is the number of the protocol in decimal. + + + For example: + + C: GETPROTOBYNAME ip + + S: 261 Protocol found + ip:IP:0: + . + + C: GETPROTOBYNUMBER 17 + + S: 261 Protocol found + udp:UDP:17: + . + + C: GETPROTOENT + + S: 261 OK + ip:IP:0: + icmp:ICMP:1: + igmp:IGMP:2: + ggp:GGP:3: + tcp:TCP:6: + egp:EGP:8: + pup:PUP:12: + udp:UDP:17: + hmp:HMP:20: + xns-idp:XNS-IDP:22: + rdp:RDP:27: + iso-tp4:ISO-TP4:29: + iso-ip:ISO-IP:80: + encap:ENCAP:98: + . + +3.7 The NETGROUP commands + +3.7.1 GETNETGRENT netgrouup + + Returns a textual response with the netgroup information enocoded in an + ascii format. + +3.6.4 Reponses + + 270 No such netgroup + 271 Netgroups found + + For the given netgroup a list of the netgroup entries will be + returned. Each netgroup entry is three fields separated by colons. A field + may be empty to indicate wildcarding. + + :hostname:username:domainname: + + For example: + + C: GETNETGRENT devlopers + + S: 271 OK + :gw.home.vix.com:brister:vix.com: + :bb.rc.vix.com:vixie:: + . + + + + |
