{"id":633,"date":"2013-05-27T12:22:16","date_gmt":"2013-05-27T10:22:16","guid":{"rendered":"http:\/\/www.nubaria.com\/en\/blog\/?p=633"},"modified":"2014-09-13T11:49:18","modified_gmt":"2014-09-13T09:49:18","slug":"setting-up-a-central-git-repository-on-a-windows-server","status":"publish","type":"post","link":"http:\/\/www.nubaria.com\/en\/blog\/?p=633","title":{"rendered":"Setting up a central Git repository on a Windows server"},"content":{"rendered":"

In one of the first posts I wrote when I started this blog I tried to give a general overview of Git<\/a>, which has quickly become probably the most successful version control system in current use, especially in new and open-source projects. I’ve been a regular Git user since the time when I wrote that post, and recently I found myself in a situation where I had to set up a Git repository for a client on a computer running Windows Server 2003, which I would have to access through the Internet. What I initially thought would be a pretty straightforward task turned out to be much harder than I expected. To begin with, Git repositories with remote access are mostly set up on computers running Linux, where things are considerably simpler. This is due to the fact that Linux offers much better support for the SSH protocol that Git uses. When one searches the web for information, it’s hard to find good documentation about how to set Git up for remote access on Windows, and some of the resources I found were often not completely reliable. Spiked by the challenge and all the troubles I bumped into, I’ve decided to write down a quick guide of all the steps for my future reference and share it here just in case others may find it useful too. If you find anything inaccurate or just feel like commenting or sharing any additional information on this topic, please don’t hesitate to use the comments area below.<\/p>\n

<\/p>\n

1. The Proposed Workflow<\/h2>\n

As a peer-to-peer system, Git is very flexible in allowing a lot of different workflows. Scott Chacon’s seminal book on Git has a chapter, Distributed Workflows<\/a>, that briefly goes through some of the likely workflows that we may come across in real-life projects. The workflow I’m interested in is the first one Chacon describes: the \u2018centralised workflow\u2019, which consists in a bare repository sitting on a server computer. Such a central repository should regularly be backed up, and a number of developers will sync the code on their computers with it.<\/p>\n

So, basically, what I intend to do is set up a Git bare repository (the \u2018shared repository\u2019) on a server computer running Windows which is connected to the Internet and which only authorised users can access through their Git clients.<\/p>\n

The steps I describe in this post can actually be generalised to any other workflow. It would simply be a matter of treating as a \u2018server\u2019 any computer that must allow pulling changes from it and as a \u2018client\u2019 any computer which pulls and pushes changes from the others.<\/p>\n

2. The Server: Setting Up a User Account for Development Tasks<\/h2>\n

Before setting up the SSH server and the Git repository we will need to create a new user account in Windows with administrator rights [Edit 13 Sep 2014<\/strong>: Actually, as suggested in one of the comments below, a regular user account may be enough for this]<\/strong><\/em>. While it is not strictly necessary to create a new account for this, we will need a user account to open the SSH connections for Git communication, and having a specific user account for this can help administration and logging tasks.<\/p>\n

On my server computer running Windows Server 2003, I’ve opened up Control Panel<\/em>\/Computer Management<\/em>\/System Tools<\/em>\/Local Users and Groups<\/em>\/Users<\/em> (the actual names may vary depending on Windows version and localisation) and I’ve created a new administrative account with the user name \u2018dev\u2019.<\/p>\n

3. The Server: Choosing and Installing SSH Software<\/h2>\n

Remote communication in Git is handled by means of the Secure Shell (SSH) protocol<\/a>. There are two other protocols that can be used, HTTP and Git’s own protocol, but these are more limited in use. If we want full access to the remote repository with user authentication, then SSH becomes the only option. When we install Git for Windows we get an SSH client bundled with the Git program, but we will need to set up an SSH server on the computer that hosts the central shared repository, which must listen to connections on the SSH port (by default 22). Unlike the situation in both Linux and Mac OS X, there is no default SSH server coming with Windows out of the box, so we need to install one.<\/p>\n

The problem is that it is not easy to choose between the available options. Right now (May 2013) there are several SSH products for Windows available but the licencing conditions can be tricky. The Wikipedia article Comparison of SSH Servers<\/a> contains a handy list of SSH software. That list reveals that there aren’t many options available. There is also a stackoverflow thread on SSH servers for Windows<\/a> that offers some information and useful comments about the various possibilities.<\/p>\n

The first option I considered was to install Cygwin<\/a>, a distribution of a variety of Linux tools for use under Windows, and run OpenSSH<\/a> on top of Cygwin. This would replicate the standard setup of SSH on a Linux system. I thought about this possibility, but Cygwin is pretty massive and since I only needed an SSH server, I decided it would make more sense to find an option that integrates with Windows better, rather than trying to replicate a whole Linux universe on the Windows machine. This led me to two commercial products WinSSHd<\/a> (now rebranded as “Bitvise SSH Server”) and Copssh<\/a>. I didn’t want to pay, if possible, so these two tools didn’t look like an optimal solution for me. But it turns out that CopSSH used to be free and the old free version is still available with a GNU General Public Licence. The more recent versions cost money and have more features, but since what I need server-side is something very simple just to use it with Git, this old free version is fine. Note that CopSSH uses Cygwin and OpenSSH internally, but it only installs a small subset of the whole thing and the installation is pretty straightforward. If I hadn’t found this free version, I’d probably have gone the Cygwin+OpenSSH route, but using CopSSH has made things easier [Edit 13 Sep 2014<\/strong>: The situation is different in 2014. The older CopSSH 3.1.4 is no longer offered on the Itefix website (reasonably enough, as old versions of security software will inevitably have known vulnerabilities), and there are new versions of the software, including a free one (see below). As the situation regarding SSH software for Windows may continue to evolve, I recommend that anyone reading this check the characteristics and licencing\/pricing information of the available SSH products]<\/strong><\/em>.<\/p>\n

So, the first thing to do on the machine that will act as a server is to download and install this software:<\/p>\n

1.<\/strong> Download the free version of CopSSH 3.1.4. At the time of writing it is available at the CopSSH website: https:\/\/www.itefix.no\/i2\/content\/copssh-free-edition<\/del> [Edit 13 Sep 2014<\/strong>: As mentioned above, the older free edition of CopSSH that I used is no longer available. The newer version can be downloaded from https:\/\/www.itefix.net\/content\/copssh-free-edition<\/a>. I haven’t got round to using it, so I’ve left the rest of this article unedited with the original references to the older 3.1.4 version. Anyway, the steps to follow should be similar.]<\/strong><\/em>.<\/p>\n

2.<\/strong> Unzip the installer and run it.<\/p>\n

\n\"The\n<\/div>\n

3.<\/strong> The installer suggests a user account under which the Windows service will run. Rather than letting the installer create a new user account, I have entered the \u2018dev\u2019 user name and the password that I set up before (section 1).<\/p>\n

\n\"The\n<\/div>\n

4.<\/strong> When the installation is complete, the installation wizard informs you that you will need to activate a user for the newly-created SSH server:<\/p>\n

\n\"The\n<\/div>\n

5.<\/strong> In the Windows Start menu there is now a \u2018Copssh\u2019 folder with several entries. Select the \u201801. Activate User\u2019 option and in the dialog that appears uncheck the options (unless you know what you’re doing and need any of that) and enter the user name that we’ve created before:<\/p>\n

\n\"The\n<\/div>\n

Note that you may need to include a domain with the user name, like \u2018DOMAIN\\dev\u2019.<\/p>\n

Once CopSSH has been installed, the SSH server should be running as a Windows service. Let’s check this.<\/p>\n

6.<\/strong> Open the \u2018Services\u2019 dialog (under \u2018Administrative Tools\u2019) and check that there is an entry \u2018Openssh SSHD\u2019. It should appear as \u2018Started\u2019 (or the equivalent localised term like Spanish \u2018Iniciado\u2019 in my screenshot):<\/p>\n

\n\"The\n<\/div>\n

4. The Server: Configuring the SSH Settings<\/h2>\n

Now that the SSH server is up and running, we need to review its settings. The underlying OpenSSH implementation that CopSSh uses has two configuration files in the etc<\/em> directory. If you’ve installed CopSSH in the default location, you’ll need to open C:\\Program Files\\ICW<\/em> (or C:\\Program Files(x86)\\ICW<\/em> on 64-bit editions of Windows). There you will find an etc<\/em> directory. There are two configuration files there: ssh_config<\/em> and sshd_config<\/em>. The first one affects the ssh.exe<\/em> program and the second one the daemon version sshd.exe<\/em>. We will make our changes in both files to avoid any mismatches between the two.<\/p>\n

There are two settings we might want to change. First, the SSH software supports both authentication with cryptographic keys and with a plain combination of a user name and a password. Authentication with keys is much more secure. Because of that, we will disable password-based authentication.<\/p>\n

A second setting you may want to change is the port used for the SSH traffic. The default port for SSH is port 22, but if you prefer to use another one, now is the time to change it.<\/p>\n

7.<\/strong> In a text editor like Notepad++ (plain Notepad has problems with the Linux-style line feeds), open up the C:\/Program Files [(x86)]\/ICW\/etc\/ssh_config file. The default settings appear as commented-out lines starting with \u2018#\u2019. We will need to edit the PasswordAuthentication<\/code> option (line 25) by uncommenting it and setting it to no<\/code>:<\/p>\n

[...]
\n   PasswordAuthentication no
\n[...]<\/code><\/p>\n

Similarly, you would edit the #Port 22<\/code> line if you want to use a different port number.<\/p>\n

8.<\/strong> In a text editor, open up the C:\/Program Files [(x86)]\/ICW\/etc\/sshd_config file and set the PasswordAuthentication<\/code> option (line 61) to no<\/code>:<\/p>\n

[...]
\nPasswordAuthentication no
\n[...]<\/code><\/p>\n

Again, if you’re changing the port number you should also look for the Port<\/code> option and edit it.<\/p>\n

5. The Server: Establishing a Home Directory<\/h2>\n

By default, the SSH server will treat the user directory dev<\/em> as its home directory. We may want to change this to a different location, like C:\\repositories<\/em>. The home directory is specified in the passwd<\/em> configuration file. Note that some SSH implementations rely on a \u2018HOME\u2019 environment variable to query the home path, but Copssh doesn’t seem to support this, so editing the passwd<\/em> file is apparently the only way of customising the home path.<\/p>\n

9.<\/strong> In a text editor, open up the C:\/Program Files [(x86)]\/ICW\/etc\/passwd file. The last line should be something like the following:<\/p>\n

dev:unused_by_nt\/2000\/xp:0000:000:U-DOMAIN\\dev,s-1-0-00-000000000-0000000000-0000:\/home\/dev:\/bin\/bash<\/code><\/p>\n

10.<\/strong> Edit the last line in the passwd<\/em> file, replacing \/home\/dev<\/em> with the home path for the Git repositories. Forward slashes must be used as directory separators and drive units like C:\\<\/em> must be replaced with \/cygdrive\/C\/<\/em>. If the home directory we want is C:\\repositories<\/em> then:<\/p>\n

dev:unused_by_nt\/2000\/xp:0000:000:U-DOMAIN\\dev,s-1-0-00-000000000-0000000000-0000:\/cygdrive\/C\/repositories<\/strong>:\/bin\/bash<\/code><\/p>\n

11.<\/strong> Save the passwd<\/em> file and close it.<\/p>\n

12.<\/strong> In the home directory we will have to create a directory with the name .ssh<\/em>. It may be tricky to get Windows to create a directory with a name starting with \u2018.\u2019 so the easiest way is to open a command console and type:<\/p>\n

cd C:\\repositories
\nmkdir .ssh<\/code><\/p>\n

13.<\/strong> In the .ssh<\/em> directory create an empty text file with the name authorized_keys<\/em>. We will edit it later.<\/p>\n

6. The Client Computer: Creating a Cryptographic Key Pair for Authentication<\/h2>\n

We want to be able to authenticate the client when it connects to the server. This will be done through public-key authentication (much safer than a user\/password combination), which requires that the client generate a pair of cryptographic keys and makes its public key known to the server. Let’s do this now.<\/p>\n

I will assume that the client computer is also running Windows (Windows 7 in my tests), and I am going to use the free and open-source software PuTTY as an SSH client and also as a tool for key generation.<\/p>\n

14.<\/strong> On the client computer, download and install PuTTY (http:\/\/www.chiark.greenend.org.uk\/~sgtatham\/putty\/download.html<\/a>).<\/p>\n

15.<\/strong> Open up the PuTTYgen program that comes bundled with PuTTY (you’ll find it under the Start\/All Programs\/PuTTY<\/em> menu) and click the \u2018Generate\u2019 button:<\/p>\n

\n\"The\n<\/div>\n

After clicking \u2018Generate\u2019 you’ll need to move the mouse over the dialog in order to generate some randomness. That will ensure that the newly-created cryptographic keys are secure.<\/p>\n

16.<\/strong> Once the keys have been generated, type a passphrase to encrypt the private key and click the \u2018Save private key\u2019 button. You’re then prompted to save it to disk. I saved it as C:\\ssh_keys\\git_access_key.ppk<\/em>.<\/p>\n

What we have saved to disk in the .ppk file is a cryptographic private<\/em> key that we must not give to anyone. It must stay within the client computer. What we will need to copy to the server is the public<\/em> key, which is not a secret at all and can be visible to others. The public key is what the server needs in order to verify that the data connection can only come from a client that has the matching private key. Note that we don’t need to save the public key to any file since it can be recalculated from the private key whenever it is needed. We’d simply load the private-key file with PuTTYgen if we need to check the generated public key again.<\/p>\n

So, we now need to copy that public key to the server.<\/p>\n

17.<\/strong> Select and copy the public-key text that appears in the field \u2018Public key for pasting into OpenSSH authorized_keys file\u2019. You can customise the \u2018Key comment\u2019 field with a descriptive comment.<\/p>\n

\n\"The\n<\/div>\n

18.<\/strong> Paste the public-key text into an e-mail or a text file that you can later open from the server (remember, again, that this is the public<\/em> key so it doesn’t matter if we’re sending it over through a communication channel that is not particularly secure). In a test of mine, this was:<\/p>\n

ssh-rsa<\/span> AAAAB3NzaC1yc2EAAAABJQAAAIEAlOISku1zWfUfhhpy2gtgWOboHqjdSz3WO+c+l9zEvD8
\nLzlrbn8eYxxo9H69lPRUuRIb6RpzYNq3ISU9uROEv\/ZuTH6dSzL3zJHcE4uiFd6gNdi27LsEYSq1LV9
\nmaRE4osQz0u\/P4VbmR+6lCylaaTD9AQMDSI9T0yKhwx47uI2E<\/span>=<\/span> Public key from A. Developer’s laptop<\/span><\/p>\n

The blue string is the actual public key, but we’ll need to paste the whole thing into the authorized_keys<\/em> file on the server. <\/p>\n

7. The Server: Registering the Client’s Public Key<\/h2>\n

Now we need to access the public key that we generated client-side and authorise it on the server machine.<\/p>\n

19.<\/strong> On the server computer, open the e-mail or the text file where the public-key text was stored and copy it.<\/p>\n

20.<\/strong> Open the C:\\repositories\\.ssh\\authorized_keys<\/em> file in a text editor and paste the whole line beginning with \u2018ssh-rsa\u2019 and ending with the custom comment, without line breaks.<\/p>\n

21.<\/strong> Save the file.<\/p>\n

8. The Client Computer: Testing the SSH Connection<\/h2>\n

Now we can test that the SSH connection can be established correctly from the client computer where we generated the cryptographic key pair.<\/p>\n

22.<\/strong> On the client machine, open up PuTTY and in the \u2018Session\u2019 category enter the IP or the URL of the server and make sure that SSH is selected as the \u2018Connection Type\u2019.<\/p>\n

23.<\/strong> On the left-hand tree view of categories select \u2018Connection\u2019\/\u2018SSH\u2019\/\u2018Auth\u2019 and enter the path of the .ppk file you’ve saved as the \u2018Private key file for authentication\u2019:<\/p>\n

\n\"The\n<\/div>\n

24.<\/strong> Click \u2018Open\u2019.<\/p>\n

25.<\/strong> A \u2018PuTTY Security Alert\u2019 appears telling us that the server we’re connecting to is unknown. Hit \u2018OK\u2019 so that the remote machine will be cached as a known server from now on.<\/p>\n

26.<\/strong> A PuTTY connection console opens up and prompts us to enter a user name. Type \u2018dev\u2019 (or whatever Windows account name you chose in step 1 above).<\/p>\n

27.<\/strong> The connection console should display the message \u2018Authenticating with public key\u2019 followed by the comment we added at the end of the public-key text:<\/p>\n

\n\"The\n<\/div>\n

28.<\/strong> We can now test that the SSH connection is active by typing a command like ls<\/em> to list the directories and files. We should be able to see whatever is hanging from the home directory, C:\\repositories<\/em>, on the server.<\/p>\n

If the connection has succeeded, we have succeeded in setting up the SSH communication between server and client. It should now be very easy to make Git work.<\/p>\n

9. Setting Up a Shared Git Repository on the Server<\/h2>\n

First we need to ensure that Git for Windows is installed on the server computer.<\/p>\n

29.<\/strong> If Git hasn’t been installed yet on the server computer, download the latest version of the installer and run it. As of this writing (May 2013), the download link is https:\/\/code.google.com\/p\/msysgit\/downloads\/list<\/a>.<\/p>\n

There remain two important configuration issues on the server side. First, attempts to execute Git commands remotely will fail because Windows won’t recognise commands such as git-upload-pack<\/em>. We need to add a couple of paths to the \u2018Path\u2019 environment variable so that Windows can find all the Git-related executables. Besides, the Git installation comes with an SSH server (which, as I explained in section 3 above, is much trickier to set up than Copssh) and we need to tell Git to use the SSH executable installed by the Copssh server. This is also done through an environment variable.<\/p>\n

30.<\/strong> Open up the Control Panel\/System<\/em> dialog and in the Advanced Options<\/em> tab click the Environment Variables<\/em> button. A Dialog displaying the environment variables appears.<\/p>\n

31.<\/strong> In the \u2018System Variables\u2019 list select \u2018Path\u2019 and click the \u2018Modify\u2019 button. Add two additional paths by appending the string \u2018;C:\\Program Files\\Git\\bin;C:\\Program Files\\Git\\libexec\\git-core\u2019 (assuming C:\\Program Files\\Git<\/em> is the Git installation path; it may of course be different because of non-English localisation or if you’ve installed it in a custom location. Also note that this step may not be necessary if you installed Git for Windows with the option that allows running Git from a Windows command prompt).<\/p>\n

32.<\/strong> In the \u2018Environment Variables\u2019 dialog, click the \u2018New\u2019 button under the \u2018System Variables\u2019 list. A small dialog prompts you to enter a name and a value for a new environment variable. Enter the name \u2018GIT_SSH\u2019 and the value \u2018C:\\Program Files\\ICW\\Bin\\ssh.exe\u2019 (i.e. the path for the ssh.exe<\/em> program installed by Copssh; it may be different if you’ve used a custom location or if your system has a localised name for \u2018Program Files\u2019). Click \u2018OK\u2019 to validate the new environment variable.<\/p>\n

33.<\/strong> Click \u2018OK\u2019 to close the \u2018Environment Variables\u2019 dialog.<\/p>\n

At this point the server should be ready to accept incoming connections from the client computer. In order to test that, we should create a simple test project on the server.<\/p>\n

34.<\/strong> On the server, create a Git bare repository (git init --bare<\/code>) in the directory we’ve designated as the home directory. In my test I created a bare repository at C:\\repositories\\test_project.git<\/em>, cloned it locally and added a test file, which I committed and pushed. We will now try to clone this test_project.git<\/em> repository from the client computer.<\/p>\n

10. Testing the Git Client Connection to the Central Repository<\/h2>\n

Now we have to test that we can clone the test_project.git<\/em> repository from the client computer. We’re assuming that the client is also running Windows and that a cryptographic key pair for authentication was previously generated with PuTTYgen (steps 15 and 16 above). We need to tell Git that we’re using PuTTY for SSH key authentication, which is done through the GIT_SSH environment variable. This can be done through the Git for Windows installation process if you install it after you’ve been using PuTTY. Otherwise you’ll have to manually add or edit the GIT_SSH environment variable so that it points to the C:\\Program Files [(x86)]\\PuTTY\\plink.exe<\/em> path.<\/p>\n

35.<\/strong> On the client computer make sure that Git is installed. If you’re installing it now and the installation process prompts you to choose the SSH executable (see reference 7<\/a> below for more details), select the path to the plink.exe program that comes with PuTTY (typically C:\\Program Files [x86]\\PuTTY\\plink.exe<\/em>). Otherwise, if Git is already installed, open the Windows \u2018System Properties\u2019 dialog from the Control Panel, access the \u2018Advanced\u2019 tab and click the \u2018Environment Variables…\u2019 button. Add a variable \u2018GIT_SSH\u2019 with the value \u2018C:\\Program Files [(x86)]\\PuTTY\\plink.exe\u2019 (or whatever your plink.exe<\/em> path is).<\/p>\n

We’re ready to clone the test_project.git<\/em> project.<\/p>\n

36.<\/strong> Open a Git Bash console and type (substituting The URL or IP address of your server for \u2018example.com\u2019):<\/p>\n

git clone ssh:\/\/dev@example.com:\/~\/test_project.git<\/code><\/p>\n

You can of course do the same using a graphic interface like Git GUI or TortoiseGit.<\/p>\n

If authentication fails, you’ll have to make sure that Pageant, the PuTTY program that runs on the background for authentication, is running and is aware of the git_access.ppk<\/em> keys. If using TortoiseGit, you may need to enter the path for the git_access.ppk<\/em> file in the \u2018Load Putty Key\u2019 field (I think that’s not necessary if Pageant is running).<\/p>\n

A working copy of the test_project.git<\/em> repository should have popped up on your computer. You can now make changes, commit those changes and push them to the repository to check that everything is working fine.<\/p>\n

In the URL for the repository we can drop the \u2018ssh:\/\/\u2019 prefix since that is what Git uses by default. We need the \u2018\/~\u2019 part, which refers to the home directory that the SSH server is using (C:\\repositories<\/em> in my test). I’ve found that Copssh tries to find the repository in the C: root if \u2018\/~\u2019 is missing. Finally, if you’ve set up Copssh on the server to listen to connections on a port different from the default 22, the custom port number should be indicated after the colon that follows the host.<\/p>\n

11. Registering authorised users<\/h2>\n

Sections 6 and 7 above describe the steps required to authorise a client by registering the public key with the server. That procedure should be repeated for other authorised users. Note that some references you can find on the Internet suggest that you can create the cryptographic key pairs on the server and then give the private key to the authorised user. I strongly advise against doing that. Sending a .ppk file attached to an e-mail or simply letting two people know a private key is a breach in security that must always be avoided. The server administrator should never know the private key at all. It is the developer who should create the private<\/em> key on his or her computer and then send the public<\/em> key to the server administrator. Also note that it is not really necessary to keep back-up copies of the .ppk files. If a developer’s computer gets lost or stolen, the associated public key should be deleted from the authorized_keys<\/em> file and the developer can simply generate a a new cryptographic pair on his or her new computer.<\/p>\n

12. References<\/h2>\n
    \n
  1. Git – Distributed Workflows<\/em><\/a>. A chapter of the Pro Git<\/em> book by Scott Chacon.<\/li>\n
  2. Setting up a Msysgit Server with copSSH on Windows<\/em><\/a>. An article by Tim Davies. This is by far the most useful reference I found while I was investigating this. I had some trouble following some of the steps though.<\/li>\n
  3. Step by Step Setup Git Server on Windows with CopSSH + msysGit and Integrate Git with Visual Studio<\/em><\/a> An article by Jin Jiwei. It uses Git Extensions and the commercial version of Copssh.<\/li>\n
  4. Setting up a Git server on Windows using Git for Windows and CopSSH<\/em><\/a> by Johannes Schindelin.<\/li>\n
  5. Working with Git on Windows<\/em><\/a>. An article by Igor Balo\u0161 with good information about SSH keys and authentication issues.<\/li>\n
  6. Set up a Git server with msysgit on Windows<\/em><\/a>. A Stack Overflow thread with useful information.<\/li>\n
  7. An Illustrated Guide to Git on Windows<\/em><\/a>. A good introduction to the use of Git Gui on Windows.<\/li>\n<\/ol>\n
    Tweet<\/a>