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).

Java memory settings

Note that the memory settings used by the client command-line utilities are set in the script env-client.sh (or env-client.bat on Windows). If you have any problems with running out of memory you can change the default values in this file.

Note: There are also server command-line utilities which perform server rebuilding, validation, and other functions.

fedora-dsinfo

fedora-dsinfo [host] [port] [user] [password] [pid] [protocol] [context]

Where:

host - 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)
password - the Fedora user's password
pid - the pid of the object whose datastream information should be shown
protocol - how to connect to repository, either http or https
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

Example:

Display key information about each of an object's datastreams.

fedora-dsinfo localhost 8080 fedoraAdmin fedoraAdmin demo:5 http

fedora-export

fedora-export [host:port] [user] [password] [pid | ftyps] [format] [econtext] [path] [protocol] [context]

Where:

host:port - the repository's hostname and the port separated by colon
user - the Fedora user (e.g. fedoraAdmin)
password - the Fedora user's password
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 export directory
protocol - how to connect to repository, either http or https
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

Examples:

Export demo:1 for migration in FOXML 1.1 format (from example.com:80 to the current directory).

fedora-export example.com:80 fedoraAdmin fedoraAdmin demo:1 info:fedora/fedora-system:FOXML-1.1 migrate . http

Export all objects in the default export format and context (from example.com:80 to directory /tmp/fedoradump).

fedora-export example.com:80 fedoraAdmin fedoraAdmin DMO default default /tmp/fedoradump http

fedora-find

fedora-find [host] [port] [user] [password] [fields] [phrase] [protocol] [context]

user - the Fedora user (e.g. fedoraAdmin)
password - the Fedora user's password

Where:

host - the hostname of the Fedora server; default is localhost
port - the port number on which the Fedora server is running; default is 8080
fields - 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.
phrase - A simple text string to search all fields for. This may include wildcard characters and is case-insensitive.
protocol - how to connect to repository, either http or https
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

Example:

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 (shows the pid, Fedora object type, title, and description fields of each object that has the word fedora somewhere in it's indexed fields).

fedora-find localhost 8080 "pid fType title description" "fedora" http

fedora-ingest

fedora-ingest f[ile] [path] [format] [targetHost:targetPort] [targetUser] [targetPassword] [targetProtocol] [log] [context]
fedora-ingest d[ir] [path] [format] [targetHost:targetPort] [targetUser] [targetPassword] [targetProtocol] [log] [context]
fedora-ingest r[epos] [sourceHost:sourcePort] [sourceUser] [sourcePassword] [pid | *] [targetHost:targetPort] [targetUser] [targetPassword] [sourceProtocol] [targetProtocol] [log] [context]

Where:

f[ile] or d[ir] or r[epos] - indicates 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
sourceHost/targetHost - the source or target repository's hostname
sourcePort/targetPort - the source or target repository's port number
sourceUser/targetUser - the id of the source or target repository user
sourcePassword/targetPassword - the password of the source or target repository user
pid | * - Either the identifier (PID) of the object to export from the repository OR * to indicate all objects from the source repository
sourceProtocol - the protocol to communicate with source repository, either http or https
targetProtocol - 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)
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration). NOTE: This parameter can only be used if the 'log' parameter has been used as well.

Examples:

Ingest 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 log message will be system-generated, indicating the source path+filename.

fedora-ingest f obj1.xml info:fedora/fedora-system:FOXML-1.1 myrepo.com:80 jane jpw http

Traverse the entire directory structure of c:\archive, and ingests any file. It assumes all files will be in the FOXML 1.1 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.1 myrepo.com:80 jane janepw http ""

Ingest 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 demo:1 myrepo.com:80 jane jpw http http ""

Same as above, but ingests all data objects (type O).

fedora-ingest r jrepo.com:8081 mike mpw O myrepo.com:80 jane jpw http http ""

fedora-ingest-demos

fedora-ingest-demos [host] [port] [user] [password] [protocol] [context]

Where:

host - 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)
password - the Fedora user's password
protocol - how to connect to repository, either http or https
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

Example:

A convenient script to ingest all included demo objects for a new Fedora installation. See the Demo guide for descriptions of these objects. Note for Fedora 3.1 and below: 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-ingest-demos localhost 8080 fedoraAdmin fedoraAdmin http

fedora-convert-demos

Information

This script is available in Fedora 3.1 and below only. In Fedora 3.2+, the demo objects don't need conversion because they use the special "http://local.fedora.server/fedora/" syntax where appropriate. This causes the Fedora server to automatically translate the URLs based on where it is hosted (e.g. http://example.org/foo/), at runtime.

fedora-purge

fedora-purge [host:port] [user] [password] [pid] [protocol] [log] [context]

Where:

host - 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)
password - 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
log - an optional log message explaining the removal
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

Example:

Permanently removes an object from the repository.

fedora-purge localhost 8080 fedoraAdmin fedoraAdmin demo:6 http "It was just a test object"

fedora-modify

The fedora-modify command line utility enables the running of the batch modify utility from the command line. The default behavior is to only validate the directives. To actually execute them, you must specify a value for execute-directives. A sample file showing all the available directives is available in FEDORA_HOME/client/demo/batch-demo/modify-batch-directives.xml.

fedora-modify [host:port] [user] [password] [directives-filepath] [log-filepath] [protocol] [execute-directives] [context]

Where:

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
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
execute-directives - an optional parameter indicating whether to actually process the directives. This can have any value, and when specified, means that the directives should actually be executed. If unspecified, the directives will be validated only.
context - an optional parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration). NOTE: This parameter can only be used if the 'execute-directives' has been specified as well.

fedora-batch-build

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

fedora-batch-ingest

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-ingest [object-directory] [log-filepath] [log-format] [format] [host:port] [user] [password] [protocol] [context]

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
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)
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.
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

fedora-batch-buildingest

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.

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

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.
context - an _optional_ parameter indicating the webapp context. This is only necessary if the Fedora server was installed under a context name other than 'fedora' (see Alternative Webapp Context Configuration).

fedora-validate-objects

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-LITE. 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.

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.

# 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

All Versions

Child pages

Table of Contents

Introduction

fedora-dsinfo

fedora-export

fedora-find

fedora-ingest

fedora-ingest-demos

fedora-convert-demos

fedora-purge

fedora-modify

fedora-batch-build

fedora-batch-ingest

fedora-batch-buildingest

fedora-validate-objects