Table of Contents

Tentacle protocol specifications

¿What is Tentacle?

Tentacle, a client/server file transfer tool, is:

Tentacle has been created to replace more complex tools such as SCP/SSH and FTP for simple file transfers and to move away from insecure authentication mechanisms such as .netrc , as well as automated interactive logins with expect and the SSH key mechanism, to an authentication based on the X.509 standard, using certificates.

The client and server are designed to be run from the command line, or called from a shell script. Tentacle is since 2008 the default transfer method for Pandora FMS, replacing SCP.

Tentacle is implemented in Perl and ANSI C (both platforms included in MS Windows®).

You may download it and learn more about it at the Official website of the project at SourceForge.

GNU Linux Tentacle User's Guide

Perl version installation

Installing from Source Forge Net

To install Tentacle server you must have rights equivalent to root user, after having installed it you will be able to run it as a standard user.

Get the file tentacle_server-762.tar.gz from Source Forge Net:

https://sourceforge.net/projects/pandora/files/Tools%20and%20dependencies%20%28All%20versions%29/

For example (you must have wget installed):

wget https://sourceforge.net/projects/pandora/files/Tools%20and%20dependencies%20%28All%20versions%29/tentacle_server-762.tar.gz

Installation on Rocky Linux 8

Installation on CentOS 7

Installation from SVN

The process consists of downloading the source code using Apache® Subversion® (svn) and compiling it. To do this you will need to have administrator or root rights (in this documentation it is the lines starting with the numeral character # ). You are solely responsible for this key.

To install both the client and server versions, run:

 $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/ tentacle
 $ cd tentacle
 $ perl Makefile.PL
 $ make
 # make install

To install only the client part run:

 $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/client
 $ cd client
 $ perl Makefile.PL
 $ make
 # make install

To install only the server part of the server run:

 $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/trunk/perl/server
 $ cd server
 $ perl Makefile.PL
 $ make
 # make install

If you want to install to a specific directory, replace:

 $ perl Makefile.PL

by:

 $ perl Makefile.PL PREFIX=/location

Manual installation

If make is not available on your system, you may install it manually by copying the tentacle_client and tentacle_server files to the appropriate directory (e.g. /usr/local/bin).

In this case, if the Perl binary is not located at /usr/bin/perl, edit both Tentacle files and change the first line so that it points to the correct path where your Perl binary is located. So, for example, replace location with the location of Perl on the system to install:

 #!/location/perl

Installing the C version

Installing from SVN

Taking into account the preamble to the installation of the previous section, to install the Tentacle client run:

 $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/c/ tentacle
 $ cd tentacle
 $ ./configure
 $ make
 # make install

Make sure that the output of the configure command does not generate any errors, incomplete header dependencies, etc..

To disable OpenSSL support, which is enabled by default, replace:

$ ./configure

by:

 $ ./configure --disable-ssl

Examples of Tentacle usage

To display the available options run with the -h parameter, both in the client and server versions:

$ tentacle_client -h
Usage: tentacle_client [options] [file] [file] ...

Tentacle client v0.4.0.

Options:
       -a address      Server address (default 127.0.0.1).
       -b localaddress Local address to bind.
       -c              Enable SSL without a client certificate.
       -e cert         OpenSSL certificate file. Enables SSL.
       -f ca           Verify that the peer certificate is signed by a ca.
       -g              Get files from the server.
       -h              Show help.
       -k key          OpenSSL private key file.
       -p port         Server port (default 41121).
       -q              Quiet. Do now print error messages.
       -r number       Number of retries for network operations (default 3).
       -t time         Time-out for network operations in seconds (default 1s).
       -v              Be verbose.
       -w              Prompt for OpenSSL private key password.
       -x pwd          Server password.
       -y proxy        Proxy server string (user:password@address:port).
$ tentacle_server -h
Usage: /usr/local/bin/tentacle_server -s <storage directory> [options]

Tentacle server v0.6.2. See https://pandorafms.com/docs/ for protocol description.

Options:
        -a ip_addresses IP addresses to listen on (default 0,0.0.0.0).
                        (Multiple addresses separated by comma can be defined.)
        -c number       Maximum number of simultaneous connections (default 10).
        -d              Run as daemon.
        -e cert         OpenSSL certificate file. Enables SSL.
        -f ca_cert      Verify that the peer certificate is signed by a ca.
        -F config_file  Configuration file full path.
        -h              Show help.
        -I              Enable insecure operations (file listing and moving).
        -i              Filters.
        -k key          OpenSSL private key file.
        -l log_file             File to write logs.
        -m size         Maximum file size in bytes (default 2000000b).
        -o              Enable file overwrite.
        -p port         Port to listen on (default 41121).
        -q              Quiet. Do now print error messages.
        -r number       Number of retries for network operations (default 3).
        -s Storage directory
        -S (install|uninstall|run) Manage the win32 service.
        -t time         Time-out for network operations in seconds (default 1s).
        -v              Be verbose (display errors).
        -V              Be verbose on hard way (display errors and other info).
        -w              Prompt for OpenSSL private key password.
        -x pwd          Server password.
        -b ip_address   Proxy requests to the given address.
        -g port         Proxy requests to the given port.
        -T              Enable tcpwrappers support.
                        (To use this option, 'Authen::Libwrap' should be installed.)

The default values for all options will also be shown in the Help.

For all the examples shown below, the server is located at address 192.168.1.1 and the client's private key is not password protected..

$ tentacle_server -m 1048576 -s /tmp -v
$ tentacle_client -a 192.168.1.1 -v /home/user/myfile.dat
$ tentacle_server -o -p 65000 -s /tmp -v
$ tentacle_client -a 192.168.1.1 -p 65000 -v /home/user/myfile.dat
$ tentacle_server -x password -s /tmp -v
$ tentacle_client -a 192.168.1.1 -x password -v /home/user/myfile.dat
$ tentacle_server -e cert.pem -k key.pem -w -s /tmp -v
$ tentacle_client -a 192.168.1.1 -c -v /home/user/myfile.dat
$ tentacle_server -e cert.pem -k key.pem -f cacert.pem -w -s /tmp -v
$ tentacle_client -a 192.168.1.1 -e cert.pem -k key.pem -v /home/user/myfile.dat
$ tentacle_server -x password -e cert.pem -k key.pem -f cacert.pem -w -s /tmp -v
$ tentacle_client \
  -a 192.168.1.1 \
  -x password \
  -e cert.pem \
  -k key.pem \
  -v /home/user/myfile.dat

The Tentacle server allows its configuration through a plain text file. All command line options are available through this file. If the same configuration option is specified in the file and on the command line, the value specified in the command line will take precedence. The full path to the configuration file is indicated by option -F.

$ tentacle_server -F /etc/tentacle/tentacle_server.conf

Tentacle Proxy

The Tentacle server can work as a proxy communicating many Tentacle clients to an inaccessible Tentacle server..

The following diagram shows how Tentacle's proxy server works:

The proxy does not have any information, but only sends the information from the clients to the Tentacle server. For example, to launch the Tentacle server in proxy mode use the following parameters:

$ tentacle_server -b 192.168.200.200 -g 65000

These parameters are IP address (-b) and port (-g) of the inaccessible tentacle server. Add, in addition, the normal parameters in a single line:

$ tentacle_server -a 192.168.100.100 -p 45000 -b 192.168.200.200 -g 65000

The Tentacle protocol in proxy mode also supports authentication and encryption parameters.

Tentacle Guide on MS Windows

Configure and run the Tentacle client and server on MS Windows®..

Perl version installation

Installation of the Perl environment

Using ActiveState® download ActivePerl 5.8 using the following link and run the installer with the default options:

Installation of the IO-Socket-SSL module

Download and install OpenSSL from:

Download the following Perl modules:

Execute from command line in the directory where the files are located .ppd:

> ppm install Net_SSLeay.pm.ppd> ppm install IO-Socket-SSL.ppd

Running the Tentacle client and server

the execution is similar to that of Unix/Linux systems, you only need to enter the Perl command first, followed by the full syntax, e.g.:

> perl tentacle_client -v c:\file> perl tentacle_server -q -s c:\tmp

Tentacle protocol definition

The Tentacle protocol itself is very simple and straightforward. Some important design features are:

'?[]/\=+<>:;',*~'

ASCII sequence diagrams will be used to illustrate the possible cases. Commands are shown in single quotes.

Send file(s)

A successful file transfer is displayed first

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

If the server rejects a file, a generic error message is sent back to the client. For security reasons, no details are shown as to why the command fails. This occurs when:

File receipt

Tentacle also supports file requests from the client.

The client has the opportunity to reject the file after the server informs about its size.

As with the “SEND” command, a new “RECV” command can be sent after a successful transfer (even if the file was rejected by the client) and always before the “QUIT” command. A generic error will be sent if the server refuses to send the file. The latter may take place when:

Password authentication

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

A double MD5 of the password will be sent to obfuscate. If you are working over an unencrypted connection, this does NOT implement or add any security. If you need security use SSL encrypted connections .

Error handling

In case of any error, the server will close the connection without explanation. This may be due to an incorrect command, an erroneous password, more data sent than was supposed to be sent, or any other reason that causes the server to operate outside of what is established or considered “normal”.

By default, the Tentacle log is set to /dev/null.

Quick guide to OpenSSL certificates

This is a quick start guide on OpenSSL certificates for use with Tentacle or other applications. For more information you may check the official website of the OpenSSL project:

Certificate creation

Environment preparation:

$ mkdir demoCA
$ mkdir demoCA/newcerts
$ mkdir demoCA/private

Remember to set, for security purposes, writing and reading permissions of the different users in your system on the newly created folders.

The next step is to make a self-signed CA certificate and move it into the created directories:

$ openssl req -new -x509 -keyout cakey.pem -out cacert.pem
$ mv cakey.pem demoCA/private/
$ mv cacert.pem demoCA/

Fill in the requested fields for the certificate and remember them well because they will be needed again later, exactly the same. Now create a certificate request:

$ openssl req -new -keyout tentaclekey.pem -out tentaclereq.pem -days 360

Sign the certificate request, also establishing a consecutive series of certificates as a control and auditing mechanism:

$ cat tentaclereq.pem tentaclekey.pem> tentaclenew.pem
$ touch demoCA/index.txt
$ echo "01">> demoCA/serial
$ openssl ca -out tentaclecert.pem -in tentaclenew.pem

Please note that if you submit the random seed file If there is any inconvenience, you may delete it with root user rights: sudo rm ~/.rnd. That way it can be created again with its own writing and reading rights. You are solely responsible for this root key.

Create a self-signed certificate

$ openssl req -new -x509 -keyout tentaclekey.pem -out tentaclecert.pem -days 360

Generate an RSA private key

This is very useful to avoid having to enter a password on the client side using Tentacle.

Generate key:

$ openssl genrsa -out tentaclekey.pem

And replace -keyout with -key in the previous sections.

Export certificate to another format

Certificates may be required in DER format instead of PEM for some operating systems (such as Ubuntu® or Windows®). If that is the case, the certificate can be obtained in that format from the generated PEM.:

openssl x509 -outform der -in tentaclecert.pem -out tentaclecert.der

Secure communication configuration with Tentacle

It explains step by step how to configure both Software Agents and Tentacle servers for secure communication.

First of all, it is highly recommended to test them manually from the terminals to ensure that the configuration, parameters and certificates are correct.

A permanent configuration can then be made in the respective configuration files:

Tentacle Servers

/etc/tentacle/tentacle_server.conf

Software Agents on Unix/Linux

/etc/pandora/pandora_agent.conf

MS Windows® Software Agents

%ProgramFiles%\pandora_agent\pandora_agent.conf

Satellite Servers

/etc/pandora/satellite_server.conf

Tentacle Proxy Servers

/etc/tentacle/tentacle_server.conf

Remember to restart the corresponding services after any modification. In the case of Unix/Linux you may also use the option TENTACLE_EXT_OPTS located at /etc/init.d/tentacle_serverd (see the rest of the options for this daemon in this link).

Communication encryption

In order to encrypt the communication between the clients and the Tentacle server, it will be necessary to have SSL certificates and keys. In this guide we will see all the possible configuration options, so the certificates can be either self-signed as signed by a valid CA.

To avoid misinterpretations in this article, certificates and keys on each side are identified with the following names:

It is ALWAYS necessary to indicate in the parameters the absolute paths where certificates are located, e.g. /etc/ssl/tentaclecert.pem

To use Tentacle's safe options, please check that the perl(IO::Socket::SSL) package is installed on your system.

Certificate configuration on Tentacle server accepting any certificate on the client

For this configuration you must specify the certificate and key used for encryption in the Tentacle server configuration..

Run manually on the server with parameters -e and -k:

$ su - pandora -s /bin/bash
# tentacle_server -v -e tentacle_cert -k tentacle_key -s /tmp

Execute manually on the client with the parameter -c.:

$ echo test> file.txt
$ tentacle_client -v -c -a 192.168.70.125 file.txt

If this manual execution works correctly, you may configure it permanently in the corresponding file:

ssl_cert tentacle_cert
ssl_key tentacle_key
server_opts -c
server_opts -c

Certificate configuration on the Tentacle server and on the client by verifying the certificate with a specific CA on the client.

For this configuration specify the certificate and key used for encryption in the Tentacle server configuration and the certificates used for encryption on the clients..

Run manually on the server with parameters -e and -k:

# su - pandora -s /bin/bash
# tentacle_server -v -e tentacle_cert -k tentacle_key -s /tmp

Execute manually on the client with parameter -e and -f:

# echo test> file.txt
# tentacle_client -v -e tentacle_client_cert -f ca_cert -a 192.168.70.125 file.txt

If this manual execution works correctly, you may configure it permanently in the corresponding file:

ssl_cert tentacle_cert
ssl_key tentacle_key
server_opts -e tentacle_client_cert -f ca_cert
server_opts -e tentacle_client_cert -f ca_cert

Certificate configuration on the Tentacle server and on the client by verifying the certificate with a specific CA on the server.

For this configuration specify the certificates and keys used for encryption in the configuration of the Tentacle server and clients..

Run manually on the server with the parameters -e, -k and -f:

# su - pandora -s /bin/bash
# tentacle_server -v -e tentacle_cert -k tentacle_key -f ca_cert -s /tmp

Manually run on the client with the -e and -k parameters (note the use of the \ line connector):

# echo test> file.txt
# tentacle_client -v \
           -e tentacle_client_cert \
           -k tentacle_client_key \
           -a 192.168.70.125 file.txt

If this manual execution works correctly, you may configure it permanently in the corresponding file:

ssl_cert tentacle_cert
ssl_ca ca_cert
ssl_key tentacle_key
server_opts -e tentacle_client_cert -k tentacle_client_key
server_opts -e tentacle_client_cert -k tentacle_client_key

Configuration of certificates on the Tentacle server and on the client by verifying the certificate with a specific CA in both

For this configuration specify the certificates and keys used for encryption in the configuration of the Tentacle server and clients.

Run manually on the server with the parameters -e, -k and -f:

# su - pandora -s /bin/bash
# tentacle_server -v -e tentacle_cert -k tentacle_key -f ca_cert -s /tmp

Execute manually on the client with the parameters -e, -k and -f:

# echo test> file.txt
# tentacle_client -v \
         -e tentacle_client_cert \
         -k tentacle_client_key \
         -f ca_cert \
         -a 192.168.70.125 file.txt

If this manual execution works correctly, you may configure it permanently in the corresponding file:

ssl_cert tentacle_cert
ssl_ca ca_cert
ssl_key tentacle_key
server_opts -e tentacle_client_cert -k tentacle_client_key -f ca_cert
server_opts -e tentacle_client_cert -k tentacle_client_key -f ca_cert

Secure configuration of Tentacle

Both the Tentacle server and the Software Agents can use secure communication with certificates and passwords, either direct communication between the two, or via a Tentacle Proxy server.

It is ALWAYS necessary to indicate in parameters the full paths where certificates are located, for instance /etc/ssl/tentaclecert.pem.

To use Tentacle's secure options, please verify that the perl(IO::Socket::SSL) package is installed on your system.

In the previous sections the different combinations are explained in detail; in this section the password options, Tentacle Proxy server and the use of TENTACLE_EXT_OPTS to set configurations are added. Also check this previous section for certificate names and keys on each side. A simplified syntax is used for didactic purposes only:

Simple transfer with password-based authentication:

Extra parameter in the server for password:

 -x password

Extra parameter in the client for password ( TENTACLE_EXT_OPTS ):

 -x password

Secure transfer, without client certificate:

Extra parameters on the server:

 -e tentacle_cert -k tentacle_key

Secure transfer with client certificate

Extra parameters on the server:

 -e tentacle_cert -k tentacle_key -f ca_cert

Extra parameters on the client ( TENTACLE_EXT_OPTS ):

 -e tentacle_client_cert -k tentacle_client_key

Secure transfer with client certificate and additional password authentication:

Extra parameters on the server:

 -x password -e tentacle_cert -k tentacle_key -f ca_cert

Extra parameters on the client ( TENTACLE_EXT_OPTS ):

 -x password -e tentacle_client_cert -k tentacle_client_key

Secure setup use case with Tentacle proxy

It explains step by step how to configure both the Software Agents and the Tentacle server for secure communication, also using a Tentacle Proxy server.

Manual tests:

1. Start tentacle_server manually:

 sudo -u //user//  tentacle_server \
           -x password \
           -e tentacle_cert \
           -k tentacle_key \
           -f ca_cert -s /tmp -v

2. Start proxy manually:

 sudo -u //user//  tentacle_server -b //ip_server//
  -g 41124

3. Start tentacle_client manually:

 sudo -u //user//  tentacle_client \
            -a //ip_proxy/ip_server//  \
            -x password \
            -e tentaclecert.pem \
            -k tentaclekey.pem \
            -v //file//

Once you have verified that file submission was successful, you may proceed to permanently configure the tentacle_server and clients.

To configure the tentacle_server with the certificate options, edit the tentacle_serverd service configuration file, commonly located at /etc/tentacle/tentacle_server.conf, the same to configure an intermediate point to work as a proxy. To configure Software Agents to use Tentacle safe communication, edit the pandora_agent.conf configuration files, commonly located at /etc/pandora/pandora_agent.conf.

Permanent settings:

1. Start the server with SSL. Modify the configuration file /etc/tentacle/tentacle_server.conf and uncomment and complete the lines password, ssl_cert, ssl_key, ssl_ca with the values or the valid paths for your certificate:

Remember that every time you make changes to the Tentacle configuration file, it is necessary to restart the service for the changes to take effect: /etc/init.d/tentacle_serverd start .

2. Start the proxy. As in previous point number 1, modify the configuration file /etc/tentacle/tentacle_server.conf of the machine that will act as proxy. Likewise, uncomment and complete the proxy_ip and proxy_port lines with the valid configuration in your environment:

Remember that every time you make changes to the Tentacle configuration file, it is necessary to restart the service for the changes to take effect: /etc/init.d/tentacle_serverd start .

3. Start the Software Agent with the corresponding options. Modify the file pandora_agent.conf, look for the line server_opts and add:

-x password -e tentacle_client_cert -k tentacle_client_key

Remember that the server_ip token should be set to point to the proxy's IP instead of the main server's. It would look like this:

server_opts -x password -e tentacle_client_cert -k tentacle_client_key

If you do not want to use any of the options, such as the password, simply do not use the corresponding parameter.

Data compression in Tentacle

Version NG 725 or higher.

Tentacle allows you to enable data compression in transit with the -z command line option, reducing the size of transferred data at the expense of CPU load.

Pandora FMS Agent

Edit the file /etc/pandora/pandora_agent.conf and add -z to server_opts:

server_opts -z

Satellite server

Edit the file /etc/pandora/satellite_server.conf and add -z to server_opts:

server_opts -z

Configuration file elements

By default the Tentacle configuration file is located in /etc/tentacle/tentacle_server.conf.

Remember that every time you make changes to the Tentacle configuration file, you need to restart the service for the changes to take effect: /etc/init.d/tentacle_serverd start .

addresses

# [-a] IPv4 address to listen on. Several IP address can be selected separating it by comma.
addresses 0.0.0.0

port

# [-p] Port number to listen on
port 41121

max_connections

# [-c] Maximum number of simultaneous connections
max_connections 10

daemon

# [-d] Run as daemon. 1 true, 0 false
daemon 1

insecure

# [-I] Enable insecure mode
insecure 0

filters

# Filters (regexp:dir;regexp:dir...)
filters .*\.conf:conf;.*\.md5:md5;.*\.zip:collections;.*\.lock:trans;.*\.rcmd:commands

max_size

# [-m] Maximum file size allowed by the server in bytes
max_size 2000000

overwrite

# [-o] Accept files with a repeated name. 1 true, 0 false.
overwrite 0

quiet

# [-q] Do not output error messages.
quiet 0

retries

# [-r] Number of retries for socket read/write operations
retries 3

directory

# [-s] Storage directory
directory /var/spool/pandora/data_in

proxy_ip

# [-b] IP address to proxy client requests to
proxy_ip 127.0.0.1

proxy_port

# [-g] Port number to proxy client requests to
proxy_port 41121

timeout

# [-t] Timeout for socket read/write operations in seconds
timeout 1

verbose

# [-v and -V] Verbose level
#   0: Do not display any informative messages
#   1: Display only important messages [-v]
#   2: Display all messages [-V]
verbose 0

log_file

# [-l] Log file
log_file /dev/null

password

# [-x] Server password
# password PASSWORD

ssl_cert

# [-e] SSL certificate file full path
# ssl_cert /path/to/ssl/cert

ssl_ca

# [-f] SSL CA file full path
# ssl_ca /path/to/ssl/ca

ssl_key

# [-k] SSL private key file
# ssl_key /path/to/private/key/file

ssl_password

# [-w] SSL password. Set to 1 to ask for password by command line
# ssl_password 0

use_libwrap

# [-T] Use libwrap library (Authen::Libwrap perl module). 1 true, 0 false
# use_libwrap 0

ssl_version

# [-z] Restrict to a specific ssl version
# ssl_version TLSv1_3

ssl_cipher

# [-u] Restrict to a specific ssl cipher
#ssl_cipher AES256-SHA

Return to Pandora FMS documentation index