configuration.md

Redis Commander - Configuration

This file describes all parameters settable at the configuration files inside the config folder.

Redis Commander uses the node "config" module (https://github.com/lorenwest/node-config) More information about possible file formats and config file names as well as there evaluation order can be found in the wiki of the node-config project.

Configuration data

The entire system can be configured within the json configuration files located below the config/ folder. Some parameters can be set additionally via environment variable and/or command line parameter. Whenever this is possible the name of the environment variable is listed too as well as a flag to show when it can be set as cli parameter (overwriting the config file as well as the environment variable)

1. General Parameter

All top-level configuration data are

Name	Type	Default	Cli	Environment-Var	Description
noSave	boolean	false	--nosave	NOSAVE	do not persist changes in active connection list
noLogData	boolean	false	--no-log-data	NO_LOG_DATA	do not log values of redis keys to console
ui	object				see section 2. User interface parameter
redis	object				see section 3. General Redis connection parameter
server	object				see section 4. Express HTTP Server parameter
connections	list	[]			see section 5. Redis Connections

2. User interface parameter

The ui object contains configuration values regarding the web user interface of Redis Commander.

Name	Type	Default	Cli	Environment-Var	Description
ui.sidebarWidth	number	250			start width in pixel of the tree view on the left side of the ui.
ui.locked	boolean	false			if "true" do not change height of command line, otherwise increase height if cli is active
ui.cliHeight	number	320			start height in pixel of the command line at the bottom (if opened)
ui.cliOpen	boolean	false			start with maximized cli height on "true", with minimized one on "false"
ui.foldingChar	string	':'	--folding-char	FOLDING_CHAR	character to use for creation of a virtual hierarchical tree of all keys. e.g key 'top/sub/mykey' is divided into a folder 'top' containing the folder 'sub' with the key 'mykey' inside it.
ui.jsonViewAsDefault	string list	'none'		VIEW_JSON_DEFAULT	comma separated list of data types where valid json data should be displayed as JSON tree object instead of plain string. Default '' or 'none' displays no data as string, 'all' displays all data-types supported as JSON objects. Example: "string,hash" only displays these two types as JSON if possible per default Values supported: '', 'none', 'all', 'string', 'list', 'set', 'zset', 'hash'
ui.binaryAsHex	boolean	true		BINARY_AS_HEX	do not display binary data as string but in hexadecimal view
ui.maxHashFieldSize	number	0		MAX_HASH_FIELD_SIZE	The max number of bytes for a hash field before you must click to view it. Defaults to 0, which is disabled

Configure Treeview for Redis keys - Folding Character

The global UI parameter "foldingChar" can be overwritten on a per connection base with the same parameter within a specific connection object.

Example:

{
  "ui": {
    "foldingChar": ":"
  },
  "connections": [{
      "host": "10.2.3.4"
    },
    {
      "host": "10.9.8.7",
      "foldingChar": "/"    
    }
  ]
}

Now the first connection to host 10.2.3.4 creates virtual folders on the ':' key (global default) while the second connection to 10.9.8.7 uses '/' here:

10.2.3.4
 |- blah:
 |  |- blub      => Key blah:blub
 |- yadda/yammi
 
10.9.8.7
 |- blah:blub
 |- yadda/
    |- yammi     => Key yadda/yammi 

3. General Redis connection parameter

Name	Type	Default	Cli	Environment-Var	Description
redis.readOnly	boolean	false	--read-only	READ_ONLY	use Redis Commander in read-only mode - if set to "true" no commands modifying data are allowed (ui and command line)
redis.flushOnImport	boolean	false		FLUSH_ON_IMPORT	flag to either check "flush" checkbox (true) on import page or uncheck (false) it. If "true" the entire database is flushed before bulk importing the data.
redis.useScan	boolean	true	--use-scan	USE_SCAN	use redis "SCAN" command instead of "KEYS" to enumerate all keys inside db for display
redis.scanCount	number	100	--scan-count	SCAN_COUNT	number of keys read when using SCAN cursor instead of KEYS (useScan must be true)
redis.rootPattern	string	'*'	--root-pattern	ROOT_PATTERN	filter pattern to use at start, can be used to exclude some date inside redis db
redis.connectionName	string	'redis-commander'		REDIS_CONNECTION_NAME	connection name to set at redis client for easier identification of clients at redis server (command "client list")
redis.defaultLabel	string	'local'		REDIS_LABEL	default label to display for a connection if no label is specified (e.g. for connection from env vars or command line)
redis.defaultSentinelGroup	string	'mymaster'			default redis database group if using sentinels to connect and no special database group via connection param 'sentinelName' is given.
redis.extraAllowedReadOnlyCommands	list	['select', 'info']			list of additional redis commands allowed if set to read-only. See remark below

Read-Only Mode

Setting the parameter redis.readOnly to true only commands not changing data are allowed. As Default the list with all read-only commands is directly queried from the server (calling "COMMANDS") and parsing the output for the "readonly" flag.

Some commands are not marked as read-only by there server - adding these commands to the list at redis.extraAllowedReadOnlyCommands allows them too being in readOnly mode. This list is not used if all commands are allowed (readOnly=false).

Attention: if this list shall be changed (ore set to emtpy) within a local config file (like local.json) the new value overwrites the default list defined in the default.json file. The values are not appended and the full list of allowed commands must be configured in the local file.

Example (shortened) output from "COMMANDS" command showing dbsize flagged as readonly while select is not

61) 1) "select"
     2) (integer) 2
     3) 1) loading
        2) fast
     4) (integer) 0
     5) (integer) 0
     6) (integer) 0
...
86) 1) "dbsize"
     2) (integer) 1
     3) 1) readonly
        2) fast
     4) (integer) 0
     5) (integer) 0
     6) (integer) 0
...

4. Express HTTP Server parameter

Name	Type	Default	Cli	Environment-Var	Description
server.address	string	'0.0.0.0'	--address	ADDRESS	ip address of interface to bind http server to, use 0.0.0.0 to bind to all interfaces
server.port	number	8081	--port	PORT	port to listen on for HTTP server
server.urlPrefix	string	''	--url-prefix	URL_PREFIX	path prefix to run Redis Commander at, can be used if run behind a reverse proxy with different path set (e.g. /rc), if set must start with '/'
server.signinPath	string	'signin'		SIGNIN_PATH	path added after urlPrefix as route to send login requests too. Some platforms (e.g. github codespaces) may require changing this path.
server.httpAuthHeaderName	string	'Authorization'		NAUGHTY_ISTIO_WORKAROUND_HEADER	set HTTP header name for our own JWT session token to some non-standard name beside 'Authorization'
server.trustProxy	boolean or string	false	--trust-proxy	TRUST_PROXY	should be set to true if run behind a reverse proxy and 'X-Forwarded-For' headers shall be trusted to get real client ip for logging, this parameter maps directly to the Express "trust proxy" setting (https://expressjs.com/de/guide/behind-proxies.html)
server.clientMaxBodySize	number or string	'100kb'		CLIENT_MAX_BODY_SIZE	number in bytes or a string with size and SI-unit, this parameter maps to the "limit" options of body-parser (https://github.com/expressjs/body-parser#limit)
server.auth	object				see section 4.1 Authentication

4.1 Authentication configuration for HTTP server

To enable HTTP authentication inside Redis Commander set a username and either a password (clear text) or a passwordHash.

If username is empty Redis Commander does not use any authentication leaving all your redis keys accessible to anyone. This mode may be used if an HTTP reverse proxy in front of Redis commander performs the user authentication.

Please be aware that using an HTTP reverse proxy for authentication and not using Redis Commander builtin auth allows (at least) all users having accounts on the server running Redis Commander to connect via localhost directly to via app port (e.g. 8081) unauthenticated!

Name	Type	Default	Cli	Environment-Var	Description
server.httpAuth.username	string	''	--http-u	HTTP_USER	set a username and either password or passwordHash to
server.httpAuth.password	string	''	--http-p	HTTP_PASSWORD	clear text password to use for HTTP Basic auth (either password or passwordHash allowed)
server.httpAuth.passwordHash	string	''	--http-h	HTTP_PASSWORD_HASH	password hash to use for HTTP Basic auth (either password or passwordHash allowed)
server.httpAuth.jwtSecret	string	''			Shared Secret used to sign JWT tokens for all future requests after initial login to not send HTTP basic auth header on all requests. If this value is empty a random value is generated on every startup.

Using HTTP authentication all further requests to the server are secured with an JWT token generated by Redis-Commander that is changed quite often.

Remark: Using Redis commander inside a Kubernetes cluster secured with Istio authentication no other apps than Istio are allowed to use the HTTP standard "Authentication" header anymore. Istio does not play along with others - it just tries to validate every connection using the RFC conformant HTTP header and (naturally) fails doing so. Failing JWT validation it just resets the HTTP connection and no more communication allowed. To work around Istio cutting in the line the name of the authorization header can be changed to something else ignored by Istio. (config value "server.httpAuthHeaderName" or environment variable NAUGHTY_ISTIO_WORKAROUND_HEADER)

5. Redis Connections

All Connections use be redis commander are defined as entries of the "connections" list. The possible values for a connection are described in the connections.md file.

Environment Variables

All possible environment variables with their mapping to configuration data are defined inside the file custom-environment-variables.json. This file can be extended if there is any need to define more environment variables for custom config data like connection configs.