improving docs

This commit is contained in:
kevgliss 2015-09-14 13:46:39 -07:00
parent 6a1a744eff
commit 067122f8f4
13 changed files with 120 additions and 21 deletions

View File

@ -74,8 +74,6 @@ Basic Configuration
The TOKEN_SECRET is the secret used to create JWT tokens that are given out to users. This should be securely generated and be kept private. The TOKEN_SECRET is the secret used to create JWT tokens that are given out to users. This should be securely generated and be kept private.
See `SECRET_KEY` for methods on secure secret generation.
:: ::
LEMUR_TOKEN_SECRET = 'supersecret' LEMUR_TOKEN_SECRET = 'supersecret'
@ -122,7 +120,7 @@ and are used when Lemur creates the CSR for your certificates.
:: ::
LEMUR_DEFAULT_STATE = "CA" LEMUR_DEFAULT_STATE = "California"
.. data:: LEMUR_DEFAULT_LOCATION .. data:: LEMUR_DEFAULT_LOCATION
@ -152,15 +150,16 @@ and are used when Lemur creates the CSR for your certificates.
Notification Options Notification Options
-------------------- --------------------
Lemur currently has very basic support for notifications. Notifications are sent to the certificate creator, owner and Lemur currently has very basic support for notifications. Currently only expiration notifications are supported. Actual notification
security team as specified by the `SECURITY_TEAM_EMAIL` configuration parameter. is handling by the notification plugins that you have configured. Lemur ships with the 'Email' notification that allows expiration emails
to be sent to subscribers.
The template for all of these notifications lives under lemur/template/event.html and can be easily modified to fit your Templates for expiration emails are located under `lemur/plugins/lemur_email/templates` and can be modified for your needs.
needs. Notifications are sent to the certificate creator, owner and security team as specified by the `LEMUR_SECURITY_TEAM_EMAIL` configuration parameter.
Certificates marked as in-active will **not** be notified of upcoming expiration. This enables a user to essentially Certificates marked as in-active will **not** be notified of upcoming expiration. This enables a user to essentially
silence the expiration. If a certificate is active and is expiring the above will be notified at 30, 15, 5, 2 days silence the expiration. If a certificate is active and is expiring the above will be notified according to the `LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS` or
respectively. 30, 15, 2 days before expiration if no intervals are set.
Lemur supports sending certification expiration notifications through SES and SMTP. Lemur supports sending certification expiration notifications through SES and SMTP.
@ -197,6 +196,16 @@ Lemur supports sending certification expiration notifications through SES and SM
LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com'] LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com']
.. data:: LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS
:noindex:
Lemur notification intervals
::
LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2]
Authority Options Authority Options
----------------- -----------------
@ -309,9 +318,9 @@ In order for Lemur to manage it's own account and other accounts we must ensure
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.
In order to limit the permissions we will create a new two IAM roles for Lemur. You can name them whatever you would like but for example sake we will be calling them LemurInstanceProfile and Lemur. In order to limit the permissions, we will create two new IAM roles for Lemur. You can name them whatever you would like but for example sake we will be calling them LemurInstanceProfile and Lemur.
Lemur uses to STS to talk to different accounts. For managing one account this isn't necessary but we will still use it so that we can easily add new accounts. Lemur uses to STS to talk to different accounts. For managing one account this isn't necessary but we will still use it so that we can easily add new accounts.
@ -357,6 +366,11 @@ STS-AssumeRole
Next we will create the the Lemur IAM role. Lemur Next we will create the the Lemur IAM role. Lemur
..note::
The default IAM role that Lemur assumes into is called `Lemur`, if you need to change this ensure you set `LEMUR_INSTANCE_PROFILE` to your role name in the configuration.
Here is an example policy for Lemur: Here is an example policy for Lemur:
IAM-ServerCertificate IAM-ServerCertificate
@ -614,7 +628,8 @@ that the `Authority` is associated with it Lemur allows that user to user/view/u
This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission 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 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. 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. These permissions are applied to the user upon login and refreshed on every request.

View File

@ -215,7 +215,7 @@ certificate Lemur does not know about and adding the certificate to it's invento
The `SourcePlugin` object has one default option of `pollRate`. This controls the number of seconds which to get new certificates. The `SourcePlugin` object has one default option of `pollRate`. This controls the number of seconds which to get new certificates.
.. warning:: .. warning::
Lemur currently has a very basic polling system of running a cron job every 15min to see which source plugins need to be run. A lock file is generated to guarentee that ] Lemur currently has a very basic polling system of running a cron job every 15min to see which source plugins need to be run. A lock file is generated to guarantee that
only one sync is running at a time. It also means that the minimum resolution of a source plugin poll rate is effectively 15min. You can always specify a faster cron only one sync is running at a time. It also means that the minimum resolution of a source plugin poll rate is effectively 15min. You can always specify a faster cron
job if you need a higher resolution sync job. job if you need a higher resolution sync job.

Binary file not shown.

After

Width:  |  Height:  |  Size: 125 KiB

BIN
docs/guide/create.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

BIN
docs/guide/create_role.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/guide/create_user.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

View File

@ -1,14 +1,95 @@
Creating Users User Guide
============== ==========
These guides are quick tutorials on how to perform basic tasks in Lemur.
Create a New User
~~~~~~~~~~~~~~~~~
.. figure:: settings.png
From the settings dropdown select "Users"
.. figure:: create.png
In the user table select "Create"
.. figure:: create_user.png
Enter the username, email and password for the user. You can also assign any
roles that the user will need when they login. While there is no deletion
(we want to track creators forever) you can mark a user as 'Inactive' that will
not allow them to login to Lemur.
Creating Roles Create a New Role
============== ~~~~~~~~~~~~~~~~~
.. figure:: settings.png
From the settings dropdown select "Roles"
.. figure:: create.png
In the role table select "Create"
.. figure:: create_role.png
Enter a role name and short description about the role. You can optionally store
a user/password on the role. This is useful if your authority require specific roles.
You can then accurately map those roles onto Lemur users. Also optional you can assign
users to your new role.
Creating Authorities Create a New Authority
==================== ~~~~~~~~~~~~~~~~~~~~~~
.. figure:: create.png
In the authority table select "Create"
.. figure:: create_authority.png
Enter a authority name and short description about the authority. Enter an owner,
and certificate common name. Depending on the authority and the authority/issuer plugin
these values may or may not be used.
.. figure:: create_authority_options.png
Again how many of these values get used largely depends on the underlying plugin. It
is important to make sure you select the right plugin that you wish to use.
Creating Certificates Create a New Certificate
===================== ~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: create.png
In the certificate table select "Create"
.. figure:: create_certificate.png
Enter a owner, short description and the authority you wish to issue this certificate.
Enter a common name into the certificate, if no validity range is selected two years is
the default.
You can add notification options and upload the created certificate to a destination, both
of these are editable features and can be changed after the certificate has been created.
.. figure:: certificate_extensions.png
These options are typically for advanced users, the one exception is the `Subject Alternate Names` or SAN.
For certificates that need to include more than one domains, the first domain is the Common Name and all
other domains are added here as DNSName entries.
Import an Existing Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: upload_certificate.png
Enter a owner, short description and public certificate. If there are intermediates and private keys
Lemur will track them just as it does if the certificate were created through Lemur. Lemur generates
a certificate name but you can override that by passing a value to the `Custom Name` field.
You can add notification options and upload the created certificate to a destination, both
of these are editable features and can be changed after the certificate has been created.

BIN
docs/guide/settings.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

View File

@ -4,6 +4,8 @@ Quickstart
This guide will step you through setting up a Python-based virtualenv, installing the required packages, and configuring the basic web service. This guide will step you through setting up a Python-based virtualenv, installing the required packages, and configuring the basic web service.
This guide assumes a clean Ubuntu 14.04 instance, commands may differ based on the OS and configuration being used. This guide assumes a clean Ubuntu 14.04 instance, commands may differ based on the OS and configuration being used.
Pressed for time? See the Lemur docker file on `Github <https://github.com/Netflix/lemur-docker>`_.
Dependencies Dependencies
------------ ------------
@ -18,6 +20,7 @@ Some basic prerequisites which you'll need in order to run Lemur:
are largely handled for us. Lemur does **not** require AWS to function. Our guides and documentation try to be are largely handled for us. Lemur does **not** require AWS to function. Our guides and documentation try to be
be as generic as possible and are not intended to document every step of launching Lemur into a given environment. be as generic as possible and are not intended to document every step of launching Lemur into a given environment.
Setting up an Environment Setting up an Environment
------------------------- -------------------------