From 28a1e9bfdbcda573e3071cd529b1cb8670683d87 Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 27 Nov 2012 17:18:38 -0500 Subject: [PATCH] Documentation --- docs/01_setup.mkd | 68 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 55 insertions(+), 13 deletions(-) diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd index c19f7fb1..5c8c0066 100644 --- a/docs/01_setup.mkd +++ b/docs/01_setup.mkd @@ -27,23 +27,28 @@ Open `gitblit.properties` in your favorite text editor and make sure to review a - *git.repositoryFolder* (path may be relative or absolute) - *groovy.scriptsFolder* (path may be relative or absolute) - *groovy.grapeFolder* (path may be relative or absolute) + - *web.siteName* (used in certificate generation, etc) - *server.tempFolder* (path may be relative or absolute) - *server.httpPort* and *server.httpsPort* - *server.httpBindInterface* and *server.httpsBindInterface* + - *server.storePassword* **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication! - *git.packedGitLimit* (set larger than the size of your largest repository) - *git.streamFileThreshold* (set larger than the size of your largest committed file) -3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line -4. Wait a minute or two while all dependencies are downloaded and your self-signed *localhost* certificate is generated. - Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*. +3. Execute `authority.cmd` or `java -jar authority.jar` from a command-line + a. enter default values for your generated certificates in the *new certificate defaults* dialog + b. enter the store password used in *server.storePassword* when prompted *(this generates an SSL certificate for **localhost**)* + c. you will also want to generate SSL certificates for the hostnames or ip addresses you serve from + d. exit the authority app +4. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line 5. Open your browser to or depending on your chosen configuration. 6. Enter the default administrator credentials: **admin / admin** and click the *Login* button **NOTE:** Make sure to change the administrator username and/or password!! -### Creating your own Self-Signed Certificate -Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*. +### Creating your own Self-Signed SSL Certificate +Gitblit GO (and Gitblit Certificate Authority) automatically generates a Certificate Authority (CA) certificate and an ssl certificate signed by this CA certificate that is bound to *localhost*. -Remote Eclipse/EGit/JGit clients (<= 1.1.0) will fail to communicate using this certificate because JGit always verifies the hostname of the certificate, regardless of the *http.sslVerify=false* client-side setting. +Remote Eclipse/EGit/JGit clients (<= 2.1.0) will fail to communicate using this certificate because JGit always verifies the hostname of the certificate, regardless of the *http.sslVerify=false* client-side setting. The EGit failure message is something like: @@ -52,14 +57,45 @@ The EGit failure message is something like: If you want to serve your repositories to another machine over https then you will want to generate your own certificate. -1. Review the contents of `makekeystore.cmd` or `makekeystore_jdk.cmd` -2. Set *your hostname* into the *HOSTNAME* variable. -3. Execute the script.
This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*. +1. `authority.cmd` or `java -jar authority.jar` +2. Click the *new ssl certificate* button (red rosette in the toolbar in upper left of window) +3. Enter the hostname or ip address +4. Enter the *server.storePassword* password -**NOTE:** -If you use `makekeystore_jdk.cmd`, the certificate password AND the keystore password must match and must be set as *server.storePassword* or specified with the *storePassword* command-line parameter! +Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to delete the following files and then start the Gitblit Certificate Authority app: +1. serverKeyStore.jks +2. serverTrustStore.jks +3. certs/caKeyStore.jks +4. certs/ca.crt + +### Client SSL Certificates +SINCE 1.2.0 + +Gitblit supports X509 certificate authentication. This authentication method relies on your servlet container to validate/verify/trust your client certificate and can be used by your browser and your git client. + +All X509 certificates have a *distinguished name (DN)* which is a signature of several fields like: + + C=US,O=Gitblit,OU=Gitblit,CN=james + +Gitblit must be able to map the DN of the certificate to an *existing* account username. The default mapping is to extract the *common name (CN)* value from the DN and use that as the account name. If the CN is a valid account, then the user is authenticated. The servlet container which runs Gitblit validates, verifies, and trusts the certificate passed to Gitblit. If you need to specify an alternative DN mapping you may do so with the *git.certificateUsernameOIDs* setting, but this mapping must be matched to the user account name. + +How do you make your servlet container trust a client certificate? -Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to generate a new certificate afterwards. +In the WAR variant, you will have to manually setup your servlet container to: +1. want/need client certificates +2. trust a CA certificate used to sign your client certificates +3. generate client certificates signed by your CA certificate + +Alternatively, Gitblit GO is designed to facilitate use of client certificate authentication. Gitblit GO ships with a tool that simplifies creation and management of client certificates, Gitblit Certificate Authority. + +#### Creating SSL Certificates with Gitblit Certificate Authority + +When you generate a new client certificate, a zip file bundle is created which includes a P12 keystore for browsers and a PEM keystore for Git. Both of these are password-protected. Additionally, a personalized README file is generated with setup instructions for popular browsers and Git. The README is generated from `certs\instructions.tmpl` and can be modified to suit your needs. + +1. `authority.cmd` or `java -jar authority.jar` +2. Select the user for which to generate the certificate +3. Click the *new certificate* button and enter the expiration date of the certificate. You must also enter a password for the generated keystore. This password is not the same as the user's login password. This password is used to protect the privatekey and public certificate you will generate for the selected user. You must also enter a password hint for the user. +4. If your mail server settings are properly configured you will have a *send email* checkbox which you can use to immediately send the generated certificate bundle to the user. ### Running as a Windows Service Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service. @@ -659,7 +695,7 @@ You must tell Git/JGit not to verify the self-signed certificate in order to per **NOTE:** The default self-signed certificate generated by Gitlbit GO is bound to *localhost*. If you are using Eclipse/EGit/JGit clients, you will have to generate your own certificate that specifies the exact hostname used in your clone/push url. -You must do this because Eclipse/EGit/JGit (<= 1.1.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. +You must do this because Eclipse/EGit/JGit (<= 2.1.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. - **Eclipse/EGit/JGit** 1. Window->Preferences->Team->Git->Configuration @@ -669,6 +705,12 @@ Value = false - **Command-line Git** ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html)) 
git config --global --bool --add http.sslVerify false
+### Http Post Buffer Size +You may find the default post buffer of your git client is too small to push large deltas to Gitblit. Sometimes this can be observed on your client as *hanging* during a push. Other times it can be observed by git erroring out with a message like: error: RPC failed; result=52, HTTP code = 0. + +This can be adjusted on your client by changing the default post buffer size: +
git config --global http.postBuffer 524288000
+ ### Cloning an Access Restricted Repository - **Eclipse/EGit/JGit** Nothing special to configure, EGit figures out everything. -- 2.39.5