update manpage

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