Feature Setup on Docker

🚧

The feature is only available if the docker container can run on a systemd Linux host machine.

The following steps need to be performed:

  • Expose the host journal file
  • (optional) Grant to ESF write capabilities to the host machine journal

Expose the host journal file

In order to be able to read the host journal file, ESF needs access to the location where the journal file is available.

This can be done only in Linux hosts where systemd is enabled. As explained in ESF on Docker, the 32 characters ESF_MASTER_PASSWORD has to be set.

sudo docker run -d -p 443:443 -e ESF_MASTER_PASSWORD=<master_password> --volume="/var/log/journal:/var/log/journal" -t <esf-container>

The previous command will start the ESF docker container, mounting the host /var/log/journal folder into the /var/log/journal location of the container. In this way, the ESF Log Analytics feature will be able to access and process the host machine journal file.

In order to be able to process not only the host machine journal logs but also the logs generated by the ESF instance itself, the previous command can be changed as follows:

sudo docker run -d -p 443:443 -e ESF_MASTER_PASSWORD=<master_password> --log-driver=journald --volume="/var/log/journal:/var/log/journal" -t <esf-container>

This will instruct Docker to redirect the ESF container logs into the host machine journal file.

Grant to ESF write capabilities to the host machine journal

This optional step allows the ESF container to be able to write directly to the host journal without the Docker mediation.

In order to do so, the ESF docker container needs to be started with the ENV_LOG_JOURNALDoption set to true and mounting the host journald socket location:

sudo docker run -d -p 443:443 -e ENV_LOG_JOURNALD='true' -e ESF_MASTER_PASSWORD=<master_password> --log-driver=journald --volume="/var/log/journal:/var/log/journal" --volume="/run/systemd/journal:/run/systemd/journal" -t <esf-container>

In case of multiple ESF instances writing to the same journal of the host machine, the ESF_LOGGER_NAME property can be set in the container starting command, in order to redefine the name in the SYSLOG_IDENTIFIER to ease the log messages identification.

sudo docker run -d -p 443:443 -e ENV_LOG_JOURNALD='true' -e ESF_LOGGER_NAME="foo" -e ESF_MASTER_PASSWORD=<master_password> --log-driver=journald --volume="/var/log/journal:/var/log/journal" --volume="/run/systemd/journal:/run/systemd/journal" -t <esf-container>

When applied, the previous command line will start a new container that will be able to write to the journald socket and read from the journal file of the host machine.

In the logs, the container will write with a SYSLOG_IDENTIFIER value set to "foo".