Fix documentation for roundup-server about the 'host' parameter...

...as suggested in issue2550693, fixes the first part of this
issue. Make 'localhost' the new default for this parameter, note the
upgrading documentation of changed behaviour.  We also deprecate the
empty host parameter for binding to all interfaces now (still left in
for compatibility). Thanks to Toni Mueller for providing the first
version of this patch and discussing implementations.

Author: Ralf Schlatterbeck

CHANGES.txt

@@ -89,6 +89,13 @@ Fixed:
   generation. Set this to a higher value on faster systems which want
   more security. Thanks to Eli Collins for implementing this (see
   issue2550688).
+- Fix documentation for roundup-server about the 'host' parameter as
+  suggested in issue2550693, fixes the first part of this issue. Make
+  'localhost' the new default for this parameter, note the upgrading
+  documentation of changed behaviour.  We also deprecate the empty host
+  parameter for binding to all interfaces now (still left in for
+  compatibility). Thanks to Toni Mueller for providing the first version
+  of this patch and discussing implementations.
 
 2010-10-08 1.4.16 (r4541)
 

doc/admin_guide.txt

@@ -74,7 +74,7 @@ The basic configuration file layout is as follows (take from the
 
     [main]
     port = 8080
-    ;hostname =
+    ;host =
     ;user =
     ;group =
     ;log_ip = yes
@@ -93,9 +93,13 @@ are as follows:
 
 **port**
   Defines the local TCP port to listen for clients on.
-**hostname**
-  Defines the local hostname to listen for clients on. Only required if
-  "localhost" is not sufficient.
+**host**
+  Defines the hostname or IP number to listen for clients on. Only
+  required if `localhost` is not sufficient. If left empty (as opposed
+  to no `host` keyword in the config-file) this will listen to all
+  network interfaces and is equivalent to an explicit address `0.0.0.0`.
+  The use of an empty string to listen to all interfaces is deprecated
+  and will go away in a future version.
 **user** and **group**
   Defines the Unix user and group to run the server as. Only work if the
   server is started as root.

doc/upgrading.txt

@@ -16,13 +16,23 @@ steps.
 Migrating from 1.4.x to 1.4.17
 ==============================
 
-There is a new config-option 'migrate_passwords' in section 'web' to
+There is a new config-option `migrate_passwords` in section `web` to
 auto-migrate passwords at web-login time to a more secure storage
 scheme. Default for the new option is "yes" so if you don't want that
 passwords are auto-migrated to a more secure password scheme on user
 login, set this to "no" before running your tracker(s) after the
 upgrade.
 
+The standalone roundup-server now defaults to listening on localhost (no
+longer on all network interfaces). This will not affect you if you're
+already using a configuration file for roundup-server. If you are using
+an empty setting for the `host` parameter in the config-file you should
+explicitly put 0.0.0.0 there as the use of an empty string to specify
+listening to all interfaces is deprecated and will go away in a future
+version.  If you are starting the server without a configuration file
+and want to explicitly listen to all network interface, you should
+specify the -n option with the address `0.0.0.0`.
+
 Searching now requires either read-permission without a check method, or
 you will have to add a "Search" permission for a class or a list of
 properties for a class (if you want to allow searching). For the classic

roundup/scripts/roundup_server.py

@@ -465,9 +465,16 @@ class ServerConfig(configuration.Config):
 
     SETTINGS = (
             ("main", (
-            (configuration.Option, "host", "",
+            (configuration.Option, "host", "localhost",
                 "Host name of the Roundup web server instance.\n"
-                "If empty, listen on all network interfaces."),
+                "If left unconfigured (no 'host' setting) the default\n"
+                "will be used.\n"
+                "If empty, listen on all network interfaces.\n"
+                "If you want to explicitly listen on all\n"
+                "network interfaces, the address 0.0.0.0 is a more\n"
+                "explicit way to achieve this, the use of an empty\n"
+                "string for this purpose is deprecated and will go away\n"
+                "in a future release."),
             (configuration.IntegerNumberOption, "port", DEFAULT_PORT,
                 "Port to listen on."),
             (configuration.NullableFilePathOption, "favicon", "favicon.ico",
@@ -734,7 +741,10 @@ def usage(message=''):
  -h            print this text and exit
  -S            create or update configuration file and exit
  -C <fname>    use configuration file <fname>
- -n <name>     set the host name of the Roundup web server instance
+ -n <name>     set the host name of the Roundup web server instance,
+               specifies on which network interfaces to listen for
+               connections, defaults to localhost, use 0.0.0.0 to bind
+               to all network interfaces
  -p <port>     set the port to listen on (default: %(port)s)
  -l <fname>    log to the file indicated by fname instead of stderr/stdout
  -N            log client machine names instead of IP addresses (much slower)