.. _dem-agent-install: Digital Experience Monitoring (DEM) Agent Installation ============================================================== .. _24.1|VOSS-1319: Deployment Architecture ----------------------- VOSS Insights provides for the installation and configuration of Digital Experience Monitoring (DEM) Agents. The VOSS Insights Forwarder is an agent that collects statistics such as latency and response times on various cloud endpoints, along with system CPU statistics, which is sent by means of the API back to the Arbitrator. The purpose of the agents are to monitor network experience, in particular for Microsoft Graph API, Teams, Web login and Exchange. Measuring and widgets are available to: * Measure hops * Measure latency * Measure web performance * Provide alarms on for example: too many hops, latency, bad response A number of installation deployment options are available: |1.png| One agent built into a single Collector |2.png| Multiple agents within a customer network |3.png| Agent hosted in the cloud .. image:: /src/images/dem-agent-architecture.png Hardware/OS requirements ------------------------- The agent requires the deployment of a platform for it to run on - the agent itself is installed on that platform. No specific hardware specification in terms of RAM, CPU, and so on is available: since this is a very lightweight agent, it can run on many hardware platforms. However, some basic considerations are: - Location - you want the device to be as close to the end user environment as possible - e.g "on the floor" with the users, not part of the data center (DC) infrastructure. For instance, part of the office wifi if that is the primary means of connectivity, or cabled into the local LAN if that is the primary. - Connectivity - think of the different user connectivity options you want to test the experience over - LAN, wifi, guest wifi, etc. - Small form factors typically work best, for example Intel NUC, Raspberry Pi, an old laptop, and so on. - OS requirements are: Debian Linux OS. The agent installs via a Debian package install process. The DEM agent does not currently support multiple network interfaces as part of the test suite - so if multiple interfaces are present, it will use the OS default routing. It is therefore currently best to just have a single network interface per device to ensure you know the interface being used. Connectivity ------------ This section outlines the connectivity required to and from the agent. VOSS Insights platform connectivity .................................... The agent needs to communicate with the Arbitrator - whether that is in the same environment or in the VOSS Cloud. .. tabularcolumns:: |p{4cm}|p{5cm}|p{6cm}| +---------------+----------------------+----------------------+ | Destination | Protocol/Port/Type | Purpose | +===============+======================+======================+ | Arbitrator | HTTPS 443 TCP | Registration and | | | | sending test results | | | ICMP | | +---------------+----------------------+----------------------+ Testing Connectivity .................... DNS - for resolving hostnames as part of the testing. The recommended tests require the following connectivity if you intend to use them. Additional/alternate connectivity may be required if other tests are intended to be used. The current schedule of test runs is every 5 minutes. .. tabularcolumns:: |p{7cm}|p{3cm}|p{4cm}| +-----------------------------------+--------------------+----------------------+ | Destination | Protocol/Port/Type | Purpose | +===================================+====================+======================+ | https://graph.microsoft.com | HTTPS 443 TCP | Graph API | | | | connectivity | +-----------------------------------+--------------------+----------------------+ | https://graph.microsoft.com | ICMP | Reachability stats | | | | for graph | +-----------------------------------+--------------------+----------------------+ | https://teams.microsoft.com | HTTPS 443 TCP | Access to Teams | | | | front-end | +-----------------------------------+--------------------+----------------------+ | https://teams.microsoft.com | ICMP | Reachability stats | | | | for Teams | +-----------------------------------+--------------------+----------------------+ | https://login.microsoftonline.com | HTTPS 443 TCP | Web Testing example | | | | - microsoft login | | | | front-end | +-----------------------------------+--------------------+----------------------+ | https://outlook.office.com | HTTPS 443 TCP | Web Testing example | | | | - Microsoft exchange | | | | web | +-----------------------------------+--------------------+----------------------+ | https://outlook.Office365.com | HTTPS 443 TCP | Web Testing example | | | | - Microsoft exchange | | | | web | +-----------------------------------+--------------------+----------------------+ Setup and Configuration ......................... From release 24.1, the Arbitrator is automatically furnished with a new user account. This username is : ``voss_agent_api_user`` .. image:: /src/images/c9fcda712e0b024f.png .. important:: By default, no password is set for this user. Therefore, this account needs to have a password set. To set the user password, log in to the configuration area of the Arbitrator and follow the steps below: 1. Click on **Access Control** |b5303afe026169bb.png|. 2. Click on **Users** |2827309f8713c6e8.png|. 3. Click on the green pencil |4d3f2de58b0000f6.png| to modify. 4. Set the password. .. image:: /src/images/ee71b5155052b662.png Note when entering the password, you will see the text, but once the password is saved, it will be masked. 5. Once the password has been set, click the blue tick mark to confirm |9ae2674d56b4df14.png|. 6. Click **Save** at the bottom of the page. .. image:: /src/images/bc09e5cee1cac7d3.png Agent Installation ................... When installing the Voss-Forwarder package to the agent host, a number of failsafe options built in to assist you with the correct installation. These are also highlighted below. The first step is to move the installation file to the host. (Use SCP, Filezilla, etc.) The current file is named: ``voss-insights-forwarder-1.0.deb`` 1. At the host prompt, run: ``sudo apt install ./voss-insights-forwarder-1.0.deb`` .. image:: /src/images/414df7720b524d16.png 2. Enter the IP Address or FQDN of the Arbitrator that the agent is to report to then press Enter. The agent will now do a connectivity check via ICMP (Ping) to the Arbitrator. * If connectivity is good, move on to the next step. * If there is no connectivity after 4 attempts, the package will exit. .. image:: /src/images/a46aa0325bbcd64f.png 3. Enter the username (if you created a new API user) or keep the default user and press Enter. .. image:: /src/images/d372e3558ff9b852.png 4. Enter the password (set on the Arbitrator). This will then check the credentials are valid. * If credentials are valid, you move on to the next step. * If credentials are invalid after 4 attempts, the package will exit. .. image:: /src/images/48560d0b3b2a69c6.png 5. Enter a customer name (data is required to continue) and press Enter. .. image:: /src/images/d21a8d3cd9f58d55.png 6. Enter the Forwarder name (this should for example be a descriptive location). Press Enter. .. image:: /src/images/f0121f051185ffb.png This completes the configuration. The **DEM Agent Stats** dashboard under **Diagnostics > Synthetic Transactions Dashboards** then shows each agent configuration on the widgets: **Forwarder System Stats** and **Forwarder Linux Distributions**. Changes to Agent Configuration .............................. In the event of redeploying the agent to another site or a different Arbitrator, the commands below allow you to make these changes. To update or change configuration, run any of the following commands: * To change the IP Address or FQDN for the Arbitrator: ``sudo ./etc/voss/bin/update-forwarder-arbitrator.sh`` * To update / change the API credentials: ``sudo ./etc/voss/bin/update-forwarder-credentials.sh`` * To update / change the Customer: ``sudo ./etc/voss/bin/update-forwarder-customer.sh`` * To update / change the Forwarder Name: ``sudo ./etc/voss/bin/update-forwarder-name.sh`` .. |1.png| image:: /src/images/1.png .. |2.png| image:: /src/images/2.png .. |3.png| image:: /src/images/3.png .. |b5303afe026169bb.png| image:: /src/images/b5303afe026169bb.png .. |2827309f8713c6e8.png| image:: /src/images/2827309f8713c6e8.png .. |4d3f2de58b0000f6.png| image:: /src/images/4d3f2de58b0000f6.png .. |9ae2674d56b4df14.png| image:: /src/images/9ae2674d56b4df14.png