azure-iot-edge-runtime-ctl 1.0.0rc14

Azure IoT Edge Runtime Control

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+

• Setuptools (if installing via python)

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.

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 to operate the IoT Edge runtime are: setup, start, restart, stop, status, update, login and uninstall.

• setup: This command accepts users input to configure the runtime. The required configuration files and certificates to operate the IoT Edge are created as part of this step. Users can setup the IoT Edge either by using an input configuration file or specify the configuration items via command line args. When running this command, a user may need to run this with admin (sudo) privileges. The output of this command is a configuration file in JSON format. This file is created in these directory paths on the host:

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

• start: This command starts the IoT Edge runtime. This 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. If a runtime is active, it will be stopped and 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.

Print Help and Exit

$> iotedgectl --help

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

$> iotedgectl setup --help
$> iotedgectl setup --config-file edge_config.json
$> iotedgectl setup --verbose DEBUG --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 Args

$> 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 semi colon 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. 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