Expand description
Pure-Rust SMB2/3 client library with pipelined I/O.
No C dependencies, no FFI. Pipelined reads/writes fill the credit window so downloads run ~10-25x faster than sequential SMB clients.
§Quick start
use smb2::{SmbClient, ClientConfig};
let mut client = smb2::connect("192.168.1.100:445", "user", "pass").await?;
// List shares
let shares = client.list_shares().await?;
// Connect to a share
let mut share = client.connect_share("Documents").await?;
// List files
let entries = client.list_directory(&mut share, "projects/").await?;
for entry in &entries {
println!("{} ({} bytes)", entry.name, entry.size);
}
// Read a file
let data = client.read_file(&mut share, "report.pdf").await?;§Async runtime
Runs on tokio (the tokio feature, on by default) or
smol (the smol feature). With smol
on, it also runs under any other executor, since smol brings its own
reactor and executor threads. With both on, each call runs on tokio when
it’s made inside a tokio runtime and on smol otherwise, so feature
unification can’t put a consumer on the wrong one. A smol-only consumer
leaves tokio’s reactor and runtime out of the build (the crate still uses
tokio’s channels and semaphores, which work on any executor):
smb2 = { version = "0.26", default-features = false, features = ["smol"] }§Modules
client– High-level API:SmbClient,Tree,Pipeline. This is what most users need.error– Error types and NTSTATUS mapping.msg– Wire format message structs (advanced/internal use).name– The private-use-area mapping that lets a name carrying?,*,"or another SMB2-illegal character exist on a share at all. Runs on every path automatically; the functions are public for a consumer that wants to see the literal wire form.pack– Binary serialization primitives (advanced/internal use).transport– Transport trait and TCP implementation (advanced/internal use).crypto– Signing and encryption (advanced/internal use).auth– NTLM authentication (advanced/internal use).rpc– Named pipe RPC for share enumeration (advanced/internal use).types– Protocol newtypes and flag types (advanced/internal use).
Re-exports§
pub use error::Error;pub use error::ErrorKind;pub use error::Result;pub use name::decode_name;pub use name::decode_path;pub use name::encode_name;pub use name::encode_path;pub use client::connect;pub use client::ClientConfig;pub use client::SmbClient;pub use client::stream::FileDownload;pub use client::stream::FileReader;pub use client::stream::FileUpload;pub use client::stream::FileWriter;pub use client::stream::Progress;pub use client::stream::ReadAhead;pub use client::stream::WriteBehind;pub use client::stream::DOWNLOAD_CHUNK_SIZE;pub use client::stream::UPLOAD_CHUNK_SIZE;pub use client::copy::CopyChunk;pub use client::copy::CopyChunkOutcome;pub use client::copy::CopyChunkResult;pub use client::copy::ResumeKey;pub use client::copy::ServerSideCopyLimits;pub use client::tree::DfsOrigin;pub use client::tree::DirectoryEntry;pub use client::tree::FileInfo;pub use client::tree::FsInfo;pub use client::tree::ListingTrace;pub use client::tree::QueryStep;pub use client::tree::Tree;pub use client::times::FileTimes;pub use types::flags::FileAttributes;pub use client::durable::FileIdentity;pub use client::resolve::Resolved;pub use client::pipeline::Op;pub use client::pipeline::OpResult;pub use client::pipeline::Pipeline;pub use client::connection::CompoundOp;pub use client::connection::Frame;pub use client::connection::NegotiatedParams;pub use client::connection::ReconnectEvent;pub use client::connection::ReconnectObserver;pub use client::connection::ReconnectPolicy;pub use client::connection::SessionReviver;pub use client::session::Session;pub use client::diagnostics::ClientInfo;pub use client::diagnostics::ClientMetricsSnapshot;pub use client::diagnostics::CompressionInfo;pub use client::diagnostics::ConnectionDiagnostics;pub use client::diagnostics::CreditInfo;pub use client::diagnostics::DfsCacheEntry;pub use client::diagnostics::Diagnostics;pub use client::diagnostics::EncryptionInfo;pub use client::diagnostics::InboundProgress;pub use client::diagnostics::Liveness;pub use client::diagnostics::MetricsSnapshot;pub use client::diagnostics::NegotiatedSummary;pub use client::diagnostics::SessionDiagnostics;pub use client::diagnostics::SigningInfo;pub use client::watcher::FileNotifyAction;pub use client::watcher::FileNotifyEvent;pub use client::watcher::Watcher;pub use auth::kerberos::KerberosAuthenticator;pub use auth::kerberos::KerberosCredentials;
Modules§
- auth
- Authentication mechanisms for SMB2.
- client
- High-level SMB2 client API.
- crypto
- Cryptographic operations for SMB2/3: signing, encryption, key derivation, and compression.
- error
- Error types for the SMB2 library.
- fuzzing
- Fuzzing entry points for
fuzz/targets. - msg
- Wire format message structs for SMB2/3.
- name
- Mapping for filename characters SMB2 does not allow on the wire.
- pack
- Binary serialization/deserialization primitives for SMB2.
- rpc
- Named pipe RPC (MS-RPCE / NDR) for share enumeration.
- testing
- Docker-based SMB test servers for integration testing.
- transport
- Transport abstraction for sending and receiving SMB2 messages.
- types
- Newtypes, enums, and common data structures for SMB2/3 protocol fields.