Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
sstallion committed Jan 25, 2024
1 parent 0b081c0 commit 3580a89
Show file tree
Hide file tree
Showing 4 changed files with 42 additions and 48 deletions.
Binary file removed .github/images/clipboard.png
Binary file not shown.
Binary file modified .github/images/settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 16 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ not have time to contribute!

## Making Changes

> **Note**: This guide assumes you have a working Windows installation with the
> latest [Windows SDK][2] installed. [CMake 3.26][3] (or newer) is required to
> build the project using either [Visual Studio 2019][4] or [Clang 16][5].
> [!IMPORTANT]
> This guide assumes you have a working Windows installation with the latest
> [Windows SDK][2] installed. [CMake 3.26][3] (or newer) is required to build
> the project using either [Visual Studio 2019][4] or [Clang 16][5].
To get started, [fork][6] this repository on GitHub and clone a working copy for
development:
Expand All @@ -20,8 +21,8 @@ To build the Debug configuration using Visual Studio, issue:
cmake -B build && cmake --build build
```

> **Note**: Once built, the ClipSock executable can be found in the build
> directory.
> [!NOTE]
> Once built, the ClipSock executable can be found in the build directory.
To run tests, issue:
```
Expand Down Expand Up @@ -68,6 +69,14 @@ To make a release, perform the following:
6. Review the draft release created by GitHub Actions and make adjustments as
needed. Once finished, publish the release to make it publicly available.

7. Submit a pull request to the [winget-pkgs][12] repository to update the
`ClipSock.ClipSock` package to the latest release using [winget-create][13]:
```
wingetcreate update --urls https://github.com/sstallion/ClipSock/releases/download/v<version>/ClipSock-<version>-x64.msi ^
https://github.com/sstallion/ClipSock/releases/download/v<version>/ClipSock-<version>-x86.msi ^
--version <version> ClipSock.ClipSock
```

## License

By contributing to this repository, you agree that your contributions will be
Expand All @@ -84,3 +93,5 @@ licensed under its Simplified BSD License.
[9]: https://github.com/sstallion/ClipSock/blob/master/CHANGELOG.md
[10]: https://github.com/sstallion/ClipSock/actions/workflows/ci.yml
[11]: https://github.com/sstallion/ClipSock/actions/workflows/release.yml
[12]: https://github.com/microsoft/winget-pkgs
[13]: https://github.com/microsoft/winget-create
69 changes: 26 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,27 @@ clipboard data over remote SSH tunnels.

## Installation

Pre-built Windows Installer packages are provided for each [Release][2].
Windows Installer packages can be downloaded from the [Releases][2] page or
installed using the [Windows Package Manager][7]:
```
winget install ClipSock.ClipSock
```

> [!IMPORTANT]
> The latest version of the [Visual C++ Redistributable][8] package for Visual
> Studio 2019 must be installed, otherwise an error indicating MSVCP140.dll can
> not be found will occur. This step is not required when using the Windows
> Package Manager as it will install this package automatically.
CMake workflow presets are available to build installer packages from source
using Visual Studio 2019. Install the prerequisites documented in [Making
Changes][7], then issue:
using Visual Studio 2019. Install the prerequisites documented in
[Making Changes][9], then issue:
```
cmake --workflow --preset Release-MSVC-x64 ; or Release-MSVC-x86
```

> **Note**: Once built, installer packages can be found in the build directory.
> [!NOTE]
> Once built, installer packages can be found in the build directory.
## Configuration

Expand All @@ -38,45 +49,16 @@ Once confirmed, the settings dialog may be revisited by right clicking the
taskbar notification area icon and selecting Settings from the context menu. The
server will automatically restart once the dialog closes.

> **Note**: It is strongly advised to listen to localhost and use remote
> tunneling to protect the privacy of clipboard data transmitted between hosts.
### OpenSSH for Windows

To configure the [Windows OpenSSH][8] client, a Host entry should be added to
`%USERPROFILE%\.ssh\config` with a RemoteForward declaration to forward packets
from port 5494 on the remote host to ClipSock over the secure channel:
```
Host host.example.com
RemoteForward 127.0.0.1:5494 127.0.0.1:5494
```

SSH into the remote host and create a shell alias to read from standard input
using either GNU Netcat or Socat:
```
$ alias clip="nc -N 127.0.0.1 5494" # GNU Netcat
$ alias clip="socat - TCP:127.0.0.1:5494" # Socat
```

> **Note**: The above assumes a Bourne-style shell. See vendor documentation on
> how to create an alias if using a different shell.
To verify ClipSock is working over the secure channel, issue:
```
$ echo -n "Hello, World!" | clip
```

Finally, press the **Windows logo key + V** to view your clipboard history,
which should now contain the phrase `Hello, World!`:

![](./.github/images/clipboard.png)
> [!IMPORTANT]
> It is strongly advised to listen to localhost and use remote tunneling to
> protect the privacy of clipboard data transmitted between hosts.
Configuration for other SSH clients and terminal multiplexers can be found on
the [Wiki][9].
Additional configuration for popular SSH clients and terminal multiplexers can
be found on the [Wiki][10].

## Contributing

Pull requests are welcome! See [CONTRIBUTING.md][10] for details.
Pull requests are welcome! See [CONTRIBUTING.md][11] for details.

## License

Expand All @@ -89,7 +71,8 @@ Source code in this repository is licensed under a Simplified BSD License. See
[4]: https://support.microsoft.com/en-us/windows/clipboard-in-windows-c436501e-985d-1c8d-97ea-fe46ddf338c6
[5]: https://netcat.sourceforge.net/
[6]: http://www.dest-unreach.org/socat/
[7]: https://github.com/sstallion/ClipSock/blob/master/CONTRIBUTING.md#making-changes
[8]: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview
[9]: https://github.com/sstallion/ClipSock/wiki/Configuration
[10]: https://github.com/sstallion/ClipSock/blob/master/CONTRIBUTING.md
[7]: https://learn.microsoft.com/en-us/windows/package-manager/
[8]: https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022
[9]: https://github.com/sstallion/ClipSock/blob/master/CONTRIBUTING.md#making-changes
[10]: https://github.com/sstallion/ClipSock/wiki/Configuration
[11]: https://github.com/sstallion/ClipSock/blob/master/CONTRIBUTING.md

0 comments on commit 3580a89

Please sign in to comment.