CKEditor Ecosystem Documentation
Contribute to this guideReport an issue
Home/CKFinder 3 for Java/Guides

guideConfiguration

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 the Proxy 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 the ImagePreview command.
  • thumbnails – Cache lifetime for thumbnail images.
  • proxyCommand – Cache lifetime for files served by the Proxy 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