OCM Configuration

Table of Contents

Introduction
Default Values
Enable OCM
Trust Between Instances
Invitation Workflow
Configuration
- Environment Variables
- YAML Example

Introduction

The Infinite Scale OCM service provides federated sharing functionality based on the ScienceMesh and OCM HTTP APIs.

Overview:

ScienceMesh is the Federated Science Cloud Mesh that connects existing and heterogeneous sites in a transparent way. It provides a managed white list of trusted federated sites.
The Open Cloud Mesh Protocol provides the disovery and use of the RESTful API endpoints, request and response headers, possible response codes, request and response formats, hypermedia controls, error handling etc. Using this protocol, consumers do not need to accept a share, the shared resource will be available to them immediately.

Both API’s have their roots in CERN where providing resources to trusted partners in an easy way is a key for their daily scientific work.

See the Setup Federations Using ScienceMesh for details on how to setup sharing between users via a federation using OCM.

Default Values

OCM listens on port 9280 by default.

Enable OCM

To enable OpenCloudMesh, you have to set the following environment variable.

OCIS_ENABLE_OCM=true

Trust Between Instances

For security reasons and data protection, invitations are limited to trusted instances only. These have to be defined by the administrator before setting up any federation.

The OCM service implements an invitation workflow for trusted instances when creating federated shares.

The list of trusts for an instance is defined via a json file. Note that this ocmproviders.json file, which holds that configuration, is expected to be located in the root of the Infinite Scale config directory if not otherwise defined. See the OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE environment variable for more details.

When all instances of a federation should trust each other, an ocmproviders.json file like this can be used for all instances. The following example federation consists of two instances: cloud.owncloud.test and cloud.ocis.test that can use the Invitation Workflow described below to generate, send and accept invitations.

[
    {
        "name": "oCIS Test",
        "full_name": "oCIS Test provider",
        "organization": "oCIS",
        "domain": "cloud.ocis.test",
        "homepage": "https://ocis.test",
        "description": "oCIS Example cloud storage",
        "services": [
            {
                "endpoint": {
                    "type": {
                        "name": "OCM",
                        "description": "cloud.ocis.test Open Cloud Mesh API"
                    },
                    "name": "cloud.ocis.test - OCM API",
                    "path": "https://cloud.ocis.test/ocm/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "http://cloud.ocis.test"
            },
            {
                "endpoint": {
                    "type": {
                        "name": "Webdav",
                        "description": "cloud.ocis.test Webdav API"
                    },
                    "name": "cloud.ocis.test Example - Webdav API",
                    "path": "https://cloud.ocis.test/dav/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "https://cloud.ocis.test/"
            }
        ]
    },
    {
        "name": "ownCloud Test",
        "full_name": "ownCloud Test provider",
        "organization": "ownCloud",
        "domain": "cloud.owncloud.test",
        "homepage": "https://owncloud.test",
        "description": "ownCloud Example cloud storage",
        "services": [
            {
                "endpoint": {
                    "type": {
                        "name": "OCM",
                        "description": "cloud.owncloud.test Open Cloud Mesh API"
                    },
                    "name": "cloud.owncloud.test - OCM API",
                    "path": "https://cloud.owncloud.test/ocm/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "http://cloud.owncloud.test"
            },
            {
                "endpoint": {
                    "type": {
                        "name": "Webdav",
                        "description": "cloud.owncloud.test Webdav API"
                    },
                    "name": "cloud.owncloud.test Example - Webdav API",
                    "path": "https://cloud.owncloud.test/dav/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "https://cloud.owncloud.test/"
            }
        ]
    }
]

The domain must not contain the protocol as it has to match the GOCDB site object domain.

Invitation Workflow

After the federation has been setup but before sharing a resource with a remote user, this user has to be invited by the sharer.

Internally, a request is sent to the ScienceMesh API. The generated token is passed on to the receiver, who will then accept the invitation. As a result, remote users will be added on both sides and the data for this grant is saved in a file defined via the OCM_OCM_INVITE_MANAGER_JSON_FILE environment variable.

Configuration

Environment Variables

The ocm service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

master + Rolling 6.6.0

Environment variables for the ocm service
Name	IV	Type	Default Value	Description
`OCIS_TRACING_ENABLED` `OCM_TRACING_ENABLED`	5.0	bool	false	Activates tracing.
`OCIS_TRACING_TYPE` `OCM_TRACING_TYPE`	5.0	string		The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now.
`OCIS_TRACING_ENDPOINT` `OCM_TRACING_ENDPOINT`	5.0	string		The endpoint of the tracing agent.
`OCIS_TRACING_COLLECTOR` `OCM_TRACING_COLLECTOR`	5.0	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
`OCIS_LOG_LEVEL` `OCM_LOG_LEVEL`	5.0	string		The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.
`OCIS_LOG_PRETTY` `OCM_LOG_PRETTY`	5.0	bool	false	Activates pretty log output.
`OCIS_LOG_COLOR` `OCM_LOG_COLOR`	5.0	bool	false	Activates colorized log output.
`OCIS_LOG_FILE` `OCM_LOG_FILE`	5.0	string		The path to the log file. Activates logging to this file if set.
`OCM_DEBUG_ADDR`	5.0	string	127.0.0.1:9281	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
`OCM_DEBUG_TOKEN`	5.0	string		Token to secure the metrics endpoint.
`OCM_DEBUG_PPROF`	5.0	bool	false	Enables pprof, which can be used for profiling.
`OCM_DEBUG_ZPAGES`	5.0	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
`OCM_HTTP_ADDR`	5.0	string	127.0.0.1:9280	The bind address of the HTTP service.
`OCM_HTTP_PROTOCOL`	5.0	string	tcp	The transport protocol of the HTTP service.
`OCM_HTTP_PREFIX`	5.0	string		The path prefix where OCM can be accessed (defaults to /).
`OCIS_CORS_ALLOW_ORIGINS` `OCM_CORS_ALLOW_ORIGINS`	5.0	[]string	[https://localhost:9200]	A list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details.
`OCIS_CORS_ALLOW_METHODS` `OCM_CORS_ALLOW_METHODS`	5.0	[]string	[OPTIONS HEAD GET PUT POST DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]	A list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.
`OCIS_CORS_ALLOW_HEADERS` `OCM_CORS_ALLOW_HEADERS`	5.0	[]string	[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override Cache-Control]	A list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.
`OCIS_CORS_ALLOW_CREDENTIALS` `OCM_CORS_ALLOW_CREDENTIALS`	5.0	bool	false	Allow credentials for CORS.See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.
`OCM_GRPC_ADDR`	5.0	string	127.0.0.1:9282	The bind address of the GRPC service.
`OCIS_GRPC_PROTOCOL` `OCM_GRPC_PROTOCOL`	5.0	string		The transport protocol of the GRPC service.
`OCIS_SERVICE_ACCOUNT_ID` `OCM_SERVICE_ACCOUNT_ID`	5.0	string		The ID of the service account the service should use. See the 'auth-service' service description for more details.
`OCIS_SERVICE_ACCOUNT_SECRET` `OCM_SERVICE_ACCOUNT_SECRET`	5.0	string		The service account secret.
`OCIS_EVENTS_ENDPOINT` `OCM_EVENTS_ENDPOINT`	pre5.0	string	127.0.0.1:9233	The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture.
`OCIS_EVENTS_CLUSTER` `OCM_EVENTS_CLUSTER`	pre5.0	string	ocis-cluster	The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Mandatory when using NATS as event system.
`OCIS_INSECURE` `OCM_EVENTS_TLS_INSECURE`	pre5.0	bool	false	Whether to verify the server TLS certificates.
`OCIS_EVENTS_TLS_ROOT_CA_CERTIFICATE` `OCM_EVENTS_TLS_ROOT_CA_CERTIFICATE`	pre5.0	string		The root CA certificate used to validate the server’s TLS certificate. If provided OCM_EVENTS_TLS_INSECURE will be seen as false.
`OCIS_EVENTS_ENABLE_TLS` `OCM_EVENTS_ENABLE_TLS`	pre5.0	bool	false	Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services.
`OCIS_EVENTS_AUTH_USERNAME` `OCM_EVENTS_AUTH_USERNAME`	5.0	string		The username to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.
`OCIS_EVENTS_AUTH_PASSWORD` `OCM_EVENTS_AUTH_PASSWORD`	5.0	string		The password to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.
`OCIS_JWT_SECRET` `OCM_JWT_SECRET`	pre5.0	string		The secret to mint and validate jwt tokens.
`OCIS_REVA_GATEWAY`	pre5.0	string	com.owncloud.api.gateway	The CS3 gateway endpoint.
`OCIS_GRPC_CLIENT_TLS_MODE`	pre5.0	string		TLS mode for grpc connection to the go-micro based grpc services. Possible values are 'off', 'insecure' and 'on'. 'off': disables transport security for the clients. 'insecure' allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server certificate verification.
`OCIS_GRPC_CLIENT_TLS_CACERT`	pre5.0	string		Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services.
`OCM_OCMD_PREFIX`	5.0	string	ocm	URL path prefix for the OCMD service. Note that the string must not start with '/'.
`OCM_OCMD_EXPOSE_RECIPIENT_DISPLAY_NAME`	5.0	bool	false	Expose the display name of OCM share recipients.
`OCM_SCIENCEMESH_PREFIX`	5.0	string	sciencemesh	URL path prefix for the ScienceMesh service. Note that the string must not start with '/'.
`OCM_MESH_DIRECTORY_URL`	5.0	string		URL of the mesh directory service.
`OCM_OCM_INVITE_MANAGER_DRIVER`	5.0	string	json	Driver to be used to persist OCM invites. Supported value is only 'json'.
`OCM_OCM_INVITE_MANAGER_JSON_FILE`	5.0	string	/var/lib/ocis/storage/ocm/ocminvites.json	Path to the JSON file where OCM invite data will be stored. This file is maintained by the instance and must not be changed manually. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage/ocm.
`OCM_OCM_INVITE_MANAGER_TOKEN_EXPIRATION`	6.0.1	Duration	24h0m0s	Expiry duration for invite tokens.
`OCM_OCM_INVITE_MANAGER_TIMEOUT`	6.0.1	Duration	30s	Timeout specifies a time limit for requests made to OCM endpoints.
`OCM_OCM_INVITE_MANAGER_INSECURE`	5.0	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
`SHARING_OCM_PROVIDER_AUTHORIZER_DRIVER`	5.0	string	json	Driver to be used to persist ocm invites. Supported value is only 'json'.
`OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE`	5.0	string	/etc/ocis/ocmproviders.json	Path to the JSON file where ocm invite data will be stored. Defaults to $OCIS_CONFIG_DIR/ocmproviders.json.
`OCM_OCM_PROVIDER_AUTHORIZER_VERIFY_REQUEST_HOSTNAME`	5.0	bool	true	Verify the hostname of the incoming request against the hostname of the OCM provider.
`OCM_OCM_SHARE_PROVIDER_DRIVER`	5.0	string	json	Driver to be used for the OCM share provider. Supported value is only 'json'.
`OCM_OCM_SHAREPROVIDER_JSON_FILE`	5.0	string	/var/lib/ocis/storage/ocm/ocmshares.json	Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage.
`OCM_OCM_SHARE_PROVIDER_INSECURE`	5.0	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
`OCM_WEBAPP_TEMPLATE`	5.0	string		Template for the webapp url.
`OCM_OCM_CORE_DRIVER`	5.0	string	json	Driver to be used for the OCM core. Supported value is only 'json'.
`OCM_OCM_CORE_JSON_FILE`	5.0	string	/var/lib/ocis/storage/ocm/ocmshares.json	Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage.
`OCM_OCM_STORAGE_PROVIDER_INSECURE`	5.0	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
`OCM_OCM_STORAGE_PROVIDER_STORAGE_ROOT`	5.0	string	/var/lib/ocis/storage/ocm	Directory where the ocm storage provider persists its data like tus upload info files.

YAML Example

Note the file shown below must be renamed and placed in the correct folder according to the Configuration File Naming conventions to be effective.
See the Notes for Environment Variables if you want to use environment variables in the yaml file.

master + Rolling 6.6.0

# Autogenerated
# Filename: ocm-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9281
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:9280
  protocol: tcp
  prefix: ""
  cors:
    allow_origins:
    - https://localhost:9200
    allow_methods:
    - OPTIONS
    - HEAD
    - GET
    - PUT
    - POST
    - DELETE
    - MKCOL
    - PROPFIND
    - PROPPATCH
    - MOVE
    - COPY
    - REPORT
    - SEARCH
    allow_headers:
    - Origin
    - Accept
    - Content-Type
    - Depth
    - Authorization
    - Ocs-Apirequest
    - If-None-Match
    - If-Match
    - Destination
    - Overwrite
    - X-Request-Id
    - X-Requested-With
    - Tus-Resumable
    - Tus-Checksum-Algorithm
    - Upload-Concat
    - Upload-Length
    - Upload-Metadata
    - Upload-Defer-Length
    - Upload-Expires
    - Upload-Checksum
    - Upload-Offset
    - X-HTTP-Method-Override
    - Cache-Control
    allow_credentials: false
middleware:
  auth:
    credentials_by_user_agent: {}
grpc:
  addr: 127.0.0.1:9282
  tls: null
  protocol: ""
grpc_client_tls: null
service_account:
  service_account_id: ""
  service_account_secret: ""
token_manager:
  jwt_secret: ""
reva:
  address: com.owncloud.api.gateway
  tls:
    mode: ""
    cacert: ""
ocmd:
  prefix: ocm
  expose_recipient_display_name: false
sciencemesh:
  prefix: sciencemesh
  science_mesh_directory_url: ""
ocm_invite_manager:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocminvites.json
  token_expiration: 24h0m0s
  timeout: 30s
  insecure: false
ocm_provider_authorizer_driver: json
ocm_provider_authorizer_drivers:
  json:
    providers: /etc/ocis/ocmproviders.json
    verify_request_hostname: true
ocm_share_provider:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocmshares.json
  insecure: false
  webapp_template: ""
ocm_core:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocmshares.json
ocm_storage_provider:
  insecure: false
  storage_root: /var/lib/ocis/storage/ocm