Service API Configuration

This document explains how to configure the Service API using the YAML configuration file (service-api.yml), which replaces the previous XML-based configuration (Configuration.xml). The configuration file allows customization of various aspects of the service including email settings, speed tests, subscription parameters, service groups, and wireless configurations.

1. Overview

The Service API configuration is now managed through a YAML file instead of XML. This change simplifies configuration and makes it more maintainable. The service-api.yml file must be created and properly configured before deploying the Service API.

2. File Location

When running the Service API in Docker, the configuration file should be placed in a directory that will be mounted to /etc/app/yml/ within the container:

mkdir -p /path/to/yml
touch /path/to/yml/service-api.yml
# Edit the file with your preferred editor
nano /path/to/yml/service-api.yml

3. Configuration Sections

The service-api.yml file contains several main sections that correspond to the different aspects of the Service API that can be customized.

3.1. API Configuration

This section configures the SOAP API settings:

api:
  soap:
    url: FTACSWS

3.2. Email Server Configuration

This section configures email server parameters for sending messages to users:

mail:
  from: example@mail.com
  host: smtp.mail.com
  login: login_name
  password: password
  port: 587
  ssl: true

Configuration options:

  • host - SMTP server address

  • port - SMTP port number

  • ssl - Enables or disables SSL encryption (Boolean)

  • from - "From" field in emails

  • login - Email account login name

  • password - Email account password

3.3. Speed Test Configuration

This section configures settings for measuring internet connection speed:

speed-test:
  download-url: http://82.80.120.71/webdav/FYI.tgz
  upload-file-size: 10000
  upload-url: http://82.80.120.71/webdav/

Configuration options:

  • upload-url - URL for uploading files during speed tests

  • upload-file-size - Size of the file to be uploaded (in bytes)

  • download-url - URL for downloading files during speed tests

The maximum file size for speed tests should not exceed 232 bytes.

3.4. Subscription Configuration

This section defines parameters for different types of services (wireless, VoIP, internet, IPTV) that can be enabled or disabled for customer subscriptions:

subscription:
  wireless:
    parameters:
      - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.Enable"
        path181: "Device.WiFi.AccessPoint.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
      - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.RadioEnabled"
        path181: "Device.WiFi.Radio.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
      # More wireless parameters...
  internet:
    parameters:
      - path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Enable"
        path181: "Device.PPP.Interface.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
  iptv:
    parameters:
      - path: "InternetGatewayDevice.Time.DaylightSavingsUsed"
        path181: ""
        activeValue: "1"
        inactiveValue: "0"

For each parameter:

  • path - Full parameter path for TR-098 devices

  • path181 - Full parameter path for TR-181 devices

  • activeValue - Value applied when the service is activated

  • inactiveValue - Value applied when the service is deactivated

3.4.1. Device-Specific Subscription Configuration

You can also define device-specific configurations for subscriptions:

subscription:
  # General parameters as shown above...
  devices:
    - key: "AudioCodes MP262"
      wireless:
        parameters:
          - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.Enable"
            path181: ""
            activeValue: "1"
            inactiveValue: "0"
          # More device-specific wireless parameters...
      voip:
        parameters:
          - path: "InternetGatewayDevice.Services.VoiceService.1.VoiceProfile.1.Line.1.Status"
            path181: ""
            activeValue: "Enabled"
            inactiveValue: "Disabled"
          # More device-specific VoIP parameters...
      internet:
        parameters:
          - path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Enable"
            path181: ""
            activeValue: "1"
            inactiveValue: "0"
      iptv:
        parameters:
          - path: "InternetGatewayDevice.Time.DaylightSavingsUsed"
            path181: ""
            activeValue: "1"
            inactiveValue: "0"

The key attribute identifies the device model as "Manufacturer product class" (e.g., "AudioCodes MP262").

3.5. Service Group Configuration

This section defines service groups and their parameters:

service-group:
  service-groups:
    - key: "group2"
      service-group-parameters:
        - key: "param1"
          path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.PortMapping.1.ExternalPort"
          path181: "Device.NAT.PortMapping.1.ExternalPort"
          readonly: false
          defaultValue: "1"
          values: "2,4,5,6"
    - key: "group3"
      service-group-parameters:
        - key: "NTP"
          path: "InternetGatewayDevice.Time.NTPServer1"
          path181: "Device.Time.NTPServer1"
          readonly: false
          defaultValue: "time.partner.co.il"
          values: "msn2.com"

For each service group parameter:

  • key - Parameter identifier

  • path - Full parameter path for TR-098 devices

  • path181 - Full parameter path for TR-181 devices

  • readonly - Whether the parameter is read-only

  • defaultValue - Default value for the parameter

  • values - Optional list of allowed values (comma-separated)

3.5.1. Device-Specific Service Group Configuration

Device-specific service group configurations can also be defined:

service-group:
  # General service groups as shown above...
  devices:
    - key: "AudioCodes MP2621"
      service-groups:
        - key: "group1"
          service-group-parameters:
            - key: "param1"
              path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Username"
              path181: ""
              readonly: false
              defaultValue: "Username@ISPMP"
              values: ""
            - key: "param2"
              path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Password"
              path181: ""
              readonly: false
              defaultValue: "MP"
              values: ""
        # More device-specific service groups...

The key attribute under devices identifies the device model as "Manufacturer product class".

3.6. Wireless Configuration

This section defines wireless-related parameters for different security types. It supports both default/general configurations (applied to all devices unless overridden) and device-specific configurations.

3.6.1. General/Default Wireless Configuration

Define default wireless security configurations that apply to all devices unless overridden by device-specific settings:

wireless:
  # Default/General wireless configuration (fallback for devices not specifically configured)
  unsecure:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "false"
  wep:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "hex"
        name: "WEPKey"
        override: ""
        send: "true"
  wpa:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  wpa2:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  mixed:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  wpaPersonal:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  wpa2Personal:
    parameters:
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  wpaWpa2Personal:
    parameters:
      - type: ""
        name: "Enable"
        override: ""
        send: "true"
      - type: "ascii"
        name: "PreSharedKey"
        override: ""
        send: "true"
  wpa3Personal:
    parameters:
      - type: "ascii"
        name: "SAEPassphrase"
        override: ""
        send: "true"
  wpa3PersonalTransition:
    parameters:
      - type: "ascii"
        name: "SAEPassphrase"
        override: ""
        send: "true"

3.6.2. Device-Specific Wireless Configuration

You can override default configurations for specific device models:

wireless:
  # General configurations as shown above...

  # Device-specific configurations (override defaults above)
  devices:
    - key: "Siemens SL 2141"
      unsecure:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "false"
      wep:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "true"
          - type: "hex"
            name: "WEPKey"
            override: ""
            send: "true"
      wpa:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "true"
          - type: "ascii"
            name: "PreSharedKey"
            override: ""
            send: "true"
      wpa2:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "true"
          - type: "ascii"
            name: "PreSharedKey"
            override: ""
            send: "true"
      mixed:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "true"
          - type: "ascii"
            name: "PreSharedKey"
            override: ""
            send: "true"
    - key: "AlticeLabs GR240JH"
      wpa3Personal:
        parameters:
          - type: "ascii"
            name: "SAEPassphrase"
            override: ""
            send: "true"

The key attribute identifies the device model as "Manufacturer product class" (e.g., "Siemens SL 2141").

For each wireless parameter:

  • type - Encryption key type:

    • Empty string: No specific type

    • "ascii": ASCII format

    • "hex": Hexadecimal format

  • name - Parameter name, one of:

    • "Enable" - Enable/disable wireless network

    • "RadioEnabled" - Enable/disable radio

    • "BeaconType" - Beacon type

    • "BasicEncryptionModes" - Basic encryption modes

    • "WEPKeyIndex" - WEP key index

    • "WPAAuthenticationMode" - WPA authentication mode

    • "WPAEncryptionModes" - WPA encryption modes

    • "IEEE11iAuthenticationMode" - IEEE 802.11i authentication mode

    • "IEEE11iEncryptionModes" - IEEE 802.11i encryption modes

    • "PreSharedKey" - Pre-shared key

    • "KeyPassphrase" - Key passphrase

    • "WEPKey" - WEP key

    • "SAEPassphrase" - SAE passphrase (for WPA3)

    • "SSID" - Service Set Identifier

  • override - Optional parameter to override:

    • "KeyPassphrase" can be specified to override "PreSharedKey"

  • send - Whether the parameter should be sent to the device:

    • "true" - Parameter will be updated if relevant input is present

    • "false" - Parameter will not be updated even if relevant input is present

4. Complete Configuration Example

Below is a complete example of a service-api.yml file with all sections:

api:
  soap:
    url: FTACSWS

mail:
  from: noreply@example.com
  host: smtp.example.com
  login: apimail
  password: securepassword
  port: 587
  ssl: true

speed-test:
  download-url: http://speedtest.example.com/test.bin
  upload-file-size: 10000
  upload-url: http://speedtest.example.com/upload/

subscription:
  wireless:
    parameters:
      - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.Enable"
        path181: "Device.WiFi.AccessPoint.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
      - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.RadioEnabled"
        path181: "Device.WiFi.Radio.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
      - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID"
        path181: "Device.WiFi.SSID.1.SSID"
        activeValue: "FriendlyNetwork"
        inactiveValue: ""
  internet:
    parameters:
      - path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Enable"
        path181: "Device.PPP.Interface.1.Enable"
        activeValue: "1"
        inactiveValue: "0"
  iptv:
    parameters:
      - path: "InternetGatewayDevice.Time.DaylightSavingsUsed"
        path181: ""
        activeValue: "1"
        inactiveValue: "0"
  devices:
    - key: "AudioCodes MP262"
      wireless:
        parameters:
          - path: "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.Enable"
            path181: ""
            activeValue: "1"
            inactiveValue: "0"
      voip:
        parameters:
          - path: "InternetGatewayDevice.Services.VoiceService.1.VoiceProfile.1.Enable"
            path181: ""
            activeValue: "Enabled"
            inactiveValue: "Disabled"

service-group:
  service-groups:
    - key: "internet"
      service-group-parameters:
        - key: "username"
          path: "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Username"
          path181: "Device.PPP.Interface.1.Username"
          readonly: false
          defaultValue: "user@isp.com"
          values: ""
    - key: "ntp"
      service-group-parameters:
        - key: "server"
          path: "InternetGatewayDevice.Time.NTPServer1"
          path181: "Device.Time.NTPServer1"
          readonly: false
          defaultValue: "pool.ntp.org"
          values: "0.pool.ntp.org,1.pool.ntp.org,2.pool.ntp.org"

wireless:
  devices:
    - key: "Default"
      wpa2:
        parameters:
          - type: ""
            name: "Enable"
            override: ""
            send: "true"
          - type: "ascii"
            name: "PreSharedKey"
            override: ""
            send: "true"
    - key: "Modern Router"
      wpa3Personal:
        parameters:
          - type: "ascii"
            name: "SAEPassphrase"
            override: ""
            send: "true"

5. Using the Configuration File

When deploying the Service API using Docker, mount the directory containing your service-api.yml file to /etc/app/yml/ inside the container:

docker run -d \
  --name service-api \
  --env-file app.env \
  -v /path/to/yml:/etc/app/yml \
  -v /path/to/logs:/app/logs \
  -p 8080:8080 \
  service-api:latest

Make sure the CONFIG_PATH environment variable is set to file:/etc/app/yml/ in your environment configuration.

6. Migration from Configuration.xml

If you’re migrating from the previous XML-based configuration, here’s a mapping of the main sections:

XML Section YAML Section

<mailConfiguration>

mail:

<speedTestConfiguration>

speed-test:

<subscriptionConfiguration>

subscription:

<serviceGroupConfiguration>

service-group:

<wirelessConfiguration>

wireless:

The structure has been simplified in the YAML format, but all the same configuration options are available.