rsmount 0.1.0

Safe Rust wrapper around the `util-linux/libmount` C library
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# rsmount

----

[![Crates.io Version](https://img.shields.io/crates/v/rsmount?labelColor=%23222222&color=%23fdb42f)][1]
[![docs.rs](https://img.shields.io/docsrs/rsmount?labelColor=%23222222&color=%2322a884)][2]
![Crates.io MSRV](https://img.shields.io/crates/msrv/rsmount?labelColor=%23222222&color=%239c179e)
![Crates.io License](https://img.shields.io/crates/l/rsmount?labelColor=%23222222&color=%230d0887)

⚠️ WARNING: **This library is still in development, thus not yet suitable for
use in production.**

The `rsmount` library is a safe Rust wrapper around [`util-linux/libmount`][3].

`rsmount` allows users to, among other things:

- mount devices on an operating system’s file hierarchy,
- list/manage mount points in `/proc/<pid>/mountinfo`,
- consult the system’s swap usage from /proc/swaps,
- compose/edit /etc/fstab, the file describing all devices an OS should mount
  at boot.
- etc.

## Usage

This crate requires `libmount` version `2.39.2` or later.

Add the following to your `Cargo.toml`:

```toml
[dependencies]
rsmount = "0.1.0"
```

Then install the system packages below before running `cargo build`:

- `util-linux`: to generate Rust bindings from `libmount`'s header files.
- `libclang`: to satisfy the [dependency][4] of [`bindgen`][5] on `libclang`.
- `pkg-config`: to detect system libraries.

Read the [installation instructions](#install-required-dependencies) below to
install the required dependencies on your system.

[Documentation (docs.rs)][2]

## Example

In this example we mount a disk on `/mnt/backup`.

```rust
use rsmount::core::device::BlockDevice;
use rsmount::core::flags::MountFlag;
use rsmount::core::fs::FileSystem;
use rsmount::mount::Mount;

fn main() -> rsmount::Result<()> {
    // Configure the `Mount` struct.
    let block_device: BlockDevice = "/dev/vda".parse()?;
    let mut mount = Mount::builder()
        // Device to mount.
        .source(block_device.into())
        // Location of the mount point in the file tree.
        .target("/mnt/backup")
        // Do not allow writing to the file system while it is mounted.
        .mount_flags(vec![MountFlag::ReadOnly])
        // Gives a hint about the file system used by the device (optional).
        .file_system(FileSystem::Ext4)
        .build()?;

    // Mount `/dev/vda` at `/mnt/backup`.
    mount.mount_device()?;

    Ok(())
}

```

## Install required dependencies

### Alpine Linux

As `root`, issue the following command:

```console
apk add util-linux-dev clang-libclang pkgconfig
```

### NixOS

Install the packages in a temporary environment with:

```console
nix-shell -p util-linux.dev libclang.lib pkg-config
```

or permanently with:

```console
nix-env -iA nixos.util-linux.dev nixos.libclang.lib nixos.pkg-config
```

### Ubuntu

```console
sudo apt-get install libmount-dev libclang-dev pkg-config
```

## License

This project is licensed under either of the following:

- [Apache License, Version 2.0][6]
- [MIT License][7]

at your discretion.

Files in the [third-party/][8] and [web-snapshots/][9] directories are subject
to their own licenses and/or copyrights.

SPDX-License-Identifier: Apache-2.0 OR MIT

Copyright (c) 2023 Nick Piaddo

[1]: https://crates.io/crates/rsmount
[2]: https://docs.rs/rsmount
[3]: https://github.com/util-linux/util-linux/tree/master
[4]: https://rust-lang.github.io/rust-bindgen/requirements.html#clang
[5]: https://crates.io/crates/bindgen
[6]: https://www.apache.org/licenses/LICENSE-2.0
[7]: https://opensource.org/licenses/MIT
[8]: ./third-party/
[9]: ./web-snapshots/