opa-run - Man Page

Start OPA in interactive or server mode

Synopsis

opa run [flags]

Description

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

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

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/#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/#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.

Options

-a, --addr=[:8181] set listening address of the server (e.g., [ip]: for TCP, unix:// for UNIX domain socket)

--authentication=off set authentication scheme

--authorization=off set authorization scheme

-b, --bundle[=false] load paths as bundle files or root directories

-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]: for TCP, unix:// for UNIX domain socket)

--exclude-files-verify=[] set file names to exclude during bundle verification

-f, --format="pretty" set shell output format, i.e, pretty, json

--h2c[=false] enable H2C for HTTP listeners

-h, --help[=false] help for run

-H, --history="/builddir/.opa_history" set path of history file

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

--log-format=json set log format

-l, --log-level=info set log level

-m, --max-errors=10 set the number of errors to allow before compilation fails early

--min-tls-version=1.2 set minimum TLS version to be used by OPA's server, default is 1.2

--pprof[=false] enables pprof endpoints

--ready-timeout=0 wait (in seconds) for configured plugins before starting server (value <= 0 disables ready check)

--scope="" scope to use for bundle signature verification

-s, --server[=false] start the runtime in server mode

--set=[] override config values on the command line (use commas to specify multiple values)

--set-file=[] override config values with files on the command line (use commas to specify multiple values)

--shutdown-grace-period=10 set the time (in seconds) that the server will wait to gracefully shut down

--shutdown-wait-period=0 set the time (in seconds) that the server will wait before initiating shutdown

--signing-alg="RS256" name of the signing algorithm

--skip-verify[=false] disables bundle signature verification

--skip-version-check[=true] disables anonymous version reporting (see: https://openpolicyagent.org/docs/latest/privacy)

--tls-ca-cert-file="" set path of TLS CA cert file

--tls-cert-file="" set path of TLS certificate file

--tls-private-key-file="" set path of TLS private key file

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

--verification-key-id="default" name assigned to the verification key used for bundle verification

-w, --watch[=false] watch command line files for changes

See Also

opa(1)

Referenced By

opa(1).

Jul 2021