Cluster Configuration Settings

A DFS cluster is configured in two places: file.ini for Exponential itself, and the CLUSTER_* constants of config.php for index_cluster.php, the script that serves clustered files to browsers. Both must name the same database and mount on every web server.

file.ini

Put the cluster settings in the global override settings/override/file.ini.append.php. They are read before extensions and siteaccesses, so an extension or siteaccess override is not used.

[ClusteringSettings]
# eZFSFileHandler (default, one server) or eZDFSFileHandler (several servers)
FileHandler=eZDFSFileHandler
# what a process does when a cache file is being generated by another process and no
# expired copy exists: wait (default) or generate (generate its own, without storing it)
NonExistantStaleCacheHandling[viewcache]=wait
NonExistantStaleCacheHandling[cacheblock]=wait
NonExistantStaleCacheHandling[misc]=wait

[eZDFSClusteringSettings]
# the NFS mount, the same path on every server
MountPointPath=/mnt/exponential-dfs
# the metadata backend (see below)
DBBackend=eZDFSFileHandlerMySQLiBackend
# the class that reads and writes the files on the mount
DFSBackend=eZDFSFileHandlerDFSBackend
DBHost=db.example.com
DBPort=3306
DBSocket=
DBName=cluster
DBUser=cluster
DBPassword=secret
# retries of the connection, of a statement, and of a copy from the mount
DBConnectRetries=3
DBExecuteRetries=20
MaxCopyRetries=5

DBBackend is eZDFSFileHandlerMySQLiBackend (kernel, MySQL and MariaDB), eZDFSFileHandlerPostgresqlBackend (package ezpostgresqlcluster) or eZDFSFileHandlerOracleBackend (extension ezoracle). DFSBackend can name your own class implementing eZDFSFileHandlerDFSBackendInterface, for storage other than a mounted directory.

[ClusteringSettings] ExtensionDirectories[] (handlers in extensions) is deprecated.

[PassThroughSettings]

How clustered binary files are sent: as a download (attachment, the default) or shown in the browser (inline), per MIME type:

[PassThroughSettings]
DefaultContentDisposition=attachment
ContentDisposition[video/mp4]=inline

[ClusterEventsSettings]

ClusterEvents=disabled by default. With a listener class, an extension can react to cluster operations (DFS with the MySQLi backend only).

config.php: the constants of index_cluster.php

index_cluster.php reads config.php and, when it exists, config.cluster.php. Without CLUSTER_STORAGE_BACKEND it answers 500. The constants, with the values index_cluster.php uses when one is not set:

define( 'CLUSTER_STORAGE_BACKEND', 'dfsmysqli' );   // required: kernel/clustering/<backend>.php
define( 'CLUSTER_STORAGE_HOST', 'db.example.com' );
define( 'CLUSTER_STORAGE_PORT', 3306 );
define( 'CLUSTER_STORAGE_USER', 'cluster' );         // default ''
define( 'CLUSTER_STORAGE_PASS', 'secret' );          // default ''
define( 'CLUSTER_STORAGE_DB', 'cluster' );           // default ''
define( 'CLUSTER_MOUNT_POINT_PATH', '/mnt/exponential-dfs' );
define( 'CLUSTER_ENABLE_HTTP_RANGE', true );         // default true
define( 'CLUSTER_ENABLE_HTTP_CACHE', true );         // default true
define( 'CLUSTER_EXPIRY_TIMEOUT', 86400 );           // default 86400 seconds
define( 'CLUSTER_PERSISTENT_CONNECTION', false );    // default false
define( 'CLUSTER_ENABLE_DEBUG', false );             // default false
define( 'CLUSTER_HEADER_X_POWERED_BY', 'Exponential' );

Set them from the console rather than by hand. Each set shows a diff, writes only with --apply, backs config.php up to var/backup/config/<time>/ and checks the result with php -l:

./console exp:config:set CLUSTER_STORAGE_BACKEND dfsmysqli --apply
./console exp:config:set CLUSTER_STORAGE_HOST db.example.com --apply
./console exp:config:set CLUSTER_STORAGE_PASS --value="$CLUSTER_DB_PASS" --apply
./console exp:config:set CLUSTER_MOUNT_POINT_PATH /mnt/exponential-dfs --apply
# what config.php sets now; passwords show as ********
./console exp:config:list --only-set

Keep config.php, config.cluster.php and settings/override/file.ini.append.php out of version control: they hold database credentials.

Related pages

• Setting it up for an eZDFSFileHandler
• Setting up .htaccess and config.php from the console
• file.ini