--version Print the version number of GeneTorrent to the standard output stream. This version number should be included in all bug reports.

Transcription

1 GeneTorrent NAME GeneTorrent - transfer genomic data reliably across a network SYNOPSIS GeneTorrent -u manifest-file -c cred [ -p path ] GeneTorrent -d < URI UUID.xml.gto > -c cred [ -p path ] GeneTorrent -s path -q work-queue -c cred --security-api signing-uri DESCRIPTION GeneTorrent is a file transfer client application designed for the optimal transfer of genomic data across a computer network. File transfers using GeneTorrent are designed to be authenticated, secure, reliable, and efficient. GeneTorrent has 3 operating modes: upload, download, and server. Upload mode is used to send files to the repository. Download mode is used to retrieve files from the repository. Server mode is used within the repository to create GeneTorrent server instances that deliver data to download actors. OPTIONS General Command Line Arguments: -h, --help Print a usage message briefly summarizing these command-line options, then exit. --version Print the version number of GeneTorrent to the standard output stream. This version number should be included in all bug reports. -b address, --bind-ip address The IP address for GeneTorrent to bind. Default is to bind all addresses on the system. -c credential-file, --credential-file credential-file Required for all modes, unless you are directly passing a.gto file to the -d option. The absolute or relative path to the file containing the access credentials (security token) previously received from the repository. -C confdir, --config-dir confdir Specify an absolute or relative path to the GeneTorrent configuration directory. This directory should contain dhparam.pem. --config-file configuration-file Specifies the absolute or relative path to a configuration file from which to read program options. (See below for format.) Virtually every option that can be specified on the command line can also be specified in the configuration file. Options present on the

2 command line will override the contents of the configuration file. -e address, --advertised-ip address The IP address to advertise to the transactor. This option is useful when this actor is running behind a NAT firewall and the publicly exposed IP address is not the same as the actual IP address. The default is to advertise the IP address of the host's default route, or the address specified with the -b option. -f port, --advertised-port port The first port to advertise to the transactor. This option is useful when this actor is running behind a NAT firewall and the publicly exposed ports are not the same as the ports actually bound. The range of advertised ports will start at the port number specified in this option, so for instance if 9 ports are configured, then the advertised ports will run from port to port+8. The default is to advertise the ports that are actually used. -i startport[:endport], --internal-port startport[:endport] Specifies the range of ports actually used by GeneTorrent. By default these ports are also advertised externally unless the -f option is used. If an endport is not specified, 9 ports will be configured, so endport = startport + 8. The default is to use ports through k minutes, --inactivity-timeout minutes Specifies a duration of inactivity in minutes after which GeneTorrent, in download or upload mode, will abort file transfers and exit. The activity measured to make this determination is actual payload data transfer over the GeneTorrent protocol. The default behavior is to never timeout, which is the recommended setting. When using this setting, it is recommended that it be set for 40 or more minutes. -l destination[:verbosity], --log destination[:verbosity] Specifies the destination of a log file and a verbosity level. Possible values for the destination include "none", "stdout", "stderr", "syslog", or a filename; the log output will be directed to the destination specified. Possible values for verbosity include (in order of increasing volume of messages) "standard", "verbose", or "full"; standard is the default. The default behavior is no logging if this parameter is not specified. --ssl-no-verify-ca Specifies that GeneTorrent should not verify the SSL certificates presented by web services. This is not recommended. -v, --verbose level Controls the level of on-screen progress reporting to stdout. By default GeneTorrent offers no status information unless an error occurs. The long and short forms of this option work slightly differently. With the short form, you can receive summary progress information by specifying a single -v, or detailed progress information by specifying -vv (e.g., two -v's). With the long form, you specify a numeric level between 1 and 2; for instance, use --verbose=1 for summary progress

3 information. -t, --timestamps Specifies that the on-screen progress messages (controlled by the -v flag, above) should include a timestamp. This is primarily useful when these messages are being redirected to a file for later review. --null-storage Enable null storage implementation. This is a command line only option and is not available in the configuration file. A virtual storage device intended for a receive-only peer which throws away all data received (rather than writing to disk). Of course this means a receive peer running in this mode cannot turn around and share any blocks it has received. This mode disables hash checking of the downloaded pieces so there is no handling of corrupt pieces, every piece downloaded is assumed correct. This mode can not be used to transmit files. Use this mode when performance testing the client side of download transfers. Can not be used in conjunction with --zero-storage for a given invocation of GeneTorrent. In some cases it makes sense to use --zero-storage on the server side and --null-storage on the download client side. --zero-storage Enable zero storage implementation. This is a command line only option and is not available in the configuration file. A virtual storage device intended for a transmit or receive peer which throws away all data received (rather than writing to disk). Transmitted data will always consist of a stream of zeros. Of course this means the receive peer running in this mode cannot turn around and share any blocks it has received. The transmitter of the data must have a precomputed torrent file which hashes properly since GeneTorrent will not be able to create a torrent file (.gto file) when run in zero storage mode. Can not be used in conjunction with --null-storage for a given invocation of GeneTorrent. Upload Mode Command Line Arguments: -u manifest-file, --upload manifest-file Required; indicates upload mode. The absolute or relative path to the manifest-file, which must follow the format specified by Annai Systems. This file lists all the data files that are to be transferred to the repository. -p path, --path path The absolute or relative path to the root directory for upload. Note that files to be uploaded must always be in a subdirectory named after the analysis UUID for the submission. If the -p option is present, path can point to the UUID directory, or to the directory that contains the UUID directory. The current directory will be used by default.

4 -r max-rate, --rate-limit max-rate The maximum data rate to upload, specified in MB/sec (megabytes per second). --upload-gto-path path The absolute or relative path to a directory in which the GTO file and other temporary files can be created. The GTO file is created as a part of the upload process by GeneTorrent. By default, it will be stored in the UUID directory for the submission. Download Mode Command Line Arguments: -d content-specifier, --download content-specifier Required. Indicates download mode. content-specifier should be one of the following: o A fully-qualified URI pointing to an analysis object at the GeneTorrent Executive. o A UUID denoting an analysis object at the GeneTorrent Executive. In this case, GeneTorrent will construct a URI based on the default server, currently o The absolute or relative path to an XML file, which will be parsed to obtain a list of URIs. o The absolute or relative path to a.gto file directly, which eliminates all calls to the GeneTorrent Executive and causes a download to begin. In this case you do not need to supply access credentials using the -c option. Note that multiple -d options can be specified on the same command line, in which case multiple analysis objects will be downloaded. -p path, --path path The absolute or relative path to save data files in the gto file(s). UUID is part of the gto and will always be added to path, so after download data files will be found at path/uuid. The current directory will be used by default. --max-children max-children The maximum number of parallel children that should be spawned to perform the download. By default up to 8 children are used, but this number may be adjusted. For maximum performance, the recommended number of children is between C/2 and C, if C is the number of cores on your machine. -r max-rate, --rate-limit max-rate The maximum data rate to download, specified in MB/sec (megabytes per second). --security-api signing-uri signing-uri is a fully-qualified URI which will sign CSRs for this download instance. Server Mode Command Line Arguments: -s path, --server path Required. Indicates server mode. path is the absolute or relative path to the directory

5 under which the data files being shared are to be found. Note that UUID is always be added to path, so data files will be found at path/uuid. -q work-queue, --queue work-queue Server Mode Command Line Arguments: -s path, --server path Required. Indicates server mode. path is the absolute or relative path to the directory under which the data files being shared are to be found. Note that UUID is always be added to path, so data files will be found at path/uuid. -q work-queue, --queue work-queue Required. work-queue is the absolute or relative path to a directory where this server instance will look for.gto files to begin sharing content. --security-api signing-uri Required. signing-uri is a fully-qualified URI which will sign CSRs for this server instance. CONFIGURATION FILE All options that can be specified on the command line can also be specified in a configuration file, which is specified on the command line via the --config-file option. The configuration file is a simple flat ASCII file with lines of the form "parameter=value". Except for 'help', 'version', and 'config-file', any long-form option from the command line may be used as a parameter, and the # character introduces a comment that spans until the end of the line. Sample GeneTorrent server configuration file: # GeneTorrent configuration file log=syslog:full server=/cghub/data queue=/cghub/data/workqueues/dropzone-app04 credential-file=/cghub/home/shared/gtorrent.pem security-api= advertised-ip= advertised-port=6921 COPYRIGHT Copyright Annai Systems, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.