OpenLI Tutorial 05: Installing OpenLI
You may either watch the tutorial lesson on YouTube by clicking on the image above, or you can download the slides and read them alongside the transcript provided below.
Hello again and welcome to the fifth lesson in the OpenLI training series. This time around, I’m going to show you how to install the OpenLI components using the software packages that we publish for every OpenLI release. If you are familiar with installing software packages for Debian, Ubuntu or Red Hat derivative Linux distributions then this should all be fairly straightforward for you. Even if you aren’t, this lesson should be comprehensive enough for you to be able to complete a successful installation anyway.
Before we begin, I would like to reiterate that (at present) OpenLI can only be installed and run on machines running Linux -- there are no OpenLI binaries for Windows or Mac OS, nor are there any long-term plans to build OpenLI for those operating systems.
As I already mentioned, we build and distribute software packages for each OpenLI release. Packaged software is far easier for users to install and maintain than building the OpenLI components from the source code. There are no arcane compilation commands for the user to learn and the package manager will automatically detect and install any other software that OpenLI requires before installing the OpenLI package.
Right now, we publish packages for all LTS versions of Debian and Ubuntu, as well as CentOS 7 and Fedora. In the past, we have published CentOS 8 packages but the move towards CentOS Stream has made this distribution much less appealing for our users, as well as made it more difficult for us to release and maintain packages so direct support for CentOS 8 / Stream will soon come to an end.
One slight complication is that the OpenLI software is not currently present in the official package repositories for each of the supported distributions. This means that you will have to take the extra step of adding our repositories to your package sources list before you can begin installing the software.
The repositories that contain OpenLI, as well as some of its dependencies, are hosted on Cloudsmith and can be browsed at the URL shown there on the slide (https://cloudsmith.io/~wand/repos/).
We’re going to begin by walking through an example install for a server running either Ubuntu or Debian Linux. The steps I describe here should be sufficient, but we also include a complete written document of this install process on the OpenLI wiki.
Before we begin, we need to make sure that our server has all of the necessary software to download and run the OpenLI installation scripts. There’s a good chance that you’ll already have both of these packages installed, but better to be safe than sorry.
Do note that all of the installation steps will require you to have root permissions on the machine that you’re installing OpenLI onto, even if that OpenLI component is able to run without root permissions.
Now you can use curl to download and run the scripts that will add the WAND repositories for the libraries that OpenLI depends on to your apt sources list. Obviously, downloading random shell scripts from the Internet and executing them as root is usually not the best idea, so please do consider taking the time to look over the scripts before running these commands directly to make sure that the scripts are not doing anything unexpected.
Now you can add the WAND repository for OpenLI itself using the same process. Again, consider checking over the script before running it, just to be safe.
Once you’ve added those repositories to your apt sources list, you’ll need to run apt update to force your package manager to fetch the latest list of available packages from each repository.
And now you are ready to install the OpenLI components themselves. Each component is its own separate package, so you’ll need to run three separate install commands. In a real OpenLI deployment, each package would be installed on a different host but if you’re just testing and playing around then there is no harm in installing all three packages on the same host.
And that’s all there is to it.
I’ll also now run through the same process for a CentOS 7 install. Once again, there is a wiki page that also documents this process, and includes instructions for Fedora installation as well (https://github.com/wanduow/openli/wiki/Installing-via-RPM).
For the most part, the steps are the same as with a Debian install -- it is just that the commands have different names or use a slightly different syntax.
Before you begin your CentOS install, you need to make sure that your package manager is configured to have access to the EPEL repositories, as there are several key dependencies for OpenLI that are not present in the base official repository for CentOS.
Just running the command shown on the screen (sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm) should be sufficient to add the EPEL repository to your system.
Now we can go ahead and add the WAND Cloudsmith repositories to the yum sources list, using a very similar process to what I demonstrated earlier for the Debian install. If you weren’t paying attention then, I will again remind you to verify the shell scripts that are fetched by these commands before running them, just to make sure that nothing dodgy has snuck in there.
For our CentOS install, there is one extra dependency repository that we need to add, which is the official RabbitMQ repository that hosts the packages for RabbitMQ and erlang. These packages are not available in any official CentOS repositories, so we have to fetch them direct from the RabbitMQ team ourselves. These packages are hosted on packagecloud, rather than cloudsmith, but the process is very similar -- use curl to download a shell script and then pipe it into bash to set up the repository details.
As with the Cloudsmith scripts, don’t hesitate to examine the bash scripts before you run them!
Note that the OpenLI provisioner does not depend on RabbitMQ, so you can skip this step on hosts where you are only installing the provisioner.
The repositories for all of our dependencies are now configured, so we can add the OpenLI repository itself from Cloudsmith. For the last time: the same caveats about downloading and running shell scripts from the Internet apply here.
And now you will be able to use yum to install your desired OpenLI components onto your CentOS system. As with the Debian version, each component is its own separate package but they can happily co-exist on the same machine for testing and experimentation purposes.
Regardless of whether you install OpenLI on Debian, Ubuntu, CentOS or Fedora, the actual installed content is the same.
Each component package comes with a binary executable which will be installed into /usr/bin. Outside of any testing or debugging activities though, you will probably not find yourself running the binaries directly, as each component is also registered with systemd as a service. You can then use standard systemd commands to interact with the service, such as the example given here which demonstrates how to check the status of the OpenLI provisioner service. Note the hyphen in the service name; this hyphen is present in the service name for all three components.
Documentation for each component will be installed into /usr/share/doc/openli
OpenLI configuration files must be placed in the /etc/openli directory, which will be created when you install your first component package. Each component has its own configuration file, which MUST be located at the paths shown on the slide here. The provisioner also has a second configuration file where it maintains the current set of active intercepts and their specific settings; this too must be present at the path shown on the slide.
Example config files are pre-installed to /etc/openli when the corresponding package is installed, but all example configs have the word “example” in their name to prevent them from being accidentally used by a running component.
This means that a fresh packaged install of a collector, for example, will NOT have a config file at /etc/openli/collector-config.yaml -- you will need to create one manually before you can start the collector service.
OpenLI component packages will also install a corresponding rsyslog config file into /etc/openli/rsyslog.d. If you are using rsyslog on your OpenLI machines, then you can copy these config files into /etc/rsyslog.d and restart your rsyslog daemon to enable them. Once you do that, the installed OpenLI components will write their log messages to files located in /var/log/openli.
If you are not using rsyslog for logging, or cannot be bothered with the steps I just described, then you will instead find any log messages generated by OpenLI components within /var/log/messages.
The version of OpenLI that you have just installed is not perfect and we are continually working on adding new features and fixing bugs. These fixes and improvements are periodically combined into new releases of the software, which I strongly recommend that you upgrade to as soon as they are made available.
There are a few ways for you to ensure that you are notified when a new OpenLI release has occurred. The first is to simply periodically check in at the releases page on the OpenLI github, as all new releases are published there (https://github.com/wanduow/openli/releases). Another way would be to use the watch functionality on github to subscribe to notifications of new releases. Lastly, if you prefer an atom feed of the releases page then you can grab that at the URL shown on the slide (https://github.com/wanduow/openli/releases.atom).
Once you are aware of a new release, then updating an installed OpenLI package is as simple as running the appropriate update command for your package manager.
And, if for some strange reason, you decide that you no longer want an OpenLI component package that you have installed, you can also remove the package with a single command. Once again, the corresponding command to uninstall the OpenLI collector for each package manager is shown on the slide.
Note that in the Debian / Ubuntu case, the --purge argument will also delete any configuration files that you have created in /etc/openli -- if you wish to preserve these files for whatever reason, then you can leave the --purge argument out of your uninstall command.
And that brings us to the end of this lesson -- you should now be in a position where you can comfortably install the OpenLI software packages on your preferred Linux distribution.
In the next lesson, I’m going to introduce you to the OpenLI training lab: a set of docker containers that will allow you to experiment with an OpenLI deployment in a virtual environment. Much of the remainder of this training is going to use this lab to walk you through configuring the OpenLI components and give you an opportunity to see a working deployment in action. This experience will hopefully assist you when it comes time to deploy OpenLI on your own network.
I look forward to seeing you again in the next lesson.