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 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

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

To run the offline migration execute following steps:

  • Stop all Gerrit primary instances

  • Set the auth.userNameCaseInsensitive to false

[auth]
  userNameCaseInsensitive = false

  • Run:

java -jar gerrit.war ChangeExternalIdCaseSensitivity -d <SITE_PATH> [--batch]

See: 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

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: cmd-migrate-externalids-to-insensitive.html

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: 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:

java -jar gerrit.war ChangeExternalIdCaseSensitivity -d <SITE_PATH> [--batch]

See: 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