Merge lp:~smoser/cloud-init/trunk.doc-seedrandom into lp:~cloud-init-dev/cloud-init/trunk

[Scott Moser]

Doc: document random_seed in cloud-config

As raised in bug 1424549 this needs some documentation.

[lp:~smoser/cloud-init/trunk.doc-seedrandom]

1152. By Scott Moser on 2015-10-20

add random_seed dict

=== added file 'doc/examples/cloud-config-random-seed.txt'
--- doc/examples/cloud-config-random-seed.txt	1970-01-01 00:00:00 +0000
+++ doc/examples/cloud-config-random-seed.txt	2015-10-20 16:18:46 +0000
@@ -0,0 +1,48 @@
+#cloud-config
+
+# cloud-config can configure a random seed through the 'random_seed' module.
+# The purpose of the module is effectively to write random data into
+# /dev/urandom to seed this system's entropy pool to improve the random data
+# generated.  This is especially important early in boot and first boot when
+# random data is required by ssh to generate host keys.
+
+# The configuration looks like this:
+#
+# random_seed:
+#  file: "/dev/urandom"
+#     the file to write data to. defaults to '/dev/urandom'
+#     this is presented to 'command' below in an environment variable
+#     named RANDOM_SEED_FILE.
+#
+#  data: ""
+#    if data is provided, it will be written to 'file'.
+#    This gives the user a way to provide their own random data.
+#
+#  command: ['pollinate', '-q']
+#    This command is run, and is expected to aid in seeding entropy
+#    pool.  The default command is as shown.  It can be set to anything.
+#    The command will have access to the environment variable
+#    RANDOM_SEED_FILE that is set to 'file' from above.
+#    
+#    To set a specific pollinate server, you could use:
+#      command: ['pollinate', '--server', 'http://your.server/']
+#    
+#    If the command exits failure, a warning will be raised.
+#    
+#  command_required: False
+#    command_required indicates if this config module should fail
+#    if the command is not present.  For example, if your image does
+#    not have 'pollinate' and you set 'command_required' to True
+#    then this module would raise an error.
+#
+random_seed:
+  file: /dev/urandom
+  data: ""
+  command: ['pollinate', '-q']
+  command_required: False
+
+#
+# Additionally, if the datasource provides some random data, cloud-init
+# will use that as well.  The Openstack datasource provides a hunk of random
+# data in its metadata, and the Azure datasource provides random data
+# in an acpi table (/sys/firmware/acpi/tables/OEM0).