Command line utilities¶

Igor comes with a number of command line utilities to access and control the database. Most of these use a common configuration file ~/.igor/igor.cfg and a number of environment variables to set defaults for arguments.

igorVar¶

igorVar is the main program used to access the database from the command line and from shell scripts. It allows getting and setting of database variables in various different formats (text, xml, json, python).

Access Igor home automation service and other http databases

usage: igorVar [-h] [--configFile FILE] [--config SECTION] [-u URL]
               [--verbose] [--bearer TOKEN] [--access TOKEN]
               [--credentials USER:PASS] [--noverify] [--certificate CERTFILE]
               [--noSystemRootCertificates] [-e] [-v VARIANT] [-M MIMETYPE]
               [--text] [--json] [--xml] [--python] [--pretty] [--delete]
               [--create] [--put MIMETYPE] [--post MIMETYPE] [--data DATA]
               [--checkdata] [--checknonempty] [-0]
               var

Positional Arguments¶

var

Variable to get (or put, or post). The variable is specified in XPath syntax. Relative names are relative to the toplevel /data element in the database. Absolute names are also allowed (so /data/environment is equivalent to environment).

Access to non-database portions of the REST API is allowed, so getting /action/save will have the side-effect of saving the database.

Full XPath syntax is allowed, so something like actions/action[name='save'] will retrieve the definition of the save action. For some XPath expressions, such as expressions with a toplevel XPath function, it may be necessary to pass the --eval switch.

Named Arguments¶

`--configFile`	Get default arguments from ini-style config FILE (default: ~/.igor/igor.cfg)
`--config`	Get default arguments from config file section [SECTION] (default: igor).
`-u, --url`	Base URL of the server (default: “http://igor.local:9333/data”) Default: “http://igor.local:9333/data”
`--verbose`	Print what is happening
`--bearer`	Add Authorization: Bearer TOKEN header line Default: “”
`--access`	Add access_token=TOKEN query argument Default: “”
`--credentials`	Add Authorization: Basic header line with given credentials Default: “”
`--noverify`	Disable verification of https signatures
`--certificate`	Verify https certificates from given file Default: “”
`--noSystemRootCertificates`
	Do not use system root certificates, use REQUESTS_CA_BUNDLE or what requests package has
`-e, --eval`	Evaluate XPath expression in stead of retrieving variable (by changing /data to /evaluate in URL)
`-v, --variant`	Variant of data to get (or put, post)
`-M, --mimetype`	Get result as given mimetype
`--text`	Get result as plain text
`--json`	Get result as JSON
`--xml`	Get result as XML
`--python`	Get result as Python (converted from JSON)
`--pretty`	Pretty-print result (only for Python, currently)
`--delete`	Delete variable
`--create`	Create or clear a variable
`--put`	PUT data of type MIMETYPE, from –data or stdin
`--post`	POST data of type MIMETYPE, from –data or stdin
`--data`	POST or PUT DATA, in stead of reading from stdin
`--checkdata`	Check that data is valid XML or JSON
`--checknonempty`
	Check that data is valid XML or JSON data, and fail silently on empty data
`-0, --allow-empty`
	Allow empty data from stdin

Argument defaults can also be specified in environment variables like IGORSERVER_URL (for –url), etc.

Some examples may help understanding how igorVar can be used to access and modify your database. The following command will create a variable (in the sandbox section of the database, which is specifically there for experimenting), assuming it does not exist yet. It will print the full XPath of the variable created.

igorVar --put text/plain --data "Hello world" sandbox/helloworld

Running that command multiple times will overwrite the variable. Running the following command is completely equivalent:

echo "Hello World" | igorVar --put text/plain sandbox/helloworld

You can get the plaintext value of variable with either of the following commands (which are completely equivalent):

igorVar --mimetype text/plain sandbox/helloworld
igorVar --mimetype text/plain /data/sandbox/helloworld

The default mimetype, however, is application/xml because igorVar is primarily meant for use in scripts, not interactively by a human.

To delete a variable, if it exists, use

igorVar --delete sandbox/helloworld

Post is similar to put, but always create a new entry. So if you have no helloworld variable yet the following command line is equivalent to the first example. But if you run it three times you will have three variables, named sandbox/helloworld[1], sandbox/helloworld[2] and sandbox/helloworld[3]:

igorVar --post text/plain --data "Hello world one" sandbox/helloworld
igorVar --post text/plain --data "Hello world two" sandbox/helloworld
igorVar --post text/plain --data "Hello world three" sandbox/helloworld

To retrieve one of these you must supply the index. Or use --variant multi but that only works when you want the value in JSON or XML:

igorVar --mimetype text/plain 'sandbox/helloworld[2]'
igorVar --mimetype application/json --variant multi sandbox/helloworld

Note that this [2] construct is an XPath expression. Read up on XPath, it is a very powerful but simple language to select variables in your database. Also note that many XPath operators are also magical to the shell, so put your variable name in single or double quotes when in doubt.

igorCA¶

igorCA is the command line interface to using Igor as a Certificate Authority. Under the hood it is implemented using the openssl command line tool. It is intended to serve as CA for the .local domain, to enable secure communication between local devices and Igor (and other local devices).

When used as a command line tool igorCA can also comunicate to another igorCA operating as a plugin in another Igor, thereby making it possible to run the CA only on a single machine in the local network, even if multiple Igor instances are used. This mode of operation is enabled by using the –remote argument to igorCA.

Igor Certificate and Key utility

usage: igorCA [-h] [--configFile FILE] [--config SECTION] [-u URL] [--verbose]
              [--bearer TOKEN] [--access TOKEN] [--credentials USER:PASS]
              [--noverify] [--certificate CERTFILE]
              [--noSystemRootCertificates] [-s BITS] [-r] [-d DIR]
              action [arguments [arguments ...]]

Positional Arguments¶

action

Action to perform: help, initialize, …

Default: “help”

arguments

Arguments to the action

Named Arguments¶

`--configFile`	Get default arguments from ini-style config FILE (default: ~/.igor/igor.cfg)
`--config`	Get default arguments from config file section [SECTION] (default: igor).
`-u, --url`	Base URL of the server (default: “http://igor.local:9333/data”) Default: “http://igor.local:9333/data”
`--verbose`	Print what is happening
`--bearer`	Add Authorization: Bearer TOKEN header line Default: “”
`--access`	Add access_token=TOKEN query argument Default: “”
`--credentials`	Add Authorization: Basic header line with given credentials Default: “”
`--noverify`	Disable verification of https signatures
`--certificate`	Verify https certificates from given file Default: “”
`--noSystemRootCertificates`
	Do not use system root certificates, use REQUESTS_CA_BUNDLE or what requests package has
`-s, --keysize`	Override key size (default: 2048)
`-r, --remote`	Use CA on remote Igor (default is on the local filesystem)
`-d, --database`	(local only) Database and scripts are stored in DIR (default: ~/.igor, environment IGORSERVER_DIR)

Available commands: csrtemplate Return template config file for for openSSL CSR request current Print current certificate serial for given Common Name dn Return CA distinghuished name as a JSON structure gen Generate a a server key and certificate for a named service and sign it with the intermediate Igor CA key. genCRL Generate CRL in static/crl.pem getCRL Output the CRL (Certificate Revocation List) getRoot Returns the signing certificate chain (for installation in browser or operating system) help Show list of available commands initialize create CA infrastructure, root key and certificate and intermediate key and certificate list Return list of certificates signed (optional arguments restricts to single Common Name). revoke Revoke a certificate. Argument is the number of the certificate to revoke (see list). revokecn Revoke certificate for a given Common Name, if one exists self Create a server key and certificate for Igor itself, and sign it with the intermediate Igor CA key selfCSR Create secret key and CSR for Igor itself. Outputs CSR. sign Sign a Certificate Signing Request and return the certificate. status Returns nothing if CA status is ok, otherwise error message

igorCA actions¶

initialize root-issuer intermediate-issuer

Create CA infrastructure, root key and certificate and intermediate key and certificate.

The root-issuer argument is the name of this Certificate Authority, according to the X.509 standard. See <https://tools.ietf.org/rfc/rfc5280.txt> section 4.1.2.4 for exact details of the fields allowed, but some fields are required: C for country name, ST for state and O for organization. Adding CN for common name is probably a good idea, this will allow people on the local network to recognize the certificate issuer.

The fields are introduced by slashes, so the following is an example of what you could use as root-issuer after replacing the various fields with the correct values for your situation:

'/CN=root.ca.igor.local/C=NL/ST=Netherlands/O=Jack Jansen'

The intermediate-issuer is the same, but for the intermediate certificate. CN=intermediate.ca.igor.local is suggested.

getRoot

Returns the signing certificate chain (for installation in browser or operating system).

status

Returns nothing if CA status is ok, otherwise error message

csrtemplate

Return template config file for openSSL CSR (Certificate Signing Request)

dn

Return CA distinghuished name as a JSON structure

gen prefix name-or-ip […]

Generate a a server key and certificate for a named service and sign it with the intermediate Igor CA key. The prefix is used to generate the filenames where the results of this action are stored:

prefix.key will contain the secret key for the service
prefix.crt will contain the certificate for the service
prefix.csr is a temporary file containing the CSR
prefix.csrConfig is a temporary containing the openSSL configuration used to create the CSR

sign csrfile certfile

Read a Certificate Signing Request from csrfile and sign it with the CA keys. Save the resulting certificate to certfile.

selfCSR name-or-ip […]

Create secret key and CSR (Certificate Signing Request) for Igor itself. Pass all DNS names (or IP addresses) for this Igor host as arguments. Outputs CSR.

self name-or-ip […]

Create a secret key and certificate for Igor itself, and sign it with the intermediate Igor CA key.

revoke number

Revoke a certificate. Argument is the number of the certificate to revoke (can be obtained through the list action or by inspecting the certificate). Regenerates CRL as well.

genCRL

Generate CRL (Certificate Revokation List) in static/crl.pem so it can be retrieved by other Igors.

getCRL

Output the CRL (Certificate Revocation List), for example for use in browsers or in the operating system certificate support.

list

Return list of certificates signed and certificates signed and subsequently revoked.

igorControl¶

igorControl allows some control over a running Igor, through the REST interface. All functions it allows can also be accessed through igorVar but igorControl provides a more convenient interface.

Control Igor home automation service

usage: igorControl [-h] [--configFile FILE] [--config SECTION] [-u URL]
                   [--verbose] [--bearer TOKEN] [--access TOKEN]
                   [--credentials USER:PASS] [--noverify]
                   [--certificate CERTFILE] [--noSystemRootCertificates]
                   action [NAME=VALUE [NAME=VALUE ...]]

Positional Arguments¶

`action`	Action to perform: help, save, stop, restart, command, …
`NAME=VALUE`	Arguments to the action

Named Arguments¶

`--configFile`	Get default arguments from ini-style config FILE (default: ~/.igor/igor.cfg)
`--config`	Get default arguments from config file section [SECTION] (default: igor).
`-u, --url`	Base URL of the server (default: “http://igor.local:9333/data”) Default: “http://igor.local:9333/data”
`--verbose`	Print what is happening
`--bearer`	Add Authorization: Bearer TOKEN header line Default: “”
`--access`	Add access_token=TOKEN query argument Default: “”
`--credentials`	Add Authorization: Basic header line with given credentials Default: “”
`--noverify`	Disable verification of https signatures
`--certificate`	Verify https certificates from given file Default: “”
`--noSystemRootCertificates`
	Do not use system root certificates, use REQUESTS_CA_BUNDLE or what requests package has

Argument defaults can also be specified in environment variables like IGORSERVER_URL (for –url), etc.

igorControl actions¶

version: Show Igor version.
save: Saves the database to the filesystem.
stop: Gracefully stop Igor.
restart: Attempt to gracefully stop and restart Igor.
log: Show current igor log file.
dump: Show internal run queues, action handlers and events.
fail: Raises a Python exception (intended for testing only).
flush: Wait until all currently queued urlCaller events have been completed (intended for testing only).

igorSetup¶

igorSetup is the utility to initialize an Igor installation on the current machine and control it from the command line. Unlike the other command line utilities this utility uses normal Unix/Linux filesystem access and process control, and it can therefore only be used on the machine that also runs Igor (and by a user that has the right Unix permissions).

usage: 
Usage: igorSetup [options] command [command-args]

Initialize or modify igor database.
Note: use only on host where igorServer is hosted, and not when it is running.

Positional Arguments¶

action

Action to perform: help, initialize, …

Default: “help”

arguments

Arguments to the action

Named Arguments¶

`-d, --database`	Database and scripts are stored in DIR (default: ~/.igor, environment IGORSERVER_DIR)
`-r, --run`	Run any needed shell commands (default is to print them only)

igorSetup actions¶

initialize: create empty igor database.
runatboot: make igorServer run at system boot (Linux or OSX, requires sudo permission).
runatlogin: make igorServer run at user login (OSX only).
start: start service (using normal OSX or Linux commands).
stop: stop service (using normal OSX or Linux commands).
add pathname […]: add plugin (copy) from given pathname. Only use this command while Igor is not running. Note that it is potentially dangerous to install an Igor plugin, especially if it comes from an unknown source: an Igor plugin currently has complete access to the Igor internals, and can therefore access any data or modify it, and probably also read or write files on your Igor host.
addstd name*[=*srcname] […]: add standard plugin srcname (linked) with given name. Only use this command while Igor is not running. Using the plugin.html Igor interface is easier.
remove name […]: remove plugin name. Using the plugin.html Igor interface is easier.
list: show all installed plugins. Using the plugin.html Igor interface is easier.
liststd: list all available standard plugins. Using the plugin.html Igor interface is easier.
certificate hostname […]: create https certificate for Igor using Igor as CA (using the igorCA module). Only use this command while Igor is not running.
certificateSelfSigned subject hostname […]: create self-signed https certificate for Igor (deprecated, use certificate command in stead). Only use this command while Igor is not running.
edit: stop, edit the database (using the $EDITOR program) and restart the service.
rebuild: stop, rebuild and restart the service (must be run in source directory).
rebuildedit: stop, edit database, rebuild and start the service (must be run in source directory).

Configuration file¶

igorVar, igorCA and igorControl all read default values for named arguments from a configuration file ~/.igor/igor.cfg, section [igor] (but these are overridable through the --configFile and --config arguments).

The following igor.cfg file causes igorVar to access an Igor on machine downstairs.local and igorVar --config upstairs to access an Igor an machine upstairs.local with HTTPS certification turned off:

[igor]
url = https://downstairs.local:9333/data/
[upstairs]
url = https://upstairs.local:9333/data/
noverify = 1

Environment variables¶

igorVar, igorCA and igorControl can also get their default values for named arguments from environment variables. These environment variables start with IGORSERVER_ followed by the upper-cased argument name. As an example, IGORSERVER_URL can be used to provide a default for the --url argument.

Values passed on the command line have the highest priority, then values in environment variables, then values read from the configuration file.

Igor

Navigation

Related Topics

Command line utilities¶

igorVar¶

Positional Arguments¶

Named Arguments¶

igorCA¶

Positional Arguments¶

Named Arguments¶

igorCA actions¶

igorControl¶

Positional Arguments¶

Named Arguments¶

igorControl actions¶

igorSetup¶

Positional Arguments¶

Named Arguments¶

igorSetup actions¶

Configuration file¶

Environment variables¶