From 95c0f205f1a05d8e4963311b4b33f19eec7a0a6b Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Mon, 25 Jul 2022 02:29:53 +0300 Subject: [PATCH 01/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 64 +++++++++++++++++------- 1 file changed, 47 insertions(+), 17 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index b82ff34d..6bb8ad9b 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -21,6 +21,11 @@ properties are ignored and are left to the embedding application to implement. flowFile : the file used to store the flows. Default: `flows_.json` +flowFilePretty +: By default, the flow JSON will be formatted over multiple lines making + it easier to compare changes when using version control. + To disable pretty-printing of the JSON set the following property to false. Default: `flowFilePretty: true` + userDir : the directory to store all user data, such as flow and credential files and all library data. Default: `$HOME/.node-red` @@ -33,8 +38,11 @@ nodesDir uiHost : the interface to listen for connections on. Default: `0.0.0.0` - - *all IPv4 interfaces*. - + By default, the Node-RED UI accepts connections on all IPv4 interfaces. + To listen on all IPv6 addresses, set uiHost to "::", + The following property can be used to listen on a specific interface. For + example, the following would only allow connections from the local machine. + *Standalone only*. uiPort @@ -42,6 +50,10 @@ uiPort *Standalone only*. + apiMaxLength + : The maximum size of HTTP request that will be accepted by the runtime api. + Default: `apiMaxLength: '5mb',` + httpAdminRoot : the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` @@ -122,7 +134,19 @@ logging - **debug** - record information which is more verbose than info + info + warn + error + fatal errors - **trace** - record very detailed logging + debug + info + warn + error + fatal errors -The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". +The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". + +diagnosticsOptions +: Configure diagnostics options. + + diagnosticsOptions: { + /** @type {boolean} enable or disable diagnostics. Must be set to `false` to disable */ + enabled: true, + /** @type {"basic"|"admin"} diagnostic level can be "basic" (default) or "admin" (more sensitive details are included) */ + level: "basic", + }, + +When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. externalModules : Configure how the runtime will handle external npm modules. This covers: @@ -133,20 +157,26 @@ externalModules will install/load. It can use `*` as a wildcard that matches anything. externalModules: { - autoInstall: false, - autoInstallRetry: 30, - palette: { - allowInstall: true, - allowUpload: true, - allowList: [], - denyList: [] - }, - modules: { - allowInstall: true, - allowList: [], - denyList: [] - } - } + // autoInstall: false, /** Whether the runtime will attempt to automatically install missing modules */ + // autoInstallRetry: 30, /** Interval, in seconds, between reinstall attempts */ + // palette: { /** Configuration for the Palette Manager */ + // allowInstall: true, /** Enable the Palette Manager in the editor */ + // allowUpdate: true, /** Allow modules to be updated in the Palette Manager */ + // allowUpload: true, /** Allow module tgz files to be uploaded and installed */ + // allowList: ['*'], + // denyList: [], + // allowUpdateList: ['*'], + // denyUpdateList: [] + // }, + // modules: { /** Configuration for node-specified modules */ + // allowInstall: true, + // allowList: [], + // denyList: [] + // } + }, + +functionExternalModules +: Allow the Function node to load additional npm modules directly. Default: `true` ### Editor Configuration From 9896ebb1c656f26dfdc7da6b033aad833a648bb2 Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Mon, 25 Jul 2022 19:39:43 +0300 Subject: [PATCH 02/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 134 +++++++++++++++++++---- 1 file changed, 114 insertions(+), 20 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 6bb8ad9b..99a6c6cb 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -41,18 +41,17 @@ uiHost By default, the Node-RED UI accepts connections on all IPv4 interfaces. To listen on all IPv6 addresses, set uiHost to "::", The following property can be used to listen on a specific interface. For - example, the following would only allow connections from the local machine. + example, the following would only allow connections from the local machine `uiHost: "127.0.0.1",` *Standalone only*. uiPort -: the port used to serve the editor UI. Default: `1880`. +: the port used to serve the editor UI. Default: `process.env.PORT || 1880`. *Standalone only*. - apiMaxLength - : The maximum size of HTTP request that will be accepted by the runtime api. - Default: `apiMaxLength: '5mb',` +apiMaxLength +: The maximum size of HTTP request that will be accepted by the runtime api. Default: `apiMaxLength: '5mb',` httpAdminRoot : the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` @@ -90,11 +89,37 @@ httpRoot : this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. https -: enables https, with the specified options object, as defined - [here](http://nodejs.org/api/https.html#https_https_createserver_options_requestlistener). +: The following property can be used to enable HTTPS. + See [here](http://nodejs.org/api/https.html#https_https_createserver_options_requestlistener) for details of its contents. + This property can be either an object, containing both a (private) key + * and a (public) certificate, or a function that returns such an object. + +``` + /** Option 1: static object */ + //https: { + // key: require("fs").readFileSync('privkey.pem'), + // cert: require("fs").readFileSync('cert.pem') + //}, + + /** Option 2: function that returns the HTTP configuration object */ + // https: function() { + // // This function should return the options object, or a Promise + // // that resolves to the options object + // return { + // key: require("fs").readFileSync('privkey.pem'), + // cert: require("fs").readFileSync('cert.pem') + // } + // }, +``` *Standalone only*. +httpsRefreshInterval +: If the `https` setting is a function, the following setting can be used to set how often, in hours, the function will be called. That can be used to refresh any certificates. `httpsRefreshInterval : 12,` + +requireHttps +: The following property can be used to cause insecure HTTP connections to be redirected to HTTPS. `requireHttps: true,` + disableEditor : if set to `true`, prevents the editor UI from being served by the runtime. The admin api endpoints remain active. Default: `false`. @@ -133,9 +158,20 @@ logging - **info** - record information about the general running of the application + warn + error + fatal errors - **debug** - record information which is more verbose than info + info + warn + error + fatal errors - **trace** - record very detailed logging + debug + info + warn + error + fatal errors - +``` +logging: { + console: { + level: "info", + metrics: false, /** Whether or not to include metric events in the log output */ + audit: false /** Whether or not to include audit events in the log output */ + } +}, +``` The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". +lang +: the following option is to run node-red in your preferred language. Available languages include: en-US (default), ja, de, zh-CN, zh-TW, ru, ko Some languages are more complete than others. Example: `lang: "de",` + diagnosticsOptions : Configure diagnostics options. @@ -148,13 +184,27 @@ diagnosticsOptions When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. +runtimeState +: enable or disable flows/state + + runtimeState: { + /** enable or disable flows/state endpoint. Must be set to `false` to disable */ + enabled: false, + /** show or hide runtime stop/start options in the node-red editor. Must be set to `false` to hide */ + ui: false, + }, + +exportGlobalContextKeys +: `global.keys()` returns a list of all properties set in global context. This allows them to be displayed in the Context Sidebar within the editor. In some circumstances it is not desirable to expose them to the editor. The following property can be used to hide any property set in `functionGlobalContext` from being list by `global.keys()`. +By default, the property is set to false to avoid accidental exposure of their values. Setting this to true will cause the keys to be listed. + + externalModules -: Configure how the runtime will handle external npm modules. This covers: - - whether the editor will allow new node modules to be installed +: Configure how the runtime will handle external npm modules. This covers:
+ - whether the editor will allow new node modules to be installed
- whether nodes, such as the Function node are allowed to have their own dynamically configured dependencies. - The allow/denyList options can be used to limit what modules the runtime - will install/load. It can use `*` as a wildcard that matches anything. +The allow/denyList options can be used to limit what modules the runtime will install/load. It can use `*` as a wildcard that matches anything. externalModules: { // autoInstall: false, /** Whether the runtime will attempt to automatically install missing modules */ @@ -194,6 +244,13 @@ paletteCategories _Note_: Until the user creates a subflow the subflow category will be empty and will not be visible in the palette. +debugUseColors +: Colourise the console output of the debug node. Default: `true` + +debugMaxLength +: Debug Nodes - the maximum length, in characters, of any message sent to the + debug sidebar tab. Default: `1000` + ### Editor Themes The theme of the editor can be changed by using the following settings object. All parts are optional. @@ -261,6 +318,7 @@ ui to any already defined **httpNodeRoot** ui : { path: "mydashboard" }, + ### Node Configuration @@ -283,26 +341,62 @@ functionGlobalContext This method is still supported, but deprecated in favour of the global.get/global.set functions. Any data stored using this method will not be persisted across restarts and will not be visible in the sidebar context viewer. +
+ +nodeMessageBufferMaxLength +: The maximum number of messages nodes will buffer internally as part of their operation. This applies across a range of nodes that operate on message sequences. defaults to no limit. A value of 0 also means no limit is applied. functionExternalModules : if set to `true`, the Function node's Setup tab will allow adding additional modules that will become available to the function. See [Writing Functions](../writing-functions#using-the-functionexternalmodules-option) for more information. Default: `false`. -debugMaxLength -: Debug Nodes - the maximum length, in characters, of any message sent to the - debug sidebar tab. Default: 1000 - mqttReconnectTime : MQTT Nodes - if the connection is lost, how long to wait, in milliseconds, - before attempting to reconnect. Default: 5000 + before attempting to reconnect. Default: `5000` serialReconnectTime : Serial Nodes - how long to wait, in milliseconds, before attempting to reopen - a serial port. Default: 5000 + a serial port. Default: `5000` socketReconnectTime : TCP Nodes - how long to wait, in milliseconds, before attempting to reconnect. - Default: 10000 + Default: `10000` socketTimeout : TCP Nodes - how long to wait, in milliseconds, before timing out a socket. - Default: 120000 + Default: `120000` + +tcpMsgQueueSize +: Maximum number of messages to wait in queue while attempting to connect to TCP socket. Defaults to 1000 + +inboundWebSocketTimeout +: Timeout in milliseconds for inbound WebSocket connections that do not match any configured node. Defaults to `5000` + +tlsConfigDisableLocalFiles +: To disable the option for using local files for storing keys and certificates in the TLS configuration node, set this to `true` + +execMaxBufferSize +: Maximum buffer size for the exec node. Defaults to 10Mb. `execMaxBufferSize: 10000000` + +httpRequestTimeout +: Timeout in milliseconds for HTTP request connections. Defaults to 120s. Setting in ms `120000` + +webSocketNodeVerifyClient +: The following property can be used to verify websocket connection attempts. This allows, for example, the HTTP request headers to be checked to ensure they include valid authentication information. +``` +//webSocketNodeVerifyClient: function(info) { + // /** 'info' has three properties: + // * - origin : the value in the Origin header + // * - req : the HTTP request + // * - secure : true if req.connection.authorized or req.connection.encrypted is set + // * + // * The function should return true if the connection should be accepted, false otherwise. + // * + // * Alternatively, if this function is defined to accept a second argument, callback, + // * it can be used to verify the client asynchronously. + // * The callback takes three arguments: + // * - result : boolean, whether to accept the connection or not + // * - code : if result is false, the HTTP error status to return + // * - reason: if result is false, the HTTP reason string to return + // */ + //}, +``` \ No newline at end of file From 368f7be452d7ef26ef58abe2a5161bbcad8a0a1f Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Mon, 25 Jul 2022 20:22:03 +0300 Subject: [PATCH 03/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 99a6c6cb..2740b6b9 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -170,7 +170,8 @@ logging: { The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". lang -: the following option is to run node-red in your preferred language. Available languages include: en-US (default), ja, de, zh-CN, zh-TW, ru, ko Some languages are more complete than others. Example: `lang: "de",` +: the following option is to run node-red in your preferred language.
+Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. Some languages are more complete than others. diagnosticsOptions : Configure diagnostics options. @@ -325,8 +326,7 @@ to any already defined **httpNodeRoot** Any node type can define its own settings to be provided in the file. functionGlobalContext -: Function Nodes - a collection of objects to attach to the global function - context. For example, +: Function Nodes - a collection of objects to attach to the global function context. For example, functionGlobalContext: { osModule:require('os') } From 7e42a99cbec29fc730aca714a8c5b7bb4c60dc1c Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Tue, 26 Jul 2022 20:14:34 +0300 Subject: [PATCH 04/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 41 +++++++++++------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 2740b6b9..363cd716 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -26,6 +26,9 @@ flowFilePretty it easier to compare changes when using version control. To disable pretty-printing of the JSON set the following property to false. Default: `flowFilePretty: true` +credentialSecret +: By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. + userDir : the directory to store all user data, such as flow and credential files and all library data. Default: `$HOME/.node-red` @@ -51,7 +54,7 @@ uiPort *Standalone only*. apiMaxLength -: The maximum size of HTTP request that will be accepted by the runtime api. Default: `apiMaxLength: '5mb',` +: The maximum size of HTTP request that will be accepted by the runtime api.
Default: `apiMaxLength: '5mb',` httpAdminRoot : the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` @@ -175,25 +178,26 @@ Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. So diagnosticsOptions : Configure diagnostics options. - +``` diagnosticsOptions: { /** @type {boolean} enable or disable diagnostics. Must be set to `false` to disable */ enabled: true, /** @type {"basic"|"admin"} diagnostic level can be "basic" (default) or "admin" (more sensitive details are included) */ level: "basic", }, - +``` When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. runtimeState : enable or disable flows/state - +``` runtimeState: { /** enable or disable flows/state endpoint. Must be set to `false` to disable */ enabled: false, /** show or hide runtime stop/start options in the node-red editor. Must be set to `false` to hide */ ui: false, }, +``` exportGlobalContextKeys : `global.keys()` returns a list of all properties set in global context. This allows them to be displayed in the Context Sidebar within the editor. In some circumstances it is not desirable to expose them to the editor. The following property can be used to hide any property set in `functionGlobalContext` from being list by `global.keys()`. @@ -316,9 +320,7 @@ The theme of the editor can be changed by using the following settings object. A ui : The home path for the Node-RED-Dashboard add-on nodes can specified. This is relative -to any already defined **httpNodeRoot** - - ui : { path: "mydashboard" }, +to any already defined **httpNodeRoot**. Example: `ui: { path: "mydashboard" },` ### Node Configuration @@ -326,25 +328,20 @@ to any already defined **httpNodeRoot** Any node type can define its own settings to be provided in the file. functionGlobalContext -: Function Nodes - a collection of objects to attach to the global function context. For example, +: Function Nodes - a collection of objects to attach to the global function context. For example: - functionGlobalContext: { osModule:require('os') } +`functionGlobalContext: { osModule:require('os') }` - can be accessed in a function node as: +can be accessed in a function node as: - var myos = global.get('osModule'); +`var myos = global.get('osModule');` -
Note : Prior to Node-RED v0.13, the documented - way to use global context was to access it as a sub-property of context: - 
context.global.foo = "bar";
- var osModule = context.global.osModule;
- This method is still supported, but deprecated in favour of the global.get/global.set - functions. Any data stored using this method will not be persisted across restarts and will not be visible in the sidebar context viewer. -
-
+
Note : Prior to Node-RED v0.13, the documented + way to use global context was to access it as a sub-property of context: context.global.foo = "bar"; var osModule = context.global.osModule;This method is still supported, but deprecated in favour of the global.get/ global.set functions. Any data stored using this method will not be persisted across restarts and will not be visible in the sidebar context viewer. +
nodeMessageBufferMaxLength -: The maximum number of messages nodes will buffer internally as part of their operation. This applies across a range of nodes that operate on message sequences. defaults to no limit. A value of 0 also means no limit is applied. +: The maximum number of messages nodes will buffer internally as part of their operation. This applies across a range of nodes that operate on message sequences. defaults to no limit. A value of `0` also means no limit is applied. functionExternalModules : if set to `true`, the Function node's Setup tab will allow adding additional modules that will become available to the function. See [Writing Functions](../writing-functions#using-the-functionexternalmodules-option) for more information. Default: `false`. @@ -355,7 +352,7 @@ mqttReconnectTime serialReconnectTime : Serial Nodes - how long to wait, in milliseconds, before attempting to reopen - a serial port. Default: `5000` + a serial port.
Default: `5000` socketReconnectTime : TCP Nodes - how long to wait, in milliseconds, before attempting to reconnect. @@ -366,7 +363,7 @@ socketTimeout Default: `120000` tcpMsgQueueSize -: Maximum number of messages to wait in queue while attempting to connect to TCP socket. Defaults to 1000 +: Maximum number of messages to wait in queue while attempting to connect to TCP socket. Defaults to `1000` inboundWebSocketTimeout : Timeout in milliseconds for inbound WebSocket connections that do not match any configured node. Defaults to `5000` From cd4ffd6691549cc6b539325a002bb5f2b451be71 Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Wed, 27 Jul 2022 00:07:01 +0300 Subject: [PATCH 05/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 380 +++++++++++++---------- 1 file changed, 209 insertions(+), 171 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 363cd716..1642fa2f 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -16,82 +16,44 @@ When running as an [embedded application](embedding), the configuration options are passed in the call to `RED.init()`. However, when run in this mode, certain properties are ignored and are left to the embedding application to implement. -### Runtime Configuration - -flowFile -: the file used to store the flows. Default: `flows_.json` +The settings are split into the following sections: +- Flow File and User Directory Settings +- Security +- Server Settings +- Runtime Settings +- Editor Settings +- Node Settings + +### Flow File and User Directory Settings + +**flowFile** +: the file used to store the flows. Default: `flows.json` + +**credentialSecret** +: By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. -flowFilePretty +**flowFilePretty** : By default, the flow JSON will be formatted over multiple lines making it easier to compare changes when using version control. To disable pretty-printing of the JSON set the following property to false. Default: `flowFilePretty: true` -credentialSecret -: By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. -userDir -: the directory to store all user data, such as flow and credential files and all - library data. Default: `$HOME/.node-red` +**userDir** +: By default, all user data is stored in a directory called `.node-red` under the user's home directory. To use a different location, the following property can be used `userDir: '/home/nol/.node-red/',` Default: `$HOME/.node-red` -nodesDir +**nodesDir** : a directory to search for additional installed nodes. Node-RED searches the `nodes` directory under the *userDir* directory. This property allows an additional directory to be searched, so that nodes can be installed outside of the Node-RED install structure. Default: `$HOME/.node-red/nodes` -uiHost -: the interface to listen for connections on. Default: `0.0.0.0` - - By default, the Node-RED UI accepts connections on all IPv4 interfaces. - To listen on all IPv6 addresses, set uiHost to "::", - The following property can be used to listen on a specific interface. For - example, the following would only allow connections from the local machine `uiHost: "127.0.0.1",` - - *Standalone only*. - -uiPort -: the port used to serve the editor UI. Default: `process.env.PORT || 1880`. - - *Standalone only*. - -apiMaxLength -: The maximum size of HTTP request that will be accepted by the runtime api.
Default: `apiMaxLength: '5mb',` - -httpAdminRoot -: the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` - -httpAdminAuth -: *Deprecated*: see `adminAuth`. - - enables HTTP Basic Authentication on the editor UI: - - httpAdminAuth: {user:"nol", pass:"5f4dcc3b5aa765d61d8327deb882cf99"} - - The `pass` property is the md5 hash of the actual password. The following - command can be used to generate the hash: - - node -e "console.log(require('crypto').createHash('md5').update('YOUR PASSWORD HERE','utf8').digest('hex'))" - - *Standalone only*. - -httpAdminMiddleware -: an HTTP middleware function, or array of functions, that is added to all admin routes. - The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). - - httpAdminMiddleware: function(req,res,next) { - // Perform any processing on the request. - // Be sure to call next() if the request should be passed on - } - -httpNodeRoot -: the root url for nodes that provide HTTP endpoints. If set to `false`, all node-based HTTP endpoints are disabled. Default: `/` - -httpNodeAuth -: enables HTTP Basic Authentication. See `httpAdminAuth` for format. +### Security -httpRoot -: this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. +**adminAuth** +: enables user-level security in the editor and admin API.
See [Securing Node-RED](securing-node-red) + for more information. -https +**https** : The following property can be used to enable HTTPS. See [here](http://nodejs.org/api/https.html#https_https_createserver_options_requestlistener) for details of its contents. This property can be either an object, containing both a (private) key @@ -117,69 +79,128 @@ https *Standalone only*. -httpsRefreshInterval +**httpsRefreshInterval** : If the `https` setting is a function, the following setting can be used to set how often, in hours, the function will be called. That can be used to refresh any certificates. `httpsRefreshInterval : 12,` -requireHttps +**requireHttps** : The following property can be used to cause insecure HTTP connections to be redirected to HTTPS. `requireHttps: true,` -disableEditor -: if set to `true`, prevents the editor UI from being served by the runtime. The admin api endpoints remain active. Default: `false`. +**httpNodeAuth** +: enables HTTP Basic Authentication. See `adminAuth` for format. + +**httpStaticAuth** +: enabled HTTP Basic Authentication on the static content. See `adminAuth` for format. + +### Server Settings + +**uiPort** +: the port used to serve the editor UI. Default: `process.env.PORT || 1880`. -httpStatic -: a local directory from which to serve static web content from. This content is - served from the top level url, `/`. When this property is used, `httpAdminRoot` must - also be used to make editor UI available at a path other than `/`. + *Standalone only*. +**uiHost** +: the interface to listen for connections on. Default: `0.0.0.0` - + By default, the Node-RED UI accepts connections on all IPv4 interfaces. + To listen on all IPv6 addresses, set uiHost to "::", + The following property can be used to listen on a specific interface. For + example, the following would only allow connections from the local machine `uiHost: "127.0.0.1",` + *Standalone only*. -httpStaticAuth -: enabled HTTP Basic Authentication on the static content. See `httpAdminAuth` for format. +**apiMaxLength** +: The maximum size of HTTP request that will be accepted by the runtime api.
Default: `apiMaxLength: '5mb',` + +**httpServerOptions** +: The following property can be used to pass custom options to the Express.js server used by Node-RED. For a full list of available options, refer to [Express.js](http://expressjs.com/en/api.html#app.settings.table) `httpServerOptions: { },` + +**httpAdminRoot** +: the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` + +**httpAdminMiddleware** +: an HTTP middleware function, or array of functions, that is added to all admin routes. + The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). + +``` + // httpAdminMiddleware: function(req,res,next) { + // // Set the X-Frame-Options header to limit where the editor + // // can be embedded + // //res.set('X-Frame-Options', 'sameorigin'); + // next(); + // }, +``` +**httpNodeRoot** +: Some nodes, such as HTTP In, can be used to listen for incoming http requests. By default, these are served relative to '/'. The following property can be used to specifiy a different root path. If set to `false`, this is disabled. Default: `/` -httpNodeCors +**httpNodeCors** : enables cross-origin resource sharing for the nodes that provide HTTP endpoints, as defined [here](https://github.com/troygoode/node-cors#configuration-options) -httpNodeMiddleware +**httpNodeMiddleware** : an HTTP middleware function, or array of functions, that is added to all HTTP In nodes. This allows whatever custom processing, such as authentication, is needed for the nodes. The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). - httpNodeMiddleware: function(req,res,next) { - // Perform any processing on the request. - // Be sure to call next() if the request should be passed - // to the relevant HTTP In node. - } - -logging -: currently only console logging is supported. Various levels of logging can be specified. Options are: +``` +//httpNodeMiddleware: function(req,res,next) { + // // Handle/reject the request, or pass it on to the http in node by calling next(); + // // Optionally skip our rawBodyParser by setting this to true; + // //req.skipRawBodyParser = true; + // next(); + //}, +``` +**httpStatic** +: When httpAdminRoot is used to move the UI to a different root path, the following property can be used to identify a directory of static content that should be served at http://localhost:1880/. When httpStaticRoot is set differently to httpAdminRoot, there is no need to move httpAdminRoot - - **fatal** - only those errors which make the application unusable should be recorded - - **error** - record errors which are deemed fatal for a particular request + fatal errors - - **warn** - record problems which are non fatal + errors + fatal errors - - **info** - record information about the general running of the application + warn + error + fatal errors - - **debug** - record information which is more verbose than info + info + warn + error + fatal errors - - **trace** - record very detailed logging + debug + info + warn + error + fatal errors ``` -logging: { - console: { - level: "info", - metrics: false, /** Whether or not to include metric events in the log output */ - audit: false /** Whether or not to include audit events in the log output */ - } -}, + //httpStatic: '/home/nol/node-red-static/', //single static source + /* OR multiple static sources can be created using an array of objects... */ + //httpStatic: [ + // {path: '/home/nol/pics/', root: "/img/"}, + // {path: '/home/nol/reports/', root: "/doc/"}, + //], + + /** + * All static routes will be appended to httpStaticRoot + * e.g. if httpStatic = "/home/nol/docs" and httpStaticRoot = "/static/" + * then "/home/nol/docs" will be served at "/static/" + * e.g. if httpStatic = [{path: '/home/nol/pics/', root: "/img/"}] + * and httpStaticRoot = "/static/" + * then "/home/nol/pics/" will be served at "/static/img/" + */ + //httpStaticRoot: '/static/', ``` -The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". -lang + *Standalone only*. + +httpAdminAuth +: *Deprecated*: see `adminAuth`. + + enables HTTP Basic Authentication on the editor UI: + + httpAdminAuth: {user:"nol", pass:"5f4dcc3b5aa765d61d8327deb882cf99"} + + The `pass` property is the md5 hash of the actual password. The following + command can be used to generate the hash: + + node -e "console.log(require('crypto').createHash('md5').update('YOUR PASSWORD HERE','utf8').digest('hex'))" + + *Standalone only*. + +httpRoot +: this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. + + +### Runtime Settings + +**lang** : the following option is to run node-red in your preferred language.
Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. Some languages are more complete than others. -diagnosticsOptions +**diagnostics** : Configure diagnostics options. ``` - diagnosticsOptions: { + diagnostics: { /** @type {boolean} enable or disable diagnostics. Must be set to `false` to disable */ enabled: true, /** @type {"basic"|"admin"} diagnostic level can be "basic" (default) or "admin" (more sensitive details are included) */ @@ -188,7 +209,7 @@ diagnosticsOptions ``` When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. -runtimeState +**runtimeState** : enable or disable flows/state ``` runtimeState: { @@ -199,18 +220,41 @@ runtimeState }, ``` -exportGlobalContextKeys +**logging** +: currently only console logging is supported. Various levels of logging can be specified. Options are: + + - **fatal** - only those errors which make the application unusable should be recorded + - **error** - record errors which are deemed fatal for a particular request + fatal errors + - **warn** - record problems which are non fatal + errors + fatal errors + - **info** - record information about the general running of the application + warn + error + fatal errors + - **debug** - record information which is more verbose than info + info + warn + error + fatal errors + - **trace** - record very detailed logging + debug + info + warn + error + fatal errors +``` +logging: { + console: { + level: "info", + metrics: false, /** Whether or not to include metric events in the log output */ + audit: false /** Whether or not to include audit events in the log output */ + } +}, +``` +The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". + +**contextStorage** +: The following property can be used to enable context storage. The configuration provided here will enable file-based context that flushes to disk every 30 seconds. Refer to the documentation for further options [here](https://nodered.org/docs/api/context/) + +**exportGlobalContextKeys** : `global.keys()` returns a list of all properties set in global context. This allows them to be displayed in the Context Sidebar within the editor. In some circumstances it is not desirable to expose them to the editor. The following property can be used to hide any property set in `functionGlobalContext` from being list by `global.keys()`. By default, the property is set to false to avoid accidental exposure of their values. Setting this to true will cause the keys to be listed. -externalModules +**externalModules** : Configure how the runtime will handle external npm modules. This covers:
- whether the editor will allow new node modules to be installed
- whether nodes, such as the Function node are allowed to have their own dynamically configured dependencies. The allow/denyList options can be used to limit what modules the runtime will install/load. It can use `*` as a wildcard that matches anything. - +``` externalModules: { // autoInstall: false, /** Whether the runtime will attempt to automatically install missing modules */ // autoInstallRetry: 30, /** Interval, in seconds, between reinstall attempts */ @@ -229,93 +273,87 @@ The allow/denyList options can be used to limit what modules the runtime will in // denyList: [] // } }, +``` -functionExternalModules +**functionExternalModules** : Allow the Function node to load additional npm modules directly. Default: `true` -### Editor Configuration - -adminAuth -: enables user-level security in the editor and admin API. See [Securing Node-RED](securing-node-red) - for more information. - -paletteCategories -: defines the order of categories in the palette. If a node's category is not in - the list, the category will get added to the end of the palette. If not set, - the following default order is used: +### Editor Settings - ['subflows', 'common', 'function', 'network', 'sequence', 'parser', 'storage'], +**disableEditor** +: if set to `true`, prevents the editor UI from being served by the runtime. The admin api endpoints remain active. Default: `false`. - _Note_: Until the user creates a subflow the subflow category will be empty and will - not be visible in the palette. +**editorTheme** +: The following property can be used to set a custom theme for the editor. See [here](https://github.com/node-red-contrib-themes/theme-collection) for a collection of themes to choose from. -debugUseColors -: Colourise the console output of the debug node. Default: `true` - -debugMaxLength -: Debug Nodes - the maximum length, in characters, of any message sent to the - debug sidebar tab. Default: `1000` +``` +editorTheme: { -### Editor Themes + //theme: "", -The theme of the editor can be changed by using the following settings object. All parts are optional. + /** To disable the 'Welcome to Node-RED' tour that is displayed the first + * time you access the editor for each release of Node-RED, set this to false + */ + //tours: false, - editorTheme: { - page: { - title: "Node-RED", - favicon: "/absolute/path/to/theme/icon", - css: "/absolute/path/to/custom/css/file", - scripts: [ "/absolute/path/to/custom/script/file", "/another/script/file"] - }, - header: { - title: "Node-RED", - image: "/absolute/path/to/header/image", // or null to remove image - url: "http://nodered.org" // optional url to make the header text/image a link to this url - }, - deployButton: { - type:"simple", - label:"Save", - icon: "/absolute/path/to/deploy/button/image" // or null to remove image - }, - menu: { // Hide unwanted menu items by id. see packages/node_modules/@node-red/editor-client/src/js/red.js:loadEditor for complete list - "menu-item-import-library": false, - "menu-item-export-library": false, - "menu-item-keyboard-shortcuts": false, - "menu-item-help": { - label: "Alternative Help Link Text", - url: "http://example.com" - } - }, - tours: false, // disable the Welcome Tour for new users - userMenu: false, // Hide the user-menu even if adminAuth is enabled - login: { - image: "/absolute/path/to/login/page/big/image" // a 256x256 image - }, - logout: { - redirect: "http://example.com" - }, palette: { - editable: true, // *Deprecated* - use externalModules.palette.allowInstall instead - catalogues: [ // Alternative palette manager catalogues - 'https://catalogue.nodered.org/catalogue.json' - ], - theme: [ // Override node colours - rules test against category/type by RegExp. - { category: ".*", type: ".*", color: "#f0f" } - ] + /** The following property can be used to order the categories in the editor + * palette. If a node's category is not in the list, the category will get + * added to the end of the palette. + * If not set, the following default order is used: + */ + //categories: ['subflows', 'common', 'function', 'network', 'sequence', 'parser', 'storage'], }, + projects: { - enabled: false // Enable the projects feature + /** To enable the Projects feature, set this value to true */ + enabled: false, + workflow: { + /** Set the default projects workflow mode. + * - manual - you must manually commit changes + * - auto - changes are automatically committed + * This can be overridden per-user from the 'Git config' + * section of 'User Settings' within the editor + */ + mode: "manual" + } }, - theme: "", // Select a color theme for the editor. See https://github.com/node-red-contrib-themes/theme-collection for a collection of themes to choose from + codeEditor: { - lib: "ace", // Select the text editor component used by the editor. Defaults to "ace", but can be set to "ace" or "monaco" + /** Select the text editor component used by the editor. + * As of Node-RED V3, this defaults to "monaco", but can be set to "ace" if desired + */ + lib: "monaco", options: { - // The following only apply if the editor is set to "monaco" - theme: "vs", // Select a color theme for the text editor component. Must match the file name of a theme in packages/node_modules/@node-red/editor-client/src/vendor/monaco/dist/theme + /** The follow options only apply if the editor is set to "monaco" + * + * theme - must match the file name of a theme in + * packages/node_modules/@node-red/editor-client/src/vendor/monaco/dist/theme + * e.g. "tomorrow-night", "upstream-sunburst", "github", "my-theme" + */ + // theme: "vs", + /** other overrides can be set e.g. fontSize, fontFamily, fontLigatures etc. + * for the full list, see https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.IStandaloneEditorConstructionOptions.html + */ + //fontSize: 14, + //fontFamily: "Cascadia Code, Fira Code, Consolas, 'Courier New', monospace", + //fontLigatures: true, } } }, +``` + +### Node Settings + +debugUseColors +: Colourise the console output of the debug node. Default: `true` + +debugMaxLength +: Debug Nodes - the maximum length, in characters, of any message sent to the + debug sidebar tab. Default: `1000` + + ### Dashboard ui From 8055969a202ebff87547fa279172ac9cee8c50ea Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Wed, 27 Jul 2022 01:15:15 +0300 Subject: [PATCH 06/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 73 ++++++++++++------------ 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 1642fa2f..a5a8f29f 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -345,27 +345,15 @@ editorTheme: { ``` ### Node Settings +Any node type can define its own settings to be provided in the file. -debugUseColors -: Colourise the console output of the debug node. Default: `true` - -debugMaxLength -: Debug Nodes - the maximum length, in characters, of any message sent to the - debug sidebar tab. Default: `1000` - - -### Dashboard - -ui -: The home path for the Node-RED-Dashboard add-on nodes can specified. This is relative -to any already defined **httpNodeRoot**. Example: `ui: { path: "mydashboard" },` - - -### Node Configuration +**fileWorkingDirectory** +: The working directory to handle relative file paths from within the File nodes defaults to the working directory of the Node-RED process. -Any node type can define its own settings to be provided in the file. +**functionExternalModules** +: if set to `true`, the Function node's Setup tab will allow adding additional modules that will become available to the function. See [Writing Functions](../writing-functions#using-the-functionexternalmodules-option) for more information. Default: `true`. -functionGlobalContext +**functionGlobalContext** : Function Nodes - a collection of objects to attach to the global function context. For example: `functionGlobalContext: { osModule:require('os') }` @@ -378,44 +366,59 @@ can be accessed in a function node as: way to use global context was to access it as a sub-property of context: context.global.foo = "bar"; var osModule = context.global.osModule;This method is still supported, but deprecated in favour of the global.get/ global.set functions. Any data stored using this method will not be persisted across restarts and will not be visible in the sidebar context viewer. -nodeMessageBufferMaxLength + +**nodeMessageBufferMaxLength** : The maximum number of messages nodes will buffer internally as part of their operation. This applies across a range of nodes that operate on message sequences. defaults to no limit. A value of `0` also means no limit is applied. -functionExternalModules -: if set to `true`, the Function node's Setup tab will allow adding additional modules that will become available to the function. See [Writing Functions](../writing-functions#using-the-functionexternalmodules-option) for more information. Default: `false`. +**ui** +: The home path for the Node-RED-Dashboard add-on nodes can specified. This is relative +to any already defined **httpNodeRoot**.
Example: `ui: { path: "mydashboard" },` +Other optional properties include : +``` +readOnly:{boolean}, +middleware:{function or array}, (req,res,next) - http middleware +ioMiddleware:{function or array}, (socket,next) - socket.io middleware +``` + +**debugUseColors** +: Colourise the console output of the debug node. Default: `true` + +**debugMaxLength** +: Debug Nodes - the maximum length, in characters, of any message sent to the + debug sidebar tab. Default: `1000` + +**execMaxBufferSize** +: Maximum buffer size for the exec node. Defaults to 10Mb. `execMaxBufferSize: 10000000` + +**httpRequestTimeout** +: Timeout in milliseconds for HTTP request connections. Defaults to 120s. Setting in ms `120000` -mqttReconnectTime +**mqttReconnectTime** : MQTT Nodes - if the connection is lost, how long to wait, in milliseconds, before attempting to reconnect. Default: `5000` -serialReconnectTime +**serialReconnectTime** : Serial Nodes - how long to wait, in milliseconds, before attempting to reopen a serial port.
Default: `5000` -socketReconnectTime +**socketReconnectTime** : TCP Nodes - how long to wait, in milliseconds, before attempting to reconnect. Default: `10000` -socketTimeout +**socketTimeout** : TCP Nodes - how long to wait, in milliseconds, before timing out a socket. Default: `120000` -tcpMsgQueueSize +**tcpMsgQueueSize** : Maximum number of messages to wait in queue while attempting to connect to TCP socket. Defaults to `1000` -inboundWebSocketTimeout +**inboundWebSocketTimeout** : Timeout in milliseconds for inbound WebSocket connections that do not match any configured node. Defaults to `5000` -tlsConfigDisableLocalFiles +**tlsConfigDisableLocalFiles** : To disable the option for using local files for storing keys and certificates in the TLS configuration node, set this to `true` -execMaxBufferSize -: Maximum buffer size for the exec node. Defaults to 10Mb. `execMaxBufferSize: 10000000` - -httpRequestTimeout -: Timeout in milliseconds for HTTP request connections. Defaults to 120s. Setting in ms `120000` - -webSocketNodeVerifyClient +**webSocketNodeVerifyClient** : The following property can be used to verify websocket connection attempts. This allows, for example, the HTTP request headers to be checked to ensure they include valid authentication information. ``` //webSocketNodeVerifyClient: function(info) { From 88797f7b97d3a99c6cb19ef480becd6706ebd416 Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Wed, 27 Jul 2022 08:44:36 +0300 Subject: [PATCH 07/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index a5a8f29f..0c0c0b36 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -150,7 +150,7 @@ The settings are split into the following sections: //}, ``` **httpStatic** -: When httpAdminRoot is used to move the UI to a different root path, the following property can be used to identify a directory of static content that should be served at http://localhost:1880/. When httpStaticRoot is set differently to httpAdminRoot, there is no need to move httpAdminRoot +: When httpAdminRoot is used to move the UI to a different root path, the following property can be used to identify a directory of static content that should be served at `http://localhost:1880/` When httpStaticRoot is set differently to httpAdminRoot, there is no need to move httpAdminRoot ``` //httpStatic: '/home/nol/node-red-static/', //single static source From 218e3e089955b43bb85a309ac5981799643a1651 Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Thu, 28 Jul 2022 02:57:52 +0300 Subject: [PATCH 08/14] Update Configuration Documentation --- docs/user-guide/runtime/configuration.md | 25 +++++++++++------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 0c0c0b36..f5a9f8c9 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -17,20 +17,20 @@ are passed in the call to `RED.init()`. However, when run in this mode, certain properties are ignored and are left to the embedding application to implement. The settings are split into the following sections: -- Flow File and User Directory Settings +- Flow File and User Directory - Security -- Server Settings -- Runtime Settings -- Editor Settings -- Node Settings +- Server +- Runtime +- Editor +- Node -### Flow File and User Directory Settings +### Flow File and User Directory **flowFile** : the file used to store the flows. Default: `flows.json` **credentialSecret** -: By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. +: By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. Example: `credentialSecret: "a-secret-key",` **flowFilePretty** : By default, the flow JSON will be formatted over multiple lines making @@ -91,7 +91,7 @@ The settings are split into the following sections: **httpStaticAuth** : enabled HTTP Basic Authentication on the static content. See `adminAuth` for format. -### Server Settings +### Server **uiPort** : the port used to serve the editor UI. Default: `process.env.PORT || 1880`. @@ -191,7 +191,7 @@ httpRoot : this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. -### Runtime Settings +### Runtime **lang** : the following option is to run node-red in your preferred language.
@@ -275,10 +275,7 @@ The allow/denyList options can be used to limit what modules the runtime will in }, ``` -**functionExternalModules** -: Allow the Function node to load additional npm modules directly. Default: `true` - -### Editor Settings +### Editor **disableEditor** : if set to `true`, prevents the editor UI from being served by the runtime. The admin api endpoints remain active. Default: `false`. @@ -344,7 +341,7 @@ editorTheme: { ``` -### Node Settings +### Node Any node type can define its own settings to be provided in the file. **fileWorkingDirectory** From a321d154033541ea06de98962e66293ecae1aa1d Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Fri, 29 Jul 2022 01:19:50 +0300 Subject: [PATCH 09/14] Minor changes for example code coloring --- docs/user-guide/runtime/configuration.md | 140 ++++++++++++----------- 1 file changed, 74 insertions(+), 66 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index f5a9f8c9..b2c84196 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -7,7 +7,8 @@ redirect_from: - /docs/configuration - /docs/user-guide/configuration --- -The following properties can be used to configure Node-RED. +The following properties can be used to configure Node-RED.\ +*Please note that some of the options may not apply for older versions of Node-red.* When running as a normal application, it loads its configuration from a settings file. For more information about the settings file and where it is, read [this guide](settings-file). @@ -59,22 +60,22 @@ The settings are split into the following sections: This property can be either an object, containing both a (private) key * and a (public) certificate, or a function that returns such an object. -``` +```javascript /** Option 1: static object */ - //https: { - // key: require("fs").readFileSync('privkey.pem'), - // cert: require("fs").readFileSync('cert.pem') - //}, + https: { + key: require("fs").readFileSync('privkey.pem'), + cert: require("fs").readFileSync('cert.pem') + }, /** Option 2: function that returns the HTTP configuration object */ - // https: function() { - // // This function should return the options object, or a Promise - // // that resolves to the options object - // return { - // key: require("fs").readFileSync('privkey.pem'), - // cert: require("fs").readFileSync('cert.pem') - // } - // }, + https: function() { + // This function should return the options object, or a Promise + // that resolves to the options object + return { + key: require("fs").readFileSync('privkey.pem'), + cert: require("fs").readFileSync('cert.pem') + } + }, ``` *Standalone only*. @@ -120,13 +121,13 @@ The settings are split into the following sections: : an HTTP middleware function, or array of functions, that is added to all admin routes. The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). -``` - // httpAdminMiddleware: function(req,res,next) { - // // Set the X-Frame-Options header to limit where the editor - // // can be embedded - // //res.set('X-Frame-Options', 'sameorigin'); - // next(); - // }, +```javascript + httpAdminMiddleware: function(req,res,next) { + // Set the X-Frame-Options header to limit where the editor + // can be embedded + res.set('X-Frame-Options', 'sameorigin'); + next(); + }, ``` **httpNodeRoot** : Some nodes, such as HTTP In, can be used to listen for incoming http requests. By default, these are served relative to '/'. The following property can be used to specifiy a different root path. If set to `false`, this is disabled. Default: `/` @@ -138,27 +139,26 @@ The settings are split into the following sections: **httpNodeMiddleware** : an HTTP middleware function, or array of functions, that is added to all HTTP In nodes. This allows whatever custom processing, such as authentication, is needed for - the nodes. The format of the middleware function is - documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). - -``` -//httpNodeMiddleware: function(req,res,next) { - // // Handle/reject the request, or pass it on to the http in node by calling next(); - // // Optionally skip our rawBodyParser by setting this to true; - // //req.skipRawBodyParser = true; - // next(); - //}, + the nodes. The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). + +```javascript +httpNodeMiddleware: function(req,res,next) { + // Handle/reject the request, or pass it on to the http in node by calling next(); + // Optionally skip our rawBodyParser by setting this to true; + req.skipRawBodyParser = true; + next(); + }, ``` **httpStatic** : When httpAdminRoot is used to move the UI to a different root path, the following property can be used to identify a directory of static content that should be served at `http://localhost:1880/` When httpStaticRoot is set differently to httpAdminRoot, there is no need to move httpAdminRoot -``` - //httpStatic: '/home/nol/node-red-static/', //single static source +```javascript + httpStatic: '/home/nol/node-red-static/', //single static source /* OR multiple static sources can be created using an array of objects... */ - //httpStatic: [ - // {path: '/home/nol/pics/', root: "/img/"}, - // {path: '/home/nol/reports/', root: "/doc/"}, - //], + httpStatic: [ + {path: '/home/nol/pics/', root: "/img/"}, + {path: '/home/nol/reports/', root: "/doc/"}, + ], /** * All static routes will be appended to httpStaticRoot @@ -168,26 +168,28 @@ The settings are split into the following sections: * and httpStaticRoot = "/static/" * then "/home/nol/pics/" will be served at "/static/img/" */ - //httpStaticRoot: '/static/', + httpStaticRoot: '/static/', ``` *Standalone only*. -httpAdminAuth +**httpAdminAuth** : *Deprecated*: see `adminAuth`. enables HTTP Basic Authentication on the editor UI: - httpAdminAuth: {user:"nol", pass:"5f4dcc3b5aa765d61d8327deb882cf99"} +```javascript + httpAdminAuth: {user:"nol", pass:"5f4dcc3b5aa765d61d8327deb882cf99"} +``` - The `pass` property is the md5 hash of the actual password. The following - command can be used to generate the hash: +The `pass` property is the md5 hash of the actual password. The following + command can be used to generate the hash: - node -e "console.log(require('crypto').createHash('md5').update('YOUR PASSWORD HERE','utf8').digest('hex'))" + node -e "console.log(require('crypto').createHash('md5').update('YOUR PASSWORD HERE','utf8').digest('hex'))" *Standalone only*. -httpRoot +**httpRoot** : this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. @@ -199,7 +201,8 @@ Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. So **diagnostics** : Configure diagnostics options. -``` + +```javascript diagnostics: { /** @type {boolean} enable or disable diagnostics. Must be set to `false` to disable */ enabled: true, @@ -211,7 +214,8 @@ When `enabled` is `true` (or unset), diagnostics data will be available at http: **runtimeState** : enable or disable flows/state -``` + +```javascript runtimeState: { /** enable or disable flows/state endpoint. Must be set to `false` to disable */ enabled: false, @@ -229,7 +233,8 @@ When `enabled` is `true` (or unset), diagnostics data will be available at http: - **info** - record information about the general running of the application + warn + error + fatal errors - **debug** - record information which is more verbose than info + info + warn + error + fatal errors - **trace** - record very detailed logging + debug + info + warn + error + fatal errors -``` + +```javascript logging: { console: { level: "info", @@ -238,6 +243,7 @@ logging: { } }, ``` + The default level is `info`. For embedded devices with limited flash storage you may wish to set this to `fatal` to minimise writes to "disk". **contextStorage** @@ -254,24 +260,25 @@ By default, the property is set to false to avoid accidental exposure of their v - whether nodes, such as the Function node are allowed to have their own dynamically configured dependencies. The allow/denyList options can be used to limit what modules the runtime will install/load. It can use `*` as a wildcard that matches anything. -``` + +```javascript externalModules: { - // autoInstall: false, /** Whether the runtime will attempt to automatically install missing modules */ - // autoInstallRetry: 30, /** Interval, in seconds, between reinstall attempts */ - // palette: { /** Configuration for the Palette Manager */ - // allowInstall: true, /** Enable the Palette Manager in the editor */ - // allowUpdate: true, /** Allow modules to be updated in the Palette Manager */ - // allowUpload: true, /** Allow module tgz files to be uploaded and installed */ - // allowList: ['*'], - // denyList: [], - // allowUpdateList: ['*'], - // denyUpdateList: [] - // }, - // modules: { /** Configuration for node-specified modules */ - // allowInstall: true, - // allowList: [], - // denyList: [] - // } + autoInstall: false, /** Whether the runtime will attempt to automatically install missing modules */ + autoInstallRetry: 30, /** Interval, in seconds, between reinstall attempts */ + palette: { /** Configuration for the Palette Manager */ + allowInstall: true, /** Enable the Palette Manager in the editor */ + allowUpdate: true, /** Allow modules to be updated in the Palette Manager */ + allowUpload: true, /** Allow module tgz files to be uploaded and installed */ + allowList: ['*'], + denyList: [], + allowUpdateList: ['*'], + denyUpdateList: [] + }, + modules: { /** Configuration for node-specified modules */ + allowInstall: true, + allowList: [], + denyList: [] + } }, ``` @@ -283,7 +290,7 @@ The allow/denyList options can be used to limit what modules the runtime will in **editorTheme** : The following property can be used to set a custom theme for the editor. See [here](https://github.com/node-red-contrib-themes/theme-collection) for a collection of themes to choose from. -``` +```javascript editorTheme: { //theme: "", @@ -417,7 +424,8 @@ ioMiddleware:{function or array}, (socket,next) - socket.io middleware **webSocketNodeVerifyClient** : The following property can be used to verify websocket connection attempts. This allows, for example, the HTTP request headers to be checked to ensure they include valid authentication information. -``` + +```javascript //webSocketNodeVerifyClient: function(info) { // /** 'info' has three properties: // * - origin : the value in the Origin header From 2744201a9e0abeb21d61bb17ea80ce6a7e2367a2 Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Sun, 31 Jul 2022 03:20:21 +0300 Subject: [PATCH 10/14] Added some info when the option was introduced --- docs/user-guide/runtime/configuration.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index b2c84196..ee09324d 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -28,7 +28,7 @@ The settings are split into the following sections: ### Flow File and User Directory **flowFile** -: the file used to store the flows. Default: `flows.json` +: the file used to store the flows. If not set, defaults to `flows_.json`
Default: `flowFile: 'flows.json',` **credentialSecret** : By default, credentials are encrypted in storage using a generated key. To specify your own secret, set the following property. If you want to disable encryption of credentials, set this property to false. Note: once you set this property, do not change it - doing so will prevent node-red from being able to decrypt your existing credentials and they will be lost. Example: `credentialSecret: "a-secret-key",` @@ -43,6 +43,7 @@ The settings are split into the following sections: : By default, all user data is stored in a directory called `.node-red` under the user's home directory. To use a different location, the following property can be used `userDir: '/home/nol/.node-red/',` Default: `$HOME/.node-red` **nodesDir** +*Since Node-RED 3.0.0.* : a directory to search for additional installed nodes. Node-RED searches the `nodes` directory under the *userDir* directory. This property allows an additional directory to be searched, so that nodes can be installed outside of the Node-RED install @@ -81,6 +82,7 @@ The settings are split into the following sections: *Standalone only*. **httpsRefreshInterval** +*Since Node-RED 2.0.0.* : If the `https` setting is a function, the following setting can be used to set how often, in hours, the function will be called. That can be used to refresh any certificates. `httpsRefreshInterval : 12,` **requireHttps** @@ -118,6 +120,7 @@ The settings are split into the following sections: : the root url for the editor UI. If set to `false`, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the `disableEditor` property below. Default: `/` **httpAdminMiddleware** +*Since Node-RED 2.0.0.* : an HTTP middleware function, or array of functions, that is added to all admin routes. The format of the middleware function is documented [here](http://expressjs.com/guide/using-middleware.html#middleware.application). @@ -190,16 +193,17 @@ The `pass` property is the md5 hash of the actual password. The following *Standalone only*. **httpRoot** -: this sets the root url for both admin and node endpoints. It overrides the values set by `httpAdminRoot` and `httpNodeRoot`. - +: *Deprecated*: see `httpAdminRoot` and `httpNodeRoot`. ### Runtime **lang** +*Since Node-RED 2.0.0.* : the following option is to run node-red in your preferred language.
Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. Some languages are more complete than others. **diagnostics** +*Since Node-RED 3.0.0.* : Configure diagnostics options. ```javascript @@ -213,6 +217,7 @@ Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. So When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. **runtimeState** +*Since Node-RED 3.0.0.* : enable or disable flows/state ```javascript @@ -250,11 +255,13 @@ The default level is `info`. For embedded devices with limited flash storage you : The following property can be used to enable context storage. The configuration provided here will enable file-based context that flushes to disk every 30 seconds. Refer to the documentation for further options [here](https://nodered.org/docs/api/context/) **exportGlobalContextKeys** +*Since Node-RED 2.0.0.* : `global.keys()` returns a list of all properties set in global context. This allows them to be displayed in the Context Sidebar within the editor. In some circumstances it is not desirable to expose them to the editor. The following property can be used to hide any property set in `functionGlobalContext` from being list by `global.keys()`. By default, the property is set to false to avoid accidental exposure of their values. Setting this to true will cause the keys to be listed. **externalModules** +*Since Node-RED 2.0.0.* : Configure how the runtime will handle external npm modules. This covers:
- whether the editor will allow new node modules to be installed
- whether nodes, such as the Function node are allowed to have their own dynamically configured dependencies. @@ -351,10 +358,12 @@ editorTheme: { ### Node Any node type can define its own settings to be provided in the file. -**fileWorkingDirectory** +**fileWorkingDirectory** +*Since Node-RED 2.0.0.* : The working directory to handle relative file paths from within the File nodes defaults to the working directory of the Node-RED process. **functionExternalModules** +*Since Node-RED 1.3.0.* : if set to `true`, the Function node's Setup tab will allow adding additional modules that will become available to the function. See [Writing Functions](../writing-functions#using-the-functionexternalmodules-option) for more information. Default: `true`. **functionGlobalContext** @@ -392,6 +401,7 @@ ioMiddleware:{function or array}, (socket,next) - socket.io middleware debug sidebar tab. Default: `1000` **execMaxBufferSize** +*Since Node-RED 2.0.0.* : Maximum buffer size for the exec node. Defaults to 10Mb. `execMaxBufferSize: 10000000` **httpRequestTimeout** From f8071e228ac35d13ba85f36bc85424d6fb12376f Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Sun, 31 Jul 2022 19:02:12 +0300 Subject: [PATCH 11/14] Update diagnostics description Updated `diagnostics` description following Steve's suggestion Co-authored-by: Stephen McLaughlin <44235289+Steve-Mcl@users.noreply.github.com> --- docs/user-guide/runtime/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index ee09324d..45143713 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -208,10 +208,10 @@ Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. So ```javascript diagnostics: { - /** @type {boolean} enable or disable diagnostics. Must be set to `false` to disable */ + /** enable or disable diagnostics endpoint. Must be set to `false` to disable */ enabled: true, - /** @type {"basic"|"admin"} diagnostic level can be "basic" (default) or "admin" (more sensitive details are included) */ - level: "basic", + /** enable or disable diagnostics display in the node-red editor. Must be set to `false` to disable */ + ui: true, }, ``` When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. From cf6fc0a1f9e4644a36ed7cd790075cb78e4290f1 Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Sun, 31 Jul 2022 19:06:22 +0300 Subject: [PATCH 12/14] Update diagnostics description Co-authored-by: Stephen McLaughlin <44235289+Steve-Mcl@users.noreply.github.com> --- docs/user-guide/runtime/configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 45143713..d77b83e3 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -214,7 +214,8 @@ Available languages include: `en-US (default), ja, de, zh-CN, zh-TW, ru, ko`. So ui: true, }, ``` -When `enabled` is `true` (or unset), diagnostics data will be available at http://localhost:1880/diagnostics . When `level` is "basic" (or unset), the diagnostics will not include sensitive data. Set level to "admin" for detailed diagnostics. +When `enabled` is `true` (or unset), diagnostics data will be available at `http://localhost:1880/diagnostics`. +When `ui` is `true` (or unset), diagnostics data will accessible in the Node-RED Action List as "Show System Info" **runtimeState** *Since Node-RED 3.0.0.* From 6935318db3ba2278bafeabfe2f8e678db34a2054 Mon Sep 17 00:00:00 2001 From: unborn-andy <93290787+unborn-andy@users.noreply.github.com> Date: Sun, 31 Jul 2022 19:08:13 +0300 Subject: [PATCH 13/14] Update runtimeState description Co-authored-by: Stephen McLaughlin <44235289+Steve-Mcl@users.noreply.github.com> --- docs/user-guide/runtime/configuration.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index d77b83e3..1631d543 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -219,16 +219,15 @@ When `ui` is `true` (or unset), diagnostics data will accessible in the Node-RED **runtimeState** *Since Node-RED 3.0.0.* -: enable or disable flows/state +: enable or disable the ability to Start and Stop the runtime ```javascript runtimeState: { - /** enable or disable flows/state endpoint. Must be set to `false` to disable */ + /** enable or disable this feature. */ enabled: false, - /** show or hide runtime stop/start options in the node-red editor. Must be set to `false` to hide */ + /** show or hide runtime stop/start options in the node-red editor. */ ui: false, }, -``` **logging** : currently only console logging is supported. Various levels of logging can be specified. Options are: From afcedbcc2b574d62aee96ab583f8a4fc6fa9b8cb Mon Sep 17 00:00:00 2001 From: unborn-andy Date: Sun, 31 Jul 2022 19:22:54 +0300 Subject: [PATCH 14/14] Update runtimeState description --- docs/user-guide/runtime/configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guide/runtime/configuration.md b/docs/user-guide/runtime/configuration.md index 1631d543..4dabe9aa 100644 --- a/docs/user-guide/runtime/configuration.md +++ b/docs/user-guide/runtime/configuration.md @@ -228,6 +228,7 @@ When `ui` is `true` (or unset), diagnostics data will accessible in the Node-RED /** show or hide runtime stop/start options in the node-red editor. */ ui: false, }, +``` **logging** : currently only console logging is supported. Various levels of logging can be specified. Options are: