Operations

VICIdial time zones: local_gmt and calls at the wrong hour

A VICIdial server keeps several clocks and a stock ViciBox ships them disagreeing. How servers.local_gmt shifts calling windows, and how to check each clock.

By Published Updated 5 min read
Row of wall clocks showing different time zones

To the point

A VICIdial server has at least three clocks, and a stock ViciBox ships them disagreeing. Each lead carries its own GMT offset, set from its area code, and the hopper measures every calling window against servers.local_gmt, not the operating system clock. That setting ships as -5.00, so a server nobody corrected is five hours off wherever it is, and every window moves by the difference.

  • On the ViciBox 12 server we read, the OS ran on UTC while local_gmt said -5.00. Local time was five hours out.
  • A 24hours call time hides it. A 9am to 9pm window opens and closes five hours wrong.
  • PHP has its own zone (date.timezone = 'UTC'), so reports and the agent screen disagree with the dialer logs.
  • The check is four commands.

The three clocks

Diagram: the operating system, servers.local_gmt and PHP, with what each one controls
Three clocks, three owners, one server

1. The operating system. What date prints. MariaDB's NOW() and the Perl daemons follow it.

2. servers.local_gmt. A number stored per server, which ships as -5.00. The hopper (AST_VDhopper.pl) takes it as its own GMT reference and measures each lead's window against it:

localtime(now - (servers.local_gmt + isdst) * 3600 + p * 3600)

p is a lead's offset on the ladder the hopper walks, +13.00 down to -12.75 in steps of 0.25. If the OS zone and local_gmt differ, the result is wrong by exactly the difference.

3. PHP's own. ViciBox sets date.timezone = 'UTC' in /etc/php8/apache2/php.ini and /etc/php8/cli/php.ini. Everything PHP writes keeps UTC: vicidial_api_log, the agent screen, the admin reports and their idea of "today". On a US box the PHP and Perl timestamps sit four or five hours apart.

Correcting the OS zone alone does not fix it. Change local_gmt, the same field in system_settings and phones, and both php.ini files, then reload Apache.

Where to set it, step by step

Test server screens follow. The red markers are numbered in the order of the steps beneath them.

In VICIdial's admin

VICIdial server record with Local GMT highlighted
Admin, Servers, then your server: the offset the hopper uses
  1. Local GMT: the standard-time offset, east-positive, so US zones are negative. A New York box sits at -5.00 all year.
VICIdial system settings with Default Local GMT highlighted
Admin, System Settings: the system-wide default offset
  1. Default Local GMT: the same offset at system level. Keep it equal to the server's.

In the Trustane console

Trustane console Set Up tab with Call time and Finish dialing by highlighted
The calling window that the hopper's clock is measured against
  1. Call time: the named window for the campaign.
  2. Finish dialing by: the time of day the campaign stops dialing.

What the windows test

For each offset the hopper derives a wall clock and weekday. A lead passes when start <= HHMM < stop: the start minute is in, the stop minute is out. A weekday left at 0/0 takes the default hours, and 2400 stands for never. Holidays can only tighten a window, and only where the stop is above zero. To close a whole day give the holiday 2400 for both. State rules remove their states from the default set. See reading the hopper.

A shifted clock moves every test together. It looks like "the campaign stopped early", not like an error. Whether an hour is allowed for a lead is a compliance matter, and the rule is yours to check.

A five-minute check

date
mysql -sNe 'SELECT NOW()'
php -r 'echo date("T");'
mysql -sNe 'SELECT server_ip, local_gmt FROM servers'

Then ask VICIdial. The Non-Agent API version function reports the zone it believes it is in. On a repaired box ours returned TZ: -5.00 DST: 1 TZNOW: -4. Read your copy of the documentation for the exact fields.

You want one story:

  • date shows the intended zone and abbreviation.
  • NOW() agrees with date.
  • PHP's abbreviation agrees. PHP on UTC while the rest say EDT is the third clock.
  • local_gmt is the standard-time offset, and the daylight saving flag is right for today. It is stored without daylight saving.

If the floor is in a different zone from the server, which clock should rule the call times is your decision.

Why nobody sees it at first

The campaign dials and agents talk. Symptoms are indirect: a campaign "stops early", yesterday's report looks short, a lead in the next zone east is called later than allowed. People check the list, call time and carrier first. We put the clock check in the opening minutes of a server review, before any tuning.

What to change, in order

  1. Set the OS zone with timedatectl set-timezone ....
  2. Set local_gmt in servers, and the matching fields in system_settings and phones.
  3. Set date.timezone in both php.ini files and reload Apache.
  4. Restart nothing else until you have checked. The Perl daemons read the system zone on start, so a restart may be needed. We did not test which.
  5. Repeat the check and watch the hopper for a few passes.

Reports have the same split. A report for "today" can start at midnight UTC, and a call placed at 8pm local can land on tomorrow's date. The calls are filed under another date, not missing.

What we did not test

One ViciBox 12 server. Not other images, half-hour or quarter-hour server offsets, or a daylight saving change on a live campaign.

Questions people ask

Why did my campaign stop at the wrong hour?

The hopper reads servers.local_gmt, not the OS clock. If they differ, every window shifts by the difference.

Does local_gmt change for daylight saving?

No. It is stored as standard time, so a New York box stays at -5.00 all year and the extra hour is applied separately.

Next steps

Run the four commands on every box you manage and write the results in one table. Fix any disagreement in the order above. Servers we build on our hosting have all four set to one zone. To have an existing box checked, contact us, or see how moving a server to us works.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.