Readme for Tur-Trial
Contact information can be found at the end of this file.

This script, together with tur-trial.tcl, can be used to check
how your users is doing in either a weekly or montly trial
using !passed <user> from irc. If the user is not in any of
the trial groups, it can be used as a way to keep track of weekly/monthly quota.                                          
It supports up to 9 stat sections. If it finds more then one   
it will simply add them all up.

If you just want the quota checking, you can disable the TRiAL part =)
Vice versa too ofcourse.
                                                                
Trial users should be in group TRiAL (definable), and since the trials     
always starts when the reset binary resets the stats (yeah it does, if
you dont like static weeks/months, dont use this one), you can   
also put users in a TRiAL-2 group. (so you can add them to     
site before the trial begins). TRiAL-2 = trial next week.      

If enabled, users not in any of the trial groups will be       
considered to be on a weekly/monthly quota, unless excluded.   
                                                               
For logging, automatic switching of groups and deleting failed 
users, see text in the settings below. 

The old Triallist and MonthUpAll are both merged into one script now.
The only difference is that the quota part (MonthUpAll can not delete users
only put flag 6 on them).

These scripts/options are used to log how everyone did at the end of 
any defined periods, so you can just check the logs, both for triallers
and quota users.


Installation:
                                                               
Put tur-trial.sh & tur-trial.conf in glftpd's bin dir, and                      
tur-trial.tcl in your bots scripts dir. 
If you'd rather have the config file somewhere else, set its 
path in tur-trial.sh

Load the tcl in your bots conf file. Rehash the bot.                           
                                                                
Make sure tur-trial.sh is executable -> by the user who runs the bot <-.
                                                                
Set up the parameters in tur-trial.conf and try to run tur-trial.sh   
from shell. If it works from shell, it should work from the bot.                                                       
For logging of triallers and quota users, see settings below.

##-[ NOTE ]-########################################################################
# If you, from the bots partyline, get an error like /root/.bashrc - Access denied #
# either solve it and tell me why or do:                                           #
# chmod 755 /root; chmod 755 /root/.bashrc                                         #
####################################################################################
                                                                
Make sure to create the trial groups in glftpd first.

-[ TRiAL and TRiAL-2 specific settings ]------------------------

 DISABLETRIAL = Disable trial functions. This is if you want
                to use another script for trial but use
                tur-trial for quota. Setting this to TRUE
                will display the DISTEXT below when someone checks
                a user that is in the TRIALGROUP below.

                If you set this to TRUE, then set TRIALGROUP
                to the name of the trialgroup that the other
                script uses. So if they try to check quota
                limit while in the trial group, it will just
                say "This is only for quota users, use !trial
                instead" (or whatever trigger your other script
                uses).

 DISTEXT=       If DISABLETRIAL is TRUE then this is what
                tur-trial will say if it hits a user in the
                TRIALGROUP. Change the text as you please.

 LIMIT=         If a user is in TRiAL or TRiAL-2, what is the limit  
                to pass trial?                                       
                                                                
 DURATION=      Whats the duration of the trial? W/M                 
                W = Weekly, M = Monthly.                             
                                                                
 TRIALGROUP=    The name of the trial group.

 TRIALGROUPN=   The name of the trial group for next week.        
                                                                
 EUROWEEK=      TRUE/FALSE. Do you use european weeks in glftpd?     
                This will make a new week start on Monday if TRUE.   
                Default is FALSE, for new week on Sunday.           
                                                                
 NOTE: To disable this function, simply dont add users to TRiAL 
       or TRiAL-2 groups (or change those groups to someting    
       non existent). This is, if you are not running another
       script for trials, in which case you should use
       DISABLETRIAL above instead.
                                                                
-[ Weekly/Monthly quota specific settings ]---------------------

 NOTRIALLIMIT= If not in any trial groups, what is the limit to 
               pass the quota? Settings this to "" will disable 
               this function, and simply say "soandso is not on 
               trial, blabla".                                  
               Incase you do not have any monthly quotas, I
               recomend you disable it, or run another script
               to check quota.
                                                                
 NOTRIALDURATION= If not in trial groups, what is the duration? 
                  W = Weekly, M = Monthly                       
                                                                
 AFFILS=          Any groups that should be excluded from the   
                  quotas. Space Seperated.                      
                                                                
 AFFILSFOLDER=    One or more folders, containing your predirs. 
                  If one of the dirs it finds in here matches a 
                  users group, it will say that they are not on 
                  any trial or quota. Either use space as 
                  delimiter or use the setup from the example.
                                                                
 VACATIONDATA=    If you use Tur-Vacation 1.4+, you may use this
                  to deduct MB from the quota limit in regards to
                  how many days the user was on vacation.
                  See the bottom of this README for more info.
                  This is by default disabled with a # infront.

 VACATIONGROUP=   If VACATIONDATA is not disabled, this is the
                  same name of the VACATIONGROUP in tur-vacation.sh
                  

 NOTE: Settings NOTRIALLIMIT to "" will disable this function and 
       just use the trial part of it.

-[ Generic settings ]-------------------------------------------

 USERSLOCATION=   Full path to your users folder.
                                                                
 TMP=             Just a temporary location I can write too.    
                                                                
 BOLD=            Dont change this. Its a control char that will
                  be interpreded as bold by your bot. If you 
                  manage to change it by mistake, its CTRL-b
                  in vi.                            
                                                                
 SITENAME=        Name of your site.                            
                                                                
 SHOWLIMIT=       With this on TRUE, it will say how big the    
                  current limit is to pass.                     
                                                                
 EXCLUDE=         These users can not be checked. Seperate with 
                  a space.                                      
                                                                
 EXCLUDEDTEXT=    What to say when someone tries to check a     
                  user that is excluded. Set "" to say nothing. 
                                                                 
 DELETEDTEXT=     Text to show incase the user has flag 6.
                  Use $1 instead of username. Leave empty to 
                  not say anything.

 GLLOG=           Path to glftpf.log

                                                                
 If you wish to change the outputs, you can use $BOLD to start  
 and stop the text from being displayed in bold.                
 Finding the output might be tricky since its sliced and diced
 depending on certain things. The majority of the text is at 
 the bottom of tur-trial.sh though.
                                                                
-[ Quota log settings ]-----------------------------------------

 MonthUpAll is merged into this script. This will log everyone  
 that is not on trial to make sure they passed the quota this   
 week/month. Affils are excluded from both the AFFILS and       
 AFFILSFOLDER settings. Users can be excluded specifically too.

 This has nothing to do with TRiAL or TRiAL-2. This is for      
 everyone if you have a quota on how much must be uploaded each 
 period.
 
 You run this simply by adding a few parameters when executing
 tur-trial.sh. To prevent users from triggering it from irc, we
 use a dummy as the first argument and 'quota' as the second.
 So, for a live run, its: tur-trial.sh dummy quota

 Note that 'dummy' can be anything. It does not matter.
 tur-trial.tcl only passes on one argument, so users can never do
 for instance, !passed dummy quota, because the tcl would only run:
 tur-trial.sh dummy. It will then say "User dummy does not exist."

 It also comes with the same debug mode that MonthUpAll did. To 
 use this one too, add 'test' to the end too. With test, it will
 only output the result on screen and set any destructive settings
 to FALSE. Example: tur-trial.sh dummy quota test

 Note: Since it sets FLAGDEL to FALSE when running in debug mode,
 it will not tell you that it is adding flag 6 to users. It might
 even tell you that its moving the users to a specific group if
 ADDTOGROUP is not empty. Just disregard that.
                                                                
 It will detect if its the last day of the week/month, so       
 crontab this one every day at, say 11:57 PM. Heres an example: 
 57 23 * * * /glftpd/bin/tur-trial.sh dummy quota

 If you have the old MonthUpAll already crontabbed, you may remove
 it or use that one instead.
                                                                
 QLOGFILE=        Where to log the quota users too?             
                                                                
 EXCLUDEDUSERS=   Users to exclude totally from list.           
                  Space delimited.                              
                                                                
 EXCLUDELEECH=    TRUE/FALSE. Exclude users that have leech     
                  (Ratio 0) ?                                   
                                                                
 FLAGDEL=         Shall we put flag 6 on those who does not     
                  pass quota?

 ADDTOGROUP=      Move failed users to this group.
                  Requires that FLAGDEL is FALSE.
                  With this, you can move failed quota users
                  to any existing group. For instance, put them
                  in TRiAL-2 so they have a chance to redeem
                  themselfs.
                                                                
 SETCREDS=        This allows you to decide what to set their 
                  credits too if they should fail.
                  Requires that FLAGDEL is FALSE.
                  The amount is in KiloBytes, so take your megs
                  and multiply it by 1024. 
                  Set it to "" to not touch credits (default).

 TEST=            TRUE/FALSE. FLAGDEL wont actually del, just   
                  say it does.
                                                                
 QANNOUNCE=       TRUE/FALSE. Write end of period and who       
                  failed to GLLOG? This way, you can announce   
                  it on irc. See ANNOUNCE options below for how 
                  to get to to announce this.                   
                                                                
-[ List log settings ]------------------------------------------

 Triallist is merged into this script. What it does is list  
 all users in the trial or trial-2 groups, calculate if they    
 passed or not, then write that to a file. It can also delete
 users who did not pass, as well as move trial-2 users to trial
 etc..

 This is so you do not have to do !passed on everyone on trial  
 before the stats reset. Just check the log instead.            
 If you have triallist.sh in your crontab from previous         
 versions, remove it ( Or use that one too, heck if I care =) ) 

 As with quota, to prevent users from executing this from irc, we
 use a dummy as the first argument and 'triallist' as the second.
 Example: tur-trial.sh dummy triallist
 The word dummy can be any word. It does not matter as long as
 its followed by triallist.

 Also like quota, it will detect if its the last day of the 
 week/month so crontab it with that argument everyday at 23:58 or 
 similar. 
 Example: 58 23 * * * /glftpd/bin/tur-trial.sh dummy triallist                 
                                                                
 Since it only runs at the last day of the week/month, I added 
 a test mode here too. To make sure it works, run, from shell:
 tur-trial.sh dummy triallist test
 Test mode will set any destructive settings to FALSE so do
 not worry about it deleting any failed triallers here.
 -> It will not output any user results unless you actually have
 any users in the defined trial groups. <-

 LOGFILE=         Which file to write the output too?           
                                                                
 ANNOUNCE=        Announce who failed and passed on irc? With   
                  this on TRUE, it will just print it to the    
                  glftpd.log.                                   
                                                                
-[ Announce settings ]------------------------------------------

 To get quota and triallist to announce, add the following to 
 dZSbot.tcl if you are using zipscript-c. 
 I do not know how for other bots.
 Note: You only need this for announcing who failed quota or 
 trial. For normal !passed from irc, it is not needed.

 Add: 
 TURTRIAL to 'set msgtypes(DEFAULT)'                       
 set chanlist(TURTRIAL)  "YourChan"                            
 set disable(TURTRIAL)   0                                      
 set variables(TURTRIAL) "%message"                             
 set announce(TURTRIAL)  "%message"                             
                                                                
 Dont forget to .rehash the bot once added.

 To change what it says, search for ANNOUNCE in the script. I   
 was too lazy to just output the variables so you could change  
 it in dZSbot.tcl.                                              
                                                                
-[ AutoMove settings ]------------------------------------------

 This part can be executed when running the triallist above.    
 What it does is move users automatically from group to group   
 depening on if he passed or not.                               
 If the user is in TRiAL-2 and fail, he/she is moved to TRiAL.  
 If the user is in TRiAL-2 and pass, he can either be removed   
 from trial (passed early), or moved to TRiAL.                  
 If the user is in TRiAL and pass, it will move him out of the  
 TRiAL group and into another specified group, unless he is     
 already in another group in which case it will just remove    
 the user from the TRiAL group.                                 
 (So add users with 2 groups. The trial group and his real one) 
                                                                
 If the user is in TRiAL and fail, it can either move him to    
 a "failed" group OR put flag 6 on him (deleted). If he gets    
 the 6 flag, it will simply remove him from the TRiAL group.    
 (No point in moving him to a failed group if hes deleted.)
    
 Ofcourse, it will only do this if its actually the last day of 
 the week/month, since it is part of the triallist above.       
 NOTE: This one uses the settings from the List section above   
       so make sure those are set first.                        
                                                                
 AUTOCHANGE=   TRUE/FALSE. Move users between groups at all?    
               If FALSE, you have to do all work yourself.      
               ( Like ancient versions. )
                                                                
 PASSGROUP=    If the user passes, and he is not in another     
               group already, what do you want to move him to?  
               This group must be created in glftpd already.    
                                                                
 FAILGROUP=    If the user fails the trial, and DELFAIL below   
               is FALSE, which group do we move him to?         
               This group must be created in glftpd already.    
                                                                
 DELFAIL=      If the user fails the trial, do we automatically 
               put flag 6 (deleted) on him? If so, the setting  
               above has no effect.                             
                                                                
 PASSEARLY=    TRUE/FALSE. If a user passes trial while in     
               TRiAL-2 (up for trial next week), does that      
               count as a passed trial? If TRUE, it will simply 
               remove him from the TRiAL-2 group and if he is   
               in NO other group, add him to the PASSGROUP.     
               If FALSE, it will move him to the TRiAL group    
               even though he passed, so he have to pass again.                           
                                                                

-[ Custom Text Output ]------------------------------------------                                                                

Ok, this part can look kinda messy, and I guess it is. Anyway,
there are a number of cookies you can use in the output. Those are:

%BOLD%       = Start and stop bold output
%USER%       = The username checked
%GROUP%      = Users primary group
%EGROUP%     = If user is excluded because of a group, this is the name
               of that group.
%SHOWL%      = Limit to pass
%DURNAME%    = either month/week
%RATIO%      = Display difference between limit and currently uploaded/downloaded.
%DAY%        = How many days/hours/minutes left
%PERDAY%     = Ratio / day. How much to upload per %DAY%
%PERDAYNAME% = Name of %PERDAY% ( day/days/hour/hours/minute/minutes )

NOTEXISTS=    This will be shown if the user does not exist.

Trial stuff:

PASSED_TRIAL=          Output for when the user is on trial and passed.
NOTPASSED_TRIAL=       Output for when the user is on trial and havent passed.

PASSED_NEXTDUR=        Output for when the user is on trial next week and passed early.
NOTPASSED_NEXTDUR=     Output for when the user is on trial next week and have not passed.

PASSED_NOTRIAL=        This is only shown if the quota part is disabled in the script.
                       Its when a user is not on trial but would have passed anyway.
NOTPASSED_NOTRIAL=     As above, but would not have passed if he were on trial

Quota stuff:

QUOTA_EX_PASSED=       The user is excluded from quota but would have passed if he werent excluded.
QUOTA_EX_NOTPASSED=    The user is excluded from quota and would not have passed yet if he were on quota.

QUOTA_PASSED=          User is on quota and has passed.
QUOTA_NOTPASSED=       User is on quota and has yet to pass (use the ring Frodo).

FIRST_QUOTA_PASSED=    The user has not yet been on the site for a month yet. Had he been, he would have passed.
FIRST_QUOTA_NOTPASSED= The user has not yet been on the site for a month yet. Had he been, he wouldnt have passed yet.

Ok, those are the normal outputs when there are no custom outputs. There is also possible to set a custom one of any
of the ones above. You can do this for both single users and for groups. I took the "construction" from zio's Spacemaker.
Hope he dosnt mind =)

Basically its "Username:What to say" or "=GroupName:What To Say". Not the = infront of the name to define it to a group.
NEVER remove the TOT lines. Set them to 0 if you remove all the custom outputs. If you remove then, the script will go into
an endless loop.

C_PASSED_TRIAL[0]=   Custom one for PASSED_TRIAL.
C_PASSED_TRIALTOT=1  How many custom lines are there above? ( last number + 1 )

I'm not gonna bother typing all of them, cause they are described in the config itself.


-[ Working with Tur-Vacation ]-----------------------------------------

Tur-Trial 2.1+ can work together with Tur-Vacation 1.4+ so that if the
user was on vacation for half the month, he should only need to upload
half the limit to pass quota.

Set up Tur-Vacation for this first, then set up Tur-Trial.
No real reason, just easier.

This will deduct the amount the user needs to upload to pass quota
depending on how many days he/she was gone.

You still need to exclude the VACATION group. This only kicks in if
the user comes back from vacation in the middle of the month.
It does not have any effect on trial limit.
It does not work for weekly quota. Only monthly.
It will show a deducted amount when doing !passed from irc.
It will show DEBUG values when doing tur-trial.sh dummy quota test

The two settings in tur-trial.conf to handle this:
 VACATIONDATA=/glftpd/etc/quota_vacation.db  ## Set to same as in tur-vacation.sh
 VACATIONGROUP=VACATION                      ## Vacation group.

Point VACATIONDATA to the same file you set to TRIALDATA in tur-vacation.sh

Note that tur-trial.sh runs from shell, thus not chrooted, and
tur-vacation.sh runs chrooted from inside glftpd. Thus
tur-vacation.sh: /etc/quota_vacation.db
tur-trial.sh   : /glftpd/etc/quota_vacation.db

Also note: This is NOT the same file as defined as DB in tur-vacation.sh
That user gets removed from that file when he comes back from vacation
so we cant use it.

Other setting, VACATIONGROUP, should simply match VACATIONGROUP in
tur-vacation.sh. This group should still be excluded in tur-trial.conf

When running 'tur-trial.sh dummy quota' and its the end of the month,
it will go through the VACATIONDATA file and reset the number of seconds
the user has been on vacation ( since 1970 ).
This happens ONLY if the user is still in the VACATIONGROUP. If he is not
it will remove him/her from the VACATIONDATA file. Otherwise it will just
pile up with names that were once on vacation.

Setting VACATIONDATA to "" or putting a # infront of it simply
disables this function totally, which also happens to be the default (disabled).

OK, have fun =)

-[ Contact ]----------------------------------------------------
 Contact Turranius on Efnet/Linknet. Usually in #glftpd (efnet).
 Email: grandis@bredband.net
 http://www.grandis.nu/glftpd
