anti-patterns: add /usr/bin/env launching
Outside of OpenBMC, most applications that provide systemd unit files
don't launch applications in this way.
Change-Id: Ie918be8727c51a1f8f05b8f845b9967c2a18c5af
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/anti-patterns.md b/anti-patterns.md
index bdad52c..65c2d47 100644
--- a/anti-patterns.md
+++ b/anti-patterns.md
@@ -72,3 +72,60 @@
Do not list shared library packages in RDEPENDS. This eliminates the
possibility of installing unnecessary shared library packages due to
unmaintained library dependency lists in bitbake metadata.
+
+## Use of /usr/bin/env in systemd service files
+
+### Identification
+In systemd unit files:
+```
+[Service]
+
+ExecStart=/usr/bin/env some-application
+```
+
+### Description
+Outside of OpenBMC, most applications that provide systemd unit files don't
+launch applications in this way. So if nothing else, this just looks strange
+and violates the [princple of least
+astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).
+
+### Background
+This anti-pattern exists because a requirement exists to enable live patching of
+applications on read-only filesystems. Launching applications in this way was
+part of the implementation that satisfied the live patch requirement. For
+example:
+
+```
+/usr/bin/phosphor-hwmon
+```
+
+on a read-only filesystem becomes:
+
+```
+/usr/local/bin/phosphor-hwmon`
+```
+
+on a writeable /usr/local filesystem.
+
+### Resolution
+The /usr/bin/env method only enables live patching of applications. A method
+that supports live patching of any file in the read-only filesystem has emerged.
+Assuming a writeable filesystem exists _somewhere_ on the bmc, something like:
+
+```
+mkdir -p /var/persist/usr
+mkdir -p /var/persist/work/usr
+mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr
+```
+can enable live system patching without any additional requirements on how
+applications are launched from systemd service files. This is the preferred
+method for enabling live system patching as it allows OpenBMC developers to
+write systemd service files in the same way as most other projects.
+
+To undo existing instances of this anti-pattern remove /usr/bin/env from systemd
+service files and replace with the fully qualified path to the application being
+launched. For example, given an application in /usr/bin:
+
+```
+sed -i s,/usr/bin/env ,/usr/bin/, foo.service
+```