
1. bdebstrap does not enforce any policy for execution of shell commands other
   than exiting with error if the command returns non-zero.
   If running shell commands that require variables, consider enforcing a
   stricter evaluation policy with set -u.

---
mmdebstrap:
  keyrings:
    - /usr/share/keyrings/debian-archive-keyring.gpg
  mode: unshare
  suite: unstable
  target: root.tar.xz
  variant: apt
  setup-hooks:
    - echo foo ; true  # ok
    - echo foo ; false # will fail
  customize-hooks:
    - echo $notavar          # won't fail
    - set -u ; echo $notavar # will fail
    - |                      # use scalar block syntax for complex expressions
      set -eu ;
      chroot $1 sh -c "if ! id -u $USER >/dev/null 2>&1; then
      adduser --disabled-password --gecos \"\" $USER;
      fi"


2. Other YAML syntax options which may/may not work based on requirements:

Folded Block Scalar:
customize-hooks:
  - >
    uchroot $1 'mkdir -m 0700 -p /home/${USER}/.ssh &&
    install -m 0600 -o ${USER} -g ${USER} /dev/null /home/${USER}/.ssh/authorized_keys'


Folded Block Scalar >- (Strips Final Newline):
customize-hooks:
  - >-
    uchroot $1 'mkdir -m 0700 -p /home/${USER}/.ssh &&
    install -m 0600 -o ${USER} -g ${USER} /dev/null /home/${USER}/.ssh/authorized_keys'


Plain String with Line Continuation:
customize-hooks:
  - uchroot $1 'mkdir -m 0700 -p /home/${USER}/.ssh &&
    install -m 0600 -o ${USER} -g ${USER} /dev/null /home/${USER}/.ssh/authorized_keys'


Break at Natural Points:
customize-hooks:
  - >-
    uchroot $1 'mkdir -m 0700 -p /home/${USER}/.ssh 
    && install -m 0600 -o ${USER} -g ${USER} /dev/null /home/${USER}/.ssh/authorized_keys'


3. Use the lint metadata engine command for layer development.
   Linting will catch:
     Unsupported fields (schema violations)
     Missing variable prefix when variables are defined
     Orphaned attributes (e.g., X-Env-Var-PORT-Desc without X-Env-Var-PORT)
     Invalid default values that don't match their own validation rules
     Invalid validation rules (unparseable rule syntax)

   Linting will NOT catch:
     Missing environment variables (that's runtime, not syntax)
     Invalid environment values (that's runtime validation)

4. Match dpkgopts path-exclude/path-include rules to the paths recorded
   in packages from the Debian suite used by the image. dpkg matches
   package paths; merged-usr symlinks do not rewrite them.

   For example, firmware-brcm80211 ships /lib/firmware/... in Bookworm
   but /usr/lib/firmware/... in Trixie. A filter for /lib/firmware/*
   matches the Bookworm package even on merged-usr systems, but cannot
   match Trixie's /usr/lib/firmware/* entries.

   Inspect the target suite's package file list (for example, with
   `dpkg -L firmware-brcm80211` in a matching build environment) before
   choosing filters. A non-matching path-exclude is silently ignored,
   so check the built image to verify the intended files were removed.
