Running Ioto

After building Ioto, the Ioto binaries and libraries will be in the build/bin directory. Each app binary is named ioto-APP where APP is the app name. For example, ioto-http, ioto-ai, etc.

You can run Ioto via make run:

$ make run
app: info: Starting Ioto with "http" app, using "dev" profile
setup: info: Enabling services: db web
web: info: Listening http://:9090
web: info: Listening https://:4443
app: info: Ioto ready

When Ioto runs, it starts enabled services and listens on any required HTTP ports (if you are running the web server service). If your selected services enable the web server, Ioto will listen for connections on the configured ports and serve documents from the ./site directory.

You can also directly invoke the binary from the build directory:

build/bin/ioto-http -v

Ioto Command Line

The Ioto command line is:

ioto-APP [options]

Where APP is the name of the app (e.g., http, ai, blank, blink, unit).

Ioto Command Options

Option	Description
--background	Run Ioto in the background detached from the terminal.
--config dir	Set the directory for config files.
--configFile	Path to the ioto.json5 configuration file.
--debug	Emit very verbose debug tracing.
--exit event or seconds	Exit on event or after 'seconds'.
--home directory	Change to directory to run.
--id Token	Device ID. Overrides device.json5.
--ioto path	Set the path for the ioto.json5 config.
--nolocal	Do not apply local.json5.
--nosave	Run in-memory and do not save state.
--profile profile	Select execution profile from ioto.json5
--quiet	Don't show web server headers. Alias for --show ''.
--reset	Reset state to factory defaults.
--show [HBhb]	Show request headers/body (HB) and response headers/body (hb).
--state dir	Directory for the state files.
--test Suite	Run test suite from config/test.json5.
--timeouts	Disable timeouts for debugging.
--trace file[:types:from]	Trace to file.
--verbose	Verbose operation. Alias for --show Hhb plus module trace.
--version	Output version information

When Ioto starts, it reads the ioto.json5 and other configuration files from the app's state/config directory. These are prepared at build-time by the app's bin/prepare script which copies and blends configuration files from the apps/NAME/ directory. The ioto.json5 file defines the default logging and tracing configuration. This can be overridden by command line options and environment variables. See below for details.

In the examples below, replace ioto-APP with your actual binary name (e.g., ioto-http).

See Configuration Files for details.

Logging and Tracing

Ioto provides detailed log tracing for all operational aspects of Ioto.

The Ioto tracing is configured via the log property collection in the ioto.json5 file.

The log property specifies the trace destination via the path property. This property can be set to stdout, stderr, or any filename.

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

The format property specifies how the log messages will be formatted. It contains a printf style string with 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 trace message, 'P' for the process ID , 'S' for the message source, and 'T' for the trace message type.

Message Types

Ioto classifies trace messages according to types. The supported types are: debug, error, fatal, info, and trace. The types property specifies a comma separate list of trace message types to emit.

Message Sources

Log messages are emitted from "sources". These are the names of the code module that originate the trace messages. The sources property is a comma separated list of sources. Some of the Ioto trace message sources are: "runtime", "tls", "json", "url" and "web".

You can use "all" for types and sources to match all types/sources. You can also use "!type" and "!source" to negate a type or source.

For example:

types: 'all,!debug,!trace'

This will emit messages of all types, except for debug and trace messages.

Command Line

The logging configuration defined in the ioto.json5 file can be overridden via via the --trace, --verbose and --debug Ioto command line options. It can also be overridden via the LOG_FILTER environment variable.

The --trace option specifies the trace file destination and a list of types and sources.

$ ioto-APP --trace FILENAME[:TYPES[:SOURCES]]

The types are a comma separated list of message types. Valid types include: info, debug, error, trace and all. Sources are the code module names originating the trace messages. You can use "!type" and "!source" to negate a type or source.

For example:

$ ioto-APP --trace trace.log  # Same as path:trace.log
$ ioto-APP --verbose          # Same as path:stdout, types:raw,error,info, sources:all
$ ioto-APP --debug            # Same as path:stdout, types:raw,error,info,trace,!debug, sources:all
$ ioto-APP --trace file:all:all
$ ioto-APP --trace file:all,!debug,!trace:all

You can also use the -v short cut for --verbose and -d for --debug.

Trace Environment Overrides

Similar to the command line options, you can override the trace configuration via two environment variables.

Command Line Options	Environment Variable	Description
--trace	LOG_FILTER	Override the log filter definition
--verbose		Override the log filter definition
--debug		Override the log filter definition

These variables take the same string values as their command line option counterparts.

The order of precedence of configuration is:

1. Command line --trace, --debug or --verbose options
2. Environment variable LOG_FILTER, LOG_FORMAT values
3. ioto.json5 configuration

Web Server Tracing

Ioto provides special control for the web server HTTP request and response tracing. You can selectively trace HTTP request and response headers and bodies via the show property.

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

The show property is a string with the following characters:

Character	Description
b	Show the response body
h	Show the response HTTP headers
B	Show the client request HTTP body
H	Show the client request HTTP headers
empty	Show no HTTP trace

You can override the ioto.json5 show property configuration via the --show Ioto command line option.

For example:

$ ioto-APP --show hH

You can also override the configuration via the WEB_SHOW environment variable.

Command Line Options	Environment Variable	Description
--show	WEB_SHOW	Override the show definition

The order of precedence of configuration is:

1. Command line --show option value
2. Environment variable LOG_FILTER, LOG_FORMAT values
3. ioto.json5 configuration

HTTP Client Tracing

Similar to the web server HTTP tracing, you can trace client HTTP requests and responses. Tracing HTTP client requests can be enabled via the URL_SHOW environment variable.

For example:

$ URL_SHOW=hH ioto-APP --trace trace.log

This will trace any client HTTP requests issued via the URL module. This includes internal Ioto client requests and your own client HTTP requests that use the URL API.

Other Environment Variables

You can override the Ioto mode and profile settings via environment variables:

Command Line Option	Environment Variable	Description
--profile PROFILE	IOTO_PROFILE	Override the execution profile (dev | prod)

Test Suites

Ioto provides a test facility via the Unit testing app. The apps/unit/test.json5 configuration file defines the available test suites. You can create your own tests in the unitTest.c source file and define them in the test.json5 config file.

The default Ioto source distribution includes a demo property collection to run a simple demo test that will increment a counter and post to the device database.

demo: {
    count: 30,
    delay: '30sec',
    enable: true,
},

The count property defines how many test iterations will be performed. The delay property indicates the delay between each test.

Ioto Manual Pages

This Ioto distribution provides manual pages that can be viewed (on Unix-like systems) using the systems man command. Text copies of the pages are included below:

Topic	Description
ioto	Ioto device agent
db	Database client program
json	JSON tool
password	Password manager
url	URL HTTP client test program