Ehorus: OnPremise EN

De eHorus Wiki
Saltar a: navegación, buscar

This guide will help you install your own eHorus infrastructure. To familiarize yourself with the eHorus application and architecture, first consult the Administration Guide.

1 Architechture

Below is a general scheme of the eHorus architecture and data flow, as well as the ports on which the different services listen.


Ehorus arquitectura.png


  • eHorus Agent: Software that is installed on the remote computer and allows access to it.
  • eHorus Server: Manages connections between remote computers (eHorus Agent) and users (eHorus Client).
  • eHorus Client: JavaScript application that connects to the eHorus server and allows interaction with the remote computer.


Ehorus client.png


  • eHorus Portal: Web application that allows you to manage remote computers, users, groups, and run eHorus Client.


Ehorus portal.png


  • eHorus Directory: Manages application data and access control to remote computers.
  • MySQL Server: Physically stores application data.

2 Previous Requirements

Ideally, you will have three hosts to install the eHorus directory, portal, and server with at least 4GB of RAM. If you wish, you can use an additional host for the directory database.

For environments with less than 100 agents, it is possible to install all components on a single server as long as conflicts between the ports of the different components are avoided. It is recommended that you have at least 4GB of RAM.

None of the eHorus components are CPU-intensive.

Before starting the installation make sure you have obtained the following files from Ártica Soluciones Tecnológicas:

ehorus-directory-1.0.0.tgz
ehorus-portal-1.0.0.tgz
ehorus-server-1.0.0.tgz

Version 1.0.0 will be used as an example, if your version is different adjust the commands shown in this guide as needed. For example, tar zxvf ehorus-directory-1.0.1.tgz instead of tar zxvf ehorus-directory-1.0.0.tgz.

The installation of the different eHorus components will take place on a CentOS version 7 system. If you use another operating system, the result may not be as expected.

All commands will be executed with the root user.

You must also have received from Ártica Soluciones Tecnológicas an identification number necessary to obtain your eHorus license.

In addition, you must have valid X.509 certificates to encrypt communications between the directory, the portal and the server.

In case of doubt contact Ártica Soluciones Tecnológicas at: [email protected]

3 Node.js and NGINX Installation

eHorus Directory and eHorus Portal need the Node.js environment to run themselves. In this guide we will use the NGINX web server to access these applications.

On the hosts of the directory and portal, execute the following commands:

yum install -y epel-release
yum install -y gcc-c++ make nginx nodejs npm
npm install --global yarn
npm install --global pm2
Instalación de MariaDB

On the directory hosts, run the following commands:

yum -y install mariadb-server mariadb
systemctl start mariadb
systemctl enable mariadb

Next, create eHorus database:

echo "CREATE DATABASE ehorus;" | mysql -u root

Replace the string 'STRONG PASSWORD with a strong password and create the user ehorus:

echo "GRANT ALL PRIVILEGES ON *.* TO 'ehorus'@'localhost' \
IDENTIFIED BY 'STRONG PASSWORD' WITH GRANT OPTION;" | mysql -u root
echo "FLUSH PRIVILEGES;" | mysql -u root

Finally, set a password for the MariaDB root user (consult the MariaDB documentation if in doubt):

mysql_secure_installation

4 Installation of eHorus directories

Execute the following commands:

mkdir -p /etc/ehorus /var/log/{ehorus-directory,ehorus-directory-clean-db}

Unzip the file ehorus_server_1.0.0.tgz:

tar zxvf ehorus-directory-1.0.0.tgz

Install the directories' dependencies:

yum groupinstall -y 'Development Tools'
yum install -y npm
mv package /opt/ehorus_directory
cd /opt/ehorus_directory
yarn install

Create the directory database (you will need the password you used when creating the eHorus user in the database):

cd /opt/ehorus_directory
cat db/schema/1-tables.sql | mysql -u ehorus -p ehorus
cat db/schema/2-rows.sql | mysql -u ehorus -p ehorus

Generate two random strings for directory configuration. For example, using the following command:

cat /dev/urandom | tr -c -d A-Za-z | fold -w 16 | head -1
cat /dev/urandom | tr -c -d A-Za-z | fold -w 16 | head -1

Create the file /etc/ehorus/ehorus-directory.pm2.json with the following content, substituting every instance of the string 1234567890 for a different random chain generated in the previous step. The value of JWT_SECRET will be necessary later to install the portal. Substitute [email protected] by a valid email address that Ártica Soluciones Tecnológicas will associate with its eHorus license:

{
  "apps": [
    {
      "name": "ehorus-directory",
      "script": "server.js",
      "cwd": "/opt/ehorus_directory",
      "env": {
        "NODE_ENV": "development",
        "PORT": 3000,
        "JWT_SECRET": "1234567890",
        "EKID_SECRET": "1234567890",
        "DB_CONF_PATH": "/etc/ehorus/ehorus-directory.db-config.json"
      },
      "env_production" : {
         "NODE_ENV": "production"
      },
      "error_file": "/var/log/ehorus-directory/stderr.log",
      "out_file": "/var/log/ehorus-directory/stdout.log",
      "merge_logs": true,
      "min_uptime": "20s",
      "max_restarts": 20,
      "max_memory_restart": "200M",
      "autorestart": true,
      "restart_delay": 0
    },
    {
      "name": "ehorus-directory-clean-db",
      "script": "clean-db.js",
      "cwd": "/opt/ehorus_directory/tools",
      "env": {
        "DB_CONF_PATH": "/etc/ehorus/ehorus-directory.db-config.json"
      },
      "args": "-i",
      "error_file": "/var/log/ehorus-directory-clean-db/stderr.log",
      "out_file": "/var/log/ehorus-directory-clean-db/stdout.log",
      "merge_logs": true,
      "min_uptime": "20s",
      "max_restarts": 20,
      "max_memory_restart": "100M",
      "autorestart": true,
      "restart_delay": 1
    }
  ]
}

Create the file /etc/ehorus/ehorus-directory.db-config.json with the following content. Substitute the string STRONG PASSWORD by the password you used when creating the eHorus user in the database:

{
  "host": "127.0.0.1",
  "user": "ehorus",
  "password": "STRONG PASSWORD",
  "port": 3306,
  "database": "ehorus",
  "debug": false
}

Create the file /etc/ehorus/ehorus-directory.smtp-config.json with the following content. Enter the parameters for your SMTP server (consult the documentation about Nodemailer for more info):

{
  "debug": false,
  "logger": false,
  "host": "127.0.0.1",
  "port": 465,
  "auth": {
    "user": "USERNAME",
    "pass": "PASSWORD"
  }
}

To install the server, execute the following command:

pm2 start --env production /etc/ehorus/ehorus-directory.pm2.json
pm2 startup
pm2 save

Copy the certificate of the host and the public key file in /etc/ehorus/ehorus_directory.crt and /etc/ehorus/ehorus_directory.key respectively.

To configure NGINX create the file /etc/nginx/conf.d/ehorus_directory.conf with the content shown below. Replace the string 'FQDN with the full domain name of the host. Refer to the NGINX documentation if you want to customize the configuration:

upstream ehorus_directory {
    server 127.0.0.1:3000;
}

server {
    listen       443 ssl;
    server_name  FQDN;

    # Add Strict-Transport-Security to prevent man in the middle attacks
    add_header Strict-Transport-Security "max-age=31536000";

    ssl_certificate /etc/ehorus/ehorus_directory.crt;
    ssl_certificate_key /etc/ehorus/ehorus_directory.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers AES256+EECDH:AES256+EDH:!aNULL;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_pass http://ehorus_directory;
        proxy_redirect off;
    }
}

Last, restart NGINX:

service nginx restart

5 Installation of the eHorus portal

Run the following commands:

mkdir -p /etc/ehorus /var/log/ehorus-portal

Unzip the file ehorus_server_1.0.0.tgz:

tar zxvf ehorus-portal-1.0.0.tgz

Install the portal dependencies:

mv package /opt/ehorus_portal
cd /opt/ehorus_portal
yarn install
yarn run build

Generate a random password for the user ehorus-api that we are going to create next:

cat /dev/urandom | tr -c -d A-Za-z | fold -w 48 | head -1

Create the user ehorus-api in the application, which the portal and server will use to make requests to the directory. Replace the string FQDN with the full domain name of the directory and STRONG PASSWORD with the password generated in the previous step:

LOGIN_TOKEN=$(curl -s --data "username=admin&password=admin" 'https://FQDN/login' | python -c 'import sys, json; print json.load(sys.stdin)["token"]')
curl -s -H "Authorization: JWT $LOGIN_TOKEN" --data "name=ehorus-api&password=STRONG PASSWORD&fullname=ehorus-api&[email protected]" 'https://FQDN/api/users'

On the directory host (this is the only command you should run outside the portal host) run the following command. You will need the password you used to create the ehorus user in the database:

echo 'UPDATE users SET level="admin" WHERE user="ehorus-api"' | mysql -u ehorus -p ehorus

Back to the portal host, generate a JSON Web Token to make requests from the portal to the directory. Replace the string FQDN with the full domain name of the directory and STRONG PASSWORD with the previously generated password for the ehorus-api user:

LOGIN_TOKEN=$(curl -s --data "username=ehorus-api&password=STRONG PASSWORD" 'https://FQDN/login' | python -c 'import sys, json; print json.load(sys.stdin)["token"]')
curl -s -H "Authorization: JWT $LOGIN_TOKEN" 'https://FQDN/api/token?audience=/users&expires=36000d' | python -c 'import sys, json; print json.load(sys.stdin)["token"]'

Create the file /etc/ehorus/ehorus-portal.pm2.json with the following content, substituting __API_SECRET__ for the JSON Web Token generated in the previous step, __JWT_SECRET__ for the value JWT_SECRET used in the installation of the directory and __DIRECTORIO__ for eHorus directory's full domain:

{
  "apps": [
    {
      "name": "ehorus-portal",
      "script": "server",
      "cwd": "/opt/ehorus_portal",
      "env": {
        "NODE_ENV": "development",
        "PORT": 3001,
        "API": "https://__DIRECTORIO__",
        "API_SECRET": "__API_SECRET__",
        "JWT_SECRET": "__JWT_SECRET__",
        "MAIL_CONF_PATH": "/etc/ehorus/ehorus-portal.smtp-config.json",
      },
      "env_production" : {
         "NODE_ENV": "production"
      },
      "error_file": "/var/log/ehorus-portal/stderr.log",
      "out_file": "/var/log/ehorus-portal/stdout.log",
      "merge_logs": true,
      "min_uptime": "20s",
      "max_restarts": 20,
      "max_memory_restart": "200M",
      "autorestart": true,
      "restart_delay": 0
    }
  ]
}

Create the file /etc/ehorus/ehorus-portal.smtp-config.json with the following content. If you wish to receive emails from eHorus, enter the correct parameters in the smtp section, for your SMTP server (consult the Nodemailer documentation for more info):

{
  "from": "eHorus <[email protected]>",
  "smtp": {
    "debug": false,
    "logger": false,
    "host": "127.0.0.1",
    "port": 465,
    "auth": {
      "user": "USERNAME",
      "pass": "PASSWORD"
    }
  }
}

To install the service, run the following command:

pm2 start --env production /etc/ehorus/ehorus-portal.pm2.json
pm2 startup
pm2 save

Copy the host certificate and the public key file in /etc/ehorus/ehorus_portal.crt and /etc/ehorus/ehorus_portal.key respectively.

To configure NGINX create the file /etc/nginx/conf.d/ehorus_portal.conf with the content shown below. Replace the string FQDN with the full domain name. Refer to the NGINX documentation if you want to customize the configuration:

upstream ehorus_portal {
    server 127.0.0.1:3001;
}

server {
    listen      80;
    server_name FQDN;

    return      301 https://$server_name$request_uri;
}

server {
    listen      443 ssl;
    server_name FQDN;

    # Add Strict-Transport-Security to prevent man in the middle attacks
    add_header Strict-Transport-Security "max-age=31536000";

    ssl_certificate /etc/ehorus/ehorus_portal.crt;
    ssl_certificate_key /etc/ehorus/ehorus_portal.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers AES256+EECDH:AES256+EDH:!aNULL;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_pass http://ehorus_portal;
        proxy_redirect off;
    }
}

Last, restart NGINX:

service nginx restart

6 Installation of eHorus server

Unzip the file ehorus_server-1.0.0.tgz:

tar zxvf  ehorus-server-1.0.0.tgz

Execute the installer:

cd ehorus_server-0.1.0
./ehorus_server_installer --install

You must then obtain a valid license. To do so, please go to licensing.artica.es, enter the identification number you have received from Ártica in the Auth Key field, and in the Request Key field (from ehorus) the full domain of the eHorus directory. This value must match the domain listed in the X509 certificate you install in the directory (e.g. directory.ehorus.com). Finally, click on the Generate button and save in a safe place the license that will appear in License Key.


Ehorus key.png


Generate a JSON Web Token to make petitions form the server to the directory. Substitute the string FQDN by the full domain name of the directory and STRONG PASSWORD by the password generated during the installation of the portal for the user ehorus-api:

LOGIN_TOKEN=$(curl -s --data "username=ehorus-api&password=STRONG PASSWORD" 'https://FQDN/login' | python -c 'import sys, json; print json.load(sys.stdin)["token"]')
curl -s -H "Authorization: JWT $LOGIN_TOKEN" 'https://FQDN/api/token?audience=/stats&expires=36000d' | python -c 'import sys, json; print json.load(sys.stdin)["token"]'

Next, edit the configuration file/etc/ehorus/ehorus_server.conf and modify the following parameters:

  • license: Delete the comment (#) character and enter the license you obtained in the previous step (do not put it in quotation marks). For example:
license 1234567890
  • ssl_cert: Absolute path to the X.509 certificate of the server. For example:
ssl_cert /etc/ehorus/ehorus_cert.pem
  • ssl_key: Absolute path to the server X.509 certificate key file. For example:
ssl_cert /etc/ehorus/ehorus_key.pem
  • eh_auth_token: JSON Web Token generated in the previous step. For example:
eh_auth_token 1234567890

Manually lift the eHorus server to check that the configuration is correct:

ehorus_server -f /etc/ehorus/ehorus_server.conf

Stop the eHorus server and raise it as a service:

service ehorus_server start

Enter the eHorus portal (https://<FQDN del portal>/) with the admin user (admin password), and click Servers:


Ehorus portal servers.png


Enter the following info:

  • Name: Name of the server. It is merely descriptive.
  • Address: Blank. Not necessary in on-premise installations.
  • Domain: Complete domain of the eHorus server.


Ehorus portal servers 2.png


7 Additional Considerations

  • It is recommended to change the password of the admin user in the portal from the Users section.
  • The use of firewalls on all hosts is recommended. If you have followed this guide, you will need to access ports 443 of the portal and directory and 443 and 8080 of the eHorus server.

8 First steps

Once the infrastructure is installed you can start installing the eHorus agents on the computers you want to manage remotely. For that, check again the Administration guide.

9 Annexes

9.1 Portal customization

IMPORTANT: Keep a backup copy of your customizations, as they may be lost if you update the software.

Emails The templates for emails sent by the eHorus portal can be found in the directory ehorus_portal/server/mailer/templates. For each email there is a plain text version in the text subdirectory, and another in HTML in the html subdirectory.

The templates are loaded into memory, so it will be necessary to restart the portal with the command shown below if modified:

pm2 restart ehorus-portal

Templates support macros, written in between curly brackets (e.g. {{email}}), which eHorus portal will substitute for the suitable value before sending an email.

9.1.1 Welcome Screen

  • HTML: /opt/ehorus_portal/server/mailer/templates/html/welcome.html
  • Plain text: /opt/ehorus_portal/server/mailer/templates/text/welcome.txt

Supported macros:

  • {{host}}: Full domain of the eHorus portal.
  • {{email}}: Address to which the e-mail is sent.
  • {{user}}: Name of the user to whom the email is sent.
  • {{name}}: Full name of the user to whom the email is sent.

9.1.2 Password reset

  • HTML: /opt/ehorus_portal/server/mailer/templates/html/password-reset.html
  • Plain text: /opt/ehorus_portal/server/mailer/templates/text/password-reset.txt

Supported macros:

  • {{host}}: Full domain of the eHorus portal.
  • {{email}}: Address to which the e-mail is sent.
  • {{user}}: Name of the user to whom the email is sent.
  • {{name}}: Full name of the user to whom the email is sent.
  • {{token}}: The JSON Web Token used to authorize the password change operation.

9.1.3 Password change

  • HTML: /opt/ehorus_portal/server/mailer/templates/html/password-changed.html
  • Plain text: /opt/ehorus_portal/server/mailer/templates/text/password-changed.txt

Supported macros:

  • {{host}}: Full domain of the eHorus portal.
  • {{email}}: Address to which the e-mail is sent.
  • {{user}}: Name of the user to whom the email is sent.
  • {{name}}: Full name of the user to whom the email is sent.

9.1.4 Email change

  • HTML: /opt/ehorus_portal/server/mailer/templates/html/email-changed.html
  • Plain text: /opt/ehorus_portal/server/mailer/templates/text/email-changed.txt

Supported macros:

  • {{host}}: Full domain of the eHorus portal.
  • {{oldEmail}}: Previous email address.
  • {{email}}: New email address to which the e-mail is sent.
  • {{user}}: Name of the user to whom the email is sent.
  • {{name}}: Full name of the user to whom the email is sent.

9.1.5 Assets

If changes are made to the files shown in this section, execute the following command to copy them to the directoryo /opt/ehorus_portal/build:

cd /opt/ehorus
npm run build

To change the eHorus portal logo replace the following files ehorus_portal/assets/images/logo.png and ehorus_portal/assets/images/logo-grey.png.

9.1.7 CSS

9.1.7.1 Portal

The CSS files of the eHorus portal are in the directory /opt/ehorus_portal/assets/css.

For the general styles use Bulma and for the icons Font Awesome. The fonts can be found in the directory /opt/ehorus_portal/assets/fonts.

Styles can also be overwritten using a custom CSS file and modifying the file /opt/ehorus_portal/assets/index.html to include it.

9.1.7.2 Client

The CSS files of the eHorus client are in the directory /opt/ehorus_portal/assets/client/css.

For general styles use Bootstrap and for icons xterm.js. The fonts are in the directory /opt/ehorus_portal/assets/client/fonts.

Styles can also be overwritten using a custom CSS file and modifying the file /opt/ehorus_portal/assets/index.html to include it.

9.1.8 URL

9.1.8.1 User registration

The URL to register a user shown on the home screen can be changed by placing in the environment variable URL_CREATE_ACCOUNT the desired URL before executing the command npm run build. For example:

cd /opt/ehorus_portal
CREATE_ACCOUNT="https://localhost.localdomain/sign-up" npm run build


Ehorus portal login.png


9.2 Certificate generation

If you want to generate your own X.509 certificates, generate the CA certificate first:

mkdir /etc/pki/CA/newcerts
mkdir /etc/pki/CA/private
touch /etc/pki/CA/index.txt
echo "01" >> /etc/pki/CA/serial
openssl genrsa -out /etc/pki/CA/private/cakey.pem
openssl req -new -x509 -key /etc/pki/CA/private/cakey.pem -out  /etc/pki/CA/cacert.pem

Then install the CA certificate as a trusted root certificate:

yum install -y ca-certificates
update-ca-trust force-enable
cp /etc/pki/CA/cacert.pem /etc/pki/ca-trust/source/anchors/
update-ca-trust extract

Finally, generate and sign the eHorus certificate:

openssl genrsa -out ehorus.key
openssl req -new -key ehorus.key -out ehorus.req -days 36000
cat ehorus.req ehorus.key  > ehorus.pem
openssl ca -out ehorus.crt -in ehorus.pem

To prevent the eHorus portal from displaying as an insecure page, consult your browser's documentation to add the newly created CA certificate. (e.g., https://wiki.mozilla.org/CA/AddRootToFirefox).