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:: .