5.6 smbutil and mount_smbfs

The smbutil and mount_smbfs programs provide SMB client functionality for FreeBSD, Darwin, and Mac OS X. Neither of the programs is part of the Samba distribution; however, we are including them to give you a little additional support in case you have BSD- related Unix systems on your network.

5.6.1 smbutil

The smbutil program provides functionality similar to some of the Samba suite's command-line utilities. It can be used to list the shares available on an SMB server or perform NetBIOS name lookups.

The first argument given to smbutil is one of a number of subcommands and is usually followed by arguments specific to the subcommand. For example, to list the resources offered by a server, use the view subcommand, and enter your server password when prompted:

 %  smbutil view //vamana  Password: Share        Type        Comment ------------------------------------------------------------- public        disk SS2500        printer     Stylus Scan 2500 IPC$          pipe        IPC Service (Samba 2.2.5) ADMIN$        disk        IPC Service (Samba 2.2.5) leonvs        disk        User Home Directories 5 shares listed from 5 available 

If you wish to connect to the server with a username that differs from that on your client, you can specify it on the command line by preceding the name of the server with the username and using an at sign ( @ ) as a separator:

 %  smbutil view //leonvs@vamana  

You can also include the password after the username, using a colon (:) as a separator, to avoid being prompted for it:

 %  smbutil view //leonvs:leonspassword@vamana  

Typing your password in the open like this is strongly discouraged. It's a little better if you use an encrypted password, which you can generate using smbutil 's crypt subcommand:

 %  smbutil crypt leonspassword  $25a5723293f0710e5faffcfc6 

This can then be used in place of a clear-text password. However, the encryption is not particularly strong and will foil only the most casual inspection. As noted earlier, the only reasonably secure method of providing a password is to be prompted for it.

While starting up, smbutil reads the file .nsmbrc in the user's home directory. Also, the file /usr/local/etc/nsmb.conf is read, and directives in that file override those in users' ~/.nsmbrc files. This is to allow administrators to apply mandatory settings to all users. Directives can be placed in this file using the section and parameter format similar to that of the Samba configuration file. A list of common configuration parameters is given in Table 5-2.

For example, to keep your password in your ~/.nsmbrc file, you can create an entry in the file such as the following:

 [VAMANA:LEONVS]     password=$25a5723293f0710e5faffcfc6 

The section heading in brackets specifies the SMB server's NetBIOS name and the username to which the subsequent parameter settings apply. (The hostname and username should be supplied in uppercase characters .) Section headings can also consist of just a hostname or can contain a share name as a third element for specifying parameters applicable to a single share. Finally, if a [default] section is present, the settings in it apply to all connections.

The following example .nsmbrc shows some of the other parameters you might use:

 [default]     username=leonvs     # NetBIOS name server     nbns=192.168.1.3 [VAMANA]     # server IP address     addr=192.168.1.6     workgroup=TEST [VAMANA:LEONVS]     password=$25a5723293f0710e5faffcfc6 

Another thing you can do with smbutil is translate between IP addresses or DNS names and NetBIOS names . For example, the status subcommand takes an IP address or DNS hostname as an argument and returns the corresponding SMB server's NetBIOS name and workgroup:

 %  smbutil status 192.168.1.6  Workgroup: TEST Server: VAMANA 

The lookup subcommand returns the IP address associated with a given NetBIOS hostname. A NetBIOS name server can be optionally specified with the -w argument:

 %  smbutil lookup -w 192.168.1.3 VAMANA  Got response from 192.168.1.3 IP address of VAMANA: 192.168.1.6 

5.6.2 mount_smbfs

The mount_smbfs program performs essentially the same function as smbmount on Linux. It mounts an SMB share on a directory in the local filesystem. The SMB share can then be accessed just like any other directory, subject to some behavioral differences noted earlier in Section 5.4.1.

The command synopsis for mount_smbfs is:

 mount_smbfs   [options]     Share-UNC     mount-point   

where Share-UNC is of the form:

 //[   workgroup   ;][   username   [:   password   ]@]   server   [/   share   ] 

For example:

 #  mount_smbfs '//TEST;leonvs:$25a5723293f0710e5faffcfc6@vamana/leonvs' /  \  Volumes/leonvs  

The ownership and permissions of the mount point determine the default ownership and permissions for files and directories in the mounted share. These can be modified with command-line arguments, like this:

 #  mount_smbfs -u leonvs -g admin -f 0750 -d 0755 //leonvs@vamana/leonvs  \  /Volumes/leonvs  

In this example, the files and directories in the mounted share will be owned by the user leonvs and the group admin, with files and directories having permissions 750 and 755, respectively. (As usual, the permissions are specified in the octal format used by the Unix chmod command.)

The mount_smbfs command also makes use of settings in /usr/local/etc/nsmb.conf and ~/.nsmbrc , as described earlier. A list of common configuration parameters and command-line options is provided in Table 5-2.

Table 5-2. Common smbutil and mount_smbfs options

Command-line option	Configuration file parameter	Description
-I hostname	addr	Avoid NetBIOS name resolution and connect to the server using the specified DNS hostname or IP address.
-N	none	Do not prompt for a password.
-R count	retry_count	Number of times to retry connection before giving up.
-T seconds	timeout	Timeout, in seconds, per connection request.
-U username	username	Username to use for authentication. Defaults to Unix username.
-W workgroup	workgroup	Name of workgroup of remote server.
-d mode	none	Permissions to apply to directories in the mounted share. Defaults to the same as the file permissions, plus an execute (search) bit whenever the read bit is set.
-f mode	none	Permissions to apply to files in the mounted share. Defaults to the same as the permissions set on the directory used as the mount point.
-g group	none	Name or numeric GID to apply to all files and directories in the mounted share. Defaults to the group of the directory used as the mount point.
-n long	none	Disable support for long filenames. Restrict filenames to 8.3 naming standard.
-u username	none	Username or numeric UID to apply as the owner of all files and directories in the mounted share. Defaults to the owner of the directory used as the mount point.
-w hostname	nbns	Hostname or IP address of the NetBIOS name server.
none	password	Password to use for authentication.

5.6.3 Mac OS X

In addition to smbutil and mount_smbfs , OS X includes a graphical interface to the functionality they provide. To use this interface, open the Go menu and select the Connect to Server . . . menu item. Instead of using a UNC, specify the share in the form of a Uniform Resource Identifier (URI) with a prefix of smb:// entered in the Address field, as shown in Figure 5-5.

Figure 5-5. OS X Connect to Server dialog

You can specify a server, share, workgroup, username, and password (optionally encrypted with smbutil crypt ) in the URI, in the same format as the UNC argument to mount_smbfs . If you don't specify a share name in the URI, you will be shown a window that lets you choose from a list of shares available to mount. See Figure 5-6.

Figure 5-6. Selecting a share to mount

Only guest-accessible shares will show up in the list until you've authenticated. After pressing the Authenticate button, you'll be prompted for a workgroup, username, and password, as shown in Figure 5-7. You'll also see this dialog if you provide a share name in the URI, but not a username and password. ^[4]

^[4] If you've previously stored your authentication information in a Keychain, you will instead be prompted for your Keychain password.

Figure 5-7. Client authentication

As usual for Mac OS X, shares are mounted under /Volumes , but show up in the root of the Finder hierarchy.

If you have a WINS server on your network, you can provide the server's IP address in the Directory Access application, or by using the wins server parameter in /etc/smb.conf .

If you don't know the name of a server to which you wish to connect, you can look for it in the browse list, using the graphical frontend to the nmblookup command provided with Samba. Click the downward-pointing arrow in the Connect to Server . . . dialog box to show a hierarchical, column-based view of available workgroups and servers, similar to that shown in Figure 5-8. If your client is also acting as an SMB file server, it won't show up in its own browse list.

Figure 5-8. Browsing the network