diff --git a/README.md b/README.md index 36d6e8b..84262f3 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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\\OmniSSHAgent.sock` -The WSL1 path will be `/mnt/c/Users//OmniSSHAgent.sock`. +The WSL1 path would be `/mnt/c/Users//OmniSSHAgent.sock`. -2. Add the following line to `~/.bashrc` +2. Add the following line to `~/.bashrc`: ```bash export SSH_AUTH_SOCK=/mnt/c/Users//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\\OmniSSHCygwin.sock`. - * The Cygwin path will be `/mnt/c/Users//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\\OmniSSHCygwin.sock` + * The Cygwin path would be `/mnt/c/Users//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//OmniSSHAgent.sock +Variable value: /mnt/c/Users//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