Merge branch 'f-documentation-server-conf' into f-more-sql-benchmarking

conf/core/server.conf

+# Set the timezone of the server
+# e.g. TIMEZONE=Europe/Berlin or TIMEZONE=UTC.
+# Leaving this empty means that the server assumes the timezone of the host.
 TIMEZONE=
+# Set the name of the server owner
+# e.g: SERVER_OWNER=XY Department
 SERVER_OWNER=
+# Name of this CaosDB Server
 SERVER_NAME=CaosDB Server
+
+# --------------------------------------------------
+# The following paths are relative to the working directory of the server.
+# --------------------------------------------------
+
+# The location of the server side scripting binaries.
+# Put your executable python scripts here, if they need to be called from the scripting API.
 SERVER_SIDE_SCRIPTING_BIN_DIR=./scripting/bin/
+
+# Working directory of the server side scripting API.
+# On execution of binaries and scripts the server will create a corresponding working directory in this folder.
 SERVER_SIDE_SCRIPTING_WORKING_DIR=./scripting/working/
+
+# Home directories of the server side scripting API.
+# Specific config files, pip packages or other prerequisites for running a script or binary
+# can go into a specific home directory for the respective script within this folder.
 SERVER_SIDE_SCRIPTING_HOME_DIR=./scripting/home/
+
+# The CaosDB file system root.
+# The file hierarchy of CaosDB's internal file system starts at this folder.
+# An absolute file path of File objects within CaosDB is relative to this folder.
 FILE_SYSTEM_ROOT=./CaosDBFileSystem/FileSystemRoot/
+
+# Path to the drop off box.
+# This is were users can place files that should be picked up by the CaosDB drop off box program.
 DROP_OFF_BOX=./CaosDBFileSystem/DropOffBox/
+
+# Location of temporary files
+# All temporary files with the exception of files created by the scripting API will go into this folder.
 TMP_FILES=./CaosDBFileSystem/TMP/
+
+# Shared folder
+# Additional folder for longer term storage of scripting API output.
+# In contrast to the script's working directory, these subdirectories are publicly accessible.
 SHARED_FOLDER=./CaosDBFileSystem/Shared/
+
+# Path to the chown script which is needed by the drop off box in order to change permissions of files.
 CHOWN_SCRIPT=./misc/chown_script/caosdb_chown_dropoffbox
+
+# This file is responsible for setting individual user and group permissions.
 USER_SOURCES_INI_FILE=./conf/ext/usersources.ini
+# The default state of users which are added to the internal user source.
 NEW_USER_DEFAULT_ACTIVITY=INACTIVE
+# If set to true, unauthenticated access to the database is possible with an anonymous user.
 AUTH_OPTIONAL=FALSE
 
+# --------------------------------------------------
+# MySQL settings
+# --------------------------------------------------
+# Hostname of the mysql instance used by CaosDB
 MYSQL_HOST=localhost
+# Port of the mysql instance
 MYSQL_PORT=3306
+# Database name of the mysql database
 MYSQL_DATABASE_NAME=caosdb
+# User name for connecting to mysql
 MYSQL_USER_NAME=caosdb
+# Password for the user
 MYSQL_USER_PASSWORD=caosdb
-
+# Schema of mysql procedures and tables which is required by this CaosDB instance
 MYSQL_SCHEMA_VERSION=v2.1.1
 
-CONTEXT_ROOT=
 
+# --------------------------------------------------
+# Server options
+# --------------------------------------------------
+# The context root is a prefix which allows running multiple instances of CaosDB using the same
+# hostname and port.
+CONTEXT_ROOT=
+# HTTPS port of this server instance.
 SERVER_PORT_HTTPS=443
+# HTTP port of this server instance.
 SERVER_PORT_HTTP=80
 
+# Initial number of HTTPConnection objects in the pool.
+INITIAL_CONNECTIONS=1
+# Maximum number of parallel HTTPConnections of the server
+MAX_CONNECTIONS=10
+
+
+# --------------------------------------------------
+# HTTPS options
+# --------------------------------------------------
+# Allowed TLS versions
 HTTPS_ENABLED_PROTOCOLS=TLSv1.3 TLSv1.2
+# Forbidden TLS versions
 HTTPS_DISABLED_PROTOCOLS=SSLv3 SSLv2Hello TLSv1.1 TLSv1.0
+# Allowed cipher suites which are used for the encryption of the HTTP payload.
 HTTPS_ENABLED_CIPHER_SUITES=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_CCM_SHA256 TLS_AES_128_CCM_8_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
+# Forbidden cipher suites which are used for the encryption of the HTTP payload.
 HTTPS_DISABLED_CIPHER_SUITES=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHASSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_RC4_128_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
 
-INITIAL_CONNECTIONS=1
+# Password for the private key for the HTTPS server.
+CERTIFICATES_KEY_PASSWORD=
+# Path to the keystore which typically ends in jks.
+CERTIFICATES_KEY_STORE_PATH=
+# Password of the keystore which stores the private key.
+CERTIFICATES_KEY_STORE_PASSWORD=
 
-MAX_CONNECTIONS=10
+# --------------------------------------------------
+# Timeout settings
+# --------------------------------------------------
 
+# The session timeout after which the cookie expires.
 # 10 min
 SESSION_TIMEOUT_MS=600000
+
+# Time after which activation tokens for the activation of new users (internal
+# user sources) expire.
 # 7days
 ACTIVATION_TIMEOUT_MS=604800000
 
+# The value for the HTTP cache directive "max-age"
+WEBUI_HTTP_HEADER_CACHE_MAX_AGE=28800
+
+# --------------------------------------------------
+# Mail settings
+# --------------------------------------------------
+# The handler that treats sent mails.
+# The default handler pipes mails to a file.
 MAIL_HANDLER_CLASS=caosdb.server.utils.mail.ToFileHandler
+# The file were the ToFileHanlder pipes messages to.
 MAIL_TO_FILE_HANDLER_LOC=./
 
+# --------------------------------------------------
+# Admin settings
+# # --------------------------------------------------
+# Name of the administrator of this instance
 ADMIN_NAME=CaosDB Admin
+# Email of the administrator of this instance
 ADMIN_EMAIL=
+# An URL to the bugtracker for managing instance related bugs.
 BUGTRACKER_URI=
 
+# If set to true MySQL stores transaction benchmarks for all SQL queries. Used for benchmarking and debugging.
 TRANSACTION_BENCHMARK_ENABLED=true
+# Location of the configuration file for the CaosDB cache.
 CACHE_CONF_LOC=./conf/core/cache.ccf
+# Set this option to true to lobally disable caching. Used for debugging.
 CACHE_DISABLE=false
 
+# The server is allowed to create symlinks to files and folders within this whitelist of directories.
 INSERT_FILES_IN_DIR_ALLOWED_DIRS=
 
+# Sudo password of the system.
+# Needed by the drop off box to set file permissions.
 SUDO_PASSWORD=
+
+# If set to false ACL checks are circumvented during querying. This may leak information but is a lot faster.
 QUERY_FILTER_ENTITIES_WITHOUT_RETRIEVE_PERMISSIONS=TRUE
 
+# When checking the ACL of an entity roles which are unknown to the server
+# raise an error (when set to MUST) or a warning (when set to SHOULD).
+# Unknown roles occur when a user or group is removed or when entities are
+# loaded from other instances of the CaosDB Server where different users are
+# present.
+# CHECK_ENTITY_ACL_ROLES_MODE=[MUST,SHOULD]
 CHECK_ENTITY_ACL_ROLES_MODE=MUST
 
+# Location of the global ACL file for entities. The global ACL is implicitly
+# part of any Entity ACL.
 GLOBAL_ENTITY_PERMISSIONS_FILE=./conf/core/global_entity_permissions.xml
 
-CERTIFICATES_KEY_PASSWORD=
-CERTIFICATES_KEY_STORE_PATH=
-CERTIFICATES_KEY_STORE_PASSWORD=
-
-WEBUI_HTTP_HEADER_CACHE_MAX_AGE=28800