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:Installation

    though 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.



  • @ember1205:

    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.


  • Rebel Alliance Global Moderator

    ""FAQs" and "HOWTOs" don't cut it."

    Says who?

    Here is install doc
    https://doc.pfsense.org/index.php/Installing_pfSense

    Could 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 ;)



  • Netgate Administrator

    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.



  • @ember1205:

    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.

    @ember1205:

    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.

    @ember1205:

    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?



  • @kejianshi:

    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.



  • @kejianshi:

    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.


  • Netgate

    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.



  • @Derelict:

    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?


  • Netgate

    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.


  • Netgate Administrator

    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



  • @Derelict:

    "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.



  • @stephenw10:

    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.




  • Netgate

    @ember1205:

    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?


  • Netgate Administrator

    I'm sorry things turned out like this for you.
    I have a feeling that much of this (and no doubt similar experiences other have) is down to managing expectations. pfSense has a very wide user base. It is used by networking noobs as well as seasoned firewall professionals. It can be used in place of the cheapest SOHO router or an incredibly expensive commercial firewall product. Depending where you are coming from on that spectrum your expectations are going to vary massively. Personally I came from Smoothwall via IPCop and don't remember having much difficulty getting pfSense going or struggling to find the documentation to do so. Of course as I said earlier it's hard to remember not knowing something after you become sufficiently familiar with it.  ;)

    I don't think anyone here would disagree that improving/updating the docs would be a good thing.

    Steve



  • Enjoy the linux release.



  • @ember1205:

    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.

    Yeah, we could, say, go the Cisco route. With the big bucks you pay for Cisco ASAs, surely they make flawless, perfectly comprehensive documentation available, right? No one would even bother writing or buying a book about a Cisco ASA, right?

    Go search Amazon books for Cisco ASA. 122 books matching Cisco ASA. Into double digits recent books where the ASA is the primary topic. Oh…maybe not such a brilliant plan.

    Show me one comparable solution that's free and has better documentation freely available. AFAIK, there isn't one. We have a good deal of up-to-date information available, and a whole lot more that's a bit dated but still easy to follow and correct on 2.2 today. You're paying somewhere.

    @ember1205:

    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.

    I don't get what's so difficult - we're extremely widely used because you don't need to "reverse engineer" or "forward engineer" all the intricacies of the underlying components. The system is largely self-documented with descriptive text on every page of the web interface. Anyone with experience with commercial-grade firewalls tends to pick things up quickly. Those who haven't dealt with anything more complex than a Linksys have a learning curve, but that'd be true regardless of what comparable-grade product you threw in front of them.

    If you know enough to manually configure these things, you can surely figure out the web interface. Any question you might have has almost certainly been asked and answered before, likely several times - there are over 437,000 posts here today. Google site:forum.pfsense.org or site:pfsense.org to catch all our sites.


  • Netgate

    Dude was an iptables troll, dare I say dick.  I've been watching for the last couple days and I have seen a few questions answered with links into the doc wiki.  No, they weren't current with 2.1.5 but were more than enough information to get the config correct.

    Nothing could get me to migrate from pf to iptables.  Nothing.



  • @Derelict:

    Nothing could get me to migrate from pf to iptables.  Nothing.

    that's it!



  • Derelict - Not necessarily.  Some people, even with a fully complete manual in hand or a set of instructions just can't get things working.

    Maybe he is like that?

    Let him enjoy his SUSE Firewall/UTM (If there is such a thing)


  • Rebel Alliance Developer Netgate

    The doc wiki does need some updating but anyone who claims it lacks categorization or lacks in size is definitely trolling.

    https://doc.pfsense.org/index.php/Special:Categories

    98(!) different categories that can be used to lookup docs, and 490 different articles in total.

    We are working to update much of the old stuff and add in some new things, but the book will always be the preferred reference. Some things lend themselves better to a book style, others lend themselves better to a wiki style. The two will always complement each other.

    Some recent big updates:
    https://doc.pfsense.org/index.php/VPN_Capability_OpenVPN - OpenVPN Remote Access How-To updated for 2.1.x
    https://doc.pfsense.org/index.php/Writing_Disk_Images - A complete rewrite of the instructions for writing disk images (e.g. memstick and NanoBSD)
    https://doc.pfsense.org/index.php/Low_Throughput_Troubleshooting - An entirely new article on troubleshooting slow connections
    https://doc.pfsense.org/index.php/Asymmetric_Routing_and_Firewall_Rules - A new article expanding info on dealing with asymmetric routing
    https://doc.pfsense.org/index.php/Forcing_Interface_Speed_or_Duplex_Settings - Removing cruft from 1.2.x and bringing the info current
    https://doc.pfsense.org/index.php/Filter_Log_Format_for_pfSense_2.2 - A doc detailing the precise format of the raw firewall log on 2.2

    And that's just a few of ones that I've created or updated in the last month, not counting all the updates by cmb plus a few community contributors.


  • Netgate Administrator

    @Derelict:

    Dude was an iptables troll, dare I say dick.

    I disagree. If you look at his other posts he made useful contributions to other threads. He expected a high level of documentation and for whatever reason he didn't find what he was looking for.

    Steve



  • @stephenw10:

    I disagree. If you look at his other posts he made useful contributions to other threads. He expected a high level of documentation and for whatever reason he didn't find what he was looking for.

    Steve

    With all due respect, I concur with Derelict. In this particular topic, he was being a dick.
    He states he's been doing this for 20 years, but he can't figure out the basics of installation and use without pristine docs? Then he whines because no one held his hand configuring a bunch of advanced stuff? Wants to do squid, squidguard with custom blacklists, captive portal, qos for voip, reverse proxy etc, but can't buy the book or take the time to learn?  I suppose if I went to the opensuse site there would be a step by step walkthrough showing me how to do all of that stuff with the current version…
    Sorry for the rant, but the guys attitude rubbed me the wrong way.



  • derelict and dotdash can both go get over themselves. I was not being a troll or attempting to "be a dick". Well, at least not dotdash - derelict deserved the comment I made directly to him. Sorry that the two of you have less than stellar capabilities of understanding how to deal with the public and with potential customers.

    The pfSense documentation is sorely lacking for 2.1.5. Period. I have raised up numerous times a couple of issues that I encountered with things like understanding dependencies for packages, uninstallation of packages failing with no way to seemingly correct it, and a got zero information from everyone that just keeps touting how "98 categories" of areas to look in the docs is supposed to be the end-all, be-all of documentation.

    I am NOT familiar with BSD in any of its forms directly. I don't know the package model, I don't know if the filesystem follows LSB, I don't know who creates or maintains the individual packages, whether THEY conform to LSB, and there is NO DOCUMENTATION to take a new user through the full installation and configuration of the product.

    Could I reverse engineer it at the file level? Sure. Will it take me a lot of time? Yep. See comments above.

    The problem is that I've been snake-bitten plenty of times before by managing things directly at the file level and then having that break the web interface controls. Clearly, a lot of time has gone into the admin interface to abstract things away from what's going on under the hood. If I start rooting around down at the file level, my gut tells me I'm going to break the web interface controls for at least one particular item, and that defeats the purpose of looking for a product that has a great web interface.

    With regard to the Cisco example: You apparently missed comments that I have made where I directly stated that having good online docs and a book that's even better is something I would be all for. I used some really good on line documents a long time ago to get my postfix mail servers configured exactly the way that I wanted them. Then, I went out and learned a ton more from one of the great books that was available.

    Yeah… You've got a great community here. On top of having little in the way of documentation for the current version of the product, plenty of people to tell a potential user that they don't know what they're talking about, don't have a clue, and then start calling them names. Kudos to not just the members, but the admins that allow (and dare I say even encourage?) this sort of behavior.



  • All I can say is that when I first looked at pfsense I was also not familiar with it, but somehow was able to make everything I need work.

    The feeling I get is as if you are a windows user taking his first look at linux and being upset that its not windows.

    Don't know what to say except that if your point is that there is a learning curve for advanced features, you are right.

    I'm sure its the same with all projects and products.


  • Rebel Alliance Developer Netgate

    True, the wiki is not the end-all, be-all of documentation, and I didn't state that it was. It doesn't claim to be. But to say there is a lack of documentation is demonstrably incorrect. Between the wiki and book and other resources inside the GUI and around the forum there is a lot of documentation.

    It may not have been the exact documents you were looking for, but plenty of documentation does exist.

    The reason you're not getting info on how to fix your package issues here in this thread is that is not the topic of this thread and it's also not in the packages forum. Post a single question in its own thread in the right place and you'll probably get a relevant response.