One place for hosting & domains

      Secure

      How To Secure Apache with Let’s Encrypt on FreeBSD 12.0


      The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.

      Introduction

      Let’s Encrypt is a Certificate Authority (CA) that provides an easy way to obtain and install free TLS/SSL certificates, thereby enabling encrypted HTTPS on web servers. It simplifies the process by providing a software client, Certbot, that attempts to automate most (if not all) of the required steps.

      In this tutorial, you will use Certbot to set up a TLS/SSL certificate from Let’s Encrypt on a FreeBSD 12.0 server running Apache as a web server. Additionally, you will automate the certificate renewal process using a cron job.

      Prerequisites

      Before you begin this guide you’ll need the following:

      • A FreeBSD 12.0 server that you can set up as you wish using this guide on How To Get Started with FreeBSD.

      • Apache installed by completing Step 1 of this FAMP stack tutorial.

      • An enabled firewall by using the firewall configuration step in this tutorial instructions.

      • Two DNS A Records that point your domain to the public IP address of your server. Our setup will use your-domain and www.your-domain as the domain names, both of which will require a valid DNS record. You can follow this introduction to DigitalOcean DNS for details on how to add the DNS records with the DigitalOcean platform. DNS A records are required because of how Let’s Encrypt validates that you own the domain for which it is issuing a certificate. For example, if you want to obtain a certificate for your-domain, that domain must resolve to your server for the validation process to work.

      Once these prerequisites are fulfilled you can start installing Certbot, the tool that will allow you to install Let’s Encrypt certificates.

      A Let’s Encrypt certificate ensures that users’ browsers can verify that the web server is secured by a trusted Certificate Authority. Communications with the web server are protected by encryption using HTTPS.

      In this step you’ll install the Certbot tool for your web server to make a request to the Let’s Encrypt servers in order to issue a valid certificate and keys for your domain.

      Run the following command to install the Certbot package and its Apache HTTP plugin:

      • sudo pkg install -y py36-certbot py36-certbot-apache

      Now that you’ve installed the package, you can move on to enable TLS connections in the web server.

      Step 2 — Enabling SSL/TLS connections in Apache HTTP

      By default any install of Apache HTTP will be serving content on port 80 (HTTP). The Listen 80 entry in the main httpd.conf configuration file confirms this. In order to allow HTTPS connections, you’ll need the default port to be 443. To add port 443 and to establish SSL/TLS connections you’ll enable the mod_ssl module in Apache HTTP.

      To find this module in the httpd.conf file, you’ll use grep with the -n flag to number the lines from the file in the specified path. Here you’ll find mod_ssl.so by running the following command:

      • grep -n 'mod_ssl.so' /usr/local/etc/apache24/httpd.conf

      As output you’ll receive the number for the line you need:

      /usr/local/etc/apache24/httpd.conf

      148 #LoadModule ssl_module libexec/apache24/mod_ssl.so
      

      To enable the module, you’ll remove the hashtag symbol at the beginning of the line.

      Using the line number from the previous command open the file with the following:

      • sudo vi +148 /usr/local/etc/apache24/httpd.conf

      This will take you directly to the correct line for editing.

      Edit the line to look like the following by pressing x:

      /usr/local/etc/apache24/httpd.conf

      #LoadModule session_dbd_module libexec/apache24/mod_session_dbd.so
      #LoadModule slotmem_shm_module libexec/apache24/mod_slotmem_shm.so
      #LoadModule slotmem_plain_module libexec/apache24/mod_slotmem_plain.so
      LoadModule ssl_module libexec/apache24/mod_ssl.so
      #LoadModule dialup_module libexec/apache24/mod_dialup.so
      #LoadModule http2_module libexec/apache24/mod_http2.so
      #LoadModule proxy_http2_module libexec/apache24/mod_proxy_http2.so
      

      Once you’ve removed the #, press :wq and then ENTER to close the file.

      You’ve enabled the SSL/TLS capabilities in Apache HTTP. In the next step you’ll configure the virtual hosts in Apache HTTP.

      Step 3 — Enabling and Configuring Virtual Hosts

      A virtual host is a method by which several websites can concurrently and independently live in the same server using the same Apache HTTP installation. Certbot requires this setup to place specific rules within the configuration file (virtual host) for the Let’s Encrypt certificates to work.

      To begin, you’ll enable virtual hosts in Apache HTTP. Run the following command to locate the directive in the file:

      • grep -n 'vhosts' /usr/local/etc/apache24/httpd.conf

      You’ll see the line number in your output:

      Output

      508 #Include etc/apache24/extra/httpd-vhosts.conf

      Now use the following command to edit the file and remove # from the beginning of that line:

      • sudo vi +508 /usr/local/etc/apache24/httpd.conf

      As before, hit x to delete # from the beginning of the line to look like the following:

      /usr/local/etc/apache24/httpd.conf

      ...
      # User home directories
      #Include etc/apache24/extra/httpd-userdir.conf
      
      # Real-time info on requests and configuration
      #Include etc/apache24/extra/httpd-info.conf
      
      # Virtual hosts
      Include etc/apache24/extra/httpd-vhosts.conf
      
      # Local access to the Apache HTTP Server Manual
      #Include etc/apache24/extra/httpd-manual.conf
      
      # Distributed authoring and versioning (WebDAV)
      #Include etc/apache24/extra/httpd-dav.conf
      ...
      

      Then press :wq and ENTER to save and quit the file.

      Now that you’ve enabled virtual hosts in Apache HTTP you’ll modify the default virtual host configuration file to replace the example domains with your domain name.

      You’ll now add a virtual host block to the httpd-vhosts.conf file. You’ll edit the file and remove the two existing VirtualHost blocks, after the comments block at line 23, with the following command:

      • sudo vi +23 /usr/local/etc/apache24/extra/httpd-vhosts.conf

      After opening the file remove the two existing VirtualHost configuration blocks, then add the following block with this specific configuration:

      /usr/local/etc/apache24/extra/httpd-vhosts.conf

      <VirtualHost *:80>
          ServerAdmin your_email@your_domain.com
          DocumentRoot "/usr/local/www/apache24/data/your_domain.com"
          ServerName your_domain.com
          ServerAlias www.your_domain.com
          ErrorLog "/var/log/your_domain.com-error_log"
          CustomLog "/var/log/your_domain.com-access_log" common
      </VirtualHost>
      

      In this block you’re configuring the following:

      • ServerAdmin: This is where the email from the person in charge of that particular site is placed.
      • DocumentRoot: This directive defines where the files for the specific site will be placed and be read from.
      • ServerName: This is for the domain name of the site.
      • ServerAlias: Similar to ServerName but placing www. before the domain name.
      • ErrorLog: This is where the error log path is declared. All error messages will be written in the file specified in this directive.
      • CustomLog: Similar to ErrorLog but this time the file is the one collecting all the access logs.

      Finally you’ll create the directory where the site will be placed. This path has to match the one you’ve declared in the DocumentRoot directive in the httpd-vhosts.conf file.

      • sudo mkdir /usr/local/www/apache24/data/your_domain.com

      Now change the permissions of the directory so the Apache HTTP process (running as the www user) can work with it:

      • sudo chown -R www:www /usr/local/www/apache24/data/your_domain.com

      You’ve used chown to change the ownership with the -R flag to make the action recursive. The user and group are set by the www:www.

      You’ve enabled virtual hosts in Apache HTTP. You’ll now enable the rewrite module.

      Step 4 — Enabling the Rewrite Module

      Enabling the rewrite module within Apache HTTP is necessary to make URLs change, for example when redirecting from HTTP to HTTPS.

      Use the following command to find the rewrite module:

      • grep -n 'rewrite' /usr/local/etc/apache24/httpd.conf

      You’ll see output similar to:

      Output

      180 #LoadModule rewrite_module libexec/apache24/mod_rewrite.so

      To enable the module you will now remove # from the beginning of the line:

      • sudo vi +180 /usr/local/etc/apache24/httpd.conf

      Edit your file to look like the following by hitting x to delete # from the start of the line:

      /usr/local/etc/apache24/httpd.conf

      #LoadModule actions_module libexec/apache24/mod_actions.so
      #LoadModule speling_module libexec/apache24/mod_speling.so
      #LoadModule userdir_module libexec/apache24/mod_userdir.so
      LoadModule alias_module libexec/apache24/mod_alias.so
      LoadModule rewrite_module libexec/apache24/mod_rewrite.so
      LoadModule php7_module        libexec/apache24/libphp7.so
      
      # Third party modules
      IncludeOptional etc/apache24/modules.d/[0-9][0-9][0-9]_*.conf
      
      <IfModule unixd_module>
      

      Save and exit this file.

      You’ve now finished setting up the necessary configurations in Apache.

      Step 5 — Obtaining a Let’s Encrypt Certificate

      Certbot provides a variety of ways to obtain SSL certificates through various plugins. The apache plugin will take care of reconfiguring Apache HTTP. To execute the interactive installation and obtain a certificate that covers only a single domain, run the following certbot command:

      • sudo certbot --apache -d your-domain -d www.your-domain

      If you want to install a single certificate that is valid for multiple domains or subdomains, you can pass them as additional parameters to the command, tagging each new domain or subdomain with the -d flag. The first domain name in the list of parameters will be the base domain used by Let’s Encrypt to create the certificate. For this reason, pass the base domain name first, followed by any additional subdomains or aliases.

      If this is your first time running certbot on this server, the client will prompt you to enter an email address and agree to the Let’s Encrypt terms of service. After doing so, certbot will communicate with the Let’s Encrypt server, then run a challenge to verify that you control the domain you’re requesting a certificate for.

      If the challenge is successful, Certbot will ask how you’d like to configure your HTTPS settings:

      Output

      . . . Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access. ------------------------------------------------------------------------------- 1: No redirect - Make no further changes to the webserver configuration. 2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for new sites, or if you're confident your site works on HTTPS. You can undo this change by editing your web server's configuration. ------------------------------------------------------------------------------- Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2

      You will also be able to choose between enabling both HTTP and HTTPS access or forcing all requests to redirect to HTTPS. For better security, it is recommended to choose the option 2: Redirect if you do not have any special need to allow unencrypted connections. Select your choice then hit ENTER.

      This will update the configuration and reload Apache HTTP to pick up the new settings. certbot will wrap up with a message telling you the process was successful and where your certificates are stored:

      Output

      IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /usr/local/etc/letsencrypt/live/example.com/fullchain.pem Your key file has been saved at: /usr/local/etc/letsencrypt/live/example.com/privkey.pem Your cert will expire on yyyy-mm-dd. To obtain a new or tweaked version of this certificate in the future, simply run certbot again. To non-interactively renew *all* of your certificates, run "certbot renew" - Your account credentials have been saved in your Certbot configuration directory at /usr/local/etc/letsencrypt. You should make a secure backup of this folder now. This configuration directory will also contain certificates and private keys obtained by Certbot so making regular backups of this folder is ideal. - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate Donating to EFF: https://eff.org/donate-le

      Your certificates are now downloaded, installed, and configured. Try reloading your website using https:// and notice your browser’s security indicator. It’ll represent that the site is properly secured, usually with a green lock icon. If you test your server using the SSL Labs Server Test, it will get an A grade.

      Certbot has made some important configuration changes. When it installs the certificates in your web server it has to place them in specific paths. If you now read the content in the httpd-vhosts.conf file you’ll observe a few changes made by the Certbot program.

      For example in the <VirtualHost *:80> section the redirect rules (if chosen) are placed at the bottom of it.

      /usr/local/etc/apache24/extra/httpd-vhosts.conf

      RewriteEngine on
      RewriteCond %{SERVER_NAME} =www.your_domain.com [OR]
      RewriteCond %{SERVER_NAME} =your_domain.com
      RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
      

      Certbot has also created a file called httpd-vhosts-le-ssl.conf where the configuration for the certificates on Apache has been placed:

      /usr/local/etc/apache24/extra/httpd-vhosts-le-ssl.conf

      <IfModule mod_ssl.c>
      <VirtualHost *:443>
          ServerAdmin your_email@your_domain.com
          DocumentRoot "/usr/local/www/apache24/data/your_domain.com"
          ServerName your_domain.com
          ServerAlias www.your_domain.com
          ErrorLog "/var/log/your_domain.com-error_log"
          CustomLog "/var/log/your_domain.com-access_log" common
      
      Include /usr/local/etc/letsencrypt/options-ssl-apache.conf
      SSLCertificateFile /usr/local/etc/letsencrypt/live/your_domain.com/fullchain.pem
      SSLCertificateKeyFile /usr/local/etc/letsencrypt/live/your_domain.com/privkey.pem
      </VirtualHost>
      </IfModule>
      

      Note: If you would like to make changes to the use of cipher suites on sites with Let’s Encrypt certificates, you can do so in the /usr/local/etc/letsencrypt/options-ssl-apache.conf file.

      Having obtained your Let’s Encrypt certificate, you can now move on to set up automatic renewals.

      Step 6 — Configuring Automatic Certificate Renewal

      Let’s Encrypt certificates are valid for 90 days, but it’s recommended that you renew the certificates every 60 days to allow a margin of error. Because of this, it is best practice to automate this process to periodically check and renew the certificate.

      First, let’s examine the command that you will use to renew the certificate. The certbot Let’s Encrypt client has a renew command that automatically checks the currently installed certificates and tries to renew them if they are less than 30 days away from the expiration date. By using the --dry-run option, you can run a simulation of this task to test how renew works:

      • sudo certbot renew --dry-run

      A practical way to ensure your certificates will not get outdated is to create a cron job that will periodically execute the automatic renewal command for you. Since the renewal first checks for the expiration date and only executes the renewal if the certificate is less than 30 days away from expiration, it is safe to create a cron job that runs every week or even every day.

      The official Certbot documentation recommends running cron twice per day. This will ensure that, in case Let’s Encrypt initiates a certificate revocation, there will be no more than half a day before Certbot renews your certificate.

      Edit the crontab to create a new job that will run the renewal twice per day. To edit the crontab for the root user, run:

      Place the following configuration in the file so that, twice a day, the system will look for renewable certificates and will renew them if they need to:

      SHELL=/bin/sh
      PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
      # Order of crontab fields
      # minute    hour    mday    month   wday    command
        0         0,12    *       *       *       /usr/local/bin/certbot renew
      

      In the first two lines you are declaring the environment variables, hence where the executable paths are found and what shell they’re executing on. You then indicate the time frames you’re interested in and the command to execute.

      With this short set of instructions you’ve configured the automatic renewal of certificates.

      Conclusion

      In this tutorial, you’ve installed the Let’s Encrypt client certbot, downloaded SSL certificates for a domain, configured Apache to use these certificates, and set up automatic certificate renewal. For further information see Certbot’s documentation.



      Source link

      How to Install and Secure the Mosquitto MQTT Messaging Broker on Debian 10


      Introduction

      MQTT is a machine-to-machine messaging protocol, designed to provide lightweight publish/subscribe communication to “Internet of Things” devices. It is commonly used for geo-tracking fleets of vehicles, home automation, environmental sensor networks, and utility-scale data collection.

      Mosquitto is a popular MQTT server (or broker, in MQTT parlance) that has great community support and is easy to install and configure.

      In this tutorial, we’ll install Mosquitto and set up our broker to use SSL to secure our password-protected MQTT communications.

      Prerequisites

      Before starting this tutorial, you will need:

      Step 1 — Installing Mosquitto

      Debian 10 has a fairly recent version of Mosquitto in its default software repository, so we can install it from there.

      First, log in using your non-root user and update the package lists using apt update:

      Now, install Mosquitto using apt install:

      • sudo apt install mosquitto mosquitto-clients

      By default, Debian will start the Mosquitto service after install. Let’s test the default configuration. We’ll use one of the Mosquitto clients we just installed to subscribe to a topic on our broker.

      Topics are labels that you publish messages to and subscribe to. They are arranged as a hierarchy, so you could have sensors/outside/temp and sensors/outside/humidity, for example. How you arrange topics is up to you and your needs. Throughout this tutorial we will use a simple test topic to test our configuration changes.

      Log in to your server a second time, so you have two terminals side-by-side. In the new terminal, use mosquitto_sub to subscribe to the test topic:

      • mosquitto_sub -h localhost -t test

      -h is used to specify the hostname of the MQTT server, and -t is the topic name. You’ll see no output after hitting ENTER because mosquitto_sub is waiting for messages to arrive. Switch back to your other terminal and publish a message:

      • mosquitto_pub -h localhost -t test -m "hello world"

      The options for mosquitto_pub are the same as mosquitto_sub, though this time we use the additional -m option to specify our message. Hit ENTER, and you should see hello world pop up in the other terminal. You’ve sent your first MQTT message!

      Enter CTRL+C in the second terminal to exit out of mosquitto_sub, but keep the connection to the server open. We’ll use it again for another test in Step 5.

      Next, we’ll secure our installation using password-based authentication.

      Step 2 — Configuring MQTT Passwords

      Let’s configure Mosquitto to use passwords. Mosquitto includes a utility to generate a special password file called mosquitto_passwd. This command will prompt you to enter a password for the specified username, and place the results in /etc/mosquitto/passwd.

      • sudo mosquitto_passwd -c /etc/mosquitto/passwd sammy

      Now we’ll open up a new configuration file for Mosquitto and tell it to use this password file to require logins for all connections:

      • sudo nano /etc/mosquitto/conf.d/default.conf

      This should open an empty file. Paste in the following:

      /etc/mosquitto/conf.d/default.conf

      allow_anonymous false
      password_file /etc/mosquitto/passwd
      
      

      Be sure to leave a trailing newline at the end of the file.

      allow_anonymous false will disable all non-authenticated connections, and the password_file line tells Mosquitto where to look for user and password information. Save and exit the file.

      Now we need to restart Mosquitto and test our changes.

      • sudo systemctl restart mosquitto

      Try to publish a message without a password:

      • mosquitto_pub -h localhost -t "test" -m "hello world"

      The message should be rejected:

      Output

      Connection Refused: not authorised. Error: The connection was refused.

      Before we try again with the password, switch to your second terminal window again, and subscribe to the ‘test’ topic, using the username and password this time:

      • mosquitto_sub -h localhost -t test -u "sammy" -P "password"

      It should connect and sit, waiting for messages. You can leave this terminal open and connected for the rest of the tutorial, as we’ll periodically send it test messages.

      Now publish a message with your other terminal, again using the username and password:

      • mosquitto_pub -h localhost -t "test" -m "hello world" -u "sammy" -P "password"

      The message should go through as in Step 1. We’ve successfully added password protection to Mosquitto. Unfortunately, we’re sending passwords unencrypted over the internet. We’ll fix that next by adding SSL encryption to Mosquitto.

      Step 3 — Configuring MQTT SSL

      To enable SSL encryption, we need to tell Mosquitto where our Let’s Encrypt certificates are stored. Open up the configuration file we previously started:

      • sudo nano /etc/mosquitto/conf.d/default.conf

      Paste in the following at the end of the file, leaving the two lines we already added:

      /etc/mosquitto/conf.d/default.conf

      . . .
      listener 1883 localhost
      
      listener 8883
      certfile /etc/letsencrypt/live/mqtt.example.com/cert.pem
      cafile /etc/letsencrypt/live/mqtt.example.com/chain.pem
      keyfile /etc/letsencrypt/live/mqtt.example.com/privkey.pem
      
      

      Again, be sure to leave a trailing newline at the end of the file.

      We’re adding two separate listener blocks to the config. The first, listener 1883 localhost, updates the default MQTT listener on port 1883, which is what we’ve been connecting to so far. 1883 is the standard unencrypted MQTT port. The localhost portion of the line instructs Mosquitto to only bind this port to the localhost interface, so it’s not accessible externally. External requests would have been blocked by our firewall anyway, but it’s good to be explicit.

      listener 8883 sets up an encrypted listener on port 8883. This is the standard port for MQTT + SSL, often referred to as MQTTS. The next three lines, certfile, cafile, and keyfile, all point Mosquitto to the appropriate Let’s Encrypt files to set up the encrypted connections.

      Save and exit the file, then restart Mosquitto to update the settings:

      • sudo systemctl restart mosquitto

      Update the firewall to allow connections to port 8883.

      Output

      Rule added Rule added (v6)

      Now we test again using mosquitto_pub, with a few different options for SSL:

      • mosquitto_pub -h mqtt.example.com -t test -m "hello again" -p 8883 --capath /etc/ssl/certs/ -u "sammy" -P "password"

      Note that we’re using the full hostname instead of localhost. Because our SSL certificate is issued for mqtt.example.com, if we attempt a secure connection to localhost we’ll get an error saying the hostname does not match the certificate hostname (even though they both point to the same Mosquitto server).

      --capath /etc/ssl/certs/ enables SSL for mosquitto_pub, and tells it where to look for root certificates. These are typically installed by your operating system, so the path is different for Mac OS, Windows, etc. mosquitto_pub uses the root certificate to verify that the Mosquitto server’s certificate was properly signed by the Let’s Encrypt certificate authority. It’s important to note that mosquitto_pub and mosquitto_sub will not attempt an SSL connection without this option (or the similar --cafile option), even if you’re connecting to the standard secure port of 8883.

      If all goes well with the test, we’ll see hello again show up in the other mosquitto_sub terminal. This means your server is fully set up! If you’d like to extend the MQTT protocol to work with websockets, you can follow the final step.

      Step 4 — Configuring MQTT Over Websockets (Optional)

      In order to speak MQTT using JavaScript from within web browsers, the protocol was adapted to work over standard websockets. If you don’t need this functionality, you may skip this step.

      We need to add one more listener block to our Mosquitto config:

      • sudo nano /etc/mosquitto/conf.d/default.conf

      At the end of the file, add the following:

      /etc/mosquitto/conf.d/default.conf

      . . .
      listener 8083
      protocol websockets
      certfile /etc/letsencrypt/live/mqtt.example.com/cert.pem
      cafile /etc/letsencrypt/live/mqtt.example.com/chain.pem
      keyfile /etc/letsencrypt/live/mqtt.example.com/privkey.pem
      
      

      Again, be sure to leave a trailing newline at the end of the file.

      This is mostly the same as the previous block, except for the port number and the protocol websockets line. There is no official standardized port for MQTT over websockets, but 8083 is the most common.

      Save and exit the file, then restart Mosquitto.

      • sudo systemctl restart mosquitto

      Now, open up port 8083 in the firewall.

      To test this functionality, we’ll use a public, browser-based MQTT client. There are a few out there, but the Eclipse Paho JavaScript Client is simple and straightforward to use. Open the Paho client in your browser. You’ll see the following:

      Paho Client Screen

      Fill out the connection information as follows:

      • Host should be the domain for your Mosquitto server, mqtt.example.com.
      • Port should be 8083.
      • ClientId can be left to the default value, js-utility-DI1m6.
      • Path can be left to the default value, /mqtt.
      • Username should be your Mosquitto username; here, we used sammy.
      • Password should be the password you chose.

      The remaining fields can be left to their default values.

      After pressing Connect, the Paho browser-based client will connect to your Mosquitto server.

      To publish a message, navigate to the Publish Message pane, fill out Topic as test, and enter any message in the Message section. Next, press Publish. The message will show up in your mosquitto_sub terminal.

      Conclusion

      We’ve now set up a secure, password-protected and SSL-secured MQTT server. This can serve as a robust and secure messaging platform for whatever projects you dream up. Some popular software and hardware that work well with the MQTT protocol include:

      • OwnTracks, an open-source geo-tracking app you can install on your phone. OwnTracks will periodically report position information to your MQTT server, which you could then store and display on a map, or create alerts and activate IoT hardware based on your location.
      • Node-RED is a browser-based graphical interface for 'wiring’ together the Internet of Things. You drag the output of one node to the input of another, and can route information through filters, between various protocols, into databases, and so on. MQTT is very well supported by Node-RED.
      • The ESP32 is an inexpensive wifi microcontroller with MQTT capabilities. You could wire one up to publish temperature data to a topic, or perhaps subscribe to a barometric pressure topic and sound a buzzer when a storm is coming!

      These are just a few popular examples from the MQTT ecosystem. There is much more hardware and software out there that speaks the protocol. If you already have a favorite hardware platform, or software language, it probably has MQTT capabilities. Have fun getting your “things” talking to each other!



      Source link

      How To Install and Secure Grafana on Ubuntu 18.04


      The author selected Dev Color to receive a donation as part of the Write for DOnations program.

      Introduction

      Grafana is an open-source data visualization and monitoring tool that integrates with complex data from sources like Prometheus, InfluxDB, Graphite, and ElasticSearch. Grafana lets you create alerts, notifications, and ad-hoc filters for your data while also making collaboration with your teammates easier through built-in sharing features.

      In this tutorial, you will install Grafana and secure it with an SSL certificate and an Nginx reverse proxy. Once you have set up Grafana, you’ll have the option to configure user authentication through GitHub, allowing you to better organize your team permissions.

      Prerequisites

      To follow this tutorial, you will need:

      Step 1 — Installing Grafana

      In this first step, you will install Grafana onto your Ubuntu 18.04 server. You can install Grafana either by downloading it directly from its official website or by going through an APT repository. Because an APT repository makes it easier to install and manage Grafana’s updates, you’ll use that method in this tutorial.

      Although Grafana is available in the official Ubuntu 18.04 packages repository, the version of Grafana there may not be the latest, so use Grafana’s official repository.

      Download the Grafana GPG key with wget, then pipe the output to apt-key. This will add the key to your APT installation’s list of trusted keys, which will allow you to download and verify the GPG-signed Grafana package.

      • wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -

      In this command, the option -q turns off the status update message for wget, and -O outputs the file that you downloaded to the terminal. These two options ensure that only the contents of the downloaded file are pipelined to apt-key.

      Next, add the Grafana repository to your APT sources:

      • sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"

      Refresh your APT cache to update your package lists:

      Next, make sure Grafana will be installed from the Grafana repository:

      The output of the previous command tells you the version of Grafana that you are about to install, and where you will retrieve the package from. Verify that the installation candidate at the top of the list will come from the official Grafana repository at https://packages.grafana.com/oss/deb.

      Output of apt-cache policy grafana

      grafana: Installed: (none) Candidate: 6.3.3 Version table: 6.3.3 500 500 https://packages.grafana.com/oss/deb stable/main amd64 Packages …

      You can now proceed with the installation:

      Once Grafana is installed, use systemctl to start the Grafana server:

      • sudo systemctl start grafana-server

      Next, verify that Grafana is running by checking the service’s status:

      • sudo systemctl status grafana-server

      You will receive output similar to this:

      Output of grafana-server status

      ● grafana-server.service - Grafana instance Loaded: loaded (/usr/lib/systemd/system/grafana-server.service; disabled; vendor preset: enabled) Active: active (running) since Tue 2019-08-13 08:22:30 UTC; 11s ago Docs: http://docs.grafana.org Main PID: 13630 (grafana-server) Tasks: 7 (limit: 1152) …

      This output contains information about Grafana’s process, including its status, Main Process Identifier (PID), and more. active (running) shows that the process is running correctly.

      Lastly, enable the service to automatically start Grafana on boot:

      • sudo systemctl enable grafana-server

      You will receive the following output:

      Output of systemctl enable grafana-server

      Synchronizing state of grafana-server.service with SysV service script with /lib/systemd/systemd-sysv-install. Executing: /lib/systemd/systemd-sysv-install enable grafana-server Created symlink /etc/systemd/system/multi-user.target.wants/grafana-server.service → /usr/lib/systemd/system/grafana-server.service.

      This confirms that systemd has created the necessary symbolic links to autostart Grafana.

      Grafana is now installed and ready for use. Next, you wil secure your connection to Grafana with a reverse proxy and SSL certificate.

      Step 2 — Setting Up the Reverse Proxy

      Using an SSL certificate will ensure that your data is secure by encrypting the connection to and from Grafana. But, to make use of this connection, you’ll first need to reconfigure Nginx as a reverse proxy for Grafana.

      Open the Nginx configuration file you created when you set up the Nginx server block with Let’s Encrypt in the Prerequisites. You can use any text editor, but for this tutorial we’ll use nano:

      • sudo nano /etc/nginx/sites-available/your_domain

      Locate the following block:

      /etc/nginx/sites-available/your_domain

      …
          location / {
              try_files $uri $uri/ =404;
          }
      …
      

      Because you already configured Nginx to communicate over SSL and because all web traffic to your server already passes through Nginx, you just need to tell Nginx to forward all requests to Grafana, which runs on port 3000 by default.

      Delete the existing try_files line in this location block and replace it with the following proxy_pass option.

      /etc/nginx/sites-available/your_domain

      …
          location / {
              proxy_pass http://localhost:3000;
          }
      …
      

      This will map the proxy to the appropriate port. Once you’re done, save and close the file by pressing CTRL+X, followed by Y and then ENTER if you’re using nano.

      Now, test the new settings to make sure everything is configured correctly:

      You will receive the following output:

      Output

      nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful

      Finally, activate the changes by reloading Nginx:

      • sudo systemctl reload nginx

      You can now access the default Grafana login screen by pointing your web browser to https://your_domain. If you’re unable to reach Grafana, verify that your firewall is set to allow traffic on port 443 and then re-trace the previous instructions.

      With the connection to Grafana encrypted, you can now implement additional security measures, starting with changing Grafana’s default administrative credentials.

      Step 3 — Updating Credentials

      Because every Grafana installation uses the same administrative credentials by default, it is best practice to change your login information as soon as possible. In this step, you’ll update the credentials to improve security.

      Start by navigating to https://your_domain from your web browser. This will bring up the default login screen where you’ll see the Grafana logo, a form asking you to enter an email or username and password, a Log in button, and a Forgot your password? link.

      Grafana Login

      Enter admin into both the User and Password fields and then click on the Log in button.

      On the next screen, you’ll be asked to make your account more secure by changing the default password:

      Change Password

      Enter the password you’d like to start using into the New password and Confirm new password fields.

      From here, you can click Save to save the new information or press Skip to skip this step. If you skip, you will be prompted to change the password next time you login.

      In order to increase the security of your Grafana setup, click Save. You’ll return to the Home Dashboard page:

      Home Dashboard

      You’ve now secured your account by changing the default credentials. Next, you will make changes to your Grafana configuration so that nobody can create a new Grafana account without your permission.

      Step 4 — Disabling Grafana Registrations and Anonymous Access

      Grafana provides options that allow visitors to create user accounts for themselves and preview dashboards without registering. When Grafana isn’t accessible via the internet or when it’s working with publicly available data like service statuses, you may want to allow these features. However, when using Grafana online to work with sensitive data, anonymous access could be a security problem. To fix this problem, make some changes to your Grafana configuration.

      Start by opening Grafana’s main configuration file for editing:

      • sudo nano /etc/grafana/grafana.ini

      Locate the following allow_sign_up directive under the [users] heading:

      /etc/grafana/grafana.ini

      …
      [users]
      # disable user signup / registration
      ;allow_sign_up = true
      …
      

      Enabling this directive with true adds a Sign Up button to the login screen, allowing users to register themselves and access Grafana.

      Disabling this directive with false removes the Sign Up button and strengthens Grafana’s security and privacy.

      Uncomment this directive by removing the ; at the beginning of the line and then setting the option to false:

      /etc/grafana/grafana.ini

      …
      [users]
      # disable user signup / registration
      allow_sign_up = false

      Next, locate the following enabled directive under the [auth.anonymous] heading:

      /etc/grafana/grafana.ini

      …
      [auth.anonymous]
      # enable anonymous access
      ;enabled = false
      …
      

      Setting enabled to true gives non-registered users access to your dashboards; setting this option to false limits dashboard access to registered users only.

      Uncomment this directive by removing the ; at the beginning of the line and then setting the option to false.

      /etc/grafana/grafana.ini

      …
      [auth.anonymous]
      enabled = false

      Save the file and exit your text editor.

      To activate the changes, restart Grafana:

      • sudo systemctl restart grafana-server

      Verify that everything is working by checking Grafana’s service status:

      • sudo systemctl status grafana-server

      Like before, the output will report that Grafana is active (running).

      Now, point your web browser to https://your_domain. To return to the Sign Up screen, bring your cursor to your avatar in the lower left of the screen and click on the Sign out option that appears.

      Once you have signed out, verify that there is no Sign Up button and that you can’t sign in without entering login credentials.

      At this point, Grafana is fully configured and ready for use. Next, you can simplify the login process for your organization by authenticating through GitHub.

      (Optional) Step 5 — Setting Up a GitHub OAuth App

      For an alternative approach to signing in, you can configure Grafana to authenticate through GitHub, which provides login access to all members of authorized GitHub organizations. This can be particularly useful when you want to allow multiple developers to collaborate and access metrics without having to create Grafana-specific credentials.

      Start by logging into a GitHub account associated with your organization and then navigate to your GitHub profile page at https://github.com/settings/profile.

      Click on your organization’s name under Organization settings in the navigation menu on the left-hand side of the screen.

      GitHub Organization settings

      On the next screen, you’ll see your Organization profile where you can change settings like your Organization display name, organization Email, and organization URL.

      Because Grafana uses OAuth — an open standard for granting remote third parties access to local resources — to authenticate users through GitHub, you’ll need to create a new OAuth application within GitHub.

      Click the OAuth Apps link under Developer settings on the lower left-hand side of the screen.

      If you don’t already have any OAuth applications associated with your organization on GitHub, you’ll be told there are No Organization Owned Applications. Otherwise, you’ll see a list of the OAuth applications already connected to your account.

      Click the Register an application button to continue.

      On the next screen, fill in the following details about your Grafana installation:

      • Application name - This helps you distinguish your different OAuth applications from one another.
      • Homepage URL - This tells GitHub where to find Grafana. Type https://your_domain into this field, replacing your_domain with your domain.
      • Application Description - This provides a description of your OAuth application’s purpose.
      • Application callback URL - This is the address where users will be sent once successfully authenticated. For Grafana, this field must be set to https://your_domain/login/github.

      Keep in mind that Grafana users logging in through GitHub will see the values you entered in the first three preceding fields, so be sure to enter something meaningful and appropriate.

      When completed, the form will look something like:

      GitHub Register OAuth Application

      Click the green, Register application button.

      You will now be redirected to a page containing the Client ID and Client Secret associated with your new OAuth application. Make note of both values, because you will need to add them to Grafana’s main configuration file to complete the setup.

      Warning: Make sure to keep your Client ID and Client Secret in a secure and non-public location, because they could be used as the basis of an attack.

      With your GitHub OAuth application created, you’re now ready to reconfigure Grafana to use GitHub for authentication.

      (Optional) Step 6 — Configuring Grafana as a GitHub OAuth App

      To complete GitHub authentication for your Grafana setup, you will now make some changes to your Grafana configuration files.

      To begin, open the main Grafana configuration file.

      • sudo nano /etc/grafana/grafana.ini

      Locate the [auth.github] heading, and uncomment this section by removing the ; at the beginning of every line except ;team_ids=, which will not be changed in this tutorial.

      Next, configure Grafana to use GitHub with your OAuth application’s client_id and client_secret values.

      • Set enabled and allow_sign_up to true. This will enable GitHub Authentication and permit members of the allowed organization to create accounts themselves. Note that this setting is different than the allow_sign_up property under [users] that you changed in Step 4.
      • Set client_id and client_secret to the values you got while creating your GitHub OAuth application.
      • Set allowed_organizations to the name of your organization to ensure that only members of your organization can sign up and log into Grafana.

      The complete configuration will look like:

      /etc/grafana/grafana.ini

      …
      [auth.github]
      enabled = true
      allow_sign_up = true
      client_id = your_client_id_from_github
      client_secret = your_client_secret_from_github
      scopes = user:email,read:org
      auth_url = https://github.com/login/oauth/authorize
      token_url = https://github.com/login/oauth/access_token
      api_url = https://api.github.com/user
      ;team_ids =
      allowed_organizations = your_organization_name

      You’ve now told Grafana everything it needs to know about GitHub. To complete the setup, you’ll need to enable redirects behind a reverse proxy. This is done by setting a root_url value under the [server] heading.

      /etc/grafana/grafana.ini

      …
      [server]
      root_url = https://your_domain

      Save your configuration and close the file.

      Then, restart Grafana to activate the changes:

      • sudo systemctl restart grafana-server

      Lastly, verify that the service is up and running.

      • sudo systemctl status grafana-server

      The output will indicate that the service is active (running).

      Now, test your new authentication system by navigating to https://your_domain. If you are already logged into Grafana, hover your mouse over the avatar log in the lower left-hand corner of the screen, and click on Sign out in the secondary menu that appears next to your name.

      On the login page, you’ll see a new section under the original Log in button that includes a Sign in with GitHub button with the GitHub logo.

      Grafana Login page with GitHub

      Click on the Sign in with GitHub button to be redirected to GitHub, where you’ll sign into your GitHub account and confirm your intention to Authorize Grafana.

      Click the green, Authorize your_github_organization button.

      Note: Make sure your GitHub account is a member of your approved organization and your Grafana email address matches your GitHub email address. If you try to authenticate with a GitHub account that isn’t a member of your approved organization, you’ll get a Login Failed message telling you, User not a member of one of the required organizations.

      You will now be logged in with your existing Grafana account. If a Grafana account doesn’t already exist for the user you logged in as, Grafana will create a new user account with Viewer permissions, ensuring that new users can only use existing dashboards.

      To change the default permissions for new users, open the main Grafana configuration file for editing.

      • sudo nano /etc/grafana/grafana.ini

      Locate the auto_assign_org_role directive under the [users] heading, and uncomment the setting by removing the ; at the beginning of the line.

      Set the directive to one of the following values:

      • Viewer — can only use existing dashboards
      • Editor — can change use, modify, and add dashboards
      • Admin — has permission to do everything

      This tutorial will set the auto-assign to Viewer:

      /etc/grafana/grafana.ini

      …
      [users]
      …
      auto_assign_org_role = Viewer

      Once you’ve saved your changes, close the file and restart Grafana:

      • sudo systemctl restart grafana-server

      Check the service’s status:

      • sudo systemctl status grafana-server

      Like before, the status will read active (running).

      At this point, you have fully configured Grafana to allow members of your GitHub organization to register and use your Grafana installation.

      Conclusion

      In this tutorial you installed, configured, and secured Grafana, and you also learned how to permit members of your organization to authenticate through GitHub.

      To extend your current Grafana installation, see the list of official and community-built dashboards. To learn more about using Grafana in general, see the official Grafana documentation, or check out our other monitoring tutorials.



      Source link