1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="smbclient.1">
6 <refentrytitle>smbclient</refentrytitle>
7 <manvolnum>1</manvolnum>
8 <refmiscinfo class="source">Samba</refmiscinfo>
9 <refmiscinfo class="manual">User Commands</refmiscinfo>
10 <refmiscinfo class="version">&doc.version;</refmiscinfo>
15 <refname>smbclient</refname>
16 <refpurpose>ftp-like client to access SMB/CIFS resources
17 on servers</refpurpose>
22 <command>smbclient</command>
23 <arg choice="opt">-b <buffer size></arg>
24 <arg choice="opt">-d debuglevel</arg>
25 <arg choice="opt">-e</arg>
26 <arg choice="opt">-L <netbios name></arg>
27 <arg choice="opt">-U username</arg>
28 <arg choice="opt">-I destinationIP</arg>
29 <arg choice="opt">-M <netbios name></arg>
30 <arg choice="opt">-m maxprotocol</arg>
31 <arg choice="opt">-A authfile</arg>
32 <arg choice="opt">-N</arg>
33 <arg choice="opt">-C</arg>
34 <arg choice="opt">-g</arg>
35 <arg choice="opt">-i scope</arg>
36 <arg choice="opt">-O <socket options></arg>
37 <arg choice="opt">-p port</arg>
38 <arg choice="opt">-R <name resolve order></arg>
39 <arg choice="opt">-s <smb config file></arg>
40 <arg choice="opt">-t <per-operation timeout in seconds></arg>
41 <arg choice="opt">-k</arg>
42 <arg choice="opt">-P</arg>
43 <arg choice="opt">-c <command></arg>
47 <command>smbclient</command>
48 <arg choice="req">servicename</arg>
49 <arg choice="opt">password</arg>
50 <arg choice="opt">-b <buffer size></arg>
51 <arg choice="opt">-d debuglevel</arg>
52 <arg choice="opt">-e</arg>
53 <arg choice="opt">-D Directory</arg>
54 <arg choice="opt">-U username</arg>
55 <arg choice="opt">-W workgroup</arg>
56 <arg choice="opt">-M <netbios name></arg>
57 <arg choice="opt">-m maxprotocol</arg>
58 <arg choice="opt">-A authfile</arg>
59 <arg choice="opt">-N</arg>
60 <arg choice="opt">-C</arg>
61 <arg choice="opt">-g</arg>
62 <arg choice="opt">-l log-basename</arg>
63 <arg choice="opt">-I destinationIP</arg>
64 <arg choice="opt">-E</arg>
65 <arg choice="opt">-c <command string></arg>
66 <arg choice="opt">-i scope</arg>
67 <arg choice="opt">-O <socket options></arg>
68 <arg choice="opt">-p port</arg>
69 <arg choice="opt">-R <name resolve order></arg>
70 <arg choice="opt">-s <smb config file></arg>
71 <arg choice="opt">-t <per-operation timeout in seconds></arg>
72 <arg choice="opt">-T<c|x>IXFqgbNan</arg>
73 <arg choice="opt">-k</arg>
78 <title>DESCRIPTION</title>
80 <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
81 <manvolnum>7</manvolnum></citerefentry> suite.</para>
83 <para><command>smbclient</command> is a client that can
84 'talk' to an SMB/CIFS server. It offers an interface
85 similar to that of the ftp program (see <citerefentry><refentrytitle>ftp</refentrytitle>
86 <manvolnum>1</manvolnum></citerefentry>).
87 Operations include things like getting files from the server
88 to the local machine, putting files from the local machine to
89 the server, retrieving directory information from the server
95 <title>OPTIONS</title>
99 <term>servicename</term>
100 <listitem><para>servicename is the name of the service
101 you want to use on the server. A service name takes the form
102 <filename>//server/service</filename> where <parameter>server
103 </parameter> is the NetBIOS name of the SMB/CIFS server
104 offering the desired service and <parameter>service</parameter>
105 is the name of the service offered. Thus to connect to
106 the service "printer" on the SMB/CIFS server "smbserver",
107 you would use the servicename <filename>//smbserver/printer
110 <para>Note that the server name required is NOT necessarily
111 the IP (DNS) host name of the server ! The name required is
112 a NetBIOS server name, which may or may not be the
113 same as the IP hostname of the machine running the server.
116 <para>The server name is looked up according to either
117 the <parameter>-R</parameter> parameter to <command>smbclient</command> or
118 using the name resolve order parameter in
119 the <citerefentry><refentrytitle>smb.conf</refentrytitle>
120 <manvolnum>5</manvolnum></citerefentry> file,
121 allowing an administrator to change the order and methods
122 by which server names are looked up. </para></listitem>
126 <term>password</term>
127 <listitem><para>The password required to access the specified
128 service on the specified server. If this parameter is
129 supplied, the <parameter>-N</parameter> option (suppress
130 password prompt) is assumed. </para>
132 <para>There is no default password. If no password is supplied
133 on the command line (either by using this parameter or adding
134 a password to the <parameter>-U</parameter> option (see
135 below)) and the <parameter>-N</parameter> option is not
136 specified, the client will prompt for a password, even if
137 the desired service does not require one. (If no password is
138 required, simply press ENTER to provide a null password.)
141 <para>Note: Some servers (including OS/2 and Windows for
142 Workgroups) insist on an uppercase password. Lowercase
143 or mixed case passwords may be rejected by these servers.
146 <para>Be cautious about including passwords in scripts.
151 <term>-R|--name-resolve <name resolve order></term>
152 <listitem><para>This option is used by the programs in the Samba
153 suite to determine what naming services and in what order to resolve
154 host names to IP addresses. The option takes a space-separated
155 string of different name resolution options.</para>
157 <para>The options are :"lmhosts", "host", "wins" and "bcast". They
158 cause names to be resolved as follows:</para>
161 <listitem><para><constant>lmhosts</constant>: Lookup an IP
162 address in the Samba lmhosts file. If the line in lmhosts has
163 no name type attached to the NetBIOS name (see
164 the <citerefentry><refentrytitle>lmhosts</refentrytitle>
165 <manvolnum>5</manvolnum></citerefentry> for details) then
166 any name type matches for lookup.</para>
169 <listitem><para><constant>host</constant>: Do a standard host
170 name to IP address resolution, using the system <filename>/etc/hosts
171 </filename>, NIS, or DNS lookups. This method of name resolution
172 is operating system dependent, for instance on IRIX or Solaris this
173 may be controlled by the <filename>/etc/nsswitch.conf</filename>
174 file). Note that this method is only used if the NetBIOS name
175 type being queried is the 0x20 (server) name type, otherwise
176 it is ignored.</para>
179 <listitem><para><constant>wins</constant>: Query a name with
180 the IP address listed in the <parameter>wins server</parameter>
181 parameter. If no WINS server has
182 been specified this method will be ignored.</para>
185 <listitem><para><constant>bcast</constant>: Do a broadcast on
186 each of the known local interfaces listed in the
187 <parameter>interfaces</parameter>
188 parameter. This is the least reliable of the name resolution
189 methods as it depends on the target host being on a locally
190 connected subnet.</para>
194 <para>If this parameter is not set then the name resolve order
195 defined in the <citerefentry><refentrytitle>smb.conf</refentrytitle>
196 <manvolnum>5</manvolnum></citerefentry> file parameter
197 (name resolve order) will be used. </para>
199 <para>The default order is lmhosts, host, wins, bcast and without
200 this parameter or any entry in the <parameter>name resolve order
201 </parameter> parameter of the <citerefentry><refentrytitle>smb.conf</refentrytitle>
202 <manvolnum>5</manvolnum></citerefentry> file the name resolution
203 methods will be attempted in this order. </para></listitem>
208 <term>-M|--message NetBIOS name</term>
209 <listitem><para>This options allows you to send messages, using
210 the "WinPopup" protocol, to another computer. Once a connection is
211 established you then type your message, pressing ^D (control-D) to
214 <para>If the receiving computer is running WinPopup the user will
215 receive the message and probably a beep. If they are not running
216 WinPopup the message will be lost, and no error message will
219 <para>The message is also automatically truncated if the message
220 is over 1600 bytes, as this is the limit of the protocol.
224 One useful trick is to pipe the message through <command>smbclient</command>.
225 For example: smbclient -M FRED < mymessage.txt will send the
226 message in the file <filename>mymessage.txt</filename> to the
230 <para>You may also find the <parameter>-U</parameter> and
231 <parameter>-I</parameter> options useful, as they allow you to
232 control the FROM and TO parts of the message. </para>
234 <para>See the <parameter>message command</parameter> parameter in the <citerefentry><refentrytitle>smb.conf</refentrytitle>
235 <manvolnum>5</manvolnum></citerefentry> for a description of how to handle incoming
236 WinPopup messages in Samba. </para>
238 <para><emphasis>Note</emphasis>: Copy WinPopup into the startup group
239 on your WfWg PCs if you want them to always be able to receive
240 messages. </para></listitem>
244 <term>-p|--port port</term>
245 <listitem><para>This number is the TCP port number that will be used
246 when making connections to the server. The standard (well-known)
247 TCP port number for an SMB/CIFS server is 139, which is the
248 default. </para></listitem>
252 <term>-g|--grepable</term>
253 <listitem><para>This parameter provides combined with
254 <parameter>-L</parameter> easy parseable output that allows processing
255 with utilities such as grep and cut.
260 <term>-m|--max-protocol protocol</term>
261 <listitem><para>This allows the user to select the
262 highest SMB protocol level that smbclient will use to
263 connect to the server. By default this is set to
264 NT1, which is the highest available SMB1 protocol.
265 To connect using SMB2 or SMB3 protocol, use the
266 strings SMB2 or SMB3 respectively. Note that to connect
267 to a Windows 2012 server with encrypted transport selecting
268 a max-protocol of SMB3 is required.
273 <term>-P|--machine-pass</term>
275 Make queries to the external server using the machine account of the local server.
280 <term>-I|--ip-address IP-address</term>
281 <listitem><para><replaceable>IP address</replaceable> is the address of the server to connect to.
282 It should be specified in standard "a.b.c.d" notation. </para>
284 <para>Normally the client would attempt to locate a named
285 SMB/CIFS server by looking it up via the NetBIOS name resolution
286 mechanism described above in the <parameter>name resolve order</parameter>
287 parameter above. Using this parameter will force the client
288 to assume that the server is on the machine with the specified IP
289 address and the NetBIOS name component of the resource being
290 connected to will be ignored. </para>
292 <para>There is no default for this parameter. If not supplied,
293 it will be determined automatically by the client as described
294 above. </para></listitem>
298 <term>-E|--stderr</term>
299 <listitem><para>This parameter causes the client to write messages
300 to the standard error stream (stderr) rather than to the standard
301 output stream. </para>
303 <para>By default, the client writes messages to standard output
304 - typically the user's tty. </para></listitem>
308 <term>-L|--list</term>
309 <listitem><para>This option allows you to look at what services
310 are available on a server. You use it as <command>smbclient -L
311 host</command> and a list should appear. The <parameter>-I
312 </parameter> option may be useful if your NetBIOS names don't
313 match your TCP/IP DNS host names or if you are trying to reach a
314 host on another network. </para></listitem>
318 <term>-b|--send-buffer buffersize</term>
320 When sending or receiving files, smbclient uses an
321 internal buffer sized by the maximum number of allowed requests
322 to the connected server. This command allows this size to be set to any
323 range between 0 (which means use the default server controlled size) bytes
324 and 16776960 (0xFFFF00) bytes. Using the server controlled size is the
325 most efficient as smbclient will pipeline as many simultaneous reads or
326 writes needed to keep the server as busy as possible. Setting this to
327 any other size will slow down the transfer. This can also be set
328 using the <command>iosize</command> command inside smbclient.
333 <term>-B|--browse</term>
334 <listitem><para>Browse SMB servers using DNS.</para>
338 &stdarg.client.debug;
340 &popt.common.credentials;
341 &popt.common.connection;
345 <term>-t|--timeout <timeout-seconds></term>
346 <listitem><para>This allows the user to tune the default
347 timeout used for each SMB request. The default setting is
348 20 seconds. Increase it if requests to the server sometimes
349 time out. This can happen when SMB3 encryption is selected
350 and smbclient is overwhelming the server with requests.
351 This can also be set using the <command>timeout</command>
352 command inside smbclient.
357 <term>-T|--tar tar options</term>
358 <listitem><para>smbclient may be used to create <command>tar(1)
359 </command> compatible backups of all the files on an SMB/CIFS
360 share. The secondary tar flags that can be given to this option
364 <listitem><para><parameter>c</parameter> - Create a tar
365 backup archive on the local system. Must be followed by
366 the name of a tar file, tape device or "-" for standard
367 output. If using standard output you must turn the log
368 level to its lowest value -d0 to avoid corrupting your tar
369 file. This flag is mutually exclusive with the
370 <parameter>x</parameter> flag. </para></listitem>
372 <listitem><para><parameter>x</parameter> - Extract (restore) a local
373 tar file back to a share. Unless the -D option is given, the tar
374 files will be restored from the top level of the share. Must be
375 followed by the name of the tar file, device or "-" for standard
376 input. Mutually exclusive with the <parameter>c</parameter> flag.
377 Restored files have their creation times (mtime) set to the
378 date saved in the tar file. Directories currently do not get
379 their creation dates restored properly. </para></listitem>
381 <listitem><para><parameter>I</parameter> - Include files and directories.
382 Is the default behavior when filenames are specified above. Causes
383 files to be included in an extract or create (and therefore
384 everything else to be excluded). See example below. Filename globbing
385 works in one of two ways. See <parameter>r</parameter> below. </para></listitem>
387 <listitem><para><parameter>X</parameter> - Exclude files and directories.
388 Causes files to be excluded from an extract or create. See
389 example below. Filename globbing works in one of two ways.
390 See <parameter>r</parameter> below. </para></listitem>
392 <listitem><para><parameter>F</parameter> - File containing a list of files and directories.
393 The <parameter>F</parameter> causes the name following the tarfile to
394 create to be read as a filename that contains a list of files and directories to
395 be included in an extract or create (and therefore everything else to be excluded).
396 See example below. Filename globbing works in one of two ways.
397 See <parameter>r</parameter> below.
400 <listitem><para><parameter>b</parameter> - Blocksize. Must be followed
401 by a valid (greater than zero) blocksize. Causes tar file to be
402 written out in blocksize*TBLOCK (512 byte) blocks.
405 <listitem><para><parameter>g</parameter> - Incremental. Only back up
406 files that have the archive bit set. Useful only with the
407 <parameter>c</parameter> flag. </para></listitem>
409 <listitem><para><parameter>q</parameter> - Quiet. Keeps tar from printing
410 diagnostics as it works. This is the same as tarmode quiet.
413 <listitem><para><parameter>r</parameter> - Use wildcard
414 matching to include or exclude. Deprecated.
417 <listitem><para><parameter>N</parameter> - Newer than. Must be followed
418 by the name of a file whose date is compared against files found
419 on the share during a create. Only files newer than the file
420 specified are backed up to the tar file. Useful only with the
421 <parameter>c</parameter> flag. </para></listitem>
423 <listitem><para><parameter>a</parameter> - Set archive bit. Causes the
424 archive bit to be reset when a file is backed up. Useful with the
425 <parameter>g</parameter> and <parameter>c</parameter> flags.
429 <para><emphasis>Tar Long File Names</emphasis></para>
431 <para><command>smbclient</command>'s tar option now supports long
432 file names both on backup and restore. However, the full path
433 name of the file must be less than 1024 bytes. Also, when
434 a tar archive is created, <command>smbclient</command>'s tar option places all
435 files in the archive with relative names, not absolute names.
438 <para><emphasis>Tar Filenames</emphasis></para>
440 <para>All file names can be given as DOS path names (with '\\'
441 as the component separator) or as UNIX path names (with '/' as
442 the component separator). </para>
444 <para><emphasis>Examples</emphasis></para>
446 <para>Restore from tar file <filename>backup.tar</filename> into myshare on mypc
447 (no password on share). </para>
449 <para><command>smbclient //mypc/myshare "" -N -Tx backup.tar
452 <para>Restore everything except <filename>users/docs</filename>
455 <para><command>smbclient //mypc/myshare "" -N -TXx backup.tar
456 users/docs</command></para>
458 <para>Create a tar file of the files beneath <filename>
459 users/docs</filename>. </para>
461 <para><command>smbclient //mypc/myshare "" -N -Tc
462 backup.tar users/docs </command></para>
464 <para>Create the same tar file as above, but now use
465 a DOS path name. </para>
467 <para><command>smbclient //mypc/myshare "" -N -Tc backup.tar
468 users\edocs </command></para>
470 <para>Create a tar file of the files listed in the file <filename>tarlist</filename>.</para>
472 <para><command>smbclient //mypc/myshare "" -N -TcF
473 backup.tar tarlist</command></para>
475 <para>Create a tar file of all the files and directories in
478 <para><command>smbclient //mypc/myshare "" -N -Tc backup.tar *
484 <term>-D|--directory initial directory</term>
485 <listitem><para>Change to initial directory before starting. Probably
486 only of any use with the tar -T option. </para></listitem>
490 <term>-c|--command command string</term>
491 <listitem><para>command string is a semicolon-separated list of
492 commands to be executed instead of prompting from stdin. <parameter>
493 -N</parameter> is implied by <parameter>-c</parameter>.</para>
495 <para>This is particularly useful in scripts and for printing stdin
496 to the server, e.g. <command>-c 'print -'</command>. </para></listitem>
504 <title>OPERATIONS</title>
506 <para>Once the client is running, the user is presented with
509 <para><prompt>smb:\> </prompt></para>
511 <para>The backslash ("\\") indicates the current working directory
512 on the server, and will change if the current working directory
515 <para>The prompt indicates that the client is ready and waiting to
516 carry out a user command. Each command is a single word, optionally
517 followed by parameters specific to that command. Command and parameters
518 are space-delimited unless these notes specifically
519 state otherwise. All commands are case-insensitive. Parameters to
520 commands may or may not be case sensitive, depending on the command.
523 <para>You can specify file names which have spaces in them by quoting
524 the name with double quotes, for example "a long file name". </para>
526 <para>Parameters shown in square brackets (e.g., "[parameter]") are
527 optional. If not given, the command will use suitable defaults. Parameters
528 shown in angle brackets (e.g., "<parameter>") are required.
532 <para>Note that all commands operating on the server are actually
533 performed by issuing a request to the server. Thus the behavior may
534 vary from server to server, depending on how the server was implemented.
537 <para>The commands available are given here in alphabetical order. </para>
541 <term>? [command]</term>
542 <listitem><para>If <replaceable>command</replaceable> is specified, the ? command will display
543 a brief informative message about the specified command. If no
544 command is specified, a list of available commands will
545 be displayed. </para></listitem>
549 <term>! [shell command]</term>
550 <listitem><para>If <replaceable>shell command</replaceable> is specified, the !
551 command will execute a shell locally and run the specified shell
552 command. If no command is specified, a local shell will be run.
557 <term>allinfo file</term>
558 <listitem><para>The client will request that the server return
559 all known information about a file or directory (including streams).
564 <term>altname file</term>
565 <listitem><para>The client will request that the server return
566 the "alternate" name (the 8.3 name) for a file or directory.
571 <term>archive <number></term>
572 <listitem><para>Sets the archive level when operating on files.
573 0 means ignore the archive bit, 1 means only operate on files with this bit set,
574 2 means only operate on files with this bit set and reset it after operation,
575 3 means operate on all files and reset it after operation. The default is 0.
581 <listitem><para>Toggle the state of the "backup intent" flag
582 sent to the server on directory listings and file opens. If
583 the "backup intent" flag is true, the server will try and
584 bypass some file system checks if the user has been granted
585 SE_BACKUP or SE_RESTORE privileges. This state is useful when
586 performing a backup or restore operation.
591 <term>blocksize <number></term>
592 <listitem><para>Sets the blocksize parameter for a tar operation. The default is 20.
593 Causes tar file to be written out in blocksize*TBLOCK (normally 512 byte) units.
598 <term>cancel jobid0 [jobid1] ... [jobidN]</term>
599 <listitem><para>The client will request that the server cancel
600 the printjobs identified by the given numeric print job ids.
605 <term>case_sensitive</term>
606 <listitem><para>Toggles the setting of the flag in SMB packets that
607 tells the server to treat filenames as case sensitive. Set to OFF by
608 default (tells file server to treat filenames as case insensitive). Only
609 currently affects Samba 3.0.5 and above file servers with the case sensitive
610 parameter set to auto in the smb.conf.
615 <term>cd <directory name></term>
616 <listitem><para>If "directory name" is specified, the current
617 working directory on the server will be changed to the directory
618 specified. This operation will fail if for any reason the specified
619 directory is inaccessible. </para>
621 <para>If no directory name is specified, the current working
622 directory on the server will be reported. </para></listitem>
626 <term>chmod file mode in octal</term>
627 <listitem><para>This command depends on the server supporting the CIFS
628 UNIX extensions and will fail if the server does not. The client requests that the server
629 change the UNIX permissions to the given octal mode, in standard UNIX format.
634 <term>chown file uid gid</term>
635 <listitem><para>This command depends on the server supporting the CIFS
636 UNIX extensions and will fail if the server does not. The client requests that the server
637 change the UNIX user and group ownership to the given decimal values. Note there is
638 currently no way to remotely look up the UNIX uid and gid values for a given name.
639 This may be addressed in future versions of the CIFS UNIX extensions.
644 <term>close <fileid></term>
645 <listitem><para>Closes a file explicitly opened by the open command. Used for
646 internal Samba testing purposes.
651 <term>del <mask></term>
652 <listitem><para>The client will request that the server attempt
653 to delete all files matching <replaceable>mask</replaceable> from the current working
654 directory on the server. </para></listitem>
658 <term>deltree <mask></term>
659 <listitem><para>The client will request that the server attempt
660 to delete all files and directories matching <replaceable>mask</replaceable> from the current working
661 directory on the server. Note this will recursively delete files and directories within
662 the directories selected even without the recurse command being set. If any of the delete
663 requests fail the command will stop processing at that point, leaving files and directories
664 not yet processed untouched. This is by design.</para></listitem>
668 <term>dir <mask></term>
669 <listitem><para>A list of the files matching <replaceable>mask</replaceable> in the current
670 working directory on the server will be retrieved from the server
671 and displayed. </para></listitem>
675 <term>du <filename></term>
676 <listitem><para>Does a directory listing and then prints out the current disk usage and free space on a share.
681 <term>echo <number> <data></term>
682 <listitem><para>Does an SMBecho request to ping the server. Used for internal Samba testing purposes.
688 <listitem><para>Terminate the connection with the server and exit
689 from the program. </para></listitem>
693 <term>get <remote file name> [local file name]</term>
694 <listitem><para>Copy the file called <filename>remote file name</filename> from
695 the server to the machine running the client. If specified, name
696 the local copy <filename>local file name</filename>. Note that all transfers in
697 <command>smbclient</command> are binary. See also the
698 lowercase command. </para></listitem>
702 <term>getfacl <filename></term>
703 <listitem><para>Requires the server support the UNIX extensions. Requests and prints
704 the POSIX ACL on a file.
709 <term>hardlink <src> <dest></term>
710 <listitem><para>Creates a hardlink on the server using Windows CIFS semantics.
715 <term>help [command]</term>
716 <listitem><para>See the ? command above. </para></listitem>
720 <term>history</term> <listitem><para>Displays the command history.</para></listitem>
724 <term>iosize <bytes></term>
726 When sending or receiving files, smbclient uses an
727 internal buffer sized by the maximum number of allowed requests
728 to the connected server. This command allows this size to be set to any
729 range between 0 (which means use the default server controlled size) bytes
730 and 16776960 (0xFFFF00) bytes. Using the server controlled size is the
731 most efficient as smbclient will pipeline as many simultaneous reads or
732 writes needed to keep the server as busy as possible. Setting this to
733 any other size will slow down the transfer.
738 <term>lcd [directory name]</term>
739 <listitem><para>If <replaceable>directory name</replaceable> is specified, the current
740 working directory on the local machine will be changed to
741 the directory specified. This operation will fail if for any
742 reason the specified directory is inaccessible. </para>
744 <para>If no directory name is specified, the name of the
745 current working directory on the local machine will be reported.
750 <term>link target linkname</term>
751 <listitem><para>This command depends on the server supporting the CIFS
752 UNIX extensions and will fail if the server does not. The client requests that the server
753 create a hard link between the linkname and target files. The linkname file
759 <term>listconnect</term>
760 <listitem><para>Show the current connections held for DFS purposes.
765 <term>lock <filenum> <r|w> <hex-start> <hex-len></term>
766 <listitem><para>This command depends on the server supporting the CIFS
767 UNIX extensions and will fail if the server does not. Tries to set a POSIX
768 fcntl lock of the given type on the given range. Used for internal Samba testing purposes.
773 <term>logon <username> <password></term>
774 <listitem><para>Establishes a new vuid for this session by logging on again.
775 Replaces the current vuid. Prints out the new vuid. Used for internal Samba testing purposes.
781 <listitem><para>Logs the user off the server, closing the session.
782 Used for internal Samba testing purposes.
787 <term>lowercase</term>
788 <listitem><para>Toggle lowercasing of filenames for the get and
792 <para>When lowercasing is toggled ON, local filenames are converted
793 to lowercase when using the get and mget commands. This is
794 often useful when copying (say) MSDOS files from a server, because
795 lowercase filenames are the norm on UNIX systems. </para></listitem>
799 <term>ls <mask></term>
800 <listitem><para>See the dir command above. </para></listitem>
804 <term>mask <mask></term>
805 <listitem><para>This command allows the user to set up a mask
806 which will be used during recursive operation of the mget and
807 mput commands. </para>
809 <para>The masks specified to the mget and mput commands act as
810 filters for directories rather than files when recursion is
813 <para>The mask specified with the mask command is necessary
814 to filter files within those directories. For example, if the
815 mask specified in an mget command is "source*" and the mask
816 specified with the mask command is "*.c" and recursion is
817 toggled ON, the mget command will retrieve all files matching
818 "*.c" in all directories below and including all directories
819 matching "source*" in the current working directory. </para>
821 <para>Note that the value for mask defaults to blank (equivalent
822 to "*") and remains so until the mask command is used to change it.
823 It retains the most recently specified value indefinitely. To
824 avoid unexpected results it would be wise to change the value of
825 mask back to "*" after using the mget or mput commands. </para></listitem>
829 <term>md <directory name></term>
830 <listitem><para>See the mkdir command. </para></listitem>
834 <term>mget <mask></term>
835 <listitem><para>Copy all files matching <replaceable>mask</replaceable> from the server to
836 the machine running the client. </para>
838 <para>Note that <replaceable>mask</replaceable> is interpreted differently during recursive
839 operation and non-recursive operation - refer to the recurse and
840 mask commands for more information. Note that all transfers in
841 <command>smbclient</command> are binary. See also the lowercase command. </para></listitem>
845 <term>mkdir <directory name></term>
846 <listitem><para>Create a new directory on the server (user access
847 privileges permitting) with the specified name. </para></listitem>
851 <term>more <file name></term>
852 <listitem><para>Fetch a remote file and view it with the contents
853 of your PAGER environment variable.
858 <term>mput <mask></term>
859 <listitem><para>Copy all files matching <replaceable>mask</replaceable> in the current working
860 directory on the local machine to the current working directory on
863 <para>Note that <replaceable>mask</replaceable> is interpreted differently during recursive
864 operation and non-recursive operation - refer to the recurse and mask
865 commands for more information. Note that all transfers in <command>smbclient</command>
866 are binary. </para></listitem>
870 <term>notify <dir name></term>
871 <listitem><para>Query a directory for change
872 notifications. This command issues a recursive
873 filechangenotify call for all possible changes. As
874 changes come in will print one line per change. See
875 <ulink url="https://msdn.microsoft.com/en-us/library/dn392331.aspx">https://msdn.microsoft.com/en-us/library/dn392331.aspx</ulink>
876 for a description of the action numbers that this
877 command prints.</para>
878 <para>This command never ends, it waits for event
885 <listitem><para>Query the remote server to see if it supports the CIFS UNIX
886 extensions and prints out the list of capabilities supported. If so, turn
887 on POSIX pathname processing and large file read/writes (if available),.
892 <term>posix_encrypt <domain> <username> <password></term>
893 <listitem><para>This command depends on the server supporting the CIFS
894 UNIX extensions and will fail if the server does not. Attempt to negotiate
895 SMB encryption on this connection. If smbclient connected with kerberos
896 credentials (-k) the arguments to this command are ignored and the kerberos
897 credentials are used to negotiate GSSAPI signing and sealing instead. See
898 also the -e option to smbclient to force encryption on initial connection.
899 This command is new with Samba 3.2.
904 <term>posix_open <filename> <octal mode></term>
905 <listitem><para>This command depends on the server supporting the CIFS
906 UNIX extensions and will fail if the server does not. Opens a remote file
907 using the CIFS UNIX extensions and prints a fileid. Used for internal Samba
913 <term>posix_mkdir <directoryname> <octal mode></term>
914 <listitem><para>This command depends on the server supporting the CIFS
915 UNIX extensions and will fail if the server does not. Creates a remote directory
916 using the CIFS UNIX extensions with the given mode.
921 <term>posix_rmdir <directoryname></term>
922 <listitem><para>This command depends on the server supporting the CIFS
923 UNIX extensions and will fail if the server does not. Deletes a remote directory
924 using the CIFS UNIX extensions.
929 <term>posix_unlink <filename></term>
930 <listitem><para>This command depends on the server supporting the CIFS
931 UNIX extensions and will fail if the server does not. Deletes a remote file
932 using the CIFS UNIX extensions.
937 <term>posix_whoami</term>
938 <listitem><para>Query the remote server for the user token using the CIFS UNIX
939 extensions WHOAMI call. Prints out the guest status, user, group, group list and
940 sid list that the remote server is using on behalf of the logged on user.
945 <term>print <file name></term>
946 <listitem><para>Print the specified file from the local machine
947 through a printable service on the server. </para></listitem>
952 <listitem><para>Toggle prompting for filenames during operation
953 of the mget and mput commands. </para>
955 <para>When toggled ON, the user will be prompted to confirm
956 the transfer of each file during these commands. When toggled
957 OFF, all specified files will be transferred without prompting.
962 <term>put <local file name> [remote file name]</term>
963 <listitem><para>Copy the file called <filename>local file name</filename> from the
964 machine running the client to the server. If specified,
965 name the remote copy <filename>remote file name</filename>. Note that all transfers
966 in <command>smbclient</command> are binary. See also the lowercase command.
972 <listitem><para>Displays the print queue, showing the job id,
973 name, size and current status. </para></listitem>
978 <listitem><para>See the exit command. </para></listitem>
982 <term>readlink symlinkname</term>
983 <listitem><para>This command depends on the server supporting the CIFS
984 UNIX extensions and will fail if the server does not. Print
985 the value of the symlink "symlinkname".
990 <term>rd <directory name></term>
991 <listitem><para>See the rmdir command. </para></listitem>
996 <listitem><para>Toggle directory recursion for the commands mget
999 <para>When toggled ON, these commands will process all directories
1000 in the source directory (i.e., the directory they are copying
1001 from ) and will recurse into any that match the mask specified
1002 to the command. Only files that match the mask specified using
1003 the mask command will be retrieved. See also the mask command.
1006 <para>When recursion is toggled OFF, only files from the current
1007 working directory on the source machine that match the mask specified
1008 to the mget or mput commands will be copied, and any mask specified
1009 using the mask command will be ignored. </para></listitem>
1013 <term>rename <old filename> <new filename> [-f]</term>
1014 <listitem><para>Rename files in the current working directory on the
1015 server from <replaceable>old filename</replaceable> to
1016 <replaceable>new filename</replaceable>. The optional
1017 -f switch allows for superseding the destination file,
1018 if it exists. This is supported by NT1 protocol dialect
1019 and SMB2 protocol family.</para></listitem>
1023 <term>rm <mask></term>
1024 <listitem><para>Remove all files matching <replaceable>mask</replaceable> from the current
1025 working directory on the server. </para></listitem>
1029 <term>rmdir <directory name></term>
1030 <listitem><para>Remove the specified directory (user access
1031 privileges permitting) from the server. </para></listitem>
1035 <term>scopy <source filename> <destination filename></term>
1036 <listitem><para>Attempt to copy a file on the server using the
1037 most efficient server-side copy calls. Falls back to using
1038 read then write if server doesn't support server-side copy.
1043 <term>setmode <filename> <perm=[+|\-]rsha></term>
1044 <listitem><para>A version of the DOS attrib command to set
1045 file permissions. For example: </para>
1047 <para><command>setmode myfile +r </command></para>
1049 <para>would make myfile read only. </para></listitem>
1053 <term>showconnect</term>
1054 <listitem><para>Show the currently active connection held for DFS purposes.
1059 <term>stat file</term>
1060 <listitem><para>This command depends on the server supporting the CIFS
1061 UNIX extensions and will fail if the server does not. The client requests the
1062 UNIX basic info level and prints out the same info that the Linux stat command
1063 would about the file. This includes the size, blocks used on disk, file type,
1064 permissions, inode number, number of links and finally the three timestamps
1065 (access, modify and change). If the file is a special file (symlink, character or
1066 block device, fifo or socket) then extra information may also be printed.
1071 <term>symlink target linkname</term>
1072 <listitem><para>This command depends on the server supporting the CIFS
1073 UNIX extensions and will fail if the server does not. The client requests that the server
1074 create a symbolic hard link between the target and linkname files. The linkname file
1075 must not exist. Note that the server will not create a link to any path that lies
1076 outside the currently connected share. This is enforced by the Samba server.
1081 <term>tar <c|x>[IXbgNa]</term>
1082 <listitem><para>Performs a tar operation - see the
1083 <parameter>-T</parameter> command line option above. Behavior
1084 may be affected by the tarmode command (see below). Using g
1085 (incremental) and N (newer) will affect tarmode settings. Note
1086 that using the "-" option with tar x may not work - use the
1087 command line option instead.</para></listitem>
1091 <term>blocksize <blocksize></term>
1092 <listitem><para>Blocksize. Must be followed by a valid (greater
1093 than zero) blocksize. Causes tar file to be written out in
1094 <replaceable>blocksize</replaceable>*TBLOCK (512 byte) blocks. </para></listitem>
1098 <term>tarmode <full|inc|reset|noreset|system|nosystem|hidden|nohidden></term>
1099 <listitem><para>Changes tar's behavior with regard to DOS
1100 attributes. There are 4 modes which can be turned on or
1103 <para>Incremental mode (default off). When off (using
1104 <command>full</command>) tar will back up everything
1105 regardless of the <emphasis>archive</emphasis> bit
1106 setting. When on (using <command>inc</command>), tar will only
1107 back up files with the archive bit set.</para>
1109 <para>Reset mode (default off). When on (using
1110 <command>reset</command>), tar will remove the archive bit on
1111 all files it backs up (implies read/write share). Use
1112 <command>noreset</command> to turn off.</para>
1114 <para>System mode (default on). When off, tar will not backup
1115 system files. Use <command>nosystem</command> to turn off.</para>
1117 <para>Hidden mode (default on). When off, tar will not backup
1118 hidden files. Use <command>nohidden</command> to turn off.</para>
1123 <term>timeout <per-operation timeout in seconds></term>
1124 <listitem><para>This allows the user to tune the default
1125 timeout used for each SMB request. The default setting is
1126 20 seconds. Increase it if requests to the server sometimes
1127 time out. This can happen when SMB3 encryption is selected
1128 and smbclient is overwhelming the server with requests.
1133 <term>unlock <filenum> <hex-start> <hex-len></term>
1134 <listitem><para>This command depends on the server supporting the CIFS
1135 UNIX extensions and will fail if the server does not. Tries to unlock a POSIX
1136 fcntl lock on the given range. Used for internal Samba testing purposes.
1142 <listitem><para>Prints the current volume name of the share.
1147 <term>vuid <number></term>
1148 <listitem><para>Changes the currently used vuid in the protocol to
1149 the given arbitrary number. Without an argument prints out the current
1150 vuid being used. Used for internal Samba testing purposes.
1155 <term>tcon <sharename></term>
1156 <listitem><para>Establishes a new tree connect (connection to a share).
1157 Replaces the current tree connect. Prints the new tid (tree id).
1158 Used for internal Samba testing purposes.
1164 <listitem><para>Close the current share connection (tree disconnect).
1165 Used for internal Samba testing purposes.
1170 <term>tid <number></term>
1171 <listitem><para>Changes the current tree id (tid) in the
1172 protocol to a new arbitrary number. Without an argument, it
1173 prints out the tid currently used.
1174 Used for internal Samba testing purposes.
1179 <term>utimes <filename> <create time> <access time> <write time> <
1180 change time></term>
1181 <listitem><para>Changes the timestamps on a file by name.
1182 Times should be specified in the format YY:MM:DD-HH:MM:SS or -1 for no change.
1190 <title>NOTES</title>
1192 <para>Some servers are fussy about the case of supplied usernames,
1193 passwords, share names (AKA service names) and machine names.
1194 If you fail to connect try giving all parameters in uppercase.
1197 <para>It is often necessary to use the -n option when connecting
1198 to some types of servers. For example OS/2 LanManager insists
1199 on a valid NetBIOS name being used, so you need to supply a valid
1200 name that would be known to the server.</para>
1202 <para>smbclient supports long file names where the server
1203 supports the LANMAN2 protocol or above. </para>
1207 <title>ENVIRONMENT VARIABLES</title>
1209 <para>The variable <envar>USER</envar> may contain the
1210 username of the person using the client. This information is
1211 used only if the protocol level is high enough to support
1212 session-level passwords.</para>
1215 <para>The variable <envar>PASSWD</envar> may contain
1216 the password of the person using the client. This information is
1217 used only if the protocol level is high enough to support
1218 session-level passwords. </para>
1223 <title>INSTALLATION</title>
1225 <para>The location of the client program is a matter for
1226 individual system administrators. The following are thus
1227 suggestions only. </para>
1229 <para>It is recommended that the smbclient software be installed
1230 in the <filename>/usr/local/samba/bin/</filename> or <filename>
1231 /usr/samba/bin/</filename> directory, this directory readable
1232 by all, writeable only by root. The client program itself should
1233 be executable by all. The client should <emphasis>NOT</emphasis> be
1234 setuid or setgid! </para>
1236 <para>The client log files should be put in a directory readable
1237 and writeable only by the user. </para>
1239 <para>To test the client, you will need to know the name of a
1240 running SMB/CIFS server. It is possible to run <citerefentry><refentrytitle>smbd</refentrytitle>
1241 <manvolnum>8</manvolnum></citerefentry> as an ordinary user - running that server as a daemon
1242 on a user-accessible port (typically any port number over 1024)
1243 would provide a suitable test server. </para>
1248 <title>DIAGNOSTICS</title>
1250 <para>Most diagnostics issued by the client are logged in a
1251 specified log file. The log file name is specified at compile time,
1252 but may be overridden on the command line. </para>
1254 <para>The number and nature of diagnostics available depends
1255 on the debug level used by the client. If you have problems,
1256 set the debug level to 3 and peruse the log files. </para>
1261 <title>VERSION</title>
1263 <para>This man page is part of version &doc.version; of the Samba suite.</para>
1268 <title>AUTHOR</title>
1270 <para>The original Samba software and related utilities
1271 were created by Andrew Tridgell. Samba is now developed
1272 by the Samba Team as an Open Source project similar
1273 to the way the Linux kernel is developed.</para>