Clean up some config docs formatting

Previously, we could get quoted sections that we didn't intend.

Change-Id: I82d687390da13df85910dda0d3fc536c018c596a
This commit is contained in:
Tim Burke 2018-11-19 17:50:39 -08:00
parent 503e9b904f
commit a63406d89c
4 changed files with 146 additions and 147 deletions

View File

@ -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.

View File

@ -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``

View File

@ -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

View File

@ -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