Configuration
CKFinder 3 comes with two configuration files:
ckfinder.yml
– A server-side configuration file, explained in this article.config.js
– An optional client-side configuration file, explained in the API documentation article about setting the JavaScript configuration.
By default, the CKFinder 3 for Java connector searches the application’s resources directory for a file named ckfinder.yml
.
The template of this configuration file can be found here.
If you would like to load the configuration from any other location, refer to the Loading configuration from a custom location tutorial.
The following options can be set in the ckfinder.yml
file:
Option name | Type | Description |
---|---|---|
accessControl |
sequence |
Access Control Lists (ACL) to grant users different permissions for working with CKFinder folders and files based on user roles. |
backends |
sequence |
Backends configuration where all types of storage that CKFinder should support must be defined (e.g. the target path on a local file system; Amazon S3 account credentials). |
cache |
mapping |
Configures cache lifetime for various CKFinder components. |
checkSizeAfterScaling |
boolean |
Whether to check the file size of images before or after scaling for the maximum allowed dimensions. |
csrfProtection |
boolean |
Enables CSRF protection in the connector. |
extraHeaders |
mapping |
HTTP headers to be added to every connector response. |
images |
mapping |
The image configuration, like maximum allowed width and height. |
licenseKey |
string |
The CKFinder license key. If invalid, CKFinder will run in Demo mode. |
licenseName |
string |
The CKFinder license name. If invalid, CKFinder will run in Demo mode. |
privateDir |
mapping |
The private directory location and settings. |
resourceTypes |
sequence |
The resource types handled in CKFinder. Each resource type is represented as a “root” folder in CKFinder (e.g. Files and Images) and points to a specific folder of the configured backend. |
roleSessionAttribute |
string |
The session variable name that CKFinder must use to retrieve the “role” of the current user. |
secureImageUploads |
boolean |
Whether to perform additional checks when uploading image files. |
serveStaticResources |
boolean |
Whether the CKFinder’s servlet should serve the static resources used by the CKFinder frontend (JavaScript and HTML files, CSS styles, etc.). |
thumbnails |
mapping |
Internal thumbnails configuration. |
# Configuration options
# accessControl
Access Control List (ACL) is a feature that grants your users different permissions for working with CKFinder folders and files. The default settings placed in the config.php
file grant full permissions for all options to every user.
# Access Control List syntax
accessControl:
- role: '*'
resourceType: '*'
folder: /
FOLDER_VIEW: true
FOLDER_CREATE: true
FOLDER_RENAME: true
FOLDER_DELETE: true
FILE_VIEW: true
FILE_CREATE: true
FILE_RENAME: true
FILE_DELETE: true
IMAGE_RESIZE: true
IMAGE_RESIZE_CUSTOM: true
Access Control List entries are defined using the following values:
Option name | Type | Description |
---|---|---|
role |
string |
The role (see roleSessionAttribute ) of the user for whom the ACL setting is provided. By default it is set to * (asterisk) which means “everybody”. |
resourceType |
string |
The name of the resource type (see resourceTypes ). By default it is set to * (asterisk) which means “all resource types”. |
folder |
string |
The folder where the restrictions will be used. By default it is set to / (slash) which means “the root folder of a resource type”. |
FOLDER_VIEW |
boolean |
Whether the user can view the list of files. |
FOLDER_CREATE |
boolean |
Whether the user can create a folder. |
FOLDER_RENAME |
boolean |
Whether the user can rename a folder. |
FOLDER_DELETE |
boolean |
Whether the user can delete a folder. |
FILE_VIEW |
boolean |
Whether the user can view the file content. |
FILE_CREATE |
boolean |
Whether the user can create (e.g. upload) files. |
FILE_RENAME |
boolean |
Whether the user can rename files. |
FILE_DELETE |
boolean |
Whether the user can delete files. |
IMAGE_RESIZE |
boolean |
Whether, when choosing the image, the user can resize it to dimensions predefined in the configuration file. |
IMAGE_RESIZE_CUSTOM |
boolean |
Whether, when choosing the image, the user can resize it to any dimensions. |
Note: The IMAGE_RESIZE
and IMAGE_RESIZE_CUSTOM
options correspond to the Choose Resized feature which automatically creates a resized version of the chosen image. They do not affect resizing of the image modified in the CKFinder’s image editor (Edit feature).
It is possible to define numerous ACL entries. All attributes are optional. Subfolders inherit their default settings from their parents’ definitions.
# About the folder
option
It is important to understand what the folder
entry means. In the ACL definition the folder
is a path relative to the resource type location. This is not an absolute path to a folder on the server.
Example
If the Files
resource type points to /home/joe/www/example.com/userfiles/files/
, then ACL defined for folder /documents
in the Files
resource type will be applied to /home/joe/www/example.com/userfiles/files/documents/
.
# Access Control List examples
Take a look at the following examples that present various permission configurations in order to learn more about using Access Control Lists in CKFinder.
Example 1
Disallowing file operations in the /Logos
folder of the Images
resource type.
To restrict the upload, renaming, or deletion of files in the Logos
folder of the Images
resource type, use the following ACL settings:
accessControl:
- role: '*'
resourceType: 'Images'
folder: '/Logos'
FOLDER_VIEW: true
FOLDER_CREATE: true
FOLDER_RENAME: true
FOLDER_DELETE: true
FILE_VIEW: true
FILE_CREATE: false
FILE_RENAME: false
FILE_DELETE: false
IMAGE_RESIZE: true
IMAGE_RESIZE_CUSTOM: true
Note: This example only refers to file operations in the /Logos
folder. It does not restrict operations on folders, so the user can still delete or rename it. In order to limit the users’ ability to modify the folder itself (not its content), you should change the folder permissions as well.
Example 2
Making the /Logos
folder fully read-only for all resource types.
To restrict the upload, renaming, or deletion of files as well as creation, renaming and deletion of folders in the /Logos
folder (including the /Logos
folder itself) in all resource types (*
), use the following ACL settings:
accessControl:
- role: '*'
resourceType: '*'
folder: '/Logos'
FOLDER_VIEW: true
FOLDER_CREATE: false
FOLDER_RENAME: false
FOLDER_DELETE: false
FILE_VIEW: true
FILE_CREATE: false
FILE_RENAME: false
FILE_DELETE: false
IMAGE_RESIZE: false
IMAGE_RESIZE_CUSTOM: false
With such permissions the user will not even have the rights to create resized versions of existing images with the Choose Resized feature.
Example 3
As permissions are inherited by subfolders, it is enough to define permissions that will be further modified by ACL entries.
The default setting in CKFinder allows everyone to do everything:
accessControl:
- role: '*'
resourceType: '*'
folder: '/'
FOLDER_VIEW: true
FOLDER_CREATE: true
FOLDER_RENAME: true
FOLDER_DELETE: true
FILE_VIEW: true
FILE_CREATE: true
FILE_RENAME: true
FILE_DELETE: true
IMAGE_RESIZE: true
IMAGE_RESIZE_CUSTOM: true
It means that to forbid any folder operations apart from viewing you can set:
accessControl:
- role: '*'
resourceType: '*'
folder: '/'
FOLDER_CREATE: false
FOLDER_RENAME: false
FOLDER_DELETE: false
without having to repeat all entries set to true
.
# backends
Backends are used in resource type definitions as a definition of the storage where files should be located. Although backends and resource types are strictly related, they are defined separately to simplify the configuration in a situation where e.g. the same S3 account is used to define four different resource types, where the only difference is the name of a subfolder on the S3 bucket.
Example
An example of a connection between a backend defined as default
and two resource types:
backends:
- name: 'default'
adapter: 'local'
baseUrl: 'http://example.com/userfiles'
root: '/path/to/userfiles'
disallowUnsafeCharacters: true
forceAscii: false
hideFolders: ['.*', 'CVS', '__thumbs']
hideFiles: ['.*']
htmlExtensions: ['html', 'htm', 'xml', 'js']
overwriteOnUpload: false
useProxyCommand: false
resourceTypes:
- name: 'Files'
backend: 'default'
directory: '/files' # = /path/to/userfiles/files
allowedExtensions: pdf,zip,doc,xls,mp3,txt,jpg,png,bmp,gif
deniedExtensions: ~
maxSize: 0
- name: 'Images'
backend: 'default'
directory: '/images' # = /path/to/userfiles/images
allowedExtensions: bmp,jpeg,jpg,png
deniedExtensions: ~
maxSize: 0
# Common configuration options
The set of options listed below can be used with any backend type.
Option name | Type | Description |
---|---|---|
name |
string |
The unique name of the backend. |
adapter |
string |
The type of adapter used by this backend — local for a local file system. |
root |
string |
The file system path to the directory with CKFinder users’ files. This directory must exist on the server. |
baseUrl optional |
string |
The base URL used for direct access to CKFinder files. This URL must correspond to the directory where CKFinder users’ files are stored. |
useProxyCommand optional |
boolean |
Whether the links to files stored on this backend should be pointing to the Proxy command. |
forceAscii optional |
boolean |
Forces ASCII names for files and folders. If enabled, characters with accent marks, like å , ä , ö , ć , č , đ or š will be automatically converted to their ASCII counterparts. |
overwriteOnUpload optional |
boolean |
Changes the default behavior of CKFinder when uploading a file with a name that already exists in a folder. If enabled, then instead of auto renaming files, the existing files will be overwritten. |
checkDoubleExtension optional |
boolean |
Whether to allow for files with double file extension. Due to security issues with Apache modules it is recommended to leave checkDoubleExtension enabled. If checkDoubleExtension is enabled, each part of the file name after the dot is checked, not only the last part. If an extension is disallowed, the dot (. ) is replaced with an underscore (_ ). If, for example, the rar extension is allowed and the php extension is forbidden, the uploaded foo.php.rar file will be renamed into foo_php.rar . |
disallowUnsafeCharacters optional |
boolean |
Disallows creating folders and uploading files whose names contain characters that are not safe in a Windows environment. |
hideFolders optional |
sequence |
Folders that are not to be displayed in CKFinder, no matter their location. |
hideFiles optional |
sequence |
Files that are not to be displayed in CKFinder. |
htmlExtensions optional |
sequence |
The types of files that may allow for HTML code in the first 1kB of their data. CKFinder will upload the file with the HTML code only when the file extension is specified in htmlExtensions . |
fileSystemOptions optional |
mapping |
The file system specific configuration options (e.g. access credentials). |
# useProxyCommand
The useProxyCommand
configuration is a powerful option that allows to serve any files stored in CKFinder. Creating links to files for your web page may be difficult, or even impossible in some cases (for example when the files are stored on a private FTP server, or are not in the web server root folder). Enabling this option for a backend tells CKFinder to create links to files using the Proxy
command.
Serving files this way has the following advantages:
- The files do not need to be publicly accessible with direct links. You do not have to change your storage configuration to make files accessible for anonymous users.
- Better control over access to files. You can use CKFinder ACL options to define more strict access rights to files (see the
accessControl
configuration option). - Easier control over client-side caching rules. Using the
cache
configuration option you can define for how long the file served by theProxy
command should be cached in the browser.
The disadvantage of this approach is that all links to files will be dependent on the CKFinder connector, so if you decide to remove CKFinder one day, the links will simply stop working.
# hideFolders
Folders that are not to be displayed in CKFinder for a given backend. No paths are accepted, only folder names.
The *
(asterisk) and ?
(question mark) wildcards are accepted. *
matches any number of characters, ?
matches exactly one character.
Example
Hide all folders that start with a dot character and two additional folders: CVS
and __thumbs
.
backends:
- name: 'default'
adapter: 'local'
baseUrl: 'http://example.com/userfiles'
root: '/path/to/userfiles'
hideFolders: ['.*', 'CVS', '__thumbs']
# hideFiles
Files that are not to be displayed in CKFinder for a given backend. No paths are accepted, only file names, including the extension.
The *
(asterisk) and ?
(question mark) wildcards are accepted. *
matches any number of characters, ?
matches exactly one character.
Example
Hide all files that start with a dot character.
backends:
- name: 'default'
adapter: 'local'
baseUrl: 'http://example.com/userfiles'
root: '/path/to/userfiles'
hideFiles: ['.*']
# Supported backends
The CKFinder 3 for Java connector uses a NIO.2 file system abstraction layer (JSR-203), which allows to use many different file systems transparently.
Below you can find a list of supported backends with their configuration options.
# Local file system
This is the default backend in CKFinder which points to a folder in the local file system of the server.
Example
An example of a local file system backend configuration, and the connection between the backend defined as default
and two resource types:
backends:
- name: 'default'
adapter: 'local'
baseUrl: 'http://example.com/userfiles'
root: '/path/to/userfiles'
disallowUnsafeCharacters: true
forceAscii: false
hideFolders: ['.*', 'CVS', '__thumbs']
hideFiles: ['.*']
htmlExtensions: ['html', 'htm', 'xml', 'js']
overwriteOnUpload: false
useProxyCommand: false
resourceTypes:
- name: 'Files'
backend: 'default'
directory: '/files' # = /path/to/userfiles/files
allowedExtensions: pdf,zip,doc,xls,mp3,txt,jpg,png,bmp,gif
deniedExtensions: ~
maxSize: 0
- name: 'Images'
backend: 'default'
directory: '/images' # = /path/to/userfiles/images
allowedExtensions: bmp,jpeg,jpg,png
deniedExtensions: ~
maxSize: 0
# Amazon S3
Coming in future versions of CKFinder for Java.
# cache
Configures cache lifetime for various CKFinder components:
imagePreview
– Cache lifetime for images returned by theImagePreview
command.thumbnails
– Cache lifetime for thumbnail images.proxyCommand
– Cache lifetime for files served by theProxy
command.
The lifetime is defined as an integer representing the number of seconds. If the value provided
is not a positive number larger than 0, the cache for a component will be disabled.
Example
cache:
imagePreview: 86400 # 24 * 3600 (24h)
thumbnails: 31536000 # 24 * 3600 * 365 (1 year)
proxyCommand: 0
# checkSizeAfterScaling
Indicates that the file size of uploaded images must be checked against the maxSize
setting defined in the resource type configuration only after scaling down (when needed). Otherwise, the size is checked right after uploading.
Example
checkSizeAfterScaling: true
# csrfProtection
Enables CSRF protection in the connector. The default CSRF protection mechanism is based on double submit cookies.
Example
csrfProtection: true
# extraHeaders
Extra HTTP headers that should be added to every connector response.
Example
extraHeaders:
'Access-Control-Allow-Origin': '*'
'Access-Control-Allow-Credentials': 'true'
# images
Image configuration for CKFinder.
# Configuration options
Option name | Type | Description |
---|---|---|
maxWidth |
integer |
The maximum width of uploaded images. If the image size is bigger than the one specified, the image will be resized to the defined dimensions. |
maxHeight |
integer |
The maximum height of uploaded images. If the image size is bigger than the one specified, the image will be resized to the defined dimensions. |
quality |
integer |
The quality of created images in a range from 1 to 100. The smaller the quality value, the smaller the size of resized images. Note that an acceptable quality value is about 80-90. |
sizes |
mapping |
Predefined sizes of images that can be easily selected from CKFinder and passed to an external application (e.g. CKEditor) without having to resize the image manually. The keys of the mapping are translated and used as entries in the “Select Thumbnail” context menu. The translated label for a particular entry is taken from the language files, for example small will be translated as lang.image[‘small’] . If a translation key is not set for the current language, an English version is used. If an English version was not found, an untranslated string is used (with the first letter set to uppercase). |
Example
images:
maxWidth: 1600
maxHeight: 1200
quality: 80
sizes:
small:
width: 480
height: 320
quality: 80
medium:
width: 600
height: 480
quality: 80
large:
width: 800
height: 600
quality: 80
# licenseKey
CKFinder license key. If invalid, CKFinder will run in Demo mode.
Example
licenseKey: 'ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ12'
# licenseName
CKFinder license name. If invalid, CKFinder will run in Demo mode.
Example
licenseName: 'example.com'
# privateDir
Internal directories configuration.
Important: CKFinder needs to access these directories frequently, so it is recommended to keep this folder on a local file system.
Option name | Type | Description |
---|---|---|
backend |
string |
The backend where the private directory should be located. |
path |
string |
An internal backend-relative path for the private directory. |
data optional |
string |
An internal folder for storing metadata for files. By default it is located in the cache/data folder. |
thumbs optional |
string |
A folder for internal thumbnails (image previews). By default it is located in the cache/thumbs folder. |
Example
Setting the private directories location to the .ckfinder
folder inside the default
backend.
privateDir:
backend: 'default'
path: '.ckfinder/'
# resourceTypes
Resource type is nothing more than a way to group files under different paths, each one having different configuration settings. Resource types are represented in CKFinder as “root folders”. Each resource type may use a different backend.
By default the CKFinder configuration file comes with two sample resource types configured: Files
and Images
. There are no restrictions on the maximum number of resource types configured. You can change or remove the default ones, but make sure to configure at least one resource type.
# Configuration options
Option name | Type | Description |
---|---|---|
name |
string |
A machine-friendly name of the resource type that will be used for the communication between the CKFinder UI and the server connector. |
label |
string |
A human-friendly name of the resource type that will be used as the “root folder” name in the CKFinder UI. |
backend |
string |
The name of the backend where this resource type should point to. |
directory optional |
string |
The path to the backend subfolder where the resource type should point exactly. |
maxSize optional |
string |
The maximum size of the uploaded file defined in bytes. |
allowedExtensions |
string |
The file extensions you wish to be allowed for upload with CKFinder. The NO_EXT value can be used for files without an extension. |
deniedExtensions optional |
string |
The file extensions you do not wish to be uploaded with CKFinder. It should only be set if allowedExtensions is left empty. The NO_EXT value can be used for files without an extension. |
lazyLoaded optional |
boolean |
If set to true , the Init command will not check if the resource type contains child folders. This option is especially useful for remote backends, as the Init command will be executed faster, and therefore CKFinder will start faster, too. It is recommended to set it to true for remote backends. |
Important: It is recommended to always use the allowedExtensions
setting, in favor of deniedExtensions
. If you leave allowedExtensions
empty and add an extension to the deniedExtensions
list, for example pdf
, the settings will allow the upload of all other files except the files with the pdf
extension (e.g. .php
or .exe
files).
Example
A simple resource type definition where the label
was set to a French equivalent of Files
. The name
(machine-name) set to Files
can be used when integrating CKFinder with CKEditor.
resourceTypes:
- name: 'Files'
label: 'Fichiers'
backend: 'default'
directory: '/files/'
maxSize: 8388608 # 8 MB
allowedExtensions: 'doc,gif,jpg,pdf,png,zip'
# roleSessionAttribute
The HttpSession
attribute name that CKFinder must use to retrieve the role of the current user.
Example
roleSessionAttribute: 'CKFinder_UserRole'
The role
can be used to set the ACL settings.
Example
Set read-only permission for all users, but allow users with the administrator
role for full access:
accessControl:
- role: '*'
resourceType: '*'
folder: /
FOLDER_VIEW: true
FOLDER_CREATE: false
FOLDER_RENAME: false
FOLDER_DELETE: false
FILE_VIEW: true
FILE_CREATE: false
FILE_RENAME: false
FILE_DELETE: false
IMAGE_RESIZE: false
IMAGE_RESIZE_CUSTOM: false
- role: 'administrator'
resourceType: '*'
folder: /
FOLDER_VIEW: true
FOLDER_CREATE: true
FOLDER_RENAME: true
FOLDER_DELETE: true
FILE_VIEW: true
FILE_CREATE: true
FILE_RENAME: true
FILE_DELETE: true
IMAGE_RESIZE: true
IMAGE_RESIZE_CUSTOM: true
# secureImageUploads
Whether to perform additional checks when uploading image files.
Sometimes a user can try to upload a file which is not an image file but appears to be one. Example: You have a text file called document.jpg
and you try to upload it. You can enable the image checking function by setting secureImageUploads
to true
:
Example
secureImageUploads: true
# serveStaticResources
Whether the CKFinder servlet should serve static resources (e.g. JavaScript, CSS, translation files of the CKFinder frontend).
Example
serveStaticResources: true
# thumbnails
Internal thumbnails configuration.
Note: Changing the minimum and maximum value will result in a different slider range in the settings panel of the CKFinder UI.
# Configuration options
Option name | Type | Description |
---|---|---|
enabled |
Boolean | Whether CKFinder should display real thumbnails for image files. |
sizes |
sequence |
Predefined sizes of internal thumbnails that CKFinder is allowed to create. As CKFinder allows for changing the size of thumbnails in the application using a slider, a few predefined sets are used by default to use a small and most efficient size when the user does not need big images (150px), up to 500px when the user prefers bigger images. |
Example
thumbnails:
enabled: true
sizes:
- width: 150
height: 150
quality: 80
- width: 300
height: 300
quality: 80
- width: 500
height: 500
quality: 80
# Configuration file template
By default, the CKFinder 3 for Java connector looks for a file named ckfinder.yml
in the application’s resources directory.
The YAML on the listing below presents a base structure of this configuration file.
# ckfinder.yml
licenseName: ''
licenseKey: ''
roleSessionAttribute: 'CKFinder_UserRole'
serveStaticResources: true
checkSizeAfterScaling: true
secureImageUploads: true
csrfProtection: true
backends:
- name: 'default'
adapter: 'local'
baseUrl: 'http://example.com/userfiles'
root: '/path/to/userfiles'
disallowUnsafeCharacters: true
forceAscii: false
hideFolders: ['.*', 'CVS', '__thumbs']
hideFiles: ['.*']
htmlExtensions: ['html', 'htm', 'xml', 'js']
overwriteOnUpload: false
useProxyCommand: false
resourceTypes:
- name: 'Files'
backend: 'default'
directory: '/files'
allowedExtensions: 7z,aiff,asf,avi,bmp,csv,doc,docx,fla,flv,gif,gz,gzip,jpeg,jpg,mid,mov,mp3,mp4,mpc,mpeg,mpg,ods,odt,pdf,png,ppt,pptx,qt,ram,rar,rm,rmi,rmvb,rtf,sdc,swf,sxc,sxw,tar,tgz,tif,tiff,txt,vsd,wav,wma,wmv,xls,xlsx,zip
deniedExtensions: ~
maxSize: 0
- name: 'Images'
backend: 'default'
directory: '/images'
allowedExtensions: bmp,jpeg,jpg,png
deniedExtensions: ~
maxSize: 0
privateDir:
backend: 'default'
path: '.ckfinder/'
thumbnails:
enabled: true
sizes:
- width: 150
height: 150
quality: 80
- width: 300
height: 300
quality: 80
- width: 500
height: 500
quality: 80
images:
maxWidth: 1600
maxHeight: 1200
quality: 80
sizes:
small:
width: 480
height: 320
quality: 80
medium:
width: 600
height: 480
quality: 80
large:
width: 800
height: 600
quality: 80
cache:
imagePreview: 86400 # 24 * 3600 (24h)
thumbnails: 31536000 # 24 * 3600 * 365 (1 year)
proxyCommand: 0
accessControl:
- role: '*'
resourceType: '*'
folder: /
FOLDER_VIEW: true
FOLDER_CREATE: true
FOLDER_RENAME: true
FOLDER_DELETE: true
FILE_VIEW: true
FILE_CREATE: true
FILE_RENAME: true
FILE_DELETE: true
IMAGE_RESIZE: true
IMAGE_RESIZE_CUSTOM: true