Advanced configuration

Owned by Javier Celaya (Unlicensed)
Last updated: Oct 31, 2019 by Jorge Olmos (Unlicensed)
7 min read

Usually, default settings are fit for everyone, but sometimes flexVDI components must be further configured to your needs. flexvdi-config is the main configuration utility, but not-so-common options can be set through various configuration files.

flexVDI Agent

The flexVDI Agent is configured by editing the file /etc/flexvdi/flexvdi-agent.conf. Editing it will automatically reload the flexvdi-agent service, so you do not need to do it explicitly. This is an INI-formated text file that configures the CherryPy engine. Values are integers, booleans or strings. For boolean values, case-insensitive values "true", "yes" and 1 all mean true, and anything else means false. The configuration file also contains the following flexVDI-specific sections:

  • Storage
    • disk_pattern_list: String. This is a string with a comma-separated list of file patterns that identify disk block devices. Default value is "/dev/sd[a-z],/dev/sd[a-z][a-z],/dev/drbd[0-9],/dev/drbd[0-9][0-9]", which icludes all SCSI and DRBD devices. flexVDI will allow you to pass these devices as physical disks to a guest, or create OCFS2 volumes on them. DO NOT include multipath devices here, they are automatically detected.
    • allow_overcommit: Boolean. Sets whether images are created with thick or thin provisioning. Its default value is false, which means images are created with their disk space allocated in advance. Otherwise, images are created with 0 bytes allocated, and they grow as needed.
  • Monitors. The flexVDI Agent includes a set of monitors that check the the system periodically.
    • intmon_warning: Integer. Timeout in seconds to warn about a monitor that has not notified its activity yet. Its default value is 60.
    • intmon_fail: Integer. Timeout in seconds to restart the flexVDI agent if a monitor has not notified its activity yet. Its default value is 120.
    • domains: Integer. Period in seconds to check running virtual machines. Default value is 10.
    • volumes: Iteger. Period in seconds to check mounted volumes. Default value is 10.
    • mediastorages: Integer. Period in seconds to check mounted media storages. Default value is 10.
    • disks: Integer. Period in seconds to check for new disk devices. As this is an expensive operation, its default value is 30, but the value in the installed configuration file is 0, meaning disks are discovered only at startup.
    • watchdog: Integer. Period in seconds to check Manager's health. Default value is 10.
    • watchdog_iterations: Integer. Number of iterations in which the Manager appears to be failed after which it is restarted.
  • Debug
    • log_level: String. Minimum log level of the messages that are written to the log file. Default value is INFO. Other possible values are DEBUG, WARNING and ERROR. Setting the log level to DEBUG will not output all the debug messages, you also have to set one or more of the following options.
    • disks: Boolean. Output debug messages related to disk management.
    • volumes: Boolean. Output debug messages related to volumes.
    • domains: Boolean. Output debug messages related to virtual machine lifecycle.
    • spice: Boolean. Output spice server debug messages to the Qemu log file.
    • debug_domains: String. Comma-separated list of GLib debug domains for the spice server. If the spice flag is true, the "Spice" domain is always included.

Watchdog

When the flexVDI Agent is also in charge of keeping the flexVDI Manager instance up and running, it uses another configuration file at /etc/flexvdi/flexvdi-agent-watchdog.conf. It must contain a JSON object with information on how to check that the flexVDI Manager instance is alive, and restart it when needed. This file is created and maintained automatically when the Manager is installed, upgraded or moved to a different volume, so you should not need to modify it.

The following keys are recognized, and all of them are mandatory (no default values):

  • ipaddress: IP address of the flexVDI Manager instance. It is used to check that the Manager is alive.
  • vmname: Name of the libvirt domain that contains the flexVDI Manager.
  • vmimage: Path to the flexVDI Manager image that contains its operating system. This image is replaced when the Manager is upgraded.
  • vmdata: Path to the flexVDI Manager image that contains its data (database, configuration and log files).
  • vmpassword: Spice password of this virtual machine. If you have problems getting the flexVDI Manager up and running, you can connect to its console using a generic Spice client (like the Spicy binary that is distributed with the flexVDI Dashboard). Connect to the IP of the host that is running the Manager, port 5800, and use this password.
  • instance: Instance ID of this platform. The instance ID is part of the MAC address of all the virtual machines in the platform, so that there is no address collision with another flexVDI platform in the same subnetwork.
  • ha_mode: High availability mode. Either "single" or "clustered". Single means that only one host is in charge of keeping the Manager alive, and is used after the installation of the flexVDI Manager. When the Manager is first moved to a volume, this parameter changes to clustered.
  • storage_mode: Either "internal", "external" or "ocfs2". Internal is only used when ha_mode is "single". Otherwise, the storage_mode parameter states the kind of volume where the Manager is stored, "ocfs2" for a Volume and "external" for an External Volume.
  • imagestorage_id: Image Storage ID where the Manager is stored, if ha_mode is "clustered". The old name "ocfs2_imagestorage_id" is also accepted, but deprecated.
  • volume_id: Volume ID where the Manager is stored, if ha_mode is "clustered". The old name "ocfs2_volume_id" is also accepted, but deprecated.
  • ocfs2_primarydisk_id: If the storage_mode is "ocfs2", this parameter states the SCSI id of the disk that contains the OCFS2 volume, so that it can be mounted.
  • mount_point: If the storage_mode is "external", the mount point of the external volume.
  • host_list: List of hosts that must check the Manager instance is alive, and can bring it up when it is not. It only contains the current host when ha_mode is "single", and the list of hosts that can access the Image Storage where the Manager is stored when ha_mode is "clustered".

Log files

Log messages are output to /var/log/flexvdi/flexvdi-agent.log, as configured in the flexvdi-agent.conf file. This file is rotated every 10MB and the last 10 files are kept. Besides, since Libvirt is used to manage virtual machines, you should also check the files in directory /var/log/libvirt. In particular, a log file is created for each virtual machine in the /var/log/libvirt/qemu directory. Although they use very small space, their number can grow quite fast if you use volatile desktops. Keep an eye on this directory to delete the log files of virtual machines that you do not need anymore.

flexVDI Manager

The flexVDI Manager instance is a virtual machine running CentOS 7.5, with the flexvdi-manager service and a mongodb database. You can log into this virtual machine with SSH, user root and the Manager password you have configured with flexvdi-config (the password is flexvdi by default).

This virtual machine's persistent storage consists of two disk images. The first one, vda, contains one partition with the operating system and the binary code of flexvdi-manager and mongodb. It is replaced every time you upgrade the Manager version, so everything you install to this disk will be deleted.

The second one, vdb, contains a partition that is mounted in /flexvdi/external with the following directories:

  • db: Contains the MongoDB data files.
  • network: The network configuration scripts.
  • manager: The manager configuration files.
  • log: /var/log is a symlink to this directory, and contains all the system log files, including the ones for the flexvdi-manager and mongodb services.

If you ever run out of space in the vdb disk (e.g. your log or database files have grown too much) you can just stop the flexVDI Manager instance and make its data disk image bigger. On the next restart, the partition and file system it includes will be resized automatically as needed. For instance, if your flexVDI Manager data image is in /var/lib/flexvdi/local and you wanted it to have 1GB more of space, you would run:

# virsh destroy flexVDI Manager
# qemu-img resize /var/lib/flexvdi/local/flexvdi-manager-data +1G

After some minutes, the flexVDI Agent will restart the flexVDI Manager instance and the new space will be available. Never shrink the image file, it will end in data corruption.

Configuration

Since flexVDI 3.1, the configuration for the flexvdi-manager service is divided into two files, /flexvdi/external/manager/application.conf and /flexvdi/external/manager/flexvdi.conf, where the first one includes the second. The application.conf file configures the Play and Akka Frameworks, so it uses the HOCON file format. The flexvdi.conf file configures the flexVDI Manager features.

Do not change Play and Akka configuration unless you know what you are doing.

The flexVDI properties are:

  • flexvdi.desktop_broker.demo: Boolean, default false. This flag activates the demo mode, in which a certain username is considered as if no authentication was used. Useful for showcasing and guest users.

  • flexvdi.desktop_broker.demo_username: String, default "flexvdi". If demo mode is activated, this user is not authenticated against the LDAP server, and is considered as if no authentication was used, e.g. a guest user.

  • flexvdi.desktop_broker.demo_password: String, default "". Password for the demo user. If empty, any password is valid.

  • flexvdi.desktop_broker.clone_name_pattern: String, default "${t}-volatile-${r}". A pattern to name cloned desktops after, with placeholders that are replaced with actual desktop properties. Valid placeholders are:

    • ${d}: Desktop Policy name that created the clone.
    • ${t}: Template name from which the clone comes.
    • ${p}: Pool name from where resources are being taken.
    • ${w}: Windows domain configured in the Desktop Policy.
    • ${i}: Image Storage name where the clone images are stored.
    • ${v}: Volume name where the clone images are stored.
    • ${r}: A random string with 8 alphanumeric (lower-case letters and numbers) characters.

  • flexvdi.host_agent.fail_threshold: Int, default 60. Number of seconds after which a host that is not responding becomes unavailable.

  • flexvdi.host_agent.port: Int, default 9443. TCP port where flexVDI Agents are listening to.

  • flexvdi.host_agent.use_ssl: Boolean, default true. Use TLS when connecting to the flexVDI Agents.

  • flexvdi.spice_port_base: Int, default 5900. First Spice port to assign.

  • flexvdi.spice_port_num: Int, default 10000. Number of Spice ports to assign, in sequence. So, the last port is spice_port_base + spice_port_num.

  • flexvdi.hw_address_base: String, default "02:f1:00:00". First four octets of the MAC addresses of the virtual machines. MAC addresses are then assigned by varying the last two octets (65534 addresses). When the Manager is installed for the first time, this parameter is initialized to "02:f1:00:id", where id is the instance id of the platform. This avoids MAC address collisions between flexVDI platforms in the same subnetwork.

  • flexvdi.hw_address_num: Int, default 1000. Maximum number of MAC address to assign.

  • flexvdi.secure_server: Boolean, default false. If this flag is set to true, the environment is considered "secure" and no authentication is required for API calls. For debug purposes only.

  • flexvdi.db_name: String, default "flexvdi". The name of the MongoDB database. For debug purposes only.

Log files

The flexVDI Manager's log files are stored in /flexvdi/external/log/manager*.log. The MongoDB log files are stored in /var/log/mongodb/mongod.log.

The logging configuration resides in the file /flexvdi/external/manager/logger.xml. It is an XML log file that configures Logback, check its documentation for details. The default configuration is:

  • All the messages are sent to the log file. It is rotated and gzip-ed every day and every 100 MB, keeping 15 days worth of logs and 3GB at most.
  • Messages with level INFO or higher of the flexVDI logger are also sent to Syslog in localhost, with USER facility.
  • Messages with level lower than INFO are filtered out for the flexVDI and Play Framework loggers, lower than ERROR for any other logger.

Usually, if you need additional messages to be recorded, set the DEBUG level in the correct logger and restart the flexvdi-manager service.

TLS certificate

If you want to use your own TLS certificate for HTTPS connections on port 443 (e.g. to access the Dashboard web application), you can overwrite the file /flexvdi/external/manager/nginx.cert with a PEM-formated file that contains both the certificate and the private key.