html/adminmanual-2.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4  <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
   5  <TITLE>The DXSpider Administration Manual v1.47: Filtering (Old Style upto v1.44)</TITLE>
   6  <LINK HREF="adminmanual-3.html" REL=next>
   7  <LINK HREF="adminmanual-1.html" REL=previous>
   8  <LINK HREF="adminmanual.html#toc2" REL=contents>
   9 <link rel=stylesheet href="style.css" type="text/css" title="default stylesheet">
  10 </HEAD>
  11 <BODY>
  12 <A HREF="adminmanual-3.html">Next</A>
  13 <A HREF="adminmanual-1.html">Previous</A>
  14 <A HREF="adminmanual.html#toc2">Contents</A>
  15 <HR>
  16 <H2><A NAME="s2">2. Filtering (Old Style upto v1.44)</A></H2>
  17
  18 <P>Filters can be set for spots, announcements and WWV.  You will find the
  19 directories for these under /spider/filter.  You will find some examples in
  20 the directories with the suffix <EM>.issue</EM>.  There are two types of
  21 filter, one for incoming information and one for outgoing information.
  22 Outgoing filters are in the form <EM>CALLSIGN.pl</EM> and incoming filters
  23 are in the form <EM>in_CALLSIGN.pl</EM>.  Filters can be set for both nodes
  24 and users.
  25 <P>
  26 <P>All filters work in basically the same way.  There are several elements
  27 delimited by commas.  There can be many lines in the filter and they are
  28 read from the top by the program.  When writing a filter you need to think
  29 carefully about just what you want to achieve.  You are either going to write
  30 a filter to <EM>accept</EM> or to <EM>reject</EM>.  Think of a filter as
  31 having 2 main elements.  For a reject filter, you would have a line or multiple
  32 lines rejecting the things you do not wish to receive and then a default line
  33 accepting everything else that is not included in the filter.  Likewise, for an
  34 accept filter, you would have a line or multiple lines accepting the things you
  35 wish to receive and a default line rejecting everthing else.
  36 <P>
  37 <P>In the example below, a user requires a filter that would only return SSB spots
  38 posted in Europe on the HF bands.  This is achieved by first rejecting the CW
  39 section of each HF band and rejecting all of VHF, UHF etc based on frequency.
  40 Secondly, a filter rule is set based on CQ zones to only accept spots posted in
  41 Europe.  Lastly, a default filter rule is set to reject anything outside the filter.
  42 <P>
  43 <BLOCKQUOTE><CODE>
  44 <PRE>
  45 $in = [
  46         [ 0, 0, 'r', # reject all CW spots
  47                 [
  48                 1800.0, 1850.0,
  49                 3500.0, 3600.0,
  50                 7000.0, 7040.0,
  51                 14000.0, 14100.0,
  52                 18068.0, 18110.0,
  53                 21000.0, 21150.0,
  54                 24890.0, 24930.0,
  55                 28000.0, 28180.0,
  56                 30000.0, 49000000000.0,
  57                 ] ,1 ],
  58         [ 1, 11, 'n', [ 14, 15, 16, 20, 33, ], 15 ], #accept EU
  59         [ 0, 0, 'd', 0, 1 ], # 1 = want, 'd' = everything else
  60 ];
  61 </PRE>
  62 </CODE></BLOCKQUOTE>
  63 <P>
  64 <P>The actual elements of each filter are described more fully in the following
  65 sections.
  66 <P>
  67 <H2><A NAME="ss2.1">2.1 Spots</A>
  68 </H2>
  69
  70 <P>The elements of the Spot filter are ....
  71 <P>
  72 <BLOCKQUOTE><CODE>
  73 <PRE>
  74 [action, field_no, sort, possible_values, hops]
  75 </PRE>
  76 </CODE></BLOCKQUOTE>
  77 <P>
  78 <P>There are 3 elements here to look at.  Firstly, the action element.  This is
  79 very simple and only 2 possible states exist, accept (1) or drop (0).
  80 <P>
  81 <P>The second element is the field_no.  There are 13 possiblities to choose from
  82 here ....
  83 <P>
  84 <BLOCKQUOTE><CODE>
  85 <PRE>
  86       0 = frequency
  87       1 = call
  88       2 = date in unix format
  89       3 = comment
  90       4 = spotter
  91       5 = spotted dxcc country
  92       6 = spotter's dxcc country
  93       7 = origin
  94       8 = spotted itu
  95       9 = spotted cq
  96       10 = spotter's itu
  97       11 = spotter's cq
  98       12 = callsign of the channel on which the spot has appeared
  99 </PRE>
 100 </CODE></BLOCKQUOTE>
 101 <P>
 102 <P>The third element tells us what to expect in the fourth element.  There are
 103 4 possibilities ....
 104 <P>
 105 <BLOCKQUOTE><CODE>
 106 <PRE>
 107      n - numeric list of numbers e.g. [ 1,2,3 ]
 108      r - ranges of pairs of numbers e.g. between 2 and 4 or 10 to 17 - [ 2,4, 10,17 ]
 109      a - an alphanumeric regex
 110      d - the default rule
 111 </PRE>
 112 </CODE></BLOCKQUOTE>
 113 <P>
 114 <P>The fifth element is simply the hops to set in this filter.  This would only
 115 be used if the filter was for a node of course and overrides the hop count in
 116 hop_table.pl.
 117 <P>
 118 <P>So, let's look at an example spot filter.  It does not matter in the example
 119 who the filter is to be used for.  So, what do we need in the filter?  We need
 120 to filter the spots the user/node requires and also set a default rule for
 121 anything else outside the filter.  Below is a simple filter that stops spots
 122 arriving from outside Europe.
 123 <P>
 124 <BLOCKQUOTE><CODE>
 125 <PRE>
 126 $in = [
 127   [ 0, 4, 'a', '^(K|N|A|W|VE|VA|J)'],  # 0 = drop, 'a' = alphanumeric
 128   [ 1, 0, 'd', 0, 1 ],                 # 1 = want, 'd' = everything else
 129                      ];
 130 </PRE>
 131 </CODE></BLOCKQUOTE>
 132 <P>
 133 <P>So the filter is wrapped in between a pair of square brackets.  This tells
 134 Spider to look in between these limits.  Then each line is contained within
 135 its own square brackets and ends with a comma. Lets look carefully at the first
 136 line.  The first element is 0 (drop).  Therefore anything we put on this line
 137 will not be accepted.  The next element is 4.  This means we are filtering by
 138 the spotter.  The third element is the letter "a" which tells the program to
 139 expect an alphanumeric expression in the fourth element.  The fourth element
 140 is a list of letters separated by the pipe symbol.
 141 <P>
 142 <P>What this line does is tell the program to drop any spots posted by anyone in
 143 the USA, Canada or Japan.
 144 <P>
 145 <P>The second line is the default rule for anything else.  The "d" tells us this
 146 and the line simply reads... accept anything else.
 147 <P>
 148 <P>You can add as many lines as you need to complete the filter but if there are
 149 several lines of the same type it is neater to enclose them all as one line.
 150 An example of this is where specific bands are set.  We could write this like
 151 this ....
 152 <P>
 153 <BLOCKQUOTE><CODE>
 154 <PRE>
 155 [ 0,0,'r',[1800.0, 2000.0], 1],
 156 [ 0,0,'r',[10100.0, 10150.0], 1],
 157 [ 0,0,'r',[14000.0, 14350.0], 1],
 158 [ 0,0,'r',[18000.0, 18200.0], 1],
 159 </PRE>
 160 </CODE></BLOCKQUOTE>
 161 <P>
 162 <P>But the line below achieves the same thing and is more efficient ....
 163 <P>
 164 <BLOCKQUOTE><CODE>
 165 <PRE>
 166   [ 0, 0, 'r',
 167     [
 168       1800.0, 2000.0,         # top band
 169       10100.0, 10150.0,       # WARC
 170       14000.0, 14350.0,       # 20m
 171       18000.0, 18200.0,       # WARC
 172     [ ,1 ],
 173 </PRE>
 174 </CODE></BLOCKQUOTE>
 175 <P>
 176 <P>
 177 <H2><A NAME="ss2.2">2.2 Announcements</A>
 178 </H2>
 179
 180 <P>
 181 <BLOCKQUOTE><CODE>
 182 <PRE>
 183
 184 # This is an example announce or filter allowing only West EU announces
 185 #
 186 # The element list is:-
 187 # 0 - callsign of announcer
 188 # 1 - destination * = all, &lt;callsign> = routed to the node
 189 # 2 - text
 190 # 3 - * - sysop, &lt;some text> - special list eg 6MUK, ' ', normal announce
 191 # 4 - origin
 192 # 5 - 0 - announce, 1 - wx
 193 # 6 - channel callsign (the interface from which this spot came)
 194
 195 $in = [
 196         [ 1, 0, 'a', '^(P[ABCDE]|DK0WCY|G|M|2|EI|F|ON)' ],
 197         [ 0, 0, 'd', 0 ]
 198 ];
 199 </PRE>
 200 </CODE></BLOCKQUOTE>
 201 <P>In this example, only the prefixes listed will be allowed.  It is possible to
 202 be quite specific.  The Dutch prefix "P" is followed by several secondary
 203 identifiers which are allowed.  So, in the example, "PA" or "PE" would be ok
 204 but not "PG".  It is even possible to allow information from a single callsign.
 205 In the example this is DK0WCY, to allow the posting of his Aurora Beacon.
 206 <P>
 207 <H2><A NAME="ss2.3">2.3 WWV</A>
 208 </H2>
 209
 210 <P>
 211 <BLOCKQUOTE><CODE>
 212 <PRE>
 213
 214 # This is an example WWV filter
 215 #
 216 # The element list is:-
 217 # 0 - nominal unix date of spot (ie the day + hour:13)
 218 # 1 - the hour
 219 # 2 - SFI
 220 # 3 - K
 221 # 4 - I
 222 # 5 - text
 223 # 6 - spotter
 224 # 7 - origin
 225 # 8 - incoming interface callsign
 226
 227 # this one doesn't filter, it just sets the hop count to 6 and is
 228 # used mainly just to override any isolation from WWV coming from
 229 # the internet.
 230
 231 $in = [
 232         [ 1, 0, 'd', 0, 6 ]
 233 ];
 234 </PRE>
 235 </CODE></BLOCKQUOTE>
 236 <P>
 237 <P>It should be noted that the filter will start to be used only once a user/node
 238 has logged out and back in again.
 239 <P>I am not going to spend any more time on these filters now as they will become
 240 more "comprehensive" in the near future.
 241 <P>
 242 <HR>
 243 <A HREF="adminmanual-3.html">Next</A>
 244 <A HREF="adminmanual-1.html">Previous</A>
 245 <A HREF="adminmanual.html#toc2">Contents</A>
 246 </BODY>
 247 </HTML>