path: root/contrib/bind/doc/notes/irp.txt

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