1 .TH SMBCLIENT 1 "09 Oct 1998" "smbclient 2.0.0-alpha11"
3 smbclient \- ftp-like Lan Manager client program
61 This program is part of the Samba suite.
64 is a client that can 'talk' to a Lan Manager server. It offers
65 an interface similar to that of the
69 Operations include things like getting files from the
70 server to the local machine, putting files from the local machine to
71 the server, retrieving directory information from the server and so on.
76 is the name of the service you want to use on the server. A service
78 .B "\e\eserver\eservice"
81 is the netbios name of the Lan Manager server offering the desired service and
83 is the name of the service offered. Thus to connect to the service "printer"
84 on the Lan Manager server "lanman", you would use the servicename
87 .B "\e\elanman\eprinter"
90 Note that the server name required is NOT necessarily the host name of the
91 server! The name required is a Lan Manager server name, which may or may not
92 be the same as the hostname of the machine running the server.
94 With Samba 1.9.18p4 the server name is looked up according to the
95 "name resolve order=" parameter in the smb.conf file, allowing an
96 administrator to change the order and methods by which server names
104 is the password required to access the specified service on the
105 specified server. If supplied, the
107 option (suppress password prompt) is assumed.
109 There is no default password. If no password is supplied on the command line
110 (either here or using the
112 option (see below)) and
114 is not specified, the client will prompt for a password, even if the desired
115 service does not require one. (If no password is
116 required, simply press ENTER to provide a null password.)
118 Note: Some servers (including OS/2 and Windows for Workgroups) insist
119 on an uppercase password. Lowercase or mixed case passwords may be
120 rejected by these servers.
122 Be cautious about including passwords in scripts.
125 .B \-R name resolve order
128 This parameter will override the default name resolution order of the
129 server listed in the "name resolve order" parameter in smb.conf. This
130 is useful to force name resolution to take place by a particular method.
131 This command line parameter only exists in Samba 1.9.18p4 and above.
137 This parameter, if specified, causes the maximum debug level to be selected.
138 Be warned that this generates prodigious amounts of debug data. There is also
139 a security issue involved, as at the maximum debug level cleartext passwords
140 may be written to some log files.
146 This option allows you to look at what services are available on a
147 server. You use it as "smbclient -L host" and a list should appear.
150 option may be useful if your netbios names don't match your
151 tcp/ip host names or if you are trying to reach a host on another
152 network. For example:
154 smbclient -L ftp -I ftp.microsoft.com
156 will list the shares available on Microsoft's public server.
162 This options allows you to send messages, using the "WinPopup"
163 protocol, to another computer. Once a connection is established you
164 then type your message, pressing ^D (control-D) to end.
166 If the receiving computer is running WinPopup the user will receive
167 the message and probably a beep. If they are not running WinPopup the
168 message will be lost, and no error message will occur.
170 The message is also automatically truncated if the message is over
171 1600 bytes, as this is the limit of the protocol.
173 One useful trick is to cat the message through
177 cat mymessage.txt | smbclient -M FRED
179 will send the message in the file "mymessage.txt" to the machine FRED.
181 You may also find the
185 options useful, as they allow you to
186 control the FROM and TO parts of the message.
188 See the message command section of
190 for a description of how to handle incoming WinPopup messages in Samba.
192 Note: Copy WinPopup into the startup group on your WfWg PCs if you
193 want them to always be able to receive messages.
199 This parameter, if specified, causes the client to write messages to the
200 standard error stream (stderr) rather than to the standard output stream.
202 By default, the client writes messages to standard output - typically the
211 represents the IP number of the server to connect to. It should
212 be specified in standard "a.b.c.d" notation.
214 Normally the client will attempt to locate the specified Lan Manager server
215 by looking it up - that is, broadcasting a request for the given server to
216 identify itself. Using this parameter will force the client to assume that
217 the server is on the machine with the specified IP number.
219 There is no default for this parameter. If not supplied, it will be determined
220 automatically by the client as described above.
226 If specified, this parameter suppresses the normal password prompt from the
227 client to the user. This is useful when accessing a service that does not
230 Unless a password is specified on the command line or this parameter is
231 specified, the client will request a password.
238 See the socket options section of
246 If specified, the service requested will be connected to as a printer service
247 rather than as a normal filespace service. Operations such as put and get
248 will not be applicable for such a connection.
250 By default, services will be connected to as NON-printer services.
258 is the user name that will be used by the client to make a connection,
259 assuming your server is running a protocol that allows for usernames.
261 Some servers are fussy about the case of this name, and some insist
262 that it must be a valid netbios name.
266 is supplied, it will default to an uppercase version of the
274 is supplied and neither environment variable exists the user name will
277 If the USER environment variable containts a '%' character, everything
278 after that will be treated as a password. This allows you to set the
279 environment variable to be
280 .B USER=username%password
281 so that a password is not passed on the command line (where it may
282 be seen by the ps command).
284 If the service you are connecting to requires a password, it can be supplied
287 option, by appending a percent symbol ("%") then the password to
289 For example, to attach to a service as user "fred" with password "secret", you
293 on the command line. Note that there are no spaces around the percent symbol.
295 If you specify the password as part of
299 option (suppress password prompt) is assumed.
301 If you specify the password as a parameter AND as part of
303 then the password as part of
305 will take precedence. Putting nothing before or nothing after the percent
306 symbol will cause an empty username or an empty password to be used,
309 Note: Some servers (including OS/2 and Windows for Workgroups) insist
310 on an uppercase password. Lowercase or mixed case passwords may be
311 rejected by these servers.
313 Be cautious about including passwords in scripts.
320 debuglevel is an integer from 0 to 5.
322 The default value if this parameter is not specified is zero.
324 The higher this value, the more detail will be logged to the log files about
325 the activities of the client. At level 0, only critical errors and serious
326 warnings will be logged. Level 1 is a reasonable level for day to day running
327 - it generates a small amount of information about operations carried out.
329 Levels above 1 will generate considerable amounts of log data, and should
330 only be used when investigating a problem. Levels above 3 are designed for
331 use only by developers and generate HUGE amounts of log data, most of which
332 is extremely cryptic.
341 specifies a base filename into which operational data from the running client
344 The default base name is specified at compile time.
346 The base name is used to generate actual log file names. For example, if the
347 name specified was "log", the following files would be used for log data:
350 log.client.debug (containing debugging information)
352 log.client.in (containing inbound transaction data)
354 log.client.out (containing outbound transaction data)
357 The log files generated are never removed by the client.
364 By default, the client will use the local machine's hostname (in
365 uppercase) as its netbios name. This parameter allows you to override
366 the host name and use whatever netbios name you wish.
373 Override what workgroup is used for the connection. This may be needed
374 to connect to some servers.
381 port number is a positive integer value.
383 The default value if this parameter is not specified is 139.
385 This number is the port number that will be used when making connections to
386 the server. The standard (well-known) port number for the server is 139,
389 This parameter is not normally specified.
398 consists of one or more of
412 .B "\e\eserver\eshare"
427 Create a tar file on UNIX. Must be followed by the name of a tar file,
428 tape device or "\-" for standard output. (May be useful to set debugging
431 to avoid corrupting your tar file if using "\-"). Mutually
437 Extract (restore) a local tar file back to a share. Unless the
439 option is given, the tar files will be restored from the top level of
440 the share. Must be followed by the name of the tar file, device or "\-"
441 for standard input. Mutually exclusive with the
443 flag. Restored files have theuir creation times (mtime) set to the date saved in
444 the tar file. Directories currently do not get their creation dates restored
448 Include files and directories. Is the default behaviour when
450 are specified above. Causes tar files to be included in an extract or create
451 (and therefore everything else to be excluded). See example below.
452 Filename globbing does not work for included files for extractions (yet).
455 Exclude files and directories. Causes tar files to be excluded from
456 an extract or create. See example below.
457 Filename globbing does not work for excluded files (yet).
460 Blocksize. Must be followed by a valid (greater than zero) blocksize.
461 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
465 Incremental. Only back up files that have the archive bit set. Useful
471 Quiet. Keeps tar from printing diagnostics as it works. This is the
472 same as tarmode quiet.
475 Newer than. Must be followed by the name of a file whose date is
476 compared against files found on the share during a create. Only files
477 newer than the file specified are backed up to the tar file. Useful
483 Set archive bit. Causes the archive bit to be reset when a file is backed
493 smbclient's tar option now supports long file names both on backup and
494 restore. However, the full path name of the file must be less than 1024 bytes.
495 Also, when a tar archive is created, smbclient's tar option places all files
496 in the archive with relative names, not absolute names.
500 All file names can be given as DOS path names (with \e as the component
501 separator) or as UNIX path names (with / as the component separator).
505 smbclient \e\emypc\emyshare "" -N -Tx backup.tar
507 Restore from tar file backup.tar into myshare on mypc (no password on share).
509 smbclient \e\emypc\emyshare "" -N -TXx backup.tar users/docs
511 Restore everything except users/docs
513 smbclient \e\emypc\emyshare "" -N -Tc backup.tar users/docs
515 Create a tar file of the files beneath users/docs.
517 smbclient \e\emypc\emyshare "" -N -tc backup.tar users\edocs
519 Create the same tar file as above, but now use a DOS path name.
521 smbclient \e\emypc\emyshare "" -N -Tc backup.tar \e*
523 Create a tar file of all the files and directories in the share.
531 Change to initial directory before starting. Probably only of any use
541 command string is a semicolon separated list of commands to be
542 executed instead of prompting from stdin.
547 This is particularly useful in scripts and for printing stdin to
548 the server, e.g. \-c 'print \-'.
551 Once the client is running, the user is presented with a prompt, "smb: \e>".
552 The backslash ("\e") indicates the current working directory on the server,
553 and will change if the current working directory is changed.
555 The prompt indicates that the client is ready and waiting to carry out a user
556 command. Each command is a single word, optionally followed by parameters
557 specific to that command. Command and parameters are space-delimited unless
558 these notes specifically state otherwise. All commands are case-insensitive.
559 Parameters to commands may or may not be case sensitive, depending on the
562 You can specify file names which have spaces in them by quoting the
563 name with double quotes, for example "a long file name".
565 Parameters shown in square brackets (eg., "[parameter]") are optional. If not
566 given, the command will use suitable defaults. Parameters shown in angle
567 brackets (eg., "<parameter>") are required.
569 Note that all commands operating on the server are actually performed by
570 issuing a request to the server. Thus the behaviour may vary from server to
571 server, depending on how the server was implemented.
573 The commands available are given here in alphabetical order.
588 command will display a brief informative message about the specified command.
590 If no command is specified, a list of available commands will be displayed.
607 command will execute a shell locally and run the specified shell command. If
608 no command is specified, a shell will be run.
623 is specified, the current working directory
625 will be changed to the directory specified. This operation will fail if for
626 any reason the specified directory is inaccessible.
628 If no directory name is specified, the current working directory
643 The client will request that the server attempt to delete all files matching
645 from the current working directory
659 A list of the files matching
661 in the current working directory
663 will be retrieved from the server and displayed.
676 Terminate the connection with the server and exit from the program.
684 .I <remote file name> [local file name]
691 from the server to the machine running the client. If specified, name the
694 Note that all transfers in
696 are binary. See also the
728 is specified, the current working directory
729 .B on the local machine
730 will be changed to the directory specified. This operation will fail if for
731 any reason the specified directory is inaccessible.
733 If no directory name is specified, the name of the current working directory
734 .B on the local machine
748 Toggle lowercasing of filenames for the
754 When lowercasing is toggled ON, local filenames are converted to lowercase
759 commands. This is often useful when copying (say) MSDOS files from a server,
760 because lowercase filenames are the norm on UNIX systems.
788 This command allows the user to set up a mask which will be used during
789 recursive operation of the
795 The masks specified to the
799 commands act as filters for directories
800 rather than files when recursion is toggled ON.
802 The mask specified with the
804 command is necessary to filter files within those directories. For example,
805 if the mask specified in an
809 the mask specified with the
813 recursion is toggled ON, the
815 command will retrieve all files matching "*.c" in all directories below
816 and including all directories matching "source*" in the current working
819 Note that the value for
821 defaults to blank (equivalent to "*") and remains so until the
823 command is used to change it. It retains the most recently specified value
824 indefinitely. To avoid unexpected results it would be wise to change the
827 back to "*" after using the
859 Copy all files matching
861 from the server to the machine running the client.
865 is interpreted differently during recursive operation and non-recursive
866 operation - refer to the
870 commands for more information. Note that all transfers in
872 are binary. See also the
887 Create a new directory
889 (user access privileges permitting) with the specified name.
902 Copy all files matching
904 in the current working directory
905 .B on the local machine
906 to the current working directory on the server.
910 is interpreted differently during recursive operation and non-recursive
911 operation - refer to the
915 commands for more information. Note that all transfers in
930 Print the specified file
931 .B from the local machine
932 through a printable service on the server.
944 .I <graphics or text>
949 Set the print mode to suit either binary data (such as graphical information)
952 commands will use the currently set print mode.
965 Toggle prompting for filenames during operation of the
971 When toggled ON, the user will be prompted to confirm the transfer of each
972 file during these commands. When toggled OFF, all specified files will be
973 transferred without prompting.
981 .I <local file name> [remote file name]
988 from the machine running the client to the server. If specified, name the
991 Note that all transfers in
993 are binary. See also the
1008 Displays the print queue, showing the job id, name, size and current status.
1051 Toggle directory recursion for the commands
1056 When toggled ON, these commands will process all directories in the source
1057 directory (i.e., the directory they are copying
1059 and will recurse into any that match the mask specified to the command. Only
1060 files that match the mask specified using the
1062 command will be retrieved. See also the
1066 When recursion is toggled OFF, only files from the current working
1067 directory on the source machine that match the mask specified to the
1071 commands will be copied, and any mask specified using the
1073 command will be ignored.
1086 Remove all files matching
1088 from the current working directory
1102 Remove the specified directory (user access privileges permitting)
1116 Performs a tar operation - see the
1118 command line option above. Behaviour
1119 may be affected by the
1121 command (see below). Using g (incremental) and N (newer) will affect
1122 tarmode settings. Note that using the "\-" option with tar x may not
1123 work - use the command line option instead.
1136 Blocksize. Must be followed by a valid (greater than zero) blocksize.
1137 Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte)
1146 .I <full|inc|reset|noreset>
1151 Changes tar's behaviour with regard to archive bits. In full mode,
1152 tar will back up everything regardless of the archive bit setting (this
1153 is the default mode). In incremental mode, tar will only back up files
1154 with the archive bit set. In reset mode, tar will reset the archive bit
1155 on all files it backs up (implies read/write share).
1163 .I <filename> <perm=[+|\-]rsha>
1168 A version of the DOS attrib command to set file permissions. For example,
1172 would make myfile read only.
1176 Some servers are fussy about the case of supplied usernames, passwords, share
1177 names (aka service names) and machine names. If you fail to connect try
1178 giving all parameters in uppercase.
1180 It is often necessary to use the
1182 option when connecting to some types
1183 of servers. For example OS/2 LanManager insists on a valid netbios name
1184 being used, so you need to supply a valid name that would be known to
1188 supports long file names where the server supports the LANMAN2
1192 .SH ENVIRONMENT VARIABLES
1195 The variable USER may contain the username of the person using the client.
1196 This information is used only if the protocol level is high enough to support
1197 session-level passwords.
1200 The location of the client program is a matter for individual system
1201 administrators. The following are thus suggestions only.
1203 It is recommended that the client software be installed under the
1205 hierarchy, in a directory readable by all, writeable only by root. The client
1206 program itself should be executable by all. The client should NOT be setuid
1209 The client log files should be put in a directory readable and writable only
1212 To test the client, you will need to know the name of a running Lan manager
1213 server. It is possible to run
1217 as an ordinary user - running that server as a daemon on a
1218 user-accessible port (typically any port number over 1024) would
1219 provide a suitable test server.
1221 This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
1222 of the recent patches to it. These notes will necessarily lag behind
1223 development of the client software, so it is possible that your version of
1224 the client has extensions or parameter semantics that differ from or are not
1225 covered by this man page. Please notify these to the address below for
1230 [This section under construction]
1232 Most diagnostics issued by the client are logged in a specified log file. The
1233 log file name is specified at compile time, but may be overridden on the
1236 The number and nature of diagnostics available depends on the debug level used
1237 by the client. If you have problems, set the debug level to 3 and peruse the
1240 Most messages are reasonably self-explanatory. Unfortunately, at time of
1241 creation of this man page the source code is still too fluid to warrant
1242 describing each and every diagnostic. At this stage your best bet is still
1243 to grep the source code and inspect the conditions that gave rise to the
1244 diagnostics you are seeing.
1248 The original Samba software and related utilities were created by
1249 Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
1250 of the Source for this project.
1254 for a full list of contributors and details on how to
1255 submit bug reports, comments etc.