-2. **Azure AD provisioning service** runs the scheduled cycles from the cloud HR app tenant and identifies changes that need to be processed for sync with Active Directory.

-Depending on the number of Active Directory domains involved in the inbound user provisioning configuration, you may consider one of the following deployment topologies. Each topology diagram uses an example deployment scenario to highlight configuration aspects. Use the example that closely resembles your deployment requirement to determine the configuration that will meet your needs.

-### Deployment topology 1: Single app to provision all users from Cloud HR to single on-premises Active Directory domain

-This is the most common deployment topology. Use this topology, if you need to provision all users from Cloud HR to a single AD domain and same provisioning rules apply to all users.

-### Deployment topology 2: Separate apps to provision distinct user sets from Cloud HR to single on-premises Active Directory domain

-* Use [scoping filters](define-conditional-rules-for-provisioning-user-accounts.md) in the provisioning app to define users to be processed by each app.

-* To handle the scenario where managers references need to be resolved across distinct user sets (e.g. contractors reporting to managers who are employees), you can create a separate HR2AD provisioning app for updating only the *manager* attribute. Set the scope of this app to all users.

-### Deployment topology 3: Separate apps to provision distinct user sets from Cloud HR to multiple on-premises Active Directory domains (no cross-domain visibility)

-Use this topology to manage multiple independent child AD domains belonging to the same forest, if managers always exist in the same domain as the user and your unique ID generation rules for attributes like *userPrincipalName*, *samAccountName* and *mail* doesn't require a forest-wide lookup. It also offers the flexibility of delegating the administration of each provisioning job by domain boundary.

-For example: In the diagram below, the provisioning apps are set up for each geographic region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). Depending on the location, users are provisioned to the respective AD domain. Delegated administration of the provisioning app is possible so that *EMEA administrators* can independently manage the provisioning configuration of users belonging to the EMEA region.

-### Deployment topology 4: Separate apps to provision distinct user sets from Cloud HR to multiple on-premises Active Directory domains (with cross-domain visibility)

-Use this topology to manage multiple independent child AD domains belonging to the same forest, if a user's manager may exist in the different domain and your unique ID generation rules for attributes like *userPrincipalName*, *samAccountName* and *mail* requires a forest-wide lookup.

-For example: In the diagram below, the provisioning apps are set up for each geographic region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). Depending on the location, users are provisioned to the respective AD domain. Cross-domain manager references and forest-wide lookup are handled by enabling referral chasing on the provisioning agent.

-For example: In the diagram below, a single provisioning app manages users present in three different child domains grouped by region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). The attribute mapping for *parentDistinguishedName* is used to dynamically create a user in the appropriate child domain. Cross-domain manager references and forest-wide lookup are handled by enabling referral chasing on the provisioning agent.

-In large organizations, it isn't uncommon to have multiple HR systems. During business M&A (mergers and acquisitions) scenarios, you may come across a need to connect your on-premises Active Directory to multiple HR sources. We recommend the topology below if you have multiple HR sources and would like to channel the identity data from these HR sources to either the same or different on-premises Active Directory domains.

-The following articles provide additional information regarding password reset through Azure AD:

-[Authentication]: ./media/concept-sspr-howitworks/manage-authentication-methods-for-password-reset.png "Azure AD authentication methods available and quantity required"

-[Registration]: ./media/concept-sspr-howitworks/configure-registration-options.png "Configure SSPR registration options in the Azure portal"

-[Writeback]: ./media/concept-sspr-howitworks/on-premises-integration.png "On-premises integration for SSPR in the Azure portal"

->[!NOTE]

->Rollout has not yet completed across Outlook applications. If this feature is enabled in your tenant, your users may not yet be prompted for the experience. To minimize user disruption, we recommend enabling this feature when the rollout completes.

- |Android | 4.2309.1 |

- |iOS | 4.2309.0 |

- 1. In the Azure portal, click Security > Authentication methods > Microsoft Authenticator.

-| [AddSessionTokenCaches](/dotnet/api/microsoft.identity.web.microsoftidentityappcallswebapiauthenticationbuilder.addsessiontokencaches) | The token cache is bound to the user session. This option isn't ideal if the ID token contains many claims, because the cookie becomes too large.

-To configure those you'll follow these steps:

-1. For Logic Apps authorization policy, we'll need the managed identities **Application ID**. Since the Azure portal only shows the Object ID, we need to look up the Application ID. You can search for the managed identity by Object ID under **Enterprise Applications in the Azure portal** to find the required Application ID.

-1. Create two authorization policies based on the tables below:

- Policy name: AzureADLifecycleWorkflowsAuthPolicy

- Policy name: AzureADLifecycleWorkflowsAuthPolicyV2App

-> [!NOTE]

-> Due to a current bug in the Logic Apps UI you may have to save the authorization policy after each claim before adding another.

-1. In the **Details** tab, choose whether youΓÇÖd like to use an existing Logic App. Selecting Yes in the field ΓÇ£Create new logic appΓÇ¥ (default) creates a new blank Logic App that is already linked to this custom extension. Regardless, you need to provide:

-The admin is responsible for configuring an automated process that is able to send the API **resume request** payload back to entitlement management, once the Logic App workflow has completed. To send back the resume request payload, follow the instructions here in the graph API documents. See information here on the [resume request](/graph/api/accesspackageassignmentrequest-resume)

-Microsoft.graph.accessPackageCustomExtensionStage.assignmentRequestRemoved

-Group-based assignment requires Azure Active Directory Premium P1 or P2 edition. Group-based assignment is supported for Security groups only. Nested group memberships and Microsoft 365 groups aren't currently supported. For more licensing requirements for the features discussed in this article, see the [Azure Active Directory pricing page](https://azure.microsoft.com/pricing/details/active-directory).

-## Activate a role with PowerShell

-There is also an option to activate Privileged Identity Management using PowerShell. You may find more details as documented in the article [PowerShell for Azure AD roles PIM](powershell-for-azure-ad-roles.md).

-The following is a sample script for how to activate Azure resource roles using PowerShell.

-```powershell

-$managementgroupID = "<management group ID" # Tenant Root Group

-$guid = (New-Guid)

-$startTime = Get-Date -Format o

-$userObjectID = "<user object ID"

-$RoleDefinitionID = "b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor

-$scope = "/providers/Microsoft.Management/managementGroups/$managementgroupID"

-New-AzRoleAssignmentScheduleRequest -Name $guid -Scope $scope -ExpirationDuration PT8H -ExpirationType AfterDuration -PrincipalId $userObjectID -RequestType SelfActivate -RoleDefinitionId /providersproviders/Microsoft.Management/managementGroups/$managementgroupID/providers/Microsoft.Authorization/roleDefinitions/$roledefinitionId -ScheduleInfoStartDateTime $startTime -Justification work

-```

-description: Manage Azure AD roles using PowerShell cmdlets in Azure AD Privileged Identity Management (PIM).

-# PowerShell for Azure AD roles in Privileged Identity Management

-This article tells you how to use PowerShell cmdlets to manage Azure AD roles using Privileged Identity Management (PIM) in Azure Active Directory (Azure AD), part of Microsoft Entra. It also tells you how to get set up with the Azure AD PowerShell module.

-## Installation and Setup

-1. Install the Azure AD Preview module

- ```powershell

- Install-module AzureADPreview

- ```

-1. Ensure that you have the required role permissions before proceeding. If you are trying to perform management tasks like giving a role assignment or updating role setting, ensure that you have either the Global administrator or Privileged role administrator role. If you are just trying to activate your own assignment, no permissions beyond the default user permissions are required.

-1. Connect to Azure AD.

- ```powershell

- $AzureAdCred = Get-Credential

- Connect-AzureAD -Credential $AzureAdCred

- ```

-1. Find the Tenant ID for your Azure AD organization by going to **Azure Active Directory** > **Properties** > **Directory ID**. In the cmdlets section, use this ID whenever you need to supply the resourceId.

- 

-> [!Note]

-> The following sections are simple examples that can help get you up and running. You can find more detailed documentation regarding the following cmdlets at [/powershell/module/azuread/?view=azureadps-2.0-preview&preserve-view=true#privileged_role_management](/powershell/module/azuread/?view=azureadps-2.0-preview&preserve-view=true#privileged_role_management). However, you must replace "azureResources" in the providerID parameter with "aadRoles". You will also need to remember to use the Tenant ID for your Azure AD organization as the resourceId parameter.

-## Retrieving role definitions

-Use the following cmdlet to get all built-in and custom Azure AD roles in your Azure AD organization. This important step gives you the mapping between the role name and the roleDefinitionId. The roleDefinitionId is used throughout these cmdlets in order to reference a specific role.

-The roleDefinitionId is specific to your Azure AD organization and is different from the roleDefinitionId returned by the role management API.

-```powershell

-Get-AzureADMSPrivilegedRoleDefinition -ProviderId aadRoles -ResourceId 926d99e7-117c-4a6a-8031-0cc481e9da26

-```

-Result:

-

-## Retrieving role assignments

-Use the following cmdlet to retrieve all role assignments in your Azure AD organization.

-```powershell

-Get-AzureADMSPrivilegedRoleAssignment -ProviderId "aadRoles" -ResourceId "926d99e7-117c-4a6a-8031-0cc481e9da26"

-```

-Use the following cmdlet to retrieve all role assignments for a particular user. This list is also known as "My Roles" in the Azure portal. The only difference here is that you have added a filter for the subject ID. The subject ID in this context is the user ID or the group ID.

-```powershell

-Get-AzureADMSPrivilegedRoleAssignment -ProviderId "aadRoles" -ResourceId "926d99e7-117c-4a6a-8031-0cc481e9da26" -Filter "subjectId eq 'f7d1887c-7777-4ba3-ba3d-974488524a9d'"

-```

-Use the following cmdlet to retrieve all role assignments for a particular role. The roleDefinitionId here is the ID that is returned by the previous cmdlet.

-```powershell

-Get-AzureADMSPrivilegedRoleAssignment -ProviderId "aadRoles" -ResourceId "926d99e7-117c-4a6a-8031-0cc481e9da26" -Filter "roleDefinitionId eq '0bb54a22-a3df-4592-9dc7-9e1418f0f61c'"

-```

-The cmdlets result in a list of role assignment objects shown below. The subject ID is the user ID of the user to whom the role is assigned. The assignment state could either be active or eligible. If the user is active and there is an ID in the LinkedEligibleRoleAssignmentId field, that means the role is currently activated.

-Result:

-

-## Assign a role

-Use the following cmdlet to create an eligible assignment.

-```powershell

-Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'aadRoles' -ResourceId '926d99e7-117c-4a6a-8031-0cc481e9da26' -RoleDefinitionId 'ff690580-d1c6-42b1-8272-c029ded94dec' -SubjectId 'f7d1887c-7777-4ba3-ba3d-974488524a9d' -Type 'adminAdd' -AssignmentState 'Eligible' -schedule $schedule -reason "dsasdsas"

-```

-The schedule, which defines the start and end time of the assignment, is an object that can be created like the following example:

-```powershell

-$schedule = New-Object Microsoft.Open.MSGraph.Model.AzureADMSPrivilegedSchedule

-$schedule.Type = "Once"

-$schedule.StartDateTime = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")

-$schedule.endDateTime = "2020-07-25T20:49:11.770Z"

-```

-> [!Note]

-> If the value of endDateTime is set to null, it indicates a permanent assignment.

-## Activate a role assignment

-Use the following cmdlet to activate an eligible assignment in a context of a regular user:

-```powershell

-Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'aadRoles' -ResourceId '926d99e7-117c-4a6a-8031-0cc481e9da26' -RoleDefinitionId 'f55a9a68-f424-41b7-8bee-cee6a442d418' -SubjectId 'f7d1887c-7777-4ba3-ba3d-974488524a9d' -Type 'UserAdd' -AssignmentState 'Active' -Schedule $schedule -Reason "Business Justification for the role assignment"

-```

-If you need to activate an eligible assignment as administrator, for the `Type` parameter, specify `adminAdd`:

-```powershell

-Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'aadRoles' -ResourceId '926d99e7-117c-4a6a-8031-0cc481e9da26' -RoleDefinitionId 'f55a9a68-f424-41b7-8bee-cee6a442d418' -SubjectId 'f7d1887c-7777-4ba3-ba3d-974488524a9d' -Type 'adminAdd' -AssignmentState 'Active' -Schedule $schedule -Reason "Business Justification for the role assignment"

-```

-This cmdlet is almost identical to the cmdlet for creating a role assignment. The key difference between the cmdlets is that for the ΓÇôType parameter, activation is "userAdd" instead of "adminAdd". The other difference is that the ΓÇôAssignmentState parameter is "Active" instead of "Eligible."

-> [!Note]

-> There are two limiting scenarios for role activation through PowerShell.

-> 1. If you require ticket system / ticket number in your role setting, there is no way to supply those as a parameter. Thus, it would not be possible to activate the role beyond the Azure portal. This feature is being rolled out to PowerShell over the next few months.

-> 1. If you require multi-factor authentication for role activation, there is currently no way for PowerShell to challenge the user when they activate their role. Instead, users will need to trigger the MFA challenge when they connect to Azure AD by following [this blog post](http://www.anujchaudhary.com/2020/02/connect-to-azure-ad-powershell-with-mfa.html) from one of our engineers. If you are developing an app for PIM, one possible implementation is to challenge users and reconnect them to the module after they receive a "MfaRule" error.

-## Retrieving and updating role settings

-Use the following cmdlet to get all role settings in your Azure AD organization.

-```powershell

-Get-AzureADMSPrivilegedRoleSetting -ProviderId 'aadRoles' -Filter "ResourceId eq '926d99e7-117c-4a6a-8031-0cc481e9da26'"

-```

-There are four main objects in the setting. Only three of these objects are currently used by PIM. The UserMemberSettings are activation settings, AdminEligibleSettings are assignment settings for eligible assignments, and the AdminmemberSettings are assignment settings for active assignments.

-[](media/powershell-for-azure-ad-roles/get-update-role-settings-result.png#lightbox)

-To update the role setting, you must get the existing setting object for a particular role and make changes to it:

-```powershell

-Get-AzureADMSPrivilegedRoleSetting -ProviderId 'aadRoles' -Filter "ResourceId eq 'tenant id' and RoleDefinitionId eq 'role id'"

-$settinga = New-Object Microsoft.Open.MSGraph.Model.AzureADMSPrivilegedRuleSetting

-$settinga.RuleIdentifier = "JustificationRule"

-$settinga.Setting = '{"required":false}'

-```

-You can then go ahead and apply the setting to one of the objects for a particular role as shown below. The ID here is the role setting ID that can be retrieved from the result of the list role settings cmdlet.

-```powershell

-Set-AzureADMSPrivilegedRoleSetting -ProviderId 'aadRoles' -Id 'ff518d09-47f5-45a9-bb32-71916d9aeadf' -ResourceId '3f5887ed-dd6e-4821-8bde-c813ec508cf9' -RoleDefinitionId '2387ced3-4e95-4c36-a915-73d803f93702' -UserMemberSettings $settinga

-```

-## Next steps

- | firstname | user.givenname | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | lastname | user.surname | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | title | user.jobtitle | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | picture | URL to the employee's picture | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | company | user.companyname | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | firstName | user.givenname | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | lastName | user.surname | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

- | phone | user.telephonenumber | http://schemas.xmlsoap.org/ws/2005/05/identity/claims |

-| Assess device management requirements | [Microsoft IntTune](/mem/intune/fundamentals/what-is-intune) provides mobile device management (MDM) and mobile application management (MAM). It provides control over company and personal devices. You can manage device usage and enforce policies to control mobile applications. |

-1. Open [end to end demo](http://woodgroveemployee.azurewebsites.net/) in your browser

-We analyzed your Database for PostgreSQL usage pattern over last 30 days and recommend reserved instance purchase that maximizes your savings. With reserved instance you can pre-purchase PostgresSQL Database hourly usage and save over your on-demand costs. Reserved instance is a billing benefit and will automatically apply to new or existing deployments. Saving estimates are calculated for individual subscriptions and the usage pattern over last 30 days. Shared scope recommendations are available in reservation purchase experience and can increase savings further.

-AKS follows a strict versioning window with regard to supportability. With properly selected auto-upgrade channels, you can avoid clusters falling into an unsupported version. For more on the AKS support window, see [Alias minor versions][supported-kubernetes-versions].

-If youΓÇÖre using cluster auto-upgrade, you can no longer upgrade the control plane first and then upgrade the individual node pools. Cluster auto-upgrade will always upgrade the control plane and the node pools together. There is no ability of upgrading the control plane only, and trying to run the command `az aks upgrade --control-plane-only` will raise the error: `NotAllAgentPoolOrchestratorVersionSpecifiedAndUnchanged: Using managed cluster api, all Agent pools' OrchestratorVersion must be all specified or all unspecified. If all specified, they must be stay unchanged or the same with control plane.`

-If using the `node-image` cluster auto-upgrade channel or the `NodeImage` node image auto-upgrade channel, Linux [unattended upgrades][unattended-upgrades] will be disabled by default.

-| `node-image`| automatically upgrade the node image to the latest version available.| Microsoft provides patches and new images for image nodes frequently (usually weekly), but your running nodes won't get the new images unless you do a node image upgrade. Turning on the node-image channel will automatically update your node images whenever a new version is available. If you use this channel, Linux [unattended upgrades] will be disabled by default.|

-If youΓÇÖre using Planned Maintenance and cluster auto-upgrade, your upgrade will start during your specified maintenance window.

-The following best practices will help maximize your success when using auto-upgrade:

-[supported-kubernetes-versions]: supported-kubernetes-versions.md

-[upgrade-aks-cluster]: upgrade-cluster.md

-[planned-maintenance]: planned-maintenance.md

-* An [Azure Active Directory workload identity][aad-workload-identity] (preview)

- --set controller.service.loadBalancerIP=$STATIC_IP

- --set controller.service.loadBalancerIP=$StaticIP

- --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-dns-label-name"=$DNSLABEL

- --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-dns-label-name"=$DnsLabel

-An [Azure resource group][azure-resource-group] is a logical group in which Azure resources are deployed and managed. When you create a resource group, you are prompted to specify a location. This location is:

-* Where your resources will run in Azure if you don't specify another region during resource creation.

-## Install the aks-preview Azure CLI extension

-To install the aks-preview extension, run the following command:

-```azurecli-interactive

-az extension add --name aks-preview

-```

-Run the following command to update to the latest version of the extension released:

-```azurecli-interactive

-az extension update --name aks-preview

-```

-## Register the 'EnableWorkloadIdentityPreview' feature flag

-Register the `EnableWorkloadIdentityPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:

-```azurecli-interactive

-az feature register --namespace "Microsoft.ContainerService" --name "EnableWorkloadIdentityPreview"

-```

-It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature list][az-feature-list] command:

-```azurecli-interactive

-az feature show --namespace "Microsoft.ContainerService" --name "EnableWorkloadIdentityPreview"

-```

-When the status shows *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:

-```azurecli-interactive

-az provider register --namespace Microsoft.ContainerService

-az aks create -g myResourceGroup -n myAKSCluster --node-count 1 --enable-oidc-issuer --enable-workload-identity --generate-ssh-keys

-To get the OIDC Issuer URL and save it to an environmental variable, run the following command. Replace the default value for the arguments `-n`, which is the name of the cluster and `-g`, the resource group name:

-export AKS_OIDC_ISSUER="$(az aks show -n myAKSCluster -g myResourceGroup --query "oidcIssuerProfile.issuerUrl" -otsv)"

-```

-## Export environmental variables

-To help simplify steps to configure creating Azure Key Vault and other identities required, the steps below define

-environmental variables for reference on the cluster.

-Run the following commands to create these variables. Replace the default values for `RESOURCE_GROUP`, `LOCATION`, `KEYVAULT_SECRET_NAME`, `SERVICE_ACCOUNT_NAME`, `SUBSCRIPTION`, `UAID`, and `FICID`.

-```bash

-# environment variables for the Azure Key Vault resource

-export KEYVAULT_NAME="azwi-kv-tutorial"

-export KEYVAULT_SECRET_NAME="my-secret"

-export RESOURCE_GROUP="resourceGroupName"

-export LOCATION="westcentralus"

-# environment variables for the Kubernetes Service account & federated identity credential

-export SERVICE_ACCOUNT_NAMESPACE="default"

-export SERVICE_ACCOUNT_NAME="workload-identity-sa"

-# environment variables for the Federated Identity

-export SUBSCRIPTION="{your subscription ID}"

-# user assigned identity name

-export UAID="fic-test-ua"

-# federated identity name

-export FICID="fic-test-fic-name"

-export KEYVAULT_URL="$(az keyvault show -g ${RESOURCE_GROUP} -n ${KEYVAULT_NAME} --query properties.vaultUri -o tsv)"

-az identity create --name "${UAID}" --resource-group "${RESOURCE_GROUP}" --location "${LOCATION}" --subscription "${SUBSCRIPTION}"

-export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "${RESOURCE_GROUP}" --name "${UAID}" --query 'clientId' -otsv)"

-az identity federated-credential create --name ${FICID} --identity-name ${UAID} --resource-group ${RESOURCE_GROUP} --issuer ${AKS_OIDC_ISSUER} --subject system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}

-To check whether all properties are injected properly by the webhook, use

-test working with an Azure AD workload identity (preview).

-This article covers how to use Azure RBAC for Kubernetes Authorization, which allows for the unified management and access control across Azure resources, AKS, and Kubernetes resources. For more information, see [Azure RBAC for Kubernetes Authorization][azure-rbac-kubernetes-rbac].

-* [Access and identity options for AKS](/concepts-identity.md)

-[kubernetes-rbac]: /concepts-identity#azure-rbac-for-kubernetes-authorization

-[azure-rbac-kubernetes-rbac]: /concepts-identity#azure-rbac-for-kubernetes-authorization

-```azurecli-interactive

-```azurecli-interactive

-```

-```

-Open Service Mesh (OSM) is a supported service mesh that runs Azure Kubernetes Service (AKS):

-[istio]: https://istio.io/latest/docs/setup/install/

- - port: 80

-With AKS, you can create a cluster without specifying the exact patch version. When you create a cluster without designating a patch, the cluster will run the minor version's latest GA patch. For example, if you create a cluster with **`1.21`**, your cluster will run **`1.21.7`**, which is the latest GA patch version of *1.21*.

-When you upgrade by alias minor version, only a higher minor version is supported. For example, upgrading from `1.14.x` to `1.14` won't trigger an upgrade to the latest GA `1.14` patch, but upgrading to `1.15` will trigger an upgrade to the latest GA `1.15` patch. If you wish to upgrade your patch version in the same minor version, please use [auto-upgrade](./auto-upgrade-cluster.md#using-cluster-auto-upgrade).

-To see what patch you're on, run the `az aks show --resource-group myResourceGroup --name myAKSCluster` command. The `currentKubernetesVersion` property shows the whole Kubernetes version.

-Where ".letter" is representative of patch versions.

-When a new minor version is introduced, the oldest minor version and patch releases supported are deprecated and removed. For example, if the current supported version list is:

-az group create --name myResourceGroup --location eastus

-az aks create -g myResourceGroup -n myAKSCluster --enable-oidc-issuer --enable-workload-identity

-To get the OIDC Issuer URL and save it to an environmental variable, run the following command. Replace the default values for the cluster name and the resource group name.

-export AKS_OIDC_ISSUER="$(az aks show -n myAKSCluster -g myResourceGroup --query "oidcIssuerProfile.issuerUrl" -otsv)"

-export SUBSCRIPTION_ID="$(az account show --query id --output tsv)"

-export USER_ASSIGNED_IDENTITY_NAME="myIdentity"

-export RG_NAME="myResourceGroup"

-export LOCATION="eastus"

-az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RG_NAME}" --location "${LOCATION}" --subscription "${SUBSCRIPTION_ID}"

-az aks get-credentials -n myAKSCluster -g myResourceGroup

-Copy and paste the following multi-line input in the Azure CLI, and update the values for `SERVICE_ACCOUNT_NAME` and `SERVICE_ACCOUNT_NAMESPACE` with the Kubernetes service account name and its namespace.

-export SERVICE_ACCOUNT_NAME="workload-identity-sa"

-export SERVICE_ACCOUNT_NAMESPACE="my-namespace"

-export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "${RESOURCE_GROUP}" --name "${UAID}" --query 'clientId' -otsv)"

-az identity federated-credential create --name myfederatedIdentity --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RG_NAME}" --issuer "${AKS_OIDC_ISSUER}" --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" --audience api://AzureADTokenExchange

- export RG_NAME="myResourceGroup"

- export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "${RG_NAME}" --name "${USER_ASSIGNED_IDENTITY_NAME}" --query 'clientId' -otsv)"

-Azure AD workload identity works especially well with the Azure Identity client library using the [Azure SDK][azure-sdk-download] and the [Microsoft Authentication Library][microsoft-authentication-library] (MSAL) if you're using [application registration][azure-ad-application-registration]. Your workload can use any of these libraries to seamlessly authenticate and access Azure cloud resources.

-## Azure Identity SDK

-The following client libraries are the **minimum** version required

-| Language | Library | Minimum Version | Example |

-|--|--|-|-|

-| Go | [azure-sdk-for-go](https://github.com/Azure/azure-sdk-for-go) | [sdk/azidentity/v1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-go/releases/tag/sdk/azidentity/v1.3.0-beta.1)| [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/azure-identity/go) |

-| C# | [azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net) | [Azure.Identity_1.5.0](https://github.com/Azure/azure-sdk-for-net/releases/tag/Azure.Identity_1.5.0)| [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/azure-identity/dotnet) |

-| JavaScript/TypeScript | [azure-sdk-for-js](https://github.com/Azure/azure-sdk-for-js) | [@azure/identity_2.0.0](https://github.com/Azure/azure-sdk-for-js/releases/tag/@azure/identity_2.0.0) | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/azure-identity/node) |

-| Python | [azure-sdk-for-python](https://github.com/Azure/azure-sdk-for-python) | [azure-identity_1.7.0](https://github.com/Azure/azure-sdk-for-python/releases/tag/azure-identity_1.7.0) | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/azure-identity/python) |

-| Java | [azure-sdk-for-java]() | [azure-identity_1.4.0](https://github.com/Azure/azure-sdk-for-java/releases/tag/azure-identity_1.4.0) | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/azure-identity/java) |

-| C# | [microsoft-authentication-library-for-dotnet](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) | ghcr.io/azure/azure-workload-identity/msal-net | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/msal-net/akvdotnet) | Yes |

-| JavaScript/TypeScript | [microsoft-authentication-library-for-js](https://github.com/AzureAD/microsoft-authentication-library-for-js) | ghcr.io/azure/azure-workload-identity/msal-node | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/msal-node) | No |

-| Python | [microsoft-authentication-library-for-python](https://github.com/AzureAD/microsoft-authentication-library-for-python) | ghcr.io/azure/azure-workload-identity/msal-python | [Link](https://github.com/Azure/azure-workload-identity/tree/main/examples/msal-python) | No |

-[azure-sdk-download]: https://azure.microsoft.com/downloads/

-| [WebSocket APIs](websocket-api.md) | No | Yes | Yes | Yes | Yes |

-| [GraphQL APIs](graphql-api.md)⁵ | Yes | Yes | Yes | Yes | Yes |

-| [Synthetic GraphQL APIs (preview)](graphql-schema-resolve-api.md) | No | Yes | Yes | Yes | Yes |

-⁵ GraphQL subscriptions aren't supported in the Consumption tier.

-| [Passthrough GraphQL](graphql-api.md) | Γ£ö∩╕Å | Γ£ö∩╕Ź | Γ¥î |

-| [Synthetic GraphQL](graphql-schema-resolve-api.md) | ✔️ | ❌ | ❌ |

-| [Passthrough WebSocket](websocket-api.md) | ✔️ | ❌ | ✔️ |

-¹ GraphQL subscriptions aren't supported in the Consumption tier.

-| [Set GraphQL resolver](set-graphql-resolver-policy.md) | ✔️ | ❌ | ❌ |

-Follow these steps to grant:

-* `User.Read` **delegated** permission for Microsoft Graph API.

-* `Directory.ReadAll` **application** permission for Microsoft Graph API.

-1. Update the first 3 lines of the following Azure CLI script to match your environment and run it.

- ```azurecli

- $subId = "Your Azure subscription ID" # Example: "1fb8fadf-03a3-4253-8993-65391f432d3a"

- $tenantId = "Your Azure AD Tenant or Organization ID" # Example: 0e054eb4-e5d0-43b8-ba1e-d7b5156f6da8"

- $appObjectID = "Application Object ID that has been registered in AAD" # Example: "2215b54a-df84-453f-b4db-ae079c0d2619"

- #Login and Set the Subscription

- az login

- az account set --subscription $subId

- #Assign the following permission: Microsoft Graph Delegated Permission: User.Read, Microsoft Graph Application Permission: Directory.ReadAll

- az rest --method PATCH --uri "https://graph.microsoft.com/v1.0/$($tenantId)/applications/$($appObjectID)" --body "{'requiredResourceAccess':[{'resourceAccess': [{'id': 'e1fe6dd8-ba31-4d61-89e7-88639da4683d','type': 'Scope'},{'id': '7ab1d382-f21e-4acd-a863-ba3e13f7da61','type': 'Role'}],'resourceAppId': '00000003-0000-0000-c000-000000000000'}]}"

- ```

-1. Sign out and sign back in to the Azure portal.

-1. Select **API Permissions**. You should see the permissions granted by the Azure CLI script in step 1.

-## GraphQL API policies

-|`context`|[`Api`](#ref-context-api): [`IApi`](#ref-iapi)<br /><br /> [`Deployment`](#ref-context-deployment)<br /><br /> Elapsed: `TimeSpan` - time interval between the value of `Timestamp` and current time<br /><br /> [`LastError`](#ref-context-lasterror)<br /><br /> [`Operation`](#ref-context-operation)<br /><br /> [`Product`](#ref-context-product)<br /><br /> [`Request`](#ref-context-request)<br /><br /> `RequestId`: `Guid` - unique request identifier<br /><br /> [`Response`](#ref-context-response)<br /><br /> [`Subscription`](#ref-context-subscription)<br /><br /> `Timestamp`: `DateTime` - point in time when request was received<br /><br /> `Tracing`: `bool` - indicates if tracing is on or off <br /><br /> [User](#ref-context-user)<br /><br /> [`Variables`](#ref-context-variables): `IReadOnlyDictionary<string, object>`<br /><br /> `void Trace(message: string)`|

-If you have existing instances hosted on the `stv1` platform, you can follow our [migration guide](../compute-infrastructure.md#how-do-i-migrate-to-the-stv2-platform) which provides all the details to ensure a successful migration.

-description: Learn about the compute platform used to host your API Management service instance

-We've minimized impacts of this upgrade on your operation of your API Management instance. Upgrades are managed by the platform, and new instances created in service tiers other than the Consumption tier are mostly hosted on the `stv2` platform. However, for existing instances hosted on the `stv1` platform, you have options to trigger migration to the `stv2` platform.

-| `stv2` | Single-tenant v2 | Azure-allocated compute infrastructure that supports availability zones, private endpoints | Developer, Basic, Standard, Premium¹ |

-¹ Newly created instances in these tiers, created using the Azure portal or specifying API version 2021-01-01-preview or later. Includes some existing instances in Developer and Premium tiers configured with virtual networks or availability zones.

-Starting with API version `2021-04-01-preview`, the API Management instance exposes a read-only `platformVersion` property that shows this platform information.

-You can find this information using the portal or the API Management [REST API](/rest/api/apimanagement/current-ga/api-management-service/get).

-To find the `platformVersion` property in the portal:

-1. Go to your API Management instance.

-1. On the **Overview** page, select **JSON view**.

-1. In **API version**, select a current version such as `2021-08-01` or later.

-1. In the JSON view, scroll down to find the `platformVersion` property.

- :::image type="content" source="media/compute-infrastructure/platformversion-property.png" alt-text="platformVersion property in JSON view":::

-## How do I migrate to the `stv2` platform?

-The following table summarizes migration options for instances in the different API Management service tiers that are currently hosted on the `stv1` platform. See the linked documentation for detailed steps.

-> [!NOTE]

-> Check the [`platformVersion` property](#how-do-i-know-which-platform-hosts-my-api-management-instance) before starting migration, and after your configuration change.

-|Tier |Migration options |

-|||

-|Premium | 1. Enable [zone redundancy](../reliability/migrate-api-mgt.md)<br/> -or-<br/> 2. Create new [external](api-management-using-with-vnet.md) or [internal](api-management-using-with-internal-vnet.md) VNet connection¹<br/> -or-<br/> 3. Update existing [VNet configuration](#update-vnet-configuration) |

-|Developer | 1. Create new [external](api-management-using-with-vnet.md) or [internal](api-management-using-with-internal-vnet.md) VNet connection¹<br/>-or-<br/> 2. Update existing [VNet configuration](#update-vnet-configuration) |

-| Standard | 1. [Change your service tier](upgrade-and-scale.md#change-your-api-management-service-tier) (downgrade to Developer or upgrade to Premium). Follow migration options in new tier.<br/>-or-<br/>2. Deploy new instance in existing tier and migrate configurations² |

-| Basic | 1. [Change your service tier](upgrade-and-scale.md#change-your-api-management-service-tier) (downgrade to Developer or upgrade to Premium). Follow migration options in new tier<br/>-or-<br/>2. Deploy new instance in existing tier and migrate configurations² |

-| Consumption | Not applicable |

-¹ Use Azure portal or specify API version 2021-01-01-preview or later.

-

-² Migrate configurations with the following mechanisms: [Backup and restore](api-management-howto-disaster-recovery-backup-restore.md), [Migration script for the developer portal](automate-portal-deployments.md), [APIOps with Azure API Management](/azure/architecture/example-scenario/devops/automated-api-deployments-apiops).

-## Update VNet configuration

-If you have an existing Developer or Premium tier instance that's connected to a virtual network and hosted on the `stv1` platform, trigger migration to the `stv2` platform by updating the VNet configuration.

-### Prerequisites

-* A new or existing virtual network and subnet in the same region and subscription as your API Management instance. The subnet must be different from the one currently used for the instance hosted on the `stv1` platform, and a network security group must be attached.

-* A new or existing Standard SKU [public IPv4 address](../virtual-network/ip-services/public-ip-addresses.md#sku) resource in the same region and subscription as your API Management instance.

-To update the existing external or internal VNet configuration using the portal:

-1. Navigate to your API Management instance.

-1. In the left menu, select **Network** > **Virtual network**.

-1. Select the network connection in the location you want to update.

-1. Select the virtual network, subnet, and IP address resources you want to configure, and select **Apply**.

-1. Continue configuring VNet settings for the remaining locations of your API Management instance.

-1. In the top navigation bar, select **Save**, then select **Apply network configuration**.

-The virtual network configuration is updated, and the instance is migrated to the `stv2` platform. Confirm migration by checking the [`platformVersion` property](#how-do-i-know-which-platform-hosts-my-api-management-instance).

-> [!NOTE]

-> * Updating the VNet configuration takes from 15 to 45 minutes to complete.

-> * The VIP address(es) of your API Management instance will change.

-* Learn more about using a [virtual network](virtual-network-concepts.md) with API Management.

-* Learn more about enabling [availability zones](../reliability/migrate-api-mgt.md).

-* Wildcard domain names, like `*.contoso.com`, are supported in all tiers except the Consumption tier.

-

-> * Learn more about the benefits of using GraphQL APIs.

-> * Add a GraphQL API to your API Management instance.

-> * Learn the limitations of your GraphQL API in API Management.

- :::image type="content" source="media/graphql-api/create-from-graphql-schema.png" alt-text="Screenshot of fields for creating a GraphQL API.":::

- | **GraphQL API endpoint** | The base URL with your GraphQL API endpoint name. <br /> For example: *`https://example.com/your-GraphQL-name`*. You can also use a common "Star Wars" GraphQL endpoint such as `https://swapi-graphql.azure-api.net/graphql` as a demo. |

- | **URL scheme** | Select **HTTP**, **HTTPS**, or **Both**. Default selection: *Both*. |

- | **Gateways** | Associate your GraphQL API with existing gateways. Default gateway selection: *Managed*. |

-1. After the API is created, browse the schema on the **Design** tab, in the **Frontend** section.

-description: Import a GraphQL schema to API Management and configure a policy to resolve a GraphQL query using an HTTP-based data source.

-# Import a GraphQL schema and set up field resolvers

-> * Set up a resolver for a GraphQL query using an existing HTTP endpoints

-1. Under **Define a new API**, select the **Synthetic GraphQL** icon.

- :::image type="content" source="media/graphql-schema-resolve-api/import-graphql-api.png" alt-text="Screenshot of selecting Synthetic GraphQL icon from list of APIs.":::

- | Field | Description |

- | **Fallback GraphQL endpoint** | For this scenario, optionally enter a URL with a GraphQL API endpoint name. API Management passes GraphQL queries to this endpoint when a custom resolver isn't set for a field. |

- | **Upload schema file** | Select to browse and upload a valid GraphQL schema file with the `.graphql` extension. |

- | Description | Add a description of your API. |

- | URL scheme | Select **HTTP**, **HTTPS**, or **Both**. Default selection: *Both*. |

- | **Gateways** | Associate your GraphQL API with existing gateways. Default gateway selection: *Managed*. |

-1. After the API is created, browse the schema on the **Design** tab, in the **Frontend** section.

-Configure the [set-graphql-resolver](set-graphql-resolver-policy.md) policy to map a field in the schema to an existing HTTP endpoint.

-1. On the **Design** tab of your GraphQL API, select **All operations**.

-1. In the **Backend** processing section, select **+ Add policy**.

-1. Configure the `set-graphql-resolver` policy to resolve the *users* query using an HTTP data source.

- For example, the following `set-graphql-resolver` policy retrieves the *users* field by using a `GET` call on an existing HTTP data source.

- <set-graphql-resolver parent-type="Query" field="users">

- </set-graphql-resolver>

-1. To resolve data for other fields in the schema, repeat the preceding step.

-1. Select **Save**.

-description: Reference for the set-graphql-resolver policy available for use in Azure API Management. Provides policy usage, settings, and examples.

-# Set GraphQL resolver

-The `set-graphql-resolver` policy retrieves or sets data for a GraphQL field in an object type specified in a GraphQL schema. The schema must be imported to API Management. Currently the data must be resolved using an HTTP-based data source (REST or SOAP API).

- <json-to-xml>...json-to-xml policy configuration...</json-to-xml>

-| http-request | Specifies a URL and child policies to configure the resolver's HTTP request. Each child element can be specified at most once. | Yes |

-| set-method| Method of the resolver's HTTP request, configured using the [set-method](set-method-policy.md) policy. | Yes |

-| set-url | URL of the resolver's HTTP request. | Yes |

-| set-header | Header set in the resolver's HTTP request, configured using the [set-header](set-header-policy.md) policy. | No |

-| set-body | Body set in the resolver's HTTP request, configured using the [set-body](set-body-policy.md) policy. | No |

-| authentication-certificate | Client certificate presented in the resolver's HTTP request, configured using the [authentication-certificate](authentication-certificate-policy.md) policy. | No |

-| http-response | Optionally specifies child policies to configure the resolver's HTTP response. If not specified, the response is returned as a raw string. Each child element can be specified at most once. |

-| json-to-xml | Transforms the resolver's HTTP response using the [json-to-xml](json-to-xml-policy.md) policy. | No |

-| xml-to-json | Transforms the resolver's HTTP response using the [xml-to-json](xml-to-json-policy.md) policy. | No |

-| find-and-replace | Transforms the resolver's HTTP response using the [find-and-replace](find-and-replace-policy.md) policy. | No |

-* v2 doesn't support IPv6, so IPv6 enabled v1 gateways aren't migrated. If you run the script, it may not complete.

-* If the v1 gateway has only a private IP address, the script creates a public IP address and a private IP address for the new v2 gateway. v2 gateways currently don't support only private IP addresses.

-|Azure Network Watcher integration|Not supported.|

-Azure Form Recognizer is a cloud-based [Azure Applied AI Service](../../applied-ai-services/index.yml) that uses machine-learning models to extract key-value pairs, text, and tables from your documents. Here, you'll learn how to create a Form Recognizer resource in the Azure portal.

- * **Resource group**. The [Azure resource group](/azure/cloud-adoption-framework/govern/resource-consistency/resource-access-management#what-is-an-azure-resource-group) that will contain your resource. You can create a new group or add it to a pre-existing group.

-1. Copy the key and endpoint values from your Form Recognizer resource paste them in a convenient location, such as *Microsoft Notepad*. You'll need the key and endpoint values to connect your application to the Form Recognizer API.

-Azure Policy based Guest configuration is the next iteration of Azure Automation State configuration. [Learn more](../governance/machine-configuration/machine-configuration-policy-effects.md).

- | Obtain compliance data that may include: The configuration of the operating system ΓÇô files, registry, and services, Application configuration or presence, Check environment settings. </br> </br> Audit or deploy settings to all machines (Set) in scope either reactively to existing machines or proactively to new machines as they are deployed. </br> </br> Respond to policy events to provide [remediation on demand or continuous remediation.](../governance/machine-configuration/machine-configuration-policy-effects.md#remediation-on-demand-applyandmonitor) | The Central IT, Infrastructure Administrators, Auditors (Cloud custodians) are working towards the regulatory requirements at scale and ensuring that servers' end state looks as desired. </br> </br> The application teams validate compliance before releasing change. |

-4. Deploy Azure Active Directory from [MSOnline 1.0](http://www.powershellgallery.com/packages/MSOnline/1.0).

-The controllers installed in your Kubernetes cluster with the Microsoft Flux extension require the following CPU and memory resource limits to properly schedule on Kubernetes cluster nodes.

-| Container Name | CPU limit | Memory limit |

-| fluxconfig-agent | 50 m | 150 Mi |

-| fluxconfig-controller | 100 m | 150 Mi |

-| fluent-bit | 20 m | 150 Mi |

-| helm-controller | 1000 m | 1 Gi |

-| source-controller | 1000 m | 1 Gi |

-| kustomize-controller | 1000 m | 1 i |

-| notification-controller | 1000 m | 1 Gi |

-| image-automation-controller | 1000 m | 1 Gi |

-| image-reflector-controller | 1000 m | 1 Gi |

-| `Arc` | `his.arc.azure.com`, `guestconfiguration.azure.com`, `guestnotificationservice.azure.com`, `servicebus.windows.net` |

-> The Desired State Configuration VM extension is no longer available for Azure Arc-enabled servers. Alternatively, we recommend [migrating to machine configuration](../../governance/machine-configuration/machine-configuration-azure-automation-migration.md) or using the Custom Script Extension to manage the post-deployment configuration of your server.

-We'll use the Azure Maps [Data service] to store and render overlays.

-In this section, we'll upload path and pin data to Azure Map data storage.

-You can modify the appearance of the pins by adding style modifiers. For example, to make pushpins and their labels larger or smaller, use the `sc` "scale style" modifier. This modifier takes a value that's greater than zero. A value of 1 is the standard scale. Values larger than 1 will make the pins larger, and values smaller than 1 will make them smaller. For more information about style modifiers, see [static image service path parameters].

-8. Now we'll change the color of the pushpins by modifying the `co` style modifier. If you look at the value of the `pins` parameter (`pins=default|la15+50|al0.66|lc003C62|co002D62|`), you'll see that the current color is `#002D62`. To change the color to `#41d42a`, we'll replace `#002D62` with `#41d42a`. Now the `pins` parameter is `pins=default|la15+50|al0.66|lc003C62|co41D42A|`. The request looks like the following URL:

-[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

-[Postman]: https://www.postman.com/

-[static image service]: /rest/api/maps/render/getmapimage

-[Render service]: /rest/api/maps/render/get-map-image

-[Azure Maps Get Map Image API]: /rest/api/maps/render/getmapimage

-[service documentation]: /rest/api/maps/data

-description: How to configure a web application which supports Azure AD single-sign-on with Azure Maps Web SDK using OpenID Connect protocol.

-The following guide pertains to an application which is hosted on web servers, maintains multiple business scenarios, and deploys to web servers. The application has the requirement to provide protected resources secured only to Azure AD users. The objective of the scenario is to enable the web application to authenticate to Azure AD and call Azure Maps REST APIs on behalf of the user.

-You must create the web application in Azure AD for users to sign in. This web application will then delegate user access to Azure Maps REST APIs.

- > [!div class="mx-imgBorder"]

- > 

-2. Enter a **Name**, choose a **Support account type**, provide a redirect URI which will represent the url which Azure AD will issue the token and is the url where the map control is hosted. For more details please see Azure AD [Scenario: Web app that signs in users](../active-directory/develop/scenario-web-app-sign-user-overview.md). Complete the provided steps from the Azure AD scenario.

-3. Once the application registration is complete, Confirm that application sign-in works for users. Once sign-in works, then the application can be granted delegated access to Azure Maps REST APIs.

-

-4. To assign delegated API permissions to Azure Maps, go to the application. Then select **API permissions** > **Add a permission**. Under **APIs my organization uses**, search for and select **Azure Maps**.

- > [!div class="mx-imgBorder"]

- > 

- > [!div class="mx-imgBorder"]

- > 

-6. Enable the web application to call Azure Maps REST APIs by configuring the app registration with an application secret, For detailed steps, see [A web app that calls web APIs: App registration](../active-directory/develop/scenario-web-app-call-api-app-registration.md). A secret is required to authenticate to Azure AD on-behalf of the user. The app registration certificate or secret should be stored in a secure store for the web application to retrieve to authenticate to Azure AD.

-

- * If the application already has configured an Azure AD app registration and a secret this step may be skipped.

-> [!Tip]

-> If the application is hosted in an Azure environment, we recommend using [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md) and an Azure Key Vault instance to access secrets by [acquiring an access token](../active-directory/managed-identities-azure-resources/how-to-use-vm-token.md) for accessing Azure Key Vault secrets or certificates. To connect to Azure Key Vault to retrieve secrets, see [tutorial to connect through managed identity](../key-vault/general/tutorial-net-create-vault-azure-web-app.md).

-

-7. Implement a secure token endpoint for the Azure Maps Web SDK to access a token.

-

- * For a sample token controller, see [Azure Maps Azure AD Samples](https://github.com/Azure-Samples/Azure-Maps-AzureAD-Samples/blob/master/src/OpenIdConnect/AzureMapsOpenIdConnectv1/AzureMapsOpenIdConnect/Controllers/TokenController.cs).

-8. Configure Azure role-based access control (Azure RBAC) for users or groups. See [grant role-based access for users](#grant-role-based-access-for-users-to-azure-maps).

-9. Configure the web application page with the Azure Maps Web SDK to access the secure token endpoint.

-> [Azure Maps Azure AD Web App Samples](https://github.com/Azure-Samples/Azure-Maps-AzureAD-Samples/tree/master/src/OpenIdConnect)

-| [Update Management](../../automation/update-management/overview.md) (available without Azure Monitor Agent) | Use Update Management v2 - Public preview | None | [Update management center (Public preview) documentation](../../update-center/index.yml) |

-| [Automation Hybrid Runbook Worker overview](../../automation/automation-hybrid-runbook-worker.md) (available without Azure Monitor Agent) | Migrate to Azure Automation Hybrid Worker Extension - Generally available | None | [Migrate an existing Agent based to Extension based Hybrid Workers](../../automation/extension-based-hybrid-runbook-worker-install.md#migrate-an-existing-agent-based-to-extension-based-hybrid-workers) |

- }

-You can disable or delete a Failure Anomalies alert rule, but once deleted you can't create another one for the same Application Insights resource.

-Notice that if you delete an Application Insights resource, the associated Failure Anomalies alert rule doesn't get deleted automatically. You can do so manually on the Alert rules page or with the following Azure CLI command:

-Access to the legacy Free Trial pricing tier was limited on July 1, 2022.

-The Per Node pricing tier charges per monitored VM (node) on an hour granularity. For each monitored node, the workspace is allocated 500 MB of data per day that's not billed. This allocation is calculated with hourly granularity and is aggregated at the workspace level each day. Data ingested above the aggregate daily data allocation is billed per GB as data overage.

-> The Azure NetApp Files backup feature is currently in preview. You need to submit a waitlist request for accessing the feature through the **[Azure NetApp Files Backup Public Preview](https://aka.ms/anfbackuppreviewsignup)** page. Wait for an official confirmation email from the Azure NetApp Files team before using the Azure NetApp Files backup feature.

-> Customer-managed keys for Azure NetApp Files volume encryption is currently in preview. You need to submit a waitlist request for accessing the feature through the **[Customer-managed keys for Azure NetApp Files volume encryption](https://aka.ms/anfcmkpreviewsignup)** page. Customer-managed keys feature is expected to be enabled within a week from submitting waitlist request.

-> The SMB Continuous Availability feature is currently in public preview. You need to submit a waitlist request for accessing the feature through the **[Azure NetApp Files SMB Continuous Availability Shares Public Preview waitlist submission page](https://aka.ms/anfsmbcasharespreviewsignup)**. Wait for an official confirmation email from the Azure NetApp Files team before using the Continuous Availability feature.

-> See the [**Enable Continuous Availability**](azure-netapp-files-create-volumes-smb.md#continuous-availability) option for additional details and considerations.

-To use the publish command, you must have Bicep CLI version **0.4.1008 or later**.

-az bicep publish --file <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag>

-az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

-}

-Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

-az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

-az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

-Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

-| mulResult | Int | 15 |

- "CustomLanguages": null,

- "ExcludedAIs": "Face",

-* [Important notice](#important-notice) about planned changes

-## Important notice

-## April 2023

-You can view the Archive tier pricing from our [pricing page](azure-backup-pricing.md).

-Some general types of errors you might see in Batch are:

-For detailed information about specific error codes, see [Batch Status and Error Codes](/rest/api/batchservice/batch-status-and-error-codes). This reference includes error codes for REST API, Batch service, and job tasks and scheduling.

-During execution, an application might produce diagnostic output. You can use this output to troubleshoot issues. The Batch service writes standard output and standard error output to the `stdout.txt` and `stderr.txt` files in the task directory on the compute node. For more information, see [Files and directories in Batch](files-and-directories.md).

-The process that the task's command line specifies can also fail. For more information, see [Task exit codes](#task-exit-codes).

-To specify the maximum execution duration for a job or task, set the **maxWallClockTime** constraint. Use this setting to terminate tasks that fail to progress.

-The Batch service doesn't determine a task's exit code. The process itself, or the operating system on which the process executed, determines the exit code.

-You can perform additional debugging and troubleshooting by signing in to a compute node remotely. Use the Azure portal to download a Remote Desktop Protocol (RDP) file for Windows nodes, and obtain Secure Shell (SSH) connection information for Linux nodes. You can also download this information using the [Batch .NET](/dotnet/api/microsoft.azure.batch.computenode) or [Batch Python](batch-linux-nodes.md#connect-to-linux-nodes-using-ssh) APIs.

-If necessary, [restrict or disable RDP or SSH access to compute nodes](pool-endpoint-configuration.md).

-Disabling task scheduling on a node effectively takes the node offline. Batch assigns no further tasks to the node. However, the node continues running in the pool. You can then further investigate the failures without losing the failed tasks's data. The node also won't cause additional task failures.

-Batch supports two types of node communication modes:

-This document describes the simplified compute node communication mode and the associated network configuration requirements.

-> Information in this document pertaining to networking resources and rules such as NSGs does not apply to

-> Batch pools with [no public IP addresses](simplified-node-communication-pool-no-public-ip.md) using the

-> node management private endpoint without Internet outbound access.

-> The classic compute node communication model will be retired on **31 March 2026** and will be replaced with

-> the simplified compute node communication model as described in this document. For more information, see the

-> classic compute node communication mode

-> [migration guide](batch-pools-to-simplified-compute-node-communication-model-migration-guide.md).

-## Compute node communication differences between classic and simplified modes

-The simplified compute node communication mode streamlines the way Batch pool infrastructure is

-managed on behalf of users. This communication mode reduces the complexity and scope of inbound

-and outbound networking connections required in baseline operations.

-Batch pools with the `classic` communication mode require the following networking rules in network

-security groups (NSGs), user-defined routes (UDRs), and firewalls when

-[creating a pool in a virtual network](batch-virtual-network.md):

- - Destination ports 29876, 29877 over TCP from BatchNodeManagement.*region*

- - Destination port 443 over TCP to Storage.*region*

- - Destination port 443 over TCP to BatchNodeManagement.*region* for certain workloads that require communication back to the Batch Service, such as Job Manager tasks

-Batch pools with the `simplified` communication mode require the following networking rules in

-NSGs, UDRs, and firewalls:

- - Destination port 443 over ANY to BatchNodeManagement.*region*

-Outbound requirements for a Batch account can be discovered using the

-[List Outbound Network Dependencies Endpoints API](/rest/api/batchmanagement/batch-account/list-outbound-network-dependencies-endpoints)

-This API reports the base set of dependencies, depending upon the Batch account pool communication mode.

-User-specific workloads may need extra rules such as opening traffic to other Azure resources (such as Azure

-Storage for Application Packages, Azure Container Registry, etc.) or endpoints like the Microsoft package

-repository for virtual file system mounting functionality.

-## Benefits of the simplified communication mode

-Azure Batch users utilizing the simplified mode benefit from simplification of networking connections and

-rules. Simplified compute node communication helps reduce security risks by removing the requirement to open

-ports for inbound communication from the internet. Only a single outbound rule to a well-known Service Tag is

-required for baseline operation.

-The `simplified` mode also provides more fine-grained data exfiltration control over the `classic`

-communication mode since outbound communication to Storage.*region* is no longer required. You can

-explicitly lock down outbound communication to Azure Storage if necessary for your workflow. For

-example, you can scope your outbound communication rules to Azure Storage to enable your AppPackage

-storage accounts or other storage accounts for resource files or output files.

-Even if your workloads aren't currently impacted by the changes (as described in the next section), it's

-recommended to move to the `simplified` mode. Future improvements in the Batch service may only be functional

-with simplified compute node communication.

-In many cases, the `simplified` communication mode doesn't directly affect your Batch workloads. However,

-simplified compute node communication has an impact for the following cases:

-If either of these cases applies to you, then follow the steps outlined in the next section to ensure that

-your Batch workloads can still function under the `simplified` mode. We strongly recommend that you test and

-verify all of your changes in a dev and test environment first before pushing your changes into production.

-### Required network configuration changes for simplified communication mode

-The following set of steps is required to migrate to the new communication mode:

-1. Ensure your networking configuration as applicable to Batch pools (NSGs, UDRs, firewalls, etc.) includes a union of the modes (that is, the combined network rules of both `classic` and `simplified` modes). At a minimum, these rules would be:

- - Destination ports 29876, 29877 over TCP from BatchNodeManagement.*region*

- - Destination port 443 over TCP to Storage.*region*

- - Destination port 443 over ANY to BatchNodeManagement.*region*

- - Create new pools with the `targetNodeCommunicationMode` set to `simplified` and validate that the new pools are working correctly. Migrate your workload to the new pools and delete any earlier pools.

- - Update existing pools `targetNodeCommunicationMode` property to `simplified` and then resize all existing pools to zero nodes and scale back out.

-1. Use the [Get Pool](/rest/api/batchservice/pool/get), [List Pool](/rest/api/batchservice/pool/list) API or Portal to confirm the `currentNodeCommunicationMode` is set to the desired communication mode of `simplified`.

-1. Modify all applicable networking configuration to the Simplified Compute Node Communication rules, at the minimum (note any extra rules needed as discussed above):

- - Destination port 443 over ANY to BatchNodeManagement.*region*

-If you follow these steps, but later want to switch back to `classic` compute node communication, you need to take the following actions:

-1. Revert any networking configuration operating exclusively in `simplified` compute node communication mode.

-1. Create new pools or update existing pools `targetNodeCommunicationMode` property set to `classic`.

-1. See step 4 above to confirm that your pools are operating in `classic` communication mode.

-## Specifying the node communication mode on a Batch pool

-The [`targetNodeCommunicationMode`](/rest/api/batchservice/pool/add) property on Batch pools allows you to indicate a preference

-to the Batch service for which communication mode to utilize between the Batch service and compute nodes. The following are

-the allowable options on this property:

-network, the pool may be created in either `classic` or `simplified` mode. For pools with a virtual network, the pool will always

-default to `classic` until **30 September 2024**. For more information, see the classic compute node communication mode

-[migration guide](batch-pools-to-simplified-compute-node-communication-model-migration-guide.md).

-> Specifying the target node communication mode is a preference indication for the Batch service and not a guarantee that it

-> will be honored. Certain configurations on the pool may prevent the Batch service from honoring the specified target node

-> communication mode, such as interaction with No public IP address, virtual networks, and the pool configuration type.

-The following are examples of how to create a Batch pool with `simplified` compute node communication.

-Navigate to the Pools blade of your Batch account and click the Add button. Under `OPTIONAL SETTINGS`, you can

-select `Simplified` as an option from the pull-down of `Node communication mode` as shown below.

-To update an existing pool to simplified communication mode, navigate to the Pools blade of your Batch account and

-click on the pool to update. On the left-side navigation, select `Node communication mode`. There you're able

-to select a new target node communication mode as shown below. After selecting the appropriate communication mode,

-click the `Save` button to update. You need to scale the pool down to zero nodes first, and then back out

-for the change to take effect, if conditions allow.

-To display the current node communication mode for a pool, navigate to the Pools blade of your Batch account, and

-click on the pool to view. Select `Properties` on the left-side navigation and the pool node communication mode

-will be shown under the General section.

-This example shows how to use the [Batch Service REST API](/rest/api/batchservice/pool/add) to create a pool with

-`simplified` compute node communication.

-The following are known limitations of the `simplified` communication mode:

-([V1 preview](batch-pool-no-public-ip-address.md)). These pools can only be migrated if created in a

-[virtual network](batch-virtual-network.md), otherwise they won't use simplified compute node communication, even

-if specified on the pool. For more information, see the

-[migration guide](batch-pools-without-public-ip-addresses-classic-retirement-migration-guide.md).

-[deprecated](https://azure.microsoft.com/updates/azure-batch-cloudserviceconfiguration-pools-will-be-retired-on-29-february-2024/).

-Specifying a communication mode for these types of pools aren't honored and always results in `classic`

-communication mode. We recommend using Virtual Machine Configuration for your Batch pools. For more information, see

-[Migrate Batch pool configuration from Cloud Services to Virtual Machine](batch-pool-cloud-service-to-virtual-machine-configuration.md).

- The language used here is [Razor](http://www.asp.net/web-pages/overview/getting-started/introducing-razor-syntax-c), which lets you embed executable code in HTML markup. The ```@foreach``` statement in the middle of the file enumerates the **BlobInfo** objects passed from the controller in **ViewBag** and creates HTML ```<img>``` elements from them. The ```src``` property of each element is initialized with the URI of the blob containing the image thumbnail.

-### Using Speech-to-text custom models

-### Using Speech-to-text batch transcription

-To identify languages in [Batch transcription](batch-transcription.md), you need to use `languageIdentification` property in the body of your [transcription REST request](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create). The example in this section shows the usage of `languageIdentification` property with four candidate languages.

-> [!WARNING]

-> Batch transcription only supports language identification for base models. If both language identification and a custom model are specified in the transcription request, the service will fall back to use the base models for the specified candidate languages. This may result in unexpected recognition results.

->

-> If your speech to text scenario requires both language identification and custom models, use [real-time speech to text](#using-speech-to-text-custom-models) instead of batch transcription.

-```json

-{

- <...>

-

- "properties": {

- <...>

-

- "languageIdentification": {

- "candidateLocales": [

- "en-US",

- "ja-JP",

- "zh-CN",

- "hi-IN"

- ]

- },

- <...>

- }

-}

-```

-> See [Speech Containers](speech-container-howto.md#available-speech-containers) and [Embedded Speech](embedded-speech.md#models-and-voices) separately for their supported languages.

-The batch kit container is available for free on [GitHub](https://github.com/microsoft/batch-processing-kit) and [Docker hub](https://hub.docker.com/r/batchkit/speech-batch-kit/tags). You are only [billed](speech-container-howto.md#billing) for the Speech containers you use.

-```Docker

-```Docker

-```Docker

-Speech containers enable customers to build one speech application architecture that is optimized to take advantage of both robust cloud capabilities and edge locality. The supported speech containers are **speech-to-text**, **Custom speech-to-text**, **speech language identification** and **Neural text-to-speech**.

-The **Speech** container runtime environment is configured using the `docker run` command arguments. This container has several required settings, along with a few optional settings. Several [examples](#example-docker-run-commands) of the command are available. The container-specific settings are the billing settings.

-> The [`ApiKey`](#apikey-configuration-setting), [`Billing`](#billing-configuration-setting), and [`Eula`](#eula-setting) settings are used together, and you must provide valid values for all three of them; otherwise your container won't start. For more information about using these configuration settings to instantiate a container, see [Billing](speech-container-howto.md#billing).

-| Yes | `Billing` | String | Billing endpoint URI. For more information on obtaining the billing URI, see [gather required parameters](speech-container-howto.md#gather-required-parameters). For more information and a complete list of regional endpoints, see [Custom subdomain names for Cognitive Services](../cognitive-services-custom-subdomains.md). |

-### Volume mount example

-This command mounts the host machine _C:\input_ directory to the containers _/usr/local/models_ directory.

-> [!IMPORTANT]

-> The volume mount settings are only applicable to **Custom Speech-to-text** containers. The **Speech-to-text**, **Neural Text-to-speech** and **Speech language identification** containers do not use volume mounts.

-## Example docker run commands

-The following examples use the configuration settings to illustrate how to write and use `docker run` commands. Once running, the container continues to run until you [stop](speech-container-howto.md#stop-the-container) it.

-Replace {_argument_name_} with your own values:

-| Placeholder | Value | Format or example |

-| -- | -- | -- |

-| **{API_KEY}** | The endpoint key of the `Speech` resource on the Azure `Speech` Keys page. | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

-| **{ENDPOINT_URI}** | The billing endpoint value is available on the Azure `Speech` Overview page. | See [gather required parameters](speech-container-howto.md#gather-required-parameters) for explicit examples. |

-> [!IMPORTANT]

-> The `Eula`, `Billing`, and `ApiKey` options must be specified to run the container; otherwise, the container won't start. For more information, see [Billing](#billing-configuration-setting).

-> The ApiKey value is the **Key** from the Azure Speech Resource keys page.

-## Speech container Docker examples

-The following Docker examples are for the Speech container.

-## [Speech-to-text](#tab/stt)

-### Basic example for Speech-to-text

-```Docker

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-### Logging example for Speech-to-text

-```Docker

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY} \

-Logging:Console:LogLevel:Default=Information

-```

-## [Custom Speech-to-text](#tab/cstt)

-### Basic example for Custom Speech-to-text

-```Docker

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-ModelId={MODEL_ID} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-### Logging example for Custom Speech-to-text

-```Docker

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-ModelId={MODEL_ID} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY} \

-Logging:Console:LogLevel:Default=Information

-```

-## [Neural Text-to-speech](#tab/ntts)

-### Basic example for Neural Text-to-speech

-```Docker

-docker run --rm -it -p 5000:5000 --memory 12g --cpus 6 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-### Logging example for Neural Text-to-speech

-```Docker

-docker run --rm -it -p 5000:5000 --memory 12g --cpus 6 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY} \

-Logging:Console:LogLevel:Default=Information

-```

-## [Speech Language Identification](#tab/lid)

-### Basic example for Speech language identification

-```Docker

-docker run --rm -it -p 5000:5000 --memory 1g --cpus 1 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-### Logging example for Speech language identification

-```Docker

-docker run --rm -it -p 5000:5000 --memory 1g --cpus 1 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY} \

-Logging:Console:LogLevel:Default=Information

-```

-description: Use the Docker containers for the Speech service to perform speech recognition, transcription, generation, and more on-premises.

-# Install and run Docker containers for the Speech service APIs

-By using containers, you can run _some_ of the Azure Cognitive Services Speech service APIs in your own environment. Containers are great for specific security and data governance requirements. In this article, you'll learn how to download, install, and run a Speech container.

-With Speech containers, you can build a speech application architecture that's optimized for both robust cloud capabilities and edge locality. Several containers are available, which use the same [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/) as the cloud-based Azure Speech services.

-## Available Speech containers

-> [!IMPORTANT]

-> We retired the standard speech synthesis voices and text-to-speech container on August 31, 2021. Consider migrating your applications to use the neural text-to-speech container instead. For more information on updating your application, see [Migrate from standard voice to prebuilt neural voice](./how-to-migrate-to-prebuilt-neural-voice.md).

-| Container | Features | Supported versions and locales |

-|--|--|--|

-| Speech-to-text | Analyzes sentiment and transcribes continuous real-time speech or batch audio recordings with intermediate results. | Latest: 3.13.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/speech-to-text/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/speech-to-text/tags/list).|

-| Custom speech-to-text | Using a custom model from the [Custom Speech portal](https://speech.microsoft.com/customspeech), transcribes continuous real-time speech or batch audio recordings into text with intermediate results. | Latest: 3.13.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/custom-speech-to-text/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/speech-to-text/tags/list). |

-| Speech language identification | Detects the language spoken in audio files. | Latest: 1.11.0¹<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/language-detection/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/language-detection/tags/list). |

-| Neural text-to-speech | Converts text to natural-sounding speech by using deep neural network technology, which allows for more natural synthesized speech. | Latest: 2.12.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/neural-text-to-speech/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/neural-text-to-speech/tags/list). |

-¹ The container is available in public preview. Containers in preview are still under development and don't meet Microsoft's stability and support requirements.

-> [!IMPORTANT]

-> To use the Speech containers, you must submit an online request and have it approved. For more information, see the "Request approval to run the container" section.

-## Host computer requirements and recommendations

-> For example, speech-to-text containers memory map portions of a large language model. We recommend that the entire file should fit in memory. You need to add an additional 4 to 8 GB to load the speech modesl (see above table).

-### Advanced Vector Extension support

-The *host* is the computer that runs the Docker container. The host *must support* [Advanced Vector Extensions](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#CPUs_with_AVX2) (AVX2). You can check for AVX2 support on Linux hosts with the following command:

-```console

-grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

-```

-> [!WARNING]

-> The host computer is *required* to support AVX2. The container *will not* function correctly without AVX2 support.

-## Request approval to run the container

-Fill out and submit the [request form](https://aka.ms/csgate) to request access to the container.

-## Speech container images

-# [Speech-to-text](#tab/stt)

-The Speech-to-text container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/speechservices/` repository and is named `speech-to-text`. The fully qualified container image name is, `mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text`. You can find a full list of [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/speech-to-text/tags).

-| Container | Repository |

-|--||

-| Speech-to-text | `mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest` |

-# [Custom speech-to-text](#tab/cstt)

-The Custom Speech-to-text container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/speechservices/` repository and is named `custom-speech-to-text`. The fully qualified container image name is `mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text`.

-To use the latest version of the container, you can use the `latest` tag. You can also find a full list of [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/custom-speech-to-text/tags).

-| Container | Repository |

-|--||

-| Custom speech-to-text | `mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text:latest` |

-# [Neural text-to-speech](#tab/ntts)

-The Neural Text-to-speech container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/speechservices/` repository and is named `neural-text-to-speech`. The fully qualified container image name is, `mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech`.

-To use the latest version of the container, you can use the `latest` tag. You can also find a full list of [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/neural-text-to-speech/about).

-| Container | Repository |

-|--||

-| Neural text-to-speech | `mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech:latest` |

-# [Speech language identification](#tab/lid)

-The Speech language detection container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/speechservices/` repository and is named `language-detection`. The fully qualified container image name is, `mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection`.

-To use the latest version of the container, you can use the `latest` tag. You can also find a full list of [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/language-detection/tags).

-> [!TIP]

-> To get the most useful results, use the Speech language identification container with the speech-to-text or custom speech-to-text containers.

-| Container | Repository |

-|--||

-| Speech language identification | `mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection:latest` |

-***

-### Get the container image with docker pull

-# [Speech-to-text](#tab/stt)

-#### Docker pull for the speech-to-text container

-Use the [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) command to download a container image from Microsoft Container Registry:

-```Docker

-docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest

-```

-> [!IMPORTANT]

-> The `latest` tag pulls the `en-US` locale. For additional locales, see [Speech-to-text locales](#speech-to-text-locales).

-#### Speech-to-text locales

-All tags, except for `latest`, are in the following format and are case sensitive:

-```

-<major>.<minor>.<patch>-<platform>-<locale>-<prerelease>

-```

-The following tag is an example of the format:

-```

-2.6.0-amd64-en-us

-```

-For all the supported locales of the speech-to-text container, see [Speech-to-text image tags](../containers/container-image-tags.md#speech-to-text).

-# [Custom speech-to-text](#tab/cstt)

-#### Docker pull for the custom speech-to-text container

-Use the [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) command to download a container image from Microsoft Container Registry:

-```Docker

-docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text:latest

-```

-> [!NOTE]

-> The `locale` and `voice` for custom Speech containers is determined by the custom model ingested by the container.

-# [Neural text-to-speech](#tab/ntts)

-#### Docker pull for the neural text-to-speech container

-Use the [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) command to download a container image from Microsoft Container Registry:

-```Docker

-docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech:latest

-```

-> [!IMPORTANT]

-> The `latest` tag pulls the `en-US` locale and `arianeural` voice. For more locales, see [Neural text-to-speech locales](#neural-text-to-speech-locales).

-#### Neural text-to-speech locales

-All tags, except for `latest`, are in the following format and are case sensitive:

-```

-<major>.<minor>.<patch>-<platform>-<locale>-<voice>

-```

-The following tag is an example of the format:

-```

-1.3.0-amd64-en-us-arianeural

-```

-For all the supported locales and corresponding voices of the neural text-to-speech container, see [Neural text-to-speech image tags](../containers/container-image-tags.md#neural-text-to-speech).

-> [!IMPORTANT]

-> When you construct a neural text-to-speech HTTP POST, the [SSML](speech-synthesis-markup.md) message requires a `voice` element with a `name` attribute. The value is the corresponding container [locale and voice](language-support.md?tabs=tts). For example, the `latest` tag would have a voice name of `en-US-AriaNeural`.

-# [Speech language identification](#tab/lid)

-#### Docker pull for the Speech language identification container

-Use the [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) command to download a container image from Microsoft Container Registry:

-```Docker

-docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection:latest

-```

-***

-## Use the container

-After the container is on the [host computer](#host-computer-requirements-and-recommendations), use the following process to work with the container.

-1. [Run the container](#run-the-container-with-docker-run) with the required billing settings. More [examples](speech-container-configuration.md#example-docker-run-commands) of the `docker run` command are available.

-1. [Query the container's prediction endpoint](#query-the-containers-prediction-endpoint).

-## Run the container with docker run

-Use the [docker run](https://docs.docker.com/engine/reference/commandline/run/) command to run the container. For more information on how to get the `{Endpoint_URI}` and `{API_Key}` values, see [Gather required parameters](#gather-required-parameters). More [examples](speech-container-configuration.md#example-docker-run-commands) of the `docker run` command are also available.

-> [!NOTE]

-> For general container requirements, see [Container requirements and recommendations](#container-requirements-and-recommendations).

-# [Speech-to-text](#tab/stt)

-### Run the container connected to the internet

-To run the standard speech-to-text container, execute the following `docker run` command:

-```bash

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-This command:

-* Runs a *speech-to-text* container from the container image.

-* Allocates 4 CPU cores and 8 GB of memory.

-* Exposes TCP port 5000 and allocates a pseudo-TTY for the container.

-* Automatically removes the container after it exits. The container image is still available on the host computer.

-> To install GStreamer in a container,

-> follow Linux instructions for GStreamer in [Use codec compressed audio input with the Speech SDK](how-to-use-codec-compressed-audio-input-streams.md).

-### Run the container disconnected from the internet

-The speech-to-text container provide a default directory for writing the license file and billing log at runtime. The default directories are /license and /output respectively.

-When you're mounting these directories to the container with the `docker run -v` command, make sure the local machine directory is set ownership to `user:group nonroot:nonroot` before running the container.

-Below is a sample command to set file/directory ownership.

-```bash

-sudo chown -R nonroot:nonroot <YOUR_LOCAL_MACHINE_PATH_1> <YOUR_LOCAL_MACHINE_PATH_2> ...

-### Diarization on the speech-to-text output

-Diarization is enabled by default. To get diarization in your response, use `diarize_speech_config.set_service_property`.

-1. Set the phrase output format to `Detailed`.

-2. Set the mode of diarization. The supported modes are `Identity` and `Anonymous`.

-

- ```python

- diarize_speech_config.set_service_property(

- name='speechcontext-PhraseOutput.Format',

- value='Detailed',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

- )

-

- diarize_speech_config.set_service_property(

- name='speechcontext-phraseDetection.speakerDiarization.mode',

- value='Identity',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

- )

- ```

- > [!NOTE]

- > "Identity" mode returns `"SpeakerId": "Customer"` or `"SpeakerId": "Agent"`.

- > "Anonymous" mode returns `"SpeakerId": "Speaker 1"` or `"SpeakerId": "Speaker 2"`.

-

-### Analyze sentiment on the speech-to-text output

-Starting in v2.6.0 of the speech-to-text container, you should use Language service 3.0 API endpoint instead of the preview one. For example:

-* `https://eastus.api.cognitive.microsoft.com/text/analytics/v3.0/sentiment`

-* `https://localhost:5000/text/analytics/v3.0/sentiment`

-> [!NOTE]

-> The Language service `v3.0` API isn't backward compatible with `v3.0-preview.1`. To get the latest sentiment feature support, use `v2.6.0` of the speech-to-text container image and Language service `v3.0`.

-Starting in v2.2.0 of the speech-to-text container, you can call the [sentiment analysis v3 API](../text-analytics/how-tos/text-analytics-how-to-sentiment-analysis.md) on the output. To call sentiment analysis, you'll need a Language service API resource endpoint. For example:

-* `https://eastus.api.cognitive.microsoft.com/text/analytics/v3.0-preview.1/sentiment`

-* `https://localhost:5000/text/analytics/v3.0-preview.1/sentiment`

-If you're accessing a Language service endpoint in the cloud, you'll need a key. If you're running Language service features locally, you might not need to provide this.

-The key and endpoint are passed to the Speech container as arguments, as in the following example:

-docker run -it --rm -p 5000:5000 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY} \

-CloudAI:SentimentAnalysisSettings:TextAnalyticsHost={TEXT_ANALYTICS_HOST} \

-CloudAI:SentimentAnalysisSettings:SentimentAnalysisApiKey={SENTIMENT_APIKEY}

-```

-This command:

-* Performs the same steps as the preceding command.

-* Stores a Language service API endpoint and key, for sending sentiment analysis requests.

-### Phraselist v2 on the speech-to-text output

-Starting in v2.6.0 of the speech-to-text container, you can get the output with your own phrases, either the whole sentence or phrases in the middle. For example, *the tall man* in the following sentence:

-* "This is a sentence **the tall man** this is another sentence."

-To configure a phrase list, you need to add your own phrases when you make the call. For example:

-```python

- phrase="the tall man"

- recognizer = speechsdk.SpeechRecognizer(

- speech_config=dict_speech_config,

- audio_config=audio_config)

- phrase_list_grammer = speechsdk.PhraseListGrammar.from_recognizer(recognizer)

- phrase_list_grammer.addPhrase(phrase)

-

- dict_speech_config.set_service_property(

- name='setflight',

- value='xonlineinterp',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

- )

-If you have multiple phrases to add, call `.addPhrase()` for each phrase to add it to the phrase list.

-# [Custom speech-to-text](#tab/cstt)

-The custom speech-to-text container relies on a Custom Speech model. The custom model has to have been [trained](how-to-custom-speech-train-model.md) by using the [Speech Studio](https://aka.ms/speechstudio/customspeech).

-The custom speech **Model ID** is required to run the container. For more information about how to get the model ID, see [Custom Speech model lifecycle](how-to-custom-speech-model-and-endpoint-lifecycle.md).

-

-Obtain the **Model ID** to use as the argument to the `ModelId` parameter of the `docker run` command.

-

-The following table represents the various `docker run` parameters and their corresponding descriptions:

-| Parameter | Description |

-|||

-| `{VOLUME_MOUNT}` | The host computer [volume mount](https://docs.docker.com/storage/volumes/), which Docker uses to persist the custom model. An example is *C:\CustomSpeech* where the C drive is located on the host machine. |

-| `{MODEL_ID}` | The custom speech model ID. For more information, see [Custom Speech model lifecycle](how-to-custom-speech-model-and-endpoint-lifecycle.md). |

-| `{ENDPOINT_URI}` | The endpoint is required for metering and billing. For more information, see [Gather required parameters](#gather-required-parameters). |

-| `{API_KEY}` | The API key is required. For more information, see [Gather required parameters](#gather-required-parameters). |

-To run the custom speech-to-text container, execute the following `docker run` command:

-```bash

-docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-ModelId={MODEL_ID} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-This command:

-* Runs a custom speech-to-text container from the container image.

-* Allocates 4 CPU cores and 8 GB of memory.

-* Loads the custom speech-to-text model from the volume input mount, for example, *C:\CustomSpeech*.

-* Exposes TCP port 5000 and allocates a pseudo-TTY for the container.

-* Downloads the model given the `ModelId` (if not found on the volume mount).

-* If the custom model was previously downloaded, the `ModelId` is ignored.

-* Automatically removes the container after it exits. The container image is still available on the host computer.

-#### Base model download on the custom speech-to-text container

-Starting in v2.6.0 of the custom-speech-to-text container, you can get the available base model information by using option `BaseModelLocale={LOCALE}`. This option gives you a list of available base models on that locale under your billing account. For example:

-```bash

-docker run --rm -it \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-BaseModelLocale={LOCALE} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-This command:

-* Runs a custom speech-to-text container from the container image.

-* Checks and returns the available base models of the target locale.

-The output gives you a list of base models with the information locale, model ID, and creation date time. You can use the model ID to download and use the specific base model you prefer. For example:

-```

-Checking available base model for en-us

-2020/10/30 21:54:20 [Info] Searching available base models for en-us

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2016-11-04T08:23:42Z, Id: a3d8aab9-6f36-44cd-9904-b37389ce2bfa

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2016-11-04T12:01:02Z, Id: cc7826ac-5355-471d-9bc6-a54673d06e45

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2017-08-17T12:00:00Z, Id: a1f8db59-40ff-4f0e-b011-37629c3a1a53

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2018-04-16T11:55:00Z, Id: c7a69da3-27de-4a4b-ab75-b6716f6321e5

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2018-09-21T15:18:43Z, Id: da494a53-0dad-4158-b15f-8f9daca7a412

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2018-10-19T11:28:54Z, Id: 84ec130b-d047-44bf-a46d-58c1ac292ca7

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2018-11-26T07:59:09Z, Id: ee5c100f-152f-4ae5-9e9d-014af3c01c56

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2018-11-26T09:21:55Z, Id: d04959a6-71da-4913-9997-836793e3c115

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2019-01-11T10:04:19Z, Id: 488e5f23-8bc5-46f8-9ad8-ea9a49a8efda

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2019-02-18T14:37:57Z, Id: 0207b3e6-92a8-4363-8c0e-361114cdd719

-2020/10/30 21:54:21 [Info] [Base model] Locale: en-us, CreatedDate: 2019-03-03T17:34:10Z, Id: 198d9b79-2950-4609-b6ec-f52254074a05

-2020/10/30 21:54:21 [Fatal] Please run this tool again and assign --modelId '<one above base model id>'. If no model id listed above, it means currently there is no available base model for en-us

-```

-#### Display model download on the custom speech-to-text container

-Starting in v3.1.0 of the custom-speech-to-text container, you can get the available display models information and choose to download those models into your speech-to-text container to get highly improved final display output.

-You can query or download any or all of these display model types: Rescoring (`Rescore`), Punctuation (`Punct`), resegmentation (`Resegment`), and wfstitn (`Wfstitn`). Otherwise, you can use the `FullDisplay` option (with or without the other types) to query or download all types of display models.

-Set the `BaseModelLocale` to query the latest available display model on the target locale. If you include multiple display model types, the command will return the latest available display models for each type. For example:

-```bash

-docker run --rm -it \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-Punct Rescore Resegment Wfstitn \ # Specify `FullDisplay` or a space-separated subset of display models

-BaseModelLocale={LOCALE} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-Set the `DisplayLocale` to download the latest available display model on the target locale. When you set `DisplayLocale`, you must also specify `FullDisplay` or a space-separated subset of display models. The command will download the latest available display model for each specified type. For example:

-```bash

-docker run --rm -it \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-Punct Rescore Resegment Wfstitn \ # Specify `FullDisplay` or a space-separated subset of display models

-DisplayLocale={LOCALE} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-Set one model ID parameter to download a specific display model: Rescoring (`RescoreId`), Punctuation (`PunctId`), resegmentation (`ResegmentId`), or wfstitn (`WfstitnId`). This is similar to how you would download a base model via the `ModelId` parameter. For example, to download a rescoring display model, you can use the following command with the `RescoreId` parameter:

-```bash

-docker run --rm -it \

-mcr.microsoft.com/azure-cognitive-services/speechservices/custom-speech-to-text \

-RescoreId={RESCORE_MODEL_ID} \

-Eula=accept \

-Billing={ENDPOINT_URI} \

-ApiKey={API_KEY}

-```

-> If you set more than one query or download parameter, the command will prioritize in this order: `BaseModelLocale`, model ID, and then `DisplayLocale` (only applicable for display models).

-#### Custom pronunciation on the custom speech-to-text container

-Starting in v2.5.0 of the custom-speech-to-text container, you can get custom pronunciation results in the output. All you need to do is have your own custom pronunciation rules set up in your custom model and mount the model to a custom-speech-to-text container.

-### Run the container disconnected from the internet

-To use this container disconnected from the internet, you must first request access by filling out an application, and purchasing a commitment plan. See [Use Docker containers in disconnected environments](../containers/disconnected-containers.md) for more information.

-In order to prepare and configure the Custom Speech-to-Text container you will need two separate speech resources:

-1. A regular Azure Speech Service resource which is either configured to use a "**S0 - Standard**" pricing tier or a "**Speech to Text (Custom)**" commitment tier pricing plan. This will be used to train, download, and configure your custom speech models for use in your container.

-1. An Azure Speech Service resource which is configured to use the "**DC0 Commitment (Disconnected)**" pricing plan. This is used to download your disconnected container license file required to run the container in disconnected mode.

-Download the docker container and run it to get the required speech model as [described above](#get-the-container-image-with-docker-pull) using the regular Azure Speech resource. Next, you will need to download your disconnected license file.

-The `DownloadLicense=True` parameter in your `docker run` command will download a license file that will enable your Docker container to run when it isn't connected to the internet. It also contains an expiration date, after which the license file will be invalid to run the container. You can only use a license file with the appropriate container that you've been approved for. For example, you can't use a license file for a speech-to-text container with a form recognizer container.

-| Placeholder | Value | Format or example |

-|-|-||

-| `{IMAGE}` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice` |

-| `{LICENSE_MOUNT}` | The path where the license will be downloaded, and mounted. | `/host/license:/path/to/license/directory` |

-| `{ENDPOINT_URI}` | The endpoint for authenticating your service request. You can find it on your resource's **Key and endpoint** page, on the Azure portal. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |

-| `{API_KEY}` | The key for your Text Analytics resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal. |`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`|

-| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

-```bash

-docker run --rm -it -p 5000:5000 \

-{IMAGE} \

-eula=accept \

-billing={ENDPOINT_URI} \

-apikey={API_KEY} \

-DownloadLicense=True \

-Mounts:License={CONTAINER_LICENSE_DIRECTORY}

-```

-Once the license file has been downloaded, you can run the container in a disconnected environment. The following example shows the formatting of the `docker run` command you'll use, with placeholder values. Replace these placeholder values with your own values.

-Wherever the container is run, the license file must be mounted to the container and the location of the license folder on the container's local filesystem must be specified with `Mounts:License=`. An output mount must also be specified so that billing usage records can be written.

-Placeholder | Value | Format or example |

-|-|-||

-| `{IMAGE}` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice` |

- `{MEMORY_SIZE}` | The appropriate size of memory to allocate for your container. | `4g` |

-| `{NUMBER_CPUS}` | The appropriate number of CPUs to allocate for your container. | `4` |

-| `{LICENSE_MOUNT}` | The path where the license will be located and mounted. | `/host/license:/path/to/license/directory` |

-| `{OUTPUT_PATH}` | The output path for logging [usage records](../containers/disconnected-containers.md#usage-records). | `/host/output:/path/to/output/directory` |

-| `{MODEL_PATH}` | The path where the model is located. | `/path/to/model/` |

-| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

-| `{CONTAINER_OUTPUT_DIRECTORY}` | Location of the output folder on the container's local filesystem. | `/path/to/output/directory` |

-```bash

-docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-{IMAGE} \

-eula=accept \

-Mounts:License={CONTAINER_LICENSE_DIRECTORY}

-Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

-```

-The [Custom Speech-to-Text](../speech-service/speech-container-howto.md?tabs=cstt) container provides a default directory for writing the license file and billing log at runtime. The default directories are /license and /output respectively.

-When you're mounting these directories to the container with the `docker run -v` command, make sure the local machine directory is set ownership to `user:group nonroot:nonroot` before running the container.

-Below is a sample command to set file/directory ownership.

-```bash

-sudo chown -R nonroot:nonroot <YOUR_LOCAL_MACHINE_PATH_1> <YOUR_LOCAL_MACHINE_PATH_2> ...

-```

-# [Neural text-to-speech](#tab/ntts)

-To run the neural text-to-speech container, execute the following `docker run` command:

-ApiKey={API_KEY}

-This command:

-* Runs a neural text-to-speech container from the container image.

-* Allocates 6 CPU cores and 12 GB of memory.

-* Exposes TCP port 5000 and allocates a pseudo-TTY for the container.

-* Automatically removes the container after it exits. The container image is still available on the host computer.

-### Run the container disconnected from the internet

-The neural text-to-speech container provide a default directory for writing the license file and billing log at runtime. The default directories are /license and /output respectively.

-When you're mounting these directories to the container with the `docker run -v` command, make sure the local machine directory is set ownership to `user:group nonroot:nonroot` before running the container.

-Below is a sample command to set file/directory ownership.

-sudo chown -R nonroot:nonroot <YOUR_LOCAL_MACHINE_PATH_1> <YOUR_LOCAL_MACHINE_PATH_2> ...

-# [Speech language identification](#tab/lid)

-To run the Speech language identification container, execute the following `docker run` command:

-docker run --rm -it -p 5003:5003 --memory 1g --cpus 1 \

-mcr.microsoft.com/azure-cognitive-services/speechservices/language-detection \

-Eula=accept \

-This command:

-* Runs a Speech language-detection container from the container image. Currently, you won't be charged for running this image.

-* Allocates 1 CPU core and 1 GB of memory.

-* Exposes TCP port 5003 and allocates a pseudo-TTY for the container.

-* Automatically removes the container after it exits. The container image is still available on the host computer.

-If you want to run this container with the speech-to-text container, you can use this [docker image](https://hub.docker.com/r/antsu/on-prem-client). After both containers have been started, use this `docker run` command to execute `speech-to-text-with-languagedetection-client`:

-```Docker

-docker run --rm -v ${HOME}:/root -ti antsu/on-prem-client:latest ./speech-to-text-with-languagedetection-client ./audio/LanguageDetection_en-us.wav --host localhost --lport 5003 --sport 5000

-```

-Increasing the number of concurrent calls can affect reliability and latency. For language identification, we recommend a maximum of four concurrent calls using 1 CPU with 1 GB of memory. For hosts with 2 CPUs and 2 GB of memory, we recommend a maximum of six concurrent calls.

-***

-> [!IMPORTANT]

-> The `Eula`, `Billing`, and `ApiKey` options must be specified to run the container. Otherwise, the container won't start. For more information, see [Billing](#billing).

-## Query the container's prediction endpoint

-> [!NOTE]

-> Use a unique port number if you're running multiple containers.

-| Containers | SDK Host URL | Protocol |

-|--|--|--|

-| Standard speech-to-text and custom speech-to-text | `ws://localhost:5000` | WS |

-| Neural Text-to-speech, Speech language identification | `http://localhost:5000` | HTTP |

-For more information on using WSS and HTTPS protocols, see [Container security](../cognitive-services-container-support.md#azure-cognitive-services-container-security).

-### Speech-to-text (standard and custom)

-#### Analyze sentiment

-If you provided your Language service API credentials [to the container](#analyze-sentiment-on-the-speech-to-text-output), you can use the Speech SDK to send speech recognition requests with sentiment analysis. You can configure the API responses to use either a *simple* or *detailed* format.

-> [!NOTE]

-> v1.13 of the Speech Service Python SDK has an identified issue with sentiment analysis. Use v1.12.x or earlier if you're using sentiment analysis in the Speech Service Python SDK.

-# [Simple format](#tab/simple-format)

-To configure the Speech client to use a simple format, add `"Sentiment"` as a value for `Simple.Extensions`. If you want to choose a specific Language service model version, replace `'latest'` in the `speechcontext-phraseDetection.sentimentAnalysis.modelversion` property configuration.

-```python

-speech_config.set_service_property(

- name='speechcontext-PhraseOutput.Simple.Extensions',

- value='["Sentiment"]',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-speech_config.set_service_property(

- name='speechcontext-phraseDetection.sentimentAnalysis.modelversion',

- value='latest',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-```

-`Simple.Extensions` returns the sentiment result in the root layer of the response.

-```json

-{

- "DisplayText":"What's the weather like?",

- "Duration":13000000,

- "Id":"6098574b79434bd4849fee7e0a50f22e",

- "Offset":4700000,

- "RecognitionStatus":"Success",

- "Sentiment":{

- "Negative":0.03,

- "Neutral":0.79,

- "Positive":0.18

- }

-}

-```

-# [Detailed format](#tab/detailed-format)

-To configure the Speech client to use a detailed format, add `"Sentiment"` as a value for `Detailed.Extensions`, `Detailed.Options`, or both. If you want to choose a specific sentiment analysis model version, replace `'latest'` in the `speechcontext-phraseDetection.sentimentAnalysis.modelversion` property configuration.

-```python

-speech_config.set_service_property(

- name='speechcontext-PhraseOutput.Detailed.Options',

- value='["Sentiment"]',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-speech_config.set_service_property(

- name='speechcontext-PhraseOutput.Detailed.Extensions',

- value='["Sentiment"]',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-speech_config.set_service_property(

- name='speechcontext-phraseDetection.sentimentAnalysis.modelversion',

- value='latest',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-```

-`Detailed.Extensions` provides the sentiment result in the root layer of the response. `Detailed.Options` provides the result in the `NBest` layer of the response. They can be used separately or together.

-```json

-{

- "DisplayText":"What's the weather like?",

- "Duration":13000000,

- "Id":"6a2aac009b9743d8a47794f3e81f7963",

- "NBest":[

- {

- "Confidence":0.973695,

- "Display":"What's the weather like?",

- "ITN":"what's the weather like",

- "Lexical":"what's the weather like",

- "MaskedITN":"What's the weather like",

- "Sentiment":{

- "Negative":0.03,

- "Neutral":0.79,

- "Positive":0.18

- }

- },

- {

- "Confidence":0.9164971,

- "Display":"What is the weather like?",

- "ITN":"what is the weather like",

- "Lexical":"what is the weather like",

- "MaskedITN":"What is the weather like",

- "Sentiment":{

- "Negative":0.02,

- "Neutral":0.88,

- "Positive":0.1

- }

- }

- ],

- "Offset":4700000,

- "RecognitionStatus":"Success",

- "Sentiment":{

- "Negative":0.03,

- "Neutral":0.79,

- "Positive":0.18

- }

-}

-```

-If you want to completely disable sentiment analysis, add a `false` value to `sentimentanalysis.enabled`.

-```python

-speech_config.set_service_property(

- name='speechcontext-phraseDetection.sentimentanalysis.enabled',

- value='false',

- channel=speechsdk.ServicePropertyChannel.UriQueryParameter

-)

-```

-### Neural Text-to-Speech

-### Run multiple containers on the same host

-If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. For example, run the first container on port 5000 and the second container on port 5001.

-You can have this container and a different Cognitive Services container running on the HOST together. You also can have multiple containers of the same Cognitive Services container running.

-## Stop the container

-## Troubleshooting

-When you start or run the container, you might experience issues. Use an output [mount](speech-container-configuration.md#mount-settings) and enable logging. Doing so allows the container to generate log files that are helpful when you troubleshoot issues.

-## Billing

-The Speech containers send billing information to Azure by using a Speech resource on your Azure account.

-For more information about these options, see [Configure containers](speech-container-configuration.md).

-## Summary

-In this article, you learned concepts and workflow for how to download, install, and run Speech containers. In summary:

-* Speech provides four Linux containers for Docker that have various capabilities:

- * Speech-to-text

- * Custom speech-to-text

- * Neural text-to-speech

- * Speech language identification

-* Container images are downloaded from the container registry in Azure.

-* Container images run in Docker.

-* Whether you use the REST API (text-to-speech only) or the SDK (speech-to-text or text-to-speech), you specify the host URI of the container.

-* You're required to provide billing information when you instantiate a container.

-> [!IMPORTANT]

-> Cognitive Services containers aren't licensed to run without being connected to Azure for metering. Customers need to enable the containers to communicate billing information with the metering service at all times. Cognitive Services containers don't send customer data (for example, the image or text that's being analyzed) to Microsoft.

-* Use more [Cognitive Services containers](../cognitive-services-container-support.md).

-| File size | 3,000 characters per file | 20,000 characters per file |

-## Content limits

-This table lists the limits for data that you send to Document Translation:

-|Attribute | Limit|

-|||

-|Document size| Γëñ 40 MB |

-|Total number of files.|Γëñ 1000 |

-|Total content size in a batch | Γëñ 250 MB|

-|Number of target languages in a batch| Γëñ 10 |

-|Size of Translation memory file| Γëñ 10 MB|

-Document Translation can't be used to translate secured documents such as those with an encrypted password or with restricted access to copy content.

-## Troubleshooting

->

->

-> For more information on input requirements, *see* [content limits](get-started-with-document-translation.md#content-limits)

-description: This article lists request limits for the Translator. Charges are incurred based on character count, not request frequency with a limit of 50,000 characters per request. Character limits are subscription-based, with F0 limited to 2 million characters per hour.

-# Request limits for Translator

-This article provides throttling limits for the Translator translation, transliteration, sentence length detection, language detection, and alternate translations.

-## Character and array limits per request

-Each translate request is limited to 50,000 characters, across all the target languages you're translating to. For example, sending a translate request of 3,000 characters to translate to three different languages results in a request size of 3000x3 = 9,000 characters, which satisfy the request limit. You're charged per character, not by the number of requests. It's recommended to send shorter requests.

-The following table lists array element and character limits for each operation of the Translator.

-| Translate | 50,000| 1,000| 50,000 |

-| Transliterate | 5,000| 10| 5,000 |

-| Detect | 50,000 |100 |50,000 |

-| BreakSentence | 50,000| 100 |50,000 |

-| Dictionary Lookup| 100 |10| 1,000 |

-| Dictionary Examples | 100 for text and 100 for translation (200 total)| 10|2,000 |

-## Character limits per hour

-## Latency

-The Translator has a maximum latency of 15 seconds using standard models and 120 seconds when using custom models. Typically, responses *for text within 100 characters* are returned in 150 milliseconds to 300 milliseconds. The custom translator models have similar latency characteristics on sustained request rate and may have a higher latency when your request rate is intermittent. Response times will vary based on the size of the request and language pair. If you don't receive a translation or an [error response](./reference/v3-0-reference.md#errors) within that timeframe, check your code, your network connection, and retry.

-* A repeated translation, even if you've previously translated the same text. Every character submitted to the translate function is counted even when the content is unchanged or the source and target language are the same.

-2. In the left rail, make your selection under **Cost Management**:

-Attribution isn't required when using Translator for text and speech translation. It is recommended that you inform users that the content they're viewing is machine translated.

-Translator Service is a cloud-based neural machine translation service that is part of the [Azure Cognitive Services](../what-are-cognitive-services.md) family of REST APIs and can be used with any operating system. Translator powers many Microsoft products and services used by thousands of businesses worldwide to perform language translation and other language-related operations. In this overview, you'll learn how Translator can enable you to build intelligent, multi-language solutions for your applications across all [supported languages](./language-support.md).

-The following features are supported by the Translator service. Use the links in this table to learn more about each feature and browse the API references.

-First, you'll need a Microsoft account; if you don't have one, you can sign up for free at the [**Microsoft account portal**](https://account.microsoft.com/account). Select **Create a Microsoft account** and follow the steps to create and verify your new account.

-Next, you'll need to have an Azure accountΓÇönavigate to the [**Azure sign-up page**](https://azure.microsoft.com/free/ai/), select the **Start free** button, and create a new Azure account using your Microsoft account credentials.

-| [Speech Service API][sp-containers-stt] | **Speech-to-text** ([image](https://hub.docker.com/_/microsoft-azure-cognitive-services-speechservices-custom-speech-to-text)) | Transcribes continuous real-time speech into text. | Generally available. <br> This container can also [run in disconnected environments](containers/disconnected-containers.md). |

-[sp-containers-lid]: speech-service/speech-container-howto.md?tabs=lid

-[sp-containers-stt]: speech-service/speech-container-howto.md?tabs=stt

-[sp-containers-cstt]: speech-service/speech-container-howto.md?tabs=cstt

-[sp-containers-tts]: speech-service/speech-container-howto.md?tabs=tts

-[sp-containers-ctts]: speech-service/speech-container-howto.md?tabs=ctts

-[sp-containers-ntts]: speech-service/speech-container-howto.md?tabs=ntts

-# SME: Siddhartha Prasad <siprasa@microsoft.com>

- * [Speech-to-Text](../speech-service/speech-container-howto.md?tabs=stt#run-the-container-disconnected-from-the-internet)

- * [Custom Speech-to-Text](../speech-service/speech-container-howto.md?tabs=cstt#run-the-container-disconnected-from-the-internet-1)

- * [Neural Text-to-Speech](../speech-service/speech-container-howto.md?tabs=ntts#run-the-container-disconnected-from-the-internet-2)

-| ada | N/A | East US ² | 2,049 | Oct 2019|

-| babbage | N/A | East US² | 2,049 | Oct 2019 |

-| curie | N/A | East US² | 2,049 | Oct 2019 |

-<br>² South Central US and West Europe were previously available, but due to high demand they are currently unavailable for new customers to use for fine-tuning. Please use the East US region for fine-tuning.

-| Requests per minute per model* | Davinci-models (002 and later): 120 <br> ChatGPT model (preview): 300 <br> GPT-4 models (preview): 12 <br> All other models: 300 |

-zone_pivot_groups: acs-azcli-js-csharp-java-python-power-platform

-## Architecture overview

-``` html

- <!DOCTYPE html>

- <html>

- <head>

- <meta charset="utf-8">

- <title>Call Widget App - Vanilla</title>

- <link rel="stylesheet" href="style.css">

- </head>

- <body>

- <div id="call-widget">

- <div id="call-widget-header">

- <div id="call-widget-header-title">Call Widget App</div>

- <button class='widget'> ? </button >

- <div class='callWidget'></div>

- </div>

- </body>

- </html>

-```

-``` css

- .widget {

- height: 75px;

- width: 75px;

- position: absolute;

- right: 0;

- bottom: 0;

- background-color: blue;

- margin-bottom: 35px;

- margin-right: 35px;

- border-radius: 50%;

- text-align: center;

- vertical-align: middle;

- line-height: 75px;

- color: white;

- font-size: 30px;

- }

-

- .callWidget {

- height: 400px;

- width: 600px;

- background-color: blue;

- position: absolute;

- right: 35px;

- bottom: 120px;

- z-index: 10;

- display: none;

- border-radius: 5px;

- border-style: solid;

- border-width: 5px;

- }

-```

-1. Configure the call window to be hidden by default. We show it when the user clicks the button.

-``` html

- <script>

- var open = false;

- const button = document.querySelector('.widget');

- const content = document.querySelector('.callWidget');

- button.addEventListener('click', async function() {

- if(!open){

- open = !open;

- content.style.display = 'block';

- button.innerHTML = 'X';

- //Add code to initialize call widget here

- } else if (open) {

- open = !open;

- content.style.display = 'none';

- button.innerHTML = '?';

- });

-

- async function getAccessToken(){

- //Add code to get access token here

- }

- </script>

-```

-``` html

- <script src="https://github.com/ddematheu2/ACS-UI-Library-Widget/releases/download/widget/callComposite.js"></script>

-```

-1. Add the following code under the button event listener:

-``` javascript

- button.addEventListener('click', async function() {

- if(!open){

- open = !open;

- content.style.display = 'block';

- button.innerHTML = 'X';

- let response = await getChatContext();

- console.log(response);

- const callAdapter = await callComposite.loadCallComposite(

- {

- displayName: "Test User",

- locator: { participantIds: ['INSERT USER UNIQUE IDENTIFIER FROM MICROSOFT GRAPH']},

- userId: response.user,

- token: response.userToken

- },

- content,

- {

- formFactor: 'mobile',

- key: new Date()

- }

- );

- } else if (open) {

- open = !open;

- content.style.display = 'none';

- button.innerHTML = '?';

- }

- });

-```

-You must ensure you've got two or more numbers that you own which are globally routable. Your onboarding team needs these numbers to configure test lines.

-Collect all of the values in the following table for all test lines you want to configure for Azure Communications Gateway. You must configure at least one test line.

- |The phone number of the test line. |**Phone Number**|

- |Whether the test line is manual or automated: **Manual** test lines will be used by you and Microsoft staff to make test calls during integration testing. **Automated** test lines will be assigned to Microsoft Teams test suites for validation testing. |**Testing purpose**|

- --name 'myqueue" \

- "defaultValue": "",

- "defaultValue": "",

- "type": "String"

-resource acrResource 'Microsoft.ContainerRegistry/registries@2021-06-01-preview' = {

-Change data capture (CDC) in [Azure Cosmos DB analytical store](analytical-store-introduction.md) allows you to efficiently consume a continuous and incremental feed of changed (inserted, updated, and deleted) data from analytical store. The change data capture feature of the analytical store is seamlessly integrated with Azure Synapse and Azure Data Factory, providing you with a scalable no-code experience for high data volume. As the change data capture feature is based on analytical store, it [doesn't consume provisioned RUs, doesn't affect your transactional workloads](analytical-store-introduction.md#decoupled-performance-for-analytical-workloads), provides lower latency, and has lower TCO.

-> [!IMPORTANT]

-> This feature is currently in preview.

-description: Learn about Azure Cosmos DB transactional (row-based) and analytical(column-based) store. Benefits of analytical store, performance impact for large-scale workloads, and auto sync of data from transactional store to analytical store

-Traditionally, to analyze large amounts of data, operational data is extracted from Azure Cosmos DB's transactional store and stored in a separate data layer. For example, the data is stored in a data warehouse or data lake in a suitable format. This data is later used for large-scale analytics and analyzed using compute engine such as the Apache Spark clusters. This separation of analytical storage and compute layers from operational data results in additional latency, because the ETL(Extract, Transform, Load) pipelines are run less frequently to minimize the potential impact on your transactional workloads.

-Auto-Sync refers to the fully managed capability of Azure Cosmos DB where the inserts, updates, deletes to operational data are automatically synced from transactional store to analytical store in near real time. Auto-sync latency is usually within 2 minutes. In cases of shared throughput database with a large number of containers, auto-sync latency of individual containers could be higher and take up to 5 minutes. We would like to learn more how this latency fits your scenarios. For that, please reach out to the [Azure Cosmos DB Team](mailto:cosmosdbsynapselink@microsoft.com).

- * If your document's first level has 2000 properties, only the first 1000 will be represented.

- * If your documents have five levels with 200 properties in each one, all properties will be represented.

- * If your documents have 10 levels with 400 properties in each one, only the two first levels will be fully represented in analytical store. Half of the third level will also be represented.

- * Spark pools in Azure Synapse will represent these columns as `string`.

- * SQL serverless pools in Azure Synapse will represent these columns as `varchar(8000)`.

-* SQL serverless pools in Azure Synapse support result sets with up to 1000 columns, and exposing nested columns also counts towards that limit. Please consider this information when designing your data architecture and modeling your transactional data.

-There are two types of schema representation in the analytical store. These types define the schema representation method for all containers in the database account and have tradeoffs between the simplicity of query experience versus the convenience of a more inclusive columnar representation for polymorphic schemas.

- * From `float` to `integer`. All documents will be represented in analytical store.

- * From `integer` to `float`. All documents will be represented in analytical store. However, to read this data with Azure Synapse SQL serverless pools, you must use a WITH clause to convert the column to `varchar`. And after this initial conversion, it's possible to convert it again to a number. Please check the example below, where **num** initial value was an integer and the second one was a float.

- * Spark pools in Azure Synapse will represent these values as `undefined`.

- * SQL serverless pools in Azure Synapse will represent these values as `NULL`.

- * Spark pools in Azure Synapse will read these values as `0` (zero). And it will change to `undefined` as soon as the column has a non-null value.

- * SQL serverless pools in Azure Synapse will read these values as `NULL`.

- * Spark pools in Azure Synapse will represent these columns as `undefined`.

- * SQL serverless pools in Azure Synapse will represent these columns as `NULL`.

- * To abandon the property with the wrong schema and add a new one, with another name, that has the correct schema in all documents. Example: You have billions of documents in the **Orders** container where the **status** property is a string. But the first document in that container has **status** defined with integer. So, one document will have **status** correctly represented and all other documents will have `NULL`. You can add the **status2** property to all documents and start to use it, instead of the original property.

-```Python

-import org.apache.spark.sql.types._

-val simpleSchema = StructType(Array(

-    StructField("_id", StructType(Array(StructField("objectId",BinaryType,true)) ),true),

-    StructField("id", StringType, true)

-  ))

-df = spark.read.format("cosmos.olap")\

- .option("spark.synapse.linkedService", "<enter linked service name>")\

- .option("spark.cosmos.container", "<enter container name>")\

- .schema(simpleSchema)

- .load()

-df.select("id", "_id.objectId").show()

-```

-> [!NOTE]

-> This workaround was designed to work with Spark 2.4.

-* Currently Azure Cosmso DB for MongoDB isn't compatible with this possibility of changing the schema representation. All MongoDB accounts will always have full fidelity schema representation type.

-* Currently, containers schema in analytical store are defined when the container is created, even if Synapse Link has not been enabled in the database account.

- * By default, Azure Cosmos DB database accounts allocate analytical store in Locally Redundant Storage (LRS) accounts.

- * If any geo-region of the database account is configured for zone-redundancy, it is allocated in Zone-redundant Storage (ZRS) accounts. Customers need to enable Availability Zones on a region of their Azure Cosmos DB database account to have analytical data of that region stored in ZRS.

-### Backup Polices

-## Global Distribution

-While the above estimate is for scanning 1TB of data in analytical store, applying filters reduces the volume of data scanned and this determines the exact number of analytical read operations given the consumption pricing model. A proof-of-concept around the analytical workload would provide a more finer estimate of analytical read operations. This estimate doesn't include the cost of Azure Synapse Analytics.

-* Azure Cosmos DB APIs for SQL and MongoDB are supported for continuous backup. API for Cassandra isn't supported now.

-# Get started with change data capture in the analytical store for Azure Cosmos DB

-1. Enable Azure Synapse Link: [Enable Azure Synapse Link for an Azure Cosmos DB account](configure-synapse-link.md#enable-synapse-link) |

-1. Enable analytical store for your container\[s\]:

-Up to 2 TiB of storage is supported on coordinator and worker nodes. See the

-available storage options and IOPS calculation [above](resources-compute.md)

-for node and cluster sizes.

-The following cmdlet is an example to trigger a restore operation with the restore command by using the target account, source account, location, resource group, and timestamp:

-Recommendations are refreshed several times a day. However, it may take up to five days for the newly purchased savings plans and reservations to begin to be reflected in recommendations.

-If you're trading multiple reservations, the aggregate outstanding commitment is used. You may choose to increase the value, but you can't decrease it. The new savings plan will be used to cover usage of eligible resources.

- > For Azure-SSIS in Azure Synapse, use corresponding Azure Synapse REST API to [Get Integration Runtime status](/rest/api/synapse/integration-runtimes/get), [Start Integration Runtime](/rest/api/synapse/integration-runtimes/start) and [Stop Integration Runtime](/rest/api/synapse/integration-runtimes/stop).

->:::image type="content" source="./media/sensor-data-flow-new.png" alt-text="Screenshot showing sensor data flow.":::

->:::image type="content" source="./media/sensor-topology-new.png" alt-text="Screenshot showing sensor topology.":::

->:::image type="content" source="./media/solution-framework-isv-1.png" alt-text="Screenshot showing ISV solution framework.":::

->:::image type="content" source="./media/3p-solutions-new.png" alt-text="Screenshot showing access flow for ISV API.":::

- >:::image type="content" source="./media/sensor-partners.png" alt-text="Screenshot showing the partners message.":::

->:::image type="content" source="./media/role-assignment-1.png" alt-text="Screenshot showing role assignment.":::

->:::image type="content" source="./media/sensor-partner-role.png" alt-text="Screenshot showing app selection for authorization.":::

->:::image type="content" source="./media/sensor-partners-flow.png" alt-text="Screenshot showing sensor partners flow.":::

->:::image type="content" source="./media/schema-1.png" alt-text="Screenshot showing entity relationships.":::

->:::image type="content" source="./media/about-data-manager.png" alt-text="Screenshot showing key features.":::

-> [Investigate security recommendations](tutorial-investigate-security-recommendations.md)

-For more information, see [Certificates for appliance encryption and authentication (OT appliances)](how-to-deploy-certificates.md).

-|**Samsung** | Samsung TV |

-|**GE** | Bentley Nevada (System 1 / BN3500)<br> EGD<br> GSM (GE MarkVI and MarkVIe)<br> SRTP (GE)<br> GE_CMP |

-|**Rockwell Automation** | ENIP<br> EtherNet/IP CIP (including Rockwell extension)<br> EtherNet/IP CIP FW version 27 and above |

-|**Siemens** | CAMP<br> PCS7<br> PCS7 WinCC ΓÇô Historian<br> Profinet DCP<br> Profinet Realtime<br> Siemens PHD<br> Siemens S7<br> Siemens S7-Plus<br> Siemens SICAM<br> Siemens WinCC |

-Horizon helps you to write plugins for OT sensors that enable Deep Packet Inspection (DPI) on the traffic and detect threats in realtime. Customize your plugins localize and customize text for alerts, events, and protocol parameters.

-If an OT network sensor has already learned the device, running the script outlined in this article retrieves the device's information and enrichment data.

-## Run the script

-This procedure describes how to obtain, deploy, and run the script on the Windows workstation and servers that you want to monitor in Defender for IoT.

-The script you run to detect enriched Windows data is run as a utility and not as an installed program. Running the script doesn't affect the endpoint.

-1. To acquire the script, [contact customer support](mailto:support.microsoft.com).

-1. Deploy the script once, or using ongoing automation, using standard automated deployment methods and tools.

- After the script runs to probe the registry, a CX-snapshot file appears with the registry information. The filename indicates the system name, date, and time of the snapshot with the following syntax: `CX-snaphot_SystemName_Month_Year_Time`

-Files generated by the script:

-After having run the script as described [earlier](#run-the-script), import the generated data to your sensor to view the device details in the **Device inventory**.

-1. Select **Close**. The device registry information is imported and a successful confirmation message is shown.

- If there's a problem uploading one of the files, you'll be informed which file upload failed.

-For more information, see [Activate and set up your sensor](how-to-activate-and-set-up-your-sensor.md), [Getting started with advanced CLI commands](references-work-with-defender-for-iot-cli-commands.md), and [CLI command reference from OT network sensors](cli-ot-sensor.md).

- If you want to use on-premises sensors, make sure that you have the [hardware appliances](ot-appliance-sizing.md) for those sensors and any administrative user permissions.

-description: Activating the management console ensures that sensors are registered with Azure and sending information to the on-premises management console, and that the on-premises management console carries out management tasks on connected sensors.

-# Activate and set up your on-premises management console

-Activation and setup of the on-premises management console ensures that:

-## Sign in for the first time

-To sign in to the on-premises management console:

-1. Go to the IP address you received for the on-premises management console during the system installation.

-1. Enter the username and password you received for the on-premises management console during the system installation.

-If you forgot your password, select the **Recover Password** option.

-## Activate the on-premises management console

-After you sign in for the first time, you need to activate the on-premises management console by getting and uploading an activation file. Activation files on the on-premises management console enforce the number of committed devices configured for your subscription and Defender for IoT plan. For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md).

-**To activate the on-premises management console**:

-1. Sign in to the on-premises management console.

-1. In the alert notification at the top of the screen, select **Take Action**.

- :::image type="content" source="media/how-to-manage-sensors-from-the-on-premises-management-console/take-action.png" alt-text="Screenshot that shows the Take Action link in the alert at the top of the screen.":::

-1. In the **Activation** pop-up screen, select **Azure portal**.

- :::image type="content" source="media/how-to-manage-sensors-from-the-on-premises-management-console/azure-portal.png" alt-text="Screenshot that shows the Azure portal link in the pop-up message.":::

-

-1. Select a subscription to associate the on-premises management console to. Then select **Download on-premises management console activation file**. The activation file downloads.

- The on-premises management console can be associated to one or more subscriptions. The activation file is associated with all the selected subscriptions and the number of committed devices at the time of download.

- [!INCLUDE [root-of-trust](includes/root-of-trust.md)]

- :::image type="content" source="media/how-to-manage-sensors-from-the-on-premises-management-console/multiple-subscriptions.png" alt-text="Screenshot that shows selecting multiple subscriptions." lightbox="media/how-to-manage-sensors-from-the-on-premises-management-console/multiple-subscriptions.png":::

- If you haven't already onboarded Defender for IoT to a subscription, see [Onboard a Defender for IoT plan for OT networks](how-to-manage-subscriptions.md#onboard-a-defender-for-iot-plan-for-ot-networks).

- > [!Note]

- > If you delete a subscription, you must upload a new activation file to the on-premises management console that was affiliated with the deleted subscription.

-1. Go back to the **Activation** pop-up screen and select **CHOOSE FILE**.

-1. Select the downloaded file.

-After initial activation, the number of monitored devices might exceed the number of committed devices defined during onboarding. This issue occurs if you connect more sensors to the management console. If there's a discrepancy between the number of monitored devices and the number of committed devices, a warning appears on the management console.

-If this warning appears, you need to upload a [new activation file](#activate-the-on-premises-management-console).

-### Activation expirations

-After activating an on-premises management console, you'll need to apply new activation files on both the on-premises management console and connected sensors as follows:

-|Location |Activation process |

-|||

-|**On-premises management console** | Apply a new activation file on your on-premises management console if you've [modified the number of committed devices](how-to-manage-subscriptions.md#edit-a-plan-for-ot-networks) in your subscription. |

-|**Cloud-connected and locally managed sensors** | Cloud-connected and locally managed sensors remain activated for as long as your Azure subscription with your Defender for IoT plan is active. <br><br>If you're updating an OT sensor from a legacy version, you'll need to re-activate your updated sensor. |

-For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md).

-### Activate expired licenses from versions earlier than 10.0

-For users with versions prior to 10.0, your license might expire and the following alert will appear:

-**To activate your license**:

-1. Open a case with [support](https://portal.azure.com/?passwordRecovery=true&Microsoft_Azure_IoT_Defender=canary#create/Microsoft.Support).

-1. Supply support with your **Activation ID** number.

-1. Support will supply you with new license information in the form of a string of letters.

-1. Read the terms and conditions, and select the checkbox to approve.

-1. Paste the string into the space provided.

- :::image type="content" source="media/how-to-activate-and-set-up-your-on-premises-management-console/add-license.png" alt-text="Screenshot that shows pasting the string into the box.":::

-1. Select **Activate**.

-## Set up a certificate

-After you install the management console, a local self-signed certificate is generated. This certificate is used to access the console. After an administrator signs in to the management console for the first time, that user is prompted to onboard an SSL/TLS certificate.

-Two levels of security are available:

-The console supports the following types of certificates:

- > [!IMPORTANT]

- > We recommend that you don't use a self-signed certificate. The certificate isn't secure and should be used for test environments only. The owner of the certificate can't be validated, and the security of your system can't be maintained. Never use this option for production networks.

-To upload a certificate:

-1. When you're prompted after you sign in, define a certificate name.

-1. Upload the CRT and key files.

-1. Enter a passphrase and upload a PEM file if necessary.

-You might need to refresh your screen after you upload the CA-signed certificate.

-To disable validation between the management console and connected sensors:

-1. Select **Next**.

-1. Turn off the **Enable system-wide validation** toggle.

-For information about uploading a new certificate, supported certificate files, and related items, see [Manage the on-premises management console](how-to-manage-the-on-premises-management-console.md).

-## Connect sensors to the on-premises management console

-Ensure that sensors send information to the on-premises management console. Make sure that the on-premises management console can perform backups, manage alerts, and carry out other activity on the sensors. Use the following procedures to verify that you make an initial connection between sensors and the on-premises management console.

-Two options are available for connecting Microsoft Defender for IoT sensors to the on-premises management console:

-After connecting, set up sites and zones and assign each sensor to a zone to [monitor detected data segmented separately](monitor-zero-trust.md).

-For more information, see [Create OT sites and zones on an on-premises management console](ot-deploy/sites-and-zones-on-premises.md).

-### Connect sensors to the on-premises management console from the sensor console

-**To connect sensors to the on-premises management console from the sensor console**:

-1. In the on-premises management console, select **System Settings**.

-1. Copy the string in the **Copy Connection String** box.

- :::image type="content" source="media/how-to-manage-sensors-from-the-on-premises-management-console/connection-string.png" alt-text="Screenshot that shows copying the connection string for the sensor.":::

-1. On the sensor, go to **System Settings** > **Connection to Management Console**.

-1. Paste the copied connection string from the on-premises management console into the **Connection string** box.

- :::image type="content" source="media/how-to-manage-sensors-from-the-on-premises-management-console/paste-connection-string.png" alt-text="Screenshot that shows pasting the copied connection string into the Connection string box.":::

-1. Select **Connect**.

-### Connect sensors by using tunneling

-Enhance system security by preventing direct user access to the sensor. Instead of direct access, use proxy tunneling to let users access the sensor from the on-premises management console with a single firewall rule. This technique narrows the possibility of unauthorized access to the network environment beyond the sensor. The user's experience when signing in to the sensor remains the same.

-Using tunneling allows you to connect to the on-premises management console from its IP address and a single port (9000 by default) to any sensor.

-For example, the following image shows a sample architecture where users access the sensor consoles via the on-premises management console.

-**To set up tunneling at the on-premises management console**:

-1. Sign in to the on-premises management console's CLI with the *cyberx* or the *support* user credentials and run the following command:

- ```bash

- sudo cyberx-management-tunnel-enable

-

- ```

- For more information on users, see [Default privileged on-premises users](roles-on-premises.md#default-privileged-on-premises-users).

-1. Allow a few minutes for the connection to start.

-

- When tunneling access is configured, the following URL syntax is used to access the sensor consoles: `https://<on-premises management console address>/<sensor address>/<page URL>`

-You can also customize the port range to a number other than 9000. An example is 10000.

-**To use a new port**:

-Sign in to the on-premises management console and run the following command:

-```bash

-sudo cyberx-management-tunnel-enable --port 10000

-

-```

-**To disable the connection**:

-Sign in to the on-premises management console and run the following command:

-```bash

-cyberx-management-tunnel-disable

-

-```

-No configuration is needed on the sensor.

-**To access the tunneling log files**:

-1. **From the on-premises management console**: Sign in and go to */var/log/apache2.log*.

-1. **From the sensor**: Sign in and go to */var/cyberx/logs/tunnel.log*.

-## Next steps

-For more information, see:

-description: This article describes how to sign in and activate a sensor console.

-# Activate and set up your sensor

-This article describes how to activate a sensor and perform initial setup.

-Administrator users carry out activation when signing in for the first time and when activation management is required. Setup ensures that the sensor is configured to optimally detect and alert.

-Security analysts and read-only users can't activate a sensor or generate a new password.

-## Sign in and activation for administrator users

-Administrators who sign in for the first time should verify that they have access to the activation and password recovery files for this sensor. These files were downloaded during sensor onboarding. If Administrators don't have these files, they can generate new ones via Defender for IoT in the Azure portal. The following Azure permissions are needed to generate the files:

-### First-time sign in and activation checklist

-Before administrators sign in to the sensor console, administrator users should have access to:

-### About activation files

-Your sensor was onboarded to Microsoft Defender for IoT in a specific management mode:

-| Mode type | Description |

-|--|--|

-| **Cloud connected mode** | Information that the sensor detects is displayed in the sensor console. Alert information is also delivered to Azure and can be shared with other Azure services, such as Microsoft Sentinel. You can also enable automatic threat intelligence updates. |

-| **Locally connected mode** | Information that the sensor detects is displayed in the sensor console. Detection information is also shared with the on-premises management console, if the sensor is connected to it. |

-A locally connected, or cloud-connected activation file was generated and downloaded for this sensor during onboarding. The activation file contains instructions for the management mode of the sensor. *A unique activation file should be uploaded to each sensor you deploy.* The first time you sign in, you need to upload the relevant activation file for this sensor.

-### About certificates

-Following sensor installation, a local self-signed certificate is generated. The certificate is used to access the sensor console. After administrators sign in to the console for the first time, they're prompted to onboard an SSL/TLS certificate.

-Two levels of security are available:

-The console supports the following certificate types:

- > [!IMPORTANT]

- > We recommend that you don't use the default self-signed certificate. The certificate is not secure and should be used for test environments only. The owner of the certificate can't be validated, and the security of your system can't be maintained. Never use this option for production networks.

-### Sign in and activate the sensor

-**To sign in and activate:**

-1. Go to the sensor console from your browser by using the IP defined during the installation. The sign-in dialog box opens.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/sensor-log-in-1.png" alt-text="Screenshot of a Defender for IoT sensor sign-in page.":::

-1. Enter the credentials defined during the sensor installation, or select the **Password recovery** option. If you purchased a preconfigured sensor from Arrow, generate a password first. For more information on password recovery, see [Investigate password failure at initial sign-in](how-to-troubleshoot-the-sensor-and-on-premises-management-console.md#investigate-password-failure-at-initial-sign-in).

-1. Select **Login/Next**. The **Sensor Network Settings** tab opens.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/sensor-log-in-wizard-activate.png" alt-text="Screenshot of the sensor network settings options when signing into the sensor.":::

-1. Use this tab if you want to change the sensor network configuration before activation. The configuration parameters were defined during the software installation, or when you purchased a preconfigured sensor. The following parameters were defined:

- - IP address

- - DNS

- - Default gateway

- - Subnet mask

- - Host name

- You might want to update this information before activating the sensor. For example, you might need to change the preconfigured parameters defined by Arrow. You can also define proxy settings before activating your sensor.

-

- If you want to work with a proxy, enable the proxy toggle and add the proxy host, port and username.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/sensor-log-in-wizard-activate-proxy.png" alt-text="Screenshot of the proxy options for signing in to a sensor.":::

-1. Select **Next.** The Activation tab opens.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/wizard-upload-activation-file.png" alt-text="Screenshot of a first time activation file upload option.":::

-1. Select **Upload** and go to the activation file that you downloaded during the sensor onboarding.

-1. Approve the terms and conditions.

-1. Select **Activate**. The SSL/TLS certificate tab opens. Before defining certificates, see [Deploy SSL/TLS certificates on OT appliances](how-to-deploy-certificates.md).

- It is **not recommended** to use a locally generated certificate in a production environment.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/wizard-upload-activation-certificates-1.png" alt-text="Screenshot of the SSL/TLS Certificates page when signing in to a sensor.":::

-1. Enable the **Import trusted CA certificate (recommended)** toggle.

-1. Define a certificate name.

-1. Upload the Key, CRT, and PEM files.

-1. Enter a passphrase and upload a PEM file if necessary.

-1. It's recommended to select **Enable certificate validation** to validate the connections between management console and connected sensors.

-1. Select **Finish**.

-You might need to refresh your screen after uploading the CA-signed certificate.

-For information about uploading a new certificate, supported certificate parameters, and working with CLI certificate commands, see [Manage individual sensors](how-to-manage-individual-sensors.md).

-### Activation expirations

-After you've activated your sensor, cloud-connected and locally managed sensors remain activated for as long as your Azure subscription with your Defender for IoT plan is active.

-If you're updating an OT sensor from a legacy version, you'll need to re-activate your updated sensor.

-For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md) and [Manage the on-premises management console](how-to-manage-the-on-premises-management-console.md).

-### Activate an expired license (versions under 10.0)

-For users with versions prior to 10.0, your license may expire, and the following alert will be displayed.

- :::image type="content" source="media/how-to-activate-and-set-up-your-on-premises-management-console/activation-popup.png" alt-text="Screenshot of a license expiration popup message.":::

-**To activate your license:**

-1. Open a case with [support](https://portal.azure.com/?passwordRecovery=true&Microsoft_Azure_IoT_Defender=canary#create/Microsoft.Support).

-1. Supply support with your Activation ID number.

-1. Support will supply you with new license information in the form of a string of letters.

-1. Read the terms and conditions, and check the checkbox to approve.

-1. Paste the string into space provided.

- :::image type="content" source="media/how-to-activate-and-set-up-your-on-premises-management-console/add-license.png" alt-text="Screenshot of the license activation box and button.":::

-1. Select **Activate**.

-### Subsequent sign ins

-After first-time activation, the Microsoft Defender for IoT sensor console opens after sign-in without requiring an activation file or certificate definition. You only need your sign-in credentials.

-After your sign-in, the Microsoft Defender for IoT sensor console opens.

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/initial-dashboard.png" alt-text="Screenshot of the initial sensor console dashboard Overview page." lightbox="media/how-to-activate-and-set-up-your-sensor/initial-dashboard.png":::

-## Initial setup and learning (for administrators)

-After your first sign-in, the Microsoft Defender for IoT sensor starts to monitor your network automatically. Network devices will appear in the device map and device inventory sections. Microsoft Defender for IoT will begin to detect and alert you on all security and operational incidents that occur in your network. You can then create reports and queries based on the detected information.

-Initially this activity is carried out in the Learning mode, which instructs your sensor to learn your network's usual activity. For example, the sensor learns devices discovered in your network, protocols detected in the network, and file transfers that occur between specific devices. This activity becomes your network's baseline activity.

-### Review and update basic system settings

-Review the sensor's system settings to make sure the sensor is configured to optimally detect and alert.

-Define the sensor's system settings. For example:

-### Disable Learning mode

-After adjusting the system settings, you can let the sensor run in Learning mode until you feel that system detections accurately reflect your network activity.

-The learning mode should run for about 2 to 6 weeks, depending on your network size and complexity. After you disable Learning mode, any activity that differs from your baseline activity will trigger an alert.

-**To disable learning mode:**

-## First-time sign in for security analysts and read-only users

-Before you sign in, verify that you have:

-

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/sensor-log-in-1.png" alt-text="Screenshot of the sensor sign-in page after the initial setup.":::

-## Console tools: Overview

-You can access console tools from the side menu. Tools help you:

- :::image type="content" source="media/how-to-activate-and-set-up-your-sensor/main-page-side-bar.png" alt-text="Screenshot of the sensor console's main menu on the left.":::

-### Discover

-| Tools| Description |

-| --|--|

-| Overview | View a dashboard with high-level information about your sensor deployment, alerts, traffic, and more. |

-| Device map | View the network devices, device connections, Purdue levels, and device properties in a map. Various zooms, highlight, and filter options are available to help you gain the insight you need. For more information, see [Investigate devices on a device map](how-to-work-with-the-sensor-device-map.md) |

-| Device inventory | The Device inventory displays a list of device attributes that this sensor detects. Options are available to: <br /> - Sort, or filter the information according to the table fields, and see the filtered information displayed. <br /> - Export information to a CSV file. <br /> - Import Windows registry details. For more information, see [Detect Windows workstations and servers with a local script](detect-windows-endpoints-script.md).|

-| Alerts | Alerts are triggered when sensor engines detect changes or suspicious activity in network traffic that requires your attention. For more information, see [View and manage alerts on your OT sensor](how-to-view-alerts.md).|

-### Analyze

-| Tools| Description |

-|||

-| Event timeline | View a timeline with information about alerts, network events, and user operations. For more information, see [Track sensor activity](how-to-track-sensor-activity.md).|

-| Data mining | Generate comprehensive and granular information about your network's devices at various layers. For more information, see [Sensor data mining queries](how-to-create-data-mining-queries.md).|

-| Trends and Statistics | View trends and statistics about an extensive range of network traffic and activity. As a small example, display charts and graphs showing top traffic by port, connectivity drops by hours, S7 traffic by control function, number of devices per VLAN, SRTP errors by day, or Modbus traffic by function. For more information, see [Sensor trends and statistics reports](how-to-create-trends-and-statistics-reports.md).

-| Risk Assessment | Proactively address vulnerabilities, identify risks such as missing patches or unauthorized applications. Detect changes to device configurations, controller logic, and firmware. Prioritize fixes based on risk scoring and automated threat modeling. For more information, see [Risk assessment reporting](how-to-create-risk-assessment-reports.md#create-risk-assessment-reports).|

-| Attack Vector | Display a graphical representation of a vulnerability chain of exploitable devices. These vulnerabilities can give an attacker access to key network devices. The Attack Vector Simulator calculates attack vectors in real time and analyzes all attack vectors for a specific target. For more information, see [Attack vector reporting](how-to-create-attack-vector-reports.md#create-attack-vector-reports).|

-### Manage

-| Tools| Description |

-|||

-| System settings | Configure the system settings. For example, define DHCP settings, provide mail server details, or create port aliases. |

-| Custom alert rules | Use custom alert rules to more specifically pinpoint activity or traffic of interest to you. For more information, see [Create custom alert rules on an OT sensor](how-to-accelerate-alert-incident-response.md#create-custom-alert-rules-on-an-ot-sensor). |

-| Users | Define users and roles with various access levels. For more information, see [Create and manage users on an OT network sensor](manage-users-sensor.md). |

-| Forwarding | Forward alert information to partners that integrate with Defender for IoT, for example, Microsoft Sentinel, Splunk, ServiceNow. You can also send to email addresses, webhook servers, and more. <br /> See [Forward alert information](how-to-forward-alert-information-to-partners.md) for details. |

-**Support**

-| Tool| Description |

-|-||

-| Support | Contact [Microsoft Support](https://support.microsoft.com/) for help.|

-## Review system messages

-System messages provide general information about your sensor that may require your attention, for example if:

-

-**To review system messages:**

-1. Sign into the sensor

-1. Select the **System Messages** icon (Bell icon).

-## Next steps

-For more information, see:

-description: Learn how to deploy SSL/TLS certificates on Microsoft Defender for IoT OT network sensors and on-premises management consoles.

-# Deploy SSL/TLS certificates on OT appliances

-This article describes how to create and deploy SSL/TLS certificates on OT network sensors and on-premises management consoles. Defender for IoT uses SSL/TLS certificates to secure communication between the following system components:

-You can deploy SSL/TLS certificates during initial configuration as well as later on.

-Defender for IoT validates certificates against the certificate expiration date and against a passphrase, if one is defined. Validations against a Certificate Revocation List (CRL) and the certificate trust chain are available as well, though not mandatory. Invalid certificates can't be uploaded to OT sensors or on-premises management consoles, and will block encrypted communication between Defender for IoT components.

-Each certificate authority (CA)-signed certificate must have both a `.key` file and a `.crt` file, which are uploaded to OT network sensors and on-premises management consoles after the first sign-in. While some organizations may also require a `.pem` file, a `.pem` file isn't required for Defender for IoT.

-Make sure to create a unique certificate for each OT sensor, on-premises management console, and HA server, where each certificate meets required parameter criteria.

-## Prerequisites

-To perform the procedures described in this article, make sure that:

- For more information, see [On-premises users and roles for OT monitoring with Defender for IoT](roles-on-premises.md).

-## Deploy an SSL/TLS certificate

-Deploy your SSL/TLS certificate by importing it to your OT sensor or on-premises management console.

-Verify that your SSL/TLS certificate [meets the required parameters](#verify-certificate-file-parameter-requirements), and that you have [access to a CRL server](#verify-crl-server-access).

-### Deploy a certificate on an OT sensor

-1. Sign into your OT sensor and select **System settings** > **Basic** > **SSL/TLS certificate**.

-1. In the **SSL/TLS certificate** pane, select one of the following, and then follow the instructions in the relevant tab:

- - **Import a trusted CA certificate (recommended)**

- - **Use Locally generated self-signed certificate (Not recommended)**

- # [Trusted CA certificates](#tab/import-trusted-ca-certificate)

-

- 1. Enter the following parameters:

-

- | Parameter | Description |

- |||

- | **Certificate Name** | Enter your certificate name. |

- | **Passphrase** - *Optional* | Enter a passphrase. |

- | **Private Key (KEY file)** | Upload a Private Key (KEY file). |

- | **Certificate (CRT file)** | Upload a Certificate (CRT file). |

- | **Certificate Chain (PEM file)** - *Optional* | Upload a Certificate Chain (PEM file). |

-

- Select **Use CRL (Certificate Revocation List) to check certificate status** to validate the certificate against a [CRL server](#verify-crl-server-access). The certificate is checked once during the import process.

- For example:

- :::image type="content" source="media/how-to-deploy-certificates/recommended-ssl.png" alt-text="Screenshot of importing a trusted CA certificate." lightbox="media/how-to-deploy-certificates/recommended-ssl.png":::

-

- # [Locally generated self-signed certificates](#tab/locally-generated-self-signed-certificate)

-

- > [!NOTE]

- > Using self-signed certificates in a production environment is not recommended, as it leads to a less secure environment.

- > We recommend using self-signed certificates in test environments only.

- > The owner of the certificate cannot be validated and the security of your system cannot be maintained.

- Select **Confirm** to acknowledge the warning.

-

-1. In the **Validation for on-premises management console certificates** area, select **Required** if SSL/TLS certificate validation is required. Otherwise, select **None**.

-1. Select **Save** to save your certificate settings.

-### Deploy a certificate on an on-premises management console

-1. Sign into your on-premises management console and select **System settings** > **SSL/TLS certificates**.

-1. In the **SSL/TLS certificate** pane, select one of the following, and then follow the instructions in the relevant tab:

- - **Import a trusted CA certificate**

- - **Use Locally generated self-signed certificate (Insecure, not recommended)**

- # [Trusted CA certificates](#tab/cm-import-trusted-ca-certificate)

-

- 1. In the **SSL/TLS Certificates** dialog, select **Add Certificate**.

- 1. Enter the following parameters:

-

- | Parameter | Description |

- |||

- | **Certificate Name** | Enter your certificate name. |

- | **Passphrase** - *Optional* | Enter a passphrase. |

- | **Private Key (KEY file)** | Upload a Private Key (KEY file). |

- | **Certificate (CRT file)** | Upload a Certificate (CRT file). |

- | **Certificate Chain (PEM file)** - *Optional* | Upload a Certificate Chain (PEM file). |

- For example:

- :::image type="content" source="media/how-to-deploy-certificates/management-ssl-certificate.png" alt-text="Screenshot of importing a trusted CA certificate." lightbox="media/how-to-deploy-certificates/management-ssl-certificate.png":::

- # [Locally generated self-signed certificates](#tab/cm-locally-generated-self-signed-certificate)

-

- > [!NOTE]

- > Using self-signed certificates in a production environment is not recommended, as it leads to a less secure environment.

- > We recommend using self-signed certificates in test environments only.

- > The owner of the certificate cannot be validated and the security of your system cannot be maintained.

- Select **I CONFIRM** to acknowledge the warning.

-

-1. Select the **Enable Certificate Validation** option to turn on system-wide validation for SSL/TLS certificates with the issuing [Certificate Authority](#create-ca-signed-ssltls-certificates) and [Certificate Revocation Lists](#verify-crl-server-access).

-1. Select **SAVE** to save your certificate settings.

-You can also [import the certificate to your OT sensor using CLI commands](references-work-with-defender-for-iot-cli-commands.md#tlsssl-certificate-commands).

-### Verify certificate file parameter requirements

-Verify that the certificates meet the following requirements:

- | Field | Requirement |

- |||

- | **Signature Algorithm** | SHA256RSA |

- | **Signature Hash Algorithm** | SHA256 |

- | **Valid from** | A valid past date |

- | **Valid To** | A valid future date |

- | **Public Key** | RSA 2048 bits (Minimum) or 4096 bits |

- | **CRL Distribution Point** | URL to a CRL server. If your organization doesn't [validate certificates against a CRL server](#verify-crl-server-access), remove this line from the certificate. |

- | **Subject CN (Common Name)** | domain name of the appliance, such as *sensor.contoso.com*, or *.contoso.com* |

- | **Subject (C)ountry** | Certificate country code, such as `US` |

- | **Subject (OU) Org Unit** | The organization's unit name, such as *Contoso Labs* |

- | **Subject (O)rganization** | The organization's name, such as *Contoso Inc.* |

- > [!IMPORTANT]

- > While certificates with other parameters might work, they aren't supported by Defender for IoT. Additionally, wildcard SSL certificates, which are public key certificates that can be used on multiple subdomains such as *.contoso.com*, are insecure and aren't supported.

- > Each appliance must use a unique CN.

-### Verify CRL server access

-If your organization validates certificates, your OT sensors and on-premises management console must be able to access the CRL server defined by the certificate. By default, certificates access the CRL server URL via HTTP port 80. However, some organizational security policies block access to this port.

-If your OT sensors and on-premises management consoles can't access your CRL server on port 80, you can use one of the following workarounds:

- - The URL you define must be configured as `http: //` and not `https://`

- - Make sure that the destination CRL server can listen on the port you define

- For more information, see [Forward OT alert information](how-to-forward-alert-information-to-partners.md).

-If validation fails, communication between the relevant components is halted and a validation error is presented in the console.

-## Create a certificate

-Create either a CA-signed SSL/TLS certificate or a self-signed SSL/TLS certificate (not recommended).

-### Create CA-signed SSL/TLS certificates

-Use a certificate management platform, such as an automated PKI management platform, to create a certificate. Verify that the certificate meets [certificate file requirements](#verify-certificate-file-parameter-requirements), and then [test the certificate](#test-your-ssltls-certificates) file you created when you're done.

-If you aren't carrying out certificate validation, remove the CRL URL reference in the certificate. For more information, see [certificate file requirements](#verify-certificate-file-parameter-requirements).

-Consult a security, PKI, or other qualified certificate lead if you don't have an application that can automatically create certificates.

-You can also convert existing certificate files if you don't want to create new ones.

-### Create self-signed SSL/TLS certificates

-Create self-signed SSL/TLS certificates by first [downloading a security certificate](#download-a-security-certificate) from the OT sensor or on-premises management console and then exporting it to the required file types.

-> [!NOTE]

-> While you can use a locally-generated and self-signed certificate, we do not recommend this option.

-**Export as a certificate file:**

-After downloading the security certificate, use a certificate management platform to create the following types of SSL/TLS certificate files:

-| File type | Description |

-|||

-| **.crt – certificate container file** | A `.pem`, or `.der` file, with a different extension for support in Windows Explorer.|

-| **.key – Private key file** | A key file is in the same format as a `.pem` file, with a different extension for support in Windows Explorer.|

-| **.pem – certificate container file (optional)** | Optional. A text file with a Base64-encoding of the certificate text, and a plain-text header and footer to mark the beginning and end of the certificate. |

-For example:

-1. Open the downloaded certificate file and select the **Details** tab > **Copy to file** to run the **Certificate Export Wizard**.

-1. In the **Certificate Export Wizard**, select **Next** > **DER encoded binary X.509 (.CER)** > and then select **Next** again.

-1. In the **File to Export** screen, select **Browse**, choose a location to store the certificate, and then select **Next**.

-1. Select **Finish** to export the certificate.

-> [!NOTE]

-> You may need to convert existing files types to supported types.

-### Check your certificate against a sample

-Use the following sample certificate to compare to the certificate you've created, making sure that the same fields exist in the same order.

-``` Sample SSL certificate

-Bag Attributes: <No Attributes>

-subject=C = US, S = Illinois, L = Springfield, O = Contoso Ltd, OU= Contoso Labs, CN= sensor.contoso.com, E

-= support@contoso.com

-issuer C=US, S = Illinois, L = Springfield, O = Contoso Ltd, OU= Contoso Labs, CN= Cert-ssl-root-da2e22f7-24af-4398-be51-

-e4e11f006383, E = support@contoso.com

-MIIESDCCAZCgAwIBAgIIEZK00815Dp4wDQYJKoZIhvcNAQELBQAwgaQxCzAJBgNV

-BAYTAIVTMREwDwYDVQQIDAhJbGxpbm9pczEUMBIGA1UEBwwLU3ByaW5nZmllbGQx

-FDASBgNVBAoMCONvbnRvc28gTHRKMRUWEwYDVQQLDAXDb250b3NvIExhYnMxGzAZ

-BgNVBAMMEnNlbnNvci5jb250b3NvLmNvbTEIMCAGCSqGSIb3DQEJARYTc3VwcG9y

-dEBjb250b3NvLmNvbTAeFw0yMDEyMTcxODQwMzhaFw0yMjEyMTcxODQwMzhaMIGK

-MQswCQYDVQQGEwJVUzERMA8GA1UECAwISWxsaW5vaXMxFDASBgNVBAcMC1Nwcmlu

-Z2ZpZWxkMRQwEgYDVQQKDAtDb250b3NvIEX0ZDEVMBMGA1UECwwMQ29udG9zbyBM

-YWJzMRswGQYDVQQDDBJzZW5zb3luY29udG9zby5jb20xljAgBgkqhkiG9w0BCQEW

-E3N1cHBvcnRAY29udG9zby5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK

-AoIBAQDRGXBNJSGJTfP/K5ThK8vGOPzh/N8AjFtLvQiiSfkJ4cxU/6d1hNFEMRYG

-GU+jY1Vknr0|A2nq7qPB1BVenW3 MwsuJZe Floo123rC5ekzZ7oe85Bww6+6eRbAT

-WyqpvGVVpfcsloDznBzfp5UM9SVI5UEybllod31MRR/LQUEIKLWILHLW0eR5pcLW

-pPLtOW7wsK60u+X3tqFo1AjzsNbXbEZ5pnVpCMqURKSNmxYpcrjnVCzyQA0C0eyq

-GXePs9PL5DXfHy1x4WBFTd98X83 pmh/vyydFtA+F/imUKMJ8iuOEWUtuDsaVSX0X

-kwv2+emz8CMDLsbWvUmo8Sg0OwfzAgMBAAGjfDB6MB0GA1UdDgQWBBQ27hu11E/w

-21Nx3dwjp0keRPuTsTAfBgNVHSMEGDAWgBQ27hu1lE/w21Nx3dwjp0keRPUTSTAM

-BgNVHRMEBTADAQH/MAsGA1UdDwQEAwIDqDAdBgNVHSUEFjAUBggrBgEFBQcDAgYI

-KwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggEBADLsn1ZXYsbGJLLzsGegYv7jmmLh

-nfBFQqucORSQ8tqb2CHFME7LnAMfzFGpYYV0h1RAR+1ZL1DVtm+IKGHdU9GLnuyv

-9x9hu7R4yBh3K99ILjX9H+KACvfDUehxR/ljvthoOZLalsqZIPnRD/ri/UtbpWtB

-cfvmYleYA/zq3xdk4vfOI0YTOW11qjNuBIHh0d5S5sn+VhhjHL/s3MFaScWOQU3G

-9ju6mQSo0R1F989aWd+44+8WhtOEjxBvr+17CLqHsmbCmqBI7qVnj5dHvkh0Bplw

-zhJp150DfUzXY+2sV7Uqnel9aEU2Hlc/63EnaoSrxx6TEYYT/rPKSYL+++8=

-```

-### Test your SSL/TLS certificates

-If you want to check the information within the certificate `.csr` file or private key file, use the following CLI commands:

-If these tests fail, review [certificate file parameter requirements](#verify-certificate-file-parameter-requirements) to verify that your file parameters are accurate, or consult your certificate specialist.

-## Troubleshoot

-### Download a security certificate

-1. After [installing your OT sensor software](ot-deploy/install-software-ot-sensor.md) or [on-premises management console](ot-deploy/install-software-on-premises-management-console.md), go to the sensor's or on-premises management console's IP address in a browser.

-1. Select the :::image type="icon" source="media/how-to-deploy-certificates/warning-icon.png" border="false"::: **Not secure** alert in the address bar of your web browser, then select the **>** icon next to the warning message **"Your connection to this site isn't secure"**. For example:

- :::image type="content" source="media/how-to-deploy-certificates/connection-is-not-secure.png" alt-text="Screenshot of web page with a Not secure warning in the address bar." lightbox="media/how-to-deploy-certificates/connection-is-not-secure.png":::

-1. Select the :::image type="icon" source="media/how-to-deploy-certificates/show-certificate-icon.png" border="false"::: **Show certificate** icon to view the security certificate for this website.

-1. In the **Certificate viewer** pane, select the **Details** tab, then select **Export** to save the file on your local machine.

-### Import a sensor's locally signed certificate to your certificate store

-After creating your locally signed certificate, import it to a trusted storage location. For example:

-1. Open the security certificate file and, in the **General** tab, select **Install Certificate** to start the **Certificate Import Wizard**.

-1. In **Store Location**, select **Local Machine**, then select **Next**.

-1. If a **User Allow Control** prompt appears, select **Yes** to allow the app to make changes to your device.

-1. In the **Certificate Store** screen, select **Automatically select the certificate store based on the type of certificate**, then select **Next**.

-1. Select **Place all certificates in the following store**, then **Browse**, and then select the **Trusted Root Certification Authorities** store. When you're done, select **Next**. For example:

- :::image type="content" source="media/how-to-deploy-certificates/certificate-store-trusted-root.png" alt-text="Screenshot of the certificate store screen where you can browse to the trusted root folder." lightbox="media/how-to-deploy-certificates/certificate-store-trusted-root.png":::

-1. Select **Finish** to complete the import.

-### Validate the certificate's common name

-1. To view the certificate's common name, open the certificate file and select the Details tab, and then select the **Subject** field.

- The certificate's common name will then appear next to **CN**.

-1. Sign-in to your sensor console without a secure connection. In the **Your connection isn't private** warning screen, you might see a **NET::ERR_CERT_COMMON_NAME_INVALID** error message.

-1. Select the error message to expand it, and then copy the string next to **Subject**. For example:

- :::image type="content" source="media/how-to-deploy-certificates/connection-is-not-private-subject.png" alt-text="Screenshot of the connection isn't private screen with the details expanded." lightbox="media/how-to-deploy-certificates/connection-is-not-private-subject.png":::

- The subject string should match the **CN** string in the security certificate's details.

-1. In your local file explorer, browse to the hosts file, such as at **This PC > Local Disk (C:) > Windows > System32 > drivers > etc**, and open the **hosts** file.

-1. In the hosts file, add in a line at the end of document with the sensor's IP address and the SSL certificate's common name that you copied in the previous steps. When you're done, save the changes. For example:

- :::image type="content" source="media/how-to-deploy-certificates/hosts-file.png" alt-text="Screenshot of the hosts file." lightbox="media/how-to-deploy-certificates/hosts-file.png":::

-### Troubleshoot certificate upload errors

-You won't be able to upload certificates to your OT sensors or on-premises management consoles if the certificates aren't created properly or are invalid. Use the following table to understand how to take action if your certificate upload fails and an error message is shown:

-| **Certificate validation error** | **Recommendation** |

-|--|--|

-| **Passphrase does not match to the key** | Make sure you have the correct passphrase. If the problem continues, try recreating the certificate using the correct passphrase. |

-| **Cannot validate chain of trust. The provided Certificate and Root CA don't match.** | Make sure a `.pem` file correlates to the `.crt` file. <br> If the problem continues, try recreating the certificate using the correct chain of trust, as defined by the `.pem` file. |

-| **This SSL certificate has expired and isn't considered valid.** | Create a new certificate with valid dates.|

-|**This certificate has been revoked by the CRL and can't be trusted for a secure connection** | Create a new unrevoked certificate. |

-|**The CRL (Certificate Revocation List) location is not reachable. Verify the URL can be accessed from this appliance** | Make sure that your network configuration allows the sensor or on-premises management console to reach the CRL server defined in the certificate. <br> For more information, see [CRL server access](#verify-crl-server-access). |

-|**Certificate validation failed** | This indicates a general error in the appliance. <br> Contact [Microsoft Support](https://support.microsoft.com/supportforbusiness/productselection?sapId=82c8f35-1b8e-f274-ec11-c6efdd6dd099).|

-## Next steps

-For more information, see:

-description: Learn how to customize port and VLAN names on Microsoft Defender for IoT OT network sensors.

-# Customize port and VLAN names on OT network sensors

-Enrich device data shown in Defender for IoT by customizing port and VLAN names on your OT network sensors.

-For example, you might want to assign a name to a non-reserved port that shows unusually high activity in order to call it out, or assign a name to a VLAN number to identify it quicker.

-## Prerequisites

-To customize port and VLAN names, you must be able to access the OT network sensor as an **Admin** user.

-For more information, see [On-premises users and roles for OT monitoring with Defender for IoT](roles-on-premises.md).

-## Customize names of detected ports

-Defender for IoT automatically assigns names to most universally reserved ports, such as DHCP or HTTP. However, you might want to customize the name of a specific port to highlight it, such as when you're watching a port with unusually high detected activity.

-Port names are shown in Defender for IoT when [viewing device groups from the OT sensor's device map](how-to-work-with-the-sensor-device-map.md), or when you create OT sensor reports that include port information.

-**To customize a port name:**

-1. Sign into your OT sensor as an **Admin** user.

-1. Select **System settings** on the left and then, under **Network monitoring**, select **Port Naming**.

-1. In the **Port naming** pane that appears, enter the port number you want to name, the port's protocol, and a meaningful name. Supported protocol values include: **TCP**, **UDP**, and **BOTH**.

-1. Select **+ Add port** to customize an additional port, and **Save** when you're done.

-## Customize a VLAN name

-VLANs are either discovered automatically by the OT network sensor or added manually. Automatically discovered VLANs can't be edited or deleted, but manually added VLANs require a unique name. If a VLAN isn't explicitly named, the VLAN's number is shown instead.

-VLAN's support is based on 802.1q (up to VLAN ID 4094).

-VLAN names aren't synchronized between the OT network sensor and the on-premises management console. If you want to view customized VLAN names on the on-premises management console, [define the VLAN names](how-to-manage-the-on-premises-management-console.md#define-vlan-names) there as well.

-**To configure VLAN names on an OT network sensor:**

-1. Sign in to your OT sensor as an **Admin** user.

-1. Select **System Settings** on the left and then, under **Network monitoring**, select **VLAN Naming**.

-1. In the **VLAN naming** pane that appears, enter a VLAN ID and unique VLAN name. VLAN names can contain up to 50 ASCII characters.

-1. Select **+ Add VLAN** to customize an additional VLAN, and **Save** when you're done.

-1. **For Cisco switches**: Add the `monitor session 1 destination interface XX/XX encapsulation dot1q` command to the SPAN port configuration, where *XX/XX* is the name and number of the port.

-## Next steps

-> [!div class="nextstepaction"]

-> [Investigate detected devices from the OT sensor device inventory](how-to-investigate-sensor-detections-in-a-device-inventory.md)

-> [!div class="nextstepaction"]

-> [Create sensor trends and statistics reports](how-to-create-trends-and-statistics-reports.md)

-> [!div class="nextstepaction"]

-> [Create sensor data mining queries](how-to-create-data-mining-queries.md)

- If your OT sensors or on-premises management console are configured to [validate certificates](how-to-deploy-certificates.md#verify-crl-server-access) and the certificate can't be verified, the alerts aren't forwarded.

-description: Gain insight into global, regional, and local threats by using the site map in the on-premises management console.

-# Gain insight into global, regional, and local threats

-The site map in the on-premises management console helps you achieve full security coverage by dividing your network into geographical and logical segments that reflect your business topology:

- The map is interactive and enables opening each site and delving into this site's information.

- For example, a global company that contains glass factories, plastic factories, and automobile factories can be managed as three different business units. A physical site located in Toronto includes three different glass production lines, a plastic production line, and a truck engine production line. So, this site has representatives of all three business units.

-## Work with site map views

-The on-premises management console provides an overall view of your industrial network in a context-related map. The general map view presents the global map of your organization with the geographical location of each site.

-### Color-coded map views

-**Green**: The number of security events is below the threshold that Defender for IoT has defined for your system. No action is needed.

-**Yellow**: The number of security events is equal to the threshold that Defender for IoT has defined for your system. Consider investigating the events.

-**Red**: The number of security events is beyond the threshold that Defender for IoT has defined for your system. Take immediate action.

-### Risk-level map views

-**Risk Assessment**: The Risk Assessment view displays information on site risks. Risk information helps you prioritize mitigation and build a road map to plan security improvements.

-**Incident Response**: Get a centralized view of all unacknowledged alerts on each site across the enterprise. You can drill down and manage alerts detected in a specific site.

-**Malicious Activity**: If malware was detected, the site appears in red. This indicates that you should take immediate action.

-**Operational Alerts**: This map view for OT systems provides a better understanding of which OT system might experience operational incidents, such as PLC stops, firmware upload, and program upload.

-To choose a map view:

-1. Select **Default View** from the map.

-2. Select a view.

-## Update the site map image

-Defender for IoT provides a default world map. You can change it to reflect your organization: a country map or a city map, for example.

-To replace the map:

-1. On the left pane, select **System Settings**.

-2. Select the **Change Site Map** and upload the graphic file to replace the default map.

-## Next step

-[View alerts](how-to-view-alerts.md)

-1. In the **Validation for on-premises management console certificates** area, select **Required** if SSL/TLS certificate validation is required. Otherwise, select **None**.

- If you've selected **Required** and validation fails, communication between relevant components is halted, and a validation error is shown on the sensor. For more information, see [CRT file requirements](best-practices/certificate-requirements.md#crt-file-requirements).

-1. In the **Validation for on-premises management console certificates** area, select **Required** if SSL/TLS certificate validation is required. Otherwise, select **None**.

-description: Learn about solution architecture, network preparation, prerequisites, and other information needed to ensure that you successfully set up your network to work with Microsoft Defender for IoT appliances.

-# Prepare your OT network for Microsoft Defender for IoT

-This article describes how to set up your OT network to work with Microsoft Defender for IoT components, including the OT network sensors, the Azure portal, and an optional on-premises management console.

-OT network sensors use agentless, patented technology to discover, learn, and continuously monitor network devices for a deep visibility into OT/ICS/IoT risks. Sensors carry out data collection, analysis, and alerting on-site, making them ideal for locations with low bandwidth or high latency.

-This article is intended for personnel experienced in operating and managing OT and IoT networks, such as automation engineers, plant managers, OT network infrastructure service providers, cybersecurity teams, CISOs, and CIOs.

-We recommend that you use this article together with our [pre-deployment checklist](pre-deployment-checklist.md).

-For assistance or support, contact [Microsoft Support](https://support.microsoft.com/supportforbusiness/productselection?sapId=82c88f35-1b8e-f274-ec11-c6efdd6dd099).

-## Prerequisites

-Before performing the procedures in this article, make sure you understand your own network architecture and how you'll connect to Defender for IoT. For more information, see:

-## On-site deployment tasks

-Perform the steps in this section before deploying Defender for IoT on your network.

-Make sure to perform each step methodologically, requesting the information and reviewing the data you receive. Prepare and configure your site and then validate your configuration.

-### Collect site information

-Record the following site information:

-### Prepare a configuration workstation

-**To prepare a Windows or Mac workstation**:

- For more information, see [recommended browsers for the Azure portal](../../azure-portal/azure-portal-supported-browsers-devices.md#recommended-browsers).

-### Set up certificates

-After you've installed the Defender for IoT sensor or on-premises management console software, a local, self-signed certificate is generated, and used to access the sensor web application.

-The first time they sign in to Defender for IoT, administrator users are prompted to provide an SSL/TLS certificate. Optional certificate validation is enabled by default.

-We recommend having your certificates ready before you start your deployment. For more information, see [Defender for IoT installation](how-to-install-software.md) and [About Certificates](how-to-deploy-certificates.md).

-### Plan rack installation

-**To plan your rack installation**:

-1. Prepare a monitor and a keyboard for your appliance network settings.

-1. Allocate the rack space for the appliance.

-1. Have AC power available for the appliance.

-1. Prepare the LAN cable for connecting the management to the network switch.

-1. Prepare the LAN cables for connecting switch SPAN (mirror) ports and network taps to the Defender for IoT appliance.

-1. Configure, connect, and validate SPAN ports in the mirrored switches using one of the following methods:

- |Method |Description |

- |||

- |[Switch SPAN port](traffic-mirroring/configure-mirror-span.md) | Mirror local traffic from interfaces on the switch to a different interface on the same switch. |

- |[Remote SPAN (RSPAN)](traffic-mirroring/configure-mirror-rspan.md) | Mirror traffic from multiple, distributed source ports into a dedicated remote VLAN. |

- |[Active or passive aggregation (TAP)](traffic-mirroring/configure-mirror-tap.md) | Mirror traffic by installing an active or passive aggregation terminal access point (TAP) inline to the network cable. |

- |[ERSPAN](traffic-mirroring/configure-mirror-erspan.md) | Mirror traffic with ERSPAN encapsulation when you need to extend monitored traffic across Layer 3 domains, when using specific Cisco routers and switches. |

- |[ESXi vSwitch](traffic-mirroring/configure-mirror-esxi.md) | Use *Promiscuous mode* in a virtual switch environment as a workaround for configuring a monitoring port. |

- |[Hyper-V vSwitch](traffic-mirroring/configure-mirror-hyper-v.md) | Use *Promiscuous mode* in a virtual switch environment as a workaround for configuring a monitoring port. |

- > [!NOTE]

- > SPAN and RSPAN are Cisco terminology. Other brands of switches have similar functionality but might use different terminology.

- >

-1. Connect the configured SPAN port to a computer running Wireshark, and verify that the port is configured correctly.

-1. Open all the relevant firewall ports.

-### Validate your network

-After preparing your network, use the guidance in this section to validate whether you're ready to deploy Defender for IoT.

-Make an attempt to receive a sample of recorded traffic (PCAP file) from the switch SPAN or mirror port. This sample will:

-For example, you can record a sample PCAP file for a few minutes by connecting a laptop to an already configured SPAN port through the Wireshark application.

-**To use Wireshark to validate your network**:

-For example:

-## Networking requirements

-Use the following tables to ensure that required firewalls are open on your workstation and verify that your organization security policy allows required access.

-### User access to the sensor and management console

-| Protocol | Transport | In/Out | Port | Used | Purpose | Source | Destination |

-|--|--|--|--|--|--|--|--|

-| SSH | TCP | In/Out | 22 | CLI | To access the CLI | Client | Sensor and on-premises management console |

-| HTTPS | TCP | In/Out | 443 | To access the sensor, and on-premises management console web console | Access to Web console | Client | Sensor and on-premises management console |

-### Sensor access to Azure portal

-| Protocol | Transport | In/Out | Port | Purpose | Source | Destination |

-|--|--|--|--|--|--|--|

-| HTTPS | TCP | Out | 443 | Access to Azure | Sensor |OT network sensors connect to Azure to provide alert and device data and sensor health messages, access threat intelligence packages, and more. Connected Azure services include IoT Hub, Blob Storage, Event Hubs, and the Microsoft Download Center.<br><br>**For OT sensor versions 22.x**: Download the list from the **Sites and sensors** page in the Azure portal. Select an OT sensor with software versions 22.x or higher, or a site with one or more supported sensor versions. Then, select **More options > Download endpoint details**. For more information, see [Sensor management options from the Azure portal](how-to-manage-sensors-on-the-cloud.md#sensor-management-options-from-the-azure-portal).<br><br>**For OT sensor versions 10.x**: `*.azure-devices.net`<br> `*.blob.core.windows.net`<br> `*.servicebus.windows.net`<br> `download.microsoft.com`|

-### Sensor access to the on-premises management console

-| Protocol | Transport | In/Out | Port | Used | Purpose | Source | Destination |

-|--|--|--|--|--|--|--|--|

-| NTP | UDP | In/Out | 123 | Time Sync | Connects the NTP to the on-premises management console | Sensor | On-premises management console |

-| TLS/SSL | TCP | In/Out | 443 | Give the sensor access to the on-premises management console. | The connection between the sensor, and the on-premises management console | Sensor | On-premises management console |

-### Other firewall rules for external services (optional)

-Open these ports to allow extra services for Defender for IoT.

-| Protocol | Transport | In/Out | Port | Used | Purpose | Source | Destination |

-|--|--|--|--|--|--|--|--|

-| SMTP | TCP | Out | 25 | Email | Used to open the customer's mail server, in order to send emails for alerts, and events | Sensor and On-premises management console | Email server |

-| DNS | TCP/UDP | In/Out | 53 | DNS | The DNS server port | On-premises management console and Sensor | DNS server |

-| HTTP | TCP | Out | 80 | The CRL download for certificate validation when uploading certificates. | Access to the CRL server | Sensor and on-premises management console | CRL server |

-| [WMI](how-to-configure-windows-endpoint-monitoring.md) | TCP/UDP | Out | 135, 1025-65535 | Monitoring | Windows Endpoint Monitoring | Sensor | Relevant network element |

-| [SNMP](how-to-set-up-snmp-mib-monitoring.md) | UDP | Out | 161 | Monitoring | Monitors the sensor's health | On-premises management console and Sensor | SNMP server |

-| LDAP | TCP | In/Out | 389 | Active Directory | Allows Active Directory management of users that have access, to sign in to the system | On-premises management console and Sensor | LDAP server |

-| Proxy | TCP/UDP | In/Out | 443 | Proxy | To connect the sensor to a proxy server | On-premises management console and Sensor | Proxy server |

-| Syslog | UDP | Out | 514 | LEEF | The logs that are sent from the on-premises management console to Syslog server | On-premises management console and Sensor | Syslog server |

-| LDAPS | TCP | In/Out | 636 | Active Directory | Allows Active Directory management of users that have access, to sign in to the system | On-premises management console and Sensor | LDAPS server |

-| Tunneling | TCP | In | 9000 </br></br> In addition to port 443 </br></br> Allows access from the sensor, or end user, to the on-premises management console </br></br> Port 22 from the sensor to the on-premises management console | Monitoring | Tunneling | Endpoint, Sensor | On-premises management console |

-## Choose a cloud connection method

-If you're setting up OT sensors and connecting them to the cloud, understand supported cloud connection methods, and make sure to connect your sensors as needed.

-For more information, see:

-## Troubleshooting

-This section provides troubleshooting for common issues when preparing your network for a Defender for IoT deployment.

-### Can't connect by using a web interface

-1. Verify that the computer you're trying to connect is on the same network as the appliance.

-2. Verify that the GUI network is connected to the management port on the sensor.

-3. Ping the appliance IP address. If there's no response to ping:

- 1. Connect a monitor and a keyboard to the appliance.

- 1. Use the **support** user* and password to sign in.

- 1. Use the command **network list** to see the current IP address.

-4. If the network parameters are misconfigured, sign into the OT sensor as the **cyberx_host** user* to re-run the OT monitoring software configuration wizard. For example:

- ```bash

- root@xsense:/# sudo dpkg-reconfigure iot-sensor

- ```

- The configuration wizard starts automatically. For more information, see [Install OT monitoring software](../how-to-install-software.md#install-ot-monitoring-software).

-5. Restart the sensor machine and sign in with the **support** user*. Run the **network list** command to verify that the parameters were changed.

-6. Try to ping and connect from the GUI again.

-(*) For more information, see [Default privileged on-premises users](roles-on-premises.md#default-privileged-on-premises-users).

-### Appliance isn't responding

-1. Connect with a monitor and keyboard to the appliance, or use PuTTY to connect remotely to the CLI.

-2. Use the *support* credentials to sign in.

-3. Use the **system sanity** command and check that all processes are running.

- :::image type="content" source="media/how-to-set-up-your-network/system-sanity-command.png" alt-text="Screenshot of the system sanity command.":::

-For any other issues, contact [Microsoft Support](https://support.microsoft.com/supportforbusiness/productselection?sapId=82c88f35-1b8e-f274-ec11-c6efdd6dd099).

-## Next steps

-For more information, see:

-description: Troubleshoot your OT sensor and on-premises management console to eliminate any problems you might be having.

-# Troubleshoot the sensor and on-premises management console

-This article describes basic troubleshooting tools for the sensor and the on-premises management console. In addition to the items described here, you can check the health of your system in the following ways:

-## Check system health

-Check your system health from the sensor or on-premises management console.

-**To access the system health tool**:

-1. Sign in to the sensor or on-premises management console with the *support* user credentials.

-1. Select **System Statistics** from the **System Settings** window.

- :::image type="icon" source="media/tutorial-install-components/system-statistics-icon.png" border="false":::

-1. System health data appears. Select an item on the left to view more details in the box. For example:

- :::image type="content" source="media/tutorial-install-components/system-health-check-screen.png" alt-text="Screenshot that shows the system health check.":::

-System health checks include the following:

-|Name |Description |

-|||

-|**Sanity** | |

-|- Appliance | Runs the appliance sanity check. You can perform the same check by using the CLI command `system-sanity`. |

-|- Version | Displays the appliance version. |

-|- Network Properties | Displays the sensor network parameters. |

-|**Redis** | |

-|- Memory | Provides the overall picture of memory usage, such as how much memory was used and how much remained. |

-|- Longest Key | Displays the longest keys that might cause extensive memory usage. |

-|**System** | |

-|- Core Log | Provides the last 500 rows of the core log, so that you can view the recent log rows without exporting the entire system log. |

-|- Task Manager | Translates the tasks that appear in the table of processes to the following layers: <br><br> - Persistent layer (Redis)<br> - Cache layer (SQL) |

-|- Network Statistics | Displays your network statistics. |

-|- TOP | Shows the table of processes. It's a Linux command that provides a dynamic real-time view of the running system. |

-|- Backup Memory Check | Provides the status of the backup memory, checking the following:<br><br> - The location of the backup folder<br> - The size of the backup folder<br> - The limitations of the backup folder<br> - When the last backup happened<br> - How much space there are for the extra backup files |

-|- ifconfig | Displays the parameters for the appliance's physical interfaces. |

-|- CyberX nload | Displays network traffic and bandwidth by using the six-second tests. |

-|- Errors from Core, log | Displays errors from the core log file. |

-### Check system health by using the CLI

-Verify that the system is up and running prior to testing the system's sanity.

-For more information, see [CLI command reference from OT network sensors](cli-ot-sensor.md).

-**To test the system's sanity**:

-1. Connect to the CLI with the Linux terminal (for example, PuTTY) and the user *support*.

-1. Enter `system sanity`.

-1. Check that all the services are green (running).

- :::image type="content" source="media/tutorial-install-components/support-screen.png" alt-text="Screenshot that shows running services.":::

-1. Verify that **System is UP! (prod)** appears at the bottom.

-Verify that the correct version is used:

-**To check the system's version**:

-1. Connect to the CLI with the Linux terminal (for example, PuTTY) and the user *support*.

-1. Enter `system version`.

-1. Check that the correct version appears.

-Verify that all the input interfaces configured during the installation process are running:

-**To validate the system's network status**:

-1. Connect to the CLI with the Linux terminal (for example, PuTTY) and the *support* user.

-1. Enter `network list` (the equivalent of the Linux command `ifconfig`).

-1. Validate that the required input interfaces appear. For example, if two quad Copper NICs are installed, there should be 10 interfaces in the list.

- :::image type="content" source="media/tutorial-install-components/interface-list-screen.png" alt-text="Screenshot that shows the list of interfaces.":::

-Verify that you can access the console web GUI:

-**To check that management has access to the UI**:

-1. Connect a laptop with an Ethernet cable to the management port (**Gb1**).

-1. Define the laptop NIC address to be in the same range as the appliance.

- :::image type="content" source="media/tutorial-install-components/access-to-ui.png" alt-text="Screenshot that shows management access to the UI." border="false":::

-1. Ping the appliance's IP address from the laptop to verify connectivity (default: 10.100.10.1).

-1. Open the Chrome browser in the laptop and enter the appliance's IP address.

-1. In the **Your connection is not private** window, select **Advanced** and proceed.

-1. The test is successful when the Defender for IoT sign-in screen appears.

- :::image type="content" source="media/tutorial-install-components/defender-for-iot-sign-in-screen.png" alt-text="Screenshot that shows access to management console.":::

-## Troubleshoot sensors

-### You can't connect by using a web interface

-1. Verify that the computer that you're trying to connect is on the same network as the appliance.

-1. Verify that the GUI network is connected to the management port.

-1. Ping the appliance's IP address. If there's no ping:

- 1. Connect a monitor and a keyboard to the appliance.

- 1. Use the *support* user and password to sign in.

- 1. Use the command `network list` to see the current IP address.

-1. If the network parameters are misconfigured, use the following procedure to change them:

- 1. Use the command `network edit-settings`.

- 1. To change the management network IP address, select **Y**.

- 1. To change the subnet mask, select **Y**.

- 1. To change the DNS, select **Y**.

- 1. To change the default gateway IP address, select **Y**.

- 1. For the input interface change (sensor only), select **N**.

- 1. To apply the settings, select **Y**.

-1. After restart, connect with the *support* user credentials and use the `network list` command to verify that the parameters were changed.

-1. Try to ping and connect from the GUI again.

-### The appliance isn't responding

-1. Connect a monitor and keyboard to the appliance, or use PuTTY to connect remotely to the CLI.

-1. Use the *support* user credentials to sign in.

-1. Use the `system sanity` command and check that all processes are running. For example:

- :::image type="content" source="media/tutorial-install-components/system-sanity-screen.png" alt-text="Screenshot that shows the system sanity command.":::

-For any other issues, contact [Microsoft Support](https://support.microsoft.com/en-us/supportforbusiness/productselection?sapId=82c88f35-1b8e-f274-ec11-c6efdd6dd099).

-### Investigate password failure at initial sign-in

-When signing into a pre-configured sensor for the first time, you'll need to perform password recovery as follows:

-1. On the Defender for IoT sign in screen, select **Password recovery**. The **Password recovery** screen opens.

-1. Select either **CyberX** or **Support**, and copy the unique identifier.

-1. Navigate to the Azure portal and select **Sites and Sensors**.

-1. Select the **More Actions** drop down menu and select **Recover on-premises management console password**.

- :::image type="content" source="media/how-to-create-and-manage-users/recover-password.png" alt-text=" Screenshot of the recover on-premises management console password option.":::

-1. Enter the unique identifier that you received on the **Password recovery** screen and select **Recover**. The `password_recovery.zip` file is downloaded. Don't extract or modify the zip file.

- :::image type="content" source="media/how-to-create-and-manage-users/enter-identifier.png" alt-text="Screenshot of the Recover dialog box.":::

-1. On the **Password recovery** screen, select **Upload**. **The Upload Password Recovery File** window will open.

-1. Select **Browse** to locate your `password_recovery.zip` file, or drag the `password_recovery.zip` to the window.

-1. Select **Next**, and your user, and system-generated password for your management console will then appear.

- > [!NOTE]

- > When you sign in to a sensor or on-premises management console for the first time, it's linked to your Azure subscription, which you'll need if you need to recover the password for the *cyberx*, or *support* user. For more information, see the relevant procedure for [sensors](manage-users-sensor.md#recover-privileged-access-to-a-sensor) or an [on-premises management console](manage-users-on-premises-management-console.md#recover-privileged-access-to-an-on-premises-management-console).

-### Investigate a lack of traffic

-An indicator appears at the top of the console when the sensor recognizes that there's no traffic on one of the configured ports. This indicator is visible to all users. When this message appears, you can investigate where there's no traffic. Make sure the span cable is connected and there was no change in the span architecture.

-### Check system performance

-When a new sensor is deployed or a sensor is working slowly or not showing any alerts, you can check system performance.

-1. In the Defender for IoT dashboard > **Overview**, make sure that `PPS > 0`.

-1. In *Devices** check that devices are being discovered.

-1. In **Data Mining**, generate a report.

-1. In **Trends & Statistics** window, create a dashboard.

-1. In **Alerts**, check that the alert was created.

-### Investigate a lack of expected alerts

-If the **Alerts** window doesn't show an alert that you expected, verify the following:

-1. Check if the same alert already appears in the **Alerts** window as a reaction to a different security instance. If yes, and this alert hasn't been handled yet, the sensor console does not show a new alert.

-1. Make sure you did not exclude this alert by using the **Alert Exclusion** rules in the management console.

-### Investigate dashboard that shows no data

-When the dashboards in the **Trends & Statistics** window show no data, do the following:

-1. [Check system performance](#check-system-performance).

-1. Make sure the time and region settings are properly configured and not set to a future time.

-### Investigate a device map that shows only broadcasting devices

-When devices shown on the device map appear not connected to each other, something might be wrong with the SPAN port configuration. That is, you might be seeing only broadcasting devices and no unicast traffic.

-1. Validate that you're only seeing the broadcast traffic. To do this, in **Data Mining**, select **Create report**. In **Create new report**,specify the report fields. In **Choose Category**, choose **Select all**.

-1. Save the report, and review it to see if only broadcast and multicast traffic (and no unicast traffic) appears. If so, asking networking to fix the SPAN port configuration so that you can see the unicast traffic as well. Alternately, you can record a PCAP directly from the switch, or connect a laptop by using Wireshark.

-### Connect the sensor to NTP

-You can configure a standalone sensor and a management console, with the sensors related to it, to connect to NTP.

-To connect a standalone sensor to NTP:

-To connect a sensor controlled by the management console to NTP:

-### Investigate when devices aren't shown on the map, or you have multiple internet-related alerts

-Sometimes ICS devices are configured with external IP addresses. These ICS devices are not shown on the map. Instead of the devices, an internet cloud appears on the map. The IP addresses of these devices are included in the cloud image. Another indication of the same problem is when multiple internet-related alerts appear. Fix the issue as follows:

-1. Right-click the cloud icon on the device map and select **Export IP Addresses**.

-1. Copy the public ranges that are private, and add them to the subnet list.

-1. Generate a new data-mining report for internet connections.

-1. In the data-mining report, enter the administrator mode and delete the IP addresses of your ICS devices.

-### Clearing sensor data

-In cases where the sensor needs to be relocated or erased, all learned data can be cleared from the sensor.

-### Export logs from the sensor console for troubleshooting

-For further troubleshooting, you may want to export logs to send to the support team, such as database or operating system logs.

-**To export log data**:

-1. In the sensor console, go to **System settings** > **Sensor management** > **Backup & restore** > **Backup**.

-1. In the **Export Troubleshooting Information** dialog:

- 1. In the **File Name** field, enter a meaningful name for the exported log. The default filename uses the current date, such as **13:10-June-14-2022.tar.gz**.

- 1. Select the logs you would like to export.

- 1. Select **Export**.

- The file is exported and is linked from the **Archived Files** list at the bottom of the **Export Troubleshooting Information** dialog.

-

- For example:

- :::image type="content" source="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/export-logs-sensor.png" alt-text="Screenshot of the export troubleshooting information dialog in the sensor console. " lightbox="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/export-logs-sensor.png":::

-1. Select the file link to download the exported log, and also select the :::image type="icon" source="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/eye-icon.png" border="false"::: button to view its one-time password.

-1. To open the exported logs, forward the downloaded file and the one-time password to the support team. Exported logs can be opened only together with the Microsoft support team.

- To keep your logs secure, make sure to forward the password separately from the downloaded log.

-> [!NOTE]

-> Support ticket diagnostics can be downloaded from the sensor console and then uploaded directly to the support team in the Azure portal.

-## Troubleshoot an on-premises management console

-### Investigate a lack of expected alerts

-If you don't see an expected alert on the on-premises **Alerts** page, do the following to troubleshoot:

-### Tweak the Quality of Service (QoS)

-To save your network resources, you can limit the number of alerts sent to external systems (such as emails or SIEM) in one sync operation between an appliance and the on-premises management console.

-The default is 50. This means that in one communication session between an appliance and the on-premises management console, there will be no more than 50 alerts to external systems.

-To limit the number of alerts, use the `notifications.max_number_to_report` property available in `/var/cyberx/properties/management.properties`. No restart is needed after you change this property.

-**To tweak the Quality of Service (QoS)**:

-1. Sign in as a Defender for IoT user.

-1. Verify the default values:

- ```bash

- grep \"notifications\" /var/cyberx/properties/management.properties

- ```

- The following default values appear:

- ```bash

- notifications.max_number_to_report=50

- notifications.max_time_to_report=10 (seconds)

- ```

-1. Edit the default settings:

- ```bash

- sudo nano /var/cyberx/properties/management.properties

- ```

-1. Edit the settings of the following lines:

- ```bash

- notifications.max_number_to_report=50

- notifications.max_time_to_report=10 (seconds)

- ```

-1. Save the changes. No restart is required.

-### Export logs from the on-premises management console for troubleshooting

-For further troubleshooting, you may want to export logs to send to the support team, such as audit or database logs.

-**To export log data**:

-1. In the on-premises management console, select **System Settings > Export**.

-1. In the **Export Troubleshooting Information** dialog:

- 1. In the **File Name** field, enter a meaningful name for the exported log. The default filename uses the current date, such as **13:10-June-14-2022.tar.gz**.

- 1. Select the logs you would like to export.

- 1. Select **Export**.

- The file is exported and is linked from the **Archived Files** list at the bottom of the **Export Troubleshooting Information** dialog.

- For example:

- :::image type="content" source="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/export-logs-on-premises-management-console.png" alt-text="Screenshot of the Export Troubleshooting Information dialog in the on-premises management console." lightbox="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/export-logs-on-premises-management-console.png":::

-1. Select the file link to download the exported log, and also select the :::image type="icon" source="media/how-to-troubleshoot-the-sensor-and-on-premises-management-console/eye-icon.png" border="false"::: button to view its one-time password.

-1. To open the exported logs, forward the downloaded file and the one-time password to the support team. Exported logs can be opened only together with the Microsoft support team.

- To keep your logs secure, make sure to forward the password separately from the downloaded log.

-## Next steps