cli-reference

Options

  -X, --attribute stringArray     attribute setting
      --ca-cert stringArray       additional root certificate authorities (for signing certificates)
      --config stringArray        configuration file
      --config-set strings        apply configuration set
  -C, --cred stringArray          credential setting
  -h, --help                      help for ocm
  -I, --issuer stringArray        issuer name or distinguished name (DN) (optionally for dedicated signature) ([<name>:=]<dn>
      --logconfig string          log config
  -L, --logfile string            set log file
      --logkeys stringArray       log tags/realms(with leading /) to be enabled ([/[+]]name{,[/[+]]name}[=level])
  -l, --loglevel string           set log level
  -K, --private-key stringArray   private key setting
  -k, --public-key stringArray    public key setting
  -v, --verbose                   deprecated: enable logrus verbose logging
      --version                   show version

Introduction

The Open Component Model command line client supports the work with OCM artifacts, like Component Archives, Common Transport Archive, Component Repositories, and Component Versions.

Additionally it provides some limited support for the docker daemon, OCI artifacts and registries.

It can be used in two ways:

verb/operation first: here the sub commands follow the pattern <verb> <object kind> <arguments>
area/kind first: here the area and/or object kind is given first followed by the operation according to the pattern [<area>] <object kind> <verb/operation> <arguments>

The command accepts some top level options, they can only be given before the sub commands.

A configuration according to ocm configfile is read from a .ocmconfig file located in the HOME directory. With the option –config other file locations can be specified. If nothing is specified and no file is found at the default location a default configuration is composed according to known type specific configuration files.

The following configuration sources are used:

The docker configuration file at ~/.docker/config.json is read to feed in the configured credentials for OCI registries.
The npm configuration file at ~/.npmrc is read to feed in the configured credentials for NPM registries.

With the option –cred it is possible to specify arbitrary credentials for various environments on the command line. Nevertheless it is always preferrable to use the cli config file. Every credential setting is related to a dedicated consumer and provides a set of credential attributes. All this can be specified by a sequence of –cred options.

Every option value has the format

--cred [:]<attr>=<value>

Consumer identity attributes are prefixed with the colon (:). A credential settings always start with a sequence of at least one identity attributes, followed by a sequence of credential attributes. If a credential attribute is followed by an identity attribute a new credential setting is started.

The first credential setting may omit identity attributes. In this case it is used as default credential, always used if no dedicated match is found.

For example:

--cred :type=OCIRegistry --cred :hostname=ghcr.io --cred username=mandelsoft --cred password=xyz

With the option -X it is possible to pass global settings of the form

-X <attribute>=<value>

The –log* options can be used to configure the logging behaviour. For details see ocm logging.

There is a quick config option –logkeys to configure simple tag/realm based condition rules. The comma-separated names build an AND rule. Hereby, names starting with a slash (/) denote a realm (without the leading slash). A realm is a slash separated sequence of identifiers. If the realm name starts with a plus (+) character the generated rule will match the realm and all its sub-realms, otherwise, only the dedicated realm is affected. For example /+ocm=trace will enable all log output of the OCM library.

A tag directly matches the logging tags. Used tags and realms can be found under topic ocm logging. The ocm coding basically uses the realm ocm. The default level to enable is info. Separated by an equal sign (=) optionally a dedicated level can be specified. Log levels can be (error, warn, info, debug and trace. The default level is warn. The –logconfig* options can be used to configure a complete logging configuration (yaml/json) via command line. If the argument starts with an @, the logging configuration is taken from a file.

The value can be a simple type or a JSON/YAML string for complex values (see ocm attributes. The following attributes are supported:

github.com/mandelsoft/logforward: logconfig Logging config structure used for config forwarding
This attribute is used to specify a logging configuration intended to be forwarded to other tools. (For example: TOI passes this config to the executor)
github.com/mandelsoft/oci/cache [cache]: string
Filesystem folder to use for caching OCI blobs
github.com/mandelsoft/ocm/compat [compat]: bool
Compatibility mode: Avoid generic local access methods and prefer type specific ones.
github.com/mandelsoft/ocm/hasher: JSON
Preferred hash algorithm to calculate resource digests. The following digesters are supported:
- NO-DIGEST
- SHA-256 (default)
- SHA-512
github.com/mandelsoft/ocm/keeplocalblob [keeplocalblob]: bool
Keep local blobs when importing OCI artifacts to OCI registries from localBlob access methods. By default, they will be expanded to OCI artifacts with the access method ociRegistry. If this option is set to true, they will be stored as local blobs, also. The access method will still be localBlob but with a nested ociRegistry access method for describing the global access.
github.com/mandelsoft/ocm/mapocirepo [mapocirepo]: bool|YAML
When uploading an OCI artifact blob to an OCI based OCM repository and the artifact is uploaded as OCI artifact, the repository path part is shortened, either by hashing all but the last repository name part or by executing some prefix based name mappings.
If a boolean is given the short hash or none mode is enabled. The YAML flavor uses the following fields:
- mode string: hash, shortHash, prefixMapping or none. If unset, no mapping is done.
- prefixMappings: map[string]string repository path prefix mapping.
- prefix: string repository prefix to use (replaces potential sub path of OCM repo). or none.
- prefixMapping: map[string]string repository path prefix mapping.
Notes:
- The mapping only occurs in transfer commands and only when transferring to OCI registries (e.g. when transferring to a CTF archive this option will be ignored).
- The mapping only happens for local resources. When external image references are transferred (with option –copy-resources) the mapping will be ignored.
- The mapping in mode prefixMapping requires a full prefix of the composed final name. Partial matches are not supported. The host name of the target will be skipped.
- The artifact name of the component-descriptor is not mapped.
- If the mapping is provided on the command line it must be JSON format and needs to be properly escaped (see example below).
Example:
Assume a component named github.com/my_org/myexamplewithalongname and a chart name echo in the Charts.yaml of the chart archive. The following input to a resource.yaml creates a component version:
```
name: mychart
type: helmChart
input:
  type: helm
  path: charts/mychart.tgz
---
name: myimage
type: ociImage
version: 0.1.0
input:
  type: ociImage
  repository: ocm/ocm.software/ocmcli/ocmcli-image
  path: ghcr.io/acme/ocm/ocm.software/ocmcli/ocmcli-image:0.1.0
```
The following command:
```
ocm "-X mapocirepo={\"mode\":\"mapping\",\"prefixMappings\":{\"acme/github.com/my_org/myexamplewithalongname/ocm/ocm.software/ocmcli\":\"acme/cli\", \"acme/github.com/my_org/myexamplewithalongnameabc123\":\"acme/mychart\"}}" transfer ctf -f --copy-resources ./ctf ghcr.io/acme
```
will result in the following artifacts in ghcr.io/my_org:
```
mychart/echo
cli/ocmcli-image
```
Note that the host name part of the transfer target ghcr.io/acme is excluded from the prefix but the path acme is considered.
The same using a config file .ocmconfig:
```
type: generic.config.ocm.software/v1
configurations:
...
- type: attributes.config.ocm.software
  attributes:
	...
	mapocirepo:
	  mode: mapping
	  prefixMappings:
	    acme/github.com/my\_org/myexamplewithalongname/ocm/ocm.software/ocmcli: acme/cli
		acme/github.com/my\_org/myexamplewithalongnameabc123: acme/mychart
```
```
ocm transfer ca -f --copy-resources ./ca ghcr.io/acme
```
github.com/mandelsoft/ocm/ociuploadrepo [ociuploadrepo]: oci base repository ref
Upload local OCI artifact blobs to a dedicated repository.
github.com/mandelsoft/ocm/plugindir [plugindir]: plugin directory
Directory to look for OCM plugin executables.
github.com/mandelsoft/ocm/rootcerts: JSON
General root certificate settings given as JSON document with the following format:
```
{
  "rootCertificates"": [
     {
       "data": ""<base64>"
     },
     {
       "path": ""<file path>"
     }
  ],
```
One of following data fields are possible:
- data: base64 encoded binary data
- stringdata: plain text data
- path: a file path to read the data from
github.com/mandelsoft/ocm/signing: JSON
Public and private Key settings given as JSON document with the following format:
```
{
  "publicKeys"": [
     "<provider>": {
       "data": ""<base64>"
     }
  ],
  "privateKeys"": [
     "<provider>": {
       "path": ""<file path>"
     }
  ]
```
One of following data fields are possible:
- data: base64 encoded binary data
- stringdata: plain text data
- path: a file path to read the data from
github.com/mandelsoft/tempblobcache [blobcache]: string Foldername for temporary blob cache
The temporary blob cache is used to accessing large blobs from remote sytems. The are temporarily stored in the filesystem, instead of the memory, to avoid blowing up the memory consumption.
ocm.software/compositionmode [compositionmode]: bool (default: false
Composition mode decouples a component version provided by a repository implemention from the backened persistence. Added local blobs will and other changes witll not be forwarded to the backend repository until an AddVersion is called on the component. If composition mode is disabled blobs will directly be forwarded to the backend and descriptor updated will be persisted on AddVersion or closing a provided existing component version.
ocm.software/signing/sigstore [sigstore]: sigstore config Configuration to use for sigstore based signing.
The following fields are used.
- fulcioURL string default is https://v1.fulcio.sigstore.dev
- rekorURL string default is https://rekor.sigstore.dev
- OIDCIssuer string default is https://oauth2.sigstore.dev/auth
- OIDCClientID string default is sigstore

For several options (like -X) it is possible to pass complex values using JSON or YAML syntax. To pass those arguments the escaping of the used shell must be used to pass quotes, commas, curly brackets or newlines. for the bash the easiest way to achieve this is to put the complete value into single quotes.

-X 'mapocirepo={"mode": "shortHash"}'.

Alternatively, quotes and opening curly brackets can be escaped by using a backslash (\). Often a tagged value can also be substituted from a file with the syntax

<attr>=@<filepath>

The –public-key and –private-key options can be used to define public and private keys on the command line. The options have an argument of the form <name>=<filepath>. The name is the name of the key and represents the context is used for (For example the signature name of a component version)

Alternatively a key can be specified as base64 encoded string if the argument start with the prefix ! or as direct string with the prefix =.

With –issuer it is possible to declare expected issuer constraints for public key certificates provided as part of a signature required to accept the provisioned public key (besides the successful validation of the certificate). By default, the issuer constraint is derived from the signature name. If it is not a formal distinguished name, it is assumed to be a plain common name.

With –ca-cert it is possible to define additional root certificates for signature verification, if public keys are provided by a certificate delivered with the signature.

Docs

Open Component Model

Title here

cli-reference

Options

Introduction

See Also

Sub Commands

Additional Help Topics

cli-reference

Options#

Introduction#

See Also#

Sub Commands#

Additional Help Topics#

Options

Introduction

See Also

Sub Commands

Additional Help Topics