---
layout: docs
page_title: Upgrade to Vault 1.16.x - Guides
description: |-
  Deprecations, important or breaking changes, and remediation recommendations
  for anyone upgrading to 1.16.x from Vault 1.15.x.
---

# Overview

The Vault 1.16.x upgrade guide contains information on deprecations, important
or breaking changes, and remediation recommendations for anyone upgrading from
Vault 1.15. **Please read carefully**.

## Important changes

### External plugin variables take precedence over system variables ((#external-plugin-variables))

Vault gives precedence to plugin environment variables over system environment
variables when loading external plugins. The behavior for builtin plugins and
plugins that do not specify additional environment variables is unaffected.

For example, if you register an external plugin with `SOURCE=child` in the
[env](/vault/api-docs/system/plugins-catalog#env) parameter but the main Vault
process already has `SOURCE=parent` defined, the plugin process starts
with `SOURCE=child`.

Refer to the [plugin management](/vault/docs/plugins/plugin-management) page for
more details on plugin environment variables.

<Highlight title="Avoid conflicts with containerized plugins">

  Containerized plugins do not inherit system-defined environment variables. As
  a result, containerized plugins cannot have conflicts with Vault environment
  variables.

</Highlight>

#### How to opt out

To opt out of the precedence change, set the
`VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` environment variable to `true` for the
main Vault process:

```shell-session
$ export VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING=true
```

Setting `VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` to `true` tells Vault to:

1. prioritize environment variables from the Vault server environment whenever
   the system detects a variable conflict.
1. report on plugin variable conflicts during the unseal process by printing
   warnings for plugins with conflicting environment variables or logging an
   informational entry when there are no conflicts.

For example, assume you set `VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` to `true`
and have an environment variable `SOURCE=parent`.

If you register an external plugin called `myplugin` with `SOURCE=child`, the
plugin process starts with `SOURCE=parent` and Vault reports a conflict for
`myplugin`.

### LDAP auth login changes

Users cannot log in using LDAP unless the LDAP plugin is configured
with an `userdn` value scoped to an organization unit (OU) where the
user resides.

### LDAP auth entity alias names no longer include upndomain

The `userattr` field on the LDAP auth config is now used as the entity alias.
Prior to 1.16, the LDAP auth method would detect if `upndomain` was configured
on the mount and then use `<cn>@<upndomain>` as the entity alias value.

The consequence of not configuring this correctly means users may not have the
correct policies attached to their tokens when logging in.

#### How to opt out

To opt out of the entity alias change, update the `userattr` field on the config:

```
userattr="userprincipalname"
```

Refer to the [LDAP auth method (API)](/vault/api-docs/auth/ldap) page for
more details on the configuration.

### Secrets Sync now requires setting a one-time flag before use

To use the Secrets Sync feature, the feature must be activated with a new one-time
operation called an activation-flag. The feature is gated until a Vault operator
decides to trigger the flag. More information can be found in the
[secrets sync documentation](/vault/docs/sync#activating-the-feature).

### Activity Log Changes

#### Default Activity Log Querying Period

As of 1.16.13 and later, the field `default_report_months` can no longer be configured or read. Any previously set values
will be ignored by the system.


Attempts to modify `default_report_months` through the
[/sys/internal/counters/config](/vault/api-docs/system/internal-counters#update-the-client-count-configuration)
endpoint, will result in the following warning from Vault:

<CodeBlockConfig hideClipboard>

  ```shell-session

  WARNING! The following warnings were returned from Vault:

  * default_report_months is deprecated: defaulting to billing start time


  ```

</CodeBlockConfig>


The `current_billing_period` toggle for `/sys/internal/counters/activity` is also deprecated, as this will be set
true by default.

Attempts to set `current_billing_period` will result in the following warning from Vault:

<CodeBlockConfig hideClipboard>

  ```shell-session

  WARNING! The following warnings were returned from Vault:

  * current_billing_period is deprecated; unless otherwise specified, all requests will default to the current billing period


  ```

</CodeBlockConfig>

### Auto-rolled billing start date

As of 1.16.7 and later, the billing start date (license start date if not configured) automatically rolls over to the latest billing year at the end of the last cycle.

@include 'auto-roll-billing-start.mdx'

@include 'auto-roll-billing-start-example.mdx'

### Docker image no longer contains `curl`

As of 1.16.7 and later, the `curl` binary is no longer included in the published Docker container
images for Vault and Vault Enterprise. If your workflow depends on `curl` being available in the
container, consider one of the following strategies:

#### Create a wrapper container image

Use the HashiCorp image as a base image to create a new container image with `curl` installed.

```Dockerfile
FROM hashicorp/vault-enterprise
RUN apk add curl
```

**NOTE:** While this is the preferred option it will require managing your own registry and rebuilding new images.

#### Install it at runtime dynamically

When running the image as root (not recommended), you can install it at runtime dynamically by using the `apk` package manager:

```shell-session
docker exec <CONTAINER-ID> apk add curl
```
```shell-session
kubectl exec -ti <NAME> -- apk add curl
```

When running the image as non-root without privilege escalation (recommended) you can use existing
tools to install a static binary of `curl` into the `vault` users home directory:

```shell-session
docker exec <CONTAINER-ID> wget https://github.com/moparisthebest/static-curl/releases/latest/download/curl-amd64 -O /home/vault/curl && chmod +x /home/vault/curl
```
```shell-session
kubectl exec -ti <NAME> -- wget https://github.com/moparisthebest/static-curl/releases/latest/download/curl-amd64 -O /home/vault/curl && chmod +x /home/vault/curl
```

**NOTE:** When using this option you'll want to verify that the static binary comes from a trusted source.

### Product usage reporting

As of 1.16.13, Vault will collect anonymous product usage metrics for HashiCorp. This information will be collected
alongside client activity data, and will be sent automatically if automated reporting is configured, or added to manual
reports if manual reporting is preferred.

See the main page for [Vault product usage metrics reporting](/vault/docs/enterprise/license/product-usage-reporting) for
more details, and information about opt-out.

## Known issues and workarounds

@include 'known-issues/1_17_audit-log-hmac.mdx'

@include 'known-issues/1_16-jwt_auth_bound_audiences.mdx'

@include 'known-issues/1_16-jwt_auth_config.mdx'

@include 'known-issues/1_16-ldap_auth_login_anonymous_group_search.mdx'

@include 'known-issues/1_16-ldap_auth_login_missing_entity_alias.mdx'

@include 'known-issues/1_16-default-policy-needs-to-be-updated.mdx'

@include 'known-issues/1_16-default-lcq-pre-1_9-upgrade.mdx'

@include 'known-issues/ocsp-redirect.mdx'

@include 'known-issues/1_16_azure-secrets-engine-client-id.mdx'

@include 'known-issues/perf-standbys-revert-to-standby.mdx'

@include 'known-issues/1_13-reload-census-panic-standby.mdx'

@include 'known-issues/autopilot-upgrade-upgrade-version.mdx'

@include 'known-issues/1_16_secrets-sync-chroot-activation.mdx'

@include 'known-issues/config_listener_proxy_protocol_behavior_issue.mdx'

@include 'known-issues/dangling-entity-aliases-in-memory.mdx'

@include 'known-issues/duplicate-identity-groups.mdx'

@include 'known-issues/manual-entity-merge-does-not-persist.mdx'

@include 'known-issues/duplicate-hsm-key.mdx'