Accessing Git Repositories with Git LFS (Large File System) via Luminate Secure Access Cloud

Products

• Secure Access Cloud

Issue/Introduction

Accessing Git Repositories with Git LFS (Large File System) via Luminate Secure Access Cloud

Resolution

Hosted Git servers (such as, but not limited to Github Enterprise, Gitlab CE/Enterprise, Atlassian Bitbucket DataCenter) can be accessed in a Zero Trust fashion with Luminate Secure Access Cloud (TM). 

For general description of how to configure such access for a generic git server, please refer to this article. For specific directives regarding Bitbucket DataCenter, please refer here.

Git Large File Storage (Git LFS) is an open-source git extension that aims to improve handling of large files. It does this by replacing large files in LFS-enabled repositories with simple text pointers, storing the files themselves with a separate server (LFS Server). 

(Source: https://git-lfs.github.com/, Licensed under Open Source MIT License)

LFS Server provides a dedicated HTTPS-based interface for storing and retrieving large files. Currently, the LFS Server only supports Basic HTTP Authentication (i.e., User/Password). In order to support secure Zero Trust access to LFS Server with Luminate Secure Access Cloud (TM), configuration steps need to be performed, as described below.

In general, in order to provide full access to hosted Git Server functions, following interfaces should be defined:

• Web Application for an access to Git server Web UI, as described here
• SSH Application or TCP Tunnel Application, for a CLI access to Git repositories, as described here
• TCP Tunnel Application for git lfs client access, as described below

This article explains the principles of configuring LFS access to repositories inside Bitbucket DataCenter server, but the principles can be applied to all hosted git solutions that support LFS. 

 

Step 1 - Enable LFS Support on the Server, Repository

Prior to using Large File System extension, it needs to be enabled by a Bitbucket administrator. This article in Atlassian Bitbucket Server documentation describes how to enable it for a server and for a repository.

While LFS access supports HTTPS, we recommend using HTTP when configuring the access via Luminate Secure Access Cloud (TM). The connectivity will be encrypted all the way from the client machine to the Luminate Connector in the datacenter hosting the git servers, while the performance and the complexity of the configuration are significantly lower. In case of a concern of an open HTTP traffic between Luminate Connectors and git servers in the datacenter exists, we recommend positioning the connectors as close to the servers as possible for improving the performance of large files upload and download.

 

Step 2 - Configure a TCP Tunnel application for the LFS Server

In the Luminate Admin Portal, create a new TCP Tunnel application (in the site where the Web Application(s) and other SSH/TCP applications representing the connection to the git servers are located) with the following details:

The Target Address should be a Domain/IP address of either a proxy/load-balancer providing access to the Bitbucket server nodes or to the server/node directly.

The Target Port should be set to 80 (see a comment for a previous step explaining the rationale for this).

Please make sure to Assign the application to the relevant users/groups and to enable key authentication.

For convenience, we are suggesting to use the word "lfs" in the name of the Tunnel Application (for example, "my-bitbucket-lfs").

 

Step 3 - Configure LFS Client(s) and the relevant repositories 

This step assumes that the client configuration steps described in the generic git access article were already performed and that accessing regular git repositories is possible from the client via Luminate Secure Access Cloud (TM).

This step also assumes that the Git-LFS client was installed and configured, as described here.

In the Luminate Applications Portal, click on the icon of the TCP Tunnel Application defined in the previous step and copy the "command" part. 

It should look like:

ssh -N -L 80:<Internal git or proxy address>:80 [email protected]<application-name>@<application-name>.<luminate-tenant>.luminatesec.com

Please modify the first occurrence of "80" to any local port that should be available on endpoint devices in your environment. For this example, we will use 444. Please note, that this port will need to be used by all git clients in your environment (if you are not sure about the availability of certain ports, we recommend choosing a benign high port).

Also, please add the "-i" argument with the path to the Luminate SSH Key of the user. While this step is optional, without it the user will need to copy-paste the one-time token from the Web UI every time the tunnel is opened.

The eventual command should look like:

ssh -N -L 444:<Internal git or proxy address>:80 -i /path/to/luminate_ssh_key.pem  [email protected]<application-name>@<application-name>.<luminate-tenant>.luminatesec.com

This command needs to be run in the background before any clone, push or pull operations are executed on the repositories with LFS support.

Please verify that the tunnel is established successfully by witnessing the following message:

Authentication succeeded, local ports should be opened...

This command needs to be run in the background before any clone, push or pull operations are executed on the repositories with LFS support. (It might be possible to automate this with git hooks as a possible UX improvement in the future).

In each repository with enabled LFS support, perform the following command-line operations (only once), when located in its directory (assumes that .lfsconfig doesn't exist in the repository):

git config -f .lfsconfig lfs.url http://localhost:444/scm/<path to the repository>/info/lfs

This command instructs the LFS plugin to use an alternative endpoint for upload and download of large files. It is important to commit this change to the repository, simplifying the clone/push/pull operations for all the users. Once the above file is committed, the users will only need to run the port mapping command described above, and all the rest will work transparently. Please note the <path_to_the_repository> should be in the format of repositories in your git server, for example, "/test/lfstest.git".

If the .lfsconfig file already exists in the repository, then following line should be added (or modified, if there already is a definition of url):

[lfs]            url = http://localhost:444/scm/<path_to_the_repository>/info/lfs

After making the changes, please add the .lfsconfig file to git versioning (if it already isn't there), commit and push the changes:

git add .lfsconfig git commit -m “Added LFS Config with Local Tunnel URL” git push origin master

Since the git lfs client works with Basic Authentication, it will request to authenticate with user/password when a clone/pull/push is performed for the first time and will cache the credentials after that.

 

Step 4 - Test The Access

Following routine is suggested that verifying an end-to-end working solution. It assumes an empty repository named "lfstest" to exist on the git server in a project called "test" with LFS support enabled (in the Repository Settings):

git clone ssh://[email protected]<bitbucket-app-name>:7999/test/lfstest.git cd lftest git lfs track ‘*.jpg’ git add .gitattributes git commit -m “add Git LFS to the repo” git push origin master git config -f .lfsconfig lfs.url http://localhost:444/scm/test/lfstest.git/info/lfs git add .lfsconfig git commit -m “Added LFS Config with URL” git push origin master   touch first.jpg echo "This is a file for testing Git LFS" > ./first.jpg git add first.jpg git commit -m “Added first LFS file”   git push origin master cd /tmp git clone ssh://[email protected]<bitbucket-app-name>:7999/test/lfstest.git cd lfstest cat first.jpg

The output should be the content of the first.jpg file, i.e., "This is a file for testing Git LFS".

 

Step 5 (Optional) - Troubleshooting

If one of the Git operations fails, please try running it with tracing enabled in order to see the underlying reasons for failure:

GIT_TRACE=1 git <git command options>

For failed attempts of file upload/download, please verify that the TCP Tunnel command (the one starting with "ssh -L" is running in the background.

If the TCP Tunnel command doesn't show the following: 

Authentication succeeded, local ports should be opened...

Please verify that the user is assigned to the relevant TCP Tunnel application, that the Luminate SSH Key is available