view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

- **port**

    Defaults to 9200.

- **proto**

    Defaults to 'http', can also be 'https'.

- **http-username**

    If HTTP Basic Authentication is required, use this username.

    See also the ["HTTP Basic Authentication"](#http-basic-authentication) section for more details

- **password-exec**

    If HTTP Basic Authentication is required, run this command, passing the arguments:

        <command_to_run> <es_host> <es_username>

    The script expects the last line to contain the password in plaintext.

- **noop**

    Prevents any communication to the cluster from making changes to the settings or data contained therein.
    In short, it prevents anything but HEAD and GET requests, **except** POST requests to the \_search endpoint.

- **timeout**

    Timeout for connections and requests, defaults to 10.

- **keep-proxy**

    By default, HTTP proxy environment variables are stripped. Use this option to keep your proxy environment variables
    in tact.

- **insecure**

    Don't verify TLS certificates

- **cacert**

    Specify a file with the TLS CA certificates.

- **capath**

    Specify a directory containing the TLS CA certificates.

- **cert**

    Specify the path to the TLS client certificate file..

- **key**

    Specify the path to the TLS client private key file.

# AUTHENTICATION

HTTP Basic Authorization is only supported when the `proto` is set to **https**
as not to leak credentials all over.

The username is selected by going through these mechanisms until one is found:

    --http-username
    'http-username' in /etc/es-utils.yml or ~/.es-utils.yml
    Netrc element matching the hostname of the request
    CLI::Helpers prompt()

Once the username has been resolved, the following mechanisms are tried in order:

    Netrc element matching the hostname of the request
    Password executable defined by --password-exec
    'password-exec' in /etc/es-utils.yml, ~/.es-utils.yml
    CLI::Helpers prompt()

## Password Exec

It is **BAD** practice to specify passwords as a command line argument, or store it in a plaintext
file.  There are cases where this may be necessary, but it is not recommended.  The best method for securing  your
password is to use the **password-exec** option.

This option must point to an executable script.  That script will be passed two arguments, the hostname and the username
for the request.  It expects the password printed to STDOUT as the last line of output.  Here's an example password-exec setup
using Apple Keychain:

    #!/bin/sh

    HOSTNAME=$1;
    USERNAME=$2;

    /usr/bin/security find-generic-password -w -a "$USERNAME" -s "$HOSTNAME"

If we save this to "$HOME/bin/get-passwd.sh" we can execute a script
like this:

    $ es-search.pl --http-username bob --password-exec $HOME/bin/get-passwd.sh \
                    --base secure-data --fields

Though it's probably best to set this in your ~/.es-utils.yml file:

    ---
    host: secured-cluster.example.org
    port: 443
    proto: https
    http-username: bob
    password-exec: /home/bob/bin/get-passwd.sh

### CLI::Helpers and Password Prompting

If all the fails to yield a password, the last resort is to use CLI::Helpers::prompt() to ask the user for their
password.  If the user is using version 1.1 or higher of CLI::Helpers, this call will turn off echo and readline magic
for the password prompt.

# INDEX SELECTION ARGUMENTS

- **base**

    In an environment using monthly, weekly, daily, or hourly indexes.  The base index name is everything without the date.
    Parsing for bases, also provides splitting and matching on segments of the index name delineated by the '-' character.
    If we have the following indexes: