update manpage

1 files changed, 32 insertions, 4 deletions

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