Differences

This shows you the differences between two versions of the page.

--- en:documentation:08_technical_reference:09_tentacle [2021/04/30 15:42]
admscopia
+++ en:documentation:08_technical_reference:09_tentacle [2023/05/16 08:31] (current)
@@ Line 5: / Line 5: @@
-====== About Tentacle ======
+===== About Tentacle =====
-Tentacle is a client/server file transfer protocol that is:
+{{  :wiki:pfms-tentacle-protocol-abstracting.png?nolink&  }}
+**Tentacle** is a [[https://pandorafms.com/blog/tentacle-protocol/|client/server file transfer protocol]] that is:
   * Safe by design.
@@ Line 12: / Line 15: @@
   * Versatile and cross-platform.
-Tentacle was created to replace more complex tools like SCP and FTP for simple file transfer/retrieval, and switch from less safe authentication systems like **.netrc**, as well as automated interactive logins with **expect**, and SSH keys, to start using a certification based on the standard X.509, using certificates.
+**Tentacle**  was created to replace more complex tools like [[https://en.wikipedia.org/wiki/Secure copy protocol|SCP]] / [[https://en.wikipedia.org/wiki/Secure Shell|SSH]] and [[https://en.wikipedia.org/wiki/File Transfer Protocol|FTP]] for simple file transfer/retrieval, and switch from less safe authentication systems like [[https://en.wikipedia.org/wiki/Berknet|.netrc]], as well as automated interactive logins with [[https://en.wikipedia.org/wiki/Expect|expect]], and SSH keys, to start using a certification based on the standard [[https://en.wikipedia.org/wiki/X.509|X.509]], using certificates.
-The client and server are designed to be run from the command line or called from a shellscript. Since [[https://pandorafms.com/blog/good-old-style-documentation-manpages/|2008]], Tentacle is the default file transfer method for Pandora FMS, replacing SCP.
+The client and server are designed to be run from the command line or called from a shellscript. Since [[https://pandorafms.com/blog/good-old-style-documentation-manpages/|2008]], **Tentacle**  is the default file transfer method for **Pandora FMS**, replacing SCP.
-Tentacle is implemented in Perl and ANSI C (Windows platforms included).
+Tentacle is implemented in [[https://en.wikipedia.org/wiki/Perl|Perl]] and [[https://en.wikipedia.org/wiki/ANSI C|ANSI C]] (MS Windows® platforms included).
 You can download it and find more information at the [[http://tentacled.sourceforge.net|official Sourceforge project website]].
-====== Documentation ======
+Quick access:
-  * [[Pandora:Documentation_en:Tentacle:UserGuide|**Tentacle User Guide GNU/Linux**]]
-  * [[Pandora:Documentation_en:Tentacle:WindowsGuide|**Tentacle Windows Guide**]]
+  * [[:en:documentation:08_technical_reference:09_tentacle#tentacle_user_guide|Tentacle User Guide]].
-  * [[Pandora:Documentation_en:Tentacle:Protocol|**Tentacle Protocol Definition**]]
+  * [[:en:documentation:08_technical_reference:09_tentacle#installing_perl_for_windows|Tentacle Windows Guide]].
-  * [[Pandora:Documentation_en:Tentacle:OpenSSLCertificates|**OpenSSL Certificates Quick Guide**]]
+  * [[:en:documentation:08_technical_reference:09_tentacle#tentacle_protocol_definition|Tentacle Protocol Definition]].
-  * [[en:quickguides:secure_communication_with_tentacle|**Secure communication with tentacle**]]
+  * [[:en:documentation:08_technical_reference:09_tentacle#openssl_certificates_quick_guide|OpenSSL Certificates Quick Guide]].
-  * [[Pandora:Documentation_en:Tentacle:CrossCompoling|**Cross-compiling the Windows client from Linux**]]
+  * [[:en:documentation:08_technical_reference:09_tentacle#communication_encryption|Secure communication with tentacle]].
+===== Tentacle User Guide =====
+==== Installing the PERL version ====
+=== Installing from Source Forge Net ===
+To install Tentacle server you must have rights equivalent to **root** user, after having installed it you may run it as a standard user.
+<WRAP center round download 90%>
+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/|https://sourceforge.net/projects/pandora/files/Tools%20and%20dependencies%20%28All%20versions%29/]]
+For example (you must have **wget** installed):
+<code>
+wget https://sourceforge.net/projects/pandora/files/Tools%20and%20dependencies%20%28All%20versions%29/tentacle_server-762.tar.gz
+</code>
+</WRAP>
+**Installing on Rocky Linux 8**
+   * Unzip the downloaded file with ''tar xzvf tentacle_server-762.tar.gz''  .
+  * Install the Perl language with ''dnf install perl''  .
+  * Enter the directory with ''cd tentacle''  .
+  * Install with ''./tentacle_server_installer –install''  .
+**Installing on CentOS 7**
+  * Unzip the downloaded file with ''tar xzvf tentacle_server-762.tar.gz''  .
+  * Install the Perl language ''yum install perl perl-IO-Compress zlib''  .
+  * Enter the directory with ''cd tentacle''  .
+  * Install with ''./tentacle_server_installer –install''  .
+=== Installing from SVN ===
+The process consists on downloading the source code through [[https://subversion.apache.org/|Apache® Subversion®]] (**svn**) and compile it. To that end, you will need to have admin or //root// rights (in this documentation they are the lines that start with the numeral character ''#'' ). **You** are the sole responsible for said key.
+To install **both** the client and the server version run:
+<file>
+ $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/ tentacle
+ $ cd tentacle
+ $ perl Makefile.PL
+ $ make
+ # make install
+</file>
+To install just the client, run:
+<file>
+ $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/client
+ $ cd client
+ $ perl Makefile.PL
+ $ make
+ # make install
+</file>
+To install just the server, run:
+<file>
+ $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/trunk/perl/server
+ $ cd server
+ $ perl Makefile.PL
+ $ make
+ # make install
+</file>
+If you want to install to a custom location, replace:
+<file>
+ $ perl Makefile.PL
+</file>
+by:
+<file>
+ $ perl Makefile.PL PREFIX=/ubication
+</file>
+=== Manual Installation ===
+If **make** is not available in your system, you can manually copy the files ''tentacle_client'' and ''tentacle_server'' to the appropriate place (for example, ''/usr/local/bin'').
+In this case, if the Perl binary is not located at ''/usr/bin/perl'' edit both files and change the first line so that it points to the right path where the Perl binary is. So, for instance, replace ''ubication'' by the Perl location in the system to be installed.
+<file>
+#!/ubication/perl
+</file>
+==== Installing the C version ====
+=== Installing from SVN ===
+Bearing in mind the prior section, to install the Tentacle client, run:
+<file>
+ $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/c/ tentacle
+ $ cd tentacle
+ $ ./configure
+ $ make
+ # make install
+</file>
+Make sure to check the configure output for errors, missing headers etc.
+To disable OpenSSL support, enabled by default, replace:
+<file>
+$ ./configure
+</file>
+by:
+<file>
+$ ./configure –disable-ssl
+</file>
+==== Tentacle use examples ====
+To see the available options, execute ''-h'' parameter, both in the client and server version:
+<file>
+$ 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:[email protected]:port).
+</file>
+<file>
+$ 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 opertions (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.)
+</file>
+Predefined values for all options will also be shown in the help section.
+For all of the following examples. the server is located at the address 192.168.1.1 and the client private key is not protected by pasword.
+  * Simple transfer of a file limited to a maximum of 1 megabyte and placed in ''/tmp'':
+<file>
+$ tentacle_server -m 1048576 -s /tmp -v
+$ tentacle_client -a 192.168.1.1 -v /home/user/myfile.dat
+</file>
+  * Simple transfer on port 65000 with overwrite mode enabled:
+<file>
+$ tentacle_server -o -p 65000 -s /tmp -v
+$ tentacle_client -a 192.168.1.1 -p 65000 -v /home/user/myfile.dat
+</file>
+  * Simple transfer with authentication based on password:
+<file>
+$ tentacle_server -x password -s /tmp -v
+$ tentacle_client -a 192.168.1.1 -x password -v /home/user/myfile.dat
+</file>
+  * Safe transfer, with no client certificate:
+<file>
+$ 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
+</file>
+  * Safe transfer with client certificate:
+<file>
+$ 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
+</file>
+  * Safe transfer with client certificate and additional authentication with password (notice the use of the connector ''\''  to make parameter writing easier):
+<file>
+$ 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
+</file>
+The Tentacle server allows its configuration through a plain text file. All command line options are available through said file. If the same configuration option is specified both in the file and the command line, the value indicated in the latter will have preference. The full path to the configuration file is indicated with the option ''-F''
+<file>
+$ tentacle_server -F /etc/tentacle/tentacle_server.conf
+</file>
+==== Tentacle Proxy ====
+The Tentacle server can act as a proxy, communicating many Tentacle clients to an inaccessible Tentacle server.
+The following diagram shows how the Tentacle proxy server works:
+{{  :wiki:pfms-tentacle-proxy_server.png  }}
+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:
+<file>
+$ tentacle_server -b 192.168.200.200 -g 65000
+</file>
+These parameters are** IP address** (''-b'') and **port** (''-g'') //of the unreachable tentacle server//. Also add the normal parameters on a single line:
+<file>
+$ tentacle_server -a 192.168.100.100 -p 45000 -b 192.168.200.200 -g 65000
+</file>
+<WRAP center round info 60%>The tentacle in proxy mode also supports authentication and encryption parameters.</WRAP>
+===== Installing PERL for Windows =====
+This brief guide is conceived to help configure and execute Tentacle client and server on MS Windows®.
+==== Installing Perl Version ====
+=== Installing Perl Environment ===
+Through ActiveState® download ActivePerl 5.8 through the following link [[https://www.activestate.com/products/downloads/|https://www.activestate.com/products/downloads/]] and execute the installer with the default options.
+=== Installing the module IO-Socket-SSL ===
+Download and install OpenSSL from:
+[[http://gnuwin32.sourceforge.net/packages/openssl.htm|http://gnuwin32.sourceforge.net/packages/openssl.htm]]
+Download the following perl modules:
+[[http://archive.apache.org/dist/perl/win32-bin/ppms/Net_SSLeay.pm.ppd|http://archive.apache.org/dist/perl/win32-bin/ppms/Net_SSLeay.pm.ppd]] [[http://archive.apache.org/dist/perl/win32-bin/ppms/IO-Socket-SSL.ppd|http://archive.apache.org/dist/perl/win32-bin/ppms/IO-Socket-SSL.ppd]]
+And run from the command prompt in the directory where the ''.ppd'' files are located:
+<file>
+ppm install Net_SSLeay.pm.ppd ppm install IO-Socket-SSL.ppd
+</file>
+=== Running the Tentacle Client and Server ===
+The execution is similar to that of systems Unix/Linux, just enter the Perl command at the beginning, followed by the whole syntax, for instance:
+<file>> perl tentacle_client -v c:\file> perl tentacle_server -q -s c:\tmp
+</file>
+===== Tentacle Protocol Definition =====
+The Tentacle protocol itself is very simple and straightforward. 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:
+<file>
+'?[]/\=+<>:;',*~'
+</file>
+ASCII sequence diagrams will be used to illustrate use cases. Commands are enclosed in single quotes.
+==== Sending Files ====
+A successful file transfer is shown first.
+{{  :wiki:pfms-tentacle-send_file.png  }}
+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.
+{{  :es:documentation:08_technical_reference:pfms-tentacle-recieve_error.png?663x229  }}
+[[:wiki:pfms-tentacle-error.png?id=en:documentation:08_technical_reference:09_tentacle&media=wiki:pfms-tentacle-error.png|{{  :wiki:pfms-tentacle-error.png?nolink&  }}]]
+==== Receiving Files ====
+Single files can be requested from the server.
+{{  :es:documentation:08_technical_reference:pfms-tentacle-recieve_file.png?659x404  }}
+The client has the 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** command. 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.
+{{  :es:documentation:08_technical_reference:pfms-tentacle-recieve_error.png?663x229  }}
+==== Password Authentication ====
+If the server requires a password, the client must authenticate before sending any other command.
+{{  :es:documentation:08_technical_reference:pfms-tentacle-autentication_warning_cipher_connection_.png?654x222  }}
+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-encrypted connections.
+==== 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.
+{{  :es:documentation:08_technical_reference:pfms-tentacle-error_manage.png?652x366  }}
+<WRAP center round info 60%>\\
+By default, the Tentacle log is configured at ''/dev/null''.\\
+</WRAP>
+===== OpenSSL Certificates Quick Guide =====
+This is just a quick guide that will get you started with OpenSSL certificates. See [[http://www.openssl.org/docs/|http://www.openssl.org/docs/]] for documentation.
+==== Creating a Certificate ====
+Preparing the environment:
+<file>
+$ mkdir demoCA
+$ mkdir demoCA/newcerts
+$ mkdir demoCA/private
+</file>
+<WRAP center round important 60%>
+Remember to set in place, for safety reasons, writing and reading permissions of the different users in your system in the recently created folders.
+</WRAP>
+The following step is make a self-signed CA certificate and move it to the created directories:
+<file>
+$ openssl req -new -x509 -keyout cakey.pem -out cacert.pem
+$ mv cakey.pem demoCA/private/
+$ mv cacert.pem demoCA/
+</file>
+Fill in the requested fields for the certificate and remember them because you will need them again later on, exactly the same ones. Now create a certificate request:
+<file>
+$ openssl req -new -keyout tentaclekey.pem -out tentaclereq.pem -days 360
+</file>
+Sign the certificate request, setting in addition a consecutive serial as a control and aduting system:
+<file>
+$ cat tentaclereq.pem tentaclekey.pem> tentaclenew.pem
+$ touch demoCA/index.txt
+$ echo "01">> demoCA/serial
+$ openssl ca -out tentaclecert.pem -in tentaclenew.pem
+</file>
+Bear on mind that if the [[https://www.openssl.org/docs/man1.0.2/man3/RAND_load_file.html|random load file]] presents some inconvenient, you may delete it with //root// user rights: ''sudo rm ~/.rnd''. That way it may be created again with your own writing and reading permissions. **You** are the sole responsible for said //root// key.
+==== Creating a Self-Signed Certificate ====
+<file>
+$ openssl req -new -x509 -keyout tentaclekey.pem -out tentaclecert.pem -days 360
+</file>
+==== Generating an RSA Private Key ====
+This is very useful to avoid having to enter a password on the client side using Tentacle.
+Generate the key:
+<file>
+$ openssl genrsa -out tentaclekey.pem
+</file>
+And replace ''-keyout'' with ''-key'' on the previous steps.
+==== Exporting certificate to another format ====
+Certificates can be required in DER format instead of PEM for some operative systems (such as Ubuntu® or Windows®). If that is the case, you may obatin the certificate of said format through the generated PEM:
+<file>
+openssl x509 -outform der -in tentaclecert.pem -out tentaclecert.der
+</file>
+===== Tentacle configuration guide with security options =====
+This guide will explain step by step how to configure both **Agent Software** and **Tentacle server** to ensure safe communication.
+First, it is recommended to carry out manual tests from the devices to make sure configuration, parameters and certificates are correct.
+Then configure permanently the according configuration files:
+**Tentacle servers**
+''/etc/tentacle/tentacle_server.conf''
+**Unix/Linux software agents**
+''/etc/pandora/pandora_agent.conf''
+**MS Windows® software agents**
+''%ProgramFiles%\pandora_agent\pandora_agent.conf''
+**Satellite servers**
+''ect/pandora/satellite_server.conf''
+**Tentacle Proxy servers**
+''/etc/tentacle/tentacle_server.conf''
+Remember to restart the according 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'' (you may check the rest of the options for said daemon [[:en:documentation:02_installation:04_configuration#tentacle_configuration|in this link]] ).
+==== Communication encryption ====
+Both the Tentacle server and the Software Agents can use a secure communication with certificates and password, either direct communication between both, or through a Tentacle Proxy server.
+<WRAP center round info 60%>It is **ALWAYS** necessary to indicate in the parameters the absolute paths where the certificates are located, e.g. ''/etc/ssl/tentaclecert.pem''
+</WRAP>\\
+<WRAP center round important 60%>To use Tentacle's secure options, please verify that the package ''perl(IO::Socket::SSL)'' //is installed on your system//.
+</WRAP>
+In the previous sections the various combinations are explained in detail; in this section the password options, Tentacle Proxy server and the use of ''TENTACLE_EXT_OPTS'' para fijar configuraciones. to set configurations are added. Also review in **this earlier section** the 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:
+<file>
+ -x password
+</file>
+Extra parameter in the client for password ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -x password
+</file>
+**Secure transfer, without client certificate:**
+Extra parameters on the server:
+<file>
+ -e tentacle_cert -k tentacle_key
+</file>
+**Secure transfer with customer certificate**
+Extra parameters on the server:
+<file>
+ -e tentacle_cert -k tentacle_key -f ca_cert
+</file>
+Extra parameters in the client ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -e tentacle_client_cert -k tentacle_client_key
+</file>
+**Secure transfer with client certificate and additional password authentication:**
+Extra parameters on the server:
+<file>
+ -x password -e tentacle_cert -k tentacle_key -f ca_cert
+</file>
+Extra parameters in the client ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -x password -e tentacle_client_cert -k tentacle_client_key
+</file>
+==== Certificate configuration in Tentacle server accepting any certificate in client ====
+For this configuration, just enter the certificate and key used for encryption in Tentacle server configuration.
+When laucnhing the **server** manually, include the parameters ''-e'' and ''-k'':
+<file>
+$ su - pandora -s /bin/bash
+# tentacle_server -v -e tentacle_cert -k tentacle_key -s /tmp
+</file>
+Launch in the **client** manually, include the ''-c'' parameter:
+<file>
+$ echo test> file.txt
+$ tentacle_client -v -c -a 192.168.70.125 file.txt
+</file>
+If this manual execution works properly, you may continue with the permanent configuration in the appropriate file:
+  * For** Tentacle servers**:
+<file>
+ssl_cert tentacle_cert
+ssl_key tentacle_key
+</file>
+  * For **Software Agents**:
+<file>
+server_opts -c
+</file>
+  * For** Satellite servers**:
+<file>
+server_opts -c
+</file>
+==== Tentacle server and client certificate configuration verifying the certificate with a specific CA in client ====
+For this configuration, indicate de certificate and key used for encryption in Tentacle server configuration and client encryption certificates.
+When launching the **server** manually, include the ''-e'' and ''-k'' [[:en:documentation:08_technical_reference:09_tentacle#tentacle_use_examples|parameters]]:
+<file>
+ # su - pandora -s /bin/bash
+ # tentacle_server -v -e tentacle_cert -k tentacle_key -s /tmp
+</file>
+When launching the **client** manually, include the ''-e'' and ''-f'' parameters:
+<file>
+ # echo test> file.txt
+ # tentacle_client -v -e tentacle_client_cert -f ca_cert -a 192.168.70.125 file.txt
+</file>
+If this manual execution works properly, permanent configuration will be possible in the appropriate file.
+  * For **Tentacle servers**:
+<file>
+ ssl_cert tentacle_cert
+ ssl_key tentacle_key
+</file>
+  * For Pandora FMS **Software Agents**:
+<file>
+server_opts -e tentacle_client_cert -f ca_cert
+</file>
+  * For Pandora FMS **Satellite servers**:
+<file>
+server_opts -e tentacle_client_cert -f ca_cert
+</file>
+==== Tentacle server and client certificate configuration verifying the certificate with a specific CA in server ====
+For this configuration, indicate the certificates and keys used for encryption in Tentacle server and client configuration.
+When launching the **server** manually, include the ''-e'', ''-k'' and ''-f'' parameters:
+<file>
+ # su - pandora -s /bin/bash
+ # tentacle_server -v -e tentacle_cert -k tentacle_key -f ca_cert -s /tmp
+</file>
+When launching the **client** manually, include the ''-e'' and ''-k'' parameters (notice the use of the line connector ''\'':
+<file>
+ # echo test> file.txt
+ # tentacle_client -v \
+            -e tentacle_client_cert \
+            -k tentacle_client_key \
+            -a 192.168.70.125 file.txt
+</file>
+If this manual execution works properly, permanent configuration will be possible in the appropriate file.
+  * For **Tentacle servers**:
+<file>
+ ssl_cert tentacle_cert
+ ssl_ca ca_cert
+ ssl_key tentacle_key
+</file>
+  * For Pandora FMS **Software Agents**:
+<file>
+server_opts -e tentacle_client_cert -k tentacle_client_key
+</file>
+  * For Pandora FMS **Satellite servers**:
+<file>
+server_opts -e tentacle_client_cert -k tentacle_client_key
+</file>
+==== Tentacle server and client certificate configuration verifying the certificate with a specific CA in both of them ====
+For this configuration, indicate the certificates and keys used for encryption in Tentacle server and client configuration.
+When launching the server manually, include the ''-e'', ''-k'' and ''-f'' parameters:
+<file>
+ # su - pandora -s /bin/bash
+ # tentacle_server -v -e tentacle_cert -k tentacle_key -f ca_cert -s /tmp
+</file>
+When launching the client manually, include the ''-e'', ''-k'' and ''-f'' parameters:
+<file>
+ # 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
+</file>
+If this manual execution works properly, permanent configuration will be possible.
+  * For **Tentacle servers**:
+<file>
+ ssl_cert tentacle_cert
+ ssl_ca ca_cert
+ ssl_key tentacle_key
+</file>
+  * For Pandora FMS **Software Agents**:
+<code>
+server_opts -e tentacle_client_cert -k tentacle_client_key -f ca_cert
+</code>
+  * For Pandora FMS **Satellite servers**:
+<code>
+server_opts -e tentacle_client_cert -k tentacle_client_key -f ca_cert
+</code>
+==== Safe Tentacle configuration ====
+Both the Tentacle server and the software agents can use safe communication through certificates and password, either directly between them or through a Tentacle Proxy.
+<WRAP center round important 60%>**ALWAYS** indicate in the parameters the absolute paths where the certificates are found, for example ''/etc/ssl/tentaclecert.pem''
+</WRAP>\\
+<WRAP center round important 60%>To use Tentacle safe options, please verify the package ''perl(IO::Socket::SSL)'' //is installed on your system//.
+</WRAP>
+\\
+In previous sections, the different combinations are explained in detail; in this section we add options such as password, Tentacle Proxy server and the use of ''TENTACLE_EXT_OPTS'' Check in the **previous section** the names of the certificates and the keys on each side. A simplified syntax is used just for learning purposes:
+**Simple transfer with password-based authentication:**
+Extra parameter in the server for password:
+<file>
+ -x password
+</file>
+Extra parameter in the client for password ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -x password
+</file>
+**Safe transfer, with no client certificate:**
+Extra server parameters:
+<file>
+ -e tentacle_cert -k tentacle_key
+</file>
+**Safe transfer with client certificate**
+Extra server parameters:
+<file>
+ -e tentacle_cert -k tentacle_key -f ca_cert
+</file>
+Extra client parameters  ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -e tentacle_client_cert -k tentacle_client_key
+</file>
+**Safe transfer with client certificate and additional authentication with password:**
+Extra server parameters:
+<file>
+ -x password -e tentacle_cert -k tentacle_key -f ca_cert
+</file>
+Extra client parameters ( ''TENTACLE_EXT_OPTS'' ):
+<file>
+ -x password -e tentacle_client_cert -k tentacle_client_key
+</file>
+=== Tentacle proxy safe configuration use case ===
+You are explained step by step how to configure both software agents as well as the Tentacle server for safe communication, using the Tentacle Proxy server too. Check out in the previous section the names of the certificates and the keys on each side. Check the available parameters in this section.
+**Manual tests:**
+. Start tentacle_server manually:
+<file>
+  sudo -u user tentacle_server \
+            -x password \
+            -e tentacle_cert \
+            -k tentacle_key \
+            -f ca_cert -s /tmp -v
+</file>
+. Start the proxy manually:
+<file>
+sudo -u user tentacle_server -b ip_server -g 41124
+</file>
+. Start tentacle_client manually:
+<file>
+  sudo -u user tentacle_client \
+             -a ip_proxy/ip_server \
+             -x password \
+             -e tentaclecert.pem \
+             -k tentaclekey.pem \
+             -v file
+</file>
+Once you have checked that the file was sent successfully, proceed to configure tentacle_server permanently as well as the clients.
+To configure tentacle_server with the certificate options, edite the starting script of the service **tentacle_serverd**, usually located at ''/etc/init.d/tentacle_serverd''. An intermidate point should be configured similarly to work as a proxy. To configure software agents to use Tentacle safe communication, edit the configuration files **pandora_agent.conf**, usually located at ''/etc/pandora/pandora_agent.conf''.
+**Permanent configuration:**
+. Start the server with SSL. Modify the booting script ''/etc/tentacle/tentacle_server.conf'' and uncomment and complete the lines ''password'', ''ssl_cert'', ''ssl_key'', ''ssl_ca'' with the valid values or paths for your certificate:
+{{  :wiki:pfms-etc-tentacle-tentacle_server_dot_conf.png  }}
+<WRAP center round tip 75%> Remember that each 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'' .
+</WRAP>\\
+. Start the proxy. As in the previous point number 1, modify the configuration file ''/etc/tentacle/tentacle_server.conf'' of the machine that is going to act as proxy. Also, uncomment and complete the lines ''proxy_ip'' y ''proxy_port'' with the configuration valid in your environment:
+{{  :wiki:pfms-etc-tentacle-tentacle_server_dot_conf_proxy.png  }}
+<WRAP center round tip 75%> Remember that each 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'' .
+</WRAP>
+. Start the Software Agent with the corresponding options. Modify the file ''pandora_agent.conf'', find the line ''server_opts'' and add:
+<file>
+-x password -e tentacle_client_cert -k tentacle_client_key
+</file>
+Remember that the //token// **server_ip** must be configurated pointing to Proxy's IP direction instead main server's IP direction:
+<code>
+server_opts -x password -e tentacle_client_cert -k tentacle_client_key
+</code>
+<WRAP center round tip 60%>\\
+If you do not want to use any of the options, such as the password, simply do not use the corresponding parameter.\\
+</WRAP>
+==== Tentacle data compression ====
+<WRAP center round tip 60%>\\
+Version NG 725 or superior.\\
+</WRAP>\\
+Tentacle allows enabling data compression with the option ''-z'' of the command line, reducing the size of the transferred data at the expense of the CPU load.
+=== Pandora FMS Agent ===
+Edit the file ''/etc/pandora/pandora_agent.conf'' and add ''-z'' to ''server_opts'':
+<file>
+server_opts -z
+</file>
+=== Satellite server ===
+Edit the file ''/etc/pandora/satellite_server.conf'' and add ''-z'' to ''server_opts'':
+<file>
+server_opts -z
+</file>
+===== Configuration file elements =====
+By default the Tentacle configuration file is located at ''/etc/tentacle/tentacle_server.conf''.
+<WRAP center round info 60%>
+Remember that each 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'' .
+</WRAP>
+==== addresses ====
+<code>
+# [-a] IPv4 address to listen on. Several IP address can be selected separating it by comma.
+addresses 0.0.0.0
+</code>
+  * IPv4 address where the Tentacle will listen. Several IP addresses can be separated by comma.
+  * Paramaeter equivalent by command line: ''-a''.
+==== port ====
+<code>
+# [-p] Port number to listen on
+port 41121
+</code>
+  * Port number where the Tentacle server will listen.
+  * Equivalent parameter by command line: ''-p''.
+==== max_connections ====
+<code>
+# [-c] Maximum number of simultaneous connections
+max_connections 10
+</code>
+  * Maximum number of simultaneous connections.
+  * Equivalent parameter by command line: ''-c''.
+==== daemon ====
+<code>
+# [-d] Run as daemon. 1 true, 0 false
+daemon 1
+</code>
+  * Execute as //[[:en:documentation:01_understanding:03_glossary|daemon]]// ''1'', otherwise ''0''.
+  * Equivalent parameter by command line: ''-d''.
+==== insecure ====
+<code>
+# [-I] Enable insecure mode
+insecure 0
+</code>
+  * Enable insecure mode ''1'', otherwise ''0''  (refers to operations such as listing files, etc.).
+  * Equivalent parameter by command line: ''-I''.
+==== filters ====
+<code>
+# Filters (regexp:dir;regexp:dir...)
+filters .*\.conf:conf;.*\.md5:md5;.*\.zip:collections;.*\.lock:trans;.*\.rcmd:commands
+</code>
+  * It allwos to set filters by file types in specfic directories. Add a regular expression (filter as such) separated by '':'' and the corresponding directory. To add another filter, separate with '';''.
+  * Equivalent parameter by command line: ''-i''.
+==== max_size ====
+<code>
+# [-m] Maximum file size allowed by the server in bytes
+max_size 2000000
+</code>
+  * Maximum file size allowed (in bytes).
+  * Equivalent parameter by command line: ''-m''.
+==== overwrite ====
+<code>
+# [-o] Accept files with a repeated name. 1 true, 0 false.
+overwrite 0
+</code>
+  * It allows to overwrite if the received file has the same name and already exists, disabled by default (''0''), to activate it, enter ''1''.
+  * Equivalent parameter by command line: ''-o''.
+==== quiet ====
+<code>
+# [-q] Do not output error messages.
+quiet 0
+</code>
+  * Avoid to show error messages; enabled ''1'', disabled ''0''.
+  * Equivalent parameter by command line: ''-q''.
+==== retries ====
+<code>
+# [-r] Number of retries for socket read/write operations
+retries 3
+</code>
+  * Number of retries for reading and writing operations.
+  * Equivalent parameter by command line: ''–r''.
+==== directory ====
+<code>
+# [-s] Storage directory
+directory /var/spool/pandora/data_in
+</code>
+  * Il allows to set the storage directory.
+  * Equivalent parameter by command line: ''-s''.
+==== proxy_ip ====
+<code>
+# [-b] IP address to proxy client requests to
+proxy_ip 127.0.0.1
+</code>
+  * It allows to set the IP address for an intermediary device (//proxy client//).
+  * Equivalent parameter by command line: ''-b''.
+==== proxy_port ====
+<code>
+# [-g] Port number to proxy client requests to
+proxy_port 41121
+</code>
+  * It allows to set the port number for an intermediate device (//proxy client//).
+  * Equivalent parameter by command line: ''-g''.
+==== timeout ====
+<code>
+# [-t] Timeout for socket read/write operations in seconds
+timeout 1
+</code>
+  * Expiration time in seconds dor reading and writing operations.
+  * Equivalent parameter by command line: ''-t''.
+==== verbose ====
+<code>
+# [-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
+</code>
+  * It sets the amount of information to be shown with debugging purposes.
+      * ''-v 0''  : No informative messages.
+      * ''-v 1''  o ''-v'': It only shows important messages.
+      * ''-v 2''  o ''-V'': It shows all messages.
+==== log_file ====
+<code>
+# [-l] Log file
+log_file /dev/null
+</code>
+  * It allows to set an event log.
+  * Equivalent parameter by command line: ''-l''.
+==== password ====
+<code>
+# [-x] Server password
+# password PASSWORD
+</code>
+  * It sets the password fot the Tentacle server.
+  * Equivalent parameter by command line: ''-x''.
+==== ssl_cert ====
+<code>
+# [-e] SSL certificate file full path
+# ssl_cert /path/to/ssl/cert
+</code>
+  * It allows to set the full path to the file that contains the SSL certificate.
+  * Equivalent parameter by command line: ''-e''.
+==== ssl_ca ====
+<code>
+# [-f] SSL CA file full path
+# ssl_ca /path/to/ssl/ca
+</code>
+  * It allows to set the full path to the file that contains the Cetifying Authority (CA) of the [[:en:documentation:08_technical_reference:09_tentacle#ssl_cert|SSL certificate]].
+  * Equivalent parameter by command line: ''-f''.
+==== ssl_key ====
+<code>
+# [-k] SSL private key file
+# ssl_key /path/to/private/key/file
+</code>
+  * Location of the file with the private key of the SSL certificate.
+  * Equivalent parameter by command line: ''-k''.
+==== ssl_password ====
+<code>
+# [-w] SSL password. Set to 1 to ask for password by command line
+# ssl_password 0
+</code>
+  * If the SSL certificate contains a password, it allows to request it (''1'') in the command line.
+  * Equivalent parameter by command line: ''-w''.
+==== use_libwrap ====
+<code>
+# [-T] Use libwrap library (Authen::Libwrap perl module). 1 true, 0 false
+# use_libwrap 0
+</code>
+  * For Perl language, it allows to use the module ''Authen::Libwrap''. Enabled ''1'', disabled ''0''.
+  * Equivalent parameter by command line: ''-T''.
+[[:en:documentation:start|Go back to Pandora FMS documentation index]]
-[[Category: Tentacle]]

ºº