Differences

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

--- blocks:server:virtualized [2021-05-11 19:23]
admin Updated for Blocks 5
+++ blocks:server:virtualized [2023-03-27 10:05] (current)
mattias [Connecting the USB License Key to Another Computer]
@@ Line 2: / Line 2: @@
 While the full Linux-based server image can be installed on a virtual machine, it is not specifically designed for that purpose. Installations that run Blocks in a virtualized environment often have different priorities than those using a stand-alone server. Many of the features included in the full server Linux image are typically managed by other parts of the infrastructure in a virtualized environment.
-:!: This is an advanced guide. If you don't feel at home in a linux server terminal window, you should probably not follow it.
+:!: This is an advanced guide. If you don't feel at home in a Linux terminal window, you should probably not follow it.
 ===Minimal Server OS===
-The full Linux-based server runs an enhanced desktop version of Ubuntu, including a user friendly window-and-mouse based desktop environment. Thats suitable for users that prefer such a desktop environment for managing their server.
+The full Linux-based server runs an enhanced desktop version of Ubuntu, including a user friendly window-and-mouse based desktop environment. That's suitable for users that prefer such a desktop environment for managing their server. In contrast, the virtual server image discussed here runs on Debian, which is essentially the same operating system core, but a pure server-version, without any desktop environment. Thus, all system management and maintenance must be done from the command line.
-This virtual server image runs on Debian, which is essentially the same operating system core, but a pure server-version, without any desktop environment. Thus, all system management and maintenance must be done from the command line.
 ===No Webmin interface===
@@ Line 18: / Line 17: @@
 =====Virtual Environment=====
-This image is designed to be used in a virtualized environment. It is distributed as a [[https://int.pixilab.se/outgoing/files/Blocks5-Debian10.ova|OVA file]], compatible with most virtual hosts.
+This image is designed to be used in a virtualized environment. It is distributed as an [[https://pixilab.se/outgoing/blocks/virtualized/Blocks6-Debian10.ova|OVA file]], compatible with most virtual hosts from VMWare, Oracle, Synology and QNAP. The image is based on Debian 10, and includes Blocks software and all components required to run Blocks. For testing purposes, you can use one of the following:
-  * OVA image based on Debian 10. A complete virtual machine "image", containing the operating system (Debian 10), Java runtime, Blocks server software, and associated components.
-  * VirtualBox 6 or later. A free virtual machine available for most operating systems
+  * Oracle [[https://www.virtualbox.org/wiki/Downloads|VirtualBox]] – a free virtual machine available for most operating systems
-  * VMWare provides a wide variety of virtual environments, including the free "Workstation Player" and the popular "VMWare Fusion" program.
+  * VMWare's free "Workstation Player" as well as their popular "VMWare Fusion".
+After importing the OVA file into your virtualizer of choice, start it up and wait for the login screen to appear.
 =====Users and Passwords=====
-User name **root**, with password //pixi// is the root user of the system, and can do anything without restrictions. Be careful. Use for system software installation, upgrades, etc requiring super-user privileges. The password can be changed using the //passwd// command.
+For full system access, log in with the user name **root**, with password //pixi//. This **root** user can do anything without restrictions, so be careful. Use this user for for system software installation, upgrades, etc requiring super-user privileges. The password can be changed using the //passwd// command.
-User name **blocks**, with password //PixiServer!// is the account under which the Blocks server is run. This user has limited rights, and can not use the sudo command to escalate its privileges. The password can be changed by the root user using the //passwd blocks// command.
+User name **blocks**, with default password //PixiServer!// is the account under which the Blocks server is run. This user has limited rights, and can not use the sudo command to escalate its privileges (you can, however, use the //su// command to switch to the root user). The password can be changed by the root user using the //passwd blocks// command.
 =====Network Configuration=====
-On the Host computer, running VirtualBox (or other preferred virtualizer), add a Bridged adapter as the primary one.
+On the Host computer, running VirtualBox (or other preferred virtualizer), add a Bridged adapter as the primary one. You may need to shut down the Blocks server while changing network settings.
 ====Guest Linux OS terminal window====
-Find the name and verify connectivity of the network interface.
+Find the network interface name and verify connectivity.
-  * Use the command //ip addr// to see all network interfaces with their names. Ignore the lo loopback interface.
+  * Use the command //ip addr// to see all network interfaces with their names. Ignore the //lo// loopback interface.
-  * The name is typically something like enp0s3.
+  * The name is typically something like //enp0s3//.
   * If the interface is already UP, and you have internet access, you're done
   * Verify internet access by using the command //ping 1.1.1.1//, that should show the turn-around time in mS repeatedly if OK.
-===Verify/add network adapter settings===
-Specified by a file in /etc/network/interface.d
-Name the file //primary// (although the actual file name isn't important). Enter the following data into the file. You can do so using the simple terminal text editor //nano//.
+===Verify/Add Network Adapter Settings===
+If you didn't automatically get network access, you need to configure networking inside the virtual Blocks server. Settings are specified in the **/etc/network/interface.d** directory.
+If required, add a file there and name it //primary// (although the actual file name isn't important). Enter the following data into the file. You can do so using the simple terminal text editor //nano//.
 <code>
 auto enp0s3
@@ Line 52: / Line 53: @@
 :!: Do not use a wifi network interface, since that will typically not provide a dynamic address to the virtual machine.
-Alternatively, to use a fixed IP address instead, set the file primary to:
+Alternatively, to use a fixed IP address instead, edit the //primary// file discussed above to read something like this (specifying IP addresses and subnet width as appropriate for your network):
 <code>
 auto enp0s3
@@ Line 62: / Line 63: @@
 </code>
-After making changes, restart the virtual machine using //reboot now// or restart the networking stack by
+After making changes, restart the virtual machine using //reboot now// or merely restart the networking stack by
 //systemctl restart networking//.
-=====License Key Access=====
+=====License Access=====
-Blocks server software requires a license key to be operational. This license key connects to a USB port. It can be accessed either directly from that USB port or over a network connection.
+Blocks server software requires a license to be operational. Either connect a physical license key to a USB port or request a cloud-based license (requires internet access). A physical license key can be accessed either directly from a USB port attached to the virtual machine or over the local network.
-====Network Access from Host Computer====
+[[blocks:wibu|Install a Blocks license.]]
-This method provides access to the license key over the network. Assuming both the guest and host operating systems are on the same network (which they will be when using a network adapter in bridge mode), the license key can be accessed remotely. Thus, the physical USB key can be connected to the host computer and will be automatically found by Blocks.
-=== Host operating system ===
-  * Open the CodeMeter Control Center.
-  * Click the WebAdmin button, and wait for the web UI to appear.
-  * Select Configuration > Server.
-  * Under Network Server, select Enable.
-  * Click Apply.
-=== Guest operating system ===
-The CodeMeter software has been pre-installed, and configured to look for the license key on the network. To verify availability:
-  * Start the virtual machine.
-  * Once up, use the command //cmu --list-server --list-content//.
-  * This should show your network server's IP address and license information. Look for the text "102977"
-=== Attaching the license key to another computer ===
-In the example above, the license key is  physically connected to the host computer, and then accessed over the network. If you can't connect the license key to the host computer for some reason, you can connect it to another computer on the same subnet, and it will be found automatically by Blocks.
-It's also possible to access the license key attached to a computer on another network, assuming that computer can be reached by name or IP address. Contact PIXILAB for more information on this option, should you need it.
+=====Blocks Configuration=====
+There's no [[blocks:server_configuration_file|configuration file]] included for Blocks in the VM image. This means that Blocks defaults to HTTP over port 8080. Add a configuration file if you need to adjust Blocks' server settings. Note that since Blocks runs under a limited user account, ports below 1024 (thus including the default HTTP port 80) can't be directly specified in the configuration file. However, the included //nginx// program – acting as a reverse proxy – provides access to Blocks on the customary ports (80 and 443 if you have HTTPS enabled). More on //nginx// and HTTPS below.
-====Direct USB Access====
+=====Starting and Stopping Blocks=====
-If you have physical access to the computer running the virtualizer, you may prefer to connect the license key directly to this computer, and make the USB port accessible to the guest OS.
+Assuming that the license key is accessible, Blocks should start automatically. Blocks is started and stopped by an operating system service known as //[[https://wiki.debian.org/systemd|systemd]]//, which is controlled by the //systemctl// command line program. Since Blocks runs under the //blocks// user account, you must be logged in as the //blocks// user in order to control Blocks using //systemctl//. Use this command to determine whether Blocks is currently active:
-=== Host computer ===
+<code>
+systemctl --user status blocks
+</code>
-  * Connect the license key. The key must be physically connected to a USB port on the host computer.
+If Blocks is currently active, you should see the text "Active: active (running)" as part of the status. To enable and start Blocks, use this command:
-  * Do NOT install the CodeMeter driver/software (or disable it if already installed).
-:!: The host computer must NOT run the CodeMeter software, since only one driver may access the physical key at a time, and in this case this is the driver inside the virtual machine.
+<code>
+systemctl --user enable --now blocks
+</code>
-===VirtualBox settings ===
+To stop and disable Blocks:
-  * Select your guest OS in the list on the left hand side
-  * Select its Details settings pane
-  * Click USB
-  * Make sure "Enable USB Controller" is selected
-  * Add a "USB Device Filter" using the + button to the right
-  * Select your CodeMeter device
-To verify license key availability:
-  * Start the virtual machine.
-  * Once up, use the command //cmu -x//.
-  * This should show the details of your license key. Look for the text "102977".
-=====Blocks Configuration=====
+<code>
-There's no configuration file included for Blocks in the VM image. This means that Blocks runs only on port 8080 with the HTTP protocol. Add such a file for to adjust Blocks' configuration if desired. Note that since Blocks runs under a limited user account, ports below 1024 (thus including the default HTTP port 80) can't be specified in the configuration file.
+systemctl --user disable --now blocks
+</code>
-=====Security, Firewall and Ports=====
+Note that //systemd// differentiates between //starting// and //enabling// a service. The command shown above will do both. An //enabled// service will automatically be started as the server computer is started, which is useful f you for some reason need to restart your Blocks server (e.g., as the result of a power outage). To merely start or stop a service, without changing its enablement, use the //start// and //stop// sub-commands instead. See the //systemd// documentation for details.
-This section lists a number of optional enhancements and considerations. You don't need to do any of this to get a functioning Blocks system.
-====Security Considerations====
+If you run into trouble launching Blocks, and the //status// command doesn't provide sufficient details, you can use the //journalctl// command to obtain more details:
-===Secure Shell Remote Access (SSH)===
+<code>
-Secure Shell is not enabled in the VM image. SSH may be useful for many system configuration and remote access purposes. If desired, enable SSH in the VM's console window using the command //systemctl enable ssh// under the root account. Before enabling SSH, set a strong password for the blocks user account. The root account is not enabled for SSH access. This can be changed in the file /etc/ssh/sshd_config.
+journalctl -n 20 --no-pager --user-unit blocks
+</code>
-===Firewall===
+This will show the 20 most recent //systemd// log messages related to blocks. Again, you must be logged in as the //blocks// user in order to use this command.
-The firewall is not enabled in the VM image. Very few services are enabled, so you may not need a firewall since only the required ports are exposed. Feel free to configure and enable the included //iptables// firewall if desired. Alternatively, use an external firewall.
-====HTTPS====
+=====Using HTTPS with Blocks=====
-HTTPS is not enabled by default. If your server is exposed to the Internet, you're strongly advised to use and enforce HTTPS. Enable HTTPS in Blocks' configuration file or using a reverse proxy in front of Blocks.
-===Certificate===
+The server image includes [[http://nginx.org|nginx]], acting as a reverse proxy in front of Blocks. This can be configured to manage secure HTTPS connections, as described [[blocks:server:nginx|here]].
-Regardless of how you implement HTTPS, you'll need a certificate, provided by an official Certificate Authority. Either buy a certificate from such a company, or get one for free from https://letsencrypt.org. The certificate can either be used directly by the Blocks server (then specified in Blocks' [[blocks:server_configuration_file|configuration file]]), or by a reverse proxy (see below).
-====Port Remapping====
+=====Security Considerations=====
-You may enable the built-in //iptables// firewall, and use it to re-map the ports exposed by the Blocks server (e.g., port 8080) to other port numbers (e.g. port 80 for HTTP). Alternatively, such re-mapping can be used by an external router, or by a reverse proxy.
+This section describes some security considerations. You don't need to do any of this to get a functioning Blocks system.
-====Using a Reverse Proxy====
+===Secure Shell Remote Access (SSH)===
-A reverse proxy, such as NGINX, can be placed in front of Blocks, serving multiple purposes.
+Secure Shell is not enabled in the VM image. SSH may be useful for many system configuration and remote access purposes. If desired, enable SSH in the VM's console window using the command //systemctl enable ssh// while running as the root user. Before enabling SSH, set a strong password for the blocks user account. The root account is not enabled for SSH access. This can be changed in the file /etc/ssh/sshd_config (not recommended).
-:!: Configuration of NGINX or other reverse proxy software (e.g., Apache) is not supported by PIXILAB.
+===Firewall===
+The firewall is not enabled in the VM image. Very few services are enabled, so you may not need a firewall since only the required ports are exposed. Feel free to [[https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-20-04|configure and enable]] the pre-installed //ufw// firewall if desired. Or, even better, use an external firewall in your IT infrastructure.
-===Port Remapping===
-The reverse proxy can re-map port numbers as the traffic flows through it, thereby exposing HTTP on the default port 80 for the outside world, and passing it on to Blocks on port 8080. The same for HTTPS on port 443.
-===HTTPS termination===
-The reverse proxy can terminate the TLS connection, thus offloading the work of encryption and decryption from Blocks
-===Serving of Static Files===
-The reverse proxy can be configured to serve all static files (those under /public) by itself, rather than passing those requests on to Blocks. Offloading static files as well as TLS processing leaves more headroom in Blocks for dealing with more advanced functions.