OpenLI Tutorial 07: Provisioner Configuration
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 seventh chapter in the OpenLI training series. In this lesson, I’m going to show you how to configure and start an OpenLI provisioner.
This lesson is going to assume that you have created an instance of the OpenLI training lab on your own computer by following the instructions in the previous lesson. This will allow you to get hands on experience with OpenLI by performing the exact same steps on your lab containers as I describe them here in this lesson. I always find practical exercises are a great way to learn your way around new software, so please try to make use of the lab environment if you can.
Just to remind ourselves of what we’re about to try and do: remember that the provisioner is the central orchestrator for your OpenLI deployment. What this means in practice is that all of your other components will have to connect to the provisioner, and the provisioner will then issue instructions to each component regarding what is to be intercepted, how the intercepts should be labelled and who the intercepts are to be passed on to.
So our main goal right now is to get the provisioner in a position where it is able to listen for incoming connection attempts from the other OpenLI components. To do that, we’ll need to tell the provisioner, via a configuration file, which addresses and ports it should be listening on for these connections.
If you’re using the OpenLI training lab, then your first step will be to get a shell on the provisioner container using the docker exec command, just like we covered in the previous lesson. Of course, you may not remember the exact syntax, so I’ve reproduced it here on the slide for you to make things easier.
You should now have a terminal prompt that looks something like the one on the slide, with your current working directory set to /home/openli-prov.
Now we need to know which IP address our provisioner should be listening on for those incoming connections. For your production deployment, you will probably already know this (or at least how to figure this out).
However, this may not be so obvious from within the training lab container. Remember from the last chapter though, that the eth1 interfaces on each component are connected to the network for inter-component communication. So the address that we want is going to be the address assigned to the eth1 interface.
Which, in my example, you can see is 172.19.0.3 -- it may be a slightly different address on your container, though, so make sure you check the eth1 interface on your specific container.
Now that we have the address to listen on, we can now start to edit the provisioner configuration file. You’ll hopefully remember that OpenLI configuration files are located in /etc/openli/ and that the provisioner config file is called provisioner-config.yaml.
Open up this file in your preferred text editor. My example here is using vim, but any text editor will work just fine.
You should see some text that looks very close to what is shown on the slide. The configuration is expressed using the YAML format, which you will hopefully find fairly intuitive to work with. There are plenty of resources online to learn more about YAML if you need it, but the instructions in this lesson shouldn’t require you to have any specific YAML knowledge to follow them.
There’ll also be some additional configuration text below what appears on this slide, most of which will be preceded by a hash character. The leading hash in YAML indicates that the rest of the line is a comment, and not intended to be interpreted as configuration. In this case, these lines express some advanced configuration options that we will cover in future lessons.
The first edit you’ll need to make is to replace all instances of the term PROVIP, within angle brackets, with the IP address for eth1 that we found a couple of slides back.
There’ll be three places where you need to insert that address, as the provisioner will be listening for three different types of connections.
Don’t forget to note down this IP address, as we’ll need to configure our other components to connect to it later on.
Next, we need to decide which port numbers each of the three listening services will be using.
One port will be used to listen for HTTP requests via the REST API, one port will be used by collectors to connect to the provisioner to receive intercept instructions, and the remaining port will be used by mediators to connect to the provisioner to receive forwarding instructions.
You can choose more or less any port number you want, as long as it is greater than 1024. For this demonstration, I’ve chosen 8080 for my REST API, 9001 for my collectors and 9002 for the mediators. Feel free to do the same for your provisioner as well, if you don’t have any strong feelings otherwise.
Don’t forget to make a note of these port numbers, of course, so that you can configure other components to connect to them.
Now we can go ahead with editing the provisioner config file to insert the port numbers that we have chosen into their corresponding config option.
Hopefully the angle-bracketed labels that are in the config file are fairly self-explanatory as to which port applies to which configuration option, but just in case…
In my case, COLLECTORPORT should be replaced with 9001. RESTAPIPORT should be replaced with 8080, and MEDIATORPORT should be replaced with 9002.
And for now, that’s all the configuration we need for our provisioner. Save your edited config file and feel free to exit your text editor.
One more thing we need to do before trying to start our provisioner -- because the container has rsyslog installed, you can use the rsyslog configuration that is installed with the openli-provisioner package to redirect all OpenLI log messages into /var/log/openli.
To enable this logging behaviour, copy the rsyslog configuration from /etc/openli/rsyslog.d into /etc/rsyslog.d and then simply restart your rsyslog daemon.
There is a slight complication here that is specific to the containerized lab environment -- unfortunately docker and systemd have some incompatibilities that mean that systemd cannot be used to stop a service that is running within a container. Normally, this wouldn’t matter because in a container eco-system, you don’t stop services -- you pre-configure and then run a service on the container. If you want the service to halt, you stop the entire container.
But because I want to walk you through the steps that you would need to follow if you were deploying OpenLI outside of a containerized environment, we do need to be able to stop and start services to be able to experiment and see the effects of our configuration changes.
So to make this work as an educational environment, each container includes special “stop” scripts that will halt particular running daemons on the container. For stopping rsyslog, for instance, there is a script called stop_rsyslog.sh that you can run on the container.
Once you move beyond the training lab and start deploying OpenLI on either real hardware or virtual machines, the stop scripts won’t be required (or even available, unless you make a point of copying them over from the lab). So just bear in mind that these scripts are just here to deal with a specific glitch in the lab containers and are not part of the regular OpenLI configuration process.
Moving on from that slight digression, we are now in a position where we can start the OpenLI provisioner service. In this case, systemd is going to be able to do what we want inside our container, so we can simply run service openli-provisioner start. You should then see some feedback on your terminal showing that the provisioner service started successfully.
Just because the service has started, that does not necessarily mean that it has not immediately exited due to a configuration error or some other failure. It’s always a good idea to quickly check the logs to make sure that the provisioner is indeed running as expected.
As I mentioned earlier, the rsyslog config that we added means that our log files are located in /var/log/openli. Log messages from the provisioner service can be found in the provisioner.log file within that directory.
Here’s an example of logs from a provisioner that has started successfully and is running without any configuration errors. Most importantly, you will see that we have three messages stating that each of our listening sockets are up and are listening on the address and ports that we configured earlier.
If your logs look like this, then congratulations, you have managed to configure and start an OpenLI provisioner.
By comparison, here’s what your logs might look like if you made a mistake in your configuration. Maybe you typo’d your IP address or chose a port number that is invalid or already in use. Whatever happened, you should be able to see an error message in your log file that will give you some idea as to what might have gone wrong, much like the example on the slide here.
If that happens to you, go back and double-check your configuration file to see if there are any obvious errors.
If you do make a mistake, or just want to adjust your configuration, you’ll need to stop and restart the provisioner service to re-apply your modified configuration.
In a normal deployment, you would use systemd to issue a stop command to service. Unfortunately, we’re in a container and the same issue that affected the rsyslog service applies here as well. So once again, I’ve provided a custom script in the provisioner container that will find and halt the provisioner service for you, called stop_provisioner.sh. Just remember that you’ll want to use systemd commands on your real deployment.
But otherwise, that is all you need to know for now about configuring an OpenLI provisioner. Of course, the provisioner doesn’t do a lot on its own so next time, we will walk through the configuration process for an OpenLI mediator and get one step closer to having a working intercept system.
Until then, take a little breather and I hope to see you again soon.