Pavão

~ A Rust client library for SMB ~

Developed by @veeso

Current version: 0.2.3 (16/05/2023)

Pavão

About Pavão 🦚

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.

Pavão |> Pavé |> Animal Crossing |> Carnival |> Rio De Janeiro |> Samba |> SMB

Get started 🏁

Add pavao to your Cargo.toml 🦀

pavao = "0.2"

Install pavao C dependencies on your system 🖥️

MacOS 🍎

Install samba with brew:

brew install samba

Debian based systems 🐧

Install libsmbclient with apt:

apt install -y libsmbclient-dev libsmbclient

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

RedHat based systems 🐧

Install libsmbclient with dnf:

dnf install libsmbclient-devel libsmbclient

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

Build from sources 📁

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/

Create a pavao application

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);

Run examples

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>

Documentation 📚

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

Support the developer ☕

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:

Contributing and issues 🤝🏻

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

Changelog ⏳

View Pavão's changelog HERE

License 📃

Pavão is licensed under the GPLv3 license.

You can read the entire license HERE

veeso/pavao