Where is the documentation?
-
""FAQs" and "HOWTOs" don't cut it."
Says who?
Here is install doc
https://doc.pfsense.org/index.php/Installing_pfSenseCould prob use a refresh sure..
"Since there is zero context-sensitive help in the admin pages themselves"
Have you even looked at the gui? See attached - every item is pretty much documented on what it does or does not do. There is a link to documentation for that section in the top right corner of every page as mentioned already.
If you want to create an actual TOC and docs for every section - you are more than welcome to do that. Email a mod and they can create an account, and give you write permission to the wiki. Got mine in less than a day when I requested it. And away you go with your 20+ years of writing tech documentation.. Will be a great help to the pfsense user community that has seemed too have a real problem figuring out what stuff does for all this time without it ;)
Looking forward to proofing your wiki pages on documentation!! You can do that for FREE btw ;)
-
It's pretty much universally recognised that opensource software is generally lacking in the documentation department for any number of reasons. pfSense seems substantially above the curve on this IMHO. However you will be aware as a technical writer that once you understand enough about a subject to be able to write the docs it often hard to see things from the point of view of someone completely new to it. I have nothing but impressed by the official book everytime I've referenced it. I can see it must have taken Chris and Jim many, many hours and their time is valuable.
I first installed pfSense using only the docs wiki and various 3rd party instructions. There are quite a few video walk-throughs on Youtube for example. There is also http://pfsensesetup.com/ which has fairly good walk-throughs of much of pfSense though I have no idea who the author is. I assume he was someone like yourself who tried pfSense, found the documentation lacking and set out to improve things.Steve
-
I've always been one to try and figure it out on my own first. If that doesn't pan out like I need it to, I will definitely reach out for help. The problem I'm facing with pfSense is that 2.1.5 has a lot of pages in it that don't correspond to the HOWTO's and such that have been posted.
With regard to whether I've even looked at the GUI, yes. I've installed the product from scratch a few times and attempted to set up Squid and SquidGuard. The resultant mess, because there's no documentation or proper guidance that I can find, is a non-working system that requires a re-install because packages won't uninstall properly.
I understand the concept of being so familiar with the process that you miss stuff when documenting it, but I have done a LOT of consulting work where my deliverable was documentation that the customer would use to build the systems themselves. So, I'm quite familiar with how to ensure that the docs are accurate.
-
With regard to whether I've even looked at the GUI, yes. I've installed the product from scratch a few times and attempted to set up Squid and SquidGuard. The resultant mess, because there's no documentation or proper guidance that I can find, is a non-working system that requires a re-install because packages won't uninstall properly.
Packages uninstall fine in general, the issues that were inherent in the old package system pre-2.1x were solved with the change to PBIs in 2.1 and newer.
I have done a LOT of consulting work where my deliverable was documentation that the customer would use to build the systems themselves. So, I'm quite familiar with how to ensure that the docs are accurate.
That's exactly what we do as part of our professional services. That tends to be very environment-specific, where general purpose documentation (largely our book at this point) fills the gaps.
Where your complaint in that area resides isn't in official sources, rather community-contributed content that's of varying quality, completeness and age.
The problem I'm facing with pfSense is that 2.1.5 has a lot of pages in it that don't correspond to the HOWTO's and such that have been posted.
That's the nature of anything with a project that's existed for a decade. Our own sites should do a better job there in either clearly marking outdated content (talking doc.pfsense.org largely), or maybe just removing things that aren't current. Some of it just needs some updates. It's an ongoing work in progress, something I'm working on right now actually.
I'm working on making sure we have adequate installation and introductory level documentation freely available. At this point, I would say we don't. The only place we have a well-documented "out of the box" experience today is with the hardware we sell, for which quick start guides are available.
-
@cmb:
Packages uninstall fine in general, the issues that were inherent in the old package system pre-2.1x were solved with the change to PBIs in 2.1 and newer.
No matter what I tried, I could not figure out how to get Squid and SquidGuard to uninstall so that I could reinstall them. The system kept hanging. From what I could discern, it was likely related to some sort of dependency order or something. And, I can't tell whether the packages in pfSense have dependency checking or not (it seems, at first blush, that they do not since you can install squidguard without squid).
@cmb:
That's the nature of anything with a project that's existed for a decade. Our own sites should do a better job there in either clearly marking outdated content (talking doc.pfsense.org largely), or maybe just removing things that aren't current. Some of it just needs some updates. It's an ongoing work in progress, something I'm working on right now actually.
I'm working on making sure we have adequate installation and introductory level documentation freely available. At this point, I would say we don't. The only place we have a well-documented "out of the box" experience today is with the hardware we sell, for which quick start guides are available.
Quite honestly, I would expect that a lot more categorization and such of docs would be in place with a project that's been around for ten years. And, maybe the big gap is that docs and such simply aren't broken down into version-specific areas. While general installation information seems "good enough", it leaves a user with only basic functionality if there isn't any reference information to validate how to enable the additional functions properly. Maybe instead of selling a book to understand how to use the product, certain features should be licensed. Software license revenue is repeating, item sales are singular. Personally, I'm unlikely to buy a book in order to use a product when there are plenty of competing products that don't require me to buy a book.
I have 20 years of experience with Linux and Unix systems of all kinds. I'm not terribly interested in "reverse engineering" the processes that are used in pfSense so that I can understand how to locate configuration files, control scripts / daemons, logs, and the like. If I can't quickly find the information on line of things like how to install and configure a package like squidguard, I'll move on to the next product out there. And, at this point, I'm leaning very heavily toward just going back to a custom, slim OpenSUSE install with Squid, SquidGuard, transparent proxying, iptables firewalling, and wondershaper. It covers 85% of what I want, and 100% of what I need. One of the things I "want" is a purpose-built distro that focuses on home firewalling and content control to keep the kids safe. That way, I don't have to worry about maintaining individual packages for the different pieces.
-
Now that we have gotten past understanding that you are annoyed with documentation…
What are you trying to accomplish and what isn't working?
-
Now that we have gotten past understanding that you are annoyed with documentation…
What are you trying to accomplish and what isn't working?
How do I configure Captive Portal? What packages are required? What additional systems might be required?
How do I install and configure Squid in conjunction with SquidGuard? What versions work properly together? Can I leverage any of the black lists that are out there for either in conjunction with the basic configuration?
How do I configure QoS to reserve bandwidth for VoIP services?
How can I configure pfSense to only allow my proxy server to access the Internet (except for HTTPS/SSL - 443)?
How do I configure reverse proxy for web content that I server from different internal servers?
How do I disable SSL3 and require TLS 1.0 instead?
-
If you take those questions and post them in a new thread, I bet they will all be answered with either a new reply or a link to an existing thread that outlines it.
All the things you have asked about have been answered many times over, so I'm sure you will get a relevant reply quickly.
-
If you take those questions and post them in a new thread, I bet they will all be answered with either a new reply or a link to an existing thread that outlines it.
All the things you have asked about have been answered many times over, so I'm sure you will get a relevant reply quickly.
I've looked.. Anything existing that I've found deals with prior versions, isn't solved, or is part of a larger total installation (where Squid is being used only because it's required by additional items like Diladele).
Further, I -have- posted looking for help and haven't gotten what I've requested. That isn't to say that I have gotten decent comments and such, but no one has been able to actually answer my questions.
-
So now all you're going to do is whine?
-
So now all you're going to do is whine?
I think he's trying to volunteer to help update the docs.
-
So now all you're going to do is whine?
I'm not whining at all. I'm pointing out that there's a massive gap between the documentation and the product. I'd be happy to try and help close that, even if it were just a little bit, if anyone at all out there could point me to some legitimate, accurate documentation for 2.1.5.
But, if you prefer to take it as whining, maybe you'd like to fix the docs instead?
-
legitimate, accurate documentation for 2.1.5.
You know there's a book right?
It is not uncommon to charge a pretty penny for a fantastic book on an open source project. Exim is one such example. Yes, online docs exist. The book is better. pfSense is another, though the printed version will probably be cheaper than a Gold subscription. (Zero affiliation other than being a gold member, btw.)
What you're proposing is a catch22 - point me at the legitimate, accurate documentation for 2.1.5 so I can help create legitimate, accurate documentation for 2.1.5. If the documentation existed to your liking, you would have nothing to do.
I'm not whining at all.
"Further, I -have- posted looking for help and haven't gotten what I've requested."
"But I was going into Tosche Station to pick up some power converters!"
But, if you prefer to take it as whining, maybe you'd like to fix the docs instead?
I don't find them as deficient as you do. Captive Portal is not hard to configure, for example. The tone of this entire thread has left me with zero desire to help you. Maybe the threads you say you started asking all these unanswered questions had the same effect on others. Considering your litany of questions, it seems $99 for the book would be well worth the money.
-
To be fair the book is not really an option for someone experimenting with various router/firewall projects. The fact that Chris has said he is releasing the introduction and installation chapters for free should significantly address this.
Steve
-
"But I was going into Tosche Station to pick up some power converters!"
What?
Your "assistance" is exactly the sort of help I've been getting all through here. You haven't read the whole post (or you didn't bother to take the time to understand it) and you're just throwing out the same knee-jerk reaction you give to everyone know that "whines" that the docs are poor.
On line docs are good and the book is better. I'm all for that. Where's the on line docs? They're essentially non-existent for 2.1.5. The fact that everyone keeps referring to the book as "the" source for docs reconfirms this.
-
To be fair the book is not really an option for someone experimenting with various router/firewall projects. The fact that Chris has said he is releasing the introduction and installation chapters for free should significantly address this.
Steve
Steve,
This is very true. I want to understand this project before I commit to it all around. The fact that I can't accurately set up my instance of pfSense to test the things that are important to me pushes this project way down to the bottom of the list of contenders. And, the fact that I'm -still- here trying to get help should demonstrate that I really do want to try it.
-
See if any of this answers some of your questions.
https://www.youtube.com/channel/UCrLC48qoJygdQOmgzmYVKBg/videos
https://www.youtube.com/watch?v=czU56xmJAmE
http://pfsensesetup.com/web-filtering-with-squidguard-part-one/
https://www.youtube.com/watch?v=s6BDVzTcAnw
https://doc.pfsense.org/index.php/Traffic_Shaping_Guide
https://www.youtube.com/watch?v=xUnJs5XP1y0
http://pfsensesetup.com/qos-management-using-the-traffic-shaper-wizard/
http://blogs.technet.com/b/nexthop/archive/2014/04/07/configuring-pfsense-as-a-reverse-proxy-for-lync-web-services.aspx
http://pfsensesetup.com/reverse-proxy-services-with-varnish-part-one/
https://forum.pfsense.org/index.php?topic=82914.0
http://www.astiostech.com/blog/?p=100
Not complete list - I'm sure there is more.
-
Where's the on line docs? They're essentially non-existent for 2.1.5. The fact that everyone keeps referring to the book as "the" source for docs reconfirms this.
It is, after all, called "The Definitive Guide."
You have, today, the documentation you have, not the documentation you want. That is not going to change today. Certain deficiencies have been acknowledged by those in the best position to correct them. I don't know what else you want. Post a thread, ask your question. Don't use 2.1.5 in your searches, use 2.1.
-
kejianshi
Thank you for posting some links. I don't understand why there were links to POODLE discussions… ???
As far as answering questions, yes... The answer is: There are no good docs available for 2.1.5 that a new user has access to for testing purposes. I don't watch videos for help with installations, and all of the other "docs" were outdated and/or don't actually take you through the process of package installation (this is the single biggest issue I have with Squid and SquidGuard).
So, I guess it's settled for me... Back to an OpenSUSE build with manual installation and configuration of all of the packages. It will take me longer, but it's 100% rock solid and is something that I've been doing for almost a decade. So, I won't be learning a new system after all.
-
Poodle - because poodle is an ssl3 issue and the cure is to use tls?
