add page for xmpp

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/special_remotes/xmpp.mdwn b/doc/special_remotes/xmpp.mdwn
new file mode 100644
index 000000000..b106d83eb
--- /dev/null
+++ b/doc/special_remotes/xmpp.mdwn
@@ -0,0 +1,24 @@
+XMPP (Jabber) is used by the [[assistant]] as a git remote. This is,
+technically not a git-annex special remote (large files are not transferred
+over XMPP; only git commits are sent).
+
+Typically XMPP will be set up using the web app, but here's how a manual
+set up could be accomplished:
+
+1. xmpp login credentials need to be stored in `.git/annex/creds/xmpp`.
+   Obviously this file should be mode 600. An example file:
+
+	XMPPCreds {xmppUsername = "joeyhess", xmppPassword = "xxxx", xmppHostname = "xmpp.l.google.com.", xmppPort = 5222, xmppJID = "joeyhess@gmail.com"}
+
+2. A git remote is created using a special url, of the form `xmpp::user@host`
+   For the above example, it would be `url = xmpp:joeyhess@gmail.com`
+
+3. The uuid of one of the other clients using XMPP should be configured
+   using the `annex.uuid` setting, the same as is set up for other remotes.
+
+With the above configuration, the [[assistant]] will use xmpp remotes much as
+any other git remote. Since XMPP requires a client that is continually running
+to see incoming pushes, the XMPP remote cannot be used with git at the
+command line.
+
+See also: [[xmpp_protocol_design_notes|design/assistant/xmpp]]