fix(debian): preserve vector.yaml as a conffile + move examples to docs folder

Cargo.toml

@@ -54,11 +54,12 @@ workspace = true
 name = "vector"
 section = "admin"
 maintainer-scripts = "distribution/debian/scripts/"
-conf-files = ["/etc/default/vector"]
+conf-files = ["/etc/default/vector", "/etc/vector/vector.yaml"]
 assets = [
   ["target/release/vector", "/usr/bin/", "755"],
+  ["distribution/debian/vector.yaml", "/etc/vector/vector.yaml", "644"],
   ["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-conffile-examples-location.fix.md

@@ -0,0 +1,4 @@
+Fixed two Debian packaging issues: `/etc/vector/vector.yaml` is now shipped as a proper Debian conffile (a stub with no active sources/sinks) so local modifications are preserved across upgrades; example configurations have been moved from `/etc/vector/examples/` to `/usr/share/doc/vector/examples/` where they belong as documentation rather than administrator-managed configuration.
+
+Since `/etc/vector/vector.yaml` was not previously a dpkg conffile, a pre-existing file at that path (created by a user, or by a Vector version prior to this fix) would otherwise make `dpkg` stop with an interactive "file created by you" conffile prompt, breaking unattended upgrades. Maintainer scripts now move any such untracked file aside before install and restore it afterwards, so upgrades complete without prompting and existing content is preserved byte-for-byte.
+authors: koenserry

distribution/debian/scripts/postinst

@@ -1,6 +1,37 @@
 #!/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.57.0-1 vector -- "$@"
+done
+
+# Restore a pre-existing /etc/vector/vector.yaml that preinst moved aside
+# (see preinst for why). This puts the user's original content back in
+# place of the stub conffile dpkg just unpacked, so nothing is lost and no
+# conffile prompt was ever shown.
+if [ -e /etc/vector/vector.yaml.vector-preserve ]; then
+  mv -f /etc/vector/vector.yaml.vector-preserve /etc/vector/vector.yaml
+fi
+
 # Add Vector to adm group to read /var/logs
 usermod --append --groups adm vector || true
 

distribution/debian/scripts/preinst

@@ -1,6 +1,30 @@
 #!/bin/sh
 set -e
 
+# /etc/vector/examples/*.yaml were conffiles through v0.57.0; they moved to
+# /usr/share/doc/vector/examples/. Remove unmodified copies 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.57.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 \
@@ -12,4 +36,21 @@ mkdir -p /var/lib/vector
 # Make vector:vector the owner of the Vector data directory
 chown -R vector:vector /var/lib/vector
 
+# /etc/vector/vector.yaml was not a dpkg conffile before this version. If a
+# file already exists at that path, dpkg has no record of it and will treat
+# it as "created by you", prompting interactively (or failing outright on
+# unattended upgrades) before it will unpack the new conffile over it. Move
+# any such untracked file out of the way so dpkg can install the conffile
+# cleanly; postinst restores it afterwards so the user's content is kept
+# byte-for-byte, without ever prompting.
+case "$1" in
+  install|upgrade)
+    if [ -e /etc/vector/vector.yaml ] && [ ! -L /etc/vector/vector.yaml ]; then
+      if ! dpkg-query -W -f='${Conffiles}' vector 2>/dev/null | grep -qE ' /etc/vector/vector\.yaml [0-9a-f]'; then
+        mv /etc/vector/vector.yaml /etc/vector/vector.yaml.vector-preserve
+      fi
+    fi
+    ;;
+esac
+
 #DEBHELPER#

distribution/debian/vector.yaml

@@ -0,0 +1,41 @@
+#                                    __   __  __
+#                                    \ \ / / / /
+#                                     \ V / / /
+#                                      \_/  \/
+#
+#                                    V E C T O R
+#                                   Configuration
+#
+# ------------------------------------------------------------------------------
+# Website: https://vector.dev
+# Docs: https://vector.dev/docs
+# Chat: https://chat.vector.dev
+# ------------------------------------------------------------------------------
+
+# Change this to use a non-default directory for Vector data storage:
+# data_dir: "/var/lib/vector"
+
+# Example configurations are available at /usr/share/doc/vector/examples/
+
+# Add your sources, transforms, and sinks here.
+# See https://vector.dev/docs/reference/configuration/ for full reference.
+
+# sources:
+#   my_source:
+#     type: "..."
+
+# transforms:
+#   my_transform:
+#     type: "..."
+#     inputs: ["my_source"]
+
+# sinks:
+#   my_sink:
+#     type: "..."
+#     inputs: ["my_transform"]
+
+# Vector's API (disabled by default)
+# Uncomment to try it out with the `vector top` command
+# api:
+#   enabled: true
+#   address: "127.0.0.1:8686"

scripts/verify-install.sh

@@ -20,16 +20,43 @@ install_package () {
   esac
 }
 
+case "$package" in
+  *.deb)
+    # Simulate a pre-existing /etc/vector/vector.yaml that predates this file
+    # being a dpkg conffile (e.g. a user-created file from before this fix, or
+    # an earlier Vector version that didn't ship one at all). Installing over
+    # it must not prompt (dpkg has no tty here, so a prompt would hang/fail
+    # this script) and must leave the user's content untouched.
+    mkdir -p /etc/vector
+    echo "unmanaged: pre-existing-config" > /etc/vector/vector.yaml
+    ;;
+esac
+
 install_package "$package"
 
+case "$package" in
+  *.deb)
+    grep -q "unmanaged: pre-existing-config" /etc/vector/vector.yaml || \
+      (echo "pre-existing, dpkg-untracked /etc/vector/vector.yaml was not preserved on install" && exit 1)
+    ;;
+esac
+
 getent passwd vector || (echo "vector user missing" && exit 1)
 getent group vector || (echo "vector group  missing" && exit 1)
 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 -f /etc/vector/vector.yaml || (echo "/etc/vector/vector.yaml should be installed by default" && exit 1)
+    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)
+    ;;
+  *.rpm)
+    test ! -e /etc/vector/vector.yaml || (echo "/etc/vector/vector.yaml should not be installed by default" && exit 1)
+    ;;
+esac
 
-mkdir -p /etc/vector
 echo "FOO=bar" > /etc/default/vector
 echo "foo: bar" > /etc/vector/vector.yaml