INSTALLATION

Below we describe in detail all the steps that are needed to complete the installation of a FWCloud server, using as a starting point a newly installed Ubuntu 18 LTS server, although this process is easily extrapolated to any other Linux distribution.

Although it is convenient to read this section to better understand the components that constitute a FWCloud platform, you can save this whole process by downloading FWCloud-VM, a virtual machine that you can run in your virtualization environment with everything pre-installed.

As we stated in the description section, FWCloud contains two main modules: the user interface (FWCloud-UI) and the REST API (FWCloud-API), which handles all the actions requested by the user.

Normally when a user accesses a FWCloud server, the first thing he does is download the user interface using a web browser (Chrome, Firefox, etc.) and access the access URL which can be, for example, https: //ui.fwcloud.net (it does not have to be a domain name, it can also be an IP address). This URL will take us to a web server (Nginx, Apache, etc.) from which the FWCloud-UI application will be downloaded to the user's terminal.

Once the application has been downloaded to our web browser, it will start running, displaying the login screen. From this moment, any action that we perform on FWCloud-UI (for example, completing the login process) will be carried out using FWCloud-API, to which FWCloud-UI will access using the API access URL, which can be, for example, https://api.fwcloud.net:3000.

It is very important to keep in mind that, once FWCloud-UI is running in our browser, it must have access to the API URL in order to work correctly. That is, from our user terminal, we have to have access to the API URL so that FWCloud-UI can work correctly.

A FWCloud installation will have two URLs:

  • FWCloud-UI access URL. We'll use it to download and run the user interface application in our web browser.
  • FWCloud-API access URL. It's used by FWCloud-UI to perform all the tasks provided by the FWCloud system, such as login, firewall management, VPN management and so forth.

It's not necessary that these URL are domain names, they can also be IP addresses. For example, in the pre-configured FWCloud-VM virtual machine we have set https://10.9.8.7 as the access URL to the user interface and https://10.9.8.7:3000  as the URL to communicate with the API server, using self-signed TLS certificates.

However, we must bear in mind that if we use self-signed certificates, the browser will display a warning message indicating that we are accessing an insecure site and, in addition, in Firefox, the FWCloud-UI communication with FWCloud-API will not work because of the browser's  security directives.

Therefore, we recommend using for both URLs a couple of host names with their corresponding certificates, issued by a valid certificate authority, such as Let's Encrypt.

We also have to keep in mind that we can have the two main components FWCloud-UI and FWCloud-API on different servers, they do not need to be installed on the same one.

Once this is clear, we can now go on to explain in detail the installation process.

FWCloud-API (back-end)

Next we will describe the steps needed to carry out the installation of FWCloud-API, on our newly installed Ubuntu 18 LTS server.

We will also explain how to verify the correct working of our FWCloud-API, once the entire installation process has been completed to ensure that our installation has been satisfactory.

1. Package updating.

We have to access the server with a user that has administrator privileges to be able to execute commands as root using sudo.

The first thing we should do is to update or Ubuntu server with the latest available packages.

$ sudo apt update
$ sudo apt -y dist-upgrade

If the kernel has been updated, reboot the server to start using the new version.

$ sudo init 6

After rebooting, we can continue the installation process, logging in with an user with sudo privileges.

The following package is not necessary to install FWCloud, but we'll use it in this documentation to generate random strong passwords. Alternatively, we can use another password management software as KeePassX.

$ sudo apt-get install -y pwgen

It is also convenient that we install the OpenVPN package, since, as you can see in the FWCloud-UI tutorial, it will be useful to configure the VPN server for administration VPNs.

$ sudo apt-get install -y openvpn

2. Repository cloning.

The installation root folder of FWCloud-API will be /opt/fwcloud-api, although it can be anyone else. We'll clone the Github repository in this folder by running the following two commands:

$ cd /opt/
$ sudo git clone https://github.com/soltecsis/fwcloud-api.git

3. Database.

FWCloud-API uses MySQL database engine to store its data, so we need to install it before we can continue.

WARNING: The database has triggers that aren't compatible with MariaDB yet, so it's mandatory to install MySQL server instead of MariaDB.

$ sudo apt install -y mysql-server

With the following commands, we'll create the database and will fill it with the basic data needed for running FWCloud-API correctly.

$ echo "create database fwcloud" | sudo mysql -u root
$ sudo mysql -u root fwcloud < /opt/fwcloud-api/config/data_ini/fwcloud.sql
$ sudo mysql -u root fwcloud < /opt/fwcloud-api/config/data_ini/ipobj_std.sql

We need a user to be able to access the FWCloud-API database. We are going to use the pwgen command to generate a random password. Remember not to use the password indicated in this document, use your own, generated with the pwgen or with any other program that allows the generation of random passwords.

$ pwgen 24 1 -s
GFhnXBJ7FdwhxImYamlDJLwN
$ echo "CREATE USER 'fwcdbusr'@'localhost' IDENTIFIED BY 'GFhnXBJ7FdwhxImYamlDJLwN'" | sudo mysql -u root fwcloud
$ echo "GRANT ALL PRIVILEGES ON fwcloud.* TO 'fwcdbusr'@'localhost'" | sudo mysql -u root fwcloud
$ echo "FLUSH PRIVILEGES" | sudo mysql -u root fwcloud

4. Node.js.

The backend is developed using Node.js and npm, so we need to install them before continuing. In this example, we are installing the 12.x version of Node.js, since it is the last to date of this documentation, but there should be no problem installing the latest version available.

$ curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
$ sudo apt-get install -y nodejs

One of the Node.js packages used by FWCloud-API, specifically bcrypt, needs to be compiled to be used, therefore, we need the build-essential package of the Linux distribution for it:

$ sudo apt install -y build-essential

Now we are going to create a group and a system user without administrator privileges, which we will use for the installation and execution of FWCloud-API.

$ sudo groupadd fwcloud
$ sudo useradd fwcloud -g fwcloud -m -c "SOLTECSIS - FWCloud.net" -s /bin/bash

We assign a password to the newly created user. We can use the pwgen command to generate a password for our user.

$ pwgen 16 1
$ sudo passwd fwcloud

Now let's give the user permission to fwcloud over the entire folder that we just created.

$ sudo chown -R fwcloud:fwcloud /opt/fwcloud-api/

We change to user fwcloud to carry out the following steps in the installation. We will have to use the password that we have assigned to this user.

$ su - fwcloud
Password:

We install next the Node.js packages necessary for the operation of FWCloud-API, executing the following sequence of commands:

$ cd /opt/fwcloud-api/
$ npm install

5. TLS certificates.

Although it is possible to use communication without encryption, both at the user interface and the API level, it is something that should only be done in a development environment. In a production environment it is highly advisable to use encrypted communications both at the level of access to the user interface and in accessing the API.

Since we are going to use a web browser to access the user interface, the mechanism used to encrypt communications is the HTTPS protocol. Therefore, we will have to configure TLS certificates both in the web server that will allow access to the user interface, and in communication with the API.

To avoid problems with web browsers, it is advisable to use a TLS certificate signed by a valid certification authority. You can use a free such as Let's Encript. However, we can also use self-signed TLS certificates, although it is not advisable due to the following problem.

WARNING: If you are going to use a self-signed certificate, please note that the user interface will not work in FireFox since, although it allows the download of FWCloud-UI (displaying a security warning), it will not allow communication with FWCloud-API. With a self-signed certificate, we recommend using Chrome as a web browser.

For simplicity, for the installation that we are describing in this document, we will generate self-signed certificates.

Having said this, we will continue with the next step in the installation of FWCloud-API which consists in the generation of the TLS self-signed certificate for the API. In bold we indicate the sample data for the certificate, you can use the ones you think are convenient for your installation.

 

$ mkdir /opt/fwcloud-api/config/tls
$ cd /opt/fwcloud-api/config/tls
$ openssl req -nodes -new -x509 -keyout fwcloud-api.key -out fwcloud-api.crt
Utilizando los siguientes datos de ejemplo, aunque puede utilizar los suyos propios:
Country Name (2 letter code) [AU]:ES
State or Province Name (full name) [Some-State]:Alicante
Locality Name (eg, city) []:Altea
Organization Name (eg, company) [Internet Widgits Pty Ltd]:SOLTECSIS - FWCloud.net
Organizational Unit Name (eg, section) []:I+D+I
Common Name (e.g. server FQDN or YOUR name) []:FWCloud-API
Email Address []:info@fwcloud.net

6. Configuration.

We'll set up the basic configuration to start the API server. To do this, we need to update the file  /opt/fwcloud-api/.env to define the following options.

Note that, for the configuration keys SESSION_SECRET and CRYPT_SECRET we can use the pwgen command again with the following parameters:

$ pwgen 64 1 -s
3NORV6mOQdG2GzibNGEsMBCEQGVoh9ENDiene3Qhtrn2nAPFFLoLLnRoObKEPf1L
$ pwgen 64 1 -s
DPOmbJlnWP5ZTXy3Fxr7xMBEOLDjzJFHYebBZcF679ESeoHuNOmseR94JQZZPv6E

We can even use the -y option and that would generate passwords with random symbols, but we have to be careful that these symbols do not contain special characters.

We need to set the option FWCLOUD-UI_IP_OR_DNS_NAME with the IP address or DNS name that we'll use to access FWCloud-UI.

$ vi /opt/fwcloud-api/.env

NODE_ENV="prod"

#LISTEN_IP=0.0.0.0
#LISTEN_PORT=3000

#HTTPS_CERT="./config/tls/fwcloud-api.crt"
#HTTPS_KEY="./config/tls/fwcloud-api.key"

# URLs used for FWCloud-UI access. It can be a comma separated list.
CORS_WHITELIST="https://FWCLOUD-UI_IP_OR_DNS_NAME"

# Secret used for session cookies and CSRF (Cros-Site Rquest Forgery) tockens.
SESSION_SECRET="3NORV6mOQdG2GzibNGEsMBCEQGVoh9ENDiene3Qhtrn2nAPFFLoLLnRoObKEPf1L"

# Secret used for data encryption.
CRYPT_SECRET="DPOmbJlnWP5ZTXy3Fxr7xMBEOLDjzJFHYebBZcF679ESeoHuNOmseR94JQZZPv6E"

# Database access data.
DB_HOST="127.0.0.1"
DB_USER="fwcdbusr"
DB_PASS="GFhnXBJ7FdwhxImYamlDJLwN"

The following commands have to be executed with the user with sudo privileges, therefore, we close the actual session that we have opened with the user fwcloud.

$ exit

7. Startup script.

The last step is to create the service file to start and stop our FWCloud-API server.

$ sudo cp /opt/fwcloud-api/config/sys/fwcloud-api.service /etc/systemd/system/

We enable the service to start automatically every time we restart the server:

$ sudo systemctl enable fwcloud-api

Now we can start the FWCloud-API service using the following command:

$ sudo systemctl start fwcloud-api

The next step will allow us to see that everything worked correctly. If we can not access the logs folder to see if there is any problem.

$ sudo systemctl status fwcloud-api
fwcloud-api.service - FWCloud-API
  Loaded: loaded (/etc/systemd/system/fwcloud-api.service; disabled; vendor preset: enabled)
  Active: active (running) since Fri 2019-06-07 14:58:01 UTC; 8s ago
Main PID: 14359 (node)
   Tasks: 11 (limit: 1109)
  CGroup: /system.slice/fwcloud-api.service
          └─14359 /usr/bin/node /opt/fwcloud-api/bin/www

Jun 07 14:58:01 fwcloud-vm systemd[1]: Started FWCloud-API.

8. Verification.

The next thing is to verify that the API works correctly, for which we are going to use the API call to log in. In a new installation, we have created the following credentials by default:

Código de cliente: 1
Nombre de usuario: fwcadmin
Contraseña: fwcadmin

Using the curl command, this would be the call that we would have to use to log in. We use the --insecure option because we are using a self-signed certificate. If we use a certificate signed by a recognized certification authority such as Let's Encrypt, this option would not be necessary.

curl --insecure -X POST \
https://localhost:3000/user/login \
-H 'Content-Type: application/json' \
-H 'Origin: https://10.9.8.7' \
-d '{
  "customer": 1,
  "username": "fwcadmin",
  "password": "fwcadmin"
}'

In response to this call to the API it will return a code 200 indicating that everything went well and a JSON object of the following type:

{
  "user": 1,
  "role": 1
}

If we get this response, we have our FWCloud-API installation fully functional. If not, we should inspect the system logs or contact us to troubleshoot what went wrong.

FWCloud-UI (front-end)

Now that we have the back-end ready, the next step is to install and configure the front-end, ie the user interface FWCloud-UI.

Next we will give the details about how to carry out this installation in the same Ubuntu server in which we have just installed FWCloud-API. Please note that there is no problem in installing FWCloud-UI on a different server.

We will explain the configuration for the Nginx web server, although there is no problem in using another web server, such as Apache, for accessing the user interface from the user's terminal.

1. Nginx web server.

Before anything else, we need to install Nginx web server.

$ sudo apt install -y nginx

To make things easier, the FWCloud-API installation has a basic Nginx config file. We'll copy it to  /etc/nginx/conf.d/

$ sudo cp /opt/fwcloud-api/config/sys/nginx/fwcloud-ui.conf /etc/nginx/conf.d/

We have to edit the above file /etc/nginx/conf.d/fwcloud-ui.conf to update the variable FWCLOUD-UI_IP_OR_DNS_NAME with the IP address or DNS name that we'll use to access to FWCloud-UI.

In the same way we have to change the string FWCLOUD-API_IP_OR_DNS_NAME by the IP or DNS name that we will use to access the FWCloud-API.

$ sudo vi /etc/nginx/conf.d/fwcloud-ui.conf

We use the same self-signed certificates that we generated for the API.

WARNING: In order to use self-signed certificates with Chrome, it is necessary that the ones in the user interface are the same as those in the API.

$ sudo cp /opt/fwcloud-api/config/tls/fwcloud-api.crt /etc/ssl/certs/fwcloud-ui.crt
$ sudo cp /opt/fwcloud-api/config/tls/fwcloud-api.key /etc/ssl/certs/fwcloud-ui.key

Restart Nginx server to apply the changes.

$ sudo systemctl restart nginx

2. Repository cloning.

We create the directory in which we are going to clone the Git repository for FWCloud-UI.

$ cd /opt/
$ sudo git clone https://github.com/soltecsis/fwcloud-ui.git

3. Configuration.

Configuration for the user interface where we indicate how to communicate with FWCloud-API.

$ sudo mkdir /opt/fwcloud-ui/dist/assets/config
$ sudo vi /opt/fwcloud-ui/dist/assets/config/config.json
{
  "fwcAppURL" : "https://FWCLOUD-API_IP_OR_DNS_NAME:3000",
  "fwcConsoleLogs" : false
}

We have to replace FWCLOUD-API_IP_OR_DNS_NAME by the IP address or DNS name of the server where FWCloud-API is installed.

WARNING: We must bear in mind that the connection to the API will be carried out from our browser, therefore, we can not use https: // localhost: 3000 unless we are using the browser on the server itself, which It is not usual.

Finally we modify the owner of the entire directory that we just installed:

$ sudo chown -R fwcloud:fwcloud /opt/fwcloud-ui

4. Access.

We already have our user interface FWCloud-UI ready to access. Using the access URL of the user interface we should be able to log in with the default credentials for a new installation:

Código de cliente: 1
Nombre de usuario: fwcloud
Contraseña: fwcloud