Cosmos GUI

Content:

Introduction

There is a GUI governing both the storage and the computing cluster (in future releases, it will be fully integrated with Sahara's dashboard as well). Through this GUI the users will be able to create an account, i.e. a HDFS userspace for storing data, and access to the computing resources for running MapReduce applications.

Fully detailed information about Cosmos GUI can be found at Github.

Installation

This is a software written in JavaScript, specifically suited for Node.js (JavaScript on the server side). JavaScript is an interpreted programming language thus it is not necessary to compile it nor build any package; having the source code downloaded somewhere in your machine is enough.

Top

Prerequisites

This GUI has no sense if there is no storage and computing clusters to be managed.

A couple of sudoer users, one within the storage cluster and another one within the computing clusters, are required. Through these users the cosmos-gui will remotely run certain administration commands such as new users creation, HDFS userspaces provision, etc. The access through these sudoer users will be authenticated by means of private keys. Please, see the Annex A in order to know how to create a sudoer user, and how to install its RSA identity for ssh operation.

The Cosmos users management is done by means of a MySQL database, thus install it in the same node the GUI runs, or a remote but accessible machine.

As said, cosmos-gui is a Node.js application, therefore install it from the official download. An advanced alternative is to install Node Version Manager (nvm) by creationix/Tim Caswell, whcih will allow you to have several versions of Node.js and switch among them.

Of course, common Unix tools such as git and curl are needed.

Top

Installating the GUI

cosmos-gui must be installed in a machine having ssh access both to the storage and computing clusters the GUI is going to manage. This ssh access may be limited to the Namenode (or Namenodes, if HA is enabled) of each cluster, and it is necessary since certain administration commands are remotely run through ssh.

Start by creating, if not yet created, a Unix user named cosmos-gui; it is needed for installing and running the application. You can only do this as root, or as another sudoer user:

$ sudo useradd cosmos-gui
$ sudo passwd cosmos-gui <choose_a_password>

While you are a sudoer user, create a folder for saving the cosmos-gui log traces under a path of your choice, typically /var/log/cosmos/cosmos-gui, and set cosmos-gui as the owner:

$ sudo mkdir -p /var/log/cosmos/cosmos-gui
$ sudo chown cosmos-gui:cosmos-gui /var/log/cosmos/cosmos-gui

Now, change to the new fresh cosmos-gui user:

$ su - cosmos-gui

Before continuing, remember to add the RSA key fingerprints of the Namenodes accessed by the GUI. This fingerprints are automatically added to /home/cosmos-gui/.ssh/known_hosts if you try a ssh access to the Namenodes for the first time.

$ ssh somesudoeruser@my.storage.namenode.com
The authenticity of host 'my.storage.namenode.com (192.168.12.1)' can't be established.
RSA key fingerprint is 96:c4:0b:8c:09:ce:d4:09:91:a2:b2:9c:40:71:9b:c6.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'my.storage.namenode.com,192.168.12.1' (RSA) to the list of known hosts.

Please observe somesudoeruser is the (ficticious) sudoer user required for the storage cluster, as stated in the Prerequisites section. Do the same for the computing cluster.

Then, clone the Cosmos repository somewhere of your ownership:

$ git clone https://github.com/telefonicaid/fiware-cosmos.git

cosmos-gui code is located at fiware-cosmos/cosmos-gui. Change to that directory and execute the installation command:

$ cd fiware-cosmos/cosmos-gui
$ git checkout release/x.y.z
$ npm install

That must download all the dependencies under a node_modules directory.

Top

Installing the database

The user management for the storage cluster is done through a MySQL database, cosmos. The commands for creating this database and the cosmos_user table can be found at resources/mysql_db_and_tables.sql. Please observe if you already installed a database for a previous version of the GUI, please ignore this section and visit the specific upgrading section.

Simply log into your MySQL deployment and execute the sentence within the file above:

mysql> resources/mysql_db_and_tables.sql

Alternatively, you can copy&paste the SQL sentences and execute them:

$ mysql -u <user> -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1640
Server version: 5.1.73 Source distribution

Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights
reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> CREATE DATABASE IF NOT EXISTS cosmos;
mysql> USE cosmos;
mysql> CREATE TABLE cosmos_user (
    -> id VARCHAR(128) NOT NULL PRIMARY KEY UNIQUE,
    -> email TEXT NOT NULL,
    -> hdfs_quota BIGINT NOT NULL,
    -> hdfs_used BIGINT NOT NULL,
    -> fs_used BIGINT NOT NULL,
    -> registration_time TIMESTAMP DEFAULT "0000-00-00 00:00:00",
    -> last_access_time TIMESTAMP DEFAULT "0000-00-00 00:00:00",
    -> num_ssh_conn_ok BIGINT NOT NULL,
    -> num_ssh_conn_fail BIGINT NOT NULL);

Top

Upgrading from 0.1.0 to 0.2.0

NOTE: It is highly recommended you backup your cosmos database before performing any upgrade operation.

You are visiting this section since you already installed Cosmos GUI 0.1.0 and want to upgrade to 0.2.0. If you never installed the GUI before, please go to the Installing the database section.

Cosmos GUI 0.2.0 adds some columns to the cosmos_user table, and many others are modified. In order to do the upgrade, please execute the resources/mysql_upgrade_0.1.0-0.2.0.sql file:

mysql> SOURCE resources/mysql_upgrade_0.1.0-0.2.0.sql

Or type the sentences within that file into a mysql shell:

mysql> USE cosmos;
mysql> ALTER TABLE cosmos_user MODIFY registration_time TIMESTAMP DEFAULT "0000-00-00 00:00:00";
mysql> ALTER TABLE cosmos_user ADD COLUMN last_access_time TIMESTAMP DEFAULT "0000-00-00 00:00:00";
mysql> ALTER TABLE cosmos_user ADD COLUMN hdfs_used BIGINT NOT NULL;
mysql> ALTER TABLE cosmos_user ADD COLUMN fs_used BIGINT NOT NULL;
mysql> ALTER TABLE cosmos_user ADD COLUMN num_ssh_conn_ok BIGINT NOT NULL;
mysql> ALTER TABLE cosmos_user ADD COLUMN num_ssh_conn_fail BIGINT NOT NULL;
mysql> ALTER TABLE cosmos_user MODIFY hdfs_quota BIGINT NOT NULL;
mysql> UPDATE cosmos_user SET hdfs_quota=1073741824*hdfs_quota;

Top

Upgrading from 0.2.0 to 0.3.0

NOTE: It is highly recommended you backup your cosmos database before performing any upgrade operation.

You are visiting this section since you already installed Cosmos GUI 0.2.0 and want to upgrade to 0.3.0. If you never installed the GUI before, please go to the Installing the database section.

Please observe moving from 0.2.0 to 0.3.0 implies a hard change of behaviour regarding the Cosmos user provision and the Cosmos usage itself:

  • On the one hand, Cosmos passwords are not necessary anymore, thus, ssh accesses to the clusters are not allowed anymore.
  • On the other hand, the Cosmos users are not based on the Identity Manager (IdM) registered email, but the ID of the user at the IdM.

Both changes have direct implications on the database, where the idm_username and username are replaced by email and id, respectively. In order to do the upgrade, please execute the resources/mysql_upgrade_0.2.0-0.3.0.sql file:

mysql> SOURCE resources/mysql_upgrade_0.2.0-0.3.0.sql

Or type the sentences within that file into a mysql shell:

mysql> USE cosmos;
mysql> ALTER TABLE cosmos_user RENAME idm_username TO email;
mysql> ALTER TABLE cosmos_user RENAME username TO id;

Top

Registering the application in the Identity Manager

Authentication in cosmos-gui is done through a FIWARE's Identity Manager (for instance, FIWARE LAB one is https://account.lab.fiware.org). By using this kind of authentication the cosmos-gui is integrated in a fully common experience together with many other enablers of the FIWARE ecosystem, instead of performing a propietary user management.

Please observe the user management for accessing the GUI or any other FIWARE component is not related to the Hadoop user management performed, particularly, by this GUI.

Registration must be done one and only once. As an already registered user in the Identity Manager, login (this user will be the admin user). You should be able to see an applications panel, in addition to an organizations panel, in your home tab:

Click in the register button of the applications panel and give a name, a description, a URL and a callback URL for the new application. For instance:

Then choose an image for the application, this will be shown as an icon for future users:

Finally, manage the roles for this application. If you do not expect to add more roles than the default ones, or you simply do not know about roles, skip this step and finish the user registration:

cosmos-gui is now registered:

An important result of the registration process are the OAuth2 credentials that can be inspected by clicking on the appropriate button. These credentials must be configured in cosmos-gui as shown later.

Top

Unit tests

The tests are running by invoking the make command:

$ make
***** STARTING TESTS *****

  ․ [mysqlDriver.addUser] add a new user should return null error and an empty result set: 5ms
  ․ [mysqlDriver.getUser] get a user by his/her id should return null error and a result set containing frb: 1ms

  2 passing (15ms)

****** TESTS ENDED *******

Top

Configuration

cosmos-gui is configured through conf/cosmos-gui.json. There you will find a JSON document with six main sections:

  • gui:
    • port: Specifies the listening port for the application. By default it is 80, but can be changed if such a port is being used in your deployment.
    • private_key_file: File name containing the private key used to encrypt the communications with the clients.
    • certificate_file: File name containing the self-signed X509 certificate used by the server to send the clients the public counterpart of the above private key (see Annex B].
  • clusters:
    • storage
      • endpoint: IP address or FQDN of the Namenode/HttpFS server of the storage cluster.
      • user: Unix user within the Namenode/HttpFS server having sudo permissions.
      • private_key: user's private key used to ssh into the Namenode/HttpFS server.
    • computing
      • endpoint: IP address or FQDN of the Namenode/HttpFS server of the computing cluster.
      • user: Unix user within the Namenode/HttpFS server having sudo permissions.
      • private_key: User's private key used to ssh into the Namenode/HttpFS server.
  • hdfs:
    • quota: Measured in bytes, defines the size of the HDFS space assigned to each Cosmos user.
    • superuser: HDFS superuser, typically hdfs.
  • oauth2:
    • idmURL: URL where the FIWARE Identity Manager runs. If using the global instance at FIWARE LAB, it is https://account.lab.fiware.org.
    • client_id: This is given by the Identity Manager once the cosmos-gui has been registered.
    • client_secret: This is given by the Identity Manager once the cosmos-gui has been registered.
    • callbackURL: URL used by the Identity Manager to return the control to the GUI once the delegated authentication step has finished. This must be http://localhost:<listening_port>/auth.
    • response_type: Must be code.
  • mysql:
    • host: IP or FQDN of the host running the MySQL server.
    • port: Port the MySQL server is listening for new incoming connections. Typically 3306.
    • user: A valid user in the MySQL server with permissions to insert into the cosmos_user table.
    • password: Password for the above user in MySQL.
    • database: Must be cosmos.
  • users_blacklist: An array of strings not allowed to be a username.
  • log:
    • file_name: Path of the file where the log traces will be saved in a daily rotation basis. This file must be within the logging folder owned by the the user cosmos-gui.
    • date_pattern: Data pattern to be appended to the log file name when the log file is rotated.
    • level: Minimum logging level to be considered. Possible values (including hierarchy) are: OFF > ERROR > WARN > INFO > DEBUG > ALL.

Top

Running

The GUI implemented by cosmos-gui is run as (assuming your current directory is fiware-cosmos/cosmos-gui):

$ npm start

This command invokes the start script within package.josn:

"scripts": {
    "start": "sudo node ./src/cosmos_gui.js"
}

Please observe the usage of sudo. This is because the GUI must be able to execute certain privileged Unix and Hadoop commands when setting up Cosmos accounts. Never run cosmos-gui (nor any other service) as the root user.

If everything goes well, you should be able to see in a web browser the login page (http://<node_hosting_cosmos_gui>:<port>):

cosmos-gui typically listens in the TCP/443 port (TLS encryption), but you can change it by editing conf/cosmos-gui.conf.

Top

Administration

Two are the sources of data, the logs and the database, useful for an administrator of cosmos-gui.

Top

Logging traces

Logging traces, typically saved under /var/log/cosmos/cosmos-gui, are the main source of information regarding the GUI performance. These traces are written in JSON format, having the following fields: level, message and timestamp. For instance:

{"level":"info","message":"cosmos-gui running at http://localhost:9090","timestamp":"2015-07-23T13:25:20.019Z"}

Logging levels follow this hierarchy:

debug < info < warn < error < fatal

Within the log it is expected to find many info messages, and a few of warn or error types. Of special interest are the errors:

  • There was some error when connecting to MySQL database. The server will not be run: This message may appear when starting the GUI. Most probably the MySQL endpoint is not correct, the MySQL user is not allowed to remotely connect, of there is some network error like a port filtering.
  • There was some error when getting user information from the database: This message may appear when a user gets the main page and his/her session has not yet expired; then, his/her information is retrieved from the database. Most probably some network error is avoiding to get that information, since the initial connection to the database was successful.
  • There was some error when getting user information from the IdM: This message may appear when a user signs in using his/her Identity Manager (IdM) credentials. Most probably the IdM endpoint is not correct, the client id and secret related to cosmos-gui are not correct or the callback URL has not been properly set.
  • There was some error when adding information in the database for user \: This message may appear when a new fresh user has accessed the GUI for the first time. Most probably some network error is avoiding to get that information, since the initial connection to the database was successful.
  • There was an error while adding the Unix user \<unix_user>: This message may appear once the user has successfully signed in and the GUI starts provisioning his/her Cosmos account. Most probably, the user configured for the storage or computing cluster is not a sudoer, or there is some network error with the ssh access.
  • There was an error while creating the HDFS folder for user \<cosmos_user>: This message may appear once the user has successfully signed in and the GUI starts provisioning his/her Cosmos account. Most probably, the user configured for the storage or computing cluster is not a sudoer, or there is some network error with the ssh access.
  • There was an error while changing the ownership of /user/\<cosmos_user>: This message may appear once the user has successfully signed in and the GUI starts provisioning his/her Cosmos account. Most probably, the superuser configured for HDFS is not a superuser, or there is some network error with the ssh access.
  • There was an error while changing the permissions to /user/\<cosmos_user>: This message may appear once the user has successfully signed in and the GUI starts provisioning his/her Cosmos account. Most probably, the superuser configured for HDFS is not a superuser, or there is some network error with the ssh access.
  • There was an error while setting the quota to /user/\<cosmos_user>:: This message may appear once the user has successfully signed in and the GUI starts provisioning his/her Cosmos account. Most probably, the superuser configured for HDFS is not a superuser, or there is some network error with the ssh access.

Top

Database

Information regarding registered users in Cosmos can be found in a MySQL table named cosmos_user within a database named cosmos_gui in the MySQL deployment you did when installing the GUI. Such a table contains the IdM username, the Cosmos username, the password and the registration time.

$ mysql -u cb -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
...
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> show databases;
+-----------------------+
| Database              |
+-----------------------+
| information_schema    |
| cosmos                |
| mysql                 |
| test                  |
+-----------------------+
4 rows in set (0.00 sec)

mysql> use cosmos;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql> show tables;
+------------------+
| Tables_in_cosmos |
+------------------+
| cosmos_user      |
| tidoop_job       |
+------------------+
2 rows in set (0.00 sec)

mysql> select * from cosmos_user;
+----------------------------------+--------------------------------------+------------+-----------+---------+---------------------+---------------------+-----------------+-------------------+
| id                               | email                                | hdfs_quota | hdfs_used | fs_used | registration_time   | last_access_time    | num_ssh_conn_ok | num_ssh_conn_fail |
+----------------------------------+--------------------------------------+------------+-----------+---------+---------------------+---------------------+-----------------+-------------------+
| e170190b41724b298862fdc89d32f8e7 | francisco.romerobueno@telefonica.com | 5368709120 |         0 |       0 | 0000-00-00 00:00:00 | 0000-00-00 00:00:00 |               0 |                 0 |
+----------------------------------+--------------------------------------+------------+-----------+---------+---------------------+---------------------+-----------------+-------------------+

368 rows in set (0.00 sec)

Top

Annexes

Annex A: Creating and installing a RSA identity

For this guide we will assume there is a server machine server_vm needed to be accessed by a client machine client_vm.

First of all, log into the server machine as any other sudoer user and create the cosmos-sudo user:

$ sudo useradd cosmos-sudo

Do not add a password to the cosmos-sudo user since only the ssh keypair will be used for authentication.

Add this user to the sudoers group:

$ visudo

Add the following line to the appropriate section:

cosmos  ALL=(ALL)       ALL

Now, log as cosmos-sudo and create the ssh keypair; when prompted for the passphrase, leave it empty; use the default id_rsa name for the private key (id_rsa.pub will be the public counterpart):

$ su - cosmos-sudo
$ ssh-keygen

Despite the empty passphrase, it is necessary to remove it (it exists, but it is empty):

$ openssl rsa -in ./ssh/id_rsa -out ./ssh/id_rsa2

Then, change the permissions of the private key, the default ones are too open:

$ chmod 600 ./ssh/id_rsa2

The private key must be copied somewhere the GUI running in the client machine may found it within the cosmos-gui user account, let's say fiware-cosmos/cosmos-gui/conf/:

$ scp ./ssh/id_rsa2 cosmos-gui@client_vm:/home/cosmos-gui/fiware-cosmos/cosmos-gui/conf/

Copy the public key to the authorized_keys file as well; this file is read by ssh when authenticating as the cosmos-sudo user:

$ cat /home/cosmos-sudo/.ssh/id_rsa.pub >> /home/cosmos-sudo/.ssh/authorized_keys

Finally, you can check the access from the client machine:

$ su - cosmos-gui
$ ssh -i conf/id_rsa2 cosmos@server_vm

Top

Annex B: Creating a self-signed certificate

First of all, create a private key; it may not be necessary if you already have one:

$ openssl genrsa -out private-key.pem 1024

Second, create a Certificate Signing Request (CSR) using the private key:

$ openssl req -new -key private-key.pem -out csr.pem

Finally, create the self-signed certificate:

$ openssl x509 -req -in csr.pem -signkey private-key.pem -out public-cert.pem -days 1000

Please observe a duration of 1000 days for the certificate has been specified.

Top

Annex C: Binding the GUI to a port under TCP/1024

This GUI may run in any port the user configures. Nevertheless, most of the Unix-like systems avoid non sudoer users to bind applications to ports under 1024. Since the cosmos-gui user is not a sudoer one, you won't be able to run the GUI in the typical TCP/443 port, for instance.

In order to solve this, there are several possibilities. One of them is setting the cap_net_bind_service capability:

$ setcap cap_net_bind_service=+ep /path/to/cosmos-gui

Nevertheless, the above shows some problems, for instance, it is only valid for kernels over 2.6.24, and Linux will disable LD_LIBRARY_PATH on any program that has elevated privileges like setcap or suid.

Another one option (the preferred one) is to use port forwarding. By using this technique, the GUI is run on a port over 1024 (e.g. 9090) and an iptables rule is configured this way:

$ iptables -A PREROUTING -t nat -p tcp --dport 443 -j REDIRECT --to-port 9090

Which means all the traffic sent to the TCP/443 port will be forwarded to real binding port, TCP/9090.

Top