/ 
Rex-Endpoint-HTTP-0.35.0
River stage zero No dependents
/ Rex::Endpoint::HTTP

NAME

Rex::Endpoint::HTTP - Execute Rex over HTTP

DESCRIPTION

This is a replacement for the default SSH endpoint of Rex.

DEPENDENCIES

  • Mojolicious

  • Digest::SHA

CONFIGURATION

Configuration File

rex_endpoint_http search at multiple locations for the configuration file. In this file you can define a user database file and configure the build in webserver (hypnotoad from Mojolicious).

  • /etc/rex/httpd.conf

  • /usr/local/etc/rex/httpd.conf

  • ./httpd.conf

The format of the file is a Perl Hash Reference. So you have to start and end the file with braces.

{
   key1 => "value1",
   key2 => "value2",
};

Configure Hypnotoad

As a default hypnotoad listens on every device on port 8080 without encryption. This is a thing you want to change on production servers. To configure hypnotoad you have to add a new section. It is possible to use it without encryption but we advise you not to do that. If you have your own CA or want to create one, please read SSL Authentication.

hypnotoad => {
   listen => ['https://127.0.0.1:8433'],
},

The full file may look like this:

{
   hypnotoad => {
      listen => ['https://127.0.0.1:8443'],
   },
};

User/Password Authentication

If you want to use basic user/password authentication you have to add the location of the user file into the configuration. The key is user_file.

user_file => "/path/to/your/user.db",

The full file may look like this:

{
   user_file => "/path/to/your/user.db",
      
   # configure hypnotoad
   hypnotoad => {
      listen => ['https://127.0.0.1:8443'],
   },
};

You also have to create a user database for the authentication.

This file exists of 2 columns seperated by ":".

username:sha1crypted-password

You can create the sha1 strings with the following command.

perl -MDigest::SHA -le 'print Digest::SHA::sha1_hex("your-password")'

SSL Authentication

If you want to use SSL Authentication (with client/server certificates) you have to configure it. Open the file /etc/rex/httpd.conf and modify the listen line. And now you can remove the user_file line.

{
   hypnotoad => {
      listen => ["https://*:8443?cert=/path/to/your/cert-file.crt&key=/path/to/your/private.key&ca=/path/to/your/ca-file.crt"],
   },
};

It is also possible to put Apache or another Webserver in front of it. This is an example configuration:

<VirtualHost _default_:8443>
   ServerName your-server.your-domain.tld
   ServerAlias your-server
   
   SSLEngine on
   
   SSLCertificateFile    /etc/apache2/ssl/ssl.crt
   SSLCertificateKeyFile /etc/apache2/ssl/ssl.key
   SSLCACertificateFile  /etc/apache2/ssl/ca.crt
   
   SSLVerifyClient require
   SSLVerifyDepth  10
   SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
   
   <Location />
      ProxyPass http://localhost:8080/
      ProxyPassReverse http://localhost:8080/
  </Location>
  
</VirtualHost>

For this to work you need to create your own Certificate Authority (CA). There is a Rex recipe that will help you. Just create a small Rex project.

bash# rexify ca --use Rex::SSL::CA
bash# cd ca
bash ~/ca# cat >Rexfile<<EOF
require Rex::SSL::CA;
require Rex::SSL::CA::Server;
EOF

Please don't use a servername for the cn parameter here!

bash# rex SSL:CA:create --password=pass [--country=cn --state=state --city=city --org=organization --unit=organizational-unit --cn=name-of-the-ca --email=email]

And to create a server/client certificate you can use the following task. Here you have to use the server name for the cn parameter.

bash# rex SSL:CA:Server:create --cn=name-of-the-server --password=password [--challenge-password=challenge-password --country=country --state=state --city=city --org=organization --unit=organizational-unit --email=email]

After that you can copy the cert file from ca/certs/$cn.crt and the keyfile from ca/private/$cn.key. The CA Cert file is located at ca/certs/ca.crt.

USAGE

To use the HTTP/S endpoint in your rexfiles you just have to enable it.

To use HTTP Transport use the following line inside your Rexfile:

set connection => "http";

To use HTTPS Transport use this one:

set connection => "https";

If you want to use HTTPS/SSL Authentication use this:

set connection => "https";
set ca => "/path/to/ca-cert-file.crt";
set cert => "/path/to/client-cert-file.crt";
set key => "/path/to/client-key-file.key";

INIT

You can download an init script from https://github.com/krimdomu/rex-endpoint-http/tree/master/doc.