Raijin Grafana plugin

Grafana is an open-source analytics and visualization platform that uses plugins to connect to a variety of data sources. For establishing connectivity with Raijin it uses the Raijin Grafana Plugin.

This guide provides instructions on how to deploy Raijin and Grafana on Linux-based systems. Alternatively, you can also try a Docker container-based setup.

Manual setup

Grafana requires TLS for connecting to data sources. Nginx can be used as a proxy for Raijin to provide TLS functionality.

Before proceeding, install Raijin, Nginx, and Grafana according to your platform:

These instructions were tested with the following software versions:

  • Ubuntu 20.04 LTS

  • Raijin 0.9.3901

  • Nginx 1.18.0

  • Grafana 9.0.0

Configuring a TLS-enabled Raijin website

  1. To enable TLS for the Raijin website, you need a valid TLS certificate. Follow these steps to create a certificate using OpenSSL.

    1. If you don’t already have a CA certificate, create one using the following command. This command requires an OpenSSL configuration file. For example, you may use gencert.cnf from our public repository.

      $ SUBJ="/CN=ca/O=nxlog.org/C=HU/ST=state/L=location"
      $ openssl req -x509 -nodes -newkey rsa:2048 -keyout root-ca.key -out root-ca.crt -batch -subj "$SUBJ" -config gencert.cnf -days 3650

      You will need the resulting root-ca.crt and root-ca.key to sign the client certificate.

    2. Create a private key.

      $ openssl genrsa -out server.key 2048
    3. Create a certificate signing request. Execute the following command and follow the instructions. When asked for the common name, enter the name for the Raijin website. We will be using raijin in this example.

      $ openssl req -new -key server.key -out server.csr
    4. Create a raijin.ext file with the following content:

      authorityKeyIdentifier=keyid,issuer
      basicConstraints=CA:FALSE
      keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
      subjectAltName = @alt_names
      
      [alt_names]
      DNS.1 = raijin
    5. Create the client certificate signed by your CA certificate. Replace the certificate paths with the actual paths used on your server.

      $ openssl x509 -req -in server.csr -CA root-ca.crt -CAkey root-ca.key -CAcreateserial -out server.crt -days 3650 -sha256 -extfile raijin.ext
  2. Copy the resulting server.crt and server.key files to a location accessible by Nginx.

  3. Create an Nginx website for Raijin by saving the following configuration in /etc/nginx/sites-available/raijin:

    charset utf-8;
    
    upstream raijin {
      server raijin:2500;
    }
    
    server {
    	listen                 443 ssl;
    	server_name            raijin;
    
    	ssl_certificate        /etc/nginx/ssl/server.crt;
    	ssl_certificate_key    /etc/nginx/ssl/server.key;
    
    	#   Allow TLS version 1.2 only, which is a recommended default
    	#   by international information security standards.
    	ssl_protocols          TLSv1.2 TLSv1.3;
    	ssl_ciphers            HIGH:!aNULL:!MD5;
    	ssl_prefer_server_ciphers  on;
    
    	location / {
    		proxy_pass     http://raijin/;
    		proxy_redirect off;
    	}
    
    	root                   /usr/nginx/html;
    }
  4. Enable the site by creating a symbolic link to the raijin file you just created in the sites-available directory from the /etc/nginx/sites-enabled directory.

    $ sudo ln -s /etc/nginx/sites-available/raijin /etc/nginx/sites-enabled/
  5. Verify that the Raijin website URL resolves to the correct IP. Add the following line to your /etc/hosts file for testing purposes:

    127.0.0.1	localhost raijin
  6. Restart Nginx.

    $ sudo systemctl restart nginx
  7. Open your web browser and verify that you can access the Raijin UI from https://raijin. Until you have added the CA certificate you used above to the trusted root certification authorities in your browser, it will show a certificate error. Follow your brower’s instructions for adding the CA certificate as a trusted root CA.

  8. Verify that Nginx is configured to start automatically.

    $ sudo systemctl enable nginx

Configuring Grafana and the Raijin plugin

  1. Download the grafana_raijin_plugin.tar.gz package from the Downloads page.

  2. Extract the contents of the archive.

    $ tar -xf grafana_raijin_plugin.tar.gz
  3. Copy the extracted plugin directory to the Grafana plugins directory. Its default location is /var/lib/grafana/plugins.

  4. Add the CA certificate used to create the Nginx server certificate above to the trusted certificates. On Debian-based systems:

    1. Copy the certificate to /usr/local/share/ca-certificates.

    2. Execute the command sudo update-ca-certificates.

  5. Verify that the Raijin website URL resolves to the correct IP on the Grafana server. Add the following line to the /etc/hosts file for testing purposes:

    <nginx_server_ip> raijin
  6. Open the Grafana configuration file, by default /etc/grafana/grafana.ini, with a text editor and add the following line under the [plugins] section:

    [plugins]
    allow_loading_unsigned_plugins = nxlog-raijin-datasource
  7. Restart Grafana.

    $ sudo systemctl restart grafana-server
  8. Open the Grafana UI, by default http://localhost:3000/.

  9. Navigate to Configuration > Data Sources.

  10. Click Add data source, and you should find Raijin Data Source Plugin under SQL.

Container-based setup

The raijindb/raijin-grafana container on our Docker Hub page makes it easy to deploy Raijin and Grafana as a Docker application stack. It comprises Raijin, Nginx as a proxy for a TLS-enabled Raijin website, and Grafana with the Raijin Data Source Plugin.

These instructions require Docker Compose and Docker Engine. They have been tested with Docker Desktop 4.9.1 (81317) and Docker Engine 20.10.16.

  1. Download the Raijin Grafana container package from the Downloads page.

  2. Extract the contents of the archive.

    $ tar -xf raijin-grafana-container.tar.gz
  3. Start the container-based setup from the directory where docker-compose.yml is located.

    $ docker-compose up -d
  4. Create a DNS entry for the Raijin website or add the following line to your /etc/hosts file on Linux or C:\Windows\System32\drivers\etc\hosts on Windows for testing purposes:

    127.0.0.1	localhost raijin
  5. After the container starts, you can access the following URLs:

    • https://raijin for the Raijin UI

    • http://localhost:3000 for the Grafana UI

      Your browser will show a certificate error for the Raijin UI until you add the ./ssl/root-ca.crt certificate to the trusted root certification authorities. Follow your browser’s instructions for adding the CA certificate as a trusted root CA.

See the README.md file included in the package for more information on the setup.