1 mailto(samba-bugs@samba.anu.edu.au)
3 manpage(smbclient)(1)(23 Oct 1998)(Samba)(SAMBA)
6 manpagename(smbclient)(ftp-like client to access SMB/CIFS resources on servers)
11 bf(smbclient) service [password] [-s smb.conf] [-B IP addr] [-O socket_options][-R name resolve order] [-M NetBIOS name] [-i scope] [-N] [-n NetBIOS name] [-d debuglevel] [-P] [-p port] [-l log basename] [-h] [-I dest IP] [-E] [-U username] [-L NetBIOS name] [-t terminal code] [-m max protocol] [-W workgroup] [-T<c|x>IXFqgbNan] [-D directory] [-c command string]
16 This program is part of the bf(Samba) suite.
18 bf(smbclient) is a client that can 'talk' to an SMB/CIFS server. It
19 offers an interface similar to that of the ftp program (see bf(ftp
20 (1))). Operations include things like getting files from the server
21 to the local machine, putting files from the local machine to the
22 server, retrieving directory information from the server and so on.
29 dit(bf(servicename)) servicename is the name of the service you want
30 to use on the server. A service name takes the form
31 tt(//server/service) where em(server) is the NetBIOS name of the SMB/CIFS
32 server offering the desired service and em(service) is the name
33 of the service offered. Thus to connect to the service em(printer) on
34 the SMB/CIFS server em(lanman), you would use the servicename
38 Note that the server name required is NOT necessarily the host name of
39 the server! The name required is a NetBIOS server name, which may or
40 may not be the same as the IP (DNS) hostname of the machine running
43 The server name is looked up according to the bf(name resolve order)
44 parameter in the smb.conf file, allowing an administrator to change
45 the order and methods by which server names are looked up.
47 dit(bf(password)) password is the password required to access the
48 specified service on the specified server. If this parameter is
49 supplied, the bf(-N) option (suppress password prompt) is assumed.
51 There is no default password. If no password is supplied on the
52 command line (either by using this parameter or adding a password to
53 the bf(-U) option (see below)) and the bf(-N) option is not specified,
54 the client will prompt for a password, even if the desired service
55 does not require one. (If no password is required, simply press ENTER
56 to provide a null password.)
58 Note: Some servers (including OS/2 and Windows for Workgroups) insist
59 on an uppercase password. Lowercase or mixed case passwords may be
60 rejected by these servers.
62 Be cautious about including passwords in scripts.
64 dit(bf(-s smb.conf)) This parameter specifies the pathname to the
65 Samba configuration file, smb.conf. This file controls all aspects of
66 the Samba setup on the machine and smbclient also needs to read this
69 dit(bf(-B IP addr)) The IP address to use when sending a broadcast packet.
71 dit(bf(-O socket_options)) TCP socket options to set on the client socket.
73 dit(bf(-R name resolve order)) This option allows the user of
74 smbclient to determine what name resolution services to use when
75 looking up the NetBIOS name of the host being connected to.
77 The options are :"lmhosts", "host", "wins" and "bcast". They cause
78 names to be resolved as follows :
82 it() bf(lmhosts) : Lookup an IP address in the Samba lmhosts file.
84 it() bf(host) : Do a standard host name to IP address resolution,
85 using the system /etc/hosts, NIS, or DNS lookups. This method of name
86 resolution is operating system depended for instance on IRIX or
87 Solaris this may be controlled by the em(/etc/nsswitch.conf) file).
89 it() bf(wins) : Query a name with the IP address listed in the bf(wins
90 server) parameter in the smb.conf file. If no WINS server has been
91 specified this method will be ignored.
93 it() bf(bcast) : Do a broadcast on each of the known local interfaces
94 listed in the bf(interfaces) parameter in the smb.conf file. This is
95 the least reliable of the name resolution methods as it depends on the
96 target host being on a locally connected subnet. To specify a
97 particular broadcast address the bf(-B) option may be used.
101 The default order is lmhosts, host, wins, bcast and without this
102 parameter the name resolution methods will be attempted in this order.
104 dit(bf(-M NetBIOS name)) This options allows you to send messages,
105 using the "WinPopup" protocol, to another computer. Once a connection
106 is established you then type your message, pressing ^D (control-D) to
109 If the receiving computer is running WinPopup the user will receive
110 the message and probably a beep. If they are not running WinPopup the
111 message will be lost, and no error message will occur.
113 The message is also automatically truncated if the message is over
114 1600 bytes, as this is the limit of the protocol.
116 One useful trick is to cat the message through bf(smbclient).
119 tt(cat mymessage.txt | smbclient -M FRED)
121 will send the message in the file em(mymessage.txt) to the machine FRED.
123 You may also find the bf(-U) and bf(-I) options useful, as they allow
124 you to control the FROM and TO parts of the message.
126 See the message command section of bf(smb.conf (5)) for a description
127 of how to handle incoming WinPopup messages in Samba.
129 Note: Copy WinPopup into the startup group on your WfWg PCs if you
130 want them to always be able to receive messages.
132 dit(bf(-i scope)) This specifies a NetBIOS scope that smbclient will use
133 to communicate with when generating NetBIOS names. For details on the
134 use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes
135 are em(very) rarely used, only set this parameter if you are the
136 system administrator in charge of all the NetBIOS systems you
139 dit(bf(-N)) If specified, this parameter suppresses the normal
140 password prompt from the client to the user. This is useful when
141 accessing a service that does not require a password.
143 Unless a password is specified on the command line or this parameter
144 is specified, the client will request a password.
146 dit(bf(-n NetBIOS name)) By default, the client will use the local
147 machine's hostname (in uppercase) as its NetBIOS name. This parameter
148 allows you to override the host name and use whatever NetBIOS name you
151 dit(bf(-d debuglevel)) debuglevel is an integer from 0 to 10, or the
154 The default value if this parameter is not specified is zero.
156 The higher this value, the more detail will be logged to the log files
157 about the activities of the client. At level 0, only critical errors
158 and serious warnings will be logged. Level 1 is a reasonable level for
159 day to day running - it generates a small amount of information about
160 operations carried out.
162 Levels above 1 will generate considerable amounts of log data, and should
163 only be used when investigating a problem. Levels above 3 are designed for
164 use only by developers and generate HUGE amounts of log data, most of which
165 is extremely cryptic.
170 DEBUG(0,("\t-d debuglevel set the debuglevel\n"));
171 DEBUG(0,("\t-P connect to service as a printer\n"));
172 DEBUG(0,("\t-p port connect to the specified port\n"));
173 DEBUG(0,("\t-l log basename. Basename for log/debug files\n"));
174 DEBUG(0,("\t-h Print this help message.\n"));
175 DEBUG(0,("\t-I dest IP use this IP to connect to\n"));
176 DEBUG(0,("\t-E write messages to stderr instead of stdout\n"));
177 DEBUG(0,("\t-U username set the network username\n"));
178 DEBUG(0,("\t-L host get a list of shares available on a host\n"));
179 DEBUG(0,("\t-t terminal code terminal i/o code {sjis|euc|jis7|jis8|junet|hex}\n"));
180 DEBUG(0,("\t-m max protocol set the max protocol level\n"));
181 DEBUG(0,("\t-W workgroup set the workgroup name\n"));
182 DEBUG(0,("\t-T<c|x>IXFqgbNan command line tar\n"));
183 DEBUG(0,("\t-D directory start from directory\n"));
184 DEBUG(0,("\t-c command string execute semicolon separated commands\n"));
186 .B \-R name resolve order
189 This parameter will override the default name resolution order of the
190 server listed in the "name resolve order" parameter in smb.conf. This
191 is useful to force name resolution to take place by a particular method.
192 This command line parameter only exists in Samba 1.9.18p4 and above.
198 This parameter, if specified, causes the maximum debug level to be selected.
199 Be warned that this generates prodigious amounts of debug data. There is also
200 a security issue involved, as at the maximum debug level cleartext passwords
201 may be written to some log files.
207 This option allows you to look at what services are available on a
208 server. You use it as "smbclient -L host" and a list should appear.
211 option may be useful if your NetBIOS names don't match your
212 tcp/ip host names or if you are trying to reach a host on another
213 network. For example:
215 smbclient -L ftp -I ftp.microsoft.com
217 will list the shares available on Microsoft's public server.
226 This parameter, if specified, causes the client to write messages to the
227 standard error stream (stderr) rather than to the standard output stream.
229 By default, the client writes messages to standard output - typically the
238 represents the IP number of the server to connect to. It should
239 be specified in standard "a.b.c.d" notation.
241 Normally the client will attempt to locate the specified Lan Manager server
242 by looking it up - that is, broadcasting a request for the given server to
243 identify itself. Using this parameter will force the client to assume that
244 the server is on the machine with the specified IP number.
246 There is no default for this parameter. If not supplied, it will be determined
247 automatically by the client as described above.
254 See the socket options section of
262 If specified, the service requested will be connected to as a printer service
263 rather than as a normal filespace service. Operations such as put and get
264 will not be applicable for such a connection.
266 By default, services will be connected to as NON-printer services.
274 is the user name that will be used by the client to make a connection,
275 assuming your server is running a protocol that allows for usernames.
277 Some servers are fussy about the case of this name, and some insist
278 that it must be a valid NetBIOS name.
282 is supplied, it will default to an uppercase version of the
290 is supplied and neither environment variable exists the user name will
293 If the USER environment variable containts a '%' character, everything
294 after that will be treated as a password. This allows you to set the
295 environment variable to be
296 .B USER=username%password
297 so that a password is not passed on the command line (where it may
298 be seen by the ps command).
300 If the service you are connecting to requires a password, it can be supplied
303 option, by appending a percent symbol ("%") then the password to
305 For example, to attach to a service as user "fred" with password "secret", you
309 on the command line. Note that there are no spaces around the percent symbol.
311 If you specify the password as part of
315 option (suppress password prompt) is assumed.
317 If you specify the password as a parameter AND as part of
319 then the password as part of
321 will take precedence. Putting nothing before or nothing after the percent
322 symbol will cause an empty username or an empty password to be used,
325 Note: Some servers (including OS/2 and Windows for Workgroups) insist
326 on an uppercase password. Lowercase or mixed case passwords may be
327 rejected by these servers.
329 Be cautious about including passwords in scripts.
338 specifies a base filename into which operational data from the running client
341 The default base name is specified at compile time.
343 The base name is used to generate actual log file names. For example, if the
344 name specified was "log", the following files would be used for log data:
347 log.client.debug (containing debugging information)
349 log.client.in (containing inbound transaction data)
351 log.client.out (containing outbound transaction data)
354 The log files generated are never removed by the client.
361 Override what workgroup is used for the connection. This may be needed
362 to connect to some servers.
369 port number is a positive integer value.
371 The default value if this parameter is not specified is 139.
373 This number is the port number that will be used when making connections to
374 the server. The standard (well-known) port number for the server is 139,
377 This parameter is not normally specified.
386 consists of one or more of
400 .B "\e\eserver\eshare"
415 Create a tar file on UNIX. Must be followed by the name of a tar file,
416 tape device or "\-" for standard output. (May be useful to set debugging
419 to avoid corrupting your tar file if using "\-"). Mutually
425 Extract (restore) a local tar file back to a share. Unless the
427 option is given, the tar files will be restored from the top level of
428 the share. Must be followed by the name of the tar file, device or "\-"
429 for standard input. Mutually exclusive with the
431 flag. Restored files have theuir creation times (mtime) set to the date saved in
432 the tar file. Directories currently do not get their creation dates restored
436 Include files and directories. Is the default behaviour when
438 are specified above. Causes tar files to be included in an extract or create
439 (and therefore everything else to be excluded). See example below.
440 Filename globbing does not work for included files for extractions (yet).
443 Exclude files and directories. Causes tar files to be excluded from
444 an extract or create. See example below.
445 Filename globbing does not work for excluded files (yet).
448 Blocksize. Must be followed by a valid (greater than zero) blocksize.
449 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
453 Incremental. Only back up files that have the archive bit set. Useful
459 Quiet. Keeps tar from printing diagnostics as it works. This is the
460 same as tarmode quiet.
463 Newer than. Must be followed by the name of a file whose date is
464 compared against files found on the share during a create. Only files
465 newer than the file specified are backed up to the tar file. Useful
471 Set archive bit. Causes the archive bit to be reset when a file is backed
481 smbclient's tar option now supports long file names both on backup and
482 restore. However, the full path name of the file must be less than 1024 bytes.
483 Also, when a tar archive is created, smbclient's tar option places all files
484 in the archive with relative names, not absolute names.
488 All file names can be given as DOS path names (with \e as the component
489 separator) or as UNIX path names (with / as the component separator).
493 smbclient \e\emypc\emyshare "" -N -Tx backup.tar
495 Restore from tar file backup.tar into myshare on mypc (no password on share).
497 smbclient \e\emypc\emyshare "" -N -TXx backup.tar users/docs
499 Restore everything except users/docs
501 smbclient \e\emypc\emyshare "" -N -Tc backup.tar users/docs
503 Create a tar file of the files beneath users/docs.
505 smbclient \e\emypc\emyshare "" -N -tc backup.tar users\edocs
507 Create the same tar file as above, but now use a DOS path name.
509 smbclient \e\emypc\emyshare "" -N -Tc backup.tar \e*
511 Create a tar file of all the files and directories in the share.
519 Change to initial directory before starting. Probably only of any use
529 command string is a semicolon separated list of commands to be
530 executed instead of prompting from stdin.
535 This is particularly useful in scripts and for printing stdin to
536 the server, e.g. \-c 'print \-'.
539 Once the client is running, the user is presented with a prompt, "smb: \e>".
540 The backslash ("\e") indicates the current working directory on the server,
541 and will change if the current working directory is changed.
543 The prompt indicates that the client is ready and waiting to carry out a user
544 command. Each command is a single word, optionally followed by parameters
545 specific to that command. Command and parameters are space-delimited unless
546 these notes specifically state otherwise. All commands are case-insensitive.
547 Parameters to commands may or may not be case sensitive, depending on the
550 You can specify file names which have spaces in them by quoting the
551 name with double quotes, for example "a long file name".
553 Parameters shown in square brackets (eg., "[parameter]") are optional. If not
554 given, the command will use suitable defaults. Parameters shown in angle
555 brackets (eg., "<parameter>") are required.
557 Note that all commands operating on the server are actually performed by
558 issuing a request to the server. Thus the behaviour may vary from server to
559 server, depending on how the server was implemented.
561 The commands available are given here in alphabetical order.
576 command will display a brief informative message about the specified command.
578 If no command is specified, a list of available commands will be displayed.
595 command will execute a shell locally and run the specified shell command. If
596 no command is specified, a shell will be run.
611 is specified, the current working directory
613 will be changed to the directory specified. This operation will fail if for
614 any reason the specified directory is inaccessible.
616 If no directory name is specified, the current working directory
631 The client will request that the server attempt to delete all files matching
633 from the current working directory
647 A list of the files matching
649 in the current working directory
651 will be retrieved from the server and displayed.
664 Terminate the connection with the server and exit from the program.
672 .I <remote file name> [local file name]
679 from the server to the machine running the client. If specified, name the
682 Note that all transfers in
684 are binary. See also the
716 is specified, the current working directory
717 .B on the local machine
718 will be changed to the directory specified. This operation will fail if for
719 any reason the specified directory is inaccessible.
721 If no directory name is specified, the name of the current working directory
722 .B on the local machine
736 Toggle lowercasing of filenames for the
742 When lowercasing is toggled ON, local filenames are converted to lowercase
747 commands. This is often useful when copying (say) MSDOS files from a server,
748 because lowercase filenames are the norm on UNIX systems.
776 This command allows the user to set up a mask which will be used during
777 recursive operation of the
783 The masks specified to the
787 commands act as filters for directories
788 rather than files when recursion is toggled ON.
790 The mask specified with the
792 command is necessary to filter files within those directories. For example,
793 if the mask specified in an
797 the mask specified with the
801 recursion is toggled ON, the
803 command will retrieve all files matching "*.c" in all directories below
804 and including all directories matching "source*" in the current working
807 Note that the value for
809 defaults to blank (equivalent to "*") and remains so until the
811 command is used to change it. It retains the most recently specified value
812 indefinitely. To avoid unexpected results it would be wise to change the
815 back to "*" after using the
847 Copy all files matching
849 from the server to the machine running the client.
853 is interpreted differently during recursive operation and non-recursive
854 operation - refer to the
858 commands for more information. Note that all transfers in
860 are binary. See also the
875 Create a new directory
877 (user access privileges permitting) with the specified name.
890 Copy all files matching
892 in the current working directory
893 .B on the local machine
894 to the current working directory on the server.
898 is interpreted differently during recursive operation and non-recursive
899 operation - refer to the
903 commands for more information. Note that all transfers in
918 Print the specified file
919 .B from the local machine
920 through a printable service on the server.
932 .I <graphics or text>
937 Set the print mode to suit either binary data (such as graphical information)
940 commands will use the currently set print mode.
953 Toggle prompting for filenames during operation of the
959 When toggled ON, the user will be prompted to confirm the transfer of each
960 file during these commands. When toggled OFF, all specified files will be
961 transferred without prompting.
969 .I <local file name> [remote file name]
976 from the machine running the client to the server. If specified, name the
979 Note that all transfers in
981 are binary. See also the
996 Displays the print queue, showing the job id, name, size and current status.
1039 Toggle directory recursion for the commands
1044 When toggled ON, these commands will process all directories in the source
1045 directory (i.e., the directory they are copying
1047 and will recurse into any that match the mask specified to the command. Only
1048 files that match the mask specified using the
1050 command will be retrieved. See also the
1054 When recursion is toggled OFF, only files from the current working
1055 directory on the source machine that match the mask specified to the
1059 commands will be copied, and any mask specified using the
1061 command will be ignored.
1074 Remove all files matching
1076 from the current working directory
1090 Remove the specified directory (user access privileges permitting)
1104 Performs a tar operation - see the
1106 command line option above. Behaviour
1107 may be affected by the
1109 command (see below). Using g (incremental) and N (newer) will affect
1110 tarmode settings. Note that using the "\-" option with tar x may not
1111 work - use the command line option instead.
1124 Blocksize. Must be followed by a valid (greater than zero) blocksize.
1125 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
1134 .I <full|inc|reset|noreset>
1139 Changes tar's behaviour with regard to archive bits. In full mode,
1140 tar will back up everything regardless of the archive bit setting (this
1141 is the default mode). In incremental mode, tar will only back up files
1142 with the archive bit set. In reset mode, tar will reset the archive bit
1143 on all files it backs up (implies read/write share).
1151 .I <filename> <perm=[+|\-]rsha>
1156 A version of the DOS attrib command to set file permissions. For example,
1160 would make myfile read only.
1164 Some servers are fussy about the case of supplied usernames, passwords, share
1165 names (aka service names) and machine names. If you fail to connect try
1166 giving all parameters in uppercase.
1168 It is often necessary to use the
1170 option when connecting to some types
1171 of servers. For example OS/2 LanManager insists on a valid NetBIOS name
1172 being used, so you need to supply a valid name that would be known to
1176 supports long file names where the server supports the LANMAN2
1180 .SH ENVIRONMENT VARIABLES
1183 The variable USER may contain the username of the person using the client.
1184 This information is used only if the protocol level is high enough to support
1185 session-level passwords.
1188 The location of the client program is a matter for individual system
1189 administrators. The following are thus suggestions only.
1191 It is recommended that the client software be installed under the
1193 hierarchy, in a directory readable by all, writeable only by root. The client
1194 program itself should be executable by all. The client should NOT be setuid
1197 The client log files should be put in a directory readable and writable only
1200 To test the client, you will need to know the name of a running Lan manager
1201 server. It is possible to run
1205 as an ordinary user - running that server as a daemon on a
1206 user-accessible port (typically any port number over 1024) would
1207 provide a suitable test server.
1209 This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
1210 of the recent patches to it. These notes will necessarily lag behind
1211 development of the client software, so it is possible that your version of
1212 the client has extensions or parameter semantics that differ from or are not
1213 covered by this man page. Please notify these to the address below for
1218 [This section under construction]
1220 Most diagnostics issued by the client are logged in a specified log file. The
1221 log file name is specified at compile time, but may be overridden on the
1224 The number and nature of diagnostics available depends on the debug level used
1225 by the client. If you have problems, set the debug level to 3 and peruse the
1228 Most messages are reasonably self-explanatory. Unfortunately, at time of
1229 creation of this man page the source code is still too fluid to warrant
1230 describing each and every diagnostic. At this stage your best bet is still
1231 to grep the source code and inspect the conditions that gave rise to the
1232 diagnostics you are seeing.
1236 The original Samba software and related utilities were created by
1237 Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
1238 of the Source for this project.
1242 for a full list of contributors and details on how to
1243 submit bug reports, comments etc.