{% extends "base.html" %}
{% block title %}Help{% endblock %}
{% block content %}
<h1>Help</h1>
<nav class="help-toc" aria-label="Contents">
  <a href="#help-overview">Overview</a>
  <a href="#help-start">Getting started</a>
  <a href="#help-editor">Patch editor</a>
  <a href="#help-nodes">Node types</a>
  <a href="#help-origin">Visitor addresses</a>
  <a href="#help-pages">Services and Stats</a>
  <a href="#help-settings">Settings and login</a>
  <a href="#help-trouble">Status messages</a>
</nav>

<section class="card help" id="help-overview">
  <h2>Overview</h2>
  <p>PatchBay forwards ports between Linux machines over SSH. One machine is the <strong>target</strong>: it runs this web UI and is reachable from the internet. Every other machine is a <strong>client</strong>: it keeps an SSH connection open to the target, so it needs no open ports and can sit behind NAT.</p>
  <p>You decide what goes where by wiring nodes on the Patch page, like cables on a patch panel. A <strong>source</strong> is a service you want to reach (for example a web server on a client), a <strong>sink</strong> is where it shows up (for example a public port on the target). All traffic passes through the target, which counts it for the Stats page.</p>
</section>

<section class="card help" id="help-start">
  <h2>Getting started</h2>
  <ol>
    <li>Install a client with <code>./install.sh --role client</code> and set <code>TargetHost</code> (and <code>TargetPort</code>) in <code>/etc/patchbay/patchbay.conf</code>.</li>
    <li>On the client, run <code>patchbayd --pubkey</code> and paste the output under <a href="{{ url_for('views.settings') }}">Settings</a> &rarr; Clients.</li>
    <li>Start <code>patchbayd</code> on the client. It shows as online on the Patch and Services pages within a few seconds.</li>
    <li>On the <a href="{{ url_for('views.patch') }}">Patch</a> page, add a Client Source for the service and a Public Sink for the port you want to open, then drag a wire from the source's output to the sink's input. That's it: the port is live as soon as the status line says "ready".</li>
  </ol>
</section>

<section class="card help" id="help-editor">
  <h2>Patch editor</h2>
  <ul>
    <li><strong>Add</strong> creates a node in the middle of the view. Fill in its fields; changes are saved automatically and applied straight away.</li>
    <li><strong>Wiring:</strong> drag from an output socket (right side) to an input socket (left side). Grab a connected input to move its wire elsewhere. Click a wire and press its &times; button, or double-click it, to remove it.</li>
    <li><strong>Wire colours:</strong> blue is TCP, orange is UDP. A dashed wire means source and sink use different protocols and will not work.</li>
    <li><strong>Moving around:</strong> drag empty space to pan, scroll to zoom, <strong>Fit</strong> shows everything.</li>
    <li><strong>Selecting:</strong> click a node, or right-drag a box over several nodes (hold Shift to add to the selection). Drag the header of any selected node to move them all. Delete removes the selected nodes.</li>
    <li><strong>Tidy</strong> snaps all nodes to the grid and keeps them on it while it is switched on.</li>
    <li>Each sink shows its state at the bottom: live traffic and open connections, or what is wrong (see <a href="#help-trouble">Status messages</a>).</li>
  </ul>
</section>

<section class="card help" id="help-nodes">
  <h2>Node types</h2>
  <table class="help-table">
    <tbody>
      <tr><td><span class="swatch client_source"></span>Client Source</td><td>A service on a client, e.g. <code>127.0.0.1:80</code> for a local web server. The address is as seen from that client, so it can also be another machine in the client's network.</td></tr>
      <tr><td><span class="swatch public_sink"></span>Public Sink</td><td>A port opened on the target. Bind <code>0.0.0.0</code> makes it reachable from everywhere, <code>127.0.0.1</code> only from the target itself.</td></tr>
      <tr><td><span class="swatch client_sink"></span>Client Sink</td><td>A port opened on a client. Use it to reach a service on one client from another client, without exposing it publicly.</td></tr>
      <tr><td><span class="swatch splitter"></span>Splitter</td><td>Sends one source to several sinks, e.g. the same service on a public port and on a client. A source has only one output, so use a splitter to fan out.</td></tr>
      <tr><td><span class="swatch tunnel_source"></span>Tunnel Source</td><td>A host behind a VPN interface (<code>tun0</code> etc.), on the target or on a client. Enter the interface and the peer's address inside the VPN.</td></tr>
      <tr><td><span class="swatch tunnel_sink"></span>Tunnel Sink</td><td>A port that only accepts connections arriving through a VPN interface, so VPN peers can reach a service that is not open anywhere else.</td></tr>
    </tbody>
  </table>
  <p class="muted">Label is a free-text name shown in Stats. Interface suggestions come from the tun interfaces each host reports.</p>
</section>

<section class="card help" id="help-origin">
  <h2>Visitor addresses</h2>
  <p>Normally a service behind PatchBay sees every visitor as coming from PatchBay itself (for example <code>127.0.0.1</code>). Every sink has two optional checkboxes to pass the real address on. Only one can be on at a time.</p>
  <ul>
    <li><strong>PROXY v2</strong> puts a small header with the visitor's address in front of each connection. The service must understand the PROXY protocol, otherwise it sees garbage and drops the connection. Examples: Apache with <code>mod_remoteip</code> and <code>RemoteIPProxyProtocol On</code>, nginx with <code>listen ... proxy_protocol</code>, HAProxy, Postfix, Dovecot. For UDP the header is in front of every datagram.</li>
    <li><strong>Transparent source spoofing</strong> makes the connection arrive from the visitor's own address, so any program sees it without configuration. The source must be on a client, and the service should listen on a loopback address like <code>127.0.0.1</code>. PatchBay sets up the routing this needs on the client by itself (setting <code>TransparentTable</code>, default 470). If the visitor uses IPv6 and the service only IPv4, that connection falls back to the normal address.</li>
  </ul>
</section>

<section class="card help" id="help-pages">
  <h2>Services and Stats</h2>
  <p><a href="{{ url_for('views.services') }}">Services</a> lists the listening ports on every host with the program behind them, which helps to fill in source addresses. Use Refresh now to ask all hosts for a fresh list.</p>
  <p><a href="{{ url_for('views.stats') }}">Stats</a> shows traffic per sink: current rates, open connections and history from the last hour up to all time. "In" is traffic towards the service, "out" is traffic back to the visitor. How long history is kept is set under Settings.</p>
</section>

<section class="card help" id="help-settings">
  <h2>Settings and login</h2>
  <ul>
    <li>Logging in takes your password plus a 6-digit code sent by email. Too many failed attempts block your address for a while.</li>
    <li>All users can edit the patch and add or remove clients. The <strong>sysop</strong> (the account in <code>patchbay.conf</code>) also manages users, the mail server and statistics retention.</li>
    <li>Removing a client disconnects it at once; its nodes stay in the patch without a client until you pick another one.</li>
  </ul>
</section>

<section class="card help" id="help-trouble">
  <h2>Status messages</h2>
  <table class="help-table">
    <tbody>
      <tr><td>not connected</td><td>The sink has no wire into its input.</td></tr>
      <tr><td>source offline</td><td>The client with the source is not connected right now. Check that <code>patchbayd</code> runs there and its key is listed under Settings.</td></tr>
      <tr><td>protocol mismatch</td><td>Source and sink use different protocols (TCP vs UDP).</td></tr>
      <tr><td>bind ... failed</td><td>The port is already used by another program, or the bind address does not exist on that host.</td></tr>
      <tr><td>interface not present</td><td>The tun interface does not exist (yet). PatchBay retries every few seconds, so this clears once the VPN is up.</td></tr>
      <tr><td>transparent spoofing needs a source on a client</td><td>Spoofing only works when the service is reached from a client. Use PROXY v2 instead, or move the source.</td></tr>
      <tr><td>daemon not reachable</td><td>The web UI cannot talk to <code>patchbayd</code> on the target. Changes are saved and applied once it runs again.</td></tr>
    </tbody>
  </table>
</section>
{% endblock %}