Ercole is the backend component of ercole.io project.
|Operating system||CentOS, RedHat, OracleLinux 7/8|
|Database||MongoDB >= 4.2.0|
# Minimal default required network/firewall rules
 It is highly recommended to setup a reverse proxy between users/agents and ercole for avoiding to comunicate directly to the microservices using HTTP and opening too much ports, using for example nginx. See the instructions below.
# Suggested network/firewall rules
 You can safely separate ercole-reposervice from the others microservices.
# Installation guide
This installation guide is for RHEL8, but the steps can be easily adapted for RHEL7 .
curl https://repository.ercole.io/api/shared/ercole-rhel8-x86_64.repo | tee /etc/yum.repos.d/ercole-x86_64.repo
yum install ercole
- If your machine has multiple IP addresses, check and fix endpoints in
- Review ercole configuration with
systemctl start ercole
- To create ercole super user
Ercole is configured automatically during the installation but you can edit the configuration by creating/files in
/etc/ercole/conf.d. Its logs can be read with the command
journalctl -u ercole-dataservice -u ercole-alertservice -u ercole-apiservice -u ercole-reposervice -u ercole-chartservice and can be updated as usually with a simple
yum update unless in the new versions were introduced breaking changes.
It is also recommeded to also install jq (opens new window).
After the installation you may want to install ercole-web and configure nginx or to install artifacts.
# Ercole configuration
The configuration is written in TOML (opens new window) syntax and it is stored in these files/directory in ascending order of priority. The properties specified in low priority configuration files are overriden by the values in high priority configuration files. The configurations files are:
/opt/ercole/config.toml(legacy config file)
/usr/share/ercole/config.toml(distributor config file)
/etc/ercole/conf.d/20-ercolesetup.tomlis a file created by
ercole-setuputility that contains known host specific configuration like remote endpoints, paths to certificates/keys and inter microservice configuration params.
- An optional file specified to the
It's highly recommended to configure it by creating files in
/etc/ercole/conf.d/50-myconf.toml). If you change the
RemoteEndpoints of the microservices you may need to re-run
ercoleweb-setup if you have installed ercole-web).
# Configuration properties list
Mongodb.URIis the uri (opens new window) used to connect to the mongodb database. The default value is
Mongodb.DBNameis the name of the mongodb database. The default value is
Mongodb.Migratecontains true if ercole should update/migrate the database schema, otherwise false. The default value is
true. When ercole is started, it try to update the structure of the database by updating the schemas, updating the documents, creating the indexes, inserting default values.
DataService.RemoteEndpointcontains the URI used by clients to connect to the dataservice.
DataService.BindIPcontains the IP Address on which data service listen.
DataService.Portcontains the port on which data service listen.
DataService.LogHTTPRequestenable the logging of the http request.
DataService.LogInsertingHostdataenable the logging of the inserting hostdata.
DataService.LogDataPatchingenable the logging of data patching events.
DataService.EnablePatchingenable the patching of hostdata. It's required for tagging the hosts and modifying Oracle Database license count values.
DataService.AgentUsernamecontains the username used to authenticate agents
DataService.AgentPasswordcontains the password used to authenticate agents
DataService.CurrentHostCleaningJob.Crontabcontains the cron (opens new window) schedule expression for automatic archivial of the current (non archived).
DataService.CurrentHostCleaningJob.HourThresholdcontains the maximium number of hours in which a hostdata is considered up to date. After this threshold the host will be archived by the CurrentHostCleaningJob.
DataService.CurrentHostCleaningJob.RunAtStartupenable the running of the current host cleaning job at startup.
DataService.ArchivedHostCleaningJob.Crontabcontains the cron (opens new window) schedule expression for automatic deletion of archived hosts.
DataService.ArchivedHostCleaningJob.HourThresholdcontains the maximium number of hours in which a archived hostdata is retained. After this threshold the archived host will be deleted by the ArchivedHostCleaningJob.
DataService.ArchivedHostCleaningJob.RunAtStartupenable the running of the archived host cleaning job at startup.
DataService.FreshnessCheckJob.Crontabcontains the cron (opens new window) schedule expression for automatic throws of NO_DATA alerts when a current host is not up to date.
AlertService.RemoteEndpointcontains the URI used by the microservices to connect to the alertservice.
AlertService.BindIPcontains the IP Address on which alert service listen.
AlertService.Portcontains the port on which alert service listen.
AlertService.LogHTTPRequestenable the logging of the http request.
AlertService.LogMessagesenable the logging of the processing queue messages.
AlertService.LogAlertThrowsenable the logging of throwing alerts.
AlertService.PublisherUsernamecontains the username used to authenticate the microservices.
AlertService.PublisherPasswordcontains the password used to authenticate the microservices.
AlertService.Emailer.Enabledenable the notifying of the alerts by email.
AlertService.Emailer.Fromthe source email address that is used to send emails.
AlertService.Emailer.Tothe destination email addresses to which are sent the emails.
AlertService.Emailer.SMTPServerSMTP server used to send email.
AlertService.Emailer.SMTPPortport of the SMTP server used to send email.
AlertService.Emailer.SMTPUsernameusername used to authenticate to the SMTP server.
AlertService.Emailer.SMTPPasswordpassword used to authenticate to the SMTP server.
AlertService.Emailer.DisableSSLCertificateValidationtrue if disable the authentication of the SMTP server.
APIService.RemoteEndpointcontains the URI used by the clients to connect to the apiservice.
APIService.BindIPcontains the IP Address on which api service listen.
APIService.Portcontains the port on which api service listen.
APIService.LogHTTPRequestenable the logging of the http request.
APIService.ReadOnlydisable the APIs that modify the data
APIService.EnableInsertingCustomPatchingFunctionenable the possibility to add/set a custom patching function.
APIService.DebugOracleDatabaseAgreementsAssignmentAlgorithmenable the verbosity of the assignment algorithm used to distribuite oracle database agreement licenses.
APIService.AuthenticationProvider.Typescontains the authentication type: the allowed values are
ldap. It can contain both values.
basicauthentication provider uses MongoDB to store data needed for authentication and authorization.
ldapauthentication provider uses MongoDB to store data needed for authorization and needs:
APIService.AuthenticationProvider.Host, contains the server used to authenticate the users.
APIService.AuthenticationProvider.Port, contains the port used to connect to the LDAP server. e.g. 389.
APIService.AuthenticationProvider.LDAPBase, contains the LDAP base of the realm. e.g.
APIService.AuthenticationProvider.LDAPBindDN, contains the account used to authenticate to the LDAP server.
APIService.AuthenticationProvider.LDAPBindPassword, contains the password account used to authenticate to the LDAP server.
APIService.AuthenticationProvider.LDAPUserFilter, filter to search username matches, must contain
%sthat will be replaced with the username.
- Here it is a complete example working with a docker OpenLDAP example (opens new window):
APIService.AuthenticationProvider.Usernamecontains the username used by other services to authenticate to APIService. This username is created automatically during Ercole first start, but it can be changed later.
APIService.AuthenticationProvider.Passwordcontains the password used by other services to authenticate to APIService. This password is created automatically during Ercole first start, but it can be changed later.
[APIService.AuthenticationProvider] Types = [ "basic", "ldap", ] Username = "AjfYSzGJkjmxuhdb" Password = "%9O9P@4Yh8$Wh5Nb" Host = "127.0.0.1" Port = 10389 LDAPBase = "dc=planetexpress,dc=com" LDAPBindDN = "cn=admin,dc=planetexpress,dc=com" LDAPBindPassword = "GoodNewsEveryone" LDAPUserFilter = "(uid=%s)"
APIService.AuthenticationProvider.PrivateKeycontains the key used to sign the authentication JWT tokens.
APIService.AuthenticationProvider.PublicKeycontains the key used to validate the authentication JWT tokens.
APIService.AuthenticationProvider.TokenValidityTimeoutcontains the maximum number of seconds on which the token is considered valid.
APIService.OperatingSystemAggregationRulesare the rules used to map OS names + Version to product.
RepoService.UpstreamRepositoriescontains the upstream repository from which the artifacts are downloaded.
Namecontains the name of the repository.
Typecontains the type of the repository. The allowed values are
URLcontains the URL used to find the files. In the case of
github-releaseit should the URL of the API that return the releases list. e.g https://api.github.com/repos/ercole-io/ercole-agent/releases. In the case of
directoryit should be the directory in which the artifacts are contained. In the case of
ercole-reposerviceit should be the url of a directory that contains the directory
alland the file
RepoService.HTTP.Enablecontains true if reposervice should serve the files via HTTP.
RepoService.HTTP.RemoteEndpointcontains the url used by clients to reach the repository via HTTP.
RepoService.HTTP.BindIPcontains the IP on which reposervice listen for HTTP requests.
RepoService.HTTP.Portcontains the port on which reposervice listen for HTTP requests.
RepoService.HTTP.LogHTTPRequesttrue if reposervice should log for every received HTTP request.
ChartService.RemoteEndpointcontains the URI used by the clients to connect to the chartservice.
ChartService.BindIPcontains the IP Address on which chart service listen.
ChartService.Portcontains the port on which chart service listen.
ChartService.LogHTTPRequestenable the logging of the http request.
# Notes about the internal repository
Ercole repository is tought to be public and visibile to everyone so it shouldn't contains private informations like the password or private keys. The main ercole repository is https://repository.ercole.io/api (opens new window). It is served via HTTP so you can download files in various mode like:
curl http://myawesomeercole2.local:11114/ping.txt > /tmp/ping.txtSome repository files/directory are managed using the
ercole reposubcommands. Others files/directories can be safely modified.
ping.txtis a file used to check the liveness of the microservices. It's really managed but it's recommended to not modify it.
index.jsoncontains the cached list of available artifacts. Can be safely removed for forcing the rebuild of the cache when the next
reposubcommands is run.
all/contains the symlinks to all installed (and managed) artifacts.
rhel/*contains the RPM repositories of the packages for every RHEL versions.
win/*contains various ercole-agent setup files for windows.
aix/contains the RPM repositories of the packages for every AIX versions.
aix-tar-gz/alternative artifacts of agents for AIX.
hpux/contains the agents for HPUX.
Unmanaged known files:
shared/contains various files like some .repo files.
snapshots/is a directory present in https://repository.ercole.io/api (opens new window) that is used to store snapshots of all projects. The snapshots aren't tought to be used outside the development.
It may be a good idea to create multiple ercole reposervice for directory for stable/testing/unstable or PRD/COL/TST.
There is also a web-based version of the repository for human, non-automated, use to download the necessary packages: https://repository.ercole.io (opens new window).
ercole CLI usage
Ercole is thought as a CLI program, you can run commands and get help about them with the
Relevant commands are:
ercole versionprint the version of ercole.
ercole show-configshow the ercole's actual configuration.
ercole fire-hostdatasend a hostdata stored in a json file or from a stdin to ercole-dataservice.
ercole insert-suinsert ercole super user.
ercole migratemigrate the structure of the mongodb database from a previous one to the latest.
ercole servestart all the services. You can select explicity which services starts using
ercole repois a group of subcommands used to manage the repository:
listlists the artifacts detected in the upstream repositories.
infoget the informations about the specified artifacts.
installdownload and install the specified artifacts.
removeremove the specified artifacts.
updatetry to find newer version of all installed artifacts and install them.
To load autocompletion for each session, execute once:
$ ercole completion bash > /etc/bash_completion.d/ercole
# Various HOWTO/examples
# How to install an artifact
- The first thing to do is to find the available artifacts by running the command:
ercole repo list
- Choose the artifact you want.
- Install it with for example with the command:
ercole repo install firstname.lastname@example.org
# Install a package to rhelX from the ercole-reposervice
The first thing to do is to create a repository file .
curl https://repository.ercole.io/api/shared/ercole-rhel7-x86_64.repo | tee /etc/yum.repos.d/ercole.repo
The next thing is to install the package with yum or dnf.
yum install ercole-agent