Update README with latest information and project URLs

1 files changed, 48 insertions, 199 deletions

diff --git a/README b/README
index e7e8b9b..e8649a1 100644
--- a/README
+++ b/README
@@ -1,214 +1,63 @@
-Background
-==========
-
-'usbmuxd' stands for "USB multiplexing daemon". This daemon is in charge of
-multiplexing connections over USB to an iPhone or iPod touch. To users, it means
-you can sync your music, contacts, photos, etc. over USB. To developers, it
-means you can connect to any listening localhost socket on the device. usbmuxd
-is not used for tethering data transfer, which uses a dedicated USB interface as
-a virtual network device.
-
-Multiple connections to different TCP ports can happen in parallel. An example
-(and useful) tool called 'iproxy' is included that allows you to forward
-localhost ports to the device---allows SSH over USB on jailbroken devices, or
-allowing access the lockdown daemon (and then to all of the file access, sync,
-notification and backup services running on the device).
-
-The higher-level layers are handled by libimobiledevice. 'ifuse' is then able
-to sit on top of this and mount your device's AFC filesystem share.
-
-This package contains the usbmuxd communication interface library 'libusbmuxd'.
-
-There is also a Python implementation of the client library in the python-client
-directory, and an example tcprelay.py which performs a similar function to iproxy.
-This implementation supports OSX and Windows and the new iTunes plist-based
-usbmuxd protocol, so it is portable and will run on those operating systems with
-no modification, using Apple's native usbmuxd. This is useful if you need to
-tunnel to your device from another OS in a pinch. Run python tcpclient.py --help
-for usage information.
-
-License
-=======
+About
+=====
 
-The contents of this package are licensed under the GNU Lesser General Public
-License, version 2.1 or, at your option, any later version (see COPYING.LGPLv2.1).
-If a more permissive license is specified at the top of a source file, it takes
-precedence over this.
+A client library to multiplex connections from and to iOS devices by connecting
+to a socket provided by a usbmuxd daemon.
 
-Legal
-=====
+Requirements
+============
 
-Apple, iPhone, and iPod touch are trademarks of Apple Inc., registered in the
-U.S. and other countries.
+Development Packages of:
+	libplist
 
-Building
-========
+Software:
+	usbmuxd (Windows and Mac OS X can use the one provided by iTunes)
+	make
+	autoheader
+	automake
+	autoconf
+	libtool
+	pkg-config
+	gcc
 
-  ./autogen.sh
-  make
-  sudo make install
+Optional:
+	inotify (Linux only)
 
-Running (with magic)
-====================
+Installation
+============
 
-  (Unplug + replug your jailbroken device)
-  ./iproxy 2222 22 &
-  ssh -p 2222 root@localhost
+To compile run:
+	./autogen.sh
+	make
+	sudo make install
 
-Hopefully you get the normal SSH login prompt. You may still lots of debugging
-output for the moment. If this is getting in the way of your ssh login, then
-run the 'ssh' command from a different xterminal or virtual console. Of course,
-you need to have OpenSSH installed on your jailbroken device for this to work.
+Who/What/Where?
+===============
 
-If you have iFuse, you can run "ifuse <mountpoint">. This doesn't require
-iproxy and works on all devices, jailbroken or not.
+Home:
+	http://www.libimobiledevice.org/
 
-Running (without magic)
-=======================
+Code:
+	git clone http://git.sukimashita.com/libusbmuxd.git
 
-If 'udev' is _not_ automatically running on your machine and picking up the new
-.rules file, you will need to start usbmuxd by hand first. Check it's running
-and that there is only one copy with 'ps aux | grep
-usbmuxd'.
+Code (Mirror):
+	git clone https://github.com/libimobiledevice/libusbmuxd.git
 
-  sudo usbmuxd -U -v -v &
-  ./iproxy 2222 22 &
-  ssh -p 2222 root@localhost
+Tickets:
+	http://github.com/libimobiledevice/libusbmuxd/issues
 
-Tip: Starting SSH if disabled
-=============================
+Mailing List:
+	http://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel
+
+IRC:
+	irc://irc.freenode.net#libimobiledevice
+
+Credits
+=======
 
-If your device is rooted, but SSH isn't started and you _cannot_ (for instance,
-cracked/broken screen) get to the Services control panel on the device, then you
-can start the SSH service over the USB by mounting the (jailbroken) filesystem.
+Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc.
+libimobiledevice is an independent software library and has not been
+authorized, sponsored, or otherwise approved by Apple Inc.
 
-You will need to mount it using 'ifuse --afc2' (to access the root directory of
-the device), and then edit:
-
-  /Library/LaunchDaemons/com.openssh.sshd.plist
-
-to _remove_ the lines:
-
-  <key>Disabled</key>
-  <true/>
-
-Reboot the device and then sshd should be running.
-
-TODO
-====
-
-The server currently assumes that the device is well-behaved and does not do a
-bunch of checks like looking for the expected SEQ and ACK numbers from it. This
-is normally not an issue, but it's annoying for debugging because lost packets
-(which shouldn't happen, but can happen if the code is buggy) mean that stuff
-gets out of sync and then might crash and burn dozens of packets later.
-
-The server needs more testing, and some optimizing.
-
-Someone should probably do some edge-case testing on the TCP stuff.
-
-The outgoing ACK handling on the server probably needs some thought. Currently,
-when there's an outstanding ACK, we send it after a timeout (to avoid sending
-a no-payload ACK packet for everything the phone sends us). However, there's
-probably a better way of doing this.
-
-Architecture information
-========================
-
-The iPhone / iPod Touch basically implements a rather strange USB networking
-system that operates at a higher level. It is of course completely proprietary.
-Generally speaking, this is what goes on in a typical usage scenario:
-
-0. iTunes opens a connection to usbmuxd and asks it for device notifications
-1. User inserts phone into computer
-2. usbmuxd notices the phone and pings it with a version packet
-3. phone replies
-4. usbmuxd now considers the phone to be connected and tells iTunes
-5. iTunes opens another separate connection to usbmuxd and asks it to connect
-   to, say, the afc port on the device
-6. usbmuxd sends a pseudo-TCP SYN packet to the phone
-7. the phone's kernel driver receives the SYN packet and itself opens a
-   TCP connection to localhost on the afc port
-8. the phone replies with a pseudo-TCP SYN/ACK indicating that the port is open
-   and the connection can proceed
-7. usbmuxd sends a final ACK to the phone
-8. usbmuxd replies to iTunes with a "connection successful" message
-9. any data that iTunes writes to the usbmuxd socket from now on is forwarded,
-   through pseudo-TCP, through USB, back into a more regular TCP connection to
-   localhost, to the afc daemon on the phone, and vice versa
-
-The usbmuxd protocol is a relatively simple binary message protocol documented
-here:
-
-http://wikee.iphwn.org/usb:usbmux
-
-Note that once a connection is established the UNIX socket essentially becomes
-a dedicated pipe to the TCP connction and no more high-level control is
-possible (closing the socket closes the TCP connection). Ditto for the "listen
-for devices" mode - usbmuxd will reject any commands in such mode, and the
-socket essentially becomes a dedicated device notification pipe. This means
-that you need, at minimum, TWO connections to usbmuxd to do anything useful.
-
-On Windows, usbmuxd works the same way but a TCP connection to localhost port
-27015 replaces the UNIX socket. On OSX, the UNIX socket is /var/run/usbmuxd. The
-server and client implemented here default the same /var/run/usbmuxd socket.
-
-The phone protocol operates over a pair of USB bulk endpoints. There is an outer
-layer used for packet size info and a "protocol" (version and TCP are the only
-two options), and that header is followed by TCP headers for actual data comms.
-However, the protocol isn't actual TCP, just a custom protocol which for some
-reason uses a standard TCP header and leaves most fields unused.
-
-There is no reordering or retransmission. There are no checksums, no URG, no
-PSH, no non-ACK, no FIN. What there *is* is the SEQ/ACK/window mechanism used
-for flow control, and RST is used as the only connection teardown mechanism (and
-also for "connection refused"), and the connection startup is SYN/SYNACK/ACK.
-
-Windows are constant-scaled by 8 bits. This is legal TCP as long as the
-corresponding option is negotiated. Of course, no such negotiation happens on
-this protocol.
-
-Note that, since there are no retransmissions, there is some overlap between ACK
-and window for flow control. For example, the server doesn't ever touch its
-window size, and just refuses to ACK stuff if its buffers are full and the
-client isn't reading data. The phone happily seems to stop sending stuff.
-
-Also, if the phone RSTs you out of nowhere, look at the packet payload for a
-textual error message. Note: if it claims to suffer from amnesia, that probably
-means you overflowed its input buffer by ignoring its flow control / window
-size. Go figure. Probably a logic bug in the kernel code.
-
-Note that all normal packets need to have flags set to ACK (and only ACK). There
-is no support for, erm, not-acking. Keep the ack number field valid at all
-times.
-
-The usbmuxd CONNECT request port field is byte-swapped (network-endian). This is
-even more annoying for the plist based protocol, since it's even true there
-(where the field is plain text). So even for the plain text int, you need to
-swap the bytes (port 22 becomes <integer>5632</integer>). I have no clue if this
-is the case on the new plist protocol on PPC macs (is the newer iTunes available
-for those?)
-
-There are a bunch of gotchas due to the USB framing, and this is even worse
-because implementations tend to get it wrong (i.e. libusb, and this is the
-reason for the patch). Basically, USB Bulk offers, at the low level, the ability
-to transfer packets from 0 to wMaxPacketSize (512 here) bytes, period. There is
-no other support for higher level framing of transfers. The way you do those is
-by breaking them up into packets, and the final shorter packet marks the end of
-the transfer. The critical bit is that, if the transfer happens to be divisible
-by 512, you send a zero-length packet (ZLP) to indicate the end of the transfer.
-Libusb doesn't set this option by default and the iPhone gets packets stuck to
-each other, which it doesn't like. Actually, this framing is sort of redundant
-because the usbmux packet header includes a length field, but the phone still
-wants the ZLPs or else it breaks. To make matters worse, usbdevfs imposes a max
-transfer size of 16k, so libusb breaks transfers into that size. This is okay
-for sending as long as the ZLP is only added to the last transfer (the patch
-does that), but it can easily cause nasty race conditions on RX due to libusb
-doing multiple outstanding reads at the same time and then cancelling the rest
-when shorter data arrives (but what if some data got into the other requests
-already?), so we only do 16k reads and stick them together ourselves by looking
-at the packet size header. We still depend on ZLPs being sent to end transfers
-at non-16k boundaries that are multiples of 512, but that seems to work fine. I
-guess the ZLPs might cause spurious 0-byte transfers to show up on RX if things
-line up right, but we ignore those. By the way, the maximum packet/transfer size
-is 65535 bytes due to the 16-bit length header of the usbmux protocol.
+README Updated on:
+	2014-10-02