Introduction

Cron jobs are a way of automating tasks that you want done every week/month/day and at a certain time. To accomplish this, you will make crontab entries on your server which will tell it when it needs to run the command you want. Crontab entries tell the server to "run this command at this time on this date". Using cron with TGPX will allow you to have the software automatically build your TGP pages at specific times, backup your database, run the gallery scanner, etc.

Crontab Entries

A crontab entry consists of two parts - a time to run, and a command to run.

The time to run (the first part of the entry) is broken up into 5 fields:
1. minute of the hour
2. hour of the day (on the 24 hour clock)
3. day of the month
4. month of the year (1 = January, 2 = February, etc.)
5. day of the week (0 = Sunday, 1 = Monday, 2 = Tuesday, ..., 6 = Saturday)

A * in one of these fields indicates that the job should be executed at any or every one of these, so for instance a * in the month of the year field means that this task should be carried out every month at the time specified in the other fields. A * in the day of the week field, when there is something in the day of the month field, does not mean that this task should be carried out every day, but rather that it should be carried out on the appointed day of the month regardless of what weekday it is. Only *s in the day of the week field, and the day of the month field, and the month of the year field would indicate a daily task.

Examples:
In the examples, [command] represents the full path and filename of the file you want to execute.

The job with this time to run would run every Sunday at 12:20 am:
20 0 * * 0 [command]

This job would run at midnight on any Friday the 13th:
0 0 13 * 5 [command]

You don't have to put just one time in a field. This job, for instance, would run every day at 12:30am, 2:30am, 4:30am, 6:30am, 6:30pm, 8:30pm, and 10:30pm:
30 0,2,4,6,18,20,22 * * * [command]

This one would run every Tuesday and Friday at 5:30 am:
30 5 * * 2,5 [command]

Creating a File For Crontab Entries


To register the cron commands with the server, you will need to create a plain text file with a list of all of the crontab entries. You will then use this file along with the server's crontab command to register them with the server. Once they have been registered, they can begin executing at the time you specify.

Start with an empty text file in the text editor of your preference (EditPlus is recommended for Windows users). At the top of this file you will want to put any already existing crontab entries that you have running on your server. If you have never used cron before, there will not be any. If you have used cron before, you will need to login to your server through telnet or SSH and execute the crontab -l command. This will display a list of your existing crontab entries. Copy and paste this to the top of your text file.

Now you can start adding your TGPX crontab entries to the file. All of the available commands are covered later in this document, so be sure to read the entire thing before setting up your cron jobs.

Once you have all of the above steps completed, you can save the file. You can name it anything you want. It is recommended that you use cron.txt for the filename, however anything will work. To register these commands with the server, continue with the next section of this document.

Here is an example crontab entry file for you to look at.

Registering Your Cron Commands


Once you have created the text file containing your crontab entries, you will need to register them with the server. To do this, upload the text file to your server (for this example, assume the filename is cron.txt). A good place to upload it is the same directory where TGPX is installed.

After the cron.txt file has been uploaded, login to your server through telnet or SSH. Change into the directory where you uploaded the cron.txt file and run the command crontab cron.txt. This will register the crontab entries with the system, and they will begin executing at the next scheduled time. To make sure your crontab entries were recorded properly, you can run the crontab -l command. This will display a list of all of the current crontab entries registered under your username.

Using the cron.php Script



The cron.php script will accept one of several command line arguments that will tell it which function it should run. Each of the available command line arguments are listed below.

--build
This will build all of your TGP pages using a standard Build type of build. You can also pass an optional additional parameter to specify the exact pages that you want built:


You can find the ID number for each page through the Manage Pages interface.


--pages=3,7,9 - This will build pages with ID numbers 3, 7, and 9
--pages=5-10 - This will build pages with ID numbers 5 through 10 inclusive (5, 6, 7, 8, 9, and 10)
--tags=main_pages - This will build pages with the tag main_pages
--tags='main_pages rss_feeds' - This will build pages with the tags main_pages or rss_feeds

You can also override the lock setting on your pages by adding an optional argument:


--override-lock - This will build pages even if they are locked


--build-with-new
This will build all of your TGP pages using a Build With New type of build. You can also pass an optional additional parameter to specify the exact pages that you want built:


You can find the ID number for each page through the Manage Pages interface.


--pages=3,7,9 - This will build pages with ID numbers 3, 7, and 9
--pages=5-10 - This will build pages with ID numbers 5 through 10 inclusive (5, 6, 7, 8, 9, and 10)
--tags=main_pages - This will build pages with the tag main_pages
--tags='main_pages rss_feeds' - This will build pages with the tags main_pages or rss_feeds

You can also override the lock setting on your pages by adding an optional argument:


--override-lock - This will build pages even if they are locked


--backup
This will backup your TGPX data. This function has additional command line arguments to specify the backup filenames to use


--sql-file=sql-backup.txt - Use this setting to specify the filename to use for your MySQL data (required)
--thumbs-file=thumbs-backup.txt - Use this setting to specify the filename to use for your preview thumbnails (optional, will not be created if not provided)
--archive-file=backup.tar.gz - Use this setting to specify the filename to use for a tar.gz archive containing the SQL and thumbnail backup files (optional, will not be created if not provided)


--optimize
This will optimize and repair your MySQL database

--process-clicklog
This will process the click log and add the stats to the database if you are using the high traffic click.php script

--reset-clicks-submitted
This will reset the click counts on all submitted galleries to 0

--reset-clicks-permanent
This will reset the click counts on all permanent galleries to 0

--daily-partner
This will perform daily maintenance on your partner accounts; this should be run only once per day. This requires that you pass some additional arguments:


--email-inactive=7 - Use this argument to e-mail partner accounts that have been inactive for the number of days specified. For this example, partners that have not submitted within the last 7 days would be e-mailed. The contents of the email-partner-inactive.tpl template will be sent to each partner account.

--remove-inactive=10 - Use this argument to remove partner accounts that have been inactive for the number of days specified. For this example, partners that have not submitted within the last 10 days would be deleted.

--email-expiring=5 - Use this argument to send an e-mail message to partner accounts that are expiring soon. For this example, partners that are expiring in 5 days would be e-mailed


--cleanup
This will perform some general cleanup routines

Here are some examples of the cron commands you might use:

Use this command to build pages with ID numbers 1, 7, and 19 at 5am daily:

0 5 * * * /path/to/php /full/directory/path/to/cron.php --build --pages=1,7,19


Use this command to build all pages with a Build With New type build at 3am daily:

0 3 * * * /path/to/php /full/directory/path/to/cron.php --build-with-new


Use this command to build the page with ID number 1, even if it is locked, at 5am every Sunday:

0 5 * * 0 /path/to/php /full/directory/path/to/cron.php --build --pages=1 --override-lock


Use this command to backup your database (to sql-backup.txt) and thumbnails (to thumbs-backup.txt) once per day at midnight:

0 0 * * * /path/to/php /full/directory/path/to/cron.php --backup --sql-file=sql-backup.txt --thumbs-file=thumbs-backup.txt


Use this command to optimize your database once per week at midnight on Sunday:

0 0 * * 0 /path/to/php /full/directory/path/to/cron.php --optimize


Use this command to run daily partner account tasks at 6am every day. Partners inactive for 30 days would be deleted and partners expiring in 2 days would be e-mailed:

0 6 * * * /path/to/php /full/directory/path/to/cron.php --daily-partner --remove-inactive=30 --email-expiring=2

Note that the /full/directory/path/to/ portion would be replaced with the directory path on your server to the directory where the cron.php script is located and /path/to/php would be replaced with the location of the CLI version of PHP on your server.

Using the scanner.php Script

To use the scanner.php script your server will need to have the command line interface (CLI) version of PHP installed. If you are not sure about this, contact your server administrator and ask them if the CLI version of PHP is installed on the server. You will also need to know where the CLI PHP binary is located on the server. In most cases it is in /usr/bin or /usr/local/bin

You can start the scanner.php script through cron to have your galleries automatically scanned at the times you specify. The scanner.php script will need to be passed the ID number of the scanner configuration you want it to run. You can find the ID number for each configuration next to it's Identifier in the control panel interface. For example, if you wanted to run the gallery scanner with configuration id 7 once every week at 6am on Sunday, you would use the following crontab entry:

0 6 * * 0 /path/to/php /full/directory/path/to/scanner.php 7 &

Note that the /full/directory/path/to/ portion would be replaced with the directory path on your server to the directory where the scanner.php script is located and /path/to/php would be replaced with the location of the CLI version of PHP on your server.