Red Hat Developer Program

The JBoss Tools OpenShift tooling uses rsync to sync files between your local workstation and the running pods on an OpenShift cluster. This is used by the OpenShift server adapter to provide hot deploy and debugging features for the developer. If you’re running Red Hat JBoss Developer Studio or JBoss Tools on Windows, there are some issues with file permissions that can be painful. These problems are due to file permission model used on the underlying Windows filesystem being different than the model used by Linux. Linux and macOS users won't run into these problems. The aim of this article is to explain the root cause and how to fix it.

The problem

The OpenShift tooling uses rsync to synchronize local changes to your project to remote pods running on an OpenShift cluster. The problem on Windows is that rsync is very Linux/UNIX based and by default, it tries to map ownership/permissions of files between the two platforms. As the Windows file ownership and permission model using ACLs is totally different from the Linux model, it can lead to strange permissions being set on your files. This can cause some failures when trying to update those files.

It’s possible to prevent rsync from synchronizing file ownership and permissions using some rsync flags. Unfortunately, rsync is launched through the help of the OpenShift oc client which does not allow you to pass in the necessary flags.

The solution

On Windows, rsync (and other Linux utilities) are available from several sources. The well known ones are Cygwin and cwRsync.  cwRsync is based on Cygwin, but adds additional features for Windows. The solution below is for Cygwin. This might not work for other sources of rsync for Windows. If you aren't using Cygwin, or something based on Cygwin, check the documentation on path mapping for your distribution.

To use Linux-based utilities like rsync on Windows, a mapping between Windows paths (C:\ based) and Linux/UNIX paths are needed. For Cygwin, the mapping is controlled through a file called /etc/fstab. The solution that we are proposing here is to instruct Cygwin not to map ownership and permissions at this level. Please note that this file may not be present, so you may need to create it.

How to locate etc/fstab on your system

The fstab file is usually located in the etc directory of the cygwin/rsync distribution, while rsync itself is located in bin. The default installation for Cygwin is typically C:\cygwin, so rsync.exe will be in C:\cygwin\bin and fstab will be in C:\cygwin\etc.  One quick way to find the location where you've installed Cygwin or cwRsync is to open a Windows command shell (cmd) and type the following command to see where your system is finding rsync:

where rsync.exe

This will give you the path to the rsync.exe executable.. It has the general form of <some path>\bin\rsync.exe. The path before \bin\rsync is the installation directory for cygwin or cwRsync on your system. I will refer to that path as $MY_RSYNC_DIST_DIR.

The fstab file is located at $MY_RSYNC_DIST_DIR/etc/fstab.

Updating etc/fstab

If the file already exists, then you probably have a line similar to the following:

none /cygdrive cygdrive binary,posix=0,user 0 0

So, just add the noacl flag to the list of options. Also, make sure the line isn't commented out.  The example fstab included with Cygwin has the above line, but it is commented out with a '#'.  When you are done you should have the following line in etc/fstab:

none /cygdrive cygdrive binary,posix=0,user,noacl 0 0

 

If you distribution doesn't have an fstab file, which is typical for cwRsync, that is easily fixed. Ccreate the file at $MY_RSYNC_DIST_DIR/etc/fstab and paste the following content:

# /etc/fstab
#
#    This file is read once by the first process in a Cygwin process tree.
#    To pick up changes, restart all Cygwin processes.  For a description
#    see https://cygwin.com/cygwin-ug-net/using.html#mount-table
#
none /cygdrive cygdrive binary,posix=0,user,noacl 0 0

Save the file, you’re done.  Now you should no longer run into permission errors during rsync operations !!!.

Last updated: November 9, 2023