azure-iot-edge-runtime-ctl 1.0.0rc24

Azure IoT Edge Runtime Control

Deprecation Notice

The azure-iot-edge-runtime-ctl (iotedgectl) tool has now been deprecated! The Azure IoT Edge runtime (Edge Agent and Edge Hub) will continue to work when launched using this utility. However since the official release of the Edge security daemon, using this utility to launch the IoT Edge runtime is discouraged. To learn more about the officially supported Azure IoT Edge please visit the IoT Edge documentation.

Introduction

The Azure IoT Edge Runtime Control utility assists a user in managing and controlling the IoT Edge runtime.

Specifically, it can help: * Initial setup or bootstrap * Certificate provisioning * Starting/Stopping and other IoT Edge runtime control options.

Prerequisites

• Python 2.7+

• Python setuptools (for pip installation)

• Docker

Installation

Python

Installation requires python and setuptools. Download python here.

On Windows, make sure the python.exe and python Scripts directory are on your path. More information for installing python on Windows can be found here.

Note: See the Installation Troubleshooting section below if you run into any problems.

Python

• Installation requires python and setuptools. Download python here.

• On Windows, make sure the python.exe and python Scripts directory are on your path. More information for installing python on Windows can be found here.

• Note: See the Installation Troubleshooting section below if you run into any problems.

Docker

• Follow the instructions here to get Docker installed on your host machine https://docs.microsoft.com/en-us/azure/iot-edge

Enabling Docker on Windows Subsystem for Linux (WSL)

Note: This section applies to Windows machines only and usually targets developer environments.

• To get iotedgectl to work in WSL here are additional installation steps that need to be done.

1. Do not install Docker in WSL, instead first install Docker on your Windows machine.

• Docker installed on the Windows machine can be used directly within the bash shell.

2. In Docker Settings Window under ‘General’, check “Expose Daemon on tcp://localhost:2375 without TLS”

3. Next steps require to the run from a bash shell

1. Add the docker executable files to the $PATH environment variable and set up aliases.

• Edit file ~/.bashrc and add these lines:

PATH="$HOME/bin:$HOME/.local/bin:$PATH"
PATH="$PATH:/mnt/c/Program\ Files/Docker/Docker/resources/bin"
alias docker=docker.exe
alias docker-machine=docker-machine.exe
alias docker-compose=docker-compose.exe
export DOCKER_HOST="tcp://localhost:2375"

• Save and close the ~/.bashrc file

2. Add environment variable DOCKER_HOST to sudoers.

• Edit sudoers configuration by running

sudo visudo

• Add this line to the file

Defaults env_keep += "DOCKER_HOST"

• Save and close the file

3. Ensure the environment variables get exported

source ~/.bashrc

4. Test installation by running any docker command. Examples:

docker ps
docker images

Install the tool

In a terminal, complete the following steps run pip install azure-iot-edge-runtime-ctl (may need to run as administrator)

This should install the iotedgectl tool on your path.

See Installation Troubleshooting for common installation problems.

How To Run:

The main commands to operate the IoT Edge runtime are: setup, start, restart, stop, status, update, login and uninstall.

• setup: This command accepts user input to configure the runtime. The required configuration files and certificates to operate the IoT Edge are created as part of this step.

  IoT Edge can be setup either by using an input configuration file and command line (CLI) argument –config-file or by specifying the various configuration values via the setup CLI arguments. If using the –config-file argument, all other CLI arguments will be ignored.

  The ‘setup’ command, may need to be run with admin (sudo) privileges. One resulting output of this command is a configuration file generated in JSON format. The directory where this file is generated is configurable and if unspecified, default paths (see below) will be used.

  There are 3 ways the Edge config directory is set, here they are in the order of precedence:

  1. Environment variable EDGECONFIGDIR - When using this, an absolute path to a directory on the host must be specified as the value of this variable.

  2. iotedgectl CLI options to specify a directory path.

  • –config-file: Configure the input JSON config file with the directory path as described in this document below.

  • –edge-config-dir: When using this option, an absolute path to a directory on the host must be specified.

  Note: If environment variable EDGECONFIGDIR and a CLI option is specified, the environment variable will take precedence and the CLI option will be ignored.

  3. If none of the above are set, the following default paths will be chosen:

  Default IoT Edge Configuration Host Paths:
  ------------------------------------------
      Linux:   /etc/azure-iot-edge
      Windows: %PROGRAMDATA%\azure-iot-edge\config
      MacOS:   /etc/azure-iot-edge

• start: This command starts the IoT Edge runtime. This command downloads the Edge Agent image unless already available on the host machine. Configuration information specified during the setup step above is supplied to the Edge Agent when it is instantiated.

• stop: This command stops the IoT Edge runtime. Note: The Edge modules are stopped and not removed.

• restart: This command restarts the IoT Edge runtime and behaves like start if the Edge runtime does not exist on the host. If a runtime is active, it will be stopped along with any modules deployed by the Edge runtime. Subsequently, the Edge runtime and all other modules will be restarted again.

• status: Prints the current state of the IoT Edge runtime.

• uninstall: This command stops and uninstalls the IoT Edge runtime. Running uninstall will delete the configuration file, certificates. Additionally, the IoT Edge runtime and all modules will be removed.

• update: This command accepts an Edge Agent image as input and configures the IoT Edge with this new image. Running this command will update the IoT Edge configuration file with this new image and the existing Edge Agent will be stopped, its older image removed and restarted with the new image.

• login: This command accepts a registry server, username and credentials as input and configures the IoT Edge with this data. Running login will update the IoT Edge configuration file with the registry information. This is useful for users who host their module images on private registries. Note: in the event the Edge runtime is active and running, the Edge Agent will be stopped and the existing instance will be removed and restarted with the new credentials.

Here are a few sample command invocations:

• Print Help and Exit

$> iotedgectl --help

• Setup the IoT Edge Runtime using an IoT Edge Host Configuration file. Please see IoT Edge Host Configuration File Description

$> iotedgectl setup --help
$> iotedgectl setup --config-file edge_config.json
$> iotedgectl --verbose DEBUG setup --config-file edge_config.json
Note: When specifying the homeDir path on Windows please use "C:\\example\\edge-home"

• Setup the IoT Edge Runtime using manually specified command line arguments

$> iotedgectl setup --connection-string "HostName=<>;DeviceId=<>;SharedAccessKey=<>"
Note: When specifying the connection string ensure that it is surrounded by double quotes ".
In general, anything with a semicolon should be put into quotes.

• Start the IoT Edge Runtime

$> iotedgectl start
$> iotedgectl --verbose INFO start

• Restart the IoT Edge Runtime

$> iotedgectl restart
$> iotedgectl --verbose INFO restart

• Stop the IoT Edge Runtime

$> iotedgectl stop
$> iotedgectl --verbose INFO stop

• Uninstall the IoT Edge Runtime

$> iotedgectl uninstall
$> iotedgectl --verbose DEBUG uninstall

• Print the current status of the IoT Edge Runtime

$> iotedgectl status
$> iotedgectl --verbose INFO status

IoT Edge Home Directory Description

The IoT Edge runtime needs a directory on the host machine in order to execute. This directory will contain the necessary configuration files, certificates and module specific files. This is called the EDGEHOMEDIR. To configure the directory path of the EDGEHOMEDIR, the CLI option ‘iotedgectl setup –edge-home-dir <path>’ can be used. In case it is unspecified, the default directories listed below will be used as the EDGEHOMEDIR:

Default Host Paths:
-------------------
    Linux:   /var/lib/azure-iot-edge
    Windows: %PROGRAMDATA%\azure-iot-edge\data
    MacOS:   /var/lib/azure-iot-edge

When using the –config-file option, an absolute directory path is required to setup the Edge runtime (see below).

Note: If the directory does not exist, it will be created.

As the IoT Edge runtime is executed, the following file system structure is created under EDGEHOMEDIR.

EDGEHOMEDIR Structure:
-----------------------
    EDGEHOMEDIR
        .
        +-- certs   -- This directory is created by the iotedgectl utility when generating
        |              either self signed certificates or Device CA based certificates.
        +-- modules -- This directory is created by the iotedgectl utility to host
                       all the Edge Module specific files.

IoT Edge Host Configuration File Description

The following section describes the various configuration items required to setup the IoT Edge. * When using the command line options to setup the IoT Edge, this file is auto generated. * When using the –config-file to setup the IoT Edge device, a configuration file with appropriate input data would have to provided.

// Config file format schema; Users should not need to modify this.
"schemaVersion": "1",

// IoTHub Device Connection string in the format listed below.
// A connection string is required when using the --config-file option
// to setup the Edge runtime.
"deviceConnectionString": "HostName=<>;DeviceId=<>;SharedAccessKey=<>",

// Absolute path to the IoT Edge home dir.
// An absolute directory path is required when using the --config-file option
// to setup the Edge runtime.
// If the specified directory does not exist, it will be created.
// For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
"homeDir": "<EDGEHOMEDIR>",

// Absolute path to the IoT Edge configuration dir. This is an optional
// configuration item. Please review the setup command section above to see
// how this field is used by this utility.
// An absolute directory path is required when using the --config-file option
// to setup the Edge runtime.
// If the specified directory does not exist, it will be created.
// For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
"configDir": "<EDGECONFIGDIR>",

// IoT Edge device's DNS name;
// Specifying a FQDN is only required when operating the
// IoT Edge as a 'Gateway' for leaf device connectivity.
// If a FQDN is unavailable, the host name (or machine name) could be used.
// This typically occurs when the host is not domain registered such as
// a device on a home Wifi network. This should work just fine for Edge module
// to Edge Hub communication but may not work for leaf device connectivity.
// This hostname value is needed specifically to name the Edge Hub server
// and is also used to generate the Edge Hub server certificate.
// This server certificate is used to enable TLS connections from IoT Edge
// modules and leaf devices.
// The DNS host name is required when using the --config-file option
// to setup the Edge runtime.
"hostName": "<Hostname>",

// Log level setting for IoT Edge runtime diagnostics. "info" and "debug".
// are the supported levels and default is info. This should only
// modified for debugging purposes.
// A log level is required when using the --config-file option
// to setup the Edge runtime.
"logLevel": "info",

// Upstream protocol to be used by the Edge runtime (and possibly other module)
// when connecting to IoTHub. The permitted values are Amqp and AmqpWs.
// This is an optional setting.
"upstreamProtocol": "Amqp",

// Configuration settings for the IoT Edge Runtime
"security": {

  // Configuration of X.509 certificates; There are two options:
  //  - Self Signed Certificates:   This mode is NOT secure and is only
  //    (selfSigned)                intended for development purposes
  //                                and quick start type scenarios.
  //
  //  - Pre Installed Certificates: When this is enabled, it is expected
  //    (preInstalled)              that the "Device CA" and "Owner CA"
  //                                certificates and their corresponding
  //                                certificate chain be provided. Additionally,
  //                                the Device CA private key and its
  //                                optional passphrase should be provided.
  //                                This is more of a real world setup
  //                                where the IoT Edge is configured to run
  //                                as a gateway.
  //
  // The "option" key below selects any of the modes listed above.
  // An option is required when using the --config-file option
  // to setup the Edge runtime.
  "certificates": {
    "option": "selfSigned",
    "selfSigned": {
      // If the boolean value of forceNoPasswords is true,
      // it is not required to supply valid paths
      // to the Edge Device or Edge Agent private key
      // passphrase (password) files described below.
      "forceNoPasswords": true

      // Absolute path to the passphrase file for the Edge Device private key.
      // The passphrase must be between 4 - 1023 characters in length and the
      // file should be a regular ascii text file containing the passphrase.
      "deviceCAPassphraseFilePath": "",

      // Absolute path to the passphrase file for the Edge Agent private key.
      // The passphrase must be between 4 - 1023 characters in length and the
      // file should be a regular ascii text file containing the passphrase.
      "agentCAPassphraseFilePath": ""
    },
    "preInstalled": {
      // Absolute path to the Edge Owner CA certificate file in X.509 PEM format.
      // An absolute file path is required when using the --config-file option
      // and 'preInstalled' is the certificate option selected
      // to setup the Edge runtime.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      "ownerCACertificateFilePath": "",

      // Absolute path to the Edge Device CA certificate file in X.509 PEM format
      // An absolute file path is required when using the --config-file option
      // and 'preInstalled' is the certificate option selected
      // to setup the Edge runtime.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      "deviceCACertificateFilePath": "",

      // Absolute path to the Edge Device CA certificate chain file in X.509 PEM format.
      // This is the certificate chain from the Owner CA up to and including the
      // Device CA certificate.
      // An absolute file path is required when using the --config-file option
      // and 'preInstalled' is the certificate option selected
      // to setup the Edge runtime.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      "deviceCAChainCertificateFilePath": "",

      // Absolute path to the Edge Device CA certificate's private key
      // file in X.509 PEM format.
      // An absolute file path is required when using the --config-file option
      // and 'preInstalled' is the certificate option selected
      // to setup the Edge runtime.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      // Note: If a passphrase was used to generate the private key,
      // the passphrase must be provided via the deviceCAPassphraseFilePath
      // option described below.
      "deviceCAPrivateKeyFilePath": "",

      // Absolute path to the passphrase file for the Edge Device private key.
      // The passphrase must be between 4 - 1023 characters in length and the
      // file should be regular ascii text file containing the passphrase.
      // This would need to be provided only if the Edge Device CA private
      // was created with a passphrase.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      "deviceCAPassphraseFilePath": "",

      // If the boolean value of forceNoPasswords is true,
      // it is not required to supply valid paths
      // to the Edge Agent private key password (passphrase) file.
      "forceNoPasswords": true

      // Absolute path to the passphrase file for the Edge Agent private key.
      // The passphrase must be between 4 - 1023 characters in length and the
      // file should be a regular ascii text file containing the passphrase.
      // For Windows paths, use \\ as the path separator. Example: C:\\path\\file.ext
      "agentCAPassphraseFilePath": ""
    },
    // Certificate subject data.
    // These are values that are used when auto generating
    // any certificates required for operating the IoT Edge.
    // These values can be modified as needed
    // and the values for all the fields can be empty strings.
    // These values are not when using the preInstalled certificate
    // option, rather they are determined from the Device CA certificate.
    "subject": {
      "countryCode": "US",
      "state": "Washington",
      "locality": "Redmond",
      "organization": "Default Edge Organization",
      "organizationUnit": "Edge Unit",
      "commonName": "Edge Device CA"
    }
  }
},
// Section containing Configuration of IoT Edge Runtime Deployment and Host.
"deployment": {

  // Currently "docker" is the only deployment type supported.
  // Specifying this value is required when using the --config-file option
  // to setup the Edge runtime.
  "type": "docker",

  // Docker host settings
  "docker": {
    // Docker Daemon socket URI; This is the end point that the Edge Agent
    // will use to communicate with the daemon. Please note this may not be
    // the same docker URI end point that a user might use on their host.
    // This is true when running Linux containers on Windows.
    // A valid URI is required when using the --config-file option
    // to setup the Edge runtime.
    "uri": "unix:///var/run/docker.sock",

    // IoT Edge runtime image; This value may need to be updated as newer
    // images are released over time either by updating the config file and
    // using --config-file or the **update** command.
    // A runtime image is required when using the --config-file option
    // to setup the Edge runtime.
    "edgeRuntimeImage": "edge_repository_address/edge_image_name:version",

    // Docker registries can be added in this array for custom modules.
    // If there is no username or password associated with a registry,
    // there is no need to add any data here.
    // NOTE: This is a temporary configuration item required by the IoT Edge
    // Longer term, it will be possible to manage registries and
    // credentials using the IoTHub portal.
    // Adding a registry to the array can be done either by updating the
    // config file and using --config-file or the **login** command.
    "registries": [
      {
        "address": "example-repository-address-1",
        "username": "example-username-1",
        "password": "example-password-1"
      },
      {
        "address": "example-repository-address-2",
        "username": "example-username-2",
        "password": "example-password-2"
      }
    ],

    // Logging options for the IoT Edge runtime. The format complies with
    // the docker schema described here:
    // https://docs.docker.com/engine/admin/logging/overview/
    // Appropriate log configuration values are required when using the
    // --config-file option to setup the Edge runtime.
    "loggingOptions": {
      "log-driver": "json-file",
      "log-opts": {
        "max-size": "10m"
      }
    }
  }
}

Installation Troubleshooting

Raspbian

On the raspbian platform, you may need to update pip or the setup tools:

sudo pip install --upgrade setuptools pip

The Python installation may require some C libraries to be built, these libraries require development packages not installed by default:

sudo apt-get install python2.7-dev libffi-dev libssl-dev