aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--extra/es-public-proxy.163
-rw-r--r--extra/es-public-proxy.1.scdoc36
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