search

thevindu-w / clip_share_server

Share Clipboard across devices. Share copied files and screenshots securely. Free and open-source tool that works on Windows, Linux, macOS, and Android.
GNU General Public License v3.0
67 stars 6 forks source link
android clipboard clipboard-share clipboard-sync fileshare lan-share linux macos screenshot share-files shared-clipboard universal-clipboard windows

readme

Build and Check Last commit License

ClipShare Server

Share Clipboard and Files. Copy on one device. Paste on another device.


This is the server that runs in the background. Clients can connect to the server and share copied text, files, and images.

Download

Server Client
Get it on GitHub
(Download the server from Releases.) 		Get it on IzzyOnDroid
(Download the client app from apt.izzysoft.de/fdroid/index/apk/com.tw.clipshare.
or from GitHub Releases.)


Table of Contents


How to Use

Install dependencies

Note: This section is required only on macOS.

ClipShare needs the following libraries to run:

These libraries can be installed using Homebrew with the following command:

brew install libunistring openssl@3 libpng


Run the server


Allow through firewall

This server listens on the following ports (unless different ports are assigned from the configuration),

You may need to allow incoming connections to the above ports for the client to connect to the server.

Note that all TCP ports are for unicast, while 4337/udp is used to receive broadcast. Therefore, the firewall rule that allows 4337/udp should have the broadcast address of the interface as the destination address.


Connect the client application

You can find an Android client app in releases. You can also get it from apt.izzysoft.de. The source of the Android client app is available at github.com/thevindu-w/clip_share_client. Or you may develop a client app according to the protocol specification described in the docs/.


Installation

Note: This section is optional if you prefer manually starting the server over automatically starting on login/reboot.

To install the server to run on startup, use the corresponding installer script for your platform.

Online installers

Online installer scripts are attached with the releases. They will download the corresponding version during installation. Therefore, they do not require having the compiled binaries along with the installer to run it. However, they require internet access to download the binaries from GitHub during installation. Run the interactive script and follow the instructions to install ClipShare.

Standalone installers

Standalone installer scripts are available in the archives (zip for Windows and macOS, and tar.gz for Linux) attached to releases on GitHub. They are also available in the helper_tools/ directory. Standalone installers can run without an internet connection. However, you must have the clip_share (or clip_share.exe on Windows) executable in the current working directory to run the installer. If you download the archive from releases and extract it, you will have the executable along with the installer script. Run the interactive script and follow the instructions to install ClipShare.

Linux and macOS

  1. Open a terminal in the directory where the clip_share executable is available (the executable name may have suffixes like _GLIBC* on Linux or arm64 or x86_64 on macOS).
  2. Run the install script as shown below, and follow the instructions of it. 
    # on Linux
chmod +x install-linux.sh
./install-linux.sh
    # on macOS
chmod +x install-mac.sh
./install-mac.sh

Windows

  1. Place the install-windows.bat file and the clip_share.exe executable in the same folder. (the executable name may have suffixes)
  2. Double-click on the install-windows.bat installer script to run it. It will open a Command Prompt window. Follow the instructions on it to install ClipShare. (If double-clicking did not run the installer, right-click on it and select Run)


Create SSL/TLS certificates and key files

Note: This section is optional if you do not need the TLS encrypted mode and the web mode.

The following files should be created, and their paths should be specified in the configuration file clipshare.conf. You may use different file names and paths to store the keys and certificates.

You may use the helper script keygen.sh in the helper_tools/ directory to generate TLS keys and certificates for both the server and the client. Keep the clipshare.ext file in the same directory as the keygen.sh script when running the script.

# If you download/clone the repository and run the script from the repository root,
chmod +x helper_tools/keygen.sh
helper_tools/keygen.sh
# If you download the script separately and run the script from within the same directory,
chmod +x keygen.sh
./keygen.sh

If you use this script, the server's common name will be clipshare_server, and the client's common name will be clipshare_client. You may change those names in the keygen.sh script.

Refer to the OpenSSL manual for more information on generating keys.


Command line options

./clip_share [-h] [-s] [-r] [-R] [-d] [-D]

  -h   Help         - Display usage and exit.
                      This takes priority over all other options.

  -s   Stop         - Stop all instances of the server if any.
                      This takes priority over -r and -R.

  -r   Restart      - Stop other instances of the server if any,
                      and restart the server. This option takes
                      precedence over the restart value in the
                      configuration file.

  -R   No-Restart   - Start the server without restarting. This
                      option takes precedence over the restart
                      value in the configuration file.

  -d   Daemonize    - Exit the main process after creating child
                      processes. This option is effective only on
                      Linux and macOS. (default)

  -D   No-Daemonize - Do not exit the main process after creating
                      child processes. This option is effective
                      only on Linux and macOS.

Configuration

The ClipShare server can be configured using a configuration file. The configuration file should be named clipshare.conf. The server searches for the configuration file in the following paths in the same order until it finds one.

  1. Current working directory where the server was started.
  2. $XDG_CONFIG_HOME directory if the directory exists (on Linux and macOS only).
  3. Current user's home directory (also called user profile directory on Windows).

If it can't find a configuration file in any of the above directories, it will use the default values specified in the table below.

To customize the server, create a file named   clipshare.conf   in any of the directories mentioned above and add the following lines to that configuration file.

app_port=4337
app_port_secure=4338
udp_port=4337
web_port=4339
insecure_mode_enabled=true
secure_mode_enabled=true
web_mode_enabled=false
server_cert=cert_keys/server.pfx
ca_cert=cert_keys/ca.crt
allowed_clients=allowed_clients.txt
working_dir=./path/to/work_dir
bind_address=0.0.0.0
restart=true
max_text_length=4194304
max_file_size=68719476736
display=1
client_selects_display=false
cut_sent_files=false
min_proto_version=1
max_proto_version=3

# Windows only
tray_icon=true

Note that all the lines in the configuration file are optional. You may omit some lines if they need to get their default values.


Property Description Accepted values Default
insecure_mode_enabled Whether or not the application listens for unencrypted connections. The values true or 1 will enable it, while false or 0 will disable it. true, false, 1, 0 (Case insensitive) true
secure_mode_enabled Whether or not the application listens for TLS-encrypted connections. The values true or 1 will enable it, while false or 0 will disable it. true, false, 1, 0 (Case insensitive) false
web_mode_enabled Whether or not the application listens for TLS-encrypted connections from web clients if the web mode is available. The values true or 1 will enable it, while false or 0 will disable it. true, false, 1, 0 (Case insensitive) false
app_port The port on which the application listens for unencrypted TCP connections. (Values below 1024 may require superuser/admin privileges) Any valid, unused TCP port number (1 - 65535) 4337
udp_port The port on which the application listens for UDP broadcasts of network scanning. (Values below 1024 may require superuser/admin privileges) Any valid, unused UDP port number (1 - 65535) 4337
app_port_secure The TCP port on which the application listens for TLS-encrypted connections. (Values below 1024 may require superuser/admin privileges) Any valid, unused TCP port number (1 - 65535) 4338
web_port The TCP port on which the application listens for TLS-encrypted connections for web clients. This setting is used only if web mode is available. (Values below 1024 may require superuser/admin privileges) Any valid, unused TCP port number (1 - 65535) 4339
server_cert The TLS key and certificate store file of the server. If this is not specified, secure mode (and web mode if available) will be disabled. Absolute or relative path to the server's TLS certificate store PKCS#12 file \<Unspecified>
ca_cert The TLS certificate file of the CA that signed the TLS certificate of the server. If this is not specified, secure mode (and web mode if available) will be disabled. Absolute or relative path to the TLS certificate PEM file of the CA \<Unspecified>
allowed_clients The text file containing a list of allowed clients (Common Name of client certificate), one name per line. If this is not specified, secure mode (and web mode if available) will be disabled. Absolute or relative path to the allowed-clients file \<Unspecified>
bind_address The address of the interface to which the application should bind when listening for connections. It will listen on all interfaces if this is set to 0.0.0.0 IPv4 address of an interface in dot-decimal notation (ex: 192.168.37.5) or 0.0.0.0 0.0.0.0
restart Whether the application should start or restart by default. The values true or 1 will make the server restart by default, while false or 0 will make it just start without stopping any running instances of the server. true, false, 1, 0 (Case insensitive) true
working_dir The working directory where the application should run. All the files, that are sent from a client, will be saved in this directory. It will follow symlinks if this is a path to a symlink. The user running this application should have write access to the directory Absolute or relative path to an existing directory . (i.e. Current directory)
max_text_length The maximum length of text that can be transferred. This is the number of bytes of the text encoded in UTF-8. Any integer between 1 and 4294967295 (nearly 4 GiB) inclusive. Suffixes K, M, and G (case insensitive) denote x103, x106, and x109, respectively. 4194304 (i.e. 4 MiB)
max_file_size The maximum size of a single file in bytes that can be transferred. Any integer between 1 and 9223372036854775807 (nearly 8 EiB) inclusive. Suffixes K, M, G, and T (case insensitive) denote x103, x106, x109, and x1012, respectively. 68719476736 (i.e. 64 GiB)
display The display that should be used for screenshots. Display number (1 - 65535) 1
cut_sent_files Whether to automatically cut the files into the clipboard on the Send Files method. true, false, 1, 0 (Case insensitive) false
client_selects_display Whether the client can override the default/configured display for screenshots in protocol version 3. The values true or 1 will allow overriding the default, while false or 0 will force using the default/configured display. true, false, 1, 0 (Case insensitive) false
min_proto_version The minimum protocol version the server should accept from a client after negotiation. Any protocol version number greater than or equal to the minimum protocol version the server has implemented. (ex: 2) The minimum protocol version the server has implemented
max_proto_version The maximum protocol version the server should accept from a client after negotiation. Any protocol version number less than or equal to the maximum protocol version the server has implemented. (ex: 3) The maximum protocol version the server has implemented
method_get_text_enabled
method_send_text_enabled
method_get_files_enabled
method_send_files_enabled
method_get_image_enabled
method_get_copied_image_enabled
method_get_screenshot_enabled
method_info_enabled		 These configuration keys map to methods in ClipShare. They separately define whether the corresponding method is enabled or not. The values true or 1 will allow clients to use the method, while false or 0 will disable the method. true, false, 1, 0 (Case insensitive) true
tray_icon Whether the application should display a system tray icon. This option is available only on Windows. The values true or 1 will display a tray icon, while false or 0 will prevent displaying a tray icon. true, false, 1, 0 (Case insensitive) true


You may change these values. But it is recommended to keep the port numbers unchanged. If the port numbers are changed, client application configurations may also need to be changed as appropriate to connect to the server.
If you changed the configuration file, you must restart the server to apply the changes.



Build from Source

Note: If you prefer using the pre-built binaries from Releases, you can ignore this section and follow the instructions in the How to Use section.

Build tools

Compiling ClipShare needs the following tools,

Linux

On Linux, these tools can be installed with the following command:

Windows

On Windows, these tools can be installed with MinGW.
In an MSYS2 environment, these tools can be installed using pacman with the following command:

  pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make

You may need to rename (or copy) the <MSYS2 directory>/mingw64/bin/mingw32-make.exe to <MSYS2 directory>/mingw64/bin/make.exe before running the command make

macOS

On macOS, these tools are installed with Xcode Command Line Tools.


Dependencies

Linux

The following development libraries are required.

(You may refer to docker/Dockerfile.* to see how to install the dependencies on various Linux distros)

Windows

The following development libraries are required.

In an MSYS2 environment, these tools can be installed using pacman with the following command:

pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-libpng mingw-w64-x86_64-libunistring

macOS

The following development libraries are required.

These tools can be installed using Homebrew with the following command:

brew install openssl@3 libpng libunistring


Compiling

  1. Open a terminal / command prompt / Powershell in the project directory

    This can be done using the GUI or the cd command.

  2. Run the following command to make the executable file

    make

    This will generate the executable named clip_share (or clip_share.exe on Windows).

    Note: The web version is deprecated.
    To compile with the web server enabled, (Currently, this is tested only on Linux)

    make web

    This will generate the web server enabled executable named clip_share_web.