========================
Using blobs with ZEORaid
========================

ZEORaid supports the usage of blobs under different scenarios. This file
describes the various valid and invalid configuration scenarios and documents how
ZEORaid behaves under those conditions.

We split the configuration scenarios in two parts: front end configuration and
back end configuration. Any of the front end configurations can be combined
with all backend configurations.

Valid front end configurations
==============================

Front end configuration describes how blobs are transferred between the ZEO
clients and the ZEORaid server.

No support or no blob support configured
----------------------------------------

The ZEO client does not support blobs or doesn't have blob support configured.
In this case any configuration on the ZEORaid server becomes irrelevant. We
recommend to not configure blob support on the ZEORaid server to avoid
accidental inconsistencies.

Blobs via ZEO protocol
----------------------

The ZEO clients all contain a separate directory as a `cache` for blobs. The
option `shared-blob-dir` is set to `false`. This causes the blobs to be
transferred to and from the ZEORaid server via the ZEO protocol.

Blobs via file system shared with ZEORaid
-----------------------------------------

The ZEO clients are configured with a `blob-dir` that points to a directory
that is shared between all ClientStorages and the RAIDStorage's
`blob-directory` on the ZEORaid server.

The ClientStorages are configured with `shared-blob-dir` set to `true`.


Valid back end configurations
=============================

RAIDStorage and back-ends with a single shared file system
----------------------------------------------------------

The blob directories of RAIDStorage and ClientStorages (on the RAID server)
are configured with a single shared directory that is readable and writable by all
participants.

The `shared-blob-dir` option of the RAIDStorage and the ClientStorages are set
to `true`.


RAIDStorage via storage API and back-ends with individual shared file systems
-----------------------------------------------------------------------------

The RAIDStorage and all ClientStorages have separate blob directories.

The RAIDStorages `shared-blob-dir` option is set to `false`.

Each ClientStorage's blob directory is shared with its ZEO server and their
`shared-blob-dir` options are set to `true`.


RAIDStorage via storage API and back end via ZEO protocol
---------------------------------------------------------

All storages (RAIDStorage, ClientStorages and the ZEO server side) have
separate blob directories.

The RAIDStorage's and ClientStorages' `shared-blob-dir` options are set to
`false`.


Invalid back end configurations
===============================

Mixture of shared and non-shared
--------------------------------

Variation A: The RAIDStorage shares its blob directory with its
ClientStorages, but the ZEOClient do not share their blob-directory with the
backend ZEO servers.

Variation B: The RAIDStorage does not share it's blob directory with its
ClientStorages but the ClientStorages share their blob directory with the
backend ZEO servers.

Warning: ZEORaid can not automatically detect those invalid combinations and
might cause data loss if those combinations are configured.
