Provided by: ganeti-2.16_2.16.0~rc2-1build1_all bug

Name

       gnt-filter - Ganeti job filter rule administration

Synopsis

       gnt-filter {command} [options...] [arguments...]

DESCRIPTION

       The gnt-filter command is used for managing job filter rules in the Ganeti system.  Filter
       rules are used by the Ganeti job scheduler to determine which  jobs  should  be  accepted,
       rejected, paused or rate-limited.

       Filter rules consist of the following:

       • A UUID, used to refer to existing filters.

       • A  watermark.   This  is  the  highest job id ever used, as valid in the moment when the
         filter was added or replaced.

       • A priority.  This is  a  non-negative  integer.   Filters  are  processed  in  order  of
         increasing  priority.   While  there  is a well-defined order in which rules of the same
         priority are evaluated (increasing watermark, then the UUID, are taken as tie breakers),
         it is not recommended to have rules of the same priority that overlap and have different
         actions associated.

       • A list of predicates to be matched against the job.

         A predicate is a list, with the first element being the name of the  predicate  and  the
         rest  being  parameters  suitable  for  that  predicate.   Most predicates take a single
         parameter, which is a boolean expression formulated in the of the Ganeti query language.
         The currently supported predicate names are:

         • jobid.   Only  parameter  is a boolean expression.  For this expression, there is only
           one field available, id, which represents the id the job to be filtered.  In all value
           positions,  the  string  watermark  is  replaced  by the value of the watermark of the
           filter rule.

         • opcode.  Only parameter is a boolean expression.  For this expression, OP_ID  and  all
           other  fields  present in the opcode are available.  This predicate will hold true, if
           the expression is true for at least one opcode in the job.

         • reason.  Only parameter is a boolean  expression.   For  this  expression,  the  three
           fields  source,  reason,  timestamp  of  reason  trail  entries  are  available.  This
           predicate is true, if one of the entries of one of the opcodes in this  job  satisfies
           the expression.

       • An action.  One of:

         • ACCEPT.  The job will be accepted; no further filter rules are applied.

         • PAUSE.   The  job  will  be accepted to the queue and remain there; however, it is not
           executed.  Has no effect if the job is already running.

         • REJECT.  The job is rejected.  If it is already in the queue, it will be cancelled.

         • CONTINUE.  The filtering continues processing with the next rule.  Such  a  rule  will
           never  have  any  direct  or  indirect effect, but it can serve as documentation for a
           "normally present, but currently disabled" rule.

         • RATE_LIMIT n, where n is a positive integer.  The job will be held in the queue  while
           n  or  more  jobs where this rule applies are running.  Jobs already running when this
           rule is  added  are  not  changed.   Logically,  this  rule  is  applied  job  by  job
           sequentially,  so that the number of jobs where this rule applies is limited to n once
           the jobs running at rule addition have finished.

       • A reason trail, in the same format as reason trails for job opcodes  (see  the  --reason
         option  in  ganeti(7)).   This  allows  to  find out which maintenance (or other reason)
         caused the addition of this filter rule.

COMMANDS

   ADD
       add
       [--priority=*priority*]
       [--predicates=*predicates*]
       [--action=*action*]

       Creates a new filter rule.  A UUID is automatically assigned.

       The --priority option sets the priority of the filter.   It  is  a  non-negative  integer.
       Default: 0 (the highest possible priority).

       The  --predicates option sets the predicates of the filter.  It is a list of predicates in
       the format described in the DESCRIPTION above.  Default: [] (no predicate,  filter  always
       matches).

       The  --action  option  sets  the  action  of the filter.  It is one of the strings ACCEPT,
       PAUSE, REJECT, CONTINUE, or RATE_LIMIT n (see the DESCRIPTION above).  Default: CONTINUE.

       See ganeti(7) for a description of --reason and other common options.

   REPLACE
       replace
       [--priority=*priority*]
       [--predicates=*predicates*]
       [--action=*action*]
       [--reason=*reason*]
       {filter-uuid}

       Replaces a filter rule, or creates one if it doesn't already exist.

       Accepts all options described above in ADD.

       When being replaced, the filter will be assigned an updated watermark.

       See ganeti(7) for a description of --reason and other common options.

   DELETE
       delete {filter-uuid}

       Deletes the indicated filter rule.

   LIST
       list [--no-headers] [--separator=*separator*] [-v]
       [-o [+]field,...] [filter-uuid...]

       Lists all existing filters in the cluster.  If no filter UUIDs are given, then all filters
       are included.  Otherwise, only the given filters will be listed.

       The  --no-headers  option will skip the initial header line.  The --separator option takes
       an argument which denotes what will be used between the output fields.  Both these options
       are to help scripting.

       The  -v  option  activates verbose mode, which changes the display of special field states
       (see ganeti(7)).

       The -o option takes a comma-separated list of output fields.  If the value of  the  option
       starts  with  the  character  +,  the  new fields will be added to the default list.  This
       allows to quickly see the default list plus a few other fields, instead  of  retyping  the
       entire list of fields.

       The available fields and their meaning are:

       action Action

       predicates
              Predicates

       priority
              Priority

       reason_trail
              Reason trail

       uuid   Network UUID

       watermark
              Watermark

   LIST-FIELDS
       list-fields [field...]

       List available fields for filters.

   INFO
       info [filter-uuid...]

       Displays information about a given filter.

EXAMPLES

       Draining the queue.  :

              gnt-filter add '--predicates=[["jobid", [">", "id", "watermark"]]]' --action=REJECT

       Soft draining could be achieved by replacing REJECT by PAUSE in the above example.

       Pausing all new jobs not belonging to a specific maintenance.  :

              gnt-filter add --priority=0 '--predicates=[["reason", ["=~", "reason", "maintenance pink bunny"]]]' --action=ACCEPT
              gnt-filter add --priority=1 '--predicates=[["jobid", [">", "id", "watermark"]]]' --action=PAUSE

       Cancelling all queued instance creations and disallowing new such jobs.  :

              gnt-filter add '--predicates=[["opcode", ["=", "OP_ID", "OP_INSTANCE_CREATE"]]]' --action=REJECT

       Limiting  the number of simultaneous instance disk replacements to 10 in order to throttle
       replication traffic.  :

              gnt-filter add '--predicates=[["opcode", ["=", "OP_ID", "OP_INSTANCE_REPLACE_DISKS"]]]' '--action=RATE_LIMIT 10'

REPORTING BUGS

       Report  bugs  to  project  website  (http://code.google.com/p/ganeti/)  or   contact   the
       developers using the Ganeti mailing list (ganeti@googlegroups.com).

SEE ALSO

       Ganeti  overview  and specifications: ganeti(7) (general overview), ganeti-os-interface(7)
       (guest OS definitions), ganeti-extstorage-interface(7) (external storage providers).

       Ganeti  commands:  gnt-cluster(8)   (cluster-wide   commands),   gnt-job(8)   (job-related
       commands),  gnt-node(8)  (node-related  commands),  gnt-instance(8)  (instance  commands),
       gnt-os(8) (guest OS commands), gnt-storage(8) (storage commands), gnt-group(8) (node group
       commands), gnt-backup(8) (instance import/export commands), gnt-debug(8) (debug commands).

       Ganeti  daemons:  ganeti-watcher(8) (automatic instance restarter), ganeti-cleaner(8) (job
       queue cleaner), ganeti-noded(8) (node daemon), ganeti-rapi(8) (remote API daemon).

       Ganeti htools: htools(1) (generic binary), hbal(1) (cluster balancer), hspace(1) (capacity
       calculation),  hail(1) (IAllocator plugin), hscan(1) (data gatherer from remote clusters),
       hinfo(1) (cluster information printer), mon-collector(7) (data collectors interface).

COPYRIGHT

       Copyright (C) 2006-2015 Google Inc.  All rights reserved.

       Redistribution and use in source and binary  forms,  with  or  without  modification,  are
       permitted provided that the following conditions are met:

       1.   Redistributions  of  source code must retain the above copyright notice, this list of
       conditions and the following disclaimer.

       2.  Redistributions in binary form must reproduce the above copyright notice, this list of
       conditions  and  the  following  disclaimer  in  the  documentation and/or other materials
       provided with the distribution.

       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT  HOLDERS  AND  CONTRIBUTORS  "AS  IS"  AND  ANY
       EXPRESS  OR  IMPLIED  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN  NO  EVENT  SHALL
       THE  COPYRIGHT  HOLDER  OR  CONTRIBUTORS  BE  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED  TO,  PROCUREMENT
       OF  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
       HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT  LIABILITY,  OR
       TORT  (INCLUDING  NEGLIGENCE  OR  OTHERWISE)  ARISING  IN  ANY  WAY OUT OF THE USE OF THIS
       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.