James Moger
2011-10-02 f762b160efd5cafd919a6fd7f9587f578eceb454
docs/02_federation.mkd
@@ -2,15 +2,20 @@
*SINCE 0.6.0*
A Gitblit federation is basically an automated backup solution from one Gitblit instance to another.  If you are/were a Subversion user you might think of this as [svn-sync](http://svnbook.red-bean.com/en/1.5/svn.ref.svnsync.html), but better.
A Gitblit federation is a mechanism to clone repositories and keep them in sync from one Gitblit instance to another.  Federation can be used to maintain a mirror of your Gitblit instance, to aggregate repositories from developer workstations, or to initially clone groups of repositories to developer workstations.  If you are/were a Subversion user you might think of this as [svn-sync](http://svnbook.red-bean.com/en/1.5/svn.ref.svnsync.html), but better.
If your Gitblit instance allows federation and it is properly registered with another Gitblit instance, each of the *non-excluded* repositories of your Gitblit instance can be mirrored, in their entirety, to the pulling Gitblit instance.  You may optionally allow pulling of user accounts and server settings.
If your Gitblit instance allows federation and it is properly registered with another Gitblit instance, each of the *non-excluded* repositories of your Gitblit instance can be mirrored, in their entirety, to the pulling Gitblit instance.  You may optionally allow pulling of user accounts and backup of server settings.
### Source Gitblit Instance Requirements
The federation feature should be considered a security backdoor and enabled or disabled as appropriate for your installation.<br/>
Please review all the documentation to understand how it works and its limitations.
![block diagram](fed_aggregation.png "Gitblit Federation Aggregation")
### Origin Gitblit Instance Requirements
- *git.enableGitServlet* must be true, all Git clone and pull requests are handled through Gitblit's JGit servlet
- *federation.passphrase* must be non-empty
- The Gitblit source instance must be http/https accessible by the pulling Gitblit instance.<br/>That may require configuring port-forwarding on your router and/or opening ports on your firewall.
- The Gitblit origin instance must be http/https accessible by the pulling Gitblit instance.<br/>That may require configuring port-forwarding on your router and/or opening ports on your firewall.
#### federation.passphrase
@@ -27,14 +32,14 @@
### Pulling Gitblit Instance Requirements
 - consider setting *federation.allowProposals=true* to facilitate the registration process from source Gitblit instances
 - consider setting *federation.allowProposals=true* to facilitate the registration process from origin Gitblit instances
 - properly registered Gitblit instance including, at a minimum, url, *federation token*, and update frequency
### Controlling What Gets Pulled
If you want your repositories (and optionally users accounts and settings) to be pulled by another Gitblit instance, you need to register your source Gitblit instance with a pulling Gitblit instance by providing the url of your Gitblit instance and a federation token.
If you want your repositories (and optionally users accounts and settings) to be pulled by another Gitblit instance, you need to register your origin Gitblit instance with a pulling Gitblit instance by providing the url of your Gitblit instance and a federation token.
Gitblit generates the following federation tokens:
Gitblit generates the following standard federation tokens:
%BEGINCODE%
String allToken = SHA1(passphrase + "-ALL");
String usersAndRepositoriesToken = SHA1(passphrase + "-USERS_AND_REPOSITORIES");
@@ -49,25 +54,29 @@
If *federation.passphrase* has a non-empty value, the federation tokens are displayed in the log file and are visible, to administrators, in the web ui.
The three standard tokens grant access to ALL your non-excluded repositories.  However, if you only want to specify different groups of repositories to be federated then you need to define *federation sets*.
#### Federation Sets
Federation Sets (*federation.sets*) are named groups of repositories.  The Federation Sets are available for selection in the repository settings page.  You can assign a repository to one or more sets and then distribute the token for the set.  This allows you to grant federation pull access to a subset of your available repositories.  Tokens for federation sets only grant pull access for the member repositories.
Federation Sets (*federation.sets*) are named groups of repositories.  The Federation Sets are defined in `gitblit.properties` and are available for selection in the repository settings page.  You can assign a repository to one or more sets and then distribute the federation token for the set.  This allows you to grant federation pull access to a subset of your available repositories.  Tokens for federation sets only grant pull access for the member repositories.
### Federation Proposals (Source Gitblit Instance)
### Federation Proposals (Origin Gitblit Instance)
Once you have properly setup your passphrase and can see your federation tokens, you are ready to share them with a pulling Gitblit instance.
 
The registration process can be partially automated by sending a *federation proposal* to another Gitblit instance.<br/>
The registration process can be partially automated by sending a *federation proposal* to the pulling Gitblit instance.<br/>
To send a proposal:
1. Login to your Gitblit instance as an administrator
2. Select and click the *send proposal* link for the appropriate token at the bottom of the repositories page
3. Enter the url of the Gitblit instance you want to federate with
4. Click submit
2. Select and click the *propose* link for the appropriate token at the bottom of the repositories page
3. Confirm the publicly accessible url of your (origin) Gitblit instance
4. Enter the url of the pulling Gitblit instance you want to federate with
5. Optionally enter a message for the administrators
6. Click *propose*
Not all Gitblit instances accept *federation proposals*, there is a setting which allows Gitblit to outright reject them.  In this case an email or instant message to the administrator of the other Gitblit instance is required.  :)
If your proposal is accepted, the proposal is cached to disk on the remote Gitblit server and, if properly configured, the administrators of that Gitblit server will receive an email notification of your proposal.
If your proposal is accepted, the proposal is cached to disk on the pulling Gitblit server and, if properly configured, the administrators of that Gitblit server will receive an email notification of your proposal.
Your proposal includes:
@@ -75,18 +84,18 @@
2. the federation token you selected and its type
3. the list of your *non-excluded* repositories, and their configuration details, that you propose to share
Submitting a proposal does not automatically register your server with the remote Gitblit instance.<br/>
Submitting a proposal does not automatically register your server with the pulling Gitblit instance.<br/>
Registration is a manual process for an administrator.
### Federation Proposals (Pulling Gitblit Instance)
If your Giblit instance has received a *federation proposal*, you will be alerted to that information the next time you login to Gitblit as an administrator.
You may view the details of a proposal from scrolling down to the bottom of the repositories page and selecting a proposal.  Sample registration settings will be generated for you that you may copy & paste into either your `gitblit.properties` file or your `web.xml` file.
You may view the details of a proposal by scrolling down to the bottom of the repositories page and selecting a proposal.  Sample registration settings will be generated for you that you may copy & paste into either your `gitblit.properties` file or your `web.xml` file.
### Excluding Repositories (Source Gitblit Instance)
### Excluding Repositories (Origin Gitblit Instance)
You may exclude a repository from being pulled by a federated Gitblit instance by setting its *federation strategy* in the repository's settings page.
You may exclude a repository from being pulled by any federated Gitblit instance by setting its *federation strategy* to EXCLUDE in the repository's settings page.
### Excluding Repositories (Pulling Gitblit Instance)
@@ -106,21 +115,19 @@
    
### Tracking Status (Pulling Gitblit Instance)
Below the repositories list on the repositories page you will find a section named *federation registrations*.  This section enumerates the other gitblit servers you have configured to periodically pull.  The *status* of the latest pull will be indicated on the left with a colored circle, similar to the status of an executed unit test or Hudson/Jenkins build.  You can drill into the details of the registration to view the status of the last pull from each repository available from that source Gitblit instance.  Additionally, you can specify the *federation.N.notifyOnError=true* flag, to be alerted via email of regressive status changes to individual registrations.
Below the repositories list on the repositories page you will find a section named *federation registrations*.  This section enumerates the other gitblit servers you have configured to periodically pull.  The *status* of the latest pull will be indicated on the left with a colored circle, similar to the status of an executed unit test or Hudson/Jenkins build.  You can drill into the details of the registration to view the status of the last pull from each repository available from that origin Gitblit instance.  Additionally, you can specify the *federation.N.notifyOnError=true* flag, to be alerted via email of regressive status changes to individual registrations.
### Tracking Status (Source Gitblit Instance)
### Tracking Status (Origin Gitblit Instance)
Source Gitblit instances can not directly track the success or failure status of Pulling Gitblit instances.  However, the Pulling Gitblit instance may elect to send a status acknowledgment (*federation.N.sendStatus=true*) to the source Gitblit server that indicates the per-repository status of the pull operation.  This is the same data that is displayed on the Pulling Gitblit instances ui.
Origin Gitblit instances can not directly track the success or failure status of Pulling Gitblit instances.  However, the Pulling Gitblit instance may elect to send a status acknowledgment (*federation.N.sendStatus=true*) to the origin Gitblit server that indicates the per-repository status of the pull operation.  This is the same data that is displayed on the Pulling Gitblit instances ui.
### How does it work? (Source Gitblit Instances)
### How does it work? (Origin Gitblit Instances)
A pulling Gitblit instance will periodically contact your Gitblit instance and will provide the token as proof that you have granted it federation access.  Your Gitblit instance will decide, based on the supplied token, if the requested data should be returned to the pulling Gitblit instance.  Gitblit data (user accounts, repository metadata, and server settings) are serialized as [JSON](http://json.org) using [google-gson](http://google-gson.googlecode.com) and returned to the pulling Gitblit instance.  Standard Git clone and pull operations are used to transfer commits.
The federation process executes using an internal administrator account, *$gitblit*.  All the normal authentication and authorization processes are used for federation requests. For example, Git commands are authenticated as *$gitblit / token*.
While the *$gitblit* account has access to all repositories, server settings, and user accounts, it is prohibited from accessing the web ui and it is disabled if *federation.passphrase* is empty.
The federation feature should be considered a backdoor and enabled or disabled as appropriate for your installation.
### How does it work? (Pulling Gitblit Instances)
@@ -140,19 +147,19 @@
#### User Accounts
By default all user accounts except the *admin* account are automatically pulled when using the *ALL* token or the *USERS_AND_REPOSITORIES* token.  You may exclude a user account form being pulled by a federated Gitblit instance by checking *exclude from federation* in the edit user page.
By default all user accounts except the *admin* account are automatically pulled when using the *ALL* token or the *USERS_AND_REPOSITORIES* token.  You may exclude a user account from being pulled by a federated Gitblit instance by checking *exclude from federation* in the edit user page.
The pulling Gitblit instance will store a registration-specific `users.properties` file for the pulled user accounts and their repository permissions. This file is stored in the *federation.N.folder* folder.
If you specify *federation.N.mergeAccounts=true*, then the user accounts from the source Gitblit instance will be integrated into the `users.properties` file of your Gitblit instance and allow sign-on of those users.
If you specify *federation.N.mergeAccounts=true*, then the user accounts from the origin Gitblit instance will be integrated into the `users.properties` file of your Gitblit instance and allow sign-on of those users.
**NOTE:**<br/>
Upgrades from older Gitblit versions will not have the *#notfederated* role assigned to the *admin* account.  Without that role, your admin account WILL be transferred with an *ALL* or *USERS_AND_REPOSITORIES* token.<br/>
Please consider setting that flag!
Please consider adding the *#notfederated* role to your admin account!
#### Server Settings 
Server settings are automatically pulled when using the *ALL* token.
Server settings are only pulled when using the *ALL* token.
The pulling Gitblit instance will store a registration-specific `gitblit.properties` file for all pulled settings.  This file is stored in the *federation.N.folder* folder.
@@ -164,19 +171,19 @@
If an object exists locally that has the same name as the remote object, it is assumed they are the same and the contents of the remote object are merged into the local object.  If you can not guarantee that this is the case, then you should not store any federated repositories directly in *git.repositoriesFolder* and you should not enable *mergeAccounts*.
By default, federated repositories can not be pushed to, they are read-only by the *isFrozen* flag.  This flag is **ONLY** enforced by Gitblit's JGit servlet.  If you push to a federated repository after resetting the *isFrozen* flag or via some other Git access technique then you may break Gitblit's ability to continue pulling from the source repository.  If you are only pushing to a local branch then you might be safe.
By default, federated repositories can not be pushed to, they are read-only by the *isFrozen* flag.  This flag is **ONLY** enforced by Gitblit's JGit servlet.  If you push to a federated repository after resetting the *isFrozen* flag or via some other Git access technique then you may break Gitblit's ability to continue pulling from the origin repository.  If you are only pushing to a local branch then you might be safe.
## Federation Pull Registration Keys
<table>
<tr><th>federation.N.url</th>
<td>string</td>
<td>the url of the source Gitblit instance</td>
<td>the url of the origin Gitblit instance *(required)*</td>
</tr>
<tr><th>federation.N.token</th>
<td>string</td>
<td>the token provided by the source Gitblit instance</td>
<td>the token provided by the origin Gitblit instance *(required)*</td>
</tr>
<tr><th>federation.N.frequency</th>
@@ -186,22 +193,27 @@
<tr><th>federation.N.folder</th>
<td>string</td>
<td>the destination folder, relative to *git.repositoriesFolder*, for these repositories.  If empty, the repositories are put in *git.repositoriesFolder*.</td>
<td>the destination folder, relative to *git.repositoriesFolder*, for these repositories.<br/>default is *git.repositoriesFolder*</td>
</tr>
<tr><th>federation.N.bare</th>
<td>boolean</td>
<td>if **true** *(default)*, each repository is cloned as a bare repository (i.e. no working folder).</td>
</tr>
<tr><th>federation.N.mirror</th>
<td>boolean</td>
<td>if **true** *(default)*, each repository HEAD is reset to *origin/master* after each pull.  The repository is flagged *isFrozen* after the initial clone.<p>If **false**, each repository HEAD will point to the FETCH_HEAD of the initial clone from the origin until pushed to or otherwise manipulated.</td>
</tr>
<tr><th>federation.N.mergeAccounts</th>
<td>boolean</td>
<td>merge the retrieved accounts into the `users.properties` of **this** Gitblit instance</td>
<td>if **true**, merge the retrieved accounts into the `users.properties` of **this** Gitblit instance.<br/>*default is false*</td>
</tr>
<tr><th>federation.N.sendStatus</th>
<td>boolean</td>
<td>send the status of the federated pull to the source Gitblit instance</td>
</tr>
<tr><th>federation.N.freeze</th>
<td>boolean</td>
<td>freeze the repository after the first pull, subsequent pulls respect the local *isFrozen* setting</td>
<td>if **true**, send the status of the federated pull to the origin Gitblit instance.<br/>*default is false*</td>
</tr>
<tr><th>federation.N.include</th>
@@ -216,7 +228,7 @@
<tr><th>federation.N.notifyOnError</th>
<td>boolean</td>
<td>send an email to the administrators on an error</td>
<td>if **true**, send an email to the administrators on an error.<br/>*default is false*</td>
</tr>
</table>
@@ -226,48 +238,79 @@
#### (Nearly) Perfect Mirror Example
This assumes that the *token* is the *ALL* token from the source gitblit instance.<br/>
The repositories, example1_users.properties, and example1_gitblit.properties will be put in *git.repositoriesFolder* and the source user accounts will be merged into the local user accounts, including passwords and administrator status.  The mirror instance will also send a status acknowledgment at the end of the pull operation which will include the state of each repository pull (EXCLUDED, SKIPPED, PULLED).  This way the source Gitblit instance can monitor the health of its mirrors.
![block diagram](fed_mirror.png "Gitblit Mirror")
This example is considered *nearly* perfect because while the remote Gitblit's server settings are pulled and saved locally, they are not merged with your server settings so its not a true mirror, but its likely the mirror you'd want to configure.
This assumes that the *token* is the *ALL* token from the origin gitblit instance.
The repositories, example1_users.properties, and example1_gitblit.properties will be put in *git.repositoriesFolder* and the origin user accounts will be merged into the local user accounts, including passwords and all roles.  The Gitblit instance will also send a status acknowledgment to the origin Gitblit instance at the end of the pull operation.  The status report will include the state of each repository pull (EXCLUDED, SKIPPED, NOCHANGE, PULLED, MIRRORED).  This way the origin Gitblit instance can monitor the health of its mirrors.
This example is considered *nearly* perfect because while the origin Gitblit's server settings are pulled and saved locally, they are not merged with your server settings so its not a true mirror, but its likely the mirror you'd want to configure.
    federation.example1.url = https://go.gitblit.com
    federation.example1.token = 6f3b8a24bf970f17289b234284c94f43eb42f0e4
    federation.example1.frequency = 120 mins
    federation.example1.folder =
    federation.example1.folder =
    federation.example1.bare = true
    federation.example1.mirror = true
    federation.example1.mergeAccounts = true
    federation.example1.sendStatus = true
    federation.example1.freeze = true
    
#### Just Repositories Example
This assumes that the *token* is the *REPOSITORIES* token from the remote gitblit instance.<br/>
This assumes that the *token* is the *REPOSITORIES* token from the origin gitblit instance.<br/>
The repositories will be put in *git.repositoriesFolder*/example2.
    federation.example2.url = https://tomcat.gitblit.com/gitblit
    federation.example2.token = 6f3b8a24bf970f17289b234284c94f43eb42f0e4
    federation.example2.frequency = 120 mins
    federation.example2.folder = example2
    federation.example2.bare = true
    federation.example2.mirror = true
    
#### All-but-One Repository Example
This assumes that the *token* is the *REPOSITORIES* token from the remote gitblit instance.<br/>
This assumes that the *token* is the *REPOSITORIES* token from the origin gitblit instance.<br/>
The repositories will be put in *git.repositoriesFolder*/example3.
    federation.example3.url = https://tomcat.gitblit.com/gitblit
    federation.example3.token = 6f3b8a24bf970f17289b234284c94f43eb42f0e4
    federation.example3.frequency = 120 mins
    federation.example3.folder = example3
    federation.example3.bare = true
    federation.example3.mirror = true
    federation.example3.exclude = somerepo.git
    
#### Just One Repository Example
This assumes that the *token* is the *REPOSITORIES* token from the remote gitblit instance.<br/>
This assumes that the *token* is the *REPOSITORIES* token from the origin gitblit instance.<br/>
The repositories will be put in *git.repositoriesFolder*/example4.
    federation.example4.url = https://tomcat.gitblit.com/gitblit
    federation.example4.token = 6f3b8a24bf970f17289b234284c94f43eb42f0e4
    federation.example4.frequency = 120 mins
    federation.example4.folder = example4
    federation.example4.bare = true
    federation.example4.mirror = true
    federation.example4.exclude = *
    federation.example4.include = somerepo.git
    federation.example4.include = somerepo.git
## Federation Client
Instead of setting up a full-blown pulling Gitblit instance, you can also use the [federation client](http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%) command-line utility.  This is a packaged subset of the federation feature in a smaller, simpler command-line only tool.
The *federation client* relies on many of the same dependencies as Gitblit and will download them on first execution.
### federation.properties
You may use the `federation.properties` file to configure one or more Gitblit instances that you want to pull from.  This file is a subset of the standard `gitblit.properties` file.
By default this tool does not daemonize itself; it executes and then quits.  This allows you to use the native scheduling feature of your OS.  Of course, if you'd rather use Gitblit's scheduler you may use that by specifying the `--daemon` parameter.
### Command-Line Parameters
Instead of using `federation.properties` you may directly specify a Gitblit instance to pull from with command-line parameters.
    java -jar fedclient.jar --url https://go.gitblit.com --mirror --bare --token 123456789
         --repositoriesFolder c:/mymirror
    java -jar fedclient.jar --url https://go.gitblit.com --mirror --bare --token 123456789
         --repositoriesFolder c:/mymirror --daemon --frequency "24 hours"