Documentation/config-replication.txt - gerrit - Git at Google

 Gerrit Code Review - 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 short delay.  This gives Gerrit a small
 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/*
     threads = 3
     authGroup = Public Mirror Group
     authGroup = Second Public Mirror Group
 ====

 To manually trigger replication at runtime, see
 link:cmd-replicate.html[gerrit replicate].

 [[replication_config]]File `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.

 Each remote section uses its own thread pool.  If pushing to
 multiple remotes, over differing types of network connections
 (e.g. LAN and also public Internet), its a good idea to put them
 into different remote sections, so that replication to the slower
 connection does not starve out the faster local one.  The example
 file above does this.

 [[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]]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.  Assuming sufficient
 threads in the thread pool, 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]]remote.<name>.receivepack::
 +
 Path of the `git-receive-pack` executable on the remote system, if
 using the SSH transport.
 +
 Defaults to `git-receive-pack`.

 [[remote.name.uploadpack]]remote.<name>.uploadpack::
 +
 Path of the `git-upload-pack` executable on the remote system, if
 using the SSH transport.
 +
 Defaults to `git-upload-pack`.

 [[remote.name.push]]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.

 [[remote.name.timeout]]remote.<name>.timeout::
 +
 Number of seconds to wait for a network read or write to complete
 before giving up and declaring the remote side is not responding.
 If 0, there is no timeout, and the push client waits indefinitely.
 +
 A timeout should be large enough to mostly transfer the objects to
 the other side.  1 second may be too small for larger projects,
 especially over a WAN link, while 10-30 seconds is a much more
 reasonable timeout value.
 +
 Defaults to 0 seconds, wait indefinitely.

 [[remote.name.replicationDelay]]remote.<name>.replicationDelay::
 +
 Number of seconds to wait before scheduling a remote push operation.
 Setting the delay to 0 effectively disables the delay, causing the
 push to start as soon as possible.
 +
 This is a Gerrit specific extension to the Git remote block.
 +
 By default, 15 seconds.

 [[remote.name.threads]]remote.<name>.threads::
 +
 Number of worker threads to dedicate to pushing to the repositories
 described by this remote.  Each thread can push one project at a
 time, to one destination URL.  Scheduling within the thread pool
 is done on a per-project basis.  If a remote block describes 4
 URLs, allocating 4 threads in the pool will permit some level of
 parallel pushing.
 +
 By default, 1 thread.

 [[remote.name.authGroup]]remote.<name>.authGroup::
 +
 Specifies the name of a group that the remote should use to access
 the repositories. Multiple authGroups may be specified within a
 single remote block to signify a wider access right. In the project
 administration web interface the read access can be specified for
 this group to control if a project should be replicated or not to the
 remote.
 +
 By default, replicates without group control, i.e replicates
 everything to all remotes.


 [[ssh_config]]File `~/.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

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

 Supported options:

  * Host
  * Hostname
  * User
  * Port
  * IdentityFile
  * PreferredAuthentications
  * 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.

 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
	Gerrit Code Review - 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 short delay. This gives Gerrit a small
	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/*
	threads = 3
	authGroup = Public Mirror Group
	authGroup = Second Public Mirror Group
	====

	To manually trigger replication at runtime, see
	link:cmd-replicate.html[gerrit replicate].

	[[replication_config]]File `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.

	Each remote section uses its own thread pool. If pushing to
	multiple remotes, over differing types of network connections
	(e.g. LAN and also public Internet), its a good idea to put them
	into different remote sections, so that replication to the slower
	connection does not starve out the faster local one. The example
	file above does this.

	[[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]]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. Assuming sufficient
	threads in the thread pool, 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]]remote.<name>.receivepack::
	+
	Path of the `git-receive-pack` executable on the remote system, if
	using the SSH transport.
	+
	Defaults to `git-receive-pack`.

	[[remote.name.uploadpack]]remote.<name>.uploadpack::
	+
	Path of the `git-upload-pack` executable on the remote system, if
	using the SSH transport.
	+
	Defaults to `git-upload-pack`.

	[[remote.name.push]]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.

	[[remote.name.timeout]]remote.<name>.timeout::
	+
	Number of seconds to wait for a network read or write to complete
	before giving up and declaring the remote side is not responding.
	If 0, there is no timeout, and the push client waits indefinitely.
	+
	A timeout should be large enough to mostly transfer the objects to
	the other side. 1 second may be too small for larger projects,
	especially over a WAN link, while 10-30 seconds is a much more
	reasonable timeout value.
	+
	Defaults to 0 seconds, wait indefinitely.

	[[remote.name.replicationDelay]]remote.<name>.replicationDelay::
	+
	Number of seconds to wait before scheduling a remote push operation.
	Setting the delay to 0 effectively disables the delay, causing the
	push to start as soon as possible.
	+
	This is a Gerrit specific extension to the Git remote block.
	+
	By default, 15 seconds.

	[[remote.name.threads]]remote.<name>.threads::
	+
	Number of worker threads to dedicate to pushing to the repositories
	described by this remote. Each thread can push one project at a
	time, to one destination URL. Scheduling within the thread pool
	is done on a per-project basis. If a remote block describes 4
	URLs, allocating 4 threads in the pool will permit some level of
	parallel pushing.
	+
	By default, 1 thread.

	[[remote.name.authGroup]]remote.<name>.authGroup::
	+
	Specifies the name of a group that the remote should use to access
	the repositories. Multiple authGroups may be specified within a
	single remote block to signify a wider access right. In the project
	administration web interface the read access can be specified for
	this group to control if a project should be replicated or not to the
	remote.
	+
	By default, replicates without group control, i.e replicates
	everything to all remotes.


	[[ssh_config]]File `~/.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

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

	Supported options:

	* Host
	* Hostname
	* User
	* Port
	* IdentityFile
	* PreferredAuthentications
	* 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.

	GERRIT
	------
	Part of link:index.html[Gerrit Code Review]