summaryrefslogtreecommitdiff
path: root/doc/ssh/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ssh/index.md')
-rw-r--r--doc/ssh/index.md385
1 files changed, 385 insertions, 0 deletions
diff --git a/doc/ssh/index.md b/doc/ssh/index.md
new file mode 100644
index 00000000000..fd95a483344
--- /dev/null
+++ b/doc/ssh/index.md
@@ -0,0 +1,385 @@
+---
+stage: Manage
+group: Access
+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"
+type: howto, reference
+---
+
+# GitLab and SSH keys
+
+Git is a distributed version control system, which means you can work locally,
+then share or "push" your changes to a server. In this case, the server is GitLab.
+
+GitLab uses the SSH protocol to securely communicate with Git.
+When you use SSH keys to authenticate to the GitLab remote server,
+you don't need to supply your username and password each time.
+
+## Prerequisites
+
+To use SSH to communicate with GitLab, you need:
+
+- 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.
+
+To view the version of SSH installed on your system, run `ssh -V`.
+
+## Supported SSH key types
+
+To communicate with GitLab, you can use the following SSH key types:
+
+- [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.)
+
+Administrators can [restrict which keys are permitted and their minimum lengths](../security/ssh_keys_restrictions.md).
+
+### ED25519 SSH keys
+
+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.
+
+OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most
+operating systems.
+
+### RSA SSH keys
+
+Available documentation suggests that ED25519 is more secure than RSA.
+
+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.
+
+## See if you have an existing SSH key pair
+
+Before you create a key pair, see if a key pair already exists.
+
+1. On Windows, Linux, or macOS, go to your home directory.
+1. Go to the `.ssh/` subdirectory. If the `.ssh/` subdirectory doesn't exist,
+ you are either not in the home directory, or you haven't used `ssh` before.
+ In the latter case, you need to [generate an SSH key pair](#generate-an-ssh-key-pair).
+1. See if a file with one of the following formats exists:
+
+ | 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` |
+
+## Generate an SSH key pair
+
+If you do not have an existing SSH key pair, generate a new one.
+
+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:
+
+ ```shell
+ ssh-keygen -t ed25519 -C "<comment>"
+ ```
+
+ For 2048-bit RSA:
+
+ ```shell
+ ssh-keygen -t rsa -b 2048 -C "<comment>"
+ ```
+
+1. Press Enter. Output similar to the following is displayed:
+
+ ```plaintext
+ Generating public/private ed25519 key pair.
+ Enter file in which to save the key (/home/user/.ssh/id_ed25519):
+ ```
+
+1. Accept the suggested filename and directory, unless you are generating a [deploy key](../user/project/deploy_keys/index.md)
+ or want to save in a specific directory where you store other keys.
+
+ You can also dedicate the SSH key pair to a [specific host](#configure-ssh-to-point-to-a-different-directory).
+
+1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase):
+
+ ```plaintext
+ Enter passphrase (empty for no passphrase):
+ Enter same passphrase again:
+ ```
+
+1. A confirmation is displayed, including information about where your files are stored.
+
+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.
+
+### Configure SSH to point to a different directory
+
+If you did not save your SSH key pair in the default directory,
+configure your SSH client to point to the directory where the private key is stored.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ eval $(ssh-agent -s)
+ ssh-add <directory to private SSH key>
+ ```
+
+1. Save these settings in the `~/.ssh/config` file. For example:
+
+ ```conf
+ # GitLab.com
+ Host gitlab.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/gitlab_com_rsa
+
+ # Private GitLab instance
+ Host gitlab.company.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/example_com_rsa
+ ```
+
+ For more information on these settings, see the [`man ssh_config`](https://man.openbsd.org/ssh_config) page in the SSH configuration manual.
+
+Public SSH keys must be unique to GitLab because they bind to your account.
+Your SSH key is the only identifier you have when you push code with SSH.
+It must uniquely map to a single user.
+
+### Update your SSH key passphrase
+
+You can update the passphrase for your SSH key.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ ssh-keygen -p -f /path/to/ssh_key
+ ```
+
+1. At the prompts, type the passphrase and press Enter.
+
+### Upgrade your RSA key pair to a more secure format
+
+If your version of OpenSSH is between 6.5 and 7.8,
+you can save your private RSA SSH keys in a more secure
+OpenSSH format.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ ssh-keygen -o -f ~/.ssh/id_rsa
+ ```
+
+ Alternatively, you can generate a new RSA key with the more secure encryption format with
+ the following command:
+
+ ```shell
+ ssh-keygen -o -t rsa -b 4096 -C "<comment>"
+ ```
+
+## Add an SSH key to your GitLab account
+
+To use SSH with GitLab, copy your public key to your GitLab account.
+
+1. Copy the contents of your public key file. You can do this manually or use a script.
+ For example, to copy an ED25519 key to the clipboard:
+
+ **macOS:**
+
+ ```shell
+ tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
+ ```
+
+ **Linux** (requires the `xclip` package):
+
+ ```shell
+ xclip -sel clip < ~/.ssh/id_ed25519.pub
+ ```
+
+ **Git Bash on Windows:**
+
+ ```shell
+ cat ~/.ssh/id_ed25519.pub | clip
+ ```
+
+ Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA.
+
+1. Sign in to GitLab.
+1. In the top right corner, select your avatar.
+1. Select **Preferences**.
+1. From the left sidebar, select **SSH Keys**.
+1. In the **Key** box, paste the contents of your public key.
+ If you manually copied the key, make sure you copy the entire key,
+ which starts with `ssh-ed25519` or `ssh-rsa`, and may end with a comment.
+1. In the **Title** text box, type a description, like _Work Laptop_ or
+ _Home Workstation_.
+1. Optional. In the **Expires at** box, select an expiration date. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243).)
+ The expiration date is informational only, and does not prevent you from using
+ the key. However, administrators can view expiration dates and
+ use them for guidance when [deleting keys](../user/admin_area/credentials_inventory.md#delete-a-users-ssh-key).
+ - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
+ - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
+1. Select **Add key**.
+
+## Verify that you can connect
+
+Verify that your SSH key was added correctly.
+
+1. For GitLab.com, to ensure you're connecting to the correct server, confirm the
+ [SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints).
+1. Open a terminal and run this command, replacing `gitlab.example.com` with your GitLab instance URL:
+
+ ```shell
+ ssh -T git@gitlab.example.com
+ ```
+
+1. If this is the first time you connect, you should verify the
+ authenticity of the GitLab host. If you see a message like:
+
+ ```plaintext
+ The authenticity of host 'gitlab.example.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.example.com' (ECDSA) to the list of known hosts.
+ ```
+
+ Type `yes` and press Enter.
+
+1. Run the `ssh -T git@gitlab.example.com` command again. You should receive a _Welcome to GitLab, `@username`!_ message.
+
+If the welcome message doesn't appear, you can troubleshoot by running `ssh`
+in verbose mode:
+
+```shell
+ssh -Tvvv git@gitlab.example.com
+```
+
+## Use different keys for different repositories
+
+You can use a different key for each repository.
+
+Open a terminal and run this command:
+
+```shell
+git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
+```
+
+This command does not use the SSH Agent and requires Git 2.10 or later. For more information
+on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`.
+
+## Use different accounts on a single GitLab instance
+
+You can use multiple accounts to connect to a single instance of GitLab.
+You can do this by using the command in the [previous topic](#use-different-keys-for-different-repositories).
+However, even if you set `IdentitiesOnly` to `yes`, you cannot sign in if an `IdentityFile` exists
+outside of a `Host` block.
+
+Instead, you can assign aliases to hosts in the `~.ssh/config` file.
+
+- For the `Host`, use an alias like `user_1.gitlab.com` and
+ `user_2.gitlab.com`. Advanced configurations
+ are more difficult to maintain, and these strings are easier to
+ understand when you use tools like `git remote`.
+- For the `IdentityFile`, use the path the private key.
+
+```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>
+```
+
+Now, to clone a repository for `user_1`, use `user_1.gitlab.com` in the `git clone` command:
+
+```shell
+git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
+```
+
+To update a previously-cloned repository that is aliased as `origin`:
+
+```shell
+git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
+```
+
+NOTE:
+Private and public keys contain sensitive data. Ensure the permissions
+on the files make them readable to you but not accessible to others.
+
+## Configure 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).
+
+## Use EGit on Eclipse
+
+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).
+
+## Use SSH on Microsoft Windows
+
+If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+with [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2) which
+has both `git` and `ssh` preinstalled, or install [Git for Windows](https://gitforwindows.org) to
+use SSH through Powershell.
+
+The SSH key generated in WSL is not directly available for Git for Windows, and vice versa,
+as both have a different home directory:
+
+- WSL: `/home/<user>`
+- Git for Windows: `C:\Users\<user>`
+
+You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment.
+
+Alternative tools include:
+
+- [Cygwin](https://www.cygwin.com)
+- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
+
+## Overriding SSH settings on the GitLab server
+
+GitLab integrates with the system-installed SSH daemon and designates a user
+(typically named `git`) through which all access requests are handled. Users
+who connect to the GitLab server over SSH are identified by their SSH key instead
+of their username.
+
+SSH *client* operations performed on the GitLab server are executed as this
+user. You can modify this SSH configuration. For example, you can specify
+a private SSH key for this user to use for authentication requests. However, this practice
+is **not supported** and is strongly discouraged as it presents significant
+security risks.
+
+GitLab checks for this condition, and directs you
+to this section if your server is configured this way. For example:
+
+```shell
+$ gitlab-rake gitlab:check
+
+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:
+ [Overriding SSH settings on the GitLab server](#overriding-ssh-settings-on-the-gitlab-server)
+ Please fix the error above and rerun the checks.
+```
+
+Remove the custom configuration as soon as you can. These customizations
+are **explicitly not supported** and may stop working at any time.
+
+## Troubleshooting SSH connections
+
+When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`.
+This indicates that something is wrong with your SSH setup.
+
+- Ensure that you generated your SSH key pair correctly and added the public SSH
+ key to your GitLab profile.
+- Try to manually register your private SSH key by using `ssh-agent`.
+- Try to debug the connection by running `ssh -Tv git@example.com`.
+ Replace `example.com` with your GitLab URL.