From 70ed09d334e365d74e7fbb5069d930f0bdac1716 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Mon, 27 Jan 2020 10:08:52 -0800
Subject: [PATCH 01/25] Update vmware docs

* Add nav entry for VMware Vsphere
* Fix typo in source doc
* Rename VMware source directory to proper name
---
 docs/sources/VMWare/index.md | 4 ++--
 mkdocs.yml                   | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/sources/VMWare/index.md b/docs/sources/VMWare/index.md
index 7a9e54f..9463ae5 100644
--- a/docs/sources/VMWare/index.md
+++ b/docs/sources/VMWare/index.md
@@ -1,6 +1,6 @@
-# Vendor - Dell - VMWare
+# Vendor - Dell - VMware
 
-## Product - vSphwere - ESX NSX (Controller, Manager, Edge)
+## Product - vSphere - ESX NSX (Controller, Manager, Edge)
 
 
 | Ref            | Link                                                                                                    |
diff --git a/mkdocs.yml b/mkdocs.yml
index 869a54c..dcf986c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -27,6 +27,7 @@ nav:
       - Proofpoint: sources/Proofpoint/index.md
       - Symantec: sources/Symantec/index.md
       - Ubiquiti: sources/Ubiquiti/index.md
+      - VMware: sources/VMware/index.md
       - Zscaler: sources/Zscaler/index.md
   - 'Demo Lab': 'demo.md'
   - Performance: 'performance.md'

From 2bf9d032a1a83d926c6d5e1d9d9428ba4899c8b2 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Wed, 29 Jan 2020 11:35:49 -0800
Subject: [PATCH 02/25] update context_templates directory

* Update `context_templates` to add example extension to allow copying to local mount
* No-clobber copy to "non-example" version of context files if they do not exist locally
* Make a directory if needed for the disk buffer now that the local mount point is `var` and container doesn't create it for us
---
 ..._by_source.conf => compliance_meta_by_source.conf.example} | 0
 ...ta_by_source.csv => compliance_meta_by_source.csv.example} | 0
 .../{splunk_index.csv => splunk_index.csv.example}            | 0
 ...t_by_source.conf => vendor_product_by_source.conf.example} | 0
 ...uct_by_source.csv => vendor_product_by_source.csv.example} | 0
 package/sbin/entrypoint.sh                                    | 4 +++-
 6 files changed, 3 insertions(+), 1 deletion(-)
 rename package/etc/context_templates/{compliance_meta_by_source.conf => compliance_meta_by_source.conf.example} (100%)
 rename package/etc/context_templates/{compliance_meta_by_source.csv => compliance_meta_by_source.csv.example} (100%)
 rename package/etc/context_templates/{splunk_index.csv => splunk_index.csv.example} (100%)
 rename package/etc/context_templates/{vendor_product_by_source.conf => vendor_product_by_source.conf.example} (100%)
 rename package/etc/context_templates/{vendor_product_by_source.csv => vendor_product_by_source.csv.example} (100%)

diff --git a/package/etc/context_templates/compliance_meta_by_source.conf b/package/etc/context_templates/compliance_meta_by_source.conf.example
similarity index 100%
rename from package/etc/context_templates/compliance_meta_by_source.conf
rename to package/etc/context_templates/compliance_meta_by_source.conf.example
diff --git a/package/etc/context_templates/compliance_meta_by_source.csv b/package/etc/context_templates/compliance_meta_by_source.csv.example
similarity index 100%
rename from package/etc/context_templates/compliance_meta_by_source.csv
rename to package/etc/context_templates/compliance_meta_by_source.csv.example
diff --git a/package/etc/context_templates/splunk_index.csv b/package/etc/context_templates/splunk_index.csv.example
similarity index 100%
rename from package/etc/context_templates/splunk_index.csv
rename to package/etc/context_templates/splunk_index.csv.example
diff --git a/package/etc/context_templates/vendor_product_by_source.conf b/package/etc/context_templates/vendor_product_by_source.conf.example
similarity index 100%
rename from package/etc/context_templates/vendor_product_by_source.conf
rename to package/etc/context_templates/vendor_product_by_source.conf.example
diff --git a/package/etc/context_templates/vendor_product_by_source.csv b/package/etc/context_templates/vendor_product_by_source.csv.example
similarity index 100%
rename from package/etc/context_templates/vendor_product_by_source.csv
rename to package/etc/context_templates/vendor_product_by_source.csv.example
diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh
index 229a384..8438192 100755
--- a/package/sbin/entrypoint.sh
+++ b/package/sbin/entrypoint.sh
@@ -15,7 +15,9 @@ gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --
 
 mkdir -p /opt/syslog-ng/etc/conf.d/local/context/
 mkdir -p /opt/syslog-ng/etc/conf.d/local/config/
-cp --verbose -n /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
+mkdir -p /opt/syslog-ng/var/data/disk-buffer/
+cp --verbose /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
+for file in /opt/syslog-ng/etc/conf.d/local/context/*.example ; do cp --verbose -n $file ${file%.example}; done
 cp --verbose -R /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/
 
 echo syslog-ng checking config

From bdf793de0dfd741c86dde0bf206ba9c1648d08bb Mon Sep 17 00:00:00 2001
From: mbonsack <mbonsack@splunk.com>
Date: Wed, 29 Jan 2020 12:11:29 -0800
Subject: [PATCH 03/25] Update entrypoint.sh

---
 package/sbin/entrypoint.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh
index 8438192..7f0b376 100755
--- a/package/sbin/entrypoint.sh
+++ b/package/sbin/entrypoint.sh
@@ -16,7 +16,7 @@ gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --
 mkdir -p /opt/syslog-ng/etc/conf.d/local/context/
 mkdir -p /opt/syslog-ng/etc/conf.d/local/config/
 mkdir -p /opt/syslog-ng/var/data/disk-buffer/
-cp --verbose /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
+cp /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
 for file in /opt/syslog-ng/etc/conf.d/local/context/*.example ; do cp --verbose -n $file ${file%.example}; done
 cp --verbose -R /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/
 
@@ -24,4 +24,4 @@ echo syslog-ng checking config
 /opt/syslog-ng/sbin/syslog-ng -s >/var/log/syslog-ng.out 2>/var/log/syslog-ng.err
 
 echo syslog-ng starting
-exec /opt/syslog-ng/sbin/syslog-ng $@
\ No newline at end of file
+exec /opt/syslog-ng/sbin/syslog-ng $@

From 849a3b95b04dfaea878e70f332100f6c7cc2aa0d Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Thu, 30 Jan 2020 10:26:57 -0800
Subject: [PATCH 04/25] Remove specific disk buffer directory; use defaults

* Remove reference to specific disk buffer directory; allow unerlying syslog-ng to use default location for disk buffer files
---
 package/etc/conf.d/destinations/splunk_hec.conf.tmpl | 1 -
 package/sbin/entrypoint.sh                           | 1 -
 2 files changed, 2 deletions(-)

diff --git a/package/etc/conf.d/destinations/splunk_hec.conf.tmpl b/package/etc/conf.d/destinations/splunk_hec.conf.tmpl
index eb19250..68320bc 100644
--- a/package/etc/conf.d/destinations/splunk_hec.conf.tmpl
+++ b/package/etc/conf.d/destinations/splunk_hec.conf.tmpl
@@ -25,7 +25,6 @@ destination d_hec {
             reliable(no)
             {{- end}}
             disk-buf-size({{conv.ToInt64 (math.Round ( math.Div (getenv "SC4S_DEST_SPLUNK_HEC_DISKBUFF_DISKBUFSIZE" "53687091200") (getenv "SC4S_DEST_SPLUNK_HEC_WORKERS" "10")))}})
-            dir("/opt/syslog-ng/var/data/disk-buffer/")
              )
          {{- end}}
          tls(peer-verify({{- getenv "SC4S_DEST_SPLUNK_HEC_TLS_VERIFY" "yes"}})
diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh
index 7f0b376..799b191 100755
--- a/package/sbin/entrypoint.sh
+++ b/package/sbin/entrypoint.sh
@@ -15,7 +15,6 @@ gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --
 
 mkdir -p /opt/syslog-ng/etc/conf.d/local/context/
 mkdir -p /opt/syslog-ng/etc/conf.d/local/config/
-mkdir -p /opt/syslog-ng/var/data/disk-buffer/
 cp /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
 for file in /opt/syslog-ng/etc/conf.d/local/context/*.example ; do cp --verbose -n $file ${file%.example}; done
 cp --verbose -R /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/

From f32c9a1b23fd9a7b3571b98f106496bf7fb1ff86 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Fri, 31 Jan 2020 09:32:51 -0800
Subject: [PATCH 05/25] Update ASA log path to account for events with no
 hostname

* Update ASA log path and add filter to detect events with no hostname included
---
 package/etc/conf.d/filters/cisco/asa.conf                | 9 +++++++--
 .../etc/conf.d/log_paths/lp-cisco_asa_legacy.conf.tmpl   | 6 +++++-
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/package/etc/conf.d/filters/cisco/asa.conf b/package/etc/conf.d/filters/cisco/asa.conf
index bbd3157..a7ac9b7 100644
--- a/package/etc/conf.d/filters/cisco/asa.conf
+++ b/package/etc/conf.d/filters/cisco/asa.conf
@@ -1,3 +1,8 @@
 filter f_cisco_asa {
-    message('^%ASA-\d+-\d{1,10}: ');
-};
\ No newline at end of file
+    message('^%ASA-\d+-\d{1,10}: ') or
+    match('^%ASA-\d+-\d{1,10}:', value("LEGACY_MSGHDR"));
+};
+
+filter f_cisco_asa_nohost {
+    match('^%ASA-\d+-\d{1,10}:', value("LEGACY_MSGHDR"));
+};
diff --git a/package/etc/conf.d/log_paths/lp-cisco_asa_legacy.conf.tmpl b/package/etc/conf.d/log_paths/lp-cisco_asa_legacy.conf.tmpl
index 0749e68..a8bf9c5 100644
--- a/package/etc/conf.d/log_paths/lp-cisco_asa_legacy.conf.tmpl
+++ b/package/etc/conf.d/log_paths/lp-cisco_asa_legacy.conf.tmpl
@@ -27,7 +27,11 @@ log {
     };
     parser {p_add_context_splunk(key("cisco_asa")); };
     parser (compliance_meta_by_source);
-    rewrite { set("$(template ${.splunk.sc4s_template} $(template t_msg_only))" value("MSG")); };
+    if (filter (f_cisco_asa_nohost)) {
+        rewrite { set("$(template ${.splunk.sc4s_template} $(template t_legacy_hdr_msg))" value("MSG")); };
+    } else {
+        rewrite { set("$(template ${.splunk.sc4s_template} $(template t_msg_only))" value("MSG")); };
+    };
 
 {{- if or (conv.ToBool (getenv "SC4S_DEST_SPLUNK_HEC_GLOBAL" "yes")) (conv.ToBool (getenv "SC4S_DEST_CISCO_ASA_HEC" "no")) }}
     destination(d_hec);

From d5f68b1e6795be91dc05b8236aa0dc9db3abbe27 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Fri, 31 Jan 2020 10:16:11 -0800
Subject: [PATCH 06/25] Add Cisco ASA "nohost" test

* Add Cisco ASA test for events with no hostname set
---
 tests/test_cisco_asa.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/tests/test_cisco_asa.py b/tests/test_cisco_asa.py
index 1399ac8..7c1e5bc 100644
--- a/tests/test_cisco_asa.py
+++ b/tests/test_cisco_asa.py
@@ -36,6 +36,27 @@ def test_cisco_asa_traditional(record_property, setup_wordlist, setup_splunk):
 
     assert resultCount == 1
 
+# <164>Jan 31 2020 17:24:03: %ASA-4-402119: IPSEC: Received an ESP packet (SPI= 0x0C190BF9, sequence number= 0x598243) from 192.0.0.1 (user= 192.0.0.1) to 192.0.0.2 that failed anti-replay checking.
+def test_cisco_asa_traditional_nohost(record_property, setup_wordlist, setup_splunk):
+    host = "{}-{}".format(random.choice(setup_wordlist), random.choice(setup_wordlist))
+
+    mt = env.from_string(
+        "{{ mark }} {% now 'utc', '%b %d %H:%M:%S' %}: %ASA-4-402119: IPSEC: Received an ESP packet (SPI= 0x0C190BF9, sequence number= 0x598243) from 192.0.0.1 (user= 192.0.0.1) to 192.0.0.2 that failed anti-replay checking.\n")
+    message = mt.render(mark="<111>", host=host)
+
+    sendsingle(message)
+
+    st = env.from_string("search index=netfw sourcetype=\"cisco:asa\" \"%ASA-4-402119\" | head 1")
+    search = st.render(host=host)
+
+    resultCount, eventCount = splunk_single(setup_splunk, search)
+
+    record_property("host", host)
+    record_property("resultCount", resultCount)
+    record_property("message", message)
+
+    assert resultCount == 1
+
 
 # <166>2018-06-27T12:17:46Z asa : %ASA-3-710003: TCP access denied by ACL from 179.236.133.160/8949 to outside:72.142.18.38/23
 def test_cisco_asa_rfc5424(record_property, setup_wordlist, setup_splunk):

From 4e639d9b6b9a15e659efe4566cef079b3551ccd7 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Fri, 31 Jan 2020 10:44:22 -0800
Subject: [PATCH 07/25] Update test_cisco_asa.py

---
 tests/test_cisco_asa.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_cisco_asa.py b/tests/test_cisco_asa.py
index 7c1e5bc..6bcd920 100644
--- a/tests/test_cisco_asa.py
+++ b/tests/test_cisco_asa.py
@@ -41,12 +41,12 @@ def test_cisco_asa_traditional_nohost(record_property, setup_wordlist, setup_spl
     host = "{}-{}".format(random.choice(setup_wordlist), random.choice(setup_wordlist))
 
     mt = env.from_string(
-        "{{ mark }} {% now 'utc', '%b %d %H:%M:%S' %}: %ASA-4-402119: IPSEC: Received an ESP packet (SPI= 0x0C190BF9, sequence number= 0x598243) from 192.0.0.1 (user= 192.0.0.1) to 192.0.0.2 that failed anti-replay checking.\n")
+        "{{ mark }} {% now 'utc', '%b %d %H:%M:%S' %}: %ASA-4-402119: IPSEC: Received an ESP packet (SPI= 0x0C190BF9, sequence number= 0x598243) from {host} (user= 192.0.0.1) to 192.0.0.2 that failed anti-replay checking.\n")
     message = mt.render(mark="<111>", host=host)
 
     sendsingle(message)
 
-    st = env.from_string("search index=netfw sourcetype=\"cisco:asa\" \"%ASA-4-402119\" | head 1")
+    st = env.from_string("search index=netfw sourcetype=\"cisco:asa\" \"%ASA-4-402119\" \"{host}\" | head 2")
     search = st.render(host=host)
 
     resultCount, eventCount = splunk_single(setup_splunk, search)

From 73dbcc5886ee5f516fcfb52d07ab533dcf4dbfbc Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sat, 1 Feb 2020 17:28:00 -0800
Subject: [PATCH 08/25] Update docs with new unit file/initialization details

* Update Unit files for RHEL 7/8 compatibility
* Update BYOE docs to correct installation location (`/etc/syslog-ng`)
* Update procedure for disk-buffer files (container volume vs file mount)
* Update docs to explain the "example" context files
* Remove "preflight" from unit files; functionality included in `/entrypoint.sh`
* Include Release Notes in docs
---
 docs/gettingstarted/byoe-rhel7.md             | 46 +++++++----
 docs/gettingstarted/docker-swarm-general.md   | 35 ++++----
 docs/gettingstarted/docker-swarm-rhel7.md     | 37 +++++----
 docs/gettingstarted/docker-systemd-general.md | 74 ++++++++---------
 docs/gettingstarted/podman-systemd-general.md | 82 +++++++++----------
 docs/release.md                               | 12 +++
 mkdocs.yml                                    |  1 +
 7 files changed, 154 insertions(+), 133 deletions(-)
 create mode 100644 docs/release.md

diff --git a/docs/gettingstarted/byoe-rhel7.md b/docs/gettingstarted/byoe-rhel7.md
index e91f5b1..2cb4540 100644
--- a/docs/gettingstarted/byoe-rhel7.md
+++ b/docs/gettingstarted/byoe-rhel7.md
@@ -21,7 +21,16 @@ for the reason why syslog-ng builds are so dated in almost all RHEL/Debian distr
 
 # BYOE Installation Instructions
 
-* Install CentOS or RHEL 7.7
+These installation instructions assume a recent RHEL or CentOS-based release.  Minor adjustments may have to be made for
+Debian/Ubuntu.  In addition, almost _all_ pre-compiled binaries for syslog-ng assume installation in `etc/syslog-ng`; these instructions
+will reflect that.
+
+The following installation instructions are summarized from a 
+[blog](https://www.syslog-ng.com/community/b/blog/posts/introducing-the-syslog-ng-stable-rpm-repositories)
+maintained by a developer at One Identity (formerly Balabit), who is the owner of the syslog-ng Open Source project.
+It is always adivisable to review the blog for the latest changes to the repo(s), as changes here are quite dynamic.
+
+* Install CentOS or RHEL 7.7/8.0
 
 * Enable EPEL (Centos 7)
 
@@ -55,15 +64,10 @@ sudo systemctl stop syslog-ng
 sudo systemctl disable syslog-ng
 ```        
 
-* Download the latest bare_metal.tar from [releases](https://github.com/splunk/splunk-connect-for-syslog/releases) on github and untar the package
+* Download the latest bare_metal.tar from [releases](https://github.com/splunk/splunk-connect-for-syslog/releases) on github and untar the package in `/etc/syslog-ng`
 
 ```bash
-cd /tmp
-sudo wget https://github.com/splunk/splunk-connect-for-syslog/releases/download/0.12.1/baremetal.tar
-tar -xf baremetal.tar 
-sudo mkdir -p /opt/syslog-ng/etc
-sudo mkdir -p /opt/syslog-ng/var
-sudo cp -R etc/* /opt/syslog-ng/etc/
+sudo wget -c https://github.com/splunk/splunk-connect-for-syslog/releases/download/latest/baremetal.tar -O - | sudo tar -x -C /etc/syslog-ng
 ```
 
 * Install gomplate and confirm that the version is 3.5.0 or newer 
@@ -103,13 +107,20 @@ Restart=on-failure
 WantedBy=multi-user.target
 ```
 
-* create the file ``/opt/sc4s/bin/preconfig.sh``.  This file should be made executable according to your file permission standards. Add the following content: 
+* NOTE:  The `wget` process above will download a file called `entrypoint.sh` and place it in `/etc/syslog-ng`.  This is the
+preconfiguration file that is used for the container version of sc4s, and forms the foundation of the BYOE version of the file you will
+create below.  Do _not_ use it verbatim as there are differences between them (most notably the install location).  However, it does include
+the "latest and greatest" updates from the container, and should be used (with appropriate modifications) as the basis of the contents of
+`preconfig.sh` below.
+
+* create the file ``/opt/sc4s/bin/preconfig.sh``.  This file should be made executable according to your file permission standards.
+Add the following content (but be sure to check the note above to ensure the latest updates are included):
 
 ```bash
 #!/usr/bin/env bash
 source scl_source enable rh-python36
 
-cd /opt/syslog-ng
+cd /etc/syslog-ng
 #The following is no longer needed but retained as a comment just in case we run into command line length issues
 #for d in $(find /opt/syslog-ng/etc -type d)
 #do
@@ -120,15 +131,14 @@ cd /opt/syslog-ng
 #    --exclude=*.conf --exclude=*.csv --exclude=*.t --exclude=.*\
 #    --output-map="$d/{{ .in | strings.ReplaceAll \".conf.tmpl\" \".conf\" }}"
 #done
+
 gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --out=\2/') --template t=etc/go_templates/
 
-mkdir -p /opt/syslog-ng/etc/conf.d/local/context/
-mkdir -p /opt/syslog-ng/etc/conf.d/local/config/
-cp --verbose -n /opt/syslog-ng/etc/context_templates/* /opt/syslog-ng/etc/conf.d/local/context/
-cp --verbose -R -n /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/
-mkdir -p /opt/syslog-ng/var/data/disk-buffer/
-mkdir -p /opt/syslog-ng/var/archive/
-mkdir -p /opt/syslog-ng/tls/
+mkdir -p /etc/syslog-ng/etc/conf.d/local/context/
+mkdir -p /etc/syslog-ng/etc/conf.d/local/config/
+cp /etc/syslog-ng/etc/context_templates/* /etc/syslog-ng/etc/conf.d/local/context/
+for file in /etc/syslog-ng/etc/conf.d/local/context/*.example ; do cp -v -n $file ${file%.example}; done
+cp -v -R /etc/syslog-ng/etc/local_config/* /etc/syslog-ng/etc/conf.d/local/config/
 ```
 
 * (Optional) Execute the preconfiguration shell script created above.  You may also optionally execute it as part of the unit
@@ -142,7 +152,7 @@ sudo bash /opt/sc4s/bin/preconfig.sh
 * Create the file ``/opt/sc4s/env_file`` and add the following environment variables:
 
 ```dotenv
-SYSLOGNG_OPTS=-f /opt/syslog-ng/etc/syslog-ng.conf 
+SYSLOGNG_OPTS=-f /etc/syslog-ng/etc/syslog-ng.conf 
 SPLUNK_HEC_URL=https://splunk.smg.aws:8088
 SPLUNK_HEC_TOKEN=a778f63a-5dff-4e3c-a72c-a03183659e94
 SC4S_DEST_SPLUNK_HEC_WORKERS=6
diff --git a/docs/gettingstarted/docker-swarm-general.md b/docs/gettingstarted/docker-swarm-general.md
index a26a1c1..9e1a85f 100644
--- a/docs/gettingstarted/docker-swarm-general.md
+++ b/docs/gettingstarted/docker-swarm-general.md
@@ -55,33 +55,34 @@ services:
       - /opt/sc4s/env_file
     volumes:
       - /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z
-      - /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z
+      - splunk-sc4s-var:/opt/syslog-ng/var
 # Uncomment the following line if local disk archiving is desired
 #     - /opt/sc4s/archive:/opt/syslog-ng/var/archive:z
 # Uncomment the following line if custom TLS certs are provided
 #     - /opt/sc4s/tls:/opt/syslog-ng/tls:z
 ```
 
+* Execute the following command to create a local volume that will contain the disk buffer files in the event of a communication
+failure to the upstream destination(s).  This will also be used to keep track of the state of syslog-ng between restarts, and in
+particular the state of the disk buffer.  This is a required step.
+```
+sudo docker volume create splunk-sc4s-var
+```
+
 * Create the subdirectory ``/opt/sc4s/local``.  This will be used as a mount point for local overrides and configurations.
 
-    * The empty ``local`` directory created above will populate with templates at the first invocation 
-of SC4S for local configurations and overrides. Changes made to these files will be preserved on subsequent 
-restarts (i.e. a "no-clobber" copy is performed for any missing files).  _Do not_ change the directory structure of 
+    * The empty ``local`` directory created above will populate with defaults and examples at the first invocation 
+of SC4S for local configurations and context overrides. _Do not_ change the directory structure of 
 the files that are laid down; change (or add) only individual files if desired.  SC4S depends on the directory layout
-to read the local configurations properly.
-
-    * You can back up the contents of this directory elsewhere and return the directory to an empty state
-when a new version of SC4S is released to pick up any new changes provided by Splunk.  Upon a restart,
-the direcory will populate as it did when you first installed SC4S.  Your previous changes can then
-be merged back in and will take effect after another restart.
+to read the local configurations properly.  See the notes below for which files will be preserved on restarts.
 
-* Create the subdirectory ``/opt/sc4s/disk-buffer``.  This will be used as a mount point for local disk buffering
-of events in the event of network failure to the Splunk infrastructure.
+    * In the `local/config` directory, there are example log path files (`lp-example.*`) and a filter (`example.conf`) in the
+appropriate subdirectories.  These should _not_ be used directly, but copied as examples for your own log path development.
+They _will_ get overwritten at each SC4S start.    
 
-    * This directory will populate with the disk buffer files upon SC4S startup.  If SC4S restarts for any reason, a new
-    set of files will be created in addition to the original ones.  _The original ones will not be removed_.
-    If you are sure, after stopping SC4S, that all data has been sent, these files can be removed.  They will be created
-    again upon restart.
+    * In the `local/context` directory, if you change the "non-example" version of a file (e.g. `splunk_index.csv`) the changes
+will be preserved on a restart.  However, the "example" files _themselves_ (e.g. `splunk_index.csv.example`) will be updated
+regularly, and should be used as a template to merge new/changed functionality into existing context files.  
     
 * Create the subdirectory ``/opt/sc4s/archive``.  This will be used as a mount point for local storage of syslog events
 (if the optional mount is uncommented above).  The events will be written in the syslog-ng EWMM format. See the "configuration"
@@ -183,7 +184,7 @@ services:
       - /opt/sc4s/env_file
     volumes:
       - /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z
-      - /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z
+      - splunk-sc4s-var:/opt/syslog-ng/var
 # Uncomment the following line if local disk archiving is desired
 #     - /opt/sc4s/archive:/opt/syslog-ng/var/archive:z
 # Uncomment the following line if custom TLS certs are provided
diff --git a/docs/gettingstarted/docker-swarm-rhel7.md b/docs/gettingstarted/docker-swarm-rhel7.md
index 251c9fa..c276f64 100644
--- a/docs/gettingstarted/docker-swarm-rhel7.md
+++ b/docs/gettingstarted/docker-swarm-rhel7.md
@@ -63,34 +63,35 @@ services:
       - /opt/sc4s/env_file
     volumes:
       - /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z
-      - /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z
+      - splunk-sc4s-var:/opt/syslog-ng/var
 # Uncomment the following line if local disk archiving is desired
 #     - /opt/sc4s/archive:/opt/syslog-ng/var/archive:z
 # Uncomment the following line if custom TLS certs are provided
 #     - /opt/sc4s/tls:/opt/syslog-ng/tls:z
 ```
 
+* Execute the following command to create a local volume that will contain the disk buffer files in the event of a communication
+failure to the upstream destination(s).  This will also be used to keep track of the state of syslog-ng between restarts, and in
+particular the state of the disk buffer.  This is a required step.
+```
+sudo docker volume create splunk-sc4s-var
+```
+
 * Create the subdirectory ``/opt/sc4s/local``.  This will be used as a mount point for local overrides and configurations.
 
-    * The empty ``local`` directory created above will populate with templates at the first invocation 
-of SC4S for local configurations and overrides. Changes made to these files will be preserved on subsequent 
-restarts (i.e. a "no-clobber" copy is performed for any missing files).  _Do not_ change the directory structure of 
+    * The empty ``local`` directory created above will populate with defaults and examples at the first invocation 
+of SC4S for local configurations and context overrides. _Do not_ change the directory structure of 
 the files that are laid down; change (or add) only individual files if desired.  SC4S depends on the directory layout
-to read the local configurations properly.
+to read the local configurations properly.  See the notes below for which files will be preserved on restarts.
 
-    * You can back up the contents of this directory elsewhere and return the directory to an empty state
-when a new version of SC4S is released to pick up any new changes provided by Splunk.  Upon a restart,
-the direcory will populate as it did when you first installed SC4S.  Your previous changes can then
-be merged back in and will take effect after another restart.
-
-* Create the subdirectory ``/opt/sc4s/disk-buffer``.  This will be used as a mount point for local disk buffering
-of events in the event of network failure to the Splunk infrastructure.
-
-    * This directory will populate with the disk buffer files upon SC4S startup.  If SC4S restarts for any reason, a new
-set of files will be created in addition to the original ones.  _The original ones will not be removed_.
-If you are sure, after stopping SC4S, that all data has been sent, these files can be removed.  They will be created
-again upon restart
+    * In the `local/config` directory, there are example log path files (`lp-example.*`) and a filter (`example.conf`) in the
+appropriate subdirectories.  These should _not_ be used directly, but copied as examples for your own log path development.
+They _will_ get overwritten at each SC4S start.    
 
+    * In the `local/context` directory, if you change the "non-example" version of a file (e.g. `splunk_index.csv`) the changes
+will be preserved on a restart.  However, the "example" files _themselves_ (e.g. `splunk_index.csv.example`) will be updated
+regularly, and should be used as a template to merge new/changed functionality into existing context files.  
+    
 * Create the subdirectory ``/opt/sc4s/archive``.  This will be used as a mount point for local storage of syslog events
 (if the optional mount is uncommented above).  The events will be written in the syslog-ng EWMM format. See the "configuration"
 document for details on the directory structure the archive uses.
@@ -191,7 +192,7 @@ services:
       - /opt/sc4s/env_file
     volumes:
       - /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z
-      - /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z
+      - splunk-sc4s-var:/opt/syslog-ng/var
 # Uncomment the following line if local disk archiving is desired
 #     - /opt/sc4s/archive:/opt/syslog-ng/var/archive:z
 # Uncomment the following line if custom TLS certs are provided
diff --git a/docs/gettingstarted/docker-systemd-general.md b/docs/gettingstarted/docker-systemd-general.md
index 55a4788..4c3dbee 100644
--- a/docs/gettingstarted/docker-systemd-general.md
+++ b/docs/gettingstarted/docker-systemd-general.md
@@ -28,21 +28,24 @@ net.ipv4.ip_forward=1
 ```ini
 [Unit]
 Description=SC4S Container
-Wants=network.target network-online.target
-After=network.target network-online.target
+Wants=NetworkManager.service network-online.target
+After=NetworkManager.service network-online.target
+
+[Install]
+WantedBy=multi-user.target
 
 [Service]
 Environment="SC4S_IMAGE=splunk/scs:latest"
 
+# Required mount point for syslog-ng persist data (including disk buffer)
+Environment="SC4S_PERSIST_VOLUME=-v splunk-sc4s-var:/opt/syslog-ng/var"
+
 # Optional mount point for local overrides and configurations; see notes in docs
 Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
 
 # Optional mount point for local disk archive (EWMM output) files
 # Environment="SC4S_LOCAL_ARCHIVE_MOUNT=-v /opt/sc4s/archive:/opt/syslog-ng/var/archive:z"
 
-# Mount point for local disk buffer (required)
-Environment="SC4S_LOCAL_DISK_BUFFER_MOUNT=-v /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z"
-
 # Uncomment the following line if custom TLS certs are provided
 # Environment="SC4S_TLS_DIR=-v /opt/sc4s/tls:/opt/syslog-ng/tls:z"
 
@@ -50,42 +53,38 @@ TimeoutStartSec=0
 Restart=always
 
 ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
-ExecStartPre=/usr/bin/docker run \
-        --env-file=/opt/sc4s/env_file \
-        "$SC4S_LOCAL_CONFIG_MOUNT" \
-        --name SC4S_preflight \
-        --rm $SC4S_IMAGE -s
 ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 \
         --env-file=/opt/sc4s/env_file \
+        "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \
-        "$SC4S_LOCAL_DISK_BUFFER_MOUNT" \
         "$SC4S_LOCAL_ARCHIVE_MOUNT" \
         "$SC4S_TLS_DIR" \
         --name SC4S \
         --rm $SC4S_IMAGE
 ```
 
+* Execute the following command to create a local volume that will contain the disk buffer files in the event of a communication
+failure to the upstream destination(s).  This will also be used to keep track of the state of syslog-ng between restarts, and in
+particular the state of the disk buffer.  This is a required step.
+```
+sudo docker volume create splunk-sc4s-var
+```
+
 * Create the subdirectory ``/opt/sc4s/local``.  This will be used as a mount point for local overrides and configurations.
 
-    * The empty ``local`` directory created above will populate with templates at the first invocation 
-of SC4S for local configurations and overrides. Changes made to these files will be preserved on subsequent 
-restarts (i.e. a "no-clobber" copy is performed for any missing files).  _Do not_ change the directory structure of 
+    * The empty ``local`` directory created above will populate with defaults and examples at the first invocation 
+of SC4S for local configurations and context overrides. _Do not_ change the directory structure of 
 the files that are laid down; change (or add) only individual files if desired.  SC4S depends on the directory layout
-to read the local configurations properly.
-
-    * You can back up the contents of this directory elsewhere and return the directory to an empty state
-when a new version of SC4S is released to pick up any new changes provided by Splunk.  Upon a restart,
-the direcory will populate as it did when you first installed SC4S.  Your previous changes can then
-be merged back in and will take effect after another restart.
+to read the local configurations properly.  See the notes below for which files will be preserved on restarts.
 
-* Create the subdirectory ``/opt/sc4s/disk-buffer``.  This will be used as a mount point for local disk buffering
-of events in the event of network failure to the Splunk infrastructure.
-
-    * This directory will populate with the disk buffer files upon SC4S startup.  If SC4S restarts for any reason, a new
-set of files will be created in addition to the original ones.  _The original ones will not be removed_.
-If you are sure, after stopping SC4S, that all data has been sent, these files can be removed.  They will be created
-again upon restart
+    * In the `local/config` directory, there are example log path files (`lp-example.*`) and a filter (`example.conf`) in the
+appropriate subdirectories.  These should _not_ be used directly, but copied as examples for your own log path development.
+They _will_ get overwritten at each SC4S start.    
 
+    * In the `local/context` directory, if you change the "non-example" version of a file (e.g. `splunk_index.csv`) the changes
+will be preserved on a restart.  However, the "example" files _themselves_ (e.g. `splunk_index.csv.example`) will be updated
+regularly, and should be used as a template to merge new/changed functionality into existing context files.  
+    
 * Create the subdirectory ``/opt/sc4s/archive``.  This will be used as a mount point for local storage of syslog events
 (if the optional mount is uncommented above).  The events will be written in the syslog-ng EWMM format. See the "configuration"
 document for details on the directory structure the archive uses.
@@ -149,36 +148,35 @@ documentation to identify the specific environment variables that are mapped to
 ```ini
 [Unit]
 Description=SC4S Container
-After=network.service
-Requires=network.service
+Wants=NetworkManager.service network-online.target
+After=NetworkManager.service network-online.target
+
+[Install]
+WantedBy=multi-user.target
 
 [Service]
 Environment="SC4S_IMAGE=splunk/scs:latest"
 
+# Required mount point for syslog-ng persist data (including disk buffer)
+Environment="SC4S_PERSIST_VOLUME=-v splunk-sc4s-var:/opt/syslog-ng/var"
+
 # Optional mount point for local overrides and configurations; see notes in docs
 Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
 
 # Optional mount point for local disk archive (EWMM output) files
 # Environment="SC4S_LOCAL_ARCHIVE_MOUNT=-v /opt/sc4s/archive:/opt/syslog-ng/var/archive:z"
 
-# Mount point for local disk buffer (required)
-Environment="SC4S_LOCAL_DISK_BUFFER_MOUNT=-v /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z"
-
 # Uncomment the following line if custom TLS certs are provided
 # Environment="SC4S_TLS_DIR=-v /opt/sc4s/tls:/opt/syslog-ng/tls"
 
 TimeoutStartSec=0
 Restart=always
+
 ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
-ExecStartPre=/usr/bin/docker run \
-        --env-file=/opt/sc4s/env_file \
-        "$SC4S_LOCAL_CONFIG_MOUNT" \
-        --name SC4S_preflight \
-        --rm $SC4S_IMAGE -s
 ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
         --env-file=/opt/sc4s/env_file \
+        "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \
-        "$SC4S_LOCAL_DISK_BUFFER_MOUNT" \
         "$SC4S_LOCAL_ARCHIVE_MOUNT" \
         "$SC4S_TLS_DIR" \
         --name SC4S \
diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 7b49762..0d76496 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -10,64 +10,63 @@ Refer to [Installation](https://podman.io/getting-started/installation)
 ```ini
 [Unit]
 Description=SC4S Container
-Wants=network.target network-online.target
-After=network.target network-online.target
+Wants=NetworkManager.service network-online.target
+After=NetworkManager.service network-online.target
+
+[Install]
+WantedBy=multi-user.target
 
 [Service]
 Environment="SC4S_IMAGE=splunk/scs:latest"
 
+# Required mount point for syslog-ng persist data (including disk buffer)
+Environment="SC4S_PERSIST_VOLUME=-v splunk-sc4s-var:/opt/syslog-ng/var"
+
 # Optional mount point for local overrides and configurations; see notes in docs
 Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
 
 # Optional mount point for local disk archive (EWMM output) files
 # Environment="SC4S_LOCAL_ARCHIVE_MOUNT=-v /opt/sc4s/archive:/opt/syslog-ng/var/archive:z"
 
-# Mount point for local disk buffer (required)
-Environment="SC4S_LOCAL_DISK_BUFFER_MOUNT=-v /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z"
-
 # Uncomment the following line if custom TLS certs are provided
 # Environment="SC4S_TLS_DIR=-v /opt/sc4s/tls:/opt/syslog-ng/tls:z"
 
 TimeoutStartSec=0
 Restart=always
 
-ExecStartPre=/usr/bin/podman pull $SC4S_IMAGE
-ExecStartPre=/usr/bin/podman run \
-        --env-file=/opt/sc4s/env_file \
-        "$SC4S_LOCAL_CONFIG_MOUNT" \
-        --name SC4S_preflight \
-        --rm $SC4S_IMAGE -s
-ExecStart=/usr/bin/podman run -p 514:514 -p 514:514/udp -p 6514:6514 \
+ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
+ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 \
         --env-file=/opt/sc4s/env_file \
+        "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \
-        "$SC4S_LOCAL_DISK_BUFFER_MOUNT" \
         "$SC4S_LOCAL_ARCHIVE_MOUNT" \
         "$SC4S_TLS_DIR" \
         --name SC4S \
         --rm $SC4S_IMAGE
 ```
 
+* Execute the following command to create a local volume that will contain the disk buffer files in the event of a communication
+failure to the upstream destination(s).  This will also be used to keep track of the state of syslog-ng between restarts, and in
+particular the state of the disk buffer.  This is a required step.
+```
+sudo docker volume create splunk-sc4s-var
+```
+
 * Create the subdirectory ``/opt/sc4s/local``.  This will be used as a mount point for local overrides and configurations.
 
-    * The empty ``local`` directory created above will populate with templates at the first invocation 
-of SC4S for local configurations and overrides. Changes made to these files will be preserved on subsequent 
-restarts (i.e. a "no-clobber" copy is performed for any missing files).  _Do not_ change the directory structure of 
+    * The empty ``local`` directory created above will populate with defaults and examples at the first invocation 
+of SC4S for local configurations and context overrides. _Do not_ change the directory structure of 
 the files that are laid down; change (or add) only individual files if desired.  SC4S depends on the directory layout
-to read the local configurations properly.
-
-    * You can back up the contents of this directory elsewhere and return the directory to an empty state
-when a new version of SC4S is released to pick up any new changes provided by Splunk.  Upon a restart,
-the direcory will populate as it did when you first installed SC4S.  Your previous changes can then
-be merged back in and will take effect after another restart.
+to read the local configurations properly.  See the notes below for which files will be preserved on restarts.
 
-* Create the subdirectory ``/opt/sc4s/disk-buffer``.  This will be used as a mount point for local disk buffering
-of events in the event of network failure to the Splunk infrastructure.
-
-    * This directory will populate with the disk buffer files upon SC4S startup.  If SC4S restarts for any reason, a new
-set of files will be created in addition to the original ones.  _The original ones will not be removed_.
-If you are sure, after stopping SC4S, that all data has been sent, these files can be removed.  They will be created
-again upon restart
+    * In the `local/config` directory, there are example log path files (`lp-example.*`) and a filter (`example.conf`) in the
+appropriate subdirectories.  These should _not_ be used directly, but copied as examples for your own log path development.
+They _will_ get overwritten at each SC4S start.    
 
+    * In the `local/context` directory, if you change the "non-example" version of a file (e.g. `splunk_index.csv`) the changes
+will be preserved on a restart.  However, the "example" files _themselves_ (e.g. `splunk_index.csv.example`) will be updated
+regularly, and should be used as a template to merge new/changed functionality into existing context files.  
+    
 * Create the subdirectory ``/opt/sc4s/archive``.  This will be used as a mount point for local storage of syslog events
 (if the optional mount is uncommented above).  The events will be written in the syslog-ng EWMM format. See the "configuration"
 document for details on the directory structure the archive uses.
@@ -131,36 +130,35 @@ documentation to identify the specific environment variables that are mapped to
 ```ini
 [Unit]
 Description=SC4S Container
-After=network.service
-Requires=network.service
+Wants=NetworkManager.service network-online.target
+After=NetworkManager.service network-online.target
+
+[Install]
+WantedBy=multi-user.target
 
 [Service]
 Environment="SC4S_IMAGE=splunk/scs:latest"
 
+# Required mount point for syslog-ng persist data (including disk buffer)
+Environment="SC4S_PERSIST_VOLUME=-v splunk-sc4s-var:/opt/syslog-ng/var"
+
 # Optional mount point for local overrides and configurations; see notes in docs
 Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
 
 # Optional mount point for local disk archive (EWMM output) files
 # Environment="SC4S_LOCAL_ARCHIVE_MOUNT=-v /opt/sc4s/archive:/opt/syslog-ng/var/archive:z"
 
-# Mount point for local disk buffer (required)
-Environment="SC4S_LOCAL_DISK_BUFFER_MOUNT=-v /opt/sc4s/disk-buffer:/opt/syslog-ng/var/data/disk-buffer:z"
-
 # Uncomment the following line if custom TLS certs are provided
 # Environment="SC4S_TLS_DIR=-v /opt/sc4s/tls:/opt/syslog-ng/tls"
 
 TimeoutStartSec=0
 Restart=always
-ExecStartPre=/usr/bin/podman pull $SC4S_IMAGE
-ExecStartPre=/usr/bin/podman run \
-        --env-file=/opt/sc4s/env_file \
-        "$SC4S_LOCAL_CONFIG_MOUNT" \
-        --name SC4S_preflight \
-        --rm $SC4S_IMAGE -s
-ExecStart=/usr/bin/podman run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
+
+ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
+ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
         --env-file=/opt/sc4s/env_file \
+        "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \
-        "$SC4S_LOCAL_DISK_BUFFER_MOUNT" \
         "$SC4S_LOCAL_ARCHIVE_MOUNT" \
         "$SC4S_TLS_DIR" \
         --name SC4S \
diff --git a/docs/release.md b/docs/release.md
new file mode 100644
index 0000000..fdf5c6b
--- /dev/null
+++ b/docs/release.md
@@ -0,0 +1,12 @@
+# Release Notes
+
+Splunk Connect for Syslog is updated regularly using a CI/CD development process.  Check back often for the latest on each release
+here.  Changes that will affect current installations, as well as new and deprecated features, will be outlined below.
+
+## Version 1.9.0
+
+* Version string added
+* Example context files added to local mount.  These example files will be updated at each release to add support for new data sources,
+and the new content can be added to existing context files (without the `.example` extension).  Existing context files will _not_ be
+overwritten on subsequent SC4S starts/upgrades, so ensure that content for new data sources is incorporated in existing context files.
+* Support for Cisco devices sending events with no hostname has been added.
diff --git a/mkdocs.yml b/mkdocs.yml
index dcf986c..8ae29c6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -32,6 +32,7 @@ nav:
   - 'Demo Lab': 'demo.md'
   - Performance: 'performance.md'
   - Troubleshooting: 'troubleshooting.md'
+  - 'Release Notes': 'release.md'
 
 markdown_extensions:
     - toc:

From 334886800c2771c600059b1b02666c20e6b54a88 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sat, 1 Feb 2020 21:43:16 -0800
Subject: [PATCH 09/25] Add RAWMSG storage for debugging

* Add an environment variable `SC4S_SOURCE_STORE_RAWMSG` to enable the collection/storage of the "on the wire" message for use in the 3164 fallback template.
* Useful for development and debugging of log paths and filters.  NOT FOR USE IN PRODUCTION due to memory/disk overhead.
---
 docker-compose.yml                                | 1 +
 docs/configuration.md                             | 2 +-
 package/etc/conf.d/conflib/_common/templates.conf | 1 +
 package/etc/go_templates/source_network.t         | 8 ++++----
 4 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 323da58..a2b7ae4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -55,6 +55,7 @@ services:
       - SC4S_LISTEN_PALOALTO_PANOS_TCP_PORT=5005
       - SC4S_LISTEN_PFSENSE_TCP_PORT=5006
       - SC4S_ARCHIVE_GLOBAL=yes
+#     - SC4S_SOURCE_STORE_RAWMSG=yes
     volumes:
       - ./tls:/opt/syslog-ng/tls
   splunk:
diff --git a/docs/configuration.md b/docs/configuration.md
index f19488b..75b7e82 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -73,7 +73,7 @@ and/or move them to an archival system to avoid exhaustion of disk space.
 | SC4S_SOURCE_TCP_IW_SIZE | 20000000 | Initial Window size |
 | SC4S_SOURCE_TCP_FETCH_LIMIT | 2000 | Number of events to fetch from server buffer at once |
 | SC4S_SOURCE_UDP_SO_RCVBUFF | 425984 | UDP server buffer size in bytes |
-
+| SC4S_SOURCE_STORE_RAWMSG | undefined or "no" | Store unprocessed "on the wire" raw message in the RAWMSG macro for use with the "fallback" sourcetype.  Do _not_ set this in production; substantial memory and disk overhead will result. Use for log path/filter development only. |
 
 ## Syslog Source TLS Certificate Configuration
 
diff --git a/package/etc/conf.d/conflib/_common/templates.conf b/package/etc/conf.d/conflib/_common/templates.conf
index 46b63b2..5746a1c 100644
--- a/package/etc/conf.d/conflib/_common/templates.conf
+++ b/package/etc/conf.d/conflib/_common/templates.conf
@@ -61,6 +61,7 @@ template t_JSON_3164 {
     template('$(format-json --scope rfc3164
                 --pair PRI="<$PRI>"
                 --key LEGACY_MSGHDR
+                --key RAWMSG
                 --exclude FACILITY
                 --exclude PRIORITY
                 )');
diff --git a/package/etc/go_templates/source_network.t b/package/etc/go_templates/source_network.t
index 7b201eb..a49e89b 100644
--- a/package/etc/go_templates/source_network.t
+++ b/package/etc/go_templates/source_network.t
@@ -60,14 +60,14 @@ source s_{{ .port_id }} {
         };
 {{ if eq .parser "rfc3164" }}
         parser {
-            syslog-parser(time-zone({{getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone));
+            syslog-parser(time-zone({{getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone {{- if (conv.ToBool (getenv "SC4S_SOURCE_STORE_RAWMSG" "no")) }} store-raw-message {{- end}}));
         };
         rewrite(set_rfc3164);
 {{ else if eq .parser "rfc3164_version" }}
 #       filter(f_rfc3164_version);
         rewrite(set_rfc3164_no_version_string);
         parser {
-            syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone));
+            syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone {{- if (conv.ToBool (getenv "SC4S_SOURCE_STORE_RAWMSG" "no")) }} store-raw-message {{- end}}));
         };
         rewrite(set_rfc3164_version);
 {{ else if eq .parser "rfc5424_strict" }}
@@ -104,7 +104,7 @@ source s_{{ .port_id }} {
             filter(f_rfc3164_version);
             rewrite(set_rfc3164_no_version_string);
             parser {
-                    syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone));
+                    syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone {{- if (conv.ToBool (getenv "SC4S_SOURCE_STORE_RAWMSG" "no")) }} store-raw-message {{- end}}));
                 };
             rewrite(set_rfc3164_version);
         } elif {
@@ -118,7 +118,7 @@ source s_{{ .port_id }} {
             rewrite(set_cisco_ios);
         } else {
             parser {
-                syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone));
+                syslog-parser(time-zone({{- getenv "SC4S_DEFAULT_TIMEZONE" "GMT"}}) flags(guess-timezone {{- if (conv.ToBool (getenv "SC4S_SOURCE_STORE_RAWMSG" "no")) }} store-raw-message {{- end}}));
             };
             rewrite(set_rfc3164);
         };

From ab1d8f9ff3437214c1a34630d17e221eee528cff Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 13:27:34 -0800
Subject: [PATCH 10/25] Add non-root opreration to podman runtime doc

* Add section on non-root operation for the Podman runtime
---
 docs/gettingstarted/podman-systemd-general.md | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 0d76496..2d4331b 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -264,3 +264,61 @@ Oct  1 05:29:55 77cd4776af41 syslog-ng[1]: Syslog connection closed; fd='49', cl
 If you see http server errors such as 4xx or 5xx responses from the http (HEC) endpoint, one or more of the items above are likely set
 incorrectly.  If validating/fixing the configuration fails to correct the problem, proceed to the "Troubleshooting" section for more
 information.
+
+# SC4S non-root operation
+
+To operate SC4S as a user other than root, follow the instructions above, with these modifications:
+
+## Prepare SC4S user
+
+Create a non-root user in which to run SC4S and prepare podman for non-root operation:
+
+```bash
+sudo useradd -m -d /home/sc4s -s /bin/bash sc4s
+sudo su - sc4s
+mkdir -p /home/sc4s/local
+mkdir -p /home/sc4s/archive
+mkdir -p /home/sc4s/tls
+podman system migrate
+```
+
+## Initial Setup
+
+NOTE:  Be sure to exectute all instructions below as the SC4S user created above with the exception of changes to the unit file,
+which requires sudo access.
+
+Make the following changes to the unit file(s) configured in the main section:
+
+* Add the name of the user create above immediately after the Service declaration, as shown in the snippet below:
+
+```
+[Service]
+User=sc4s
+```
+
+* Replace all references to `/opt/sc4s` in the "Environment" declarations with `/home/sc4s`.  Make sure _not_ to change the
+right-hand-side of the mount. For example:
+
+```
+Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /home/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
+```
+
+* Replace all references to standard UDP/TCP listening ports (typically 514) with arbirtrary high-numbered (> 1024) ports so
+that the container can listen without root privleges:
+
+```
+ExecStart=/usr/bin/docker run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
+```
+
+If not done in the "Prepare SC4S user" above, create the three local mount directories as instructed in the main instructions,
+replacing the head of the directory (`/opt/sc4s`) with the sc4s service user's home directory as shown below:
+```
+mkdir /home/sc4s/local
+mkdir /home/sc4s/archive
+mkdir /home/sc4s/tls
+```
+
+## Remaining Setup
+
+The remainder of the setup can be followed directly from the main setup instructions.
+

From fd6924bfb4e028bf4e3af93fac6b83f12b406f78 Mon Sep 17 00:00:00 2001
From: mbonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 13:36:00 -0800
Subject: [PATCH 11/25] Correct Typo

* Correct typo
---
 docs/gettingstarted/podman-systemd-general.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 2d4331b..3a0498f 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -289,7 +289,7 @@ which requires sudo access.
 
 Make the following changes to the unit file(s) configured in the main section:
 
-* Add the name of the user create above immediately after the Service declaration, as shown in the snippet below:
+* Add the name of the user created above immediately after the Service declaration, as shown in the snippet below:
 
 ```
 [Service]

From eea8ea5f616c8ad84b53cf5cdba86e992484420a Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 13:37:01 -0800
Subject: [PATCH 12/25] podman runtime/typo

* Correct typo
---
 docs/gettingstarted/podman-systemd-general.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 2d4331b..3a0498f 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -289,7 +289,7 @@ which requires sudo access.
 
 Make the following changes to the unit file(s) configured in the main section:
 
-* Add the name of the user create above immediately after the Service declaration, as shown in the snippet below:
+* Add the name of the user created above immediately after the Service declaration, as shown in the snippet below:
 
 ```
 [Service]

From 18521a64ad5ea553d37f2196e27a510f49aa0d15 Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Sun, 2 Feb 2020 18:14:20 -0500
Subject: [PATCH 13/25] Change root of tarball release

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index d13a074..0d3076a 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -70,7 +70,7 @@ jobs:
       - run:
           name: BYOE Config
           command: |
-            tar rvf /tmp/workspace/baremetal.tar -C package etc
+            tar rvf /tmp/workspace/baremetal.tar -C package/etc .
             tar rvf /tmp/workspace/baremetal.tar -C package/sbin entrypoint.sh
 
       - store_test_results:

From 72b9c9055584b854098b33a659fa2e5513cbf53d Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 21:25:11 -0800
Subject: [PATCH 14/25] Revert change from unit file (re-enable the preflight)

* Revert previous change to unit file; re-enable preflight check to prevent startup loops
* Fix cut/paste error and restore proper runtime (podman) to podman runtime doc
---
 docs/gettingstarted/docker-systemd-general.md | 10 ++++++++++
 docs/gettingstarted/podman-systemd-general.md | 18 ++++++++++++++----
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/gettingstarted/docker-systemd-general.md b/docs/gettingstarted/docker-systemd-general.md
index 4c3dbee..f0882bd 100644
--- a/docs/gettingstarted/docker-systemd-general.md
+++ b/docs/gettingstarted/docker-systemd-general.md
@@ -53,6 +53,11 @@ TimeoutStartSec=0
 Restart=always
 
 ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
+ExecStartPre=/usr/bin/docker run \
+        --env-file=/opt/sc4s/env_file \
+        "$SC4S_LOCAL_CONFIG_MOUNT" \
+        --name SC4S_preflight \
+        --rm $SC4S_IMAGE -s
 ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 \
         --env-file=/opt/sc4s/env_file \
         "$SC4S_PERSIST_VOLUME" \
@@ -173,6 +178,11 @@ TimeoutStartSec=0
 Restart=always
 
 ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
+ExecStartPre=/usr/bin/docker run \
+        --env-file=/opt/sc4s/env_file \
+        "$SC4S_LOCAL_CONFIG_MOUNT" \
+        --name SC4S_preflight \
+        --rm $SC4S_IMAGE -s
 ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
         --env-file=/opt/sc4s/env_file \
         "$SC4S_PERSIST_VOLUME" \
diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 3a0498f..38cac72 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -34,8 +34,13 @@ Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.
 TimeoutStartSec=0
 Restart=always
 
-ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
-ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 \
+ExecStartPre=/usr/bin/podman pull $SC4S_IMAGE
+ExecStartPre=/usr/bin/podman run \
+        --env-file=/opt/sc4s/env_file \
+        "$SC4S_LOCAL_CONFIG_MOUNT" \
+        --name SC4S_preflight \
+        --rm $SC4S_IMAGE -s
+ExecStart=/usr/bin/podman run -p 514:514 -p 514:514/udp -p 6514:6514 \
         --env-file=/opt/sc4s/env_file \
         "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \
@@ -154,8 +159,13 @@ Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /opt/sc4s/local:/opt/syslog-ng/etc/conf.
 TimeoutStartSec=0
 Restart=always
 
-ExecStartPre=/usr/bin/docker pull $SC4S_IMAGE
-ExecStart=/usr/bin/docker run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
+ExecStartPre=/usr/bin/podman pull $SC4S_IMAGE
+ExecStartPre=/usr/bin/podman run \
+        --env-file=/opt/sc4s/env_file \
+        "$SC4S_LOCAL_CONFIG_MOUNT" \
+        --name SC4S_preflight \
+        --rm $SC4S_IMAGE -s
+ExecStart=/usr/bin/podman run -p 514:514 -p 514:514/udp -p 6514:6514 -p 5000-5020:5000-5020 -p 5000-5020:5000-5020/udp \
         --env-file=/opt/sc4s/env_file \
         "$SC4S_PERSIST_VOLUME" \
         "$SC4S_LOCAL_CONFIG_MOUNT" \

From 0896a460c28b2126093006428ec4d56299e40d3b Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 21:42:50 -0800
Subject: [PATCH 15/25] Update BYOE to account for new tarball root

* Update the BYOE instructions for new tarball root
* Warn administrators that default syslog-ng configuration will be overwritten
---
 docs/gettingstarted/byoe-rhel7.md | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/gettingstarted/byoe-rhel7.md b/docs/gettingstarted/byoe-rhel7.md
index 2cb4540..f3d5645 100644
--- a/docs/gettingstarted/byoe-rhel7.md
+++ b/docs/gettingstarted/byoe-rhel7.md
@@ -66,6 +66,10 @@ sudo systemctl disable syslog-ng
 
 * Download the latest bare_metal.tar from [releases](https://github.com/splunk/splunk-connect-for-syslog/releases) on github and untar the package in `/etc/syslog-ng`
 
+* NOTE:  The `wget` process below will unpack a tarball with the sc4s version of the syslog-ng config files in the standard
+`/etc/syslog-ng` location, and _will_ overwrite existing content.  Ensure that any previous configurations of syslog-ng are saved
+if needed prior to executing the download step.
+
 ```bash
 sudo wget -c https://github.com/splunk/splunk-connect-for-syslog/releases/download/latest/baremetal.tar -O - | sudo tar -x -C /etc/syslog-ng
 ```
@@ -82,7 +86,7 @@ gomplate --version
 
 ```scl enable rh-python36 bash```
 
-* create the sc4s unit file drop in ``/etc/systemd/system/sc4s.service`` and add the following content
+* create the sc4s unit file ``/etc/systemd/system/sc4s.service`` and add the following content
 
 ```ini
 [Unit]
@@ -132,13 +136,13 @@ cd /etc/syslog-ng
 #    --output-map="$d/{{ .in | strings.ReplaceAll \".conf.tmpl\" \".conf\" }}"
 #done
 
-gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --out=\2/') --template t=etc/go_templates/
+gomplate $(find . -name *.tmpl | sed -E 's/^(\/.*\/)*(.*)\..*$/--file=\2.tmpl --out=\2/') --template t=go_templates/
 
-mkdir -p /etc/syslog-ng/etc/conf.d/local/context/
-mkdir -p /etc/syslog-ng/etc/conf.d/local/config/
-cp /etc/syslog-ng/etc/context_templates/* /etc/syslog-ng/etc/conf.d/local/context/
-for file in /etc/syslog-ng/etc/conf.d/local/context/*.example ; do cp -v -n $file ${file%.example}; done
-cp -v -R /etc/syslog-ng/etc/local_config/* /etc/syslog-ng/etc/conf.d/local/config/
+mkdir -p /etc/syslog-ng/conf.d/local/context/
+mkdir -p /etc/syslog-ng/conf.d/local/config/
+cp /etc/syslog-ng/context_templates/* /etc/syslog-ng/conf.d/local/context/
+for file in /etc/syslog-ng/conf.d/local/context/*.example ; do cp -v -n $file ${file%.example}; done
+cp -v -R /etc/syslog-ng/local_config/* /etc/syslog-ng/conf.d/local/config/
 ```
 
 * (Optional) Execute the preconfiguration shell script created above.  You may also optionally execute it as part of the unit
@@ -152,7 +156,7 @@ sudo bash /opt/sc4s/bin/preconfig.sh
 * Create the file ``/opt/sc4s/env_file`` and add the following environment variables:
 
 ```dotenv
-SYSLOGNG_OPTS=-f /etc/syslog-ng/etc/syslog-ng.conf 
+SYSLOGNG_OPTS=-f /etc/syslog-ng/syslog-ng.conf 
 SPLUNK_HEC_URL=https://splunk.smg.aws:8088
 SPLUNK_HEC_TOKEN=a778f63a-5dff-4e3c-a72c-a03183659e94
 SC4S_DEST_SPLUNK_HEC_WORKERS=6

From b0998cf47d3cf93ca7ed66d83942e3def967350c Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Sun, 2 Feb 2020 21:58:17 -0800
Subject: [PATCH 16/25] Re-add non-root operation to Docker systemd runtime

* Add non-root runtime to docker systemd runtime
* Fix wrong cut/paste error in podman systemd runtime
---
 docs/gettingstarted/docker-systemd-general.md | 59 ++++++++++++++++++-
 docs/gettingstarted/podman-systemd-general.md |  3 +-
 2 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/docs/gettingstarted/docker-systemd-general.md b/docs/gettingstarted/docker-systemd-general.md
index f0882bd..d4735b8 100644
--- a/docs/gettingstarted/docker-systemd-general.md
+++ b/docs/gettingstarted/docker-systemd-general.md
@@ -291,4 +291,61 @@ Oct  1 05:29:55 77cd4776af41 syslog-ng[1]: Syslog connection closed; fd='49', cl
 ```
 If you see http server errors such as 4xx or 5xx responses from the http (HEC) endpoint, one or more of the items above are likely set
 incorrectly.  If validating/fixing the configuration fails to correct the problem, proceed to the "Troubleshooting" section for more
-information.
\ No newline at end of file
+information.
+
+# SC4S non-root operation
+
+To operate SC4S as a user other than root, follow the instructions above, with these modifications:
+
+## Prepare SC4S user
+
+Create a non-root user in which to run SC4S and prepare podman for non-root operation:
+
+```bash
+sudo useradd -m -d /home/sc4s -s /bin/bash sc4s
+sudo su - sc4s
+mkdir -p /home/sc4s/local
+mkdir -p /home/sc4s/archive
+mkdir -p /home/sc4s/tls
+podman system migrate
+```
+
+## Initial Setup
+
+NOTE:  Be sure to exectute all instructions below as the SC4S user created above with the exception of changes to the unit file,
+which requires sudo access.
+
+Make the following changes to the unit file(s) configured in the main section:
+
+* Add the name of the user created above immediately after the Service declaration, as shown in the snippet below:
+
+```
+[Service]
+User=sc4s
+```
+
+* Replace all references to `/opt/sc4s` in the "Environment" declarations with `/home/sc4s`.  Make sure _not_ to change the
+right-hand-side of the mount. For example:
+
+```
+Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /home/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
+```
+
+* Replace all references to standard UDP/TCP listening ports (typically 514) with arbirtrary high-numbered (> 1024) ports so
+that the container can listen without root privleges:
+
+```
+ExecStart=/usr/bin/docker run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
+```
+
+If not done in the "Prepare SC4S user" above, create the three local mount directories as instructed in the main instructions,
+replacing the head of the directory (`/opt/sc4s`) with the sc4s service user's home directory as shown below:
+```
+mkdir /home/sc4s/local
+mkdir /home/sc4s/archive
+mkdir /home/sc4s/tls
+```
+
+## Remaining Setup
+
+The remainder of the setup can be followed directly from the main setup instructions.
diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 38cac72..9e06996 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -317,7 +317,7 @@ Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /home/sc4s/local:/opt/syslog-ng/etc/conf
 that the container can listen without root privleges:
 
 ```
-ExecStart=/usr/bin/docker run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
+ExecStart=/usr/bin/podman run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
 ```
 
 If not done in the "Prepare SC4S user" above, create the three local mount directories as instructed in the main instructions,
@@ -331,4 +331,3 @@ mkdir /home/sc4s/tls
 ## Remaining Setup
 
 The remainder of the setup can be followed directly from the main setup instructions.
-

From b637492f8f49954f0cc3e4b04dd76d88c79753d8 Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Mon, 3 Feb 2020 06:55:39 -0500
Subject: [PATCH 17/25] Add version to DockerFile and echo at startup

---
 .circleci/config.yml       | 3 ++-
 docker-compose.yml         | 4 ----
 package/Dockerfile         | 2 ++
 package/VERSION            | 1 +
 package/sbin/entrypoint.sh | 4 +++-
 5 files changed, 8 insertions(+), 6 deletions(-)
 create mode 100644 package/VERSION

diff --git a/.circleci/config.yml b/.circleci/config.yml
index d13a074..9cdeb79 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -29,7 +29,8 @@ jobs:
       - versioning/define_version
       - versioning/create_version_file:
          version_file_path: /tmp/workspace/VERSION
-
+      - versioning/create_version_file:
+         version_file_path: package
       - docker/install-docker
       - docker/check:
           registry: $REGISTRY
diff --git a/docker-compose.yml b/docker-compose.yml
index a2b7ae4..81191cb 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -13,8 +13,6 @@ services:
     links:
       - splunk
       - sc4s
-    volumes:
-      - sc4s-results:/work/test-results
     environment:
       - SPLUNK_USER=admin
       - SPLUNK_PASSWORD=${SPLUNK_PASSWORD}
@@ -85,7 +83,5 @@ services:
       - ./replay:/work
 
 volumes:
-  sc4s-results:
-    external: true
   splunk-etc:
     external: true
diff --git a/package/Dockerfile b/package/Dockerfile
index 22dbf53..75a9c62 100644
--- a/package/Dockerfile
+++ b/package/Dockerfile
@@ -77,6 +77,8 @@ COPY sbin/entrypoint.sh /
 RUN mkdir -p /opt/syslog-ng/var/data/disk-buffer
 RUN source scl_source enable rh-python36 ;/opt/syslog-ng/sbin/syslog-ng -V
 
+COPY VERSION /
+
 EXPOSE 514
 EXPOSE 601/tcp
 EXPOSE 6514/tcp
diff --git a/package/VERSION b/package/VERSION
new file mode 100644
index 0000000..fedd7e5
--- /dev/null
+++ b/package/VERSION
@@ -0,0 +1 @@
+UNKNOWN
\ No newline at end of file
diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh
index 799b191..d8d8b53 100755
--- a/package/sbin/entrypoint.sh
+++ b/package/sbin/entrypoint.sh
@@ -20,7 +20,9 @@ for file in /opt/syslog-ng/etc/conf.d/local/context/*.example ; do cp --verbose
 cp --verbose -R /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/
 
 echo syslog-ng checking config
-/opt/syslog-ng/sbin/syslog-ng -s >/var/log/syslog-ng.out 2>/var/log/syslog-ng.err
+echo sc4s version=$(cat /version)
+echo sc4s version=$(cat /version) >/var/log/syslog-ng.out
+/opt/syslog-ng/sbin/syslog-ng -s >>/var/log/syslog-ng.out 2>/var/log/syslog-ng.err
 
 echo syslog-ng starting
 exec /opt/syslog-ng/sbin/syslog-ng $@

From 0cfe9027bea04be06a0dbe4fe27b4ea65db64ddd Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Mon, 3 Feb 2020 07:00:40 -0500
Subject: [PATCH 18/25] Update config.yml

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 9cdeb79..916daee 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -30,7 +30,7 @@ jobs:
       - versioning/create_version_file:
          version_file_path: /tmp/workspace/VERSION
       - versioning/create_version_file:
-         version_file_path: package
+         version_file_path: package/VERSION
       - docker/install-docker
       - docker/check:
           registry: $REGISTRY

From 9727a8f5b0ce88723a74ad857998e7324ad798f8 Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Mon, 3 Feb 2020 07:03:22 -0500
Subject: [PATCH 19/25] Update test_common.py

---
 tests/test_common.py | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/tests/test_common.py b/tests/test_common.py
index eecec2d..11912b5 100644
--- a/tests/test_common.py
+++ b/tests/test_common.py
@@ -172,3 +172,14 @@ def test_check_config_version_multiple(record_property, setup_wordlist, setup_sp
     record_property("resultCount", resultCount)
 
     assert resultCount == 0
+
+def test_check_sc4s_version(record_property, setup_wordlist, setup_splunk):
+
+    st = env.from_string("search index=main sourcetype=\"sc4s:events:startup:out\" \"sc4s version=\" NOT \"UNKNOWN\"")
+    search = st.render()
+
+    resultCount, eventCount = splunk_single(setup_splunk, search)
+
+    record_property("resultCount", resultCount)
+
+    assert resultCount == 0
\ No newline at end of file

From 1f3e1ee6a9fc2c06a2bac72cea2832e220f9e9c6 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Mon, 3 Feb 2020 08:38:27 -0800
Subject: [PATCH 20/25] Update non-root operation

* Remove non-root instructions for docker systemd; behavior is different for docker
* Change listening port pairs to have container continue to listen on port 514 (`-p 2514:514`)
---
 docs/gettingstarted/docker-systemd-general.md | 56 -------------------
 docs/gettingstarted/podman-systemd-general.md |  7 ++-
 2 files changed, 4 insertions(+), 59 deletions(-)

diff --git a/docs/gettingstarted/docker-systemd-general.md b/docs/gettingstarted/docker-systemd-general.md
index d4735b8..2f25337 100644
--- a/docs/gettingstarted/docker-systemd-general.md
+++ b/docs/gettingstarted/docker-systemd-general.md
@@ -293,59 +293,3 @@ If you see http server errors such as 4xx or 5xx responses from the http (HEC) e
 incorrectly.  If validating/fixing the configuration fails to correct the problem, proceed to the "Troubleshooting" section for more
 information.
 
-# SC4S non-root operation
-
-To operate SC4S as a user other than root, follow the instructions above, with these modifications:
-
-## Prepare SC4S user
-
-Create a non-root user in which to run SC4S and prepare podman for non-root operation:
-
-```bash
-sudo useradd -m -d /home/sc4s -s /bin/bash sc4s
-sudo su - sc4s
-mkdir -p /home/sc4s/local
-mkdir -p /home/sc4s/archive
-mkdir -p /home/sc4s/tls
-podman system migrate
-```
-
-## Initial Setup
-
-NOTE:  Be sure to exectute all instructions below as the SC4S user created above with the exception of changes to the unit file,
-which requires sudo access.
-
-Make the following changes to the unit file(s) configured in the main section:
-
-* Add the name of the user created above immediately after the Service declaration, as shown in the snippet below:
-
-```
-[Service]
-User=sc4s
-```
-
-* Replace all references to `/opt/sc4s` in the "Environment" declarations with `/home/sc4s`.  Make sure _not_ to change the
-right-hand-side of the mount. For example:
-
-```
-Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /home/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
-```
-
-* Replace all references to standard UDP/TCP listening ports (typically 514) with arbirtrary high-numbered (> 1024) ports so
-that the container can listen without root privleges:
-
-```
-ExecStart=/usr/bin/docker run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
-```
-
-If not done in the "Prepare SC4S user" above, create the three local mount directories as instructed in the main instructions,
-replacing the head of the directory (`/opt/sc4s`) with the sc4s service user's home directory as shown below:
-```
-mkdir /home/sc4s/local
-mkdir /home/sc4s/archive
-mkdir /home/sc4s/tls
-```
-
-## Remaining Setup
-
-The remainder of the setup can be followed directly from the main setup instructions.
diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index 9e06996..cc4714e 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -313,11 +313,12 @@ right-hand-side of the mount. For example:
 Environment="SC4S_LOCAL_CONFIG_MOUNT=-v /home/sc4s/local:/opt/syslog-ng/etc/conf.d/local:z"
 ```
 
-* Replace all references to standard UDP/TCP listening ports (typically 514) with arbirtrary high-numbered (> 1024) ports so
-that the container can listen without root privleges:
+* Replace all references to standard UDP/TCP outside listening ports (typically 514) on the _left hand side only_ of the port pairs
+with arbirtrary high-numbered (> 1024) ports so that the container can listen without root privleges.  The right hand side of the pairs
+(also typically 514) should remain unchanged:
 
 ```
-ExecStart=/usr/bin/podman run -p 2514:2514 -p 2514:2514/udp -p 6514:6514 
+ExecStart=/usr/bin/podman run -p 2514:514 -p 2514:514/udp -p 6514:6514 
 ```
 
 If not done in the "Prepare SC4S user" above, create the three local mount directories as instructed in the main instructions,

From 028f98bc70541fdf066bc60c71702dc9b2ceb2d7 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Mon, 3 Feb 2020 08:58:06 -0800
Subject: [PATCH 21/25] Rename release notes to upgrade

* Add top-level doc on upgrading considerations
---
 docs/release.md | 12 ------------
 docs/upgrade.md | 12 ++++++++++++
 mkdocs.yml      |  2 +-
 3 files changed, 13 insertions(+), 13 deletions(-)
 delete mode 100644 docs/release.md
 create mode 100644 docs/upgrade.md

diff --git a/docs/release.md b/docs/release.md
deleted file mode 100644
index fdf5c6b..0000000
--- a/docs/release.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Release Notes
-
-Splunk Connect for Syslog is updated regularly using a CI/CD development process.  Check back often for the latest on each release
-here.  Changes that will affect current installations, as well as new and deprecated features, will be outlined below.
-
-## Version 1.9.0
-
-* Version string added
-* Example context files added to local mount.  These example files will be updated at each release to add support for new data sources,
-and the new content can be added to existing context files (without the `.example` extension).  Existing context files will _not_ be
-overwritten on subsequent SC4S starts/upgrades, so ensure that content for new data sources is incorporated in existing context files.
-* Support for Cisco devices sending events with no hostname has been added.
diff --git a/docs/upgrade.md b/docs/upgrade.md
new file mode 100644
index 0000000..38b1a0d
--- /dev/null
+++ b/docs/upgrade.md
@@ -0,0 +1,12 @@
+# Upgrading Splunk Connect for Syslog
+
+Splunk Connect for Syslog is updated regularly using a CI/CD development process.  The notes below outline significant changes that
+must be taken into account prior and after an upgrade.  Ensure to follow specific instructions below to ensure a smooth transition to
+a new version of SC4S in production.
+
+## Version 1.9.0
+
+Example context files have been added to the local mount `context` directory.  These example files will be updated at each release
+to outline support for new data sources, which can be added to existing context files (those without the `.example` extension).
+Existing context files will _not_ be overwritten on subsequent SC4S starts/upgrades, so ensure that any new content from these example
+files is incorporated into existing context files.
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ae29c6..8f18791 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -32,7 +32,7 @@ nav:
   - 'Demo Lab': 'demo.md'
   - Performance: 'performance.md'
   - Troubleshooting: 'troubleshooting.md'
-  - 'Release Notes': 'release.md'
+  - 'Upgrading SC4S': 'upgrade.md'
 
 markdown_extensions:
     - toc:

From c99e1493d3ec5a04a6f0e3d24d09bb1341e8f683 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Mon, 3 Feb 2020 10:52:09 -0800
Subject: [PATCH 22/25] Minor docs updates/corrections

* Update upgrade doc to include unit file changes
* Fix two errors in runtime docs
---
 docs/gettingstarted/byoe-rhel7.md             | 2 +-
 docs/gettingstarted/podman-systemd-general.md | 4 ++--
 docs/upgrade.md                               | 5 ++++-
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/gettingstarted/byoe-rhel7.md b/docs/gettingstarted/byoe-rhel7.md
index f3d5645..544178d 100644
--- a/docs/gettingstarted/byoe-rhel7.md
+++ b/docs/gettingstarted/byoe-rhel7.md
@@ -86,7 +86,7 @@ gomplate --version
 
 ```scl enable rh-python36 bash```
 
-* create the sc4s unit file ``/etc/systemd/system/sc4s.service`` and add the following content
+* create the sc4s unit file ``/lib/systemd/system/sc4s.service`` and add the following content
 
 ```ini
 [Unit]
diff --git a/docs/gettingstarted/podman-systemd-general.md b/docs/gettingstarted/podman-systemd-general.md
index cc4714e..f38c5b3 100644
--- a/docs/gettingstarted/podman-systemd-general.md
+++ b/docs/gettingstarted/podman-systemd-general.md
@@ -54,7 +54,7 @@ ExecStart=/usr/bin/podman run -p 514:514 -p 514:514/udp -p 6514:6514 \
 failure to the upstream destination(s).  This will also be used to keep track of the state of syslog-ng between restarts, and in
 particular the state of the disk buffer.  This is a required step.
 ```
-sudo docker volume create splunk-sc4s-var
+sudo podman volume create splunk-sc4s-var
 ```
 
 * Create the subdirectory ``/opt/sc4s/local``.  This will be used as a mount point for local overrides and configurations.
@@ -279,7 +279,7 @@ information.
 
 To operate SC4S as a user other than root, follow the instructions above, with these modifications:
 
-## Prepare SC4S user
+## Prepare sc4s user
 
 Create a non-root user in which to run SC4S and prepare podman for non-root operation:
 
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 38b1a0d..2491f14 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -6,7 +6,10 @@ a new version of SC4S in production.
 
 ## Version 1.9.0
 
-Example context files have been added to the local mount `context` directory.  These example files will be updated at each release
+* Example context files have been added to the local mount `context` directory.  These example files will be updated at each release
 to outline support for new data sources, which can be added to existing context files (those without the `.example` extension).
 Existing context files will _not_ be overwritten on subsequent SC4S starts/upgrades, so ensure that any new content from these example
 files is incorporated into existing context files.
+
+* UNIT FILE CHANGES:  Make sure to update the unit file used to start the sc4s service with the changes included in this release. It
+includes updates for proper operation with RHEL 8, and is backward-compatible with RHEL 7.7.

From 55f37c8375b03e6248dcdfff4f00e3193bbc6867 Mon Sep 17 00:00:00 2001
From: Mark Bonsack <mbonsack@splunk.com>
Date: Mon, 3 Feb 2020 12:12:59 -0800
Subject: [PATCH 23/25] Fix version string in `/entrypoint.sh`

* Update version code to reference proper file `/VERSION`
* Comment out python source -- to be addressed in a future release
---
 package/sbin/entrypoint.sh | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh
index d8d8b53..66bdb51 100755
--- a/package/sbin/entrypoint.sh
+++ b/package/sbin/entrypoint.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
-source scl_source enable rh-python36
+
+# The follwoing will be addressed in a future release
+# source scl_source enable rh-python36
 
 # The MICROFOCUS_ARCSIGHT unique port environment variables are currently deprecated
 # This will be removed when the MICROFOCUS_ARCSIGHT unique port environment variables are removed in version 2.0
@@ -20,8 +22,8 @@ for file in /opt/syslog-ng/etc/conf.d/local/context/*.example ; do cp --verbose
 cp --verbose -R /opt/syslog-ng/etc/local_config/* /opt/syslog-ng/etc/conf.d/local/config/
 
 echo syslog-ng checking config
-echo sc4s version=$(cat /version)
-echo sc4s version=$(cat /version) >/var/log/syslog-ng.out
+echo sc4s version=$(cat /VERSION)
+echo sc4s version=$(cat /VERSION) >/var/log/syslog-ng.out
 /opt/syslog-ng/sbin/syslog-ng -s >>/var/log/syslog-ng.out 2>/var/log/syslog-ng.err
 
 echo syslog-ng starting

From 697d6c733c2e629a8e2b454d513fc1d6d4f42606 Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Mon, 3 Feb 2020 18:22:38 -0500
Subject: [PATCH 24/25] Update config.yml

---
 .circleci/config.yml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index d13a074..25a98cd 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -29,7 +29,13 @@ jobs:
       - versioning/define_version
       - versioning/create_version_file:
          version_file_path: /tmp/workspace/VERSION
-
+      - run:
+          name: Record version
+          command: |
+            CIRCLE_BRANCH_CLEAN=$(echo ${CIRCLE_BRANCH} | sed 's/[^a-zA-Z0-9\._-]//g')
+            if [ -n "${CIRCLE_TAG}" ]; then DOCKER_TAG=${CIRCLE_TAG}; else DOCKER_TAG="${CIRCLE_BRANCH_CLEAN}"; fi
+            if [ -n "${CIRCLE_TAG}" ]; then VERSION=${CIRCLE_TAG}; else VERSION="${CIRCLE_BRANCH_CLEAN}@${CIRCLE_SHA1:0:6}"; fi
+            echo $DOCKER_TAG>package/VERSION
       - docker/install-docker
       - docker/check:
           registry: $REGISTRY

From 076707adc80eb6519aae6b332d39986caf3e57bb Mon Sep 17 00:00:00 2001
From: rfaircloth-splunk <rfaircloth@splunk.com>
Date: Mon, 3 Feb 2020 21:10:36 -0500
Subject: [PATCH 25/25] Update config.yml

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index fd33715..353c0ff 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -35,7 +35,7 @@ jobs:
             CIRCLE_BRANCH_CLEAN=$(echo ${CIRCLE_BRANCH} | sed 's/[^a-zA-Z0-9\._-]//g')
             if [ -n "${CIRCLE_TAG}" ]; then DOCKER_TAG=${CIRCLE_TAG}; else DOCKER_TAG="${CIRCLE_BRANCH_CLEAN}"; fi
             if [ -n "${CIRCLE_TAG}" ]; then VERSION=${CIRCLE_TAG}; else VERSION="${CIRCLE_BRANCH_CLEAN}@${CIRCLE_SHA1:0:6}"; fi
-            echo $DOCKER_TAG>package/VERSION
+            echo $DOCKER_TAG-${CIRCLE_BRANCH_CLEAN}@${CIRCLE_SHA1:0:7}>package/VERSION
       - docker/install-docker
       - docker/check:
           registry: $REGISTRY