Git / SSH Setup Guide

1. Introduction

This guide explains how to set up SSH keys for secure authentication with Git servers, configure SSH for easy access, troubleshoot common errors, and ensure correct key permissions on your system.

---

2. Generating SSH Keys

SSH keys enable secure, passwordless authentication with remote servers and Git repositories.

Generate a new SSH key pair

bash

복사편집

ssh-keygen -t ed25519 -C "your.email@example.com"

 

• This creates two files in your ~/.ssh/ directory:
  
  

---

3. Set Correct Permissions on SSH Keys

Permissions are crucial; incorrect permissions can cause SSH to ignore your keys.

Run these commands to secure your keys:

bash

복사편집

chmod 700 ~/.ssh

chmod 600 ~/.ssh/id_ed25519

chmod 644 ~/.ssh/id_ed25519.pub

 

• ~/.ssh directory should be accessible only by your user.
  
  
• Private keys (id_ed25519) must have read-write for user only.
  
  
• Public keys (id_ed25519.pub) can be world-readable.
  
  

---

4. Add SSH Key to SSH Agent

To use your SSH key without entering the passphrase every time:

bash

복사편집

eval "$(ssh-agent -s)"        # Start the ssh-agent

ssh-add ~/.ssh/id_ed25519     # Add your private key

 

Verify loaded keys with:

bash

복사편집

ssh-add -l

 

---

5. Upload Your Public Key to the Remote Server or Git Hosting Service

• Copy your public key content:
  
  

bash

복사편집

cat ~/.ssh/id_ed25519.pub

 

• Paste it into your Git hosting service (e.g., GitLab, GitHub) under SSH Keys settings, or add to ~/.ssh/authorized_keys on a remote server you control.
  
  

---

6. Configure SSH Client for Easier Use

Create or edit the SSH config file:

bash

복사편집

nano ~/.ssh/config

 

Example configuration:

bash

복사편집

Host gitlab-company

    HostName git.<company>.com

    User git

    IdentityFile ~/.ssh/id_ed25519

 

This lets you connect with:

bash

복사편집

ssh gitlab-company

 

---

7. Common Errors and How to Fix Them

Error / Message	Cause	Solution
Permission denied (publickey)	Key not added or not authorized	Add key to ssh-agent and upload public key
Asked for password after SSH connection	Key not authorized or wrong user name	Verify authorized_keys and use correct SSH URL
Could not find OpenSSL installation	Missing OpenSSL libs for Rust crate	Install OpenSSL dev libraries and set OPENSSL_DIR env var
ModuleNotFoundError: setuptools_rust	Missing Python package	Install with pip install setuptools-rust

---

8. Testing Your SSH Connection

Test connection to Git host:

bash

복사편집

ssh -T git@gitlab.com