Skip to content

[DOCS] Standardize docs for url setting #41117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jrodewig merged 2 commits into from
Apr 24, 2019
Merged

[DOCS] Standardize docs for url setting #41117

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0fbcc1d
[DOCS] Standardize docs for `url` setting
jrodewig Apr 10, 2019
ef9d7d7
[DOCS] Revise docs for LDAP and Active Directory realm setting
jrodewig Apr 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions docs/reference/settings/security-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,10 +278,13 @@ Defaults to `true`.
The `type` setting must be set to `ldap`. In addition to the
<<ref-realm-settings>>, you can specify the following settings:

`url`:: Specifies one or more LDAP URLs in the format
`ldap[s]://<server>:<port>`. Multiple URLs can be defined using a comma
separated value or array syntax: `[ "ldaps://server1:636", "ldaps://server2:636" ]`.
`ldaps` and `ldap` URL protocols cannot be mixed in the same realm. Required.
`url`::
One or more LDAP URLs in the `ldap[s]://<server>:<port>` format. Required.
+
To provide a single URL, use the `ldap` protocol: `ldap://server1:636`. To
provide multiple URLs, use the `ldaps` protocol with an array syntax:
`["ldaps://server1:636", "ldaps://server2:636" ]`. You can't mix the `ldap` and
`ldaps` URL protocols.
Copy link
Contributor

@tvernum tvernum Apr 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect, though it's a logical interpretation of the old text (hence the need to update it)

Ignoring, for a moment, what we want the docs to say, the rules are:

  • you can specific ldap or ldaps protocols for a single URL.
  • you can specific ldap or ldaps protocols when providing multiple URLs, but you must be consistent across all URLs. That is, they must all be ldap or must all be ldaps.
  • if providing multiple URLs you can either:
    1. use YAML array syntax url: ["ldaps://server1:636", "ldaps://server2:636" ]; or
    2. use a comma separated string: url: "ldaps://server1:636,ldaps://server2:636"

I struggle to find the sweet spot between documenting every possible option, and overwhelming the reader with too much information, vs just documenting a common set of option and have users get confused about why a certain behaviour is not documented.

Which is to say, I'm not sure whether it would be better to document all of the rules that I've written above, or simplify to it.


`load_balance.type`::
The behavior to use when there are multiple LDAP URLs defined. For supported
Expand Down Expand Up @@ -547,11 +550,18 @@ The `type` setting must be set to `active_directory`. In addition to the
the following settings:

`url`::
An LDAP URL of the form `ldap[s]://<server>:<port>`. {es} attempts to
authenticate against this URL. If the URL is not specified, it is derived from
the `domain_name` setting and assumes an unencrypted connection to port 389.
Defaults to `ldap://<domain_name>:389`. This setting is required when connecting
using SSL/TLS or when using a custom port.
One or more LDAP URLs in the `ldap[s]://<server>:<port>` format. Defaults to
`ldap://<domain_name>:389`. This setting is required when connecting using
SSL/TLS or when using a custom port.
+
To provide a single URL, use the `ldap` protocol: `ldap://server1:389`. To
provide multiple URLs, use the `ldaps` protocol with an array syntax:
`["ldaps://server1:389", "ldaps://server2:389" ]`. You can't mix the `ldap` and
`ldaps` URL protocols.
Copy link
Contributor

@tvernum tvernum Apr 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per above - whatever we decide to do there should be included here.

+
If no URL is provided, {es} uses a default of `ldap://<domain_name>:389`. This
default uses the `domain_name` setting value and assumes an unencrypted
connection to port 389.

`load_balance.type`::
The behavior to use when there are multiple LDAP URLs defined. For supported
Expand Down