From a63406d89c44842550bb45f04c701a9d9bf47a41 Mon Sep 17 00:00:00 2001 From: Tim Burke Date: Mon, 19 Nov 2018 17:50:39 -0800 Subject: [PATCH] Clean up some config docs formatting Previously, we could get quoted sections that we didn't intend. Change-Id: I82d687390da13df85910dda0d3fc536c018c596a --- doc/source/configuration/audit.rst | 10 +- doc/source/configuration/keystone.rst | 70 +++---- doc/source/configuration/noauth.rst | 18 +- doc/source/configuration/troubleshooting.rst | 195 +++++++++---------- 4 files changed, 146 insertions(+), 147 deletions(-) diff --git a/doc/source/configuration/audit.rst b/doc/source/configuration/audit.rst index d2e672931..c366106ca 100644 --- a/doc/source/configuration/audit.rst +++ b/doc/source/configuration/audit.rst @@ -57,11 +57,13 @@ Steps #. Edit ``/etc/barbican/barbican-api-paste.ini`` - Replace the /v1 app pipeline from ``barbican_api`` to - ``barbican-api-keystone-audit`` pipeline + Replace the /v1 app pipeline from ``barbican_api`` to + ``barbican-api-keystone-audit`` pipeline: - [pipeline:barbican-api-keystone-audit] pipeline = - authtoken context audit apiapp + .. code-block:: text + + [pipeline:barbican-api-keystone-audit] + pipeline = authtoken context audit apiapp #. Edit ``barbican.conf`` to update *notification_driver* value. diff --git a/doc/source/configuration/keystone.rst b/doc/source/configuration/keystone.rst index 7a7e4d82f..5df1edd61 100644 --- a/doc/source/configuration/keystone.rst +++ b/doc/source/configuration/keystone.rst @@ -9,9 +9,9 @@ where all services including Keystone and Barbican are from the same release. If you don't have an instance of Keystone available, you can use one of the following ways to setup your own. - #. `Simple Dockerized Keystone`_ - #. `Installing Keystone`_ - #. An OpenStack cloud with Keystone (Devstack in the simplest case) +#. `Simple Dockerized Keystone`_ +#. `Installing Keystone`_ +#. An OpenStack cloud with Keystone (Devstack in the simplest case) .. _Simple Dockerized Keystone: https://registry.hub.docker.com/u/ jmvrbanac/simple-keystone/ @@ -34,50 +34,50 @@ the get version call. necessary on barbican from OpenStack Newton or higher, since barbican will default to using Keystone authentication as of OpenStack Newton. - .. code-block:: ini + .. code-block:: ini - [composite:main] - use = egg:Paste#urlmap - /: barbican_version - /v1: barbican-api-keystone + [composite:main] + use = egg:Paste#urlmap + /: barbican_version + /v1: barbican-api-keystone 2. Replace ``authtoken`` filter values to match your Keystone setup - .. code-block:: ini + .. code-block:: ini - [filter:authtoken] - paste.filter_factory = keystonemiddleware.auth_token:filter_factory - auth_plugin = password - username = {YOUR_KEYSTONE_USERNAME} - password = {YOUR_KEYSTONE_PASSWORD} - user_domain_id = {YOUR_KEYSTONE_USER_DOMAIN} - project_name = {YOUR_KEYSTONE_PROJECT} - project_domain_id = {YOUR_KEYSTONE_PROJECT_DOMAIN} - www_authenticate_uri = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 - auth_url = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 + [filter:authtoken] + paste.filter_factory = keystonemiddleware.auth_token:filter_factory + auth_plugin = password + username = {YOUR_KEYSTONE_USERNAME} + password = {YOUR_KEYSTONE_PASSWORD} + user_domain_id = {YOUR_KEYSTONE_USER_DOMAIN} + project_name = {YOUR_KEYSTONE_PROJECT} + project_domain_id = {YOUR_KEYSTONE_PROJECT_DOMAIN} + www_authenticate_uri = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 + auth_url = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 - Alternatively, you can shorten this to + Alternatively, you can shorten this to - .. code-block:: ini + .. code-block:: ini - [filter:authtoken] - paste.filter_factory = keystonemiddleware.auth_token:filter_factory + [filter:authtoken] + paste.filter_factory = keystonemiddleware.auth_token:filter_factory - and store Barbican's Keystone credentials in the ``[keystone_authtoken]`` - section of ``/etc/barbican/barbican.conf`` + and store Barbican's Keystone credentials in the ``[keystone_authtoken]`` + section of ``/etc/barbican/barbican.conf`` - .. code-block:: ini + .. code-block:: ini - [keystone_authtoken] - auth_plugin = password - username = {YOUR_KEYSTONE_USERNAME} - password = {YOUR_KEYSTONE_PASSWORD} - user_domain_id = {YOUR_KEYSTONE_USER_DOMAIN} - project_name = {YOUR_KEYSTONE_PROJECT} - project_domain_id = {YOUR_KEYSTONE_PROJECT_DOMAIN} - www_authenticate_uri = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 - auth_url = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 + [keystone_authtoken] + auth_plugin = password + username = {YOUR_KEYSTONE_USERNAME} + password = {YOUR_KEYSTONE_PASSWORD} + user_domain_id = {YOUR_KEYSTONE_USER_DOMAIN} + project_name = {YOUR_KEYSTONE_PROJECT} + project_domain_id = {YOUR_KEYSTONE_PROJECT_DOMAIN} + www_authenticate_uri = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 + auth_url = http://{YOUR_KEYSTONE_ENDPOINT}:5000/v3 3. Start Barbican ``{barbican_home}/bin/barbican.sh start`` diff --git a/doc/source/configuration/noauth.rst b/doc/source/configuration/noauth.rst index 6f9ceacf5..709589266 100644 --- a/doc/source/configuration/noauth.rst +++ b/doc/source/configuration/noauth.rst @@ -6,16 +6,16 @@ other OpenStack service for identity and access control. Nonetheless, sometimes it may be useful to run barbican without any authentication service for development purposes. -To this end, `barbican-api-paste.ini` contains a filter pipeline +To this end, ``barbican-api-paste.ini`` contains a filter pipeline without any authentication (no auth mode): .. code-block:: ini - # Use this pipeline for barbican API - DEFAULT no authentication - [pipeline:barbican_api] - pipeline = unauthenticated-context apiapp + # Use this pipeline for barbican API - DEFAULT no authentication + [pipeline:barbican_api] + pipeline = unauthenticated-context apiapp -To enable this pipe line proceed as follows: +To enable this pipeline proceed as follows: 1. Turn off any active instances of barbican @@ -26,10 +26,10 @@ To enable this pipe line proceed as follows: .. code-block:: ini - [composite:main] - use = egg:Paste#urlmap - /: barbican_version - /v1: barbican_api + [composite:main] + use = egg:Paste#urlmap + /: barbican_version + /v1: barbican_api With every OpenStack service integrated with keystone, its API requires access token to retireve certain information and validate user's information and diff --git a/doc/source/configuration/troubleshooting.rst b/doc/source/configuration/troubleshooting.rst index cf8b0e828..fdeca20eb 100644 --- a/doc/source/configuration/troubleshooting.rst +++ b/doc/source/configuration/troubleshooting.rst @@ -16,9 +16,9 @@ You get a HTTP 401 Unauthorized response even with a valid token .. code-block:: bash - curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-type: application/json" \ - -d '{"payload": "my-secret-here", "payload_content_type": "text/plain"}' \ - http://localhost:9311/v1/secrets + curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-type: application/json" \ + -d '{"payload": "my-secret-here", "payload_content_type": "text/plain"}' \ + http://localhost:9311/v1/secrets Caused by ^^^^^^^^^^ @@ -33,22 +33,22 @@ Check for an expired Keystone signing certificate on your Barbican server. Look at the expiration date in ``/tmp/barbican/cache/signing_cert.pem``. If it is expired then follow these steps. - #. On your Keystone server, verify that signing_cert.pem has the same - expiration date as the one on your Barbican machine. You can normally find - ``signing_cert.pem`` on your Keystone server in ``/etc/keystone/ssl/certs``. +#. On your Keystone server, verify that signing_cert.pem has the same + expiration date as the one on your Barbican machine. You can normally find + ``signing_cert.pem`` on your Keystone server in ``/etc/keystone/ssl/certs``. - #. If the cert matches then follow these steps to create a new one +#. If the cert matches then follow these steps to create a new one - #. Delete it from both your Barbican and Keystone servers. - #. Edit ``/etc/keystone/ssl/certs/index.txt.attr`` and set unique_subject - to no. - #. Run ``keystone-manage pki_setup`` to create a new ``signing_cert.pem`` - #. The updated cert will be downloaded to your Barbican server the next - time you hit the Barbican API. + #. Delete it from both your Barbican and Keystone servers. + #. Edit ``/etc/keystone/ssl/certs/index.txt.attr`` and set unique_subject + to no. + #. Run ``keystone-manage pki_setup`` to create a new ``signing_cert.pem`` + #. The updated cert will be downloaded to your Barbican server the next + time you hit the Barbican API. - #. If the cert **doesn't match** then delete the ``signing_cert.pem`` from - your Barbican server. Do not delete from Keystone. The cert from Keystone - will be downloaded to your machine the next time you hit the Barbican API. +#. If the cert **doesn't match** then delete the ``signing_cert.pem`` from + your Barbican server. Do not delete from Keystone. The cert from Keystone + will be downloaded to your machine the next time you hit the Barbican API. Returned refs use localhost instead of the correct hostname @@ -59,15 +59,14 @@ What you might see .. code-block:: bash - curl -X POST \ - -H "Content-type: application/json" -H "X-Auth-Token: $TOKEN" -d \ - '{"payload": "my-secret-here", "payload_content_type": "text/plain"}' \ - http://myhostname.com/v1/secrets + curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-type: application/json" \ + -d '{"payload": "my-secret-here", "payload_content_type": "text/plain"}' \ + http://myhostname.com/v1/secrets - # Response: - { - "secret_ref": "http://localhost:9311/v1/secrets/UUID_HERE" - } + # Response: + { + "secret_ref": "http://localhost:9311/v1/secrets/UUID_HERE" + } Caused by @@ -90,7 +89,9 @@ Barbican's tox tests fail to run on my Mac What you might see ^^^^^^^^^^^^^^^^^^^ -``clang: error: unknown argument: '-mno-fused-madd'`` +.. code-block:: text + + clang: error: unknown argument: '-mno-fused-madd' How to avoid ^^^^^^^^^^^^^ @@ -111,9 +112,9 @@ What you might see .. code-block:: text - c/_cffi_backend.c:13:10: fatal error: 'ffi.h' file not found - ... - ERROR: could not install deps [...]; v = InvocationError('...', 1) + c/_cffi_backend.c:13:10: fatal error: 'ffi.h' file not found + ... + ERROR: could not install deps [...]; v = InvocationError('...', 1) How to avoid ^^^^^^^^^^^^ @@ -133,7 +134,7 @@ What you might see .. code-block:: text - ImportError: No module named _bsddb + ImportError: No module named _bsddb How to avoid ^^^^^^^^^^^^ @@ -149,19 +150,19 @@ What you might see .. code-block:: text - ... - spawned uWSGI master process (pid: 59190) - spawned uWSGI worker 1 (pid: 59191, cores: 1) - spawned uWSGI worker 1 (pid: 59192, cores: 1) - Loading paste environment: config:/etc/barbican/barbican-api-paste.ini - WSGI app 0 (mountpoint='') ready in 0 seconds on interpreter \ - 0x7fd098c08520 pid: 59191 (default app) - OOPS ! failed loading app in worker 1 (pid 59192) :( trying again... - Respawned uWSGI worker 1 (new pid: 59193) - Loading paste environment: config:/etc/barbican/barbican-api-paste.ini - OOPS ! failed loading app in worker 1 (pid 59193) :( trying again... - worker respawning too fast !!! i have to sleep a bit (2 seconds)... - ... + ... + spawned uWSGI master process (pid: 59190) + spawned uWSGI worker 1 (pid: 59191, cores: 1) + spawned uWSGI worker 1 (pid: 59192, cores: 1) + Loading paste environment: config:/etc/barbican/barbican-api-paste.ini + WSGI app 0 (mountpoint='') ready in 0 seconds on interpreter \ + 0x7fd098c08520 pid: 59191 (default app) + OOPS ! failed loading app in worker 1 (pid 59192) :( trying again... + Respawned uWSGI worker 1 (new pid: 59193) + Loading paste environment: config:/etc/barbican/barbican-api-paste.ini + OOPS ! failed loading app in worker 1 (pid 59193) :( trying again... + worker respawning too fast !!! i have to sleep a bit (2 seconds)... + ... .. note:: You will not see any useful logs or stack traces with this error! @@ -187,10 +188,10 @@ What you might see .. code-block:: text - ... - File ".../oslo_config/cfg.py", line 1275, in register_cli_opt - raise ArgsAlreadyParsedError("cannot register CLI option") - ArgsAlreadyParsedError: arguments already parsed: cannot register CLI option + ... + File ".../oslo_config/cfg.py", line 1275, in register_cli_opt + raise ArgsAlreadyParsedError("cannot register CLI option") + ArgsAlreadyParsedError: arguments already parsed: cannot register CLI option Caused by @@ -211,18 +212,18 @@ logger, call ``from barbican.common import config`` with this to get a logger to use in your source file: ``LOG = config.getLogger(__name__)``. -Responder raised TypeError: 'NoneType' object has no attribute '__getitem__' ----------------------------------------------------------------------------- +Responder raised ``TypeError: 'NoneType' object has no attribute '__getitem__'`` +-------------------------------------------------------------------------------- What you might see ^^^^^^^^^^^^^^^^^^ .. code-block:: text - ... - 2013-04-14 14:17:56 [FALCON] [ERROR] POST \ - /da71dfbc-a959-4ad3-bdab-5ee190ce7515/csrs? => Responder raised \ - TypeError: 'NoneType' object has no attribute '__getitem__' + ... + 2013-04-14 14:17:56 [FALCON] [ERROR] POST \ + /da71dfbc-a959-4ad3-bdab-5ee190ce7515/csrs? => Responder raised \ + TypeError: 'NoneType' object has no attribute '__getitem__' Caused by @@ -247,11 +248,11 @@ What you might see .. code-block:: text - ... - uwsgi socket 0 bound to TCP address :9311 fd 3 - Python version: 2.7.3 (...) [...] - Set PythonHome to ./.venv - ImportError: No module named site + ... + uwsgi socket 0 bound to TCP address :9311 fd 3 + Python version: 2.7.3 (...) [...] + Set PythonHome to ./.venv + ImportError: No module named site Caused by @@ -278,9 +279,9 @@ What you might see .. code-block:: json - { - "title": "Malformed JSON" - } + { + "title": "Malformed JSON" + } Caused by @@ -315,8 +316,7 @@ A stack trace that has this in it (for example): .. code-block:: text - CryptoMimeTypeNotSupportedException: Crypto Mime Type of 'text/plain' not \ - supported + CryptoMimeTypeNotSupportedException: Crypto Mime Type of 'text/plain' not supported Caused by @@ -340,19 +340,17 @@ What you might see .. code-block:: text - *** has_emperor mode detected (fd: 6) *** - ... - !!! UNABLE to load uWSGI plugin: dlopen(./python_plugin.so, 10): image not \ - found !!! - ... - File "./site-packages/paste/deploy/loadwsgi.py", line 22, in import_string - return pkg_resources.EntryPoint.parse("x=" + s).load(False) - File "./site-packages/distribute-0.6.35-py2.7.egg/pkg_resources.py", line \ - 2015, in load - entry = __import__(self.module_name, globals(),globals(), ['__name__']) - ImportError: No module named barbican.api.app - ... - *** Starting uWSGI 1.9.13 (64bit) on [Fri Jul 5 09:59:29 2013] *** + *** has_emperor mode detected (fd: 6) *** + ... + !!! UNABLE to load uWSGI plugin: dlopen(./python_plugin.so, 10): image not found !!! + ... + File "./site-packages/paste/deploy/loadwsgi.py", line 22, in import_string + return pkg_resources.EntryPoint.parse("x=" + s).load(False) + File "./site-packages/distribute-0.6.35-py2.7.egg/pkg_resources.py", line 2015, in load + entry = __import__(self.module_name, globals(),globals(), ['__name__']) + ImportError: No module named barbican.api.app + ... + *** Starting uWSGI 1.9.13 (64bit) on [Fri Jul 5 09:59:29 2013] *** Caused by @@ -379,14 +377,14 @@ What you might see .. code-block:: text - ... - File "./site-packages/sqlalchemy/engine/strategies.py", line 80, in connect - return dialect.connect(*cargs, **cparams) - File "./site-packages/sqlalchemy/engine/default.py", line 283, in connect - return self.dbapi.connect(*cargs, **cparams) - OperationalError: (OperationalError) unable to open database file None None - [emperor] removed uwsgi instance barbican-api.ini - ... + ... + File "./site-packages/sqlalchemy/engine/strategies.py", line 80, in connect + return dialect.connect(*cargs, **cparams) + File "./site-packages/sqlalchemy/engine/default.py", line 283, in connect + return self.dbapi.connect(*cargs, **cparams) + OperationalError: (OperationalError) unable to open database file None None + [emperor] removed uwsgi instance barbican-api.ini + ... Caused by @@ -410,20 +408,20 @@ What you might see .. code-block:: text - ... - 2013-08-15 16:55:15.759 2445 DEBUG keystoneclient.middleware.auth_token \ - [-] Token validation failure. _validate_user_token \ - ./site-packages/keystoneclient/middleware/auth_token.py:711 - ... - 2013-08-15 16:55:15.759 2445 TRACE keystoneclient.middleware.auth_token \ - raise ValueError("No JSON object could be decoded") - 2013-08-15 16:55:15.759 24458 TRACE keystoneclient.middleware.auth_token \ - ValueError: No JSON object could be decoded - ... - 2013-08-15 16:55:15.766 2445 WARNING keystoneclient.middleware.auth_token \ - [-] Authorization failed for token ... - 2013-08-15 16:55:15.766 2445 INFO keystoneclient.middleware.auth_token \ - [-] Invalid user token - rejecting request... + ... + 2013-08-15 16:55:15.759 2445 DEBUG keystoneclient.middleware.auth_token \ + [-] Token validation failure. _validate_user_token \ + ./site-packages/keystoneclient/middleware/auth_token.py:711 + ... + 2013-08-15 16:55:15.759 2445 TRACE keystoneclient.middleware.auth_token \ + raise ValueError("No JSON object could be decoded") + 2013-08-15 16:55:15.759 24458 TRACE keystoneclient.middleware.auth_token \ + ValueError: No JSON object could be decoded + ... + 2013-08-15 16:55:15.766 2445 WARNING keystoneclient.middleware.auth_token \ + [-] Authorization failed for token ... + 2013-08-15 16:55:15.766 2445 INFO keystoneclient.middleware.auth_token \ + [-] Invalid user token - rejecting request... Caused by @@ -447,8 +445,7 @@ What you might see .. code-block:: text - Secret retrieval issue seen - accept-encoding of 'gzip,deflate,sdch' not \ - supported + Secret retrieval issue seen - accept-encoding of 'gzip,deflate,sdch' not supported Caused by