Documentation/config-replication.txt

Gerrit2 Git Replication
=======================

Gerrit can automatically push any changes it makes to its managed Git
repositories to another system.  Usually this would be configured to
provide mirroring of changes, for warm-standby backups, or a
load-balanced public mirror farm.

The replication runs on a 15 second delay.  This gives Gerrit a short
time window to batch updates going to the same project, such as when a
user uploads multiple changes at once.

Typically replication should be done over SSH, with a passwordless
public/private key pair.  On a trusted network it is also possible to
use replication over the insecure (but much faster) git:// protocol,
by enabling the `receive-pack` service on the receiving system, but
this configuration is not recommended.

Enabling Replication
--------------------

If replicating over SSH (recommended), ensure the host key of the
remote system(s) is already in the Gerrit user's `~/.ssh/known_hosts`
file.  The easiest way to add the host key is to connect once by hand
with the command line:

====
  sudo su -c 'ssh mirror1.us.some.org echo' gerrit2
====

Next, create `'$site_path'/replication.config` as a Git-style config
file, and restart Gerrit.

Example `replication.config` to replicate in parallel to four
different hosts:

====
  [remote "host-one"]
    url = gerrit2@host-one.example.com:/some/path/${name}.git

  [remote "pubmirror"]
    url = mirror1.us.some.org:/pub/git/${name}.git
    url = mirror2.us.some.org:/pub/git/${name}.git
    url = mirror3.us.some.org:/pub/git/${name}.git
    push = +refs/heads/*
    push = +refs/tags/*
====

File `replication.config`[[replication_config]]
-----------------------------------------------

The optional file `'$site_path'/replication.config` is a Git-style
config file that controls the replication settings for Gerrit.

The file is composed of one or more `remote` sections, each remote
section provides common configuration settings for one or more
destination URLs.

Section remote[[section_remote]]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the keys below, the <name> portion is unused by Gerrit, but must be
unique to distinguish the different sections if more than one remote
section appears in the file.

remote.<name>.url::
+
Address of the remote server to push to.  Multiple URLs may be
specified within a single remote block, listing different destinations
which share the same settings.  Gerrit pushes to all URLs in parallel,
using one thread per URL.
+
Within each URL value the magic placeholder `$\{name}` is replaced
with the Gerrit project name.  This is a Gerrit specific extension
to the otherwise standard Git URL syntax.
+
See link:http://www.kernel.org/pub/software/scm/git/docs/git-push.html#URLS[GIT URLS]
for details on Git URL syntax.

remote.<name>.receivepack::
+
Path of the `git-receive-pack` executable on the remote system, if
using the SSH transport.
+
Defaults to `git receive-pack`, which works on any version of Git so
long as `git` is in the remote user's PATH.

remote.<name>.push::
+
Standard Git refspec denoting what should be replicated.  Setting this
to `+refs/heads/\*:refs/heads/\*` would mirror only the active
branches, but not the change refs under `refs/changes/`, or the tags
under `refs/tags/`.
+
Multiple push keys can be supplied, to specify multiple patterns
to match against.  In the example file above, remote "pubmirror"
uses two push keys to match both `refs/heads/\*` and `refs/tags/*`,
but excludes all others, including `refs/changes/*`.
+
Defaults to `+refs/\*:refs/*` (all refs) if not specified.


File `~/.ssh/config`[[ssh_config]]
----------------------------------

If present, Gerrit reads and caches `~/.ssh/config` at startup, and
supports most SSH configuration options.  For example:

====
  Host host-one.example.com:
    IdentityFile ~/.ssh/id_hostone
    PreferredAuthentications publickey
    BatchMode yes

  Host mirror*.us.some.org:
    User mirror-updater
    IdentityFile ~/.ssh/id_pubmirror
    PreferredAuthentications publickey
    BatchMode yes
====

Supported options:

 * Host
 * Hostname
 * User
 * Port
 * IdentityFile
 * PreferredAuthentications
 * BatchMode
 * StrictHostKeyChecking

SSH authentication must be by passwordless public key, as there is
no facility to read passphases on startup or passwords during the
SSH connection setup, and SSH agents are not supported from Java.

Host keys for any destination SSH servers must appear in the user's
`~/.ssh/known_hosts` file, and must be added in advance, before
Gerrit starts.  If a host key is not listed, Gerrit will be unable to
connect to that destination, and replication to that URL will fail.