git-annex/ assistant/ local pairing walkthrough

So you have two computers in the same building, and you want them to share the same synchronised folder, communicating directly with each other.

This is incredibly easy to set up with the git annex assistant.

Let's say the two computers are your computer and your friend's computer. We'll start on your computer, where you open up your git annex dashboard.

`*click*`

`*click*`

Now the hard bit. You have to think up a secret phrase, and type it in, (and perhaps get the spelling correct).

Now your computer is in pairing mode. When your friend looks at her git annex dashboard, she sees something like this.

`*click*`

Now it's up to you to let her know what the secret is. As soon as she enters it, both your computers will be paired, and will begin to sync their git-annex folders. Just like that you can share files.

## Requirements

For local pairing to work, you must have sshd (ssh server daemon) installed and working on all machines involved. That means you must allow at least local connections to sshd. On most Linux distributions, sshd is packaged in either openssh (openSUSE) or openssh-server (Debian).

It is highly recommended that you disable root login, disable password login to sshd and just enable key based authentication instead. No one will be able to login without your key.

To disable root, after installing sshd, edit the sshd config (usually /etc/ssh/sshd_config file) and disable root login by adding:

    PermitRootLogin no

Restart sshd. See man sshd_config for details.

To disable password login and enable key based authentication, edit the sshd config (just like above) by uncommenting and changing the following options:

    ChallengeResponseAuthentication no
    PasswordAuthentication no
    UsePAM no

    PubkeyAuthentication yes

Restart sshd. See man sshd_config for details.

You can also restrict login to your local network only (not allow internet users from trying to log into your computer). Edit the hosts.deny file (usually /etc/hosts.deny) by adding the following:

    sshd : ALL EXCEPT LOCAL

Do note that restricting login to your local network may or may not block git-annex. Also note that this will not work on Mac OSX because Apple decided to disable this feature and replace it with a crippled version made by Apple.

## Tips

Something to keep in mind, especially if pairing doesn't seem to be working, is that the two computers need to be on the same network for this pairing process to work. Sometimes a building will have more than one network inside it, and you'll need to connect them both to the same one. Make sure the wireless network name is the same, or that they're both plugged into the same router.

Also, the file sharing set up by this pairing only works when both computers are on the same network. If you go on a trip, any files you edit will not be visible to your friend until you get back.

To get around this, you'll often also want to set up tor pairing too, which they can use to exchange files while away.

And also, you can pair with as many other computers as you like, not just one!

## What does pairing actually do behind the scenes?

It ensures that both repositories have correctly configured remotes pointing to each other. If you have already configured this manually, you do not need to perform pairing.

Diagnosing local pairing issues.
In my situation, a local pairing is initiated on machine A, machine B sees the request, prompts for the pass-phrase, both machines proceed with the actual sync process, but nothing actually happens. The last message in B's log is "Pairing with [A] in progress" and machine A says "main: Pairing in progress". How do I diagnose this issue?
Comment by lhunath — Wed Oct 29 14:05:27 2025
comment 8
I don't understand how IPv6 could affect local pairing. The assistant does not currently do pairing over ipv6 due to a limitation in the multicast library it's using.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Make sure your network is correctly set up in the first place!

It turns out that my internal network had badly broken IPv6 configs between the boxes. That was interfering with the multicast packets but not with anything else since all of my other internal traffic is over IPv4.

Getting rid of these static IPv6 addresses has solved my problem. Local pairing is now working as advertised :)

Comment by https://openid.fmarier.org/ — Wed Oct 29 14:05:27 2025
comment 6
It's quite possible that your router doesn't handle multicast traffic to 224.0.0.251. The best way to check is to a) see if avahi/zeroconf works, since it's sending similar traffic and b) run tcpdump on both machines and see if the packets being sent on port 55556 by one are seen by the other.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Still stuck at "pairing in progress"

I hadn't thought of ssh. So here's what I've got now:

- both laptop and desktop have `-A INPUT -d 224.0.0.251/32 -p udp --dport 55556 -j ACCEPT`
- `git annex webapp` is running as user `francois` on both machines
- laptop has `openssh-server` running on port 22 and its firewall allows desktop to connect
- desktop has `openssh-server` running on port 22 and its firewall allows the whole internal network to connect
- laptop's ssh pubkey is in francois' `~/.ssh/authorized_keys` on desktop and ssh'ing works
- deskop's ssh pubkey is not in francois' `~/.ssh/authorized_keys` on laptop (is that required?)
- (as mentioned before) both desktop and laptop are on the same switch and connected over CAT5
- I'm using `password` as a pairing key just to rule out any typos there

I don't see anything in the git-annex log on both of these machines. There's just a bunch of key generation stuff and then the last line is "Pairing in progress".

Comment by https://openid.fmarier.org/ — Wed Oct 29 14:05:27 2025
comment 4

Local pairing uses UDP port 55556. This is sent to multicast address 224.0.0.251 (same used by Avahi).

(You also need TCP port 22 open for ssh.)

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Ports to open on the firewall?

I'm trying to get local pairing working between two local machines (same switch, both connected via cat5 cables) and they're not seeing each other, though I can happily ssh from one box to the other.

In order to eliminate possible sources of problems, I tried these insecure settings:

- add a `-A INPUT -j ACCEPT` to the top of my firewall rules
- use `password` as the shared secret

but I still can't get past "pairing in progress" when pairing with a "Local computer".

Is there any way to get information as to where the two machines are failing to see one another?

Comment by https://openid.fmarier.org/ — Wed Oct 29 14:05:27 2025
easy peasy
A headless machine is probably a server. On the same page that has the "local computer" link, there's a "remote server" link that'll get you set up.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Pairing
Is there a way to do this pairing with one machine being a desktop machine and one a headless machine?
Comment by https://launchpad.net/~mattharrison — Wed Oct 29 14:05:27 2025
Comments on this page are closed.