Timezone Updater Tool

Introduction

The TZUpdater tool is provided to allow you to update installed Java Development Kit (JDK) and Java Runtime Environment (JRE) software with more recent timezone data, to accommodate daylight saving time (DST) changes in different countries. Oracle relies on the timezone data publicly available through IANA's Time Zone Database.

Oracle recommends that you use the latest Oracle Java SE platform JDK or JRE update release as the preferred means of delivering both timezone data updates and other product improvements, such as security fixes. To see which JDK or JRE update release incorporates the updated timezone data for your locale, see Timezone Data Versions in the Java Runtime. However, if you are unable to use Oracle's latest JDK or JRE update release or if the timezone data on the latest release is not the most current one available, the TZUpdater tool provides a means of updating timezone data while leaving other system configuration and dependencies unchanged.

System Requirements

The TZUpdater tool supports all currently supported versions of the JDK. Prior to version 2.3.1, the tool only worked on Oracle binaries.

Download

A version of TZUpdater tool for updating the current version of Oracle’s Java Runtime Environment is available in Java SE TZUpdater Downloads.

Support customers can download a TZUpdater tool for older versions through Supported Java SE and Java Component Downloads on MOS (Doc ID 1439822.2).

Usage

The TZUpdater tool modifies the JDK/JRE software instance that is used to execute the tool. A single image of the JDK/JRE software is modified per execution. To administer the tool to multiple instances of the JDK/JRE software, see the section Systemwide Usage.

You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image.

Run the TZUpdater tool with the following command:

java -jar tzupdater.jar options

To update timezone data successfully, you should ensure that you have sufficient privileges to modify the JDK_HOME/jre/lib or JRE_HOME/lib directory. If you do not have sufficient privileges to modify these directories, contact your system administrator.

Options

If you do not specify any options, the usage message is displayed. To update the timezone data, use either the -l or the -f option.

Error Handling

The tool tries to restore the original state when it has encountered an unexpected error, such as lack of disk space.

Reporting Problems Against TZUpdater

If a user wishes to raise an issue against TZUpdater, please file a bug at https://bugs.java.com.

Tool Updates

• 2.3.3 Bug Fix

  • JDK-8339645: (tzupdater) Improve parsing of Day/Month in tzdata rules

  • JDK-8340873: (tzupdater) Acknowledge case insensitive unambiguous keywords in tzdata files

• 2.3.2 Bug Fix

  • JDK-8254226: tzupdater2.3.1 is broken with tzdata2020b

• 2.3.1 Enhancement/Bug Fix

  • JDK-8245460: Allow all JDK vendors to work with TZUpdater

    Removed restriction of letting TZUpdater update only Oracle JDK binaries. The TZUpdater tool now allows updates to any JDK binary.

  • JDK-8245950: TZUpdater cannot update to tzdata2020a for JDK 7u

• 2.3.0 Enhancements

  • The 2.3.0 release now supports the vanguard tzdata format which has not been supported since tzdata2018e. The following are the related bug fixes:

  • JDK-8230554: TZUpdater support for "vanguard" format (JSR-310 part only)

  • JDK-8229818: Add workaround to TZUpdater for converting tzdata files from vanguard to rearguard (JDK 7u only)

    TZUpdater tool usage for JDK 7u only has a workaround that involves translating vanguard to rearguard format before computation of javazic data sources.

    A new TZUpdater property, tzupdater.forceUseOfVanguard, is introduced as a fallback option if the TZUpdater fails due to unforeseen circumstances.

    The new TZUpdater property can be enabled by setting:

    -Dtzupdater.forceUseOfVanguard=true

• 2.2.0 Bug Fix
  • JDK-8194474 (not public): Remove use of security digest calculations from tzupdater
    The IANA website now provides https functionality to allow secure downloading of tzdata resource bundles. As a result, the SHA-512 digest calculations (and hosted files) for tzdata bundle downloads are no longer required.

  • JDK-8203908 : TZUpdater tool fails to print version info for the users without write permission

• 2.1.2 Bug Fix

  • Updated the protocol used for connecting to IANA for downloading the latest time-zone information to match recent changes in the IANA sites.

  • JDK-8193405 (not public): tzupdater.jar --version fails to correctly display latest version

• 2.1.1 Bug Fix

  • JDK-8166928: TZupdater failing with tzdata2016g release due to missing version information

• 2.1 Enhancements

  • -u Option Removed

    Use the -l option to update data. For information on this option and other options available, pass the -h option to the tool as shown in the following example:

    java -jar tzupdater.jar -h

  • The tzupdater.jar file is digitally signed. Use the following command to verify the signature: jarsigner -verify -verbose -certs tzupdater.jar

• 2.0.3 Bug Fix

  • JDK-8151879: TZupdater not able to update with tzdata2016b release

• 2.0.2 Bug Fix

  • JDK-8149811: TZUpdater tool removes PST timezone from Java 7

• 2.0 Enhancements

  • New TZUpdater Functionality: Updating Timezones On Demand

    Starting with version 2.0, the -l option allows the user to point to the IANA repositories and get the tool to compile the latest tzdata sources on demand.

    The tool also references a https resource website for SHA-512 hash values if the -l option is specified with a http or https protocol.

    For this reason, any environment which operates with proxy access, will need to set the http and https proxy values while running the tool.

    HTTP: -Dhttp.proxyHost, -Dhttp.proxyPort HTTPS : -Dhttps.proxyHost, -Dhttps.proxyPort

    If the tool is unable to connect to the specified resource, a socket exception will be thrown:

    Network issue while connecting to http resource. Please reference tzupdater README.

    Automatic SHA-512 hash checks will be performed on the downloaded tzdata bundle for integrity verification. If the SHA-512 hash value does not match expectations, the tool will exit.

Overriding the SHA-512 Hash Checks (Not Applicable for TZupdater version 2.2.0 and above)

There may be some situations where a new tzdata release is available but Oracle has not yet updated the https resource website with the new SHA-512 hash value.

In such cases, the user will see the following exception message:

No SHA-512 hash file found: https://javadl-esd-secure.oracle.com/update/tzupdater/tzdata2014a.tar.gz.sha512. If using http(s) resource location, the file may not yet be available. Please reference tzupdater README

The user, in such a case, has the option to use the file:// protocol with the new -l option where they can specify their own local SHA-512 hash value:

1. Download a copy of the desired tzdata.tar.gz bundle to a local directory.
2. Calculate the SHA-512 hash for that tar.gz bundle and create a one-line file in the same local directory that contains this SHA-512 hash value. The file name must have ".sha512" appended to the original name of the bundle containing the tzdata rules.

   For example, if you downloaded tzdata2014a.tar.gz to a local directory, then a file named tzdata2014a.tar.gz.sha512 must also exist in the same directory and must contain the SHA-512 hash value that corresponds to the tzdata2014a.tar.gz file.

3. Use the file:// protocol to apply the new timezone data. For example, if you downloaded tzdata2014a.tar.gz to the /tmp directory and created the necessary /tmp/tzdata2014a.tar.gz.sha512 file that contains the one-line sha512 hash value, the following command can be used to run the tzdata update:

   java -jar tzupdater.jar -l file:///tmp/tzdata2014a.tar.gz

   Add the -v option for verbose output.

Known Restrictions

The tool has a few restrictions due to the TimeZone API and implementation constraints.

• Timezone display names: This tool will not update display names of timezones that are completely new or have display name-related changes. Full support of all timezone display names requires installation of the latest Oracle Java SE platform JDK/JRE update release.,/p>

• Systemwide Usage: You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image. It is possible for systems to accrete multiple copies of JDK/JRE software images, so you might need to apply the tool individually to each JDK/JRE software image. Locating multiple installed copies of the JDK/JRE software on Unix derivative systems is shown below. Microsoft Windows users can use the desktop search utility.

  • Find locally installed JDK/JRE software instances for Unix-derived systems:

    /usr/bin/find DIRPATH -fstype nfs -prune -o -fstype autofs -prune -o -name java -print -exec {} -version \;

    DIRPATH is a directory path to search under for installed instances of the Java SE platform, for example, /usr.

  • Automate updating of locally installed instances:

    /usr/bin/find DIRPATH -fstype nfs -prune -o -fstype autofs -prune -o -name java -print -exec {} -jar / ABSOLUTEPATH/tzupdater.jar -l \;

    DIRPATH is a directory path to search under for installed instances of the Java SE platform, for example, /usr. Replace ABSOLUTEPATH with the full path name to the directory into which tzupdater.jar is expanded.

• Restrictive umask settings on Solaris: The TZUpdater tool creates files with default file permissions. On the Solaris operating system, this is taken from the umask . A default umask of 022 should be used for running the TZudpater tool. A more restrictive umask such as umask 077 will mean files created by the tool are unreadable by other users.

System-Specific Installation Information

TZUpdater is a pure Java tool that does not address platform-specific software management issues. For example, on a Windows system, this means that the additional and backup files created by the tool will not be removed during an uninstall. To uninstall updated JRE software, check the JRE software's install directory and remove it manually once the uninstaller completes.

For Solaris systems, where the JRE software being updated exists as a Solaris package (such as in /usr/j2se or /usr/jdk/ instances), this has meant that the pkgchk command would highlight the changes as errors or inconsistencies. Starting with version 1.1.0 of TZUpdater, the tool runs an additional series of package management commands that updates the package database where appropriate.

On a Solaris 10 system where existing package-based JRE software has been updated by the initial release of TZUpdater, and zones have been created, the zones will contain the same pkgchk errors as the global zone. During zone creation, these pkgchk errors will be highlighted at the end of the zone installation command.

To resolve Solaris package database errors, take the following steps. However, if you are not running on a Solaris 10 system or your system does not have zones, only step 1 is required. If the system is a Solaris 10 system with additional zones, run step 1 only in the global zone and follow steps 2 and 3.

1. Run the current version of TZUpdater, with the -f force option to reapply the timezone update to a previously updated JRE software instance. The update will take place, and the additional package resolution commands will be executed. The update must be executed as the root user and is relevant to the global zone only in a Solaris 10 system.
2. For systems with zones, unpack the pkg_resolve.sh script from the tzupdater.jar file:

   /bin/jar xf tzupdater.jar pkg_resolve.sh

3. In the zones where there is a package-based Java platform installation, execute the script. You must run the script as root:

   /bin/ksh ./pkg_resolve.sh JAVA_PATH

   For example:

   /bin/ksh ./pkg_resolve.sh /usr/jdk/instances/jdk1.8.0/bin/java

NOTE: The update to the package system removes many files from the package database and reinserts them, so it can take up to 15 minutes.

Removing TZUpdater Tool Changes

You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image.

There is currently no option to remove TZUpdater modifications. By following the following steps, you can manually remove the modifications made by the current TZUpdater tool.

For JDK 8 and later family versions:

1. Locate the 'tzdb.dat' file under the modified JAVAHOME/jre/lib directory. This is the newer data file.
2. Locate the 'tzdb.dat.<oldtzdataversion>' file in the same JAVAHOME/jre/lib directory. This is the replaced, older data file.
3. Obtain the currently installed timezone data version from the following command:

   java -jar tzupdater.jar -V

4. Rename the current 'tzdb.dat' file to something like 'tzdb.dat.<newtzdataversion>', or whatever version was given by the command in step 3. Ensure this name does not conflict with the older data files.
5. Rename the older data file to 'tzdb.dat'.
6. Validate the change in currently active timezone data by executing the following:

   java -jar tzupdater.jar -V

7. Restart applications on this JDK/JRE instance as desired.

For JDK 7 and earlier family versions:

1. Locate the 'zi' directory under the modified JAVAHOME/jre/lib directory. This is the newer data file.
2. Locate a 'zi.tzdata*' directory in the same JAVAHOME/jre/lib directory. This is the replaced, older data.
3. Obtain the currently installed timezone data version from the following command:

   java -jar tzupdater.jar -V

4. Rename the current 'zi' directory to something like 'zi.tzdata2016b', or whatever version was given by the command in step 3. Ensure this does not conflict with the older data directory.
5. Rename the older data directory to 'zi'.
6. Validate the change in currently active timezone data by executing the following:

   java -jar tzupdater.jar -V

7. Restart applications on this JDK/JRE instance as desired.

For More Information

The following links point to information provided by Oracle relating to timezones and DST changes and how they affect the Java platform and other Oracle products:

• Timezones, Daylight Savings, and the TZupdater for the Java Runtime Environment (JRE)
• Timezones and the Java Runtime Environment: Frequently Asked Questions
• Timezone Data Versions in the Java Runtime

The following external links provide general information about timezones and DST:

• What Is Daylight Saving Time?
• Time Zone Database from the Internet Assigned Numbers Authority (IANA) webpage
• Wikipedia: Daylight Saving Time
• Wikipedia: tz database