azure-iot-edge-runtime-ctl 1.0.0rc24

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.

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