Run the following command to create a service principal and assign it the \"Reader\" role (sufficient for discovery and read-only access to resources). It's better to limit the scope to specific resources but it's not mandatory. Ensure that you replace with your actual Azure subscription ID: az ad sp create-for-rbac --name \"AppControlServicePrincipal\" --role Reader --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>\n
- Output: The command will return a JSON object containing:
AppId (Client ID) Password (Client secret) Tenant (Tenant ID) Subscription ID (Subscription scope where the role is assigned) Save this information securely as it will be required for configuring AppControl.
Step 2: Assign Permissions (OPTIONAL)
If you need to limit the service principal's permissions to specific resource groups, or if you need to grant more access (such as managing resources), you can assign additional roles. For example, to restrict access to specific resource groups, use this command:
az role assignment create \\\n --role Reader \\\n --assignee <AppId> \\\n --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>\n
Step 3: Configure AppControl with the Service Principal Credentials
Once you\u2019ve created the Service Principal, you need to provide the credentials to AppControl for authentication.
- Navigate to Overview/New application and select Discover your infrastructure.
- Choose From Azure
- Enter the Client User Name, Client Password (obtained when creating the Service Principal), Tenant ID, Subscription ID and Tenant ID.
AppControl will use these credentials to authenticate with Azure and retrieve your resources.
This feature empowers you to visualize and manage your entire Azure infrastructure directly from AppControl, ensuring real-time control over your cloud assets.
"},{"location":"repo/","title":"Git integration","text":"AppControl YAML or XML files can be conveniently stored in a Git repository for version control and collaboration. Additionally, you can display the live status of your application directly in your documentation by adding a markdown badge link. For example:
\n
This badge will display the real-time status of your application in your documentation.
"},{"location":"repo/#automating-application-deployment-with-appcontrol-apis","title":"Automating Application Deployment with AppControl APIs","text":"AppControl provides powerful APIs that allow for automatic deployment of applications through custom scripts. These scripts can be integrated into your CI/CD pipelines or used for ad-hoc deployments. Below is a generic example of a script that loads and deploys an application map (in YAML or XML format) to AppControl.
Sample Deployment Script
#!/usr/bin/env bash\nset -o errexit\nset -o nounset\n\n# API endpoint for AppControl\nexport API=${APPCONTROL_HOME:-https://appcontrol.xcomponent.com}/core\n\ndebug() {\n [[ \"${DEBUG:-0}\" != \"0\" ]] && echo \"$@\"\n}\n\nmain() {\n # Check if the required parameters are passed\n if [[ $# -lt 2 ]]; then\n echo \"Usage: $0 <map-file> <gateway-name>\"\n exit 1\n fi\n\n local mapFile=\"$1\"\n local agentProxyName=\"$2\"\n local mapFileContents=$(cat \"$mapFile\")\n\n # Extract application name and version from the map file (XML or YAML)\n local mapName=$(grep \"<app name\" \"$mapFile\" | cut -d \"\\\"\" -f2)\n local mapVersion=$(grep \"<app name\" \"$mapFile\" | cut -d \"\\\"\" -f4)\n local escapedMapFileContents\n\n # Check if XML parsing failed (if mapName or mapVersion is empty, fallback to YAML)\n if [[ -z \"$mapName\" ]] || [[ -z \"$mapVersion\" ]]; then\n echo \"XML parsing failed or not XML format. Trying YAML...\"\n\n # Attempt to read the file as YAML using yq\n mapName=$(yq e '.Name' \"$mapFile\")\n mapVersion=$(yq e '.Version' \"$mapFile\")\n\n if [[ -z \"$mapName\" ]] || [[ -z \"$mapVersion\" ]]; then\n echo \"YAML parsing failed. Please check the file format.\"\n exit 1\n fi\n fi\n\n # Escape file contents to be used in the JSON payload\n escapedMapFileContents=$(echo \"$mapFileContents\" | jq -aRs .)\n\n # Prepare the data payload for the API\n data=$(jq -n --arg xml \"$escapedMapFileContents\" \\\n --arg app \"$mapName\" \\\n --arg version \"$mapVersion\" \\\n --arg gateway \"$agentProxyName\" \\\n '{\n Xml: $xml,\n Application: $app,\n Version: $version,\n AgentProxyName: $gateway,\n LoadMap: \"true\",\n OverWrite: \"true\",\n UseDefaultAgent: \"false\"\n }')\n\n echo \"Loading $mapName $mapVersion using gateway $agentProxyName...\"\n\n # Send the API request\n curl $API/api/Configuration -X PUT \\\n --header \"Content-Type: application/json\" \\\n --header \"Authorization: bearer $AUTH\" \\\n --data-binary \"$data\" \\\n --fail\n}\n\nmain \"$@\"\n\n
Example of usage
./deploy_app.sh myapp.yaml Azure_Gateway\n
This script will upload the myapp.yaml file and use the specified gateway (Azure_Gateway).
"},{"location":"standalone/","title":"Running AppControl Locally with Docker Compose","text":"This package lets you install and run Invivoo's X4B AppControl software locally on a Windows PC. To install X4B AppControl in standalone under Windows OS, unzip the following file into an installation directory, and move into that directory.
"},{"location":"standalone/#appcontrol-license-and-usage-terms","title":"AppControl License and Usage Terms","text":"AppControl is free to use for educational purposes. For production use, please contact Invivoo.
"},{"location":"standalone/#installing-appcontrol-locally","title":"Installing AppControl Locally","text":"The AppControl software is delivered as a set of container images, meant to be run inside a container orchestrator such as Kubernetes or Red Hat's OpenShift. Invivoo provides Helm charts for this installation, which is the recommended deployment method for production environments.
For a newcomer discovering AppControl for the first time, Invivoo is providing this deployment method, using Docker Compose, to make it easy to quickly set up an AppControl instance locally, on your laptop, and immediately start exploring its possibilities.
AppControl includes a gateway and agents that will let you manage any system, local or remote, from this local instance. Conversely, remote workstations will also be able to access and use this instance, meaning the AppControl web-based UI will be accessible from every machine on your network.
Note that this setup is NOT recommended for production deployments.
"},{"location":"standalone/#requirements","title":"Requirements","text":"You will need Docker Desktop on your PC. Invivoo recommends choosing WSL 2 over Hyper-V for the Linux virtualization (see installation instructions below).
You will need at least 16 Gb of RAM and 5 Gb of available disk space.
"},{"location":"standalone/#installation-instructions","title":"Installation Instructions","text":""},{"location":"standalone/#docker-desktop","title":"Docker Desktop","text":"To install the latest version of Docker Desktop, follow the instructions on their website.
In the System Requirements section, choose WSL 2 backend, and follow the instructions from Microsoft to enable the feature and install WSL.
"},{"location":"standalone/#appcontrol-with-docker-compose","title":"AppControl with Docker Compose","text":"Docker Compose is a tool for defining and running multi-container Docker applications. Invivoo provides the appcontrol.yml file to configure AppControl's services. This lets you create and start all the services with a single command.
Make sure that Docker Desktop is started. Open a command line tool (a normal one, administrator rights are not required), and run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml up -d\n
The command will start by retrieving all the required container images from Invivoo's DockerHub repository, this may take a few minutes. After that, the containers are started with the docker run command. Subsequent runs will reuse the locally-stored images.
When the command has finished executing, you should see an output similar to this:
- Network appcontrol-compose_default Created 0.8s\n - Container appcontrol-compose-rabbit-1 Started 8.4s\n - Container appcontrol-compose-gateway-1 Started 8.5s\n - Container appcontrol-compose-agentdebian-1 Started 8.9s\n - Container appcontrol-compose-login-1 Started 8.9s\n - Container appcontrol-compose-sql-1 Started 9.0s\n - Container appcontrol-compose-redis-1 Started 8.3s\n - Container appcontrol-compose-webapp-1 Started 8.8s\n - Container appcontrol-compose-notification-1 Started 12.6s\n - Container appcontrol-compose-api-1 Started 15.8s\n - Container appcontrol-compose-configvalidator-1 Started 12.2s\n - Container appcontrol-compose-agentmanager-bridge-1 Started 15.3s\n - Container appcontrol-compose-dbaccess-1 Started 13.7s\n - Container appcontrol-compose-scheduler-1 Started 14.5s\n - Container appcontrol-compose-launcher-1 Started 14.8s\n - Container appcontrol-compose-launcher-dispatcher-1 Started 10.3s\n - Container appcontrol-compose-statistics-1 Started 14.4s\n - Container appcontrol-compose-agentmanager-1 Started 15.2s\n - Container appcontrol-compose-agentstatus-1 Started 15.3s\n - Container appcontrol-compose-apps-1 Started 17.3s\n - Container appcontrol-compose-authentication-1 Started 21.0s\n
The AppControl services are up and running.
"},{"location":"standalone/#using-the-web-interface","title":"Using the Web Interface","text":"In your web browser, navigate to http://localhost:4000 to access the AppControl webapp. Use the following credentials to login:
- login:
admin - password:
KoordinatorAdmin
"},{"location":"standalone/#getting-help","title":"Getting Help","text":"Once you're logged into AppControl, you can access the online documentation through the help button (?) on the top right of the screen:
The dropdown menu also lets you contact Invivoo support through email, and join our Slack channel for access to the development team.
"},{"location":"standalone/#test-appcontrol-with-the-helloworld-map","title":"Test AppControl with the Helloworld map","text":"The installation package includes a sample AppControl map to help you get started. In the webapp, import the sample map by clicking on the New application button and uploading the file called hellowworld,v1.xml.
Here's a tutorial video to help you get started: Helloworld tutorial
"},{"location":"standalone/#stop-uninstall-appcontrol","title":"Stop / Uninstall AppControl","text":"Run the following command to stop AppControl:
docker-compose -f appcontrol.yml -f appcontrol-images.yml stop\n
If you want to start again, run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml up -d\n
To completely remove AppControl, run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml rm\n
"},{"location":"x4bcli/","title":"Introduction","text":"To fully utilize AppControl's capabilities with on-premises infrastructure, the X4B Gateway is required. The gateway facilitates secure communication between your on-premises agents and the AppControl SaaS platform. This allows for real-time monitoring and control of your local applications, even when agents are deployed across diverse environments.
X4B Gateway Overview The X4B Gateway acts as a secure link, enabling AppControl to interact with agents deployed on your local infrastructure. The gateway ensures that actions, incidents, and monitoring data are reliably communicated between the agents and the SaaS platform.
Agent Deployment Agents can be deployed anywhere within your Information System (I.S.) to manage and monitor your local applications. One of the key benefits of the AppControl agent architecture is that agents do not require direct internet access. The agents communicate with the X4B Gateway, which handles secure data transfer to the AppControl SaaS platform.
Getting Started with Agents To begin using agents in your local infrastructure, please refer to the Agents Installation section for step-by-step instructions on installing agents on Windows and Linux environments.
Please refer to the Agents Installation section for detailed installation instructions.
Thanks to the X4B Gateway, you can deploy your applications in the AppControl Cloud Platform while keeping agents deployed on-premises.
"},{"location":"x4bcli/#quick-deployment-of-agents-and-gateways-windows-and-macos","title":"Quick Deployment of Agents and Gateways (Windows and macOS)","text":"For both Windows and macOS, there is a quick and efficient way to deploy both agents and the X4B Gateway at the same time. This process requires administrative permissions and will prompt the user to log in to the SaaS platform to link the gateway with their user account.
"},{"location":"x4bcli/#windows-deployment","title":"Windows Deployment","text":"To deploy the agent and gateway on Windows, use the following PowerShell script:
irm https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/docs/en/scripts/appcontrolinstall.ps1 | iex\n
This script will:
- Install the agent and the X4B Gateway on your local machine.
- Prompt you to log in to the AppControl SaaS platform during installation to link the gateway with your user account.
"},{"location":"x4bcli/#macos-deployment","title":"macOS Deployment","text":"To deploy the agent and gateway on macOS, use the following bash script:
bash -c \"$(curl -fsSL https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/docs/en/scripts/appcontrolinstallmac.sh)\"\n
This script will:
- Install the agent and the X4B Gateway on your macOS system.
- Prompt you to log in to the AppControl SaaS platform during installation to link the gateway with your user account.
Important Notes:
- Administrative permissions are required to execute these scripts.
- The user will be prompted to log in during the installation process to complete the linkage between the gateway and the user account in the AppControl SaaS platform.
For more detailed steps on the installation and troubleshooting, please refer to the Agents Installation section.
"},{"location":"x4bcli/#x4b-gateway-custom-installation","title":"X4B Gateway custom installation","text":"Gateways are available for Windows and Docker. For Windows, the .NET framework is required. The X4B Gateway is necessary to take advantage of agents deployed on-premises.
Agents can be deployed anywhere in your infrastructure. They do not need internet access.
Please refer to the agents installation section for detailed instructions on agent installation.
"},{"location":"x4bcli/#latest-available-versions","title":"Latest Available Versions","text":"Operating System Format Latest Version Microsoft Windows zip Windows Gateway Zip N/A docker docker pull xcomponent/x4b-gateway:latest"},{"location":"x4bcli/#how-does-it-work","title":"How does it work ?","text":"The first step is to log in and navigate to this page: AppControl.
-
Click on Register New Gateway
-
Provide a name for your gateway and confirm.
-
Once your gateway is created, an Access Key and a Secret Access Key will be generated.
-
Now, you're ready to install the X4B Gateway. Please refer to the documentation below for the installation procedure.
-
Since the X4B Gateway communicates with agents, you'll need to install at least one agent.
-
Once your X4B Gateway and agent are up and running, you\u2019re ready to deploy a new application.
"},{"location":"x4bcli/#retrieving-x4b-gateway-credentials","title":"Retrieving X4B Gateway Credentials","text":"The first step is to retrieve the X4B Gateway credentials. Navigate to the Gateway page and note the following information:
- Name
- Access Key
-
Secret Access Key
"},{"location":"x4bcli/#microsoft-windows-platform-installation","title":"Microsoft Windows Platform Installation","text":"On Microsoft Windows, the .NET Framework 4.7.2 or later is required.
In most cases, it is already installed. Unzip the following file.
The quickest method is to execute the following command in a PowerShell window with administrative permissions. This command will install the gateway and the agent as Windows services:
irm https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/scripts/appcontrolinstall.ps1 | iex\n
Note:
For the other installation procedures mentioned above, we recommend using cmd.exe as the shell to install the gateway and the agent. We do not support installation via PowerShell.\n
On a prompt (cmd.exe), execute the following command line. Replace MY_ACCESS_KEY, MY_SECRET_ACCESSKEY and MY_GATEWAY_NAME with the suitable values.
c:\\x4b> x4b run gateway -a MY_ACCESS_KEY -k MY_SECRET_ACCESSKEY -p MY_GATEWAY_NAME [-l Trace]\n
You can also, set the following environment variables:
c:\\x4b> set X4B_ACCESS_KEY = MY_ACCESS_KEY\nc:\\x4b> set X4B_SECRET_ACCESS_KEY = MY_SECRET_ACCESSKEY\nc:\\x4b> set X4B_PROXY_NAME = MY_GATEWAY_NAME\n
If the configuration is correct, you should see the following lines in the terminal:
__ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2021\n25/02/2021 09:15:20# X4B Gateway is up and running... (Press Ctrl+C to exit)\n25/02/2021 09:15:21# Waiting for websocket connection\n25/02/2021 09:15:39# HeartBeat successfully published\n25/02/2021 09:15:39# Websocket connection established\n\n
"},{"location":"x4bcli/#microsoft-windows-service-installation","title":"Microsoft Windows service Installation","text":"In a prompt with administrative permissions:
c:\\x4b> x4b install -servicename x4bGatewayServiceName -server \"https://appcontrol.xcomponent.com/core\" -loglevel \"Trace\" -access \"myAccesToken\" -proxyname \"myGatewayName\" -secret \"mySecretToken\"\n
The first parameters to register the gateway as a service is the topshelf syntax:
Topshelf Command-Line Reference \u2014 Topshelf 3.0 documentation
The following parameters are specific to the gateway:
-server \"https://appcontrol.xcomponent.com/core\" -loglevel \"Trace\" -access \"myAccesToken\" -proxyname \"myGatewayName\" -secret \"mySecretToken\"
"},{"location":"x4bcli/#docker-installation","title":"Docker Installation","text":"The docker image is available on docker hub: x4b-gateway
docker run -e X4B_ACCESS_KEY=MY_ACCESS_KEY -e X4B_SECRET_ACCESS_KEY=MY_SECRET_ACCESSKEY -e X4B_PROXY_NAME=MY_GATEWAY_NAME xcomponent/x4b-gateway:latest\n
If the configuration is correct, you should observe the following lines in the terminal:
__ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2021\n25/02/2021 09:15:20# X4B Proxy is up and running... (Press Ctrl+C to exit)\n25/02/2021 09:15:21# Waiting for websocket connection\n25/02/2021 09:15:39# HeartBeat successfully published\n25/02/2021 09:15:39# Websocket connection established\n\n
"},{"location":"x4bcli/#display-environment-variables","title":"Display environment variables","text":"c:\\x4b>x4b env\n
"},{"location":"x4bcli/#install-and-run-the-gateway-with-docker-and-builtin-command-of-the-gateway","title":"Install and run the gateway with docker and builtin command of the gateway","text":"c:\\x4b>x4b run docker -a|--accesskey <accesskey> -k|--secretaccesskey <secretaccesskey> -p|--gatewayname <gatewayname> [-l|--loglevel <loglevel>] [-i|--imagetag <imagetag>] [-u|--urlserver <urlserver>]\n
"},{"location":"x4bcli/#remove-appcontrol-gateway-service-from-the-workstation","title":"Remove Appcontrol Gateway service from the workstation","text":"c:\\x4b>x4b uninstall -servicename x4bGatewayServiceName\n
"},{"location":"x4bcli/#remove-appcontrol-gateway-container-running-with-docker","title":"Remove Appcontrol Gateway container running with Docker","text":"c:\\x4b>x4b uninstall docker -c|--containername MY_GATEWAY_NAME\n
"},{"location":"x4bcli/#display-help","title":"Display Help","text":"x4b -v|--version x4b [command] -h x4b subcommand [command] -h|--help
c:\\x4b>x4b -h // display list of commands available\nc:\\x4b>x4b run -h // display help for command run\nc:\\x4b>x4b run docker -h //display help for the subcommand\nc:\\x4b>x4b run gateway -h // display help for the subcommand\nc:\\x4b>x4b uninstall docker -h // display help for this specific command\n
"},{"location":"x4bcli/#check-appcontrols-agent-communication","title":"Check AppControl's Agent Communication","text":"The gateway can also be useful for checking if the agent is up and running. Agents can be deployed on the same computer as the gateway or elsewhere on the network.
For example, if you have deployed an agent on the host myhost and the gateway is deployed elsewhere in the network, open cmd.exe and enter the following command:
c:\\x4b>x4b run interactive --host myhost\n
This is the list of allowed parameters:
Parameters Description Example --host Agent host name x4b run interactive --host MYHOST --port Agent port value x4b run interactive --host MYHOST --port 12345 --ssl Ssl protocol: Tls, Tls12, Tls13 x4b run interactive --host MYHOST --port 12345 --ssl Tls12 --loglevel Log Level: Error, Info, Trace x4b run interactive --host MYHOST --port 12345 --ssl Tls12 --loglevel Error If the gateway can't reach the agent, you will obtain the following output:
c:\\x4b>x4b run interactive --host myhost\nLaunching gateway in interactive mode...\n __ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2023\n\n12/09/2023 17:08:52# X4B Gateway is up and running... (Press Ctrl+C to exit)\n\n12/09/2023 17:08:55# Connection to agent fails - Retrying in few seconds...\n
If the gateway is able to reach the agent, you will obtain the following output:
C:\\>x4b run interactive --host localhost\nLaunching gateway in interactive mode...\n __ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2023\n\n12/09/2023 17:11:53# X4B Gateway is up and running... (Press Ctrl+C to exit)\n\n12/09/2023 17:11:54# Connection to agent established\n\n12/09/2023 17:11:54#\n***************************************\nAgent configuration:\nVersion=26.0\nPlatform=Windows\nCpu Usage=15%\nnetworkAddress=0.0.0.0\nport=12567\nlogdirectory=C:\\tools\\appcontrol\\xcAgent-binary\\./logs\ntempdirectory=C:\\Windows\\TEMP\nmaxlogsizeinmo=5\nnbdaystodeletelogs=10\nredirecterroutput=1\nexecutionthreshold=200\nloglevel=TRACE\ntrustedservers=\nsslprotocol=tls12\nsshkeydirectory\nshell=\nignoretrustedservers=false\nserviceaccount=\nwindows Interpreter=C:\\Windows\\system32\\cmd.exe\n\n***************************************\n\nappControlAgent@localhost %\n
The gateway is able to reach both Linux and Windows agents.
Once connected, you can execute commands on the agent's host. For example, you can use cd, dir, more for Windows, or pwd, ls, cat for Linux.
The commands are executed by the default shell, which is cmd.exe for Windows and sh or bash for Linux.
Example with a Windows agent:
appControlAgent@localhost % dir\n\n R\u00e9pertoire de C:\\tmp\\test\\xcAgent-binary-Win32\n\n12/09/2023 17:31 <DIR> .\n12/09/2023 17:31 <DIR> ..\n11/09/2023 14:15 940 config.dat\n11/09/2023 14:31 87 install.bat\n26/03/2018 23:45 2?094?592 libcrypto-1_1.dll\n26/03/2018 23:45 375?808 libssl-1_1.dll\n12/09/2023 17:32 <DIR> logs\n26/03/2018 23:45 970?912 msvcr120.dll\n11/09/2023 14:29 953?856 xcAgent.exe\n 6 fichier(s) 4?396?195 octets\n 3 R?p(s) 96?394?911?744 octets libres\n\nappControlAgent@localhost C:\\tmp\\test\\xcAgent-binary-Win32% powershell -c cat config.dat\n\n12/09/2023 17:35:25# <!-- XComponent APP Control Agent Configuration file -->\n<config>\n <item key=\"generatebatch\" value=\"false\" />\n <item key=\"windowsinterpreter\" value=\"%ComSpec%\" />\n <item key=\"networkAddress\" value=\"0.0.0.0\" />\n <item key=\"port\" value=\"12567\" />\n <item key=\"logdirectory\" value=\"./logs\" />\n <item key=\"tempdirectory\" value=\"%TEMP%\" />\n <item key=\"maxlogsizeinmo\" value=\"5\" />\n <item key=\"nbdaystodeletelogs\" value=\"10\" />\n <item key=\"redirecterroutput\" value=\"true\" />\n <item key=\"logToStandardOutput\" value=\"true\" />\n <item key=\"executionthreshold\" value=\"200\" />\n <item key=\"loglevel\" value=\"TRACE\" /> <!-- NONE, INFO, TRACE, ERROR -->\n <item key=\"trustedservers\" value=\"\" />\n <item key=\"ignoretrustedservers\" value=\"false\" />\n <item key=\"sslprotocol\" value=\"tls12\" /> <!-- ssl, tls, tls12, tls13 -->\n <item key=\"sshkeydirectory\" value=\"\" /> <!-- Linux Only -->\n <item key=\"shell\" value=\"\" />\n</config>\n\nappControlAgent@localhost C:\\tmp\\test\\xcAgent-binary-Win32%\n
Example with debian's agent:
appControlAgent@macbook % ls\n\n12/09/2023 17:36:56# config.dat\nconfig_env.dat\nlibs\nlogs\nrun.sh\ntmp\nxcAgent.bin\n\nappControlAgent@macbook /usr/src/app/xcagent% cat config.dat\n\n12/09/2023 17:37:23# <!-- XComponent APP Control Agent Configuration file -->\n<config>\n <item key=\"networkAddress\" value=\"0.0.0.0\" />\n <!--TCP listening port of the agent -->\n <item key=\"port\" value=\"12567\" />\n <item key=\"generatebatch\" value=\"true\" />\n <!--Logs and Tmp directories-->\n <item key=\"logdirectory\" value=\"logs\" />\n <item key=\"tempdirectory\" value=\"tmp\" />\n <item key=\"maxlogsizeinmo\" value=\"5\" />\n <item key=\"nbdaystodeletelogs\" value=\"10\" />\n <item key=\"redirecterroutput\" value=\"true\" />\n <item key=\"executionthreshold\" value=\"50\" />\n <item key=\"logToStandardOutput\" value=\"true\" />\n <item key=\"loglevel\" value=\"TRACE\" /> <!-- NONE, INFO, TRACE, ERROR -->\n <!-- IP address of SSH serveur (unix/linux) -->\n <item key=\"sshhost\" value=\"127.0.0.1\" />\n <!-- IP Address or DNS Names of AC2 servers authorized to communicate with the agent -->\n <item key=\"trustedservers\" value=\"\" />\n <item key=\"sslprotocol\" value=\"tls12\" /> <!-- ssl, tls, tls12 -->\n <item key=\"sshkeydirectory\" value=\"\" /> <!-- Linux Only -->\n <item key=\"shell\" value=\"\" />\n</config>\nappControlAgent@macbook /usr/src/app/xcagent%\n
"},{"location":"Getting%20Started/","title":"Get Started","text":" - Go to the XComponent AppControl website.
- Log in using a social provider
- You're done! You can now get started with AppControl
In the example section, copy the following link to the demo application: demo application.
On the AppControl website, go to the Import Application and paste the link of the demo application.
Follow the wizard (clicking on 'Next' button). In the 'Gateway' tab select 'X4B SaaS'. On the last tab click on 'Import'.
Go the 'Overview', and select the helloworld application by clicking on the checkbox. Then click on the load button.
Next, click on the 'Architecture' button:
Using, the command bar, you can now start/stop the Hello World application with ease.
"},{"location":"Getting%20Started/appcontrol_worker/","title":"Contents","text":"This document describes how to use AppControl to execute a script or program as a task in XC Scenario. It shows how to define the script invocation in an AppControl map, how to test it directly from AppControl, and finally how to use it from Scenario.
"},{"location":"Getting%20Started/appcontrol_worker/#benefits-of-using-appcontrol","title":"Benefits of using AppControl","text":"There are many advantages to running scripts through AppControl, as opposed to running them directly from a worker task:
-
the use of an AppControl agent for execution makes it easy to run scripts on remote machines, without requiring the script author to manage remote connections and logins himself
-
executions through AppControl will benefit from monitoring and supervision by the production support team
-
defining script calls in an AppControl map allows for better tracking and management of the script code base
"},{"location":"Getting%20Started/appcontrol_worker/#pre-requisites","title":"Pre-requisites","text":"This document assumes that you have access to a working X4B installation, either Invivoo's SaaS platform, or an X4B platform deployed on your premises.
This includes XC Scenario, XC AppControl, and an AppControl worker (detailed below) deployed and configured to interact with this AppControl instance. Contact the administrator of your X4B platform to make sure that all the required components are available and properly configured.
"},{"location":"Getting%20Started/appcontrol_worker/#appcontrol-worker","title":"AppControl Worker","text":"The AppControl worker is a standalone program that acts as a worker program for Scenario:
- it publishes a catalog of tasks
- it polls the task queue for tasks to execute
- it runs tasks and posts task statuses
Unlike other worker programs that implement their own tasks, the AppControl worker:
- gets its list of tasks from custom actions in AppControl maps
- runs tasks by calling custom actions that get executed by an AppControl agent
The AppControl worker must be configured to communicate with an AppControl server through a gateway, which is defined inside AppControl, and is associated with a specific AppControl user.
"},{"location":"Getting%20Started/appcontrol_worker/#defining-scripts-for-the-appcontrol-worker","title":"Defining scripts for the AppControl worker","text":"Scripts that are meant to be used with the AppControl worker need to be defined inside an AppControl map, as custom actions attached to some AppControl component.
"},{"location":"Getting%20Started/appcontrol_worker/#custom-actions","title":"Custom actions","text":"A custom action is defined by an action element (inside a component element) with a name=\"custom\" attribute. Other important attributes are commandname, which lets you identify each custom action, and value, which holds the actual command to execute.
The contents of the value attribute are sent to the AppControl agent for execution, so the platform where the agent is running determines the actual shell script language to use, Windows command/batch script or linux/unix-like shell script.
The action element can have parameters and outputParameters sub-elements, for input and output parameters, respectively.
The action element also has a visibility attribute, which controls whether the action is accessible from outside AppControl or not. The AppControl worker only retrieves public tasks, so if a custiom action is to be used with Scenario, it is mandatory to specify visibility=\"public\".
See the AppControl map documentation for more details.
"},{"location":"Getting%20Started/appcontrol_worker/#example","title":"Example","text":"The following XML snippet is an excerpt from an AppControl map that defines a component named \"comp\" (you can find the map file here). This component has a check action (mandatory) and two custom actions named calc and prod_div.
<component name=\"comp\" description=\"Script execution component\" hostref=\"LOCAL\" authref=\"LOCAL\" redirectoutput=\"false\" type=\"file\">\n <action value=\"echo 1\" name=\"check\" />\n\n <action value=\"C:\\a\\bin\\calc_script.cmd $(arg)\" commandname=\"calc\" name=\"custom\" visibility=\"public\">\n <parameters>\n <parameter name=\"arg\" value=\"\" canedit=\"true\" validation=\"*\" />\n </parameters>\n </action>\n\n <action value=\"py c:\\a\\bin\\pycalc.py $(operand1) $(operand2)\" commandname=\"prod_div\" name=\"custom\" visibility=\"public\">\n <parameters>\n <parameter name=\"operand1\" canedit=\"true\" validation=\"\\d+\" />\n <parameter name=\"operand2\" canedit=\"true\" validation=\"\\d+\" />\n </parameters>\n <outputParameters>\n <parameter name=\"product\" />\n <parameter name=\"division\" />\n </outputParameters>\n </action>\n\n</component>\n
The calc action has a single input parameter named arg, defined in the parameters/parameter element, and referenced with the $(arg) inside the value attribute. This action will run the Windows command line file found at C:\\a\\bin\\calc_script.cmd on the agent's machine, passing it the value of the arg parameter (script file here).
The prod_div action has both input and output parameters. It runs a python script with two input parameters, calculating the product and division of these two operands, and returning those two values. The outputParameters element is used to list the names of the return values, so they can be added to the task's description in the Scenario task catalog, and also identified in the script's output stream (see A script with output parameters below).
"},{"location":"Getting%20Started/appcontrol_worker/#running-custom-actions-in-appcontrol","title":"Running custom actions in AppControl","text":"Once the custom actions have been defined in the map file, as above, the map must be imported into AppControl, using the New button in the UI. Please refer to the AppControl documentation if you need more information on how to use the AppControl UI.
When the Architecture tab is chosen to display the map's graph, the components from the map are shown, and any custom actions defined on them will be found on a dropdown menu accessible through a right-click:
"},{"location":"Getting%20Started/appcontrol_worker/#a-simple-script","title":"A simple script","text":"If we pick the calc action, a dialog box (on the left) shows the command line that will be executed, as well as the arguments that are expected (in this case, the single parameter arg). Enter a value for the argument, and press the Execute Custom Action button. The dialog box (on the right) now displays the status of the execution, which can be InProgess, while it's running, and then Execution Succeeded as shown here when it's finished, with the exit code from the script on the right-hand side.
As scripts usually produce output from their execution by printing to their standard output stream, the AppControl custom action captures that output stream and displays it on the screen, below the green status line. In this case, it's the message calc_script: arg=hello that was printed by the script.
"},{"location":"Getting%20Started/appcontrol_worker/#a-script-with-output-parameters","title":"A script with output parameters","text":"A shell script does not have a notion of output parameters. But in many situations, people write code that produces results, and we want to retrieve those results, either for displaying in the AppControl UI, or for communicating them to Scenario so they can be used by other tasks.
This second example, the prod_div action, illustrates this use case with a python script that returns two output parameters, and it explains the particular syntax that's used, in the script's standard output stream, to represent return values so Scenario get use them.
The pycalc script (source code here) calls a python function that calculates the product and division of its two operands. If we pick the prod_div action in AppControl, the dialog box will shows us the command line and input arguments (operand1, operand2), and after executing the action, we'll also see the standard output, as before.
However, in this case, we see that the standard output has a very specific format:
<appcontrol>\n {\n 'Message': 'pycalc: success.',\n 'OutputValues': {\n 'product': 72,\n 'division': 8.0,\n }\n }\n</appcontrol>\n
Inside the <appcontrol> tags is an object with json/javascript syntax, that is meant to be interpreted by the AppControl worker:
-
the Message property holds some text that will be displayed in the Scenario UI, so it should be some kind of summary or resulting status from the script's execution.
-
the OutputValues property is a dictionary of the output parameters. It must match the set of parameters listed in the outputParameters element of the AppControl map (see Custom action example above), and the values must be filled in by the script.
"},{"location":"Getting%20Started/appcontrol_worker/#running-scriptscustom-actions-in-scenario","title":"Running scripts/custom actions in Scenario","text":"So far, we've seen how to define our scripts in the AppControl map, and how to run them from the AppControl UI. This section deals with using those scripts inside Scenario.
If everything has been set up correctly by your administrator, as described in Pre-requisites above, importing and loading (activating) the map that defines your scripts is enough to make them available in Scenario. The AppControl worker publishes all the custom actions from your map as Scenario tasks, in a namespace called AppControl.
"},{"location":"Getting%20Started/appcontrol_worker/#using-the-script-as-a-scenario-task","title":"Using the script as a Scenario task","text":"In the Scenario designer, when creating or modifying a scenario definition, drag and drop an automatic task object (the one with the gears icon, called Task), and select the AppControl namespace in the Task Parameters panel. In the list of tasks, you can see two tasks from the map,v1.xml file, with names:
- map,v1@admin__comp_calc
- map,v1@admin__comp_prod_div
The structure of these names reflects the AppControl artifacts: <map>@<user>__<component>_<action>. These actions are now available, like any other task, to be used in your scenario.
Select the prod_div task, enter values for operands 1 and 2, and then run the scenario. In the cockpit, you can see the output values and the message, just as we saw in the AppControl UI above:
"},{"location":"Getting%20Started/appcontrol_worker/dynamicmapinformations/","title":"Dynamic informations","text":"An application, is a set of components defined statically with an xml format (cf: Create an application). Nevertheless, the application can be enriched with dynamic informations. Dynamic informations are returned by the 'check' command.
To return dynamic informations the 'check' command should log on the standard output some informations. The informations should respect the following format:
<appcontrol> APPCONTROL JSON OBJECT </appcontrol>\n
Dynamic informations can enrich the content of the component owning the 'check'. In dynamic informations start/stop commands are not allowed.
The JSON format is the following:
{\n \"link\": \"Hyperlink to wathever you want\", //Optional\n \"name\": \"Name of the component\", //Required\n \"displayName\": \"Display name\", //Optional\n \"state\": \" Initializing | \n InError |\n Start |\n Starting |\n Started |\n Stop |\n Stopping |\n Stopped \", //Optional\n \"parents\": //Optional but highly recommanded\n [\n \"Parent1\",\n \"Parent2\",\n ],\n \"exitCode\": 256, //Optional\n \"color\": \"Color of the code RGB format or hexa code ('255,255,255' or #FFFFFF\", //Optional\n \"Type\": \" Used to display an icon on the map. An url to an image (png, jpeg or svg) can be set. Anyway you can use one of the following value: browser, cd, chip, data-information, devises, dollar, euro, file, green-thermometer, hdd, memflash, memory, middleware, network, orange-thermometer, pounds, process, service, tools, user, yen\", //Optional\n \"groupName\": \"Name of the group\", //Optional\n \"customActions\": //Optional\n [\n {\n \"visibility\": \"Private\",\n \"customActionName\": \"echo Action\",\n \"customActionDescription\": null,\n \"customActionCommandLine\": \"echo $(message)\",\n \"parallelCustomAction\": false,\n \"parameters\":\n [\n {\n \"parameterName\":\"message\",\n \"description\": \"\",\n \"defaultValue\": \"Welcome message\",\n \"validationRule\": \"*\",\n \"isEditable\": true\n }\n ]\n }\n ],\n \"filters\": {\"filter name 1\": [\"filter values\"] ,\n \"filter name 2\": [\"filter values\"]\n } //Optional,\n \"dynamicTree\" : [\n {\n //A json object with the properties defined above\n }\n ] //Optional,\n}\n
A full example is available in this documentation: - Application Xml - JSON dynamic data
The application should be tested this way.
- First copy this the link to the application: Application
- Go to the New Application menu and import the previous application
- Once the application is loaded go to the Architecture menu, you should obtain the following rendering:
On the above screenshot, you can observe that dynamic components are displayed with an 'octagon form' whereas the 'static component' is displayed with a 'square form'.
"},{"location":"openfaas/synchronous/","title":"Contents","text":"This document describes how to write a simple, synchronous python function that is run inside OpenFaas, and that can be invoked from XC Scenario to implement a scenario task. It details the integration with OpenFaas and the mechanics of making your function available on the server. A separate document will address the case of an asynchronous function.
Note that OpenFaas supports writing functions in many programming languages other than python, please have a look at the official OpenFaas documentation for more information.
Part of this document is based on the OpenFaas First Python Function tutorial.
"},{"location":"openfaas/synchronous/#openfaas-and-cli-installation","title":"OpenFaas and CLI Installation","text":"This document assumes that you have a working OpenFaas installation, and you will need to provide the URL for it. Contact an administrator if you don't have this information. In our example, we'll be using https://openfaas.xcomponent.com as the url for our OpenFaas server, or gateway.
As part of the OpenFaas installation, the faas-cli executable should be in your path. This is OpenFaas' command-line interface (CLI), and it is required to perform a number of tasks, including building and deploying your functions, so a set of valid credentials must be configured for it. Again, if needed, contact the administrator responsible for your OpenFaas installation.
"},{"location":"openfaas/synchronous/#write-a-simple-function","title":"Write a simple function","text":""},{"location":"openfaas/synchronous/#initialize-the-work-environment","title":"Initialize the work environment","text":"Create a working directory and move into it. Now scaffold a new Python function using the CLI:
faas-cli new --lang python3 pyfunc\n
This retrieves a set of templates from GitHub, if needed, then creates the following files:
pyfunc/handler.py\npyfunc/requirements.txt\npyfunc.yml\n
Again, this example uses python. Have a look at this page to see what other languages are available.
Note that for a single language, many templates may be available. The default for python is to use the Classic Watchdog, but the above link lists many others.
"},{"location":"openfaas/synchronous/#pyfuncyml","title":"pyfunc.yml","text":"This yaml file specifies your functions, and the OpenFaas gateway to use. The faas-cli new command has already filled in most of this file:
version: 1.0\nprovider:\n name: openfaas\n gateway: http://127.0.0.1:8080\nfunctions:\n pyfunc:\n lang: python3\n handler: ./pyfunc\n image: pyfunc:latest\n
You only need to change or specify the following items:
- the gateway, i.e. the url of your OpenFaas installation
- the docker image name
- the
com.xcomponent.label property (to be added)
OpenFaas supports running functions from Docker images stored on Docker Hub or in private Docker registries. If you decide to use Docker Hub, as we do in this example, you'll need to include a Docker Hub account as the prefix in the image name (joaomdsc in this case, see below).
If you want to use a private registry for your images, this document has information on how to specify the access credentials.
XC Scenario defines a label (Demo in our example) that is used to filter the functions that will be made available. That label must be referenced here so that your function can be used in XC Scenario. We'll use the labels.com.xcomponent.label property to specify a value, which has to match whatever value was configured in your installation of XC Scenario. Please contact your X4B/Scenario administrator to find out the right label to use here.
After applying these changes, here's what the modified pyfunc.yml file looks like:
version: 1.0\nprovider:\n name: openfaas\n gateway: https://openfaas.xcomponent.com\nfunctions:\n pyfunc:\n lang: python3\n handler: ./pyfunc\n image: joaomdsc/pyfunc:latest\n labels:\n com.xcomponent.label: Demo\n
"},{"location":"openfaas/synchronous/#handlerpy","title":"handler.py","text":"The handler.py file is where the function code will be implemented. It starts out with an almost empty function skeleton:
def handle(req):\n \"\"\"handle a request to the function\n Args:\n req (str): request body\n \"\"\"\n\n return req\n
The function has a single parameter req that will contain the body of the HTTP request through which the function was invoked. The default implementation in the provided template simply returns this string unchanged.
For the time being, we'll keep the function as it is, while we go through the process of making the function available and running it from XC Scenario. Later on, we'll see how to declare input and output parameters to communicate with a running scenario instance, when the function is used to implement a scenario task.
"},{"location":"openfaas/synchronous/#build-the-function","title":"Build the function","text":"Run the following command to build the function:
joao@debian1:~$ faas-cli build -f pyfunc.yml\n
Note: OpenFaas builds a docker image for the function, so make sure that docker is deployed on the machine.
On successful completion, you should see the following message:
Successfully tagged joaomdsc/pyfunc:latest\nImage: joaomdsc/pyfunc:latest built.\n
You can check the presence of the docker image:
docker images\nREPOSITORY TAG IMAGE ID CREATED SIZE\njoaomdsc/pyfunc latest e7f810f4455f 23 minutes ago 62.1MB\n
Now push the image to DockerHub:
joao@debian1:~$ docker push joaomdsc/pyfunc:latest\n
"},{"location":"openfaas/synchronous/#deploy-the-function-to-the-openfaas-server","title":"Deploy the function to the OpenFaas server","text":"You can now deploy the function to the OpenFaas server, using the following command:
joao@debian1:~$ faas-cli deploy -f pyfunc.yml\nDeploying: pyfunc.\n\nDeployed. 202 Accepted.\nURL: https://openfaas.xcomponent.com/function/pyfunc.openfaas-fn\n
Check for the presence of a 202 return code. Also note that it might take a minute or two for your function to be available.
"},{"location":"openfaas/synchronous/#test-the-function","title":"Test the function","text":"You can invoke the function through curl, passing in a request body with the -d argument:
joao@debian1:~$ curl https://openfaas.xcomponent.com/function/pyfunc -d \"Hello!\"\nHello!\njoao@debian1:~$ \n
The text that was passed in is returned by the function.
You can invoke the function through faas-cli:
joao@debian1:~$ echo -n \"Hello!\" | faas-cli -g https://openfaas.xcomponent.com invoke pyfunc\nHello!\njoao@debian1:~$ \n
You can also invoke the function through the OpenFaas portal:
Click on Request body, enter some text (good morning for example), then press Invoke.
"},{"location":"openfaas/synchronous/#use-the-function-in-xc-scenario","title":"Use the function in XC Scenario","text":"Create a new scenario, add a task, and pick the OpenFaas namespace. You should find your new function in the list of tasks on the left (if your function does not appear on the list, the label defined in pyfunc.yml may be incorrect, check with your administrator).
Select pyfunc in the list. Note the DefaultInput field (on the right image), enter some text value (Hello, OpenFaas world! in this example):
Now run the scenario, and check the cockpit. You should see the text you entered displayed in the task output:
"},{"location":"openfaas/synchronous/#write-a-function-with-multiple-parameters","title":"Write a function with multiple parameters","text":"Let's define a second, more realistic function, with input and output parameters. We'll define a function called pyfunc2 that takes two inputs, an integer n and a string txt, and returns two outputs, an integer calc and a string msg.
Repeat the above steps to create a new function called pyfunc2, and apply the following changes.
"},{"location":"openfaas/synchronous/#new-pyfunc2yml","title":"New pyfunc2.yml","text":"In the yaml file, we apply the same changes as before (gateway, image name prefix) but we also add new labels:
version: 1.0\nprovider:\n name: openfaas\n gateway: https://openfaas.xcomponent.com\nfunctions:\n pyfunc2:\n lang: python3\n handler: ./pyfunc2\n image: joaomdsc/pyfunc2:latest\n labels:\n com.xcomponent.label: Demo\n com.xcomponent.inputs.n: Number\n com.xcomponent.inputs.txt: String\n com.xcomponent.outputs.calc: Number\n com.xcomponent.outputs.msg: String\n
The com.xcomponent.inputs properties define function inputs, and com.xcomponent.outputs define function outputs. The parameter name is appended to the property name, and the value indicates the parameter's type.
All the XC Scenario base types can be used : String, Number, Boolean etc.
"},{"location":"openfaas/synchronous/#new-handlerpy","title":"New handler.py","text":"Replace the generated handler.py file with the following content:
import json\n\ndef handle(req):\n \"\"\"handle a request to the function\n Args:\n req (str): request body\n \"\"\"\n\n # De-serialize json, extract input parameters\n obj = json.loads(req)\n n = int(obj['n'])\n txt = obj['txt']\n\n # Implement your function here\n calc = 2*n\n msg = txt.upper()\n\n # Return the output parameters\n result = {\n 'calc': calc,\n 'msg': msg,\n }\n\n return json.dumps(result)\n
XC Scenario calls the OpenFaas functions with a json request body containing the input parameters. The code de-serializes the json data and extracts the two input parameters.
After this step, you can implement whatever processing your function needs to do. In our example, the numeric parameter gets multiplied by 2, and the string parameter is converted to uppercase.
The final step in the code is to return a json string encoding the output parameters defined in the yaml file, so that XC Scenario can make them available as task outputs.
"},{"location":"openfaas/synchronous/#build-and-deploy-the-new-function","title":"Build and deploy the new function","text":"Repeat the above steps to build the new pyfunc2 function, upload its docker image to Docker Hub, and deploy it on the OpenFaas server.
"},{"location":"openfaas/synchronous/#test-the-new-function","title":"Test the new function","text":"You can invoke the function from the command line as before; however, passing json strings is cumbersome, as all the double quotes must be escaped, so it's easier to put the input in a json file, let's call it inputs.json:
{\n \"n\": 13,\n \"txt\": \"hello\"\n}\n
The -d option to the curl command supports the @ syntax to specify a file name, so the function can be invoke with the following command:
joao@debian1:~$ curl https://openfaas.xcomponent.com/function/pyfunc2 -d @inputs.json\n{\"calc\": 26, \"msg\": \"HELLO\"}\njoao@debian1:~$ \n
It can also be invoked through the OpenFaas portal as before:
"},{"location":"openfaas/synchronous/#use-the-new-function-in-xc-scenario","title":"Use the new function in XC Scenario","text":"As before, create a new scenario, add a task, pick the OpenFaas namespace, and select the pyfunc2 function. The Task Inputs section shows the two input parameters n and txt:
Finally, enter some values, then run the scenario and check the cockpit for the function output:
The output parameters display the results of the OpenFaas' function processing.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"Introducing XComponent AppControl"},{"location":"#focused-on-what-really-mattersyour-applications","title":"Focused on What Really Matters\u2014Your Applications","text":"For small and mid-sized enterprises, the performance and availability of your applications are critical to your business success. That\u2019s why AppControl is designed to minimize downtime by enabling fast, automated responses to incidents directly within your applications\u2014whether they are legacy systems or modern cloud-based apps. Unlike many solutions, AppControl integrates without requiring any modifications to your existing applications, ensuring a smooth deployment without risking your critical systems. While many traditional monitoring solutions focus primarily on servers, networks, and infrastructure, AppControl takes a different approach. We follow the lifeblood of your business: your applications. Whether it's restarting services, executing custom tasks, or applying real-time fixes, AppControl gives you the power to keep your applications running smoothly\u2014without the complexity and overhead of traditional tools that often require a full infrastructure overhaul.
"},{"location":"#what-makes-appcontrol-different-from-other-solutions","title":"What Makes AppControl Different from Other Solutions","text":" - No modifications required: Unlike other tools, AppControl integrates directly with your existing applications, whether legacy or cloud-based, without needing any changes to their structure.
- Application-Centric Approach: While many competing solutions focus on infrastructure (servers, networks), AppControl is designed specifically to monitor, manage, and automate your applications, which are the core of your business.
- Hybrid Environment Management: Whether you operate on-premise systems or in the cloud, AppControl provides seamless integration and centralized management for applications across complex environments.
- Real-time automation: With AppControl, responses to incidents are automated and intelligent, eliminating human error and reducing downtime.
- Ease of Use: Unlike traditional tools, no complex setup is required. AppControl is easy to install, use, and scale with your growing needs.
- Target audience: AppControl is ideal for small and mid-sized enterprises looking for an application management solution without the complexity of large-scale orchestration tools.
"},{"location":"#key-benefits-of-appcontrol","title":"Key Benefits of AppControl","text":" - Application-Centric: Focus on what matters most\u2014your applications, not the underlying infrastructure.
- Automated Responses: Automates incident responses for both legacy and cloud-native applications.
- No Modifications Required: Integrate your existing systems without any changes.
- Real-Time Control: Act instantly when issues arise, minimizing impact on your business.
- Ease of Deployment: Simple installation with quick configuration and minimal effort.
- Scalable: Adapts to the needs of your business as it grows.
"},{"location":"#why-choose-appcontrol","title":"Why Choose AppControl?","text":"AppControl is specifically designed for businesses that:
- Operate in hybrid environments and want to modernize their systems without altering their existing infrastructure.
- Don\u2019t need the complexity of traditional infrastructure-focused solutions and are looking for a simple, effective, application-centric management tool.
- Prioritize application availability and performance over focusing solely on infrastructure.
With AppControl, you\u2019re not just notified of issues\u2014you\u2019re equipped to solve them, ensuring the continuous operation of your critical applications and minimizing the impact of disruptions on your business. It\u2019s the ideal solution for companies that want to modernize without compromise and focus on what truly matters: their applications.
Ready to take control of your application reliability? Request a demo or Start a free trial today.
"},{"location":"agentazure/","title":"Gateways and Agents Installation in Azure","text":""},{"location":"agentazure/#docker-image-for-gateway-agent-and-azure-cli-deployment-in-azure","title":"Docker Image for Gateway, Agent, and Azure CLI Deployment in Azure","text":"To simplify the deployment of AppControl\u2019s gateway and agent in Azure, a pre-configured Docker image is available. This image includes:
- AppControl Gateway
- AppControl Agent
- Azure CLI (az cli)
The goal is to streamline the process of deploying and managing the agent and gateway in an Azure environment. By running this Docker container in Managed Identity, the agent will have the capability to execute Azure CLI commands without requiring additional authentication.
Key Benefits
-
Pre-configured Environment: The Docker image includes both the gateway and the agent, along with the Azure CLI, in one cohesive package. This eliminates the need to install and configure each component separately.
-
Managed Identity Integration: When the Docker container is run with a managed identity, the agent gains access to Azure resources without manual authentication. This allows the agent to execute az commands securely, inheriting the permissions associated with the managed identity.
-
Seamless Deployment: This image is designed to be used within Azure environments, simplifying the process of deploying the gateway and agent directly in the cloud. You can use the image to monitor and manage your applications and infrastructure easily.
"},{"location":"agentazure/#deploying-an-azure-container-with-a-managed-identity-using-appcontrols-docker-image","title":"Deploying an Azure Container with a Managed Identity Using AppControl\u2019s Docker Image","text":"This guide will walk you through creating a dedicated resource group, setting up a managed identity, and running a container using AppControl's Docker image, which includes the gateway, agent, and Azure CLI.
Prerequisites
- Azure CLI installed on your local machine.
- Azure account with sufficient privileges to create resource groups, managed identities, and run containers.
Procedure
"},{"location":"agentazure/#1-create-a-resource-group","title":"1. Create a Resource Group","text":"First, create a new resource group in Azure. This resource group will house the container and the associated resources.
az group create --name AppControlResourceGroup --location <your-region>\n
Replace with the desired Azure region (e.g., eastus, westus, westeurope)."},{"location":"agentazure/#2-create-a-managed-identity","title":"2. Create a Managed Identity","text":"
Next, create a managed identity that will be used by the container to authenticate and execute Azure commands without requiring credentials.
az identity create --name AppControlIdentity --resource-group AppControlResourceGroup --location <your-region>\n
Once the managed identity is created, note down the client ID and principal ID (also referred to as the object ID) from the output.
"},{"location":"agentazure/#3-assign-the-managed-identity-to-a-role","title":"3. Assign the Managed Identity to a Role","text":"Assign the managed identity appropriate roles so that it has permissions to interact with Azure resources. For example, to allow it to manage virtual machines, assign the Virtual Machine Contributor role.
az role assignment create --assignee <principal-id> --role \"Virtual Machine Contributor\" --scope /subscriptions/<subscription-id>/resourceGroups/AppControlResourceGroup\n
Replace:
- with the principal ID of the managed identity.
- with your Azure subscription ID. You can also assign different roles depending on what permissions are needed for the agent running in the container."},{"location":"agentazure/#4-create-and-configure-an-azure-container-instance","title":"4. Create and Configure an Azure Container Instance","text":"
Now, deploy an Azure Container Instance using the Docker image that contains the AppControl gateway, agent, and Azure CLI. Make sure to assign the managed identity to this container so it can execute Azure commands without requiring explicit credentials.
az container create \\\n --resource-group AppControlResourceGroup \\\n --name appcontrol-container \\\n --image xcomponent/x4b-azuregateway:latest \\\n --assign-identity <client-id> \\\n --cpu 1 \\\n --memory 1.5 \\\n --environment-variables AZURE_CLIENT_ID=<client-id> \\\n --location <your-region> \\\n --dns-name-label appcontrol-container-instance \\\n --resource-group [**RESOURCE-GROUP-NAME**] \\\n --restart-policy OnFailure \\\n --environment-variables AZURE_CLIENT_ID=<client-id> X4B_ACCESS_KEY=[**YOUR-GATEWAY-ACCESS-KEY**] X4B_SECRET_ACCESS_KEY=[**YOUR-GATEWAY-SECRET-KEY**] X4B_PROXY_NAME=[**YOUR-GATEWAY-NAME**] APPCONTROL_API_URL=https://appcontrol.xcomponent.com/core/\n
Replace:
- with the client ID of the managed identity.
- with your preferred Azure region.
This command will:
Create a new container instance running the Docker image xcomponent/x4b-azuregateway:latest. Assign the managed identity to the container so that it can run Azure CLI commands using the permissions of that identity. Allocate 1 CPU and 1.5GB memory for the container.
"},{"location":"agentazure/#5-verify-the-container-and-managed-identity","title":"5. Verify the Container and Managed Identity","text":"After running the above command, you can verify that the container is running:
az container show --resource-group AppControlResourceGroup --name appcontrol-container --query \"instanceView.state\"\n
If everything is configured correctly, the container will be in a \"Running\" state.
"},{"location":"agentazure/#6-running-azure-cli-commands-from-inside-the-container","title":"6. Running Azure CLI Commands from Inside the Container","text":"Since the container is running with the managed identity, you can now use the Azure CLI inside the container to manage Azure resources. The managed identity provides seamless access without needing explicit authentication credentials.
To list virtual machines, for example, you can run the following command inside the container:
az vm list --output table\n
The managed identity will use the permissions assigned to it to interact with the Azure resources as needed.
"},{"location":"agentazure/#7-clean-up-resources-optional","title":"7. Clean Up Resources (Optional)","text":"Once you're done with the container and managed identity, you can delete the resource group and all its associated resources:
az group delete --name AppControlResourceGroup --yes --no-wait\n
This command will remove the resource group, the container, and the managed identity.
"},{"location":"agentazure/#conclusion","title":"Conclusion","text":"By following this procedure, you can deploy a container running AppControl\u2019s gateway, agent, and Azure CLI in an Azure environment, using a managed identity for secure, password-less authentication. This setup allows the agent to execute Azure commands seamlessly, simplifying infrastructure management and monitoring.
For more advanced configurations or additional details, refer to the official Azure and AppControl documentation.
After the container is created and starts automatically, check its operation in Azure by examining the logs.
Now check on AppControl to ensure the gateway is accessible.
You are now ready to create your map in AppControl, utilizing this gateway and agent to monitor your Azure infrastructure.
Below is an example that supervises an Azure Function:
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>\n<apps>\n <hosts>\n <host hostid=\"agent-azure\" host=\"localhost\" port=\"12567\" sslprotocol=\"Tls12\" />\n </hosts>\n <auths>\n <auth authid=\"LOCAL\" domain=\"\" password=\"\" user=\"\" />\n </auths>\n <app name=\"AZURE MAP\" version=\"v1\">\n <component name=\"Azure CLI\" description=\"Azure access\" hostref=\"agent-azure\" authref=\"LOCAL\" redirectoutput=\"false\" type=\"file\">\n <action value=\"az version\" name=\"check\" />\n <action value=\"az $(command)\" commandname=\"Test az cli\" name=\"custom\">\n <parameters>\n <parameter name=\"command\" value=\"account list\" canedit=\"true\" validation=\"\\*\" />\n </parameters>\n </action>\n </component>\n <component name=\"AzureFunction\" description=\"Azure Function\" hostref=\"agent-azure\" authref=\"LOCAL\" redirectoutput=\"true\" type=\"browser\">\n <father>Azure</father>\n <action value=\"az functionapp show --ids /subscriptions/[SUBSCRIPTION-ID]/resourceGroups/[RESOURCE-GROUP-NAME]/providers/Microsoft.Web/sites/[FUNCTION-APP-NAME] --query 'state' | grep -q '"Running"'\" name=\"check\" />\n <action value=\"az functionapp start --ids /subscriptions/[SUBSCRIPTION-ID]/resourceGroups/[RESOURCE-GROUP-NAME]/providers/Microsoft.Web/sites/[FUNCTION-APP-NAME]\" name=\"enable\" />\n <action value=\"az functionapp stop --ids /subscriptions/[SUBSCRIPTION-ID]/resourceGroups/[RESOURCE-GROUP-NAME]/providers/Microsoft.Web/sites/[FUNCTION-APP-NAME]\" name=\"disable\" />\n </component>\n </app>\n</apps>\n
"},{"location":"agents/","title":"Agent installation","text":"An AppControl Agent is a key component that enables communication between your infrastructure and the AppControl gateway. It is responsible for executing commands, checking the status of components, and relaying important information to ensure smooth operation and monitoring of your applications.
The agent is designed to be cross-platform, meaning it can be deployed on both Linux and Windows systems, offering flexibility across diverse environments. Furthermore, it is optimized to be lightweight, consuming minimal CPU and memory resources. This ensures that the agent runs efficiently in the background without impacting the performance of the host system.
With a simple installation process and low resource footprint, AppControl Agents are an essential part of managing your applications, regardless of the platform or scale.
"},{"location":"agents/#latest-available-versions","title":"Latest Available versions","text":"Operating System Version Format Latest version Microsoft Windows 32 bits All Versions zip Windows Agent32 Zip Microsoft Windows 64 bits All Versions zip Windows Agent64 Zip Alpine 3.18.3 tar.gz Alpine tar.gz Alma Linux (EL) 8.8 (Compatibility with RedHat 8) tar.gz Alma8 tar.gz Alma Linux (EL) 9.2 (Compatibility with RedHat 9) tar.gz Alma9 tar.gz Rocky Linux (EL) 8.8 (Compatibility with RedHat 8) tar.gz Rocky8 Linux Rocky Linux (EL) 9.2 (Compatibility with RedHat 9) tar.gz Rocky9 Linux Debian 11.7 tar.gz Debian11 tar.gz Debian 12.1 tar.gz Debian12 tar.gz Alpine alpine:3.18.3 docker docker pull xcomponent/appcontrol-agent:latest-alpine Alma Linux (EL) almalinux:8.8-minimal (Compatibility with RedHat 8) docker docker pull xcomponent/appcontrol-agent:latest-almalinux Alma Linux (EL) almalinux:9.2-minimal (Compatibility with RedHat 9) docker docker pull xcomponent/appcontrol-agent:latest-almalinux Debian debian:11.5-slim docker docker pull xcomponent/appcontrol-agent:latest-debian Rocky Linux (EL) rockylinux:8.8-minimal (Compatibility with RedHat 8) docker docker pull xcomponent/appcontrol-agent:latest-rockylinux Rocky Linux (EL) almalinux:9.2-minimal (Compatibility with RedHat 9) docker docker pull xcomponent/appcontrol-agent:latest-rockylinux All binary versions are listed here: All binaries versions
All docker versions are listed here: All docker versions
"},{"location":"agents/#microsoft-windows-platform","title":"Microsoft Windows Platform","text":"Note:
We recommand to use cmd.exe as a shell to install the agent. We don't offer the support for installation through powershell.\n
To install XComponent AppControl Agent under Windows OS, unzip the following file into an installation directory. The configuration file ( config.dat ) is located in the same directory. Refer to the agent configuration section to customize the configuration. You have 2 options:
- Install an run the agent as a Microsoft Windows Service
- Run the agent in interactive mode (in a cmd.exe)
"},{"location":"agents/#option-1-install-and-start-the-agent-as-a-microsoft-windows-service","title":"Option 1. Install and start the agent as a Microsoft Windows Service","text":" - To register the program in the service registry of the Microsoft\ufffd Windows machine execute the following command in a prompt (cmd.exe) with administrative permissions:
C:\\appcontrol>xcAgent --install --servicename XComponentAppControlAgent\nXComponent App Control Agent, version 9.9\nCopyright \u00a9 Invivoo Software 2022\nXComponent AppControl service name: XComponentAppControlAgentXComponent AppControl service display name: XComponent AppControl AgentXComponentAppControlAgent is installed.\n
- We can either specify the display service name during registration:
C:\\appcontrol>xcAgent.exe --install --servicename appcontrolagent --servicedisplayname \"Agent AppControl\"\nXComponent App Control Agent, version 9.9\nCopyright \u00a9 Invivoo Software 2022\nXComponent App Control service name: appcontrolagent\nXComponent App Control service display name: Agent AppControl\nappcontrolagent is installed.\n
- Uninstalling the agent can be done also with the following command line:
C:\\appcontrol>xcAgent.exe --uninstall --servicename appcontrolagent\nXComponent App Control Agent, version 9.9\nCopyright \u00a9 Invivoo Software 2022\nappcontrolagent has been uninstalled.\n
- Start the service XComponent AppControl Agent
"},{"location":"agents/#option-2-run-the-agent-in-interactive-mode-from-a-prompt-cmdexe","title":"Option 2. Run the agent in interactive mode from a prompt (cmd.exe)","text":"Run cmd.exe and then go to the agent folder.
C:\\appcontrol>xcAgent.exe --console\nXComponent AppControl Agent, version 7.0.0-R1\nCopyright \u00a9 Invivoo Software 2022\n\n
"},{"location":"agents/#adding-a-microsoft-windows-firewall-port-rule-optional-step","title":"Adding a Microsoft Windows firewall port rule (optional step)","text":"If you need to communicate with the agent from another computer, you should need to create a firewall rule to open the agent's port.
In this case the agent's port is 12567, the command above creates the correct rule on the firewall.
Run cmd.exe (with Administrative permissions) and then execute the following command.
C:\\>netsh advfirewall firewall add rule name=\"AppControl-AgentRule\" dir=in action=allow protocol=TCP localport=12567\n\n
You can check that the rule is correctly created with this command:
C:\\>netsh advfirewall firewall show rule name=\"AppControl-AgentRule\"\n
Please refer to the following link to check if the agent port is reachable.
Note:
If you are using another firewall or and anti-virus, you should refer to the corresponding documentation.\n
"},{"location":"agents/#enterprise-linux","title":"Enterprise Linux","text":"At the moment EL versions of XComponent AppControl Agent are Rocky Linux and Alma Linux.
To install XComponent AppControl Agent under EL, untar the following Alma tar.gz into an installation directory (Tarball file). The configuration file ( config.dat ) is located in the same directory. Refer to the agent configuration section to customize the configuration.
Replace /home/xc/xcagent with your own installation folder.
/home/xc/xcagent $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/xc/xcagent/libs\n/home/xc/xcagent $ ./xcAgent.bin --file /home/xc/xcagent/config.dat\n\nXComponent AppControl Agent, version 7.0.0-R1\nCopyright \ufffd Invivoo Software 2022\n\n
"},{"location":"agents/#agentless-linux-unix","title":"Agentless Linux & Unix","text":"From an XComponent AppControl Linux agent, you can enable AgentLess mode via SSH2. This mode allows a Linux XComponent AppControl Agent to forward actions provided by the AppControl server under a non permanent Ssh channel to the IP address and account configured in the agent configuration file. Refer to the agent configuration section to customize the configuration.
"},{"location":"agents/#docker-installation","title":"Docker Installation","text":"The docker image of the agent is available here on docker hub.
You can pull the docker image using the following command line:
root $ docker pull xcomponent/appcontrol-agent:latest\n
Environment variables exposed by the docker image are the following:
Variable Description CONFIG_FILE_PATH Path to the config.dat TRUSTED_SERVERS List of IP addresses, or Dns names of XComponent AppControl servers authorized to contact the agent (Can be empty) LOG_LEVEL Log levels ('NONE', 'ERROR', 'INFO', 'TRACE') PORT Default value: 12567. Port used as the agent's TCP listening port. Numerical format. NB_DAYS_TO_DELETE_LOGS Default value: 0. Retention period for trace files archived under logdirectory /logs-backup/ (In number of days) LOG_STANDARD_OUTPUT Default value: true. Boolean value (true or false). If true redirect all the logs to std output Some Technicals Points:
- If your agent needs to access to local resources (eg: scripts), you have 2 ways to achieve this:
- Inherits from this docker image and create your own image
- Or you can map a directory to the docker image
Running the docker image:
root $ docker run -p 12567:12567 xcomponent/appcontrol-agent:latest\n
"},{"location":"agents/#agent-configuration","title":"Agent Configuration","text":"The default configuration file is name config.dat. It's located near the XComponent AppControl Agent configuration file.
<config>\n <item key=\"networkAddress\" value=\"127.0.0.1\" />\n <item key=\"port\" value=\"12567\" />\n <item key=\"checktimeout\" value=\"20\" />\n <item key=\"logdirectory\" value=\"log\" />\n <item key=\"tempdirectory\" value=\"tmp\" />\n <item key=\"maxlogsizeinmo\" value=\"5\" />\n <item key=\"nbdaystodeletelogs\" value=\"10\" />\n <item key=\"executionthreshold\" value=\"30\" />\n <!--Log level : NONE, INFO, TRACE, ERROR -->\n <item key=\"loglevel\" value=\"INFO\" />\n <item key=\"trustedservers\" value=\"127.0.0.1\" />\n <item key=\"sshhost\" value=\"127.0.0.1\" />\n <item key=\"sshkeydirectory\" value=\"sshkeys\" />\n</config>\n
Key Description networkAddress IP address used to open the agent's TCP listening port. A.B.C.D format (0.0.0.0 for all interfaces of the machine) port Port used as the agent's TCP listening port. Numerical format. checktimeout Maximum time allowed for a check command. Once this period has passed, the check order is considered completed. (In seconds) logdirectory Agent's trace file recording directory. tempdirectory Agent's working directory maxlogsizeinmo Maximum size before rotation of the trace file (In Megabytes) nbdaystodeletelogs Retention period for trace files archived under logdirectory /logs-backup/ (In days) loglevel Log levels ('NONE', 'ERROR', 'INFO', 'TRACE') executionthreshold Maximum number of parallel executions for (Start/Stop/Custom actions). This parameter does not apply to check actions. trustedservers List of IP addresses, or Dns names of XComponent AppControl servers authorized to contact the agent (Can be empty) ignoretrustedservers Disable trusted server option sshhost This parameter allows the agent to perform an SSH session with the account specified in the configuration of the application. The file containing the private key to use is located in the 'sshkeydirectory' directory and bears the name of the targeted user. This property works exclusively on Linux agent. sshkeydirectory Directory for storing Ssh private key files. The name of the expected files must be named with the name of the user targeted by the application configuration. The public key must be present in the ~/ssh/authorized_keys file of the remote account"},{"location":"agents/#environment-variables-configuration","title":"Environment variables configuration","text":"Config.dat configuration supports environment variables as a value.
Under Microsoft Windows:
In config.dat you can use environment variables with the following pattern: %VARIABLE%.
<config>\n...\n <item key=\"tempdirectory\" value=\"%TEMP%\" />\n...\n</config>\n
Under Linux/Unix:
In config.dat you can use environment variables with the following pattern: $VARIABLE.
<config>\n...\n <item key=\"tempdirectory\" value=\u201d$TEMP\" />\n...\n</config>\n
Note:
Each item key of the config.dat file can be overriden by an environment variable named XC_MYITEMKEYINUPPERCASE. The priority is the following:\n1. If an XC_... variable exists the agent will use it\n2. The values in the config.dat are used only if the XC_... variables don't exist.\n\nExample:\nif an env variable named XC_TEMPDIRECTORY exists, this value will be used instead of the variable 'tempdirectory' defined in the config.dat.\n\n
"},{"location":"agents/#checking-that-agents-port-is-opened","title":"Checking that agent's port is opened","text":" In some situations, we need to check that the agent's port is correctly bind and accessible from another computer.
- Checking that the agent binds on its port (locally):
curl localhost:12567\n
If the agent is running, the expected message is:
curl: (52) Empty reply from server\n
If the agent is not running, the message is:
curl: (7) Failed to connect to localhost port 12567 after 2267 ms: Couldn't connect to server\n
- Checking that the agent binds on its port (from a remote machine):
curl mymachine:12567\n
If the agent is running, the expected message is:
curl: (52) Empty reply from server\n
If the agent is not running or unreachable (for example behind a firewall), the message is:
curl: (7) Failed to connect to mymachine port 12567 after 2267 ms: Couldn't connect to server\n
Note:
You can use the AppControl Gateway to both check agent connectivity and also to execute commands on the agent host.\n
Please refer to the following link
"},{"location":"agentsdeployment/","title":"Automatic Deployment of Agents","text":""},{"location":"agentsdeployment/#deploy-agents-automatically-via-the-gateway","title":"Deploy Agents Automatically via the Gateway","text":"AppControl simplifies the process of deploying agents in your infrastructure by leveraging the gateway. To automate the deployment of agents, AppControl requires SSH access to the target infrastructure using the private SSH key. Below are the steps to configure SSH, generate SSH keys on both Linux and Windows, and provide the necessary key to enable automatic deployment.
"},{"location":"agentsdeployment/#1-configure-ssh-access","title":"1. Configure SSH Access","text":"For AppControl to deploy agents automatically, the gateway needs access to the target machines via SSH. Ensure that SSH is properly configured on your target systems.
- Port: By default, SSH uses port 22, but AppControl allows you to customize this if needed.
- User Permissions: The user account that AppControl will use for SSH must have sufficient permissions to install and manage agents on the target machine.
Note: The public SSH key must be added to the ~/.ssh/authorized_keys file on the SSH server of the target machines. This ensures that AppControl can authenticate using the corresponding private SSH key.
"},{"location":"agentsdeployment/#2-generate-ssh-keys-private-key-required-by-appcontrol","title":"2. Generate SSH Keys (Private Key Required by AppControl)","text":"To allow AppControl to manage agent deployment via the gateway, the private SSH key must be provided. Follow the steps below to generate SSH keys on Linux or Windows.
"},{"location":"agentsdeployment/#linux-or-macos","title":"Linux (or macOS)","text":"To generate SSH keys on Linux or macOS:
- Open a terminal.
-
Run the following command to generate a new SSH key pair:
bash ssh-keygen -t rsa -b 2048 -f ~/.ssh/appcontrol_key
-t rsa: Specifies the RSA algorithm.-b 2048: Specifies the key length (2048 bits).-f ~/.ssh/appcontrol_key: Saves the key pair to the specified file (appcontrol_key).
-
When prompted for a passphrase, press Enter to leave it empty (or add a passphrase if extra security is required).
This command will generate two files:
- Private key:
~/.ssh/appcontrol_key -
Public key: ~/.ssh/appcontrol_key.pub
-
Add the public key to the authorized_keys file on the target machine:
bash cat ~/.ssh/appcontrol_key.pub >> ~/.ssh/authorized_keys
"},{"location":"agentsdeployment/#windows","title":"Windows","text":"To generate SSH keys on Windows, you can use either Git Bash or PowerShell (with OpenSSH).
"},{"location":"agentsdeployment/#option-1-using-git-bash","title":"Option 1: Using Git Bash","text":" - Install Git for Windows if not already installed.
- Open Git Bash.
-
Run the following command to generate an SSH key pair:
bash ssh-keygen -t rsa -b 2048 -f ~/.ssh/appcontrol_key
-
When prompted, press Enter to use the default file location, and leave the passphrase empty (or add one if preferred).
-
Add the public key to the authorized_keys file on the target machine:
bash cat ~/.ssh/appcontrol_key.pub >> ~/.ssh/authorized_keys
"},{"location":"agentsdeployment/#option-2-using-powershell-windows-1011","title":"Option 2: Using PowerShell (Windows 10/11)","text":" - Open PowerShell as an administrator.
-
Run the following command to generate an SSH key pair:
bash ssh-keygen -t rsa -b 2048 -f $env:USERPROFILE\\.ssh\\appcontrol_key
This will generate two files:
- Private key:
C:\\Users\\YourUsername\\.ssh\\appcontrol_key -
Public key: C:\\Users\\YourUsername\\.ssh\\appcontrol_key.pub
-
Add the public key to the authorized_keys file on the target machine:
powershell Get-Content $env:USERPROFILE\\.ssh\\appcontrol_key.pub | Out-File -Append -Encoding ascii $env:USERPROFILE\\.ssh\\authorized_keys
"},{"location":"agentsdeployment/#3-ssh-server-on-windows-optional","title":"3. SSH Server on Windows (Optional)","text":"For Windows systems, you can optionally deploy an SSH server to allow AppControl to connect and manage agents. OpenSSH Server is an optional feature in Windows, which you can enable via the following steps:
- Go to Settings > Apps > Optional Features.
- Scroll down and click Add a feature.
- Search for OpenSSH Server, select it, and click Install.
For more detailed instructions, refer to the official Windows documentation.
Once installed, configure the SSH server, and ensure the public key is added to the authorized_keys file.
"},{"location":"agentsdeployment/#4-deploy-agents-via-the-gateway","title":"4. Deploy Agents via the Gateway","text":"Once SSH is configured and the private key is provided, follow these steps to deploy agents using the AppControl gateway:
-
Select the Target Machines:
- In the AppControl dashboard, go to the \"Deploy Agents\" section and select the machines where agents should be deployed.
-
Verify Connectivity:
- AppControl will verify the SSH connection to the target machines using the private SSH key.
-
Deploy Agents:
- Once the connection is established, AppControl will automatically deploy the agents to the selected machines.
Installation Paths:
- On Windows: Agents will be installed in
C:/ProgramData/appcontrol/agent. - On Linux: The installation folder is
/opt/appcontrol/xcagent. - On macOS: The installation folder is
~/appcontrol/xcagent.
"},{"location":"agentsdeployment/#5-troubleshooting-ssh-connection","title":"5. Troubleshooting SSH Connection","text":"If you encounter issues with the SSH connection during the deployment process, check the following:
-
Private SSH Key:
- Ensure that the private SSH key is properly configured and uploaded to AppControl.
-
SSH Port and User Permissions:
- Verify that the SSH port and user permissions are correctly set up on the target machine.
-
Firewall and Network Configuration:
- Check firewall rules or network configurations that might block SSH access to the target machine.
"},{"location":"agentsdeployment/#6-provide-the-private-ssh-key-to-appcontrol","title":"6. Provide the Private SSH Key to AppControl","text":"AppControl requires the private SSH key for authentication during agent deployment. The public key is added to the target machines in the ~/.ssh/authorized_keys file, and the private key remains with AppControl to establish the connection.
- Locate the Private Key:
- Linux:
~/.ssh/appcontrol_key - Windows:
C:\\Users\\YourUsername\\.ssh\\appcontrol_key
- Upload the Private Key to AppControl:
- Log in to the AppControl dashboard.
- Navigate to Gateway Configuration and select the gateway that will manage the agent deployment.
- Upload the private SSH key (
appcontrol_key). - AppControl will securely store the key and use it for deploying agents.
Note: The private SSH key remains confidential and is only used by AppControl to establish a secure SSH connection to the target machines. The corresponding public key should already be added to the ~/.ssh/authorized_keys file on the target machines.
"},{"location":"bestpractices/","title":"Agents/Gateways configuration best practices","text":"According to your configuration, differents badges will be displayed in the UI. The badges are indicators which are used to secure your I.S (Information System).
The badges are displayed in the Agents view.
"},{"location":"bestpractices/#protocol-badges","title":"Protocol badges","text":" - The first badge encourages the use of a recent version of the Tls protocol:
Protocol Badge Tls13 Tls12 Tls - Ssl"},{"location":"bestpractices/#gateway-badges","title":"Gateway badges","text":" - The second badge encourages the use of a gateway to access agents. Indeed, the gateways are there to guarantee a stronger isolation at the network level and at the application level.
Number of gateways by agent Badge At least one None"},{"location":"bestpractices/#resilience-badges","title":"Resilience badges","text":" - The third badge encourages the use of several sites (at least primary and secondary). This declaration of the different sites is configured using the \"trustedservers\" variable in the agent's config.dat file. If \"ignoretrustedservers\" a \"gold medal\" will be displayed.
Number of servers declared in \"trustedserver\" Badge At least two One None"},{"location":"centreon/","title":"Centreon Import","text":"The X4B platform includes a mechanism for importing your current Centreon (or Nagios) setup. This allows you to start off with a draft AppControl map file which includes all the hosts and services that you have defined in your Centreon configuration.
"},{"location":"centreon/#appcontrol-map","title":"AppControl map","text":"The import will create one AppControl component for each host, and one for each service, with the host component being designated as a parent of the service component. The parent-child relationship denotes a dependency relation, where the child depends on a properly working parent to perform its own function.
You can designate one of your servers as a bastion host. If you do, it is assumed that you will deploy an AppControl agent on it, and then that server will be used to run remote checks on other hosts, using the ping or ssh commands, for example.
By default, the host components have a check command that does ping -c 1 <hostname>. The service components are created with sample check, start, and stop commands that simulate the actual checks using a temporary file. All these default commands assume the agent is running on a linux machine, but you can also configure your map to deploy the agents on Windows servers (see xxx for more details on AppControl agents).
"},{"location":"centreon/#importing-your-setup","title":"Importing your setup","text":"The import tool is a Windows binary that you can download from here. To import your setup, first log on to your Centreon server, and export your configuration to a text file, with the following command:
centreon -u <admin_user> -p <admin_password> -e > centreon_export.txt\n
Second, run the import tool, specifying your export file as the input file:
ac_from_centreon.exe -f centreon_export.txt -n CentreonExported -v 1.0\n
This creates a file called CentreonExported,1.0.xml in the current directory (you are free to pick any name and version you want, see the available options below). You can open this file in the editor of your choice to inspect or edit it, and you can upload it to AppControl with the New button on the AppControl UI. Other options are available:
Usage: ac_from_centreon.exe OPTIONS\nOptions:\n -f <filepath>\n -r | --root-host <hostname>\n -b | --bastion-host <hostname>\n -n <map name> (required)\n -v <version> (required)\n -o <map_filepath>\n
The --root-host option lets you specify one server as being the root, in the AppControl architecture map, of the servers graph. This indicates that all the other server depend on this one; you would typically choose a server playing some essential role, such as a DNS server.
The --bastion-host option lets specify one server as being the bastion, as described above.
The -n and -v options are required, as they define the map name and version. If no path is given for the map file, the file gets created in the current directory with the name <map_name>,<version>.xml; alternatively, you may specify a different path and name using the -o option.
"},{"location":"cli/","title":"AppControl Cli","text":""},{"location":"cli/#latest-available-versions","title":"Latest Available versions","text":"Operating System Format Latest version Microsoft Windows / Linux zip AppControl Cli Zip N/A docker docker pull xcomponent/appcontrol-cli:latest"},{"location":"cli/#objectives","title":"Objectives","text":"AppControl Cli is intended to start/stop/load/suspend Appcontrol's applications from the command line. This tool is mainly used to integrate AppControl in a scheduler/workload automation software.
"},{"location":"cli/#installation","title":"Installation","text":"...
"},{"location":"cli/#configuration","title":"Configuration","text":"...
"},{"location":"cmdb/","title":"AppControl CMDB Integration","text":"AppControl can be integrated with a Configuration Management Database (cmdb).
AppControl currently supports ServiceNow as a cmdb provider, but other providers such as iTop or EasyVista can also be considered.
"},{"location":"cmdb/#use-cases","title":"Use Cases","text":"There can be several use cases for integrating AppControl and a cmdb:
- conformity check between operational reality and cmdb referential
- map (eg: AppControl Application) provisioning based on cmdb data
"},{"location":"cmdb/#conformity-check","title":"Conformity check","text":"In the first use case, whenever a map is loaded, AppControl checks whether the objects declared in the map are present in the cmdb, and produces a report listing the elements that were found missing.
Currently, nothing is ever added to the cmdb; a future version may offer the possibility for the user to choose whether to populate the cmdb with elements from the map.
"},{"location":"cmdb/#map-provisioning","title":"Map provisioning","text":"In the second use case, the cmdb acts as the configuration repository for AppControl artefacts, such as the Component. For example, the cmdb may hold a standard set of actions that are expected to be present in certain components: when the actions are found to be missing in the map, they can be copied from the cmdb, ensuring that the Components in the operational reality match the cmdb view of the world.
Eventually, it might be possible to generate entire maps from the cmdb, thereby ensuring automatic conformity.
"},{"location":"cmdb/#cmdb-integration-howto","title":"Cmdb Integration HOWTO","text":""},{"location":"cmdb/#cmdb-access-and-credentials","title":"Cmdb access and credentials","text":"The first step is to define one or more cmdb objects in AppControl. In the Referential section at the bottom of the left-hand side panel, press the CMDB button to display the page where you can manage access to various CMDBs:
To register a new ServiceNow CMDB, press the register button and fill in the fields:
Name is the local AppControl identifier for this cmdbUser/Password are your credentials on the ServiceNow serverServiceNow Url identifies the ServiceNow server you wish to use
Once a cmdb has been defined, you can reference it in the map import wizard, to request a validation of the map being imported.
"},{"location":"cmdb/#map-import-wizard","title":"Map Import Wizard","text":"When importing a new map file, the fifth step is the CMDB validation, where you are presented with the list of available cmdbs.
Make sure the cmdb server you want to use is up and running at this point. Click on its name and press Next. A progress bar indicates that validation is taking place (this can take a few moments). If every element in the map is matched to a corresponding element in the cmdb, a message will indicate that the validation has succeeded:
If the verification process detected configuration information in the cmdb that was not in the map (such as Component actions) this will also be indicated:
If any discrepancies were found when comparing the map to the cmdb, a report is shown listing the elements that were found to be missing:
"},{"location":"cmdb/#understanding-the-servicenow-integration","title":"Understanding the ServiceNow integration","text":"The following sections detail the mapping choices that were made to represent AppControl data in ServiceNow. Keep in mind that ServiceNow is very much configurable, and even lets you define custom data tables, so any integration might require specific work.
"},{"location":"cmdb/#mapping-between-appcontrol-and-servicenow","title":"Mapping between AppControl and ServiceNow","text":"The following table shows the correspondance between AppControl concepts or objects, and ServiceNow resources.
AppControl ServiceNow Object ServiceNow Table Application Application cmdb_ci_appl Host Computer cmdb_ci_computer Component Service cmdb_ci_service Component hostref Computer-Service Relation cmdb_ci_rel Action Commands cmdb_running_process"},{"location":"cmdb/#representing-components-actions-in-servicenow","title":"Representing Components actions in ServiceNow","text":"Each Component in AppControl has a mandatory hostref attribute linking to the server where the component is hosted. This link is represented by a ServiceNow Depends on::Used by relation.
The actions defined on a Component are stored in the RunningProcess table (cmdb_running_process), with a link to the corresponding host. Here's the detailed mapping on the fields of the RunningProcess table:
AppControl Element Field name action name :: component name command action value parameters application name computer hostref"},{"location":"cmdb/#example","title":"Example","text":"AppControl XML map file:
<app name=\"inv_test_missing_from_map\" version=\"1.0\">\n <component name=\"inv_pricing_001\" description=\"An Invivoo component\" group=\"A group\"\n hostref=\"inv_host_001\" authref=\"LOCAL\"redirectoutput=\"false\" type=\"file\">\n <action value=\"sandbox.sh check inv_pricing_001\" name=\"check\" />\n <action value=\"sandbox.sh enable inv_pricing_001\" name=\"enable\" />\n <action value=\"sandbox.sh disable inv_pricing_001\" name=\"disable\" />\n </component>\n
ServiceNow cmdb_running_process table record (extracts):
{\n \"command\": \"sandbox.sh check inv_pricing_001\",\n \"computer\": {\n \"link\": \"https://dev78474.service-now.com/api/now/v1/table/cmdb_ci_computer/8ba1aa202f7320102cd8d49df699b687\",\n \"value\": \"8ba1aa202f7320102cd8d49df699b687\"\n },\n \"name\": \"check::inv_pricing_001\",\n \"parameters\": \"inv_test_missing_from_map\",\n}\n
"},{"location":"cmdb/#populating-your-cmdb","title":"Populating your Cmdb","text":"The cmdb can be populated by inserting individual objects using the cmdb provider's interface. But as the volume of data grows, populating your cmd can become a daunting task. Invivoo is developing tools to automate the creation of cmdb objects from AppControl maps [TO BE CONTINUED].
"},{"location":"contact/","title":"Contact Us","text":""},{"location":"contact/#contact-us","title":"Contact Us","text":"If you have any questions, need support, or want to reach out for any reason, we\u2019re here to help!
Links Contact Us Fill out our contact form Support support@appcontrol.com Community
Join our Slack channel"},{"location":"coreconcepts/","title":"Core Concepts of AppControl","text":"AppControl is built on a set of core concepts that enable effective monitoring, control, and automation of your applications across both local and cloud-based environments. Understanding these concepts will help you make full use of the platform.
"},{"location":"coreconcepts/#1-agents","title":"1. Agents","text":"AppControl uses agents to interact with your local infrastructure. These agents act as the bridge between your on-premises applications and the AppControl SaaS platform. Agents can be installed on both Windows and Linux systems, allowing for flexible integration with diverse IT environments.
"},{"location":"coreconcepts/#2-gateway","title":"2. Gateway","text":"The gateway is the critical link between agents deployed on your local infrastructure and the AppControl SaaS platform. It facilitates secure and reliable communication, ensuring that actions taken on your applications are synchronized with the cloud.
"},{"location":"coreconcepts/#3-applications","title":"3. Applications","text":"In AppControl, an application represents a collection of components that need to be monitored and managed. Each application is defined through a YAML configuration file, which describes its components and the actions that can be performed on them.
"},{"location":"coreconcepts/#4-components","title":"4. Components","text":"A component is a critical part of an application and defines the actions that AppControl can perform. Each component is described by three primary actions: start, stop, and check. In addition, some components may have optional custom commands.
"},{"location":"coreconcepts/#command-types","title":"Command Types:","text":" - Check Command: Retrieves the current state of the component.
- Start Command: Starts the component, initiating processes or services.
- Stop Command: Stops the component, halting processes or services.
- Custom Commands: Optional commands that can be defined based on specific application requirements.
"},{"location":"coreconcepts/#dependency-behavior","title":"Dependency Behavior:","text":" - Parent-Child Dependencies: Components follow a parent-child hierarchy. A component can only start if its parent components are already started. Similarly, a component can only stop if its child components are already stopped.
- Startup Sequence: When starting an application, AppControl first starts the parent components and then proceeds to start their child components.
- Shutdown Sequence: When stopping an application, AppControl stops child components first before stopping their parent components.
"},{"location":"coreconcepts/#5-diagnostics-actions-on-demand-actions","title":"5. Diagnostics Actions (On-Demand Actions)","text":"AppControl provides on-demand actions, also referred to as diagnostics actions, which allow you to perform manual checks or gather diagnostic information at any time.
- Purpose: Diagnostics actions help troubleshoot issues, gather performance metrics, or run custom scripts on-demand without waiting for an incident to trigger automated actions.
- Customizable: You can define these actions in the YAML file and provide flexible input parameters that can be edited by users as needed.
- Example: A diagnostics action might involve checking log files, gathering system metrics, or testing connectivity between components.
"},{"location":"coreconcepts/#6-diagnostics-and-issue-resolution","title":"6. Diagnostics and Issue Resolution","text":"AppControl includes built-in diagnostics to detect and resolve common issues related to component states, particularly focusing on dependency relationships between components.
"},{"location":"coreconcepts/#diagnostic-situation","title":"Diagnostic Situation:","text":" - Orphan Components: AppControl identifies issues when components are in an incorrect state relative to their parent or child components. For example:
- Issue 1: A component is stopped while its parent is running.
- Issue 2: A component is running while its child components are stopped. In these cases, AppControl flags the issue and provides diagnostic information.
"},{"location":"coreconcepts/#resolution-process","title":"Resolution Process:","text":" - Stop Orphaned Components: When an orphaned component is detected (i.e., a component that is running without its necessary parent components), AppControl will stop the orphaned components to maintain consistency.
- Healthy State: Once the issues are resolved, the system reaches a healthy state, ensuring all components are properly aligned with their parent-child dependencies.
- Restart by Branch: AppControl can restart components by \"branch,\" ensuring that all parent and child components are properly started in sequence, maintaining the application's integrity.
"},{"location":"coreconcepts/#7-automated-recovery-actions","title":"7. Automated Recovery Actions","text":"In AppControl, automated recovery actions are designed with caution to prevent escalating issues. By default, AppControl does not automatically restart components to avoid the risk of increasing a problem. Instead, AppControl offers a flexible approach where users can define scheduled auto-restart actions using built-in cron expressions.
"},{"location":"coreconcepts/#8-application-monitoring-focus","title":"8. Application Monitoring Focus","text":"AppControl is different from traditional monitoring solutions because it is application-centric. While other tools often focus on infrastructure (e.g., servers and networks), AppControl monitors and manages the actual applications, which are the heart of your business.
"},{"location":"coreconcepts/#summary","title":"Summary","text":"Understanding these core concepts will enable you to effectively use AppControl to monitor, manage, and automate your applications. Whether you are working with legacy on-premises systems or cloud-native applications, AppControl\u2019s agents, gateway, and application-centric approach offer the flexibility and control you need to maintain uptime and operational efficiency.
"},{"location":"dynamicMapInformations/","title":"Dynamic informations","text":"An application is a set of components defined statically using a YAML/XML format (see: Create an application). However, the application can be enriched with dynamic information. Dynamic information is returned by the check command.
To return dynamic information, the check command should log some data to the standard output, which must follow this format:
<appcontrol> APPCONTROL JSON OBJECT </appcontrol>\n
{\n \"link\": \"Hyperlink to wathever you want\", //Optional\n \"name\": \"Name of the component\", //Required\n \"displayName\": \"Display name\", //Optional\n \"state\": \" Initializing |\n InError |\n Start |\n Starting |\n Started |\n Stop |\n Stopping |\n Stopped \", //Optional\n \"parents\": //Optional but highly recommanded\n [\n \"Parent1\",\n \"Parent2\",\n ],\n \"exitCode\": 256, //Optional\n \"color\": \"Color of the code RGB format or hexa code ('255,255,255' or #FFFFFF\", //Optional\n \"Type\": \" Used to display an icon on the map. An url to an image (png, jpeg or svg) can be set. Anyway you can use one of the following value: browser, cd, chip, data-information, devises, dollar, euro, file, green-thermometer, hdd, memflash, memory, middleware, network, orange-thermometer, pounds, process, service, tools, user, yen\", //Optional\n \"groupName\": \"Name of the group\", //Optional\n \"customActions\": //Optional\n [\n {\n \"visibility\": \"Private\",\n \"customActionName\": \"echo Action\",\n \"customActionDescription\": null,\n \"customActionCommandLine\": \"echo $(message)\",\n \"parallelCustomAction\": false,\n \"parameters\":\n [\n {\n \"parameterName\":\"message\",\n \"description\": \"\",\n \"defaultValue\": \"Welcome message\",\n \"validationRule\": \"*\",\n \"isEditable\": true\n }\n ]\n }\n ],\n \"filters\": {\"filter name 1\": [\"filter values\"] ,\n \"filter name 2\": [\"filter values\"]\n } //Optional,\n \"dynamicTree\" : [\n {\n //A json object with the properties defined above\n }\n ] //Optional,\n}\n
A full example is available in this documentation:
- Application sample
- JSON dynamic data
In this example, dynamic components are displayed with an octagonal shape, while static components are displayed with a square shape.
"},{"location":"gettingStarted/","title":"Getting Started with AppControl","text":"AppControl is designed as a simple, cloud-based Software as a Service (SaaS) solution, allowing you to monitor and manage your applications from anywhere, without the need for complex on-premises infrastructure. This quick-start guide will help you set up and begin using AppControl in minutes.
For businesses with specific requirements\u2014whether it\u2019s tailored SLAs, on-premises deployment, or other custom needs\u2014please Contact us to discuss how we can meet your specific goals.
"},{"location":"gettingStarted/#try-demo","title":"Try AppControl with a Demo (No Local Setup Required)","text":"To help you get started quickly, AppControl offers a demo environment that allows you to explore the core features of the platform without the need for any local setup or infrastructure. This is the perfect way to understand how AppControl can reduce downtime and streamline incident response.
- Log in: - Go to the XComponent AppControl website - Log in using a social provider - You're done! You can now get started with AppControl!
- Import a demo application:
Click on the Overview/New Application button, select XML/YAML file from url and paste the following link of an \"Hello World\" application.
Copy Application Link
Follow the wizard (clicking on 'Next' button). In the 'Agent/Gateway configuration' section select 'SaaS Gateway'. Then scroll down on the bottom of the page and click on \"Create my application\".
- Explore the UI: Explore monitoring, incident management, and actions.
The demo version provides a hands-on look at AppControl\u2019s capabilities.
"},{"location":"gettingStarted/#some-explanations-about-the-demo-yaml-file","title":"Some explanations about the Demo YAML file","text":""},{"location":"gettingStarted/#yaml-configuration-for-helloworld-application","title":"YAML Configuration for \"helloworld\" Application","text":"The YAML configuration file for the \"helloworld\" application defines how the application is monitored, controlled, and secured through AppControl. This guide explains the structure and objectives of the YAML file, allowing you to customize your own configurations.
"},{"location":"gettingStarted/#objectives-of-the-yaml-configuration","title":"Objectives of the YAML Configuration","text":"The primary purpose of the YAML configuration file is to outline the application\u2019s structure, define its components, and specify the actions AppControl will perform. It also describes how agents and authentication methods are used to securely communicate with and control the application.
"},{"location":"gettingStarted/#key-objectives","title":"Key Objectives","text":" -
Define the Application Name, Version, and Components
- The YAML file begins by specifying the application\u2019s
Name and Version, followed by its components. In this case, the component \"hello\" represents the main part of the \"helloworld\" application.
-
Establish Agent-Based Monitoring and Control
- An agent, called
LOCAL, is defined to manage the application. This agent communicates over port 12567 using the TLS 1.2 protocol for secure connections. The agent monitors the application\u2019s state and can execute actions such as starting or stopping the application.
-
Define Secure Authentication Mechanism
- The file includes an authentication method,
LOCAL, to secure the communication between the agent and the application components. This ensures that only authorized agents can execute actions on the application.
-
Configure Component Actions
- The YAML file defines a series of actions that AppControl can perform on the \"hello\" component:
- Check Action: Checks the existence and content of the
hello.txt file. - Start Action: Starts the application by creating the
hello.txt file. - Stop Action: Stops the application by removing the
hello.txt file. - Custom Action: Allows users to input a custom message and execute the \"Say Hello\" command.
-
Group Components for Easier Management
- The
Group field organizes components into logical groups for easier management. In this case, the \"hello\" component is grouped under \"Hello group\".
-
Provide a Template for Automation and Customization
- The YAML file serves as a template for automating routine tasks, such as starting and stopping the application, while also allowing customization through user-defined actions.
-
Ensure Scalability and Extensibility
- The structure of the YAML file allows you to scale and extend the configuration by adding more agents, components, or actions as needed for more complex applications.
"},{"location":"gettingStarted/#example-yaml-configuration","title":"Example YAML Configuration","text":"Here\u2019s an example of the YAML configuration for the \"helloworld\" application:
Name: helloworld\nVersion: v1\nIcon: {}\nAgents:\n - Name: LOCAL\n Port: 12567\n SslProtocol: tls12\nAuthentications:\n - Name: LOCAL\nComponents:\n - Name: hello\n Agent:\n AgentName: LOCAL\n AuthentificationName: LOCAL\n Icon:\n SystemName: file\n Group: Hello group\n Description: Hello World\n Actions:\n - Name: check hello\n Type: check\n Value: cat hello.txt\n - Name: start hello\n Type: start\n Value: echo hello > hello.txt\n - Name: stop hello\n Type: stop\n Value: rm hello.txt\n - Name: Say Hello\n Type: custom\n Value: echo $(message)\n InputParameters:\n - Name: message\n Value: Hello\n CanEdit: true\n Validation: '*'\n
"},{"location":"gettingStarted/#connecting-to-local-infrastructure","title":"Connecting to Local Infrastructure","text":"If you wish to manage applications running in your on-premises environment, AppControl can be connected to your local infrastructure through agents and gateways. While this is an advanced setup, it allows for seamless integration with both legacy and cloud applications.
For detailed instructions on how to connect to your local infrastructure, including agent installation and gateway setup, please refer to the documentation.
"},{"location":"mainfeatures/","title":"Main Features of AppControl","text":"AppControl offers a variety of features that help you monitor and manage critical business applications efficiently. Below is a list of the key features available in AppControl.
"},{"location":"mainfeatures/#1-application-dashboard","title":"1. Application Dashboard","text":"Monitor the status of your applications in real time.
- Main Statuses:
- Started: Application is running as expected.
- Stopped: Application is not currently running.
- Degraded: Application is running but has performance or availability issues.
- Error: Application has encountered an error and needs attention.
"},{"location":"mainfeatures/#2-application-operations-history","title":"2. Application Operations History","text":"Track all changes and events related to your applications over time.
- Logs: Detailed logs of when applications were started, stopped, or when any issues occurred.
- Audit trail: A comprehensive view of all actions taken within the system.
"},{"location":"mainfeatures/#3-action-buttons-startstop","title":"3. Action Buttons: Start/Stop","text":"Easily control the lifecycle of your applications.
- Start: Quickly start any application.
- Stop: Gracefully shut down applications.
- Activate/Deactivate applications
- Start aplication
- Stop application
- Cancel current operation (Start/Stop)
- Force check actions
- Edit current application
- Display filters
- Advanced settings
- Show/Hide groups (groups are used to group components)
"},{"location":"mainfeatures/#4-custom-actions-on-demand-actions","title":"4. Custom Actions (On-Demand Actions)","text":"Define and execute custom actions tailored to your application\u2019s needs.
- Examples:
- Diagnostics checks
- Cleanup tasks
- Restart specific components
"},{"location":"mainfeatures/#5-notifications","title":"5. Notifications","text":"Stay informed of application statuses and incidents with integrated notification systems.
- Notification channels:
- SMS alerts for critical events.
- Microsoft Teams notifications to keep your team updated in real time.
"},{"location":"mainfeatures/#6-status-page","title":"6. Status Page","text":"The Status Page in AppControl provides a detailed overview of the availability and health of your critical applications. This page displays the percentage of availability for each application, allowing you to monitor uptime and quickly identify potential issues over the past few days.
"},{"location":"mainfeatures/#key-features","title":"Key Features:","text":" - Application Availability: Shows the percentage of time each application was available and running smoothly, helping you assess the stability and reliability of your applications.
- Historical Data: Analyze the performance of applications over a specific period (e.g., the last 7 or 30 days) to gain insights into trends or recurring issues.
- Color-Coded Indicators:
- Green: High availability (e.g., > 75%)
- Yellow: Moderate availability (e.g., 50-75%)
- Red: Low availability or critical issues (e.g., < 50%)
- Interactive Graphs: Visual representations of uptime fluctuations, making it easy to visualize downtime and availability trends.
This page helps ensure that your applications maintain high levels of availability and reliability by providing a clear and actionable view of their performance over time.
"},{"location":"mainfeatures/#6-integration-with-legacy-and-cloud-applications","title":"6. Integration with Legacy and Cloud Applications","text":"Seamlessly monitor both legacy on-premise applications and cloud-native services without requiring any modifications to existing applications.
"},{"location":"mainfeatures/#7-automated-recovery","title":"7. Automated Recovery","text":"While automated recovery avoids restarting components by default, you can schedule auto restarts using built-in cron expressions to meet your operational needs.
"},{"location":"map/","title":"AppControl Application","text":"In AppControl, applications (also referred to as \"maps\") were traditionally defined using an XML file. However, the preferred and modern format is now YAML, which offers greater flexibility and readability, making it easier to manage complex configurations.
Applications in AppControl are structured as a hierarchy of components, with each component representing a critical part of the system. These components can be defined manually by editing YAML files, giving you full control over every aspect of the application setup. For users who prefer a more guided approach, AppControl also provides built-in wizards within the UI. These wizards simplify the process by generating application definitions based on your local infrastructure or from Azure environments, allowing you to create these files quickly and efficiently.
Whether you choose to manually create your application configurations or leverage the built-in wizards, AppControl offers the flexibility to adapt to your preferred workflow, ensuring seamless integration with your existing systems.
"},{"location":"map/#yaml-format","title":"YAML Format","text":"This document describes the configuration schema for AppControl applications, which is defined in YAML format. The YAML configuration file specifies the structure of an application, including its components, agents, authentication methods, scheduling, and actions.
If you're unfamiliar with YAML, you can learn more about it here: YAML Documentation.
In the YAML format, AppControl configurations are more readable and user-friendly. YAML offers greater support for advanced features and is the recommended format for defining applications in AppControl.
The YAML file typically includes the following key information:
- Component Definitions: Each component is described by a set of commands:
- Check Command: Mandatory for verifying the component's status.
- Start Command: Optional, used to start the component.
- Stop Command: Optional, used to stop the component.
- Custom Commands: Optional, for executing specific tasks or actions tailored to the component.
- Agent List: Specifies the agents responsible for executing the commands for each component.
- Identity Information: Defines which users are authorized to run the commands for specific components.
- Scheduling Information: Allows scheduling of start/stop commands for automatic execution at predefined times.
Full YAML Format described below:
"},{"location":"map/#1-name","title":"1. Name","text":" - Type:
string - Description: The name of the service.
"},{"location":"map/#2-version","title":"2. Version","text":" - Type:
string - Description: The version of the service.
"},{"location":"map/#3-description","title":"3. Description","text":" - Type:
string - Description: A brief description of the service.
"},{"location":"map/#4-nbretry","title":"4. NbRetry","text":" - Type:
integer - Description: The number of restart attempts for the service.
"},{"location":"map/#5-variables","title":"5. Variables","text":" - Type:
array - Description: A list of variables used by the service.
- Properties:
- Name: The name of the variable (
string). - Value: The value of the variable (
string).
"},{"location":"map/#6-agents","title":"6. Agents","text":" - Type:
array - Description: A list of agents responsible for executing commands.
- Properties:
- Name: The name of the agent (
string). - Address: The address of the agent (
string). - Port: The port used by the agent (
integer). - Gateway: The gateway used by the agent (
string). - DependsOnComponent: Specifies that the agent is triggered when the component is started (
string). - SslProtocol: The SSL protocol used by the agent (
tls, tls12, or tls13).
"},{"location":"map/#7-authentications","title":"7. Authentications","text":" - Type:
array - Description: A list of authentication methods used for securing agent communications.
- Properties:
- Name: The name of the authentication method (
string).
"},{"location":"map/#8-schedulingstart","title":"8. SchedulingStart","text":" - Type:
array - Description: Scheduling of start tasks using cron expressions.
- Properties:
- Name: The name of the start task (
string). - Expression: The cron expression that defines the schedule (
string).
"},{"location":"map/#9-schedulingstop","title":"9. SchedulingStop","text":" - Type:
array - Description: Scheduling of stop tasks using cron expressions.
- Properties:
- Name: The name of the stop task (
string). - Expression: The cron expression that defines the schedule (
string).
"},{"location":"map/#10-components","title":"10. Components","text":" - Type:
array - Description: The components of the service, each defined by a set of properties and actions.
- Properties:
- Name: The name of the component (
string). - DisplayName: The display name of the component (
string). - Agent: Defines the agent associated with the component, including:
- AgentName: The name of the agent (
string). - AuthentificationName: The name of the authentication method used (
string).
- CheckFrequency: The frequency (in seconds) for checking the status of the component (
integer). - Icon: Icon properties, including:
- SystemName: The system name of the icon (e.g.,
browser, sqlserver, etc.) (string). - Url: The URL for the icon (
string).
- Group: The component's group (
string). - Description: A description of the component (
string). - Actions: A list of actions available for the component:
- Name: The name of the action (
string). - Type: The type of the action (
string). - Value: The command to execute the action (
string). - RetryTime: The time to retry the action (
integer). - Visibility: Visibility of the action (
Private, Public). - WaitAfter: Time to wait after the action (
integer). - Description: A description of the action (
string). - InputParameters: Input parameters for the action:
- Name: The name of the parameter (
string). - Value: The value of the parameter (
string). - Description: A description of the parameter (
string). - CanEdit: Specifies if the parameter can be edited (
boolean). - Validation: Validation rules for the parameter (
string).
- OutputParameters: Output parameters for the action:
- Name: The name of the parameter (
string). - Value: The value of the parameter (
string). - Description: A description of the parameter (
string).
- HypertextResources: Additional hypertext resources related to the action.
"},{"location":"map/#11-triggers","title":"11. Triggers","text":" - Type:
array - Description: Cron-based triggers for the components.
- Properties:
- Name: The name of the trigger (
string). - Expression: The cron expression (
string). - TimeZoneId: The time zone ID for the trigger (
string).
"},{"location":"map/#12-filters","title":"12. Filters","text":" - Type:
array - Description: Filters that define specific conditions for components.
- Properties:
- Name: The name of the filter (
string). - Value: The value for the filter (
string).
"},{"location":"map/#13-interactwithdesktop","title":"13. InteractWithDesktop","text":" - Type:
boolean - Description: (Windows only) Specifies if the agent running as a service can interact with the desktop.
"},{"location":"map/#required-fields","title":"Required Fields","text":"The following fields are required in the AppControl YAML configuration file:
- Name
- Version
- Description
- NbRetry
- Agents
- Authentications
- Components
Below is an example of a minimalist AppControl Hello World artefact in YAML:
Name: helloworld\nVersion: v1\nIcon: {}\nAgents:\n - Name: LOCAL\n Port: 12567\n SslProtocol: tls12\nAuthentications:\n - Name: LOCAL\nComponents:\n - Name: hello\n Agent:\n AgentName: LOCAL\n AuthentificationName: LOCAL\n Icon:\n SystemName: file\n Group: Hello group\n Description: Hello World\n Actions:\n - Name: check hello\n Type: check\n Value: cat hello.txt\n - Name: start hello\n Type: start\n Value: echo hello > hello.txt\n - Name: stop hello\n Type: stop\n Value: rm hello.txt\n - Name: Say Hello\n Type: custom\n Value: echo $(message)\n InputParameters:\n - Name: message\n Value: Hello\n CanEdit: true\n Validation: '*'\n
"},{"location":"map/#xml-format","title":"XML Format","text":"While the XML format is still supported, it is generally less flexible and more complex than YAML. The XML format is often used for legacy configurations.
The XML file typically includes the following key information:
-
Component Definitions: Each component is described by a set of commands:
- Check Command: Mandatory for verifying the component's status.
- Start Command: Optional, used to start the component.
- Stop Command: Optional, used to stop the component.
- Custom Commands: Optional, for executing specific tasks or actions tailored to the component.
-
Agent List: Specifies the agents responsible for executing the commands for each component.
-
Identity Information: Defines which users are authorized to run the commands for specific components.
-
Scheduling Information: Allows scheduling of start/stop commands for automatic execution at predefined times.
Below is an example of a minimalist AppControl Hello World artefact in XML:
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <hosts>\n <!-- The way to join the agent -->\n <host hostid=\"LOCAL\" host=\"127.0.0.1\" port=\"12567\" sslprotocol=\"tls12\" />\n </hosts>\n <auths>\n <!-- Identity of the user executing the commands. If empty, commands inherit from agent credentials -->\n <auth authid=\"LOCAL\" domain=\"\" password=\"\" user=\"\" />\n </auths>\n <app name=\"helloworld\" version=\"v1\" retry=\"1\">\n <!-- A simple component executing an 'echo command' every minute -->\n <component name=\"hello\" hostref=\"LOCAL\" authref=\"LOCAL\" redirectoutput=\"true\" checkFrequency=\"60\" type=\"file\">\n <action value=\"cat hello.txt\" name=\"check\" />\n <action value=\"echo hello > hello.txt\" name=\"enable\" />\n <action value=\"rm hello.txt\" name=\"disable\" />\n <action value=\"echo $(message)\" commandname=\"echo Action\" name=\"custom\">\n <parameters>\n <parameter name=\"message\" value=\"Hello\" canedit=\"true\" validation=\"*\" />\n </parameters>\n </action>\n </component>\n </app>\n</apps>\n\n
"},{"location":"map/#xml-tag-descriptions","title":"XML Tag Descriptions","text":""},{"location":"map/#the-apps-tag","title":"The <apps> Tag","text":"The <apps> tag is the root element that contains all the elements of the configuration.
<apps>\n <hosts>...</hosts>\n <auths>...</auths>\n <app>...</app>\n <crontable>...</crontable>\n</apps>\n
"},{"location":"map/#the-hosts-tag","title":"The <hosts> Tag","text":"The hosts tag groups together a set of host tags that describe the agents used to communicate with the components.
Attribute Description host Required Value: string. Name to resolve or IPv4 address of the machine to be contacted on the network port Required Value: integer. Tcp port number to use join the agent. hostid Required Value: string. Mnemonic name to designate the host agent and which will then be used as the value of the hostref attribute in a component tag. sslprotocol Optional Default value is set to tls12. Possible values: ssl, tls, tls12. Note: on most Operating Systems ssl and tls are obsolete"},{"location":"map/#the-auths-tag","title":"The <auths> Tag","text":"The auths tag groups together a set of auth tags that describe the identities used to perform actions on application components. These identities will be utilized by agents.
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <auths>\n <auth authid=\"LOCAL\" domain=\"\" password=\"\" user=\"\" />\n </auths>\n <!-- ... -->\n</apps>\n
Attribute Description authid Required A mnemonic name used to identify the identity that will be referenced by the authref attribute in a component tag. user Required Can be empty. The username or identity. If this value is empty, the username will default to the one running the agent. password Required Can be empty. Value: string. The user's clear text password for authentication. If both the username and password are empty, the identity will default to the one running the agent. domain Optional Microsoft Windows only. The Windows domain name for authentication. |\n
"},{"location":"map/#the-app-tag","title":"The <app> Tag","text":"The app tag defines the application and its version It can also contain a reference to a cron schedule for automatic actions.
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <app name=\"TrainingMap\" version=\"current\" cronref=\"MCO\">\n <!-- ... -->\n </app>\n <!-- ... -->\n</apps>\n
Attribute Description name Required Mnemonic name to designate an application version Required . Mnemonic name of the application version. Perhaps in a numbered form \"1.3.6\", named \"current\" or mixed \"1.3.6-Stable\" cronref Optional Reference to a \"crontable\" retry Optional Value: integer. The value of the default number of retries to perform component actions on the application"},{"location":"map/#the-component-tag","title":"The <component> Tag","text":"The component tag defines the individual components of the application and their actions (check, start, stop, custom).
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <app name=\"TrainingMap\" version=\"current\" cronref=\"MCO\">\n <component name=\"File exist\" group=\"TEST\" hostref=\"LOCAL\" authref=\"LOCAL\">\n <action name=\"check\" value=\"dir componentFile.txt\" />\n <action name=\"enable\" value=\"echo start > componentFile.txt\" />\n <action name=\"custom\" visibility=\"Public\" commandname=\"File search\" value=\"dir $(file)\">\n <parameters>\n <parameter name=\"file\"\n description=\"Filename to list\"\n value=\"\"\n canedit=\"true\"\n validation=\"\\S+\"\n />\n </parameters>\n </action>\n </component>\n </app>\n <!-- ... -->\n</apps>\n
Attribute Description name Required Name of the component (should be unique in the application). group Optional Name of the group. Used to group a set of components in the UI. hostref Mandatory Value: string. Reference to the agent (see <hosts> tag). Required if not set on the action. authref Mandatory Value: string. Reference to the agent identity (see <auths> tag). Required if not set on the action. type Optional Used to display an icon on the map. A URL to an image (png, jpeg, or svg) can be set. You can also use one of the following values: browser, cd, chip, data-information, devices, dollar, euro, file, green-thermometer, hdd, memflash, memory, middleware, network, orange-thermometer, pounds, process, service, tools, user, yen. description Optional Value: string. Label of the component in addition to the name. redirectoutput Optional Value: boolean. If set to true, standard output will be parsed to find dynamic messages or dynamic components. checkFrequency Optional Value: integer. Component check cycle frequency (in seconds). The default value is set at the server configuration level. retryNumber Optional Value: integer. Maximum number of retry attempts. displayname Optional Value: string. Display name of an application component, replacing \"name\" in the UI."},{"location":"map/#the-father-tag","title":"The father TAG","text":"The father tag creates a dependency on a component. AppControl's approach is based on the principle that child components have knowledge of their parent(s). Multiple parents for a component are allowed. However, be careful not to create a loop, as it is not allowed and will generate an error during loading.
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <app name=\"TrainingMap\" version=\"current\" cronref=\"MCO\">\n <component name=\"File exist\" group=\"TEST\" hostref=\"LOCAL\" authref=\"LOCAL\">\n <father>Attribut NAME du COMPOSANT PERE #1</father>\n <father>Attribut NAME du COMPOSANT PERE #2</father>\n <action name=\"check\" value=\"dir componentFile.txt\" />\n <action name=\"enable\" value=\"echo start > componentFile.txt\" />\n <action name=\"check\" value=\"del /Q componentFile.txt\" />\n <action name=\"custom\" visibility=\"Public\" commandname=\"File search\" value=\"dir $(file)\">\n <parameters>\n <parameter name=\"file\"\n description=\"Filename to list\"\n value=\"\"\n canedit=\"true\"\n validation=\"\\S+\"\n />\n </parameters>\n </action>\n </component>\n </app>\n <!-- ... -->\n</apps>\n
"},{"location":"map/#the-action-tag","title":"The action TAG","text":"The action tag is used to describe four kinds of actions:
- check: Periodic verification of the component's state at a specified frequency (in seconds). Only one
check action is allowed per component. - enable: Starts a component. Only one
enable action is allowed per component. - disable: Stops a component. Only one
disable action is allowed per component. - custom: Custom commands executed on demand. There can be 0 to n
custom actions per component.
<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <app name=\"TrainingMap\" version=\"current\" cronref=\"MCO\">\n <component name=\"File exist\" group=\"TEST\" hostref=\"LOCAL\" authref=\"LOCAL\">\n <!-- ... -->\n <action name=\"check\" value=\"dir componentFile.txt\" />\n <action name=\"enable\" value=\"echo start > componentFile.txt\" />\n <action name=\"check\" value=\"del /Q componentFile.txt\" />\n <action name=\"custom\" visibility=\"Public\" commandname=\"File search\" value=\"dir $(file)\">\n <parameters>\n <parameter name=\"file\"\n description=\"Filename to list\"\n value=\"\"\n canedit=\"true\"\n validation=\"\\S+\"\n />\n </parameters>\n </action>\n </component>\n </app>\n <!-- ... -->\n</apps>\n
Attribute Description name Required Value: Specifies the type of check. Possible values: enable, disable, custom. value Required The command line to execute. retryTime Optional Value: integer. Time in seconds before retrying communication with the agent. commandname Required Display name or identifier of the command. visibility Optional Controls the visibility of this custom action outside of AppControl (in XC Scenario). If set to Public, the AppControl worker will publish this action as a Scenario task. The default is Private, meaning the action will not be published. parameters Optional Used to display an icon on the map. A URL to an image (png, jpeg, or svg) can be set. You can also use one of the following values: browser, cd, chip, data-information, devices, dollar, euro, file, green-thermometer, hdd, memflash, memory, middleware, network, orange-thermometer, pounds, process, service, tools, user, yen. hostref Optional Value: string. Reference to the agent (see <hosts> tag). Required if not set on the component. authref Optional Value: string. Reference to the agent identity (see <auths> tag). Required if not set on the component."},{"location":"map/#the-parameters-tag","title":"The parameters TAG","text":"<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <!-- ... -->\n <app name=\"TrainingMap\" version=\"current\" cronref=\"MCO\">\n <component name=\"File exist\" group=\"TEST\" hostref=\"LOCAL\" authref=\"LOCAL\">\n <!-- ... -->\n <action name=\"custom\" visibility=\"Public\" commandname=\"File search\" value=\"dir $(file)\">\n <parameters>\n <parameter name=\"file\"\n description=\"Filename to list\"\n value=\"\"\n canedit=\"true\"\n validation=\"\\S+\"\n />\n </parameters>\n </action>\n </component>\n </app>\n <!-- ... -->\n</apps>\n
The parameters tag is used to define the parameters of custom actions. These parameters will be available in the UI.
The syntax for variables in AppControl is: $(variableName) Within the parameters tag, several parameter tags can be defined with the following attributes:
Attribute Description name Required The name of the variable. description Optional A description of the variable. This description is displayed in the UI. value Required The default value of the variable. canedit Optional Values: True (default) or False. If False, the value cannot be edited in the UI. validation Optional Value: regex. A regular expression applied to validate the value."},{"location":"map/#the-crontable-tag","title":"The crontable TAG","text":"<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<apps>\n <crontable>\n <cronrules cronid=\"scheduling\">\n <trigger name=\"CRON#1\" action=\"stop\" force=\"true\" components=\"A1\" propagate=\"false\" expression=\"0 00 * * * ? *\" />\n <trigger name=\"CRON#2\" action=\"start\" force=\"true\" components=\"A1\" propagate=\"true\" expression=\"0 15 * * * ? *\" />\n <trigger name=\"customDir\" action=\"custom\" components=\"A1\" customactionname=\"dirAction\" customactionparameters=\"option=c;directory=c:\\temp\" expression=\"0 0/5 * 1/1 * ? *\" />\n <trigger name=\"CRON#3\" action=\"stop\" expression=\"0 0/5 * 1/1 * ? *\" />\n <trigger name=\"CRON#3\" action=\"start\" expression=\"0 0/2 * 1/1 * ? *\" />\n </cronrules>\n </crontable>\n\n <app name=\"CronDemo\" version=\"v1\" cronref=\"scheduling\">\n <component name=\"A1\" description=\"A1 component\" hostref=\"LOCAL\" authref=\"LOCAL\" >\n <action value=\"echo demo\" name=\"check\" />\n <action value=\"start.sh\" name=\"enable\" />\n <action value=\"stop.sh\" name=\"disable\" />\n <action name=\"custom\" commandname=\"Perl version\" value=\"C:\\Strawberry\\perl\\bin\\perl.exe -$(version)\">\n <parameters>\n <parameter name=\"version\" value=\"V\" canedit=\"false\" validation=\"*\" />\n </parameters>\n </action>\n <action value=\"dir -$(option) $(directory)\" visibility=\"public\" commandname=\"dirAction\" name=\"custom\">\n <parameters>\n <parameter name=\"option\" value=\"c\" canedit=\"false\" validation=\"*\" />\n <parameter name=\"directory\" value=\"c:\\sources\\*\" canedit=\"true\" validation=\"*\" />\n </parameters>\n </action>\n </component>\n </app>\n</apps>\n
You can refer to the Quartz Scheduler documentation for a complete list of allowed cron expressions.
As shown in the example above, you can include multiple cron expressions in the same file. You can schedule start/stop actions or custom actions.
"},{"location":"map/#built-in-wizards","title":"Built-in wizards","text":""},{"location":"map/#auto-generate-application-from-running-processes","title":"Auto-Generate Application from Running Processes","text":"AppControl includes the ability to retrieve running processes on a computer through its agent. The agent, which runs on the target system (Windows or Linux), scans the machine for all active processes and reports them back to AppControl.
In the AppControl wizard, this data is then utilized to allow you to easily create applications (also referred to as \"maps\"). The wizard displays the list of running processes, and you can select the ones you wish to include in your application definition. Once selected, AppControl automatically generates a YAML file that represents the application.
The generated application is capable of starting, stopping, and checking the status of the selected processes. This provides a seamless way to monitor and control your applications' critical components without the need for manual configuration, ensuring that you can manage both legacy and modern systems efficiently.
- To start the wizard go to Overview/New application and select Discover your infrastructure
- Select: From Servers and then select your gateway and your agent.
"},{"location":"map/#auto-generate-application-from-azure-tenant","title":"Auto-Generate Application from Azure Tenant","text":"AppControl includes the ability to retrieve and visualize Azure resources from your Azure tenant through its integration with Azure APIs. Using its agent which interacts directly with your Azure environment, AppControl can scan your Azure tenant for all active resources and report them back to AppControl.
In the AppControl wizard, this data is utilized to help you easily create applications (also referred to as \"maps\"). The wizard displays a list of your Azure resources, such as virtual machines, databases, and other components, allowing you to select the ones you wish to include in your application definition. Once selected, AppControl automatically generates a YAML file that represents the application based on your Azure infrastructure.
The generated application is capable of starting, stopping, and checking the status of the selected Azure resources, providing a seamless way to monitor and control your critical cloud components. This eliminates the need for manual configuration and ensures that you can manage both cloud-native and hybrid environments efficiently.
Before starting the wizard, you have the good credentials.
To use the Azure discovery feature in AppControl, you will need to create an Azure Service Principal with sufficient permissions to allow AppControl to interact with your Azure resources.
Step 1: Create a Service Principal
- Open your terminal or command-line interface.
- Run the following command to create a service principal and assign it the \"Reader\" role (sufficient for discovery and read-only access to resources). It's better to limit the scope to specific resources but it's not mandatory. Ensure that you replace with your actual Azure subscription ID:
az ad sp create-for-rbac --name \"AppControlServicePrincipal\" --role Reader --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>\n
- Output: The command will return a JSON object containing:
AppId (Client ID) Password (Client secret) Tenant (Tenant ID) Subscription ID (Subscription scope where the role is assigned) Save this information securely as it will be required for configuring AppControl.
Step 2: Assign Permissions (OPTIONAL)
If you need to limit the service principal's permissions to specific resource groups, or if you need to grant more access (such as managing resources), you can assign additional roles. For example, to restrict access to specific resource groups, use this command:
az role assignment create \\\n --role Reader \\\n --assignee <AppId> \\\n --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>\n
Step 3: Configure AppControl with the Service Principal Credentials
Once you\u2019ve created the Service Principal, you need to provide the credentials to AppControl for authentication.
- Navigate to Overview/New application and select Discover your infrastructure.
- Choose From Azure
- Enter the Client User Name, Client Password (obtained when creating the Service Principal), Tenant ID, Subscription ID and Tenant ID.
AppControl will use these credentials to authenticate with Azure and retrieve your resources.
This feature empowers you to visualize and manage your entire Azure infrastructure directly from AppControl, ensuring real-time control over your cloud assets.
"},{"location":"repo/","title":"Git integration","text":"AppControl YAML or XML files can be conveniently stored in a Git repository for version control and collaboration. Additionally, you can display the live status of your application directly in your documentation by adding a markdown badge link. For example:
\n
This badge will display the real-time status of your application in your documentation.
"},{"location":"repo/#automating-application-deployment-with-appcontrol-apis","title":"Automating Application Deployment with AppControl APIs","text":"AppControl provides powerful APIs that allow for automatic deployment of applications through custom scripts. These scripts can be integrated into your CI/CD pipelines or used for ad-hoc deployments. Below is a generic example of a script that loads and deploys an application map (in YAML or XML format) to AppControl.
Sample Deployment Script
#!/usr/bin/env bash\nset -o errexit\nset -o nounset\n\n# API endpoint for AppControl\nexport API=${APPCONTROL_HOME:-https://appcontrol.xcomponent.com}/core\n\ndebug() {\n [[ \"${DEBUG:-0}\" != \"0\" ]] && echo \"$@\"\n}\n\nmain() {\n # Check if the required parameters are passed\n if [[ $# -lt 2 ]]; then\n echo \"Usage: $0 <map-file> <gateway-name>\"\n exit 1\n fi\n\n local mapFile=\"$1\"\n local agentProxyName=\"$2\"\n local mapFileContents=$(cat \"$mapFile\")\n\n # Extract application name and version from the map file (XML or YAML)\n local mapName=$(grep \"<app name\" \"$mapFile\" | cut -d \"\\\"\" -f2)\n local mapVersion=$(grep \"<app name\" \"$mapFile\" | cut -d \"\\\"\" -f4)\n local escapedMapFileContents\n\n # Check if XML parsing failed (if mapName or mapVersion is empty, fallback to YAML)\n if [[ -z \"$mapName\" ]] || [[ -z \"$mapVersion\" ]]; then\n echo \"XML parsing failed or not XML format. Trying YAML...\"\n\n # Attempt to read the file as YAML using yq\n mapName=$(yq e '.Name' \"$mapFile\")\n mapVersion=$(yq e '.Version' \"$mapFile\")\n\n if [[ -z \"$mapName\" ]] || [[ -z \"$mapVersion\" ]]; then\n echo \"YAML parsing failed. Please check the file format.\"\n exit 1\n fi\n fi\n\n # Escape file contents to be used in the JSON payload\n escapedMapFileContents=$(echo \"$mapFileContents\" | jq -aRs .)\n\n # Prepare the data payload for the API\n data=$(jq -n --arg xml \"$escapedMapFileContents\" \\\n --arg app \"$mapName\" \\\n --arg version \"$mapVersion\" \\\n --arg gateway \"$agentProxyName\" \\\n '{\n Xml: $xml,\n Application: $app,\n Version: $version,\n AgentProxyName: $gateway,\n LoadMap: \"true\",\n OverWrite: \"true\",\n UseDefaultAgent: \"false\"\n }')\n\n echo \"Loading $mapName $mapVersion using gateway $agentProxyName...\"\n\n # Send the API request\n curl $API/api/Configuration -X PUT \\\n --header \"Content-Type: application/json\" \\\n --header \"Authorization: bearer $AUTH\" \\\n --data-binary \"$data\" \\\n --fail\n}\n\nmain \"$@\"\n\n
Example of usage
./deploy_app.sh myapp.yaml Azure_Gateway\n
This script will upload the myapp.yaml file and use the specified gateway (Azure_Gateway).
"},{"location":"standalone/","title":"Running AppControl Locally with Docker Compose","text":"This package lets you install and run Invivoo's X4B AppControl software locally on a Windows PC. To install X4B AppControl in standalone under Windows OS, unzip the following file into an installation directory, and move into that directory.
"},{"location":"standalone/#appcontrol-license-and-usage-terms","title":"AppControl License and Usage Terms","text":"AppControl is free to use for educational purposes. For production use, please contact Invivoo.
"},{"location":"standalone/#installing-appcontrol-locally","title":"Installing AppControl Locally","text":"The AppControl software is delivered as a set of container images, meant to be run inside a container orchestrator such as Kubernetes or Red Hat's OpenShift. Invivoo provides Helm charts for this installation, which is the recommended deployment method for production environments.
For a newcomer discovering AppControl for the first time, Invivoo is providing this deployment method, using Docker Compose, to make it easy to quickly set up an AppControl instance locally, on your laptop, and immediately start exploring its possibilities.
AppControl includes a gateway and agents that will let you manage any system, local or remote, from this local instance. Conversely, remote workstations will also be able to access and use this instance, meaning the AppControl web-based UI will be accessible from every machine on your network.
Note that this setup is NOT recommended for production deployments.
"},{"location":"standalone/#requirements","title":"Requirements","text":"You will need Docker Desktop on your PC. Invivoo recommends choosing WSL 2 over Hyper-V for the Linux virtualization (see installation instructions below).
You will need at least 16 Gb of RAM and 5 Gb of available disk space.
"},{"location":"standalone/#installation-instructions","title":"Installation Instructions","text":""},{"location":"standalone/#docker-desktop","title":"Docker Desktop","text":"To install the latest version of Docker Desktop, follow the instructions on their website.
In the System Requirements section, choose WSL 2 backend, and follow the instructions from Microsoft to enable the feature and install WSL.
"},{"location":"standalone/#appcontrol-with-docker-compose","title":"AppControl with Docker Compose","text":"Docker Compose is a tool for defining and running multi-container Docker applications. Invivoo provides the appcontrol.yml file to configure AppControl's services. This lets you create and start all the services with a single command.
Make sure that Docker Desktop is started. Open a command line tool (a normal one, administrator rights are not required), and run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml up -d\n
The command will start by retrieving all the required container images from Invivoo's DockerHub repository, this may take a few minutes. After that, the containers are started with the docker run command. Subsequent runs will reuse the locally-stored images.
When the command has finished executing, you should see an output similar to this:
- Network appcontrol-compose_default Created 0.8s\n - Container appcontrol-compose-rabbit-1 Started 8.4s\n - Container appcontrol-compose-gateway-1 Started 8.5s\n - Container appcontrol-compose-agentdebian-1 Started 8.9s\n - Container appcontrol-compose-login-1 Started 8.9s\n - Container appcontrol-compose-sql-1 Started 9.0s\n - Container appcontrol-compose-redis-1 Started 8.3s\n - Container appcontrol-compose-webapp-1 Started 8.8s\n - Container appcontrol-compose-notification-1 Started 12.6s\n - Container appcontrol-compose-api-1 Started 15.8s\n - Container appcontrol-compose-configvalidator-1 Started 12.2s\n - Container appcontrol-compose-agentmanager-bridge-1 Started 15.3s\n - Container appcontrol-compose-dbaccess-1 Started 13.7s\n - Container appcontrol-compose-scheduler-1 Started 14.5s\n - Container appcontrol-compose-launcher-1 Started 14.8s\n - Container appcontrol-compose-launcher-dispatcher-1 Started 10.3s\n - Container appcontrol-compose-statistics-1 Started 14.4s\n - Container appcontrol-compose-agentmanager-1 Started 15.2s\n - Container appcontrol-compose-agentstatus-1 Started 15.3s\n - Container appcontrol-compose-apps-1 Started 17.3s\n - Container appcontrol-compose-authentication-1 Started 21.0s\n
The AppControl services are up and running.
"},{"location":"standalone/#using-the-web-interface","title":"Using the Web Interface","text":"In your web browser, navigate to http://localhost:4000 to access the AppControl webapp. Use the following credentials to login:
- login:
admin - password:
KoordinatorAdmin
"},{"location":"standalone/#getting-help","title":"Getting Help","text":"Once you're logged into AppControl, you can access the online documentation through the help button (?) on the top right of the screen:
The dropdown menu also lets you contact Invivoo support through email, and join our Slack channel for access to the development team.
"},{"location":"standalone/#test-appcontrol-with-the-helloworld-map","title":"Test AppControl with the Helloworld map","text":"The installation package includes a sample AppControl map to help you get started. In the webapp, import the sample map by clicking on the New application button and uploading the file called hellowworld,v1.xml.
Here's a tutorial video to help you get started: Helloworld tutorial
"},{"location":"standalone/#stop-uninstall-appcontrol","title":"Stop / Uninstall AppControl","text":"Run the following command to stop AppControl:
docker-compose -f appcontrol.yml -f appcontrol-images.yml stop\n
If you want to start again, run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml up -d\n
To completely remove AppControl, run the following command:
docker-compose -f appcontrol.yml -f appcontrol-images.yml rm\n
"},{"location":"x4bcli/","title":"Introduction","text":"To fully utilize AppControl's capabilities with on-premises infrastructure, the X4B Gateway is required. The gateway facilitates secure communication between your on-premises agents and the AppControl SaaS platform. This allows for real-time monitoring and control of your local applications, even when agents are deployed across diverse environments.
X4B Gateway Overview The X4B Gateway acts as a secure link, enabling AppControl to interact with agents deployed on your local infrastructure. The gateway ensures that actions, incidents, and monitoring data are reliably communicated between the agents and the SaaS platform.
Agent Deployment Agents can be deployed anywhere within your Information System (I.S.) to manage and monitor your local applications. One of the key benefits of the AppControl agent architecture is that agents do not require direct internet access. The agents communicate with the X4B Gateway, which handles secure data transfer to the AppControl SaaS platform.
Getting Started with Agents To begin using agents in your local infrastructure, please refer to the Agents Installation section for step-by-step instructions on installing agents on Windows and Linux environments.
Please refer to the Agents Installation section for detailed installation instructions.
Thanks to the X4B Gateway, you can deploy your applications in the AppControl Cloud Platform while keeping agents deployed on-premises.
"},{"location":"x4bcli/#quick-deployment-of-agents-and-gateways-windows-and-macos","title":"Quick Deployment of Agents and Gateways (Windows and macOS)","text":"For both Windows and macOS, there is a quick and efficient way to deploy both agents and the X4B Gateway at the same time. This process requires administrative permissions and will prompt the user to log in to the SaaS platform to link the gateway with their user account.
"},{"location":"x4bcli/#windows-deployment","title":"Windows Deployment","text":"To deploy the agent and gateway on Windows, use the following PowerShell script:
irm https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/docs/en/scripts/appcontrolinstall.ps1 | iex\n
This script will:
- Install the agent and the X4B Gateway on your local machine.
- Prompt you to log in to the AppControl SaaS platform during installation to link the gateway with your user account.
"},{"location":"x4bcli/#macos-deployment","title":"macOS Deployment","text":"To deploy the agent and gateway on macOS, use the following bash script:
bash -c \"$(curl -fsSL https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/docs/en/scripts/appcontrolinstallmac.sh)\"\n
This script will:
- Install the agent and the X4B Gateway on your macOS system.
- Prompt you to log in to the AppControl SaaS platform during installation to link the gateway with your user account.
Important Notes:
- Administrative permissions are required to execute these scripts.
- The user will be prompted to log in during the installation process to complete the linkage between the gateway and the user account in the AppControl SaaS platform.
For more detailed steps on the installation and troubleshooting, please refer to the Agents Installation section.
"},{"location":"x4bcli/#x4b-gateway-custom-installation","title":"X4B Gateway custom installation","text":"Gateways are available for Windows and Docker. For Windows, the .NET framework is required. The X4B Gateway is necessary to take advantage of agents deployed on-premises.
Agents can be deployed anywhere in your infrastructure. They do not need internet access.
Please refer to the agents installation section for detailed instructions on agent installation.
"},{"location":"x4bcli/#latest-available-versions","title":"Latest Available Versions","text":"Operating System Format Latest Version Microsoft Windows zip Windows Gateway Zip N/A docker docker pull xcomponent/x4b-gateway:latest"},{"location":"x4bcli/#how-does-it-work","title":"How does it work ?","text":"The first step is to log in and navigate to this page: AppControl.
-
Click on Register New Gateway
-
Provide a name for your gateway and confirm.
-
Once your gateway is created, an Access Key and a Secret Access Key will be generated.
-
Now, you're ready to install the X4B Gateway. Please refer to the documentation below for the installation procedure.
-
Since the X4B Gateway communicates with agents, you'll need to install at least one agent.
-
Once your X4B Gateway and agent are up and running, you\u2019re ready to deploy a new application.
"},{"location":"x4bcli/#retrieving-x4b-gateway-credentials","title":"Retrieving X4B Gateway Credentials","text":"The first step is to retrieve the X4B Gateway credentials. Navigate to the Gateway page and note the following information:
- Name
- Access Key
-
Secret Access Key
"},{"location":"x4bcli/#microsoft-windows-platform-installation","title":"Microsoft Windows Platform Installation","text":"On Microsoft Windows, the .NET Framework 4.7.2 or later is required.
In most cases, it is already installed. Unzip the following file.
The quickest method is to execute the following command in a PowerShell window with administrative permissions. This command will install the gateway and the agent as Windows services:
irm https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/main/scripts/appcontrolinstall.ps1 | iex\n
Note:
For the other installation procedures mentioned above, we recommend using cmd.exe as the shell to install the gateway and the agent. We do not support installation via PowerShell.\n
On a prompt (cmd.exe), execute the following command line. Replace MY_ACCESS_KEY, MY_SECRET_ACCESSKEY and MY_GATEWAY_NAME with the suitable values.
c:\\x4b> x4b run gateway -a MY_ACCESS_KEY -k MY_SECRET_ACCESSKEY -p MY_GATEWAY_NAME [-l Trace]\n
You can also, set the following environment variables:
c:\\x4b> set X4B_ACCESS_KEY = MY_ACCESS_KEY\nc:\\x4b> set X4B_SECRET_ACCESS_KEY = MY_SECRET_ACCESSKEY\nc:\\x4b> set X4B_PROXY_NAME = MY_GATEWAY_NAME\n
If the configuration is correct, you should see the following lines in the terminal:
__ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2021\n25/02/2021 09:15:20# X4B Gateway is up and running... (Press Ctrl+C to exit)\n25/02/2021 09:15:21# Waiting for websocket connection\n25/02/2021 09:15:39# HeartBeat successfully published\n25/02/2021 09:15:39# Websocket connection established\n\n
"},{"location":"x4bcli/#microsoft-windows-service-installation","title":"Microsoft Windows service Installation","text":"In a prompt with administrative permissions:
c:\\x4b> x4b install -servicename x4bGatewayServiceName -server \"https://appcontrol.xcomponent.com/core\" -loglevel \"Trace\" -access \"myAccesToken\" -proxyname \"myGatewayName\" -secret \"mySecretToken\"\n
The first parameters to register the gateway as a service is the topshelf syntax:
Topshelf Command-Line Reference \u2014 Topshelf 3.0 documentation
The following parameters are specific to the gateway:
-server \"https://appcontrol.xcomponent.com/core\" -loglevel \"Trace\" -access \"myAccesToken\" -proxyname \"myGatewayName\" -secret \"mySecretToken\"
"},{"location":"x4bcli/#docker-installation","title":"Docker Installation","text":"The docker image is available on docker hub: x4b-gateway
docker run -e X4B_ACCESS_KEY=MY_ACCESS_KEY -e X4B_SECRET_ACCESS_KEY=MY_SECRET_ACCESSKEY -e X4B_PROXY_NAME=MY_GATEWAY_NAME xcomponent/x4b-gateway:latest\n
If the configuration is correct, you should observe the following lines in the terminal:
__ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2021\n25/02/2021 09:15:20# X4B Proxy is up and running... (Press Ctrl+C to exit)\n25/02/2021 09:15:21# Waiting for websocket connection\n25/02/2021 09:15:39# HeartBeat successfully published\n25/02/2021 09:15:39# Websocket connection established\n\n
"},{"location":"x4bcli/#display-environment-variables","title":"Display environment variables","text":"c:\\x4b>x4b env\n
"},{"location":"x4bcli/#install-and-run-the-gateway-with-docker-and-builtin-command-of-the-gateway","title":"Install and run the gateway with docker and builtin command of the gateway","text":"c:\\x4b>x4b run docker -a|--accesskey <accesskey> -k|--secretaccesskey <secretaccesskey> -p|--gatewayname <gatewayname> [-l|--loglevel <loglevel>] [-i|--imagetag <imagetag>] [-u|--urlserver <urlserver>]\n
"},{"location":"x4bcli/#remove-appcontrol-gateway-service-from-the-workstation","title":"Remove Appcontrol Gateway service from the workstation","text":"c:\\x4b>x4b uninstall -servicename x4bGatewayServiceName\n
"},{"location":"x4bcli/#remove-appcontrol-gateway-container-running-with-docker","title":"Remove Appcontrol Gateway container running with Docker","text":"c:\\x4b>x4b uninstall docker -c|--containername MY_GATEWAY_NAME\n
"},{"location":"x4bcli/#display-help","title":"Display Help","text":"x4b -v|--version x4b [command] -h x4b subcommand [command] -h|--help
c:\\x4b>x4b -h // display list of commands available\nc:\\x4b>x4b run -h // display help for command run\nc:\\x4b>x4b run docker -h //display help for the subcommand\nc:\\x4b>x4b run gateway -h // display help for the subcommand\nc:\\x4b>x4b uninstall docker -h // display help for this specific command\n
"},{"location":"x4bcli/#check-appcontrols-agent-communication","title":"Check AppControl's Agent Communication","text":"The gateway can also be useful for checking if the agent is up and running. Agents can be deployed on the same computer as the gateway or elsewhere on the network.
For example, if you have deployed an agent on the host myhost and the gateway is deployed elsewhere in the network, open cmd.exe and enter the following command:
c:\\x4b>x4b run interactive --host myhost\n
This is the list of allowed parameters:
Parameters Description Example --host Agent host name x4b run interactive --host MYHOST --port Agent port value x4b run interactive --host MYHOST --port 12345 --ssl Ssl protocol: Tls, Tls12, Tls13 x4b run interactive --host MYHOST --port 12345 --ssl Tls12 --loglevel Log Level: Error, Info, Trace x4b run interactive --host MYHOST --port 12345 --ssl Tls12 --loglevel Error If the gateway can't reach the agent, you will obtain the following output:
c:\\x4b>x4b run interactive --host myhost\nLaunching gateway in interactive mode...\n __ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2023\n\n12/09/2023 17:08:52# X4B Gateway is up and running... (Press Ctrl+C to exit)\n\n12/09/2023 17:08:55# Connection to agent fails - Retrying in few seconds...\n
If the gateway is able to reach the agent, you will obtain the following output:
C:\\>x4b run interactive --host localhost\nLaunching gateway in interactive mode...\n __ ______ ___ __ __ ____ ___ _ _ _____ _ _ _____\n \\ \\/ / ___/ _ \\| \\/ | _ \\ / _ \\| \\ | | ____| \\ | |_ _|\n \\ / | | | | | |\\/| | |_) | | | | \\| | _| | \\| | | |\n / \\ |__| |_| | | | | __/| |_| | |\\ | |___| |\\ | | |\n /_/\\_\\____\\___/|_| |_|_| \\___/|_| \\_|_____|_| \\_| |_|\n\n\nXComponent For Business by Invivoo Software - 2023\n\n12/09/2023 17:11:53# X4B Gateway is up and running... (Press Ctrl+C to exit)\n\n12/09/2023 17:11:54# Connection to agent established\n\n12/09/2023 17:11:54#\n***************************************\nAgent configuration:\nVersion=26.0\nPlatform=Windows\nCpu Usage=15%\nnetworkAddress=0.0.0.0\nport=12567\nlogdirectory=C:\\tools\\appcontrol\\xcAgent-binary\\./logs\ntempdirectory=C:\\Windows\\TEMP\nmaxlogsizeinmo=5\nnbdaystodeletelogs=10\nredirecterroutput=1\nexecutionthreshold=200\nloglevel=TRACE\ntrustedservers=\nsslprotocol=tls12\nsshkeydirectory\nshell=\nignoretrustedservers=false\nserviceaccount=\nwindows Interpreter=C:\\Windows\\system32\\cmd.exe\n\n***************************************\n\nappControlAgent@localhost %\n
The gateway is able to reach both Linux and Windows agents.
Once connected, you can execute commands on the agent's host. For example, you can use cd, dir, more for Windows, or pwd, ls, cat for Linux.
The commands are executed by the default shell, which is cmd.exe for Windows and sh or bash for Linux.
Example with a Windows agent:
appControlAgent@localhost % dir\n\n R\u00e9pertoire de C:\\tmp\\test\\xcAgent-binary-Win32\n\n12/09/2023 17:31 <DIR> .\n12/09/2023 17:31 <DIR> ..\n11/09/2023 14:15 940 config.dat\n11/09/2023 14:31 87 install.bat\n26/03/2018 23:45 2?094?592 libcrypto-1_1.dll\n26/03/2018 23:45 375?808 libssl-1_1.dll\n12/09/2023 17:32 <DIR> logs\n26/03/2018 23:45 970?912 msvcr120.dll\n11/09/2023 14:29 953?856 xcAgent.exe\n 6 fichier(s) 4?396?195 octets\n 3 R?p(s) 96?394?911?744 octets libres\n\nappControlAgent@localhost C:\\tmp\\test\\xcAgent-binary-Win32% powershell -c cat config.dat\n\n12/09/2023 17:35:25# <!-- XComponent APP Control Agent Configuration file -->\n<config>\n <item key=\"generatebatch\" value=\"false\" />\n <item key=\"windowsinterpreter\" value=\"%ComSpec%\" />\n <item key=\"networkAddress\" value=\"0.0.0.0\" />\n <item key=\"port\" value=\"12567\" />\n <item key=\"logdirectory\" value=\"./logs\" />\n <item key=\"tempdirectory\" value=\"%TEMP%\" />\n <item key=\"maxlogsizeinmo\" value=\"5\" />\n <item key=\"nbdaystodeletelogs\" value=\"10\" />\n <item key=\"redirecterroutput\" value=\"true\" />\n <item key=\"logToStandardOutput\" value=\"true\" />\n <item key=\"executionthreshold\" value=\"200\" />\n <item key=\"loglevel\" value=\"TRACE\" /> <!-- NONE, INFO, TRACE, ERROR -->\n <item key=\"trustedservers\" value=\"\" />\n <item key=\"ignoretrustedservers\" value=\"false\" />\n <item key=\"sslprotocol\" value=\"tls12\" /> <!-- ssl, tls, tls12, tls13 -->\n <item key=\"sshkeydirectory\" value=\"\" /> <!-- Linux Only -->\n <item key=\"shell\" value=\"\" />\n</config>\n\nappControlAgent@localhost C:\\tmp\\test\\xcAgent-binary-Win32%\n
Example with debian's agent:
appControlAgent@macbook % ls\n\n12/09/2023 17:36:56# config.dat\nconfig_env.dat\nlibs\nlogs\nrun.sh\ntmp\nxcAgent.bin\n\nappControlAgent@macbook /usr/src/app/xcagent% cat config.dat\n\n12/09/2023 17:37:23# <!-- XComponent APP Control Agent Configuration file -->\n<config>\n <item key=\"networkAddress\" value=\"0.0.0.0\" />\n <!--TCP listening port of the agent -->\n <item key=\"port\" value=\"12567\" />\n <item key=\"generatebatch\" value=\"true\" />\n <!--Logs and Tmp directories-->\n <item key=\"logdirectory\" value=\"logs\" />\n <item key=\"tempdirectory\" value=\"tmp\" />\n <item key=\"maxlogsizeinmo\" value=\"5\" />\n <item key=\"nbdaystodeletelogs\" value=\"10\" />\n <item key=\"redirecterroutput\" value=\"true\" />\n <item key=\"executionthreshold\" value=\"50\" />\n <item key=\"logToStandardOutput\" value=\"true\" />\n <item key=\"loglevel\" value=\"TRACE\" /> <!-- NONE, INFO, TRACE, ERROR -->\n <!-- IP address of SSH serveur (unix/linux) -->\n <item key=\"sshhost\" value=\"127.0.0.1\" />\n <!-- IP Address or DNS Names of AC2 servers authorized to communicate with the agent -->\n <item key=\"trustedservers\" value=\"\" />\n <item key=\"sslprotocol\" value=\"tls12\" /> <!-- ssl, tls, tls12 -->\n <item key=\"sshkeydirectory\" value=\"\" /> <!-- Linux Only -->\n <item key=\"shell\" value=\"\" />\n</config>\nappControlAgent@macbook /usr/src/app/xcagent%\n
"},{"location":"Getting%20Started/","title":"Get Started","text":" - Go to the XComponent AppControl website.
- Log in using a social provider
- You're done! You can now get started with AppControl
In the example section, copy the following link to the demo application: demo application.
On the AppControl website, go to the Import Application and paste the link of the demo application.
Follow the wizard (clicking on 'Next' button). In the 'Gateway' tab select 'X4B SaaS'. On the last tab click on 'Import'.
Go the 'Overview', and select the helloworld application by clicking on the checkbox. Then click on the load button.
Next, click on the 'Architecture' button:
Using, the command bar, you can now start/stop the Hello World application with ease.
"},{"location":"Getting%20Started/appcontrol_worker/","title":"Contents","text":"This document describes how to use AppControl to execute a script or program as a task in XC Scenario. It shows how to define the script invocation in an AppControl map, how to test it directly from AppControl, and finally how to use it from Scenario.
"},{"location":"Getting%20Started/appcontrol_worker/#benefits-of-using-appcontrol","title":"Benefits of using AppControl","text":"There are many advantages to running scripts through AppControl, as opposed to running them directly from a worker task:
-
the use of an AppControl agent for execution makes it easy to run scripts on remote machines, without requiring the script author to manage remote connections and logins himself
-
executions through AppControl will benefit from monitoring and supervision by the production support team
-
defining script calls in an AppControl map allows for better tracking and management of the script code base
"},{"location":"Getting%20Started/appcontrol_worker/#pre-requisites","title":"Pre-requisites","text":"This document assumes that you have access to a working X4B installation, either Invivoo's SaaS platform, or an X4B platform deployed on your premises.
This includes XC Scenario, XC AppControl, and an AppControl worker (detailed below) deployed and configured to interact with this AppControl instance. Contact the administrator of your X4B platform to make sure that all the required components are available and properly configured.
"},{"location":"Getting%20Started/appcontrol_worker/#appcontrol-worker","title":"AppControl Worker","text":"The AppControl worker is a standalone program that acts as a worker program for Scenario:
- it publishes a catalog of tasks
- it polls the task queue for tasks to execute
- it runs tasks and posts task statuses
Unlike other worker programs that implement their own tasks, the AppControl worker:
- gets its list of tasks from custom actions in AppControl maps
- runs tasks by calling custom actions that get executed by an AppControl agent
The AppControl worker must be configured to communicate with an AppControl server through a gateway, which is defined inside AppControl, and is associated with a specific AppControl user.
"},{"location":"Getting%20Started/appcontrol_worker/#defining-scripts-for-the-appcontrol-worker","title":"Defining scripts for the AppControl worker","text":"Scripts that are meant to be used with the AppControl worker need to be defined inside an AppControl map, as custom actions attached to some AppControl component.
"},{"location":"Getting%20Started/appcontrol_worker/#custom-actions","title":"Custom actions","text":"A custom action is defined by an action element (inside a component element) with a name=\"custom\" attribute. Other important attributes are commandname, which lets you identify each custom action, and value, which holds the actual command to execute.
The contents of the value attribute are sent to the AppControl agent for execution, so the platform where the agent is running determines the actual shell script language to use, Windows command/batch script or linux/unix-like shell script.
The action element can have parameters and outputParameters sub-elements, for input and output parameters, respectively.
The action element also has a visibility attribute, which controls whether the action is accessible from outside AppControl or not. The AppControl worker only retrieves public tasks, so if a custiom action is to be used with Scenario, it is mandatory to specify visibility=\"public\".
See the AppControl map documentation for more details.
"},{"location":"Getting%20Started/appcontrol_worker/#example","title":"Example","text":"The following XML snippet is an excerpt from an AppControl map that defines a component named \"comp\" (you can find the map file here). This component has a check action (mandatory) and two custom actions named calc and prod_div.
<component name=\"comp\" description=\"Script execution component\" hostref=\"LOCAL\" authref=\"LOCAL\" redirectoutput=\"false\" type=\"file\">\n <action value=\"echo 1\" name=\"check\" />\n\n <action value=\"C:\\a\\bin\\calc_script.cmd $(arg)\" commandname=\"calc\" name=\"custom\" visibility=\"public\">\n <parameters>\n <parameter name=\"arg\" value=\"\" canedit=\"true\" validation=\"*\" />\n </parameters>\n </action>\n\n <action value=\"py c:\\a\\bin\\pycalc.py $(operand1) $(operand2)\" commandname=\"prod_div\" name=\"custom\" visibility=\"public\">\n <parameters>\n <parameter name=\"operand1\" canedit=\"true\" validation=\"\\d+\" />\n <parameter name=\"operand2\" canedit=\"true\" validation=\"\\d+\" />\n </parameters>\n <outputParameters>\n <parameter name=\"product\" />\n <parameter name=\"division\" />\n </outputParameters>\n </action>\n\n</component>\n
The calc action has a single input parameter named arg, defined in the parameters/parameter element, and referenced with the $(arg) inside the value attribute. This action will run the Windows command line file found at C:\\a\\bin\\calc_script.cmd on the agent's machine, passing it the value of the arg parameter (script file here).
The prod_div action has both input and output parameters. It runs a python script with two input parameters, calculating the product and division of these two operands, and returning those two values. The outputParameters element is used to list the names of the return values, so they can be added to the task's description in the Scenario task catalog, and also identified in the script's output stream (see A script with output parameters below).
"},{"location":"Getting%20Started/appcontrol_worker/#running-custom-actions-in-appcontrol","title":"Running custom actions in AppControl","text":"Once the custom actions have been defined in the map file, as above, the map must be imported into AppControl, using the New button in the UI. Please refer to the AppControl documentation if you need more information on how to use the AppControl UI.
When the Architecture tab is chosen to display the map's graph, the components from the map are shown, and any custom actions defined on them will be found on a dropdown menu accessible through a right-click:
"},{"location":"Getting%20Started/appcontrol_worker/#a-simple-script","title":"A simple script","text":"If we pick the calc action, a dialog box (on the left) shows the command line that will be executed, as well as the arguments that are expected (in this case, the single parameter arg). Enter a value for the argument, and press the Execute Custom Action button. The dialog box (on the right) now displays the status of the execution, which can be InProgess, while it's running, and then Execution Succeeded as shown here when it's finished, with the exit code from the script on the right-hand side.
As scripts usually produce output from their execution by printing to their standard output stream, the AppControl custom action captures that output stream and displays it on the screen, below the green status line. In this case, it's the message calc_script: arg=hello that was printed by the script.
"},{"location":"Getting%20Started/appcontrol_worker/#a-script-with-output-parameters","title":"A script with output parameters","text":"A shell script does not have a notion of output parameters. But in many situations, people write code that produces results, and we want to retrieve those results, either for displaying in the AppControl UI, or for communicating them to Scenario so they can be used by other tasks.
This second example, the prod_div action, illustrates this use case with a python script that returns two output parameters, and it explains the particular syntax that's used, in the script's standard output stream, to represent return values so Scenario get use them.
The pycalc script (source code here) calls a python function that calculates the product and division of its two operands. If we pick the prod_div action in AppControl, the dialog box will shows us the command line and input arguments (operand1, operand2), and after executing the action, we'll also see the standard output, as before.
However, in this case, we see that the standard output has a very specific format:
<appcontrol>\n {\n 'Message': 'pycalc: success.',\n 'OutputValues': {\n 'product': 72,\n 'division': 8.0,\n }\n }\n</appcontrol>\n
Inside the <appcontrol> tags is an object with json/javascript syntax, that is meant to be interpreted by the AppControl worker:
-
the Message property holds some text that will be displayed in the Scenario UI, so it should be some kind of summary or resulting status from the script's execution.
-
the OutputValues property is a dictionary of the output parameters. It must match the set of parameters listed in the outputParameters element of the AppControl map (see Custom action example above), and the values must be filled in by the script.
"},{"location":"Getting%20Started/appcontrol_worker/#running-scriptscustom-actions-in-scenario","title":"Running scripts/custom actions in Scenario","text":"So far, we've seen how to define our scripts in the AppControl map, and how to run them from the AppControl UI. This section deals with using those scripts inside Scenario.
If everything has been set up correctly by your administrator, as described in Pre-requisites above, importing and loading (activating) the map that defines your scripts is enough to make them available in Scenario. The AppControl worker publishes all the custom actions from your map as Scenario tasks, in a namespace called AppControl.
"},{"location":"Getting%20Started/appcontrol_worker/#using-the-script-as-a-scenario-task","title":"Using the script as a Scenario task","text":"In the Scenario designer, when creating or modifying a scenario definition, drag and drop an automatic task object (the one with the gears icon, called Task), and select the AppControl namespace in the Task Parameters panel. In the list of tasks, you can see two tasks from the map,v1.xml file, with names:
- map,v1@admin__comp_calc
- map,v1@admin__comp_prod_div
The structure of these names reflects the AppControl artifacts: <map>@<user>__<component>_<action>. These actions are now available, like any other task, to be used in your scenario.
Select the prod_div task, enter values for operands 1 and 2, and then run the scenario. In the cockpit, you can see the output values and the message, just as we saw in the AppControl UI above:
"},{"location":"Getting%20Started/appcontrol_worker/dynamicmapinformations/","title":"Dynamic informations","text":"An application, is a set of components defined statically with an xml format (cf: Create an application). Nevertheless, the application can be enriched with dynamic informations. Dynamic informations are returned by the 'check' command.
To return dynamic informations the 'check' command should log on the standard output some informations. The informations should respect the following format:
<appcontrol> APPCONTROL JSON OBJECT </appcontrol>\n
Dynamic informations can enrich the content of the component owning the 'check'. In dynamic informations start/stop commands are not allowed.
The JSON format is the following:
{\n \"link\": \"Hyperlink to wathever you want\", //Optional\n \"name\": \"Name of the component\", //Required\n \"displayName\": \"Display name\", //Optional\n \"state\": \" Initializing | \n InError |\n Start |\n Starting |\n Started |\n Stop |\n Stopping |\n Stopped \", //Optional\n \"parents\": //Optional but highly recommanded\n [\n \"Parent1\",\n \"Parent2\",\n ],\n \"exitCode\": 256, //Optional\n \"color\": \"Color of the code RGB format or hexa code ('255,255,255' or #FFFFFF\", //Optional\n \"Type\": \" Used to display an icon on the map. An url to an image (png, jpeg or svg) can be set. Anyway you can use one of the following value: browser, cd, chip, data-information, devises, dollar, euro, file, green-thermometer, hdd, memflash, memory, middleware, network, orange-thermometer, pounds, process, service, tools, user, yen\", //Optional\n \"groupName\": \"Name of the group\", //Optional\n \"customActions\": //Optional\n [\n {\n \"visibility\": \"Private\",\n \"customActionName\": \"echo Action\",\n \"customActionDescription\": null,\n \"customActionCommandLine\": \"echo $(message)\",\n \"parallelCustomAction\": false,\n \"parameters\":\n [\n {\n \"parameterName\":\"message\",\n \"description\": \"\",\n \"defaultValue\": \"Welcome message\",\n \"validationRule\": \"*\",\n \"isEditable\": true\n }\n ]\n }\n ],\n \"filters\": {\"filter name 1\": [\"filter values\"] ,\n \"filter name 2\": [\"filter values\"]\n } //Optional,\n \"dynamicTree\" : [\n {\n //A json object with the properties defined above\n }\n ] //Optional,\n}\n
A full example is available in this documentation: - Application Xml - JSON dynamic data
The application should be tested this way.
- First copy this the link to the application: Application
- Go to the New Application menu and import the previous application
- Once the application is loaded go to the Architecture menu, you should obtain the following rendering:
On the above screenshot, you can observe that dynamic components are displayed with an 'octagon form' whereas the 'static component' is displayed with a 'square form'.
"},{"location":"openfaas/synchronous/","title":"Contents","text":"This document describes how to write a simple, synchronous python function that is run inside OpenFaas, and that can be invoked from XC Scenario to implement a scenario task. It details the integration with OpenFaas and the mechanics of making your function available on the server. A separate document will address the case of an asynchronous function.
Note that OpenFaas supports writing functions in many programming languages other than python, please have a look at the official OpenFaas documentation for more information.
Part of this document is based on the OpenFaas First Python Function tutorial.
"},{"location":"openfaas/synchronous/#openfaas-and-cli-installation","title":"OpenFaas and CLI Installation","text":"This document assumes that you have a working OpenFaas installation, and you will need to provide the URL for it. Contact an administrator if you don't have this information. In our example, we'll be using https://openfaas.xcomponent.com as the url for our OpenFaas server, or gateway.
As part of the OpenFaas installation, the faas-cli executable should be in your path. This is OpenFaas' command-line interface (CLI), and it is required to perform a number of tasks, including building and deploying your functions, so a set of valid credentials must be configured for it. Again, if needed, contact the administrator responsible for your OpenFaas installation.
"},{"location":"openfaas/synchronous/#write-a-simple-function","title":"Write a simple function","text":""},{"location":"openfaas/synchronous/#initialize-the-work-environment","title":"Initialize the work environment","text":"Create a working directory and move into it. Now scaffold a new Python function using the CLI:
faas-cli new --lang python3 pyfunc\n
This retrieves a set of templates from GitHub, if needed, then creates the following files:
pyfunc/handler.py\npyfunc/requirements.txt\npyfunc.yml\n
Again, this example uses python. Have a look at this page to see what other languages are available.
Note that for a single language, many templates may be available. The default for python is to use the Classic Watchdog, but the above link lists many others.
"},{"location":"openfaas/synchronous/#pyfuncyml","title":"pyfunc.yml","text":"This yaml file specifies your functions, and the OpenFaas gateway to use. The faas-cli new command has already filled in most of this file:
version: 1.0\nprovider:\n name: openfaas\n gateway: http://127.0.0.1:8080\nfunctions:\n pyfunc:\n lang: python3\n handler: ./pyfunc\n image: pyfunc:latest\n
You only need to change or specify the following items:
- the gateway, i.e. the url of your OpenFaas installation
- the docker image name
- the
com.xcomponent.label property (to be added)
OpenFaas supports running functions from Docker images stored on Docker Hub or in private Docker registries. If you decide to use Docker Hub, as we do in this example, you'll need to include a Docker Hub account as the prefix in the image name (joaomdsc in this case, see below).
If you want to use a private registry for your images, this document has information on how to specify the access credentials.
XC Scenario defines a label (Demo in our example) that is used to filter the functions that will be made available. That label must be referenced here so that your function can be used in XC Scenario. We'll use the labels.com.xcomponent.label property to specify a value, which has to match whatever value was configured in your installation of XC Scenario. Please contact your X4B/Scenario administrator to find out the right label to use here.
After applying these changes, here's what the modified pyfunc.yml file looks like:
version: 1.0\nprovider:\n name: openfaas\n gateway: https://openfaas.xcomponent.com\nfunctions:\n pyfunc:\n lang: python3\n handler: ./pyfunc\n image: joaomdsc/pyfunc:latest\n labels:\n com.xcomponent.label: Demo\n
"},{"location":"openfaas/synchronous/#handlerpy","title":"handler.py","text":"The handler.py file is where the function code will be implemented. It starts out with an almost empty function skeleton:
def handle(req):\n \"\"\"handle a request to the function\n Args:\n req (str): request body\n \"\"\"\n\n return req\n
The function has a single parameter req that will contain the body of the HTTP request through which the function was invoked. The default implementation in the provided template simply returns this string unchanged.
For the time being, we'll keep the function as it is, while we go through the process of making the function available and running it from XC Scenario. Later on, we'll see how to declare input and output parameters to communicate with a running scenario instance, when the function is used to implement a scenario task.
"},{"location":"openfaas/synchronous/#build-the-function","title":"Build the function","text":"Run the following command to build the function:
joao@debian1:~$ faas-cli build -f pyfunc.yml\n
Note: OpenFaas builds a docker image for the function, so make sure that docker is deployed on the machine.
On successful completion, you should see the following message:
Successfully tagged joaomdsc/pyfunc:latest\nImage: joaomdsc/pyfunc:latest built.\n
You can check the presence of the docker image:
docker images\nREPOSITORY TAG IMAGE ID CREATED SIZE\njoaomdsc/pyfunc latest e7f810f4455f 23 minutes ago 62.1MB\n
Now push the image to DockerHub:
joao@debian1:~$ docker push joaomdsc/pyfunc:latest\n
"},{"location":"openfaas/synchronous/#deploy-the-function-to-the-openfaas-server","title":"Deploy the function to the OpenFaas server","text":"You can now deploy the function to the OpenFaas server, using the following command:
joao@debian1:~$ faas-cli deploy -f pyfunc.yml\nDeploying: pyfunc.\n\nDeployed. 202 Accepted.\nURL: https://openfaas.xcomponent.com/function/pyfunc.openfaas-fn\n
Check for the presence of a 202 return code. Also note that it might take a minute or two for your function to be available.
"},{"location":"openfaas/synchronous/#test-the-function","title":"Test the function","text":"You can invoke the function through curl, passing in a request body with the -d argument:
joao@debian1:~$ curl https://openfaas.xcomponent.com/function/pyfunc -d \"Hello!\"\nHello!\njoao@debian1:~$ \n
The text that was passed in is returned by the function.
You can invoke the function through faas-cli:
joao@debian1:~$ echo -n \"Hello!\" | faas-cli -g https://openfaas.xcomponent.com invoke pyfunc\nHello!\njoao@debian1:~$ \n
You can also invoke the function through the OpenFaas portal:
Click on Request body, enter some text (good morning for example), then press Invoke.
"},{"location":"openfaas/synchronous/#use-the-function-in-xc-scenario","title":"Use the function in XC Scenario","text":"Create a new scenario, add a task, and pick the OpenFaas namespace. You should find your new function in the list of tasks on the left (if your function does not appear on the list, the label defined in pyfunc.yml may be incorrect, check with your administrator).
Select pyfunc in the list. Note the DefaultInput field (on the right image), enter some text value (Hello, OpenFaas world! in this example):
Now run the scenario, and check the cockpit. You should see the text you entered displayed in the task output:
"},{"location":"openfaas/synchronous/#write-a-function-with-multiple-parameters","title":"Write a function with multiple parameters","text":"Let's define a second, more realistic function, with input and output parameters. We'll define a function called pyfunc2 that takes two inputs, an integer n and a string txt, and returns two outputs, an integer calc and a string msg.
Repeat the above steps to create a new function called pyfunc2, and apply the following changes.
"},{"location":"openfaas/synchronous/#new-pyfunc2yml","title":"New pyfunc2.yml","text":"In the yaml file, we apply the same changes as before (gateway, image name prefix) but we also add new labels:
version: 1.0\nprovider:\n name: openfaas\n gateway: https://openfaas.xcomponent.com\nfunctions:\n pyfunc2:\n lang: python3\n handler: ./pyfunc2\n image: joaomdsc/pyfunc2:latest\n labels:\n com.xcomponent.label: Demo\n com.xcomponent.inputs.n: Number\n com.xcomponent.inputs.txt: String\n com.xcomponent.outputs.calc: Number\n com.xcomponent.outputs.msg: String\n
The com.xcomponent.inputs properties define function inputs, and com.xcomponent.outputs define function outputs. The parameter name is appended to the property name, and the value indicates the parameter's type.
All the XC Scenario base types can be used : String, Number, Boolean etc.
"},{"location":"openfaas/synchronous/#new-handlerpy","title":"New handler.py","text":"Replace the generated handler.py file with the following content:
import json\n\ndef handle(req):\n \"\"\"handle a request to the function\n Args:\n req (str): request body\n \"\"\"\n\n # De-serialize json, extract input parameters\n obj = json.loads(req)\n n = int(obj['n'])\n txt = obj['txt']\n\n # Implement your function here\n calc = 2*n\n msg = txt.upper()\n\n # Return the output parameters\n result = {\n 'calc': calc,\n 'msg': msg,\n }\n\n return json.dumps(result)\n
XC Scenario calls the OpenFaas functions with a json request body containing the input parameters. The code de-serializes the json data and extracts the two input parameters.
After this step, you can implement whatever processing your function needs to do. In our example, the numeric parameter gets multiplied by 2, and the string parameter is converted to uppercase.
The final step in the code is to return a json string encoding the output parameters defined in the yaml file, so that XC Scenario can make them available as task outputs.
"},{"location":"openfaas/synchronous/#build-and-deploy-the-new-function","title":"Build and deploy the new function","text":"Repeat the above steps to build the new pyfunc2 function, upload its docker image to Docker Hub, and deploy it on the OpenFaas server.
"},{"location":"openfaas/synchronous/#test-the-new-function","title":"Test the new function","text":"You can invoke the function from the command line as before; however, passing json strings is cumbersome, as all the double quotes must be escaped, so it's easier to put the input in a json file, let's call it inputs.json:
{\n \"n\": 13,\n \"txt\": \"hello\"\n}\n
The -d option to the curl command supports the @ syntax to specify a file name, so the function can be invoke with the following command:
joao@debian1:~$ curl https://openfaas.xcomponent.com/function/pyfunc2 -d @inputs.json\n{\"calc\": 26, \"msg\": \"HELLO\"}\njoao@debian1:~$ \n
It can also be invoked through the OpenFaas portal as before:
"},{"location":"openfaas/synchronous/#use-the-new-function-in-xc-scenario","title":"Use the new function in XC Scenario","text":"As before, create a new scenario, add a task, pick the OpenFaas namespace, and select the pyfunc2 function. The Task Inputs section shows the two input parameters n and txt:
Finally, enter some values, then run the scenario and check the cockpit for the function output:
The output parameters display the results of the OpenFaas' function processing.
"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 345be71..b30d910 100755
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,107 +2,107 @@
https://xcomponent.github.io/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/agentazure/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/agents/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/agentsdeployment/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/bestpractices/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/centreon/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/cli/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/cmdb/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/contact/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/coreconcepts/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/dynamicMapInformations/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/gettingStarted/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/mainfeatures/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/map/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/repo/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/standalone/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/x4bcli/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/Getting%20Started/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/Getting%20Started/appcontrol_worker/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/Getting%20Started/appcontrol_worker/dynamicmapinformations/
- 2024-09-30
+ 2024-10-07
daily
https://xcomponent.github.io/openfaas/synchronous/
- 2024-09-30
+ 2024-10-07
daily
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 8ae78f7..0d0beb2 100755
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ