Configuration Guide

1. Overview

This document describes the configuration options for the Northbound API application. The application uses multiple configuration files:

  • api.properties - Main API configuration

  • Environment variables (in Docker via .env.mysql or .env.oracle)

  • Spring configuration profiles in YAML format

  • hazelcast-client.yaml - Hazelcast client configuration for caching

2. API Properties Configuration

The api.properties file contains core settings that control the behavior of the API. This file is loaded from the path specified in the API_CONFIG_PATH environment variable.

2.1. SOAP API Configuration

Property Description

api.soap.url

SOAP API endpoint name. Default: FTACSWS

api.settings.response.transaction

Controls whether to show transactionId in the result XML. Default: true

2.2. Request Handling Settings

Property Description

api.settings.request.provision-add

Default value for reprovision when absent in request. Default: false

api.settings.request.timeout.parameters-get

Timeout in seconds for FTGetDeviceParameters(REST analog(HTTP method, path): POST, api/Parameter) when a source != "1". Default: 30

api.settings.request.timeout.device-create

Timeout in seconds to wait for CPE creation in FTCreateDevice(REST analog(HTTP method, path): PUT, api/Device/). 0 means no waiting. Default: 5

api.settings.request.device-create.product-class-check

Whether to check model name and OUI before creating CPE. Default: true

api.settings.request.parameters-check-exist

Whether to check if parameter exists (used in FTAddObject(REST analog(HTTP method, path): PUT, api/Object/) and FTSetDeviceParameters(REST analog(HTTP method, path): PUT, api/Parameter)). Default: false

api.settings.request.task.priority

Priority for tasks when isn’t set in the request. Default: 1

api.settings.request.push

Default value for push. Default: true

api.settings.request.oui-as-manufacturer

If true, allows setting manufacturer name to OUI field in all web methods. Default: false

api.settings.device.username-password-mandatory

Whether username and password are required for device operations. Default: false

2.3. Logging Configuration

Property Description

api.settings.log.db

Whether to store log information in the database (table process_log). Default: false

api.settings.log.file

Whether to store log information in the ProcessLog file. Default: false

api.settings.log.level

Log level setting: error (only errors and calls >5 seconds), debug (all calls), or other values (nothing), info - as debug + api.settings.log.columns.exclude=input_values, output_values. Default: error

api.settings.log.folder

Directory where ProcessLog files are stored. Default: ./logs (resolves to /app/logs inside the container). In Docker deployments, do not change this value — instead, adjust the volume mount in compose.yml or docker run to map /app/logs to the desired host directory (e.g., -v /opt/nbi-logs:/app/logs).

api.settings.log.columns.exclude

For api.settings.log.level=debug. Exclude columns for write to table process_log. Possible values: input_values, output_values, state, client_ip, server_ip, version, creator, appid. Default is empty.

api.settings.log.methods.exclude

For ProcessLogLevel=debug. Exclude methods for write to table process_log. Default is empty.

2.4. Runtime Log Level Management

The application supports changing the log level at runtime without restarting the container, using Spring Boot Actuator.

Level What is logged

ERROR

Critical errors only (lost connection to ACS/DB)

WARN

Business errors (device not found, invalid parameter) — without stack trace

INFO

Key operations (startup, authorization, main actions)

DEBUG

Detailed diagnostics + stack traces for business errors

In production use INFO. Switch to DEBUG temporarily when investigating issues — business errors will include full stack traces.

2.4.1. Changing log level on the fly (Actuator)

Changes take effect immediately, no restart required. Resets on container restart.

View current log level (GET)
curl http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi
Response example (HTTP 200)
{
    "configuredLevel": "DEBUG",
    "effectiveLevel": "DEBUG"
}
Switch to INFO (POST)
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "INFO"}'
Switch to DEBUG (POST)
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'
Reset to default (POST)
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": null}'
All POST requests return HTTP 204 No Content with an empty body — this is the expected success response. To verify the change, use the GET request above.
If the API runs over HTTPS (port 8443), use https://<host>:8443 and add -k for self-signed certificates.

2.4.2. Changing the log level for a specific package

# Example: enable DEBUG only for custom RPC service
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi.customrpc \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'

2.4.3. Changing log level via environment variable (on restart)

Set LOGGING_LEVEL_COM_FRIENDLY_NORTHBOUNDAPI in the environment file (.env.mysql or .env.oracle):

# Values: ERROR, WARN, INFO, DEBUG
LOGGING_LEVEL_COM_FRIENDLY_NORTHBOUNDAPI=INFO

The change takes effect on container restart.

2.4.4. Troubleshooting scenario: investigating a business error

  1. Enable DEBUG to get stack traces:

    curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'

  2. Reproduce the issue

  3. Collect logs — business errors now include full stack traces

  4. Restore INFO after investigation:

    curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.northboundapi \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "INFO"}'

2.5. Timeout Settings

Property Description

api.settings.timeout.push

Additional timeout in seconds for kickDevice (test online status). Used in FTCPEStatus(REST analog(HTTP method, path): POST, api/Device/Status), FTGetDeviceParametersTransID(REST analog(HTTP method, path): POST, api/Transaction/Parameter) and FTGetDeviceParameters(REST analog(HTTP method, path): POST, api/Parameter). Default: 60

api.settings.timeout.acs

ACS response timeout in seconds. Default: 120

api.settings.timeout.rpc

Timeout in milliseconds for waiting for RPC response in FTRPCInvoke(REST analog(HTTP method, path): PUT, api/Rpc). Default: 50000

api.settings.transaction.timeout

Transaction timeout in seconds. Default: 100

2.6. ISP and Authentication Settings

Property Description

api.settings.isp

ISP setting mode: 0 (both Domain by Subscriber info and ACS disabled), 1 (Domain by Subscriber info), 2 (Domain by ACS). Default: 2

api.settings.auth

Whether to enable authentication by username/password. Default: false

2.7. Upload Settings

Property Description

api.settings.upload.http.url

HTTP URL for upload. Default: http://127.0.0.1/put/

api.settings.upload.http.username

HTTP username for upload. Default: not set

api.settings.upload.http.password

HTTP password for upload. Default: not set

api.settings.upload.ftp.url

FTP URL for upload. Default: ftp://127.0.0.1/put/

api.settings.upload.ftp.username

FTP username for upload. Default: not set

api.settings.upload.ftp.password

FTP password for upload. Default: not set

api.settings.upload.extensions

List of extensions for upload files, delimited by ;. Default: .cfg

Maintain environment-specific versions of the upload endpoints (DEV/QA/PROD) in api.properties. For example, keep production credentials and URLs in the production artifact while pointing staging environments to isolated HTTP/FTP servers so that firmware and configuration packages stay segregated.

2.8. Miscellaneous Settings

Property Description

api.settings.statistics

Whether to write statistics into 'process_stat'. Default: false

api.connection.strings.encrypted

Whether connection strings are encrypted. Default: false

api.device.parameters.retrieval.method

Defines which ACS method is used by FTGetDeviceParameters: Directly (use getParameterDataListDirectlyFromCPE) or Polling (use getParameterDataListFromCPE). Default: Directly

3. Environment Variables Configuration

The application uses environment variables for configuring database connections, service endpoints, and other runtime settings. These variables can be specified in the environment file (.env.mysql or .env.oracle) when running with Docker.

3.1. Application Configuration

Environment Variable Description

PORT

HTTP port. When HTTPS is enabled, this value is used by the additional plain-HTTP connector (http.port). Default: 8080

HTTPS_PORT

Primary HTTPS listener port (server.port). Set explicitly for HTTPS mode. Typical value: 8443

SPRING_PROFILES_ACTIVE

Active Spring profile (local, mysql, or oracle). Default: mysql

SERVER_SSL_ENABLED

Enable HTTPS/TLS listener (true/false). Default: false

SERVER_SSL_KEY_STORE

Path to the TLS keystore, for example file:/etc/app/keystore.p12

SERVER_SSL_KEY_STORE_PASSWORD

Password for the TLS keystore

SERVER_SSL_KEY_STORE_TYPE

Keystore type (PKCS12 or JKS). Default: PKCS12

SERVER_SSL_KEY_PASSWORD

Private key password (if different from keystore password)

SERVER_SSL_KEY_ALIAS

Alias of the certificate key in the keystore. Default: server

SERVER_SSL_TRUST_STORE

Optional trust store path used for custom CA or mTLS setups

SERVER_SSL_TRUST_STORE_PASSWORD

Password for optional trust store

To enable HTTPS in Docker, place keystore file (for example keystore.p12) in ./configs, set SERVER_SSL_ENABLED=true, set HTTPS_PORT=8443, and provide keystore passwords in the environment file. In this mode Tomcat starts with two connectors: HTTPS on HTTPS_PORT and HTTP on PORT. Keep PORT and HTTPS_PORT different to avoid connector binding conflicts.

3.2. Database Configuration

3.2.1. Common Settings

Environment Variable Description

DB_MAX_POOL_SIZE

Upper bound for the HikariCP pool. Raise it for high-concurrency workloads, but be mindful of the actual database limits. Default: 10

DB_MIN_IDLE

Minimum number of warm connections that HikariCP keeps ready. Lower values reduce idle resource usage; higher values keep latency low for bursty workloads. Default: 5

DB_CONNECTION_TIMEOUT_MS

How long the application will wait for a free connection before failing a request. Increase this when the database experiences temporary spikes. Default: 30000

3.2.2. MySQL Profile

Environment Variable Description

MYSQL_JDBC_URL

Complete JDBC URL override. Provide this when you need extra connection parameters or wish to skip separate host/port/schema variables. Default: auto-generated from MYSQL_HOST, MYSQL_PORT, and MYSQL_SCHEMA.

MYSQL_HOST

MySQL hostname. Defaults to DB_HOST, which lets you point everything to a Docker DNS name such as northbound-db.

MYSQL_PORT

The port exposed by the MySQL server or container. Default: 3306

MYSQL_SCHEMA

Schema (database) name that stores the ACS data. Default: ftacs

MYSQL_USER

User account used by the application. Adjust this if you delegate access through a read/write database role. Inherits DB_USERNAME when unset. Default: ftacs

MYSQL_PASSWORD

Password for MYSQL_USER. Inherits DB_PASSWORD when not explicitly set. Default: ftacs

MYSQL_DRIVER_CLASS_NAME

Driver class used by Spring Boot. Change it only when targeting a MySQL-compatible engine with a vendor driver. Default: com.mysql.cj.jdbc.Driver

MYSQL_SCHEMA_IOTW

Schema (database) name of the OneIoT web back-end, read by the second iotw datasource that powers the Group Update API. Connects on the same MYSQL_HOST/MYSQL_PORT and with the same MYSQL_USER/MYSQL_PASSWORD as the ACS datasource. Default: iotw

MYSQL_URL_IOTW

Complete JDBC URL override for the iotw datasource. Provide this when the OneIoT schema lives on a different host or needs extra connection parameters. Default: auto-generated from MYSQL_HOST, MYSQL_PORT, and MYSQL_SCHEMA_IOTW.

3.2.3. Oracle Profile

Environment Variable Description

ORACLE_JDBC_URL

Complete JDBC URL override. Useful when connecting through Oracle Wallets or adding advanced parameters – the host/port/service variables are ignored once this is set. Default: jdbc:oracle:thin:@//{ORACLE_HOST}:{ORACLE_PORT}/{ORACLE_SERVICE}

ORACLE_HOST

Oracle hostname or service name exposed via Docker. Defaults back to DB_HOST.

ORACLE_PORT

Oracle listener port. Default: 1521

ORACLE_SERVICE

Oracle service/SID that contains the ACS schema. Default: XEPDB1

ORACLE_USER

Shared fallback user for both Oracle datasources. Used when the datasource-specific ORACLE_USER_FTACS / ORACLE_USER_IOTW overrides are not provided. Default: ftacs

ORACLE_PASSWORD

Shared fallback password for both Oracle datasources. Used when the datasource-specific ORACLE_PASSWORD_FTACS / ORACLE_PASSWORD_IOTW overrides are not provided. Default: ftacs

ORACLE_USER_FTACS

User owning the ACS (FTACS) schema. Falls back to ORACLE_USER when unset. Default: ftacs

ORACLE_PASSWORD_FTACS

Password for ORACLE_USER_FTACS. Falls back to ORACLE_PASSWORD when unset. Default: ftacs

ORACLE_USER_IOTW

User owning the OneIoT web back-end schema, read by the second iotw datasource that powers the Group Update API. In Oracle the schema is identified by this user, so set it to the account that owns the OneIoT tables. Falls back to ORACLE_USER when unset. Default: iotw

ORACLE_PASSWORD_IOTW

Password for ORACLE_USER_IOTW. Falls back to ORACLE_PASSWORD when unset. Default: ftacs

ORACLE_DRIVER_CLASS_NAME

Oracle JDBC driver class name. Keep oracle.jdbc.OracleDriver unless you package a customized datasource implementation. Default: oracle.jdbc.OracleDriver

3.2.4. IOTW (OneIoT) Datasource

The application opens a second datasource named iotw against the OneIoT web back-end schema. It is required by the Group Update API (condition views are read from this schema); other endpoints do not use it.

It is configured through the active database profile rather than a separate variable set:

  • MySQL profile — reuses MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DRIVER_CLASS_NAME. Only the schema differs, via MYSQL_SCHEMA_IOTW (or a full MYSQL_URL_IOTW override). See MySQL Profile.

  • Oracle profile — reuses the same listener (ORACLE_HOST/ORACLE_PORT/ORACLE_SERVICE or ORACLE_JDBC_URL) and ORACLE_DRIVER_CLASS_NAME. The schema is selected by a dedicated account through ORACLE_USER_IOTW / ORACLE_PASSWORD_IOTW. See Oracle Profile.

There are no IOTW_DATABASE_URL / IOTW_DATABASE_USER / IOTW_DATABASE_PASS / IOTW_DRIVER_CLASS_NAME variables — the iotw datasource is driven entirely by the *_IOTW variables of the active profile listed above.

3.3. SQL Login Queries

The following properties define SQL statements used to authenticate administrative users:

Property Description

SQL_LOGIN_BY_NAME_AND_LOCATION0

Query to authenticate by name when location_id = 0. SELECT password, location_id FROM admin.login WHERE name = :name AND location_id = 0

SQL_LOGIN_BY_NAME_AND_LOCATIONS

Query to authenticate by name when location_id is in a list of domain/location IDs. SELECT password, location_id FROM admin.login WHERE name = :name AND location_id IN (:ids)

SQL_LOGIN_BY_NAME_NULL_OR_0

Query to authenticate by name when location_id is NULL or 0. SELECT password, location_id FROM admin.login WHERE name = :name AND (location_id IS NULL OR location_id = 0)

3.4. ACS Service Configuration

Environment Variable Description

ACS_URL

Base URL of the ACS service (scheme + host, without port/path). Use http://…​; for HTTP ACS or https://…​; for HTTPS ACS. Examples: http://ftacs, http://127.0.0.1, http://host.docker.internal, http://acs.example.internal, https://acs.example.internal. Default: http://127.0.0.1

ACS_PORT

Port of the ACS service. Typical values: 8080 (HTTP), 443 or 8443 (HTTPS). Default: 8080

ACS_USERNAME

Username for ACS service authentication. Default: user

ACS_PASSWORD

Password for ACS service authentication. Default: secure-password

3.5. Other Configuration

Environment Variable Description

API_CONFIG_PATH

Path to API configuration properties file. Default: file:/etc/app/api.properties

CACHE_CONFIG_PATH

Path to Hazelcast client configuration directory. Default: file:/etc/app/

JWT_TOKEN_SECRET

Secret key for JWT token generation and validation. Default: friendly

JWT_TOKEN_EXPIRED

JWT token expiration time in milliseconds. Default: 36000000 (10 hours)

LOGGING_LEVEL_COM_FRIENDLY_NORTHBOUNDAPI

Log level for the application package (com.friendly.northboundapi). Values: ERROR, WARN, INFO, DEBUG. In DEBUG mode business errors include stack traces. Can also be changed at runtime via Actuator (see Runtime Log Level Management). Default: DEBUG

Make sure to place the api.properties and hazelcast-client.yaml files at the paths specified by the environment variables API_CONFIG_PATH and CACHE_CONFIG_PATH, respectively; without these files, the application will not start.

4. Cache Configuration

The application uses Hazelcast for caching. The Hazelcast client configuration is stored in hazelcast-client.yaml (or hazelcast-client.yml in legacy deployments) and is mounted into the container via the CACHE_CONFIG_PATH environment variable. Place the file in the working directory next to api.properties when following the Docker layout from the installation guide so it resolves to /etc/app/hazelcast-client.yaml inside the container.

A configuration looks like this (update cluster-name to the value used by your Hazelcast deployment and adjust other fields as required):

# Copyright (c) 2008-2024, Hazelcast, Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# The default Hazelcast client configuration used in hz-cli script.
#
# This file differs from hazelcast-client-default.yaml in some settings
# and it is used in the ZIP/TAR distributions,
# which are the basis for other distributions like docker & package managers.
#
# To learn how to configure Hazelcast, please see the Reference Manual
# at https://docs.hazelcast.com/

hazelcast-client:
  cluster-name: dev
  properties:
    hazelcast.client.shuffle.member.list: true
    hazelcast.client.heartbeat.timeout: 60000
    hazelcast.client.heartbeat.interval: 5000
    hazelcast.client.event.thread.count: 5
    hazelcast.client.event.queue.capacity: 1000000
    hazelcast.client.invocation.timeout.seconds: 120

  network:
    # List of addresses for the client to try to connect to. All members of
    # a Hazelcast cluster accept client connections.
    # Use the format <hostname>:<port>
    # If a port number is not specified, port range 5701-5703 will be tried.
    cluster-members:
      - ipOrHostName:portLike5701
    # Whether client should discover and connect other members in the cluster
    # and route requests to them or only connects to the members listed
    # above.
    #    cluster-routing:
    #      mode: "ALL_MEMBERS"
    redo-operation: true
    connection-timeout: 60000
    socket-options:
      tcp-no-delay: false
      keep-alive: true
      reuse-address: true
      linger-seconds: 3
      buffer-size: 128
  near-cache:
    default:
      time-to-live-seconds: 90
      max-idle-seconds: 100
      invalidate-on-change: true
      in-memory-format: OBJECT
      serialize-keys: true
      local-update-policy: INVALIDATE
      preloader:
        enabled: false
        directory: directory
        store-initial-delay-seconds: 50
        store-interval-seconds: 10
  connection-strategy:
    async-start: true
    reconnect-mode: ASYNC
    connection-retry:
      initial-backoff-millis: 2000
      max-backoff-millis: 60000
      multiplier: 3
      cluster-connect-timeout-millis: 5000
      jitter: 0.5
  user-code-deployment:
    enabled: false

cluster-name must match the server-side Hazelcast configuration; using a mismatched value prevents the client from joining the cluster. Update cluster-members to match the hostnames or container names that run the Hazelcast members on your Docker network.

The default parameters and their values are:

Parameter Default Value Description

cluster-name

ft-iot-cache

Name of the Hazelcast cluster the client connects to.

properties.hazelcast.client.shuffle.member.list

true

Whether to shuffle the list of cluster members before attempting connection.

properties.hazelcast.client.heartbeat.timeout

60000

Heartbeat timeout in milliseconds for client-server health checks.

properties.hazelcast.client.heartbeat.interval

5000

Interval in milliseconds between heartbeat messages.

properties.hazelcast.client.event.thread.count

5

Number of threads dedicated to processing cluster events.

properties.hazelcast.client.event.queue.capacity

1000000

Maximum number of events to queue for processing.

properties.hazelcast.client.invocation.timeout.seconds

120

Operation invocation timeout in seconds before failure.

network.cluster-members

127.0.0.1:5701

Comma-separated list of cluster member addresses in host:port format.

network.redo-operation

true

Whether to automatically retry failed operations.

network.connection-timeout

60000

Socket connection timeout in milliseconds.

network.socket-options.tcp-no-delay

false

Enable TCP_NODELAY to disable Nagle’s algorithm.

network.socket-options.keep-alive

true

Enable SO_KEEPALIVE to detect dead peers.

network.socket-options.reuse-address

true

Enable SO_REUSEADDR to allow address reuse.

network.socket-options.linger-seconds

3

Linger time in seconds before closing the socket.

network.socket-options.buffer-size

128

Socket buffer size in bytes.

near-cache.default.time-to-live-seconds

90

Time-to-live for near-cache entries in seconds.

near-cache.default.max-idle-seconds

100

Maximum idle time in seconds before near-cache eviction.

near-cache.default.invalidate-on-change

true

Invalidate near-cache entries upon cluster data changes.

near-cache.default.in-memory-format

OBJECT

Format for storing cache entries (OBJECT or BINARY).

near-cache.default.serialize-keys

true

Whether to serialize keys when storing in near-cache.

near-cache.default.local-update-policy

INVALIDATE

Policy for handling local updates: INVALIDATE or CACHE.

near-cache.default.preloader.enabled

false

Whether the near-cache preloader is enabled.

near-cache.default.preloader.directory

directory

Filesystem directory to store near-cache preload data.

near-cache.default.preloader.store-initial-delay-seconds

50

Initial delay in seconds before the first preloader store.

near-cache.default.preloader.store-interval-seconds

10

Interval in seconds between preloader store executions.

connection-strategy.async-start

true

Whether to start the client connection process asynchronously.

connection-strategy.reconnect-mode

ASYNC

Reconnection strategy mode for handling lost connections.

connection-strategy.connection-retry.initial-backoff-millis

2000

Initial backoff in milliseconds for retrying connections.

connection-strategy.connection-retry.max-backoff-millis

60000

Maximum backoff in milliseconds for retrying connections.

connection-strategy.connection-retry.multiplier

3

Multiplier for exponential backoff between retries.

connection-strategy.connection-retry.cluster-connect-timeout-millis

5000

Timeout in milliseconds for initial cluster discovery.

connection-strategy.connection-retry.jitter

0.5

Jitter factor to randomize retry intervals.

user-code-deployment.enabled

false

Whether deployment of user-provided code is enabled.

5. Docker Configuration

When running in Docker, the application uses the settings from the environment file (.env.mysql or .env.oracle) and mounts the configuration files. The Docker container exposes port 8080 and includes a healthcheck to monitor application health.

See the Dockerfile and Docker Installation Guide for more details on Docker deployment.