search

opnsense / docs

OPNsense documentation
Other
118 stars 187 forks source link

Update to install.rst #456

Closed linuxdude21 closed 1 year ago

linuxdude21 commented 1 year ago

First-half installation page change. I wanted to know what you all think before continuing to update the 2nd half of the installation guide. The biggest changes are the order (flow) of the install guide and OPNsense Importer.

Order: The page first talks about Image types then jumps to Download & verification (should be closer to the installation section), and then back to installation Media, naming, etc. The flow in this change is installation images/media, downloading, verifying, and installing.

OPNsense Importer: Complete rewrite to give direction on how to use it.

Removals: LibreSSL vs OpenSSL Cut back on the directions for downloading image files, as the previous directions failed after step 2. Most browsers today download even if you right-click and open in a new tab. (lands signed and verified in the GUI of the running software) Updates: Installation Media adding Image Type column add openssl checksum step

fichtner commented 1 year ago

Thanks for doing this! I'll probably nag here quite a bit but really appreciate the help. Apologies in advance :)

linuxdude21 commented 1 year ago

No nags at all, I appreciate the insights. No apologies are needed at all. I want to know if I'm heading in the right direction. One bit of help I'm going to need on my side is the proper use of Github. Do I make these corrections on my local doc and update this pull request? Honestly, this is the part of Github I just don't understand, forking, push/pulls requests.

fichtner commented 1 year ago

The git branch is basically the GitHub PR... you add more changes locally, commit them on top and push to same branch to make the additions appear here.

linuxdude21 commented 1 year ago

Sorry guys not sure if I did the 2nd PR correctly or not. I've made all the edits from last night.

linuxdude21 commented 1 year ago

Hey folks, Sorry if I'm doing too many PRs. Please let me know if that is unwanted. Or I should follow a different process?

Also, would like to know if I'm going in the right direction. I don't want to send a bunch of edits that are completely unusable or not accepted. Thanks Nick,

AdSchellevis commented 1 year ago

@linuxdude21 we'll try to discuss next week how we can move this one to a merge, but so far the process from my end looks normal. Just open a new PR (branch) when working on a new topic. When processing feedback, we're used to kep the original one open until it's finished. It has been a busy week, these things sometimes just take time.

linuxdude21 commented 1 year ago

@AdSchellevis & @fichtner Thank you for the replies. When I first got into this, I had a very mild idea of what things I wanted to update. Few section updates, and minor re-ordering. After that last few nights, it's turning into a complete reordering of the sections. With most sections needing some form of updating. I don't mind putting in the time/effort, just don't want it to go to waste because I'm headed in the wrong direction. Please ignore me I'm sure you have bigger fish to fry. Have a great weekend!

AdSchellevis commented 1 year ago

@AdSchellevis & @fichtner Thank you for the replies. When I first got into this, I had a very mild idea of what things I wanted to update. Few section updates, and minor re-ordering. After that last few nights, it's turning into a complete reordering of the sections. With most sections needing some form of updating. I don't mind putting in the time/effort, just don't want it to go to waste because I'm headed in the wrong direction. Please ignore me I'm sure you have bigger fish to fry. Have a great weekend!

@linuxdude21 I've left some small remarks and answers to some of your questions, really love what you're doing with the page. In my humble opinion the sections aren't set in stone, if shifting makes it better readable, we should certainly do so. The only thing that for the whole documentation is more or less fixed is the main menu organization, as that matches most of the product menu layout. I probably want to do a final review after we pulled it in and build the html, sometimes you notice things in its final shape.

fichtner commented 1 year ago

I think we are almost in a mergable state minus what @AdSchellevis wants. May need to go over the doc post-merge as the diff is pretty hard to follow in the grand scheme of things, but that's not an issue.

Thanks so far! :)

Cheers, Franco

linuxdude21 commented 1 year ago

@fichtner Thank you for your edits. Not a problem. Post-merge is the only way to see these suggested changes. The most significant change is the flow of the doc. I have not finished the last Section, "Initial Configuration". As I wanted to focus more on the installation side of things. One my steps was to get a nano image up and running and fell into a rabbit whole with NAT.

Unrelated to the install doc: Where I found a significant flaw in NATing. Not sure if this is a bug or not: my post on the issue But doing a simple Port Forward with an associated filter does not work.

AdSchellevis commented 1 year ago

@linuxdude21 thanks a lot for the updates, made some small changes in https://github.com/opnsense/docs/commit/349fed697443d82177f29cdf57e75644ea9debad (links and added an index due to the length of the page). Results are already published online https://docs.opnsense.org/manual/install.html

About your forum question, I see there's communication there, one tool that's always very helpful when debugging issues is the packet capture in interface/diagnostics (apart from the live log you're already using).

linuxdude21 commented 1 year ago

@AdSchellevis Wow, you already merged. HAHA this is great. Several items were missed. I believe that's my fault, as I started using comments within the doc. With all my edits, they were easy to miss. I submit another PR. I finally got the upstream master to update my local repo. Still trying to under github/repos.

Thank you for the packet capture suggestion. I had already used it on this problem. I saw the firewall sending the packet out the WAN interface, but my client never got them. Franco got the problem disable reply-to on WAN, but I still question why that setting is enabled by default. Another topic for a different day. Thanks again, guys.

AdSchellevis commented 1 year ago

@linuxdude21 ok, let's try to finish this as soon as possible then.

The default reply-to//route-to is mostly for historic reasons, when using multiwan setups you do need to know where to return packets to as default routing doesn't apply. These rules ar a bit wider than you might want, but without adding a lot of hard to follow complexity not really solvable. When not using multi-wan, it's always safe to disable both, when you do need multiwan and "on net" traffic, you just need additional rules to make that explicit (disabling the reply-to).