From fcc69a30b2580acde1a271f158994f3b154134b6 Mon Sep 17 00:00:00 2001
From: Alexis Mousset <alexis.mousset@rudder.io>
Date: Thu, 19 Dec 2024 16:28:43 +0100
Subject: [PATCH] Add documentation for the env prefix in package promises's
 options attribute

---
 reference/promise-types/packages.markdown | 99 +++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/reference/promise-types/packages.markdown b/reference/promise-types/packages.markdown
index 1514d7fc3..e46c14145 100644
--- a/reference/promise-types/packages.markdown
+++ b/reference/promise-types/packages.markdown
@@ -127,6 +127,20 @@ rescue solution when a package module has added functionality which is not
 covered by the package promise API. As such there is no official documentation
 for this attribute, its usage depends on the package module in question.
 
+Some package managers support a special ```env``` prefix to set environment
+variables for the package manager. For example, to set the ```EXTERNAL_URL```
+environment variable:
+
+```cf3
+packages:
+    "gitlab-ce"
+      policy => "present",
+      options => { "env:EXTERNAL_URL=https://example.com" };
+```
+
+This allows customizing the behavior of some package managers, or setting
+parameters used by some packaging scripts.
+
 **Type:** `slist`
 
 **Allowed input range:** (arbitrary string)
@@ -441,10 +455,28 @@ bundle agent example
   screen-4.1.0-0.19.20120314git3c2946.el7.x86_64
   ```
 
+* Supports [```options```][packages#options] attribute. Each space separate
+  option must be added as a separate list element. The options are passed
+  directly through to the package manager.
+* It is possible to use the [```options```][packages#options] attribute to pass
+  environment variables to the package manager with the ```env``` prefix. For
+  example, to set the ```EXTERNAL_URL``` environment variable:
+
+  ```cf3
+  bundle agent example_yum_pass_env_options
+  {
+    packages:
+        "gitlab-ce"
+          policy => "present",
+          options => { "env:EXTERNAL_URL=https://example.com" };
+  }
+  ```
+
 **History:**
 
 * Added in CFEngine 3.7.0
 * `enablerepo` and `disablerepo` option support added in 3.7.8, 3.10.4, 3.12.0
+* ```env``` prefix ```options``` in support added in 3.21.7, 3.24.2 and 3.25.0
 
 ### apt_get
 
@@ -478,10 +510,24 @@ packages:
 * Supports [```options```][packages#options] attribute. Each space separate
   option must be added as a separate list element. The options are passed
   directly through to the package manager.
+* It is possible to use the [```options```][packages#options] attribute to pass
+  environment variables to the package manager with the ```env``` prefix. For
+  example, to set the ```EXTERNAL_URL``` environment variable:
+
+  ```cf3
+  packages:
+      "gitlab-ce"
+        policy => "present",
+        options => { "env:EXTERNAL_URL=https://example.com" };
+  ```
+  
+  It can for exemple be used to modify the default behavior of ```needrestart```
+  ([documentation](https://manpages.ubuntu.com/manpages/focal/man1/needrestart.1.html)).
 
 **History:**
 
 * Added in CFEngine 3.7.0
+* ```env``` prefix ```options``` in support added in 3.21.7, 3.24.2 and 3.25.0
 
 ### freebsd_ports
 
@@ -656,3 +702,56 @@ bundle agent main
 
 - version `latest` is *not* supported when promising an absence
 - `list-updates` is *not* implemented, snaps are automatically updated by default
+
+### zypper
+
+Manage packages using ```zypper```. This is the [default package module][lib/packages.cf#package_module_knowledge] for SLES, SLED and OpenSUSE.
+
+**Examples:**
+
+File based package source.
+
+```cf3
+packages:
+  sles|sled|opensuse::
+    "/mnt/nfs/packages/apache2-2.2.22.x86_64.rpm"
+      policy => "present";
+```
+
+Repository based package source with a specific version of the package.
+
+```cf3
+packages:
+  sles|sled|opensuse::
+    "apache2"
+      policy => "present",
+      version => "2.2.22";
+```
+
+**Notes:**
+
+* Supports file path and repository sourced packages.
+
+* Requires Python version 2 or 3 to be installed on the host.
+
+* Supports [```options```][packages#options] attribute. Each space separate
+  option must be added as a separate list element. The options are passed
+  directly through to the package manager.
+* It is possible to use the [```options```][packages#options] attribute to pass
+  environment variables to the package manager with the ```env``` prefix. For
+  example, to set the ```EXTERNAL_URL``` environment variable:
+
+  ```cf3
+  bundle agent example_yum_pass_env_options
+  {
+    packages:
+        "gitlab-ce"
+          policy => "present",
+          options => { "env:EXTERNAL_URL=https://example.com" };
+  }
+  ```
+
+**History:**
+
+* Added in CFEngine 3.11.0
+* ```env``` prefix ```options``` in support added in 3.21.7, 3.24.2 and 3.25.0