Differences

This shows you the differences between two versions of the page.

--- blocks:server_configuration_file [2022-09-09 09:44]
admin typos
+++ blocks:server_configuration_file [2024-05-17 07:41] (current)
admin defaultSpotCSS added note
@@ Line 10: / Line 10: @@
 You can configure Blocks using a configuration file. There are two possible locations and names for this file:
-  - In the home directory of the user account under which the server is run, named //PIXILAB-Blocks-config.yml//.
+  - In the home directory of the user account under which Blocks runs, named //PIXILAB-Blocks-config.yml//.
-  - Inside Blocks' data folder, then named //config.yml//. Blocks' data folder must in this case be named “PIXILAB-Blocks-root”, and located in the home directory of the user account under which the server is run.
+  - Inside Blocks' data folder, then named //config.yml//. Blocks' data folder must in this case be named “PIXILAB-Blocks-root”, and located in the home directory of the user account under which Blocks runs.
-:!: On our Linux-based server, the home directory of the user account under which the server is at /home/pixi-server/.
+:!: **NOTE:** On our Linux-based server, this home directory is at /home/pixi-server/.
 Here’s an example of what you may find in this file:
 <code>
-# Location of Blocks' data folder
+# Location of Blocks' data folder.
+# IMPORTANT: If changed, you must also update any nginx configuration
+# accordingly. See under "Alternative Blocks Root Directory" below.
 root: /home/pixi-server/PIXILAB-Blocks-root
@@ Line 31: / Line 33: @@
   #corsPath: /rest/script/invoke/*
   #corsAllowOrigin: "*"
   applicationConnectors:
     - type: http
       port: 8080
+  #auth:    # Uncoment to control authorization settings explicitly
+  #  servlet:
+  #    security:
+  #      - matchers: internalMatcher
+  #        authorizers: isAuthenticated
+  #        clients: internalDigest  # internalDigest internalForm OidcClient
 scripting:
   watchFiles: true
@@ Line 71: / Line 81: @@
   * **root**. Absolute path to Blocks' root data directory. Not required when using the //config.yml// file inside your Blocks' root data directory (option 1 above). See more under [[#alternative_blocks_data_location|alternative blocks data location]] below.
-  * **serverRootRedirect**. Server path to go to when accessing the root level of the server. This is often used to specify the path to a Visitor Spot to be accessed by default by guests.
+  * **serverRootRedirect**. Server path to go to when accessing the root level of the server. This is often used to specify the path to a Visitor Spot to be accessed by default by guests using the //mobile// [[blocks:api:query-parameters|query parameter]].
-  * **defaultSpotCSS**. Specifies a default CSS file that will be automatically applied to all Spots. The path, if any, must be specified relative to the public directory.
+  * **defaultSpotCSS**. Specifies a default CSS file that will be automatically applied to all Spots. The path must be relative (with no leading slash), and is then relative to the server's //public// directory. Note that this CSS file is also applied to the editor (in order to be viewed there correctly), so some care must be taken to not interfere with the editor's operation.
   * **homeScreenIcon**. Specifies a custom home screen icon, to appear when adding a Spot to the home screen on an iOS or Android device. Specify the URL to the image file, which must be 180 x 180 pixels. Preferably, store the image on the Blocks server under /public/xxx, as shown in the example, using a URL specifying only the path to the image; e.g. "/public/img/my-icon-180.png".
   * **defaultNetwork**. Address of network interface (NIC) to be use for general broadcast data, such as wake-on-LAN packets. Set this to the NIC used by such devices if your server has more than one active NIC, to avoid having such data go out the wrong NIC.
   * **scripting**. The only option available hereunder is //watchFiles//. Set to //true// to automatically reload User Scripts and [[blocks:drivers:concepts|Devices Drivers]], as those are modified. Defaults to //false//, requiring that you restart the server to pick up any such file changes.
   * **artnet**. Options related to ArtNET/DMX-512 data. The //bindToAddress// sub-option specifies which NIC to use for Art-Net data. Set this to the IP address of the desired NIC if you want to segregate ArtNet data on a separate subnet. The //sendToAddress// sub-option specifies the destination address used by Art-Net data. If not specified, ArtNet data will be broadcast.
-  * **httpClient**. Configuration for outgoing http requests, as used by the //SimpleServer// scripting API. More details can be found [[https://www.dropwizard.io/en/latest/manual/configuration.html#man-configuration-clients-http|here]].
+  * **httpClient**. Options for outgoing http requests, as used by the //SimpleServer// scripting API. More details can be found [[https://www.dropwizard.io/en/latest/manual/configuration.html#man-configuration-clients-http|here]].
-  * **mirror**. Configuration options for the Blocks' [[blocks:server:mirror#mirror_server_configuration|mirroring service]].
+  * **mirror**. Options for Blocks' [[blocks:server:mirror#mirror_server_configuration|mirroring service]].
+  * **tftp**. Options for Blocks' internal TFTP-server, used for network booting of PIXILAB Player. See below.
+  * **mail**. Options for sending email from Blocks, such as the SMTP server credentials to use. See below.
+  * **apiKeys**. Keys and values for protecting Blocks API endpoints. See below.
+  * **mqtt**. Enables MQTT integration, optionally setting broker connection parameters. See below.
 Some top-level items have more complex structure, and are described individually below.
@@ Line 104: / Line 118: @@
     - type: http
       port: 8080
-    - type: https
-      port: 8443
-      keyStorePath: "/home/pixi-server/certs/pixi.guide.p12"
-      keyStoreType: PKCS12
-      keyStorePassword: 3xamplePwd
-      certAlias: 1
 </code>
 If not specified, port 8080 is used for http and https is disabled. Under Windows, you may change the http connector to use the standard port 80 instead, thus removing the need to type :8080 after domain name IP address in a browser. Under Linux/MacOS, you can not use ports below 1024.
-The above example is appropriate when using PIXILAB's Linux-based server, which provides //iptables// redirection rules for the standard port 80 (http) and 443 (https) to the ports specified above. The //keyStore// and //certAlias// options shown above depend on the certificate used for the [[blocks:server:https|https connection]]. PIXILAB can provide a certificate for use with the //pixi.guide// domain name. If you want to use another domain name, or access your Blocks installation from Internet using a domain name, you must obtain and install the necessary domain name and certificate yourself.
+The above example is appropriate when using PIXILAB's Linux-based server, which provides an //nginx// reverse proxy managing the standard HTTP port 80 by forwarding to port 8080, mentioned above. Learn more about the nginx reverse proxy, including how it can also be used to support HTTPS connection, [[blocks:server:nginx|here]].
-:!: A certificate has a limited timespan. You must replace the certificate with a new one before it expires, or your https connection will cease to work on the expiration date.
 See [[https://www.dropwizard.io/en/latest/manual/configuration.html#man-configuration-connectors|here]] for more details on advanced //applicationConnectors// settings. Those are advanced settings, that most users won't need. PIXILAB doesn't support servers where such advanced settings have been applied.
-=== server: requireHttps ===
+=== server: auth ===
-If set to true, a secure https connection will be enforced for all **/edit/…** operations, as well as **/spot/…** connections that need authentication. Spots used only for display purposes generally don't have a keyboard connected, and don't provide access to protected functions, so they will continue to use http.
+Specifies advanced authentication and authorization options. The settings shown above correspond to the defaults if no auth section is provided. In most cases, you don't need to specify these settings. If you specify the //internalForm// authorization method, a "Log Out" command will be added to Blocks' Page menu, allowing you to explicitly log out.   The OidcClient setting allows for integration with single-sign-on systems such as [[blocks:sso:adfs|Active Directory]] or [[blocks:sso:okta|OKTA]].
-The default value for requireHttps is normally false. However, if you switch to [[blocks:server:form_authentication|FORM]] authentication, the default value for requireHttps is true in order to prevent credentials from being sent as unencrypted plain text. To //never// enforce https from Blocks, set //requireHttps// to //false//. That is useful in cases where a reverse proxy is used in front of Blocks, and the reverse proxy then handles the https SSL offloading before passing requests on to Blocks.
-=== server: auth ===
-Specifies advanced authentication and authorization options. In most cases, you don't need to specify these settings. Use only when specifically instructed to do so, e.g. for integration with single-sign-on systems such as Active Directory or OKTA. Here's an [[https://int.pixilab.se/docs/blocks/sso/okta|example]] of how you can configure such options.
+:!: **IMPORTANT**: While the //internalForm// method provides log-out functionality, it also sends all authoriztion credentials, including your password, as clear text. The default //internalDigest// method, while not providing any log-out functionality, avoids sending your password as clear text. When using Blocks on publicly accessible networks, you're strongly advised to use and only allow [[blocks:server:nginx|encrypted connection#https_domain_name_and_certificate]] (HTTPS) for all editing operations.
 ==== Top level tftp item ====
 Specifies options for the built-in TFTP-server. This is intended for [[blocks:server:pxe-boot|network booting]] of PIXILAB Player. It accepts the following options:
@@ Line 180: / Line 182: @@
 See [[https://www.dropwizard.io/en/latest/manual/configuration.html#logging|here]] for more details on advanced logging. Those are advanced settings, that most users won't need. PIXILAB doesn't support servers where such advanced settings have been applied.
+==== Top level apiKeys item ====
-===== Alternative Blocks Data Location =====
+:!: **NOTE**: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.
+Lists a number of keys with their values:
+<code>
+apiKeys:
+  upload: "super-secret" # Value required as apiKey query parameter for uploads
+  customKey: "super-secret2"
+</code>
+The //upload// key's value (if specified) will be used by Blocks' [[blocks:api:upload|file upload API]]. When specified, all uploads must add an //apiKey// query parameter to their URL, with the value specified for the //upload// key.
+You can specify additional key/value pairs, as exemplified by the //customKey// key/value shown above. Such a key can then be applied to custom API endpoints decorated by @resource by also applying an @apiKey decorator, like this:
+<code>
+/* Receives a GET request such as:
+    http://<SERVER><:PORT-IF-REQUIRED>/rest/script/invoke/ScriptName/message/on/B
+   Exposing the trailing part (here "on/B") as the lastMessage property.
+ */
+@resource(undefined, 'GET')
+@apiKey("customKey") // Requires the query parameter apiKey=super-secret2
+public message(
+  body: object,    // Not used for GET requests (but must still be declared!)
+  trailer: string  // Trailing part of URL
+) {
+  this.lastMessage = trailer;
+  this.resetSoon();
+}
+</code>
+A function such as the one shown here must be placed in a User Script. For more information, see [[blocks:advanced_scripting#resource|this example]].
+:!: **IMPORTANT**: Unless you're using a secure (encrypted) server connection, //apiKey// query parameters are sent as clear text, and can be seen by anyone with access to your network. Learn more on how to use a secure (HTTPS) server connection [[blocks:server:nginx|here (if using our Linux based server image)]] or [[blocks:server:https|here]].
+==== Top level mqtt item ====
+:!: **NOTE**: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.
+<code>
+mqtt:
+  defaultBroker:
+    address: localhost  # Default is localhost
+    username: pixi   # Default is no username and password
+    password: pixi
+    encryption: false #Change to true if secure connection (tls) is available.
+</code>
+In the standard case, no explicit MQTT configuration is required, in which case a default broker connection to //localhost// with no username or password will be attempted. This is appropriate when using the MQTT broker included with our [[blocks:server:advanced_server_configuration:mqtt|Linux server image]] version 221214 and later.
+:!: **NOTE**: In addition to an MQTT broker, a suitable device driver is required for the device you want to control (here's an [[https://github.com/pixilab/blocks-script/blob/6.1/driver-archive/ShellySwitchGen1.ts|example MQTT driver]]).
+If you want to use a broker running on another computer, specify its IP address or name using the //address// setting as shown above. If your broker [[blocks:server:advanced_server_configuration:mqtt#security|requires authorization]] in order to connect, you must also specify the //username// and //password// options as ecpected by your broker's configuration.
+:!: **NOTE**: These are the credentials of your MQTT broker – not your Blocks server.
+===== Alternative Blocks Root Directory =====
 You can store Blocks' data somewhere else than in the “PIXILAB-Blocks-root” directory in the current user's home directory. This is done by putting a file named "PIXILAB-Blocks-config.yml" in the current user's home directory (option 1 of those mentioned at the top of this article). In this case, you must specify //root// in the configuration file:
@@ Line 189: / Line 250: @@
 </code>
-If running your Blocks server on windows, the PIXILAB-Blocks-config.yml is still placed in the user home directory (C:\Users\[Your username]) and the path to the root directory should follow this structure:
+:!: **IMPORTANT note for servers based on our Linux server image version 221214 or later**: If you change the root path in the configuration file you must also change the corresponding //root// path under //location// under //server// in the file /etc/nginx/sites-available/blocks. You must be logged in as the //pixi-admin// user to edit that file and use //sudo// to edit the file (e.g., //sudo nano /etc/nginx/sites-available/blocks//), and finally restart nginx (or reboot the server).
+=== Windows Alternative Blocks Root Location ===
+If you're running Blocks server under Windows, the //PIXILAB-Blocks-config.yml// file is placed in the current user's home directory at //C:\Users\[Your username]//. The path to the desired Blocks root directory must be specified like this:
 <code>
 root: C:/External4/Blocks
 </code>
 This option tells Blocks to look for its data at the specified path, thus allowing you to put Blocks' data directory where you want. Additional options are specified in this "PIXILAB-Blocks-config.yml" file, as Blocks will //not// look in its data directory for any config.yml file.