ONECLIENT(1)

NAME
oneclient - Onedata command line client

SYNOPSIS
oneclient [-h|--help] [-V|--version] [-u|--unmount] [-c|--config config_path] [-H|--host hostname] [-P|--port port] [-i|--insecure] [-t|--token access_token] [--space] [--space-id] [-l|--log-dir log_path] [--force-proxy-io] [--force-direct-io] [--buffer-scheduler-thread-count threads] [--communicator-thread-count threads] [--scheduler-thread-count threads] [--storage-helper-thread-count threads] [--no-buffer] [--read-buffer-min-size size] [--read-buffer-max-size size] [--read-buffer-prefetch-duration duration] [--write-buffer-min-size size] [--write-buffer-max-size size] [--write-buffer-flush-delay delay] [-f|--foreground] [-d|--debug] [--seqrd-prefetch-threshold fraction] [--rndrd-prefetch-threshold fraction] [--rndrd-prefetch-eval-frequency count] [--rndrd-prefetch-block-threshold count] [--rndrd-prefetch-cluster-window size] [--rndrd-prefetch-cluster-block-threshold count] [--rndrd-prefetch-cluster-window-grow-factor fraction] [--prefetch-mode arg] [--cluster-prefetch-threshold-random] [--metadata-cache-size size] [--readdir-prefetch-size size] [--tag-on-create name:value] [--tag-on-modify name:value] [-r|--override storageId:name:value] [-s|--single-thread] [-o|--opt mount_options] mountpoint

DESCRIPTION
oneclient provides command line interface to mount Onedata (https://onedata.org) distributed file system data spaces on local machine using Fuse.

oneclient relies on Fuse (Filesystem in Userspace) library, which enables POSIX access to remote data managed by Onedata platform. Fuse command line options (-f, -d, -s and -o) can be passed directly to the oneclient on the command line or in the config file (see oneclient.conf(5)).

USAGE
In order to connect to Onedata services, oneclient needs credentials in the form of access token to authenticate the user remotely on the Oneprovider side. Access tokens can be generated in the web user interface or using the REST API.

oneclient connects to a specific Oneprovider service selected by the user and specified using -H or --host option and port using -P or --port. Port can be omitted if Oneprovider service is deployed on default port (443).

NOTE: If you are connecting to a Onedata provider service, which does not have a globally trusted certificate, you will have to use -i or --insecure on every oneclient invocation.

  Access tokens
In order to get an authentication token, login to Onezone web user interface, expand Access Tokens menu on the left and press Create new access token. Copy the generated token and pass it to the oneclient command line options using -t or --token option.

Additionally, the access token can be specified in the ONECLIENT_ACCESS_TOKEN environment variable.

  Mounting spaces
When oneclient connects successfully to the Oneprovider, the <mountpoint> directory will contain the entire list of user spaces, and all regular command line tools can be used to access and modify the files and directories in there, as long as the permissions allow for.

It is possible to limit the spaces which are visible, by providing a white list of the spaces on the command line.

  Proxy IO and Direct IO modes
oneclient has a unique feature enabling it to transparently detect whenever it has direct access to storage which is used by some Oneprovider instance managing user space, and in such case redirects all IO operations directly to the storage without going through the Oneprovider service (Direct IO mode). This feature is detected by oneclient automatically.

  Buffering
oneclient employs an in-memory buffer for input and output data blocks, which can significantly improve performance for various types of storages, in particular object based storages such as S3.

If for some reason this local cache is undesired, it can be disabled using --no-buffer option.

  Force full block read mode
By default, POSIX read request can return less bytes than requested, especially on network filesystem which can return partial data range which is immediately available and request the remaining bytes assuming the application will run another read request with adjusted offset and size. However, some applications assume that the read always return the requested range or error. In order to enable this behavior in oneclient it necessary to provide the --force-fullblock-read on the command line.

  Overriding storage helper parameters
Oneclient allows to override certain storage helper parameters in order to customize direct access to storage from a Oneclient host to the storage. Use cases for this feature include specifying custom mounpoint for POSIX storages, alternate IP addresses for network storages (e.g. available over local network from Oneclient host), etc.

For example, to tell Oneclient that storage with a NFS storage is mounted at /home/user1/nfs the following option should be added to the Oneclient command line: --override 2bede2623303bc2a19696e5817e13c0b:mountPoint:/home/user/nfs. 2bede2623303bc2a19696e5817e13c0b is the storage Id of this storage.

The --override option takes 3 arguments separated by :: * storade ID: This is Onedata internal storage Id, which can be obtained from Onepanel administrator interface or using REST API

parameter name
    This is the name of the storage helper parameter, these are specific to particular type of storage

parameter value
    Value which should override the value specified in the Oneprovider when registering the storage

  Logging
In order to enable a verbose log, oneclient provides a -v flag which takes a single integer argument which determines the log verbosity:

•   -v 0 - (default) only serious errors

•   -v 1 - warnings and errors which are not fatal

•   -v 2 - verbose information on requests and their handling

•   -v 3 - trace function calls along with their arguments

•   -v 4 - binary messages between Oneclient and Oneprovider

Please note that above level 2, the size of the logs can be substantial thus it is necessary to monitor free disk space.

CONFIGURATION
Beside the command line configuration options, oneclient reads options from a global configuration file located by default at /usr/local/etc/oneclient.conf (/etc/oneclient.conf when installed from a distribution package). For details see oneclient.conf(5).

OPTIONS

-h, --help
    Show this help and exit.

-V, --version
    Show current oneclient version and exit.

-u, --unmount
    Unmount oneclient and exit.

-c <config_path>, --config <config_path>
    Specify path to user config file.

-H <host>, --host <host>
    Specify the hostname of the Oneprovider instance to which the oneclient should connect.

-P <port>, --port <port>
    Specify the port to which the oneclient should connect on the Oneprovider.

-i, --insecure
    Disable verification of server certificate, allows to connect to servers without valid certificate.

-t <token>, --token <token>
    Specify Onedata access token for authentication and authorization.

-l <log_path>, --log-dir <log_path>
    Specify custom path for oneclient logs.

--space <name>
    Every occurence of this option followed by the name of a space will limit the mounted spaces to the specified spaces

--space-id <id>
    Every occurence of this option followed by the id of a space will limit the mounted spaces to the specified spaces

--force-proxy-io
    Force proxied access to storage via Oneprovider for all spaces.

--force-direct-io
    Force direct access to storage for all spaces.

--buffer-scheduler-thread-count <threads>
    Specify number of parallel buffer scheduler threads.

--communicator-thread-count <threads>
    Specify number of parallel communicator threads.

--scheduler-thread-count <threads>
    Specify number of parallel scheduler threads.

--storage-helper-thread-count <threads>
    Specify number of parallel storage helper threads.

--no-buffer
    Disable in-memory cache for input/output data blocks.

--provider-timeout <duration>
    Specify Oneprovider connection timeout in seconds.

--disable-read-events
    Disable reporting of file read events.

--no-fullblock-read
    Disable fullblock read mode. With this option read can return less data than requested in case it is immediately available and consecutive blocks need to be prefetched from remote storage.

--read-buffer-min-size <size>
    Specify minimum size in bytes of in-memory cache for input data blocks.

--read-buffer-max-size <size>
    Specify maximum size in bytes of in-memory cache for input data blocks.

--read-buffer-prefetch-duration <duration>
    Specify read ahead period in seconds of in-memory cache for input data blocks.

--write-buffer-min-size <size>
    Specify minimum size in bytes of in-memory cache for output data blocks.

--write-buffer-max-size <size>
    Specify maximum size in bytes of in-memory cache for output data blocks.

--write-buffer-flush-delay <delay>
    Specify idle period in seconds before flush of in-memory cache for output data blocks.

--seqrd-prefetch-threshold <fraction>
    Specify the fraction of the file, which will trigger replication prefetch after that part of the file is already replicated (experimental).

--rndrd-prefetch-threshold <fraction>
    Specify the fraction of the file, which will trigger replication prefetch after that part of the file is already replicated in random blocks across entire file (experimental).

--rndrd-prefetch-eval-frequency
    Number of reads from single file handle which will be skipped before next evaluation of cluster prefetch. 0 means that prefetch evaluation will be performed on each read. (experimental).

--rndrd-prefetch-block-threshold
    Number of separate blocks after which replication for the file is triggered automatically. 0 disables this feature (experimental).

--rndrd-prefetch-cluster-window
    Cluster window size for prefetching in [bytes]. When -1 is provided, the entire file is considered for prefetching (experimental).

--rndrd-prefetch-cluster-block-threshold
    Number of separate blocks in a cluster window around current read, after which replication of a cluster block (window) is triggered (experimental).

--rndrd-prefetch-cluster-window-grow-factor
    Prefetch cluster window grow factor, which enables the prefetch window to grow proportionally to current replication progress - initial_window_size[1+grow_factorfile_size*replication_progress/initial_window_size)] (experimental).

--prefetch-mode <arg>
    Defines the type of block prefetch mode. Possible values are: async, sync. Default is: async (experimental).

--cluster-prefetch-threshold-random
    Enables random cluster prefetch threshold selection (experimental).

--metadata-cache-size <size>
    Number of separate blocks after which replication for the file is triggered automatically.

--readdir-prefetch-size <size>
    Specify the size of requests made during readdir prefetch (in number of dir entries).

--tag-on-create <name>:<value>
    Adds name=value extended attribute to each locally created file.

--tag-on-modify <name>:<value>: Adds name=value extended attribute to each locally modified file.

-r [ --override ] <storageId>:<name>:<value>
    Allows to override selected helper parameters for specific storage, e.g. 'd40f2f63433da7c845886f6fe970048b:mount Point:/mnt/nfs'

-f, --foreground
    Foreground operation (see fuse(8)).

-d, --debug
    Enable debug mode (implies -f) (see fuse(8)).

-s, --single-thread
    Single-threaded operation (see fuse(8)).

-o <mount_options>, --opt <mount_options>
    Pass mount arguments directly to FUSE (see fuse.mount(8)).

ENVIRONMENT VARIABLES
Some options in the config file can be overriden using environment variables, whose names are capitalized version of the config options. The available environment variables are:

ONECLIENT_CONFIG
    Allows to specify path to user config file.

ONECLIENT_PROVIDER_HOST
    Allows to specify the Oneprovider host to which the oneclient will connect.

ONECLIENT_PROVIDER_PORT
    Allows to specify Oneprovider port, to which oneclient will connect (default: 443).

ONECLIENT_INSECURE
    If set to 1, disables verification of server certificate and allows to connect to servers without valid certificate. (default: 0).

ONECLIENT_ACCESS_TOKEN
    Allows to specify Onedata access token for authentication and authorization.

ONECLIENT_LOG_DIR
    Allows to specify the log directory for oneclient (default: /tmp).

ONECLIENT_FUSE_FOREGROUND
    If set to 1, oneclient will run in foreground mode (default: 0).

ONECLIENT_FUSE_DEBUG
    If set to 1, oneclient will run in debug mode (default: 0).

ONECLIENT_FUSE_SINGLE_THREAD
    If set to 1, oneclient will run in single thread mode (default: 0).

ONECLIENT_MOUNTPOINT
    Allows to specify default mountpoint for oneclient.

EXAMPLES
In order to simply mount your spaces into some local folder use the following command:

oneclient -H onedata.org -t <ACCESS_TOKEN> ~/mnt/onedata

Connect without validating server certificate and pass token in environment variable:

export ONECLIENT_INSECURE=1

export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN>

export ONECLIENT_PROVIDER_HOST=<ONEPROVIDER_HOST>

oneclient ~/mnt/onedata

To unmount Onedata spaces use oneclient:

oneclient -u ~/mnt/onedata

or using Fuse:

fusermount -uz ~/mnt/onedata

COPYRIGHT
Copyright (C) 2014-2019, Academic Computer Centre CYFRONET AGH, Krakow, Poland. Released under the Apache 2.0 license.

SEE ALSO
oneclient.conf(5), fuse(8), fuse.mount(8)