website: more getting started

website/source/intro/getting-started/first-secret.html.md

@@ -0,0 +1,110 @@
+---
+layout: "intro"
+page_title: "Your First Secret"
+sidebar_current: "gettingstarted-firstsecret"
+description: |-
+  With the Vault server running, let's read and write our first secret.
+---
+
+# Your First Secret
+
+Now that the dev server is up and running, let's get straight to it and
+read and write our first secret.
+
+One of the core features of Vault is the ability to read and write
+arbitrary secrets securely. On this page, we'll do this using the CLI,
+but there is also a complete
+[HTTP API](#)
+that can be used to programmatically do anything with Vault.
+
+Secrets written to Vault are encrypted and then written to the backend
+storage. For our dev server, backend storage is in-memory, but in production
+this would more likely be on disk or in [Consul](https://www.consul.io).
+Vault encrypts the value before it is ever handed to the storage driver.
+The backend storage mechanism _never_ sees the unencrypted value and doesn't
+have the means necessary to decrypt it without Vault.
+
+## Writing a Secret
+
+Let's start by writing a secret. This is done very simply with the
+`vault write` command, as shown below:
+
+```
+$ vault write secret/hello value=world
+Success! Data written to: secret/hello
+```
+
+This writes the pair `value=world` to the path `secret/hello`. We'll
+cover paths in more detail later, but for now it is important that the
+path is prefixed with `secret/`, otherwise this example won't work. The
+`secret/` prefix is where arbitrary secrets can be read and written.
+
+You can even write multiple pieces of data, if you want:
+
+```
+$ vault write secret/hello value=world excited=yes
+Success! Data written to: secret/hello
+```
+
+`vault write` is a very powerful command. In addition to writing data
+directly from the command-line, it can read values and keypairs from
+stdin as well as files. For more information, see the
+[vault write documentation](#).
+
+## Reading a Secret
+
+As you might expect, secrets can be read with `vault read`:
+
+```
+$ vault read secret/hello
+Key     	Value
+excited 	yes
+value   	world
+```
+
+As you can see, the values we wrote are given back to us. Vault read
+the data from storage and decrypted it.
+The output format is purposefully whitespace separated to make it easy
+to pipe into a tool like `awk`.
+
+In addition to the tabular format, if you're working with machines or
+a tool like `jq`, you can output the data in JSON format:
+
+```
+$ vault read -format=json secret/hello
+{
+	"renewable": false,
+	"lease_duration": 2592000,
+	"data": {
+		"excited": "yes",
+		"value": "world"
+	}
+}
+```
+
+This contains some extra information, but you can see our data mirrored
+here as well. The JSON output is very useful for scripts. For example below
+we use the `jq` tool to extract the "excited" value:
+
+```
+$ vault read -format=json secret/hello | jq -r .data.excited
+yes
+```
+
+## Deleting a Secret
+
+Now that we've learned how to read and write a secret, let's go ahead
+and delete it. We can do this with `vault delete`:
+
+```
+$ vault delete secret/hello
+'secret/hello' successfully deleted.
+```
+
+## Next
+
+In this section we learned how to use the powerful CRUD features of
+Vault to store arbitrary secrets. On its own this is already a useful
+but basic feature.
+
+Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html).

website/source/intro/getting-started/secret-backends.html.md

@@ -0,0 +1,119 @@
+---
+layout: "intro"
+page_title: "Secret Backends"
+sidebar_current: "gettingstarted-secretbackends"
+description: |-
+  Secret backends are what create, read, update, and delete secrets.
+---
+
+# Secret Backends
+
+Previously, we saw how to read and write arbitrary secrets to Vault.
+To do this, we used the `secret/` prefix. This prefix specifies the
+_secret backend_ to use, and Vault defaults to mounting the _generic_
+backend to `secret/`. The generic backend reads and writes raw data to
+the backend storage.
+
+Vault supports other backends in addition to "generic", and this feature
+in particular is what makes Vault unique. For example, the "aws" backend
+generates AWS access keys dynamically, on demand. Another example --
+this time of a backend that doesn't yet exist -- is a backend that
+reads and writes data directly to an
+[HSM](http://en.wikipedia.org/wiki/Hardware_security_module).
+As Vault matures, more and more backends will be added.
+
+To represent backends, Vault behaves much like a filesystem: backends
+are _mounted_ at specific paths. For example, the "generic" backend is
+_mounted_ at the `secret/` prefix.
+
+On this page, we'll learn about the mount system and the operations
+that can be performed with them. We do this as prerequisite knowledge
+to the next page, where we'll create dynamic secrets.
+
+## Mount a Backend
+
+To start, let's mount another "generic" backend. Just like a normal
+filesystem, Vault can mount a backend multiple times at different
+mount points. This is useful if you want different access control policies
+(covered later) or configurations for different paths.
+
+To mount the backend:
+
+```
+$ vault mount generic
+Successfully mounted 'generic' at 'generic'!
+```
+
+By default, the mount point will be the same name as the backend. This
+is because 99% of the time, you don't want to customize this mount point.
+In this example, we mounted the "generic" backend at `generic/`.
+
+You can inspect mounts using `vault mounts`:
+
+```
+$ vault mounts
+Path      Type     Description
+generic/  generic
+secret/   generic  generic secret storage
+sys/      system   system endpoints used for control, policy and debugging
+```
+
+You can see the `generic/` path we just mounted, as well as the built-in
+secret path. You can also see the `sys/` path. We won't cover this in the
+getting started guide, but this mount point is used to interact with
+the Vault core system.
+
+Spend some time reading and writing secrets to the new mount point to
+convince yourself it works. As a bonus, write to the `secret/` endpoint
+and observe that those values unavailable via `generic/`: they share the
+same backend, but do not share any data. In addition to this, backends
+(of the same type or otherwise) _cannot_ access the data of other backends;
+they can only access data within their mount point.
+
+## Unmount a Backend
+
+Once you're sufficiently convinced mounts behave as you expect, you can
+unmount it. When a backend is unmounted, all of its secrets are revoked
+and its data is deleted. If either of these operations fail, the backend
+remains mounted.
+
+```
+$ vault unmount generic/
+Successfully unmounted 'generic/'!
+```
+
+In addition to unmounting, you can _remount_ a backend. Remounting a
+backend changes its mount point. This is still a disruptive command: the
+stored data is retained, but all secrets are revoked since secrets are
+closely tied to their mount paths.
+
+## What is a Secret Backend?
+
+Now that you've mounted and unmounted a backend, you might wonder:
+"what is a secret backend? what is the point of this mounting system?"
+
+Vault behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system).
+The read/write/delete operations are forwarded to the backend, and the
+backend can choose to react to these operations however it wishes.
+For example, the "generic" backend simply passes this through to the
+storage backend (after encrypting data first).
+
+However, the "aws" backend (which you'll see soon), will read/write IAM
+policies and access tokens. So, while you might do a `vault read aws/deploy`,
+this isn't readnig from any _physical_ path "aws/deploy". Instead, the AWS
+backend is dynamically generating an access key based on the "deploy" policy.
+
+This abstraction is incredibly powerful. It lets Vault interface directly
+with physical systems such as the backend as well as things such as SQL
+databases, HSMs, etc. But in addition to these physical systems, Vault
+can interact with more unique environments: AWS IAM, dynamic SQL user creation,
+etc. all using the same read/write interface.
+
+## Next
+
+You now know about secret backends and how to operate on the mount table.
+This is important knowledge to move forward and learn about other secret
+backends.
+
+Next, we'll use the
+[AWS backend to generate dynamic secrets](/intro/getting-started/dynamic-secrets.html).

website/source/layouts/intro.erb

@@ -46,6 +46,14 @@
 							<a href="/intro/getting-started/first-secret.html">Your First Secret</a>
 						</li>
 
+						<li<%= sidebar_current("gettingstarted-secretbackends") %>>
+							<a href="/intro/getting-started/secret-backends.html">Secret Backends</a>
+						</li>
+
+						<li<%= sidebar_current("gettingstarted-dynamicsecrets") %>>
+							<a href="/intro/getting-started/dynamic-secrets.html">Dynamic Secrets</a>
+						</li>
+
 						<li<%= sidebar_current("gettingstarted-nextsteps") %>>
 							<a href="/intro/getting-started/next-steps.html">Next Steps</a>
 						</li>