1 /* Include for communications with GNUstep Distributed Objects name server. 2 Copyright (C) 1996, 1997 Free Software Foundation, Inc. 3 4 Written by: Richard Frith-Macdonald <richard@brainstorm.co.uk> 5 Created: October 1996 6 7 This file is part of the GNUstep Project. 8 9 This program is free software; you can redistribute it and/or 10 modify it under the terms of the GNU General Public License 11 as published by the Free Software Foundation; either 12 version 2 of the License, or (at your option) any later version. 13 14 You should have received a copy of the GNU General Public 15 License along with this program; see the file COPYING. 16 If not, write to the Free Software Foundation, 17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 19 */ 20 21 /* 22 * About the GNU Distributed Objects name-server 23 * 24 * The name server is intended to work with both the UDP and the TCP 25 * protocols. It is intended that the TCP interface be used by 26 * GNUstep programs, while the UDP interface is intended primarily 27 * for communication between name servers on different machines. 28 * 29 * The communications protocol is identical for both TCP and UDP and 30 * consists of a simple request-response sequence. 31 * 32 * Each request is a single message consisting of - 33 * a single byte request type, 34 * a single byte giving name length, 35 * a single byte specifying the type of port being registered 36 * or looked up, or a nul byte for probe operations. 37 * a single nul byte. 38 * a four byte port number in network byte order must be 39 * present for register operations, otherwise this is zero. 40 * a service name of 0 to GDO_NAME_MAX_LEN bytes (or two IP 41 * addresses in network byte order and an optional list of 42 * additional addresseso for probe operations) 43 * 0 to GDO_NAME_MAX_LEN nul bytes padding the service name to its 44 * full size. 45 * a terminating nul byte. 46 * The total is always sent in a packet with everything after the 47 * service name (except the final byte) cleared to nul bytes. 48 * 49 * Each response consists of at least 4 bytes and depends on the 50 * corresponding request type and where it came from as follows - 51 * 52 * Request type Effect 53 * 54 * GDO_LOOKUP Looks up the server name and returns its port number. 55 * Response is the port number in network byte order, 56 * or zero if the named server was not registered. 57 * 58 * GDO_REGISTER Registers the given server name with a port number. 59 * This service is only available to processes on the 60 * same host as the name server. 61 * Response is the port number in network byte order, 62 * or zero if the named server was already registered. 63 * 64 * GDO_UNREG Un-register the server name and return old port number. 65 * If the server name is of length zero, and the port is 66 * non-zero then all names for the port are unregistered. 67 * This service is only available to a process on the 68 * same host as this name server. 69 * Response is the old port number in network byte order, 70 * or zero if the name could not be un-registered. 71 * If multiple names were unregistered the response is 72 * the port for those names. 73 * 74 * GDO_SERVERS Return a list of the known servers on the local net. 75 * Response is an unsigned long (in network byte order) 76 * saying how many servers the name server knows about, 77 * followed by a list of their IP addresses in network 78 * byte order. 79 * NB. This response may not be possible over UDP as the 80 * response length may exceed the maximum UDP packet size. 81 * 82 * GDO_NAMES Return a list of registered names known to the server. 83 * Response is an unsigned long (in network byte order) 84 * saying how many bytes of data are to follow, 85 * followed by a list of the names each preceded by the 86 * name length (a single byte) and port type (a byte). 87 * NB. This response may not be possible over UDP as the 88 * response length may exceed the maximum UDP packet size. 89 * 90 * The following are used for communications between name servers - 91 * 92 * GDO_PROBE Requests a response 93 * Passes two IP addresses in the name field - first the 94 * address of the sender, next that of the recipient. 95 * The packet may (optionally) include a variable number 96 * of addresses (as specified by the name length minus the 97 * size of the two addresses), each of which is an internet 98 * address on which the sender is also listening. 99 * For a request from a name server via UDP there is no 100 * response, but a GDO_REPLY request is sent. 101 * For a request from a non-name-server, or a TCP 102 * connect, the response is the port number of this 103 * server in network byte order. 104 * 105 * GDO_PREPLY Replies to a GDO_PROBE via UDP from a name server. 106 * The format of the message is as for GDO_PROBE. 107 * No response is sent. 108 * 109 * 110 * HOW IT WORKS AND WHY (implementation notes) 111 * 112 * 1. The fixed size of a request packet was chosen for maximum 113 * ease and speed of implementation of a non-blocking name server. 114 * The server knows how much it needs to read and can therefore 115 * usually do a read as a single operation since it doesn't have 116 * to read a little, figure out request length, allocate a buffer, 117 * and read the rest. 118 * 119 * The server name length (bytes) is specified - no assumptions 120 * should be made about whether the name contains nul characters 121 * or indeed about the name at all. This is future-proofing. 122 * 123 * 2. Why UDP as well as TCP? 124 * The OpenStep specification says that a connection may be 125 * established to any host on the local network which supplys a 126 * named service if the host name is specified as '*' 127 * 128 * This means that the application must poll to see if it can 129 * find a server with the name it wants. The polling could take 130 * a huge amount of time! 131 * 132 * To make this all easier - the server is capable of supplying 133 * a list of those hosts on the local network which it knows to 134 * have (or have had) a name server running on them. 135 * 136 * The application then need only poll those name servers to find 137 * the service it wants. 138 * 139 * However - to give the application a list of hosts, the name 140 * server must have got the information from somewhere. 141 * To gather the information the server has to poll the machines 142 * on the net which would take ages using TCP since attempts to 143 * talk to machines which are down or do not exist will take a 144 * while to time out. 145 * 146 * To make things speedy, the server sends out GDO_PROBE requests 147 * on UDP to all the machines on the net when it starts up. 148 * Each machine which has a name server notes that the new name 149 * server has started up and sends back a GDOPREPLY packet so 150 * that the new name server will know about it. 151 * 152 * Things are never perfect though - if a name server dies, the 153 * other name servers won't know, and will continute to tell 154 * applications that it is there. 155 * 156 * 3. Port type codes - these are used to say what the port is for so 157 * that clients can look up only the names that are relevant to them. 158 * This is to permit the name server to be used for multiple 159 * communications protocols (at the moment, tcp or udp) and for 160 * different systems (distributed objects or others). 161 * This guarantees that if one app is using DO over UDP, its services 162 * will not be found by an app which is using DO over TCP. 163 */ 164 165 #define GDOMAP_PORT (538) /* The well-known port for name server. */ 166 167 /* 168 * Request type codes 169 */ 170 #define GDO_REGISTER 'R' 171 #define GDO_LOOKUP 'L' 172 #define GDO_UNREG 'U' 173 #define GDO_SERVERS 'S' 174 #define GDO_PROBE 'P' 175 #define GDO_PREPLY 'p' 176 #define GDO_NAMES 'N' 177 178 /* 179 * Port type codes 180 */ 181 #define GDO_NET_MASK 0x70 /* Network protocol of port. */ 182 #define GDO_NET_TCP 0x10 183 #define GDO_NET_UDP 0x20 184 #define GDO_SVC_MASK 0x0f /* High level protocol of port. */ 185 #define GDO_SVC_GDO 0x01 186 #define GDO_SVC_FOREIGN 0x02 187 188 /* tcp/ip distributed object server. */ 189 #define GDO_TCP_GDO (GDO_NET_TCP|GDO_SVC_GDO) 190 191 /* udp/ip distributed object server. */ 192 #define GDO_UDP_GDO (GDO_NET_UDP|GDO_SVC_GDO) 193 194 /* tcp/ip simple socket connection. */ 195 #define GDO_TCP_FOREIGN (GDO_NET_TCP|GDO_SVC_FOREIGN) 196 197 /* udp/ip simple socket connection. */ 198 #define GDO_UDP_FOREIGN (GDO_NET_UDP|GDO_SVC_FOREIGN) 199 200 201 #define GDO_NAME_MAX_LEN 255 /* Max length registered name. */ 202 203 /* 204 * Structure to hold a request. 205 */ 206 typedef struct { 207 unsigned char rtype; /* Type of request being made. */ 208 unsigned char nsize; /* Length of the name to use. */ 209 unsigned char ptype; /* Type of port registered. */ 210 unsigned char dummy; 211 unsigned int port; 212 unsigned char name[GDO_NAME_MAX_LEN+1]; 213 } gdo_req; 214 215 #define GDO_REQ_SIZE sizeof(gdo_req) /* Size of a request packet. */ 216 217 /* 218 * If you have a fascist sysadmin who will not let you run gdomap 219 * as root and will not even let you modify /etc/services to point 220 * gdomap to another port, you can uncomment the next #define to 221 * run gdomap on port 6006 (or modify this to a port of your choice). 222 * Whatever port you choose, you should make sure that no other 223 * processes running on your network use that number! 224 * 225 * When you have done this you must recompile gdomap.c and 226 * NSPortNameServer.m and re-install the base library with 227 * the new NSPortNameServer.o 228 * 229 * NB. Doing this will render your system unable to communicate with 230 * other systems which have not performed the same remapping. You 231 * should not do it unless you have no choice. 232 */ 233 /* #define GDOMAP_PORT_OVERRIDE 6006 */ 234 235