MikeTeo.net

A Software Technologist's Blog (Wanna Email Me?)

pysmb

June 9, 2009 By miketeo
 

pysmb is an experimental SMB/CIFS library written in Python. It implements the client-side SMB/CIFS protocol (SMB1 and SMB2) which allows your Python application to access and transfer files to/from SMB/CIFS shared folders like your Windows file sharing and Samba folders.

If you use pysmb in your applications, please drop me a comment at the bottom of this page to let me and the others know of what you have done using pysmb. Thanks.

What It Can Do

From version 1.0.0, pysmb has been completely rewritten and has been tested to be able to login to and upload/download files from shared folders on Samba, Windows XP, Windows Vista and Windows 7 machines. For more information on how to write your own file transfer applications using pysmb, please refer to the online documentation at python.org or check out the documentation in the 1.0 source files.

What It Can’t Do

Note that this is only a client library. It does not share files.

Downloads

If you have problems opening tar.gz files in Windows, please install 7-Zip. It supports 7z, ZIP, GZIP, BZIP2, TAR and many other archive formats.

Version 1.1.3, 2013-03-18 (Download)

  • Fix a bug which results in endless loop in SMBConnection when remote CIFS server closes the connection. Thanks to Nitin Garg for submitting the bug fixes.

Version 1.1.2, 2012-09-28 (Download)

  • Improve queryIPForName() in nmb.NetBIOS and nmb.NBNSProtocol class to return only server machine name and ignore workgroup names.

Version 1.1.1, 2012-06-09 (Download)

  • Adds support for Python3. Noted that the Python3 SMB/NMB protocol implementations for Twisted are not well-tested as Twisted (as of v12.1) is not Python3 ready yet.
  • Adds support for retrieving list of shadow copies (also known as “previous versions” in Windows). Note that not all Windows editions support shadow copies.

Version 1.1.0, 2012-06-01 (Download)

  • Adds SMB2 protocol implementation with signing for outgoing SMB2 messages. pysmb will utilize SMB2 protocol with servers that support SMB2 protocol (eg. Windows Vista, Windows 7 and Samba 3).  If the remote server does not support SMB2, pysmb will fall back automatically to using SMB1 protocol.

Version 1.0.5, 2012-05-07 (Download)

  • Add supports for SMB message signing. pysmb can sign SMB messages from the CIFS client to the server, but it does not verify the signatures of the  SMB messages from the server.

Version 1.0.4, 2012-05-01 (Download)

  • Adds support for “smb://” URL in urllib2 python packages to retrieve or upload files from/to remote CIFS servers.
  • Improve documentation

Version 1.0.3, 2012-04-28 (Download)

  • Fix a crash in SMB._storFile() method which occurs when the remote CIFS server utilizes a max raw size larger than 65535 bytes. The bug was discovered with  Windows 7 Pro SP1. Thanks to Bram Deprettere for submitting the bug report.
  • Fix a bug in SMB._listPath() method where the files/folders time information are not properly converted to Epoch time. Thanks to John Lau for discovering this bug.
  • Add NBNSProtocol.queryIPForName() and NetBIOS.queryIPForName() methods to query for a machine’s NetBIOS name at the given IP address. Thanks to Jason Anderson for providing the initial implementation.
  • Add SMBProtocol.retrieveFileFromOffset() and SMBConnection.retrieveFileFromOffset() methods for a finer control of file retrieval operation with read offset and write limits.

Version 1.0.2, 2012-03-25 (Download)

  • Fix a bug in SMB._handleSessionChallenge() method in base.py where the domain attribute was not used to generate the corresponding NTLM authentication packets, resulting in the default WORKGROUP domain for used for all subsequent authentications. Thanks to John Lau for submitting the bug report.

Version 1.0.1, 2012-01-25 (Download)

  • Fixes a bug in listPath() method which causes directory listing for sub-directories to return an empty list.
  • Fixes an incorrect implementation of the TRANS2_FIND_FIRST2 and TRANS2_FIND_NEXT2 request/response handling which causes directory listing to crash when the remote directory contains a certain number of entries.

Version 1.0.0a, 2011-12-30 (Download)

  • Completely rewrites pysmb. API is not compatible with previous pysmb-0.x.x
  • Supports NTLMv1 and NTLMv2 authentication
  • Adds in NMB/SMB protocol implementation for use with Twisted framework
  • Tested with Windows XP SP3, Windows Vista, Windows 7 and Samba 3.x
  • Requires Python 2.4.4 or later, and pyasn1. Not tested with Python3
  • Fixes a bug in previous release (1.0.0) where the package was not built properly and had missing files. (Many thanks to Adrian Klaver for pointing this out)

Version 0.4.5, 2009-06-22 (Download)

  • Prevents pysmb from failing when there are too many files/folders to
    be returned in a single SMB TRANS2 call. pysmb will “resume” requesting
    for more files/folders information in subsequent SMB TRANS2 requests.

Version 0.4.4, 2004-01-12 (Download)

  • Add in support for AMK’s Python Cryptography Toolkit which will be used for DES password hashing. If AMK’s pycrypto is found, it will be used instead of mxCrypto.

Version 0.4.3, 2003-02-22 (Download)

  • Fix a bug which fails to close the socket in nmb.py on socket exception
  • Fix a bug which fails to close the NetBIOSSession in smb.py if the session has not been properly established yet

Version 0.4.2, 2002-08-03 (Download)

  • Add new methods to SharedFile instances, get_mtime_epoch, get_atime_epoch and get_ctime_epoch. These methods will return the mtime, atime and ctime in epoch time rather than SMB time.
  • Remove debugging printout in smb.py which has been released accidentally with the last release.
  • Fix a bug in smbcp which causes to local to remote copy to fail

Version 0.4.1, 2002-06-22 (Download)

  • Fix a bug in smb.py which does not return the correct file size for files with their archive bits turned off. This results in these files not being retrieved or sent properly.
  • Fix some typo error in the documentations

Version 0.4.0, 2002-04-17 (Download)

  • Use NT LM0.12 dialect.
  • New smb.SMBMachine class
  • Add SMB.get_server_domain(), smb.get_server_os(), SMB.get_server_lanman()

Version 0.3.1, 2001-11-12 (Download)

  • Fix a problem with some Windows server where an UID is required when server is in share mode.  Now, pysmb calls login() with empty authentication information when server is in share mode.
  • Add TYPE_DOMAIN_MASTER constant and description to nmb.py.

Version 0.3.0, 2001-11-10 (Download)

  • Add support for services in share mode. Minor changes to smb.SMB class API.
  • Fix a bug in smb.py’s __raw_retr_file which has failed to initialize the max_buf_size prior to usage.
  • Fix a bug in smblistshare which fails to print the correct NMB error message
  • Modify smb.py not throw AttributeError in the destructor when there is an error while creating a session in the constructor

Version 0.2.0, 2001-10-04 (Download)

  • Add support for encrypted authentication using DES
  • Fix a bug(?) which treats all services and filenames as case-sensitive

Version 0.1.3, 2001-09-03 (Download)

  • Fix a bug in smblistshare and smbdu which fails to catch the nmb.NetBIOSError raised when session setup fails.
  • Fix a bug in smb.SMB that arises from the change in nmb.NetBIOSSession which sends the session port number as the remote host type.
Version 0.1.2, 2001-09-01 (Download)
  • Fix a bug in nmb.NetBIOSSession which specifies a TYPE_WORKSTATION for remote host instead of TYPE_SERVER.
  • Minor change to nmb.NetBIOSSession constructor API.
  • Fix a bug in smbdu which raises OverflowError when printing long file size values.
  • Fix a bug in smbcp which does not handle the destination path correctly when the source file is copied to a different filename.
Version 0.1.1, 2001-08-25 (Download)
  • Change nmb’s NetBIOS and NetBIOSSession class such that they raise a NetBIOSError with a tuple of ( err_msg, err_class, err_code )
  • Add a function strerror() in both smb and nmb to return human readable messages for error codes.
  • Fix a bug in smbcp which fails to print an error message and terminate when the remote source path is not found.
  • Add in another utility, smblistshare.
Version 0.1.0, 2001-08-20 (Download)
  • First public release
  1. MikeTeo.net » Blog Archive » pysmb 0.4.5 released! Said,

    [...] more information, please visit: http://miketeo.net/wp/index.php/projects/pysmb Bookmark This Rattle… Posted in: Python, Software Development ADD [...]

  2. Thorsten Kaufmann Said,

    Hi Mike,

    great piece of code and seems to work pretty flawlessly. Just one minor thing i would love to do is reuse an existing connection to a smb server. So on windows once you are logged in on a server with say explorer it wouldnt re-need authentication and would reuse the windows connection. Is that possible and how would i go about it ?

    Kind Regards and thanks in advance,
    Thorsten

  3. nevdull Said,

    i’ve been searching for a python netbios name resolution module, and came across pysmb. just what i needed- native python and lightweight, thanks.

    also, wanted to let you know that i found a small error while testing NetBIOS.gethostbyname(). if a wins server returns multiple nodes in response to a query, each node is 6 bytes long: 2 bytes for flags followed by 4 bytes for the ip address. however, the code only increments by 4 bytes if multiple modes are found.

    for i in range(0, num_records):
    # In Python2, we can use socket.inet_ntoa(data[58 + i * 4:62 + i * 4]) to convert
    addrs.append(NBHostEntry(string.rstrip(qn_name[:-1]) + qn_scope, ord(qn_name[-1]), ‘%d.%d.%d.%d’ % unpack(’4B’, (data[offset:offset + 4]))))
    offset = offset + 4

    changing the offset increment to “offset = offset + 6″ solves the problem. no idea how accurate this is across all versions and types of query responses, especially since the response record contains the data length (in this case 12 when 2 unique h-records are returned).

    anyways thanks..

  4. lrq3000 Said,

    As I had to make an automatic backup script uploading to a SMB share, I chose your tool as the base for my work, but I had some troubles making it work since the terminology in the documentation is somewhat obscure and no working example is provided.

    Here is a simple python script example :

    #!/bin/env python

    # Author : Stephen LARROQUE

    # DESCRIPTION : simple python script to demonstrate the use of the pysmb library to connect to a Samba share and send a file. This could be useful for other devs, as there are nearly no documentation on the web, and all other solutions aren’t as versatile and interoperable as this one (it should work on any plateform)

    import smb, nmb, getpass, os;

    fileshare = smb.SMB(‘YOURSMBHOSTNAME’, ‘YOURSMBHOSTIP’, my_name = “THEMATRIX”, host_type = nmb.TYPE_SERVER, sess_port = nmb.NETBIOS_SESSION_PORT);
    fileshare.login(‘yourlogin’, ‘password’)
    #fileshare.stor_file(‘Call’, remote_path+filename, sz.read)
    serveros = fileshare.get_server_os();
    print serveros;

    if (fileshare.is_login_required()) :
    print “Login is required on this server.”;

    print fileshare.list_shared();

    if (fileshare.list_path(“SMBSHAREMOUNT”, “PATH\*”)) :
    print “Dir exists !”;

    src_path = ‘D:/test.txt’;
    dest_service = “SMBSHAREMOUNT”;
    dest_path = “PATH/test11.txt”;
    fh = open(src_path, ‘rb’);
    fileshare.stor_file(dest_service, dest_path, fh.read);
    fh.close();

  5. nevdull Said,

    hi, found another minor error, when querying a node for its status. for instance, if you want to verify the IP returned by a name query sent to a WINS server is not a stale or tombstoned reference. -query the returned IP for its nbname and check that against the original name query, (if they match all is well). in this case setting the recursion bit against a client will cause status request to be ignored.

    so, within __querynodestatus()

    if destaddr:
    req = pack(‘>HHHHHH’, trn_id, 0×0100, 0×01, 0×00, 0×00, 0×00) + qn_label + pack(‘>HH’, 0×21, 0×01)
    else:
    req = pack(‘>HHHHHH’, trn_id, 0×0110, 0×01, 0×00, 0×00, 0×00) + qn_label + pack(‘>HH’, 0×21, 0×01)

    change the flags word from 0×0100 to 0×000 when destaddr is set and from 0×0110 to 0×0010 when it is not set.

  6. Sujit Ghosal Said,

    Does this module handle SMB Chaining as well? Even though I didn’t go through all of the modules functions/classes I just wanted to know before I start working on it.

    - Sujit

  7. Filoxb Said,

    Hello boys,
    pysmb is awesome, but if i try to use it on a shared folder with password encryption it fails(xp, linux or others)!!!
    Does it really support pasword encryption? Is there a correct way to encrypt a password?

    Please please please help!!!!!!

    Thanks

  8. Stef Bon Said,

    Hi,

    I’m looking for an example to lookup the hosts in my network. Where can I find it?

    S.

  9. miketeo Said,

    @Stef Bon:
    You can try the following code with pysmb-1.0.4 and above. You may need administrator privilege to run the queryName() method.

    from nmb.NetBIOS import NetBIOS

    n = NetBIOS()
    print n.queryName('CETUS')
    print n.queryIPForName('192.168.1.2')

  10. Bob Said,

    Any ideas why same code will work against a samba server but not a Win7 system? Using smbclient I can auth and browse files on the Win7 system but with pysmb I get the following error on OSX:

    Traceback (most recent call last):
    File “”, line 1, in
    File “/Users/tanner/projects/clients/igi.com/scripts/sandbox/lib/python2.7/site-packages/smb/SMBConnection.py”, line 97, in connect
    self._pollForNetBIOSPacket(timeout)
    File “/Users/tanner/projects/clients/igi.com/scripts/sandbox/lib/python2.7/site-packages/smb/SMBConnection.py”, line 446, in _pollForNetBIOSPacket
    d = self.sock.recv(read_len)
    socket.error: [Errno 54] Connection reset by peer

  11. tuckmeng Said,

    Hi,

    I keep getting a No module called _md5 when I do a from smb import SMBHandler. Wonder if there’s anything missing? I’m using AIX

  12. Vashek Said,

    Hi, thanks for this great piece of work!
    Is there a bug tracker somewhere?
    It works fine for me, except for one thing: if I specify the server name as something that points to the right IP address but is not the hostname of the server (e.g. if I specify the IP address itself), the SMBConnection gets into an infinite loop somewhere and uses 100% CPU.

    Thanks again,
    Vashek

  13. miketeo Said,

    @Vashek: No, there is no bug tracker for pysmb. Most developers usually email me directly for support, or use this comment section for bugs reporting. I have taken note of the bug you have mentioned, and will attempt to fix it in the next release. Thanks.

  14. Ramakrishna Said,

    Hi Mike,

    Found this tool interesting. Thanks for developing and supporting this great work.

    We work on the SMB Protocol optimization and looking for an open source test tool for unit testing purposes during development.

    Can we use this tool to write customized smb protocol test scripts.

    Looking forward to hear your inputs.

  15. miketeo Said,

    @Ramakrishna: Yes, you can.

  16. Nitin Said,

    Hi Mike!
    Thanks for the awesome module. I have a couple of doubts though:

    1. Once a connection is made (using SMBConnection and connect method), how long does the connection last?
    2. How are the read/write calls to the CIFS server authenticated? Through a sesssion or are username and password passed along every time?

    Regards

  17. miketeo Said,

    @Nitin:
    1. In development, most servers drop the connection after being idle for about 5 minutes. As documented, you should not keep the SMBConnection “idle” if you are not using it.
    2. The authentication is performed once during session setup during which the user name and password are transmitted in a secure manner. The authentication is not performed during file operations.

  18. Nitin Said,

    Thanks for the prompt reply! Follow up questions :)

    So when the connection is made, does the server pass some kind of session token or session ID to the client? And then the client passes that token during file operations? If so, where is this ID/token stored?

    OR the server creates a session and keeps the information to itself and validates incoming requests based on IP address? And upon 5 minutes of inactivity, destroys the session?

  19. miketeo Said,

    @Nitin: When the connection is established, the SMB client and server engage in a session negotiation phase which determines the variant of SMB protocol (aka SMB dialect) and also involves authenticating the remote SMB client. The session information is only useful within the authentication communication and is not being used directly in subsequent file operations. When the TCP connection is closed, the remote SMB client will need to perform the session negotiation and authentication again when it re-connects back to the server.

  20. Nitin Said,

    Thanks again. And lastly I want to ask: Is there any support to connect using Active Directory’s UPNs (User Principal Names) like username@domain? I tried putting the username and domain parameters in the constructor, but it didn’t work.

    SMBConnection(username, password, my_name, remote_name, domain=”, use_ntlm_v2=True, sign_options=2)

    Actually I tried UPN with the smbclient command too, but that didn’t work either. So SMB doesn’t allow connections using UPNs?

  21. miketeo Said,

    @Nitin:
    I have heard that one of the pysmb users had used pysmb to authenticate against AD successfully.

  22. Nitin Said,

    Someone posted this in Nov last year, and I’m facing the same issue now: http://stackoverflow.com/questions/13252443/pysmb-windows-file-share-buffer-overflow

    Interestingly it happens only after I create a new share on the server.
    FYI: Client is a CentOS 5 machine and the server is a Win 2008 R2.

  23. miketeo Said,

    @Nitin: Can you send me the tcpdump of the communication using ethereal?

  24. Nitin Said,

    Hey Mike, sorry about the late reply. I’m not using listShares anymore, but I’ll send you the tcpdump soon if possible.

    Meanwhile, is there any way that listPath can return the list in batches. E.g. a folder has 1 million files, and I want the server to return the list in batches of 100. Because returning all the 1 million items together takes up too much time. I don’t see any such options for listPath in the documentation, but is it possible to play with the underlying code to make this possible?

  25. miketeo Said,

    @Nitin:
    The SMBConnection class does not support asynchronous operations. You might want to look into the SMBProtocolFactory (which uses Twisted framework) and subclass the listPath method implementation in the SMBProtocol to incorporate your batched retrieval needs.

  26. Nitin Said,

    Hi Mike,

    Does pysmb support SMB communications directly over TCP, port 445?

    If not, is there any way to get pysmb working with a server that doesn’t support NetBIOS?

  27. miketeo Said,

    @Nitin: As of pysmb 1.1.3, pysmb does not support direct SMB over TCP. There are some modifications required to bypass the NetBIOS session setup and add in some shim NetBIOS session headers for this to work.

Add A Comment