Document the --http-addr flag.

Accompanies the merged fix cockroachdb/cockroach#7475

manual-deployment.md

@@ -142,7 +142,7 @@ Store the CA key somewhere safe and keep a backup; if you lose it, you will not
 Copy the `cockroach` binary, CA certificate, and node 1 certificate and key to the first machine and then start the node:
 
 ~~~ shell
-$ cockroach start --ca-cert=ca.cert --cert=node1.cert --key=node1.key --host=<node1-hostname>
+$ cockroach start --http-addr=127.0.0.1 --ca-cert=ca.cert --cert=node1.cert --key=node1.key --host=<node1-hostname>
 ~~~
 
 This command specifies the location of certificates and the address at which other nodes can reach it. Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html). 
@@ -152,7 +152,7 @@ This command specifies the location of certificates and the address at which oth
 Copy the `cockroach` binary, CA certificate, and node 2 certificate and key to the second machine and then start the node:
 
 ~~~ shell
-$ cockroach start --ca-cert=ca.cert --cert=node2.cert --key=node2.key --host=<node2-hostname> --join=<node1-hostname>:26257
+$ cockroach start --http-addr=127.0.0.1 --ca-cert=ca.cert --cert=node2.cert --key=node2.key --host=<node2-hostname> --join=<node1-hostname>:26257
 ~~~
 
 The only difference when starting the second node is that you connect it to the cluster with the `--join` flag, which takes the address and port of the first node. Otherwise, it's fine to accept all defaults; since each node is on a unique machine, using identical ports won't cause conflicts.
@@ -211,17 +211,27 @@ For a list of recommended drivers that we've tested, see [Install Client Drivers
 
 ### 8. Monitor your cluster
 
-The CockroachDB Admin UI lets you monitor cluster-wide, node-level, and database-level metrics and events. To start up the Admin UI, point your browser to the URL in the `admin` field listed in the standard output of any node on startup, for example:
+The CockroachDB Admin UI lets you monitor cluster-wide, node-level, and database-level metrics and events. To view the secured Admin UI on remote node1.example.com, first establish an ssh tunnel, then point your browser to the URL in the `admin` field listed in the standard output of any node on startup. For example, your start command may have gaven output like this:
 
 ~~~ shell
-$ cockroach start --insecure --host=node1.example.com
+$ cockroach start --http-addr=127.0.0.1 --ca-cert=ca.cert --cert=node1.cert --key=node1.key --host=node1.example.com
 build:     {{site.data.strings.version}} @ {{site.data.strings.build_time}}
-admin:     https://node1.example.com:8080 <-------------------------------- USE THIS URL
+admin:     https://127.0.0.1:8080 <-------------- ESTABLISH SSH TUNNEL TO HERE
 sql:       postgresql://[email protected]:26257?sslcert=%2FUsers%2F...
 logs:      cockroach-data/logs
 store[0]:  path=cockroach-data
 ~~~
 
+Here is how to use ssh to tunnel port 8081 from your desktop to the node1.example.com cluster node:
+
+~~~ shell
+$ ssh -L 8081:127.0.0.1:8080 node1.example.com
+~~~
+
+(See the ssh man pages for details the -L port forwarding command)[http://linuxcommand.org/man_pages/ssh1.html]. Once the ssh login is complete, you may just leave the remote shell open in the terminal window. This allows you to easily monitor the tunnel, should network problems cause a disconnect.
+
+Continuing the example above, you would point your browser to `https://127.0.0.1:8081` to view the Admin UI. The ssh tunnel takes care of securely routing this traffic to port 8080 on the node1.example.com, without exposing the Admin UI to the public world.
+
 <img src="images/admin_ui.png" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />
 
 ## See Also

secure-a-cluster.md

@@ -46,7 +46,7 @@ Now that you have a [local cluster](start-a-local-cluster.html) up and running,
 3.  Restart the first node:
  
     ~~~ shell
-    $ cockroach start --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --background
+    $ cockroach start --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --http-addr=127.0.0.1 --background
 
     build:     {{site.data.strings.version}} @ {{site.data.strings.build_time}}
     admin:     https://ROACHs-MBP:8080
@@ -65,14 +65,14 @@ Now that you have a [local cluster](start-a-local-cluster.html) up and running,
 4.  Restart additional nodes:
 
     ~~~ shell
-    $ cockroach start --store=node2 --port=26258 --http-port=8081 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --background
-    $ cockroach start --store=node3 --port=26259 --http-port=8082 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --background
+    $ cockroach start --store=node2 --port=26258 --http-port=8081 --http-addr=127.0.0.1 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --background
+    $ cockroach start --store=node3 --port=26259 --http-port=8082 --http-addr=127.0.0.1 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key --background
     ~~~
 
     <button type="button" class="btn details collapsed" data-toggle="collapse" data-target="#details-secure4">Details</button>
     <div id="details-secure4" class="collapse" markdown="1">
 
-    These commands restart additional nodes with their existing data, but securely. The commands are the same as before but now uses the additional `--ca-cert`, `--cert`, and `--key` flags to point to the CA certificate and the node certificate and key created in step 2.
+    These commands restart additional nodes with their existing data, but securely. The commands are the same as before but now uses the additional `--ca-cert`, `--cert`, and `--key` flags to point to the CA certificate and the node certificate and key created in step 2. The additional `--http-addr` restricts access to the http Admin UI interface, so that only local 127.0.0.1 or ssh-tunnelled administrators may access it.
 
     </div>
 
@@ -119,7 +119,7 @@ Now that you have a [local cluster](start-a-local-cluster.html) up and running,
 
     When you're done using the SQL shell, press **CTRL + D** to exit.
 
-7.  Reopen the [Admin UI](explore-the-admin-ui.html) by pointing your browser to `https://localhost:8080`. You can also find the address in the `admin` field in the standard output of any node on startup. 
+7.  Access the [Admin UI](explore-the-admin-ui.html) by first establishing an SSH tunnel for the http traffic from you laptop to the cockroach server by doing `ssh -L 8081:127.0.0.1:8080 ROACHs-MBP` at the shell prompt (substitute your first node's address for ROACHs-MBP). Note that you can and should skip the ssh tunnel if you are running cockroach locally on your laptop. Then point your browser at `https://127.0.0.1:8081`. You can find the address to tunnel to in the `admin` field in the standard output of any node on startup. 
 
     Note that your browser will consider the CockroachDB-created certificate invalid; you’ll need to click through a warning message to get to the UI.
 

start-a-local-cluster.md

@@ -45,6 +45,7 @@ This command starts a node, accepting all [`cockroach start`](start-a-node.html)
 
 - Communication is insecure, with the server listening only on `localhost` on port `26257` for internal and client communication and on port `8080` for HTTP requests from the Admin UI. 
    - To bind to different ports, set `--port=<port>` and `--http-port=<port>`. 
+   - To bind the Admin web UI to a private IP address or host, set `--http-addr=<private-addr>`.
    - To listen on an external hostname or IP address, set `--insecure` and `--host=<external address>`. For a demonstration, see [Manual Deployment](manual-deployment.html). 
 
 - Node data is stored in the `cockroach-data` directory. To store data in a different location, set `--store=<filepath>`. To use multiple stores, set this flag separately for each.

start-a-node.md

@@ -33,7 +33,8 @@ Flag | Description
 `--ca-cert` | The path to the [CA certificate](create-security-certificates.html). This flag is required to start a secure node. 
 `--cert` | The path to the [node certificate](create-security-certificates.html). This flag is required to start a secure node.
 `--host` | The address to listen on for internal and client communication. The node also advertises itself to other nodes using this address. Therefore, if it is a hostname, it must be resolvable from all nodes, and if it is an IP address, it must be routable from all nodes.<br><br>When running an insecure local cluster (without `--insecure` and without cert flags), this defaults to `localhost` and cannot be changed. When running an insecure distributed cluster (with `--insecure` but without cert flags) or a secure local or distributed cluster (without `--insecure` but with cert flags), this can be an external address.
-`--http-port` | The port to listen on for HTTP requests from the Admin UI. <br><br>**Default:** 8080
+`--http-port` | The port to listen on for HTTP requests to the Admin UI. <br><br>**Default:** 8080
+`--http-addr` | The IP address or hostname to bind for Admin UI HTTP requests. <br><br>**Default:** same as --host
 `--insecure` | Set this only if the cluster is insecure and running on multiple machines.<br><br>If the cluster is insecure and local, leave this out. If the cluster is secure, leave this out and set the `--ca-cert`, `--cert`, and `-key` flags.
 `--join` | The address for connecting the node to an existing cluster. When starting the first node, leave this flag out. When starting subsequent nodes, set this flag to the address of any existing node. Optionally, you can specify the addresses of multiple existing nodes as a comma-separated list.
 `--key` | The path to the [node key](create-security-certificates.html) protecting the node certificate. This flag is required to start a secure node. 
@@ -84,9 +85,9 @@ $ cockroach start --store=cockroach-data2 --port=26258 --http-port=8081 --join=l
 $ cockroach start --store=cockroach-data3 --port=26259 --http-port=8082 --join=localhost:26257
 
 # Secure:
-$ cockroach start --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key  
-$ cockroach start --store=cockroach-data2 --port=26258 --http-port=8081 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key
-$ cockroach start --store=cockroach-data3 --port=26259 --http-port=8082 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key
+$ cockroach start --http-addr=127.0.0.1 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key  
+$ cockroach start --store=cockroach-data2 --port=26258 --http-port=8081 --http-addr=127.0.0.1 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key
+$ cockroach start --store=cockroach-data3 --port=26259 --http-port=8082  --http-addr=127.0.0.1 --join=localhost:26257 --ca-cert=certs/ca.cert --cert=certs/node.cert --key=certs/node.key
 ~~~
 
 ### Start a distributed cluster