Deploy an SAP data connector agent from the command line
Article
This article provides command line options for deploying an SAP data connector agent. For typical deployments we recommend that you use the portal instead of the command line, as data connector agents installed via the command line can be managed only via the command line.
However, if you're using a configuration file to store your credentials instead of Azure Key Vault, or if you're an advanced user who wants to deploy the data connector manually, such as in a Kubernetes cluster, use the procedures in this article instead.
While you can run multiple data connector agents on a single machine, we recommend that you start with one only, monitor the performance, and then increase the number of connectors slowly. We also recommend that your security team perform this procedure with help from the SAP BASIS team.
Deploy the data connector agent using a managed identity or registered application
This procedure describes how to create a new agent and connect it to your SAP system via the command line, authenticating with a managed identity or a Microsoft Entra ID registered application.
For Microsoft Azure operated by 21Vianet, add --cloud mooncake to the end of the copied command.
For Azure Government - US, add --cloud fairfax to the end of the copied command.
For a registered application, use the following command to download the deployment kickstart script from the Microsoft Sentinel GitHub repository and mark it executable:
Run the script, specifying the application ID, secret (the "password"), tenant ID, and key vault name that you copied in the previous steps. For example:
The script updates the OS components, installs the Azure CLI and Docker software and other required utilities (jq, netcat, curl), and prompts you for configuration parameter values. Supply extra parameters to the script to minimize the number of prompts or to customize the container deployment. For more information on available command line options, see Kickstart script reference.
Follow the on-screen instructions to enter your SAP and key vault details and complete the deployment. When the deployment is complete, a confirmation message is displayed:
The process has been successfully completed, thank you!
Make a note of the Docker container name in the script output. To see the list of docker containers on your VM, run:
docker ps -a
You'll use the name of the docker container in the next step.
Deploying the SAP data connector agent requires that you grant your agent's VM identity with specific permissions to the Log Analytics workspace enabled for Microsoft Sentinel, using the Microsoft Sentinel Business Applications Agent Operator and Reader roles.
To run the command in this step, you must be a resource group owner on the Log Analytics workspace enabled for Microsoft Sentinel. If you aren't a resource group owner on your workspace, this procedure can also be performed later on.
Assign the Microsoft Sentinel Business Applications Agent Operator and Reader roles to the VM's identity:
Get the agent ID by running the following command, replacing the <container_name> placeholder with the name of the docker container that you'd created with the kickstart script:
For example, an agent ID returned might be 234fba02-3b34-4c55-8c0e-e6423ceb405b.
Assign the Microsoft Sentinel Business Applications Agent Operator and Reader roles by running the following commands:
az role assignment create --assignee-object-id <Object_ID> --role --assignee-principal-type ServicePrincipal "Microsoft Sentinel Business Applications Agent Operator" --scope /subscriptions/<SUB_ID>/resourcegroups/<RESOURCE_GROUP_NAME>/providers/microsoft.operationalinsights/workspaces/<WS_NAME>/providers/Microsoft.SecurityInsights/BusinessApplicationAgents/<AGENT_IDENTIFIER>
az role assignment create --assignee-object-id <Object_ID> --role --assignee-principal-type ServicePrincipal "Reader" --scope /subscriptions/<SUB_ID>/resourcegroups/<RESOURCE_GROUP_NAME>/providers/microsoft.operationalinsights/workspaces/<WS_NAME>/providers/Microsoft.SecurityInsights/BusinessApplicationAgents/<AGENT_IDENTIFIER>
Replace placeholder values as follows:
Placeholder
Value
<OBJ_ID>
Your VM identity object ID.
To find your VM identity object ID in Azure: - For a managed identity, the object ID is listed on the VM's Identity page. - For a service principal, go to Enterprise application in Azure. Select All applications and then select your VM. The object ID is displayed on the Overview page.
<SUB_ID>
The subscription ID for you Log Analytics workspace enabled for Microsoft Sentinel
<RESOURCE_GROUP_NAME>
The resource group name for your Log Analytics workspace enabled for Microsoft Sentinel
<WS_NAME>
The name of your Log Analytics workspace enabled for Microsoft Sentinel
<AGENT_IDENTIFIER>
The agent ID displayed after running the command in the previous step.
To configure the Docker container to start automatically, run the following command, replacing the <container-name> placeholder with the name of your container:
The deployment procedure generates a systemconfig.json file that contains the configuration details for the SAP data connector agent. The file is located in the /sapcon-app/sapcon/config/system directory on your VM.
Deploy the data connector using a configuration file
Azure Key Vault is the recommended method to store your authentication credentials and configuration data. If you're prevented from using Azure Key Vault, this procedure describes how you can deploy the data connector agent container using a configuration file instead.
The script updates the OS components, installs the Azure CLI and Docker software and other required utilities (jq, netcat, curl), and prompts you for configuration parameter values. Supply extra parameters to the script as needed to minimize the number of prompts or to customize the container deployment. For more information, see the Kickstart script reference.
Follow the on-screen instructions to enter the requested details and complete the deployment. When the deployment is complete, a confirmation message is displayed:
The process has been successfully completed, thank you!
Make a note of the Docker container name in the script output. To see the list of docker containers on your VM, run:
docker ps -a
You'll use the name of the docker container in the next step.
Deploying the SAP data connector agent requires that you grant your agent's VM identity with specific permissions to the Log Analytics workspace enabled for Microsoft Sentinel, using the Microsoft Sentinel Business Applications Agent Operator and Reader roles.
To run the commands in this step, you must be a resource group owner on your workspace. If you aren't a resource group owner on your workspace, this step can also be performed later on.
Assign the Microsoft Sentinel Business Applications Agent Operator and Reader roles to the VM's identity:
Get the agent ID by running the following command, replacing the <container_name> placeholder with the name of the docker container that you created with the Kickstart script:
For example, an agent ID returned might be 234fba02-3b34-4c55-8c0e-e6423ceb405b.
Assign the Microsoft Sentinel Business Applications Agent Operator and Reader roles by running the following commands:
az role assignment create --assignee-object-id <Object_ID> --role --assignee-principal-type ServicePrincipal "Microsoft Sentinel Business Applications Agent Operator" --scope /subscriptions/<SUB_ID>/resourcegroups/<RESOURCE_GROUP_NAME>/providers/microsoft.operationalinsights/workspaces/<WS_NAME>/providers/Microsoft.SecurityInsights/BusinessApplicationAgents/<AGENT_IDENTIFIER>
az role assignment create --assignee-object-id <Object_ID> --role --assignee-principal-type ServicePrincipal "Reader" --scope /subscriptions/<SUB_ID>/resourcegroups/<RESOURCE_GROUP_NAME>/providers/microsoft.operationalinsights/workspaces/<WS_NAME>/providers/Microsoft.SecurityInsights/BusinessApplicationAgents/<AGENT_IDENTIFIER>
Replace placeholder values as follows:
Placeholder
Value
<OBJ_ID>
Your VM identity object ID.
To find your VM identity object ID in Azure: For a managed identity, the object ID is listed on the VM's Identity page. For a service principal, go to Enterprise application in Azure. Select All applications and then select your VM. The object ID is displayed on the Overview page.
<SUB_ID>
The subscription ID for your Log Analytics workspace enabled for Microsoft Sentinel
<RESOURCE_GROUP_NAME>
The resource group name for your Log Analytics workspace enabled for Microsoft Sentinel
<WS_NAME>
The name of your Log Analytics workspace enabled for Microsoft Sentinel
<AGENT_IDENTIFIER>
The agent ID displayed after running the command in the previous step.
Run the following command to configure the Docker container to start automatically.
The deployment procedure generates a systemconfig.json file that contains the configuration details for the SAP data connector agent. The file is located in the /sapcon-app/sapcon/config/system directory on your VM.
Prepare the kickstart script for secure communication with SNC
This procedure describes how to prepare the deployment script to configure settings for secure communications with your SAP system using SNC. If you're using SNC, you must perform this procedure before deploying the data connector agent.
To configure the container for secure communication with SNC:
Transfer the libsapcrypto.so and sapgenpse files to the system where you're creating the container.
Transfer the client certificate, including both private and public keys to the system where you're creating the container.
The client certificate and key can be in .p12, .pfx, or Base64 .crt and .key format.
Transfer the server certificate (public key only) to the system where you're creating the container.
The server certificate must be in Base64 .crt format.
If the client certificate was issued by an enterprise certification authority, transfer the issuing CA and root CA certificates to the system where you're creating the container.
Get the kickstart script from the Microsoft Sentinel GitHub repository:
For optimal results in monitoring the SAP PAHI table, open the systemconfig.json file for editing and under the [ABAP Table Selector](reference-systemconfig-json.md#abap-table-selector) section, enable both the PAHI_FULL and the PAHI_INCREMENTAL parameters.
This module covers the configuration of the Azure Enhanced Monitoring Extension for SAP. Prepare for Exam AZ-120 Planning and Administering Microsoft Azure for SAP Workloads.