MAIN README for tur-trial3

Features:
Trial and Quota.

Trial is no longer locked to static weeks. The default number of days
are 7 although that can be changed. It can also be changed on individual
basis from user to user by a simple command or two.

Quota is always set to static months. 

Support for multiple stat sections with different pass-ratios in each one.
Support for monthup quota, where a user MUST be in a specific monthup position
to pass quota that month.

Limits to pass both trial and quota can also be changed from the default limits
on individual basis.

Quota part can be turned off if you only like to have a trial system.
(see README.usage for instructions how to do that.)

MSS support in that it creates actionfiles for each user that fails quota/trial.

TUR-VACATION support in that it excludes the user for the current month if hes
on vacation (or any other vacation script that uses a GROUP on the user).

Fun stuff:
With multiple sections, define a number and if the user passes that many sections
he/she gets excluded from quota next month.

Define another number. If the user passes quota in any section by that many times
he/she gets excluded from quota next month.

Should the user pass both above, define a third number and the user gets excluded for
that many months.


Installation:

1: You are required to have access to a mysql server somewhere. The mysql client
   needs to be installed on the machine thats running the tur-trial3.sh script.
   Note that you do not have to have any knowledge of mysql to use this script, just
   know the IP adress of the server and the root password (not the same password as
   on the shell).

   So, start with reading the README.mysql document in mysql_stuff and set up the 
   database/tables with the provided script.


2: Copy tur-trial3.sh, tur-trial3.conf & tur-trial3.theme to /glftpd/bin.
   As usual, 'chmod 755 tur-trial3.sh' and 'chmod 644 tur-trial3.conf'

   The three files MUST be in the same directory.


3: Edit tur-trial3.conf. See README.config


4: Now that the config is complete, there are one thing we need to do to start with.

   Make sure DEBUG=TRUE in the config.

   Run the following command from shell.
>  /glftpd/bin/tur-trial3.sh update

   This will update the 'exclude' and 'rank' tables with data.
   The exclude table consists of username, excluded. 
   If a user is excluded by group, the excluded field is 1. If not, its 0.   

   Once that has finished and you didnt get any errors, we should crontab it.

   How often you do this is up to you. I recomend every 31 minutes (weird huh?)

>  */31 * * * * /glftpd/bin/tur-trial3.sh update


5: We need it to check if anyone is beyond their defined trial time as well, so
   we need another cronjob.
   You can try this from shell first if you like. If you havent added any triallers
   (which you shouldnt have yet) it will just quit.
   Run: 
   /glftpd/bin/tur-trial3.sh tcron

   No errors? Good. Crontab it. How often is up to you, but it should be ATLEAST once
   every hour.
   I recomend every 30 minutes.
>  */30 * * * * /glftpd/bin/tur-trial3.sh tcron

   The above job will make sure users are either kicked when their trial time is passed
   OR get removed from trial (this can happen even if the time limit isnt passed yet).


6: Now the most important part. We need to crontab the qcron part as well.
   This one should be executed at midnight but its VERY important that 'reset'
   does NOT run in the middle of it to reset the stats.

   Therefor, if you havent already, make a midnight.sh script. Use your favorite
   editor and (using emacs in the example):

   emacs /glftpd/bin/midnight.sh
   <type in>
   #!/bin/bash
   /glftpd/bin/tur-trial3.sh qcron
   /glftpd/bin/reset
   <save>
   chmod 700 /glftpd/bin/midnight.sh

   There. We now have a midnight.sh script thats executable and performs the two tasks.
   First, it will check if anyone failed quota. Once its finished, it will reset the
   stats in the userfiles.

   Crontab the midnight.sh script at midnight INSTEAD of reset, so remove reset from crontab.
>  0 0 * * * /glftpd/bin/midnight.sh


7: The basic of tur-trial3 are now complete. But perhaps we should add some admin functions eh?

   If you, in step 1 above, installed the mysql client in glftpd's chrooted enviroment, we can
   add the admin part so it works from site.
   All you need to do is to add one custom command in /etc/glftpd.conf
   site_cmd trial EXEC /bin/tur-trial3.sh
   custom-trial 1

   There. You should now be able to execute 'site trial' from the site to reach the admin interface.

   If you also want a 'site passed' command so the users can check their status from inside your site
   then also add this:
   site_cmd passed EXEC /bin/tur-trial3.sh[:space:]check
   custom-passed *


8: The users must be able to see where they are in quota/trial from irc. We need the good-ol !passed
   command!

   Copy tur-trial3.tcl to your bots config dir and load it in the config file.
   Remember to remove any other commands you have in here from the old tur-trial if you were using it.

   As you can see when editing tur-trial3.tcl, there are 4 commands in it.
   !passed = Open for everyone. See where you are in trial/quota.
   !trials = Open for everyone. See how each and every user on trial is doing so far.
   !quota  = Open for everyone. Show passed or failed quota users. This is done in realtime
             and is not exactly lightning fast.
   !tt3    = Open for ops only. This is the same admin interface as from glftpd so your
             admins can do stuff from irc as well.
             The flag on the bind command is 'o' which means the users who should be able to
             run this must have flag o ON THE BOT THIS SCRIPT IS LOADED ON.
             Otherwise it wont do anything when trying to execute it.


9: Getting the bot to announce failed trial/quota users.
   First, you've defined GLLOG in tur-trial3.conf, yes? Good.

   We use the TURGEN: trigger in tur-trial3, so if you already have that
   added to your bot, you dont need to do anything.

   In either case, for Dark0n3s dZSbot.tcl, we need to edit it and:

    To 'set msgtypes(DEFAULT)', add TURGEN
    Add the following in the appropriate places:
    set chanlist(TURGEN) "#YourChan"
    set disable(TURGEN) 0
    set variables(TURGEN) "%msg"
    set announce(TURGEN)  "%msg"

  Once done, rehash the bot.

  If you use pzs-ng beta3+, everything is the same except for set announce(TURGEN).
  Instead of the above 'set announce' line, you'll want to add
  announce.TURGEN = "%msg"
  to the themefile for the bot.

  If you use the SS5 bot, I think if you edit tur-trial3.sh and do a search
  and replace on TURGEN: to RAW: it will announce fine as well.

  

10: We're all done. See README.usage for more indepth instructions on
    how to actually USE it as well.
    If you like, you can modify the output in tur-trial3.theme. Just remember to
    create a backup cause its fairly easy to miss a " or similar somewhere.
