Configuration & Provisioning

Create the Configuration File

A configuration file can be created using the vendor platform instead of manually. Using the UI ensures all required fields are correctly configured and helps reduce the risk of errors. For a step-by-step guide, see Auto Generated Config File Guide.

1

Create a folder named config next to your Floating Server binary.

2

Inside this folder, create a file named default.yaml.

config/default.yaml

3

Use the following template:

database:
 # if using sqlite
  type: sqlite
  path: ./data/db.sqlite
# if using sqlcipher
  type: sqlcipher        # <-- switch from sqlite to sqlcipher
  path: ./data/app.db
  password: "your-password" 
# if using postgres
  type: postgres
  host: localhost
  port: 5432
  user: fsuser
  password: fspassword
  name: fsdb
  sslmode: "disable"   # options: disable, require, verify-ca
  sslrootcert: "/path/to/sslcert/ca.crt" # ignore if sslmode: "disable"
  CryptoProviderKey: "" # secret used to encrypt db data in OAuth mode

server:
  port: 8080 # port on which the server runs
  Verbose: true # level of information given in logs
  DisableUserAuth: false # disable user authentication requirement, not admin!

cloud:
  UseOAuth: false
  # if authenticating with API/Shared key
  APIKey: ""
  SharedKey: ""
  # if authenticating with OAuth
  ClientId: ""
  ClientSecret: ""
  # cloud server config
  BaseURL: "" # default: "https://api.licensespring.com"
  APIPrefix: "" # default: "/api/v4/"
  ServerPublicKey: "" # default: LicenseSpring Prod's public key
  # if having Airgap licenses, fetch this key from platform
  AirgapPublicKey: ""
  # provisioning config
  UseHardwareKey: false # choose provisioning method
  HardwareKeyPIN: "" # optional, custom PIN
  PrivateKeyPath: "" # path to generated priv key. Ignore if using hardware key
  CertificatePath: "" # path to cert received from LS

Comment out or remove the fields for the database type you are not using.

Database Configuration

The database section defines how the application connects to the underlying database. Two database types are currently supported: SQLite and PostgreSQL.

SQLite

When using SQLite, make sure the database directory specified in the YAML configuration file actually exists. For example, if you're using ./data/db.sqlite as shown in the sample above, ensure that the data directory exists. The Floating Server will not create missing directories automatically. The database file can be named anything. The server will create it if it doesn't exist.

If you're using SQLite, provide the file path for the database file:

type: sqlite path: ./data/db.sqlite

SQLCipher Integration

Starting from v2.1.0, we offer full encryption of the SQLite database. To enable it:

• In your config file, set the database type to sqlcipher instead of sqlite.

• Before running the server, install SQLCipher on your system (Linux or Windows) and ensure your app links to it.

Installing SQLCipher

Linux

sudo apt update
sudo apt install sqlcipher libsqlcipher-dev

Windows

If you’re on Win 10 or above, install WSL on Windows and run:

sudo apt-get install sqlcipher

PostgreSQL

Update the default.yaml file with the following:

Fields:

• host: The PostgreSQL server address (usually localhost for local development)

• port: Port number (default is 5432)

• user: The PostgreSQL username

• password: The password for the specified user

• name: The name of the database to connect to

type: postgres host: the posgres host port: the postgres port user: the user in db password: password name: give the db a name

Setting Up PostgreSQL (Local)

• Install PostgreSQL (if not installed)

• Create the database and user: run psql postgres then, inside the psql prompt:

psql

CREATE DATABASE fsdb;
CREATE USER fsuser WITH PASSWORD 'fspassword';
GRANT ALL PRIVILEGES ON DATABASE fsdb TO fsuser;

Verify the connection:

macOS / Linux

psql -h localhost -U fsuser -d fsdb

Windows (PowerShell)

You will be prompted to enter the password you set for the database user (for example, fspassword).

This process in MacOS is shown in the image below.

CryptoProviderKey

CryptoProviderKey is a secret key you may use to encrypt data before storing it in the database.

OAuth: You must set CryptoProviderKey to encrypt data in the database.

API/Shared Keys: Not required. The database uses SharedKey for encryption automatically.

Server Configuration

• Port: Network port the server listens on.

• Verbose: Set true for development logs, false for production.

• DisableUserAuth: Only set true for testing; this disables user authentication for license management features.

Cloud Configuration

• API/Shared Keys: Fill APIKey and SharedKey.

• OAuth: Set UseOAuth: true and provide ClientId, ClientSecret, and CryptoProviderKey.

• If your BaseURL or APIPrefix differs from the defaults, specify them in the cloud section. You must also provide the server’s public key in the following format:

ServerPublicKey: |
  -----BEGIN PUBLIC KEY-----
  (your public key here)
  -----END PUBLIC KEY-----

{% hint style="success" %} Floating Server v2.2.0+: The private key PEM supports either BEGIN RSA PRIVATE KEY or BEGIN PRIVATE KEY . {% endhint %}

Provisioning the Floating Server

Provisioning ensures that only authorized instances of the server are allowed to run.

Starting with Floating Server v2.2.0, provisioning can be completed using either:

• Hardware Key authentication (YubiKey), or

• The previously supported certificate-based method (CSR)

Both provisioning options are available and managed through the LicenseSpring Platform. This section provides a high-level overview; detailed steps for each method are outlined below.

Floating Server Provisioning with Certificates (CSR)

{% stepper %} {% step %} Generate a key pair:

openssl genrsa -out private.key 2048 {% endstep %}

{% step %} Provision via the LicenseSpring Platform:

• Open the LicenseSpring Platform.

• Navigate to Enterprise Company → Licenses → Floating Servers.

• Click Provision the Floating Server. {% endstep %}

{% step %} Choose Certificate as the authentication type:

• Enter a name and optional expiration date.

• Generate a CSR (Certificate Signing Request) locally.

• Copy the contents of request.csr into the LS Platform form and click Confirm. {% endstep %}

{% step %} Download and save certificates:

• Save the issued certificate (e.g., certificate.crt).

• Generate the chain certificate from the platform (e.g., chain.pem).

• Keep your private key accessible. {% endstep %}

{% step %} Update default.yaml:

cloud:
  UseHardwareKey: false # choose provisioning method
  PrivateKeyPath: "" # ignore if using hardware key
  CertificatePath: "" # ignore if using hardware key

Image: Provisioning the Floating Server

Floating Server Provisioning Using a Hardware Key

As an alternative to certificate-based provisioning, the Floating Server can be provisioned using a hardware key (dongle). This method authorizes the server based on the presence of a physical security device connected to the machine. When a hardware key is enabled, the Floating Server workflow remains largely the same as in the previously described examples, with the added requirement of a connected hardware key.

Use this option when physical enforcement or offline licensing is required.

Optional: Set a Custom Hardware Key PIN

Before starting the provisioning process with a hardware key, you may choose to update the default hardware key PIN. If you set a custom PIN, ensure that the new value is included in the Floating Server configuration file, as shown below.

Configuration for Hardware Key Provisioning

When provisioning with a hardware key, update the configuration file (default.yaml) accordingly:

UseHardwareKey: true # choose provisioning method
HardwareKeyPIN: "" # optional, custom PIN
CertificatePath: "" # path to cert received from LS

To use a YubiKey with the Floating Server, set the UseHardwareKey configuration value to true. When this option is enabled, the server detects the hardware key and establishes the connection during startup.

The Floating Server only checks for the hardware key during startup. If the key is unplugged while the server is running, the connection cannot be re-established automatically.

Requirements

• A supported hardware key (YubiKey)

• Hardware key drivers installed on the server

• Hardware key physically connected to the Floating Server machine

• Required permissions to perform this action

1

Provision the Floating Server:

• Open the LicenseSpring Platform

• Navigate to → Licenses → Floating Servers

• Click Provision the Floating Server

• Enter a server name

• Select Hardware Key as the authentication type

• Follow the steps in the platform UI and click Confirm

To download the YubiKey provisioning application, refer to Hardware Key Licensing.

Create a License for Hardware Key–Based Floating Server Use

After provisioning the Floating Server with a hardware key, you must create a license that is explicitly enabled for hardware key usage.

When creating or editing the license in the LicenseSpring Platform:

1

Navigate to Licenses

2

Create a new license

3

Enable the Required Hardware Key option (checkbox)

4

Save the license

Only licenses with the Hardware Key option enabled can be used with a Floating Server that is provisioned using a hardware key.

Licenses without this option enabled will not be accepted by a hardware key–provisioned Floating Server.

Hardware Key and Server Lifecycle

In Floating Server v2.2.0, the server’s lifecycle is tightly coupled to the hardware key connection:

• When the server starts, it establishes a connection to the hardware key.

• When the server shuts down, the hardware key connection is closed.

• If the hardware key is disconnected while the server is running, the server will shut down gracefully.

Current Limitations

As of v2.2.0, offline bundles and air-gapped licenses are not supported when using a hardware key. Support for these scenarios will be added in future versions.