Command-line Script Configuration

This page gives instructions on configuring your server so it is ready to send command line scripts. For instructions on how to run command line scripts see Running Command Line Scripts

CiviCRM includes a number of PHP scripts which process data and handle batch tasks "in the background". These scripts are run from the server command line, often as automatically scheduled "cron" jobs. Except where otherwise noted, all of these scripts are located in the bin directory below your main CiviCRM install directory.

NOTE: Some scripts require additional editing before use (e.g. to configure the correct FROM email address for membership renewal reminders). These scripts are delivered with a .txt extension and must be renamed before use.

Component	Script Filename	Description
CiviEvent	ParticipantProcessor.php	Updates participant statuses for Wait-list and Approval Required event registration features. Moves participants from "On waitlist" to "Pending from waitlist" as space becomes available. Moves any type of Pending registrations to "Expired" if expiration period is set for an event. Sends notifications of status changes to participants.
CiviMail	civimail.cronjob.php	Sends queued CiviMail mailings
CiviMember	UpdateMembershipRecord.php	Updates membership statuses and optionally sends renewal reminders
CiviPledge	UpdatePledgeRecord.php	Updates pledge payment and pledge statuses and optionally sends payment reminders
Core	UpdateAddress.php	Geocodes addresses in bulk
Core	UpdateGreeting.php	Updates Email Greeting, Postal Greeting and / or Postal Addressee for contacts based on a passed in format or your site defaults. (learn more...)
Core and CiviCase	Email2Activity.php	Inserts activity for a contact or a case (v2.2+) by retrieving inbound emails from a mail directory
Core	CiviReportMail.php	Generates and sends a copy of the specified report instance to the email addresses configured in that instances Report Settings.
(all}	CRM/Utils/REST.php	Handles REST API calls

You are required to pass authentication information at runtime to prevent these scripts from being invoked by an unauthorized agent. As of versions 2.1.2 OR 2.0.7 , a Site Key is required in addition to a valid username and password. Include all three parameters when invoking these scripts:

name - Valid username for an authorized Drupal or Joomla user. A CiviCRM contact associated with this user must exist.
pass - Associated password for that user
key - The value of the CiviCRM site key from your settings file (see below)

Make sure there that there are no reserved or unsafe URL characters in your username or password. These include:

and spaces.

Configuring your Site Key

For CiviCRM versions 2.0.7+ and 2.1.2+ - you must manually generate a site key, and then add it to your CiviCRM settings file.

First generate the key. We recommend using a 16-32 bit alphanumeric/punctuation key value. You can ...
- create a random 16-32 character key from your keyboard OR
- use an external service like: http://www.thebitmill.com/tools/password.html OR
- use the following shell command to generate a key
  
  Make sure there that there are no reserved or unsafe URL characters in your site key. These include:
  
  and spaces.
Open your settings file - civicrm.settings.php - in your favorite editor and either add or edit the CIVICRM_SITE_KEY value.

in Joomla, there are 2 civicrm.settings.php files. By default these are located in site/administrator/components/com_civicrm and site/components/com_civicrm - it's important to add the same key to both files as some Joomla front-end functions rely on the key (eg, decrypting the Outbound Mail SMTP Password)

Depending on which version of CiviCRM you've installed, you may have this setting in your file already with a value of null, or you may need to add the line. In either case, replace null with the value of your key.

EXAMPLE: If my generated site key value is: 3cx4aNkpQwxmM1hTMV~!B09iO6
... then my settings file should look like this:

* Finally, make sure that you include the key=<sitekey> parameter whenever your run any of these scripts.

Setting up launchd to Automate Command Line Scripts on MacOS X

Apple introduced launchd in MacOS 10.4 as, among other things, a replacement for cron. It can be used for starting, stopping and managing daemons, programs and scripts.

EXAMPLE: Use launchd to run the civimail.cronjob.php file.

Create the launchd plist file

To create the launchd plist file, type (You'll be prompted for a password):

Copy and paste the following into the new document you've created.

<plist version="1.0">
<dict>
        <key>Label</key>
        <string>org.synackpac.civicrm.cron</string>
        <key>ProgramArguments</key>
        <array>
                <string>/usr/local/bin/civicrmcron.sh</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StartInterval</key>
        <integer>300</integer>
                <key>UserName</key>
        <string>_www</string>
        <key>GroupName</key>
        <string>_www</string>
</dict>
</plist>

To quit pico, type:
When prompted to save the file, type:

Create the shell script to run the commands

To create the shell script that launchd will run, type:
Copy and past the following, adding your cron username and password, and your site key, where appropriate:

#!/bin/sh
CIVIMAILURL="http://www.example.org/sites/all/modules/civicrm/bin/civimail.cronjob.php?name=user&pass=pass&key=key"
/usr/bin/curl -s $CIVIMAILURL

Close and Save the file just like you did when creating the plist file.

Load the launchd script to the running launchd tasks

From the command line, type