From 16c469d9b2849c3969f1ff1382a75007f16d7767 Mon Sep 17 00:00:00 2001 From: jrconlin Date: Tue, 9 Aug 2016 15:17:49 -0700 Subject: [PATCH] feature: better documentation for config files & locations Add documentation about the value of the configuration files and where they can be located on the system. Closes #572 --- autopush/main.py | 9 ++- configs/autopush_connection.ini | 47 ------------ configs/autopush_endpoint.ini | 50 ------------- configs/autopush_shared.ini | 125 -------------------------------- docs/install.rst | 52 +++++++++++++ 5 files changed, 59 insertions(+), 224 deletions(-) delete mode 100644 configs/autopush_connection.ini delete mode 100644 configs/autopush_endpoint.ini delete mode 100644 configs/autopush_shared.ini diff --git a/autopush/main.py b/autopush/main.py index eab38080..8db6d29c 100644 --- a/autopush/main.py +++ b/autopush/main.py @@ -36,6 +36,7 @@ shared_config_files = [ '/etc/autopush_shared.ini', + 'configs/autopush_shared.ini', '~/.autopush_shared.ini', '.autopush_shared.ini', ] @@ -217,6 +218,7 @@ def _parse_connection(sysargs, use_files=True): if use_files: # pragma: nocover config_files = shared_config_files + [ # pragma: nocover '/etc/autopush_connection.ini', + 'configs/autopush_connection.ini', '~/.autopush_connection.ini', '.autopush_connection.ini' ] @@ -224,7 +226,8 @@ def _parse_connection(sysargs, use_files=True): config_files = [] # pragma: nocover parser = configargparse.ArgumentParser( description='Runs a Connection Node.', - default_config_files=config_files) + default_config_files=config_files, + ) parser.add_argument('--config-connection', help="Connection node configuration file path", dest='config_file', is_config_file=True) @@ -271,6 +274,7 @@ def _parse_endpoint(sysargs, use_files=True): if use_files: # pragma: nocover config_files = shared_config_files + [ '/etc/autopush_endpoint.ini', + 'configs/autopush_endpoint.ini', '~/.autopush_endpoint.ini', '.autopush_endpoint.ini' ] @@ -278,7 +282,8 @@ def _parse_endpoint(sysargs, use_files=True): config_files = [] # pragma: nocover parser = configargparse.ArgumentParser( description='Runs an Endpoint Node.', - default_config_files=config_files) + default_config_files=config_files, + ) parser.add_argument('--config-endpoint', help="Endpoint node configuration file path", dest='config_file', is_config_file=True) diff --git a/configs/autopush_connection.ini b/configs/autopush_connection.ini deleted file mode 100644 index 9ad7ad3c..00000000 --- a/configs/autopush_connection.ini +++ /dev/null @@ -1,47 +0,0 @@ -; Connection node settings. -; -; Configuration names and values are the same as command line arguments -; e.g. --port=8082 would translate to a line containing -; port = 8082 -; -; Likewise, you can specify configuration options as environment variables: -; PORT=8082 bin/autopush -; -; Use bin/autopush --help for a list of options and values. -; -; The public connection node hostname. Defaults to the system hostname -; (`socket.gethostname()`) if unspecified. -; hostname = push.services.mozilla.com -; -; The port on which to listen for WebSocket connections. -port = 8080 - -; Settings for the internal routing listener, used to deliver routed -; notifications to clients connected to this node. The port should not -; be exposed externally. -; router_hostname = push.services.mozilla.com | ec2-internal-name -router_port = 8081 -; The TLS certificates if this node will be doing SSL termination. -#router_ssl_key = -#router_ssl_cert = -# If the router requires a specific DNS name that is different than -; what the host can self discover, set this value -#router_hostname = -#router_port = 8081 - -; Settings for the websocket ping. If a websocket ping fails or times out -; the connection is auto-closed. This is useful for detecting dead -; connections because various routers may artificially keep TCP connections -; alive. This is because the internet is full of lies. -; Set to 0 to disable websocket ping checks or timeouts. -; Default values are displayed. -#auto_ping_interval = 0 -#auto_ping_timeout = 4 - -; The maximum number of concurrent connections that the server should allow. -; (Set to "0" for unlimited.) -#max_connections = 0 - -; The client handshake timeout, in seconds. Clients that fail to send a -; handshake before the timeout will be disconnected. Set to 0 to disable. -hello_timeout = 0 diff --git a/configs/autopush_endpoint.ini b/configs/autopush_endpoint.ini deleted file mode 100644 index fbfd65ee..00000000 --- a/configs/autopush_endpoint.ini +++ /dev/null @@ -1,50 +0,0 @@ -; Endpoint node settings. -; -; Configuration names and values are the same as command line arguments -; e.g. --port=8082 would translate to a line containing -; port = 8082 -; -; Likewise, you can specify configuration options as environment variables: -; PORT=8082 bin/autoendpoint -; -; Use bin/autoendpoint --help for a list of options and values. -; -; -; The public endpoint node hostname. -; hostname = updates.push.services.mozilla.com - -; The port on which to listen for notifications from app servers. -port = 8082 - -; Uncomment to disable CORS for incoming notifications. -#no_cors - -; Uncomment to enable external routers (GCM, APNs, etc.) -#external_router - -; GCM requires a API Auth key. It is STRONGLY recommended you use one specific to this app. -#gcm_apikey = - -; Minimum GCM Time To Live value. Set this in case of excessive loss of -; TTL 0 messages across the GCM bridge -#gcm_ttl = 0 - -; AuthKey are the keys to use for Bearer Auth tokens. It uses the same -; autokey generator as the crypto_key argument, and sorted [newest, oldest] -#auth_key = [HJVPy4ZwF4Yz_JdvXTL8hRcwIhv742vC60Tg5Ycrvw8=] - -; S3 is used for some state and data storage for GCM senderIDs. -; You can specify the bucket name to use. Remember, use letters, numbers and -; "_" otherwise you will be sad. -#s3_bucket = oms_autopush - -; Seconds before servers will check S3 for GCM senderID changes. -#senderid_expry = 60*15 - -; Default hash of senderids and associated authorization keys. -; THIS WILL OVERWRITE ANY VALUES STORED IN S3! -; The list is specified as a JSON object formatted as: -; { :{"auth": }} -; e.g. -; {"12345": {"auth": "abcd_efg"}, "01357": {"auth": "ZYX=abc"}} -#senderid_list = diff --git a/configs/autopush_shared.ini b/configs/autopush_shared.ini deleted file mode 100644 index 0c4d8e85..00000000 --- a/configs/autopush_shared.ini +++ /dev/null @@ -1,125 +0,0 @@ -; Settings shared by the connection and endpoint nodes. - -; Uncomment to enable verbose logging for WebSocket connections and HTTP -; requests. This should be disabled in production. -#debug - -; TLS private key and certificate file paths, used for the main -; connection and endpoint listeners. If omitted, TLS will not be -; used. -#ssl_key = -#ssl_cert = - -; The push endpoint token encryption keys. Must be 32-byte, URL-safe -; Base64 encoded strings. Keys can be generated by running -; `pypy/bin/autokey`. This key should be identical for connection and -; endpoint nodes in the same cluster; otherwise, endpoints won't be -; able to decrypt tokens generated by the connection node. -; Keys should be sorted [newest,oldest] -crypto_key = [] - -; The key_hash is the key used to hash the UAID for storage. -; Note, changing this key WILL result in previously stored UAIDs becoming -; unreadable. Note: Multiple reads against DynamoDB is really not recommended -; unless you've recently hit the powerball and don't mind signing over your -; winnings to AWS. -#key_hash = - -; Hostname is the name to announce the server. This is useful if the local -; machine name is not the "official" service name. -; (e.g. push.services.mozilla.org) -#hostname = -; -; Uncomment to resolve the local IP address into a hostname if possible. -#resolve_hostname - -; If this host is terminating SSL/TLS connections, you will need to provide -; the appropriate certificates and keys. These are file paths. -#ssl_key = -#ssl_cert = -; Path to file containing any additional parameters for the Ephemeral -; Diffie-Hellman -#ssl_dh_param = - -; Datadog credentials. If a Datadog API key is specified, the statsd -; options will be ignored. Datadog is not required to run this server. -#datadog_api_key = -#datadog_app_key = -; -; The number of seconds to wait between flushes. -#datadog_flush_interval = 10 - -; statsd server options. -statsd_host = localhost -statsd_port = 8125 - -; The running environment autopush is in (e.g. "development", "staging", -; "production", etc.) -#env = development - -; Settings for the DynamoDB storage table, used to store notification -; versions for disconnected clients. If the table does not exist on -; startup, it will be created and provisioned with the given -; throughputs. -storage_tablename = storage -storage_read_throughput = 5 -storage_write_throughput = 5 - -; Settings for the DynamoDB routing table, used to track where each -; client is currently connected. -router_tablename = router -router_read_throughput = 5 -router_write_throughput = 5 - -; Settings for the DynamoDB message table, used to store encyrpted -; messages for offline users. -#message_tablename = message -#message_read_throughput = 5 -#message_write_throughput = 5 - -; The endpoint scheme, hostname and port, used to construct the push -; endpoint URL for each registered channel. Defaults to the system -; hostname. This should match the hostname and port from -; `autoendpoint_settings.py`. -endpoint_scheme = http -#endpoint_hostname = updates.push.services.mozilla.com -endpoint_port = 8082 - -; Uncomment to provide stdout logging in a more human readable format. -#human_logs - -## External Router Arguments -; autopush allows for bridges using external router systems such as Google -; Cloud Messaging (gcm), Apple Push Notification System (apns), or -; proprietary UDP systems. These optional arguments allow you to configure -; those bridges. -; -; Uncomment to enable the Google Cloud Messaging bridge support. -#gcm_enabled - -; Seconds before servers will check S3 for GCM senderID changes. -#senderid_expry = 60*15 - -; Default hash of senderids and associated authorization keys. -; THIS WILL OVERWRITE ANY VALUES STORED IN S3! -; The list is specified as a JSON object formatted as: -; { :{"auth": }} -; e.g. -; {"12345": {"auth": "abcd_efg"}, "01357": {"auth": "ZYX=abc"}} -#senderid_list = - -; FCM is the later version of GCM -#fcm_enabled -; The FCM router only allows one senderid/auth key due to restrictions on -; the client -#fcm_collapsekey = simplepush -#fcm_senderid = -#fcm_auth = -#fcm_dryrun - -; Perform AWS specific information (like fetch the AMI ID from the meta-data -; server -; -; Uncomment to disable AWS meta checks. -#no_aws - diff --git a/docs/install.rst b/docs/install.rst index 896e392d..cc12642c 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -56,6 +56,58 @@ to specify the ``-p `` option): Then run the Makefile with ``make`` to setup the application. +Configuration files +=================== + +Autopush can be configured in three ways; by option flags, by environment variables, +and by configuration files. autopush uses three configuration files. These files use +standard `ini` formatting similar to the following: + +.. code-block:: cfg + + # A comment description + ;a_disabled_option + ;another_disabled_option=default_value + option=value + +Options can either have values or act as boolean flags. If the option is a flag +it is either True if enabled, or False if disabled. The configuration files are +usually richly commented, and you're encouraged to read them to learn how to +set up your installation of autopush. + +Please note: any line that does not begin with a `#` or `;` is considered an option +line. if an unexpected option is present in a configuration file, the application +will fail to start. + +Configuration files can be located in: + +* in the /etc/ directory + +* in the $HOME or current directory (prefixed by a period '.') + +* in the configs subdirectory + +The three configuration files are: + +* *autopush_connection.ini* - contains options for use by the websocket handler. + This file's path can be specifed by the ``--config-connection`` option. + +* *autopush_shared.ini* - contains options shared between the connection and + endpoint handler. This file's path can be specified by the ``--config-shared`` + option. + +* *autopush_endpoint.ini* - contains options for the HTTP handlers This file's + path can be specifed by the ``--config-endpoint`` option. + +For instance, if you wished to copy the sample `configs/autopush_connection.ini.sample` +file to `/usr/share/autopush/autopush_connection.ini`, you could then run + +.. code-block:: bash + + $ autopush --config-connection=/usr/share/autopush/autopush_connection.ini + +to have autopush load configuration information from that file. + Notes on OS X =============