From 7bc4e400cc38a22b5a5534c34f0b3cfc94f47680 Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Fri, 17 Jul 2026 17:03:00 +0200
Subject: [PATCH 01/10] fix(debian): preserve vector.yaml as a conffile

---
 Cargo.toml                                    |  5 ++-
 .../deb-conffile-examples-location.fix.md     |  2 +
 distribution/debian/vector.yaml               | 41 +++++++++++++++++++
 scripts/verify-install.sh                     | 12 +++++-
 4 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 changelog.d/deb-conffile-examples-location.fix.md
 create mode 100644 distribution/debian/vector.yaml

diff --git a/Cargo.toml b/Cargo.toml
index 23b52c525ade9..a855e0a7997da 100644
--- a/Cargo.toml
+++ b/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"],
diff --git a/changelog.d/deb-conffile-examples-location.fix.md b/changelog.d/deb-conffile-examples-location.fix.md
new file mode 100644
index 0000000000000..1f65b2cf8a529
--- /dev/null
+++ b/changelog.d/deb-conffile-examples-location.fix.md
@@ -0,0 +1,2 @@
+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.
+authors: koenserry
\ No newline at end of file
diff --git a/distribution/debian/vector.yaml b/distribution/debian/vector.yaml
new file mode 100644
index 0000000000000..b614de7902651
--- /dev/null
+++ b/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"
diff --git a/scripts/verify-install.sh b/scripts/verify-install.sh
index ab9e6039f3f14..92e2de5a8fe09 100755
--- a/scripts/verify-install.sh
+++ b/scripts/verify-install.sh
@@ -26,10 +26,18 @@ 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
 

From 985902b9684321498201e2db226772561cbdfb25 Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:53:30 +0200
Subject: [PATCH 02/10] fix(debian): preserve pre-existing vector.yaml when it
 becomes a conffile

Since /etc/vector/vector.yaml was not a dpkg conffile before this change,
a file already present at that path (created by a user, or by an older
Vector package) is unknown to dpkg. Unpacking it as a new conffile makes
dpkg treat it as "created by you" and stop at an interactive prompt,
which breaks unattended upgrades without --force-confold/confnew.

Add a preinst/postinst transition: preinst moves aside any untracked
pre-existing file so dpkg can install the conffile without prompting,
and postinst restores it afterwards so the content is preserved
byte-for-byte. Once installed this way the path is a normal tracked
conffile and standard dpkg conffile handling applies on later upgrades.

Extend verify-install.sh to seed such an untracked file before the first
install and assert it survives, since the existing verify path only
reinstalled the same package and never exercised this transition.
---
 .../deb-conffile-examples-location.fix.md     |  2 ++
 distribution/debian/scripts/postinst          |  8 ++++++++
 distribution/debian/scripts/preinst           | 17 +++++++++++++++++
 scripts/verify-install.sh                     | 19 +++++++++++++++++++
 4 files changed, 46 insertions(+)

diff --git a/changelog.d/deb-conffile-examples-location.fix.md b/changelog.d/deb-conffile-examples-location.fix.md
index 1f65b2cf8a529..d8faf716f9f1e 100644
--- a/changelog.d/deb-conffile-examples-location.fix.md
+++ b/changelog.d/deb-conffile-examples-location.fix.md
@@ -1,2 +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
\ No newline at end of file
diff --git a/distribution/debian/scripts/postinst b/distribution/debian/scripts/postinst
index d20a3bc4cb52b..7a079d91b13d0 100755
--- a/distribution/debian/scripts/postinst
+++ b/distribution/debian/scripts/postinst
@@ -1,6 +1,14 @@
 #!/bin/sh
 set -e
 
+# 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
 
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index 373da4aad17ec..d1d07e903c345 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -12,4 +12,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 -q ' /etc/vector/vector.yaml '; then
+        mv /etc/vector/vector.yaml /etc/vector/vector.yaml.vector-preserve
+      fi
+    fi
+    ;;
+esac
+
 #DEBHELPER#
diff --git a/scripts/verify-install.sh b/scripts/verify-install.sh
index 92e2de5a8fe09..726acf85ee306 100755
--- a/scripts/verify-install.sh
+++ b/scripts/verify-install.sh
@@ -20,8 +20,27 @@ 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)

From 80f61b88a3bfdc3cde9dd6d0d1481b6898909a3a Mon Sep 17 00:00:00 2001
From: Thomas <thomas.schneider@datadoghq.com>
Date: Wed, 22 Jul 2026 10:06:36 -0400
Subject: [PATCH 03/10] fix(debian): add rm_conffile transitions for
 /etc/vector/examples/*.yaml

---
 distribution/debian/scripts/postinst | 23 +++++++++++++++++++++++
 distribution/debian/scripts/preinst  | 24 ++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/distribution/debian/scripts/postinst b/distribution/debian/scripts/postinst
index 7a079d91b13d0..04da2bd625dec 100755
--- a/distribution/debian/scripts/postinst
+++ b/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.57.0 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
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index d1d07e903c345..f75fca120dcd1 100755
--- a/distribution/debian/scripts/preinst
+++ b/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 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 \

From 657e31940087ca7d1b7639eb080854f1fddd0105 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.schneider@datadoghq.com>
Date: Wed, 22 Jul 2026 12:47:22 -0400
Subject: [PATCH 04/10] fix(debian): use 0.57.0-1 as rm_conffile prior-version

---
 distribution/debian/scripts/postinst | 2 +-
 distribution/debian/scripts/preinst  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/distribution/debian/scripts/postinst b/distribution/debian/scripts/postinst
index 04da2bd625dec..33eda4595cd45 100755
--- a/distribution/debian/scripts/postinst
+++ b/distribution/debian/scripts/postinst
@@ -21,7 +21,7 @@ for _example_conffile in \
   namespacing/vector.yaml
 do
   dpkg-maintscript-helper rm_conffile \
-    "/etc/vector/examples/$_example_conffile" 0.57.0 vector -- "$@"
+    "/etc/vector/examples/$_example_conffile" 0.57.0-1 vector -- "$@"
 done
 
 # Restore a pre-existing /etc/vector/vector.yaml that preinst moved aside
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index f75fca120dcd1..f0275dcc9b300 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -22,7 +22,7 @@ for _example_conffile in \
   namespacing/vector.yaml
 do
   dpkg-maintscript-helper rm_conffile \
-    "/etc/vector/examples/$_example_conffile" 0.57.0 vector -- "$@"
+    "/etc/vector/examples/$_example_conffile" 0.57.0-1 vector -- "$@"
 done
 
 # Add vector:vector user & group

From bbd27f3a80c3da95cae50e45aa493f27a4eacc1c Mon Sep 17 00:00:00 2001
From: Thomas <thomas.schneider@datadoghq.com>
Date: Wed, 22 Jul 2026 13:26:21 -0400
Subject: [PATCH 05/10] fix(debian): treat obsolete vector.yaml conffile entry
 as untracked

---
 distribution/debian/scripts/preinst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index f0275dcc9b300..7f5bed9f62cf7 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -46,7 +46,7 @@ chown -R vector:vector /var/lib/vector
 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 -q ' /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

From 8ec1d430b07be054cb6ec0363d0ae66a9aeb3672 Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Mon, 21 Sep 2026 22:09:38 +0200
Subject: [PATCH 06/10] fix(debian): complete conffile transitions in postrm
 and guard foreign ownership

Add the postrm half of the rm_conffile transition for the old
/etc/vector/examples/*.yaml conffiles, as dpkg-maintscript-helper
requires, so an aborted upgrade restores them and a purge cleans up its
backups.

Also restore a preserved /etc/vector/vector.yaml from postrm on
abort-install/abort-upgrade, so a failure between preinst and postinst
never leaves Vector without the config it was running with, and skip the
preserve move entirely when another package owns the file so dpkg's own
file-conflict check still reports the conflict. The conffile lookup now
ignores entries dpkg marks obsolete.
---
 distribution/debian/scripts/postrm  | 45 +++++++++++++++++++++++++++++
 distribution/debian/scripts/preinst |  8 ++++-
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100755 distribution/debian/scripts/postrm

diff --git a/distribution/debian/scripts/postrm b/distribution/debian/scripts/postrm
new file mode 100755
index 0000000000000..cae527706eccd
--- /dev/null
+++ b/distribution/debian/scripts/postrm
@@ -0,0 +1,45 @@
+#!/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.57.0-1 vector -- "$@"
+done
+
+# If preinst moved a pre-existing /etc/vector/vector.yaml aside (see preinst)
+# and the install or upgrade then failed before postinst could restore it,
+# put it back here so a failed upgrade never leaves Vector without the
+# configuration it was running with.
+case "$1" in
+  abort-install|abort-upgrade)
+    if [ -e /etc/vector/vector.yaml.vector-preserve ]; then
+      mv -f /etc/vector/vector.yaml.vector-preserve /etc/vector/vector.yaml
+    fi
+    ;;
+  purge)
+    rm -f /etc/vector/vector.yaml.vector-preserve
+    ;;
+esac
+
+#DEBHELPER#
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index 7f5bed9f62cf7..50c4b3531bce5 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -43,10 +43,16 @@ chown -R vector:vector /var/lib/vector
 # 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.
+#
+# Only move the file when no package owns it: if it belongs to another
+# package, leave it alone so dpkg's own file-conflict check reports the
+# ownership conflict instead of us silently hiding that package's file.
 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
+      if ! dpkg-query -W -f='${Conffiles}\n' vector 2>/dev/null \
+        | awk '$1 == "/etc/vector/vector.yaml" && $3 != "obsolete" { found = 1 } END { exit !found }' \
+        && ! dpkg-query -S /etc/vector/vector.yaml >/dev/null 2>&1; then
         mv /etc/vector/vector.yaml /etc/vector/vector.yaml.vector-preserve
       fi
     fi

From d99827a50919296bc80ce61da16994addf107973 Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:47:07 +0200
Subject: [PATCH 07/10] chore(changelog): add missing trailing newline to
 fragment

---
 changelog.d/deb-conffile-examples-location.fix.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelog.d/deb-conffile-examples-location.fix.md b/changelog.d/deb-conffile-examples-location.fix.md
index d8faf716f9f1e..6439564b38b42 100644
--- a/changelog.d/deb-conffile-examples-location.fix.md
+++ b/changelog.d/deb-conffile-examples-location.fix.md
@@ -1,4 +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
\ No newline at end of file
+authors: koenserry

From 72c871a1625581a03bad152ceaa0b3b58845a2d1 Mon Sep 17 00:00:00 2001
From: Pavlos Rontidis <pavlos.rontidis@gmail.com>
Date: Tue, 22 Sep 2026 14:51:20 -0400
Subject: [PATCH 08/10] fix(debian): preserve obsolete configs and migrate
 recent examples

---
 distribution/debian/scripts/postinst |  2 +-
 distribution/debian/scripts/postrm   |  2 +-
 distribution/debian/scripts/preinst  | 70 +++++++++++++++++++++++-----
 3 files changed, 60 insertions(+), 14 deletions(-)

diff --git a/distribution/debian/scripts/postinst b/distribution/debian/scripts/postinst
index 33eda4595cd45..82d7a1255f49e 100755
--- a/distribution/debian/scripts/postinst
+++ b/distribution/debian/scripts/postinst
@@ -21,7 +21,7 @@ for _example_conffile in \
   namespacing/vector.yaml
 do
   dpkg-maintscript-helper rm_conffile \
-    "/etc/vector/examples/$_example_conffile" 0.57.0-1 vector -- "$@"
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
 done
 
 # Restore a pre-existing /etc/vector/vector.yaml that preinst moved aside
diff --git a/distribution/debian/scripts/postrm b/distribution/debian/scripts/postrm
index cae527706eccd..c539ebdad5639 100755
--- a/distribution/debian/scripts/postrm
+++ b/distribution/debian/scripts/postrm
@@ -24,7 +24,7 @@ for _example_conffile in \
   namespacing/vector.yaml
 do
   dpkg-maintscript-helper rm_conffile \
-    "/etc/vector/examples/$_example_conffile" 0.57.0-1 vector -- "$@"
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
 done
 
 # If preinst moved a pre-existing /etc/vector/vector.yaml aside (see preinst)
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index 50c4b3531bce5..1d609449a2acc 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -1,8 +1,8 @@
 #!/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.
+# /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 \
@@ -22,7 +22,7 @@ for _example_conffile in \
   namespacing/vector.yaml
 do
   dpkg-maintscript-helper rm_conffile \
-    "/etc/vector/examples/$_example_conffile" 0.57.0-1 vector -- "$@"
+    "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
 done
 
 # Add vector:vector user & group
@@ -36,15 +36,12 @@ 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.
+# Recent versions did not ship /etc/vector/vector.yaml. Preserve both
+# untracked files and obsolete conffiles retained from older versions before
+# introducing the new stub, avoiding interactive prompts on unattended
+# upgrades. postinst restores the user's original content byte-for-byte.
 #
-# Only move the file when no package owns it: if it belongs to another
+# Also preserve obsolete Vector conffiles. If the file belongs to another
 # package, leave it alone so dpkg's own file-conflict check reports the
 # ownership conflict instead of us silently hiding that package's file.
 case "$1" in
@@ -52,8 +49,57 @@ case "$1" in
     if [ -e /etc/vector/vector.yaml ] && [ ! -L /etc/vector/vector.yaml ]; then
       if ! dpkg-query -W -f='${Conffiles}\n' vector 2>/dev/null \
         | awk '$1 == "/etc/vector/vector.yaml" && $3 != "obsolete" { found = 1 } END { exit !found }' \
-        && ! dpkg-query -S /etc/vector/vector.yaml >/dev/null 2>&1; then
+        && ! dpkg-query -S /etc/vector/vector.yaml 2>/dev/null \
+        | grep -qvE '^vector(:[^: ,]+)?: /etc/vector/vector\.yaml$'; then
         mv /etc/vector/vector.yaml /etc/vector/vector.yaml.vector-preserve
+        # An obsolete conffile still has a recorded hash. Leaving its path
+        # absent makes dpkg prompt about a deleted configuration file. Stage
+        # the exact incoming stub instead, then restore the user's file in
+        # postinst (or postrm if installation aborts).
+        # Keep this content byte-for-byte in sync with ../vector.yaml.
+        cat > /etc/vector/vector.yaml <<'VECTOR_CONFIG_STUB'
+#                                    __   __  __
+#                                    \ \ / / / /
+#                                     \ 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"
+VECTOR_CONFIG_STUB
       fi
     fi
     ;;

From 675b0f720f8b53ab11bb39f20c4037c27475c3bf Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Thu, 1 Oct 2026 08:15:38 +0200
Subject: [PATCH 09/10] chore(changelog): separate authors line from fragment
 body

---
 changelog.d/deb-conffile-examples-location.fix.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/changelog.d/deb-conffile-examples-location.fix.md b/changelog.d/deb-conffile-examples-location.fix.md
index 6439564b38b42..fff2c36f41f9e 100644
--- a/changelog.d/deb-conffile-examples-location.fix.md
+++ b/changelog.d/deb-conffile-examples-location.fix.md
@@ -1,4 +1,5 @@
 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

From 77eb2129c06cb4378178cd276908dd2a8ff76be3 Mon Sep 17 00:00:00 2001
From: Koen Serry <482723+koen-serry@users.noreply.github.com>
Date: Thu, 8 Oct 2026 22:18:33 +0200
Subject: [PATCH 10/10] fix(debian): split out the vector.yaml conffile change

Per review, this PR now covers only the relocation of the example
configurations from /etc/vector/examples/ to
/usr/share/doc/vector/examples/. The /etc/vector/vector.yaml conffile
fix moves to a dedicated PR.

The changelog fragment becomes a breaking fragment with migration
instructions, since the relocation changes paths users may reference.
---
 Cargo.toml                                    |  3 +-
 .../deb-conffile-examples-location.fix.md     |  5 --
 .../deb_examples_relocation.breaking.md       | 13 ++++
 distribution/debian/scripts/postinst          |  8 ---
 distribution/debian/scripts/postrm            | 15 ----
 distribution/debian/scripts/preinst           | 69 -------------------
 distribution/debian/vector.yaml               | 41 -----------
 scripts/verify-install.sh                     | 25 +------
 8 files changed, 16 insertions(+), 163 deletions(-)
 delete mode 100644 changelog.d/deb-conffile-examples-location.fix.md
 create mode 100644 changelog.d/deb_examples_relocation.breaking.md
 delete mode 100644 distribution/debian/vector.yaml

diff --git a/Cargo.toml b/Cargo.toml
index 2fb3b71db88ed..070992db8df53 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -54,10 +54,9 @@ workspace = true
 name = "vector"
 section = "admin"
 maintainer-scripts = "distribution/debian/scripts/"
-conf-files = ["/etc/default/vector", "/etc/vector/vector.yaml"]
+conf-files = ["/etc/default/vector"]
 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/*", "/usr/share/doc/vector/examples/", "644"],
   ["distribution/systemd/vector.service", "/lib/systemd/system/vector.service", "644"],
diff --git a/changelog.d/deb-conffile-examples-location.fix.md b/changelog.d/deb-conffile-examples-location.fix.md
deleted file mode 100644
index fff2c36f41f9e..0000000000000
--- a/changelog.d/deb-conffile-examples-location.fix.md
+++ /dev/null
@@ -1,5 +0,0 @@
-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
diff --git a/changelog.d/deb_examples_relocation.breaking.md b/changelog.d/deb_examples_relocation.breaking.md
new file mode 100644
index 0000000000000..8c8c48d4a5144
--- /dev/null
+++ b/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
diff --git a/distribution/debian/scripts/postinst b/distribution/debian/scripts/postinst
index 82d7a1255f49e..e4dd1448f7922 100755
--- a/distribution/debian/scripts/postinst
+++ b/distribution/debian/scripts/postinst
@@ -24,14 +24,6 @@ do
     "/etc/vector/examples/$_example_conffile" 0.59.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
 
diff --git a/distribution/debian/scripts/postrm b/distribution/debian/scripts/postrm
index c539ebdad5639..c97dcc8be9ff2 100755
--- a/distribution/debian/scripts/postrm
+++ b/distribution/debian/scripts/postrm
@@ -27,19 +27,4 @@ do
     "/etc/vector/examples/$_example_conffile" 0.59.0-1~ vector -- "$@"
 done
 
-# If preinst moved a pre-existing /etc/vector/vector.yaml aside (see preinst)
-# and the install or upgrade then failed before postinst could restore it,
-# put it back here so a failed upgrade never leaves Vector without the
-# configuration it was running with.
-case "$1" in
-  abort-install|abort-upgrade)
-    if [ -e /etc/vector/vector.yaml.vector-preserve ]; then
-      mv -f /etc/vector/vector.yaml.vector-preserve /etc/vector/vector.yaml
-    fi
-    ;;
-  purge)
-    rm -f /etc/vector/vector.yaml.vector-preserve
-    ;;
-esac
-
 #DEBHELPER#
diff --git a/distribution/debian/scripts/preinst b/distribution/debian/scripts/preinst
index 1d609449a2acc..1f9fa34435a5d 100755
--- a/distribution/debian/scripts/preinst
+++ b/distribution/debian/scripts/preinst
@@ -36,73 +36,4 @@ mkdir -p /var/lib/vector
 # Make vector:vector the owner of the Vector data directory
 chown -R vector:vector /var/lib/vector
 
-# Recent versions did not ship /etc/vector/vector.yaml. Preserve both
-# untracked files and obsolete conffiles retained from older versions before
-# introducing the new stub, avoiding interactive prompts on unattended
-# upgrades. postinst restores the user's original content byte-for-byte.
-#
-# Also preserve obsolete Vector conffiles. If the file belongs to another
-# package, leave it alone so dpkg's own file-conflict check reports the
-# ownership conflict instead of us silently hiding that package's file.
-case "$1" in
-  install|upgrade)
-    if [ -e /etc/vector/vector.yaml ] && [ ! -L /etc/vector/vector.yaml ]; then
-      if ! dpkg-query -W -f='${Conffiles}\n' vector 2>/dev/null \
-        | awk '$1 == "/etc/vector/vector.yaml" && $3 != "obsolete" { found = 1 } END { exit !found }' \
-        && ! dpkg-query -S /etc/vector/vector.yaml 2>/dev/null \
-        | grep -qvE '^vector(:[^: ,]+)?: /etc/vector/vector\.yaml$'; then
-        mv /etc/vector/vector.yaml /etc/vector/vector.yaml.vector-preserve
-        # An obsolete conffile still has a recorded hash. Leaving its path
-        # absent makes dpkg prompt about a deleted configuration file. Stage
-        # the exact incoming stub instead, then restore the user's file in
-        # postinst (or postrm if installation aborts).
-        # Keep this content byte-for-byte in sync with ../vector.yaml.
-        cat > /etc/vector/vector.yaml <<'VECTOR_CONFIG_STUB'
-#                                    __   __  __
-#                                    \ \ / / / /
-#                                     \ 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"
-VECTOR_CONFIG_STUB
-      fi
-    fi
-    ;;
-esac
-
 #DEBHELPER#
diff --git a/distribution/debian/vector.yaml b/distribution/debian/vector.yaml
deleted file mode 100644
index b614de7902651..0000000000000
--- a/distribution/debian/vector.yaml
+++ /dev/null
@@ -1,41 +0,0 @@
-#                                    __   __  __
-#                                    \ \ / / / /
-#                                     \ 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"
diff --git a/scripts/verify-install.sh b/scripts/verify-install.sh
index 52511071cd016..54cef0b090de8 100755
--- a/scripts/verify-install.sh
+++ b/scripts/verify-install.sh
@@ -24,43 +24,22 @@ 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