Skip to content

update README #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 16, 2025
Merged

update README #91

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
19b5c6c
update README
ntozaks Jul 15, 2025
8e465ad
updating README instructions
ntozaks Jul 15, 2025
8cf909e
Merge branch 'sandialabs:main' into main
ntozaks Jul 16, 2025
d0270fc
minor README tweaks
ntozaks Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 5 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,7 @@ On the Client machine, run Wiretap's `configure` command to generate starting co

> [!IMPORTANT]
> By default the listening port will be configured to be the same as the port specified in the `--endpoint IP:port`. This can be overwritten using the `--port` argument.
> If creating an outbound connection, by default the listening port will be configured to be the same as the port specified in the `--outbound-endpoint IP:port`. This can be overwritten using the `--sport` argument.

Following the example in the diagram:
```bash
Expand Down Expand Up @@ -220,7 +221,7 @@ Config File: ./wiretap serve -f wiretap_server.conf
---

> [!NOTE]
> The 51821 ListenPort in `wiretap.conf` needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the [How It Works](#how-it-works) section for details. Use `--simple` in both the `config` command and the Server's `serve` command if your setup requires a single interface on the Client
> The 51821 ListenPort in `wiretap.conf` needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the [How It Works](#how-it-works) section for details. Use `--simple` in the `configure` command if your setup requires a single interface on the Client. The Server will auto-detect that configuration.

Install the resulting `wiretap_relay.conf` and `wiretap.conf` configs files into WireGuard on the Client:

Expand All @@ -230,22 +231,16 @@ Install the resulting `wiretap_relay.conf` and `wiretap.conf` configs files into
> [!TIP]
> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` (or re-import them into the GUI) after making the change. No changes are needed on the Server to update them.

> [!WARNING]
> In the default configuration, with the Client listening for an initial Server connection, the Server will still also listen on port 51820 so that other Servers can attach to it later. There is currently no way to change this when running the `configure` command, but when running `wiretap serve` you can manually change this in the `wiretap_server.conf` file, or using the `WIRETAP_RELAY_INTERFACE_PORT` environment variable.

Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-quick down ./wiretap.conf && sudo wg-quick down ./wiretap_relay.conf`)

### Outbound Connections
You can use the `--outbound` flag to configure the Client to Initiate the UDP connection to the Server. If you do, the `--endpoint` value will instead be used to tell the Client where to connect to the Server, and the `--port` value (explicit or implicit) will configure the Server's listening port.
You can use the `--outbound-endpoint` flag to configure the Client to Initiate the UDP connection to the Server. If you do, the `--outbound-endpoint` value will instead be used to tell the Client where to connect to the Server, and the `--sport` value (explicit or implicit) will configure the Server's listening port.

In this case the Client will listen on 51820 in case other Servers need to be added using the default Inbound mode, but this can be changed via the `ListenPort` variable in the `wiretap_relay.conf` file if needed.
In this case the Client will listen on 51820 in case other Servers need to be added using the default Inbound mode, but this can be changed by passing a value to the `--port` flag when running the `configure` command.

### Simple Mode
While not recommended, you can add the `--simple` flag to configure Wiretap as a more traditional one-Client-and-one-Server VPN. Most of Wiretap's dynamic configuration features (any Wiretap commands you would run after establishing the initial connection) will be unavailable in this mode.

> [!WARNING]
> When starting the Server, you may need to also use the `--simple` flag. The Server currently does not support automatically detecting this configuration.

## Serve

On the remote machine, upload the Wiretap binary and then run one of the commands from the output of `configure` to start Wiretap in Server mode:
Expand Down Expand Up @@ -361,7 +356,7 @@ Config File: ./wiretap serve -f wiretap_server_1.conf

This command will modify the Client's E2EE configuration (`wiretap.conf`) to allow communication with the new Server, so you need to re-import it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay config will also need to be refreshed in the same way.

Now you can use any of the `serve` command options to start Wiretap on the new Server, just like you did after running the `config` command. It will then join the Wiretap network by connecting to the existing Server.
Now you can use any of the `serve` command options to start Wiretap on the new Server, just like you did after running the `configure` command. It will then join the Wiretap network by connecting to the existing Server.

At this point the new routes should be usable! You can confirm that everything looks correct with `wiretap status`:

Expand Down
Loading