Skip to content

Commit

Permalink
fix
Browse files Browse the repository at this point in the history
  • Loading branch information
@masahide
masahide committed Oct 5, 2024
1 parent 1e4732e commit a2150d0
Showing 1 changed file with 54 additions and 59 deletions.
113 changes: 54 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,68 +7,65 @@
Unifies the chaotic ssh-agent state under Windows.

### The Chaotic State of SSH-Agent on Windows
There are several different communication methods for ssh-agent in Windows, and it is very complicated to use and configure them.
The following diagram shows the current communication methods for Windows ssh-agent.
On Windows, there are multiple communication methods for SSH agents, leading to complexity in usage and configuration. The following diagram illustrates the current SSH agent communication landscape on Windows.
![windows-ssh-agent-chaosmap](https://github.com/masahide/OmniSSHAgent/blob/main/doc/windows-ssh-agent-chaosmap.png?raw=true)


### Connection diagram of OmniSSHAgent
OmniSSHAgent is a program to simplify what used to be a chaotic situation, as shown in the following figure.
### OmniSSHAgent Connection Diagram
OmniSSHAgent simplifies this chaotic situation, as shown in the diagram below.
![OmniSSHAgentmap](https://github.com/masahide/OmniSSHAgent/blob/main/doc/OmniSSHAgent.png?raw=true)

## Required environment for operation
## System Requirements

- Windows10
- Windows 11
- [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)

## The following interfaces are supported
- pageant.exe(PuTTY) shared memory
- Unix domain socket for WSL3
## Supported Interfaces
- Pageant.exe (PuTTY) shared memory
- Unix domain socket for WSL2
- NamedPipe on Windows
- Unix domain socket for WSL1
- Unix domain socket for MSYS2(Cygwin) ( [#1](https://github.com/masahide/OmniSSHAgent/issues/1) )
- Unix domain socket for MSYS2 (Cygwin) ([#1](https://github.com/masahide/OmniSSHAgent/issues/1))

## Usage

1. Download `OmniSSHAgent.zip` from https://github.com/masahide/OmniSSHAgent/releases/latest, unzip it, and place it in a folder of your choice.
2. If you are using Windows native ssh-agent, you'll need to stop and disable it. Open powershell with administrator privileges and execute the following commands.
```bash
1. Download `OmniSSHAgent-amd64-installer.exe` from [the latest release](https://github.com/masahide/OmniSSHAgent/releases/latest), and run the installer.
2. If you are using the native Windows SSH agent, you will need to stop and disable it. Open PowerShell with administrator privileges and run the following commands:
```powershell
Stop-Service ssh-agent
Set-Service -StartupType Disabled ssh-agent
```
- Alternatively, you can set it through the GUI if you prefer.Bring up the start menu and type Services. You’ll see the Services app listed.
Once the Services app is open, find the `OpenSSH Authentication Agent` service and set the `Service Status` to `Stop` and the `Startup Type` to `Disabled`.

3. If you are using [PuTTY Pageant](https://www.chiark.greenend.org.uk/~sgtatham/putty/index.html) - stop it.
- Alternatively, you can do this through the GUI: open the Start menu, type "Services," and select the Services app.
Once open, find the `OpenSSH Authentication Agent` service, set `Service Status` to `Stop`, and `Startup Type` to `Disabled`.

4. Launch `OmniSSHAgent.exe` by double-clicking.
5. Press the `Open new file` button to add a private key file. Or you can use `ssh-add` command or [KeePassXC](https://keepassxc.org/) to add your private key.
3. If you are using [PuTTY Pageant](https://www.chiark.greenend.org.uk/~sgtatham/putty/index.html), stop it.

### Registering for launch on boot
4. Launch `OmniSSHAgent.exe` by double-clicking it.
5. Press the `Open new file` button to add a private key file, or use the `ssh-add` command or [KeePassXC](https://keepassxc.org/) to add your private key.

OmniSSHAgent does not have an installer, nor registers itself to start upon boot. You'll need to do the following to register it:
### Registering for Startup

- Press the Windows logo key + R, type shell:startup, then click OK. This opens the Startup folder.
- Copy and paste the shortcut to the OmniSSHAgent.exe from the file location to the Startup
OmniSSHAgent does not have an installer to register itself for startup automatically. To add it manually:

- Press the Windows logo key + R, type `shell:startup`, and click OK. This opens the Startup folder.
- Copy and paste a shortcut to `OmniSSHAgent.exe` into the Startup folder.

### Using with WSL2
#### Setting up wsl2-ssh-agent-proxy in Ubuntu or Rocky(WSL2).
Choose the instructions for your favourite shell below. If your shell isn't listed here you can convert the bash script to your shell syntax and send a PR to add it to the repo.
#### Setting up wsl2-ssh-agent-proxy in Ubuntu or Rocky (WSL2)
Choose the instructions for your preferred shell below. If your shell is not listed, you can convert the Bash script syntax and submit a pull request to add it to the repository.

##### Bash (and all POSIX-compliant shells)
1. Download [ubuntu.wsl2-ssh-agent-proxy.sh](hack/ubuntu.wsl2-ssh-agent-proxy.sh) with the following command:
1. Download [ubuntu.wsl2-ssh-agent-proxy.sh](hack/ubuntu.wsl2-ssh-agent-proxy.sh) using the following command:
```bash
mkdir -p $HOME/wsl2-ssh-agent-proxy
curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/wsl2-ssh-agent-proxy/hack/ubuntu.wsl2-ssh-agent-proxy.sh -o $HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.sh
```
2. Add the following line to `~/.bashrc`, `~/.zshrc`, or whatever file is applicable to your shell:
2. Add the following line to `~/.bashrc`, `~/.zshrc`, or the appropriate file for your shell:
```bash
source $HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.sh
```

##### Fish
1. Download [ubuntu.wsl2-ssh-agent-proxy.fish](hack/ubuntu.wsl2-ssh-agent-proxy.fish) with the following command:
1. Download [ubuntu.wsl2-ssh-agent-proxy.fish](hack/ubuntu.wsl2-ssh-agent-proxy.fish) using the following command:
```fish
mkdir -p $HOME/wsl2-ssh-agent-proxy
curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/wsl2-ssh-agent-proxy/hack/ubuntu.wsl2-ssh-agent-proxy.fish -o $HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.fish
Expand All @@ -79,63 +76,61 @@ curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/wsl2-ssh-agent-
```

### Using with WSL1
Setting up Unix doman socket in ubuntu environment.
Setting up a Unix domain socket in the Ubuntu environment:


1. Check the setting of `Unix domain socket file path(WSL1):` in OmniSSHAgent.
For example, if you have the following settings.. (`UserName` varies depending on your environment)
1. Check the setting for `Unix domain socket file path (WSL1)` in OmniSSHAgent.
For example, if the path is set as follows (`UserName` will vary based on your environment):
`C:\Users\<UserName>\OmniSSHAgent.sock`
The WSL1 path will be `/mnt/c/Users/<UserName>/OmniSSHAgent.sock`.
The WSL1 path would be `/mnt/c/Users/<UserName>/OmniSSHAgent.sock`.

2. Add the following line to `~/.bashrc`
2. Add the following line to `~/.bashrc`:
```bash
export SSH_AUTH_SOCK=/mnt/c/Users/<UserName>/OmniSSHAgent.sock
```

### Using with Cygwin/MSYS2/Git for windows/(GitBash)
1. Check the setting of `Cygwin Unix domain socket file path(MSYS2):` in OmniSSHAgent.
* For example, if you have the following settings.(`UserName` varies depending on your environment).
* `C:\Users\<UserName>\OmniSSHCygwin.sock`.
* The Cygwin path will be `/mnt/c/Users/<UserName>/OmniSSHCygwin.sock`.
### Using with Cygwin/MSYS2/Git for Windows (Git Bash)
1. Check the setting for `Cygwin Unix domain socket file path (MSYS2)` in OmniSSHAgent.
* For example, if the path is (`UserName` will vary based on your environment):
* `C:\Users\<UserName>\OmniSSHCygwin.sock`
* The Cygwin path would be `/mnt/c/Users/<UserName>/OmniSSHCygwin.sock`.

2. On the Windows taskbar, right-click the Windows icon and select System.
In the Settings window, under Related Settings, click Advanced system settings.
2. To set the `SSH_AUTH_SOCK` variable:
* On the Windows taskbar, right-click the Windows icon and select System.
* In the Settings window, under Related Settings, click Advanced system settings.
* On the Advanced tab, click Environment Variables.
* `Users variables` Click on `Create new` to create a new environment variable.
* Set the following values(`UserName` varies depending on your environment).
* In `User variables`, click `New` to create a new environment variable:
```
Variable name: SSH_AUTH_SOCK
Variable Value: /mnt/c/Users/<UserName>/OmniSSHAgent.sock
Variable value: /mnt/c/Users/<UserName>/OmniSSHAgent.sock
```

## Using with OpenSSH ssh-agent NamedPipe (1Password etc.) proxy mode
## Using with OpenSSH ssh-agent NamedPipe (1Password, etc.) in Proxy Mode

This is a mode using [OpenSSH ssh-agent NamedPipe](https://learn.microsoft.com/windows-server/administration/openssh/openssh_keymanagement) or [1Password's ssh-agent function](https://developer.1password.com/docs/ssh/agent/) as a backend as shown in the following figure.
This mode uses [OpenSSH ssh-agent NamedPipe](https://learn.microsoft.com/windows-server/administration/openssh/openssh_keymanagement) or [1Password's ssh-agent function](https://developer.1password.com/docs/ssh/agent/) as a backend, as shown in the diagram below.
![NamedPipe-Proxy-mode](https://github.com/masahide/OmniSSHAgent/blob/main/doc/NamedPipeProxyMode.png?raw=true)

By setting "Enable proxy mode for 1Password key-agent" in the configuration, OmniSSHAgent becomes a Proxy that works with 1Password or OpenSSH's Namedpipe ssh-agent as a backend.
By enabling "Proxy mode for 1Password key-agent" in the configuration, OmniSSHAgent functions as a proxy for 1Password or OpenSSH's NamedPipe SSH agent.

When "Enable proxy mode for 1Password key-agent" is enabled, OmniSSHAgent operates as a mere proxy, and therefore, private keys cannot be added.
Note: When "Proxy mode for 1Password key-agent" is enabled, OmniSSHAgent operates solely as a proxy, meaning private keys cannot be added.

## Supported key file formats
- PuTTY private key file (.ppk) file format
## Supported Key File Formats
- PuTTY private key file (.ppk)
- OpenSSH format

## Supported key formats
- rsa
- ecdsa
- ed25519

(dsa, ecdsa-sk, ed25519-sk are not supported)
## Supported Key Types
- RSA
- ECDSA
- ED25519

(DSA, ECDSA-SK, ED25519-SK are not supported)

## FAQ

### Where is the passphrase for the private key stored?

It's stored in [Windows Credential Manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0).
Passphrases are stored in the [Windows Credential Manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0).

# Screen shot
## Screenshots

<img src="https://github.com/masahide/OmniSSHAgent/blob/main/doc/screen.png?raw=true" width="500">
<img src="https://github.com/masahide/OmniSSHAgent/blob/main/doc/screen-setup.png?raw=true" width="500">

0 comments on commit a2150d0

Please sign in to comment.