Documentation

James Moger

2012-12-05 dc9735acfc9dcea6b970d18a315cbf8a6997c4f9

Documentation

 docs/01_features.mkd

@@ -17,7 +17,7 @@
- Optional feature to allow users to create personal repositories

- Optional feature to fork a repository to a personal repository

- Optional feature to create a repository on push

- Experimental built-in Garbage Collection

- *Experimental* built-in Garbage Collection

- Ability to federate with one or more other Gitblit instances

- RSS/JSON RPC interface

- Java/Swing Gitblit Manager tool 

@@ -59,8 +59,8 @@


## Gitblit GO Features

- Out-of-the-box integrated stack requiring minimal configuration

- Automatically generates a self-signed certificate for *localhost* https communications  
    (includes script to generate a self-signed certificate for *your hostname*, see [setup](/setup.html) for details)

- Automatic generation of ssl certificate for https communications

- Integrated GUI tool to facilitate x509 PKI including ssl and client certificate generation, client certificate revocation, and client certificate distribution

- Single text file for configuring server and gitblit

- A Windows service installation script and configuration tool

- Built-in AJP connector for Apache httpd 


 docs/01_setup.mkd

@@ -27,7 +27,6 @@
    - *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*  

@@ -36,10 +35,10 @@
    - *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 `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

    1. fill out the fields in the *new certificate defaults* dialog

    2. enter the store password used in *server.storePassword* when prompted.  This generates an SSL certificate for **localhost**.

    3. you may want to generate an SSL certificate for the hostname or ip address hostnames you are serving from<br/>**NOTE:** You can only have **one** SSL certificate specified for a port.

    5. exit the authority app

4. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line

5. Open your browser to <http://localhost:8080> or <https://localhost:8443> depending on your chosen configuration.

6. Enter the default administrator credentials: **admin / admin** and click the *Login* button    

@@ -55,18 +54,21 @@
    Cannot get remote repository refs.

    Reason: https:/myserver.com/git/myrepo.git: cannot open git-upload-pack



If you want to serve your repositories to another machine over https then you will want to generate your own certificate.

If you want to serve your repositories to another machine over https then you will want to generate a new certificate for the hostname or ip address you are serving from.



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

4. Make sure the checkbox *serve https with this certificate* is checked

5. In the keystore password prompt, enter the *server.storePassword* password

 

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:

If you decide to change the value of *server.storePassword* (recommended) <u>after</u> you have already started Gitblit or Gitblit Certificate Authority, then you will have to delete the following files and then restart the Gitblit Certificate Authority app:



1. serverKeyStore.jks

2. serverTrustStore.jks

3. certs/caKeyStore.jks

4. certs/ca.crt

5. certs/caRevocationList.crl (optional)



### Client SSL Certificates

SINCE 1.2.0

@@ -94,8 +96,12 @@


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.

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.



#### Certificate Inspection and Advanced Troubleshooting



X509 certificates can be confusing and tricky even with the simplified Gitblit Certificate Authority tool.  If you find you need more tooling to understand your keystores, certificates, and certificate revocation lists (CRLs), I highly recommend [Portecle](http://portecle.sourceforge.net) which can be conveniently launched as a [Java Web Start app](http://portecle.sourceforge.net/webstart/portecle.jnlp).



### Running as a Windows Service

Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service.

@@ -130,6 +136,7 @@
    --httpPort             HTTP port for to serve. (port <= 0 will disable this connector)

    --httpsPort            HTTPS port to serve.  (port <= 0 will disable this connector)

    --ajpPort              AJP port to serve.  (port <= 0 will disable this connector)

    --alias                Alias in keystore of SSL cert to use for https serving

    --storePassword        Password for SSL (https) keystore.

    --shutdownPort         Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)

    --tempFolder           Folder for server to extract built-in webapp


 docs/04_releases.mkd

@@ -27,7 +27,7 @@


#### additions



- Implemented discrete repository permissions (issue 36)

- Implemented discrete repository permissions (issue 36)  
    - V (view in web ui, RSS feeds, download zip)

    - R (clone)

    - RW (clone and push)

@@ -35,33 +35,34 @@
    - RWD (clone and push with ref creation, deletion)

    - RW+ (clone and push with ref creation, deletion, rewind)

While not as sophisticated as Gitolite, this does give finer access controls.  These permissions fit in cleanly with the existing users.conf and users.properties files.  In Gitblit <= 1.1.0, all your existing user accounts have RW+ access.   If you are upgrading to 1.2.0, the RW+ access is *preserved* and you will have to lower/adjust accordingly.

- Implemented *case-insensitive* regex repository permission matching (issue 36)

- Implemented *case-insensitive* regex repository permission matching (issue 36)  
This allows you to specify a permission like `RW:mygroup/.*` to grant push privileges to all repositories within the *mygroup* project/folder.

- Added DELETE, CREATE, and NON-FAST-FORWARD ref change logging

- Added support for personal repositories.

Personal repositories can be created by accounts with the *create* permission and are stored in *git.repositoriesFolder/~username*.  Each user with personal repositories will have a user page, something like the GitHub profile page.  Personal repositories have all the same features as common repositories, except personal repositories can be renamed by their owner.

- Added support for server-side forking of a repository to a personal repository (issue 137)

In order to fork a repository, the user account must have the *fork* permission **and** the repository must *allow forks*.  The clone inherits the access list of its origin.  i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork.  This is to facilitate collaboration.  The fork owner may change access to the fork and add/remove users/teams, etc as required <u>however</u> it should be noted that all personal forks will be enumerated in the fork network regardless of access view restrictions.  If you really must have an invisible fork, the clone it locally, create a new repository for your invisible fork, and push it back to Gitblit.

- Added optional *create-on-push* support

- Added support for server-side forking of a repository to a personal repository (issue 137)  
In order to fork a repository, the user account must have the *fork* permission **and** the repository must *allow forks*.  The clone inherits the access list of its origin.  i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork.  This is to facilitate collaboration.  The fork owner may change access to the fork and add/remove users/teams, etc as required <u>however</u> it should be noted that all personal forks will be enumerated in the fork network regardless of access view restrictions.  If you really must have an invisible fork, the clone it locally, create a new repository for your invisible fork, and push it back to Gitblit.  
    **New:** *web.allowForking=true*

- Added optional *create-on-push* support  
    **New:** *git.allowCreateOnPush=true*

- Added **experimental** JGit-based garbage collection service.  This service is disabled by default.

    **New:** *git.allowGarbageCollection=false*

    **New:** *git.garbageCollectionHour = 0*

    **New:** *git.defaultGarbageCollectionThreshold = 500k*

- Added **experimental** JGit-based garbage collection service.  This service is disabled by default.  
    **New:** *git.allowGarbageCollection=false*  
    **New:** *git.garbageCollectionHour = 0*  
    **New:** *git.defaultGarbageCollectionThreshold = 500k*  
    **New:** *git.defaultGarbageCollectionPeriod = 7 days*

- Added support for X509 client certificate authentication (github/kevinanderson1).  (issue 106)

You can require all git servlet access be authenticated by a client certificate.  You may also specify the OID fingerprint to use for mapping a certificate to a username.  It should be noted that the user account MUST already exist in Gitblit for this authentication mechanism to work; this mechanism can not be used to automatically create user accounts from a certificate.

    **New:** *git.requireClientCertificates = false*

    **New:** *git.enforceCertificateValidity = true*

- Added support for X509 client certificate authentication (github/kevinanderson1).  (issue 106)  
You can require all git servlet access be authenticated by a client certificate.  You may also specify the OID fingerprint to use for mapping a certificate to a username.  It should be noted that the user account MUST already exist in Gitblit for this authentication mechanism to work; this mechanism can not be used to automatically create user accounts from a certificate.  
    **New:** *git.requireClientCertificates = false*  
    **New:** *git.enforceCertificateValidity = true*  
    **New:** *git.certificateUsernameOIDs = CN*

- Revised clean install certificate generation to create a Gitblit GO Certificate Authority certificate; an SSL certificate signed by the CA certificate; and to create distinct server key and server trust stores.  <u>The store files have been renamed!</u>

- Added support for Gitblit GO to require usage of client certificates to access the entire server.

This is extreme and should be considered carefully since it affects every https access.  The default is to **want** client certificates.  Setting this value to *true* changes that to **need** client certificates.

This is extreme and should be considered carefully since it affects every https access.  The default is to **want** client certificates.  Setting this value to *true* changes that to **need** client certificates.  
    **New:** *server.requireClientCertificates = false*

- Added Gitblit Certificate Authority, an X509 certificate generation tool for Gitblit GO to encourage use of client certificate authentication.

- Added setting to control length of shortened commit ids

- Added **Gitblit Certificate Authority**, an x509 PKI management tool for Gitblit GO to encourage use of x509 client certificate authentication.

- Added setting to control length of shortened commit ids  
    **New:** *web.shortCommitIdLength=8*

- Added alternate compressed download formats: tar.gz, tar.xz, tar.bzip2 (issue 174)

- Added alternate compressed download formats: tar.gz, tar.xz, tar.bzip2 (issue 174)  
    **New:** *web.compressedDownloads = zip gz*

- Added simple project pages.  A project is a subfolder off the *git.repositoriesFolder*.

- Added support for X-Forwarded-Context for Apache subdomain proxy configurations (issue 135)

@@ -85,7 +86,7 @@
- Expose ReceivePack to Groovy push hooks (issue 125)

- Redirect to summary page when refreshing the empty repository page on a repository that is not empty (issue 129)

- Emit a warning in the log file if running on a Tomcat-based servlet container which is unfriendly to %2F forward-slash url encoding AND Gitblit is configured to mount parameters with %2F forward-slash url encoding (Github/jpyeron, issue 126)

- LDAP admin attribute setting is now consistent with LDAP teams setting and admin teams list.

- LDAP admin attribute setting is now consistent with LDAP teams setting and admin teams list.  
If *realm.ldap.maintainTeams==true* **AND** *realm.ldap.admins* is not empty, then User.canAdmin() is controlled by LDAP administrative team membership.  Otherwise, User.canAdmin() is controlled by Gitblit.

- Support servlet container authentication for existing UserModels (issue 68)