CHANNEL SETTINGS AND FILTERS IN PHOTOSERVE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  This document describes channel settings and filters for photoserve.
  Ops of all Photoserve-using channels should give it a quick read to
  get an idea of how the system works. 

  Although the files also carry generic setting, they are referred to
  as "filterfiles" (for historic reasons / backward compatibility).
  Filters are the reason the system was first created, and it continues
  to be the main function.





Format of filterfiles
~~~~~~~~~~~~~~~~~~~~~~

  The contents of a filterfile look like this:

  --------------------------------------------
  <settings>
  statsurl:http://www.xxx.net/stats.php
  botsname:LoserBot,WinnerBot,ToBor
  minpsversion:4.7
  </settings>

  <filters>
  OFFICIAL-DEFAULT:allow
  3RDPARTY-DEFAULT:exclude
  CUSTOM-DEFAULT:exclude

  SN.TRG:exclude
  SNOLDCD1:allow
  SNOLDCD2:allow
  </filters>
  --------------------------------------------
  
  As you can see, there are two sections in the file. The <FILTERS> section
  deals with filtering triggers for the channel, while the <SETTINGS> section
  has more varied setting. 

  The section markers <FILTERS>, </FILTERS>, <SETTINGS>, </SETTINGS> must be on
  their own lines. You cant write for example "SNOLDCD2:allow</FILTERS>" all on
  a single line. Setting  and filtering directives are also limited to one per 
  line. Empty lines are allowed, and nothing is case sensitive. Ordering of the
  sections (or directives inside the sections) do not matter. The following two
  snippets do exactly the same thing:

    +----------------+                   +----------------+
    | SN.TRG:exclude |   <- Same As ->   | SNOLDCD1:allow |
    | SNOLDCD1:allow |                   | SN.TRG:exclude |
    +----------------+                   +----------------+




The <Filters> section
~~~~~~~~~~~~~~~~~~~~~

  The filters consist of a set of directives in the format "item:rule". Valid
  items are default values different types of triggers, the filename of a .trg
  file, or single trigger. Two valid rules exist, "exclude" and "allow".

  --------------------------------------------
  <filters>
  OFFICIAL-DEFAULT:allow
  3RDPARTY-DEFAULT:exclude
  CUSTOM-DEFAULT:exclude
  SN.TRG:exclude
  SNOLDCD1:allow
  SNOLDCD2:allow
  </filters>
  --------------------------------------------

  Conflicting statements are allowed and are resolved by giving the most specific 
  item the highest priority. In the above example the entire group Suzenet is
  excluded, but the triggers SNOLDCD1 & 2 are allowed. Trigger is more specific
  than group so the two SNOLD statements override the group directive. The end
  result is that all triggers from Suzenet, except for SNOLD 1 & 2, are filtered.





Filter Wildcards
~~~~~~~~~~~~~~~~

  Starting with Photoserve 4.4 filters have support for wildcards. '#' in the
  item part will match any sequence of numbers in triggers, including possible
  leading zeroes.
  
  Thus this one line:
    SNCD#:exclude  

  Can replace all off:
    SNCD1:exclude
    SNCD2:exclude
    SNCD3:exclude
    ... no matter how big the SNCD series grows


  Beginning with Photoserve 4.9 you can have the wildcard at any position of
  the item, and use more than one wildcard if needed. So these will now work:
  - SEX#EXTRA -- matches SEX2003EXTRA, SEX2004EXTRA, etc
  - SEX#CD#   -- matches SEX2003CD1, SEX2004CD1, SEX2004CD2, etc

  Photoserve 4.9 has also optimised the speed of wildcard processing, but it
  will always be slightly slower than non-wildcard rules. If you are filtering
  a series you know will never have more that 2 or 3 triggers, it is recommend
  to add individual rules for those triggers instead of using a wildcard rule.




The <Setting> section
~~~~~~~~~~~~~~~~~~~~~

  The settings section carries channel specific settings not related to
  filtering of triggers. There are currently eight supported settings:

  - StatsURL:           URL of statsmaker/statsbot trigger valuation file for
                        pserve's collection advisor function. Not all channels
                        have a StatsUrl, omit this setting if that is the case.
                        If you would like to get stats functionality for your
                        channel, contact nick "_Store_" on ThundeCity network.

  - BotsName:           Names of all the channel bots, separated with commas.
                        These are used for nick coloring and giving bots a few
                        special entries in the nick right click context menu.
                        Botsname setting was added in pserve 4.4

  - MinPSVersion:       Minimum photoserve version for which leeching is
                        allowed. Versions below MinPSVersion will not be
                        able to leech, instead the user will get a message
                        urging him to upgrade. If you don't set MinPSVersion,
                        all versions can leech. Added in pserve 4.8

  - BetaBlacklist:      Comma separated list for disabling leeching with old or
                        buggy beta versions. You can specify single numbers
                        or ranges ("1-4,6,10-15,22"). Added in pserve 4.8

  - ChannelTriggersURL: URL of zip/rar file containing latest triggerpack used
                        in the channel. This setting allows users to update
                        triggers simply by right clicking in the channel and
                        selecting "Download and Update Triggers for #chan".
                        The filename of the URL does not contain any version
                        info, pserve will download and update even if you 
                        already have that triggerpack installed (not dangerous).

  - ChannelTriggersAutoUpdateChanList: This is a comma separated list of channel ids
                        in which, if the filterfile is from one of the channels, do 
                        a Automated Trigger Update. This can be set by the admins of 
                        a channel to force the users to download and update the triggers
                        on a daily basis. 
                        The id is the $md5 value of the $lower (case) channel name. 
                        to get an id type this:
                         //echo the id of #Abcd is $md5($lower(#Abcd))
                        This is to prevent giving your channel name away even if other
                        channel admins use your filterfile in their channel.
                         

  - DisableCsvUpdates:  Blacklist that disables automated CSV updates from other
                        channel members. It can sometimes happen that some fool
                        creates a custom CSV and spreads it around. Cleaning the
                        channel can be difficult because PSC can automatically
                        re-download the bad CSV even after the user has set the
                        official CSV. With DisableCsvUpdates you can prevent this
                        from happening, making the cleanup job somewhat easier.
                        The list is comma separated and may contain normal windows
                        ? and * wildcards.

  - DisableServInfo:    (1 or 0) Setting will disable the response of users to 
                        non-op !ServInfo requests IN THE CHANNEL.


  - WatchIps:           (1 or 0) Setting that will make all @ in the channel watch
                        for and kick out user with detected doublicated IP adresses. 
                        (that is running 2 mirc from the same computer)

  - keys_<channel>:     provides a list of keys (example: aa,ab,xxx,yyy) to get into a
                        channel. PS will auto try these keys if a channel cannot be 
                        entered because it is protected by a key (+k mode)
                        <channel> is the name of the channel without the # 
                        eg. keys_chat for channel #chat
                        The idea is that everyone already inside a channel is getting the 
                        keys while unknown persons get get inside a channel without getting
                        the key by someone "inviting" him. Once inside all members are updated
                        by the filterfile keys. Regular changes can ensure the keys are kept 
                        "secret". That is why the keys are a list, so old and new ones can 
                        be stored.

   - ChannelUrls:       a list of other user-named Filter entries (separated like all lists with ',')
                        will pop up a menu to Visit the locations listed in the user-named entries.

  --------------------------------------------
  <settings>
  ChannelTriggersURL: http://www.xxx.net/trigs.zip
  StatsUrl:http://www.xxx.net/stats.txt
  BotsName:LoserBot,WinnerBot,ToBor
  MinPSVersion: 4.8
  BetaBlacklist: 1,2,4-8
  DisableCsvUpdates: SNCD1,SNCD2,OBJCD*,AJDVD*
  keys_xxx: ab,secret,123
  </settings>
  --------------------------------------------

  More setting can and will be added as needed.




Adding comments 
~~~~~~~~~~~~~~~

  You may add comments to the file. Comments outside the filters & settings
  section don't require any special markup, but inside those section you
  must prefix the comment lines with ';'.


  --------------------------------------------
  Look mom, I made a filterfile!  

  <Filters>
  snoldcd1:Allow
  snoldcd2:Allow

  ; This a comment and so is the next line
  ; SWBTCD1:exclude  

  Custom-Default:eXclude
  3rdparty-Default:exclude
  Official-Default:allow
  sn.trg:EXCLUDE
  
  ; Following will NOT work:
  soft.trg:allow  ; This is wrong

  </Filters>


  <settings>
  statsurl:http://www.xxx.net/stats.txt
  </settings>

  Author: Joe
  --------------------------------------------




Distributing filterfiles
~~~~~~~~~~~~~~~~~~~~~~~~  
  
  Having a filterfile doesn't do you any good if you don't have a reliable
  method for delivering it to all the users of the channel. The primary
  delivery mechanism is WWW. Upload the file on a web server and publish
  the URL. Secondary mechanism is manual DCC send, which is meant to ensure 
  that people behind firewalls etc have some way of getting the file.

  AUTOMATIC UPDATE FROM URL

    Upload the file to a web server and publish the URL some way, eg 
    channel topic (other methods described below). The file you upload can
    be named how ever you like, as long as it ends with a number followed
    by the file extension (psfilters_1.txt, 200501.txt for example).

    The string to put in the topic is of format: "<psfilter|URL>". So the full
    topic may be something like "Pserve 4.4 out -- triggers.051229.rar --
    www.photoserve.info  -- <psfilter|www.mysite.com/u31415/psfilters_1.txt>".
    Photoserve will then automatically download the file and start using it. 

    When you need to update the filters, simply create another file, but this
    time with higher number in the end (psfilters_2.txt as an example). Once
    the file has been uploaded change the topic to point to the new file.
    Photoserve observes the topic change and downloads the updated file.

    The only significant part in the URL is the version number. You can totally
    change the filename or even move it to another server when making updates,
    the only important thing is to remember to increment the version number.
    <psfilter|www.mysite.com/u31415/1.txt>                - Change that to...
    <psfilter|klms.myip.com:88/files/ha-ha-2.txt>         - and PS will update
    
    Of course the numbering doesn't have to start from 1 and then go up by 1
    with every update. You may for example use a YYYYMMDD formatted date as
    the version number (example: psfilters_20040115.txt for a file that is
    released 2004-01-15). Just make sure the number gets larger with _every_
    update.

      If you want to turn PS Off in a channel use <psTurnOff> instead of the
      <psfilter  keyword in the topic. (this works only in the topic)

    Method 1 :: Automatic updates Topic
     
      As already explained, you put the <psfilter|URL> string in the
      channel topic and Photoserve downloads the file.

    Method 2 :: Automatic updates channel message/notice

      Although putting the <psfilter|url> in the channel topic is the
      easiest way, it's not all that pretty and it takes away space
      from other things that could be in the topic. So instead of using
      the topic you can have an op/bot say the URL on channel and PS
      auto-updates, just like with the topic method. URLs from non-ops
      will be ignored. 

      You probably want to put the message on a timer, the following
      would display the URL in channel once every every hour.
      /timer 0 3600 /msg #jpgtrades <psfilter|klms.myip.com:88/filter_2.txt>

      You may also use channel notice:
      /timer 0 3600 /notice #jpgtrades <psfilter|klms.myip.com:88/filter_2.txt>

      To minimize the annoyance factor, Photoserve hides these messages from
      the channel window. Don't try to "manually" hide the messages by using
      white color or other weirdness.

    Method 3 :: Chanop/Chanserv private notice

      Have Op/Bot or Chanserv (if the network has chanserv) send the URL
      in an on-join notice. Again, photoserve hides the notice so there
      is no spam caused by it. 

      on *:JOIN:#mypschan: /notice $nick #mypschan <psfilter|.....>
      Note how the channel is added to the notice - without it PS 
      would have no way of knowing which channel's filter URL you
      are trying to communicate.


  MANUAL DCC SEND BY OP

    In the "Remote Administration" commands menu that is displayed when you
    right click on nick, there is an entry "Filters Send Update File". This
    sends your current filterfile to the target as standard DCC SEND. The 
    target's PS will then automatically load the file.


  Automatic Updates and security

    Some people have expressed concerns regarding automatic updates:
    there really isn't anything to be worried about. The downloaded
    files contain NO EXECUTABLE CODE, so there is no way for anyone
    to format your hard drive with a bad file. 



