# Vault management (IRPCVaultsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/

Creates, attaches, detaches, destroys, upgrades, backs up, restores and copies the vaults of a
server, and takes them offline and online.

Use this interface to add, modify and remove vaults.
Use IRPCVaultsAdminBasic to get document vault definitions.

- **gRPC service:** `MFiles.IRPCVaultsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 23
- **Proto file:** [`mfiles/IRPCVaultsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultsAdmin.proto)

<a id="overview"></a>

## Overview

Server-level vault management: the vault commands of M-Files Admin and of the M-Files API's
server vault management operations. Use it from administration tools and automation scripts that
manage the vaults of an on-premises server. Read the definitions of existing vaults with
[GetVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md) and
[GetVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md); administer the contents of one
vault with [IRPCVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md).

**Session and rights.** Every method names its vault in the request, so a server-level session is
enough: log in with `login_data.vault_guid` = `{00000000-0000-0000-0000-000000000000}`. The
methods need a server right, and only logins with the system administrator server role
(`SRVROLES.system_administrator`) have server rights:

| Server right (`ServerAccess`) | Methods |
| --- | --- |
| `manage_vaults` | All methods not listed below |
| `backup_vaults` | `BackUpVault` |
| `restore_vault` | `RestoreVault`, `GetBackupFileContents` |

Exceptions: `UpdateVault` and `GetFullTextSearchInfo` also accept a vault session with full
control of the vault, and `OptimizeVaultMetaDataDatabase` a vault session with the vault right
`manage_scheduled_jobs`. A missing server right fails with gRPC status `UNKNOWN` and the message
"Access denied. You do not have the server-level access rights required by this operation."
(error codes 0x800400A8 and 0x800407E4).

**Tasks and the usual order of calls:**

- **Create a vault**: [GetDefaultDataFolderPrefix](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md),
  [TestConnectionToSQLDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md)
  (SQL Server vaults), then [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md).
- **Change a vault**: [UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md),
  [UpgradeVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md).
- **Take a vault out of use**: [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md),
  [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md),
  [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md).
- **Move a vault between servers**: [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md)
  keeps the data; [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md)
  attaches it again (check first with
  [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md) when the server
  has joined a subscription).
- **Delete a vault and its data**: [DestroyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md).
- **Back up, restore and copy**: [BackUpVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md),
  [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md),
  [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md),
  [CopyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md).
- **Maintenance**: [OptimizeVaultMetaDataDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md),
  [EncryptFileData](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md),
  [GetFullTextSearchInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md).
- **Replica vaults and ground link proxies** (special deployments):
  [CreateNewReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md),
  [UpdateReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md),
  [CreateNewGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md),
  [UpdateGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md).

**Background jobs.** `BackUpVault`, `CopyVault`, `EncryptFileData`,
`OptimizeVaultMetaDataDatabase`, `RestoreVault` (unless `synchronous`) and, when they start a
migration, `UpdateVault` and `UpdateGroundLinkProxy` create a temporary scheduled job and return
its ID in `task_id` before the work is done. Follow the job like the M-Files API does:

1. Call [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md)
   with `scheduled_job` = `task_id` about twice a second.
2. The job has finished when `is_running` is false **and** `current_step` is not -1 (-1 means
   the job has not started yet).
3. Check `last_run_succeeded` and `last_run_errors`; `output` holds the job's result.
4. Remove the finished job with
   [RemoveScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md). Cancel a
   running job with [CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md).

These jobs are server-level jobs (except an optimization started with a vault session, which is a
job of that vault). Server-level and vault-level jobs have separate IDs: read a server-level job
with a server-level session, which needs the server right `manage_jobs`.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md) | Attaches an existing vault (metadata database and file data files) to the server. | `admin` `session` |
| [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md) | Checks whether existing vault files can be attached on a server that has joined a subscription, without attaching them. | `admin` `session` `idempotent` |
| [BackUpVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md) | Backs up a vault into a backup file on the server. | `admin` `session` |
| [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md) | Brings an offline vault online so that users can log in to it again. | `admin` `session` `idempotent` |
| [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md) | Checks whether users have open sessions to a vault: succeeds if there are none and fails with a list of the sessions otherwise. | `admin` `session` `idempotent` |
| [CopyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md) | Copies the specified vault into a new vault (creates the target vault). | `admin` `session` |
| [CreateNewGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md) | Creates a ground link proxy, a vault of type `VAULT_TYPE_GROUND_LINK_PROXY`. | `admin` `session` |
| [CreateNewReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md) | Creates a new replica vault. | `admin` `session` |
| [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md) | Creates a new document vault. | `admin` `session` |
| [DestroyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md) | Destroys a vault: deletes its metadata database and its file data permanently and removes it from the server. | `admin` `session` |
| [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md) | Removes the vault from the server's list of registered vaults but does not remove the metadata database or file data files. | `admin` `session` |
| [EncryptFileData](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md) | Encrypts the existing files of a vault with the vault's latest encryption key. | `admin` `session` |
| [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md) | Reads the vault identity and data folders stored in a backup file on the server. | `admin` `session` `idempotent` |
| [GetDefaultDataFolderPrefix](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md) | Gets the default data folder prefix of new document vaults. | `admin` `session` `idempotent` |
| [GetFullTextSearchInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md) | Gets the languages that the full-text search of a vault supports, or the server's defaults. | `admin` `session` `idempotent` |
| [OptimizeVaultMetaDataDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md) | Optimizes the metadata database of a vault. | `admin` `session` |
| [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md) | Restores a vault from backup files on the server and attaches it. | `admin` `session` |
| [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md) | Takes a vault offline: users cannot log in to it until it is brought online again. | `admin` `session` `idempotent` |
| [TestConnectionToSQLDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md) | Tests whether the server can connect to a Microsoft SQL Server database, for example before creating a vault in it. | `admin` `session` `idempotent` |
| [UpdateGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md) | Updates the definition of a ground link proxy. | `admin` `session` `idempotent` |
| [UpdateReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md) | Updates the definition of a replica vault. | `admin` `session` `idempotent` |
| [UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md) | Changes the definition of a vault: name and other registration data, data folders, database, file data storage and vault variables. | `admin` `session` `idempotent` |
| [UpgradeVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md) | Upgrades an old document vault to the current version. | `admin` `session` `idempotent` |