Traditionally, Linux computer systems are installed on a physical or virtual machine, and one of the questions asked during the install is: What time zone is the machine is running in? The installer sets up a link between /etc/localtime
and a time zone file. On my Fedora machine, I see the following link:
$ ls -l /etc/localtime
lrwxrwxrwx. 1 root root 38 Feb 29 13:11 /etc/localtime -> ../usr/share/zoneinfo/America/New_York
When you ask the system what time it is, the glibc
library reads this link to display the time based on the time zone.
$ date
Tue 11 Aug 2020 03:57:43 PM EDT
If I force a change to this file to point at Japan, the way the date is reported changes:
$ ln -fs ../usr/share/zoneinfo/Japan /etc/localtime
$ date
Wed 12 Aug 2020 04:58:59 AM JST
Problem: Container images have an embedded time zone
When container engines like Podman, Docker, or CRI-O run containers, they pull down the specified OCI image from a container registry. This image is built with a hardcoded link from /etc/localtime
to one time zone. Usually, the time zone is set to the location where the image or base image was built, or to UTC±00:00. There is no installation process to modify the time zone. Once the image is pulled, the container engine just launches the container based on the hardcoded time zone. This means that your container running in Tokyo could be reporting that it is running in New York City, depending on where the image was built.
Users have attempted to fix this by mounting the time zone file from the host into the container or by adding an environment variable like TZ=jst
. These attempts have caused problems since the /etc/localtime
file is often a symbolic link and may not do what the user expects. The TZ environment variable is also a problem since not all services pay attention to the variable, causing users to become confused due to different outcomes to the same setting. For example, Fedora images accept the environment variable, while Alpine images ignore it entirely.
Additionally, some time zones even share the same abbreviation, such as CST standing both for Central Standard time (in the US) and China Standard time. Given all that, there was no easy way to change the system to cause ALL containers to use the desired time zone.
Podman (2.1) adds the --tz flag
The --tz
flag takes IANA time zones as well as local
. The reserved word local
sets the time zone to match your host machine's time zone.
Taking a look at the podman-run man page, we can see the new --tz
option:
$ man podman-run
…
--tz=time zone
Set a time zone in the container. This flag takes area-based time zones, GMT, as well as local, which sets the time zone in the container to match the host machine. See /usr/share/zoneinfo/ for valid time zones.
And here are some examples of it in action:
$ date
Tue Aug 11 16:48:10 EDT 2020
$ podman run --tz=local alpine date
Tue Aug 11 16:48:27 EDT 2020
$ podman run --tz=Asia/Shanghai alpine date
Wed Aug 12 04:48:42 CST 2020
$ podman run --tz=US/Eastern alpine date
Tue Aug 11 16:48:47 EDT 2020
This flag is also available in the podman create
command.
How does it work?
Setting a time zone works the same on rootful and rootless containers. Functionally, the time zone flag mounts a copy of your specified time zone file found in /usr/share/zoneinfo
as /etc/localtime
, thus setting the time zone in the container. If the specified time zone is local
(or happens to be a symlink, as some time zone files are simply a symlink to another file), the flag follows the symlink and mounts the pointed-to file. This solves the symlink and environment variable problems that users may have previously encountered. The time zone setting is permanent for the life of the container.
I don't want to specify this flag for every container I run?
Administrators and users can set a system-wide default time zone for all of their containers using containers.conf
. This ensures that every container created on your system has the specified time zone set unless overridden by the command line. Setting the time zone within containers.conf i
s helpful if you want to consistently make containers with the same time zone, alleviating the need to use the flag every time a container is created or run.
$ cat $HOME/.config/containers/containers.conf
[containers]
# Set time zone in container. Takes IANA time zones as well as "local",
# which sets the time zone in the container to match the host machine.
#
tz = "Europe/London"
$ podman run alpine date
Tue Aug 11 21:54:21 BST 2020
Note: containers.conf
is located at /usr/share/containers/containers.conf
and /etc/containers/containers.conf
for rootful mode and at $HOME/.config/containers/containers.conf
for rootless mode.
Conclusion
The time zone flag makes it easy and foolproof to set the time in a container to your personal needs, without fussing with mounts, symlinks, and environment variables. Setting a time zone in containers.conf
allows you to "set it and forget it" for all of your containers.
Now go on your merry way and travel the world: all within your container.
[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]
About the author
Ashley Cui is a software engineer at Red Hat, working on Podman, Buildah, and other container tools.
Browse by channel
Automation
The latest on IT automation for tech, teams, and environments
Artificial intelligence
Updates on the platforms that free customers to run AI workloads anywhere
Open hybrid cloud
Explore how we build a more flexible future with hybrid cloud
Security
The latest on how we reduce risks across environments and technologies
Edge computing
Updates on the platforms that simplify operations at the edge
Infrastructure
The latest on the world’s leading enterprise Linux platform
Applications
Inside our solutions to the toughest application challenges
Original shows
Entertaining stories from the makers and leaders in enterprise tech
Products
- Red Hat Enterprise Linux
- Red Hat OpenShift
- Red Hat Ansible Automation Platform
- Cloud services
- See all products
Tools
- Training and certification
- My account
- Customer support
- Developer resources
- Find a partner
- Red Hat Ecosystem Catalog
- Red Hat value calculator
- Documentation
Try, buy, & sell
Communicate
About Red Hat
We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.
Select a language
Red Hat legal and privacy links
- About Red Hat
- Jobs
- Events
- Locations
- Contact Red Hat
- Red Hat Blog
- Diversity, equity, and inclusion
- Cool Stuff Store
- Red Hat Summit