NAME

       pibruin - Classification Rule Insert Utility

SYNOPSIS

       pibruin [options] [<rules] file

DESCRIPTION

       Read  a  set  of classification rules from stdin and insert them directly into a PIB file.
       This program is an alternative to program int6krule and a companion  to  program  pibrump.
       Although  it  is  possible  to  ruin a PIB using this command, the name is short for "rule
       insert".

       Atheros recommends that users validate all classification rule sets used with this program
       before  inserting  them  into  an  operational PIB.  Individual rules may be syntactically
       valid but they can still be technically invalid or conflict with other.  This program does
       not perform any technical or cross-rule validation what-so-ever.

       Cross-rule  validation  is  normally  done  by  runtime  firmware when a rule arrives in a
       VS_CLASSIFIER management message.  This validation prevents the insertion  of  meaningless
       or  conflicting  rules  into  the PIB.  It may be possible to commit a PIB containing mis-
       configured classification rule sets thus causing the device  to  lockup  or  misbehave  on
       reboot.

       One recommended method of rule set validation is to program a device with individual rules
       using program int6krule then read the PIB and extract the rule set with  program  pibrump.
       The rule set should be valid at that point.

       This  program is part of the Qualcomm Atheros Powerline Toolkit.  See the AMP man page for
       an overview and installation instructions.

OPTIONS

       -o offset
              Specify an alternative PIB offset when inserting the classifier  block.   Customers
              should  not  use  this option.  It is provided to account for firmware changes that
              might occur in the future.  Improper use of this  option  can  render  a  PIB  file
              unrecoverable.

       -q     Suppresses progress messages.

       -v     Print additional information on stdout.

       -?,--help
              Print  program  help  summary  on  stdout.  This option takes precedence over other
              options on the command line.

       -!,--version
              Print program version information on stdout.  This  option  takes  precedence  over
              other  options  on  the command line.  Use this option when sending screen dumps to
              Atheros Technical Support so that they know exactly  which  version  of  the  Linux
              Toolkit you are using.

ARGUMENTS

       file   The  name  of a valid Atheros runtime parameter file.  The file is modified by this
              program only if the classification rule file is  syntactically  correct.   See  the
              DISCLAIMER  section  below.   No  backup  file  is created.  By convention, runtime
              parameter files have a .pib extention  but  this  program  does  not  enforce  that
              convention.  The file must exist and be a valid PIB file or errors will occur.

       rules  The  name  of  a  valid  classifier  rule  file.   The file is not modified by this
              program.  Classifier rule files are standard ASCII text and may be created manually
              using  a normal text editor or may be generated automatically using another program
              such as pubrump.  By convention, classifier rule files have a ..qos  extension  but
              this  program does not enforce that convention.  If this file is omitted then rules
              are read from from the console, one rule per line.

DISCLAIMER

       PIB file structure  and  content  is  proprietary  to  Qualcomm  Atheros,  Ocala  FL  USA.
       Consequently, public information is not available.  Qualcomm Atheros reserves the right to
       change the file structure or content in future firmware releases without any obligation to
       notify or compensate users of this program.

       This  program  is  provided for convenience only.  It is possible to insert meaningless or
       confilicting rule sets into a PIB with this program because approved cross-rule validation
       is  not  performed.   Incorrect  application  of perfectly valid rules may render a device
       ineffective or unusable on  a  powerline  network.   Program  users  are  responsible  for
       ensuring  that  their  rule  sets are verified by other means before using this program to
       insert them into an operational PIB file.

EXAMPLES

       The following is an example set of classification rules stored  in  file  rules.txt.   The
       file  contains  5  rules,  one  rule  per  line.   The rules are identical to command line
       arguments expected by program int6krule and one could type  them,  one  at  a  time,  into
       int6krule  and  wait  for the device to reset each time.  Alternately, we could insert all
       the rules directly into a PIB file at once then download and commit the PIB, resulting  in
       only one reset.

          # cat rules.txt
          Cap1 any VLANID is 20 add perm
          DropRX any VLANID is 25 add perm
          StripRx any VLANID is 5 VLANID is 10 VLANID is 15 add perm
          StripRx any VLANID is 20 add perm
          Cap1 any VLANID is 5 VLANID is 10 VLANID is 15 add perm

       The  following  example  reads  file rules.txt from stdin and writes it into file def.pib.
       This may be usefule if one wanted to distribute a known set of rules  to  other  users  or
       wanted to test various combinations of rules.  Sincd rule files are

          # pibruin < rules.txt

       The  next  example  reads  classification  rules  directly from file abc.pib using program
       pibrump and writes them directly into file def.pbi using program  pibruin.   This  is  one
       means of transfering classification rules from one PIB to another.

SEE ALSO

       int6krule(7), pibrump(7)

CREDITS

        Nathaniel Houghton