smbclient

Name

smbclient — ftp-like client to access SMB/CIFS resources - on servers

Synopsis

smbclient {servicename} [password] [-b <buffer size>] [-d debuglevel] [-D Directory] [-U username] [-W workgroup] [-M <netbios name>] [-m maxprotocol] [-A authfile] [-N] [-l logfile] [-L <netbios name>] [-I destinationIP] [-E] [-c <command string>] [-i scope] [-O <socket options>] [-p port] [-R <name resolve order>] [-s <smb config file>] [-T<c|x>IXFqgbNan] [-k]

DESCRIPTION

This tool is part of the Samba(7) suite.

smbclient is a client that can - 'talk' to an SMB/CIFS server. It offers an interface - similar to that of the ftp program (see ftp(1)). - Operations include things like getting files from the server - to the local machine, putting files from the local machine to - the server, retrieving directory information from the server - and so on.

OPTIONS

servicename

servicename is the name of the service - you want to use on the server. A service name takes the form - //server/service where server - is the NetBIOS name of the SMB/CIFS server - offering the desired service and service - is the name of the service offered. Thus to connect to - the service "printer" on the SMB/CIFS server "smbserver", - you would use the servicename //smbserver/printer -

Note that the server name required is NOT necessarily - the IP (DNS) host name of the server ! The name required is - a NetBIOS server name, which may or may not be the - same as the IP hostname of the machine running the server. -

The server name is looked up according to either - the -R parameter to smbclient or - using the name resolve order parameter in - the smb.conf(5) file, - allowing an administrator to change the order and methods - by which server names are looked up.

password

The password required to access the specified - service on the specified server. If this parameter is - supplied, the -N option (suppress - password prompt) is assumed.

There is no default password. If no password is supplied - on the command line (either by using this parameter or adding - a password to the -U option (see - below)) and the -N option is not - specified, the client will prompt for a password, even if - the desired service does not require one. (If no password is - required, simply press ENTER to provide a null password.) -

Note: Some servers (including OS/2 and Windows for - Workgroups) insist on an uppercase password. Lowercase - or mixed case passwords may be rejected by these servers. -

Be cautious about including passwords in scripts. -

-R <name resolve order>

This option is used by the programs in the Samba - suite to determine what naming services and in what order to resolve - host names to IP addresses. The option takes a space-separated - string of different name resolution options.

The options are :"lmhosts", "host", "wins" and "bcast". They - cause names to be resolved as follows:

lmhosts: Lookup an IP - address in the Samba lmhosts file. If the line in lmhosts has - no name type attached to the NetBIOS name (see - the lmhosts(5) for details) then - any name type matches for lookup.
host: Do a standard host - name to IP address resolution, using the system /etc/hosts -, NIS, or DNS lookups. This method of name resolution - is operating system dependent, for instance on IRIX or Solaris this - may be controlled by the /etc/nsswitch.conf - file). Note that this method is only used if the NetBIOS name - type being queried is the 0x20 (server) name type, otherwise - it is ignored.
wins: Query a name with - the IP address listed in the wins server - parameter. If no WINS server has - been specified this method will be ignored.
bcast: Do a broadcast on - each of the known local interfaces listed in the - interfaces - parameter. This is the least reliable of the name resolution - methods as it depends on the target host being on a locally - connected subnet.

If this parameter is not set then the name resolve order - defined in the smb.conf(5) file parameter - (name resolve order) will be used.

The default order is lmhosts, host, wins, bcast and without - this parameter or any entry in the name resolve order - parameter of the smb.conf(5) file the name resolution - methods will be attempted in this order.

-M NetBIOS name

This options allows you to send messages, using - the "WinPopup" protocol, to another computer. Once a connection is - established you then type your message, pressing ^D (control-D) to - end.

If the receiving computer is running WinPopup the user will - receive the message and probably a beep. If they are not running - WinPopup the message will be lost, and no error message will - occur.

The message is also automatically truncated if the message - is over 1600 bytes, as this is the limit of the protocol. -

One useful trick is to cat the message through - smbclient. For example: - cat mymessage.txt | smbclient -M FRED will - send the message in the file mymessage.txt - to the machine FRED.

You may also find the -U and - -I options useful, as they allow you to - control the FROM and TO parts of the message.

See the message command parameter in the smb.conf(5) for a description of how to handle incoming - WinPopup messages in Samba.

Note: Copy WinPopup into the startup group - on your WfWg PCs if you want them to always be able to receive - messages.

-p port

This number is the TCP port number that will be used - when making connections to the server. The standard (well-known) - TCP port number for an SMB/CIFS server is 139, which is the - default.

-h|--help

Print a summary of command line options. -

-I IP-address

IP address is the address of the server to connect to. - It should be specified in standard "a.b.c.d" notation.

Normally the client would attempt to locate a named - SMB/CIFS server by looking it up via the NetBIOS name resolution - mechanism described above in the name resolve order - parameter above. Using this parameter will force the client - to assume that the server is on the machine with the specified IP - address and the NetBIOS name component of the resource being - connected to will be ignored.

There is no default for this parameter. If not supplied, - it will be determined automatically by the client as described - above.

-E

This parameter causes the client to write messages - to the standard error stream (stderr) rather than to the standard - output stream.

By default, the client writes messages to standard output - - typically the user's tty.

-L

This option allows you to look at what services - are available on a server. You use it as smbclient -L - host and a list should appear. The -I - option may be useful if your NetBIOS names don't - match your TCP/IP DNS host names or if you are trying to reach a - host on another network.

-t terminal code

This option tells smbclient how to interpret - filenames coming from the remote server. Usually Asian language - multibyte UNIX implementations use different character sets than - SMB/CIFS servers (EUC instead of - SJIS for example). Setting this parameter will let - smbclient convert between the UNIX filenames and - the SMB filenames correctly. This option has not been seriously tested - and may have some problems.

The terminal codes include CWsjis, CWeuc, CWjis7, CWjis8, - CWjunet, CWhex, CWcap. This is not a complete list, check the Samba - source code for the complete list.

-b buffersize

This option changes the transmit/send buffer - size when getting or putting a file from/to the server. The default - is 65520 bytes. Setting this value smaller (to 1200 bytes) has been - observed to speed up file transfers to and from a Win9x server. -

-V

Prints the program version number. -

-s <configuration file>

The file specified contains the -configuration details required by the server. The -information in this file includes server-specific -information such as what printcap file to use, as well -as descriptions of all the services that the server is -to provide. See smb.conf for more information. -The default configuration file name is determined at -compile time.

-d|--debug=debuglevel

debuglevel is an integer -from 0 to 10. The default value if this parameter is -not specified is zero.

The higher this value, the more detail will be -logged to the log files about the activities of the -server. At level 0, only critical errors and serious -warnings will be logged. Level 1 is a reasonable level for -day-to-day running - it generates a small amount of -information about operations carried out.

Levels above 1 will generate considerable -amounts of log data, and should only be used when -investigating a problem. Levels above 3 are designed for -use only by developers and generate HUGE amounts of log -data, most of which is extremely cryptic.

Note that specifying this parameter here will -override the log level parameter -in the smb.conf file.

-l|--logfile=logbasename

File name for log/debug files. The extension -".client" will be appended. The log file is -never removed by the client. -

-N

If specified, this parameter suppresses the normal -password prompt from the client to the user. This is useful when -accessing a service that does not require a password.

Unless a password is specified on the command line or -this parameter is specified, the client will request a -password.

-k

-Try to authenticate with kerberos. Only useful in -an Active Directory environment. -

-A|--authfile=filename

This option allows -you to specify a file from which to read the username and -password used in the connection. The format of the file is -

-username = <value>
-password = <value>
-domain   = <value>
-

Make certain that the permissions on the file restrict -access from unwanted users.

-U|--user=username[%password]

Sets the SMB username or username and password.

If %password is not specified, the user will be prompted. The -client will first check the USER environment variable, then the -LOGNAME variable and if either exists, the -string is uppercased. If these environmental variables are not -found, the username GUEST is used.

A third option is to use a credentials file which -contains the plaintext of the username and password. This -option is mainly provided for scripts where the admin does not -wish to pass the credentials on the command line or via environment -variables. If this method is used, make certain that the permissions -on the file restrict access from unwanted users. See the --A for more details.

Be cautious about including passwords in scripts. Also, on -many systems the command line of a running process may be seen -via the ps command. To be safe always allow -rpcclient to prompt for a password and type -it in directly.

-n <primary NetBIOS name>

This option allows you to override -the NetBIOS name that Samba uses for itself. This is identical -to setting the netbios name parameter in the smb.conf file. -However, a command -line setting will take precedence over settings in -smb.conf.

-i <scope>

This specifies a NetBIOS scope that -nmblookup will use to communicate with when -generating NetBIOS names. For details on the use of NetBIOS -scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes are -very rarely used, only set this parameter -if you are the system administrator in charge of all the -NetBIOS systems you communicate with.

-W|--workgroup=domain

Set the SMB domain of the username. This -overrides the default domain which is the domain defined in -smb.conf. If the domain specified is the same as the servers -NetBIOS name, it causes the client to log on using the servers local -SAM (as opposed to the Domain SAM).

-O socket options

TCP socket options to set on the client -socket. See the socket options parameter in -the smb.conf manual page for the list of valid -options.

-T tar options

smbclient may be used to create tar(1) - compatible backups of all the files on an SMB/CIFS - share. The secondary tar flags that can be given to this option - are :

c - Create a tar file on UNIX. - Must be followed by the name of a tar file, tape device - or "-" for standard output. If using standard output you must - turn the log level to its lowest value -d0 to avoid corrupting - your tar file. This flag is mutually exclusive with the - x flag.
x - Extract (restore) a local - tar file back to a share. Unless the -D option is given, the tar - files will be restored from the top level of the share. Must be - followed by the name of the tar file, device or "-" for standard - input. Mutually exclusive with the c flag. - Restored files have their creation times (mtime) set to the - date saved in the tar file. Directories currently do not get - their creation dates restored properly.
I - Include files and directories. - Is the default behavior when filenames are specified above. Causes - tar files to be included in an extract or create (and therefore - everything else to be excluded). See example below. Filename globbing - works in one of two ways. See r below.
X - Exclude files and directories. - Causes tar files to be excluded from an extract or create. See - example below. Filename globbing works in one of two ways now. - See r below.
b - Blocksize. Must be followed - by a valid (greater than zero) blocksize. Causes tar file to be - written out in blocksize*TBLOCK (usually 512 byte) blocks. -
g - Incremental. Only back up - files that have the archive bit set. Useful only with the - c flag.
q - Quiet. Keeps tar from printing - diagnostics as it works. This is the same as tarmode quiet. -
r - Regular expression include - or exclude. Uses regular expression matching for - excluding or excluding files if compiled with HAVE_REGEX_H. - However this mode can be very slow. If not compiled with - HAVE_REGEX_H, does a limited wildcard match on '*' and '?'. -
N - Newer than. Must be followed - by the name of a file whose date is compared against files found - on the share during a create. Only files newer than the file - specified are backed up to the tar file. Useful only with the - c flag.
a - Set archive bit. Causes the - archive bit to be reset when a file is backed up. Useful with the - g and c flags. -

Tar Long File Names

smbclient's tar option now supports long - file names both on backup and restore. However, the full path - name of the file must be less than 1024 bytes. Also, when - a tar archive is created, smbclient's tar option places all - files in the archive with relative names, not absolute names. -

Tar Filenames

All file names can be given as DOS path names (with '\\' - as the component separator) or as UNIX path names (with '/' as - the component separator).

Examples

Restore from tar file backup.tar into myshare on mypc - (no password on share).

smbclient //mypc/yshare "" -N -Tx backup.tar -

Restore everything except users/docs -

smbclient //mypc/myshare "" -N -TXx backup.tar - users/docs

Create a tar file of the files beneath - users/docs.

smbclient //mypc/myshare "" -N -Tc - backup.tar users/docs

Create the same tar file as above, but now use - a DOS path name.

smbclient //mypc/myshare "" -N -tc backup.tar - users\edocs

Create a tar file of all the files and directories in - the share.

smbclient //mypc/myshare "" -N -Tc backup.tar * -

-D initial directory

Change to initial directory before starting. Probably - only of any use with the tar -T option.

-c command string

command string is a semicolon-separated list of - commands to be executed instead of prompting from stdin. - -N is implied by -c.

This is particularly useful in scripts and for printing stdin - to the server, e.g. -c 'print -'.

OPERATIONS

Once the client is running, the user is presented with - a prompt :

smb:\>

The backslash ("\\") indicates the current working directory - on the server, and will change if the current working directory - is changed.

The prompt indicates that the client is ready and waiting to - carry out a user command. Each command is a single word, optionally - followed by parameters specific to that command. Command and parameters - are space-delimited unless these notes specifically - state otherwise. All commands are case-insensitive. Parameters to - commands may or may not be case sensitive, depending on the command. -

You can specify file names which have spaces in them by quoting - the name with double quotes, for example "a long file name".

Parameters shown in square brackets (e.g., "[parameter]") are - optional. If not given, the command will use suitable defaults. Parameters - shown in angle brackets (e.g., "<parameter>") are required. -

Note that all commands operating on the server are actually - performed by issuing a request to the server. Thus the behavior may - vary from server to server, depending on how the server was implemented. -

The commands available are given here in alphabetical order.

? [command]

If command is specified, the ? command will display - a brief informative message about the specified command. If no - command is specified, a list of available commands will - be displayed.

! [shell command]

If shell command is specified, the ! - command will execute a shell locally and run the specified shell - command. If no command is specified, a local shell will be run. -

altname file

The client will request that the server return - the "alternate" name (the 8.3 name) for a file or directory. -

cancel jobid0 [jobid1] ... [jobidN]

The client will request that the server cancel - the printjobs identified by the given numeric print job ids. -

chmod file mode in octal

This command depends on the server supporting the CIFS - UNIX extensions and will fail if the server does not. The client requests that the server - change the UNIX permissions to the given octal mode, in standard UNIX format. -

chown file uid gid

This command depends on the server supporting the CIFS - UNIX extensions and will fail if the server does not. The client requests that the server - change the UNIX user and group ownership to the given decimal values. Note there is - currently no way to remotely look up the UNIX uid and gid values for a given name. - This may be addressed in future versions of the CIFS UNIX extensions. -

cd [directory name]

If "directory name" is specified, the current - working directory on the server will be changed to the directory - specified. This operation will fail if for any reason the specified - directory is inaccessible.

If no directory name is specified, the current working - directory on the server will be reported.

del <mask>

The client will request that the server attempt - to delete all files matching mask from the current working - directory on the server.

dir <mask>

A list of the files matching mask in the current - working directory on the server will be retrieved from the server - and displayed.

exit

Terminate the connection with the server and exit - from the program.

get <remote file name> [local file name]

Copy the file called remote file name from - the server to the machine running the client. If specified, name - the local copy local file name. Note that all transfers in - smbclient are binary. See also the - lowercase command.

help [command]

See the ? command above.

lcd [directory name]

If directory name is specified, the current - working directory on the local machine will be changed to - the directory specified. This operation will fail if for any - reason the specified directory is inaccessible.

If no directory name is specified, the name of the - current working directory on the local machine will be reported. -

link source destination

This command depends on the server supporting the CIFS - UNIX extensions and will fail if the server does not. The client requests that the server - create a hard link between the source and destination files. The source file - must not exist. -

lowercase

Toggle lowercasing of filenames for the get and - mget commands.

When lowercasing is toggled ON, local filenames are converted - to lowercase when using the get and mget commands. This is - often useful when copying (say) MSDOS files from a server, because - lowercase filenames are the norm on UNIX systems.

ls <mask>

See the dir command above.

mask <mask>

This command allows the user to set up a mask - which will be used during recursive operation of the mget and - mput commands.

The masks specified to the mget and mput commands act as - filters for directories rather than files when recursion is - toggled ON.

The mask specified with the mask command is necessary - to filter files within those directories. For example, if the - mask specified in an mget command is "source*" and the mask - specified with the mask command is "*.c" and recursion is - toggled ON, the mget command will retrieve all files matching - "*.c" in all directories below and including all directories - matching "source*" in the current working directory.

Note that the value for mask defaults to blank (equivalent - to "*") and remains so until the mask command is used to change it. - It retains the most recently specified value indefinitely. To - avoid unexpected results it would be wise to change the value of - mask back to "*" after using the mget or mput commands.

md <directory name>

See the mkdir command.

mget <mask>

Copy all files matching mask from the server to - the machine running the client.

Note that mask is interpreted differently during recursive - operation and non-recursive operation - refer to the recurse and - mask commands for more information. Note that all transfers in - smbclient are binary. See also the lowercase command.

mkdir <directory name>

Create a new directory on the server (user access - privileges permitting) with the specified name.

mput <mask>

Copy all files matching mask in the current working - directory on the local machine to the current working directory on - the server.

Note that mask is interpreted differently during recursive - operation and non-recursive operation - refer to the recurse and mask - commands for more information. Note that all transfers in smbclient - are binary.

print <file name>

Print the specified file from the local machine - through a printable service on the server.

NOTES

Some servers are fussy about the case of supplied usernames, - passwords, share names (AKA service names) and machine names. - If you fail to connect try giving all parameters in uppercase. -

It is often necessary to use the -n option when connecting - to some types of servers. For example OS/2 LanManager insists - on a valid NetBIOS name being used, so you need to supply a valid - name that would be known to the server.

smbclient supports long file names where the server - supports the LANMAN2 protocol or above.

ENVIRONMENT VARIABLES

The variable USER may contain the - username of the person using the client. This information is - used only if the protocol level is high enough to support - session-level passwords.

The variable PASSWD may contain - the password of the person using the client. This information is - used only if the protocol level is high enough to support - session-level passwords.

The variable LIBSMB_PROG may contain - the path, executed with system(), which the client should connect - to instead of connecting to a server. This functionality is primarily - intended as a development aid, and works best when using a LMHOSTS - file

INSTALLATION

The location of the client program is a matter for - individual system administrators. The following are thus - suggestions only.

It is recommended that the smbclient software be installed - in the /usr/local/samba/bin/ or - /usr/samba/bin/ directory, this directory readable - by all, writeable only by root. The client program itself should - be executable by all. The client should NOT be - setuid or setgid!

The client log files should be put in a directory readable - and writeable only by the user.

To test the client, you will need to know the name of a - running SMB/CIFS server. It is possible to run smbd(8) as an ordinary user - running that server as a daemon - on a user-accessible port (typically any port number over 1024) - would provide a suitable test server.

DIAGNOSTICS

Most diagnostics issued by the client are logged in a - specified log file. The log file name is specified at compile time, - but may be overridden on the command line.

The number and nature of diagnostics available depends - on the debug level used by the client. If you have problems, - set the debug level to 3 and peruse the log files.

VERSION

This man page is correct for version 2.2 of the Samba suite.

AUTHOR

The original Samba software and related utilities - were created by Andrew Tridgell. Samba is now developed - by the Samba Team as an Open Source project similar - to the way the Linux kernel is developed.

The original Samba man pages were written by Karl Auer. - The man page sources were converted to YODL format (another - excellent piece of Open Source software, available at - ftp://ftp.icce.rug.nl/pub/unix/) and updated for the Samba 2.0 - release by Jeremy Allison. The conversion to DocBook for - Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 for Samba 3.0 - was done by Alexander Bokovoy.