~ A Rust client library for SMB ~

Get started · Crates.io · Documentation

Developed by @veeso

Current version: 0.2.12 (19/03/2025)

• Pavão
  • About Pavão 🦚
    • SMB Rust client for Windows
  • Get started 🏁
    • Add pavao to your Cargo.toml 🦀
    • Install pavao C dependencies on your system 🖥️
      • MacOS 🍎
      • Debian based systems 🐧
      • RedHat based systems 🐧
      • OpenBSD 🐡
      • Termux 🤖
      • Build from sources 📁
  • Vendored libsmbclient
    • Create a pavao application
    • Run examples
  • Documentation 📚
  • Support the developer ☕
  • Contributing and issues 🤝🏻
  • Changelog ⏳
  • License 📃

Pavão (/pɐ.ˈvɐ̃w̃/) is a Rust client library for SMB version 2 and 3 which exposes type-safe functions to interact with the C libsmbclient.

SMB is natively supported on Windows by the fs module. If you're looking on how to use SMB on Windows with Rust, please check out this article https://blog.veeso.dev/blog/en/how-to-access-an-smb-share-with-rust-on-windows/ or consider adopting remotefs-smb.

pavao = "0.2"

Install samba with brew:

brew install samba

Install libsmbclient with apt:

apt install -y libsmbclient-dev libsmbclient

⚠️ libsmbclient-dev is required only on the machine where you build the application

Install libsmbclient with dnf:

dnf install libsmbclient-devel libsmbclient

⚠️ libsmbclient-devel is required only on the machine where you build the application

Install samba with pkg_add:

pkg_add samba

Install samba with pkg:

pkg install samba

Install libsmbclient building from sources:

wget -O samba.tar.gz https://github.com/samba-team/samba/archive/refs/tags/samba-4.16.1.tar.gz
mkdir -p samba/
tar  xzvf samba.tar.gz -C samba/ --strip-components=1
rm samba.tar.gz
cd samba/
./configure
make
make install
cd ..
rm -rf samba/

It is possible to build libsmbclient statically when building pavao.

To do so it is enough to enable the vendored feature for the pavao crate in your Cargo.toml:

pavao = { version = "0.2", features = ["vendored"] }

In order to build and run with the vendored feature YOU MUST have the following libraries in your LD_LIBRARY_PATH:

see DEPENDENCIES

use pavao::{SmbClient, SmbCredentials, SmbOptions, SmbOpenOptions};

// Initialize a new client
let client = SmbClient::new(
    SmbCredentials::default()
        .server(server)
        .share(share)
        .password(password)
        .username(username)
        .workgroup(workgroup),
    SmbOptions::default().one_share_per_server(true),
)
.unwrap();
// do anything you want here with client
let mut file = client.open_with("/abc/test.txt", SmbOpenOptions::default().read(true)).unwrap();
// read file...
drop(file);
// disconnect from server
drop(client);

Two examples are provided along with this repository and can be found under the examples/ directory.

The tree example can be used to get a fs tree of the smb share and can be run with:

cargo run --example tree -- -u <username> -w <workspace> -s <share> -P <password> smb://<hostname>

while the transfer example shows how to write a file to the remote host and can be run with:

cargo run --example transfer -- -i <file_on_local> -o <file_to_write> -u <username> -w <workspace> -s <share> -P <password> smb://<hostname>

The developer documentation can be found on Rust Docs at https://docs.rs/pavao

If you like Pavão and you're grateful for the work I've done, please consider a little donation 🥳

You can make a donation with one of these platforms:

Contributions, bug reports, new features and questions are welcome! 😉 If you have any question or concern, or you want to suggest a new feature, or you want just want to improve pavao, feel free to open an issue or a PR.

Please follow our contributing guidelines

View Pavão's changelog HERE

Pavão is licensed under the GPLv3 license.

You can read the entire license HERE