Genealogy Network Transfer Protocol

GNTP Version 1.0

E-Business Center

Brigham Young University

Protocol Version 0.75
This document is released under the GNU Public License .
Last Updated: February 6, 2002
Email bugs to Conan Albrecht

Introduction

GNTP is a new protocol and related architecture that enables real-time, ad-hoc sharing and transfer of genealogical information via the Internet. It allows the transfer of GEDCOM (or other formats) directly between peer-to-peer computers and enables efficient searching of the same.

GNTP defines two related peer-to-peer networks: an inner ring of directory servers and an outer network of publishers. The directory servers cache meta-information about the data contained on the publishers connected to it. This is accomplished by publishers registration at startup. Initial clients prototypes will register automatically with a central directory server to allow less-advanced users publish information without needing to understand the network architecture. After the client registers, the directory server responds by querying the publisher (using GNTP) and caching meta-information such as names and/or locations. Publishers contact their directory server periodically to keep the network updated.

GNTP remains architecture-independent as to the types and models of connections between directory servers. It also does not specify the amount of information cached at the directory server level. This allows future participants to innovate and add value to the central directory ring.

Publishers represent individual nodes or users on the network. Users load their GEDCOM (or other formats) into their client through a File | Open... dialog. Clients then listen in peer-to-peer fashion for queries submitted from other clients. The "Publisher/Uploader" circle in Figure 1 represents a publisher that is also willing to accept uploads and publish data from clients without full-time connections to the Internet. The protocol includes commands for automatic uploading and updating of data to Publisher/Uploaders to allow less-advanced genealogists to publish via proxy. These users are represented in the figure with dotted lines.

When a user submits a query to the network, the client first connects to a known directory server (such as the one that will be hosted by BYU). The directory server responds with the IP addresses and ports of all publishers it knows about that may be able to answer the user's query. The initial directory server also returns other known directory servers, with whom the process is restarted. The client then connects to the returned publishers directly and queries each one in turn. The client-to-client connections make the network follow a true peer-to-peer model. The directory servers exist to make the peer-to-peer connections more efficient by directing clients to peers that are most able to answer their queries.

The GNTP protocol and related architecture provide many benefits above and beyond today's publication methods. These are described in the following list:

GNTP is part of research at the E-Business Center in the Marriott School of Management at Brigham Young University. It is being released under the GNU Public License (GPL), which means that you may download, modify, and enhance the source code at no charge. Modifications must also be released under the GPL. We welcome all additions, development, and help in the project.

Architecture

GNTP is composed of two separate but related networks: a small ring of directory servers and a distributed network of clients. Both networks are connected via peer-to-peer connections. The smaller, central ring is provided only for efficiency reasons. The source data (GEDCOM) remains with the distributed clients. The following diagram shows a high-level view of the network architecture:

Node Types

Several types of clients exist. A given client on the network can implement any (or all) of these features, although the features are naturally split across different implementations. The current types are described in the following table:
Node Type Constant Description
Directory Server META
  • Participates in the central ring of directory servers by pointing to at least one other directory server.
  • Allows publishers to register with it. The directory server then queries each registering client and caches a superset of the results locally.
  • Listens for search requests from searchers. It returns IP addresses of publishers that most likely meet the needs of a given search.
  • Returns registered client lists (registered publishers, registered uploaders).
Publisher PUBLISH
  • Registers with at least a directory server.
  • Listens for search requests from searchers. It returns GEDCOM-compliant snippets of matching data to searchers.
Uploader UPLOAD
  • Should also be a publisher.
  • Accepts uploaded GEDCOM files from transient clients within given parameters. The uploader then publishes these data to its directory server.
  • Allows transient clients to update and manage their data on the uploader.

Transient Client n/a
  • A user who is not connected to the Internet 100 percnt; of the time or does not wish to publish data directly.
  • Publishes GEDCOM file(s) by proxy via a known Uploader.

Searcher n/a
  • Connects to directory servers to retrieve IP lists of publishers who most likely match a given query.
  • Connects directly to publishers to retrieve matching GEDCOM-compliant snippets.
  • Displays these snippets in textual or graphical format to the user.

The "Constant" column provides the constant string that identifies a given node type within the protocol (see the 200 GNTP command). Since only servers identify themselves, transient clients and searches do not require node types. If a given node implements more than one function, their types are concatenated with a plus. For example, and publisher/uploader (which will be very common) is denoted as PUBLISH+UPLOAD.

Data Format

The currently supported data format in GNTP 1.0 is GEDCOM. We expect to support other formats in the next releases of the protocol. However, we currently support GEDCOM for simplicity and because it is the only widely-recognized format for genealogical data representation. Several different XML DTDs exist for genealogical data, but none are sufficiently standardized and supported to be included in the protocol at this time.

We will support new formats (XML, etc.) when they become widely used and standardized.

Protocol Standards

The protocol uses a line-oriented, standard format for streaming data between client and server. A simple socket connection is established between client and server. Unicode text is transfered, which includes the protocol identifiers and the data. The socket is then closed by client or server (depending upon the action being taken). Since the protocol is relatively simple, no higher-level technologies such as SOAP, XML, etc. have been used.

Command Format

Most commands occupy a single line and are terminated with a hard return (\r, \n, \r\n, or \n\r). Protocol commands are formatted as follows:

     NNN AAAA [parameter [,parameter...]

     NNN = A three-digit, numerical code (000-999) identifying the protocol command
     AAAA = A four-letter, alphanumeric (AAAA-ZZZZ) identifying the protocol command. The NNN and AAAA identifiers are redundant to allow clients and servers to efficiently switch commands as well as provide a human-readable protocol. The characters are always uppercase characters between A and Z.
     parameter(s) = The parameters specific to the given command, if any.

Some commands require multiple line transmissions (such as a GEDCOM snippet). This is accomplished with the identification of an end delimiter on the initial line followed by the number of remaining lines to be received including the end delimiter line. The end delimiter is always given as a single character.

Example:

     210 Results END . LINES 5     // the transmission will be delimited by a period on a single line
     data...
     data...
     data...
     data...
     .                              // a single period

Checksum Number

The checksum caused too many problems in early beta products.  Since TCP/IP contains error correction, the use of checksum numbers is discontinued.

Encoding

All characters streamed across a socket connection must be in Unicode (specifically, UTF-8) format. UTF-8 provides an efficient encoding for ASCII file, yet allows for other character sets to be used. UCS characters U+0000 to U+007F (ASCII) are encoded simply as bytes 0x00 to 0x7F (ASCII compatibility). This means that files and strings which contain only 7-bit ASCII characters have the same encoding under both ASCII and UTF-8. Therefore, very little encoding will be done for existing GEDCOM files, since GEDCOM only supports ASCII.

Developers are referred to UTF-8 specifications for further information. The general specification is defined in ISO 10646-1 Annex R and RFC 2279 . An easier-to-read FAQ is available at http://www.cl.cam.ac.uk/˜mgk25/unicode.html#utf-8

Dates and Times

For consistency and exactness, dates and times within the protocol (not within GEDCOM itself) are given as a 64-bit integers signifying the number of milliseconds since Midnight, January 1, 1970.  Many languages natively support this time format.  Therefore, the following datetimes are equivalent:

January 01, 1970 UTC 00:00:00  =             0
June    11, 1973 MDT 05:35:03  =  108646503000   // mountain standard time +07:00

IP Addresses Only

As in most P2P networks, GNTP uses only IP addresses and does not use hostnames as defined by the DNS system.  Reliance upon DNS causes problems as most clients (who act as servers in P2P) do not have meaningful DNS host names.  Therefore, IP addresses should always be used.

In addition, many users retrieve their IP address via DHCP, meaning they have temporary addresses that may change at any time.  To ensure that servers always contain the most updated information, client IP addresses are included in all pings.  Directory servers should update themselves as pings come in as to the most current client information.

Command Groups

Commands have been grouped into functional sets for readability. These are as follows:
Range Description
000-099 Reserved for future use
100-199 Initial connection, handshaking, and setup, protocol management
200-299 Success indicators, result sets from searches, posting, etc.
300-399 Reserved for future use
400-499 Error codes
500-599 Searching codes for searchers, publishers, and directory servers
600-699 Transfer of GEDCOM data
700-799 Registration with directory servers
800-899 Reserved for future use
900-999 Reserved for application use

Connecting and Setup

The initial connection is the same between any server and client. Clients always initiate contact by opening a socket to the known server port. The server responds with a 200 code, giving its preferred GNTP version number, IP address, and node type. The client can request a different GNTP version (101), which the server then accepts (200) or rejects (402). When the client is satisfied with the version number (it will normally be immediately satisfied), it sends a hello (100) with its host name, and the server enters the ready state (201).

Simple example:

    Client opens a socket connection to server IP address and port
    S: 200 GNTP/1.0 10.0.0.1 PUBLISH+UPLOAD
    C: 100 HELO 10.0.0.2
    S: 201 OKAY

Example requesting a different version number:

    Client opens a socket connection to server IP address and port
    S: 200 GNTP/1.2 10.0.0.1 PUBLISH+UPLOAD
    C: 101 REQV GNTP/1.1
    S: 402 GNTP/1.1 not supported
    C: 101 REQV GNTP/1.0
    S: 200 GNTP/1.0 10.0.0.1 PUBLISH+UPLOAD
    C: 100 HELO 10.0.0.2
    S: 201 OKAY

The client can reset the server to its ready state at any time without closing the connection. The server and client are expected to remain at the last proposed protocol version number (that was sent by the server using the 200 command).

Example:

    client or server can be in the middle of any transaction
    C: 100 HELO 10.0.0.2
    S: 201 OKAY

Node Identification

All nodes on the network must identify themselves. The identifying information is transferred as a sequence of name/value pairs. The client requests information (140) with the information tags it is interested in. Multiple tags are separated by a space. The server responds (240) with a multiple-line transmission, with each name/value pair on a separate line.

All nodes must provide information on the required tags. Others are optional. The standard tags are as follows:
 
Tag Name Constant Description Required?
All A wildcard indicating the client wants all identification tags transmitted. Required
ContactName The name of the publisher administrator. Required
ContactEmail A valid e-mail address to contact the publisher administrator. Required
ContactState The state or province the publisher server is located in. Required
ContactCountry The country the publisher server is located in. Required
ContactAddress The publisher administrator's full mailing address. The state/province/country need not be the same as the ones the server is located in. Optional
ContactPhone The publisher administrator's phone number Optional

Example 1:

    S: 201 OKAY
    C: 140 INFO ContactName ContactEmail ContactCountry
    S: 240 INFO END . LINES 4
    S: ContactName=Joe Brown
    S: ContactEmail=joe@brown.com
    S: ContactCountry=Canada
    S: .
    S: 201 OKAY

Example 2 of a server supporting only required tags:

    S: 201 OKAY
    C: 140 INFO All
    S: 240 INFO END . LINES 5
    S: ContactName=Joe Brown
    S: ContactEmail=joe@brown.com
    S: ContactState=Alberta
    S: ContactCountry=Canada
    S: .
    S: 201 OKAY

Searching

Searching is done only on PUBLISH servers. Since the searcher node type is not defined explicitly, clients may be searchers, transient clients, other publishers, directory servers, or anything else. Directory servers (that are not publishers) do not allow direct searching. They only provide IP addresses of publishers. Publishers provide actual GEDCOM results.

Searching is currently performed via template name/value pairs. Future protocol versions may implement a full SQL-type query language. A search is always centered on an individual (cross generational searching is not possible yet).

A search is specified as a set of name/value pairs in a multi-line request. All tags are interpreted as an "AND" relationship. The valid tags are specified as follows:
 
Search Tag Constant Description Required
MaxResults n The maximum number of individuals to return in the result set. If not specified, the server determines whether to send all results or a subset of the results. If the maximum number of results is less than or equal to 0, the client requests all individuals. However, the server is never required to return all results. 0 (all results) is assumed if this tag is not included in the search request. Optional
MaxGenerations n The number of generations on each side of a matching individual to return. 0 (default) specifies that each returned GEDCOM snippet should only contain the individual. 1 specifies that parents and children of individuals will be returned. Optional
Soundex n Whether the name fields (individual, father, mother) should be matched via soundex algorithms. The possible values are 0 for false or 1 for true. True is assumed (soundex is the default) if this tag is not included in the search request. Optional
Offline n Whether to include offline publishers.  The possible values are 0 for false (not included) and 1 for true (included).  The default value is 0, or not included. Optional
Given name The individual's first name Optional
Surname name The individual's last name Optional
Sex gender The individuals gender, given as "M" or "F" Optional
SpouseGiven name The individual's spouse's first name. Optional
SpouseSurname name The individual's spouse's last name. Optional
FatherGiven name The individual's father's first name. Optional
FatherSurname name The individual's father's last name. Optional
MotherGiven name The individual's mother's first name. Optional
MotherSurname name The individual's mother's last name. Optional
Event event startyear endyear country state/province An event between (and including) a start year and an end year. To specify an exact year, make the start and end years the same. The standard event tags (event) are the same as those defined in GEDCOM. The keyword "all" in the country and/or state/province is a wildcard that will match any country or state/province. Optional

The server responds with potentially several GEDCOM snippets, one per individual. The number of generations in each snippet is specified by limits on the data or the MaxGenerations tag. Individual who are related to each other are included in a single GEDCOM snippet. Therefore, if two individuals are within MaxGenerations of each other and both match the query, they are merged into one GEDCOM snippet rather than two overlapping snippets. The server response is formatted as a series of multi-line transmissions.

Example:

    S: 201 OKAY
    C: 510 SRCH END . LINES 6
    C: MaxResults 5
    C: MaxGenerations 3
    C: Surname Hansen
    C: Event BIRT 1750 1770 USA Utah
    C: Event DEAT 1845 1845 all all
    C: .
    S: 210 RSLT 2
    S: 601 GEDC END . LINES 4
    S: 0 HEAD
    S:  ... gedcom for first individual ...
    S: 0 TRLR
    S: .
    S: 601 GEDC END . LINES 4
    S: 0 HEAD
    S:  ... gedcom for second individual ...
    S: 0 TRLR
    S: .
    S: 201 OKAY

After the client has finished transmitting its query, the server can also respond with several error codes: 400 (internal server error), 410 (syntax error in the search), and 411 (search request refused), or 230 (empty result set).

Searching Directory Servers

Directory servers provide the links between the individual nodes on the network. They make the peer-to-peer connections efficient by directing searchers to publishers that most likely contain matching results. Viewed conversely, directory servers eliminate peers that definitely do not contain matching records.

Several directory servers may exist on the network at any time. The internal structure of directory servers is not specified in the protocol; rather, they are free to cache as much information as they deem necessary and can efficiently handle. Directory servers are networked via peer-to-peer connections and know about at least one other directory server. We expect that only a few known directory servers will exist; therefore, the peer-to-peer connections between then will be efficient due to the small number.

Searchers initially contact a directory server and submit their query. The directory server parses the query as needed and returns IP addresses of publishers that most likely contain matching individuals. Searchers then contact these publishers directly. Searchers may also ask directory servers for the IP addresses of other known directory servers. Searchers then repeat the query request and continue the search. Searchers are finished when they have contacted all directory servers and all relevant publishers.

Queries are submitted to directory servers with the exact same protocol as they are to publishers. The difference is in the server response. Directory servers respond with a multi-line response containing the IP address and port of each publisher the searcher should contact. The submission of full queries to directory servers allows directory servers to cache as much information as they efficiently can and utilize as much of the searcher's query as needed.

Example:

    S: 201 OKAY
    C: 520 FIND END . LINES 5
    C: MaxResults 5
    C: Surname Hansen
    C: Event BIRT 1750 1770 USA Utah
    C: Event DEAT 1845 1845 all all
    C: .
    S: 220 PBLS END . LINES 4
    S: 10.5.33.52:2268
    S: 10.83.234.22:7922
    S: 10.1.3.1:2268
    S: .
    S: 201 OKAY
 

Identifying Publishers

Searchers can query directory servers for information about publishers by providing the IP address and port of the publisher and the identification tags it is requesting.  Possible tags are listed in "Identifying Nodes" above.

Example requesting all information on 10.0.0.2:2268:

    S: 201 OKAY
    C: 730 INFO 10.0.0.2 2268 ContactName ContactEmail ContactState ContactCountry
    S: 240 INFO END . LINES 5
    S: ContactName=Joe Brown
    S: ContactEmail=joe@brown.com
    S: ContactState=Alberta
    S: ContactCountry=Canada
    S: .
    S: 201 OKAY
 

Posting GEDCOM to Uploaders

Uploaders are publishers that are willing to host data for transient clients.  Since many users do not have broadband or permanent Internet connections, uploaders are necessary to allow for data publication on the network.  The process of uploading and publishing data by proxy is handled by GNTP to allow for automated publication of data.

Transient clients initiate the transaction with a 600 POST command.  The POST commmand includes the client's e-mail address, self-selected password, filename, and number of bytes to be transferred.  Spaces are not allowed in the e-mail, password, or filename.  Client applications should perform the necessary conversion for users.  The uploader responds with a 261 OKAY or one of several error messages.  The OKAY command signals the expiration date.  If the uploader signalled okay, the client uploads their GEDCOM via the standard 601 GEDC command.

Example:

    S: 201 OKAY
    C: 600 POST me@aol.com mypass myfile.ged 50321
    S: 261 OKAY 1088237531322
    C: 601 GEDC END . LINES 4
    C: 0 HEAD
    C: ... gedcom for first individual ...
    C: 0 TRLR
    C: .
    S: 201 OKAY

The server can specify several error codes, including 401 for retransmit, 403 for unsupported, or any of the codes in the 460-465 range.

A given transient client (using a given e-mail address) may have different passwords for each file.  That is, clients register a password for each file they upload.

Deleting GEDCOM from Uploaders

When transient clients need to update their information on an uploader, they first delete their current file data from the uploader and then repost the data.  The protocol does not support incremental updating of existing data.  To delete data, a client must send its e-mail, password, and filename.

Example:

    S: 201 OKAY
    C: 610 DELE me@aol.com mypass myfile.ged
    S: 265 OKAY
    S: 201 OKAY

Errors are reported to the client with 403 for unsupported or any of the codes in the 466-469 range.

Finding Uploaders

  Since all clients identify their type when they register, directory servers  contain lists of uploaders.  Searching clients can query directory servers for these uploaders.  Directory servers normally respond with 5 random uploaders which the client picks from.  If no uploaders have registered, a 230 code is returned. 

Example:

    S: 201 OKAY
    C: 630 LSTU
    S: 640 UPLO END . LINES 4
    S: 10.0.0.3 2269
    S: 192.168.0.1 2231
    S: 10.0.0.5 2269
    S: .

    S: 201 OKAY

Once it receives this list, the client can then contact each uploader individually, verify that they are up and are truly uploaders, and see if they will allow an additional data file.

Registration with Directory Servers

Publishers register with a directory server to join the network.  No permanent publisher-to-publisher connections are maintained.  After a publisher has registered, the directory server queries it for metadata using the standard query mechanism.  The amount of data queried is not specified in the protocol; this frees directory servers to cache as much data as they efficiently can.  Further, directory servers are responsible for querying registered publishers for their identification information and for their GEDCOM.  Publishers simply notify directory servers of their presence, who then query the publishers for their data.

When registering, publishers identify their IP address, listening port (for searchers to connect to them on), and node type.

The server responds with a unique key that is implementation-dependent.  To the publisher, the key is simply a short string.  No special characters can make up a key (letters and numbers only, no spaces).  The server also specifies the interval, in seconds, that the publisher should ping with.

Example (directory server is the server, publisher is the client):

    S: 201 OKAY
    C: 700 REGI 10.0.0.2 2268 PUBLISH+UPLOAD
    S: 270 OKAY 5AB382F32E709F 3600
    S: 201 OKAY
 

The server can also signal several error codes, including 470 if the IP/port combination is already registered.

Immediately following publisher registration, a directory server will normally immediately contact the publisher for its identification (140 INFO) and also query its data (510 SRCH or 550 META).

Should the publisher lose its key entirely (for example, a hard drive crash), it cannot publish its data with the directory server on the same port as before because it will not have valid key.  The protocol does not support automatic retrieval of keys from directory servers.  The publisher will need to register using a different port than before.

Retrieving Node Meta Information

Nodes do not initiate uploading of meta information to directory servers.  Rather,  publisher nodes simply register with the directory server.  The directory then initiates a reverse connection  to the publisher and retrieves meta information about it.  This is done for two reasons:
There are two ways that directory servers can retrieve node information.  The first is to simply query it as if the directory server was a normal searcher.  This is the less-preferred method because some clients may not allow their data to be lifted directly to another machine.  Searching normally only produces a sub-set of the Gedcom data for transfer.

The second method is using the META tags.  The server can retrieve counts of different keywords and can filter publishers on those counts.  Directory servers can issue as many META requests as deemed necessary.   The valid keywords are defined as the keywords used in searching: Surname, Given, etc.

Due to privacy issues, the META transaction contains the publisher's key on the given directory server.  When a META request comes to a publisher, it should check that this key matches the key that it was assigned to ensure that the node making this request is in fact its directory server.  In addition, it should check the remote IP address of the incoming connection and verify the directory server this way.  This functionality ensures that only directory servers can query meta information from publishers and that data cannot be simply lifted verbatim from one machine to another.

In the META transaction, the publisher responds with a multi-line response giving each instance of the keyword given

Example (note that the publisher is the server here and the directory server is the client):

    S: 201 OKAY
    C: 550 META 00000e9546beeb0000001f70017dea Surname
    S: 250 VALS END . LINES 4
    S: 5 Smith
    S: 22 Anderson
    S: 13 Kim
    S: 8 San Louis
    S: .

    S: 201 OKAY

On each line, the count comes first, then a space, then the instance of keyword.  This allows for spaces in Surnames, etc.

Pinging

If a publisher goes offline (either expectedly or unexpectedly), it reestablishes its presence with the server by pinging with its key.  This prevents the directory server from needing to retransmit the publisher's metadata.  It is up to directory server implementations to determine how long a publisher may remain offline (i.e. no pings) before the publisher's data is expunged.

A ping inludes the publisher's unique key, IP address, port, node type, and last update time.  Publishers are allowed to change their IP address, port, and node type between pings.  The key alone is deemed unique enough for security.  The directory server will update its listing automatically should a publisher's IP address, port, or node type change.

The last update time tells the directory server the last time the publisher's GEDCOM data was updated.  When the last update time is newer than the directory server's metadata, the directory server again queries the publisher for information.

Example:

    S: 201 OKAY
    C: 700 REGI 10.0.0.2 2268 PUBLISH+UPLOAD
    S: 270 OKAY 5AB382F32E709F 3600
    S: 201 OKAY

(one hour passes)

    C: 710 PING 5AB382F32E709F 10.0.0.2 2268 PUBLISH+UPLOAD 988237531991
    S: 271 OKAY
    S: 201 OKAY
 

Example of a client changing information with a ping:

    S: 201 OKAY
    C: 700 REGI 10.0.0.2 2268 PUBLISH+UPLOAD
    S: 270 OKAY 5AB382F32E709F 3600
    S: 201 OKAY

(one hour passes -- note the change of IP address and node type below)

    C: 710 PING 5AB382F32E709F 10.0.0.3 2270 PUBLISH 988237531996
    S: 271 OKAY
    S: 201 OKAY
 

Going Offline

Publishers will periodically go offline for maintenance or other reasons.  Rather than require reregistration when a publisher comes back online, a publisher can request to be offline from its directory server.  Directory server implementations are free to allow different periods of time for offline publishers to come back online.  Keeping track of offline publishers allows searchers to record the presence of offline servers that they can try to query at a later date.

To request offline status, a publisher sends the offline code (720) with its key.  The server responds with a success code (272) along with the time the publisher must ping by before its data is expunged.  The server can also respond with key not found (272) or unsupported (403).

Example:

    S: 201 OKAY
    C: 720 OFFL 5AB382F32E709F
    S: 272 OKAY 988237539382
    S: 201 OKAY

Example of a server rejecting offline status:

    S: 201 OKAY
    C: 720 OFFL 5AB382F32E709F
    S: 403 NSUP Offline publishers not supported
    S: 201 OKAY

Unregistering

When publishers are permanently going offline, they should unregister with their directory server.  This is accomplished with 750 UREG command;the server responds with an okay (273) code or a not found (472) code.

Example:

    S: 201 OKAY
    C: 750 UREG 5AB382F32E709F
    S: 273 OKAY
    S: 201 OKAY
 

Listing of All GNTP Codes

Code Structure Sent By Description
100 HELO ip address C The client is satisfied with the GNTP version number and is ready to begin transactions. This command also resets the server to the ready state.
101 REQV GNTP/x.y C The client requests a different protocol version number than the one currently being used. x denotes the major protocol version and y denotes the minor protocol version.
140 INFO taglist C Asks a node on the network to identify itself. Nodes must at least respond to the required tags. The taglist is a space-separated list of tags the client is requesting responses to. The wildcard "All" requests all tags from the server.
190 QUIT C Terminates the connection. The client normally requests termination, and the server closes the physical socket.



200 GNTP/x.y ip nodetype S The initial text sent by the server when a socket is opened or when the client has requested a different version number. The server identifies itself and its node type. The server is expecting a 100 HELO command from the client, assuming the client is happy with this protocol version. x denotes the major protocol version and y denotes the minor protocol version.
201 OKAY S The primary server ready state. The server is ready to accept the next transaction command. This state is reached after initial connection and handshaking and after the completion of any given transaction.
210 RSLT count S Server is about to send count GEDCOM snippets (in multi-line format)as the result of a query given to a publisher.
220 PBLS END delimiter LINES count S Server is about to send count IP addresses and ports (separated by a colon) of publishers that potentially match a submitted query.
230 EMPT S An empty result set was generated from a search. This server has no  matching IP addresses (for directory servers) or individuals (for publishers) or uploaders (for transient clients).
240 INFO S Responds to a 140 INFO request with a multi-line transmission. Each line contains one name/value pair.
250 VALS END delimiter LINES count
C
Responds to a 550 META request from a directory server.
261 OKAY expires_on S Returned to a transient client by an uploader when it is ready for transfer of GEDCOM to be published.
265 OKAY
S
Returned to a transient client by an uploader when it has successfully delete a GEDCOM file from its data store.
270 OKAY key ping_interval S Returned to a publisher from a directory server when the publisher registers (700).  The key is a directory-server-generated key that uniquely identifies the publisher with that server.  The ping interval is the expected interval in seconds that the publisher must ping the server with.
271 OKAY S Returned to a publisher from a directory server when the publisher has successfully pinged the server.
272 OKAY time S Responds to a 720 OFFL request.  Gives the time that the publisher must ping by before its data is expunged.
273 OKAY S Responds to a 750 UREG request.  The publisher is now successfully unregistered and the data is removed.



400 ERRO message C/S An internal client or server error has occurred. This is the catch-all code for errors that are not explicit in the protocol.
401 RETX C/S Requests that the previous transmission be resent in its entirety. For single-line transmissions, the single line is transmitted. For multi-line transmissions, the sender restarts with the initial line giving the end delimiter and line count.
402 GNTP/x.y not supported S The server does not support the requested protocol version. The client must request another version number or drop back to the last version the server proposed. x denotes the major protocol version and y denotes the minor protocol version.
403 NSUP message C/S Sent when a request is not supported on the given client or server.
410 SNTX message S A syntax error in query text was encountered. The client did not follow protocol, used unknown tags, etc.
411 RFSD message S The server has refused to answer a given query. This code allows servers to reject some queries (such as a data dump) if they choose to.
461 SIZE maximum_size_in_bytes S The transient client's GEDCOM file is too large.  The uploader's maximum upload size is maximum_size_in_bytes.
462 SPAC message S The uploader is out of space and is not longer accepting uploads
463 EXIS message S The specified uploader's file already exists.  Delete it first, then upload again.
464 GENL message S A generic message from an uploader to a transient client.  Examples are bad password, bad e-mail address, etc.
466 PASS message S The transient client's username/password/filename did not match an uploaded file on the server.
470 REGI message S Returned during publisher registration when the publisher's IP address and port are already registered with a given directory server.
471 CNCT message
S
Returned during publisher registration if the server can't connect back to the client to retrieve it's gedcom.  This signals a bad ip or port or an unreachable client (for example, a client behind a firewall or NAT).
472 NFND message S The given unique publisher key was not found on the server.  Responds to a 720 OFFL or 750 UREG command.
473 OKAY
S
The client has successfully been unregistered.



510 SRCH END delimiter LINES count C Submit a search to a publisher. GEDCOM-complient snippets are returned to the client.
520 FIND END delimiter LINES count C Submit a search to a directory server. IP addresses and port numbers of relevant publishers are returned to the client.
550 META key keyword
S
A directory server is requesting meta information from a client.  The key is the client's key with that directory server, and the keyword is the search tag.



600 POST email password filename num_bytes C Requests posting of GEDCOM to an uploader.
601 GEDC END delimiter LINES count C/S Indicates the initiation of a GEDCOM transfer. The GEDCOM is transferred using the standard GNTP multi-line format, and ends with a delimiter character.
610 DELE email password filename C Requests a deletion of a GEDCOM file on an uploader's site
630 LSTU C Requests that a directory server return about 5 random clients who have identified themselves as uploaders.
640 UPLO END delimiter LINES count S Returns one line for each uploader, formatted as "IP port", in response to a 630 LSTU request



700 REGI ip port nodetype C Sent to a directory server from a publisher when the publisher is registering as a publisher node. 
710 PING key ip port nodetype last_update C Sent periodically to a directory server from a publisher.  Tells the directory server that the publisher is still alive.  Also updates the server's information about that publisher.
720 OFFL key C Requests an offline period for a publisher from a directory server.
750 UREG key C Unregisters a publisher from a directory server.  The publishers data is removed from the directory server's cache.
900-999   This range does not include any commands, but is reserved for specific application use. If applications need to develop extensions to the GNTP protocol, they should be done within this range. These extensions are not part of the GNTP protocol and will not be supported by other clients. It is meant for communication within instances or modules of the application on a computer and is not meant for communication between clients.