From 51e21e040c65781cea10b54365e87fa8e0459737 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Mon, 10 Oct 2011 19:12:00 -0400
Subject: [PATCH] Merge branch 'master' into rpc
---
docs/01_setup.mkd | 191 ++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 186 insertions(+), 5 deletions(-)
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index eca0be2..125bac2 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -20,18 +20,19 @@
Open `gitblit.properties` in your favorite text editor and make sure to review and set:
- *git.repositoryFolder* (path may be relative or absolute)
- *server.tempFolder* (path may be relative or absolute)
+ - *server.httpPort* and *server.httpsPort*
- *server.httpBindInterface* and *server.httpsBindInterface*<br/>
- **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!
+ **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 *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.
+5. Open your browser to <http://localhost:8080> or <https://localhost:8443> 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!!
### Creating your own Self-Signed Certificate
Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.
-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.
+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.
The EGit failure message is something like:
@@ -62,6 +63,16 @@
**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.
+#### VM Considerations
+By default, the service installation script configures your Windows service to use your default JVM. This setup usually defaults to a client VM.<br/>
+If you have installed a JDK, you might consider using the `gitblitw.exe` utility to manually specify the *server* VM.
+
+1. Execute `gitblitw.exe`
+2. On the *Java* tab uncheck *Use default*.
+3. Manually navigate your filesystem and specify the server VM with the `...` button<br/><pre>
+ Java Virtual Machine:
+ C:\Program Files\Java\jre6\bin\server\jvm.dll</pre>
+
#### Command-Line Parameters
Command-Line parameters override the values in `gitblit.properties` at runtime.
@@ -77,6 +88,31 @@
**Example**
java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
+
+## Upgrading Gitblit
+Generally, upgrading is easy.
+
+Since Gitblit does not use a database the only files you have to worry about are your configuration file (`gitblit.properties` or `web.xml`) and possibly your `users.properties` file.
+
+Any important changes to the setting keys or default values will always be mentioned in the [release log](releases.html).
+
+### Upgrading Gitblit WAR
+1. Backup your `web.xml` file
+2. Delete currently deployed gitblit WAR
+3. Deploy new WAR and overwrite the `web.xml` file with your backup
+4. Review and optionally apply any new settings as indicated in the [release log](releases.html).
+
+### Upgrading Gitblit GO
+
+1. Backup your `gitblit.properties` file
+2. Backup your `users.properties` file *(if it is located in the Gitblit GO folder)*
+3. Unzip Gitblit GO to a new folder
+4. Overwrite the `gitblit.properties` file with your backup
+5. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*
+6. Review and optionally apply any new settings as indicated in the [release log](releases.html).
+
+#### Upgrading Windows Service
+You may need to delete your old service definition and install a new one depending on what has changed in the release.
## Gitblit Configuration
@@ -94,6 +130,9 @@
accessRestriction = clone
isFrozen = false
showReadme = false
+ federationStrategy = FEDERATE_THIS
+ isFederated = false
+ federationSets =
#### Repository Names
Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - .`<br/>
@@ -120,7 +159,7 @@
User passwords are CASE-SENSITIVE and may be *plain* or *md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
#### User Roles
-There is only one actual *role* in Gitblit and that is *#admin* which grants administrative powers to that user. Administrators automatically have access to all repositories. All other *roles* are repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
+There are two actual *roles* in Gitblit: *#admin*, which grants administrative powers to that user, and *#notfederated*, which prevents an account from being pulled by another Gitblit instance. Administrators automatically have access to all repositories. All other *roles* are repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
## Authentication and Authorization Customization
Instead of maintaining a `users.properties` file, you may want to integrate Gitblit into an existing environment.
@@ -129,6 +168,148 @@
Your user service class must be on Gitblit's classpath and must have a public default constructor.
+%BEGINCODE%
+public interface IUserService {
+
+ /**
+ * Setup the user service.
+ *
+ * @param settings
+ * @since 0.6.1
+ */
+ @Override
+ public void setup(IStoredSettings settings) {
+ }
+
+ /**
+ * Does the user service support cookie authentication?
+ *
+ * @return true or false
+ */
+ boolean supportsCookies();
+
+ /**
+ * Returns the cookie value for the specified user.
+ *
+ * @param model
+ * @return cookie value
+ */
+ char[] getCookie(UserModel model);
+
+ /**
+ * Authenticate a user based on their cookie.
+ *
+ * @param cookie
+ * @return a user object or null
+ */
+ UserModel authenticate(char[] cookie);
+
+ /**
+ * Authenticate a user based on a username and password.
+ *
+ * @param username
+ * @param password
+ * @return a user object or null
+ */
+ UserModel authenticate(String username, char[] password);
+
+ /**
+ * Retrieve the user object for the specified username.
+ *
+ * @param username
+ * @return a user object or null
+ */
+ UserModel getUserModel(String username);
+
+ /**
+ * Updates/writes a complete user object.
+ *
+ * @param model
+ * @return true if update is successful
+ */
+ boolean updateUserModel(UserModel model);
+
+ /**
+ * Adds/updates a user object keyed by username. This method allows for
+ * renaming a user.
+ *
+ * @param username
+ * the old username
+ * @param model
+ * the user object to use for username
+ * @return true if update is successful
+ */
+ boolean updateUserModel(String username, UserModel model);
+
+ /**
+ * Deletes the user object from the user service.
+ *
+ * @param model
+ * @return true if successful
+ */
+ boolean deleteUserModel(UserModel model);
+
+ /**
+ * Delete the user object with the specified username
+ *
+ * @param username
+ * @return true if successful
+ */
+ boolean deleteUser(String username);
+
+ /**
+ * Returns the list of all users available to the login service.
+ *
+ * @return list of all usernames
+ */
+ List<String> getAllUsernames();
+
+ /**
+ * Returns the list of all users who are allowed to bypass the access
+ * restriction placed on the specified repository.
+ *
+ * @param role
+ * the repository name
+ * @return list of all usernames that can bypass the access restriction
+ */
+ List<String> getUsernamesForRepositoryRole(String role);
+
+ /**
+ * Sets the list of all uses who are allowed to bypass the access
+ * restriction placed on the specified repository.
+ *
+ * @param role
+ * the repository name
+ * @param usernames
+ * @return true if successful
+ */
+ boolean setUsernamesForRepositoryRole(String role, List<String> usernames);
+
+ /**
+ * Renames a repository role.
+ *
+ * @param oldRole
+ * @param newRole
+ * @return true if successful
+ */
+ boolean renameRepositoryRole(String oldRole, String newRole);
+
+ /**
+ * Removes a repository role from all users.
+ *
+ * @param role
+ * @return true if successful
+ */
+ boolean deleteRepositoryRole(String role);
+
+ /**
+ * @See java.lang.Object.toString();
+ * @return string representation of the login service
+ */
+ String toString();
+}
+%ENDCODE%
+
## Client Setup and Configuration
### Https with Self-Signed Certificates
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
@@ -136,7 +317,7 @@
**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.
+You must do this because Eclipse/EGit/JGit (<= 1.1.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting.
- Eclipse/EGit/JGit
1. Window->Preferences->Team->Git->Configuration
--
Gitblit v1.9.1