debian-mirror-gitlab/doc/ssh/README.md

413 lines
15 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2021-01-03 14:25:43 +05:30
stage: Manage
group: Access
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2019-09-04 21:01:54 +05:30
type: howto, reference
---
2018-03-17 18:26:18 +05:30
# GitLab and SSH keys
2014-09-02 18:07:02 +05:30
2020-04-22 19:07:51 +05:30
Git is a distributed version control system, which means you can work locally.
In addition, you can also share or "push" your changes to other servers.
GitLab supports secure communication between Git and its servers using SSH keys.
2015-04-26 12:48:37 +05:30
2017-08-17 22:00:37 +05:30
The SSH protocol provides this security and allows you to authenticate to the
GitLab remote server without supplying your username or password each time.
2020-04-22 19:07:51 +05:30
This page can help you configure secure SSH keys which you can use to help secure
connections to GitLab repositories.
2021-03-11 19:13:27 +05:30
- If you need information on creating SSH keys, start with our [options for SSH keys](#supported-ssh-key-types).
2020-04-22 19:07:51 +05:30
- If you have SSH keys dedicated for your GitLab account, you may be interested in [Working with non-default SSH key pair paths](#working-with-non-default-ssh-key-pair-paths).
2021-03-11 19:13:27 +05:30
- If you already have an SSH key pair, you can go to how you can [add an SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account).
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
## Prerequisites
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
To use SSH to communicate with GitLab, you need:
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
- The OpenSSH client, which comes pre-installed on GNU/Linux, macOS, and Windows 10.
- SSH version 6.5 or later. Earlier versions used an MD5 signature, which is not secure.
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
To view the version of SSH installed on your system, run `ssh -V`.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
GitLab does [not support installation on Microsoft Windows](../install/requirements.md#microsoft-windows),
but you can set up SSH keys on the Windows [client](#options-for-microsoft-windows).
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
## Supported SSH key types
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
To communicate with GitLab, you can use the following SSH key types:
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
- [ED25519](#ed25519-ssh-keys)
- [RSA](#rsa-ssh-keys)
- DSA ([Deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) in GitLab 11.0.)
- ECDSA (As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA.)
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
Administrators can [restrict which keys are permitted and their minimum lengths](../security/ssh_keys_restrictions.md).
2015-04-26 12:48:37 +05:30
2019-09-04 21:01:54 +05:30
### ED25519 SSH keys
2015-04-26 12:48:37 +05:30
2020-04-22 19:07:51 +05:30
The book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures)
suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and performant than RSA keys.
2018-03-27 19:54:05 +05:30
2021-03-11 19:13:27 +05:30
OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most
operating systems.
2019-09-04 21:01:54 +05:30
2021-03-11 19:13:27 +05:30
### RSA SSH keys
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
Available documentation suggests that ED25519 is more secure than RSA.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
If you use an RSA key, the US National Institute of Science and Technology in
[Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf)
recommends a key size of at least 2048 bits. The default key size depends on your version of `ssh-keygen`.
Review the `man` page for your installed `ssh-keygen` command for details.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
## See if you have an existing SSH key pair
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
Before you create a key pair, see if a key pair already exists.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
1. On Linux or macOS, go to your home directory.
1. Go to the `.ssh/` subdirectory.
1. See if a file with one of the following formats exists:
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
| Algorithm | Public key | Private key |
| --------- | ---------- | ----------- |
| ED25519 (preferred) | `id_ed25519.pub` | `id_ed25519` |
| RSA (at least 2048-bit key size) | `id_rsa.pub` | `id_rsa` |
| DSA (deprecated) | `id_dsa.pub` | `id_dsa` |
| ECDSA | `id_ecdsa.pub` | `id_ecdsa` |
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
## Generate an SSH key pair
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
If you do not have an existing SSH key pair, generate a new one.
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
1. Open a terminal.
1. Type `ssh-keygen -t` followed by the key type and an optional comment.
This comment is included in the `.pub` file that's created.
You may want to use an email address for the comment.
For example, for ED25519:
2016-08-24 12:49:21 +05:30
2021-03-11 19:13:27 +05:30
```shell
ssh-keygen -t ed25519 -C "<comment>"
```
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
For 2048-bit RSA:
2016-08-24 12:49:21 +05:30
2021-03-11 19:13:27 +05:30
```shell
ssh-keygen -t rsa -b 2048 -C "<comment>"
```
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
1. Press Enter. Output similar to the following is displayed:
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
```plaintext
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
```
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
1. Accept the suggested filename and directory, unless you are generating a [deploy key](#deploy-keys)
or want to save in a specific directory where you store other keys.
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
You can also dedicate the SSH key pair to a [specific host](#working-with-non-default-ssh-key-pair-paths).
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase/):
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
```plaintext
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
1. A confirmation is displayed, including information about where your files are stored.
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
A public and private key are generated.
[Add the public SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account) and keep
the private key secure.
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
### Update your SSH key passphrase
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
You can update the passphrase for your SSH key.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
1. Open a terminal and type this command:
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
```shell
ssh-keygen -p -f /path/to/ssh_key
```
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
1. At the prompts, type the passphrase and press Enter.
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
### Upgrade your RSA key pair to a more secure format
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
If your version of OpenSSH is between 6.5 and 7.8,
you can save your private RSA SSH keys in a more secure
2020-04-22 19:07:51 +05:30
OpenSSH format.
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
1. Open a terminal and type this command:
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
```shell
ssh-keygen -o -f ~/.ssh/id_rsa
```
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
Alternatively, you can generate a new RSA key with the more secure encryption format with
the following command:
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
```shell
ssh-keygen -o -t rsa -b 4096 -C "<comment>"
```
2018-11-18 11:00:15 +05:30
2021-03-11 19:13:27 +05:30
## Add an SSH key to your GitLab account
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
Now you can copy the SSH key you created to your GitLab account.
2020-04-22 19:07:51 +05:30
1. Copy your **public** SSH key to a location that saves information in text format.
The following options saves information for ED25519 keys to the clipboard
for the noted operating system:
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
**macOS:**
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
pbcopy < ~/.ssh/id_ed25519.pub
```
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
**Linux (requires the `xclip` package):**
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
xclip -sel clip < ~/.ssh/id_ed25519.pub
```
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
**Git Bash on Windows:**
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
cat ~/.ssh/id_ed25519.pub | clip
```
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
If you're using an RSA key, substitute accordingly.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
1. Navigate to `https://gitlab.com` or your local GitLab instance URL and sign in.
2021-03-11 19:13:27 +05:30
1. In the top-right corner, select your avatar.
1. Select **Edit profile**.
1. In the left sidebar, select **SSH Keys**.
2020-04-22 19:07:51 +05:30
1. Paste the public key that you copied into the **Key** text box.
1. Make sure your key includes a descriptive name in the **Title** text box, such as _Work Laptop_ or
_Home Workstation_.
1. Include an (optional) expiry date for the key under "Expires at" section. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243).)
1. Click the **Add key** button.
2017-08-17 22:00:37 +05:30
2020-10-24 23:57:45 +05:30
SSH keys that have "expired" using this procedure are valid in GitLab workflows.
2020-04-22 19:07:51 +05:30
As the GitLab-configured expiration date is not included in the SSH key itself,
you can still export public SSH keys as needed.
2020-04-08 14:13:33 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2020-04-22 19:07:51 +05:30
If you manually copied your public SSH key make sure you copied the entire
key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email address.
2018-12-13 13:39:08 +05:30
2021-02-22 17:27:13 +05:30
## Two-factor Authentication (2FA)
You can set up two-factor authentication (2FA) for
[Git over SSH](../security/two_factor_authentication.md#two-factor-authentication-2fa-for-git-over-ssh-operations).
2018-12-13 13:39:08 +05:30
## Testing that everything is set up correctly
2021-02-22 17:27:13 +05:30
To test whether your SSH key was added correctly, run the following
command in your terminal (replace `gitlab.com` with the domain of
your GitLab instance):
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2018-12-13 13:39:08 +05:30
ssh -T git@gitlab.com
```
2020-10-24 23:57:45 +05:30
The first time you connect to GitLab via SSH, you should verify the
2020-04-22 19:07:51 +05:30
authenticity of the GitLab host that you're connecting to.
2019-02-15 15:39:39 +05:30
For example, when connecting to GitLab.com, answer `yes` to add GitLab.com to
the list of trusted hosts:
2020-04-08 14:13:33 +05:30
```plaintext
2019-02-15 15:39:39 +05:30
The authenticity of host 'gitlab.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts.
```
2021-02-22 17:27:13 +05:30
NOTE:
2019-02-15 15:39:39 +05:30
For GitLab.com, consult the
[SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints),
2020-10-24 23:57:45 +05:30
section to make sure you're connecting to the correct server. For example, you can see
2020-04-22 19:07:51 +05:30
the ECDSA key fingerprint shown above in the linked section.
2019-02-15 15:39:39 +05:30
2020-10-24 23:57:45 +05:30
Once added to the list of known hosts, you should validate the
2021-02-22 17:27:13 +05:30
authenticity of the GitLab host, once again. Run the above command
again, and you should receive a _Welcome to GitLab, `@username`!_ message.
2018-12-13 13:39:08 +05:30
2020-04-22 19:07:51 +05:30
If the welcome message doesn't appear, you can troubleshoot the problem by running `ssh`
in verbose mode with the following command:
```shell
ssh -Tvvv git@gitlab.com
```
2017-08-17 22:00:37 +05:30
## Working with non-default SSH key pair paths
If you used a non-default file path for your GitLab SSH key pair,
2020-04-22 19:07:51 +05:30
configure your SSH client to point to your GitLab private SSH key.
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
To make these changes, run the following commands:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2017-08-17 22:00:37 +05:30
eval $(ssh-agent -s)
2020-04-22 19:07:51 +05:30
ssh-add <path to private SSH key>
2015-04-26 12:48:37 +05:30
```
2020-04-22 19:07:51 +05:30
Now save these settings to the `~/.ssh/config` file. Two examples
for SSH keys dedicated to GitLab are shown here:
2017-08-17 22:00:37 +05:30
2018-12-13 13:39:08 +05:30
```conf
# GitLab.com
2017-08-17 22:00:37 +05:30
Host gitlab.com
2018-12-13 13:39:08 +05:30
Preferredauthentications publickey
IdentityFile ~/.ssh/gitlab_com_rsa
2015-04-26 12:48:37 +05:30
2018-12-13 13:39:08 +05:30
# Private GitLab instance
2017-08-17 22:00:37 +05:30
Host gitlab.company.com
2018-12-13 13:39:08 +05:30
Preferredauthentications publickey
IdentityFile ~/.ssh/example_com_rsa
2015-04-26 12:48:37 +05:30
```
2020-10-24 23:57:45 +05:30
Public SSH keys need to be unique to GitLab, as they bind to your account.
Your SSH key is the only identifier you have when pushing code via SSH,
2018-12-13 13:39:08 +05:30
that's why it needs to uniquely map to a single user.
2017-08-17 22:00:37 +05:30
2019-07-07 11:18:12 +05:30
## Per-repository SSH keys
If you want to use different keys depending on the repository you are working
on, you can issue the following command while inside your repository:
2020-03-13 15:44:24 +05:30
```shell
2019-07-07 11:18:12 +05:30
git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
```
2020-10-24 23:57:45 +05:30
This does not use the SSH Agent and requires at least Git 2.10.
2019-07-07 11:18:12 +05:30
2020-01-01 13:55:28 +05:30
## Multiple accounts on a single GitLab instance
The [per-repository](#per-repository-ssh-keys) method also works for using
multiple accounts within a single GitLab instance.
Alternatively, it is possible to directly assign aliases to hosts in
2020-10-24 23:57:45 +05:30
`~.ssh/config`. SSH and, by extension, Git fails to log in if there is
2020-01-01 13:55:28 +05:30
an `IdentityFile` set outside of a `Host` block in `.ssh/config`. This is
due to how SSH assembles `IdentityFile` entries and is not changed by
setting `IdentitiesOnly` to `yes`. `IdentityFile` entries should point to
the private key of an SSH key pair.
2021-02-22 17:27:13 +05:30
NOTE:
2020-01-01 13:55:28 +05:30
Private and public keys should be readable by the user only. Accomplish this
on Linux and macOS by running: `chmod 0400 ~/.ssh/<example_ssh_key>` and
`chmod 0400 ~/.ssh/<example_sh_key.pub>`.
```conf
# User1 Account Identity
Host <user_1.gitlab.com>
Hostname gitlab.com
PreferredAuthentications publickey
IdentityFile ~/.ssh/<example_ssh_key1>
# User2 Account Identity
Host <user_2.gitlab.com>
Hostname gitlab.com
PreferredAuthentications publickey
IdentityFile ~/.ssh/<example_ssh_key2>
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-01-01 13:55:28 +05:30
The example `Host` aliases are defined as `user_1.gitlab.com` and
`user_2.gitlab.com` for efficiency and transparency. Advanced configurations
are more difficult to maintain; using this type of alias makes it easier to
2020-06-23 00:09:42 +05:30
understand when using other tools such as `git remote` sub-commands. SSH
2020-01-01 13:55:28 +05:30
would understand any string as a `Host` alias thus `Tanuki1` and `Tanuki2`,
despite giving very little context as to where they point, would also work.
Cloning the `gitlab` repository normally looks like this:
2020-03-13 15:44:24 +05:30
```shell
2020-01-01 13:55:28 +05:30
git clone git@gitlab.com:gitlab-org/gitlab.git
```
To clone it for `user_1`, replace `gitlab.com` with the SSH alias `user_1.gitlab.com`:
2020-03-13 15:44:24 +05:30
```shell
2020-01-01 13:55:28 +05:30
git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
```
Fix a previously cloned repository using the `git remote` command.
The example below assumes the remote repository is aliased as `origin`.
2020-03-13 15:44:24 +05:30
```shell
2020-01-01 13:55:28 +05:30
git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
```
2015-04-26 12:48:37 +05:30
## Deploy keys
2021-03-11 19:13:27 +05:30
Read the [documentation on deploy keys](../user/project/deploy_keys/index.md).
2018-03-27 19:54:05 +05:30
2015-09-11 14:41:01 +05:30
## Applications
### Eclipse
2019-09-04 21:01:54 +05:30
If you are using [EGit](https://www.eclipse.org/egit/), you can [add your SSH key to Eclipse](https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration).
2015-09-11 14:41:01 +05:30
2018-03-17 18:26:18 +05:30
## SSH on the GitLab server
GitLab integrates with the system-installed SSH daemon, designating a user
(typically named `git`) through which all access requests are handled. Users
connecting to the GitLab server over SSH are identified by their SSH key instead
of their username.
2020-10-24 23:57:45 +05:30
SSH *client* operations performed on the GitLab server are executed as this
2018-03-17 18:26:18 +05:30
user. Although it is possible to modify the SSH configuration for this user to,
e.g., provide a private SSH key to authenticate these requests by, this practice
is **not supported** and is strongly discouraged as it presents significant
security risks.
2020-10-24 23:57:45 +05:30
The GitLab check process includes a check for this condition, and directs you
to this section if your server is configured like this, for example:
2018-03-17 18:26:18 +05:30
2020-04-08 14:13:33 +05:30
```shell
2018-03-17 18:26:18 +05:30
$ gitlab-rake gitlab:check
2020-04-08 14:13:33 +05:30
2018-03-17 18:26:18 +05:30
Git user has default SSH configuration? ... no
Try fixing it:
mkdir ~/gitlab-check-backup-1504540051
sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
For more information see:
doc/ssh/README.md in section "SSH on the GitLab server"
Please fix the error above and rerun the checks.
```
Remove the custom configuration as soon as you're able to. These customizations
are *explicitly not supported* and may stop working at any time.
2020-04-22 19:07:51 +05:30
### Options for Microsoft Windows
2020-07-28 23:09:34 +05:30
If you're running Windows 10, the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and its latest [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2) version,
2020-04-22 19:07:51 +05:30
support the installation of different Linux distributions, which include the Git and SSH clients.
For current versions of Windows, you can also install the Git and SSH clients with
[Git for Windows](https://gitforwindows.org).
Alternative tools include:
- [Cygwin](https://www.cygwin.com)
- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
2017-08-17 22:00:37 +05:30
## Troubleshooting
2015-09-11 14:41:01 +05:30
2017-08-17 22:00:37 +05:30
If on Git clone you are prompted for a password like `git@gitlab.com's password:`
something is wrong with your SSH setup.
2015-09-11 14:41:01 +05:30
2017-08-17 22:00:37 +05:30
- Ensure that you generated your SSH key pair correctly and added the public SSH
key to your GitLab profile
2018-03-17 18:26:18 +05:30
- Try manually registering your private SSH key using `ssh-agent` as documented
2017-08-17 22:00:37 +05:30
earlier in this document
- Try to debug the connection by running `ssh -Tv git@example.com`
(replacing `example.com` with your GitLab domain)