Skip to content
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.

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

Split README into Wiki #56

Closed
Aptimex opened this issue Aug 20, 2024 · 5 comments · Fixed by #67
Closed

Split README into Wiki #56

Aptimex opened this issue Aug 20, 2024 · 5 comments · Fixed by #67
Labels
documentation Improvements or additions to documentation planned feature Likely to get implemented in the future

Comments

@Aptimex
Copy link
Collaborator

Aptimex commented Aug 20, 2024

The Readme is really long, would probably be more useful to have the different headings split into topics in a Wiki format.

@Aptimex Aptimex added planned feature Likely to get implemented in the future documentation Improvements or additions to documentation labels Aug 20, 2024
@luker983
Copy link
Collaborator

The docs could certainly be better organized. I tend to prefer a table of contents and Cmd+F rather than having to rely on a wiki search bar and jumping between pages though.

Moving the demo section to a Wiki page and linking to it from pretty high up in the existing readme would be a good first step I think.

@Aptimex
Copy link
Collaborator Author

Aptimex commented Aug 26, 2024

ToC and some cleanup might be good enough. I'll get some additional internal feedback on user preferences before committing to the full Wiki idea.

Agreed that would be a good first step either way.

@Aptimex
Copy link
Collaborator Author

Aptimex commented Oct 1, 2024

@luker983 Can you review the new How it Works section in this branch and make sure I got it all right? In particular some clarification about how the API address relates to the Relay or E2EE interfaces would be helpful. Including how they get assigned, since I don't see them in the config files.

Any other feedback on the Readme there is welcome too, but it's still a WIP

@luker983
Copy link
Collaborator

luker983 commented Oct 3, 2024

Sure! Looks good. Some feedback:

I think this section could probably be moved to the wiki as well since it's grown quite a bit. Maybe just leave the diagram and a link to the wiki page?

This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details.

I think we can do both, demonstrate the concepts without compromising accuracy

These UDP connections occur over real-world TCP/IP network infrastructure.

All of the network traffic occurs over "real-world" network infrastructure, we just add one additional layer over a traditional VPN. I think "overlay network" might be the most common term for this.

Relay interfaces receive internal Wireguard IPs: 172.16.X.X for IPv4, and fd:16::X for IPv6.

This is all configurable, consider adding "By default, " before this line.

Each Server is dynamically assigned an additional unique IP (usually an IPv6 address, such as ::2) inside the E2EE network to enable the secure usage of this API.

The API addresses are assigned just like the relay/e2ee peer IPs, it's an incrementing value kept track of by the first Server: https://github.com/sandialabs/wiretap/blob/readme-updates/src/transport/api/api.go#L262

They appear in the e2ee config under AllowedIPs (so the client has a route to the API).

The API handler binds to the API address on the e2ee interface (internal to the program, the userspace networking stack, only reachable by clients).

@Aptimex
Copy link
Collaborator Author

Aptimex commented Oct 3, 2024

Yeah the Details section is probably better off in a Wiki page, I'll move that.

I think we can do both, demonstrate the concepts without compromising accuracy

Fair, that was mostly in reference to my explanation of Servers acting like typical TCP/IP Routers, and I wasn't sure if that was actually how they worked under the hood.

All of the network traffic occurs over "real-world" network infrastructure

I'm trying to differentiate between traffic that is visible to "real world" devices (packets that have IP headers for routing to host NICs) vs. packets that only get routed inside the userspace Wiretap network and are effectively invisible to the hosts during transport. Since I'm already describing the "Relay" and "E2EE" virtual/overlay networks, "real-world" network seems like the most appropriate term to differentiate where those outer-most connections happen, but I'm open to better terminology ideas.

Thanks for the API clarification, I've expanded on that section in the new Wiki page.

@Aptimex Aptimex linked a pull request Oct 31, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation planned feature Likely to get implemented in the future
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants