Infra
/
lemur
5
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #193 from kevgliss/docs 

Improving documentation layout
This commit is contained in:
kevgliss 2015-12-31 11:21:48 -08:00
parent a4bf847b56 967c7ded8d
commit d9fd952c03
12 changed files with 250 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
LICENSE
View File

@ -1,4 +1,3 @@
Apache License Apache License
Version 2.0, January 2004 Version 2.0, January 2004
http://www.apache.org/licenses/ http://www.apache.org/licenses/

223
docs/administration/index.rst → docs/administration.rst
View File

@ -24,7 +24,6 @@ Basic Configuration
LOG_FILE = "/logs/lemur/lemur-test.log" LOG_FILE = "/logs/lemur/lemur-test.log"
.. data:: debug .. data:: debug
:noindex: :noindex:
@ -34,7 +33,6 @@ Basic Configuration
debug = False debug = False
.. warning:: .. warning::
This should never be used in a production environment as it exposes Lemur to This should never be used in a production environment as it exposes Lemur to
remote code execution through the debug console. remote code execution through the debug console.
@ -176,12 +174,13 @@ Lemur supports sending certification expiration notifications through SES and SM
Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES` Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES`
.. note:: .. note::
If using STMP as your provider you will need to define additional configuration options as specified by Flask-Mail. If using SMP as your provider you will need to define additional configuration options as specified by Flask-Mail.
See: `Flask-Mail <https://pythonhosted.org/Flask-Mail>`_ See: `Flask-Mail <https://pythonhosted.org/Flask-Mail>`_
If you are using SES the email specified by the `LEMUR_MAIL` configuration will need to be verified by AWS before If you are using SES the email specified by the `LEMUR_MAIL` configuration will need to be verified by AWS before
you can send any mail. See: `Verifying Email Address in Amazon SES <http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html>`_ you can send any mail. See: `Verifying Email Address in Amazon SES <http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html>`_
.. data:: LEMUR_MAIL .. data:: LEMUR_MAIL
:noindex: :noindex:
@ -212,56 +211,8 @@ Lemur supports sending certification expiration notifications through SES and SM
LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2] LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2]
Authority Options Authentication Options
----------------- ----------------------
Authorities will each have their own configuration options. There is currently just one plugin bundled with Lemur,
Verisign/Symantec. Additional plugins may define additional options. Refer to the plugin's own documentation
for those plugins.
.. data:: VERISIGN_URL
:noindex:
This is the url for the Verisign API
.. data:: VERISIGN_PEM_PATH
:noindex:
This is the path to the mutual TLS certificate used for communicating with Verisign
.. data:: VERISIGN_FIRST_NAME
:noindex:
This is the first name to be used when requesting the certificate
.. data:: VERISIGN_LAST_NAME
:noindex:
This is the last name to be used when requesting the certificate
.. data:: VERISIGN_EMAIL
:noindex:
This is the email to be used when requesting the certificate
.. data:: VERISIGN_INTERMEDIATE
:noindex:
This is the intermediate to be used for your CA chain
.. data:: VERISIGN_ROOT
:noindex:
This is the root to be used for your CA chain
Authentication
--------------
Lemur currently supports Basic Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily. Lemur currently supports Basic Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily.
If you are not using an authentication provider you do not need to configure any of these options. If you are not using an authentication provider you do not need to configure any of these options.
@ -332,15 +283,67 @@ For more information about how to use social logins, see: `Satellizer <https://g
GOOGLE_SECRET = "somethingsecret" GOOGLE_SECRET = "somethingsecret"
AWS Plugin Configuration Plugin Specific Options
======================== -----------------------
Verisign Issuer Plugin
^^^^^^^^^^^^^^^^^^^^^^
Authorities will each have their own configuration options. There is currently just one plugin bundled with Lemur,
Verisign/Symantec. Additional plugins may define additional options. Refer to the plugin's own documentation
for those plugins.
.. data:: VERISIGN_URL
:noindex:
This is the url for the Verisign API
.. data:: VERISIGN_PEM_PATH
:noindex:
This is the path to the mutual TLS certificate used for communicating with Verisign
.. data:: VERISIGN_FIRST_NAME
:noindex:
This is the first name to be used when requesting the certificate
.. data:: VERISIGN_LAST_NAME
:noindex:
This is the last name to be used when requesting the certificate
.. data:: VERISIGN_EMAIL
:noindex:
This is the email to be used when requesting the certificate
.. data:: VERISIGN_INTERMEDIATE
:noindex:
This is the intermediate to be used for your CA chain
.. data:: VERISIGN_ROOT
:noindex:
This is the root to be used for your CA chain
AWS Source/Destination Plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order for Lemur to manage its own account and other accounts we must ensure it has the correct AWS permissions. In order for Lemur to manage its own account and other accounts we must ensure it has the correct AWS permissions.
.. note:: AWS usage is completely optional. Lemur can upload, find and manage TLS certificates in AWS. But is not required to do so. .. note:: AWS usage is completely optional. Lemur can upload, find and manage TLS certificates in AWS. But is not required to do so.
Setting up IAM roles Setting up IAM roles
-------------------- """"""""""""""""""""
Lemur's AWS plugin uses boto heavily to talk to all the AWS resources it manages. By default it uses the on-instance credentials to make the necessary calls. Lemur's AWS plugin uses boto heavily to talk to all the AWS resources it manages. By default it uses the on-instance credentials to make the necessary calls.
@ -445,7 +448,8 @@ IAM-ServerCertificate
Setting up STS access Setting up STS access
--------------------- """""""""""""""""""""
Once we have setup our accounts we need to ensure that we create a trust relationship so that LemurInstanceProfile can assume the Lemur role. Once we have setup our accounts we need to ensure that we create a trust relationship so that LemurInstanceProfile can assume the Lemur role.
In the AWS console select the Lemur IAM role and select the Trust Relationships tab and click Edit Trust Relationship In the AWS console select the Lemur IAM role and select the Trust Relationships tab and click Edit Trust Relationship
@ -472,7 +476,7 @@ Below is an example policy:
Adding N+1 accounts Adding N+1 accounts
------------------- """""""""""""""""""
To add another account we go to the new account and create a new Lemur IAM role with the same policy as above. To add another account we go to the new account and create a new Lemur IAM role with the same policy as above.
@ -500,7 +504,7 @@ An example policy:
} }
Setting up SES Setting up SES
-------------- """"""""""""""
Lemur has built in support for sending it's certificate notifications via Amazon's simple email service (SES). To force Lemur has built in support for sending it's certificate notifications via Amazon's simple email service (SES). To force
Lemur to use SES ensure you are the running as the IAM role defined above and that you have followed the steps outlined Lemur to use SES ensure you are the running as the IAM role defined above and that you have followed the steps outlined
@ -515,23 +519,6 @@ Will be the sender of all notifications, so ensure that it is verified with AWS.
SES if the default notification gateway and will be used unless SMTP settings are configured in the application configuration SES if the default notification gateway and will be used unless SMTP settings are configured in the application configuration
settings. settings.
Upgrading Lemur
===============
Lemur provides an easy way to upgrade between versions. Simply download the newest
version of Lemur from pypi and then apply any schema changes with the following command.
.. code-block:: bash
$ lemur db upgrade
.. note:: Internally, this uses `Alembic <https://alembic.readthedocs.org/en/latest/>`_ to manage database migrations.
.. note:: By default Alembic looks for the `migrations` folder in the current working directory.
The migrations folder is located under `<LEMUR_HOME>/lemur/migrations` if you are running the lemur command from any
location besides `<LEMUR_HOME>/lemur` you will need to pass the `-d` flag to specify the absolute file path to the
`migrations` folder.
.. _CommandLineInterface: .. _CommandLineInterface:
Command Line Interface Command Line Interface
@ -641,32 +628,6 @@ and to get help on sub-commands
lemur certificates --help lemur certificates --help
Identity and Access Management
==============================
Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a
user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created
depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special
meaning.
Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such
as ViewPrivateKeyPermission are compositions of these three main Permissions.
Lets take a look at how these permissions are used:
Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles
that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`.
This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission
structure is setup such that if the user is a `Creator` or `Owner` of a given certificate they are allow to view that
private key. Owners can also be a role name, such that any user with the same role as owner will be allowed to view the
private key information.
These permissions are applied to the user upon login and refreshed on every request.
.. seealso::
`Flask-Principal <https://pythonhosted.org/Flask-Principal>`_
Upgrading Lemur Upgrading Lemur
=============== ===============
@ -697,3 +658,61 @@ After you have the latest version of the Lemur code base you must run any needed
This will ensure that any needed tables or columns are created or destroyed. This will ensure that any needed tables or columns are created or destroyed.
.. note::
Internally, this uses `Alembic <https://alembic.readthedocs.org/en/latest/>`_ to manage database migrations.
.. note::
By default Alembic looks for the `migrations` folder in the current working directory.The migrations folder is
located under `<LEMUR_HOME>/lemur/migrations` if you are running the lemur command from any location besides
`<LEMUR_HOME>/lemur` you will need to pass the `-d` flag to specify the absolute file path to the `migrations` folder.
Plugins
=======
There are several interfaces currently available to extend Lemur. These are a work in
progress and the API is not frozen.
Bundled Plugins
---------------
Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services.
3rd Party Extensions
--------------------
The following extensions are available and maintained by members of the Lemur community:
Have an extension that should be listed here? Submit a `pull request <https://github.com/netflix/lemur>`_ and we'll
get it added.
Want to create your own extension? See :doc:`../developer/plugins/index` to get started.
Identity and Access Management
==============================
Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a
user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created
depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special
meaning.
Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such
as ViewPrivateKeyPermission are compositions of these three main Permissions.
Lets take a look at how these permissions are used:
Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles
that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`.
This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission
structure is setup such that if the user is a `Creator` or `Owner` of a given certificate they are allow to view that
private key. Owners can also be a role name, such that any user with the same role as owner will be allowed to view the
private key information.
These permissions are applied to the user upon login and refreshed on every request.
.. seealso::
`Flask-Principal <https://pythonhosted.org/Flask-Principal>`_

10
docs/conf.py
View File

@ -101,9 +101,13 @@ pygments_style = 'sphinx'
# -- Options for HTML output ---------------------------------------------- # -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
# a list of builtin themes. on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
html_theme = 'default'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme # Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the

81
docs/developer/index.rst
View File

@ -180,19 +180,92 @@ You can see a list of open pull requests (pending changes) by visiting https://g
Pull requests should be against **master** and pass all TravisCI checks Pull requests should be against **master** and pass all TravisCI checks
Plugins
======= Writing a Plugin
================
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
plugins/index plugins/index
REST API
========
Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the
UI. The following is documents and provides examples on how to make requests to the Lemur API.
Authentication
--------------
.. automodule:: lemur.auth.views
:members:
:undoc-members:
:show-inheritance:
Destinations
------------
.. automodule:: lemur.destinations.views
:members:
:undoc-members:
:show-inheritance:
Notifications
-------------
.. automodule:: lemur.notifications.views
:members:
:undoc-members:
:show-inheritance:
Users
-----
.. automodule:: lemur.users.views
:members:
:undoc-members:
:show-inheritance:
Roles
-----
.. automodule:: lemur.roles.views
:members:
:undoc-members:
:show-inheritance:
Certificates
------------
.. automodule:: lemur.certificates.views
:members:
:undoc-members:
:show-inheritance:
Authorities
-----------
.. automodule:: lemur.authorities.views
:members:
:undoc-members:
:show-inheritance:
Domains
-------
.. automodule:: lemur.domains.views
:members:
:undoc-members:
:show-inheritance:
Internals Internals
========= =========
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
internals/lemur internals/lemur

1
docs/developer/internals/lemur.plugins.rst
View File

@ -27,6 +27,5 @@ Subpackages
lemur.plugins.base lemur.plugins.base
lemur.plugins.bases lemur.plugins.bases
lemur.plugins.lemur_aws lemur.plugins.lemur_aws
lemur.plugins.lemur_cloudca
lemur.plugins.lemur_email lemur.plugins.lemur_email
lemur.plugins.lemur_verisign lemur.plugins.lemur_verisign

1
docs/developer/internals/lemur.rst
View File

@ -96,5 +96,4 @@ Subpackages
lemur.notifications lemur.notifications
lemur.plugins lemur.plugins
lemur.roles lemur.roles
lemur.status
lemur.users lemur.users

11
docs/developer/internals/lemur.status.rst
View File

@ -1,11 +0,0 @@
status Package
==============
:mod:`views` Module
-------------------
.. automodule:: lemur.status.views
:noindex:
:members:
:undoc-members:
:show-inheritance:

3
docs/developer/plugins/index.rst
View File

@ -1,6 +1,3 @@
Writing a Plugin
================
Several interfaces exist for extending Lemur: Several interfaces exist for extending Lemur:
* Issuer (lemur.plugins.base.issuer) * Issuer (lemur.plugins.base.issuer)

66
docs/developer/rest.rst
View File

@ -1,66 +0,0 @@
Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the
UI. The following is documents and provides examples on how to make requests to the Lemur API.
Authentication
--------------
.. automodule:: lemur.auth.views
:members:
:undoc-members:
:show-inheritance:
Destinations
------------
.. automodule:: lemur.destinations.views
:members:
:undoc-members:
:show-inheritance:
Notifications
-------------
.. automodule:: lemur.notifications.views
:members:
:undoc-members:
:show-inheritance:
Users
-----
.. automodule:: lemur.users.views
:members:
:undoc-members:
:show-inheritance:
Roles
-----
.. automodule:: lemur.roles.views
:members:
:undoc-members:
:show-inheritance:
Certificates
------------
.. automodule:: lemur.certificates.views
:members:
:undoc-members:
:show-inheritance:
Authorities
-----------
.. automodule:: lemur.authorities.views
:members:
:undoc-members:
:show-inheritance:
Domains
-------
.. automodule:: lemur.domains.views
:members:
:undoc-members:
:show-inheritance:

16
docs/index.rst
View File

@ -27,8 +27,7 @@ Administration
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
administration/index administration
plugins/index
Developers Developers
---------- ----------
@ -38,14 +37,21 @@ Developers
developer/index developer/index
Security
REST API
-------- --------
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
developer/rest security
Doing a Release
---------------
.. toctree::
:maxdepth: 1
doing-a-release
FAQ FAQ
---- ----

20
docs/plugins/index.rst
View File

@ -1,20 +0,0 @@
Plugins
=======
There are several interfaces currently available to extend Lemur. These are a work in
progress and the API is not frozen.
Bundled Plugins
---------------
Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services.
3rd Party Extensions
--------------------
The following extensions are available and maintained by members of the Lemur community:
Have an extension that should be listed here? Submit a `pull request <https://github.com/netflix/lemur>`_ and we'll
get it added.
Want to create your own extension? See :doc:`../developer/plugins/index` to get started.

4
lemur/authorities/service.py
View File

@ -28,7 +28,6 @@ def update(authority_id, description=None, owner=None, active=None, roles=None):
:param authority_id: :param authority_id:
:param roles: roles that are allowed to use this authority :param roles: roles that are allowed to use this authority
:rtype : Authority
:return: :return:
""" """
authority = get(authority_id) authority = get(authority_id)
@ -47,7 +46,6 @@ def create(kwargs):
""" """
Create a new authority. Create a new authority.
:rtype : Authority
:return: :return:
""" """
@ -123,7 +121,6 @@ def get(authority_id):
""" """
Retrieves an authority given it's ID Retrieves an authority given it's ID
:rtype : Authority
:param authority_id: :param authority_id:
:return: :return:
""" """
@ -135,7 +132,6 @@ def get_by_name(authority_name):
Retrieves an authority given it's name. Retrieves an authority given it's name.
:param authority_name: :param authority_name:
:rtype : Authority
:return: :return:
""" """
return database.get(Authority, authority_name, field='name') return database.get(Authority, authority_name, field='name')