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
--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
$ 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
/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 is 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
containers.conf is located at
/etc/containers/containers.conf for rootful mode and at
$HOME/.config/containers/containers.conf for rootless mode.
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. ]