1 .TH SMBCLIENT 1 smbclient smbclient
3 smbclient \- ftp-like Lan Manager client program
58 This program is part of the Samba suite.
61 is a client that can 'talk' to a Lan Manager server. It offers
62 an interface similar to that of the
66 Operations include things like getting files from the
67 server to the local machine, putting files from the local machine to
68 the server, retrieving directory information from the server and so on.
73 is the name of the service you want to use on the server. A service
75 .B "\e\eserver\eservice"
78 is the netbios name of the Lan Manager server offering the desired service and
80 is the name of the service offered. Thus to connect to the service "printer"
81 on the Lan Manager server "lanman", you would use the servicename
84 .B "\e\elanman\eprinter"
87 Note that the server name required is NOT necessarily the host name of the
88 server! The name required is a Lan Manager server name, which may or may not
89 be the same as the hostname of the machine running the server.
96 is the password required to access the specified service on the
97 specified server. If supplied, the
99 option (suppress password prompt) is assumed.
101 There is no default password. If no password is supplied on the command line
102 (either here or using the
104 option (see below)) and
106 is not specified, the client will prompt for a password, even if the desired
107 service does not require one. (If no password is
108 required, simply press ENTER to provide a null password.)
110 Note: Some servers (including OS/2 and Windows for Workgroups) insist
111 on an uppercase password. Lowercase or mixed case passwords may be
112 rejected by these servers.
114 Be cautious about including passwords in scripts.
120 This parameter, if specified, causes the maximum debug level to be selected.
121 Be warned that this generates prodigious amounts of debug data. There is also
122 a security issue involved, as at the maximum debug level cleartext passwords
123 may be written to some log files.
129 This option allows you to look at what services are available on a
130 server. You use it as "smbclient -L host" and a list should appear.
133 option may be useful if your netbios names don't match your
134 tcp/ip host names or if you are trying to reach a host on another
135 network. For example:
137 smbclient -L ftp -I ftp.microsoft.com
139 will list the shares available on Microsoft's public server.
145 This options allows you to send messages, using the "WinPopup"
146 protocol, to another computer. Once a connection is established you
147 then type your message, pressing ^D (control-D) to end.
149 If the receiving computer is running WinPopup the user will receive
150 the message and probably a beep. If they are not running WinPopup the
151 message will be lost, and no error message will occur.
153 The message is also automatically truncated if the message is over
154 1600 bytes, as this is the limit of the protocol.
156 One useful trick is to cat the message through
160 cat mymessage.txt | smbclient -M FRED
162 will send the message in the file "mymessage.txt" to the machine FRED.
164 You may also find the
168 options useful, as they allow you to
169 control the FROM and TO parts of the message.
171 See the message command section of
173 for a description of how to handle incoming WinPopup messages in Samba.
175 Note: Copy WinPopup into the startup group on your WfWg PCs if you
176 want them to always be able to receive messages.
182 This parameter, if specified, causes the client to write messages to the
183 standard error stream (stderr) rather than to the standard output stream.
185 By default, the client writes messages to standard output - typically the
194 represents the IP number of the server to connect to. It should
195 be specified in standard "a.b.c.d" notation.
197 Normally the client will attempt to locate the specified Lan Manager server
198 by looking it up - that is, broadcasting a request for the given server to
199 identify itself. Using this parameter will force the client to assume that
200 the server is on the machine with the specified IP number.
202 There is no default for this parameter. If not supplied, it will be determined
203 automatically by the client as described above.
209 If specified, this parameter suppresses the normal password prompt from the
210 client to the user. This is useful when accessing a service that does not
213 Unless a password is specified on the command line or this parameter is
214 specified, the client will request a password.
221 See the socket options section of
229 If specified, the service requested will be connected to as a printer service
230 rather than as a normal filespace service. Operations such as put and get
231 will not be applicable for such a connection.
233 By default, services will be connected to as NON-printer services.
241 is the user name that will be used by the client to make a connection,
242 assuming your server is running a protocol that allows for usernames.
244 Some servers are fussy about the case of this name, and some insist
245 that it must be a valid netbios name.
249 is supplied, it will default to an uppercase version of the
257 is supplied and neither environment variable exists the user name will
260 If the service you are connecting to requires a password, it can be supplied
263 option, by appending a percent symbol ("%") then the password to
265 For example, to attach to a service as user "fred" with password "secret", you
269 on the command line. Note that there are no spaces around the percent symbol.
271 If you specify the password as part of
275 option (suppress password prompt) is assumed.
277 If you specify the password as a parameter AND as part of
279 then the password as part of
281 will take precedence. Putting nothing before or nothing after the percent
282 symbol will cause an empty username or an empty password to be used,
285 Note: Some servers (including OS/2 and Windows for Workgroups) insist
286 on an uppercase password. Lowercase or mixed case passwords may be
287 rejected by these servers.
289 Be cautious about including passwords in scripts.
296 debuglevel is an integer from 0 to 5.
298 The default value if this parameter is not specified is zero.
300 The higher this value, the more detail will be logged to the log files about
301 the activities of the client. At level 0, only critical errors and serious
302 warnings will be logged. Level 1 is a reasonable level for day to day running
303 - it generates a small amount of information about operations carried out.
305 Levels above 1 will generate considerable amounts of log data, and should
306 only be used when investigating a problem. Levels above 3 are designed for
307 use only by developers and generate HUGE amounts of log data, most of which
308 is extremely cryptic.
317 specifies a base filename into which operational data from the running client
320 The default base name is specified at compile time.
322 The base name is used to generate actual log file names. For example, if the
323 name specified was "log", the following files would be used for log data:
326 log.client.debug (containing debugging information)
328 log.client.in (containing inbound transaction data)
330 log.client.out (containing outbound transaction data)
333 The log files generated are never removed by the client.
340 By default, the client will use the local machine's hostname (in
341 uppercase) as its netbios name. This parameter allows you to override
342 the host name and use whatever netbios name you wish.
349 Override what workgroup is used for the connection. This may be needed
350 to connect to some servers.
357 port number is a positive integer value.
359 The default value if this parameter is not specified is 139.
361 This number is the port number that will be used when making connections to
362 the server. The standard (well-known) port number for the server is 139,
365 This parameter is not normally specified.
374 consists of one or more of
387 .B "\e\eserver\eshare"
402 Create a tar file on UNIX. Must be followed by the name of a tar file,
403 tape device or "\-" for standard output. (May be useful to set debugging
406 to avoid corrupting your tar file if using "\-"). Mutually
412 Extract (restore) a local tar file back to a share. Unless the
414 option is given, the tar files will be restored from the top level of
415 the share. Must be followed by the name of the tar file, device or "\-"
416 for standard input. Mutually exclusive with the
421 Include files and directories. Is the default behaviour when
423 are specified above. Causes tar files to be included in an extract or create
424 (and therefore everything else to be excluded). See example below.
425 Filename globbing does not work for included files for extractions (yet).
428 Exclude files and directories. Causes tar files to be excluded from
429 an extract or create. See example below.
430 Filename globbing does not work for excluded files (yet).
433 Blocksize. Must be followed by a valid (greater than zero) blocksize.
434 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
438 Incremental. Only back up files that have the archive bit set. Useful
444 Newer than. Must be followed by the name of a file whose date is
445 compared against files found on the share during a create. Only files
446 newer than the file specified are backed up to the tar file. Useful
452 Set archive bit. Causes the archive bit to be reset when a file is backed
462 smbclient \e\emypc\emyshare "" -N -Tx backup.tar
464 Restore from tar file backup.tar into myshare on mypc (no password on share).
466 smbclient \e\emypc\emyshare "" -N -TXx backup.tar users/docs
468 Restore everything except users/docs
470 smbclient \e\emypc\emyshare "" -N -Tc backup.tar users/docs
472 Create a tar file of the files beneath users/docs.
480 Change to initial directory before starting. Probably only of any use
490 command string is a semicolon separated list of commands to be
491 executed instead of prompting from stdin.
496 This is particularly useful in scripts and for printing stdin to
497 the server, e.g. \-c 'print \-'.
500 Once the client is running, the user is presented with a prompt, "smb: \e>".
501 The backslash ("\e") indicates the current working directory on the server,
502 and will change if the current working directory is changed.
504 The prompt indicates that the client is ready and waiting to carry out a user
505 command. Each command is a single word, optionally followed by parameters
506 specific to that command. Command and parameters are space-delimited unless
507 these notes specifically state otherwise. All commands are case-insensitive.
508 Parameters to commands may or may not be case sensitive, depending on the
511 You can specify file names which have spaces in them by quoting the
512 name with double quotes, for example "a long file name".
514 Parameters shown in square brackets (eg., "[parameter]") are optional. If not
515 given, the command will use suitable defaults. Parameters shown in angle
516 brackets (eg., "<parameter>") are required.
518 Note that all commands operating on the server are actually performed by
519 issuing a request to the server. Thus the behaviour may vary from server to
520 server, depending on how the server was implemented.
522 The commands available are given here in alphabetical order.
537 command will display a brief informative message about the specified command.
539 If no command is specified, a list of available commands will be displayed.
556 command will execute a shell locally and run the specified shell command. If
557 no command is specified, a shell will be run.
572 is specified, the current working directory
574 will be changed to the directory specified. This operation will fail if for
575 any reason the specified directory is inaccessible.
577 If no directory name is specified, the current working directory
592 The client will request that the server attempt to delete all files matching
594 from the current working directory
608 A list of the files matching
610 in the current working directory
612 will be retrieved from the server and displayed.
625 Terminate the connection with the server and exit from the program.
633 .I <remote file name> [local file name]
640 from the server to the machine running the client. If specified, name the
643 Note that all transfers in
645 are binary. See also the
677 is specified, the current working directory
678 .B on the local machine
679 will be changed to the directory specified. This operation will fail if for
680 any reason the specified directory is inaccessible.
682 If no directory name is specified, the name of the current working directory
683 .B on the local machine
697 Toggle lowercasing of filenames for the
703 When lowercasing is toggled ON, local filenames are converted to lowercase
708 commands. This is often useful when copying (say) MSDOS files from a server,
709 because lowercase filenames are the norm on UNIX systems.
737 This command allows the user to set up a mask which will be used during
738 recursive operation of the
744 The masks specified to the
748 commands act as filters for directories
749 rather than files when recursion is toggled ON.
751 The mask specified with the
753 command is necessary to filter files within those directories. For example,
754 if the mask specified in an
758 the mask specified with the
762 recursion is toggled ON, the
764 command will retrieve all files matching "*.c" in all directories below
765 and including all directories matching "source*" in the current working
768 Note that the value for
770 defaults to blank (equivalent to "*") and remains so until the
772 command is used to change it. It retains the most recently specified value
773 indefinitely. To avoid unexpected results it would be wise to change the
776 back to "*" after using the
808 Copy all files matching
810 from the server to the machine running the client.
814 is interpreted differently during recursive operation and non-recursive
815 operation - refer to the
819 commands for more information. Note that all transfers in
821 are binary. See also the
836 Create a new directory
838 (user access privileges permitting) with the specified name.
851 Copy all files matching
853 in the current working directory
854 .B on the local machine
855 to the current working directory on the server.
859 is interpreted differently during recursive operation and non-recursive
860 operation - refer to the
864 commands for more information. Note that all transfers in
879 Print the specified file
880 .B from the local machine
881 through a printable service on the server.
893 .I <graphics or text>
898 Set the print mode to suit either binary data (such as graphical information)
901 commands will use the currently set print mode.
914 Toggle prompting for filenames during operation of the
920 When toggled ON, the user will be prompted to confirm the transfer of each
921 file during these commands. When toggled OFF, all specified files will be
922 transferred without prompting.
930 .I <local file name> [remote file name]
937 from the machine running the client to the server. If specified, name the
940 Note that all transfers in
942 are binary. See also the
957 Displays the print queue, showing the job id, name, size and current status.
1000 Toggle directory recursion for the commands
1005 When toggled ON, these commands will process all directories in the source
1006 directory (i.e., the directory they are copying
1008 and will recurse into any that match the mask specified to the command. Only
1009 files that match the mask specified using the
1011 command will be retrieved. See also the
1015 When recursion is toggled OFF, only files from the current working
1016 directory on the source machine that match the mask specified to the
1020 commands will be copied, and any mask specified using the
1022 command will be ignored.
1035 Remove all files matching
1037 from the current working directory
1051 Remove the specified directory (user access privileges permitting)
1065 Performs a tar operation - see the
1067 command line option above. Behaviour
1068 may be affected by the
1070 command (see below). Using g (incremental) and N (newer) will affect
1071 tarmode settings. Note that using the "\-" option with tar x may not
1072 work - use the command line option instead.
1085 Blocksize. Must be followed by a valid (greater than zero) blocksize.
1086 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
1095 .I <full|inc|reset|noreset>
1100 Changes tar's behaviour with regard to archive bits. In full mode,
1101 tar will back up everything regardless of the archive bit setting (this
1102 is the default mode). In incremental mode, tar will only back up files
1103 with the archive bit set. In reset mode, tar will reset the archive bit
1104 on all files it backs up (implies read/write share).
1112 .I <filename> <perm=[+|\-]rsha>
1117 A version of the DOS attrib command to set file permissions. For example,
1121 would make myfile read only.
1125 Some servers are fussy about the case of supplied usernames, passwords, share
1126 names (aka service names) and machine names. If you fail to connect try
1127 giving all parameters in uppercase.
1129 It is often necessary to use the
1131 option when connecting to some types
1132 of servers. For example OS/2 LanManager insists on a valid netbios name
1133 being used, so you need to supply a valid name that would be known to
1137 supports long file names where the server supports the LANMAN2
1141 .SH ENVIRONMENT VARIABLES
1144 The variable USER may contain the username of the person using the client.
1145 This information is used only if the protocol level is high enough to support
1146 session-level passwords.
1149 The location of the client program is a matter for individual system
1150 administrators. The following are thus suggestions only.
1152 It is recommended that the client software be installed under the
1154 hierarchy, in a directory readable by all, writeable only by root. The client
1155 program itself should be executable by all. The client should NOT be setuid
1158 The client log files should be put in a directory readable and writable only
1161 To test the client, you will need to know the name of a running Lan manager
1162 server. It is possible to run
1166 as an ordinary user - running that server as a daemon on a
1167 user-accessible port (typically any port number over 1024) would
1168 provide a suitable test server.
1170 This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
1171 of the recent patches to it. These notes will necessarily lag behind
1172 development of the client software, so it is possible that your version of
1173 the client has extensions or parameter semantics that differ from or are not
1174 covered by this man page. Please notify these to the address below for
1179 [This section under construction]
1181 Most diagnostics issued by the client are logged in a specified log file. The
1182 log file name is specified at compile time, but may be overridden on the
1185 The number and nature of diagnostics available depends on the debug level used
1186 by the client. If you have problems, set the debug level to 3 and peruse the
1189 Most messages are reasonably self-explanatory. Unfortunately, at time of
1190 creation of this man page the source code is still too fluid to warrant
1191 describing each and every diagnostic. At this stage your best bet is still
1192 to grep the source code and inspect the conditions that gave rise to the
1193 diagnostics you are seeing.
1197 The original Samba software and related utilities were created by
1198 Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
1199 of the Source for this project.
1203 for a full list of contributors and details on how to
1204 submit bug reports, comments etc.