search

linuxmint / warpinator

Share files across the LAN
GNU General Public License v3.0
1.24k stars 83 forks source link

readme

Warpinator - send and receive files across a local network

build

Other platforms (unofficial):

How to build and install for Linux

Mint 20+, LMDE 4+:

sudo apt-get install warpinator

Ubuntu 20.04, related:

# Install build dependencies listed below, note minimum versions:
sudo apt-get install python3-grpc-tools python3-grpcio

# Clone this repo:
git clone https://github.com/linuxmint/warpinator.git

# Enter the folder, specify version:
cd warpinator

# Check out a version you want, or skip this step to build off the current source.
git checkout 1.2.3

# Try to build. If this fails, it's probably due to missing dependencies.
# If you use GitHub Actions to compile, please install the following dependencies.
sudo apt-get -y install debhelper dh-python meson gobject-introspection cython3

# Take note of these packages, install them using apt-get:
dpkg-buildpackage --no-sign

# Once that succeeds, install:
cd ..
sudo dpkg -i *warp*.deb

# If this fails, make note of missing runtime dependencies (check list below),
# install them, repeat previous command (apt-get install -f may also work).
Note for Mint 19.x and Ubuntu Bionic (18.04) users:

Add this PPA to satisfy dependencies, then you can follow steps above: https://launchpad.net/~clementlefebvre/+archive/ubuntu/grpc?field.series_filter=bionic

Arch Linux:

For any desktop environment (DE)

sudo pacman -S warpinator

Otherwise (and this is valid anywhere if you want to avoid packaging):

meson builddir --prefix=/usr # (This is typical - /usr/local is another common choice for non-package-manager installs).
ninja -C builddir
sudo ninja -C builddir install

Flatpak

For any Linux distro with flatpak support you can also install it from Flathub:

flatpak install flathub org.x.Warpinator
build deps (ref: debian/control)
required only for makepot
runtime deps
Note about zeroconf

We've started bundling certain dependencies due to their tendency to break and/or exhibit different behavior on different distributions. To disable this, you can do something like:

meson builddir --prefix=/usr -Dbundle-zeroconf=false
ninja -C builddir
sudo ninja -C builddir install
You can get grpcio and grpc-tools from pip3 also:
pip3 install grpcio grpcio-tools

Security Considerations

Secure Mode

Group codes

The group code is a shared key that allows trusted devices on the local network to see one another in Warpinator. Any devices you wish to connect with must be using the same group code. This code is set to 'Warpinator' by default.

Enabling secure mode

Secure mode can be enabled simply by changing the group code to something unique. It is highly recommended that you do this as soon as possible, as anyone else that gets on your network would then be able to connect with you with little effort.

Certain restrictions are put in place until Secure Mode is enabled:

Folder Isolation

Overview

There is potential for incoming files to be manipulated by a sender in a manner that might cause harm to your system, making use of symbolic links (files that point to other files or folders). Warpinator tries to detect and prevent this, but can also make use of other tools to provide more protection.

Landlock:

Landlock is a relatively new security module for the Linux Kernel that allows a program to fine-tune how it can access your filesystem. In the context of Warpinator, it allows us to completely isolate your incoming folder - it essentially exists in a vacuum during transfers. Warpinator uses this automatically if it's available.

Bubblewrap:

Bubblewrap (or bwrap) is a tool that can be used to construct a restrictive environment that a program operate in. For Warpinator, Using bubblewrap provides an experience similar to Landlock, in that only your incoming folder can be written to. There are a couple of minor disadvantages, however: Changing your incoming folder location will require Warpinator to be restarted, and the rest of your filesystem will be read-only (for instance, you won't be able to create new folders elsewhere on your system from Warpinator's file dialog). Warpinator will attempt to use this if Landlock is not available.

Legacy (No isolation):

If both Landlock and Bubblewrap are unavailable, Warpinator will operate without folder isolation, though incoming transfers will still be analyzed to try and catch any potentially harmful files.

Flatpak users:

Only landlock or legacy modes are available when using the Warpinator Flatpak, as bubblewrap is already utilized by Flatpak itself. If Landlock is not available (see additional information below for how to check this), you will want to lock your Home directory down yourself using either command-line arguments or the 'Flatseal' utility (which is itself a flatpak).

To do this from the command line (or a custom launcher), you can use the following:

flatpak run --filesystem=home:ro --filesystem=<path-to-your-save-folder> org.x.Warpinator --mode=legacy

To make the change permanently using Flatseal:

When you're finished, it should look something like this:

Flatseal filesystem permissions

Make sure you restart Warpinator after making these changes.

IMPORTANT If you selected a new save folder in Warpinator preferences before allowing it in Flatseal, you will need to re-select it in Preferences. This is a characteristic of Flatpaks in general, where inaccessible user folders are re-created inside the sandbox, and Warpinator will not have the real folder's path.

Additional information:

Troubleshooting tips

Improving transfer speeds

Enable compression:

Beginning in version 1.2.0, transfers can potentially be sped up by enabling compression. Note: this will only work if the sending and receiving machine both support it. It can be enabled in General Preferences:

Compression switch

Solving connection issues

Check your group code:

All devices that wish to connnect must share the same group code. Any that do not will be ignored. Tip: You should first choose a unique code before setting up additional devices. Do not leave it as the default "Warpinator".

Make sure you're using a valid network interface:

All devices must be on the same local subnet in order to connect. While Warpinator will generally 'get this right' on its own, it can fail depending on various factors. An easy way to tell is to compare the IP address of both devices. You can check this in the lower right-hand corner of the Warpinator window. In most home-based networks, this value will start with 192.168.1. For devices to see one another, they must all share that part of the address. The last set of digits will differ on each device. If there are additional differences, the devices will probably not be able to connect.

VBox guest network settings

VBox guest network interface selection

Preferences firewall info

Transfers: TCP port

and

Authentication: TCP port

and

Zeroconf flatpak fix: UDP 5353

You should end up with:

Correct gufw rule list

Check under the hood:

It's possible there is something else causing your connection issues that is not covered here. You can run Warpinator in debug mode to gather additional information to troubleshoot (or to attach to an Issue report here).

Quit Warpinator

If you're running the Flatpak version, use this instead:

flatpak run --command=warpinator org.x.Warpinator --debug


This will cause a great deal of useful information to be logged to the terminal. You can copy this and attach it to a bug report here. This will give us a good head start on assisting you.

**Note:** Please don't copy/paste the text directly into the issue. You can save it into a text file, then simply drag the file into the editor here.