# IRPCVaultsAdmin.AttachExistingVault

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) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

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

Badges: `Administration API / specialized` `admin` `session`

Attaches an existing vault (metadata database and file data files) to the server.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/AttachExistingVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/attach-existing-vault`
- **Request:** [`AttachExistingVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md#request)
- **Response:** [`AttachExistingVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Runs in the call: the server opens the existing database and file data, registers the vault
  and returns its definition.
- On a server that has joined a subscription, check first with
  [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md).

<a id="request"></a>

## Request: AttachExistingVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Where the vault's files are: data folders and database. If `vault.vault.guid` is the null GUID, the vault keeps the GUID stored in its files; otherwise its GUID is changed to the given one. |
| `vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.vault.display_name` | `string` | The vault name shown to users. |
| `vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `options` | [`AttachVaultOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AttachVaultOptions/index.md) | Options for attaching, such as which external connections to disable and whether to update the attachment GUID. |
| `options.disable` | [`ExternalConnectionOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalConnectionOptions/index.md) | Which vault's external data connection points must be put disabled? |
| `options.disable.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.disable.external_object_types` | `bool` | Connections to external objects and value list items (connections to external databases and plug-in based sources such as web services). |
| `options.disable.external_sources` | `bool` | Connections to external sources (file/e-mail). |
| `options.disable.exported_data_sets` | `bool` | Data sets for reporting and metadata export. |
| `options.disable.scheduled_export_import_jobs` | `bool` | Scheduled export and import jobs (content replication, archiving/restoring). |
| `options.disable.external_user_groups` | `bool` | Importing external users and groups e.g. from Active Directory. |
| `options.disable.event_handlers` | `bool` | Event handlers. A event handler might be a connection point to external data but not necessarily. |
| `options.disable.vault_applications` | `bool` | Vault applications. This includes connections to external repositories. |
| `options.disable.remote_indexes` | `bool` | Remote indexes. IDOL or Smart Search search engines are usually located in different servers. |
| `options.disable.anonymous_login` | `bool` | Enabling anonymous login. |
| `options.update_attachment_guid` | `bool` | Specify true if the attachment GUID should be updated. Usually, it is desirable to update the attachment GUID each time the vault is re-attached. |
| `options.fail_attach_if_bring_online_fails` | `bool` | A flag that controls if attaching the vault must fail if its online operations do not start successfully. Typically this is false meaning that starting online operations can fail although attaching the vault succeeds. |
| `options.enforce_file_data_encryption` | `bool` | A flag that controls if file data encryption should be turned on in the vault when it is attached. |
| `options.disable_local_indexes` | `bool` | A flag that controls if the local indexes such as dtSearch are disabled when the vault is attached. |
| `options.allow_only_vault_temp_path_for_content_replication` | `bool` | If true the temporary processing location of cloud replication jobs are cleared and other replication jobs are disabled. |
| `options.ignore_vault_external_data_connection_points` | `bool` | If true vault's external data connection points are ignored when vault is already in msm cluster. |
| `attach_always` | `bool` | On a server that has joined a subscription, true attaches the vault even if it is already attached to another server. |

<a id="response"></a>

## Response: AttachExistingVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `attached_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Receives the full definition of the attached vault. |
| `attached_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `attached_vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `attached_vault.vault.display_name` | `string` | The vault name shown to users. |
| `attached_vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `attached_vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `attached_vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `attached_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `attached_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `attached_vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `attached_vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `attached_vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `attached_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `attached_vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `attached_vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `attached_vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `attached_vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `attached_vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `attached_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `attached_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |

<a id="related"></a>

## Related methods

- [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.