Code Monkey home page Code Monkey logo

docs's Introduction

alt text

OPNsense documentation

Welcome to the OPNsense documentation & wiki.
The purpose of this project is to provide OPNsense users with quality documentation.

Contribute

You can contribute to the project in many ways, e.g. testing functionality, sending in bug reports or creating pull requests directly via GitHub. Any help is always very welcome!

License

OPNsense documentation is available under the 2-Clause BSD license:

http://opensource.org/licenses/BSD-2-Clause

Every contribution made to the project must be licensed under the same conditions in order to keep OPNsense truly free and accessible for everybody.

Some pictures are licensed under the Creative Commons Zero (CC0) license:

https://creativecommons.org/publicdomain/zero/1.0/

Logos may be subject to additional copyrights, property rights, trademarks etc. and may require the consent of a third party or the license of these rights. Deciso B.V. does not represent or make any warranties that it owns or licenses any of the mentioned, nor does it grant them.

Prepare build

On FreeBSD the following packages are required:

pkg install py39-pip jpeg-turbo gmake

Install Sphinx, our default theme and contrib packages:

pip[3] install -r requirements.txt --upgrade

Update API endpoints

A script is provided to update the api endpoint documentation, this can be executed using:

./collect_api_endpoints.py --repo core /path/to/core/repository
./collect_api_endpoints.py --repo plugins /path/to/plugins/repository

Generate HTML documents

make html

(make clean to flush)

Live preview of HTML documents

Use sphinx-autobuild to track source for changes and get a live preview served via http://localhost:8000.

pip[3] install sphinx-autobuild
sphinx-autobuild source html

docs's People

Contributors

adschellevis avatar c-duv avatar cbrueffer avatar dlcasto avatar doktornotor avatar dpieski avatar e-cite avatar fabianfrz avatar fichtner avatar fvanroie avatar greelan avatar jschellevis avatar kdgundermann avatar kulikov-a avatar marcquark avatar marjohn56 avatar maurice-w avatar michaeldeciso avatar mimugmail avatar monviech avatar opensourcecontribution avatar qinohe avatar salazarbruno avatar satrapes avatar sjjh avatar swhite2 avatar teamlinux01 avatar thgoebel avatar zenarmor avatar zerwes avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

docs's Issues

Build errors in IPsec road warrior files; some duplication

When building the documentation, there are some build errors in the ipsec-rw*.rst files. Additonally, both ipsec-road.rst and ipsec-rw.rst exist, and both are about the same subject.

@mimugmail was the last person to work on it, and it appears to a work in progress. For this reason, I haven't yet touched these files, but I'd like @mimugmail to tell me what the plans are.

Build issues when using python 3

WARNING: dot code 'blockdiag {\n   OPNsense [shape="cisco.firewall", label=""];\n   internet [shape="cloud"];\n   private_net [shape="cloud", label="private net"];\n   Gateway1 [shape="cisco.router", label=""];\n   Gateway2 [shape="cisco.router", label=""];\n   Gateway3 [shape="cisco.router", label=""];\n   OPNsense -> Gateway1 -> internet;\n   OPNsense -> Gateway2 -> internet [style = dotted];\n   OPNsense -> Gateway3 -> private_net;\n\n}': integer argument expected, got float
WARNING: dot code 'nwdiag {\n\n    span_width = 90;\n    node_width = 180;\n    Internet [shape = "cisco.cloud"];\n    fileserver [label="File Server",shape="cisco.fileserver",address="192.168.1.10"];\n    fileserver -- switchlan;\n\n    network LAN {\n      switchlan [label="",shape = "cisco.workgroup_switch"];\n      label = " LAN";\n      address ="192.168.1.1.x/24";\n      fw1 [address="192.168.1.1/24"];\n    }\n\n    network WAN  {\n      label = " WAN";\n      fw1 [shape = "cisco.firewall", address="172.18.0.164"];\n      Internet;\n    }\n\n    network Remote {\n        Internet;\n        laptop [address="172.10.10.55 (WANIP),10.10.0.1 (IPsec)",label="Remote User",shape="cisco.laptop"];\n    }\n  }': integer argument expected, got float

blockdiag/blockdiag#111
blockdiag/blockdiag#130

Installation and setup / Explain a bit about plugins, ports

From time to time we see questions about software not distributed by us in binary form, it might be good to explain a bit what we ship, how it's called and how you can use ports to build packages on the machine which are not being shipped by us.

Adding other repositories (FreeBSD, HardenedBSD) has risks, which is good to warn about upfront.

Tutorial about maxmind geoip license key generation is unclear/outdated

With the latest release 19.7.9 the change "For now, this update brings you a GeoIP database configuration page for aliases which is now required due to upstream database policy changes and
a number of prominent third-party software updates we are happy to see included." is announced. In the web front end help text it says, that the OPNsense documentation contains more information. Searching online, I did find https://wiki.opnsense.org/manual/how-tos/maxmind_geo_ip.html
This how to states "Once you have created an account you’ll need to create a license key. Click in the “My License Key” link and generate a key. Save the key ID somewhere safe!!!", doing so I get asked during the key generation at maxmind if geoip update isused (I assume yes) and which version of geoipupdate is used as starting with version 3.1.1 the key is hased. The OPNsense how to doesn't contain any information regarding this choice.
I would be nice to improve the documentation by

  • mentioning that geoip update is used (if that is correct)
  • stating if the hashed or unhashed key shall be used

Core documentation gaps

Let's compile a list of the core topics missing at the moment, while restructuring the index.

  • System --> Routes
  • Interfaces --> Wireless
  • Firewall --> Rules
  • Firewall --> Groups
  • Firewall --> VirtualIPs
  • Firewall --> Settings
  • Services --> Dnsmasq DNS
  • Services --> Network Time
  • Services --> OpenDNS
  • Services --> Router Advertisements
  • Services --> Unbound DNS

web-proxy: Enable Linux Package Cache is not documented

The new feature "Enable Linux Package Cache" has a too brief description that looks more likea marketing message than a technical doc:

Enable or disable the caching of packages for linux distributions. This makes sense if you have multiple servers in your network and do not host your own package mirror. This will reduce internet traffic usage but increase disk access.

This does tell the user how the caching would function. Also the official product documentation does not include any mention of this feature.

Please provide more information regardin the outcome of this option as in which condition it would work or not.

DnsCrypt missing API docs

I am trying to find figure out how to call the API for DnsCrypt but so far from looking at the code no dice.
Can the missing Documentation for the API for this be added please? TIA

CC @mimugmail

Feature request: show the location of logfiles in GUI

Hello devs,
I was trying to locate the logfile for pf in the filesystem, but was unable to find. That was when I realised, there is no hint in the GUI, from which log the GUI data is coming from. I think it would make sense to reveal the path to the file that is being presented in the various GUI logging related menus. So if one wants to read these logs directly from CLI, there will be specific info which logfile needs to be opened.

Page unclear

Page: https://docs.opnsense.org/support.html

It is currently impossible to make a difference between T2 & T3 - is the documentation wrong or is the information missing at the plugins repository?

Are the plugins really uncritical? Many users depend on reverse proxies such as nginx or HAProxy because they have to route based on the Host header at least because they need the same port for multiple servers. Some users may need to run FRR because they operate at the edge of an AS and without it, they don't have internet access because the other routes don't have the routes back…

"one physical machine as master and a second machine as slave"

This sentence from the carp how-to contains a thinko I think.

When using different network drivers on both machines, like running a HA setup with one physical machine as master and a second machine as slave, states can not be synced as interface names differ. The only workaround would be to set up a LAGG.

I think this edit would fix it: s|second|virtual|

Where to add expanded info for new devs?

The existing docs are extremely terse. They're good for a brief example, but leave so much untouched-on, that the learning curve is unnecessarily steep once off these basics, for less experienced or new developers, and those not previously using phalcon.

Additionally OPNsense project uses a customised file style, with xml not databases, for which even fewer references exist. Even basics such as "what types exist in a form" or "how are fields organised and collated to get from xml to form?" are hard to find. The main source on available types is the source code file src/opnsense/mvc/app/views/layout_partials/form_input_tr.volt, which isn't at all easy to locate unless one knows a bit already and what to search for, and definitely isn't readily found by a completely new-to-phalcon dev who "just wants to get going". And there's not much at all about our xml files because thats a customisation.

It's often easy to overlook what's needed, hard to learn, or not obvious, once it's become familiar. (That's not in any way meant as a crtitique, it's a recognition of something almost inevitable and almost universal for new devs on many projects). As I'm a new dev, and seem (surprisingly!) to be coping with learning this, and starting to push a few PRs, I'd like to start adding some more targeted brief documentation and examples to ease the way for other new to these things, to simplify the learning curve.

It would be a kind of "New Developers Guide" (or section) taking up where "hello world" stops, to fill the gap between "hello world" and a realistic extension or core code PR, overviewing practical creating and modifying legacy and new-style code, extensions, etc - which I suspect will be useful.

Tl;Dr - If that's okay, can you let me know where to put them in the dev guide, and a preferred title for now?

Cloud Import users button missing for LDAP

The Cloud import button is missing after I added LDAP server (Zentyal, I can communicate with it):

Also I got this error, is it linked somehow?

[07-Oct-2019 16:24:01 Atlantic/Azores] PHP Warning: implode(): Invalid arguments passed in /usr/local/www/system_authservers.php on line 249

I have the system upgrade since 17.0

Currently:
OPNsense 19.7.4_1-amd64
FreeBSD 11.2-RELEASE-p14-HBSD
OpenSSL 1.0.2s 28 May 2019

"Dubunking the myths" section of wiki and notes on credibility

Debunking the Myths
There are some myths surrounding our project offered mostly by pfSense enthusiasts, if you have read their comments on us then we’d recommend to just ignore them and install OPNsense, if you have not already done so.

I am not sure if you know what debunk means, but you clearly haven't done it here. You literally just say to ignore the claims of your main competitor, and install your software with no explanation of the overall situation. This basically lets the PfSense people say whatever they want about you, and everyone only ever hears their half of the story.

I only recently became aware of the PfSense/OPNSense... "flame war" for lack of a better word, but this failure to address the claims of the PfSense people worries me. Make no mistake, I have no trust whatsoever for PfSense after they stopped releasing their source code, the opnsense.com fiasco, and their deliberately misleading advertising, but I have seen no evidence presented thus far about how OPNSense is supposed to be any better.

Obviously, they make a lot of ridiculous claims and it is difficult to debunk all of them, but there are a few recurring ones that seem to keep coming up:

  • They claim that OPNSense attempted to steal the PfSense trademark and become "PfSense in Europe".
  • They claim that you are a bunch of amateurs who routinely push alpha quality software, and deliberately remove features, so that you can add them back in over a period of several months so you look like you are doing something.
  • They claim that your code quality is bad, and that you have broken VPN functionality, and VLANs on 5 separate occasions.
  • They claim that the original OPNSense fork was mainly so that you could sell branded hardware, not because you are actually trying to improve it.
  • They claim that they have tried to contribute to OPNSense and been told to "fuck off" by the lead people.

A simple google search for "pfsense vs opnsense" should turn up the respective threads on reddit, various forums, and ycombinator, but for convenience I will list a couple of them here:

Note: A lot of the time, the posters are either gonzopacho or htilonom. I think it is reasonable to assume that they are representative of the PfSense crowd, however there are other people who bring up points on these forums that aren't explicitly associated with PfSense, but who nonetheless make claims about your behavior that I think may need to be addressed.

Broken VLANs, branded hardware and Europe trademark issue:

https://www.reddit.com/r/PFSENSE/comments/3rh9dw/pfsense_vs_opnsense/

They also claim that you tried to delete their Wikipedia page, although from what I understand they also tried to do this to you.

Feature reintroduction issue, broken VLANs:

https://www.reddit.com/r/PFSENSE/comments/35dl17/pfsense_vs_opnsense_articles/

"We've fixed bugs in opnsense for people, and were told to fuck off by both Franco and Jos. We've pointed out errors in how they do things and have been told to fuck off by Franco and Jos." Not sure about this one either, no corroborating evidence.

The point is, you not saying anything about any of this is a bad idea. It makes it seem like you are deliberately avoiding addressing these issues, which might lead some people to conclude that you have something to hide. For context, this is similar to gonzo's response (or lack thereof) to the claims that it has been impossible to reproduce PfSense builds since 2.3.5. Whenever people bring it up, he simply doesn't reply.

I can't personally edit the documentation to add this information, because I am new to this whole affair, and thus cannot comment intelligently on what has been going on. I am also not a representative of OPNSense, so it would be inappropriate.

My trust in OPNSense is undecided as of now, because of this failure to address these issues. Even if you don't cover all of them, there are a lot of them that keep coming up. It may also be a good idea to explain some of the deceptive behavior engaged in by PfSense/Netgate (or whatever their parent company is now called). The failure to release source code/build tools is a big deal, and you should really explain that in the "Why did we fork section".

Add documentation for the expected JSON data structure for API endpoints

I tried to get started with the OpnSense API following the given docs:

Connecting and interacting with the API works well so far.

As my goal is "adding custom IDS/IPS rules" to the process I tried doing
so via the following endpoint:
POST https://my-opnsense/api/ids/settings/adduserrule

What I'm missing is the expected data format of the JSON object
used within the POST that describes my actual rule.

Striving through the docs I've not seen any description of POST
values or examples. I would love to see this as an enhancement
for easing the learning curve of the API.

;-)

Hover text for service restart

Hello devs,

a note: maybe its just me, but if I see the service status any of the locations (service status on the dashboard, or System: Diagnostics: Services or the various individual services under \Services), the icon representing the "recycle" symbol can be interpreted in different ways:

  1. restart of the service
  2. reload of the service

The option 1) will result complete service-interrupting restart of the service, while 2) may just reload the service configuration file, keeping the service still UP.

I figured it out the actual performed action is indeed 1) but that may not be that obvious for any new user. Do you think some hover message when pointing to the icon with mouse should clearly say: "Restart service" to signal it wont be just a non-interrupting "Reload config" ?

The reason why I mentioned this issue under DOCS is that I couldnt find any page that describes the "services" section, where it could be clearly mentioned that the recycle symbol does service-interrupting restart and not config reload.

Thanks!

No mention of required plugins on doc pages

I was looking into dynamic routing, and there is absolutely no mention whatsoever that a plugin is required for this feature (which I expected would require a plugin). Additionally, figuring out which plugin also look far too much work to figure out, too. The docs should be updated to list required plugins on their various configuration documentation pages.

Examples:
https://wiki.opnsense.org/manual/how-tos/dynamicrouting_ospf.html
https://wiki.opnsense.org/manual/how-tos/dynamicrouting_howto.html

Update NGINX how-to with relevant image

In section 3, the image is just a blank location window. Can we get it updated to show whatever is needed to follow along?

Also, Is that the entirety of everything necessary to setup NGINX? No ports need to be adjusted in NAT, etc?

docs/source/manual/how-tos/nginx.rst

Local docs

Hi guys, don't know if it's me or it's the docs, but, in the online docs (wiki.opnsense.org) I can search for an item the results are in the right frame.
However, when I compile the docs locally I'm not able to perform a search, the 'wheel' keeps running nothing happens.
Now just as a check I didn't miss any library or other piece of software in the docs or on my server, I compiled the Pfsense wiki, put it on my local server and checked if the search function works and it does.

It could still be I'm missing something or this is already know, but I didn't find relevant info.
Thanks again for this beautiful OS, mark

install igmp proxy needed

Orange France IPTV setup

The howto looks like "igmp proxy" is installed by default.

It is not. And newbee can search it for days.

Just mention
-must be added from the plugins repo
-and a restart is needed

Unbound not starting with custom option and Override Domain

Configured Unbound to forward, as per https://wiki.opnsense.org/manual/how-tos/bind.html

Unbound failed to start, with error:
opnsense: /services_unbound.php: The command '/usr/local/sbin/unbound -c '/var/unbound/unbound.conf'' returned exit code '1', the output was '/var/unbound/unbound.conf:106: error: syntax error read /var/unbound/unbound.conf failed

The offending line in config was: do-not-query-localhost: no

Identified that the cause was also having a Domain Override configured. Once the domain override was removed, Unbound started okay and forwarding worked as expected.

More product alignment.

This looks like the last batch of things todo to create a baseline for our product documentation:

  • System --> Configuration / local backups, defaults and history
  • System --> Firmware (partially covert in installation and setup)
  • System --> HA sync, status page and some general workflow information
  • System --> Settings, move system logging into it.
  • System --> Trust, rename menu item for consistency
  • System --> Diagnostics, move content to own page, extent content when needed.
  • Interfaces --> Interfaces / assignments, not sure yet, doesn't look very useful as is, but might stay this way.
  • Interfaces --> Overview.
  • Interfaces --> Wireless, add landing page, we (as Deciso) generally don't advice wireless setups at the moment. Not planning to spend a lot of time here, some cards work, some don't.
  • Interfaces --> Mobile Networking, probably move
  • Interfaces --> Diagnostics, move content to own page, extent content when needed.
  • Firewall --> Diagnostics, move content to own page, extent content when needed.
  • Some general trouble shooting (some error codes from https://github.com/opnsense/src/blob/master/sys/sys/errno.h )

OPNsense/OpenVPN using SSL + user authentication documentation required

Is your feature request related to a problem? Please describe.
As authentication scripts are not standardized it is not clear which user name and password are used for additional authentication in this case. It is obviously not the account the certificate is connected to.

Describe the solution you'd like

  1. An exact description in the OPNsense manual section "Setup SSL VPN Road Warrior" (maybe renaming it might be a good idea because the term "Road Warrior" is not showing up anywhere in the menus) explaining the relationship between the account's user name, the Descriptive Name and the Common Name entries in the linked certificate and which of them is the User Name OpenVPN will demand for authentication.

  2. Add some reminders to the info/help texts in the OpenVPN section.

Describe alternatives you've considered
Finding out by reading the source code for hours.

[Tracking issue] Documentation coverage

This is a tracking issue, meant to track which parts of the product have been documented, which parts haven't been, and which parts have documentation that is outdated or not up to standard.

This tree follows the menu structure of OPNsense:

Also see these issues:

How-To for clamav is a bit too brief, how does clamav work?

After reading the how to for clamav ( docs/source/manual/how-tos/clamav.rst) ist's unclear to me if the plugin works on its own or if the proxy and c-icap needs to be enabled in addition to make any use of clamav. It would be good to expand a little on how clamav works (on its own) and what it does, or which other plugins (c-icap & web proxy?) need to be used together with clamav to make any use of it.

DNS for OpenVPN users (Road Warriors)

The How-To for VPN mobile users is a very good document. It has gotten me to the point where I am able to successfully connect to my private LAN. The fact that even I can do this is a strong testament to the quality of this document!

However, I do have one long-standing problem that I would very much like to see addressed in this document: How to configure my DNS services in OPNsense so that remote clients can "see" resources on the network as they do when they are physically on the LAN, or at least be able to connect to resources by hostname rather than IP address.

I currently have to do a manual DNS by logging into OPNsense, and reviewing the active DHCP leases! Fortunately for me, I can access the OPNsense server... the other remote users must rely on keen memories :)

Menu item "System > Access > Configuration" is gone

Referring to the documentation here, I am unable to find the menu entry for "System > Access > Configuration":
image

I was looking for the described settings in other sections for quite a while but did not succeed.
I was wondering whether it might be a bug?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.