SSH
The ssh protocol (Secure Shell) is a cryptographic protocol to log into remote server, calling remote commands, copy data to a server and more. It’s often used to operate in environments without a desktop like our brick.
Installing
Installing ssh is pretty straight forward.
Linux
Most distributions come with ssh already installed. If it’s not installed you can install it via command line:
sudo apt-get install ssh
On some distributions the package is called open-ssh.
If you are not using a Debian-based Linux distribution you may have to use another packet manager.
macOS
macOS has a built-in ssh client. But sometimes it can be tricky to understand how it works.
The following notes might help you to work with the ssh-agent
and the SSH-keys necessary for GitLab/Brick.
MacOS stores keys based on the current session
Reboot or killing the ssh process leads to the agent having no identities
- Stupid solution: After each reboot or killing the ssh process, re-add keys
- Kinda annoying, but works for lifetime of current session
- Solution using AppleKeychain: Add SSH-Key passphrase to AppleKeychain and load Keys with Keychain
- Prepare config for Keychain as follows:
vi ~/.ssh/config
# Enter following lines
Host *
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
IdentityFile <path-to-key1>
IdentityFile <path-to-key2>
- For each identity you want to use, add an
IdentityFile
line - Then, add the corresponding key using
ssh-add --apple-use-keychain <path-to-key>
- IMPORTANT: Only works for keys having a passphrase
- To add a passphrase, run the following:
ssh-keygen -p -f <path-to-key>
- On reboot or restart of
ssh-agent
, runssh-add --apple-load-keychain
- This loads all keys defined in the config file and protected with a passphrase from your Keychain
- How to automate / simplify things:
- Create an alias for
ssh-add --apple-use-keychain
- To run it as a default, follow these steps:
- Create an alias for
vi ~/.zshrc
# Enter following lines
ssh-add --apple-load-keychain > /dev/null 2>&1
- Good-to-know: Executing
ssh-agent
produces anotherssh-agent
process each time- Multiple processes == PROBLEMS - Don’t do that!
Windows
It is strongly recommended using the WSL (Dev > WSL)! After install you must follow the instructions for Linux!
Install native OpenSSH Client
This method is recommended, because it works system-wide and in any command line interface.
You can install a native ssh client provided by Microsoft.
To install open
Settings > Apps > Optional features > Add a feature > OpenSSH Client
[Deprecated] Use GitBash
The GitBash has a built-in ssh client. Note that it is only fully functional when using GitBash and not in cmd, Powershell nor other command line interfaces (this includes the default Terminal in VSCode). This means for every task that involves using ssh (e.g. cloning with ssh, deploy-script…) you need to use the GitBash. If you’re not using the WSL chances are you will need to install the GitBash anyway to use Git.
Generating a key
An ssh-key is used for authentication when using ssh.
In other words by setting up a key and configuring the server you don’t need to enter a password to login anymore.
To generate a key open a command line and run
ssh-keygen
The first thing this command will ask for is a location.
If you never worked with ssh-keys before it’s fine to leave it blank and use the default location.
If you already have used a ssh-key change the location because else the old key eventually will be overwritten.
The other thing is a passphrase.
You can set one, but then you will also need to use it every time you use the key.
So it’s ok to leave that blank too.
After that you key is generated.
Adding the key to Gitlab
To use the \git clone+ command with ssh you need to add your public ssh key to your Gitlab account. \
Get your public key
First you need to get your public key. Find the path you used in the key generation and the key with the .pub+ ending.
The default path is ~/.ssh/id_rsa.pub
on Linux and macOS or C:\Users\your username\.ssh\id_rsa.pub
on Windows.
Open the file in a text-editor and copy everything. Then proceed with the next step.
Add the key to your Gitlab account
Visit Settings > SSH Keys
Paste your previously copied key in the text field. The name and expiration date are optional.
Hit \Add key+ and you’re done!