Difference between revisions of "Pandora: Documentation en: Tentacle: UserGuide"

From Pandora FMS Wiki
Jump to: navigation, search
(GitLab ticket # 6607.)
(Installing from SVN)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Pandora:Documentation_en|Go back to Pandora FMS documentation index]]
+
[[Pandora:Documentation_en:Tentacle|Go back to Tentacle documentation index]]<br><br><br>
  
 
+
= Documentation =
= About Tentacle =
 
 
 
Tentacle is a client/server file transfer protocol that is:
 
 
 
* Secure by design.
 
* Easy to use.
 
* Versatile and cross-platform.
 
 
 
Tentacle was created to replace more complex tools like SCP and FTP for simple file transfer/retrieval, and switch from authentication mechanisms like '''.netrc''', automated interactive logins with expect, and SSH keys to X.509 certificates.
 
 
 
The client and server are designed to be run from the command line or called from a shell script, and no configuration files are needed.
 
 
 
Since [https://pandorafms.com/blog/good-old-style-documentation-manpages/ 2008], Tentacle is the default file transfer method for Pandora FMS
 
 
 
Tentacle is implemented in Perl and ANSI C (Windows platforms included).
 
 
 
You can download it and get more information at the [http://tentacled.sourceforge.net official Sourceforge website].
 
 
 
== Documentation ==
 
  
 
* '''Tentacle User Guide GNU/Linux''' (this guide).
 
* '''Tentacle User Guide GNU/Linux''' (this guide).
Line 27: Line 8:
 
* [[Pandora:Documentation_en:Tentacle:OpenSSLCertificates|'''OpenSSL Certificates Quick Guide''']]
 
* [[Pandora:Documentation_en:Tentacle:OpenSSLCertificates|'''OpenSSL Certificates Quick Guide''']]
 
*[[Pandora:QuickGuides_EN:Secure_communication_with_tentacle|'''Secure communication with tentacle''']]
 
*[[Pandora:QuickGuides_EN:Secure_communication_with_tentacle|'''Secure communication with tentacle''']]
* [[Pandora:Documentation_en:Tentacle:CrossCompoling|'''Cross-compiling the Windows client from Linux''']]
+
* [[Pandora:Documentation_en:Tentacle:CrossCompoling|'''Cross-compiling the Windows client from Linux''']]<br><br><br>
  
 +
= Tentacle User Guide =
  
  
= Tentacle User Guide =
+
==Installing Tentacle==
 
 
{{WIP}}
 
  
 
== Installing the PERL version ==
 
== Installing the PERL version ==
Line 39: Line 19:
 
=== Installing from SVN ===
 
=== Installing from SVN ===
  
To install '''both''' the client and the server run:
+
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 <code>#</code> ). '''You''' are the sole responsible for said key.
 +
 
 +
To install '''both''' the client and the server version run:
  
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/ tentacle
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/ tentacle
Line 47: Line 29:
 
  # make install
 
  # make install
  
To install just the '''client''' run:
+
To install just the '''client''', run:
 
   
 
   
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/client
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/client
Line 55: Line 37:
 
  # make install
 
  # make install
  
To install just the '''server''' run:
+
To install just the '''server''', run:
 
   
 
   
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/server
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/perl/server
Line 63: Line 45:
 
  # make install
 
  # make install
  
If you want to install to a custom location, substitute:
+
If you want to install to a custom location, replace:
  
 
  $ perl Makefile.PL
 
  $ perl Makefile.PL
  
with:
+
by:
  
 
  $ perl Makefile.PL PREFIX=/custom/location
 
  $ perl Makefile.PL PREFIX=/custom/location
  
A '''#''' means you need root privileges to run the command that follows.
 
  
=== Manual Install ===
+
=== 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'').
+
If '''make''' is not available in your system, you can manually copy the files <code>tentacle_client</code> and <code>tentacle_server</code> to the appropriate place (for example, <code>/usr/local/bin</code>).
  
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 location.
+
In this case, if the Perl binary is not located at <code>/usr/bin/perl</code> 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 <code>ubication</code> by the Perl location in the system to be installed.
  
=== IPv6 support ===
+
#!/ubication/perl
  
Tentacle also supports IPv6.
 
When you want to use IPv6 connection, the perl module 'IO::Socket::INET6' should be installed.
 
If it is not installed, IPv6 support is disabled (tentacle supports IPv4 only).
 
  
 
== Installing the C version ==
 
== Installing the C version ==
Line 89: Line 67:
 
=== Installing from SVN ===
 
=== Installing from SVN ===
  
To install the Tentacle client run:
+
Bearing in mind the prior [[Pandora:Documentation_en:Tentacle:UserGuide#Installing_the_PERL_version|section]], to install the Tentacle client, run:
  
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/c/ tentacle
 
  $ svn co http://svn.code.sf.net/p/tentacled/code/trunk/c/ tentacle
Line 97: Line 75:
 
  # make install
 
  # make install
  
Be sure to check the configure output for errors, missing headers etc.
+
Make sure to check the configure output for errors, missing headers etc.
  
To disable OpenSSL support, enabled by default if the OpenSSL development libraries are found, substitute:
+
To disable OpenSSL support, enabled by default, replace:
  
 
  $ ./configure
 
  $ ./configure
  
with:
+
by:
  
 
  $ ./configure --disable-ssl
 
  $ ./configure --disable-ssl
  
A '''#''' means you need root privileges to run the command that follows.
+
== Tentacle use examples ==
  
== Sample Usage ==
+
To see the available options, execute <code>-h</code> parameter, both in the client and server version:
  
To view all the options available run:
+
$ 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).
  
$ tentacle_client -h
 
 
  $ tentacle_server -h
 
  $ tentacle_server -h
 +
Usage: tentacle_server -s <storage directory> [options]
 +
 +
Tentacle server v0.5.0.
 +
 +
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.
 +
        -h              Show help.
 +
        -i              Filters.
 +
        -k key          OpenSSL private key file.
 +
        -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 (install|uninstall|run) Manage the win32 service.
 +
        -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.
 +
        -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.)
  
Default values for all options will be shown.
+
Predefined values for all options will also be shown in the help section.
  
For all the examples below, the server is located at address 192.168.1.1 and the client private key file is not password protected.
+
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 file transfer with maximum file size set to 1MB:
+
* Simple transfer of a file limeted to a maximum of 1 megabyte and  placed in <code>/tmp</code>:
  
 
  $ tentacle_server -m 1048576 -s /tmp -v
 
  $ tentacle_server -m 1048576 -s /tmp -v
  $ tentacle_client -a 192.168.1.1 -v /bin/bash
+
  $ tentacle_client -a 192.168.1.1 -v /home/user/myfile.dat
  
Simple file transfer on port 65000 with file overwrite enabled:
+
* Transferencia simple en el puerto 65000 con el modo de sobreescritura activado:
  
 
  $ tentacle_server -o -p 65000 -s /tmp -v
 
  $ tentacle_server -o -p 65000 -s /tmp -v
  $ tentacle_client -a 192.168.1.1 -p 65000 -v /bin/bash
+
  $ tentacle_client -a 192.168.1.1 -p 65000 -v /home/user/myfile.dat
  
Simple file transfer with password authentication (not secure):
+
* Simple transfer with authentication based on password:
  
 
  $ tentacle_server -x password -s /tmp -v
 
  $ tentacle_server -x password -s /tmp -v
  $ tentacle_client -a 192.168.1.1 -x password -v /bin/bash
+
  $ tentacle_client -a 192.168.1.1 -x password -v /home/user/myfile.dat
  
Secure file transfer without client certificate:
+
* Safe transfer, with no client certificate:
  
 
  $ tentacle_server -e cert.pem -k key.pem -w -s /tmp -v
 
  $ tentacle_server -e cert.pem -k key.pem -w -s /tmp -v
  $ tentacle_client -a 192.168.1.1 -c -v /bin/bash
+
  $ tentacle_client -a 192.168.1.1 -c -v /home/user/myfile.dat
  
Secure file transfer with client certificate:
+
* Safe transfer with client certificate:  
  
 
  $ tentacle_server -e cert.pem -k key.pem -f cacert.pem -w -s /tmp -v
 
  $ 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 /bin/bash
+
  $ tentacle_client -a 192.168.1.1 -e cert.pem -k key.pem -v /home/user/myfile.dat
  
Secure file transfer with client certificate and password authentication:
+
* Safe transfer with client certificate and additional authentication with password (notice the use of the connector <code>\</code> to make parameter writing easier):
  
 
  $ tentacle_server -x password -e cert.pem -k key.pem -f cacert.pem -w -s /tmp -v
 
  $ 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 /bin/bash
+
  $ tentacle_client \
 +
  -a 192.168.1.1 \
 +
  -x password \
 +
  -e cert.pem \
 +
  -k key.pem \
 +
  -v /home/user/myfile.dat
  
Save .xml and .log files in different subdirectories:
+
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 <code>-F''</code>.
 
 
$ tentacle_server -v -s /tmp -i'.*\.xml:xml_dir;.*\.log:log_dir'
 
$ tentacle_client -a 192.168.1.1 -v xml_file.xml
 
$ tentacle_client -a 192.168.1.1 -v log_file.log
 
 
 
Connect through an HTTP proxy with authentication:
 
 
 
$ tentacle_server -s /tmp -v
 
$ tentacle_client -a 192.168.1.1 -y user:[email protected]:8080 -v /bin/bash
 
 
 
Bind multiple addresses (::1 of IPv6 and 192.168.1.1 of IPv4):
 
 
 
$ tentacle_server -a ::1,192.168.1.1 -s /tmp -v
 
 
 
El servidor de Tentacle permite su configuración mediante un fichero de texto plano. Todas las opciones de linea de comandos están disponibles a través de este archivo. Si se especifica una misma opción de configuración en el ficher y en línea de comandos, tendrá preferencia el valor indicado en esta última. La ruta completa al fichero de configuración se indica con la opción ''-F''.
 
  
 
  $ tentacle_server -F /etc/tentacle/tentacle_server.conf
 
  $ tentacle_server -F /etc/tentacle/tentacle_server.conf
Line 171: Line 187:
 
== Tentacle Proxy ==
 
== Tentacle Proxy ==
  
Tentacle server can run as a proxy communicating a lot of tentacle clients to an unaccesible tentacle server.  
+
Tentacle server can run as a proxy communicating a lot of tentacle clients to an unaccessible tentacle server.  
  
 
The next diagram shows how tentacle proxy works.
 
The next diagram shows how tentacle proxy works.
Line 201: Line 217:
 
  $ tentacle_server -b 192.168.200.200 -g 65000
 
  $ tentacle_server -b 192.168.200.200 -g 65000
  
These new parameters are '''IP address''' ('''-b''') and '''port''' ('''-g''') of unaccesible tentacle server.
+
These new parameters are '''IP address''' (<code>-b</code>) and '''port''' (<code>-g</code>) of unaccessible tentacle server. In addition, add the normal parameters in a single line:
  
Of course you can set the IP address and port for incoming data in a normal way:
+
$ tentacle_server -a 192.168.100.100 -p 45000 -b 192.168.200.200 -g 65000
  
$ tentacle_server -a 192.168.100.100 -p 45000 -b 192.168.200.200 -g 65000
+
{{Tip|Tentacle in ''proxy'' mode also supports [[Pandora:QuickGuides_EN:Secure_communication_with_tentacle#Tentacle_configuration_guide_with_security_options|'''authentication''' and '''encryption''' parameters]].}}
  
'''*NOTE''': Tentacle proxy now supports '''authentication''' and '''encryption''' features!!
+
[[Pandora:Documentation_en:Tentacle|Go back to Tentacle documentation index]]<br><br><br>
  
 
[[Category: Tentacle]]
 
[[Category: Tentacle]]

Latest revision as of 09:33, 6 April 2021

Go back to Tentacle documentation index


1 Documentation

2 Tentacle User Guide

2.1 Installing Tentacle

2.2 Installing the PERL version

2.2.1 Installing from SVN

The process consists on downloading the source code through 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:

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

To install just the client, run:

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

To install just the server, run:

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

If you want to install to a custom location, replace:

$ perl Makefile.PL

by:

$ perl Makefile.PL PREFIX=/custom/location


2.2.2 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.

#!/ubication/perl


2.3 Installing the C version

2.3.1 Installing from SVN

Bearing in mind the prior 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 to check the configure output for errors, missing headers etc.

To disable OpenSSL support, enabled by default, replace:

$ ./configure

by:

$ ./configure --disable-ssl

2.4 Tentacle use examples

To see the available options, execute -h parameter, both in the client and server version:

$ 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).
$ tentacle_server -h
Usage: tentacle_server -s <storage directory> [options]

Tentacle server v0.5.0.

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.
       -h              Show help.
       -i              Filters.
       -k key          OpenSSL private key file.
       -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 (install|uninstall|run) Manage the win32 service.
       -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.
       -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.)

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 limeted to a maximum of 1 megabyte and placed in /tmp:
$ tentacle_server -m 1048576 -s /tmp -v
$ tentacle_client -a 192.168.1.1 -v /home/user/myfile.dat
  • Transferencia simple en el puerto 65000 con el modo de sobreescritura activado:
$ tentacle_server -o -p 65000 -s /tmp -v
$ tentacle_client -a 192.168.1.1 -p 65000 -v /home/user/myfile.dat
  • Simple transfer with authentication based on password:
$ tentacle_server -x password -s /tmp -v
$ tentacle_client -a 192.168.1.1 -x password -v /home/user/myfile.dat
  • Safe transfer, with no client certificate:
$ 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
  • Safe transfer with client certificate:
$ 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
  • Safe transfer with client certificate and additional authentication with password (notice the use of the connector \ to make parameter writing easier):
$ 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 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.

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

2.5 Tentacle Proxy

Tentacle server can run as a proxy communicating a lot of tentacle clients to an unaccessible tentacle server.

The next diagram shows how tentacle proxy works.

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

As you can see the proxy does not have any information it only forward data from the clients to the tentacle server.

To launch tentacle server in proxy mode you should type:

$ tentacle_server -b 192.168.200.200 -g 65000

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

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

Info.png

Tentacle in proxy mode also supports authentication and encryption parameters.

 


Go back to Tentacle documentation index