* Clarified SSL certificate generation and configuration in light of the hostname verificiation that JGit currently does despite the http.sslVerify=false setting. * Added some troubleshooting information related to filesystem permissions and reading repositories. * Switched from JavaService to Apache Commons Daemon. Not sure what happened to JavaService as it stopped working for me on Windows 7 with Java 1.6.0_26. Commons Daemon accomplishes the same thing and offers a nice service control utility.tags/v0.5.1^0
@@ -16,12 +16,12 @@ google-code-prettify | |||
http://code.google.com/p/google-code-prettify | |||
--------------------------------------------------------------------------- | |||
JavaService | |||
Commons Daemon | |||
--------------------------------------------------------------------------- | |||
JavaService, released under the | |||
BSD License and the Lesser GNU Public License. | |||
Commons Daemon, released under the | |||
Apache Software License, Version 2.0. | |||
http://forge.ow2.org/projects/javaservice | |||
http://commons.apache.org/daemon | |||
--------------------------------------------------------------------------- | |||
JGit |
@@ -23,10 +23,6 @@ | |||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |||
--> | |||
<target name="buildinfo"> | |||
<!-- build date --> | |||
<tstamp> | |||
<format property="gb.buildDate" pattern="yyyy-MM-dd" /> | |||
</tstamp> | |||
<!-- extract Gitblit version number from source code --> | |||
<loadfile property="gb.version" srcfile="${basedir}/src/com/gitblit/Constants.java"> | |||
@@ -42,7 +38,22 @@ | |||
</tokenfilter> | |||
</filterchain> | |||
</loadfile> | |||
<!-- extract Gitblit version date from source code --> | |||
<loadfile property="gb.versionDate" srcfile="${basedir}/src/com/gitblit/Constants.java"> | |||
<filterchain> | |||
<linecontains> | |||
<contains value="public static final String VERSION_DATE = " /> | |||
</linecontains> | |||
<striplinebreaks /> | |||
<tokenfilter> | |||
<replacestring from="public static final String VERSION_DATE = "" to="" /> | |||
<replacestring from="";" to="" /> | |||
<trim /> | |||
</tokenfilter> | |||
</filterchain> | |||
</loadfile> | |||
<!-- extract JGit version number from source code --> | |||
<loadfile property="jgit.version" srcfile="${basedir}/src/com/gitblit/Constants.java"> | |||
<filterchain> | |||
@@ -229,7 +240,7 @@ | |||
<arg value="%WAR%=${distribution.warfile}" /> | |||
<arg value="--substitute" /> | |||
<arg value="%BUILDDATE%=${gb.buildDate}" /> | |||
<arg value="%BUILDDATE%=${gb.versionDate}" /> | |||
<arg value="--substitute" /> | |||
<arg value="%JGIT%=${jgit.version}" /> | |||
@@ -424,7 +435,7 @@ | |||
<arg value="%WAR%=${distribution.warfile}" /> | |||
<arg value="--substitute" /> | |||
<arg value="%BUILDDATE%=${gb.buildDate}" /> | |||
<arg value="%BUILDDATE%=${gb.versionDate}" /> | |||
<arg value="--substitute" /> | |||
<arg value="%JGIT%=${jgit.version}" /> |
@@ -61,7 +61,7 @@ web.siteName = | |||
# functions. | |||
web.allowAdministration = true | |||
# Allow dyanamic zip downloads. | |||
# Allow dynamic zip downloads. | |||
web.allowZipDownloads = true | |||
# Default number of entries to include in RSS Syndication links |
@@ -1,2 +1,38 @@ | |||
set JVM=C:\Program Files\Java\jdk1.6.0_26 | |||
JavaService.exe -install gitblit "%JVM%\jre\bin\server\jvm.dll" -Xmx1024M -Djava.class.path=%CD%\gitblit.jar;"%JVM%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword gitblit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% | |||
@REM Install Gitblit as a Windows service. | |||
@REM gitblitw.exe (prunmgr.exe) is a GUI application for monitoring | |||
@REM and configuring the Gitblit procrun service. | |||
@REM | |||
@REM By default this tool launches the service properties dialog | |||
@REM but it also has some other very useful functionality. | |||
@REM | |||
@REM http://commons.apache.org/daemon/procrun.html | |||
@REM arch = x86, amd64, or ia32 | |||
SET ARCH=amd64 | |||
@REM Be careful not to introduce trailing whitespace after the ^ characters. | |||
@REM Use ; or # to separate values in the --StartParams parameter. | |||
"%CD%\%ARCH%\prunsrv.exe" //IS//gitblit ^ | |||
--DisplayName="gitblit" ^ | |||
--Description="a pure Java Git solution" ^ | |||
--Startup=auto ^ | |||
--LogPath="%CD%\logs" ^ | |||
--LogLevel=INFO ^ | |||
--LogPrefix=gitblit ^ | |||
--StdOutput=auto ^ | |||
--StdError=auto ^ | |||
--StartPath="%CD%" ^ | |||
--StartClass=com.gitblit.Launcher ^ | |||
--StartMethod=main ^ | |||
--StartParams="--storePassword;gitblit" ^ | |||
--StartMode=jvm ^ | |||
--StopPath="%CD%" ^ | |||
--StopClass=com.gitblit.Launcher ^ | |||
--StopMethod=main ^ | |||
--StopParams="--stop" ^ | |||
--StopMode=jvm ^ | |||
--Classpath="%CD%\gitblit.jar" ^ | |||
--Jvm=auto ^ | |||
--JvmMx=1024 | |||
@@ -1,2 +0,0 @@ | |||
set JVM=C:\Program Files\Java\jdk1.6.0_26 | |||
JavaService64.exe -install gitblit "%JVM%\jre\bin\server\jvm.dll" -Djava.class.path=%CD%\gitblit.jar;"%JVM%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword gitblit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% |
@@ -1,2 +1,6 @@ | |||
@REM -------------------------------------------------------------------------- | |||
@REM Set HOSTNAME to the server's hostname | |||
@REM -------------------------------------------------------------------------- | |||
@SET HOSTNAME=localhost | |||
@del keystore | |||
@java -cp gitblit.jar;"%CD%\ext\*" com.gitblit.MakeCertificate --alias localhost --subject "CN=localhost, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US" | |||
@java -cp gitblit.jar;"%CD%\ext\*" com.gitblit.MakeCertificate --hostname %HOSTNAME% --subject "CN=%HOSTNAME%, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US" |
@@ -1,2 +1,6 @@ | |||
@REM -------------------------------------------------------------------------- | |||
@REM Set HOSTNAME to the server's hostname | |||
@REM -------------------------------------------------------------------------- | |||
@SET HOSTNAME=localhost | |||
@del keystore | |||
@keytool -keystore keystore -alias localhost -genkey -keyalg RSA -dname "CN=localhost, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US" | |||
@keytool -keystore keystore -alias %HOSTNAME% -genkey -keyalg RSA -dname "CN=%HOSTNAME%, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US" |
@@ -1 +1,5 @@ | |||
javaservice -uninstall gitblit | |||
@REM arch = x86, amd64, or ia32 | |||
SET ARCH=amd64 | |||
@REM Delete the gitblit service | |||
"%CD%\%ARCH%\prunsrv.exe" //DS//gitblit |
@@ -1 +0,0 @@ | |||
javaservice64 -uninstall gitblit |
@@ -33,14 +33,16 @@ | |||
## Gitblit GO Features | |||
- Out-of-the-box integrated stack requiring minimal configuration | |||
- Automatically generates a self-signed certificate for https communications | |||
- Automatically generates a self-signed certificate for *localhost* https communications<br/>(includes script to generate a self-signed certificate for *your hostname*, see [setup](/setup.html) for details) | |||
- Single text file for configuring server and gitblit | |||
- A Windows service installation script and configuration tool | |||
## Limitations | |||
- HTTP/HTTPS are the only supported protocols | |||
- Access controls are not path-based, they are repository-based | |||
- Only Administrators can create, rename or delete repositories | |||
- Only Administrators can create, modify or delete users | |||
- Native Git may be needed to periodically run git-gc as [JGit][jgit] does not fully support the git-gc featureset. | |||
### Caveats | |||
- Gitblit may eat your data. Use at your own risk. | |||
@@ -49,7 +51,6 @@ | |||
## Todo List | |||
- Code documentation | |||
- Unit testing | |||
- Update to JGit 1.0.0 when JGit team provides Maven artifacts | |||
### Under Consideration | |||
- Clone remote repository feature | |||
@@ -61,4 +62,6 @@ | |||
- activity/timeline | |||
- query feature with paging support | |||
- change history | |||
- Ticgit write integration | |||
- Ticgit write integration | |||
[jgit]: http://eclipse.org/jgit "Eclipse JGit Site" |
@@ -1,8 +1,8 @@ | |||
## Gitblit WAR Setup | |||
1. Download [Gitblit WAR %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) to the webapps folder of your servlet container.<br/> | |||
2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder. Manual extraction depends on if your servlet container is configured to automatically deploy WAR files. | |||
3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder but accessible by your servlet container. | |||
2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder. | |||
3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder that is accessible by your servlet container. | |||
4. The Gitblit webapp is configured through its `web.xml` file.<br/> | |||
Open `web.xml` in your favorite text editor and make sure to review and set: | |||
- <context-parameter> *git.repositoryFolder* (set the full path to your repositories folder) | |||
@@ -10,7 +10,7 @@ Open `web.xml` in your favorite text editor and make sure to review and set: | |||
5. You may have to restart your servlet container. | |||
6. Open your browser to <http://localhost/gitblit> or whatever the url should be. | |||
7. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/> | |||
**NOTE:** Make sure to change the administrator username and/or password!! | |||
**NOTE:** Make sure to change the administrator username and/or password!! | |||
## Gitblit GO Setup | |||
@@ -18,29 +18,49 @@ Open `web.xml` in your favorite text editor and make sure to review and set: | |||
*Its best to eliminate spaces in the path name.* | |||
2. The server itself is configured through a simple text file.<br/> | |||
Open `gitblit.properties` in your favorite text editor and make sure to review and set: | |||
- *git.repositoryFolder* (path my be relative or absolute) | |||
- *server.tempFolder* (path my be relative or absolute) | |||
- *git.repositoryFolder* (path may be relative or absolute) | |||
- *server.tempFolder* (path may be relative or absolute) | |||
- *server.httpBindInterface* and *server.httpsBindInterface*<br/> | |||
**NOTE:** Consider using **https** exclusively because passwords for authentication are transmitted as clear text! | |||
- *server.storePassword*<br/> | |||
**NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match! | |||
**https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication! | |||
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 certificate is generated. | |||
4. Wait a minute or two while all dependencies are downloaded and your self-signed *localhost* certificate is generated.<br/>Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*. | |||
5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration. | |||
6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/> | |||
**NOTE:** Make sure to change the administrator username and/or password!! | |||
**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 contains generic, non-personalized information. | |||
Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*. | |||
Should you want to include more personal or server-specific information in your self-signed certificate you will have to generate a new one. | |||
Remote Eclipse/EGit/JGit clients (<= 1.0.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: | |||
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. | |||
1. Review the contents of `makekeystore.cmd` or `makekeystore_jdk.cmd` | |||
2. Set *your hostname* into the *HOSTNAME* variable. | |||
3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*. | |||
Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd` script and execute it.<br/> | |||
**NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match! | |||
**NOTE:**<br/>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 generate a new certificate afterwards. | |||
### Running as a Windows Service | |||
Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your installed Java Virtual Machine.<br/> | |||
Set the *JVM* variable in the script to the location of your Java Virtual Machine, add any necessary start parameters, and execute the script. | |||
Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service. | |||
1. Review the contents of the `installService.cmd` | |||
2. Set the *ARCH* value as appropriate for your installed Java Virtual Machine.<br/> | |||
3. Add any necessary *--StartParams* as enumerated below in **Command-Line Parameters**. | |||
4. Execute the script. | |||
After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.<br/> | |||
Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html). | |||
**NOTE:**<br/> | |||
If you change the name of the service from *gitblit* you must also change the name of `gitblitw.exe` to match the new service name otherwise the connection between the service and the utility is lost, at least to double-click execution. | |||
#### Command-Line Parameters | |||
Command-Line parameters override the values in `gitblit.properties` at runtime. | |||
@@ -111,9 +131,14 @@ Your user service class must be on Gitblit's classpath and must have a public de | |||
## Client Setup and Configuration | |||
### Https with Self-Signed Certificates | |||
You must tell Git not to verify the self-signed certificate in order to perform any remote Git operations. | |||
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations. | |||
- Eclipse/EGit | |||
**NOTE:**<br/> | |||
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.<br/> | |||
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.<br/> | |||
You must do this because Eclipse/EGit/JGit (<= 1.0.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. | |||
- Eclipse/EGit/JGit | |||
1. Window->Preferences->Team->Git->Configuration | |||
2. Click the *New Entry* button | |||
3. <pre>Key = *http.sslVerify* | |||
@@ -122,7 +147,7 @@ You must tell Git not to verify the self-signed certificate in order to perform | |||
<pre>git config --global --bool --add http.sslVerify false</pre> | |||
### Cloning an Access Restricted Repository | |||
- Eclipse/Egit<br/>Nothing special to configure, EGit figures out everything. | |||
- Eclipse/EGit/JGit<br/>Nothing special to configure, EGit figures out everything. | |||
<pre>https://yourserver/git/your/repository</pre> | |||
- Command-line Git<br/>*My testing indicates that your username must be embedded in the url. YMMV.* | |||
<pre>https://username@yourserver/git/your/repository</pre> |
@@ -1,6 +1,6 @@ | |||
## Troubleshooting | |||
### Eclipse/Egit/Git complains that it "can't open upload pack"? | |||
### Eclipse/Egit/JGit complains that it "can't open upload pack"? | |||
There are a few ways this can occur: | |||
1. You are using https with a self-signed certificate and you **did not** configure *http.sslVerify=false* | |||
@@ -8,24 +8,30 @@ There are a few ways this can occur: | |||
2. Click the *New Entry* button | |||
3. <pre>Key = *http.sslVerify* | |||
Value = *false*</pre> | |||
2. The repository is clone-restricted and you don't have access. | |||
3. The repository is clone-restricted and your password changed. | |||
4. A regression in Gitblit. :( | |||
2. Gitblit GO's default self-signed certificate is bound to *localhost* and you are trying to clone/push between machines. | |||
1. Review the contents of `makekeystore.cmd` | |||
2. Set *your hostname* in the *HOSTNAME* variable. | |||
3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*. | |||
3. The repository is clone-restricted and you don't have access. | |||
4. The repository is clone-restricted and your password changed. | |||
5. A regression in Gitblit. :( | |||
### Why can't I access Gitblit GO from another machine? | |||
Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`, you may be binding only to localhost. | |||
And of course ensure that any firewall you may have running either has an exception for your ports or for the running process. | |||
1. Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`, you may be only be serving on *localhost*. | |||
2. Please see the above answer about "**can't open upload pack**". | |||
3. Ensure that any firewall you may have running on the Gitblit server either has an exception for your specified ports or for the running process. | |||
### How do I run Gitblit GO on port 80 or 443 in Linux? | |||
Linux requires root permissions to serve on ports < 1024.<br/> | |||
Run the server as *root* (security concern) or change the ports you are serving to 8080 (http) and/or 8443 (https). | |||
### Gitblit GO does not list my repositories?! | |||
Confirm that the value *git.repositoriesFolder* in `gitblit.properties` actually points to your repositories folder. | |||
1. Confirm that the value *git.repositoriesFolder* in `gitblit.properties` actually points to your repositories folder. | |||
2. Confirm that the Gitblit GO process has full read-write-execute permissions to your *git.repositoriesFolder*. | |||
### Gitblit WAR does not list my repositories?! | |||
Confirm that the <context-param> *git.repositoriesFolder* value in your `web.xml` file actually points to your repositories folder. | |||
1. Confirm that the <context-param> *git.repositoriesFolder* value in your `web.xml` file actually points to your repositories folder. | |||
2. Confirm that the servlet container process has full read-write-execute permissions to your *git.repositoriesFolder*. | |||
### Gitblit WAR will not authenticate any users?! | |||
Confirm that the <context-param> *realm.userService* value in your `web.xml` file actually points to a `users.properties` file. | |||
@@ -57,9 +63,12 @@ Gitblit eliminates all that complication with its 100% Java stack and simple sin | |||
Additionally, Git and Gitweb do not offer repository creation or user management. | |||
### Do I need real Git? | |||
No. Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].<br/> | |||
No (mostly). Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].<br/> | |||
Everything you need for Gitblit (except Java) is either bundled in the distribution file or automatically downloaded on execution. | |||
**mostly**<br/> | |||
JGit does not fully support the git-gc featureset (garbage collection) so you may want native Git to periodically run git-gc until [JGit][jgit] fully supports this feature. | |||
### Can I run Gitblit in conjunction with my existing Git tooling? | |||
Yes. | |||
@@ -72,7 +81,7 @@ No. Gitblit stores its repository configuration information within the `.git/co | |||
### Can I manually edit users.properties, gitblit.properties, or .git/config? | |||
Yes. You can manually manipulate all of them and (most) changes will be immediately available to Gitblit.<br/>Exceptions to this are noted in `gitblit.properties`. | |||
*NOTE:* Care must be taken to preserve the relationship between user roles and repository names.<br/>Please see the *User Roles* section of the [setup](/setup.html) page for details. | |||
**NOTE:**<br/>Care must be taken to preserve the relationship between user roles and repository names.<br/>Please see the *User Roles* section of the [setup](/setup.html) page for details. | |||
### Can I restrict access to paths within a repository? | |||
No. Access restrictions apply to the repository as a whole. |
@@ -11,7 +11,7 @@ | |||
The following dependencies are bundled with Gitblit. | |||
- [google-code-prettify](http://code.google.com/p/google-code-prettify) (Apache 2.0) | |||
- [JavaService](http://forge.ow2.org/projects/javaservice) (BSD and LGPL) | |||
- [Commons Daemon](http://commons.apache.org/daemon) (Apache 2.0) | |||
- magnifying glass search icon courtesy of [Gnome](http://gnome.org) (Creative Commons CC-BY) | |||
- modified Git logo originally designed by [Henrik Nyh](http://henrik.nyh.se/2007/06/alternative-git-logo-and-favicon) | |||
- other icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) (Creative Commons CC-BY) |
@@ -3,7 +3,11 @@ | |||
### Current Release | |||
%VERSION% ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)) based on [%JGIT%][jgit] *released %BUILDDATE%* | |||
- clarified SSL certificate generation and configuration for both server-side and client-side | |||
- added some more troubleshooting information to documentation | |||
- replaced JavaService with Apache Commons Daemon | |||
### Older Releases | |||
none | |||
0.5.0 ([go](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.0.zip)|[war](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.0.war)) based on [JGit 1.0.0 (201106090707-r)][jgit] *released 2006-06-26* | |||
[jgit]: http://eclipse.org/jgit "Eclipse JGit Site" |
@@ -23,7 +23,11 @@ public class Constants { | |||
// The build script extracts this exact line so be careful editing it | |||
// and only use A-Z a-z 0-9 .-_ in the string. | |||
public static final String VERSION = "0.5.0"; | |||
public static final String VERSION = "0.5.1"; | |||
// The build script extracts this exact line so be careful editing it | |||
// and only use A-Z a-z 0-9 .-_ in the string. | |||
public static final String VERSION_DATE = "2011-06-28"; | |||
// The build script extracts this exact line so be careful editing it | |||
// and only use A-Z a-z 0-9 .-_ in the string. |
@@ -57,7 +57,7 @@ public class MakeCertificate { | |||
jc.usage(); | |||
} | |||
File keystore = new File("keystore"); | |||
generateSelfSignedCertificate(params.alias, keystore, params.storePassword, params.subject); | |||
generateSelfSignedCertificate(params.hostname, keystore, params.storePassword, params.subject); | |||
} | |||
public static void generateSelfSignedCertificate(String hostname, File keystore, | |||
@@ -158,8 +158,8 @@ public class MakeCertificate { | |||
private static final FileSettings FILESETTINGS = new FileSettings(Constants.PROPERTIES_FILE); | |||
@Parameter(names = { "--alias" }, description = "Server alias", required = true) | |||
public String alias; | |||
@Parameter(names = { "--hostname" }, description = "Server Hostname", required = true) | |||
public String hostname; | |||
@Parameter(names = { "--subject" }, description = "Certificate subject", required = true) | |||
public String subject; |