Index

1. Overview
2. General characteristics of Ninive Server
3. Execution environment
4. The server
5. Server Log
6. Ninive configuration file
7. XNP protocol

   1. XNP - VALIDATE request
   2. XNP - NOP request
   3. XNP - READ request
   4. XNP - WRITE request
   5. XNP - SHUTDOWN request
8. EOF

Overview

Ninive is an XML Socket server written in C and running both on Linux based platform and Microsoft Windows generic 32 bit platform;; it accepts TCP connections from clients capable of building, sending into TCP channel and interpreting in response XML buffers coded according to internal protocol XNP: XML Ninive Protocol.

So XML Socket server means that Ninive can interact with clients knowing XNP protocol, based on XML language.

The main purpose of Ninive is extending in the external resources domain software applications that can't directly write or get a resource from a location, in example for security policies. Through XML Ninive Protocol, a generic client can read a file, read a directory content, or write a file in a specific location; Ninive will perform this request, sending to client its response.
For its characteristics, Ninive can be useful as file system interface for applications written in Macromedia Flash environment.

^ back to index

General characteristics of Ninive Server

General characteristics of Ninive Server are:

^ back to index

Execution environment

Ninive execution environment is both Microsoft Windows generic 32 bit console and Linux console.

In Win32 environment, Ninive Server is an application, not a service; then, Ninive starts as any other application in your system, with a click of your mouse, or automatically at the booting phase if you insert it, or you insert a link of it, into Automatic Execution folder of your Start Panel.
Once activated, Ninive Server shows a console window containing OUT and ERR application streams. You can safely reduce to icon this window, if the server starts correctly.

In Linux environment, Ninive Server is a console executable invoking from shell or within shell scripts; in actual version, Ninive Server is not a daemon.
Once activated, Ninive Server sends its OUT and ERR application streams to the invoking shell.

Every error message will be sent to a log file, whose structure will be delineated on next paragraphs.

The Ninive package contains the entire source code to build Ninive Server in both environments. Please read INSTALL file, contained in the package, to correctly build and install Ninive Server according to your environment.

^ back to index

The Server

Ninive is a generic TCP Server: it build a socket and wait for connections at CPU 0%. The socket operates in blocking mode, so Ninive is still until a connection request.
Once a connection request is coming, Ninive server will handle it until a specific dropping request from client, or external events like error conditions, closing of client application, ecc. Unlike HTTP, the connection is not dropped by the server at the end of a response: every pair request-response use the same TCP connection.
Actually Ninive can handle only one TCP connection at a time.
User can modify some execution parameters of Ninive, like server port and connection timeout, changing relative values in the Ninive configuration file. Default server port is 1999, the year of Moon detach from Earth orbit.

^ back to index

Server Log

Ninive Server Log will be output to file ninive.log, created in the same directory of the server and reset every time the server boots, for avoiding an uncontrolled growing. Logged operations are:

• Connection request
• XNP violations
• Unsecure ending of connections
• Secure ending of connections

Ninive Server fault could be untrappable, so it can't generate a useful log.
Log file is ASCII, coded in proprietary format, and it's like this:

[time] msg

[time] contains date and hour of message emission.
[msg] is the message, made of an arbitrary sequence of ASCII bytes.

^ back to index

Ninive configuration file

Ninive configuration file is ninive_conf.xml, located in the same directory of Ninive server application and coded in XML; if missing, default values will be used.
Ninive distributions contain a configuration file whose parameters are set to server default; if you eliminate a parameter, Ninive server will use the corresponding default.
This is the configuration file distributed with any Ninive Server packages:

<?xml version="1.0" encoding="iso-8859-1"?>

<ninive version="2004.1">

<server>
<port>1999</port>
<timeout>60</timeout>
</server>

<welcome_linux>
Ninive ( Ninive Project Team - iUnknown.org) version 2004.1 successfully started.\n
Press CTRL+C if you want to shutdown Ninive.\n
</welcome_linux>

<welcome_mswin>
Ninive ( Ninive Project Team - iUnknown.org) version 2004.1 successfully started.\n
You can safely reduce to icon this window.\n
Close this window or press CTRL+C if you want to shutdown Ninive.\n
</welcome_mswin>

</ninive>

<port> element includes server listening port; default is 1999.

<timeout> element includes connection timeout in seconds before automatic dropping; default is 300 ( five minutes ). If no request is received from a client in this time interval, the connection is dropped.

<welcome_linux> element includes server boot message output in Linux enviroment, once correctly started. This message can contain escape sequences coded in C format, as '\t' or '\n'. Default is:

Ninive ( Ninive Project Team - iUnknown.org) version 1.0.0 successfully started.
Press ^C if you want to shutdown Ninive.

<welcome_mswin> element includes server boot message output in Win32 enviroment, once correctly started. This message can contain escape sequences coded in C format, as '\t' or '\n'. Default is:

Ninive ( Ninive Project Team - iUnknown.org) version 2004.1 successfully started.
You can safely reduce to icon this window.
Close this window or press CTRL+C if you want to shutdown Ninive.

^ back to index

XNP protocol

XNP protocol is the application level protocol in TCP/IP stack used by Ninive server and its clients. It has the following main characteristics:

• It relies on TCP protocol.
• It is based on XML, case-sensitive mode, using the only ASCII set of characters.
• It is based on request-response flow.
• It implements a minimal client certification sequence.
• It's not a secure protocol: it's an ASCII protocol easily viewed using a network sniffer.

General flow of protocol is request-response: the client sends a request to server, the server performs relative tasks and sends a response to client.

The generic structure of a request is:

<REQUEST ID=x>
<NAME param... >request</NAME>
<CONT>
...
</CONT>
</REQUEST>

The format is very simple: <NAME> element includes request type; its attributes are the parameters of request. Every request has a unique identification number, coded into value of attribute ID of element <REQUEST>, so client can identificate without hesitating relative server response, in asynchronous environment. This ID can be a progressive number, because it is relative to only one connection, then only one client.
Keep in mind that Ninive server does not control ID duplications: it inserts same ID of request into its relative response.
<CONT> element includes eventual extended data to send into request: this is an optional element and can be omitted if not necessary; in any case, Ninive server doesn't look for it, if the request does not explicitly foresee it.

The generic structure of a Server response is:

<RESPONSE ID=x>
<VALUE>cont</VALUE>
</RESPONSE>

Ninive server inserts the received ID of request into attribute ID of element <RESPONSE>, and inserts the physical response to client request into the element <VALUE>, without addictional parameters. The physical response can assume various formats, included XML; understanding and using the response is a client task.

In case of syntactical or semantical error, the request ID could not be inserted in response, if missing or incorrect. In these cases, Ninive server inserts the value -1.

XNP valid requests are:

• VALIDATE
• NOP
• READ
• WRITE
• SHUTDOWN

^ back to index

XNP - VALIDATE request

NAME:

VALIDATE

SYNOPSIS:

<REQUEST ID="x">
<NAME>VALIDATE</NAME>
</REQUEST>

DESCRIPTION:

VALIDATE request is the first request in absolute sense a client must send to Ninive server after connection opening; it represents the client certification request as host qualified to interact with a server through XNP protocol. If a client does not send this request, it will not be certified from Ninive server, and the connection will be automatically dropped on receiving any other request.
The attribute ID of element <REQUEST> includes the unique numeric ID of request, and it must be inserted from client.

SERVER RESPONSE:

If the request is syntactically and semantically correct, the response of Ninive server will be:

<RESPONSE ID="x">
<VALUE>
<XNP_SERVER author=".." server_version=".." xnp_version=".." />
VALIDATE OK!
</VALUE>
</RESPONSE>

server_version and xnp_version contain respectively Ninive server version and XNP version, in the format x.y.z. A client can compare its XNP implementation with server response to verify version disalignment.

In case of syntactical or semantical error, the server response will be:

<RESPONSE ID="x">
<VALUE>
<ERROR>error_explanation</ERROR>
</VALUE>
</RESPONSE>

<ERROR> element contains explanation about the impossibility of performing tasks related to request having ID number equal to value of attribute ID of element <RESPONSE>.

In case of any type of error, the connection will be dropped because the client is recognized as uncertified to continue.

^ back to index

XNP - NOP request

NAME:

NOP

SYNOPSIS:

<REQUEST ID="x">
<NAME>NOP</NAME>
</REQUEST>

DESCRIPTION:

NOP request is a notification of presence and activity of client sent to server to maintain active the TCP channel. Ninive server does not perform any task related to this request, except refresh its timeout time.
The attribute ID of element <REQUEST> includes the unique numeric ID of request, and it must be inserted from client.

SERVER RESPONSE:

If the request is syntactically and semantically correct, the response of Ninive server will be:

<RESPONSE ID="x">
<VALUE>NOP OK</VALUE>
</RESPONSE>

Timeout will be reinitialized in relation to epoch time of reception of NOP request.

In case of syntactical or semantical error, the server response will be:

<RESPONSE ID="x">
<VALUE>
<ERROR>error_explanation</ERROR>
</VALUE>
</RESPONSE>

<ERROR> element contains explanation about the impossibility of performing tasks related to request having ID number equal to value of attribute ID of element <RESPONSE>.

In case of any error, timeout will not be reinitialized.

^ back to index

XNP - READ request

NAME:

READ

SYNOPSIS:

<REQUEST ID="x">
<NAME type=".." filter=".." resource="..">READ</NAME>
</REQUEST>

DESCRIPTION:

READ request asks to Ninive Server to get data from a resource. Resource type and related format must be set as values of attributes type and resource, and can be:

filter attribute, used only if the resource type is dir, set a filter on directory entries. The format of this filter is:

(~)xx[\\...]

corresponding to one or more strings separated with terminator character '\\'. Every string is looked for into the name of any entry extracted from directory; if found, this entry is added to the list of entries to return to client. Tilde operator '˜' before a string applies the inverse filtering: an entry name that contains the string is not inserted into the list of entries to return to client. Every entry name is filtered: file and directory.
Filtering strings are processed through OR logical construct: so it's possible to insert multiple filtering strings without tilde operator for reducing the set of extracted entries, but it's not too correct, even if possible, to insert multiple filtering strings with tilde operator: in OR mode, in fact, a filter could be "all entries that does not contain 'x' OR not contain 'y'", that is, almost all directory entries as result.

The attribute ID of element <REQUEST> includes the unique numeric ID of request, and it must be inserted from client.

SERVER RESPONSE:

If the request is syntactically and semantically correct, the response of Ninive server will be:

Request of a resource of type dir:

<RESPONSE ID="x">
<VALUE>
<DIR path="..">
<FILE type="..">file</FILE>
...
</DIR>
</VALUE>
</RESPONSE>

path attribute of <DIR> element will contain the absolute path requested. Inside <DIR> element, there will be as many <FILE> elements as files into directory, after eventual filter operations. type attribute of <FILE> element indicates the file type; its possible values are:

• 'file': normal file
• 'dir': subdirectory entry

Request of a resource of type file:

<RESPONSE ID="x">
<VALUE>
<FILE name="..">
file_content
</FILE>
</VALUE>
</RESPONSE>

name attribute of <FILE> element will contain the file name with absolute path. The content of <FILE> element is the real file content, without any other formatting character.

In case of impossibility to get the resource, of any type it is, or in case of syntactical or semantical error, the server response will be:

<RESPONSE ID="x">
<VALUE>
<ERROR>error_explanation</ERROR>
</VALUE>
</RESPONSE>

<ERROR> element contains explanation about the impossibility of performing tasks related to request having ID number equal to value of attribute ID of element <RESPONSE>.

^ back to index

XNP - WRITE request

NAME:

WRITE

SYNOPSIS:

<REQUEST ID="x">
<NAME type=".." resource="..">WRITE</NAME>
<CONT>
resource_content
</CONT>
</REQUEST>

DESCRIPTION:

WRITE request asks the server to write data included into the <CONT> element, in the location equal to the value of attribute 'resource'. The type of resource is equal to the value of attribute 'type'; this type can only assume the value 'file'.
resource attribute contains the absolute path where to write data. Inside <CONT> element, there are ASCII data to write.
The attribute ID of element <REQUEST> includes the unique numeric ID of request, and it must be inserted from client.

SERVER RESPONSE:

If the request is syntactically and semantically correct, and the server has correctly processed it, the response of Ninive server will be:

<RESPONSE ID="x">
<VALUE>WRITE OK</VALUE>
</RESPONSE>

In case of impossibility to write the resource, of any type it is, or in case of syntactical or semantical error, the server response will be:

<RESPONSE ID="x">
<VALUE>
<ERROR>error_explanation</ERROR>
</VALUE>
</RESPONSE>

<ERROR> element contains explanation about the impossibility of performing tasks related to request having ID number equal to value of attribute ID of element <RESPONSE>.

^ back to index

XNP - SHUTDOWN request

NAME:

SHUTDOWN

SYNOPSIS:

<REQUEST ID="x">
<NAME>SHUTDOWN</NAME>
</REQUEST>

DESCRIPTION:

SHUTDOWN request notifies the server that the client is going to disconnect in secure mode from TCP channel, that is, correctly releasing its resource. Then, Ninive server can release in secure mode its connection. The final result of this request is the complete release of client-server connection, and the possibility, for Ninive server, to return listening to other connection requests.

The attribute ID of element <REQUEST> includes the unique numeric ID of request, and it must be inserted from client.

SERVER RESPONSE:

If the request is syntactically and semantically correct, the response of Ninive server will be:

<RESPONSE ID="x">
<VALUE>SHUTDOWN STARTED. AUREVOIR!</VALUE>
</RESPONSE>

Immediately after, the server detach the TCP connection to client.

In case of syntactical or semantical error, the server response will be:

<RESPONSE ID="x">
<VALUE>
<ERROR>error_explanation</ERROR>
</VALUE>
</RESPONSE>

<ERROR> element contains explanation about the impossibility of performing tasks related to request having ID number equal to value of attribute ID of element <RESPONSE>.

^ back to index