Re-categorized the guides on the navigation

website/source/guides/configuration/authentication.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "AppRole Pull Authentication - Guides"
-sidebar_current: "guides-authentication"
+sidebar_current: "guides-configuration-authentication"
 description: |-
   Authentication is a process in Vault by which user or machine-supplied
   information is verified to create a token with pre-configured policy.

website/source/guides/configuration/generate-root.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Generate Root Tokens using Unseal Keys - Guides"
-sidebar_current: "guides-generate-root"
+sidebar_current: "guides-configuration-generate-root"
 description: |-
   Generate a new root token using a threshold of unseal keys.
 ---

website/source/guides/configuration/index.html.md

@@ -0,0 +1,37 @@
+---
+layout: "guides"
+page_title: "Vault Configuration - Guides"
+sidebar_current: "guides-configuration"
+description: |-
+  Once a Vault instance has been installed, the next step is to configure auth
+  backend, secret backend, and manage keys. Vault configuration guides addresses
+  key concepts in configuring your Vault servers.   
+---
+
+# Vault Configuration
+
+This guide walks you through Vault configuration topics. Some guides address
+fundamental tasks to get the server setup, and some guides introduce more
+advanced discussions.
+
+- [Policies](/guides/configuration/policies.html) are used to instrument
+Role-Based Access Control (RBAC) by specifying access privileges. Authoring of
+policies is probably the first step the Vault administrator performs. This guide
+walks you through creating example policies for `admin` and `provisioner` users.
+- [AppRole Pull Authentication](/guides/configuration/authentication.html) guide
+is an introductory guide introduces the steps to generate tokens for machines
+or apps by enabling AppRole auth backend.
+- [Token and Leases](/guides/configuration/lease.html) guide helps you
+understand how tokens and leases work in Vault. The understanding of the
+lease hierarchy and expiration mechanism helps you plan for break glass
+procedures and more.
+- [Root Token Generation](/guides/configuration/generate-root.html) guide
+demonstrates the workflow of regenerating root tokens. It is considered to be a
+best practice not to persist the initial **root** token. If a root token needs
+to be regenerated, this guide helps you walk through the task.
+- [Rekeying & Rotating](/guides/configuration/rekeying-and-rotating.html) guide
+provides a high-level overview of Shamir's Secret Sharing Algorithm, and how to
+perform _rekey_ and _rotate_ operations in Vault.
+- [Building Plugin Backends](/guides/configuration/plugin-backends.html) guide
+provides steps to build, register, and mount non-database external plugin
+backends.

website/source/guides/configuration/lease.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Tokens and Leases - Guides"
-sidebar_current: "guides-lease"
+sidebar_current: "guides-configuration-lease"
 description: |-
   Tokens are the core method for authentication within Vault. For every
   authentication token and dynamic secret, Vault creates a lease

website/source/guides/configuration/plugin-backends.html.md

@@ -1,21 +1,21 @@
 ---
 layout: "guides"
 page_title: "Plugin Backends - Guides"
-sidebar_current: "guides-plugin-backends"
+sidebar_current: "guides-configuration-plugin-backends"
 description: |-
   Learn how to build, register, and mount a custom plugin backend.
 ---
 
 # Introduction
 
-Plugin backends utilize the [plugin system][plugin-system] to enable 
+Plugin backends utilize the [plugin system][plugin-system] to enable
-third-party secret and auth backends to be mounted. 
+third-party secret and auth backends to be mounted.
 
 It is worth noting that even though [database backends][database-backend]
 operate under the same underlying plugin mechanism, they are slightly different
-in design than plugin backends demonstrated in this guide. The database backend 
+in design than plugin backends demonstrated in this guide. The database backend
 manages multiple plugins under the same backend mount point, whereas plugin
-backends are generic backends that function as either secret or auth backends. 
+backends are generic backends that function as either secret or auth backends.
 
 This guide provides steps to build, register, and mount non-database external
 plugin backends.
@@ -35,7 +35,7 @@ plugin_directory="/etc/vault/vault_plugins"
 ## Build the Plugin Backend
 
 Build the custom backend binary, and move it to the `plugin_directory` path.
-In this guide, we will use `mock-plugin` that comes from Vault's 
+In this guide, we will use `mock-plugin` that comes from Vault's
 `logical/plugin/mock` package.
 
 ```

website/source/guides/configuration/policies.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Policies - Guides"
-sidebar_current: "guides-governance"
+sidebar_current: "guides-configuration-policies"
 description: |-
   Policies in Vault control what a user can access.
 ---
@@ -285,6 +285,12 @@ path "sys/auth/*"
   capabilities = ["create", "read", "update", "delete", "sudo"]
 }
 
+# List existing policies
+path "sys/policy"
+{
+  capabilities = ["read"]
+}
+
 # Create and manage ACL policies
 path "sys/policy/*"
 {

website/source/guides/configuration/rekeying-and-rotating.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Rekeying & Rotating Vault - Guides"
-sidebar_current: "guides-rekeying-and-rotating"
+sidebar_current: "guides-configuration-rekeying-and-rotating"
 description: |-
   Vault supports generating new unseal keys as well as rotating the underlying
   encryption keys. This guide covers rekeying and rotating Vault's encryption

website/source/guides/getting-started/index.html.md

@@ -0,0 +1,14 @@
+---
+layout: "guides"
+page_title: "Guides"
+sidebar_current: "getting-started"
+description: |-
+  This section takes you to the Getting Started section.
+---
+
+# Vault Getting Started
+
+Welcome to the Vault guides section! If you are just getting started with Vault,
+please start with the [Vault introduction](/intro/getting-started/install.html)
+instead and then continue on to the guides. The guides provide examples of
+common Vault workflows and actions for both beginner and advanced Vault users.

website/source/guides/operations/index.html.md

@@ -0,0 +1,23 @@
+---
+layout: "guides"
+page_title: "Vault Architecture - Guides"
+sidebar_current: "guides-operations"
+description: |-
+  Vault architecture guide covers Vault infrastructure discussions including
+  installation.   
+---
+
+# Vault Architecture
+
+Vault Architectures guides address Vault infrastructure discussions.  These
+guides are designed to help the operations team to plan and install a Vault
+cluster that meets your organization's needs.
+
+- [Production Hardening](/guides/architecture/production.html) guide provides
+guidance on best practices for a production hardened deployment of Vault.  
+The recommendations are based on the [security model](/docs/internals/security.html)
+and focus on defense in depth.
+- [Replication Setup & Guidance](/guides/architecture/replication.html)
+walks you through the commands to activate the Vault servers in replication mode.
+Please note that [Vault Replication](/docs/vault-enterprise/replication/index.html)
+is a Vault Enterprise feature.

website/source/guides/operations/production.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Production Hardening - Guides"
-sidebar_current: "guides-production-hardening"
+sidebar_current: "guides-operations-production-hardening"
 description: |-
   This guide provides guidance on best practices for a production hardened deployment of HashiCorp Vault.
 ---

website/source/guides/operations/replication.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Setting up Vault Enterprise Performance Replication - Guides"
-sidebar_current: "guides-replication"
+sidebar_current: "guides-operations-replication"
 description: |-
   Learn how to set up and manage Vault Enterprise Performance Replication.
 ---
@@ -177,6 +177,3 @@ mechanisms if DR is necessary in your implementation.
 
 If you need true DR, look at the
 [general information page](/docs/vault-enterprise/replication/index.html) for information on Vault's disaster recovery replication.
-
-
-

website/source/guides/secret-mgmt/cubbyhole.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Cubbyhole Response Wrapping - Guides"
-sidebar_current: "guides-cubbyhole"
+sidebar_current: "guides-secret-mgmt-cubbyhole"
 description: |-
   Vault provides a capability to wrap Vault response and store it in a
   "cubbyhole" where the holder of the one-time use wrapping token can unwrap to
@@ -35,7 +35,7 @@ long as its policy allows it.
 The end-to-end scenario described in this guide involves two personas:
 
 - **`admin`** with privileged permissions to create tokens
-- **`apps`** is the receiving client of a wrapped response
+- **`apps`** trusted entity retrieving secrets from Vault
 
 ## Challenge
 
@@ -43,7 +43,12 @@ In order to tightly manage the secrets, you set the scope of who can do what
 using the [Vault policy](/docs/concepts/policies.html) and attach that to
 tokens, roles, entities, etc.
 
-How to securely distribute a secret (e.g. token, credentials) to a machine or app?
+Think of a case where you have a trusted entity (Chef, Jenkins, etc.) which
+reads secrets from Vault. This trusted entity must obtain a token. If the
+trusted entity or its host machine was rebooted, it must re-authenticate with
+Vault using a valid token.
+
+How can you securely distribute the initial token to the trusted entity?
 
 ## Solution
 
@@ -81,6 +86,11 @@ path "auth/token/*" {
 path "sys/policy/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
 }
+
+# Manage secret/dev secret backend - for Verification test
+path "secret/dev" {
+  capabilities = [ "create", "read", "update", "delete", "list" ]
+}
 ```
 
 ## Steps
@@ -106,12 +116,19 @@ Secret](/guide/static-secrets.html) guide.
 ### <a name="step1"></a>Step 1: Create and wrap a token
 (**Persona:** admin)
 
+To solve the [challenge](#challenge) addressed in this guide:
+
+1. More privileged token (`admin`) wraps a secret only the expecting client can
+read
+2. The receiving client (`app`) unwraps the secret to obtain the token
+
 When the response to `vault token-create` request is wrapped, Vault inserts the
 generated token into the cubbyhole of a single-use token, returning that
 single-use wrapping token. Retrieving the secret requires an unwrap operation
 against this wrapping token.
 
-In this scenario, an [admin user](#personas) creates a token using response wrapping. To perform the steps in this guide, first create a policy for the app.
+In this scenario, an [admin user](#personas) creates a token using response
+wrapping. To perform the steps in this guide, first create a policy for the app.
 
 `apps-policy.hcl`:
 
@@ -142,16 +159,16 @@ duration of seconds (15s), minutes (20m), or hours (25h).
 
 **Example:**
 
-Generate a token for `apps` persona using response wrapping with TTL of 60
+Generate a token for `apps` persona using response wrapping with TTL of 120
 seconds.
 
 ```shell
-$ vault token-create -policy=apps -wrap-ttl=60s
+$ vault token-create -policy=apps -wrap-ttl=120
 
 Key                          	Value
 ---                          	-----
 wrapping_token:              	9ac59985-094f-a2de-aed8-bf688e436fbc
-wrapping_token_ttl:          	1m0s
+wrapping_token_ttl:          	2m0s
 wrapping_token_creation_time:	2018-01-10 00:47:54.970185208 +0000 UTC
 wrapping_token_creation_path:	auth/token/create
 wrapped_accessor:            	195763a9-3f26-1fcf-6a1a-ee0a11e76cb1
@@ -210,7 +227,7 @@ seconds (15s), minutes (20m), or hours (25h).
 To wrap the response of token-create request:
 
 ```shell
-$ curl --header "X-Vault-Wrap-TTL: 60s" \
+$ curl --header "X-Vault-Wrap-TTL: 120" \
        --header "X-Vault-Token: ..." \
        --request POST \
        --data '{"policies":["apps"]}' \
@@ -223,7 +240,7 @@ $ curl --header "X-Vault-Wrap-TTL: 60s" \
   "data": null,
   "wrap_info": {
     "token": "e095129f-123a-4fef-c007-1f6a487cfa78",
-    "ttl": 60,
+    "ttl": 120,
     "creation_time": "2018-01-10T01:43:38.025351336Z",
     "creation_path": "auth/token/create",
     "wrapped_accessor": "44e8253c-65b4-1690-1bf1-7902a7a6b2aa"
@@ -249,9 +266,47 @@ token and none arrives, this may be due to an attacker intercepting the token
 and then preventing it from traveling further. This should cause an alert to
 trigger an immediate investigation.
 
+The following tasks will be performed to demonstrate the client operations:
+
+1. Create a token with **`default`** policy
+2. Authenticate with Vault using this `default` token (less privileged token)
+3. Unwrap the secret to obtain more privileged token (**`apps`** persona token)
+4. Verify that you can read `secret/dev` using the `apps`token
+
+
 #### CLI command
 
-To unwrap the secret:
+First, create a token with `default` policy:
+
+```shell
+# Create a token with `default` policy
+$ vault token-create -policy=default
+Key            	Value
+---            	-----
+token          	4522b2e8-27fe-bdc5-b932-d982f3166c6c
+token_accessor 	96108f48-7475-6190-b058-769a2e5ebc8e
+token_duration 	768h0m0s
+token_renewable	true
+token_policies 	[default]
+
+# Authenticate using the generated token
+$ vault auth 4522b2e8-27fe-bdc5-b932-d982f3166c6c
+Successfully authenticated! You are now logged in.
+token: 4522b2e8-27fe-bdc5-b932-d982f3166c6c
+token_duration: 2764729
+token_policies: [default]
+
+# Verify that you do NOT have a permission to read secret/dev
+$ vault read secret/dev
+Error reading secret/dev: Error making API request.
+
+URL: GET http://<VAULT_ADDRESS>/v1/secret/dev
+Code: 403. Errors:
+
+* permission denied
+```
+
+The command to unwrap the wrapped secret is:
 
 ```shell
 $ vault unwrap <WRAPPING_TOKEN>
@@ -262,9 +317,6 @@ Or
 $ VAULT_TOKEN=<WRAPPING_TOKEN> vault unwrap
 ```
 
-In this scenario, the wrapped secret is a Vault token. Therefore, it probably
-makes better sense to use the second option.
-
 **Example:**
 
 ```shell
@@ -279,6 +331,8 @@ token_renewable	true
 token_policies 	[apps default]
 ```
 
+Verify that this token has `apps` policy attached.
+
 Once the client acquired the token, future requests can be made using this
 token.
 
@@ -291,7 +345,37 @@ No value found at secret/dev
 
 #### API call using cURL
 
-To unwrap the secret, use `/sys/wrapping/unwrap` endpoint:
+First, create a token with `default` policy:
+
+```shell
+# Create a new token default policy
+$ curl --header "X-Vault-Token: ..." --request POST \
+     --data '{"policies": "default"}' \
+     https://vault.rocks/v1/auth/token/create | jq
+{
+  ...
+  "auth": {
+    "client_token": "5fe14760-b0fd-22dc-403c-14a05003b67f",
+    "accessor": "e709610e-916e-f7e3-b93b-41f4dfdca7a0",
+    "policies": [
+      "default"
+    ],
+    ...
+ }
+}
+
+# Verify that you can NOT read secret/dev using default token
+$ curl --header "X-Vault-Token: 5fe14760-b0fd-22dc-403c-14a05003b67f" \
+       --request GET \
+       https://vault.rocks/v1/secret/dev | jq
+{
+ "errors": [
+   "permission denied"
+ ]
+}
+```
+
+Now, unwrap the secret using `/sys/wrapping/unwrap` endpoint:
 
 ```shell
 $ curl --header "X-Vault-Token: <WRAPPING_TOKEN>" \
@@ -339,6 +423,8 @@ $ curl --header "X-Vault-Token: af5f7682-aa55-fa37-5039-ee116df56600" \
 }
 ```
 
+Since there is no data in `secret/dev`, it returns an empty array.
+
 ## Additional Discussion
 
 The `cubbyhole` secret backend provides your own private secret storage space

website/source/guides/secret-mgmt/dynamic-secrets.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Secret as a Service - Guides"
-sidebar_current: "guides--dataynamic-secrets"
+sidebar_current: "guides-secret-mgmt-dataynamic-secrets"
 description: |-
   Vault can dynamically generate secrets on--dataemand for some systems.
 ---

website/source/guides/secret-mgmt/index.html.md

@@ -0,0 +1,31 @@
+---
+layout: "guides"
+page_title: "Secret Management - Guides"
+sidebar_current: "guides-secret-mgmt"
+description: |-
+   A very common use case of Vault is to manage your organization's secrets from
+   storing credentials and API keys to encrypting passwords for user signups.
+   Vault is meant to be a solution for all secret management needs.
+---
+
+# Secret Management
+
+Vault is a tool for securely accessing secrets. A secret is anything that you
+want to tightly control access to, such as API keys, passwords, certificates,
+and more. Vault provides a unified interface to any secret while providing
+tight access control and recording a detailed audit log.
+
+Secret Management guides demonstrate features in Vault to securely store your
+secrets.
+
+- [Static Secrets](/guides/secret-mgmt/static-secrets.html) guide walks you
+through the steps to write secrets in Vault, and control who can access them.
+
+- [Secret as a Service: Dynamic Secrets](/guides/secret-mgmt/dynamic-secrets.html)
+ guide demonstrates the Vault feature to generate database credentials
+ on-demand so that each application or system can obtain its own credentials,
+ and its permissions can be tightly controlled.
+
+- [Cubbyhole Response Wrapping](/guides/secret-mgmt/cubbyhole.html) guide
+demonstrates a secure method to distribute secrets by wrapping them where only
+the expecting client can unwrap.

website/source/guides/secret-mgmt/static-secrets.html.md

@@ -1,7 +1,7 @@
 ---
 layout: "guides"
 page_title: "Static Secrets - Guides"
-sidebar_current: "guides-static-secrets"
+sidebar_current: "guides-secret-mgmt-static-secrets"
 description: |-
   Vault supports generating new unseal keys as well as rotating the underlying
   encryption keys. This guide covers rekeying and rotating Vault's encryption

website/source/layouts/guides.erb

@@ -3,50 +3,59 @@
     <ul class="nav docs-sidenav">
 
 
-      <li<%= sidebar_current("guides-policy") %>>
+      <li<%= sidebar_current("getting-started")%>>
-        <a href="/guides/policies.html">Policies</a>
+        <a href="/guides/getting-started/index.html">Getting Started</a>
       </li>
 
-      <li<%= sidebar_current("guides-authentication") %>>
+      <li<%= sidebar_current("guides-operations")%>>
-        <a href="/guides/authentication.html">AppRole Pull Authentication</a>
+        <a href="/guides/operations/index.html">Vault Operations</a>
+        <ul class="nav">
+          <li<%= sidebar_current("guides-operations-production-hardening") %>>
+            <a href="/guides/operations/production.html">Production Hardening</a>
+          </li>
+          <li<%= sidebar_current("guides-operations-replication") %>>
+            <a href="/guides/operations/replication.html">Replication Setup &amp; Guidance</a>
+          </li>
+        </ul>
       </li>
 
-      <li<%= sidebar_current("guides-static-secrets") %>>
+      <li<%= sidebar_current("guides-configuration")%>>
-        <a href="/guides/static-secrets.html">Static Secrets</a>
+        <a href="/guides/configuration/index.html">Vault Configuration</a>
+        <ul class="nav">
+          <li<%= sidebar_current("guides-configuration-policies") %>>
+            <a href="/guides/configuration/policies.html">Policies</a>
+          </li>
+          <li<%= sidebar_current("guides-configuration-authentication") %>>
+            <a href="/guides/configuration/authentication.html">AppRole Pull Authentication</a>
+          </li>
+          <li<%= sidebar_current("guides-configuration-lease") %>>
+            <a href="/guides/configuration/lease.html">Tokens and Leases</a>
+          </li>
+          <li<%= sidebar_current("guides-configuration-generate-root") %>>
+            <a href="/guides/configuration/generate-root.html">Root Token Generation</a>
+          </li>
+          <li<%= sidebar_current("guides-configuration-rekeying-and-rotating") %>>
+            <a href="/guides/configuration/rekeying-and-rotating.html">Rekeying &amp; Rotating</a>
+          </li>
+          <li<%= sidebar_current("guides-configuration-plugin-backends") %>>
+            <a href="/guides/configuration/plugin-backends.html">Building Plugin Backends</a>
+          </li>
+        </ul>
       </li>
 
-      <li<%= sidebar_current("guides-dynamic-secrets") %>>
+      <li<%= sidebar_current("guides-secret-mgmt")%>>
-        <a href="/guides/dynamic-secrets.html">Secret as a Service</a>
+        <a href="/guides/secret-mgmt/index.html">Secret Management</a>
-      </li>
+        <ul class="nav">
-
+          <li<%= sidebar_current("guides-secret-mgmt-static-secrets") %>>
-      <li<%= sidebar_current("guides-lease") %>>
+            <a href="/guides/secret-mgmt/static-secrets.html">Static Secrets</a>
-        <a href="/guides/lease.html">Tokens and Leases</a>
+          </li>
-      </li>
+          <li<%= sidebar_current("guides-secret-mgmt-dataynamic-secrets") %>>
-
+            <a href="/guides/secret-mgmt/dynamic-secrets.html">Secret as a Service</a>
-      <li<%= sidebar_current("guides-cubbyhole") %>>
+          </li>
-        <a href="/guides/cubbyhole.html">Cubbyhole Response Wrapping</a>
+          <li<%= sidebar_current("guides-secret-mgmt-cubbyhole") %>>
-      </li>
+            <a href="/guides/secret-mgmt/cubbyhole.html">Cubbyhole Response Wrapping</a>
-
+          </li>
-
+        </ul>
-
-      <li<%= sidebar_current("guides-production-hardening") %>>
-        <a href="/guides/production.html">Production Hardening</a>
-      </li>
-
-      <li<%= sidebar_current("guides-generate-root") %>>
-        <a href="/guides/generate-root.html">Root Token Generation</a>
-      </li>
-
-      <li<%= sidebar_current("guides-rekeying-and-rotate") %>>
-        <a href="/guides/rekeying-and-rotating.html">Rekeying &amp; Rotating</a>
-      </li>
-
-      <li<%= sidebar_current("guides-replication") %>>
-        <a href="/guides/replication.html">Replication Setup &amp; Guidance</a>
-      </li>
-
-      <li<%= sidebar_current("guides-plugin-backends") %>>
-        <a href="/guides/plugin-backends.html">Building Plugin Backends</a>
       </li>
 
       <hr>