1 .\" This manpage has been automatically generated by docbook2man-spec
2 .\" from a DocBook document. docbook2man-spec can be found at:
3 .\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/>
4 .\" Please send any bug reports, improvements, comments, patches,
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH SMBCLIENT 1 "23 Jun 2001" "smbclient 2.2.0a"
8 smbclient \- ftp-like client to access SMB/CIFS resources on servers
11 \fBsmbclient\fR \fBservicename\fR [ \fBpassword\fR ] [ \fB-b <buffer size>\fR ] [ \fB-d debuglevel\fR ] [ \fB-D Directory\fR ] [ \fB-S server\fR ] [ \fB-U username\fR ] [ \fB-W workgroup\fR ] [ \fB-M <netbios name>\fR ] [ \fB-m maxprotocol\fR ] [ \fB-A authfile\fR ] [ \fB-N\fR ] [ \fB-l logfile\fR ] [ \fB-L <netbios name>\fR ] [ \fB-I destinationIP\fR ] [ \fB-E <terminal code>\fR ] [ \fB-c <command string>\fR ] [ \fB-i scope\fR ] [ \fB-O <socket options>\fR ] [ \fB-p port\fR ] [ \fB-R <name resolve order>\fR ] [ \fB-s <smb config file>\fR ] [ \fB-T<c|x>IXFqgbNan\fR ]
14 This tool is part of the Sambasuite.
16 \fBsmbclient\fR is a client that can
17 \&'talk' to an SMB/CIFS server. It offers an interface
18 similar to that of the ftp program (see \fBftp(1)\fR).
19 Operations include things like getting files from the server
20 to the local machine, putting files from the local machine to
21 the server, retrieving directory information from the server
26 servicename is the name of the service
27 you want to use on the server. A service name takes the form
28 \fI//server/service\fR where \fIserver
29 \fRis the NetBIOS name of the SMB/CIFS server
30 offering the desired service and \fIservice\fR
31 is the name of the service offered. Thus to connect to
32 the service "printer" on the SMB/CIFS server "smbserver",
33 you would use the servicename \fI//smbserver/printer
35 Note that the server name required is NOT necessarily
36 the IP (DNS) host name of the server ! The name required is
37 a NetBIOS server name, which may or may not be the
38 same as the IP hostname of the machine running the server.
40 The server name is looked up according to either
41 the \fI-R\fR parameter to smbclient or
42 using the name resolve order parameter in the smb.conf file,
43 allowing an administrator to change the order and methods
44 by which server names are looked up.
47 The password required to access the specified
48 service on the specified server. If this parameter is
49 supplied, the \fI-N\fR option (suppress
50 password prompt) is assumed.
52 There is no default password. If no password is supplied
53 on the command line (either by using this parameter or adding
54 a password to the \fI-U\fR option (see
55 below)) and the \fI-N\fR option is not
56 specified, the client will prompt for a password, even if
57 the desired service does not require one. (If no password is
58 required, simply press ENTER to provide a null password.)
60 Note: Some servers (including OS/2 and Windows for
61 Workgroups) insist on an uppercase password. Lowercase
62 or mixed case passwords may be rejected by these servers.
64 Be cautious about including passwords in scripts.
67 Specifies the location of the all important
70 \fB-O socket options\fR
71 TCP socket options to set on the client
72 socket. See the socket options parameter in the \fI smb.conf (5)\fR manpage for the list of valid
75 \fB-R <name resolve order>\fR
76 This option is used by the programs in the Samba
77 suite to determine what naming services and in what order to resolve
78 host names to IP addresses. The option takes a space separated
79 string of different name resolution options.
81 The options are :"lmhosts", "host", "wins" and "bcast". They
82 cause names to be resolved as follows :
86 lmhosts : Lookup an IP
87 address in the Samba lmhosts file. If the line in lmhosts has
88 no name type attached to the NetBIOS name (see the lmhosts(5)for details) then
89 any name type matches for lookup.
92 host : Do a standard host
93 name to IP address resolution, using the system \fI/etc/hosts
94 \fR, NIS, or DNS lookups. This method of name resolution
95 is operating system depended for instance on IRIX or Solaris this
96 may be controlled by the \fI/etc/nsswitch.conf\fR
97 file). Note that this method is only used if the NetBIOS name
98 type being queried is the 0x20 (server) name type, otherwise
102 wins : Query a name with
103 the IP address listed in the \fIwins server\fR
104 parameter. If no WINS server has
105 been specified this method will be ignored.
108 bcast : Do a broadcast on
109 each of the known local interfaces listed in the
111 parameter. This is the least reliable of the name resolution
112 methods as it depends on the target host being on a locally
116 If this parameter is not set then the name resolve order
117 defined in the \fIsmb.conf\fR file parameter
118 (name resolve order) will be used.
121 The default order is lmhosts, host, wins, bcast and without
122 this parameter or any entry in the \fIname resolve order
123 \fRparameter of the smb.conf file the name resolution
124 methods will be attempted in this order.
127 \fB-M NetBIOS name\fR
128 This options allows you to send messages, using
129 the "WinPopup" protocol, to another computer. Once a connection is
130 established you then type your message, pressing ^D (control-D) to
133 If the receiving computer is running WinPopup the user will
134 receive the message and probably a beep. If they are not running
135 WinPopup the message will be lost, and no error message will
138 The message is also automatically truncated if the message
139 is over 1600 bytes, as this is the limit of the protocol.
141 One useful trick is to cat the message through
142 \fBsmbclient\fR. For example: \fB cat mymessage.txt | smbclient -M FRED \fR will
143 send the message in the file \fImymessage.txt\fR
146 You may also find the \fI-U\fR and
147 \fI-I\fR options useful, as they allow you to
148 control the FROM and TO parts of the message.
150 See the message command parameter in the \fI smb.conf(5)\fR for a description of how to handle incoming
151 WinPopup messages in Samba.
153 \fBNote\fR: Copy WinPopup into the startup group
154 on your WfWg PCs if you want them to always be able to receive
158 This specifies a NetBIOS scope that smbclient will
159 use to communicate with when generating NetBIOS names. For details
160 on the use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt.
161 NetBIOS scopes are \fBvery\fR rarely used, only set
162 this parameter if you are the system administrator in charge of all
163 the NetBIOS systems you communicate with.
166 If specified, this parameter suppresses the normal
167 password prompt from the client to the user. This is useful when
168 accessing a service that does not require a password.
170 Unless a password is specified on the command line or
171 this parameter is specified, the client will request a
174 \fB-n NetBIOS name\fR
175 By default, the client will use the local
176 machine's hostname (in uppercase) as its NetBIOS name. This parameter
177 allows you to override the host name and use whatever NetBIOS
181 debuglevel is an integer from 0 to 10, or
184 The default value if this parameter is not specified
187 The higher this value, the more detail will be logged to
188 the log files about the activities of the
189 client. At level 0, only critical errors and serious warnings will
190 be logged. Level 1 is a reasonable level for day to day running -
191 it generates a small amount of information about operations
194 Levels above 1 will generate considerable amounts of log
195 data, and should only be used when investigating a problem.
196 Levels above 3 are designed for use only by developers and
197 generate HUGE amounts of log data, most of which is extremely
198 cryptic. If debuglevel is set to the letter 'A', then \fBall
199 \fRdebug messages will be printed. This setting
200 is for developers only (and people who \fBreally\fR want
201 to know how the code works internally).
203 Note that specifying this parameter here will override
204 the log level parameter in the \fBsmb.conf (5)\fR
208 This number is the TCP port number that will be used
209 when making connections to the server. The standard (well-known)
210 TCP port number for an SMB/CIFS server is 139, which is the
214 If specified, logfilename specifies a base filename
215 into which operational data from the running client will be
218 The default base name is specified at compile time.
220 The base name is used to generate actual log file names.
221 For example, if the name specified was "log", the debug file
222 would be \fIlog.client\fR.
224 The log file generated is never removed by the client.
227 Print the usage message for the client.
230 IP address is the address of the server to connect to.
231 It should be specified in standard "a.b.c.d" notation.
233 Normally the client would attempt to locate a named
234 SMB/CIFS server by looking it up via the NetBIOS name resolution
235 mechanism described above in the \fIname resolve order\fR
236 parameter above. Using this parameter will force the client
237 to assume that the server is on the machine with the specified IP
238 address and the NetBIOS name component of the resource being
239 connected to will be ignored.
241 There is no default for this parameter. If not supplied,
242 it will be determined automatically by the client as described
246 This parameter causes the client to write messages
247 to the standard error stream (stderr) rather than to the standard
250 By default, the client writes messages to standard output
251 - typically the user's tty.
253 \fB-U username[%pass]\fR
254 Sets the SMB username or username and password.
255 If %pass is not specified, The user will be prompted. The client
256 will first check the USER environment variable, then the
257 \fI$LOGNAME\fR variable and if either exist, the
258 string is uppercased. Anything in these variables following a '%'
259 sign will be treated as the password. If these environmental
260 variables are not found, the username GUEST
263 If the password is not included in these environment
264 variables (using the %pass syntax), rpcclient will look for
265 a \fI$PASSWD\fR environment variable from which
266 to read the password.
268 A third option is to use a credentials file which
269 contains the plaintext of the username and password. This
270 option is mainly provided for scripts where the admin doesn't
271 desire to pass the credentials on the command line or via environment
272 variables. If this method is used, make certain that the permissions
273 on the file restrict access from unwanted users. See the
274 \fI-A\fR for more details.
276 Be cautious about including passwords in scripts or in
277 the \fI$PASSWD\fR environment variable. Also, on
278 many systems the command line of a running process may be seen
279 via the \fBps\fR command to be safe always allow
280 \fBrpcclient\fR to prompt for a password and type
285 you to specify a file from which to read the username and
286 password used in the connection. The format of the file is
296 Make certain that the permissions on the file restrict
297 access from unwanted users.
300 This option allows you to look at what services
301 are available on a server. You use it as \fBsmbclient -L
302 host\fR and a list should appear. The \fI-I
303 \fRoption may be useful if your NetBIOS names don't
304 match your tcp/ip dns host names or if you are trying to reach a
305 host on another network.
307 \fB-t terminal code\fR
308 This option tells smbclient how to interpret
309 filenames coming from the remote server. Usually Asian language
310 multibyte UNIX implementations use different character sets than
311 SMB/CIFS servers (\fBEUC\fR instead of \fB SJIS\fR for example). Setting this parameter will let
312 \fBsmbclient\fR convert between the UNIX filenames and
313 the SMB filenames correctly. This option has not been seriously tested
314 and may have some problems.
316 The terminal codes include CWsjis, CWeuc, CWjis7, CWjis8,
317 CWjunet, CWhex, CWcap. This is not a complete list, check the Samba
318 source code for the complete list.
321 This option changes the transmit/send buffer
322 size when getting or putting a file from/to the server. The default
323 is 65520 bytes. Setting this value smaller (to 1200 bytes) has been
324 observed to speed up file transfers to and from a Win9x server.
327 Override the default workgroup specified in the
328 workgroup parameter of the \fIsmb.conf\fR file
329 for this connection. This may be needed to connect to some
333 smbclient may be used to create \fBtar(1)
334 \fRcompatible backups of all the files on an SMB/CIFS
335 share. The secondary tar flags that can be given to this option
340 \fIc\fR - Create a tar file on UNIX.
341 Must be followed by the name of a tar file, tape device
342 or "-" for standard output. If using standard output you must
343 turn the log level to its lowest value -d0 to avoid corrupting
344 your tar file. This flag is mutually exclusive with the
348 \fIx\fR - Extract (restore) a local
349 tar file back to a share. Unless the -D option is given, the tar
350 files will be restored from the top level of the share. Must be
351 followed by the name of the tar file, device or "-" for standard
352 input. Mutually exclusive with the \fIc\fR flag.
353 Restored files have their creation times (mtime) set to the
354 date saved in the tar file. Directories currently do not get
355 their creation dates restored properly.
358 \fII\fR - Include files and directories.
359 Is the default behavior when filenames are specified above. Causes
360 tar files to be included in an extract or create (and therefore
361 everything else to be excluded). See example below. Filename globbing
362 works in one of two ways. See r below.
365 \fIX\fR - Exclude files and directories.
366 Causes tar files to be excluded from an extract or create. See
367 example below. Filename globbing works in one of two ways now.
371 \fIb\fR - Blocksize. Must be followed
372 by a valid (greater than zero) blocksize. Causes tar file to be
373 written out in blocksize*TBLOCK (usually 512 byte) blocks.
376 \fIg\fR - Incremental. Only back up
377 files that have the archive bit set. Useful only with the
381 \fIq\fR - Quiet. Keeps tar from printing
382 diagnostics as it works. This is the same as tarmode quiet.
385 \fIr\fR - Regular expression include
386 or exclude. Uses regular regular expression matching for
387 excluding or excluding files if compiled with HAVE_REGEX_H.
388 However this mode can be very slow. If not compiled with
389 HAVE_REGEX_H, does a limited wildcard match on '*' and '?'.
392 \fIN\fR - Newer than. Must be followed
393 by the name of a file whose date is compared against files found
394 on the share during a create. Only files newer than the file
395 specified are backed up to the tar file. Useful only with the
399 \fIa\fR - Set archive bit. Causes the
400 archive bit to be reset when a file is backed up. Useful with the
401 \fIg\fR and \fIc\fR flags.
404 \fBTar Long File Names\fR
407 \fBsmbclient\fR's tar option now supports long
408 file names both on backup and restore. However, the full path
409 name of the file must be less than 1024 bytes. Also, when
410 a tar archive is created, smbclient's tar option places all
411 files in the archive with relative names, not absolute names.
417 All file names can be given as DOS path names (with '\\'
418 as the component separator) or as UNIX path names (with '/' as
419 the component separator).
425 Restore from tar file backup.tar into myshare on mypc
426 (no password on share).
429 \fBsmbclient //mypc/myshare "" -N -Tx backup.tar
432 Restore everything except \fIusers/docs\fR
435 \fBsmbclient //mypc/myshare "" -N -TXx backup.tar
439 Create a tar file of the files beneath \fI users/docs\fR.
442 \fBsmbclient //mypc/myshare "" -N -Tc
443 backup.tar users/docs \fR
446 Create the same tar file as above, but now use
450 \fBsmbclient //mypc/myshare "" -N -tc backup.tar
454 Create a tar file of all the files and directories in
458 \fBsmbclient //mypc/myshare "" -N -Tc backup.tar *
461 \fB-D initial directory\fR
462 Change to initial directory before starting. Probably
463 only of any use with the tar -T option.
465 \fB-c command string\fR
466 command string is a semicolon separated list of
467 commands to be executed instead of prompting from stdin. \fI -N\fR is implied by \fI-c\fR.
469 This is particularly useful in scripts and for printing stdin
470 to the server, e.g. \fB-c 'print -'\fR.
473 Once the client is running, the user is presented with
478 The backslash ("\\") indicates the current working directory
479 on the server, and will change if the current working directory
482 The prompt indicates that the client is ready and waiting to
483 carry out a user command. Each command is a single word, optionally
484 followed by parameters specific to that command. Command and parameters
485 are space-delimited unless these notes specifically
486 state otherwise. All commands are case-insensitive. Parameters to
487 commands may or may not be case sensitive, depending on the command.
489 You can specify file names which have spaces in them by quoting
490 the name with double quotes, for example "a long file name".
492 Parameters shown in square brackets (e.g., "[parameter]") are
493 optional. If not given, the command will use suitable defaults. Parameters
494 shown in angle brackets (e.g., "<parameter>") are required.
496 Note that all commands operating on the server are actually
497 performed by issuing a request to the server. Thus the behavior may
498 vary from server to server, depending on how the server was implemented.
500 The commands available are given here in alphabetical order.
503 If "command" is specified, the ? command will display
504 a brief informative message about the specified command. If no
505 command is specified, a list of available commands will
508 \fB! [shell command]\fR
509 If "shell command" is specified, the !
510 command will execute a shell locally and run the specified shell
511 command. If no command is specified, a local shell will be run.
513 \fBcd [directory name]\fR
514 If "directory name" is specified, the current
515 working directory on the server will be changed to the directory
516 specified. This operation will fail if for any reason the specified
517 directory is inaccessible.
519 If no directory name is specified, the current working
520 directory on the server will be reported.
523 The client will request that the server attempt
524 to delete all files matching "mask" from the current working
525 directory on the server.
528 A list of the files matching "mask" in the current
529 working directory on the server will be retrieved from the server
533 Terminate the connection with the server and exit
536 \fBget <remote file name> [local file name]\fR
537 Copy the file called "remote file name" from
538 the server to the machine running the client. If specified, name
539 the local copy "local file name". Note that all transfers in
540 \fBsmbclient\fR are binary. See also the
544 See the ? command above.
546 \fBlcd [directory name]\fR
547 If "directory name" is specified, the current
548 working directory on the local machine will be changed to
549 the directory specified. This operation will fail if for any
550 reason the specified directory is inaccessible.
552 If no directory name is specified, the name of the
553 current working directory on the local machine will be reported.
556 Toggle lowercasing of filenames for the get and
559 When lowercasing is toggled ON, local filenames are converted
560 to lowercase when using the get and mget commands. This is
561 often useful when copying (say) MSDOS files from a server, because
562 lowercase filenames are the norm on UNIX systems.
565 See the dir command above.
568 This command allows the user to set up a mask
569 which will be used during recursive operation of the mget and
572 The masks specified to the mget and mput commands act as
573 filters for directories rather than files when recursion is
576 The mask specified with the mask command is necessary
577 to filter files within those directories. For example, if the
578 mask specified in an mget command is "source*" and the mask
579 specified with the mask command is "*.c" and recursion is
580 toggled ON, the mget command will retrieve all files matching
581 "*.c" in all directories below and including all directories
582 matching "source*" in the current working directory.
584 Note that the value for mask defaults to blank (equivalent
585 to "*") and remains so until the mask command is used to change it.
586 It retains the most recently specified value indefinitely. To
587 avoid unexpected results it would be wise to change the value of
588 mask back to "*" after using the mget or mput commands.
590 \fBmd <directory name>\fR
591 See the mkdir command.
594 Copy all files matching mask from the server to
595 the machine running the client.
597 Note that mask is interpreted differently during recursive
598 operation and non-recursive operation - refer to the recurse and
599 mask commands for more information. Note that all transfers in
600 smbclient are binary. See also the lowercase command.
602 \fBmkdir <directory name>\fR
603 Create a new directory on the server (user access
604 privileges permitting) with the specified name.
607 Copy all files matching mask in the current working
608 directory on the local machine to the current working directory on
611 Note that mask is interpreted differently during recursive
612 operation and non-recursive operation - refer to the recurse and mask
613 commands for more information. Note that all transfers in smbclient
616 \fBprint <file name>\fR
617 Print the specified file from the local machine
618 through a printable service on the server.
620 See also the printmode command.
622 \fBprintmode <graphics or text>\fR
623 Set the print mode to suit either binary data
624 (such as graphical information) or text. Subsequent print
625 commands will use the currently set print mode.
628 Toggle prompting for filenames during operation
629 of the mget and mput commands.
631 When toggled ON, the user will be prompted to confirm
632 the transfer of each file during these commands. When toggled
633 OFF, all specified files will be transferred without prompting.
635 \fBput <local file name> [remote file name]\fR
636 Copy the file called "local file name" from the
637 machine running the client to the server. If specified,
638 name the remote copy "remote file name". Note that all transfers
639 in smbclient are binary. See also the lowercase command.
642 Displays the print queue, showing the job id,
643 name, size and current status.
646 See the exit command.
648 \fBrd <directory name>\fR
649 See the rmdir command.
652 Toggle directory recursion for the commands mget
655 When toggled ON, these commands will process all directories
656 in the source directory (i.e., the directory they are copying
657 from ) and will recurse into any that match the mask specified
658 to the command. Only files that match the mask specified using
659 the mask command will be retrieved. See also the mask command.
661 When recursion is toggled OFF, only files from the current
662 working directory on the source machine that match the mask specified
663 to the mget or mput commands will be copied, and any mask specified
664 using the mask command will be ignored.
667 Remove all files matching mask from the current
668 working directory on the server.
670 \fBrmdir <directory name>\fR
671 Remove the specified directory (user access
672 privileges permitting) from the server.
674 \fBtar <c|x>[IXbgNa]\fR
675 Performs a tar operation - see the \fI-T
676 \fRcommand line option above. Behavior may be affected
677 by the tarmode command (see below). Using g (incremental) and N
678 (newer) will affect tarmode settings. Note that using the "-" option
679 with tar x may not work - use the command line option instead.
681 \fBblocksize <blocksize>\fR
682 Blocksize. Must be followed by a valid (greater
683 than zero) blocksize. Causes tar file to be written out in
684 blocksize*TBLOCK (usually 512 byte) blocks.
686 \fBtarmode <full|inc|reset|noreset>\fR
687 Changes tar's behavior with regard to archive
688 bits. In full mode, tar will back up everything regardless of the
689 archive bit setting (this is the default mode). In incremental mode,
690 tar will only back up files with the archive bit set. In reset mode,
691 tar will reset the archive bit on all files it backs up (implies
694 \fBsetmode <filename> <perm=[+|\\-]rsha>\fR
695 A version of the DOS attrib command to set
696 file permissions. For example:
698 \fBsetmode myfile +r \fR
700 would make myfile read only.
703 Some servers are fussy about the case of supplied usernames,
704 passwords, share names (AKA service names) and machine names.
705 If you fail to connect try giving all parameters in uppercase.
707 It is often necessary to use the -n option when connecting
708 to some types of servers. For example OS/2 LanManager insists
709 on a valid NetBIOS name being used, so you need to supply a valid
710 name that would be known to the server.
712 smbclient supports long file names where the server
713 supports the LANMAN2 protocol or above.
714 .SH "ENVIRONMENT VARIABLES"
716 The variable \fI$USER\fR may contain the
717 username of the person using the client. This information is
718 used only if the protocol level is high enough to support
719 session-level passwords.
721 The variable \fI$PASSWD\fR may contain
722 the password of the person using the client. This information is
723 used only if the protocol level is high enough to support
724 session-level passwords.
727 The location of the client program is a matter for
728 individual system administrators. The following are thus
731 It is recommended that the smbclient software be installed
732 in the \fI/usr/local/samba/bin/\fR or \fI /usr/samba/bin/\fR directory, this directory readable
733 by all, writeable only by root. The client program itself should
734 be executable by all. The client should \fBNOT\fR be
737 The client log files should be put in a directory readable
738 and writeable only by the user.
740 To test the client, you will need to know the name of a
741 running SMB/CIFS server. It is possible to run \fBsmbd(8)
742 \fRan ordinary user - running that server as a daemon
743 on a user-accessible port (typically any port number over 1024)
744 would provide a suitable test server.
747 Most diagnostics issued by the client are logged in a
748 specified log file. The log file name is specified at compile time,
749 but may be overridden on the command line.
751 The number and nature of diagnostics available depends
752 on the debug level used by the client. If you have problems,
753 set the debug level to 3 and peruse the log files.
756 This man page is correct for version 2.2 of
760 The original Samba software and related utilities
761 were created by Andrew Tridgell. Samba is now developed
762 by the Samba Team as an Open Source project similar
763 to the way the Linux kernel is developed.
765 The original Samba man pages were written by Karl Auer.
766 The man page sources were converted to YODL format (another
767 excellent piece of Open Source software, available at
768 ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0
769 release by Jeremy Allison. The conversion to DocBook for
770 Samba 2.2 was done by Gerald Carter