fix(debian): move example configurations out of /etc/vector

Cargo.toml

@@ -58,7 +58,7 @@ conf-files = ["/etc/default/vector"]
 assets = [
   ["target/release/vector", "/usr/bin/", "755"],
   ["config/vector.yaml", "/usr/share/vector/examples/vector.yaml", "644"],
-  ["config/examples/*", "/etc/vector/examples/", "644"],
+  ["config/examples/*", "/usr/share/doc/vector/examples/", "644"],
   ["distribution/systemd/vector.service", "/lib/systemd/system/vector.service", "644"],
   ["distribution/systemd/vector.default", "/etc/default/vector", "600"],
   ["licenses/*", "/usr/share/vector/licenses/", "644"],

changelog.d/deb_examples_relocation.breaking.md

@@ -0,0 +1,13 @@
+# Debian example configurations moved out of /etc/vector {#deb-examples-relocation}
+
+## Summary
+
+The Debian package now installs its example configurations to `/usr/share/doc/vector/examples/` instead of `/etc/vector/examples/`. Examples are documentation rather than administrator-managed configuration, so `/etc` was the wrong location for them.
+
+## Migration
+
+No action is required for most users. The examples are not read by Vector; they are reference material only, and the new copies are installed automatically on upgrade.
+
+Because the old paths were dpkg conffiles, the upgrade removes unmodified copies from `/etc/vector/examples/` and leaves any file you edited in place, so local changes are never discarded silently. If you edited an example and want to keep it, move it somewhere outside `/etc/vector/examples/`; if you referenced one from your own configuration with a path under `/etc/vector/examples/`, update that path to `/usr/share/doc/vector/examples/`.
+
+authors: koenserry

distribution/debian/scripts/postinst

@@ -1,6 +1,29 @@
 #!/bin/sh
 set -e
 
+# Complete the rm_conffile transition started in preinst; see preinst for context.
+for _example_conffile in \
+  docs_example.yaml \
+  environment_variables.yaml \
+  es_s3_hybrid.yaml \
+  file_to_cloudwatch_metrics.yaml \
+  file_to_prometheus.yaml \
+  http_sink_custom_retry.yaml \
+  prometheus_to_console.yaml \
+  stdio.yaml \
+  varint_framing_protobuf.yaml \
+  wrapped_json.yaml \
+  namespacing/sinks/es_cluster.yaml \
+  namespacing/sinks/s3_archives.yaml \
+  namespacing/sources/apache_logs.yaml \
+  namespacing/transforms/apache_parser.yaml \
+  namespacing/transforms/apache_sample.yaml \
+  namespacing/vector.yaml
+do
+  dpkg-maintscript-helper rm_conffile \
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
+done
+
 # Add Vector to adm group to read /var/logs
 usermod --append --groups adm vector || true
 

distribution/debian/scripts/postrm

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -e
+
+# Complete the rm_conffile transition started in preinst; see preinst for
+# context. dpkg-maintscript-helper requires rm_conffile to be called from
+# preinst, postinst *and* postrm so that aborted upgrades restore the files
+# it moved aside and purges clean up its backups.
+for _example_conffile in \
+  docs_example.yaml \
+  environment_variables.yaml \
+  es_s3_hybrid.yaml \
+  file_to_cloudwatch_metrics.yaml \
+  file_to_prometheus.yaml \
+  http_sink_custom_retry.yaml \
+  prometheus_to_console.yaml \
+  stdio.yaml \
+  varint_framing_protobuf.yaml \
+  wrapped_json.yaml \
+  namespacing/sinks/es_cluster.yaml \
+  namespacing/sinks/s3_archives.yaml \
+  namespacing/sources/apache_logs.yaml \
+  namespacing/transforms/apache_parser.yaml \
+  namespacing/transforms/apache_sample.yaml \
+  namespacing/vector.yaml
+do
+  dpkg-maintscript-helper rm_conffile \
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
+done
+
+#DEBHELPER#

distribution/debian/scripts/preinst

@@ -1,6 +1,30 @@
 #!/bin/sh
 set -e
 
+# /etc/vector/examples/*.yaml move to /usr/share/doc/vector/examples/ in
+# v0.59.0. Remove unmodified copies from earlier versions on upgrade.
+for _example_conffile in \
+  docs_example.yaml \
+  environment_variables.yaml \
+  es_s3_hybrid.yaml \
+  file_to_cloudwatch_metrics.yaml \
+  file_to_prometheus.yaml \
+  http_sink_custom_retry.yaml \
+  prometheus_to_console.yaml \
+  stdio.yaml \
+  varint_framing_protobuf.yaml \
+  wrapped_json.yaml \
+  namespacing/sinks/es_cluster.yaml \
+  namespacing/sinks/s3_archives.yaml \
+  namespacing/sources/apache_logs.yaml \
+  namespacing/transforms/apache_parser.yaml \
+  namespacing/transforms/apache_sample.yaml \
+  namespacing/vector.yaml
+do
+  dpkg-maintscript-helper rm_conffile \
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
+done
+
 # Add vector:vector user & group
 id --user vector >/dev/null 2>&1 || \
   useradd --system --shell /sbin/nologin --home-dir /var/lib/vector --user-group \

scripts/verify-install.sh

@@ -32,6 +32,12 @@ vector --version || (echo "vector --version failed" && exit 1)
 test -f /etc/default/vector || (echo "/etc/default/vector doesn't exist" && exit 1)
 test ! -e /etc/vector/vector.yaml || (echo "/etc/vector/vector.yaml should not be installed by default" && exit 1)
 test -f /usr/share/vector/examples/vector.yaml || (echo "/usr/share/vector/examples/vector.yaml doesn't exist" && exit 1)
+case "$package" in
+  *.deb)
+    test ! -d /etc/vector/examples || (echo "examples should not be installed under /etc/vector/examples" && exit 1)
+    test -f /usr/share/doc/vector/examples/stdio.yaml || (echo "/usr/share/doc/vector/examples/ examples missing" && exit 1)
+    ;;
+esac
 
 mkdir -p /etc/vector
 echo "FOO=bar" > /etc/default/vector