Fedora Client Command-Line Utilities

Introduction

The Fedora client distribution comes with several command-line utilities that can be used to run some common operations without bringing up the GUI or writing your own SOAP client. A description and usage instructions for each follows.

This guide assumes you have correctly installed the Fedora client distribution as per the install guide, including having set up your PATH and FEDORA_HOME appropriately. The command-line scripts are located in FEDORA_HOME/client/bin/. In Windows, these commands resolve to batch files (.bat); in Unix, they resolve to shell scripts (.sh).

fedora-dsinfo

fedora-dsinfo [hostname] [port-number] [user] [pass] [pid] [protocol]

Where:

[hostname] - The hostname of the Fedora server; default is localhost.
[port-number] - The port number on which the Fedora server is running; default is 8080.
[user] - The Fedora user (e.g. fedoraAdmin).
[pass] - The Fedora user's password.
[pid] - The pid of the object whose datastream information should be shown.
[protocol] - Is how to connect to repository, either http or https.

Example:

fedora-dsinfo localhost 8080 fedoraAdmin fedoraAdmin demo:5 http
Displays key information about each of an object's datastreams.

fedora-export

fedora-export [HST:PRT] [USR] [PSS] [PID|FTYPS] [FORMAT] [ECONTEXT] [PATH] [PROTOCOL]

Where:

[HST:PRT] - The repository's hostname and the port separated by colon.
[USR] - The id of the repository user.
[PSS] - The password of the repository user.
[PID|FTYPS] - Either the identifier (PID) of the object to export from the repository OR the types of objects to export (FTYPS). FTYPS can be any combination of the characters O, D, and M, specifying which Fedora object type(s) should be exported. O=regular data objects, D=behavior definitions, M=behavior mechanisms.
[FORMAT] - The XML format to export. Valid options are: info:fedora/fedora-system:FOXML-1.1 (for FOXML 1.1), info:fedora/fedora-system:FOXML-1.0 (for FOXML 1.0), info:fedora/fedora-system:METSFedoraExt-1.1 (for METS), info:fedora/fedora-system:ATOM-1.0 (for ATOM), or default.
[ECONTEXT] - The export context (which indicates what use case the output should be prepared for. Valid options are: public, migrate, archive, or default.
[PATH] - The directory to export to.
[PROTOCOL] - Is how to connect to repository, either http or https.

Examples:

fedora-export example.com:80 fedoraAdmin fedoraAdmin demo:1 info:fedora/fedora-system:FOXML-1.1 migrate . http
Exports demo:1 for migration in FOXML 1.1 format (from example.com:80 to the current directory).

fedora-export example.com:80 fedoraAdmin fedoraAdmin DMO default default /tmp/fedoradump http
Exports all objects in the default export format and context (from example.com:80 to directory /tmp/fedoradump).

fedora-find

fedora-find [hostname] [port-number] [fieldList] [searchString] [protocol]

Where:

[hostname] - The hostname of the Fedora server; default is localhost.
[port-number] - The port number on which the Fedora server is running; default is 8080.
[fieldList] - A space-delimited list of fields. These are the fields that will be displayed for each object that matches the searchString. See http://host:port/fedora/search for a complete list of displayable fields and descriptions of each.
[searchString] - A simple text string to search all fields for. This may include wildcard characters and is case-insensitive.
[protocol] - Is how to connect to repository, either http or https.

Example:

fedora-find localhost 8080 "pid fType title description" "fedora" http
(shows the pid, Fedora object type, title, and description fields of each object that has the word fedora somewhere in it's indexed fields.)

A simple way to search a repository's indexed fields. More advanced searches can be done with the web-based search interface at http://host:port/fedora/search, or the Admin GUI's search interface.

fedora-ingest

fedora-ingest f[ile] [PATH] [FORMAT] [THST:TPRT] [TUSR] [TPSS] [TPROTOCOL] [LOG]

fedora-ingest d[ir] [PATH] [FORMAT] [FTYPS] [THST:TPRT] [TUSR] [TPSS] [TPROTOCOL] [LOG]

fedora-ingest r[epos] [SHST:SPRT] [SUSR] [SPSS] [PID|FTYPS] [THST:TPRT] [TUSR] [TPSS] [SPROTOCOL] [TPROTOCOL] [LOG]

Where:

f|[ile] or d[ir] or r[epos] indicates the whether the ingest is from a file, directory, or repository as source.
PATH - the local file or directory name.
[FORMAT] - the XML format of the ingest file(s). Valid options are: info:fedora/fedora-system:FOXML-1.1 (for FOXML 1.1), info:fedora/fedora-system:FOXML-1.0 (for FOXML 1.0), info:fedora/fedora-system:METSFedoraExt-1.1 (for METS), or info:fedora/fedora-system:ATOM-1.0 (for ATOM) Objects ingested in a format other than FOXML1.1 format are updated to conform to FOXML 1.1 as part of the ingest process.
[SHST/THST] - the source or target repository's hostname.
[SPRT/TPRT] - the source or target repository's port number.
[SUSR/TUSR] - the id of the source or target repository user.
[SPSS/TPSS] - the password of the source or target repository user.
[PID|FTYPS] - Either the identifier (PID) of the object to export from the repository OR the types of objects to export (FTYPS). FTYPS can be any combination of the characters O, D, and M, specifying which Fedora object type(s) should be exported. O=regular data objects, D=behavior definitions, M=behavior mechanisms.
[SPROTOCOL] - the protocol to communicate with source repository, either http or https.
[TPROTOCOL] - the protocol to communicate with target repository, either http or https.
[LOG] - the optional log message. If unspecified, the log message will indicate the source of the object(s).

Examples:

fedora-ingest f obj1.xml info:fedora/fedora-system:FOXML-1.1 myrepo.com:80 jane jpw http
Ingests obj1.xml (encoded in foxml1.1 format) from the current directory into the repository at myrepo.com:80 as user 'jane' with password 'jpw'. The logmessage will be system-generated, indicating the source path+filename.

fedora-ingest d c:\archive info:fedora/fedora-system:FOXML-1.0 M myrepo.com:80 jane janepw http ""
Traverses entire directory structure of c:\archive, and ingests any file that looks like a behavior mechanism object (M). It assumes all files will be in the FOXML 1.0 format and will fail on ingests of files that are not of this format. All log messages will be the quoted string.

fedora-ingest d c:\archive info:fedora/fedora-system:FOXML-1.0 ODM myrepo.com:80 jane janepw http "for jane"
Same as above, but ingests all three types of objects (O,D,M).

fedora-ingest r jrepo.com:8081 mike mpw demo:1 myrepo.com:80 jane jpw http http ""
Ingests the object whose pid is 'demo:1' from the source repository 'srcrepo.com:8081' into the target repository 'myrepo.com:80'. The object will be exported from the source repository in the default export format configured at the source. All log messages will be empty.

fedora-ingest r jrepo.com:8081 mike mpw O myrepo.com:80 jane jpw http http ""
Same as above, but ingests all data objects (type O).

fedora-ingest-demos

fedora-ingest-demos [hostname] [port-number] [user] [pass] [protocol]

Where:

[hostname] - The hostname of the Fedora server; default is localhost.
[port-number] - The port number on which the Fedora server is running; default is 8080.
[user] - The Fedora user (e.g. fedoraAdmin).
[pass] - The Fedora user's password.
[protocol] - Is how to connect to repository, either http or https.

Example:

fedora-ingest-demos localhost 8080 fedoraAdmin fedoraAdmin http
A convenient script to ingest all included demo objects for a new Fedora installation. See the Demo guide for descriptions of these objects. Note: This script should not be run until you have ensured that the hostname and port numbers in the demo objects have been corrected (with the fedora-convert-demos script) to use the actual hostname and port of your Fedora server.

fedora-convert-demos

fedora-convert-demos [fromProtocol] [fromHostName] [fromPortNum] [toProtocol] [toHostName] [toHostNum] [fedoraHomeDir]

Where:

[fromProtocol] - currently being used in the demo object files, either http or https.
[fromHostName] - The hostname currently being used in the demo object files.
[fromPortNum] - The port number currently being used in the demo object files.
[toProtocol] - The protocol to use for the repository, either http or https.
[toHostName] - The hostname of the repository.
[toPortNum] - The port number of the repository.
[fedoraHomeDir] - Fedora's install base directory. This is the directory that contains the client directory.

Example:

fedora-convert-demos http localhost 8080 http www.fedora.info 80 c:\fedora-2.0
Converts URLs in the demo objects from one protocol/host/port combination to another. After running this script with your repository's hostname, the demo objects can successfully be ingested.

Background: The demo objects that come with the Fedora client have embedded URLs inside them that assume the server is running on a machine called localhost on port number 8080. Those URLs must be changed to reflect the actual host and port the server is running on. Rather than search through all the demo files and change the references by hand, you can just run this script. It is not necessary to run this script if you have already run fedora-ingest-demos succcessfully and wish to change the hostname and port of the Fedora server, as the demo objects are already in the repository and the references inside them will automatically be corrected by the server.

fedora-purge

fedora-purge [hostname:port] [user] [pass] [pid] [protocol] [logMessage]

Where:

[hostname] - The hostname of the Fedora server; default is localhost.
[port] - The port number on which the Fedora server is running; default is 8080.
[user] - The Fedora user (e.g. fedoraAdmin).
[pass] - The Fedora user's password.
[pid] - The PID of the object to permanently remove.
[protocol] - The protocol to communicate with repository, either http or https.
[logMessage] - An optional log message explaining the removal.

Example:

fedora-purge localhost 8080 fedoraAdmin fedoraAdmin demo:6 http "It was just a test object"
Permanently removes an object from the repository.

fedora-modify

fedora-modify [hostname:port] [user] [password] [directives-filepath] [log-filepath] [protocol] [validate-only-option]*

Where:

[hostname:port] - The hostname and port of the target Fedora server.
[user] - The Fedora administrator username (e.g., fedoraAdmin)
[password] - The password for the Fedora administrator user.
[directives-filepath] - The full path to the file containing the batch modify directives.
[log-filepath] - The full path to the file where logs will be written.
[protocol] - The protocol to communicate with repository, either http or https.
[validate-only-option] - An optional parameter indicating whether to only validate the directives file or to immediately process the file. The parameter can have any non-blank value. If present, the directives file will be validated only. If omitted, the directives file will be immediately processed.

The fedora-modify command line utility enables the running of the batch modify utility of the Administrator GUI client from the command line.

fedora-batch-build

fedora-batch-build [object-template-file] [object-specific-dir] [object-directory] [log-filepath] [log-format]

Where:

[object-template-file] - The full path to the batch template file.
[obj-specific-dir] - The full path to the directory containing the object-specific files.
[object-directory] - The full path to the directory where the generated objects will be built.
[log-filepath] - The full path to the file where logs will be written.
[log-format] - The format of the log file. Valid values are text or xml.

The fedora-batch-build command line utility enables the running of the batch build utility of the Administrator GUI client from the command line. The batch build utility creates a "batch" of Fedora objects based on the specified template file and the corresponding directory of object-specific files. Refer to the documentation on the Batch Utility for more details on how to use the batch build utility.

fedora-batch-ingest

fedora-batch-ingest [object-directory] [log-filepath] [log-format] [host:port] [user] [password] [protocol]

Where:

[obj-directory] - The full path to the directory containing the objects to be ingested.
[log-filepath] - The full path to the file where logs will be written.
[log-format] - The format of the log file. Valid values are text or xml.
[host:port] - The hostname and port of the target Fedora server.
[user] - The Fedora administrator username (e.g., fedoraAdmin)
[password] - The password for the Fedora administrator user.
[protocol] - The protocol to communicate with Fedora server, either http or https.

The fedora-batch-ingest command line utility enables the running of the batch ingest utility of the Administrator GUI client from the command line. The batch ingest utility ingests a "batch" of Fedora objects from the specified directory into the repository. Refer to the documentation on the Batch Utility for more details on how to use the batch ingest utility.

fedora-batch-buildingest

fedora-batch-buildingest [object-template-file] [object-specific-dir] [object-directory] [log-filepath] [log-format] [host:port] [user] [password] [protocol]

Where:

[object-template-file] - The full path to the batch template file.
[obj-specific-dir] - The full path to the directory containing the object-specific files.
[object-directory] - The full path to the directory where the generated objects will be built.
[log-filepath] - The full path to the file where logs will be written.
[log-format] - The format of the log file. Valid values are text or xml.
[host:port] - The hostname and port of the target Fedora server.
[user] - The Fedora administrator username (e.g., fedoraAdmin).
[password] - The password for the Fedora administrator user.
[protocol] - The protocol to communicate with Fedora server, either http or https.

The fedora-batch-buildingest command line utility enables the running of the batch build & ingest utility of the Administrator GUI client from the command line. The batch build & ingest utility creates a "batch" of Fedora objects based on the specified template file and the corresponding directory of object-specific files and then ingests them into the repository. Refer to the documentation on the Batch Utility for more details on how to use the batch build & ingest utility.

fedora-validate-objects

fedora-validate-objects -serverurl [server-base-url] -username [user] -password [password] {-terms [terms] | -query [query] | -pidfile [path]} -logConfig [log4j-properties-file]

Where:

[server-base-url] - The full URL used to connect with the Fedora server: e.g. http://localhost:8080/fedora
[user] - The Fedora administrator username (e.g., fedoraAdmin).
[password] - The password for the Fedora administrator user.
[terms] - A "terms" string, as for the "FindObjects" method of API-A
[query] - A "query" string, as for the "FindObjects" method of API-A
[pidfile] - The path to a text file containing the PIDs of the objects to be validated, one PID per line.
[log4j-properties-file] - The full path to a Log4J properties file. Optional.

The fedora-validate-objects command line utility runs a validation task against a set of objects in the specified repository. Access to the repository is provided via the "-serverurl", "-username" and "-password" parameters. The set of objects is specified using either a "terms" phrase, a "query" sequence, or a "pidfile" (one of these is required, but more than one is not allowed). The "terms" and "query" parameters correspond to the strings used by the FindObjects method of API-A. The PID file is a plain text file containing one PID per line, ignoring blank lines and comment lines (lines that start with '#').

The output of the validator can be controlled with the Log4J properties file. This can be used to suppress certain categories of messages or to restrict output by severity level.

# In this example, messages regarding objects with no content model are disabled.
 
# An appender for non-validator logging.
log4j.appender.STDOUT=org.apache.log4j.ConsoleAppender
log4j.appender.STDOUT.layout=org.apache.log4j.PatternLayout
log4j.appender.STDOUT.layout.ConversionPattern=%d{yyyy-MM-dd' 'HH:mm:ss.SSS} %p (%c) %m%n
log4j.rootLogger=INFO, STDOUT

# An appender for validator logging.
log4j.appender.VALIDATOR=org.apache.log4j.ConsoleAppender
log4j.appender.VALIDATOR.layout=org.apache.log4j.PatternLayout
log4j.appender.VALIDATOR.layout.ConversionPattern=%p [%c] %m%n

# The "root" of the Validator logging categories.
log4j.logger.Validator=INFO, VALIDATOR
log4j.additivity.Validator=false

# Set some categories for special treatment.
log4j.logger.Validator.NoContentModel=OFF