diff options
| -rw-r--r-- | extra/es-public-proxy.1 | 63 | ||||
| -rw-r--r-- | extra/es-public-proxy.1.scdoc | 36 |
2 files changed, 90 insertions, 9 deletions
diff --git a/extra/es-public-proxy.1 b/extra/es-public-proxy.1 index ee12f43..7ca898e 100644 --- a/extra/es-public-proxy.1 +++ b/extra/es-public-proxy.1 @@ -4,11 +4,11 @@ .nh .ad l .\" Begin generated content: -.TH "es-public-proxy" "1" "2020-08-26" "es-public-proxy Manual Page" +.TH "es-public-proxy" "1" "2020-08-27" "es-public-proxy Manual Page" .P .SH NAME .P -es-public-proxy - something something +es-public-proxy - simple read-only HTTP reverse-proxy for exposing an Elasticsearch node to the public internet .P .SH SYNOPSIS .P @@ -16,6 +16,12 @@ es-public-proxy --config CONFIGFILE .P .SH DESCRIPTION .P +es-public-proxy is intended to be a simple and reliable alternative for the +use case of exposing popular search queries on specific indices to the public +web. HTTP requests are parsed and filtered in a safe, compiled language (Rust), +then only safe queries are re-serialized and forwarded to the backend search +instance listening on a different port. +.P .SH OPTIONS .P Argument processing is crude; only one option can be specified at a time. @@ -40,13 +46,60 @@ Supply path to configuration file (TOML), which is effectively required for oper An annotated config file (TOML) will be printed to standard out. .P .RE +.SS CONFIGURATION +.P +In all cases you will want to explicitly enumerate all of the indices to have +public access. There is an `unsafe_all_indices` intended for prototyping, but +this may allow access to additional non-index API endpoints. +.P +One simple deployment pattern is to put nginx, es-public-proxy, and +elasticsearch all on the same server. In this configuration, nginx would +listen on all network interfaces on ports 80 and 443, and handle SSL upgrade +redirects from 80 to 443, as well as add transport compression, restrict client +body payload limits, etc. es-public-proxy would listen on localhost port +9292, and connect back to elasticsearch on localhost port 9200. +.P +.P +.SS LIMITATIONS +.P +Not all of the elasticsearch API has been implemented yet. In general, this +service is likely to be more strict in parsing and corner-cases. For example: +.P +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +URL query parameters like `?human` must be expanded into a boolean like `?human=true` +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +Some cases where elasticsearch will allow short-cutting a full object into a string, this proxy requires the full object format +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +index patterns in configuration are not supported + +.RE +.P .SH EXAMPLES .P Some examples of usage will go here. .P .RS 4 -es-public-proxy --example-config > /etc/es_public_proxy.toml -.P -es-public-proxy --config /etc/es_public_proxy.toml +es-public-proxy --example-config > example.toml +es-public-proxy --config example.toml .P .RE diff --git a/extra/es-public-proxy.1.scdoc b/extra/es-public-proxy.1.scdoc index 00104d9..7aa828f 100644 --- a/extra/es-public-proxy.1.scdoc +++ b/extra/es-public-proxy.1.scdoc @@ -2,7 +2,7 @@ es-public-proxy(1) "es-public-proxy Manual Page" # NAME -es-public-proxy - something something +es-public-proxy - simple read-only HTTP reverse-proxy for exposing an Elasticsearch node to the public internet # SYNOPSIS @@ -10,6 +10,12 @@ es-public-proxy --config CONFIGFILE # DESCRIPTION +es-public-proxy is intended to be a simple and reliable alternative for the +use case of exposing popular search queries on specific indices to the public +web. HTTP requests are parsed and filtered in a safe, compiled language (Rust), +then only safe queries are re-serialized and forwarded to the backend search +instance listening on a different port. + # OPTIONS Argument processing is crude; only one option can be specified at a time. @@ -26,11 +32,33 @@ Argument processing is crude; only one option can be specified at a time. *--example-config* An annotated config file (TOML) will be printed to standard out. +## CONFIGURATION + +In all cases you will want to explicitly enumerate all of the indices to have +public access. There is an `unsafe_all_indices` intended for prototyping, but +this may allow access to additional non-index API endpoints. + +One simple deployment pattern is to put nginx, es-public-proxy, and +elasticsearch all on the same server. In this configuration, nginx would +listen on all network interfaces on ports 80 and 443, and handle SSL upgrade +redirects from 80 to 443, as well as add transport compression, restrict client +body payload limits, etc. es-public-proxy would listen on localhost port +9292, and connect back to elasticsearch on localhost port 9200. + + +## LIMITATIONS + +Not all of the elasticsearch API has been implemented yet. In general, this +service is likely to be more strict in parsing and corner-cases. For example: + +- URL query parameters like `?human` must be expanded into a boolean like `?human=true` +- Some cases where elasticsearch will allow short-cutting a full object into a string, this proxy requires the full object format +- index patterns in configuration are not supported + # EXAMPLES Some examples of usage will go here. - es-public-proxy --example-config > /etc/es_public_proxy.toml - - es-public-proxy --config /etc/es_public_proxy.toml + es-public-proxy --example-config > example.toml + es-public-proxy --config example.toml |