diff --git a/content/chapter-sources/source-default-network-drivers/_index.md b/content/chapter-sources/source-default-network-drivers/_index.md index 2b9821f8..67fec3d9 100644 --- a/content/chapter-sources/source-default-network-drivers/_index.md +++ b/content/chapter-sources/source-default-network-drivers/_index.md @@ -24,7 +24,7 @@ In addition to receiving messages on different ports and in different formats, t {{% alert title="Warning" color="warning" %}} -If you do not configure the TLS keys to dislay to the clients, {{% param "product.abbrev" %}} cannot accept encrypted connections. The application starts and listens on TCP:6514, and can receive messages on other ports, but will display a warning messages about missing keys. +If you do not configure the TLS keys to show to the clients, {{% param "product.abbrev" %}} cannot accept encrypted connections. The application starts and listens on TCP:6514, and can receive messages on other ports, but will display a warning messages about missing keys. {{% /alert %}} diff --git a/content/install/podman-systemd/_index.md b/content/install/podman-systemd/_index.md new file mode 100644 index 00000000..e438763a --- /dev/null +++ b/content/install/podman-systemd/_index.md @@ -0,0 +1,171 @@ +--- +title: Install AxoSyslog with Podman and systemd +linktitle: Podman with systemd +weight: 100 +command: podman +--- + + +This page shows you how to run {{% param "product.abbrev" %}} as a systemd service using {{< param "command" >}}. + +{{< include-headless "cloud-ready-images.md" >}} + +## Prerequisites + +Podman version 4.6.1. + +The steps in this procedure were tested on CentOS 9, but should work on other similar distributions as well. + +## Install {{% param "product.abbrev" %}} as a systemd service + +1. Make sure that there is no `axosyslog.service` unit file on the system. Run the following commands: + + ```shell + sudo rm /etc/systemd/system/axosyslog.service + ``` + + Expected output: + + ```shell + rm: cannot remove '/etc/systemd/system/axosyslog.service': No such file or directory + ``` + + ```shell + sudo systemctl cat axosyslog.service + ``` + + Expected output: + + ```shell + No files found for axosyslog.service. + ``` + +1. Create a systemd unit file called `/etc/containers/systemd/axosyslog.container` based on the following template: + + + ```shell + sudo curl -o /etc/containers/systemd/axosyslog.container https://axoflow.com/docs/axosyslog-core/install/podman-systemd/axosyslog.container + ``` + + {{< include-code "axosyslog.container" "systemd" >}} + +1. Edit the unit file as needed for your environment. + + We recommend using the default mount points: + + | Purpose | On the host | In the container | + | -------- | ------- | ------- | + | Disk-buffer and persist files | `/var/lib/syslog-ng` | `/var/lib/syslog-ng` | + | `syslog-ng` configuration file | `/opt/axosyslog/etc` | `/etc/syslog-ng` | + | Output log files | `/opt/axosyslog/var/log` | `/var/log` | + +1. (Optional) Create an `override.conf` file to set custom environment values. This can be useful if you don't want to modify `/etc/containers/systemd/axosyslog.container`. Run: + + ```shell + systemctl edit axosyslog + ``` + + Later you can edit this file by running the previous command again. + +1. Create the `/opt/axosyslog/etc/syslog-ng.conf` configuration file based on the following template. + + ```shell + sudo mkdir -p /opt/axosyslog/etc/ ; sudo curl -o /opt/axosyslog/etc/syslog-ng.conf https://axoflow.com/docs/axosyslog-core/install/podman-systemd/syslog-ng.conf + ``` + + With the following sample configuration file {{% param "product_name" %}} collects the local system logs and logs received from the network into the `/var/log/messages` file. + + {{< include-code "syslog-ng.conf" "shell" >}} + + You can customize the configuration file according to your needs. For a few pointers, see {{% xref "/quickstart/configure-servers/_index.md" %}} and the rest of this guide. + +1. Run the following commands to reload the systemd configuration and launch the `axosyslog` service. Though the systemctl commands are run as root, the container will run as the specified user if set appropriately in the unit file. + + ```shell + sudo systemctl daemon-reload + sudo systemctl stop axosyslog + sudo systemctl start axosyslog + ``` + + If there aren't any errors, these commands don't have any output. + +1. Run the following command to verify that the service was properly started: + + ```shell + journalctl -b -u axosyslog | tail -100 + ``` + + The output should be similar to: + + ```shell + Feb 12 09:04:40 systemd[1]: Starting AxoSyslog Container... + Feb 12 09:04:40 podman[2783]: 2024-02-12 09:04:40.454665314 -0500 EST m=+0.167732500 system refresh + Feb 12 09:04:40 axosyslog[2783]: Trying to pull ghcr.io/axoflow/axosyslog:latest... + Feb 12 09:04:40 axosyslog[2783]: Pulling image //ghcr.io/axoflow/axosyslog:latest inside systemd: setting pull timeout to 5m0s + Feb 12 09:04:41 axosyslog[2783]: Getting image source signatures + Feb 12 09:04:41 axosyslog[2783]: Copying blob sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1 + Feb 12 09:04:41 axosyslog[2783]: Copying blob sha256:619be1103602d98e1963557998c954c892b3872986c27365e9f651f5bc27cab8 + Feb 12 09:04:41 axosyslog[2783]: Copying blob sha256:b061f41886afb563aff2a5f731f3286ba54ea6f657ed3e282f5339a12a64c5ef + Feb 12 09:04:41 axosyslog[2783]: Copying blob sha256:1b8d965a650c6a05227bd5c549930c9898071e8e7abb26886d4169a99762de0a + Feb 12 09:04:41 axosyslog[2783]: Copying blob sha256:b5b0ce6ebef193c4f909379188cfb59443e8a1809816fbb476074908b170b4d1 + Feb 12 09:04:50 axosyslog[2783]: Copying config sha256:c379d94ef2c5ec348dfb3a93eed9a19aed667c396008db85edc354c8f4f8cb6a + Feb 12 09:04:50 axosyslog[2783]: Writing manifest to image destination + Feb 12 09:04:50 podman[2783]: 2024-02-12 09:04:50.422390687 -0500 EST m=+10.135457863 container create 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.url=https://axoflow.io/, org.opencontainers.image.source=https://github.com/axoflow/axosyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.title=AxoSyslog, org.opencontainers.image.vendor=Axoflow, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, maintainer=axoflow.io, org.opencontainers.image.licenses=GPL-3.0-only) + Feb 12 09:04:50 podman[2783]: 2024-02-12 09:04:50.402626446 -0500 EST m=+10.115693622 image pull c379d94ef2c5ec348dfb3a93eed9a19aed667c396008db85edc354c8f4f8cb6a ghcr.io/axoflow/axosyslog:latest + Feb 12 09:04:50 podman[2783]: 2024-02-12 09:04:50.489925509 -0500 EST m=+10.202992695 container init 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.licenses=GPL-3.0-only, org.opencontainers.image.vendor=Axoflow, maintainer=axoflow.io, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.url=https://axoflow.io/, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.title=AxoSyslog, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, org.opencontainers.image.source=https://github.com/axoflow/axosyslog) + Feb 12 09:04:50 systemd[1]: Started AxoSyslog Container. + Feb 12 09:04:50 podman[2783]: 2024-02-12 09:04:50.500050669 -0500 EST m=+10.213117845 container start 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.source=https://github.com/axoflow/axosyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.licenses=GPL-3.0-only, org.opencontainers.image.vendor=Axoflow, org.opencontainers.image.title=AxoSyslog, maintainer=axoflow.io, org.opencontainers.image.url=https://axoflow.io/) + Feb 12 09:04:50 axosyslog[2783]: 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f + Feb 12 09:04:50 AxoSyslog[2821]: [2024-02-12T14:04:50.806054] syslog-ng starting up; version='4.6.0' + ``` + +1. Send a test message to the service: + + ```shell + echo '<5> localhost test: this is a test message' | nc localhost 514 + ``` + + Check that the test message has arrived into the log file: + + ```shell + less /opt/axosyslog/var/log/messages + ``` + + The output should be similar to: + + ```shell + Feb 19 15:49:12 localhost test: this is a test message + ``` + +## Customize the configuration + +To customize the configuration, edit the `/opt/axosyslog/etc/syslog-ng.conf` file on the host, then reload the service. + +## Managing the {{% param "product.abbrev" %}} systemd service + +- You can reload `syslog-ng` running in the container via systemctl. The following command reloads the `syslog-ng.conf` file, without stopping/starting `syslog-ng` itself. + + ```shell + sudo systemctl reload axosyslog + ``` + +- You can access `syslog-ng-ctl` from the host, for example by running: + + ```shell + {{< param "command" >}} exec -ti AxoSyslog syslog-ng-ctl show-license-info + ``` + + If you use `syslog-ng-ctl` regularly, you can create the `/opt/axosyslog/bin/syslog-ng-ctl` file with the following content, make it executable, and add it to your path. That way running `syslog-ng-ctl ` will execute the command in the AxoSyslog container. + + ```shell + #!/bin/bash + + podman exec -ti AxoSyslog syslog-ng-ctl "$@" + ``` + +- The traditional method of starting a service at boot (`systemctl enable`) is not supported for container services. To automatically start the {{% param "product.abbrev" %}} service, make sure that the following line is included in the unit file. (It is included in the sample template.) + + ```systemd + [Install] + WantedBy=default.target + ``` diff --git a/content/install/podman-systemd/axosyslog.container b/content/install/podman-systemd/axosyslog.container new file mode 100644 index 00000000..c116db8c --- /dev/null +++ b/content/install/podman-systemd/axosyslog.container @@ -0,0 +1,52 @@ + +[Unit] +Description=AxoSyslog Container +Wants=NetworkManager.service network-online.target +After=NetworkManager.service network-online.target + +[Install] +WantedBy=multi-user.target default.target + +[Container] +# Sets User and Group ID of container syslog-ng process; should match UID/GID of desired host user +# User= and Group= values must be numeric; this is a hard requirement with strict input validation +# Example: host passwd entry syslogng:x:1000:1000 => User=1000 Group=1000 +# Any symbolic representation, environment variable, or other non-numeric value will +# be ignored and the container run as root (UID 0). +# User=1000 +# Group=1000 + +ContainerName=AxoSyslog + +AddCapability=CAP_NET_BIND_SERVICE CAP_CHOWN CAP_FOWNER CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_SYS_ADMIN + +Image=${AXOSYSLOG_IMAGE} + +Volume=${PERSIST_MOUNT}:/var/lib/syslog-ng:z +Volume=${CONFIG_MOUNT}:/etc/syslog-ng:z +Volume=${LOG_MOUNT}:/var/log:z + +Exec=-e +LogDriver=journald +Network=host +SecurityLabelDisable=true + +[Service] +# Set up environment for container above +# Container image pulled from repository +Environment="AXOSYSLOG_IMAGE=ghcr.io/axoflow/axosyslog:latest" + +Environment="PERSIST_MOUNT=/var/lib/syslog-ng" + +# Required local mount point for syslog-ng config file and associated subdirectories +Environment="CONFIG_MOUNT=/opt/axosyslog/etc" + +# Required local mount point for storing collected logs +Environment="LOG_MOUNT=/opt/axosyslog/var/log" + +# Ensure local filesystem mount points are created and set with appropriate permissions +ExecStartPre = +mkdir -p $PERSIST_MOUNT $CONFIG_MOUNT $LOG_MOUNT + +ExecReload=podman kill --signal="SIGHUP" AxoSyslog + +Restart=on-failure diff --git a/content/install/podman-systemd/syslog-ng.conf b/content/install/podman-systemd/syslog-ng.conf new file mode 100644 index 00000000..56b1f09c --- /dev/null +++ b/content/install/podman-systemd/syslog-ng.conf @@ -0,0 +1,7 @@ + +@version: current +@include "scl.conf" +log { + source { default-network-drivers(); system(); internal(); }; + destination { file("/var/log/messages"); }; +}; \ No newline at end of file diff --git a/themes/docsy-axoflow b/themes/docsy-axoflow index bb858e99..fe22b906 160000 --- a/themes/docsy-axoflow +++ b/themes/docsy-axoflow @@ -1 +1 @@ -Subproject commit bb858e99c7689f1f6d0584c3ea2e0cc48bb4f8eb +Subproject commit fe22b90671e6c59b8b7bcc4205c31e80d61f76c9