azure-iot-edge-runtime-ctl 1.0.0rc14

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.

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. Lets call this the EDGEHOMEDIR. If users do not specify a value for the EDGEHOMEDIR, these default directories will be used to setup/start/stop the IoT Edge runtime.

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

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 users use the –config-file to setup their IoT Edge device, they would have to provide this configuration file with appropriate input data.

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

// User's IoTHub Device Connection string in the format listed below.
"deviceConnectionString": "HostName=<>;DeviceId=<>;SharedAccessKey=<>",

// Path to the IoT Edge home dir, if left empty, a default home dir will be used
"homeDir": "<EDGEHOMEDIR>",

// 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 could be used. If left blank,
// the utility will determine the FQDN if available or the machine name.
// This hostname value is needed for certificate
// generation for the Edge Hub server. This certificate is used to enable
// TLS connections from IoT Edge modules and leaf devices.
"hostName": "<Hostname>",

// Log level setting for IoT Edge runtime diagnostics. "info" and "debug".
// are the supported levels and default is info. Users should only
// modify this for debugging purposes.
"logLevel": "info",

// 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, users are
  //    (preInstalled)              expected to supply the "Device CA"
  //                                and "Owner CA" certificates and
  //                                their corresponding certificate chain
  //                                and finally an optional passphrase to
  //                                access the Device CA private key.
  //                                This is more of a real world setup
  //                                where the IoT Edge is configured to run
  //                                as a gateway.
  //    - Certificate Subject       This are values that are used with generating
  //                                any certificates required for operating
  //                                the IoT Edge.
  // The "option" key below selects any of the modes listed above.
  "certificates": {
    "option": "selfSigned",
    "selfSigned": {
      "forceNoPasswords": true
    },
    "preInstalled": {
      "forceNoPasswords": true,
      "ownerCACertificateFilePath": "",
      "deviceCACertificateFilePath": "",
      "deviceCAChainCertificateFilePath": "",
      "deviceCAPrivateKeyFilePath": "",
      "deviceCAPassphraseFilePath": "",
      "agentCAPassphraseFilePath": ""
    },
    "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.
  "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.
    // Under normal circumstances users should not have modify this.
    "uri": "unix:///var/run/docker.sock",

    // IoT Edge runtime image; Users may have to update this as newer images
    // are released over time either by a manual edit or the **update** command.
    "edgeRuntimeImage": "edge_repository_address/edge_image_name:version",

    // Users can add registries in this array for their custom modules.
    // If there is no username or password associated with a registry,
    // users do not need to add any data here.
    // NOTE: This is a temporary configuration item required by the IoT Edge
    // Longer term, users would be able to manage their repositories and
    // credentials in the cloud using the IoTHub portal.
    // Users can manually add their credentials in their configuration file
    // or use 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/
    "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