Documentation/externalid-case-insensitivity.txt

:linkattrs:
= Gerrit Code Review - ExternalId case insensitivity

Gerrit usernames are case insensitive by default: e.g. `johndoe` and `JohnDoe`
represent the same account. However, for installations older than v3.5.x,
the usernames were case sensitive, e.g. `johndoe` and `JohnDoe` can both exist
as separate accounts. This could lead to issues when migrating an account
from LDAP to an internal account, if
xref:config-gerrit.txt#ldap.localUsernameToLowerCase[ldap.localUsernameToLowerCase]
was set. Such usernames can also be rather confusing for users, if they try to
identify authors of comments or changes.

When Gerrit handles case insensitive usernames (external IDs using the
`gerrit:` or `username:` scheme), their external IDs SHA-1 is always computed
using the lowercase external ID, hence there cannot be any account differing
only in the capitalization of their usernames.

Gerrit installations older than v3.5.x that are switching to the case-insensitive
username need to migrate all their existing accounts SHA-1s.

[[migration]]
== Migration

Migrating external ID notes can take several minutes for large sites(for example
migration ++~++45000 accounts can take up to five minutes), so administrators
choose whether to do the migration offline or online, depending on their
available resources and tolerance for downtime.

NOTE: Migration is required only on Gerrit primary instances.

[[offline-migration]]
=== Offline

To run the offline migration execute following steps:

* Stop all Gerrit primary instances
* Set the `auth.userNameCaseInsensitive` to false

----
[auth]
  userNameCaseInsensitive = false
----

* Run:
[verse]
--
_java_ -jar gerrit.war _ChangeExternalIdCaseSensitivity_
  -d <SITE_PATH>
  [--batch]
--

See: link:pgm-ChangeExternalIdCaseSensitivity.html[]

* During the migration `auth.userNameCaseInsensitive` will be set to true
on a node which is executing the migration. When the migration is finished,
on all other primary nodes set `auth.userNameCaseInsensitive` to true
* Start all Gerrit primary instances

[[online-migration]]
=== Online

To start the online migration, set the `auth.userNameCaseInsensitive` and
`auth.userNameCaseInsensitiveMigrationMode` options in `gerrit.config` and
restart Gerrit:
----
[auth]
  userNameCaseInsensitive = true
  userNameCaseInsensitiveMigrationMode = true
----
* Trigger online migration:
----
$ ssh -p <port> <host> gerrit migrate-externalids-to-insensitive
----

See: link:cmd-migrate-externalids-to-insensitive.html[]

[online-ha-migration]
== Online migration for high-availability setup

To start the online migration with a setup containing multiple primary
instances execute following steps:

* On all Gerrit primary instances set `auth.userNameCaseInsensitive` and
`auth.userNameCaseInsensitiveMigrationMode` and perform a rolling restart
----
[auth]
  userNameCaseInsensitive = true
  userNameCaseInsensitiveMigrationMode = true
----
* Trigger online migration:
----
$ ssh -p <port> <host> gerrit migrate-externalids-to-insensitive
----

See: link:cmd-migrate-externalids-to-insensitive.html[]

* When the migration is finished, on all other primary nodes set
`auth.userNameCaseInsensitiveMigrationMode` to false and perform a
rolling restart
----
[auth]
  userNameCaseInsensitive = true
  userNameCaseInsensitiveMigrationMode = false
----

== External ID case insensitivity rollback

The offline migration tool allows to calculate external ID notes named with the SHA-1
from the case sensitive external ID.

To rollback external ID notes migration execute following steps:

* Stop all Gerrit primary instances
* Set the `auth.userNameCaseInsensitive` to true
----
[auth]
  userNameCaseInsensitive = true
----

* Run:
[verse]
--
_java_ -jar gerrit.war _ChangeExternalIdCaseSensitivity_
  -d <SITE_PATH>
  [--batch]
--

See: link:pgm-ChangeExternalIdCaseSensitivity.html[]

* During the migration `auth.userNameCaseInsensitive` will be set to false
on a node which is executing the migration. When the migration is finished,
on all other primary nodes set `auth.userNameCaseInsensitive` to false
* Start all Gerrit primary instances