From 5185a9279824122883d21775bb157ae81a668043 Mon Sep 17 00:00:00 2001 From: Joe Nelson Date: Sat, 9 Sep 2017 20:21:46 -0500 Subject: [PATCH] Move config section to install page Document special host binding addresses Fixes #83 --- admin.rst | 102 ------------------------------------------------ conf.py | 4 +- install.rst | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 104 deletions(-) diff --git a/admin.rst b/admin.rst index 2e3e7ba23..f4b291bd1 100644 --- a/admin.rst +++ b/admin.rst @@ -1,105 +1,3 @@ -.. _configuration: - -Configuration -============= - -The PostgREST server reads a configuration file to determine information about the database and how to serve client requests. There is no predefined location for this file, you must specify the file path as the one and only argument to the server: - -.. code:: bash - - postgrest /path/to/postgrest.conf - -The file must contain a set of key value pairs. At minimum you must include these keys: - -.. code:: - - # postgrest.conf - - # The standard connection URI format, documented at - # https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347 - db-uri = "postgres://user:pass@host:5432/dbname" - - # The name of which database schema to expose to REST clients - db-schema = "api" - - # The database role to use when no client authentication is provided. - # Can (and probably should) differ from user in db-uri - db-anon-role = "anon" - -The user specified in the db-uri is also known as the authenticator role. For more information about the anonymous vs authenticator roles see the :ref:`roles`. - -Here is the full list of configuration parameters. - -================ ====== ======= ======== -Name Type Default Required -================ ====== ======= ======== -db-uri String Y -db-schema String Y -db-anon-role String Y -db-pool Int 10 -server-host String \*4 -server-port Int 3000 -server-proxy-uri String -jwt-secret String -secret-is-base64 Bool False -max-rows Int ∞ -pre-request String -================ ====== ======= ======== - -db-uri - The standard connection PostgreSQL `URI format `_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. Also allows connections over Unix sockets for higher performance. -db-schema - The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints. -db-anon-role - The database role to use when executing commands on behalf of unauthenticated clients. -db-pool - Number of connections to keep open in PostgREST's database pool. Having enough here for the maximum expected simultaneous client connections can improve performance. Note it's pointless to set this higher than the :code:`max_connections` GUC in your database. -server-host - Where to bind the PostgREST web server. -server-port - The port to bind the web server. -server-proxy-uri - Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com` - -.. code:: json - - { - "swagger": "2.0", - "info": { - "version": "0.4.0.0", - "title": "PostgREST API", - "description": "This is a dynamic API generated by PostgREST" - }, - "host": "postgrest.com:443", - "basePath": "/", - "schemes": [ - "https" - ] - } - -jwt-secret - The secret used to decode JWT tokens clients provide for authentication. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. -secret-is-base64 - When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret. -max-rows - A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests. -pre-request - A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing. - -Running the Server ------------------- - -PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a logfile or to the syslog: - -.. code-block:: bash - - ssh foo@example.com \ - 'postgrest foo.conf /var/log/postgrest.log 2>&1 &' - - # another option is to pipe the output into "logger -t postgrest" - -(Avoid :code:`nohup postgrest` because the HUP signal is used for manual :ref:`schema_reloading`.) - Hardening PostgREST =================== diff --git a/conf.py b/conf.py index 415ce36c2..394a14584 100644 --- a/conf.py +++ b/conf.py @@ -54,9 +54,9 @@ author = u'Joe Nelson' # built documents. # # The short X.Y version. -version = u'4.1' +version = u'4.3' # The full version, including alpha/beta/rc tags. -release = u'4.1.0' +release = u'4.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/install.rst b/install.rst index 7594ebc30..979dc3c1e 100644 --- a/install.rst +++ b/install.rst @@ -34,6 +34,116 @@ To use PostgREST you will need an underlying database (PostgreSQL version 9.5 or * `Instructions for Ubuntu 14.04 `_ * `Installer for Windows `_ +.. _configuration: + +Configuration +============= + +The PostgREST server reads a configuration file to determine information about the database and how to serve client requests. There is no predefined location for this file, you must specify the file path as the one and only argument to the server: + +.. code:: bash + + postgrest /path/to/postgrest.conf + +The file must contain a set of key value pairs. At minimum you must include these keys: + +.. code:: + + # postgrest.conf + + # The standard connection URI format, documented at + # https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347 + db-uri = "postgres://user:pass@host:5432/dbname" + + # The name of which database schema to expose to REST clients + db-schema = "api" + + # The database role to use when no client authentication is provided. + # Can (and probably should) differ from user in db-uri + db-anon-role = "anon" + +The user specified in the db-uri is also known as the authenticator role. For more information about the anonymous vs authenticator roles see the :ref:`roles`. + +Here is the full list of configuration parameters. + +================ ====== ======= ======== +Name Type Default Required +================ ====== ======= ======== +db-uri String Y +db-schema String Y +db-anon-role String Y +db-pool Int 10 +server-host String \*4 +server-port Int 3000 +server-proxy-uri String +jwt-secret String +secret-is-base64 Bool False +max-rows Int ∞ +pre-request String +================ ====== ======= ======== + +db-uri + The standard connection PostgreSQL `URI format `_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. Also allows connections over Unix sockets for higher performance. +db-schema + The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints. +db-anon-role + The database role to use when executing commands on behalf of unauthenticated clients. +db-pool + Number of connections to keep open in PostgREST's database pool. Having enough here for the maximum expected simultaneous client connections can improve performance. Note it's pointless to set this higher than the :code:`max_connections` GUC in your database. +server-host + Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings: + + * :code:`*` - any IPv4 or IPv6 hostname + * :code:`*4` - any IPv4 or IPv6 hostname, IPv4 preferred + * :code:`!4` - any IPv4 hostname + * :code:`*6` - any IPv4 or IPv6 hostname, IPv6 preferred + * :code:`!6` - any IPv6 hostname + +server-port + The port to bind the web server. +server-proxy-uri + Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com` + +.. code:: json + + { + "swagger": "2.0", + "info": { + "version": "0.4.3.0", + "title": "PostgREST API", + "description": "This is a dynamic API generated by PostgREST" + }, + "host": "postgrest.com:443", + "basePath": "/", + "schemes": [ + "https" + ] + } + +jwt-secret + The secret used to decode JWT tokens clients provide for authentication. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. +secret-is-base64 + When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret. +max-rows + A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests. +pre-request + A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing. + +Running the Server +------------------ + +PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a logfile or to the syslog: + +.. code-block:: bash + + ssh foo@example.com \ + 'postgrest foo.conf /var/log/postgrest.log 2>&1 &' + + # another option is to pipe the output into "logger -t postgrest" + +(Avoid :code:`nohup postgrest` because the HUP signal is used for manual :ref:`schema_reloading`.) + + Docker ======