From 2aadfe74914881d55b9173081e777080d280fc97 Mon Sep 17 00:00:00 2001
From: Bryan Newbold <bnewbold@archive.org>
Date: Wed, 26 Aug 2020 20:26:51 -0700
Subject: update manpage

---
 extra/es-public-proxy.1 | 63 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 58 insertions(+), 5 deletions(-)

(limited to 'extra/es-public-proxy.1')

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
-- 
cgit v1.2.3