{% extends "base.html.twig" %}

{% block title %}Device agents{% endblock %}

{% block body %}

<div class="container-fluid">
    <div class="row">
        <div class="col-md-12">
            <div class="bgc-white bd bdrs-3 p-20 mB-20">
                <h4 class="c-grey-900"><i class="c-yellow-500 fas fa-question-circle"></i> Device agents</h4>
                <hr>
                <h5 style="margin-top: 30px;"> Getting the correct device agent </h5>
                <hr>
                <p class="text-justify">To connect a device to the DWARFG_LONG server, you need to install an agent on the device. There are a few ways how to install an agent on a device:
                    <ul><li>Install agent on one device manually using device's web-interface.</li>
                    <li>Install agent on one device manually using device's command line.</li>
                    <li>Install (multiple) agents on multiple devices <i>of any type</i> in automated fasion using automated install from server command line or a dedicated Linux machine/VM command line. See below on more details.</li></ul></p>
                <p class="text-justify">For manual installation, you will need to download the correct agent. DWARFG_LONG version 1.0 supports following device types:
                   <ul><li><b>Advantech cellular routers</b> - a full featured device agent with automatic start, integration into device web interface and widest feature range.</li>
                   <li><b>Teltonika cellular routers</b> - device agent with automatic start, providing monitoring and alerting functionality. No integration in device web pages. Installation is via command line (both as system package and from tar.gz archive).</li>
                   <li><b>OpenWRT devices</b> - device agent with automatic start, providing monitoring and alerting functionality. No integration in device web pages. All installation methods supported.</li>
                   <li><b>Generic Linux-based devices</b> - device agent with automatic start (both Systemd and SysV Init supported), providing most functionality including Webtunnels (if device runs local web pages). Installation is via command line.</li></ul></p>
                <p class="text-justify">You absolutely need to install the correct agent type on a device.</p>
                <p class="text-justify">Also, you cannot use agent archive package downloaded from one server to connect a device to another server because the package does contains Server ID, that is generated during the DWARFG_LONG server deployment.</p>
                <p class="text-justify"><b>In case you managed to install incorrect agent type by mistake</b>, you need to first stop all the agent processes and manually wipe the <b>/opt/aDWARFG_SHORT</b> directory before attempting reinstallation of the correct agent package. Depending on the stage of installation, you may have the uninstall.sh script generated to use, or ability to run package manager tool (umupdate for Advantech routers or opkg for Teltonika/OpenWRT). Once done, check there are no running processes and manually wipe the agent directory if still present after uninstallation attempt <b>prior any reinstallation attempt</b>. If you are unsure that all agent processes are stopped, simply restart the device before manually wiping the <b>/opt/aDWARFG_SHORT</b> directory. <b>Alternatively</b>, you may run the auto-deployment tool as that will automatically take care of uninstallation for you.</p>
                <h5 style="margin-top: 30px;"> Automated Agent Installation </h5>
                <hr>
                <p class="text-justify">If you need to install agent on many devices, you should consider using the <b>AAD</b> tool.
                <ul><li>To use the tool from a Linux box, download it from <b>Donwload Agents -&gt; View All Downloads</b> from the top menu.</li>
                <li>To use the tool from the server commandline, login to the server commandline, change directory to your Dwarfguar deployment (<b>/opt/DWARFG_SHORT_&lt;domain&gt;</b>) and execute <b>push_agent.py</b>.</li>
                <li>Tool options are described <a href="https://DWARFG_SHORT.dwarftech.cz/aad-doc">online</a> or presented in a <a href="https://DWARFG_SHORT.dwarftech.cz/videos/100/aad.mp4">video</a></li></ul>
                </p>
                <h5 style="margin-top: 30px;">Agent installation details</h5>
                <hr>
                <p class="text-justify"><ul><li><b>Advantech cellular router agent</b> - is distributed in the form of package, that installs like any other RouterApp / User Module - simply select the web UI menu <b>User Modules</b>, click on <b>Select File</b>, locate the package downloaded from DWARFG_LONG and confirm via <b>Add or Update</b></li>
                <li><b>Linux agent</b> - distributed as a self-contained script with README file. Unpack the archive and run the script (agent) from command line. All required directories and system startup installation will be performed by the agent itself. </li>
                <li><b>Teltonika agent</b> - distributed in the form of IPK package (native RutOS package). As the agent is a 3rd-party package (not provided by Teltonika company), the web-based installation is not allowed. You need to copy the IPK package via ssh/scp/rsync and use the <b>opkg</b> command line tool to install the agent. The agent requires <b>curl</b> that is not installed on RutOS by default, but will be installed as a dependency during agent installation. You may also opt to install the agent from the archive (as opposed to an IPK package). This way, you would need to install the <b>curl</b> manually (be it in the form of package or from the sources). For WebTunnel to work on Teltonika device, you also need to install a fully-featured ssh client. The RutOS default ssh client (Dropbear) is not able to establish tunnel properly. </li>
                <li><b>OpenWRT agent</b> - distributed in the form of IPK package (native OpenWRT package). You can install the package via router web interface or using command line tool <b>opkg</b>. The agent requires <b>curl</b> that is not installed on OpenWRT OS by default, but will be installed as a dependency during agent installation. You may also opt to install the agent from the archive (as opposed to an IPK package). This way, you would need to install the <b>curl</b> manually (be it in the form of package or from the sources). For WebTunnel to work on OpenWRT device, you also need to install a fully-featured ssh client. The OpenWRT default ssh client (Dropbear) is not able to establish tunnel properly. </li></ul></p>
                <h5 style="margin-top: 30px;">Using agent</h5>
                <hr>
                <p class="text-justify">Once installed, agent automatically registers at the defined server and starts sending the required data and generally performing it's job.</p>
                <p class="text-justify">In general, there are only few use cases for accessing the agent on a device directly. Some useful information is exposed via local web interface (if provided by the agent in question) and also some actions can be executed directly via the interface for convenience. For device agents that do not have the local web interface, local inspection/configuration is still possible. The following files under the <b>/opt/aDWARFG_SHORT</b> can be viewed or edited on the device, but please note that breaking the file may render the agent non-functional:
                    <ul>
                        <li><b>global_log.txt</b> ... contains all global logging messages from all agents run.</li>
                        <li><b>server.ini</b> ... contains server address. Do not change manually unless you moved the server to another URL.</li>
                        <li><b>settings.ini</b> ... contains agent settings. Some of these are updated from server based on which agent profile is assigned to the device. You can see device DevID inside <b>g_devid</b> variable (never change this!) and if your server's certificate has changed, you can set the <b>g_security=1</b> to allow certificate refresh on agent. Setting <b>g_security=0</b> will disable the certificate check (but the communication will stay encrypted via HTTPS).</li>
                    </ul>
 </p>
                </div>
            </div>
        </div>
    </div>

{% endblock body %}