# Configuration & Provisioning

### Create the Configuration File

{% hint style="success" %}
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](/floating-server/floating-server-v2/configuration-and-provisioning/auto-generated-config-file-guide.md).
{% endhint %}

{% stepper %}
{% step %}
Create a folder named `config` next to your Floating Server binary.
{% endstep %}

{% step %}
Inside this folder, create a file named `default.yaml`.

> config/default.yaml
> {% endstep %}

{% step %}
Use the following template:
{% endstep %}
{% endstepper %}

```yaml
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 Microsoft SQL Server
   type: sqlserver
   host: localhost
   port:            # port on which your SQL Server instance is running
   user: floating_user
   password: fs_password
   name: FloatingServerDB
   CryptoProviderKey: ""      # secret used to encrypt db data in OAuth mode
# 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

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

server:
  port: 8080 # port on which the server runs
  Verbose: true # level of information given in logs
  BasePath: "" # path prefix of the server
  DisableUserAuth: false # disable user authentication requirement, not admin!
  LogDestination: ""   # path to log output file (e.g. "./logs/app.log"). 

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
  SyncIntervalMinutes: 0    # can be skipped, default is 0.
  SyncIntervalHours:   1    # can be skipped, defulat is 1.
  DisableSync:         false   # can be skipped, default is false
```

{% hint style="warning" %}
Comment out or remove the fields for the database type you are not using.
{% endhint %}

{% hint style="info" %}

### Cloud sync interval configuration <a href="#cloud-sync-interval-configuration" id="cloud-sync-interval-configuration"></a>

You can control how often the Floating Server syncs with LicenseSpring Cloud by configuring two options under the `cloud` section of the server configuration file:

```
cloud:
SyncIntervalMinutes: 0    # can be skipped, default is 0.
SyncIntervalHours:   1    # can be skipped, default is 1.
```

* `SyncIntervalHours` defines the number of hours between syncs.
* `SyncIntervalMinutes`defines the number of additional minutes between syncs.

The server combines these values into a single sync interval. The total interval must be between 5 minutes and 24 hours. If the configured values fall outside this range, the server will reject the configuration and log an error indicating that the interval must be between 5 minutes and 24 hours.
{% endhint %}

### Database Configuration

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

#### SQLite

{% hint style="warning" %}
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.
{% endhint %}

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](/floating-server/floating-server-v2/changelog.md), 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

```bash
sudo apt update
sudo apt install sqlcipher libsqlcipher-dev
```

Windows

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

```bash
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:

{% code title="psql" %}

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

{% endcode %}

Verify the connection:

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
psql -h localhost -U fsuser -d fsdb
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
psql -h localhost -U fsuser -d fsdb
```

{% endtab %}
{% endtabs %}

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.

![](https://api.archbee.com/api/optimize/6CLcmIv1QNNDgKDDEXj7l-wZn45Xy7Fpmp843-vU5I0-20250808-014609.png)

#### CryptoProviderKey

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

{% hint style="warning" %}
OAuth: You must set `CryptoProviderKey` to encrypt data in the database.

API/Shared Keys: Not required. The database uses `SharedKey` for encryption automatically.
{% endhint %}

### 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.
* BasePath: Starting in v2.3.0, you can configure Floating Server to serve under a path prefix by setting `BasePath`. When `BasePath` is set (for example, `/licensing`), the server will be reachable at:

  `http://<host>:<port>/<base-path>`.

### 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:

```yaml
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

```bash
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 provisioning

* Enter a name and optional expiration date.
* Generate a CSR (Certificate Signing Request) locally.
* Copy the contents of `request.csr` into the platform form.
* Click **Confirm**.
  {% endstep %}

{% step %}

### Download and save certificates

* Save the issued certificate (for example, `certificate.crt`).
* Download the chain certificate (for example, `chain.pem`).
* Keep your private key accessible.
  {% endstep %}

{% step %}

### Update `default.yaml`

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

{% endstep %}
{% endstepper %}

Image: Provisioning the Floating Server

![](/files/3773e5cdf0e9854775b63e008fb76eb44f18a7db)

<figure><img src="/files/gFFCbsr6jAB7FO8GT99Y" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/1ofz4ksIRnXF1koJuuAt" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/n81dEqtncvh0GCE6g3YU" alt=""><figcaption></figcaption></figure>

Once you select **Edit Config File**, as shown in the image above, you can define the Floating Server settings, including the port and sync interval. The port (default: 8080) can be customized to match your network setup. The sync interval determines how often the server communicates with LicenseSpring Cloud and is configured using `SyncIntervalHours` and `SyncIntervalMinutes`, which are combined into a single interval. This interval must be between 5 minutes and 24 hours; otherwise, the configuration will be rejected.

### 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.<br>

{% hint style="warning" %}
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.
{% endhint %}

#### 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:

```yaml
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.

{% hint style="info" %}
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.
{% endhint %}

#### 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

{% stepper %}
{% step %}
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
  {% endstep %}
  {% endstepper %}

![](/files/d31c1b8ff8872d89321729314abd3637b6ddb7de)

{% hint style="info" %}
To download the YubiKey provisioning application, refer to [Hardware Key Licensing](/license-entitlements/license-activation-types/hardware-key-licensing.md).
{% endhint %}

#### 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:

{% stepper %}
{% step %}
Navigate to Licenses
{% endstep %}

{% step %}
Create a new license
{% endstep %}

{% step %}
Enable the Required Hardware Key option (checkbox)
{% endstep %}

{% step %}
Save the license
{% endstep %}
{% endstepper %}

![](/files/fa04c86f75e2a419fd3c29fc724c451fdfa052f3)

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

{% hint style="info" %}
Licenses without this option enabled will not be accepted by a hardware key–provisioned Floating Server.
{% endhint %}

#### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.licensespring.com/floating-server/floating-server-v2/configuration-and-provisioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.