ICATINGEST(1)

NAME
icatingest - Restore the content of the ICAT from a dump file

SYNOPSIS

icatingest [standard options] [-i FILE] [-f FORMAT] [--upload-datafiles] [--datafile-dir DATADIR] [--duplicate OPTION]

DESCRIPTION

This script reads an ICAT data file and creates all objects found in an ICAT server. The format of that file depends on the backend that can be selected with the --format option.

OPTIONS

The configuration options may be set in the command line or in a configuration file. Some options may also be set in the environment.

  Specific Options

The following options are specific to icatingest:

-i FILE, --inputfile FILE
    Set the input file name. If the value - is used, the input will be read from standard input. This is also the default.

-f FORMAT, --format FORMAT
    Select the backend to use and thus the input file format. XML and YAML backends are available.

--upload-datafiles
    If that flag is set, Datafile objects will not be created in the ICAT server directly, but a corresponding file will be uploaded to IDS instead.

--datafile-dir DATADIR
    Directory to search for the files to be uploaded to IDS. This is only relevant if --upload-datafiles is set. The default is the current working directory.

--duplicate OPTION
    Set the behavior in the case that any object read from the input already exists in the ICAT server. Valid options are:

THROW
    Throw an error. This is the default.

IGNORE
    Skip the object read from the input.

CHECK
    Compare all attributes from the input object with the already existing object in ICAT. Throw an error of any attribute differs.

OVERWRITE
    Overwrite the existing object in ICAT, e.g. update it with all attributes set to the values found in the input object.

    If --upload-datafiles is set, this option will be ignored for Datafile objects which will then always raise an error if they already exist.

  Standard Options

The following options needed to connect the ICAT service are common for most python-icat scripts:

-h, --help
    Display a help message and exit.

-c CONFIGFILE, --configfile CONFIGFILE
    Name of a configuration file.

-s SECTION, --configsection SECTION
    Name of a section in the configuration file. If set, the values in this configuration section will be applied to define other options.

-w URL, --url URL
    URL of the ICAT server. This should point to the web service descriptions. If the URL has no path component, a default path will be added.

--idsurl URL
    URL of the IDS server. This is only relevant if --upload-datafiles is set. If the URL has no path component, a default path will be added.

--no-check-certificate
    Do not verify the ICAT server's TLS certificate. This is only relevant if the URL set with --url or --idsurl uses HTTPS. It is mostly only useful for connecting a test server that does not have a trusted certificate.

--http-proxy HTTP_PROXY
    Proxy to use for http requests.

--https-proxy HTTPS_PROXY
    Proxy to use for https requests.

--no-proxy NO_PROXY
    Comma separated list of exclusions for proxy use.

-a AUTH, --auth AUTH
    Name of the authentication plugin to use for login to the ICAT server.

-u USERNAME, --user USERNAME
    The ICAT user name.

-p PASSWORD, --pass PASSWORD
    The user's password. Will prompt for the password if not set.

-P, --prompt-pass
    Prompt for the password. This is mostly useful to override a password set in the configuration file.

KNOWN ISSUES AND LIMITATIONS

•   The user running this script need to have create permission for all objects in the dump file. In the generic case of restoring the entire content on an empty ICAT server, the script must be run by the ICAT root user.

•   A dump and restore of an ICAT will not preserve the attributes id, createId, createTime, modId, and modTime of any object. As a consequence, access rules that are based on the values of these attributes will not work after a restore.

•   Dealing with duplicates, see --duplicate, is only supported for single objects. If the object contains embedded related objects in one to many relationships that are to be created at once, the only allowed option to deal with duplicates is THROW.

ENVIRONMENT VARIABLES

ICAT_CFG
    Name of a configuration file, see --configfile.

ICAT_CFG_SECTION
    Name of a section in the configuration file, see --configsection.

ICAT_SERVICE
    URL of the ICAT server, see --url.

ICAT_DATA_SERVICE
    URL of the IDS server, see --idsurl.

http_proxy
    Proxy to use for http requests, see --http-proxy.

https_proxy
    Proxy to use for https requests, see --https-proxy.

no_proxy
    Exclusions for proxy use, see --no-proxy.

ICAT_AUTH
    Name of the authentication plugin, see --auth.

ICAT_USER
    ICAT user name, see --user.

SEE ALSO

icatdump(1)

AUTHOR
Rolf Krahl

COPYRIGHT
2013–2021, Helmholtz-Zentrum Berlin für Materialien und Energie GmbH