Merge pull request #472 from untergeek/doc/450

Release of 3.3.0

Changelog.rst

@@ -3,8 +3,8 @@
 Changelog
 =========
 
-3.3.0 (? ? ?)
--------------
+3.3.0 (31 August 2015)
+----------------------
 
 **Announcement**
 
@@ -25,8 +25,8 @@ Changelog
 
 **General**
 
-  * Allocation type can now also be 'include' or 'exclude', in addition to the
-   the existing default 'require' type. Add --type to the allocation command
+  * Allocation type can now also be ``include`` or ``exclude``, in addition to the
+   the existing default ``require`` type. Add ``--type`` to the allocation command
    to specify the type. #443 (steffo)
 
   * Bump elasticsearch python module dependency to 1.6.0+ to enable synced_flush

curator/_version.py

@@ -1 +1 @@
-__version__ = '3.3.0.dev4'
+__version__ = '3.3.0'

docs/asciidoc/commands/allocation.asciidoc

@@ -45,8 +45,9 @@ ________________________________________________________________________________
 
  
 
-It is this last method, `index.routing.allocation.require.*`, that Curator uses
-to force routing.  Curator does not use `include` or `exclude` tagging.
+In versions 3.2.3 and older, Curator used this last method,
+`index.routing.allocation.require.*`, to force routing.  Beginning in version
+3.3.0, Curator also allows the use of `include` and `exclude` tagging.
 
 [float]
 Use-case
@@ -98,14 +99,17 @@ Flags
 $ curator allocation --help
 Usage: curator allocation [OPTIONS] COMMAND [ARGS]...
 
-Index Allocation
+  Index Allocation
 
 Options:
- --rule TEXT Routing allocation rule to apply, e.g. tag=ssd
- --help Show this message and exit.
+  --rule TEXT  Routing allocation rule to apply, e.g. tag=ssd
+  --type TEXT  Specify an allocation type, include, exclude or require
+               [default: require]
+  --help       Show this message and exit.
 
 Commands:
- indices Index selection.
+  indices  Index selection.
+
 --------------------------------------------------------------------------------
 
  

docs/asciidoc/flags/certificate.asciidoc

@@ -0,0 +1,28 @@
+[[certificate]]
+== --certificate
+
+[float]
+Summary
+~~~~~~~
+
+Allows the use of a specified CA certificate file to validate the SSL certificate
+used by Elasticsearch.
+
+[float]
+Flags
+~~~~~
+
+* `--certificate` Path to certificate to use for SSL validation.
+
+IMPORTANT: This flag must come before any <<commands,command>>.
+
+[float]
+Example
+~~~~~~~
+
+Connect to a cluster at `https://example.com/` via SSL and verify the
+certificate with the provided CA certificate file:
+
+---------------------------------------------------------------------
+curator --host example.com --port 443 --use_ssl --certificate /path/to/cacert.pem <<command>> <<flags>>
+---------------------------------------------------------------------

docs/asciidoc/flags/index.asciidoc

@@ -17,6 +17,8 @@
 * <<timeout,--timeout>>
 * <<url_prefix,--url_prefix>>
 * <<use_ssl,--use_ssl>>
+* <<certificate,--certificate>>
+* <<ssl-no-validate,--ssl-no-validate>>
 * <<version,--version>>
 
 _Index and Snapshot Selection_
@@ -59,6 +61,8 @@ include::port.asciidoc[]
 include::timeout.asciidoc[]
 include::url_prefix.asciidoc[]
 include::use_ssl.asciidoc[]
+include::certificate.asciidoc[]
+include::ssl-no-validate.asciidoc[]
 include::version.asciidoc[]
 
 include::newer-than.asciidoc[]

docs/asciidoc/flags/ssl-no-validate.asciidoc

@@ -0,0 +1,34 @@
+[[ssl-no-validate]]
+== --ssl-no-validate
+
+[float]
+Summary
+~~~~~~~
+
+If access to your Elasticsearch instance is protected by SSL encryption, you
+may use the `--ssl-no-validate` flag to disable SSL certificate verification.
+
+Valid use cases for this flag include the use of self-signed certificates that
+cannot be otherwise verified and would generate error messages.
+
+NOTE: The use of this flag will likely result in a warning message that your SSL
+certificates are not trusted.  This is expected behavior.
+
+[float]
+Flags
+~~~~~
+
+* `--ssl-no-validate` Do not validate SSL certificate
+
+IMPORTANT: This flag must come before any <<commands,command>>.
+
+[float]
+Example
+~~~~~~~
+
+Connect to a cluster at `https://example.com/` via SSL but do not verify the
+certificate:
+
+---------------------------------------------------------------------
+curator --host example.com --port 443 --use_ssl --ssl-no-validate <<command>> <<flags>>
+---------------------------------------------------------------------

docs/asciidoc/flags/use_ssl.asciidoc

@@ -8,11 +8,39 @@ Summary
 If access to your Elasticsearch instance is protected by SSL encryption, you
 must use the `--use_ssl` flag.
 
-TIP: Beginning with version 3.2.0, Curator has _experimental_ support for
-validating SSL certificates.  In order to make this work, an additional Python
-module needs to be installed via `pip install certifi`. If the `certifi` module
-is installed, and you are connecting to Elasticsearch via SSL, the verification
-should automatically take place.
+[float]
+SSL Certificate Validation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Beginning with version 3.2.0, Curator added _experimental_ support for
+validating SSL certificates.  These features were enhanced in version 3.3.0 to
+support additional SSL validation options.
+
+Depending on which validation option you choose, you may need to install an
+additional Python module.
+
+**If you have certificates signed by a commonly known Certificate Authority...**
+
+Chances are good that the CA certificates bundled with Mozilla Firefox will be
+able to validate your certificate. In this case, use of the `certifi` python
+module will work. This can be installed via `pip install certifi`.
+
+With the `certifi` module installed, if you are connecting to Elasticsearch via
+SSL, the verification should automatically take place.
+
+**If you have an unrecognized CA, use self-signed certificates, or do not wish
+to install the `certifi` module...**
+
+In this case you can use the <<certificate,--certificate>> flag to point to the
+file which holds the CA certificate to use for validation. This file should be in
+PEM format.
+
+**If you do not wish to validate your certificate at all...**
+
+This is not recommended, but if you so desire, you can use the
+<<ssl-no-validate,--ssl-no-validate>> flag. Use of this flag will likely still
+yield a warning about insecure connections, but still permit the use of SSL
+communications.
 
 [float]
 Flags