OpenBSD Journal

PF documentation?

Contributed by jose on from the assistance dept.

waldo writes:
"There's been quite a few neat features added to PF recently, but there's no good documentation that says what these commands do and how to use them. the HOWTO ( http://www.inebriated.demon.nl/pf-howto) hasn't been updated in almost a year, and the OpenBSD FAQ ( http://www.openbsd.org/faq/faq6.html#6.2) covers just the basics.

Anybody have a good reference for all the new bells and whistles in PF?"

There was recently a call for testers in PF and ALTQ as well as documenters for the new features. 3.3 is coming up very soon, so someone should step up and contribute some documentation. Will it be you?

(Comments are closed)

Comments

  1. By Anonymous Coward () on

    I'd love to see some newer & better PF docs...

    BTW, when is 3.3 due, roughly?

    Comments

    1. By nathan milford () on

      6 months since 3.2 was released... roughly.

      Comments

      1. By Anonymous Coward () on

        Damn, another 3 months.. :(

        Comments

        1. By sickofthesameoldquestions () on

          http://www.openbsd.org/faq/faq1.html#Next

          Comments

          1. By Anonymous Coward () on

            man groff

  2. By Anonymous Coward () on

    Read it.

    Comments

    1. By Noob () on

      At first I was thinking "Hey I'd love to see new docs!" but your right, everyone can just look at the code to really see what is going on. ;-)

      I do really enjoy all the work put into online OpenBSD documentation though too. I think it's the best I've seen. Good Job!

      Comments

      1. By Anonymous Coward () on

        Docs are a good read, and source isn't too bad either...

      2. By James () on

        Not everyone has time to do that. We all wish we did, but unfortunately we don't. Docs would be a great hand and there really isn't any point in alienating people who aren't good coders or may not even know how to read c when the goal is internet security. Help everyone use more secure os's do the things they need with good docs.

        Comments

        1. By Anonymous Coward () on

          Not everyone has the time to write the docs for people who don't have time to use the existing resources. Help yourself and quit complaining.

          Comments

          1. By Justin () on

            quit complaining?!?!? I have not seen any complaints. I see people talking about how it would be nice to have docs especially for those of us who are not C programmers. Not everyone who uses a computer is a programmer. System admins, for example, might know how to use a system and configure it but not know how to modify the kernel sources for some special task, or how to read the pf code to realize the proper syntax of the config file. Even the point of the original article is just mentioning OpenBSD usually has extremely good documentation and we just need some(one||people) to step up and do it for all the new goodies in pf.

            Comments

            1. By Anonymous Coward () on

              I am a sysadmin and I program in several languages.
              Most other (good) sysadmins I know also code. Some people know how to help themselves while others need/want to have their hand held and be spoon feed.

              Comments

              1. By Anonymous Coward () on

                Most other (good) sysadmins I know also code. Some people know how to help themselves while others need/want to have their hand held and be spoon feed.

                not only is it your opinion, but it's also recommended by SAGE that a necessary requirement for senior system administrators is the "Ability to program in an administrative language (Tk, Perl, VBScript, a shell), to port C programs from one platform to another, and to write small C or C# programs."

                source: http://sageweb.sage.org/resources/publications/8_jobs/core.html

                Comments

                1. By Jeffrey () on

                  Oooohhhh, very interesting... =)
                  Looks like I'm halfway there! Yay!
                  ... and C is getting easier all the time ...

                  I figure if I don't learn something (whatever that something might be) each and every day then that day has been mostly wasted.

                  Comments

                  1. By Anonymous Coward () on

                    Amen.

    2. By waldo () waldo@iastate.edu on mailto:waldo@iastate.edu

      > Docs are a good read,

      as i mentioned in my post, the docs cover only the basics. i want information on the newer/more advanced commands.

      > and source isn't too bad either..

      i've looked at the source and didn't see anything useful. which file, exactly?


      and on an off-topic note, i love OpenBSD, i think it's a great operating system, but i can /not/ stand the attitude of many of it's users. Maybe it's rubbed off from Mr. DeRaadt, but flaming anybody that asks a question (on any topic, not just this one) is NOT a way to encourage anyone to use the OS you clearly think is so neato, or increase the general pleasantness of the human population. it annoys me. knock it off. you are not (surprising, i know) holier than everybody else. come down off the pedestal. it's kinda fun down here.

      Comments

      1. By A. Friend () on

        and while we're at it...stop using these posts to tell people to buy cd's. we know already that this is how a large portion of the funding is received. we all know you, yes YOU, only post those comments to let us know that you bought the cd and have dislocated your arm trying to pat yourself on the back.

      2. By jolan () on

        The man pages have excellent, up-to-date information.

        http://www.openbsd.org/cgi-bin/man.cgi?query=pf.conf&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html

        http://www.openbsd.org/cgi-bin/man.cgi?query=pfctl&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html

        A couple of pointers:

        1) The FAQ tracks -stable. Don't expect anything there on upcoming features.

        2) If you want to know what's new in pf, read:
        http://www.openbsd.org/plus.html

        3) Don't expect other sources to document stuff implemented in -current. Things change very rapidly. There's little point in documenting something that could be removed or changed dramatically the next day.

        As for the attitude stuff, I thought your question could have been answered with a little more effort on your part. It would seem other people did too, although they couldn't express it as eloquently.

      3. By Anonymous Coward () on

        People are not flamed for just asking questions. They are flamed for asking questions that have been answered 1000 times before. The answer is either in the FAQ, the mailing list achieves, or easily found by Google.


        Lets not forget reading or searching the man pages, which doesn't seem to happen as often as it should.

        We need to encourage people to RTFM.


        Why:


        1) You will find the answer faster

        2) You will not waste anyone elses time

        3) You might learn something new in the process

        4) You might find a problem with the documentation, which you can report to improve the system for everyone

        5) The mailing lists traffic will be reduced and consist of more interesting and original questions

        6) All this can only lead to becoming a more efficient system administrator.

        Comments

        1. By kremlyn () on

          Not everyone has the skill to derive how a program works from reading source code.

          //kremlyn

          Comments

          1. By Lars Hansson () on

            Which part of Google, mail archives, man pages and FAQ didnt you understand?

        2. By Wu () wu@interlogical.com on mailto:wu@interlogical.com

          man pf.conf(5) and the default /etc/pf.conf that comes with -current versions have a lot of info about how to set up pf properly.
          In my oppinion, the problem is those people to want their problem to been solved before, they it is better (and of course easy) to copy configurations from other people instead of making their own...

          pf is amazing, but of course, you need to learn how to use it. To copy other people configs is not the way (as i had say, that's my oppinion).

          Comments

          1. By Wu () wu@interlogical.com on mailto:wu@interlogical.com

            ufff, excuse my english... must read the comment one more time before post it next time... sorry.

        3. By Anonymous Coward () on

          We need to encourage people to RTFM.

          Why:

          [ lots of great reasons ]

          plus, if you read the manpages/FAQ you'll be getting the information from official sources. what if malevolent users tell newbies: "why yes, just add 'pass in quick all' at the top and it will solve all your problems" ? The same applies to uninformed users who think they know the answer.

          also the official sources are continually picked through for exactness. my reply, sent out while at work in the middle of 20 other things going on, might not be as accurate or well-worded as the FAQ/manpage. some of us tell ppl RTFM not b/c our cock is bigger than yours, but b/c we recognize we wont be able to explain any better than the faq/manpage already does.

        4. By Anonymous Coward () on

          First, it would take many dedicated tech writers to keep up to Daniel's work. Kudos...

          In no relation to the OpenBSD newsgroup, there is a guy in the bbq newsgroup that posts the same message every couple of weeks. The message is "where to find the bbq faq" and it points newbies to the reference.
          Perhaps I'll do this. A few links to some well known places to find OpenBSD information. Google will let you know of pages with the content you are looking for, but doesn't address the quaility of it. Newbie-madness at the newgroup may be frustrating, but that is not the intention of the poster.

        5. By Anonymous Coward () on

          if the question has been answered 1000 times before, shouldn't answering it be easy? a simple ``click this link'' ... have fun. not ``here's 1000 reasons why you're an asshole''

          Comments

          1. By Anonymous Coward () on

            I agree wholeheartedly to the previous post! I can understand some annoyance at asking teh same questions, but sometimes it isn't obvious what to look for and where to look for it. If people have enough time to tell someone they're a stupid lazy moron and should read the docs, they should have enough time to include a relevant link to the information in question.

            there are alot of obsd people who reply to a question with "why would you want to do that, do it my way its better, or rtfa" why bother posting a reply if you're not going to help in any way?

          2. By Lars Hansson () on

            If it has been asked, and answered, 1000 times before it is usually documented somewhere. Come on people, Google isnt that difficult to use.
            The fact that you asked it one more time clearly shows you probably didnt even try to find the answer by yourself.

    3. By Anonymous Coward () on


      > You have the source.
      > by Anonymous Coward on Thursday, January 30
      > @03:23AM

      > Read it.


      Oh yeah, thats right. Lets skip all the man pages, they are only a waste of space (and time) anyways. All examples, and other documentation can be deleted as well.


      Sorry, but I agree - judging from some answers (like this one) I guess the average OpenBSD users age is almost thirteen.

      Comments

      1. By James () on

        I'm changing that to say the average OpenBSD user's mental age is thirteen. Clearly some people are physically older. :)

        Comments

        1. By Jeffrey () on

          Well, you might also consider that the words spoken by an "Anonymous Coward" are virtually worthless. A person might as well not say anything if it is to be anonymous. Words have more effect when a name is attached IMHO.

          Maybe if anonymous postings here were not possible there would be less garbage showing up ;)

    4. By Anonymous Coward () on

      Why? I'm not a hacker.

    5. By Anonymous Coward () on

      > Read it.


      Well, you could carry that suggestion for all of OpenBSD, and conclude that there needs to be no man pages or other documentation because anyone can (and should) read the source.

      Fortunately, the people who contribute to the project have a more enlightened viewpoint, and create some of the best and thorough OS documentation around.

      All that this thread asks is that the pf documentation catch up with the pf enhancements.

  3. By Anonymous Coward () on

    My 3.2 poster just got framed and hung up in my office...

  4. By Anonymous Coward () on

    Have you tried reading the updated man page from current?

    http://www.openbsd.org/cgi-bin/cvsweb/src/share/man/man5/pf.conf.5

    Comments

    1. By Anonymous Coward () on

      Yes, I have. But it still has some info missing. If it doesn't turn up till I have some spare time, I will have a look at that...

  5. By Anonymous Coward () on

    (This was posted several layers deep, but everyone should read this.)

    The man pages have excellent, up-to-date information.

    http://www.openbsd.org/cgi-bin/man.cgi?query=pf.conf&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html

    http://www.openbsd.org/cgi-bin/man.cgi?query=pfctl&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html

    A couple of pointers:

    1) The FAQ tracks -stable. Don't expect anything there on upcoming features.

    2) If you want to know what's new in pf, read:
    http://www.openbsd.org/plus.html

    3) Don't expect other sources to document stuff implemented in -current. Things change very rapidly. There's little point in documenting something that could be removed or changed dramatically the next day.

    As for the attitude stuff, I thought your question could have been answered with a little more effort on your part. It would seem other people did too, although they couldn't express it as eloquently.

    Comments

    1. By jose () on http://www.monkey.org/~jose/

      yes, jolan is right. however, rather than scrambling to write the FAQ entries the week that 3.3 is released, why not start work on docs now? they can be edited to keep up with PF changes more easily than they can be crafted from scratch.

      also, docs assist people in testing stuff. that's always good.

    2. By waldo () waldo@iastate.edu on mailto:waldo@iastate.edu

      oo. i didn't know -current was in the web manpages. i also didn't know about /plus.html

      however, to those of you that tell me to read the code and google for it, i've tried both, and not met with much success. since you are clearly superior to me (i'm just a n00b after all), where in the code should i be looking? what's the proper google query? you're so good it ought not take you any more time than the time you spent making your asinine RTFM posts.

  6. By Jim () on

    I read the manpage, and I just can't figure out what queuing strategy is right for me. All I want to do is throttle the downstream to a certain bitrate and throttle the upstream to a different (lower) bitrate. Kind of like this does for linux: http://lartc.org/wondershaper/

    Anybody know a good ALTQ tutorial? Or does anyone know what queuing strategy I should be using? If I knew which strategy to use, I can probably figure it out from there.

    Comments

    1. By qalt () on

      wfq is simplest to configure, a working altq.conf(5) here:

      interface de0 bandwidth 100M wfq hash full

      and you have lots of time to read rest of manual, and update your config as necessary

      Comments

      1. By Jim () on

        Is there a way for me to specify a different bitrate for upstream and downstream?

        Comments

        1. By qalt () on

          basically input is called in this name because you cannot control it like sucking more bits in or pushing some back

          Comments

          1. By Anonymous Coward () on

            Sorry, I don't fully understand that sentence.

            Are you saying that I can't throttle upstream and downstream seperately using ALTQ?

            Comments

            1. By Anonymous Coward () on

              You can't throttle downstream, as it's the sender that decides the packet rate. You could drop packets, but if you tried to just throttle (delay) them, you'd run out of cache memory very quickly.

              Comments

              1. By Anonymous Coward () on

                Look, I don't know exactly how it works, but this:
                http://lartc.org/wondershaper/
                works very well in linux for throttling upstream and downstream independantly.

                Because of the nature of ADSL, when a download or upload that maxes out the bandwidth happens, it severly hurts latencies on all connections over that link.

                When the link is throttled to not allow the maxing out either the upstream or downstream connection, the ADSL modem does not spend seconds at a time on one upstream or downstream transfer, and this allows good interactivity on ssh and telnet connections.

                Since I use OpenBSD for my home router/gateway/internet server, I use the throttling mechanism in ProFTPD, and recommend that my friends use my ftp server for downloading from me.

                If people decide to use scp for transferring files, however, it will max out my upstream (at 16 KB/s), and my latencies will be horrible for ssh, web browsing, and a number of other things. Similarly, if I am doing a huge download that maxes out my downstream (at 150 KB/s), people sshing to my box will have terrible latencies, waiting up to a few seconds for what they type to appear.

                It seems to me that if proftpd can throttle upstream and downstream seperately in userland, then there shouldn't be a problem in throttling it with ALTQ....

                So I ask again, how do I do this in OpenBSD? If ALTQ can't do it, is there something else that can?

                Comments

                1. By Anonymous Coward () on

                  Not an answer about ALTQ, but you might want to check:
                  http://www.pureftpd.org/FAQ
                  wouldn't 'FTP over SSH' fix a part of the problem? Might work with ProFTPd, too

                2. By qalt () on

                  due to nature of connection tracking, altq or pf alone will not throttle input, but after they are merged (in -current or 3.3) it will be possible.

                  In the meantime you can use your ftp server to limit input rate (proftpd does its job just fine), you may protect your upstream only with altq

                  Comments

                  1. By Anonymous Coward () on

                    Good to know! thanks.

    2. By Anonymous Coward () on

      Hoang's pf doc (muine.org down)
      by SolarfluX (solarflux@bsdvault.net) on Friday, January 31 @10:16AM
      http://bsdvault.net

      http://docs.bsdaemon.be/docs/security/openbsd-pf.txt

      Comments

      1. By Anonymous Coward () on

        Thanks, but what I'm looking for is something that will throttle incoming and outgoing speeds differently on one interface. For example, I would like to do something like this:

        interface ep0 outgoing-bandwidth 1.5M wfq
        interface ep0 incoming-bandwidth 250K wfq

        Is something like this possible using ALTQ?

        Comments

        1. By qalt () on

          incoming-bandwidth for ep0 is somewhere around 10Mbps
          seems more like duplex mismatch if you cannot get subscribed rate (or your provider will tell once you call for service)

  7. By Daniel Hartmeier () daniel@benzedrine.cx on http://www.benzedrine.cx/pf.html

    I agree that documentation can get better.

    IMO, the first priority should be the man pages. You can help us by making suggestions. What questions did come up that the man pages couldn't answer? Build a list and make sure you searched the -current man pages (through cvsweb, for instance) thoroughly first. If you found the answers by other means already, a man page diff would be great. But the questions are already helpful.

    Now, certain explanations are just too verbose for the man pages, and those would better fit into a FAQ or HOWTO style document.

    Yes, it would be great if Wouter's HOWTO would be actively maintained. Have you contacted him, and asked whether he plans to update it in the future? If he doesn't have time anymore, someone else could step up, take the latest version, and work on that. It's published under a BSD license, so you can fork it and republish modified versions. All it takes is someone with time and energy :)

    Comments

    1. By Anonymous Coward () on

      Documentation could always be better. But if everybody would follow the high standard of OpenBSD when it comes to documentation the world would be a much easier place. I setup three servers for a customer last week using RedHat Linux. They had some special needs and I had to setup a few configurations I hadn't done in quite some time. The manpages were even more terrible that I remembered. Even worse, a lot of the stuff didn't even have manpages. Ok, this doesn't have anything to do with the topic so I'm going to stop now :-).

    2. By Anonymous Coward () on

      The httpd on www.benzedrine.cx is mostly unreachable from here.

      Also, indeed, Wouter's howto is great for the basics. But it doesn't include authpf for example, nor it doesn't have a lot of new features.

    3. By Anonymous Coward () on

      >> Yes, it would be great if Wouter's HOWTO would be actively maintained. Have you contacted him, and asked whether he plans to update it in the future? <<

      yes I have contacted him. He said he has not the time to update the HOWTO.

  9. By Alex Kirk () alex@schnarff.com on http://www.schnarff.com

    While I realize this comment is coming in a bit late, I think it's still relevant.

    There's a great deal of whining going on on both sides of the "I want all the features and docs now!" and "RTFM!" debate recently, here and on misc@. This whining, while understandable from respective points of view, needs to stop. It's not constructive, but in fact destructive -- it just makes OpenBSD look bad.

    As someone who has written a decent amount of documentation for other projects, but is always eagerly awaiting whatever's new in OBSD, I feel qualified to speak for both sides. From the developer/documenter side, I say, "Chill out, guys, I work a day job *and* do this in my spare time. I'm overworked, underappreciated, and will get to it soon enough." From the user side, I say, "OK, I'll happily RTFM...just as long as I know which FM you're talking about."

    Let's all try to concentrate our energy on positive things, like asking constructive questions and giving helpful (if even one-line, one-link) answers.

  10. By Ross () on

    Having read the comments on this subject, I would just like to remind you all of something my mother used to tell me: "If you don't have anything nice to say, then shut the f**k up." When I used linux, I was absolutely disgusted with the community following. Everyone on /. seems hell bent on attacking everyone else, so they can feel like "yea, I sure showed him that I knew what's up." After being introduced to OpenBSD, I was pleased that the community seemed to show a small amount of maturity, but I stand corrected. Somehow, many of you have the misconception that attacking other people will make you look better or seem knowledgeable. Oh, a newbie doesn't know where proper documentation can be found? Let's blast him!! That'll show everyone how awesoeme I am. RTFM!! RTFM!! Or, better yet, RTFS!!!

    Grow up.

    Comments

    1. By somejackass () on

      What about RTFB? That's the best one, by far.

  11. By Henning Brauer () henning@openbsd.org on mailto:henning@openbsd.org

    we are indeed looking for help with the documentation. especially, a lot of information that already is in the old manpages needs to be merged into pf.conf(5); some stuff from altq(9) for example. that isn't _too_ hard.
    anyone willing to help - feel free to contact me in private mail.

Latest Articles

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]