open-vault/website/content/api-docs/system/remount.mdx

---
layout: api
page_title: /sys/remount - HTTP API
description: >-
  The '/sys/remount' endpoint is used remount a mounted backend to a new
  endpoint.
---

# Remount ( API )

The Remount documentation details the endpoints required to trigger and monitor the status of a remount operation.

## Move Backend

The `/sys/remount` endpoint moves an already-mounted backend to a new mount point. This process works for both secret 
engines and auth methods.

The endpoint can be used to move the backend across namespaces as well, with the namespaces supplied as prefixes
on the path arguments. In this case, namespaces for both the source and destination mounts need to be 
either the namespace in which the `/remount` endpoint is called, or the children of that namespace. Let us assume that 
we have 3 namespaces ns1/, ns1/ns2/ and ns1/ns3. We want to move the mount `secret` from ns1/ns2/secret to ns1/ns3/secret. 
This can be done in one of two ways. The first way is to invoke `/remount` from the root namespace with the `from` argument as ns1/ns2/secret 
and `to` argument as ns1/ns3/new-secret. The second way is to invoke `/remount` from the namespace ns1/, with `from` as ns2/secret and `to` 
as ns3/new-secret.

The remount operation can be a long-running operation, hence the invocation of /remount triggers the start of 
the remount process, returning a migration ID to the user. The user may utlizie the migration ID to look up 
the status of the mount migration.

~> Note: This endpoint requires a policy with both `sudo` and `update` capabilities to `sys/remount`

~> Note: A mount migration will revoke all leases for the secrets of a secrets backend or tokens of an auth backend,
depending on which type of backend is being moved.


| Method | Path           |
| :----- | :------------- |
| `POST` | `/sys/remount` |

### Parameters

- `from` `(string: <required>)` – Specifies the previous mount point.

- `to` `(string: <required>)` – Specifies the new destination mount point.

### Sample Payload ( Cross Namespace )

```json
{
  "from": "ns1/ns2/secret",
  "to": "ns1/ns3/new-secret"
}
```

### Sample Payload ( Cross Namespace, Auth Mount )

```json
{
  "from": "ns1/ns2/auth/approle",
  "to": "ns1/ns3/auth/new-approle"
}
```

### Sample Payload ( Within Namespace )

```json
{
  "from": "secret",
  "to": "new-secret"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/remount
```

### Sample Response

```json
{
  "migration_id": "ef3ba21c-8be8-4e5f-8d00-cb46a532c665"
}
```

## Monitor Migration Status

This endpoint is used to monitor the status of a mount migration operation, using the ID returned in the response
of the `sys/remount` call. The response contains the passed-in ID, the source and target mounts, and a status field
that displays `in-progress`, `success` or `failure`.

| Method | Path           |
| :----- | :------------- |
| `GET` | `/sys/remount/status/:migration_id` |

### Parameters

- `migration_id` `(string: <required>)` – Specifies the id of the mount migration

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/remount/status/ef3ba21c-8be8-4e5f-8d00-cb46a532c665
```

### Sample Response

```json
{
  "migration_id": "ef3ba21c-8be8-4e5f-8d00-cb46a532c665",
  "migration_info": {
    "source_mount": "ns1/ns2/secret",
    "target_mount": "ns1/ns3/new-secret",
    "status": "in-progress",
  }
}
```