tibschemad Command-Line Reference

The Schema Repository executable is installed in TIBCO_HOME/akd/repo/bin/.

The tibschemad command starts the Schema Repository component of TIBCO® Messaging - Apache Kafka Distribution.

Usage: tibschemad [flags]

tibschmad Flags

-backup string

Back up the schema database to a file

Use the file name "-" to send the backup to stdout.

-c string

Path to a JSON configuration file

Command-line arguments override environment variables, which override configuration file arguments.

When absent, the Schema Repository first looks for ./.tibschemad, then ~/.tibschemad.

-compat string

Set compatibility level.

• strict (default) - Set to strict to guarantee compatibility with other TIBCO products and libraries.

• loose - Set to loose to relax requirements on client requests and attempt to accommodate a wider range of third-party tools.

-config string

Path to a JSON configuration file

Command-line arguments override environment variables, which override configuration file arguments. When absent, the repository first looks for ./.tibschemad, and then ~/.tibschemad.

-debug

When present, print debugging information.

-env

The repository prints the environment variables that would produce its current configuration and exits.

-force

Use with -restore to replace all existing schema data.

-ftl string

Pipe-delimited list of TIBCO FTL server URLs.

The default is http://localhost:31500.

-init-cluster string

Initialize an TIBCO FTL persistence cluster of the given size for use by the Schema Repository.

-l string

The repository listens for requests at this interface and port.

The default is localhost:31519.

-listen string

The repository listens for requests at this interface and port.

The default is localhost:31519.

-origins-allowed string

A comma-separated list of origins allowed for cross-origin resource sharing (CORS).

A value of "*" allows all origins. When absent, no origins other than the server itself are allowed access to the server's resources.

-p string

The repository authenticates itself to the realm server with this password. Supply one of the following forms:

stdin | env:<environment_variable_name> |

file:<password_file_path> | pass:<password>

For details, see the Password Security section.

-password string

The repository authenticates itself to the realm server with this password. Supply one of the following forms:

stdin | env:<environment_variable_name> |

file:<password_file_path> | pass:<password>

For details, see the Password Security section.

-q

When present, the Schema Repository prints minimal output.

-quiet

When present, the Schema Repository prints minimal output.

-readonly

When enabled, the schema repository functions in read-only mode. Any operations that would modify either schema data or configuration is disallowed regardless of user permissions.

Read operations (schema lookups, and so on) are still allowed subject to user permissions.

For details, see the Readonly section.

-restore string

Restore the database from a file.

Use the file name "-" to read the database from stdin.

-show-config

The repository prints the contents of a configuration file that would produce its current configuration and exits.

-store string

Type of backing store to use.

Choices are "ftlrealm", "ftlkv", or "memory". The default is "ftlkv".

-tls-minimum-version string

Minimum allowed TLS protocol version for clients connecting to the schema repository.

Choices are "1.0", "1.1", "1.2", or "1.3".

Newer protocol versions than the minimum are allowed, but older protocols are not allowed.

-trust-everyone

The repository trusts any realm server without verifying the trust in the realm server's certificate.

Caution: Do not use this parameter except for convenience in development and testing. It is not secure.

-trust-file string

Required only for TLS communication with a secure realm server.

When present, the repository process reads a trust file from this path, and uses that trust data in communications with the secure realm server.

For more information about security, see the TIBCO FTL® Security guide.

-user string

Username for authentication.

The repository authenticates itself to the realm server with this username.

-v

When present, the repository prints verbose output.

-validators string

A comma-separated list of external schema validator tools to invoke when a new schema for a matching subject is registered. For example, to register an external validator tool for all subjects that begin with 'foo', specify:

-validators 'foo*=python -m jsonsubschema.cli'
Basic wildcard syntax is supported for subject names.

Note: When using JSON schemas, to check for forward or backward compatibility of the schema, configure an external validator. If it is not configured, by default the schema repository rejects all new versions of a JSON schema for a given subject. TIBCO recommends using the jsonsubschema.cli tool that you can install by using pip install jsonsubschema.

When the schema repository receives a request to register a new schema or version of a schema under a subject that matches a configured validator's subject pattern, the schema repository invokes the validator with two arguments, the path to a temporary file containing the current version of the schema and the path to a temporary file containing the proposed new version of the schema. For example, if -validators 'foo*=python -m jsonsubschema.cli' is set, when an attempt is made to register a new version of a schema under the subject "foobaz", the schema repository invokes the validator as:

python -m jsonsubschema.cli /tmp/existingN25Mx /tmp/proposed8ZrQ

where /tmp/existingN25Mx and /tmp/proposed8ZrQ are randomly-named temporary files containing the current and the newly proposed schemas, respectively. If the validator returns a 0 exit code or the last line of its output in stdout and it contains true, the proposed new schema is considered valid and is accepted. If the validator returns a non-0 exit code or the last line of its output in stdout contains false, the proposed new schema is considered invalid and is rejected.

In addition to backward or forward compatibility checking, a validator can also implement custom validation logic, schema style checking, and so on.

Warning: Validators are run as the same user, with the same permissions, as the schema repository itself.

-verbose

When present, the repository prints verbose output.

-version

When present, the repository outputs version information and exits.

-X DELETE

A soft delete of a schema only deletes the version. The underlying schema ID is still available for lookup.

curl -X DELETE "https://localhost:8081/schema/v1/subjects/company-two" -H "accept: application/json"

-X DELETE and ?permanent=true

A hard delete of a schema removes all metadata, including the schema ID. You can hard delete all schema versions registered under a subject or on a specific version of a subject. To perform a hard delete, you must soft delete the schema then hard delete the schema.

curl -X DELETE "https://localhost:8081/schema/v1/subjects/company-two" -H "accept: application/json"

curl -X DELETE "https://localhost:8081/schema/v1/subjects/company-two?permanent=true" -H "accept: application/json"

To hard delete version 1 of a schema registered under the subject "time-value".

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/time-value/versions/1

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/time-value/versions/1/?permanent=true

To hard delete all versions of a schema under the subject "time-value".

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/time-value

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/time-value?permanent=true

Readonly

-readonly

When run without the -readonly command-line option, schemas may be created, modified, or deleted if the user provides appropriate credentials. With this command-line option, no modifications including new schemas, modifications to existing schemas, or schema deletions are possible regardless of the credentials provided by the user.

Use of this option allows the pre-loading of schemas when using the default settings of the Schema Repository. A subsequent restart of the Schema Repository with the read-only option prevents any schema modifications during subsequent operation regardless of the credentials provided by the user.

Credential Handling Details

If a request is passed directly to the Schema Repository (not going through the TIBCO FTL Server), any passed credentials are validated at the TIBCO FTL Server, and the Schema Repository prevents any actions that would modify its contents unless the user supplies writeable credentials. Because the Schema Repository is doing the credential evaluation in the context of the REST request, non-modifying POST requests work even with read-only credentials.

Use

To use this authorization approach, the applications should specify the URLs of the Schema Repository instead of the URLs of the TIBCO FTL Server. This does not impact high availability as the user can run multiple Schema Repositories and the applications automatically switch to another Schema Repository instance, as required.

bin/tibschemad -ftl https://localhost:13131 -trust-file /path/to/ftl-server/srv1/ftl-trust.pem -u admin -p pass:admin-pw -l localhost:9696 -readonly

Once the read only flag is set, only authorized users are able to make changes to the database. If an unauthorized user tries to modify the schema, they get the following error:

{"error_code":42205,"message":"Repository is in read-only mode"}

Steps to Start

1. Start the Schema Repository with the default setting.

2. Pre-load a schema.

3. Restart the Schema Repository with the read-only setting.

Steps if a Schema Needs to be Updated

1. Restart the Schema Repository with the default setting.

2. Update the schema.

3. Restart the Schema Repository with the read-only setting.

Note: If the read-only setting is stopping misbehaving applications with modify credentials from making schema updates, you may need to stop other applications during the maintenance window.