Changing ZCS Time Zones

From Zimbra :: Wiki

Jump to: navigation, search
   Article-check.png  - This is certified documentation and is protected for editing by Zimbra Employees & Moderators only.


Admin Article

Article Information

This article applies to the following ZCS versions.
  ZCS 5.0 Article  ZCS 5.0

Time zones change when governments change daylight saving time policies. When a time zone changes, it is necessary to change the time zone settings in ZCS. This article discusses the tools and steps used to change time zone settings in a deployed Zimbra Collaboration Suite server.

To read more about how ZCS interacts with time zones, see Time Zones in ZCS.

Contents

Before You Begin

Before you start changing a time zone on a deployed ZCS server, review the following instructions and the descriptions of the tools you will use.

Backup your ZCS Server

Before changing the time zone settings on a deployed ZCS server, it is recommended that you create a backup.

Identify which Time Zones Need Updating

Before you begin changing a time zone setting and applying those changes, you should identify which time zone needs updating. The easiest way to identify this is via REST export of a user's calendar. Take note of an appointment that is showing at the wrong time, then REST export the calendar. Find the wrong appointment in the resulting .ics file (e.g. Search for the appointment subject). The DTSTART of the appointment should refer to a TZID. Match this TZID with the VTIMEZONE listed at the beginning of the .ics file. You can then create a replacement rule by TZID, offset, rules, etc.

Repeat this process for other appointments that show incorrect times.

Create a zmzupdate Rule File

Once you have the complete list of time zones to be updated, you can create a zmtzupdate rule file, containing all update rules. For more information on creating this file, refer to zmtzupdate rule file.

Note: Zimbra recommends testing the update rules in the zmtzupdate rule file by running zmtzupdate on a few test accounts before applying the the updated file to all accounts to be updated.

Changing a ZCS Time Zone Setting

Use the following instructions to change a time zone setting on a ZCS server.

1. In the timezones.ics file, make the necessary changes to the relevant VTIMEZONE entry.

2. Restart Zimbra Services.

zmcontrol stop
zmcontrol start

3. Using zmtzupdate, update existing appointments with the changed time zone settings.

ZCS Time Zone Tools

The following tools are used to define and change time zone settings in ZCS.

timezones.ics

The timezones.ics file contains a list of well-known time zones. This file is a valid iCalendar (RFC2445) object containing a VTIMEZONE block for each time zone. It is located in /opt/zimbra/conf/.

The basic client and other JSP-based clients must know an account's default time zone to render the Calendar view. Calendar resource accounts (e.g. conference rooms) must have a default time zone set to auto-accept/decline meetings. These default time zones must be chosen from the time zones defined in the timezones.ics file.

To change a time zone, you must locate and edit its VTIMEZONE definition. Changes to the timezone.ics file become effective when the mailboxd process is restarted.

The following section identifies each part of the VTIMEZONE definitions.

VTIMEZONE Definitions

Each timezone listed in the timezone.ics file is described using a VTIMEZONE definition. The following example is the VTIMEZONE definition for US Pacific Time.

BEGIN:VTIMEZONE
TZID:(GMT-08.00) Pacific Time (US & Canada)
LAST-MODIFIED:20070209T005655Z
BEGIN:STANDARD
DTSTART:16010101T020000
TZOFFSETTO:-0800
TZOFFSETFROM:-0700
RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=11;BYDAY=1SU
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:16010101T020000
TZOFFSETTO:-0700
TZOFFSETFROM:-0800
RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=3;BYDAY=2SU
END:DAYLIGHT
END:VTIMEZONE

This definition is composed of a series of properties describing US Pacific Time. The following table lists the properties of a VTIMEZONE definition.

Note: The properties below are described based on their use in ZCS. For more information about the iCalendar syntax, refer to RFC2445.

VTIMEZONE Properties
Name Description
BEGIN <VTIMEZONE> This defines the beginning of a VTIMEZONE definition.
END <VTIMEZONE> This defines the end of a VTIMEZONE definition.
TZID This is the name of the time zone being defined.

Important: This element should not be modified.

LAST-MODIFIED This is a time stamp indicating when the time zone definition was last modified. While this is not currently used, it is recommended that you update the time stamp when you modify the definition. The date and time is given in the form of <YYYYMMDD>T<hhmmss>Z. The time should always be given in GMT. For example, the LAST-MODIFIED value for a definition that was modified October 5th, 2008 at 2:41 pm, GMT, would be 20081005T144100Z.
BEGIN <STANDARD | DAYLIGHT> This defines the beginning of either a standard time or daylight savings time rule set. A time zone that uses daylight savings time will have two BEGIN entries, one defining standard time and the other defining daylight savings time. A time zone that doesn't use daylight savings time will only have one BEGIN entry defining standard time.
END <STANDARD | DAYLIGHT> This defines the end of either a standard time or daylight savings time rule set.
DTSTART This defines the date and time the standard or daylight time rule set is applied. The date is not important, as long as it is set for a prior date. The default date for ZCS time zones is 19710101. The time indicates in local time when to apply standard or daylight savings time. The date and time is given in the form of <YYYYMMDD>T<hhmmss>. For example, a daylight savings time DTSTART value of 160101T020000 indicates that any transition to daylight savings time occurring after Jan. 1st, 1601 should be applied at 2:00 am local time.

Note: This value should be set, even if the time zone does not use daylight savings time.

TZOFFSETTO This indicates the GMT offset after the transition. If the time zone does not use daylight savings time, the TZOFFSETTO value and the TZOFFSETFROM value are both the year-round GMT offset of the time zone. The offset is given in the form of +/-hhmm. For example, -0800.
TZOFFSETFROM This indicates the GMT offset before the transition. If the time zone does not use daylight savings time, the TZOFFSETTO value and the TZOFFSETFROM value are both the year-round GMT offset of the time zone. The offset is given in the form of +/-hhmm. For examples, -0700.
RRULE This specifies the rule for the transition date. Month value ranges from 1 to 12, 1 being January. Week value is a week number followed by a 2-letter weekday. Week number ranges from 1 to 4, or can be -1 for the last week of the month. Weekday values are SU, MO, TU, WE, TH, FR, and SA. For example, US Pacific Standard Time is set to BYMONTH=11;BYDAY=1SU, indicating the transition to standard time happens on the first Sunday of November.

Important: Settings for FREQ, WKST, and INTERVAL should not be changed.

Note: If the time zone does not use daylight savings time, the RRULE is not specified.

Examples

  • In this example, we have changed US Pacific Time to start daylight savings time on the first Wednesday of April at 5:00 am and to transition to standard time on the last Saturday of October at 6:30 am.
BEGIN:VTIMEZONE
TZID:(GMT-08.00) Pacific Time (US & Canada)
LAST-MODIFIED:20070209T005655Z
BEGIN:STANDARD
DTSTART:19710101T063000
TZOFFSETTO:-0800
TZOFFSETFROM:-0700
RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=10;BYDAY=-1SA
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19710101T050000
TZOFFSETTO:-0800
TZOFFSETFROM:-0700
RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=4;BYDAY=1WE
END:DAYLIGHT
END:VTIMEZONE
  • In this example, we have changed US Pacific Time to no longer use daylight savings time.
BEGIN:VTIMEZONE
TZID:(GMT-08.00) Pacific Time (US & Canada)
LAST-MODIFIED:20070209T005655Z
BEGIN:STANDARD
DTSTART:19710101T020000
TZOFFSETTO:-0800
TZOFFSETFROM:-0800
END:STANDARD
END:VTIMEZONE

Note: Because daylight savings time is not being used, the RRULE property is not used in this definition and the TZOFFSETTO and TZOFFSETFROM values are the same.

zmtzupdate

Changes to a timezone setting in the timezones.ics file are automatically applied to appointments created after the change. Existing appointments retain the old time zone setting information. The zmtzupdate CLI tool exists to apply new timezone settings to existing appointments.

Note: Before running zmtzupdate, update the zmtzupdate rule file.

Syntax

zmtzupdate --rulefile <rulefile> -a <all | list of email addresses to modify> [--sync] [--after <time stamp>]

Description

Name Description
--rulefile <rulefile> This specifies the location of the rule file to use when applying the timezone changes. Before running zmtzupdate, this rule file should be updated with relevant time zone changes. Read more about the zmtzupdate rulefile in the Rule File section
-a <all | list of email addresses to modify> This is the list of accounts to update. The all option means to update all accounts on the server. If you only want to apply the changes to specific accounts, instead list the email addresses of the accounts to modify.
--sync If specified, this option will cause the zmtzupdate command to block until the server is done processing all requested accounts. If it is not specified, zmtzupdate will exit as soon as the server begins to update.
--after <timestamp> This specifies that only appointments that have instances after the timestamp will be updated. By default, all appointments occurring before January 1st, 2008 will not be modified. The date and time specified can be given in any of the following forms.
2008/03/06 15:56:42
2008/03/06 15:56:42 623
2008/03/06 15:56:42.623
2008/03/06-15:56:42-623
2008/03/06-15:56:42
20080306.155642.623
20080306.155642
20080306155642623
20080306155642

Note: Any date and time form which includes a space must be quoted. For example, 2008/03/06 15:56:42 should be given as '2008/03/06 15:56:42'.

zmtzupdate Rule File

The zmtzupdate rule file is an XML file listing a series of rules to match a time zone and the replacement time zone definition. For an example of what a zmtzupdate rule file looks like, see Example Rule File. Before you run zmtzupdate, this rule file should be changed to include relevant update information.

Elements
Name Description
<tzfixup> The root element of the file is <tzfixup>. It can contain one or more <fixupRule> elements.
<fixupRule> If a time zone matches any of the criteria in the <match> element, it will be replaced with the timezone in the <replace> element. Each <fixupRule> must contain one <match> element and one <replace> element.
<match> Specify one or more criteria to check against a time zone. The <match> element can contain any combination of <tzid>, <nonDst>, <rules>, and <dates>. It can contain more than one of any of these conditions. If you include multiple match conditions, time zones meeting any of the listed conditions will be matched.
<replace> Any time zone matching the criteria in the <match> element will be replaced with the time zone specified in the <replace> element. The <replace> element can contain either <wellKnownTz> or <tz>.
The following conditions are placed in a <match> element, and describe how to match a time zone. You can use any combination of these conditions, and can use the same condition multiple times.
<tzid> This condition matches a time zone by its TZID. The TZID of a time zone is compared to the id specified in the <tzid> condition. The string comparison is case-insensitive. The id value must be properly XML-escaped (e.g. Use &amp; instead of &).
<nonDst> This condition matches a non-DST time zone by GMT offset. It tests if a time zone is one that has a specific GMT offset (given as minutes) and does not use daylight savings time. GMT offset has a negative value as you move west from GMT, and positive if you move east.
<rules> This condition matches a time zone on GMT offsets of standard and daylight times, as well as the transition rules expressed as month, week number, and day of the week. The transition time (hour/minute/second) is ignored during the matching. Month value ranges from 1 to 12, 1 being January. Week value ranges from 1 to 4, or can be -1 for the last week of the month. Weekday value ranges from 1 to 7, 1 being Sunday.
<dates> This condition matches a time zone on GMT offsets of standard and daylight savings times, as well as the transition dates expressed as month and day of month. The transition time (hour/minute/second) is ignored during the matching. Standard time GMT offset and Daylight Savings time GMT offset are given in minutes. GMT offset has a negative value as you move west from GMT, and positive if you move east. Month value ranges from 1 to 12, 1 being January. Day of the month value ranges from 1 to 31.

Note:Time zones that match this type of condition are very rare, and this element should only be used if other elements are unable to find the desired match.

The following elements are placed in a <replace> element, and describe which time zone to replace the matched time zone with. You can use only one of the following elements in the replace element.
<wellKnownTz> This looks up a well-known time zone in the /opt/zimbra/conf/timezones.ics file and uses the associated id for replacement.
<tz> This provides the full definition of the time zone used for replacement. Standard time GMT offset and Daylight Savings time GMT offset are given in minutes. GMT offset has a negative value as you move west from GMT, and positive if you move east. Month value ranges from 1 to 12, 1 being January. Week value ranges from 1 to 4, or can be -1 for the last week of the month. Weekday value ranges from 1 to 7, 1 being Sunday. Hour value ranges from 0 to 23. Minute and second value range from 0 to 59.

Note: Time zones that do not use daylight savings time do not need definitions for Daylight Savings time, nor the transition rule and time.

Example Rule Files
  • The following is an example of what a rule file looks like.
<?xml version="1.0" encoding="utf-8"?>
<tzfixup>
  <!-- specify multiple fixupRule's -->
  <fixupRule>
    <!-- if timezone matches any of the criteria, replace with the timezone in <replace> -->
    <!-- specify one or many criteria; each type can be specified multiple times -->
    <match>
      <!-- match the timezone's TZID string -->
      <tzid id="[TZID]"/>

      <!-- match the GMT offset of a timezone that doesn't use daylight savings time -->
      <nonDst offset="[GMT offset in minutes]"/>

      <!-- match DST timezone based on transition rules specified as month and week number + week day -->
      <rules stdoff="[GMT offset in minutes during standard time]"
             dayoff="[GMT offset in minutes during daylight savings time]">
        <standard mon="[1..12]" week="[-1, 1..4]" wkday="[1..7]"/>
        <daylight mon="[1..12]" week="[-1, 1..4]" wkday="[1..7]"/>
        <!-- mon=1 means January, mon=12 means December -->
        <!-- week=-1 means last week of the month -->
        <!-- wkday=1 means Sunday, wkday = 7 means Saturday -->
      </rules>

      <!-- match DST timezone based on transition rules specified as month and day of month -->
      <!-- This case is rare and is typically required only for timezones introduced by past bugs. -->
      <dates stdoff="[GMT offset in minutes during standard time]"
             dayoff="[GMT offset in minutes during daylight savings time]">
        <standard mon="[1..12]" mday="[1..31]"/>
        <daylight mon="[1..12]" mday="[1..31]"/>
        <!-- mon=1 means January, mon=12 means December -->
      </dates>
    </match>

    <!-- timezone matching any of the above criteria is replaced with this timezone -->
    <replace>
      <!-- lookup a well-known timezone from /opt/zimbra/conf/timezones.ics file -->
      <wellKnownTz id="[well-known TZID]">
      OR
      <!-- full timezone definition -->
      <tz id="[custom TZID]" ... />
    </replace>
  </fixupRule>
</tzfixup>
  • The following is an example of a rule file designed to change any existing Pacific time zone to a fictitious one that starts daylight savings time on first Wednesday of April at 5am and ends on the last Saturday of October at 6:30am. Moreover, it uses standard time GMT offset of +3 hours and daylight savings time offset of +4 hours.
 <?xml version="1.0" encoding="utf-8"?>
  <tzfixup>
    <fixupRule>
      <match>
        <tzid id="(GMT-08.00) Pacific Time (US &amp; Canada)"/>
        <rules stdoff="-480" dayoff="-420">
          <standard mon="11" week="1" wkday="1"/>
          <daylight mon="3" week="2" wkday="1"/>
        </rules>
      </match>
      <replace>
        <tz id="FictitiousPacificTime" stdoff="180" dayoff="240">
          <standard mon="10" week="-1" wkday="7" hour="6" min="30" sec="0"/>
          <daylight mon="4" week="1" wkday="4" hour="5" min="0" sec="0"/>
        </tz>
      </replace>
    </fixupRule>
  </tzfixup>


Verified Against: ZCS 5.0.x Date Created: 10/6/2008
Article ID: http://wiki.zimbra.com/index.php?title=Changing_ZCS_Time_Zones Date Modified: 04/15/2010
Personal tools