Skip to content

Commit 2638c1e

Browse files
russcamrusscam
committed
Regenerate docs
1 parent 128f36c commit 2638c1e

File tree

44 files changed

+6708
-6589
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+6708
-6589
lines changed

‎docs/aggregations.asciidoc

+114-114
Large diffs are not rendered by default.

‎docs/aggregations/bucket/parent/parent-aggregation-usage.asciidoc

+1
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ new ParentAggregation("name_of_parent_agg", typeof(CommitActivity)) <1>
4747
}
4848
----
4949
<1> `join` field is determined from the _child_ type. In this example, it is `CommitActivity`
50+
5051
<2> sub-aggregations are on the type determined from the `join` field. In this example, a `Project` is a parent of `CommitActivity`
5152

5253
[source,javascript]

‎docs/aggregations/writing-aggregations.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -232,6 +232,7 @@ return s => s
232232
);
233233
----
234234
<1> a list of aggregation functions to apply
235+
235236
<2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
236237

237238
[[handling-aggregate-response]]
@@ -275,5 +276,6 @@ var maxPerChild = childAggregation.Max("max_per_child");
275276
maxPerChild.Should().NotBeNull(); <2>
276277
----
277278
<1> Do something with the average per child. Here we just assert it's not null
279+
278280
<2> Do something with the max per child. Here we just assert it's not null
279281

‎docs/client-concepts/certificates/working-with-certificates.asciidoc

+115-115
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,122 @@
1-
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master
2-
3-
:github: https://github.com/elastic/elasticsearch-net
4-
5-
:nuget: https://www.nuget.org/packages
6-
7-
////
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
88
IMPORTANT NOTE
99
==============
1010
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/ClientConcepts/Certificates/WorkingWithCertificates.doc.cs.
1111
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12-
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13-
////
14-
15-
[[working-with-certificates]]
16-
=== Working with certificates
17-
18-
If you've enabled SSL on Elasticsearch with https://www.elastic.co/products/elastic-stack[Elastic Stack Security features], or through a
19-
proxy in front of Elasticsearch, and the Certificate Authority (CA)
20-
that generated the certificate is trusted by the machine running the client code, there should be nothing for you to do to talk
21-
to the cluster over HTTPS with the client.
22-
23-
If you are using your own CA which is not trusted however, .NET won't allow you to make HTTPS calls to that endpoint by default.
24-
With .NET Framework, you can pre-empt this though a custom validation callback on the global static
25-
`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
26-
validation callback and merrily whistle off into the sunset. **This is not advisable** as it allows *any* HTTPS traffic through in the
27-
current `AppDomain` *without* any validation. Here's a concrete example:
28-
29-
Imagine you deploy a web application that talks to Elasticsearch over HTTPS using NEST, and also uses some third party SOAP/WSDL endpoint.
30-
By setting the following
31-
32-
[source,csharp]
33-
----
34-
ServicePointManager.ServerCertificateValidationCallback +=
35-
(sender, cert, chain, errors) => true
36-
----
37-
38-
validation will not be performed for HTTPS connections to *both* Elasticsearch *and* that external web service.
39-
40-
==== Validation configuration
41-
42-
It's possible to also set a callback per service endpoint with .NET, and both Elasticsearch.NET and NEST expose this through
43-
connection settings (`ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
44-
your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class
45-
`CertificateValidations`.
46-
47-
The two most basic ones are `AllowAll` and `DenyAll`, which accept or deny all SSL traffic to our nodes, respectively. Here's
48-
a couple of examples.
49-
50-
===== Denying all certificate validation
51-
52-
Here we set up `ConnectionSettings` with a validation callback that denies all certificate validation
53-
54-
[source,csharp]
55-
----
56-
[IntegrationOnly]
57-
public class DenyAllCertificatesCluster : SslAndKpiXPackCluster
58-
{
59-
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
60-
.ServerCertificateValidationCallback((o, certificate, chain, errors) => false)
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[working-with-certificates]]
16+
=== Working with certificates
17+
18+
If you've enabled SSL on Elasticsearch with https://www.elastic.co/products/elastic-stack[Elastic Stack Security features], or through a
19+
proxy in front of Elasticsearch, and the Certificate Authority (CA)
20+
that generated the certificate is trusted by the machine running the client code, there should be nothing for you to do to talk
21+
to the cluster over HTTPS with the client.
22+
23+
If you are using your own CA which is not trusted however, .NET won't allow you to make HTTPS calls to that endpoint by default.
24+
With .NET Framework, you can pre-empt this though a custom validation callback on the global static
25+
`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
26+
validation callback and merrily whistle off into the sunset. **This is not advisable** as it allows *any* HTTPS traffic through in the
27+
current `AppDomain` *without* any validation. Here's a concrete example:
28+
29+
Imagine you deploy a web application that talks to Elasticsearch over HTTPS using NEST, and also uses some third party SOAP/WSDL endpoint.
30+
By setting the following
31+
32+
[source,csharp]
33+
----
34+
ServicePointManager.ServerCertificateValidationCallback +=
35+
(sender, cert, chain, errors) => true
36+
----
37+
38+
validation will not be performed for HTTPS connections to *both* Elasticsearch *and* that external web service.
39+
40+
==== Validation configuration
41+
42+
It's possible to also set a callback per service endpoint with .NET, and both Elasticsearch.NET and NEST expose this through
43+
connection settings (`ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
44+
your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class
45+
`CertificateValidations`.
46+
47+
The two most basic ones are `AllowAll` and `DenyAll`, which accept or deny all SSL traffic to our nodes, respectively. Here's
48+
a couple of examples.
49+
50+
===== Denying all certificate validation
51+
52+
Here we set up `ConnectionSettings` with a validation callback that denies all certificate validation
53+
54+
[source,csharp]
55+
----
56+
[IntegrationOnly]
57+
public class DenyAllCertificatesCluster : SslAndKpiXPackCluster
58+
{
59+
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
60+
.ServerCertificateValidationCallback((o, certificate, chain, errors) => false)
6161
.ServerCertificateValidationCallback(CertificateValidations.DenyAll); <1>
62-
}
63-
----
64-
<1> use a lambda expression or `CertificateValidations.DenyAll` to deny all validation
65-
66-
===== Allowing all certificate validation
67-
68-
Here we set up `ConnectionSettings` with a validation callback that allows all certificate validation
69-
70-
[source,csharp]
71-
----
72-
public class AllowAllCertificatesCluster : SslAndKpiXPackCluster
73-
{
74-
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
62+
}
63+
----
64+
<1> use a lambda expression or `CertificateValidations.DenyAll` to deny all validation
65+
66+
===== Allowing all certificate validation
67+
68+
Here we set up `ConnectionSettings` with a validation callback that allows all certificate validation
69+
70+
[source,csharp]
71+
----
72+
public class AllowAllCertificatesCluster : SslAndKpiXPackCluster
73+
{
74+
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
7575
.ServerCertificateValidationCallback((o, certificate, chain, errors) => true) <1>
7676
.ServerCertificateValidationCallback(CertificateValidations.AllowAll); <1>
77-
}
78-
----
79-
<1> use a lambda expression or `CertificateValidations.AllowAll` to allow all validation
80-
81-
===== Allowing certificates from a Certificate Authority
82-
83-
If your client application has access to the public CA certificate locally, Elasticsearch.NET and NEST ship with some handy helpers
84-
that can assert that a certificate the server presents is one that came from the local CA.
85-
86-
If you use {ref_current}/certutil.html[`elasticsearch-certutil` tool] to generate SSL certificates, the generated node certificate
87-
does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
88-
`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
89-
the certificate the server presented was generated using it
90-
91-
[source,csharp]
92-
----
93-
[IntegrationOnly]
94-
public class CertgenCaCluster : SslAndKpiXPackCluster
95-
{
96-
public CertgenCaCluster() : base() { }
97-
public CertgenCaCluster(SslAndKpiClusterConfiguration configuration) : base(configuration) { }
98-
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
99-
.ServerCertificateValidationCallback(
100-
CertificateValidations.AuthorityIsRoot(new X509Certificate(this.ClusterConfiguration.FileSystem.CaCertificate))
101-
);
102-
}
103-
----
104-
105-
If your local copy does not match the server's CA, the client will fail to connect
106-
107-
[source,csharp]
108-
----
109-
[IntegrationOnly]
110-
public class BadCertgenCaCluster : SslAndKpiXPackCluster
111-
{
112-
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
113-
.ServerCertificateValidationCallback(
114-
CertificateValidations.AuthorityPartOfChain(new X509Certificate(this.ClusterConfiguration.FileSystem.UnusedCaCertificate))
115-
);
116-
}
117-
----
118-
119-
If you go for a vendor generated SSL certificate, it's common practice for the certificate to include the CA _and_ any intermediary CAs
120-
in the certificate chain. When using such a certificate, use `CertificateValidations.AuthorityPartOfChain` which validates that
121-
the local CA certificate is part of the chain that was used to generate the servers key.
122-
77+
}
78+
----
79+
<1> use a lambda expression or `CertificateValidations.AllowAll` to allow all validation
80+
81+
===== Allowing certificates from a Certificate Authority
82+
83+
If your client application has access to the public CA certificate locally, Elasticsearch.NET and NEST ship with some handy helpers
84+
that can assert that a certificate the server presents is one that came from the local CA.
85+
86+
If you use {ref_current}/certutil.html[`elasticsearch-certutil` tool] to generate SSL certificates, the generated node certificate
87+
does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
88+
`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
89+
the certificate the server presented was generated using it
90+
91+
[source,csharp]
92+
----
93+
[IntegrationOnly]
94+
public class CertgenCaCluster : SslAndKpiXPackCluster
95+
{
96+
public CertgenCaCluster() : base() { }
97+
public CertgenCaCluster(SslAndKpiClusterConfiguration configuration) : base(configuration) { }
98+
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
99+
.ServerCertificateValidationCallback(
100+
CertificateValidations.AuthorityIsRoot(new X509Certificate(this.ClusterConfiguration.FileSystem.CaCertificate))
101+
);
102+
}
103+
----
104+
105+
If your local copy does not match the server's CA, the client will fail to connect
106+
107+
[source,csharp]
108+
----
109+
[IntegrationOnly]
110+
public class BadCertgenCaCluster : SslAndKpiXPackCluster
111+
{
112+
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
113+
.ServerCertificateValidationCallback(
114+
CertificateValidations.AuthorityPartOfChain(new X509Certificate(this.ClusterConfiguration.FileSystem.UnusedCaCertificate))
115+
);
116+
}
117+
----
118+
119+
If you go for a vendor generated SSL certificate, it's common practice for the certificate to include the CA _and_ any intermediary CAs
120+
in the certificate chain. When using such a certificate, use `CertificateValidations.AuthorityPartOfChain` which validates that
121+
the local CA certificate is part of the chain that was used to generate the servers key.
122+

0 commit comments

Comments
 (0)