Document known issues with TCP/IP settings
Change-Id: I8c4ef16491fd4edf2cdd54b567881ed3b1f1db74
diff --git a/src/source/known-issues.md b/src/source/known-issues.md
index be5a846..4fa1bea 100644
--- a/src/source/known-issues.md
+++ b/src/source/known-issues.md
@@ -114,6 +114,18 @@
don't change, and if they do and you can't connect you'll have
to resolve those hostnames again and edit `etc/hosts` accordingly.
+## Difficulties syncing the source tree (TCP issues). ##
+
+**Symptom**: `repo sync` hangs while syncing, often when it's
+completed 99% of the sync.
+
+**Cause**: Some settings in the TCP/IP stack cause difficulties
+in some network environments, such that `repo sync` neither completes
+nor fails.
+
+**Fix**: On linux, `sysctl -w net.ipv4.tcp_window_scaling=0`. On
+MacOS, disable the rfc1323 extension in the network settings.
+
## `make snod` and emulator builds. ##
**Symptom**: When using `make snod` (make system no dependencies)