Command-Line Tools

The package installs the following command-line tools.

Service Commands

dump-things-service

Start the Dump Things Service.

dump-things-service [OPTIONS] <storage-root>

Arguments

<storage-root>

(Mandatory) Path to the directory used as anchor for all relative paths in the configuration.

Options

--host <IP-address>

IP address on which the service should accept connections. Default: 0.0.0.0.

--port <port>

Port on which the service should accept connections. Default: 8000.

-c, --config <config-file>

Path to a configuration file. If no persisted configuration is found in the data store, the service is initialized with the content of this file. Useful for migrating from service version <= 5 to version 6.

--origins <origin>

Add a CORS origin host. Repeat to add multiple CORS origin URLs.

--root-path <path>

Set the ASGI root_path for applications mounted below a given URL path.

--log-level <LEVEL>

Log level. Allowed values: ERROR, WARNING, INFO, DEBUG. Default: WARNING.

--admin-token-hash <sha256-hex>

Set an administrator token hash (64-digit hexadecimal SHA-256 hash of the plain-text token). If not provided, a plain-text token is read from the environment variable DTS_ADMIN_TOKEN, if it is set.

--ignore-default-config-file

If set, the service will not try to initialize itself from the default configuration file <storage-root>/.dumpthings.yaml. Otherwise, if no persisted configuration is found in the data store (and -c/--config is not provided), the service will read its initial configuration from <storage-root>/.dumpthings.yaml if it exists.

Example

dump-things-service /data/store --host 127.0.0.1 --port 8000

Configuration Tools

dump-things-upload-config

Read a configuration from a dump-things configuration-file and instantiate its elements on a running server via the administration endpoints. Objects that already exist on the server are left unchanged.

An admin token has to be provided in the environment variable DTS_ADMIN_TOKEN.

dump-things-upload-config [OPTIONS] <config-file (json or YAML)>

Options

--server <URL>

Base URL of the running service (e.g. http://127.0.0.1:8000).

--format [{json,yaml}], -f [{json,yaml}]

Specify the format of the input file. Possible values are json and yaml. If this option is given, the suffix of the configuration file is ignored.

--send-to SEND_TO

The base URL of the server API. If this option is provided, the configuration will be sent to the server API, otherwise it will just be written to stdout.

--old-format

If provided, assume that the configuration is in version 1 format and convert it to the new format internally (in version 1: tokens had no hashed-attribute and no representation-attribute, the token representation was the key of the token configuration, collections had no schema-attribute, and sqlite-backends had a schema-attribute).

--store STORE

If –old-format is provided, this option can be used to specify a store directory. The store directory will be used to load RecordDir configurations, if a collection defines are RecordDir-backend. (This option has no effect if no collection in the old configuration uses a RecordDir-backend.)

dump-things-download-config

Read the current configuration from a running service and write it to a file.

An admin token has to be provided in the environment variable DTS_ADMIN_TOKEN.

dump-things-download-config [OPTIONS] <server API URL>

Options

--entities {admin_tokens,collections,tokens}, -e {admin_tokens,collections,tokens}

Specify for which entities the configuration should be downloaded. Possible values are admin_tokens, collections, or tokens (repeat to download configuration for more than one entity). If this option is not provided, configurations for all entities will be downloaded.

--format [{json,yaml}], -f [{json,yaml}]

Specify the format of the output. Possible values are json and yaml (the default is yaml).

dump-things-hash-token

Compute the SHA-256 hash of a plain-text token for use with --admin-token-hash or as representation-value in a configuration object (file)

dump-things-hash-token <plain-text-token>

Maintenance Tools

dump-things-pid-check

Check all PIDs in a store to verify they can be resolved (useful after schema changes that affect prefix definitions).

dump-things-pid-check <path-to-store>

Audit Tools

dump-things-gitaudit-report

Report the audit information that was stored for all PIDs matching a pattern. For every change to a record the tool will report: time stamp, user ID, diff, and the resulting record.

dump-things-gitaudit-report <path-to-audit-dir> <pid-pattern>

<pid-pattern> is a Python re-module pattern that identifies PIDs of the record for which audit information should be reported. Use '.*' to report changes for all PIDs.

Each log entry contains:

• Timestamp of the change.

• Curator ID.

• Diff of the change.

• The resulting record.

dump-things-gitaudit-rebuild-index

Rebuild the index for a gitaudit backend. Normally not required in regular operations; useful for maintenance.

dump-things-gitaudit-rebuild-index <path-to-audit-dir>