Network connectivity errors during installation

Symptoms:

  • The Itron Platform installer rolls back.

  • Network connectivity errors appear in install logs:

    Error: WaitForEndpointAsync: Calling 'https://<hostname>:20800/idenapi/api/v3/diagnostics/dependencies' caused an exception. -THEN- System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Net.WebException: Unable to connect to the remote server ---> System.Net.Sockets.SocketException: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond <hostip>:20800 -OR- System.Net.WebException: Unable to connect to the remote server ---> System.Net.Sockets.SocketException: No connection could be made because the target machine actively refused it <hostip>:20800

Possible causes:

  • IIS does not listen on the target port because:
    • The port binding was unsuccessful (for example, because of a pre-allocated port).
    • The application pool could not start (for example, an IIS user is not in the IIS_IUSRS group or has an invalid password).
    • The AspNetCoreModule (part of the ASP.NET Core Server Hosting Bundle prerequisite) has not been installed on the server.
  • The hostname that was specified or detected during installation does not resolve to the actual web server that is being deployed. The hostname detection rules are as follows:
    • The FQDN command-line parameter overrules any other values detected by the other rules.
    • If the certificate was specified, then the installer tries to use the DNS alternate name first.
    • If there is no DNS alternate name specified in the certificate, then the common name is used.
    • If there was no certificate specified, or if the specified DNS name contains a wildcard or multiple hostnames, then the installer falls back to the fully qualified domain name of the web server (via reading the Domain and Hostname values under the [HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] registry key).

Resolution:

The hostname is verifiable during the installer's summary stage in the Host Address field.

Location of Host Address in the verify settings dialog.

If it does not match a hostname that resolves both on the server side and on the client side of the current web server's IP address, then the installation needs to be restarted with the Fully Qualified Domain Name (FQDN) parameter specified in a command line for executing commands on the Bootstrapper installer. For example:

Platform.Setup.x.x.x.exe -s -r -ip -- SQL_SERVER_NAME="MyDomain\MySQLServerName" SQL_DATABASE_NAME="Iden" SQL_ENSURE_DATABASE=1 IIS_DOMAIN="MyDomain" IIS_USER="JohnDoe" IIS_PASSWORD="JohnDoePassword" ADMIN_NAME="MyDomain\JaneDoe" TENANT_ID="DE02D562-4741-4C2E-8859-6CD30FA1A083"

where

-s = silent

-r = runs the installation (not just extracting all files; displays the Bootstrapper UI if not in silent mode)

-ip -- <parameters> = runs the Platform installation with parameters, where <parameters> refers to one of the following command-line parameters:

  • SQL_SERVER_NAME. The fully qualified domain name of the SQL Server, that may optionally include the SQL instance name separated with a backslash (\), and/or the non-default SQL port separated with a comma (,).
  • SQL_DATABASE_NAME. The database name that is to be created, installed, or upgraded.
  • SQL_ENSURE_DATABASE=1. Creates database if it does not exist. Any other value specified triggers the same behavior. To turn this flag off, the property needs to be omitted.
  • CERTIFICATE_THUMBPRINT. Allows a selection of a specific certificate from the command line. If not specified, the installer tries to find one that matches the server FQDN. If it is specified, but its common name/alternate DNS name differs from the actual hostname, then it sets the FQDN parameter.
  • IIS_DOMAIN. NetBIOS (pre-Windows 2000) name of the domain that the Identity Server will integrate with. It is also the domain part of the IIS app pool user’s down-level logon name (DOMAIN\UserName).
  • IIS_USER. The username (SAM Account Name) part of the IIS user’s down-level logon name (DOMAIN\UserName).
  • IIS_PASSWORD. The password of the IIS app pool user.
  • ADMIN_NAME. Down-level logon name of the primary administrator user in the Portal.
  • TENANT_ID. A globally unique tenant identifier. For test purposes, a random value can be generated if an asterisk (*) is specified. If a valid tenant ID was found in an existing database, then it has precedence over the specified or generated value.
  • FQDN. The hostname to be used by the end-users. The default value is the hostname known by the host machine itself. If this property is specified, then its value has precedence over the default and over the FQDN inferred from the certificate's common name/alternate DNS name.
  • IPL_NONDEFAULT_SHELLAPI_PORT. The default HTTPS port for the UI Portal website is 443. An alternate port number can be specified with this parameter if the default port had already been allocated for another application hosted on the same server.
  • IPL_ACCESSTOKEN_TIMEOUT. The period of inactivity (in seconds) before the user will be signed out automatically. Its default value is 3600.

Notes:

  • The command prompt must be elevated (Run as Administrator).

  • Because of a known issue, the command prompt returns immediately without waiting until the end of the installation or without echoing the log messages to the console. To determine if the installer is still running, use the tasklist | find "msiexec" command.

  • To see the result and the possible errors of the installation, check the most recent bootstrapperlogYYYYMMDD.txt and installogYYYYMMDD.txt files in C:\ProgramData\Itron\LogFiles.

Mandatory parameters:

Depending on the interactivity level (interactive or unattended) and the state of the target machine (Clean: Uninstalled, Installed, or never been installed), the parameters that must be specified are different. The following rules apply (starting with the strongest):

  • None of the parameters are mandatory in case of an interactive installation.
  • Successful installations save the most recently used parameter values in the registry—with the exception of the sensitive IIS_PASSWORD. As a consequence, only the IIS_PASSWORD parameter needs to be specified in case of upgrades, repairs, or reinstalls.
  • Parameters starting with SQL_ do have default values in case of installing the Platform from the Bootstrapper, but do not if the MSI is being executed (therefore, they become mandatory in this case).
  • CERTIFICATE_THUMBPRINT, IIS_DOMAIN, IIS_USER, IIS_PASSWORD, ADMIN_NAME, and TENANT_ID must be specified in case of clean, unattended installations.