v1.14.6/website/content/docs/upgrading/upgrade-to-0.5.0.mdx - hashicorp/vault - Git at Google

 ---
 layout: docs
 page_title: Upgrading to Vault 0.5.0 - Guides
 description: |-
   This page contains the full list of breaking changes for Vault 0.5, including
   actions you must take to facilitate a smooth upgrade path.
 ---

 # Overview

 This page contains the list of breaking changes for Vault 0.5. Please read it
 carefully.

 Please note that these are changes to Vault itself. Client libraries maintained
 by HashiCorp have been updated with support for these changes, but if you are
 using community-supported libraries, you should ensure that they are ready for
 Vault 0.5 before upgrading.

 ## Rekey requires nonce

 Vault now generates a nonce when a rekey operation is started in order to
 ensure that the operation cannot be hijacked. The nonce is output when the
 rekey operation is started and when rekey status is requested.

 The nonce must be provided as part of the request parameters when providing an
 unseal key. The nonce can be communicated from the request initiator to unseal
 key holders via side channels; the unseal key holders can then verify the nonce
 (by providing it) when they submit their unseal key.

 As a convenience, if using the CLI interactively to provide the unseal key, the
 nonce will be displayed for verification but the user will not be required to
 manually re-type it.

 ## `TTL` field in token lookup

 Previously, the `ttl` field returned when calling `lookup` or `lookup-self` on
 the token auth method displayed the TTL set at token creation. It
 now displays the time remaining (in seconds) for the token's validity period.
 The original behavior has been moved to a field named `creation_ttl`.

 ## Grace periods removed

 Vault no longer uses grace periods internally for leases or token TTLs.
 Previously these were set by backends and could differ greatly from one backend
 to another, causing confusion. TTLs (the `lease_duration` field for a lease,
 or, for a token lookup, the `ttl`) are now exact.

 ## `token-renew` CLI command

 If the token given for renewal is the same as the token in use by the client,
 the `renew-self` endpoint will be used in the API rather than the `renew`
 endpoint. Since the `default` policy contains `auth/token/renew-self` this
 makes it much more likely that the request will succeed rather than somewhat
 confusingly failing due to a lack of permissions on `auth/token/renew`.

 ## `status` CLI command

 The `status` CLI command now returns an exit code of `0` for an unsealed Vault
 (as before), `2` for a sealed Vault, and `1` for an error. This keeps error
 return codes consistent across commands.

 ## Transit upsertion behavior uses capabilities

 Previously, attempting to encrypt with a key that did not exist would create a
 key with default values. This was convenient but ultimately allowed a client to
 potentially escape an ACL policy restriction, albeit without any dangerous
 access. Now that Vault supports more granular capabilities in policies,
 upsertion behavior is controlled by whether the client has the `create`
 capability for the request (upsertion is allowed) or only the `update`
 capability (upsertion is denied).

 ## etcd physical backend uses `sync`

 The `etcd` physical backend now supports `sync` functionality and it is turned
 on by default, which maps to the upstream library's default. It can be
 disabled; see the configuration page for information.

 ## S3 physical backend prefers environment variables

 The `s3` physical backend now prefers environment variables over configuration
 file variables. This matches the behavior of the rest of the backends and of
 Vault generally.

 ## Lease default and renewal handling

 All backends now honor system and mount-specific default and maximum lease
 times, except when specifically overridden by backend configuration or role
 parameters, or when doing so would not make sense (e.g. AWS STS tokens cannot
 have a lifetime of greater than 1 hour).

 This allows for a _much_ more uniform approach to managing leases on both the
 operational side and the user side, and removes much ambiguity and uncertainty
 resulting from backend-hardcoded limits.

 However, also this means that the leases generated by the backends may return
 significantly different TTLs in 0.5 than in previous versions, unless they have
 been preconfigured. You can use the `mount-tune` CLI command or the
 `/sys/mounts/<mount point>/tune` endpoint to adjust default and max TTL
 behavior for any mount. This is supported in 0.4, so you can perform this
 tuning before upgrading.

 The following list details the ways in which lease handling has changed
 per-backend. In all cases the "mount TTL" means the mount-specific value for
 default or max TTL; however, if no value is set on a given mount, the system
 default/max values are used. This lists only the changes; any lease-issuing
 or renew function not listed here behaves the same as in 0.4.

 (As a refresher: the default TTL is the amount of time that the initial
 lease/token is valid for before it must be renewed; the maximum TTL is the
 amount of time a lease or token is valid for before it can no longer be renewed
 and must be reissued. A mount can be more restrictive with its maximum TTL, but
 cannot be less restrictive than the mount's maximum TTL.)

 #### Credential (Auth) backends

 - `github` – The renewal function now uses the backend's configured maximum
   TTL, if set; otherwise, the mount maximum TTL is used.
 - `ldap` – The renewal function now uses the mount default TTL instead of always
   using one hour.
 - `token` – Tokens can no longer be renewed forever; instead, they now honor the
   mount default/max TTL.
 - `userpass` – The renew function now uses the backend's configured maximum TTL,
   if set; otherwise the mount maximum TTL is used.

 #### Secrets engines

 - `aws` – New IAM roles no longer always have a default TTL of one hour, instead
   honoring the configured default if available and the mount default TTL if not
   (renewal always used the configured values if available). STS tokens return a
   TTL corresponding to the lifetime of the token in AWS and cannot be renewed.
 - `cassandra` – `lease_grace_period` has been removed since Vault no longer uses
   grace periods.
 - `consul` – The mount default TTL is now used as the default TTL if there is no
   backend configuration parameter. Renewal now uses the mount default and
   maximum TTLs.
 - `mysql` – The mount default TTL is now used as the default TTL if there is no
   backend configuration parameter.
 - `postgresql` – The mount default TTL is now used as the default TTL if there
   is no backend configuration parameter. In addition, there is no longer any
   grace period with the time configured for password expiration within Postgres
   itself.
	---
	layout: docs
	page_title: Upgrading to Vault 0.5.0 - Guides
	description: \|-
	This page contains the full list of breaking changes for Vault 0.5, including
	actions you must take to facilitate a smooth upgrade path.
	---

	# Overview

	This page contains the list of breaking changes for Vault 0.5. Please read it
	carefully.

	Please note that these are changes to Vault itself. Client libraries maintained
	by HashiCorp have been updated with support for these changes, but if you are
	using community-supported libraries, you should ensure that they are ready for
	Vault 0.5 before upgrading.

	## Rekey requires nonce

	Vault now generates a nonce when a rekey operation is started in order to
	ensure that the operation cannot be hijacked. The nonce is output when the
	rekey operation is started and when rekey status is requested.

	The nonce must be provided as part of the request parameters when providing an
	unseal key. The nonce can be communicated from the request initiator to unseal
	key holders via side channels; the unseal key holders can then verify the nonce
	(by providing it) when they submit their unseal key.

	As a convenience, if using the CLI interactively to provide the unseal key, the
	nonce will be displayed for verification but the user will not be required to
	manually re-type it.

	## `TTL` field in token lookup

	Previously, the `ttl` field returned when calling `lookup` or `lookup-self` on
	the token auth method displayed the TTL set at token creation. It
	now displays the time remaining (in seconds) for the token's validity period.
	The original behavior has been moved to a field named `creation_ttl`.

	## Grace periods removed

	Vault no longer uses grace periods internally for leases or token TTLs.
	Previously these were set by backends and could differ greatly from one backend
	to another, causing confusion. TTLs (the `lease_duration` field for a lease,
	or, for a token lookup, the `ttl`) are now exact.

	## `token-renew` CLI command

	If the token given for renewal is the same as the token in use by the client,
	the `renew-self` endpoint will be used in the API rather than the `renew`
	endpoint. Since the `default` policy contains `auth/token/renew-self` this
	makes it much more likely that the request will succeed rather than somewhat
	confusingly failing due to a lack of permissions on `auth/token/renew`.

	## `status` CLI command

	The `status` CLI command now returns an exit code of `0` for an unsealed Vault
	(as before), `2` for a sealed Vault, and `1` for an error. This keeps error
	return codes consistent across commands.

	## Transit upsertion behavior uses capabilities

	Previously, attempting to encrypt with a key that did not exist would create a
	key with default values. This was convenient but ultimately allowed a client to
	potentially escape an ACL policy restriction, albeit without any dangerous
	access. Now that Vault supports more granular capabilities in policies,
	upsertion behavior is controlled by whether the client has the `create`
	capability for the request (upsertion is allowed) or only the `update`
	capability (upsertion is denied).

	## etcd physical backend uses `sync`

	The `etcd` physical backend now supports `sync` functionality and it is turned
	on by default, which maps to the upstream library's default. It can be
	disabled; see the configuration page for information.

	## S3 physical backend prefers environment variables

	The `s3` physical backend now prefers environment variables over configuration
	file variables. This matches the behavior of the rest of the backends and of
	Vault generally.

	## Lease default and renewal handling

	All backends now honor system and mount-specific default and maximum lease
	times, except when specifically overridden by backend configuration or role
	parameters, or when doing so would not make sense (e.g. AWS STS tokens cannot
	have a lifetime of greater than 1 hour).

	This allows for a _much_ more uniform approach to managing leases on both the
	operational side and the user side, and removes much ambiguity and uncertainty
	resulting from backend-hardcoded limits.

	However, also this means that the leases generated by the backends may return
	significantly different TTLs in 0.5 than in previous versions, unless they have
	been preconfigured. You can use the `mount-tune` CLI command or the
	`/sys/mounts/<mount point>/tune` endpoint to adjust default and max TTL
	behavior for any mount. This is supported in 0.4, so you can perform this
	tuning before upgrading.

	The following list details the ways in which lease handling has changed
	per-backend. In all cases the "mount TTL" means the mount-specific value for
	default or max TTL; however, if no value is set on a given mount, the system
	default/max values are used. This lists only the changes; any lease-issuing
	or renew function not listed here behaves the same as in 0.4.

	(As a refresher: the default TTL is the amount of time that the initial
	lease/token is valid for before it must be renewed; the maximum TTL is the
	amount of time a lease or token is valid for before it can no longer be renewed
	and must be reissued. A mount can be more restrictive with its maximum TTL, but
	cannot be less restrictive than the mount's maximum TTL.)

	#### Credential (Auth) backends

	- `github` – The renewal function now uses the backend's configured maximum
	TTL, if set; otherwise, the mount maximum TTL is used.
	- `ldap` – The renewal function now uses the mount default TTL instead of always
	using one hour.
	- `token` – Tokens can no longer be renewed forever; instead, they now honor the
	mount default/max TTL.
	- `userpass` – The renew function now uses the backend's configured maximum TTL,
	if set; otherwise the mount maximum TTL is used.

	#### Secrets engines

	- `aws` – New IAM roles no longer always have a default TTL of one hour, instead
	honoring the configured default if available and the mount default TTL if not
	(renewal always used the configured values if available). STS tokens return a
	TTL corresponding to the lifetime of the token in AWS and cannot be renewed.
	- `cassandra` – `lease_grace_period` has been removed since Vault no longer uses
	grace periods.
	- `consul` – The mount default TTL is now used as the default TTL if there is no
	backend configuration parameter. Renewal now uses the mount default and
	maximum TTLs.
	- `mysql` – The mount default TTL is now used as the default TTL if there is no
	backend configuration parameter.
	- `postgresql` – The mount default TTL is now used as the default TTL if there
	is no backend configuration parameter. In addition, there is no longer any
	grace period with the time configured for password expiration within Postgres
	itself.