Skip to content

Configuration

Ioto is controlled via several JSON/5 configuration files that are that are read at startup by Ioto.

The configuration files are are copied from the select appplication ./app/NAME/config directory into the top-level ./config directory.

File Description
device.json5 Device registration configuration.
ioto.json5 Primary Ioto configuration file. Configures enabled services, logging and log file ingestion
local.json5 Local configuration for development.
schema.json5 Database data schema.
signature.json5 REST API signatures.
web.json5 Web server configuration file.

State files are stored in the "./state" directory and are created as Ioto executes:

File Description
ioto.crt Allocated Ioto certificate for cloud communications.
ioto.key Allocated Ioto certificate key for cloud communications.
provision.json5 Device and cloud provisioning configuration.
shadow.json5 Local copy of the AWS IoT shadow state.
state.db Saved database.

JSON/5

Ioto uses a human-readable JSON/5 for configuration. JSON/5 an extension of JSON that makes it easier to create, read and maintain configuration files in JSON.

JSON/5 adds the following JavaScript features to JSON.

  • Object keys may be JavaScript identifiers without quotes.
  • Objects or arrays may have a trailing comma.
  • Strings may be single quoted.
  • Strings may span multiple lines (single, double or back-tick quotes).
  • Numbers may have a leading or trailing decimal point, can be hexadecimal, and may begin with a plus.
  • Values may be regular expressions.
  • The undefined value may be used.
  • Single and multiline comments are allowed and preserved.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    // single-comment
    /*
        Multi-line comment
    */
    unquotedKey: 42,
    singleQuoteString: 'The "lazy brown fox" jumped...',
    multiLine: "Line one
        line two
    ",
    hex: 0x42,
    trailingComma: {
        one: 1,
        two: 2,
    },
}

Some Ioto configuration properties accept numeric values as human-readable string with unit suffixes. In this case, the value must be string. The limits and timeouts properties in the web.json5 file support the suffixes: unlimited, infinite, kb, k, mb, m, gb, g, byte, bytes, infinite, never, sec, secs, seconds, min, mins, minute, minutes, hr, hrs, hour, hours, day, days, week, weeks, month, months, year and years.

Profiles

Configuration files can provide multiple property profiles that can be selected at runtime. When Ioto is run, it executes with selected profile. This is typically prod for production and dev for development. However, you can create your own profiles for any desired execution configuration such as qa or test.

The Ioto profile is defined via the PROFILE environment variable or via the --profile command line option.

Configuration profiles are defined under the conditional.profile property in any configuration file. The relevant configuration properties are selected by the current Ioto profile.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
conditional: {
    profile: {
        dev: {
            limits: {
                //  Override the default stack size
                stack: '64k',
            }
        },
        prod: {
            log: {
                //  Send trace to a specific output file
                path: 'ioto.log',
            }
        }
    }
}

Ioto Configuration

The primary Ioto configuration file is called config/ioto.json5.

Here is a sample ioto.json5:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    services: {
        database: true,
        keys: true,
        logs: false,
        mqtt: true,
        provision: true,
        serialize: 'auto',
        shadow: false,
        sync: true,
        upgrade: true,
        url: true,
        web: false,
    },
    files: [
        {path: '/var/log/sys*log', group: 'ioto', stream: '{hostname}' }
    ],
    limits: {
        stack: '16k',
    },
    log: {
        path: 'aws',
        format: '%D %H %A[%P] %T %S %M',
        types: 'error,info',
        sources: 'all',
    }
}

The configuration file defines the following items:

  • The services to enable.
  • The files files to capture and send to CloudWatch logs.
  • The Ioto execution limits that defines the default stack size
  • The Ioto log log configuration.

The configuration properties are defined in the Configuration Properties.