Pandora: Documentation en: Tentacle: Protocol

From Pandora FMS Wiki
Jump to: navigation, search

1 Tentacle Protocol Definition

The Tentacle protocol itself is very simple and straightforward. It uses 41121 TCP port (IANA officially assigned port: http://www.iana.org/assignments/port-numbers).

Some important characteristics are:

  • Communication is always initiated from the client side.
  • Commands are always terminated by a newline character.
  • The following characters can not be part of a file name: '?[]/\=+<>:;',*~'

ASCII sequence diagrams will be used to illustrate use cases. Commands are enclosed in single quotes.

1.1 Sending Files

A successful file transfer is shown first.

+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +-------'SEND <file> SIZE size\n'---->>>+
         |                                       |
         +<<<-----------'SEND OK\n'--------------+
         |                                       |
         +-----------------data--------------->>>+
         |                                       |
         +-----------------data--------------->>>+
         |                                       |
         +-----------------data--------------->>>+
         |                                       |
         +<<<-----------'SEND OK\n'--------------+
         |                                       |
         +---------------'QUIT\n'------------->>>+
         |                                       |
         .                                       .

To allow multiple file transfers within the same session, a new 'SEND' command may be sent after a successful file transfer and before a 'QUIT'.

If the server refuses to accept a file, a generic error message is sent back to the client. For security reasons, no details are provided. This happens if the file:

  • Has an invalid file name, or a path is specified.
  • Is empty or exceeds the server's maximum allowed size.
  • Already exists on the server and file overwrite is not enabled.
+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +-------'SEND <file> SIZE size\n'---->>>+
         |                                       |
         +<<<-----------'SEND ERR\n'-------------+
         |                                       |
         .                                       .

1.2 Receiving Files

Single files can be requested from the server.

+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +------------'RECV <file>\n'--------->>>+
         |                                       |
         +<<<--------'RECV SIZE size\n'----------+
         |                                       |
         +--------------'RECV OK\n'----------->>>+
         |                                       |
         +<<<--------------data------------------+
         |                                       |
         +<<<--------------data------------------+
         |                                       |
         +<<<--------------data------------------+
         |                                       |
         +---------------'QUIT\n'------------->>>+
         |                                       |
         .                                       .

The client has a chance to reject the file after the server reports its size.

As with 'SEND', a new 'RECV' command may be sent after a successful file retrieval (even if the file was rejected by the client) and before a 'QUIT', and a generic error message is sent if the server refuses to send the file. The latter happens if the file:

  • Has an invalid file name, or a path is specified.
  • Does not exist on the server.
+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +------------'RECV <file>\n'--------->>>+
         |                                       |
         +<<<-----------'RECV ERR\n'-------------+
         |                                       |
         .                                       .

1.3 Password Authentication

If the server requires a password, the client must authenticate before sending any other command.

+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +----------'PASS pwd_digest\n'------->>>+
         |                                       |
         +<<<-----------'PASS OK\n'--------------+
         |                                       |
         .                                       .

A double md5 of the password is sent to hide the actual password, but bear in mind that this does NOT add any extra security under an unencrypted connection. If you need secure file transfers always enable SSL.

1.4 Error Handling

Under any error condition the server will shut down the connection without giving any explanation. Be it because of a bad command, a bad password, more data than that reported being sent etc.

+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +-------------'[email protected]#$%&/()=?¿'--------->>>+
         |                                       |
         .                                       .
+-----------------+                     +-----------------+
| Tentacle client |                     | Tentacle server |
+-----------------+                     +-----------------+
         |                                       |
         +---------'PASS bad_pwd_digest'------>>>+
         |                                       |
         .                                       .