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

{% block title %}How to manage Web tunnels{% 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> How to manage Web tunnels</h4>
                    <hr>
<p class = "text-justify">
Webtunnel functionality allows accessing the device internal webpages through a DWARFG_LONG server directly from your browser. In other words, even if the device is on a private network (or if it offers its webpages only to the local network and not to the Internet), you can still access its web interface via DWARFG_LONG once a tunnel to the device is running.
</p>
<p class = "text-justify">
The intended use case for tunnels is to use them for a short period of time - you setup the tunnel, solve the stuff you want to solve and close the webtunnel afterwards. While the tunnels may be pretty stable (depending on the connection and device stability), the nature of that type of communication is completely different than regular <i>device &lt--&gt DWARFG_LONG</i> communication.
</p>
<p class = "text-justify">
The regular <i>device -&gt; DWARFG_LONG -&gt; device</i> data exchange is always initiated by the device and once done, there is no connection kept until next time. This way, the DWARFG_LONG server is able to handle many devices.
</p>
<p class = "text-justify">
In contrary, device in a webtunnel keeps a connection to the server open, thus consuming some resources. Because of that, the number of webtunnels running simultaneously is limited.
</p>
<h5 style="margin-top: 30px;"> How to setup webtunnel</h5>
                    <hr>
<p class = "text-justify">
<ul>
<li><a href="{{ path('admin_tunnel_web') }}">Go to the Tunnels -&gt; Web screen</a></li>
<li>Choose a free webtunnel position</li>
<ul>
<li>If there is no free webtunnel position, shutdown some active webtunnel</li>
<li>If there is no webtunnel position at all, check <a href="{{ path('admin_system_license') }}">your license</a>. The number of webtunnels is driven by your license.</li>
</ul>
<li>Click on SETUP and choose the device you wish to setup the tunnel to.</li>
<li>For a short while, you will see <b>SETUP</b> in the <i>Operation</i> column, telling you that there is a pending operation on the webtunnel position (SETUP in this case)</li>
<li>Once the <i>Operation</i> reverts back to <b>NONE</b>, you should see <b>Waiting for device</b> in the Operation column and the selected device ID will be shown in the <i>Device</i> column.</li>
<li>The status switches to <b>Ready</b> when the device initiates the tunnel from its side. This should happen shortly after the device picks up tunnel setup command during next communication window with server.</li>
</ul>
</p>
<h5 style="margin-top: 30px;"> How does the webtunnel work</h5>
                    <hr>
<p class = "text-justify">
<ul>
<li>User chooses a device (SETUP)</li>
<li>Server prepares SSH private and public key for the device</li>
<li>Server generates a random link (URL) for this particular tunnel and prepares server config.</li>
<li>Server prepares configuration export for the device</li>
<li>Server switches tunnel state to <i>Waiting for device</i></li>
<li> ... <i> some time passes by waiting for next device -&gt server connection</i> ... </li>
<li>Device agent receives configuration update containing tunnel config and credentials</li>
<li>Device agents sets up the SSH tunnel</li>
<li>Once the SSH tunnel connects, server switches tunnel status to <i>Ready</i></li>
<li>There are additional tunnel states to describe situation when device disconnects, tunnel is being shut down (on user request) or tunnel permanent error.</li>
<li>Once the user requests tunnel shutdown, server prepares shutdown command for the device, and once the device contacts the server in the usual fashion, it picks the tunnel shutdown command and shuts the tunnel from it's side, making the tunnel position available for another device.</li>
<li>There are timeouts defined for a number or actions happening during the tunnel lifetime, making sure that the device position is not blocked by unresponsive device. Especially after a shutdown request, it is guaranteed the tunnel position becomes free in under 15 minutes, regardless of device picking up the command or not.</li>
</ul>
</p>
<h5 style="margin-top: 30px;">Webtunnel FAQ</h5>
                    <hr>
<p class = "text-justify">
<ul>
<li><b>Why is my device not able to setup WebTunnel?</b></li>
<ul><li>The WebTunnel is setup from the device side and it needs a full-featured ssh client. Some device types (e.g. Teltonika routers, OpenWRT devices) are shipping a limited ssh client (<b>dropbear</b>) by default that is not able to establish the WebTunnel. Also for other device types - if the device does not have ssh client installed or has only a limited client, you would need to install a full-featured ssh client first, to make the WebTunnel functionality working.</li>
<li>If you want to debug the problem from the device side, you want to have a look at the script <b>webtunnel.sh</b>. That script is generated by the agent once a WebTunnel setup request is received from the DWARFG_LONG server. You may try starting the script from the command line (possibly removing the silence/quiet parameters from the commands being called) and pinpoint the problem down.</li>
</ul>
<li><b>Why can't I setup no WebTunnel (no device type works) ?</b></li>
<ul><li>If there is no problem on the device side (full-featured ssh client installed, see previous point), there can be several non-device related problems:</li>
<ul><li>Communication problem - the connection to the server ssh port cannot be established due to some network element in the path blocking the port. First thing to check is that the port you are using on the server is available from the outside (no Firewall blocking it). The port is specified at <b>System -&gt; Settings</b> under <b>Device Webtunnel SSH port</b></li>
<li>SSH server problem - WebTunnels are using regular ssh communication. On the configured port (22 by default), the ssh server must be running and configured properly (e.g. not blocking the system user being used by the DWARFG_LONG). To debug the problems, your server administrator should access the SSH server logs and check if the ssh configuration, generated by DWARFG_LONG on the fly when a new tunnel setup is configured is read correctly by the SSH server)</li>
<li>Configuration problem - the DWARFG_LONG server needs to be configured properly. If, e.g. the server is supposed to use port X for the ssh communication but your server admin misconfigured it inside the DWARFG_LONG to Y, the incorrect port is sent to the agent and thus the communication cannot be established. The port is specified at <b>System -&gt; Settings</b> under <b>Device Webtunnel SSH port</b></li>
<li>Configuring the port - your server admin can configure the ssh port to be used by WebTunnels using the DWARFG_SHORT.ini file, configuration key SERV_TUNSSH_PORT (set to 22 by default as that is the usual port where the ssh server is listening).</li>
<li>TCP/IP port problems - when your server administrator chooses a port for the WebTunnels (if she does not want to use the default ssh port), the port selected must have the ssh server running</li></ul>
</ul>
<li><b>Working with two routers (of the same device type) via two WebTunnels open it two browser tabs does not work, is there a workaround?</b></li>
<ul><li>One of the known problems concerns having two Advantech router WebTunnels open and being accessed simultaneously, but it may impact also other device types. If the target device web interface is written improperly, one of the browser tabs can e.g. overwrite values of the session cookies for the device web interface, thus invalidating the session for the other tab / other router. The only possible workaround (until the device manufacturer fixes the device web interface) is to open the individual tunnels in separated browser instances that are not sharing any cache and cookies. If unsure, use different browsers (e.g. Google Chrome for one of the simultaneous WebTunnels, Mozilla Firefox for the other one)</li></ul>
<li><b>Why does my browser offer DWARFG_LONG credentials for logging into the router via WebTunnel?</b></li>
<ul><li>The way the WebTunnels URLs are adressed in DWARFG_LONG brings some security benefits but it however brings this downside. The browser, being unable to identify that you are accessing the router (a different website), is offering you the credentials for the site you are accessing (the device web is under the DWARFG_LONG domain). The best workaround is probably to not use the <i>Fill-in credentials</i> functionality for logging into the devices via WebTunnel.</li></ul>
</ul>
</p>
                </div>
            </div>
        </div>
    </div>

{% endblock body %}