Source code
Library API

All those names...
SMB is a protocol used by computers to share resources, such as files and printers, on a network. It is supported by a lot of different operating systems. Most notably, MS Windows supports smb natively.

Samba and libsmbclient
The Samba project develops the Open Source samba suite, which is excellent for people who want their computer to be smb enabled without resorting to proprietary software. Included in samba is a C library called libsmbclient which makes it easier for programmers to access smb resources.

The final step in this abstraction, away from bits and bytes and closer to the thoughts of the programmer, is by entering the dynamic and high-level nature of the Ruby programming language. That's what Ruby/SMB is for.

Working with Ruby/SMB
First (perhaps after reading this through) go to the project download page, download the latest version, unzip and untar it, then follow the instructions in the included INSTALL file.

The SMB module
To use Ruby/SMB in your Ruby program, just do:
require 'smb'

This initializes the library, which defines the SMB module. For details on the methods available see Library API. We'll look at some examples here.

Downloading and uploading files
Say that you've got a file "music.mp3" on your friend's computer "Multivac" in a shared called "public". To fetch it and save it on you computer, do the following:
require 'smb' "music.mp3", "w" do |local| "smb://multivac/public/music.mp3", "r" do |remote|
    while data =
Alternatively, you can use instead of the short form Specifying length to read (1024 in this case) is a good idea since otherwise all the data would be read into memory before writing it to disk.

What if it's you who've got the file and your friend who wants it? Easy! Just change places on those "w" and "r", and change to and local.write to remote.write.

Network browsing
You can browse the contents of smb network workgroups, servers, shares, and directories. They are all represented by the class SMB::Dir. Similar to the previous example, can be replaced by, if that feels more natural to you.

Now, to browse directories (and also workgroups, servers, and file shares, as mentioned above), we do this:
require 'smb' "smb://multivac/public/" do |dir|
  print dir.url + " contains:\n"
  while name =
    print name, "\t"
There are many ways of doing this though, so look through the documentation of the SMB::Dir class in Library API. To open a workgroup, simply use the url "smb://workgroupname/".

Ruby/SMB workings
URL format
The complete format of a smb url as recognized by Ruby/SMB and libsmbclient is:
Also, smb:// returns a browsing of all workgroups, and smb://name/ can mean both a server name and workgroup name.

The SMB::Util module, which is mixed in to SMB::File, SMB::Dir, and SMB::Dir::Entry parses out the respective parts of the smb url, which is returned by the url method of the classes mentioned.

Compatibility with Ruby's File and Dir classes
Ruby/SMB aims to be as compatible as possible with Ruby's File and Dir classes. They already do a pretty good job at this (if I may say so ;o), especially the Dir class. Generally, you can assume that the SMB::Dir and SMB::File classes work as you're used to, but check the Library API for notes on incompatibilities and incompletenesses of various methods.

Ruby/SMB is still in alpha, and many things will improve in the time to come, especially if you make bug reports and feature requests at the SourceForge project page or by mail.

back to Ruby/SMB home page

Author: Henrik Falck <hefa at>