Overview

• 1: Quickstart and Usage
• 2: UDS Runner
• 3: Bundle Overrides
• 4: Bundle Anatomy

1 - Quickstart and Usage

Install

Recommended installation method is with Brew:

brew tap defenseunicorns/tap && brew install uds

UDS CLI Binaries are also included with each Github Release

Contributing

Build instructions and contributing docs are located in CONTRIBUTING.md.

Quickstart

The UDS-CLI’s flagship feature is deploying multiple, independent Zarf packages. To create a UDSBundle of Zarf packages, create a uds-bundle.yaml file like so:

kind: UDSBundle
metadata:
  name: example
  description: an example UDS bundle
  version: 0.0.1

packages:
  - name: init
    repository: ghcr.io/defenseunicorns/packages/init
    ref: v0.33.0
    optionalComponents:
      - git-server
  - name: podinfo
    repository: ghcr.io/defenseunicorns/uds-cli/podinfo
    ref: 0.0.1

The above UDSBundle deploys the Zarf init package and podinfo.

The packages referenced in packages can exist either locally or in an OCI registry. See here for an example that deploys both local and remote Zarf packages. More UDSBundle examples can be found in the src/test/bundles folder.

Declarative Syntax

The syntax of a uds-bundle.yaml is entirely declarative. As a result, the UDS CLI will not prompt users to deploy optional components in a Zarf package. If you want to deploy an optional Zarf component, it must be specified in the optionalComponents key of a particular package.

First-class UDS Support

When running deploy,inspect,remove, and pull commands, UDS CLI contains shorthand for interacting with the Defense Unicorns org on GHCR. Specifically, unless otherwise specified, paths will automatically be expanded to the Defense Unicorns org on GHCR. For example:

• uds deploy unicorn-bundle:v0.1.0 is equivalent to uds deploy ghcr.io/defenseunicorns/packages/uds/bundles/unicorn-bundle:v0.1.0

The bundle matching and expansion is ordered as follows:

1. Local with a tar.zst extension
2. Remote path: oci://ghcr.io/defenseunicorns/packages/uds/bundles/<path>
3. Remote path: oci://ghcr.io/defenseunicorns/packages/delivery/<path>
4. Remote path: oci://ghcr.io/defenseunicorns/packages/<path>

That is to say, if the bundle is not local, UDS CLI will check path 2, path 3, etc for the remote bundle artifact. This behavior can be overridden by specifying the full path to the bundle artifact, for example uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0.

Bundle Create

Pulls the Zarf packages from the registry and bundles them into an OCI artifact.

There are 2 ways to create Bundles:

1. Inside an OCI registry: uds create <dir> -o ghcr.io/defenseunicorns/dev
2. Locally on your filesystem: uds create <dir>

Bundle Deploy

Deploys the bundle

There are 2 ways to deploy Bundles:

1. From an OCI registry: uds deploy ghcr.io/defenseunicorns/dev/<name>:<tag>
2. From your local filesystem: uds deploy uds-bundle-<name>.tar.zst

Specifying Packages using --packages

By default all the packages in the bundle are deployed, but you can also deploy only certain packages in the bundle by using the --packages flag.

As an example: uds deploy uds-bundle-<name>.tar.zst --packages init,nginx

Resuming Bundle Deploys using --resume

By default all the packages in the bundle are deployed, regardless of if they have already been deployed, but you can also choose to only deploy packages that have not already been deployed by using the --resume flag

As an example: uds deploy uds-bundle-<name>.tar.zst --resume

Bundle Inspect

Inspect the uds-bundle.yaml of a bundle

1. From an OCI registry: uds inspect oci://ghcr.io/defenseunicorns/dev/<name>:<tag>
2. From your local filesystem: uds inspect uds-bundle-<name>.tar.zst

Viewing Images in a Bundle

It is possible to derive images from a uds-bundle.yaml. This can be useful for situations where you need to know what images will be bundled before you actually create the bundle. This is accomplished with the --list-images flag. For example:

uds inspect ./uds-bundle.yaml --list-images

This command will return a list of images derived from the bundle’s packages, taking into account optional and required package components.

Viewing SBOMs

There are 2 additional flags for the uds inspect command you can use to extract and view SBOMs:

• Output the SBOMs as a tar file: uds inspect ... --sbom
• Output SBOMs into a directory as files: uds inspect ... --sbom --extract

This functionality will use the sboms.tar of the underlying Zarf packages to create new a bundle-sboms.tar artifact containing all SBOMs from the Zarf packages in the bundle.

Bundle Publish

Local bundles can be published to an OCI registry like so: uds publish <bundle>.tar.zst oci://<registry>

As an example: uds publish uds-bundle-example-arm64-0.0.1.tar.zst oci://ghcr.io/github_user

Bundle Remove

Removes the bundle

There are 2 ways to remove Bundles:

1. From an OCI registry: uds remove oci://ghcr.io/defenseunicorns/dev/<name>:<tag> --confirm
2. From your local filesystem: uds remove uds-bundle-<name>.tar.zst --confirm

By default all the packages in the bundle are removed, but you can also remove only certain packages in the bundle by using the --packages flag.

As an example: uds remove uds-bundle-<name>.tar.zst --packages init,nginx

Logs

The uds logs command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available.

Bundle Architecture and Multi-Arch Support

There are several ways to specify the architecture of a bundle according to the following precedence:

1. Setting --architecture or -a flag during uds ... operations: uds create <dir> --architecture arm64
2. Setting a UDS_ARCHITECTURE environment variable
3. Setting the options.architecture key in a uds-config.yaml
4. Setting the metadata.architecture key in a uds-bundle.yaml

This means that setting the --architecture flag takes precedence over all other methods of specifying the architecture.

UDS CLI supports multi-arch bundles. This means you can push bundles with different architectures to the same remote OCI repository, at the same tag. For example, you can push both an amd64 and arm64 bundle to ghcr.io/<org>/<bundle name>:0.0.1.

Architecture Validation

When deploying a local bundle, the bundle’s architecture will be used for comparison against the cluster architecture to ensure compatibility. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster.

If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specifying the arch with the command line architecture flag.

e.g. uds deploy -a amd64 <remote-multi-arch-bundle.tar.zst> --confirm

Variables and Configuration

The UDS CLI can be configured with a uds-config.yaml file. This file can be placed in the current working directory or specified with an environment variable called UDS_CONFIG. The basic structure of the uds-config.yaml is as follows:

options:
   log_level: debug
   architecture: arm64
   no_log_file: false
   no_progress: false
   uds_cache: /tmp/uds-cache
   tmp_dir: /tmp/tmp_dir
   insecure: false
   oci_concurrency: 3

shared:
   domain: uds.dev # shared across all packages in a bundle

variables:
  my-zarf-package:  # name of Zarf package
    ui_color: green # key is not case sensitive and refers to name of Zarf variable
    UI_MSG: "Hello Unicorn"
    hosts:          # variables can be complex types such as lists and maps
       - host: burning.boats
         paths:
            - path: "/"
              pathType: "Prefix"

The options key contains UDS CLI options that are not specific to a particular Zarf package. The variables key contains variables that are specific to a particular Zarf package. If you want to share insensitive variables across multiple Zarf packages, you can use the shared key, where the key is the variable name and the value is the variable value.

Sharing Variables

Zarf package variables can be passed between Zarf packages:

kind: UDSBundle
metadata:
  name: simple-vars
  description: show how vars work
  version: 0.0.1

packages:
  - name: output-var
    repository: localhost:888/output-var
    ref: 0.0.1
    exports:
      - name: OUTPUT
  - name: receive-var
    repository: localhost:888/receive-var
    ref: 0.0.1
    imports:
      - name: OUTPUT
        package: output-var

Variables that you want to make available to other packages are in the export block of the Zarf package to export a variable from. By default, all exported variables are available to all of the packages in a bundle. To have another package ingest a specific exported variable, like in the case of variable name collisions, use the imports key to name both the variable and package that the variable is exported from, like in the example above.

In the example above, the OUTPUT variable is created as part of a Zarf Action in the output-var package, and the receive-var package expects a variable called OUTPUT.

Sharing Variables Across Multiple Packages

If a Zarf variable has the same name in multiple packages and you don’t want to set it multiple times via the import/export syntax, you can set an environment variable prefixed with UDS_ and it will be applied to all the Zarf packages in a bundle. For example, if multiple packages require a DOMAIN variable, you could set it once with a UDS_DOMAIN environment variable and it would be applied to all packages. Note that this can also be done with the shared key in the uds-config.yaml file.

On deploy, you can also set package variables by using the --set flag. If the package name isn’t included in the key (example: --set super=true) the variable will get applied to all of the packages. If the package name is included in the key (example: --set cool-package.super=true) the variable will only get applied to that package.

Variable Precedence and Specificity

In a bundle, variables can come from 4 sources. Those sources and their precedence are shown below in order of least to most specificity:

• Variables declared in a Zarf pkg
• Variables import‘ed from a bundle package’s export
• Variables configured in the shared key in a uds-config.yaml
• Variables configured in the variables key in a uds-config.yaml
• Variables set with an environment variable prefixed with UDS_ (ex. UDS_OUTPUT)
• Variables set using the --set flag when running the uds deploy command

That is to say, variables set using the --set flag take precedence over all other variable sources.

Duplicate Packages And Naming

It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following uds-bundle.yaml deploys 3 instances of the helm-overrides Zarf packages:

kind: UDSBundle
metadata:
   name: duplicates
   description: testing a bundle with duplicate packages in specified namespaces
   version: 0.0.1

packages:
   - name: helm-overrides
     repository: localhost:5000/helm-overrides
     ref: 0.0.1
     overrides:
        podinfo-component:
           unicorn-podinfo: # name of Helm chart
              namespace: podinfo-ns

   # note the unique name and namespace
   - name: helm-overrides-duplicate
     repository: localhost:5000/helm-overrides
     ref: 0.0.1
     overrides:
        podinfo-component:
           unicorn-podinfo:
              namespace: another-podinfo-ns

   # note the unique name, namespace and the path to the Zarf package tarball
   - name: helm-overrides-local-duplicate
     path: src/test/packages/helm/zarf-package-helm-overrides-arm64-0.0.1.tar.zst
     ref: 0.0.1
     overrides:
        podinfo-component:
           unicorn-podinfo:
              namespace: yet-another-podinfo-ns

The naming conventions for deploying duplicate packages are as follows:

1. The name field of the package in the uds-bundle.yaml must be unique
2. The duplicate packages must be deployed in different namespaces
3. In order to deploy duplicates of local packages, the path field must point to a Zarf package tarball instead of to a folder.

Zarf Integration

UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run uds zarf <command>. For example, to create a Zarf package, run uds zarf create <dir>, or to use the airgap tooling that Zarf provides, run uds zarf tools <cmd>.

Dev Mode

Dev mode facilitates faster dev cycles when developing and testing bundles

uds dev deploy <path-to-bundle-yaml-dir> | <oci-ref>

The dev deploy command performs the following operations:

• Deploys the bundle in YOLO mode, eliminating the need to do a zarf init
  • Any kind: ZarfInitConfig packages in the bundle will be ignored
• For local bundles:
  • For local packages:
    • Creates the Zarf tarball if one does not already exist or the --force-create flag can be used to force the creation of a new Zarf package
      • The Zarf tarball is created in the same directory as the zarf.yaml
      • The --flavor flag can be used to specify what flavor of a package you want to create (example: --flavor podinfo=upstream to specify the flavor for the podinfo package or --flavor upstream to specify the flavor for all the packages in the bundle)
  • For remote packages:
    • The --ref flag can be used to specify what package ref you want to deploy (example: --ref podinfo=0.2.0)
  • Creates a bundle from the newly created Zarf packages

Monitor

UDS CLI provides a uds monitor command that can be used to monitor the status of a UDS cluster

Monitor Pepr

To monitor the status of a UDS cluster’s admission and operator controllers, run: uds monitor pepr

UDS Controllers

UDS clusters contain two Kubernetes controllers, both created using Pepr:

1. Admission Controller: Corresponds to the pepr-uds-core pods in the cluster. This controller is responsible for validating and mutating resources in the cluster including the enforcement of UDS Exemptions.

2. Operator Controller: Corresponds to the pepr-uds-core-watcher pods. This controller is responsible for managing the lifecyle of UDS Package resources in the cluster.

Monitor Args

Aggregate all admission and operator logs into a single stream:

uds monitor pepr

Stream UDS Operator actions (UDS Package processing, status updates, and errors):

uds monitor pepr operator

Stream UDS Policy logs (Allow, Deny, Mutate):

uds monitor pepr policies

Stream UDS Policy allow logs:

uds monitor pepr allowed

Stream UDS Policy deny logs:

uds monitor pepr denied

Stream UDS Policy mutation logs:

uds monitor pepr mutated

Stream UDS Policy deny logs and UDS Operator error logs:
uds monitor pepr failed

Monitor Flags

-f, --follow Continuously stream Pepr logs

--json Return the raw JSON output of the logs `` `–since duration Only return logs newer than a relative duration like 5s, 2m, or 3h. Defaults to all logs.

-t, --timestamps Show timestamps in Pepr log

Scan

> Scan is an ALPHA feature.

The scan command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA.

Usage

To use the scan command, run:

uds scan --org <organization> --package-name <package-name> --tag <tag> [options]

Required Parameters

• --org or -o: Organization name (default: defenseunicorns)
• --package-name or -n: Name of the package (e.g., packages/uds/gitlab-runner)
• --tag or -g: Tag name (e.g., 16.10.0-uds.0-upstream)
• --output-file or -f: Output file for CSV results

Optional Parameters

• --docker-username or -u: Docker username for registry access, accepts CSV values
• --docker-password or -p: Docker password for registry access, accepts CSV values

Example Usage

uds scan -o defenseunicorns -n packages/uds/gitlab-runner -g 16.10.0-uds.0-upstream -u docker-username -p docker-password -f gitlab-runner.csv

2 - UDS Runner

UDS CLI contains vendors and configures the maru-runner build tool to make compiling and building UDS bundles simple.

Quickstart

Running a Task

To run a task from a tasks.yaml:

uds run <task-name>

Running a Task from a specific tasks file

uds run -f <path/to/tasks.yaml> <task-name>

The Maru docs describe how to build tasks.yaml files to configure the runner. The functionality in UDS CLI is mostly identical with the following exceptions

Variables Set with Environment Variables

When running a tasks.yaml with uds run my-task you can set variables using environment prefixed with UDS_

For example, running UDS_FOO=bar uds run echo-foo on the following task will echo bar.

variables:
 - name: FOO
   default: foo
tasks:
 - name: echo-foo
   actions:
     - cmd: echo ${FOO}

Running UDS and Zarf Commands

To run uds commands from within a task, you can invoke your system uds binary using the ./uds syntax. Similarly, UDS CLI vendors Zarf, and tasks can run vendored Zarf commands using ./zarf. For example:

tasks:
- name: default
  actions:
    - cmd: ./uds inspect k3d-core-istio-dev:0.16.1 # uses system uds
    - cmd: ./zarf tools kubectl get pods -A        # uses vendored Zarf

Architecture Environment Variable

When running tasks with uds run, there is a special UDS_ARCH environment variable accessible within tasks that is automatically set to your system architecture, but is also configurable with a UDS_ARCHITECTURE environmental variable. For example:

tasks:
- name: print-arch
  actions:
    - cmd: echo ${UDS_ARCH}

• Running uds run print-arch will echo your local system architecture
• Running UDS_ARCHITECTURE=amd64 uds run print-arch will echo “amd64”

No Dependency on Zarf

Since UDS CLI also vendors Zarf, there is no need to also have Zarf installed on your system.

3 - Bundle Overrides

Bundle overrides provide a mechanism to customize Helm charts inside of Zarf packages.

Quickstart

Consider the following zarf.yaml and values.yaml which deploys podinfo with a couple of custom values:

# zarf.yaml
kind: ZarfPackageConfig
metadata:
  name: helm-overrides-package
  version: 0.0.1

components:
  - name: helm-overrides-component
    required: true
    charts:
      - name: podinfo
        version: 6.4.0
        namespace: podinfo
        url: https://github.com/stefanprodan/podinfo.git
        gitPath: charts/podinfo
        valuesFiles:
          - values.yaml
    images:
      - ghcr.io/stefanprodan/podinfo:6.4.0
---
# values.yaml
replicaCount: 1
ui:
  color: blue

The bundle overrides feature allows users to override the values specified in Zarf packages. For example:

kind: UDSBundle
metadata:
  name: helm-overrides
  description: testing a bundle with Helm overrides
  version: 0.0.1

packages:
  - name: helm-overrides-package
    path: "path/to/pkg"
    ref: 0.0.1

    overrides:
      helm-overrides-component:
        podinfo:
          valuesFiles:
            - values.yaml
          values:
            - path: "replicaCount"
              value: 2
          variables:
            - name: UI_COLOR
              path: "ui.color"
              description: "Set the color for podinfo's UI"
              default: "purple"

#values.yaml
podAnnotations:
  customAnnotation: "customValue"

This bundle will deploy the helm-overrides-package Zarf package and override the replicaCount, ui.color, and podAnnotations values in the podinfo chart. The values can’t be modified after the bundle has been created. However, at deploy time, users can override the UI_COLOR and other variables using a environment variable called UDS_UI_COLOR or by specifying it in a uds-config.yaml like so:

variables:
 helm-overrides-package:
   UI_COLOR: green

Overrides

Syntax

Consider the following bundle overrides:

packages:
  - name: helm-overrides-package
    path: "path/to/pkg"
    ref: 0.0.1

    overrides:
      helm-overrides-component: # component name inside of the helm-overrides-package Zarf pkg
        podinfo:                # chart name from the helm-overrides-component component
          valuesFiles:
            - values.yaml
          values:
            - path: "replicaCount"
              value: 2
          variables:
            - name: UI_COLOR
              path: "ui.color"
              description: "Set the color for podinfo's UI"
              default: "purple"

#values.yaml
podAnnotations:
  customAnnotation: "customValue"

In this example, the helm-overrides-package Zarf package has a component called helm-overrides-component which contains a Helm chart called podinfo; note how these names are keys in the overrides block. The podinfo chart has a replicaCount value that is overridden to 2, a podAnnotations value that is overridden to include customAnnotation: "customValue" and a variable called UI_COLOR that is overridden to purple.

Values Files

The valuesFiles in an overrides block are a list of file’s. It allows users to override multiple values in a Zarf package component’s underlying Helm chart, by providing a file with those values instead of having to include them all individually in the overrides block.

Values

The values in an overrides block are a list of path and value pairs. They allow users to override values in a Zarf package component’s underlying Helm chart. Note that values are specified by bundle authors and cannot be modified after the bundle has been created.

Path

The path uses dot notation to specify the location of a value to override in the underlying Helm chart. For example, the replicaCount path in the podinfo chart is located at the top-level of the podinfo values.yaml, so the path is simply replicaCount, while the ui.color path is located under the ui key, so the path is ui.color.

Value

The value is the value to set at the path. Values can be simple values such as numbers and strings, as well as, complex lists and objects, for example:

...
    overrides:
      helm-overrides-component:
        podinfo:
          values:
            - path: "podinfo.tolerations"
              value:
                - key: "unicorn"
                  operator: "Equal"
                  value: "defense"
                  effect: "NoSchedule"
            - path: podinfo.podAnnotations
              value:
                customAnnotation: "customValue"

Bundle Variables as Values

Bundle and Zarf variables can be used to set override values by using the syntax ${...}. For example:

# uds-config.yaml
variables:
  helm-overrides-package:
    replica_count: 2

kind: UDSBundle
metadata:
  name: example-bundle
  description: Example for using an imported variable to set an overrides value
  version: 0.0.1

packages:
  - name: output-var
    repository: localhost:888/output-var
    ref: 0.0.1
    exports:
      - name: COLOR

  - name: helm-overrides-package
    path: "../../packages/helm"
    ref: 0.0.1

    overrides:
      podinfo-component:
        unicorn-podinfo:
          values:
            - path: "podinfo.replicaCount"
              value: ${REPLICA_COUNT}
            - path: "podinfo.ui.color"
              value: ${COLOR}

In the example above ${REPLICA_COUNT} is set in the uds-config.yaml file and ${COLOR} is set as an export from the output-var package. Note that you could also set these values with the shared key in a uds-config.yaml, environment variables prefixed with UDS_ or with the --set flag during deployment.

Value Precedence

Value precedence is as follows:

1. The values in an overrides block
2. values set in the last valuesFile (if more than one specified)
3. values set in the previous valuesFile (if more than one specified)

Variables

Variables are similar to values in that they allow users to override values in a Zarf package component’s underlying Helm chart; they also share a similar syntax. However, unlike values, variables can be overridden at deploy time. For example, consider the variables key in the following uds-bundle.yaml:

kind: UDSBundle
metadata:
   name: example-bundle
   version: 0.0.1

packages:
   - name: helm-overrides-package
     path: "../../packages/helm"
     ref: 0.0.1"
     overrides:
        podinfo-component:
          unicorn-podinfo:
           variables:
           - name: UI_COLOR
             path: "ui.color"
             description: "Set the color for podinfo's UI"
             default: "purple"

There are 3 ways to override the UI_COLOR variable:

1. UDS config: you can create a uds-config.yaml file in the same directory as the bundle and specify the variable to override. For example, to override the UI_COLOR variable, you can create a uds-config.yaml:

     variables:
       helm-overrides-package:
         ui_color: green # Note that the variable for `UI_COLOR` can be upper or lowercase
   

2. Environment variables: you can create an environment variable prefixed with UDS_ and the name of the variable. For example, to override the UI_COLOR variable, you can create an environment variable called UDS_UI_COLOR and set it to the desired value. Note that environment variables take precedence over uds-config.yaml variables.

3. –set Flag: you can also override the variable using the CLI’s --set flag. For example, to override the UI_COLOR variable, you can run one of the following commands:

   # by default ui_color will apply to all packages in the bundle
   uds deploy example-bundle --set ui_color=green
   
   # to specify a specific package that the variable should apply to you can prepend th package name to the variable
   uds deploy example-bundle --set helm-overrides-package.ui_color=green
   

   :warning: Warning: Because Helm override variables and Zarf variables share the same –set syntax, be careful with variable names to avoid conflicts.

Variable Precedence

Variable precedence is as follows:

1. The --set flag
2. Environment variables
3. uds-config.yaml variables
4. Variables default in theuds-bundle.yaml

Variable Types

Variables can be of either type raw or file. The type will default to raw if not set explicitly.

kind: UDSBundle
metadata:
   name: example-bundle
   version: 0.0.1

packages:
   - name: helm-overrides-package
     path: "../../packages/helm"
     ref: 0.0.1
     overrides:
        podinfo-component:
          unicorn-podinfo:
           variables:
           - name: UI_COLOR
             path: "ui.color"
             description: "variable UI_COLOR accepts a raw value (e.g. a string, int, map) like "purple", which is passed to the ui.color helm path"
             type: raw
           - name: test_secret
             path: "testSecret"
             description: "variable TEST_SECRET will resolve to the contents of a file (e.g. test.cert), which gets passed to the testSecret helm path"
             type: file

File Paths

If a file path is not absolute, it will be set as relative to the uds-config.yaml directory.

e.g. the following uds-config.yaml is in src/test/bundles/07-helm-overrides/variable-files/

variables:
  helm-overrides:
    test_secret: test.cert

This means when test.cert is evaluated it will first be appended to the config path like so src/test/bundles/07-helm-overrides/variable-files/test.cert.

If the file path is already set to the same relative path as the config, then no merging will take place.

Namespace

It’s also possible to specify a namespace for a packaged Helm chart to be installed in. For example, to deploy the a chart in the custom-podinfo namespace, you can specify the namespace in the overrides block:

kind: UDSBundle
metadata:
   name: example-bundle
   version: 0.0.1

packages:
   - name: helm-overrides-package
     path: "../../packages/helm"
     ref: 0.0.1
     overrides:
        podinfo-component:
          unicorn-podinfo:
             namespace: custom-podinfo # custom namespace!
             values:
                - path: "podinfo.replicaCount"
                  value: 1

4 - Bundle Anatomy

Bundle Anatomy

A UDS Bundle is an OCI artifact with the following form: