Skip to content

Install Docker CE

Before you begin

Before you start:

Initial Setup

This topic provides the most recent unit file. By default, the latest SC4S image is automatically downloaded at each restart. Consult this topic when you upgrade your SC4S installation and check for changes to the provided template unit file. Make sure these changes are incorporated into your configuration before you relaunch with systemd.

  1. Create the systemd unit file /lib/systemd/system/sc4s.service based on the provided template:
[Unit]
Description=SC4S Container
Wants=NetworkManager.service network-online.target docker.service
After=NetworkManager.service network-online.target docker.service
Requires=docker.service

[Install]
WantedBy=multi-user.target

[Service]
Environment="SC4S_IMAGE=ghcr.io/splunk/splunk-connect-for-syslog/container3:latest"

# Required mount point for syslog-ng persist data (including disk buffer)
Environment="SC4S_PERSIST_MOUNT=splunk-sc4s-var:/var/lib/syslog-ng"

# Optional mount point for local overrides and configurations; see notes in docs
Environment="SC4S_LOCAL_MOUNT=/opt/sc4s/local:/etc/syslog-ng/conf.d/local:z"

# Optional mount point for local disk archive (EWMM output) files
Environment="SC4S_ARCHIVE_MOUNT=/opt/sc4s/archive:/var/lib/syslog-ng/archive:z"

# Map location of TLS custom TLS
Environment="SC4S_TLS_MOUNT=/opt/sc4s/tls:/etc/syslog-ng/tls:z"

TimeoutStartSec=0

ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE

# Note: /usr/bin/bash will not be valid path for all OS
# when startup fails on running bash check if the path is correct
ExecStartPre=/usr/bin/bash -c "/usr/bin/systemctl set-environment SC4SHOST=$(hostname -s)"

# Note: Prevent the error 'The container name "/SC4S" is already in use by container <container_id>. You have to remove (or rename) that container to be able to reuse that name.'
ExecStartPre=/usr/bin/bash -c "/usr/bin/docker rm SC4S > /dev/null 2>&1 || true"
ExecStart=/usr/bin/docker run \
        -e "SC4S_CONTAINER_HOST=${SC4SHOST}" \
        -v "$SC4S_PERSIST_MOUNT" \
        -v "$SC4S_LOCAL_MOUNT" \
        -v "$SC4S_ARCHIVE_MOUNT" \
        -v "$SC4S_TLS_MOUNT" \
        --env-file=/opt/sc4s/env_file \
        --network host \
        --name SC4S \
        --rm $SC4S_IMAGE

Restart=on-failure
  1. Execute the following command to create a local volume. This volume contains the disk buffer files in case of a communication failure to the upstream destinations:
sudo docker volume create splunk-sc4s-var
  1. Account for disk space requirements for the new Docker volume. The Docker volume can grow significantly if there is an extended outage to the SC4S destinations. This volume can be found at /var/lib/docker/volumes/. See SC4S Disk Buffer Configuration.

  2. Create the following subdirectories:

  • /opt/sc4s/local
  • /opt/sc4s/archive
  • /opt/sc4s/tls
  1. Create a file named /opt/sc4s/env_file and add the following environment variables and values:
SC4S_DEST_SPLUNK_HEC_DEFAULT_URL=https://your.splunk.instance:8088
SC4S_DEST_SPLUNK_HEC_DEFAULT_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
#Uncomment the following line if using untrusted SSL certificates
#SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_VERIFY=no
  1. Update SC4S_DEST_SPLUNK_HEC_DEFAULT_URL and SC4S_DEST_SPLUNK_HEC_DEFAULT_TOKEN to reflect the correct values for your environment. Do not configure HEC Acknowledgement when deploying the HEC token on the Splunk side, the underlying syslog-ng HTTP destination does not support this feature.

  2. The default number of SC4S_DEST_SPLUNK_HEC_<ID>_WORKERS is 10. Consult the community if you feel the number of workers should deviate from this.

  3. Splunk Connect for Syslog defaults to secure configurations. If you are not using trusted SSL certificates, be sure to uncomment the last line in the example in step 5.

For more information see Docker and Podman basic configurations and detailed configuration.

Configure SC4S for systemd

To configure SC4S for systemd run the following commands:

sudo systemctl daemon-reload
sudo systemctl enable sc4s
sudo systemctl start sc4s

Restart SC4S

To restart SC4S run the following command:

sudo systemctl restart sc4s

Implement unit file changes

If you made changes to the configuration unit file, for example to configure with dedicated ports, you must stop SC4S and re-run the systemd configuration commands to implement your changes.

sudo systemctl stop sc4s
sudo systemctl daemon-reload 
sudo systemctl enable sc4s
sudo systemctl start sc4s

Validate your configuration

SC4S performs checks to ensure that the container starts properly and that the syntax of the underlying syslog-ng configuration is correct. Once the checks are complete, validate that SC4S properly communicate with Splunk. To do this, execute the following search in Splunk:

index=* sourcetype=sc4s:events "starting up"

You should see an event similar to the following:

syslog-ng starting up; version='3.28.1'

The startup process should proceed normally without syntax errors. If it does not, follow the steps below before proceeding to deeper-level troubleshooting:

  1. Verify that the URL, token, and TLS/SSL settings are correct, and that the appropriate firewall ports are open (8088 or 443).
  2. Verify that your indexes are created in Splunk, and that your token has access to them.
  3. If you are using a load balancer, verify that it is operating properly.
  4. Execute the following command to check the SC4S startup process running in the container.
docker logs SC4S

You should see events similar to those below in the output:

syslog-ng checking config
sc4s version=v1.36.0
starting goss
starting syslog-ng
  1. If you do not see this output, see “Troubleshoot sc4s server” and “Troubleshoot resources” for more information.