This page has been accessed 205 times.NUTS NetLINK pseudo-RFC #1 Update
In this revision of this RFC, rather than present the original netlink protocol in its entireity, this presents only the modified protocol. For the original protocol, see the original RFC. To the best of my knowledge, this is current, based on the 1.0.0/1.0.1 release of NL+ for NUTS 2.x. Commands and basic function: + indicates required items (*) DISCONNECT -- polite talkers should send this before closing down a connection to another talker's netlink port. If no disconnect is received, an error message may be displayed. Handling this command when received is only necesary if an error message is displayed when the connection is lost unexpectedly. Usage: DISCONNECT\n (+) TRANS -- this is used when a used logs in via netlink. Usage: varies by version. A. Version 3.3.0 and earlier: TRANS username password description\n B. Version 3.3.1 and later: TRANS username password level description\n C. Netlink+: TRANS username password level description\n (+) REL -- this releases a user login... Usage: REL username\n (+) ACT -- this executes a command, may be disabled if you only want to allow speech and no motion or anything, though that's rather cruel. Usage: ACT username action[]\n NOTE: When a user hits return on a blank line, NUTS 3.x talkers send "ACT username NL\n". You must trap this on input, although sending the NL, even to NUTS 3.x talkers, seems to be unnecessary. (+) GRANTED -- sent when permission for a user to login is granted, Usage: GRANTED username\n (+) DENIED -- A. "DENIED CONNECT #" indicates you aren't allowed to connect your site to a remote site in the initial negotiation or the remote host refused for other reasons. A list of these numbers is provided below. B. "DENIED username #" means a user login was denied. Reasons for "DENIED CONNECT": 1 -- not in valid sites list 2 -- unable to create netlink object (out of memory) 3 -- no room had an available slot for inbound link ("no free room links."). 10 -- Connection refused -- netlink+ only Reasons for "DENIED username": 1 -- (not reused from above) 2 -- (not reused from above) 3 -- (not reused from above) 4 -- link for incoming/outgoing users only (opposite of what user is attempting) 5 -- user already logged in (at remote site) 6 -- A. out of memory creating user object -- only useful if uses dynamically allocated user structs. B. ver<3.3.3 may also return this for banned users and users below minlogin (when sending to older talkers, both conventions should be honored, by version number). 7 -- incorrect password (for valid local users) 8 -- A. login level below minlogin -- nuts 3.3.3 and up only, else use 6. B. request for action by user not logged in. 9 -- user banned -- nuts 3.3.3 and up only, else use 6. 10 -- Connection refused -- netlink+ only (+) MSG -- indicates beginning of text to be send unprocessed. Usage: MSG username\n(body of message)EMSG\n Extension: a \ before a newline indicates that it should be suppressed, e.g. prompts. (+) PRM -- requests that user's originating site display a prompt. Usage: PRM username\n (+) VERIFICATION -- sent by client to tell server _its_ version info, etc. Usage: VERIFICATION password nutsver/linkver service "Long Name" "Server Type"\n where password is the netlink password, nutsver is the NUTS version (always 3.3.3), linkver is the link version (1.0.0 currently), service the service name for the connecting talker (formerly called shortname), "Long Name" is the full name of the connecting talker, and "Server Type" is a string contianing the version and code base of the server for informational purposes. Also: The initial prompt sent upon receipt of a netlink connection should be similar: NUTS nutsver/linkver service "Long Name" "Server Type"\n (+) VERIFY -- response to VERIFICATION. Usage: VERIFY OKAY *\n, where * is IN, OUT, or ALL. (+) REMVD -- sent by remote host to originating site to indicate that the user has used go to return to originating site or has been kicked off the remote host. Usage: REMVD user\n (+) EXISTS? -- sent to request verification of a user before sending mail. Responses are EXISTS_YES and EXISTS_NO EXISTS_NO -- user does not exist EXISTS_YES -- user exists Usage: EXISTS? to from\n, where "to" is verified, and returned to from. Returns: EXISTS_* to from\n, in a like fashion (+) MAIL -- indicates start of a mail message for remote delivery Usage: MAIL to from\n (+) ENDMAIL -- indicates end of a mail message Usage: ENDMAIL\n (+) MAILERROR -- indicates an error occurred in mail delivery Usage: MAILERROR to from\n (*) KA -- keepalive message -- may be ignored when received or used to determine whether a netlink is working or not, but must be sent every so often, which may depend on the remote host -- the remote host can't disconnect in less than 300 seconds, according to the comments in the sources. Dunno why. I'd say doing it in an alarm-based signal handler every 30 seconds or so should pretty much keep other talkers happy. :-) Usage: KA\n (-) RSTAT -- remote statistics - if not supported, it should at least send a response along the lines of "MSG username\n Not supported\nEMSG\n" since it's assumed that any 3.3.3 or newer talker supports this. Usage: RSTAT username\n NOTES AND CHANGES: 1. In the current implementation, a user can go through a host to other hosts. Eventually, a hop count will be added to the negotiation. Note that stock NUTS 3.x hosts may only serve as a starting point or an ending point, i.e. you can't pass through them. 2. Because prompts require a line to be sent without a newline, and because the current netlink protocol requires commands to be preceded by a newline, including the EMSG command, such prompts cannot be supported under NUTS 3.x without modifications to the code. When dealing with a NUTS 3.x host, things may just not look quite as good. Modify functions accordingly to use sprintf followed by write_user instead of a series of shorter write_user's. When dealing with a NL+ host, this problem is eliminated using the traditional unix \ trick. Lines ending in a \ get their newline truncated before output, unless there's an even number of \'s, i.e. a \ quotes the following \, so you end up with half the number of \'s. 3. Due to problems entering URL's, the quoting character for ANSI color commands has been changed to a \. This should not significantly effect the usefulness of the link, and indeed, the NUTS 3 talkers should probably change their implementation as well, for that reason. 4. To preserve compatibility, the version number given is now in the form 3.3.3/a.b.c where a.b.c is the NetLink+ version number, and is currently 1.0.0 (or 1.0.1). 5. Version negotiation as described in previous versions of the RFC is not supported in the current code, although the 2.0 version negotiation is somewhat similar, except without "required" features. 5. Implementation: if a given talker has no say or .say command, that must be gotten around. Beyond that, user commands preceded by "ACT username" should be treated as commands. Most other commands are self-explanatory. The means for handling unknown remote users without actually creating a local user with that name is left as an exercise for the implementing person within a given architecture, and is beyond the scope of this RFC. That having been said, the easiest solution would be to have a user type number, which if equal to NETLINK_USER or some such number, would not get saved. A similar type field exists within NUTS 3.3.3. 6. A word on capitalization: *ALL* commands in the netlink protocol must be capitalized. The same goes for any extended commands. This practice should continue. However, it is suggested that you allow commands of any case (through judicious use of toupper() in a loop), especially if you are writing an implementation of this RFC from scratch, as opposed to basing it on NUTS 3.3.3's existing code. This pseudo-RFC was written by David A. Gatwood, a student at the University of Tennessee at Martin. For more information, comments, etc., send electronic mail to dgatwood@globegate.utm.edu. ----------------------- END OF pseudo-RFC ----------------------- Comments and suggestions? Send mail to dgatwood@globegate.utm.edu.