{% 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">
Tunnel functionality allows accessing the device internal webpages and SSH service through a DWARFG_LONG server directly from your browser or using DWARFG_LONG as a HTTPS proxy for SSH. In other words, even if the device is on a private network (or if it offers its webpages or SSH service 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 tunnel 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 tunnel keeps a connection to the server open, thus consuming some resources. Because of that, the number of tunnels running simultaneously is limited not only by the license but also from a resources point of view.
</p>
<h5 style="margin-top: 30px;"> How to setup a tunnel</h5>
                    <hr>
<p class = "text-justify">
<ul>
<li><a href="{{ path('admin_tunnel') }}">Go to the Tunnels screen</a></li>
<li>Choose a free tunnel type and position</li>
<ul>
<li>Note that there is a column called Type in the List of Tunnels table. Some tunnel slots are of Web type, allowing access to device Webpages, others are of the SSH type, allowing access to the device SSH service. The number of tunnels of each type available are depending on <a href="{{ path('admin_system_license') }}">your license</a></li>
<li>The Web tunnels are listed first, followed by SSH tunnels. In case you see the types mixed, you probably exchanged your license in the past and to get the tunnels sorted. Perform the Tunnel Slot Recovery as described below.</li>
<li>If there is no free tunnel position, shutdown some active tunnel of the appropriate type. If some tunnels can neither be accessed or shutdown, you need to perform the Tunnel Slot Recovery as described below.</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 Tunnel 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>
<li>Click on Connect buttone once available. In case of the Web tunnel type, you will be taken directly to the device Webpages. In case of the SSH tunnel, you will be taken to the webssh gateway page - either WebSSH or SSHWifty, which is a tool implementing web terminal. Once there, you need to select the connection:</li>
<ul>
<li>In case of WebSSH, you need to enter password or provide SSH key. You can also specify arbitrary SSH destination (connect to another machine if that machine offers SSH service and you know appropriate credentials).</li>
<li>In case the SSHWifty is used, the connection is limited to the predefined device. You need to click on the + button and select the predefined tunnel configuration to access the tunnel.</li>
</ul>
</ul>
</p>
<h5 style="margin-top: 30px;"> Installing external SW components for web terminal </h5>
<p class = "text-justify">
Both the WebSSH and SSHWifty belong among the external SW components that are not part of the standard Debian repository. Depending on the mode chosen by server admin at the time of DWARFG_LONG deployment, these components may or may not be installed already. If you want to be able to access the SSH connection to the device directly from the browser window, you need to install these SW components. The installation steps are described in the SNMP Gateway help page.
</p>
<h5 style="margin-top: 30px;"> How does the Tunnel 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;"> How to setup a tunnel</h5>
                    <hr>
<p class = "text-justify">
When there are some tunnels in invalid state (e.g. Dead) and cannot be Shutdown, you may recover the Tunnel Slots. Please note that prior attempting this action, you should close all running tunnels as running the recovery action while some of the tunnels are running may leave them open on server side, just not visible, so that the device running a tunnel will not be able to run another tunnel without any visible cause.
</p>
<p class = "text-justify">
The recovery action requires DWARFG_LONG restart, imposing a short downtime of the system. The restart should take just a few seconds usually but may take longer depending on number and size of unfinished database operations, startup time of the system dependent on number of devices and free resources on your server.
</p>
<p class = "text-justify">
To perform the action, go to <b>System -> Status</b> and click on <b>Tunnel Slot Cleanup + Restart</b> button.
</p>
<h5 style="margin-top: 30px;">Tunnel FAQ</h5>
                    <hr>
<p class = "text-justify">
	<ul>
		<li><b>Why is my device not able to setup Tunnel?</b></li>
			<ul><li>The Tunnel is setup from the device side and it needs a full-featured ssh client. Some device types (e.g. Teltonika routers, OpenWRT devices) with old firmware versions are shipping a limited ssh client (<b>dropbear</b>) by default that is not able to establish the Tunnel. 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 Tunnel functionality working. Note that with recent RUTOS (Teltonika routers), even the default client (dropbear) is able to support the Tunnel functionality and for these, you don't need to install anything.</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 Tunnel 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>
			<li>Please note that if you want to debug something on the device via the SSH Tunnel connection, you must not stop the agent running on the device. If you do that, the agent forces stop of the tunnel during agent teardown so your SSH connection will be interrupted and because you just manually stopped the agent, it will not start up again until the device reboots.</li>
		</ul>
	<li><b>Why can't I setup no Tunnel (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 Tunnel SSH port</b></li>
		<li>SSH server problem - Tunnels 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 Tunnel SSH port</b></li>
		<li>Configuring the port - your server admin can configure the ssh port to be used by Tunnels 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 Tunnels (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 Tunnels 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 Tunnels 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 Tunnels, Mozilla Firefox for the other one)</li></ul>
		<li><b>Why does my browser offer DWARFG_LONG credentials for logging into the router via Tunnel?</b></li>
		<ul><li>The way the Tunnels 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 Tunnel.</li></ul>
	</ul>
</p>
                </div>
            </div>
        </div>
    </div>

{% endblock body %}