Remoting documentation: README and System properties (#89)

* Add the Remoting configuration page

* Add README

* Update system property annotations in the code

* Docs: Convert links in the SystemProperties table to HTML

* Docs: fix the relative link in docs/configuration.md

README.md

@@ -0,0 +1,38 @@
+Jenkins Remoting layer
+====
+
+Jenkins remoting is an executable JAR, 
+which implements communication layer in [Jenkins](https://jenkins.io) automation server. 
+It's being used for master <=> agent(fka "slave") and master <=> CLI communications.
+
+In general, this library contains the bootstrap code to bridge separate JVMs into a single semi-shared space.
+It includes: TCP-based communication protocols, data serialization, Java classloading.
+
+The library is reusable outside Jenkins.
+
+### Documentation
+
+Remoting documentation is under development.
+More info will appear soon.
+Feel free to contribute.
+
+* [Changelog](CHANGELOG.md)
+* [Remoting Configuration](docs/configuration.md)
+* [Channel Termination Process](docs/close.md)
+
+### Reporting issues
+
+Remoting library uses the [Jenkins bugtracker](https://issues.jenkins-ci.org).
+Issues should be reported there in the <code>JENKINS</code> project with the <code>remoting</code> component.
+
+See [How to report an issue](https://wiki.jenkins-ci.org/display/JENKINS/How+to+report+an+issue) for more details about Jenkins issue reporting.
+
+### More info
+
+* [Remoting Architecture Overview](http://hudson-ci.org/docs/HudsonArch-Remoting.pdf) 
+by Winston Prakash, Oracle (the information is outdated)
+* [Making your plugin behave in distributed Jenkins](https://wiki.jenkins-ci.org/display/JENKINS/Making+your+plugin+behave+in+distributed+Jenkins)
+* [Writing an SCM plugin. Remoting examples](https://wiki.jenkins-ci.org/display/JENKINS/Remoting)
+* [Troubleshooting remoting issues](https://wiki.jenkins-ci.org/display/JENKINS/Remoting+issue)
+* [Scaling Jenkins to Hundreds of Nodes](https://www.cloudbees.com/jenkins/juc-2015/abstracts/us-west/02-01-1600) 
+by Akshay Dayal, Google (remoting optimization, JNLP3)

docs/configuration.md

@@ -0,0 +1,105 @@
+Remoting Configuration
+====
+
+Remoting can be configured via System properties. 
+These properties require independent configuration on both sides of the channel.
+
+### Available settings
+
+<table>
+  <tbody>
+    <tr>
+      <td>System property</td>
+      <td>Default value</td>
+      <td><a href="../CHANGELOG.md">Since</a></td>
+      <td><a href="https://jenkins.io/changelog/">Jenkins version(s)</a></td>
+      <td>Related issues</td>
+      <td>Description</td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.ClassFilter.DEFAULTS_OVERRIDE_LOCATION</td>
+      <td>null</td>
+      <td>2.53.2</td>
+      <td>1.639</td>
+      <td><a href="https://wiki.jenkins-ci.org/display/SECURITY/Jenkins+Security+Advisory+2015-11-11">SECURITY-218</a></td>
+      <td>The path to a file containing alternative regex patterns for remoting class filtering</td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.FlightRecorderInputStream.BUFFER_SIZE</td>
+      <td>1048576</td>
+      <td>2.41</td>
+      <td>1.563</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-22734">JENKINS-22734</a></td>
+      <td>Size (in bytes) of the flight recorder ring buffer used for debugging remoting issues</td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.Launcher.pingIntervalSec</td>
+      <td>0 since 2.60, 600 before</td>
+      <td>2.0</td>
+      <td>1.367</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-35190">JENKINS-35190</a></td>
+      <td>Seconds between ping checks to monitor health of slave nodes; 
+      0 to disable ping</td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.Launcher.pingTimeoutSec</td>
+      <td>240</td>
+      <td>2.0</td>
+      <td>1.367</td>
+      <td>N/A</td>
+      <td>If ping of slave node takes longer than this, consider it dead; 
+      0 to disable ping</td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.RemoteClassLoader.force</td>
+      <td>null</td>
+      <td>2.58</td>
+      <td>2.4</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-19445">JENKINS-19445</a> (workaround)</td>
+      <td>
+      Class name String.
+      Forces loading of the specified class name on incoming requests. 
+      Works around issues like <a href="https://issues.jenkins-ci.org/browse/JENKINS-19445">JENKINS-19445</a></td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.Engine.socketTimeout</td>
+      <td>30 minutes</td>
+      <td>2.58</td>
+      <td>2.4</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-34808">JENKINS-34808</a></td>
+      <td>Socket read timeout in milliseconds.
+      If timeout happens and the <code>failOnSocketTimeoutInReader</code> property is <code>true</code>, the channel will be interrupted.
+      </td>
+    </tr>
+    <tr>
+      <td>hudson.remoting.SynchronousCommandTransport.failOnSocketTimeoutInReader</td>
+      <td>false</td>
+      <td>2.60</td>
+      <td>TODO</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-22722">JENKINS-22722</a></td>
+      <td>Boolean flag.
+      Enables the original aggressive behavior, when the channel reader gets interrupted by any 
+      <code>SocketTimeoutException</code>
+      </td>
+    </tr>
+    <tr>
+      <td>${PROTOCOL_CLASS_NAME}.disabled</td>
+      <td>false</td>
+      <td>2.59</td>
+      <td>2.4</td>
+      <td><a href="https://issues.jenkins-ci.org/browse/JENKINS-34819">JENKINS-34819</a></td>
+      <td>Boolean flag, which allows disabling particular protocols in remoting.
+      Property example: <code>org.jenkinsci.remoting.engine.JnlpProtocol3.disabled</code>
+      </td>
+    </tr>
+    <!--Template
+    <tr>
+      <td></td>
+      <td></td>
+      <td></td>
+      <td></td>
+      <td></td>
+      <td></td>
+    </tr>-->
+  <tbody>
+</table>

src/main/java/hudson/remoting/ClassFilter.java

@@ -26,6 +26,7 @@ public abstract class ClassFilter {
      * Property to set to <b>override<b> the blacklist used by {{@link #DEFAULT} with a different set.
      * The location should point to a a file containing regular expressions (one per line) of classes to blacklist.
      * If this property is set but the file can not be read the default blacklist will be used.
+     * @since 2.53.2
      */
     public static final String FILE_OVERRIDE_LOCATION_PROPERTY = "hudson.remoting.ClassFilter.DEFAULTS_OVERRIDE_LOCATION";
 

src/main/java/hudson/remoting/Engine.java

@@ -578,7 +578,12 @@ private SSLSocketFactory getSSLSocketFactory()
         }
         return sslSocketFactory;
     }
-    //a read() call on the SocketInputStream associated with underlying Socket will block for only this amount of time
+
+    /**
+     * Socket read timeout.
+     * A {@link SocketInputStream#read()} call associated with underlying Socket will block for only this amount of time
+     * @since 2.4
+     */
     static final int SOCKET_TIMEOUT = Integer.getInteger(Engine.class.getName()+".socketTimeout",30*60*1000);
     /**
      * @deprecated Use {@link JnlpProtocol#GREETING_SUCCESS}.

src/main/java/hudson/remoting/FlightRecorderInputStream.java

@@ -14,6 +14,10 @@
  */
 class FlightRecorderInputStream extends InputStream {
 
+    /**
+     * Size (in bytes) of the flight recorder ring buffer used for debugging remoting issues.
+     * @since 2.41
+     */
     static final int BUFFER_SIZE = Integer.getInteger("hudson.remoting.FlightRecorderInputStream.BUFFER_SIZE", 1024 * 1024);
 
     private final InputStream source;

src/main/java/hudson/remoting/Launcher.java

@@ -527,6 +527,8 @@ public static void main(InputStream is, OutputStream os, Mode mode, boolean perf
 
         Channel channel = cb.build(is, os);
         System.err.println("channel started");
+
+        // Both settings are available since remoting-2.0
         long timeout = 1000 * Long.parseLong(
                 System.getProperty("hudson.remoting.Launcher.pingTimeoutSec", "240")),
              interval = 1000 * Long.parseLong(

src/main/java/hudson/remoting/SynchronousCommandTransport.java

@@ -24,7 +24,7 @@ public abstract class SynchronousCommandTransport extends CommandTransport {
     /**
      * Enables the original aggressive behavior, when the channel reader gets 
      * interrupted on any {@link SocketTimeoutException}.
-     * @since TODO
+     * @since 2.60
      */
     private static boolean RDR_FAIL_ON_SOCKET_TIMEOUT = Boolean.getBoolean(RDR_SOCKET_TIMEOUT_PROPERTY_NAME);
 

src/main/java/hudson/remoting/UserRequest.java

@@ -96,6 +96,7 @@ protected UserResponse<RSP,EXC> perform(Channel channel) throws EXC {
             // Allow forcibly load of a class, allows to workaround:
             // @See        https://issues.jenkins-ci.org/browse/JENKINS-19445
             // @Related    https://issues.tmatesoft.com/issue/SGT-451
+            // @Since 2.4
             final String clazz = System.getProperty(RemoteClassLoader.class.getName() + ".force", null);
             if ( clazz != null && !workaroundDone) {
                 // Optimistic logging set.

src/main/java/org/jenkinsci/remoting/engine/JnlpProtocol.java

@@ -60,6 +60,7 @@ public abstract class JnlpProtocol {
     /**
      * Whether this protocol is enabled for connecting.
      * @return {@code true} if this protocol is enabled.
+     * @since 2.59
      */
     public boolean isEnabled() {
         return !Boolean.getBoolean(getClass().getName()+".disabled");