Package: azure-iot-edge-runtime-ctl
Deprecation NoticeThe 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 theIoT Edge documentation.IntroductionThe 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.PrerequisitesPython 2.7+Python setuptools (for pip installation)DockerInstallationPythonInstallation requires python and setuptools. Downloadpython
here.On Windows, make sure the python.exe and python Scripts directory are on
your path. More information forinstalling python on
Windowscan be found
here.Note: See the Installation Troubleshooting section below if you run into
any problems.PythonInstallation requires python and setuptools. Downloadpython here.On Windows, make sure the python.exe and python Scripts directory are on your path. More information forinstalling python on Windowscan be found here.Note:See the Installation Troubleshooting section below if you run into any problems.DockerFollow the instructions here to get Docker installed on your host machinehttps://docs.microsoft.com/en-us/azure/iot-edgeEnabling 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.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.In Docker Settings Window under‘General’, check“Expose Daemon on tcp://localhost:2375 without TLS”Next steps require to the run from a bash shellAdd the docker executable files to the$PATHenvironment variable and set up aliases.Edit file~/.bashrcand 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~/.bashrcfileAdd environment variableDOCKER_HOSTto sudoers.Edit sudoers configuration by runningsudo visudoAdd this line to the fileDefaults env_keep += "DOCKER_HOST"Save and close the fileEnsure the environment variables get exportedsource ~/.bashrcTest installation by running any docker command. Examples:docker ps
docker imagesInstall the toolIn a terminal, complete the following steps runpip installazure-iot-edge-runtime-ctl(may need to run as
administrator)This should install theiotedgectltool on your path.SeeInstallation Troubleshootingfor
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 thesetupCLI 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:Environment variableEDGECONFIGDIR- When using this, an absolute
path to a directory on the host must be specified as the value of this
variable.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 variableEDGECONFIGDIRand a CLI option is specified,
the environment variable will take precedence and the CLI option will be ignored.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-edgestart: 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 thesetupstep 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 --helpSetup the IoT Edge Runtime using an IoT Edge Host Configuration file. Please seeIoT 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 startRestart the IoT Edge Runtime$> iotedgectl restart
$> iotedgectl --verbose INFO restartStop the IoT Edge Runtime$> iotedgectl stop
$> iotedgectl --verbose INFO stopUninstall the IoT Edge Runtime$> iotedgectl uninstall
$> iotedgectl --verbose DEBUG uninstallPrint the current status of the IoT Edge Runtime$> iotedgectl status
$> iotedgectl --verbose INFO statusIoT Edge Home Directory DescriptionThe 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 theEDGEHOMEDIR.
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-edgeWhen 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 underEDGEHOMEDIR.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 DescriptionThe 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 TroubleshootingRaspbianOn the raspbian platform, you may need to update pip or the setup tools:sudo pip install --upgrade setuptools pipThe 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