Configuration Properties

These are the configuration properties for the primary ioto.json5 configuration file.

See the following descriptions for other configuration files:

File	Description
device.json5	Device configuration file.
local.json5	Local Ioto overrides configuration file.
web.json5	Web server configuration file.
schema.json5	Database data schema.

api

Name	api
Description	Collection of API endpoint URLs.
Synopsis	api: { "builder": "value", serialize: "value" }
Notes	The api property collection defines various API endpoints. The api.builder endpoint is for the Builder public API. The api.serialize endpoint is for your local device serialization service employed during device manufacture.

Example

api: {
    builder: 'https://api.admin.embedthis.com/api',
    serialize: 'http://localhost:4100/ioto/serialize',
}

certs

Name	certs
Description	Ioto Certificates.
Synopsis	certs: { aws: 'path', url: 'path' }
Notes	The certs.aws property defines a filename for the AWS root certificate bundle. The certs.url property defines a root certificate bundle that is used to verify domains used by the URL client. Ioto includes default certificates for the AWS root and URL root certificates.

Example

certs: {
    aws: 'certs/aws.crt',
    url: 'certs/roots.crt',
}

conditional

Name	conditional
Description	Conditional configuration properties.
Synopsis	conditional: { "Set-Name": { /* properties */ }
Notes	The conditional property collection is used to define a suite of different configurations for Ioto. For example, it can select a "dev" profile for development and a "prod" profile for productions. Selections are made based on a controlling top level property. The mode and profile properties are used to select relevant configuration sets to apply.

Example

conditional: {
    profile: {
        dev: {
            directories: {
                log: '.',
                state: 'state'
            }
        },
        prod: {
            directories: {
                log: '/var/log',
                state: '/var/lib/ioto'
            }
        }
    }
}

database

Name	database
Description	Control the Ioto database.
Synopsis	database: { properties... }
Notes	The database property collection defines the database, schema and operational parameters that govern the Ioto database.The path property defines the filename of the on-disk database store. Ioto will also create a database journal log file that appends a ".jnl" extension to this path. The schema property defines the database scheme that defines the database indexes, entities and data types. The maxJournalSize defines how big the database journal log should grow before Ioto rewrites the database. The maxJournalAge defines how long data should be preserved in the journal log before the database file is updated. These values should be sufficiently long as writing updated data to the journal is much more efficient that updating the database file. . The maxSyncSize property defined how much data should be buffered before synchronizing to the cloud. The path and schema properties can use @db and @config prefixes which will be expanded to "state/db" and "state/config" respectively. The service property defines when to run a database maintenance task to remove expired items that define an expiry via the "ttl" schema property.

Example

database: {
    path: '@db/state.db',
    schema: '@config/schema.json5',
    maxJournalSize: '1mb',
    maxJournalAge: '1min',
    maxSyncSize: '10k',
    service: '1hr',
},

directories

Name	directories
Description	Define default Ioto directories.
Synopsis	directories: { "log": ".", state: "./state" }
Notes	The directories property collection defines various directories used by Ioto. The directories.log directory is where log files will be saved. The directories.state directory is where runtime state including databases, certificates, web pages, configuration and shadow state will be stored. These can be overridden via the ioto command line --config, --state and --ioto options.

Example

directories: {
    log: '/var/log',
    state: '/var/lib/ioto',
}

limits

Name	limits
Description	Define execution limits for Ioto.
Synopsis	limits: { "key": "value", ... }
Notes	The limits property collection defines various execution limits for Ioto. The limits.reconnect property defines the delay after MQTT communications are lost before the agent will reconnect. This is useful to throttle network load in the event of a network disconnection. The limits.stack property defines the default size of fiber coroutine stacks.

Example

limits: {
    reconnect: '10 secs',
    stack: '32K',
}

limits.stack

Name	limits.stack
Description	Define the stack size of fiber coroutines for Ioto.
Synopsis	limits: { stack: "Number" }
Notes	The limits.stack property specifies the stack size for Ioto coroutines. This should be set to the maximum anticipated stack size for your executing code. The default stack size is 64K. The core Ioto code requires a stack size of 12K. It is recommended that you minimize your use of big stack buffer variables and your use of deep recursion both of which require much bigger fiber stacks.

Example

limits: {
    stack: '16K',
},

files

Name	files
Description	Define the list of files to ingest and send to CloudWatch logs.
Synopsis	files: { path: "filename", group: "log-group', stream: "log-stream" }
Notes	The files property contains one or more file definitions to ingest and send to CloudWatch logs. The definitions define the log file name, AWS CloudWatch log group and stream names. The path property may contain wild cards and all matching files will be ingested. The group property specifies the AWS log group name which must exist. The stream property specifies the AWS log stream name which must exist. The group and stream properties may contain tokens that are expanded before use. The supported tokens are: "{hostname}" which translates to the system hostname, "{instance}" which expands to the AWS EC2 instance name and "{deviceId}" which expands to the provisioned provision.deviceId property.
Example

files: [ {
    path: '/var/log/sys*log',
    group: 'ioto',
    stream: '{hostname}'
} ],

log

Name	log
Description	Control the Ioto log file output.
Synopsis	log: { path: 'path', format: 'format', types: 'types', sources: 'sources' }
Notes	The log property collection defines how and where Ioto logs execution information. The log.path property specifies the destination of the Ioto trace log. Set it to "stdout" or "stderr", "aws" or a filename. If set to "aws", then the log.group property specifies the AWS log group name and the log.stream property specifies the AWS log stream name. The format specifies a leading format for the message that contains printf style tokens that are expanded at runtime. The supported tokens are: 'A' for the application name, 'D' for the local datetime, 'H' for the system hostname, 'M' for the message, 'P' for the process ID , 'S' for the message source, and 'T' for the message type. The types property specifies the types of messages to emit. It may contain the following types: debug, error, info and trace. It may be set to "all" for all types. The sources property specifies a comma separated list of message sources to emit. Sources may be prefixed with "!" to subtract from the list. For example: "all,!json" will emit messages from all sources except "json".

Example

log: {
    path: '/var/log/ioto.log',
    format: '%D %H %A[%P] %T %S %M',
    types: 'error,info',
    sources: 'all'
}

mqtt

Name	mqtt
Description	MQTT configuration.
Synopsis	mqtt: { properties }"
Notes	The mqtt property collection is used to configure MQTT communications to the cloud. The mqtt.cert and mqtt.key properties define filenames to the X.509 certificate and key used to secure MQTT communications. The mqtt.client defines the MQTT client ID used to uniquely identify the device. The alpn property defines the HTTPS ALPN identification string required when using HTTP port 443 for communications. The mqtt.ca property defines the authority certificate from AWS that is used as the root certificate to verify the MQTT broker endpoint. The cert, key, client and endpoint properties can be set to "auto" to have their values dynamically configured from AWS IoT core at runtime. The timeout property defines the time period in which to disconnect an idle mqtt connection. The delay property defines how long to wait before reconnecting. The schedule property is a "cron" style specification that defines the time window in which MQTT connections can be established.

Example

mqtt: {
    cert: 'auto',
    key: 'auto',
    client: 'auto',
    endpoint: 'auto',
    port: 443,
    alpn: 'x-amzn-mqtt-ca',
    ca: 'certs/aws.crt',
    timeout: '5 mins',
    delay: '1 min',
    schedule: '* * * * *',
}

optimize

Name	optimize
Description	Build for debug or production release.
Synopsis	`optimize: "debug
Notes	If debug is selected, Ioto will be built with debug symbols. If release is selected, Ioto will be built optimized without debug symbols.

optimize: 'release'

profile

Name	profile
Description	Configuration profile to select.
Synopsis	`profile: "dev
Notes	The profile property is used to select different build and execution configurations for Ioto at runtime. For example, it can select a "dev" profile for development and a "prod" profile for productions. The profile property selects a set of configuration properties from the conditional.profile collections. These are copied to the top level and overwrite any existing top-level properties.

Example

profile: "prod"

scripts

Name	scripts
Description	Set of scripts used for various management tasks.
Synopsis	scripts: { update: './scripts/update'}
Notes	The scripts.update property defines a script that is invoked to apply software updates. The script is invoked with the pathname to the update image as the first and only argument.

scripts: {
    update: './scripts/update'
}

services

Name	services
Description	Configure which Ioto services to enable at runtime.
Synopsis	`services: { 'Service-Name': true
Notes	The services property collection defines which Ioto services to enable. The supported services are: database — Local embedded database keys — Generate and rotate IAM access credentials logs — Send local O/S log files to CloudWatch logs mqtt — MQTT services provision — Enable registration and provisioning of device in the cloud serialize — Invoke manufacturing serialization service at first boot during test. shadow — AWS IoT device shadows sync — Send device state to AWS database url — Client HTTP service web — Local web server Some services depend on others. Lower-level services will be forcibly enabled if upper level services require them.

Example

services: {
    database: true,
    keys: true,
    logs: true,
    mqtt: true,
    provision: true,
    register: true,
    serialize: 'auto',
    shadow: true,
    sync: true,
    update: true,
    url: true,
    web: true
}

timeouts

Ioto supports timeout properties that improve security by limiting the duration of requests. Additional timeouts are provided from the web.json5 timeouts configuration.

Name	timeouts
Description	Collection of timeout properties.
Synopsis	timeouts: { "Timeout-Property": "Timeout-Value", ...}
Notes	All timeout values are strings, not numbers. The string values may take human-readable suffixes which indicate the units for the value. The suffixes can be upper or lower case. The supported units are: infinite, never, sec, secs, seconds, min, mins, minute, minutes, hr, hrs, hour, hours, day, days, week, weeks, month, months, year, years. Ioto has sensible defaults for these timeouts if not explicitly specified.

Example

timeouts: {
    api: "30 secs",
    aws: "60 secs",
    checkin: "30 secs",
    download: "5 mins",
}

timeouts.api

Name	timeouts.api
Description	Defines the maximum duration of requests to the Ioto cloud.
Synopsis	api: "duration"
Notes	The api timeout will be used for general calls via the Ioto cloud. The default is 30 seconds.

Example

api: "30 secs"

timeouts.aws

Name	timeouts.aws
Description	Defines the maximum duration of requests to the AWS cloud.
Synopsis	aws: "duration"
Notes	The aws timeout will be used for all calls via the aws() API. The default is 60 seconds.

Example

aws: "60 secs"

timeouts.checkin

Name	timeouts.checkin
Description	Defines the frequency of the checkin API call to the Ioto cloud.
Synopsis	checkin: "elapsed"
Notes	The checkin API will be called when Ioto starts and thereafter at this frequency. Defaults to 24 hours.

Example

checkin: "24 hours"

timeouts.download

Name	timeouts.download
Description	Defines the maximum duration of a software download from the Ioto cloud.
Synopsis	download: "duration"
Notes	The software download is used to deploy new firmware to devices. The default duration is 5 minutes.

Example

download: "5 mins"

tls

Name	tls
Description	Collection of TLS properties.
Synopsis	tls: { "Tls-Property": "Tls-Value", ... }
Notes	TLS properties apply to web server https connections. They do not apply to Ioto MQTT or Ioto client connections. The authority, certificate and key paths may use @certs prefixes to refer to the "state/certs" director.

Example

tls: {
    authority: "@certs/ca.crt",
    certificate: "@certs/server.crt",
    key: "@certs/server.key",
    verify: {
        client: true,
        issuer: true
    }
}

tls.authority

Name	tls.authority
Description	Defines the location of the certificate file for client authentication.
Synopsis	authority: "path"
Notes	The authority property defines the file containing the certificates to use when authenticating client certificates. This property is only necessary if you wish to verify client certificates. If so, you must also define the "verify.client" to be true. The certificate file contains the concatenated certificates to use in preference order. The path may be an absolute path or it may be relative to the Home directory. The path can also use the "@certs" prefix which will be expanded to "state/certs".

Example

authority: "/var/ioto/ca.crt"

tls.certificate

Name	tls.certificate
Description	Defines the location of the X.509 file containing the server certificate
Synopsis	certificate: "path"
Notes	The SSLCertificateFile directive defines the file containing the PEM encoded X.509 certificate for the server. The file may also contain the private key for the server in which case you do not need to use the key property.

Example

certificate: "@certs/server.crt"

tls.key

Name	tls.key
Description	Defines the location of the server's private key.
Synopsis	key: "path/to/key"
Notes	The key property defines the file containing the PEM encoded private key file for the server. This property is not required if the server's private key is combined with the certificate file. The private key should not be encrypted.
Security	There is a dilemma here. If you use an encrypted private key, the server will pause until you enter the pass-phrase which makes headless operation impossible. If you do not encrypt the private key, your private key is more vulnerable should the server be compromised.

Example

key: "@certs/server.key.pem"

tls.verify

Name	tls.verify
Description	Collection of TLS verification properties
Synopsis	verify: { "client": "value", "issuer": "value" }
Notes	Control the type of certificate verification.

Example

verify: {
    client: true,
    issuer: true,
}

tls.verify.client

Name	tls.verify.client
Description	Control the type of client certificate verification.
Synopsis	`client: true
Notes	This property controls whether the client must provide a client certificate for the server to verify the identity of the client. If disabled, no certificate is required. If one is supplied, it will be ignored. The certificate and the certificate's issuer will be verified. Use the "verify.issuer" directive to turn off verification of the issuer if you need to use a self-signed test certificate. If the property is enabled, the client must provide a valid certificate. The default is disabled.

Example

verify: {
    client: true,
}

tls.verify.issuer

Name	tls.verify.issuer
Description	Defines whether the issuer of the client certificate is verified.
Synopsis	`issuer: true
Notes	This property controls whether the issuer of the client certificate will be verified. If set to off, the certificate issuer will not be verified. This is useful to accept self-signed test certificates.

Example

verify: {
    issuer: true,
}

update

Name	update
Description	Collection of software update properties.
Synopsis	update: { "Update-Property": "Update-Value", ... }
Notes	The update collection controls the schedule and behavior of requesting, downloading and applying software updates.

Example

update: {
    apply: '* 0 * * *',
    jitter: '1 hr',
    period: '24 hr',
    schedule: '* 18-23 * * *',
    throttle: 100,
}

update.apply

Name	update.apply
Description	Cron-like schedule defining when the Ioto agent will apply a downloaded software updates.
Synopsis	schedule: "cron-spec string"
Notes	See Cron for details about Cron strings.

Examples

update: {
    apply: 'midnight',
}

update.jitter

Name	update.jitter
Description	Random time period to delay the scheduled software update check so that multiple devices will not all hit the service at once.

| Synopsis | jitter: "1 hr" |

Examples

update: {
    jitter: '2 hrs',
}

update.period

Name	update.period
Description	The minimum delay in seconds before checking for a software update.
Synopsis	period: "number or string numeric with suffix"
Notes	The minimum period will be applied in addition to the defined schedule. The supported suffixes are "min", "hr", "day".

Examples

update: {
    period: '6 hr',
}

update.schedule

Name	update.schedule
Description	Cron-like schedule defining when the Ioto agent will check for new sofwtare updates.
Synopsis	schedule: "cron-spec string"
Notes	See Cron for details about Cron strings.

Examples

update: {
    schedule: '* 18-23 * * *',
or
    schedule: 'midnight',
}

update.throttle

Name	update.throttle
Description	The time in milliseconds to pause between reading 4K of a software download update.
Synopsis	throttle: 50
Notes	This delay is useful to lessen the CPU and network impact on the device due to downloading a software update. Set to zero for no delay.

Examples

update: {
    throttle: 100,
}

version

Name	version
Description	Set the agent version.
Synopsis	version: "SemVer Version String"
Notes	The version string defines the versions of the embedded agent including your software. It is used when selecting software updates deployed from the Builder. Don't confuse this with the underlying Ioto version. The version string must conform to the Semantic Versioning 2.0 spec.