ec opa run

Start OPA in interactive or server mode

Synopsis

Start an instance of the Open Policy Agent (OPA).

To run the interactive shell:

$ opa run

To run the server:

$ opa run -s

The 'run' command starts an instance of the OPA runtime. The OPA runtime can be started as an interactive shell or a server.

When the runtime is started as a shell, users can define rules and evaluate expressions interactively. When the runtime is started as a server, OPA exposes an HTTP API for managing policies, reading and writing data, and executing queries.

The runtime can be initialized with one or more files that contain policies or data. If the '--bundle' option is specified the paths will be treated as policy bundles and loaded following standard bundle conventions. The path can be a compressed archive file or a directory which will be treated as a bundle. Without the '--bundle' flag OPA will recursively load ALL rego, JSON, and YAML files.

When loading from directories, only files with known extensions are considered. The current set of file extensions that OPA will consider are:

.json          # JSON data
.yaml or .yml  # YAML data
.rego          # Rego file

Non-bundle data file and directory paths can be prefixed with the desired destination in the data document with the following syntax:

<dotted-path>:<file-path>

To set a data file as the input document in the interactive shell use the "repl.input" path prefix with the input file:

repl.input:<file-path>

Example:

$ opa run repl.input:input.json

Which will load the "input.json" file at path "data.repl.input".

Use the "help input" command in the interactive shell to see more options.

File paths can be specified as URLs to resolve ambiguity in paths containing colons:

$ opa run file:///c:/path/to/data.json

URL paths to remote public bundles (http or https) will be parsed as shorthand configuration equivalent of using repeated --set flags to accomplish the same:

$ opa run -s https://example.com/bundles/bundle.tar.gz

The above shorthand command is identical to:

$ opa run -s --set "services.cli1.url=https://example.com" \
             --set "bundles.cli1.service=cli1" \
             --set "bundles.cli1.resource=/bundles/bundle.tar.gz" \
             --set "bundles.cli1.persist=true"

The 'run' command can also verify the signature of a signed bundle. A signed bundle is a normal OPA bundle that includes a file named ".signatures.json". For more information on signed bundles see https://www.openpolicyagent.org/docs/latest/management-bundles/#signing.

The key to verify the signature of signed bundle can be provided using the --verification-key flag. For example, for RSA family of algorithms, the command expects a PEM file containing the public key. For HMAC family of algorithms (eg. HS256), the secret can be provided using the --verification-key flag.

The --verification-key-id flag can be used to optionally specify a name for the key provided using the --verification-key flag.

The --signing-alg flag can be used to specify the signing algorithm. The 'run' command uses RS256 (by default) as the signing algorithm.

The --scope flag can be used to specify the scope to use for bundle signature verification.

Example:

$ opa run --verification-key secret --signing-alg HS256 --bundle bundle.tar.gz

The 'run' command will read the bundle "bundle.tar.gz", check the ".signatures.json" file and perform verification using the provided key. An error will be generated if "bundle.tar.gz" does not contain a ".signatures.json" file. For more information on the bundle verification process see https://www.openpolicyagent.org/docs/latest/management-bundles/#signature-verification.

The 'run' command can ONLY be used with the --bundle flag to verify signatures for existing bundle files or directories following the bundle structure.

To skip bundle verification, use the --skip-verify flag.

The --watch flag can be used to monitor policy and data file-system changes. When a change is detected, the updated policy and data is reloaded into OPA. Watching individual files (rather than directories) is generally not recommended as some updates might cause them to be dropped by OPA.

OPA will automatically perform type checking based on a schema inferred from known input documents and report any errors resulting from the schema check. Currently this check is performed on OPA’s Authorization Policy Input document and will be expanded in the future. To disable this, use the --skip-known-schema-check flag.

The --v1-compatible flag can be used to opt-in to OPA features and behaviors that will be enabled by default in a future OPA v1.0 release. Current behaviors enabled by this flag include: - setting OPA’s listening address to "localhost:8181" by default.

The --tls-cipher-suites flag can be used to specify the list of enabled TLS 1.0–1.2 cipher suites. Note that TLS 1.3 cipher suites are not configurable. Following are the supported TLS 1.0 - 1.2 cipher suites (IANA): TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

See https://godoc.org/crypto/tls#pkg-constants for more information.

ec opa run [flags]

Options

-a, --addr

set listening address of the server (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket) (Default: [:8181])

--authentication

set authentication scheme (Default: off)

--authorization

set authorization scheme (Default: off)

-b, --bundle

load paths as bundle files or root directories (Default: false)

-c, --config-file

set path of configuration file

--diagnostic-addr

set read-only diagnostic listening address of the server for /health and /metric APIs (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket) (Default: [])

--disable-telemetry

disables anonymous information reporting (see: https://www.openpolicyagent.org/docs/latest/privacy) (Default: false)

--exclude-files-verify

set file names to exclude during bundle verification (Default: [])

-f, --format

set shell output format, i.e, pretty, json (Default: pretty)

--h2c

enable H2C for HTTP listeners (Default: false)

-h, --help

help for run (Default: false)

-H, --history

set path of history file (Default: $HOME/.opa_history)

--ignore

set file and directory names to ignore during loading (e.g., '.*' excludes hidden files) (Default: [])

--log-format

set log format (Default: json)

-l, --log-level

set log level (Default: info)

--log-timestamp-format

set log timestamp format (OPA_LOG_TIMESTAMP_FORMAT environment variable)

-m, --max-errors

set the number of errors to allow before compilation fails early (Default: 10)

--min-tls-version

set minimum TLS version to be used by OPA’s server (Default: 1.2)

--optimize-store-for-read-speed

optimize default in-memory store for read speed. Has possible negative impact on memory footprint and write speed. See https://www.openpolicyagent.org/docs/latest/policy-performance/#storage-optimization for more details. (Default: false)

--pprof

enables pprof endpoints (Default: false)

--ready-timeout

wait (in seconds) for configured plugins before starting server (value ⇐ 0 disables ready check) (Default: 0)

--scope

scope to use for bundle signature verification

-s, --server

start the runtime in server mode (Default: false)

--set

override config values on the command line (use commas to specify multiple values) (Default: [])

--set-file

override config values with files on the command line (use commas to specify multiple values) (Default: [])

--shutdown-grace-period

set the time (in seconds) that the server will wait to gracefully shut down (Default: 10)

--shutdown-wait-period

set the time (in seconds) that the server will wait before initiating shutdown (Default: 0)

--signing-alg

name of the signing algorithm (Default: RS256)

--skip-known-schema-check

disables type checking on known input schemas (Default: false)

--skip-verify

disables bundle signature verification (Default: false)

--skip-version-check

disables anonymous version reporting (see: https://www.openpolicyagent.org/docs/latest/privacy) (Default: false)

--tls-ca-cert-file

set path of TLS CA cert file

--tls-cert-file

set path of TLS certificate file

--tls-cert-refresh-period

set certificate refresh period (Default: 0s)

--tls-cipher-suites

set list of enabled TLS 1.0–1.2 cipher suites (IANA) (Default: [])

--tls-private-key-file

set path of TLS private key file

--unix-socket-perm

specify the permissions for the Unix domain socket if used to listen for incoming connections (Default: 755)

--v0-compatible

opt-in to OPA features and behaviors prior to the OPA v1.0 release. Takes precedence over --v1-compatible (Default: false)

--v1-compatible

opt-in to OPA features and behaviors that are enabled by default in OPA v1.0 (Default: false)

--verification-key

set the secret (HMAC) or path of the PEM file containing the public key (RSA and ECDSA)

--verification-key-id

name assigned to the verification key used for bundle verification (Default: default)

-w, --watch

watch command line files for changes (Default: false)

Options inherited from parent commands

--debug

same as verbose but also show function names and line numbers (Default: false)

--kubeconfig

path to the Kubernetes config file to use

--logfile

file to write the logging output. If not specified logging output will be written to stderr

--quiet

less verbose output (Default: false)

--timeout

max overall execution duration (Default: 5m0s)

--trace

enable trace logging, set one or more comma separated values: none,all,perf,cpu,mem,opa,log (Default: none)

--verbose

more verbose output (Default: false)

See also