Configuration

This chapter describes the configuration format and usage of Sylvia-IoT.

Sylvia-IoT supports four sources of configuration, prioritized as follows (from highest to lowest):

• JSON5 configuration file
• Command-line parameters
• Environment variables
• Internal default values (may not exist; if required but not provided, an error message will be displayed)

You can refer to the sample JSON5 file for a complete list of configuration options. This chapter will provide corresponding explanations. The following conventions apply to the configuration:

• The nested structure in JSON5 is represented using . (dot).
• For command-line parameters that encounter nested JSON5, the dot notation is also used.
• For command-line parameters corresponding to camelCase JSON5 properties, they will be written in all lowercase or with - followed by lowercase. For example:
  • JSON5 property server.httpPort corresponds to --server.httpport.
  • JSON5 property broker.mqChannels corresponds to --broker.mq-channels.
• Environment variables are written in all uppercase.
• For environment variables that encounter nested JSON5, _ (underscore) is used.
• For environment variables corresponding to camelCase JSON5 properties, they will be written in all uppercase or with _ (underscore) separating words. For example:
  • JSON5 property server.httpPort corresponds to SERVER_HTTP_PORT.
  • JSON5 property broker.mqChannels corresponds to BROKER_MQCHANNELS.

Here are the complete table explanations:

If marked with Refer to example, it means that the sample JSON5 is provided or you can use the CLI help command to view the supported options.

Common Settings

Detailed Explanation

• Root certificate is not currently used.
• Both certificate and private key must be used simultaneously to enable HTTPS service.

API Scopes

All APIs require access through registered clients and access tokens. Each token is associated with a specific client, and only authorized clients can access the APIs.

When a particular API is configured with apiScopes settings, the access token must include the relevant scopes enabled by the client during registration and authorized by the user to access that API.

Both command-line parameters and environment variables should be provided as JSON strings. For example:

--auth.api-scopes='{"auth.tokeninfo.get":[]}'

You can define custom scope names and apply them to various API scopes. You can refer to the example provided in the Authentication Service section for more details.

Authentication Service (auth)

Detailed Explanation

• Templates:
  • These are the web pages required for the OAuth2 authorization code grant flow. sylvia-iot-auth provides default pages, but Sylvia-IoT allows you to customize web pages to match your own style.
  • The templates use the Jinja2 format (dependent on the tera package).
  • Both command-line parameters and environment variables should use JSON strings. For example:

    --auth.templates='{"login":"xxx"}'
    

  • For more details, please refer to OAuth2 Authentication.
• API scopes
  • The auth module provides the following scopes that can be configured for corresponding APIs to limit the scope of access for clients:
    • auth.tokeninfo.get: Authorize clients to read token data.
      • GET /api/v1/auth/tokeninfo
    • auth.logout.post: Authorize clients to log out tokens.
      • POST /auth/api/v1/auth/logout
    • user.get: Authorize clients to access current user's profile data.
      • GET /api/v1/user
    • user.path: Authorize clients to modify current user's profile data.
      • PATCH /api/v1/user
    • user.get.admin: Authorize clients to access data of all system users.
      • GET /api/v1/user/count
      • GET /api/v1/user/list
      • GET /api/v1/user/{userId}
    • user.post.admin: Authorize clients to create new users in the system.
      • POST /api/v1/user
    • user.patch.admin: Authorize clients to modify data of any system user.
      • PATCH /api/v1/user/{userId}
    • user.delete.admin: Authorize clients to delete data of any system user.
      • DELETE /api/v1/user/{userId}
    • client.get: Authorize clients to access data of all system clients.
      • GET /api/v1/client/count
      • GET /api/v1/client/list
      • GET /api/v1/client/{clientId}
    • client.post: Authorize clients to create new clients in the system.
      • POST /api/v1/client
    • client.patch: Authorize clients to modify data of any system client.
      • PATCH /api/v1/client/{clientId}
    • client.delete: Authorize clients to delete data of any system client.
      • DELETE /api/v1/client/{clientId}
    • client.delete.user: Authorize clients to delete all clients of any system user.
      • DELETE /api/v1/client/user/{userId}
  • For example, in your service, you define the following scopes:
    • api.admin: Only authorize the removal of all clients of a user.
    • api.rw: Allow read and write access to all APIs except DELETE /api/v1/client/user/{userId}.
    • api.readonly： Only allow access to GET APIs.
    • Allow access to token data and log out actions for all clients.

    "auth": {
        ...
        "apiScopes": {
            "auth.tokeninfo.get": [],
            "auth.logout.post": [],
            "user.get": ["api.rw", "api.readonly"],
            "user.patch": ["api.rw"],
            "user.post.admin": ["api.rw"],
            "user.get.admin": ["api.rw", "api.readonly"],
            "user.patch.admin": ["api.rw"],
            "user.delete.admin": ["api.rw"],
            "client.post": ["api.rw"],
            "client.get": ["api.rw", "api.readonly"],
            "client.patch": ["api.rw"],
            "client.delete": ["api.rw"],
            "client.delete.user": ["api.admin"],
        },
        ...
    }
    

    • In this example, registered clients can freely select these three scopes. Subsequently, users will be informed of this information on the authorization page and decide whether to grant authorization to the client.

Message Broker Service (broker)

Detailed Explanation

• The purpose of specifying the Authentication Service URL (broker.auth) is to verify the legitimacy of API calls, including user accounts and clients.

• MQ channels:

  • As the Sylvia-IoT Message Broker Service is a critical module that determines performance, many configurations are stored in memory. These configurations need to be propagated to various instances of the cluster through Control Channel Messages via message queues when API changes are made.
    • For relevant details, please refer to the Cache chapter.
  • data represents the Data Channel Message, which records all data into the sylvia-iot-data module.
    • If no parameters are specified (or JSON5 is set to null), no data will be stored.
    • For relevant details, please refer to the Data Flow chapter.

• API scopes: Please refer to the explanation in the Authentication Service section.

Core Manager Service (coremgr)

Detailed Explanation

• MQ channels:
  • data represents the Data Channel Message.
    • Currently, coremgr supports recording HTTP request content for all API requests except GET. Enabling the data channel will record the API usage history.
    • If no parameters are specified (or JSON5 is set to null), no data will be stored.

Core Manager Command-Line Interface (coremgr-cli)

Data Service (data)