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.

cpanm Rex::Endpoint::HTTP

perl -MCPAN -e shell
install Rex::Endpoint::HTTP