Where is the documentation?
-
Is there an actual set of documents somewhere? "FAQs" and "HOWTOs" don't cut it. I'm looking for something that actually takes you through the installation, partitioning the disk, setting the base configuration, and then walks you through the pages of the admin interface. Since there is zero context-sensitive help in the admin pages themselves, it has to be documented somewhere…
-
There are books published by a team of knowledgeable people that can be purchased.
I've not read it, but I would assume they are experts and the book is authoritative and fairly complete.
Its not free, as far as I know.
Referenced at the bottom of this page:
https://www.pfsense.org/get-support/
-
Every page in the web interface has a help button in the top right that links to relevant documentation.
Installation-related things in:
https://doc.pfsense.org/index.php/Category:Installationthough I'm about to make the introductory and installation portion of the book freely-available and will be updating a lot of that in the process, working on that this week.
The basics tend to be well covered at doc.pfsense.org. Anything beyond that, your best bet is getting a gold subscription and checking out the latest revision of our official book. It's around 700 pages and covers everything in the base system in good depth.
-
So, the best way to leverage free software is to buy something?
For the record: Context-sensitive help doesn't work. I've yet to have it bring me to anything even remotely helpful. And, I should be able to access the documentation much more easily -prior- to having it installed.
If you need someone to help proof the documentation before it's published, I'm game. I've been in technology for two decades plus and am quite adept with technical writing.
-
So, the best way to leverage free software is to buy something?
No such thing as a free lunch. Everything has a cost of some sort or another. Whether it be monetary, required knowledge to make effective use of, self support, contribution (monetary or otherwise) to make better, etc.
You know that "free" gift people get for signing up for xyz product or service. It's not free. It was "sold" (bartered for) to them for personal information. But I digress… And the value of the information obtained is not taxed. But that's yet another rat/guberment loop hole.
-
I understand… That's a big part of why I offered to help with the documentation.
The other side of this, though, is the fact that pfSense does have a commercial side to it. It is reasonably normal to produce some documentation to go along with your product if you want other people to try and use it - paid, free, or otherwise.
-
You can either the buy the book from Amazon, or get a Gold sub and download a updated copy. Those are your only two choices. I managed to download, install and configure pfSense without the book; so did many, many others. If there is something you don't understand, ask in the forum.
-
I have built my pfSense appliance from scratch, installed pfSense only reading Wiki and this forum, it has been 3 month of preparation (I pay my bills as VP Aircraft Maintenance, I am not an IT professional).
After I realized my setup was running fine and smooth with basic config I decided to buy the Gold Membership and read the Book, I want to be more expert, just for hobby.You can make pfSense working for free (no money or near to) but you have to spend time to learn.
-
""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?