# @vates/fuse-vhd

Latest version **2.1.3** (published 2026-06-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install @vates/fuse-vhd
pnpm add @vates/fuse-vhd
yarn add @vates/fuse-vhd
bun add @vates/fuse-vhd
```

Provides the command `xo-fuse-vhd`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.3 |
| Published | 2026-06-24 |
| First published | 2022-09-26 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14 |
| Dependencies | 6 |
| Unpacked size | 9.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 988 |
| Author | Vates SAS |
| Maintainers | mpiton, florent.beauchamp, mathieura, julien-f, marsaud, pdonias, tgoettelmann, enishowk, b-nollet, mlssfrncjrg, arnogues, joris-k, elise-f, nathanael-h, olivier.f, pierre.brunet289 |

## Links

- npm: https://www.npmjs.com/package/@vates/fuse-vhd
- Repository: https://github.com/vatesfr/xen-orchestra
- Homepage: https://github.com/vatesfr/xen-orchestra/tree/master/@vates/fuse-vhd
- Issues: https://github.com/vatesfr/xen-orchestra/issues
- npm.io page: https://npm.io/package/@vates/fuse-vhd

## Dependencies (6)

- [vhd-lib](https://npm.io/package/vhd-lib.md) ^4.16.0
- [lru-cache](https://npm.io/package/lru-cache.md) ^7.14.0
- [fuse-native](https://npm.io/package/fuse-native.md) ^2.2.6
- [promise-toolbox](https://npm.io/package/promise-toolbox.md) ^0.21.0
- [@xen-orchestra/fs](https://npm.io/package/@xen-orchestra/fs.md) ^4.9.1
- [@xen-orchestra/log](https://npm.io/package/@xen-orchestra/log.md) ^0.7.2

## Recent versions

- 2.1.3 (latest) — 2026-06-24
- 2.1.2 — 2024-10-28
- 2.1.1 — 2024-06-27
- 2.1.0 — 2024-01-29
- 2.0.0 — 2023-07-28
- 1.0.0 — 2022-09-26

## README

<!-- DO NOT EDIT MANUALLY, THIS FILE HAS BEEN GENERATED -->

# @vates/fuse-vhd

[![Package Version](https://badgen.net/npm/v/@vates/fuse-vhd)](https://npmjs.org/package/@vates/fuse-vhd) ![License](https://badgen.net/npm/license/@vates/fuse-vhd) [![PackagePhobia](https://badgen.net/bundlephobia/minzip/@vates/fuse-vhd)](https://bundlephobia.com/result?p=@vates/fuse-vhd) [![Node compatibility](https://badgen.net/npm/node/@vates/fuse-vhd)](https://npmjs.org/package/@vates/fuse-vhd)

## Install

Installation of the [npm package](https://npmjs.org/package/@vates/fuse-vhd):

```sh
npm install --save @vates/fuse-vhd
```

## Usage

Mount a vhd generated by xen-orchestra to filesystem

### Library

```js
import { mount } from 'fuse-vhd'

// return a disposable, see promise-toolbox/Disposable
// unmount automatically when disposable is disposed
// in case of differencing VHD, it mounts the full chain
await mount(handler, diskId, mountPoint)
```

### cli

From the install folder:

```
cli.mjs <remoteUrl> <vhdPathInRemote> <mountPoint>
```

After installing the package

```
xo-fuse-vhd <remoteUrl> <vhdPathInRemote> <mountPoint>
```

The `remoteUrl` can be found using the following command from the XOA CLI, and then picking the right `url` property:

`xo-server-db ls remote`

The `vhdPathInRemote` follows a file structure described in [VM backups](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/VM%20backups/README.md).

## Restore a file from a VHD using `fuse-vhd` CLI

1. Mount a VHD to the Filesystem (see **Usage**).
2. Verify the VHD is Correctly Mounted:

`mount | grep fuse`

3. Get the `START` and `SIZE` of the disk whose file you want to restore. Multiply `START` by 512 (block size) to get the offset value. (`mountedVhdPath` is the `mountPoint` value from earlier, followed by `/vhd0`, for example). Depending on the partition type, you may need to do some additional setup to discover the partitions.

`partx --bytes --output=NR,START,SIZE,NAME,UUID,TYPE --pairs <mountedVhdPath>`

4.  Mount the disk. Depending on the partition type, you may need to add some additional options. The `norecovery` option is used for ext3/ext4/xfs file systems; otherwise, remove this option.

`mount --options=loop,ro,norecovery,sizelimit=<SIZE>,offset=<START*512>  --source=<mountedVhdPath> --target=<diskMountPoint>`

5. Copy your files from the mounted partition, then unmount the partition.

## Contributions

Contributions are _very_ welcomed, either on the documentation or on
the code.

You may:

- report any [issue](https://github.com/vatesfr/xen-orchestra/issues)
  you've encountered;
- fork and create a pull request.

## License

[ISC](https://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr)

---
_Source: https://npm.io/package/@vates/fuse-vhd · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._