Using Samba: A File and Print Server for Linux, Unix & Mac OS X, 3rd Edition

The Samba Team supplies smbclient as a basic part of the Samba suite. At first, it might seem to be a primitive interface to the SMB network, but smbclient is actually a versatile tool. It can be used for browsing shares on servers, testing configurations, debugging, accessing shared printers, backing up shared data, and automating administrative tasks in shell scripts. And unlike smbfs and smbsh , smbclient works on all Unix variants that support Samba.

In this chapter we'll focus mostly on running smbclient as an interactive shell, using its ftp -like commands to access shared directories on the network. Using smbclient to access printers and perform backups will be covered in Chapter 10.

A complete reference to smbclient is found in Appendix C.

5.3.1 Listing Services

The -L option can be used with smbclient to list the resources on a single computer. Assuming the Samba server is configured to take the role of the master browser, we can obtain a list of the computers in the domain or workgroup like this:

$ smbclient -L toltec added interface ip=172.16.1.1 bcast=172.16.1.255 nmask=255.255.255.0 Password: Domain=[METRAN] OS=[Unix] Server=[Samba 2.2.5] Sharename Type Comment --------- ---- ------- test Disk For testing only, please IPC$ IPC IPC Service (Samba 2.2.5) ADMIN$ Disk IPC Service (Samba 2.2.5) Server Comment --------- ------- MAYA Windows 98 MIXTEC Samba 2.2.5 TOLTEC Samba 2.2.5 ZAPOTEC Workgroup Master --------- ------- METRAN TOLTEC

In the column labeled "Server", maya , mixtec , and zapotec are shown along with toltec, the Samba server. The services on toltec are listed under "Sharename". The IPC$ and ADMIN$ shares are standard Windows services that are used for network communication and administrative purposes, and test is the directory we added as a share in Chapter 2.

Now that we know the names of computers in the domain, we can list services on any of those computers. For example, here is how we would list the services offered by maya , a Windows 98 workstation:

$ smbclient -L maya added interface ip=172.16.1.1 bcast=172.16.1.255 nmask=255.255.255.0 Password: Sharename Type Comment --------- ---- ------- PRINTER$ Disk HP Printer HP 932C on Maya D Disk D: on Maya E Disk E: on Maya ADMIN$ Disk IPC$ IPC Remote Inter Process Communication Server Comment --------- ------- Workgroup Master --------- -------

A shared printer is attached to maya , so we see the PRINTER$ administrative service, along with the HP share for the printer itself. Also on maya are the D and E shares, which allow access across the network to maya 's D: and E: drives . It is normal for the Server and Workgroup sections to be empty when listing services on a Windows client.

5.3.2 Authenticating with smbclient

As with any other SMB client, smbclient needs to supply a username and password if it is authenticating in a domain environment or if it is contacting a Samba server that is set up with user -level security. In a workgroup environment, it will at least need a password to use when connecting with a password-protected resource.

By default, smbclient uses the username of the user who runs it and then prompts for a password. If you are using smbclient a lot, you might tire of entering your password every time.

smbclient supports some alternate methods of entering a username and password. The password can be entered on the command line, like this:

$ smbclient //maya/e jayspassword

Or both the username and password can be supplied by using the -U option, including the username and password separated by a percent ( % ) character:

$ smbclient //maya/e -U kelly%kellyspassword

This method is useful if you are logged in to the system under an account that is not Samba-enabled or you are testing your configuration to see how it treats another user. With either method, you can avoid having to enter the username and/or password each time you run smbclient by creating an alias for the command or creating a shell function or shell script. For example, with the bash shell, it is possible to define a function like this:

smbcl( ) { smbclient $* -U jay%jayspassword }

Adding the definition to the shell's startup script (which would be ~/.bash_profile for bash ) would result in the definition affecting all subsequent shell invocations.

Another method that can be used to supply both the username and password is to set the USER and PASSWD environment variables . Either set the USER environment variable using the username % password format, or set the USER environment variable to the username, and set PASSWD to the user's password.

It is also possible to create a credentials file containing the username on the first line and the password on the second line, like this:

username = jay password = jayspassword

Then, smbclient is run using the -A option to specify the name of the file:

$ smbclient //maya/e -A ~/.smbpw

5.3.3 An Interactive smbclient Session

A common use for smbclient is to use it as an ftp -like shell to access SMB resources on the network. To begin a session, smbclient must be provided with the UNC of a resource (which you can find using the -L option) on the command line, like this:

$ smbclient //maya/e added interface ip=172.16.1.3 bcast=172.16.1.255 nmask=255.255.255.0 Password: smb: \>

Forward slashes are accepted by smbclient for the share's UNC, which makes entering the UNC on the command line easier. Backslashes can also be used, but they must be quoted or escaped, and it is somewhat more difficult to type ' \\maya\e ' or \\\\maya\\e . After connecting to the share, smbclient displays the smb: \> prompt, waiting for a command to be entered. Commands are similar to those with which you might be familiar in ftp and are also somewhat similar to Unix shell commands. To get a list of smbclient commands, use the help command:

smb: \> help ls dir du lcd cd pwd get mget put mput rename more mask del open rm mkdir md rmdir rd prompt recurse translate lowercase print printmode queue cancel quit q exit newer archive tar blocksize tarmode setmode help ? history !

Some commands in the previous list are synonyms for other commands. For example, the ? command is a synonym for help . You can give this command the name of another command as an argument to get a concise reminder of what the command does and how to use it:

smb: \> ? ls HELP ls: <mask> list the contents of the current directory

The term <mask> refers to a file-matching pattern as commonly found in Unix shells and utilities. For example:

smb: \> ls *doc ms-ProfPol-wp.doc A 131 Tue Dec 18 09:12:34 2002 smbclient.doc A 33969 Mon Dec 10 20:22:24 2002 smbmount.doc A 7759 Mon Dec 10 20:20:00 2002 48590 blocks of size 524288. 40443 blocks available

lists all files ending in "doc" in the current directory on the remote system. In the listing, the leftmost column shows the filename. Moving left to right, we see the file's MS-DOS attributes, then its size, and the time it was last modified.

As with any other Unix utility, smbclient has a working directory on the local host. It also has another current directory on the remote SMB share. With smbclient , the cd command is used to move around on the remote system:

smb: \> cd trans smb: \trans\>

Notice how the prompt changes to reflect the new current working directory. To change your current directory on the local system, use the lcd command:

smb: \trans\> lcd /u/snd the local directory is now /u/snd

Most of smbclient 's commands are for performing operations on remote files and directories. There is no command for listing the contents of the local directory. However, smbclient allows a shell escape. Any command preceded by an exclamation point ( ! ) is interpreted as a shell command and is run in a subshell on the local system. For example:

smb: \trans\> ! ls -l total 16 drwxrwxr-x 2 jay jay 4096 Jan 10 14:46 dr220-fet drwxrwxr-x 2 jay jay 4096 Sep 22 12:16 dr220-tube -rw-rw-r-- 1 jay jay 131 Jan 10 02:22 readme.txt drwxrwxr-x 7 jay jay 4096 Jan 10 02:19 xl1

lists the contents of /u/snd . By using smbclient 's commands to operate on the remote system ”and shell-escaped commands to operate on the local system ”it is possible to manipulate data on both systems without having to exit smbclient or open another shell window.

File transfer is performed using the get and put commands. The get command transfers a single file from the remote to the local system, and the put command copies a file from the local to the remote system. For example, the following command copies the file readme.txt to the SMB share:

smb: \trans\> put readme.txt putting file readme.txt as \trans\readme.txt (127.9 kb/s) (average 10.7 kb/s)

To transfer more than one file with a single command, you can use the mget and mput commands, which accept a list of filenames in the command line. The list can be provided by typing in the filenames on the command line separated by spaces, or the group of files can be specified with a pattern as one would use in Unix shell commands. The command:

smb: \trans\> mget plain/*

copies all the files in the directory plain on the SMB share to the current directory on the local system. By default, smbclient prompts for each file, asking if you want to copy it:

smb: \trans\> mget plain/* Get file tomm.wav? n Get file toml.wav? n Get file tomh.wav? n Get file snare.wav? n Get file rim.wav? n Get file handclap.wav? n Get file bassdrum.wav? n

If you are sure you want to copy all the files, you can turn off prompting with the prompt command, like this:

smb: \trans\> prompt prompting is now off

By default, if you specify the name of a directory, smbclient will not copy the contents of the directory. To transfer the entire contents of directories listed in the mput or mget command, you must first use the recurse command:

smb: \trans\> recurse directory recursion is now on

After setting things up with the prompt and recurse commands, we can copy a directory like this:

smb: \trans\> mget acc getting file tomm.wav of size 55494 as tomm.wav (2580.6 kb/s) (average 2087.3 kb/s) getting file toml.wav of size 57220 as toml.wav (2660.9 kb/s) (average 2167.6 kb/s) getting file tomh.wav of size 55936 as tomh.wav (2601.2 kb/s) (average 2220.8 kb/s) getting file snare.wav of size 22132 as snare.wav (1200.7 kb/s) (average 2123.7 kb/s) getting file rim.wav of size 8314 as rim.wav (1623.8 kb/s) (average 2110.8 kb/s) getting file handclap.wav of size 14180 as handclap.wav (1978.2 kb/s) (average 2106.2 kb/s) getting file bassdrum.wav of size 6950 as bassdrum.wav (2262.3 kb/s) (average 2108.5 kb/s)

Directory recursion applies to all commands, so if an ls command is used while directory recursion is on, all files in the directory tree are listed. To turn directory recursion off again, simply re-enter the command. At the same time, you might also wish to toggle prompting back to its initial state:

smb: \trans\> recurse directory recursion is now off smb: \trans\> prompt prompting is now on

There are other smbclient commands that you might find useful. The mkdir command can be used to create a directory; rmdir removes a directory; rm deletes a file; and rename changes a file's name. These behave very similarly to their Unix shell counterparts. Appendix C contains a complete reference to smbclient and its command set.

To exit smbclient , use the exit or quit command:

smb: \trans\> quit

5.3.4 Programming with smbclient

The -c option of smbclient allows a list of commands to be passed on the command line. To copy the file \\maya\e\trans\readme.txt to /u/snd/readme.txt , we might use the command:

$ smbclient //maya/e -c "lcd /u/snd; cd trans; get readme.txt" -A ~/.smbpw

Everything that smbclient needs to know to perform the operation has been specified in the command. There is no interactive session, so a command such as this can be placed inside a shell script or a program in some other programming language.

By using smbclient in this manner, it is possible to create customized commands using shell functions, scripts or aliases. For example, suppose we wanted a command to print a short listing of files in a shared directory, showing just the names of the files. Using a bash function, we could define a command smbls as follows :

smbls( ) { share=`echo cut -d '/' -f '1-4'` dir=`echo cut -d '/' -f '5-'` smbclient $share -c "cd $dir; ls" -A ~/.smbpw \ grep "^ " cut -d ' ' -f 3 - sort }

After defining this function, we can use smbls like this:

$ smbls //maya/e CD-images lectures ms-ProfPol-wp.doc profile-map readme.txt RECYCLED smbclient.doc smbmount.doc smbsh.txt trans $ smbls //maya/e/lectures . .. lecture1.mp3 lecture2.mp3 lecture3.mp3 lecture4.mp3 lecture5.mp3 lecture6.mp3 lecture7.mp3 lecture8.mp3 lecture9.mp3

Another use for smbclient in scripts is performing administrative tasks. Suppose a group of users on Windows clients are sharing a set of files as part of a project on which they are working. Instead of expecting them to coordinate making daily backups, we could write a script that copies the share to the Samba server and run the script nightly as a cron job. The directory on the Samba server could be shared as well, allowing any of the users to retrieve a backup file on their own, without having to bother an administrator.

5.3.5 Backups with smbclient

A major use of smbclient is to create and restore backups of SMB file shares. The backup files smbclient writes are in tar format, making them easy to work with and portable among all Unix versions. Using smbclient on a Unix server to run network backups can result in a more centralized and easily managed solution for providing data integrity because both SMB shares and NFS filesystems can be backed up on the same system.

You can use smbclient to perform backups in two ways. When backing up an entire share, the simplest method is to use the -Tc option on the command line:

# smbclient //maya/e -A samba-domain-pw -Tc >maya-e.tar

This will create a tar archive of the \\maya\e share in the file maya-e.tar . By using the -D option, it is possible to back up a directory in the share, rather than the whole share:

# smbclient //maya/e -A samba-domain-pw -D trans -Tc >maya-e.tar

This causes smbclient to change its working directory to the trans directory of the \\maya\e share before starting the backup. It is also possible to use smbclient 's tar command in interactive mode, like this:

# smbclient //maya/e added interface ip=172.16.1.3 bcast=172.16.1.255 nmask=255.255.255.0 Password: smb: \> cd trans smb: \trans\> tarmode full hidden system quiet smb: \trans\> tar c maya-e-trans.tar

With the previous code, only the trans subdirectory in the \\maya\e share will be backed up, using the settings specified in the tarmode command. To have this type of backup run automatically from a script, use the -c option:

# smbclient //maya/e -A samba-domain-pw -c "cd trans; tarmode full hidden \ system quiet; tar >maya-e-trans.tar"

Using either the -T command-line option or smbclient 's tar command, additional options can be supplied. It is necessary to specify either the c option to create a backup archive or the x option to extract (restore) one. ^[1]

^[1] An alternative to extracting the tar archive directly to the SMB share is to use the Unix system's tar command to extract it to a directory on the Unix server, then copy the desired file(s) to a shared directory. This allows a greater amount of control over the restoration process, as when correcting for an accidental file deletion or reverting a set of files to a previous condition.

The other options can be appended to the option string and are explained in the section on smbclient in Appendix C. They allow you to create incremental backups, specify which files to include or exclude from the backup, and specify a few other miscellaneous settings. For example, suppose we wish to create an incremental backup of a share and reset the archive bit on the files to set things up for the next incremental backup. Instead of using the interactive commands:

smb: \> tarmode inc reset quiet smb: \> tar c backup.tar

we could either use the interactive command:

smb: \> tar cgaq backup.tar

or specify the -Tcgaq option on the smbclient command line.

Your best strategy for using smbclient for network backups depends on your local configuration. If you have only a few Windows systems sharing a small amount of data, you might create a script containing smbclient -Tc commands to back up each share to a separate tar file, placing the files in a directory that is included with regular backups of the Unix system. If you have huge SMB shares on your network, you might prefer to write the backup directly to a tape drive. You can do this with smbclient just as you would with a Unix tar command:

# smbclient //maya/d -A samba-domain-pw -Tc >/dev/tape

After you have become more familiar with smbclient and have an automated backup system in place, you might find that using Samba has dramatically decreased your anxiety regarding the integrity of your network's data. The authors of this book are experienced Unix system administrators, and we highly recommend having a backup strategy that has been carefully planned, implemented, and most importantly, tested and known to work as it is supposed to .