temboard-agent
configuration
SSL certificate
temboard-agent
embeds a lightweight HTTPS server aimed to serve its API, thus it is required to use a SSL certificate. As long as the agent's API is not reachable through a public interface, usage of self-signed certificates is safe.
Using provided SSL certificate
temboard-agent
provides a ready to use self-signed SSL certifcate located in /usr/share/temboard-agent
directory, if you don't want to use it, you can create a new one with the openssl
binary.
$ sudo cp /usr/share/temboard-agent/temboard-agent_CHANGEME.key /etc/temboard-agent/ssl/.
$ sudo cp /usr/share/temboard-agent/temboard-agent_CHANGEME.pem /etc/temboard-agent/ssl/.
$ sudo chown postgres.postgres /etc/temboard-agent/ssl/*
Build a new self-signed certificate
To build a new SSL certifcate:
$ sudo -u postgres openssl req -new -x509 -days 365 -nodes -out /etc/temboard-agent/ssl/localhost.pem -keyout /etc/temboard-agent/ssl/localhost.key
Then, ssl_cert_file
and ssl_key_file
parameters from temboard-agent.conf
file need to be set respectively to /etc/temboard-agent/ssl/localhost.pem
and /etc/temboard-agent/ssl/localhost.key
.
CA certificate file
The plugin supervision
sends periodically collected data to the collector (API served by the temBoard UI web server) through HTTPS. To allow this data flow, the HTTPS client implemented by the agent needs to have the UI's SSL certifcate (.pem) stored in its CA certificate file. temBoard agent embeds a default CA cert. file containing default temBoard UI SSL certificate.
$ sudo cp /usr/share/temboard-agent/temboard-agent_ca_certs_CHANGEME.pem /etc/temboard-agent/ssl/ca_certs_localhost.pem
ssl_ca_cert_file
parameter in section [supervision]
from the configuration file needs to be set to /etc/temboard-agent/ssl/ca_certs_localhost.pem
.
Restrictions on SSL files
$ sudo chmod 0600 /etc/temboard-agent/ssl/*
Access to PostgreSQL Cluster
The agent needs a PostgreSQL superuser. By default, it is configured to work with postgres
user.
To create a dedicated one with password authentication:
$ sudo -u postgres createuser temboard -s -P
This superuser should be able to connect to the cluster through the unix socket using a password, check pg_hba.conf
file and reload configuration.
Example of pg_hba.conf
entry:
local postgres temboard md5
The access to the PostgreSQL cluster is then configured in the [postgresql]
section of the /etc/temboard-agent/temboard-agent.conf
file.
Users
When interacting with the agent using HTTP, for example when accessing certain pages in the Web UI, an authentication is required. Accounts are created using the temboard-agent-adduser
.
Add a first user:
$ sudo -u postgres temboard-agent-adduser
Registration in the Web UI of the supersivion plugin
In the temboard-agent.conf
file, 2 parameters must be configurated to make the agent interact with the UI. The first one is key
and is a string used to uniquely identify the agent in the UI, it let the UI allow the agent to push its metric data.
The best way to configure the agent key is to generate a random string of letters and number:
$ cat /dev/urandom | tr -dc '[:alnum:]' | fold -w 64 | head -1
The second is collector_url
. It lets the agent know where to post its data. Just change the hostname to point to the UI. Since the UI is only reachable using HTTPS, the UI SSL certificate (or CA certificates that has issued it) must be in the filepath where ssl_ca_cert_file
points.
The configuration file
The configuration file temboard-agent.conf
is formated using INI format. Configuration parameters are distributed under sections:
- [temboard]
: this is the main section grouping core parameters;
- [postgresql]
: parameters related to the PostgreSQL cluster that the agent is connected to;
- [logging]
: how and where to log;
- [dashboard]
: parameters of the plugin dashboard
;
- [supervision]
: plugin supervision
;
- [administration]
: plugin administration
.
[temboard]
port
: port number that the agent will listen on to serve itsHTTP API
. Default:2345
;address
: IP v4 address that the agent will listen on. Default:0.0.0.0
(all);users
: Path to the file containing the list of the users allowed to use theHTTP API
. Default:/etc/temboard-agent/users
;plugins
: Array of plugin (name) to load. Default:["supervision", "dashboard", "settings", "administration", "activity"]
;ssl_cert_file
: Path to SSL certificate file (.pem) for the embeded HTTPS process serving the API. Default:/etc/temboard-agent/ssl/temboard-agent_CHANGEME.pem
;ssl_key_file
: Path to SSL private key file. Default:/etc/temboard-agent/ssl/temboard-agent_CHANGEME.key
;home
: Path to agent home directory, it contains files used to store temporary data. When running multiple agents on the same host, each agent must have its own home directory. Default:/var/lib/temboard-agent/main
.hostname
: Overload real machine hostname. Must be a valid FQDN. Default:None
;
[postgresql]
host
: Path to PostgreSQL unix socket. Default:/var/run/postgresql
;port
: PostgreSQL port number. Default:5432
;user
: PostgreSQL user, Must be a super-user. Default:postgres
;password
: User password. Default:None
;dbname
: Database name for the connection. Default:postgres
;instance
: Cluster name. Default:main
.key
: Authentication key used to send data to the UI. Default:None
;
[logging]
method
: Method used to send the logs:stderr
,syslog
orfile
. Default:syslog
;facility
: Syslog facility. Default:local0
;destination
: Path to the log file. Default:/dev/log
;level
: Log level, can be set toDEBUG
,INFO
,WARNING
,ERROR
orCRITICAL
. Default:INFO
.
[dashboard]
scheduler_interval
: Time interval, in second, between each run of the process collecting data used to render the dashboard. Default:2
;history_length
: Number of record to keep. Default:20
.
[supervision]
dbnames
: Database name list (comma separator) to supervise. * for all. Default:*
;collector_url
: Collector URL. Default:None
;probes
: List of probes to run, comma separator, * for all. Default:*
;scheduler_interval
: Interval, in second, between each run of the process executing the probes. Default:60
;ssl_ca_cert_file
: File where to store collector's SSL certificate. Default:None
.
[administration]
pg_ctl
: External command used to start/stop PostgreSQL. Default:None
.