Peekl

Caution

This project is still under active development. Expect breaking changes at any time. Use on your servers at your own risk.

Peekl is a simple yet powerful configuration management tool ! It's a more modern and highly opinionated solution at how tools such as Ansible and Puppet works.

1. Getting started
   1. Installing the server
   2. Installing the agent
2. Documentation
3. Contributing
4. License

Getting started

Peekl is composed of two main components :

• The agent, that you install on each node that you want to manage.
• The server, that the agent will communicate with to get their catalog.

Installing the server

The first step you will have to follow is to install the server. For that you can download the latest version of Peekl on GitHub.

By default the certificate generated by the server during it's bootstrap will only contains peekl as the domain name. If you want to use a custom domain name, such as example.peekl.dev, you should add a configuration file at path /etc/peekl/config/server.yml with the following content.

certificates:
  bootstrap_dns_names:
    - 'example.peekl.dev'

Then you can proceed and start the installation

export PEEKL_VERSION=0.1.0
export PEEKL_ARCH=amd64
wget https://github.com/peeklapp/peekl/releases/download/${PEEKL_VERSION}/peekl-server_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
apt install ./peekl-server_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb

The server should automatically start, bootstrap himself, and be ready to receive queries. You can validate that everything is working correctly using the following command.

systemctl status peekl-server.service

By default, and for security purpose, Peekl will only listen on host 127.0.0.1 and port 9040. You can change this behavior by adding the following configuration to the configuration file.

listen:
  host: 0.0.0.0
  port: 9040

Installing the agent

By default the agent will try to contact the Peekl server using https://peekl:9040 To work with this, you have two solutions :

Either make use of the peekl DNS name by adding it to the /etc/hosts file, using the command echo '192.168.121.10 peekl' >> /etc/hosts (update the IP accordingly to your case).

Or create a configuration file at path /etc/peekl/config/agent.yml and add the following content to it :

server:
  host: 192.168.121.10
  port: 9040

In this case, also remember to update the IP address according to your situation.

Once this is done, you can proceed by just installing the agent using the Debian packages

export PEEKL_VERSION=0.1.0
export PEEKL_ARCH=amd64
wget https://github.com/peeklapp/peekl/releases/download/${PEEKL_VERSION}/peekl-agent_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
apt install ./peekl-agent_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb

The agent should be up and running at this point.

systemctl status peekl-agent.service

But you will still have to sign the certificate on the server side

Start by listing the pending certificates, your agent should be there

peekl-server ca list pending

And use the found name to sign the certificate

peekl-server ca sign --certname name_of_the_node

After a little bit of time the agent should download it's certificate. You can go faster by running it by hand

peekl-agent run

Documentation

You find extensive documentation on the dedicated documentation website : docs.peekl.dev

Contributing

Contributions are more than welcome. But please note that supporting every little use-case is not something feasible. In order to keep the project into a maintainable state, we might refuse improvements or features suggestions, if they're deemed incompatible with the ideas of what Peekl should be : simple and efficient.

Asking for help is always ok, and reporting bug even more.

License

This software is distributed with the MIT License