Running Ioto
After building Ioto, the Ioto and other binaries and libraries will be in the binaries directory at:
1 |
|
You may want to add this directory to your shell PATH.
1 |
|
Or you can easily run Ioto via:
When Ioto runs, it listens on the required HTTP ports and registers with the cloud. By default, Ioto renders a few test pages on the embedded web server.
To manage your device from the cloud, read Managing from the Cloud.
Ioto Command Line
On Linux or Mac OS X, Ioto is installed by default in the directory /usr/local/lib/ioto. The Ioto binary program is installed at /usr/local/bin/ioto, and the Ioto configuration is at /etc/ioto.
The Ioto command line is:
Ioto Command Options
Option | Description |
---|---|
--account ID | Manager account for self-claiming. |
--background | Run Ioto in the background detached from the terminal. |
--cloud Token | Cloud claim token for self-claiming. |
--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 claim ID. Overrides device.json5. |
--ioto path | Set the path for the ioto.json5 config. |
--mode mode | Select execution mode from ioto.json5 (dev,prod). |
--nolocal | Do not apply local.json5. |
--nosave | Run in-memory and do not save state. |
--product Token | Product claim ID. Overrides device.json5. |
--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 |
Configuration
When Ioto starts, it reads the config/ioto.json5 and other configuration files from the Ioto config directory. These are copied at build-time from the apps/NAME/config directory. See Configuration Files for details.
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.
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 /etc/ioto/config/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 or cloud to send log files to AWS cloudwatch.
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:
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.
1 |
|
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:
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 varables.
Command Line Options | Environment Variable | Description |
---|---|---|
--trace, --verbose, --debug | LOG_FILTER | Override the log filter definition |
none | LOG_FORMAT | Override the log message format definition |
These variables take the same string values as their command line option counterparts.
The order of precedence of configuration is:
- Command line --trace, --debug or --verbose options
- Environment variable LOG_FILTER, LOG_FORMAT values
- 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.
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:
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:
- Command line --show option value
- Environment variable LOG_FILTER, LOG_FORMAT values
- 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:
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 Varialbes
You can override the Ioto mode and profile settings via environment variables:
Command Line Option | Environment Variable | Description |
---|---|---|
--mode MODE | IOTO_MODE | Override the execution mode (cloud | local) |
--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.
The count property defines how many test iterations will be performed. The delay property indicates the delay between each test. The type property selects the type of 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 |
pass | Password manager |
url | URL HTTP client test program |