Improve documentation of token renewal

command/token_create.go

@@ -82,8 +82,9 @@ Usage: vault token-create [options]
   This token will be created as a child of your token. The created token
   will inherit your policies, or can be assigned a subset of your policies.
 
-  A lease can also be associated with the token. If a lease is associated,
-  it will expire after that amount of time unless it is renewed.
+  A lease can also be associated with the token. If a lease is not associated
+  with the token, then it cannot be renewed. And if a lease is associated with
+  the token, it will expire after that amount of time unless it is renewed.
 
   Metadata associated with the token (specified with "-metadata") is
   written to the audit log when the token is used.
@@ -103,7 +104,8 @@ Token Options:
                           is a non-security sensitive value used to help
                           identify created secrets, i.e. prefixes.
 
-  -lease="1h"             Lease to associate with the token.
+  -lease="1h"             Lease to associate with the token. This option enables
+                          the tokens to be renewable.
 
   -metadata="key=value"   Metadata to associate with the token. This shows
                           up in the audit log. This can be specified multiple

command/token_renew.go

@@ -58,7 +58,7 @@ func (c *TokenRenewCommand) Run(args []string) int {
 }
 
 func (c *TokenRenewCommand) Synopsis() string {
-	return "Renew an auth token"
+	return "Renew an auth token if there is an associated lease"
 }
 
 func (c *TokenRenewCommand) Help() string {
@@ -66,6 +66,7 @@ func (c *TokenRenewCommand) Help() string {
 Usage: vault token-renew [options] token [increment]
 
   Renew an auth token, extending the amount of time it can be used.
+  Token is renewable only if there is a lease associated with it.
 
   This command is similar to "renew", but "renew" is only for lease IDs.
   This command is only for tokens.

vault/token_store.go

@@ -558,6 +558,7 @@ func (ts *TokenStore) handleCreate(
 			LeaseOptions: logical.LeaseOptions{
 				TTL:         leaseDuration,
 				GracePeriod: leaseDuration / 10,
+				// Tokens are renewable only if user provides lease duration
 				Renewable: leaseDuration > 0,
 			},
 			ClientToken: te.ID,
@@ -698,7 +699,7 @@ const (
 	tokenBackendHelp = `The token credential backend is always enabled and builtin to Vault.
 Client tokens are used to identify a client and to allow Vault to associate policies and ACLs
 which are enforced on every request. This backend also allows for generating sub-tokens as well
-as revocation of tokens.`
+as revocation of tokens. The tokens are renewable if associated with a lease.`
 	tokenCreateHelp       = `The token create path is used to create new tokens.`
 	tokenLookupHelp       = `This endpoint will lookup a token and its properties.`
 	tokenRevokeHelp       = `This endpoint will delete the token and all of its child tokens.`

website/source/docs/auth/token.html.md

@@ -285,8 +285,9 @@ of the header should be "X-Vault-Token" and the value should be the token.
 <dl class="api">
   <dt>Description</dt>
   <dd>
-    Renews a lease associated with a token. This is used to prevent
-    the expiration of a token, and the automatic revocation of it.
+    Renews a lease associated with a token. This is used to prevent the
+    expiration of a token, and the automatic revocation of it. Token
+    renewal is possible only if there is a lease associated with it.
   </dd>
 
   <dt>Method</dt>

website/source/docs/concepts/auth.html.md

@@ -96,4 +96,4 @@ how leasing is implemented.
 
 And just like secrets, identities can be renewed without having to
 completely reauthenticate. Just use `vault token-renew <token>` with the
-token associated with your identity to renew it.
+leased token associated with your identity to renew it.

website/source/docs/concepts/tokens.html.md

@@ -49,8 +49,9 @@ the same way as [leases for secrets](/docs/concepts/lease.html). After
 the lease period is up, the token will no longer function. In addition
 to no longer functioning, Vault will revoke it.
 
-In order to avoid your token being revoked, the `vault token-renew`
-command should be used to renew the lease on the token periodically.
+If a lease is associated with the token, in order to avoid your token being
+revoked, the `vault token-renew` command should be periodically used to renew
+the lease.
 
 After a token is revoked, all of the secrets in use by that token will
 also be revoked. Therefore, if a user requests AWS access keys, for example,

website/source/intro/getting-started/install.html.md

@@ -60,6 +60,7 @@ All other commands:
     init             Initialize a new Vault server
     key-status       Provides information about the active encryption key
     mount            Mount a logical backend
+    mount-tune       Tune mount configuration parameters
     mounts           Lists mounted backends in Vault
     policies         List the policies on the server
     policy-delete    Delete a policy from the server
@@ -68,8 +69,9 @@ All other commands:
     remount          Remount a secret backend to a new path
     rotate           Rotates the backend encryption key used to persist data
     seal             Seals the vault server
+    ssh              Initiate a SSH session
     token-create     Create a new auth token
-    token-renew      Renew an auth token
+    token-renew      Renew an auth token if there is an associated lease
     token-revoke     Revoke one or more auth tokens
     unmount          Unmount a secret backend
     unseal           Unseals the vault server