Skip to content

G
gitlab-ce
Commit 86d52920 authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Mike Jang
Browse files
Options

Edited second half of SSH file 

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/300312
parent 33e02c42
Show whitespace changes
Inline Side-by-side
Showing with 146 additions and 180 deletions
doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
View file @ 86d52920
......@@ -128,7 +128,7 @@ We'll use this variable in the `.gitlab-ci.yml` later, to easily connect to our
![variables page](img/variables_page.png)
We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../ssh/README.md#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project).
We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../user/project/deploy_keys/index.md), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project).
```shell
# As the deployer user on the server
......
doc/ci/ssh_keys/index.md
View file @ 86d52920
......@@ -33,7 +33,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/)
1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load
the private key.
1. Copy the public key to the servers you want to have access to (usually in
`~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys)
`~/.ssh/authorized_keys`) or add it as a [deploy key](../../user/project/deploy_keys/index.md)
if you are accessing a private GitLab repository.
The private key is displayed in the job log, unless you enable
......@@ -101,7 +101,7 @@ to access it. This is where an SSH key pair comes in handy.
1. As a final step, add the _public_ key from the one you created in the first
step to the services that you want to have an access to from within the build
environment. If you are accessing a private GitLab repository you need to add
it as a [deploy key](../../ssh/README.md#deploy-keys).
it as a [deploy key](../../user/project/deploy_keys/index.md).
That's it! You can now have access to private servers or repositories in your
build environment.
......@@ -130,7 +130,7 @@ on, and use that key for all projects that are run on this machine.
1. As a final step, add the _public_ key from the one you created earlier to the
services that you want to have an access to from within the build environment.
If you are accessing a private GitLab repository you need to add it as a
[deploy key](../../ssh/README.md#deploy-keys).
[deploy key](../../user/project/deploy_keys/index.md).
After generating the key, try to sign in to the remote server to accept the
fingerprint:
......
doc/integration/jenkins_deprecated.md
View file @ 86d52920
......@@ -42,7 +42,7 @@ In GitLab, perform the following steps.
Jenkins needs read access to the GitLab repository. We already specified a
private key to use in Jenkins, now we need to add a public one to the GitLab
project. For that case we need a Deploy key. Read the documentation on
[how to set up a Deploy key](../ssh/README.md#deploy-keys).
[how to set up a Deploy key](../user/project/deploy_keys/index.md).
### Jenkins service
......
doc/ssh/README.md
View file @ 86d52920
......@@ -7,19 +7,12 @@ type: howto, reference
# GitLab and SSH keys
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.
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.
The SSH protocol provides this security and allows you to authenticate to the
GitLab remote server without supplying your username or password each time.
This page can help you configure secure SSH keys which you can use to help secure
connections to GitLab repositories.
- If you need information on creating SSH keys, start with our [options for SSH keys](#supported-ssh-key-types).
- 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).
- 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).
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
......@@ -31,7 +24,7 @@ To use SSH to communicate with GitLab, you need:
To view the version of SSH installed on your system, run `ssh -V`.
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).
but you can set up SSH keys on the Windows [client](#use-ssh-on-microsoft-windows).
## Supported SSH key types
......@@ -104,10 +97,10 @@ If you do not have an existing SSH key pair, generate a new one.
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](#deploy-keys)
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](#working-with-non-default-ssh-key-pair-paths).
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/):
......@@ -122,11 +115,43 @@ 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` (SSH config manual)](https://man.openbsd.org/ssh_config) page.
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 type this command:
1. Open a terminal and run this command:
```shell
ssh-keygen -p -f /path/to/ssh_key
......@@ -140,7 +165,7 @@ 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 type this command:
1. Open a terminal and run this command:
```shell
ssh-keygen -o -f ~/.ssh/id_rsa
......@@ -155,11 +180,10 @@ OpenSSH format.
## Add an SSH key to your GitLab account
Now you can copy the SSH key you created to your GitLab account.
To use SSH with GitLab, copy your public key to your GitLab account.
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:
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:**
......@@ -167,7 +191,7 @@ Now you can copy the SSH key you created to your GitLab account.
pbcopy < ~/.ssh/id_ed25519.pub
```
**Linux (requires the `xclip` package):**
**Linux** (requires the `xclip` package):
```shell
xclip -sel clip < ~/.ssh/id_ed25519.pub
......@@ -179,128 +203,83 @@ Now you can copy the SSH key you created to your GitLab account.
cat ~/.ssh/id_ed25519.pub | clip
```
If you're using an RSA key, substitute accordingly.
Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA.
1. Navigate to `https://gitlab.com` or your local GitLab instance URL and sign in.
1. In the top-right corner, select your avatar.
1. Select **Edit profile**.
1. In the left sidebar, select **SSH Keys**.
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
1. Sign in to GitLab.
1. In the top right corner, select your avatar.
1. Select **Settings**.
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. 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.
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).
1. Select **Add key**.
SSH keys that have "expired" using this procedure are valid in GitLab workflows.
As the GitLab-configured expiration date is not included in the SSH key itself,
you can still export public SSH keys as needed.
## Verify that you can connect
NOTE:
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.
Verify that your SSH key was added correctly.
## Two-factor Authentication (2FA)
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:
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).
## Testing that everything is set up correctly
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):
```shell
ssh -T git@gitlab.com
```
The first time you connect to GitLab via SSH, you should verify the
authenticity of the GitLab host that you're connecting to.
For example, when connecting to GitLab.com, answer `yes` to add GitLab.com to
the list of trusted hosts:
```plaintext
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.
```
NOTE:
For GitLab.com, consult the
[SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints),
section to make sure you're connecting to the correct server. For example, you can see
the ECDSA key fingerprint shown above in the linked section.
Once added to the list of known hosts, you should validate the
authenticity of the GitLab host, once again. Run the above command
again, and you should receive a _Welcome to GitLab, `@username`!_ message.
```shell
ssh -T git@gitlab.example.com
```
If the welcome message doesn't appear, you can troubleshoot the problem by running `ssh`
in verbose mode with the following command:
1. If this is the first time you connect, you should verify the
authenticity of the GitLab host. If you see a message like:
```shell
ssh -Tvvv git@gitlab.com
```
```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.
```
## Working with non-default SSH key pair paths
Type `yes` and press Enter.
If you used a non-default file path for your GitLab SSH key pair,
configure your SSH client to point to your GitLab private SSH key.
1. Run the `ssh -T git@gitlab.example.com` command again. You should receive a _Welcome to GitLab, `@username`!_ message.
To make these changes, run the following commands:
If the welcome message doesn't appear, you can troubleshoot by running `ssh`
in verbose mode:
```shell
eval $(ssh-agent -s)
ssh-add <path to private SSH key>
```
Now save these settings to the `~/.ssh/config` file. Two examples
for SSH keys dedicated to GitLab are shown here:
```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
ssh -Tvvv git@gitlab.example.com
```
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,
that's why it needs to uniquely map to a single user.
## Use different keys for different repositories
## Per-repository SSH keys
You can use a different key for each repository.
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:
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 does not use the SSH Agent and requires at least Git 2.10.
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`.
## Multiple accounts on a single GitLab instance
## Use different 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.
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.
Alternatively, it is possible to directly assign aliases to hosts in
`~.ssh/config`. SSH and, by extension, Git fails to log in if there is
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.
Instead, you can assign aliases to hosts in the `~.ssh/config` file.
NOTE:
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>`.
- 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
......@@ -316,59 +295,60 @@ Host <user_2.gitlab.com>
IdentityFile ~/.ssh/<example_ssh_key2>
```
NOTE:
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
understand when using other tools such as `git remote` sub-commands. SSH
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:
```shell
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`:
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
```
Fix a previously cloned repository using the `git remote` command.
The example below assumes the remote repository is aliased as `origin`.
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
```
## Deploy keys
NOTE:
Private and public keys contain sensitive data. Ensure the permissions
on the files make them readable to you but not accessible to others.
Read the [documentation on deploy keys](../user/project/deploy_keys/index.md).
## Configure two-factor authentication (2FA)
## Applications
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).
### Eclipse
## 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).
## SSH on the GitLab server
## Use SSH on Microsoft Windows
GitLab integrates with the system-installed SSH daemon, designating a user
If you're running Windows 10, you can 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).
You can use WSL to install Linux distributions, which include the Git and SSH clients.
For other versions of Windows, you can install the Git and SSH clients by using
[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)
## 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
connecting to the GitLab server over SSH are identified by their SSH key instead
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. 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
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.
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:
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
......@@ -383,30 +363,16 @@ Git user has default SSH configuration? ... no
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.
### Options for Microsoft Windows
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,
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)
Remove the custom configuration as soon as you can. These customizations
are **explicitly not supported** and may stop working at any time.
## Troubleshooting
## Troubleshooting SSH connections
If on Git clone you are prompted for a password like `git@gitlab.com's password:`
something is wrong with your SSH setup.
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 manually registering your private SSH key using `ssh-agent` as documented
earlier in this document
- Try to debug the connection by running `ssh -Tv git@example.com`
(replacing `example.com` with your GitLab domain)
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.
doc/topics/git/troubleshooting_git.md
View file @ 86d52920
......@@ -45,7 +45,7 @@ set to 50MB. The default is 1MB.
**If pushing over SSH**, first check your SSH configuration as 'Broken pipe'
errors can sometimes be caused by underlying issues with SSH (such as
authentication). Make sure that SSH is correctly configured by following the
instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) documentation.
instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting-ssh-connections) documentation.
If you're a GitLab administrator and have access to the server, you can also prevent
session timeouts by configuring SSH `keep alive` either on the client or on the server.
......
doc/user/admin_area/index.md
View file @ 86d52920
......@@ -33,7 +33,7 @@ The Admin Area is made up of the following sections:
| **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). |
| **{push-rules}** Push rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM SELF)** |
| **{location-dot}** Geo **(PREMIUM SELF)** | Configure and maintain [Geo nodes](geo_nodes.md). |
| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). |
| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../project/deploy_keys/index.md). |
| **{lock}** Credentials **(ULTIMATE SELF)** | View [credentials](credentials_inventory.md) that can be used to access your instance. |
| **{template}** Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. |
| **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. |
......
doc/user/project/deploy_tokens/index.md
View file @ 86d52920
......@@ -20,7 +20,7 @@ Deploy tokens can be managed by [maintainers only](../../permissions.md).
Deploy tokens cannot be used with the GitLab API.
If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys)
If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md)
instead.
## Creating a Deploy Token
......
doc/user/project/repository/repository_mirroring.md
View file @ 86d52920
......@@ -340,7 +340,7 @@ If you're mirroring over SSH (that is, using an `ssh://` URL), you can authentic
- Password-based authentication, just as over HTTPS.
- Public key authentication. This is often more secure than password authentication,
especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys).
especially when the other repository supports [deploy keys](../deploy_keys/index.md).
To get started:
......@@ -401,7 +401,7 @@ GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SS
You then need to add the public SSH key to the other repository's configuration:
- If the other repository is hosted on GitLab, you should add the public SSH key
as a [deploy key](../../../ssh/README.md#deploy-keys).
as a [deploy key](../../project/deploy_keys/index.md).
- If the other repository is hosted elsewhere, you may need to add the key to
your user's `authorized_keys` file. Paste the entire public SSH key into the
file on its own line and save it.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7