docs/docbook/manpages/smbclient.1.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <refentry id="smbclient">
   3
   4 <refmeta>
   5         <refentrytitle>smbclient</refentrytitle>
   6         <manvolnum>1</manvolnum>
   7 </refmeta>
   8
   9
  10 <refnamediv>
  11         <refname>smbclient</refname>
  12         <refpurpose>ftp-like client to access SMB/CIFS resources
  13         on servers</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17         <cmdsynopsis>
  18                 <command>smbclient</command>
  19                 <arg choice="req">servicename</arg>
  20                 <arg choice="opt">password</arg>
  21                 <arg choice="opt">-b &lt;buffer size&gt;</arg>
  22                 <arg choice="opt">-d debuglevel</arg>
  23                 <arg choice="opt">-D Directory</arg>
  24                 <arg choice="opt">-S server</arg>
  25                 <arg choice="opt">-U username</arg>
  26                 <arg choice="opt">-W workgroup</arg>
  27                 <arg choice="opt">-M &lt;netbios name&gt;</arg>
  28                 <arg choice="opt">-m maxprotocol</arg>
  29                 <arg choice="opt">-A authfile</arg>
  30                 <arg choice="opt">-N</arg>
  31                 <arg choice="opt">-l logfile</arg>
  32                 <arg choice="opt">-L &lt;netbios name&gt;</arg>
  33                 <arg choice="opt">-I destinationIP</arg>
  34                 <arg choice="opt">-E &lt;terminal code&gt;</arg>
  35                 <arg choice="opt">-c &lt;command string&gt;</arg>
  36                 <arg choice="opt">-i scope</arg>
  37                 <arg choice="opt">-O &lt;socket options&gt;</arg>
  38                 <arg choice="opt">-p port</arg>
  39                 <arg choice="opt">-R &lt;name resolve order&gt;</arg>
  40                 <arg choice="opt">-s &lt;smb config file&gt;</arg>
  41                 <arg choice="opt">-T&lt;c|x&gt;IXFqgbNan</arg>
  42         </cmdsynopsis>
  43 </refsynopsisdiv>
  44
  45 <refsect1>
  46         <title>DESCRIPTION</title>
  47
  48         <para>This tool is part of the <ulink url="samba.7.html">
  49         Samba</ulink> suite.</para>
  50
  51         <para><command>smbclient</command> is a client that can
  52         'talk' to an SMB/CIFS server. It offers an interface
  53         similar to that of the ftp program (see <command>ftp(1)</command>).
  54         Operations include things like getting files from the server
  55         to the local machine, putting files from the local machine to
  56         the server, retrieving directory information from the server
  57         and so on. </para>
  58 </refsect1>
  59
  60
  61 <refsect1>
  62         <title>OPTIONS</title>
  63
  64         <variablelist>
  65                 <varlistentry>
  66                 <term>servicename</term>
  67                 <listitem><para>servicename is the name of the service
  68                 you want to use on the server. A service name takes the form
  69                 <filename>//server/service</filename> where <parameter>server
  70                 </parameter> is the NetBIOS name of the SMB/CIFS server
  71                 offering the desired service and <parameter>service</parameter>
  72                 is the name of the service offered.  Thus to connect to
  73                 the service "printer" on the SMB/CIFS server "smbserver",
  74                 you would use the servicename <filename>//smbserver/printer
  75                 </filename></para>
  76
  77                 <para>Note that the server name required is NOT necessarily
  78                 the IP (DNS) host name of the server !  The name required is
  79                 a NetBIOS server name, which may or may not be the
  80                 same as the IP hostname of the machine running the server.
  81                 </para>
  82
  83                 <para>The server name is looked up according to either
  84                 the <parameter>-R</parameter> parameter to smbclient or
  85                 using the name resolve order parameter in the smb.conf file,
  86                 allowing an administrator to change the order and methods
  87                 by which server names are looked up. </para></listitem>
  88                 </varlistentry>
  89
  90                 <varlistentry>
  91                 <term>password</term>
  92                 <listitem><para>The password required to access the specified
  93                 service on the specified server. If this parameter is
  94                 supplied, the <parameter>-N</parameter> option (suppress
  95                 password prompt) is assumed. </para>
  96
  97                 <para>There is no default password. If no password is supplied
  98                 on the command line (either by using this parameter or adding
  99                 a password to the <parameter>-U</parameter> option (see
 100                 below)) and the <parameter>-N</parameter> option is not
 101                 specified, the client will prompt for a password, even if
 102                 the desired service does not require one. (If no password is
 103                 required, simply press ENTER to provide a null password.)
 104                 </para>
 105
 106                 <para>Note: Some servers (including OS/2 and Windows for
 107                 Workgroups) insist on an uppercase password. Lowercase
 108                 or mixed case passwords may be rejected by these servers.
 109                 </para>
 110
 111                 <para>Be cautious about including passwords in scripts.
 112                 </para></listitem>
 113                 </varlistentry>
 114
 115                 <varlistentry>
 116                 <term>-s smb.conf</term>
 117                 <listitem><para>Specifies the location of the all important
 118                 <filename>smb.conf</filename> file. </para></listitem>
 119                 </varlistentry>
 120
 121                 <varlistentry>
 122                 <term>-O socket options</term>
 123                 <listitem><para>TCP socket options to set on the client
 124                 socket. See the socket options parameter in the <filename>
 125                 smb.conf (5)</filename> manpage for the list of valid
 126                 options. </para></listitem>
 127                 </varlistentry>
 128
 129
 130                 <varlistentry>
 131                 <term>-R &lt;name resolve order&gt;</term>
 132                 <listitem><para>This option is used by the programs in the Samba
 133                 suite to determine what naming services and in what order to resolve
 134                 host names to IP addresses. The option takes a space separated
 135                 string of different name resolution options.</para>
 136
 137                 <para>The options are :"lmhosts", "host", "wins" and "bcast". They
 138                 cause names to be resolved as follows :</para>
 139
 140                 <itemizedlist>
 141                         <listitem><para><constant>lmhosts</constant> : Lookup an IP
 142                         address in the Samba lmhosts file. If the line in lmhosts has
 143                         no name type attached to the NetBIOS name (see the <ulink
 144                         url="lmhosts.5.html">lmhosts(5)</ulink> for details) then
 145                         any name type matches for lookup.</para></listitem>
 146
 147                         <listitem><para><constant>host</constant> : Do a standard host
 148                         name to IP address resolution, using the system <filename>/etc/hosts
 149                         </filename>, NIS, or DNS lookups. This method of name resolution
 150                         is operating system depended for instance on IRIX or Solaris this
 151                         may be controlled by the <filename>/etc/nsswitch.conf</filename>
 152                         file).  Note that this method is only used if the NetBIOS name
 153                         type being queried is the 0x20 (server) name type, otherwise
 154                         it is ignored.</para></listitem>
 155
 156                         <listitem><para><constant>wins</constant> : Query a name with
 157                         the IP address listed in the <parameter>wins server</parameter>
 158                         parameter.  If no WINS server has
 159                         been specified this method will be ignored.</para></listitem>
 160
 161                         <listitem><para><constant>bcast</constant> : Do a broadcast on
 162                         each of the known local interfaces listed in the
 163                         <parameter>interfaces</parameter>
 164                         parameter. This is the least reliable of the name resolution
 165                         methods as it depends on the target host being on a locally
 166                         connected subnet.</para></listitem>
 167                 </itemizedlist>
 168
 169                 <para>If this parameter is not set then the name resolve order
 170                 defined in the <filename>smb.conf</filename> file parameter
 171                 (name resolve order) will be used. </para>
 172
 173                 <para>The default order is lmhosts, host, wins, bcast and without
 174                 this parameter or any entry in the <parameter>name resolve order
 175                 </parameter> parameter of the smb.conf file the name resolution
 176                 methods will be attempted in this order. </para></listitem>
 177                 </varlistentry>
 178
 179
 180                 <varlistentry>
 181                 <term>-M NetBIOS name</term>
 182                 <listitem><para>This options allows you to send messages, using
 183                 the "WinPopup" protocol, to another computer. Once a connection is
 184                 established you then type your message, pressing ^D (control-D) to
 185                 end. </para>
 186
 187                 <para>If the receiving computer is running WinPopup the user will
 188                 receive the message and probably a beep. If they are not running
 189                 WinPopup the message will be lost, and no error message will
 190                 occur. </para>
 191
 192                 <para>The message is also automatically truncated if the message
 193                 is over 1600 bytes, as this is the limit of the protocol.
 194                 </para>
 195
 196                 <para>One useful trick is to cat the message through
 197                 <command>smbclient</command>. For example: <command>
 198                 cat mymessage.txt | smbclient -M FRED </command> will
 199                 send the message in the file <filename>mymessage.txt</filename>
 200                 to the machine FRED. </para>
 201
 202                 <para>You may also find the <parameter>-U</parameter> and
 203                 <parameter>-I</parameter> options useful, as they allow you to
 204                 control the FROM and TO parts of the message. </para>
 205
 206                 <para>See the message command parameter in the <filename>
 207                 smb.conf(5)</filename> for a description of how to handle incoming
 208                 WinPopup messages in Samba. </para>
 209
 210                 <para><emphasis>Note</emphasis>: Copy WinPopup into the startup group
 211                 on your WfWg PCs if you want them to always be able to receive
 212                 messages. </para></listitem>
 213                 </varlistentry>
 214
 215                 <varlistentry>
 216                 <term>-i scope</term>
 217                 <listitem><para>This specifies a NetBIOS scope that smbclient will
 218                 use to communicate with when generating NetBIOS names. For details
 219                 on the use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt.
 220                 NetBIOS scopes are <emphasis>very</emphasis> rarely used, only set
 221                 this parameter if you are the system administrator in charge of all
 222                 the NetBIOS systems you communicate with. </para></listitem>
 223                 </varlistentry>
 224
 225
 226                 <varlistentry>
 227                 <term>-N</term>
 228                 <listitem><para>If specified, this parameter suppresses the normal
 229                 password prompt from the client to the user. This is useful when
 230                 accessing a service that does not require a password. </para>
 231
 232                 <para>Unless a password is specified on the command line or
 233                 this parameter is specified, the client will request a
 234                 password.</para></listitem>
 235                 </varlistentry>
 236
 237
 238
 239                 <varlistentry>
 240                 <term>-n NetBIOS name</term>
 241                 <listitem><para>By default, the client will use the local
 242                 machine's hostname (in uppercase) as its NetBIOS name. This parameter
 243                 allows you to override the host name and use whatever NetBIOS
 244                 name you wish. </para></listitem>
 245                 </varlistentry>
 246
 247
 248                 <varlistentry>
 249                 <term>-d debuglevel</term>
 250                 <listitem><para>debuglevel is an integer from 0 to 10, or
 251                 the letter 'A'. </para>
 252
 253                 <para>The default value if this parameter is not specified
 254                 is zero. </para>
 255
 256                 <para>The higher this value, the more detail will be logged to
 257                 the log files about the activities of the
 258                 client. At level 0, only critical errors and serious warnings will
 259                 be logged. Level 1 is a reasonable level for day to day running -
 260                 it generates a small amount of information about operations
 261                 carried out. </para>
 262
 263                 <para>Levels above 1 will generate considerable amounts of log
 264                 data, and should only be used when investigating a problem.
 265                 Levels above 3 are designed for use only by developers and
 266                 generate HUGE amounts of log data, most of which is extremely
 267                 cryptic. If debuglevel is set to the letter 'A', then <emphasis>all
 268                 </emphasis>  debug messages will be printed. This setting
 269                 is for developers only (and people who <emphasis>really</emphasis> want
 270                 to know how the code works internally). </para>
 271
 272                 <para>Note that specifying this parameter here will override
 273                 the log level parameter in the <command>smb.conf (5)</command>
 274                 file. </para></listitem>
 275                 </varlistentry>
 276
 277
 278                 <varlistentry>
 279                 <term>-p port</term>
 280                 <listitem><para>This number is the TCP port number that will be used
 281                 when making connections to the server. The standard (well-known)
 282                 TCP port number for an SMB/CIFS server is 139, which is the
 283                 default. </para></listitem>
 284                 </varlistentry>
 285
 286
 287                 <varlistentry>
 288                 <term>-l logfilename</term>
 289                 <listitem><para>If specified, logfilename specifies a base filename
 290                 into which operational data from the running client will be
 291                 logged. </para>
 292
 293                 <para>The default base name is specified at compile time.</para>
 294
 295                 <para>The base name is used to generate actual log file names.
 296                 For example, if the name specified was "log", the debug file
 297                 would be <filename>log.client</filename>.</para>
 298
 299                 <para>The log file generated is never removed by the client.
 300                 </para></listitem>
 301                 </varlistentry>
 302
 303
 304
 305                 <varlistentry>
 306                 <term>-h</term><listitem>
 307                 <para>Print the usage message for the client. </para></listitem>
 308                 </varlistentry>
 309
 310
 311
 312                 <varlistentry>
 313                 <term>-I IP-address</term>
 314                 <listitem><para>IP address is the address of the server to connect to.
 315                 It should be specified in standard "a.b.c.d" notation. </para>
 316
 317                 <para>Normally the client would attempt to locate a named
 318                 SMB/CIFS server by looking it up via the NetBIOS name resolution
 319                 mechanism described above in the <parameter>name resolve order</parameter>
 320                 parameter above. Using this parameter will force the client
 321                 to assume that the server is on the machine with the specified IP
 322                 address and the NetBIOS name component of the resource being
 323                 connected to will be ignored. </para>
 324
 325                 <para>There is no default for this parameter. If not supplied,
 326                 it will be determined automatically by the client as described
 327                 above. </para></listitem>
 328                 </varlistentry>
 329
 330
 331
 332                 <varlistentry>
 333                 <term>-E</term>
 334                 <listitem><para>This parameter causes the client to write messages
 335                 to the standard error stream (stderr) rather than to the standard
 336                 output stream. </para>
 337
 338                 <para>By default, the client writes messages to standard output
 339                 - typically the user's tty. </para></listitem>
 340                 </varlistentry>
 341
 342
 343                 <varlistentry>
 344                 <term>-U username[%pass]</term>
 345                 <listitem><para>Sets the SMB username or username and password.
 346                 If %pass is not specified, The user will be prompted. The client
 347                 will first check the USER environment variable, then the
 348                 <parameter>$LOGNAME</parameter> variable and if either exist, the
 349                 string is uppercased. Anything in these variables following a '%'
 350                 sign will be treated as the password. If these environmental
 351                 variables are not found, the username <constant>GUEST</constant>
 352                 is used. </para>
 353
 354                 <para>If the password is not included in these environment
 355                 variables (using the %pass syntax), rpcclient will look for
 356                 a <parameter>$PASSWD</parameter> environment variable from which
 357                 to read the password. </para>
 358
 359                 <para>A third option is to use a credentials file which
 360                 contains the plaintext of the username and password.  This
 361                 option is mainly provided for scripts where the admin doesn't
 362                 desire to pass the credentials on the command line or via environment
 363                 variables. If this method is used, make certain that the permissions
 364                 on the file restrict access from unwanted users.  See the
 365                 <parameter>-A</parameter> for more details. </para>
 366
 367                 <para>Be cautious about including passwords in scripts or in
 368                 the <parameter>$PASSWD</parameter> environment variable. Also, on
 369                 many systems the command line of a running process may be seen
 370                 via the <command>ps</command> command to be safe always allow
 371                 <command>rpcclient</command> to prompt for a password and type
 372                 it in directly. </para></listitem>
 373                 </varlistentry>
 374
 375
 376                 <varlistentry>
 377                 <term>-A filename</term><listitem><para>This option allows
 378                 you to specify a file from which to read the username and
 379                 password used in the connection.  The format of the file is
 380                 </para>
 381
 382                 <para><programlisting>
 383 username = &lt;value&gt;
 384 password = &lt;value&gt;
 385                 </programlisting></para>
 386
 387
 388                 <para>Make certain that the permissions on the file restrict
 389                 access from unwanted users. </para></listitem>
 390                 </varlistentry>
 391
 392
 393
 394                 <varlistentry>
 395                 <term>-L</term>
 396                 <listitem><para>This option allows you to look at what services
 397                 are available on a server. You use it as <command>smbclient -L
 398                 host</command> and a list should appear.  The <parameter>-I
 399                 </parameter> option may be useful if your NetBIOS names don't
 400                 match your tcp/ip dns host names or if you are trying to reach a
 401                 host on another network. </para></listitem>
 402                 </varlistentry>
 403
 404
 405                 <varlistentry>
 406                 <term>-t terminal code</term>
 407                 <listitem><para>This option tells smbclient how to interpret
 408                 filenames coming from the remote server. Usually Asian language
 409                 multibyte UNIX implementations use different character sets than
 410                 SMB/CIFS servers (<emphasis>EUC</emphasis> instead of <emphasis>
 411                 SJIS</emphasis> for example). Setting this parameter will let
 412                 <command>smbclient</command> convert between the UNIX filenames and
 413                 the SMB filenames correctly. This option has not been seriously tested
 414                 and may have some problems. </para>
 415
 416                 <para>The terminal codes include CWsjis, CWeuc, CWjis7, CWjis8,
 417                 CWjunet, CWhex, CWcap. This is not a complete list, check the Samba
 418                 source code for the complete list. </para></listitem>
 419                 </varlistentry>
 420
 421
 422                 <varlistentry>
 423                 <term>-b buffersize</term>
 424                 <listitem><para>This option changes the transmit/send buffer
 425                 size when getting or putting a file from/to the server. The default
 426                 is 65520 bytes. Setting this value smaller (to 1200 bytes) has been
 427                 observed to speed up file transfers to and from a Win9x server.
 428                 </para></listitem>
 429                 </varlistentry>
 430
 431
 432
 433                 <varlistentry>
 434                 <term>-W WORKGROUP</term>
 435                 <listitem><para>Override the default workgroup specified in the
 436                 workgroup parameter of the <filename>smb.conf</filename> file
 437                 for this connection. This may be needed to connect to some
 438                 servers. </para></listitem>
 439                 </varlistentry>
 440
 441
 442                 <varlistentry>
 443                 <term>-T tar options</term>
 444                 <listitem><para>smbclient may be used to create <command>tar(1)
 445                 </command> compatible backups of all the files on an SMB/CIFS
 446                 share. The secondary tar flags that can be given to this option
 447                 are : </para>
 448
 449                 <itemizedlist>
 450                         <listitem><para><parameter>c</parameter> - Create a tar file on UNIX.
 451                         Must be followed by the name of a tar file, tape device
 452                         or "-" for standard output. If using standard output you must
 453                         turn the log level to its lowest value -d0 to avoid corrupting
 454                         your tar file. This flag is mutually exclusive with the
 455                         <parameter>x</parameter> flag. </para></listitem>
 456
 457                         <listitem><para><parameter>x</parameter> - Extract (restore) a local
 458                         tar file back to a share. Unless the -D option is given, the tar
 459                         files will be restored from the top level of the share. Must be
 460                         followed by the name of the tar file, device or "-" for standard
 461                         input. Mutually exclusive with the <parameter>c</parameter> flag.
 462                         Restored files have their creation times (mtime) set to the
 463                         date saved in the tar file. Directories currently do not get
 464                         their creation dates restored properly. </para></listitem>
 465
 466                         <listitem><para><parameter>I</parameter> - Include files and directories.
 467                         Is the default behavior when filenames are specified above. Causes
 468                         tar files to be included in an extract or create (and therefore
 469                         everything else to be excluded). See example below.  Filename globbing
 470                         works  in one of two ways.  See r below. </para></listitem>
 471
 472                         <listitem><para><parameter>X</parameter> - Exclude files and directories.
 473                         Causes tar files to be excluded from an extract or create. See
 474                         example below.  Filename globbing works in one of two ways now.
 475                         See <parameter>r</parameter> below. </para></listitem>
 476
 477                         <listitem><para><parameter>b</parameter> - Blocksize. Must be followed
 478                         by a valid (greater than zero) blocksize.  Causes tar file to be
 479                         written out in blocksize*TBLOCK (usually 512 byte) blocks.
 480                         </para></listitem>
 481
 482                         <listitem><para><parameter>g</parameter> - Incremental. Only back up
 483                         files that have the archive bit set. Useful only with the
 484                         <parameter>c</parameter> flag. </para></listitem>
 485
 486                         <listitem><para><parameter>q</parameter> - Quiet. Keeps tar from printing
 487                         diagnostics as it works.  This is the same as tarmode quiet.
 488                         </para></listitem>
 489
 490                         <listitem><para><parameter>r</parameter> - Regular expression include
 491                         or exclude.  Uses regular  regular expression matching for
 492                         excluding or excluding files if  compiled with HAVE_REGEX_H.
 493                         However this mode can be very slow. If  not compiled with
 494                         HAVE_REGEX_H, does a limited wildcard match on '*' and  '?'.
 495                         </para></listitem>
 496
 497                         <listitem><para><parameter>N</parameter> - Newer than. Must be followed
 498                         by the name of a file whose date is compared against files found
 499                         on the share during a create. Only files newer than the file
 500                         specified are backed up to the tar file. Useful only with the
 501                         <parameter>c</parameter> flag. </para></listitem>
 502
 503                         <listitem><para><parameter>a</parameter> - Set archive bit. Causes the
 504                         archive bit to be reset when a file is backed up. Useful with the
 505                         <parameter>g</parameter> and <parameter>c</parameter> flags.
 506                         </para></listitem>
 507                 </itemizedlist>
 508
 509                 <para><emphasis>Tar Long File Names</emphasis></para>
 510
 511                 <para><command>smbclient</command>'s tar option now supports long
 512                 file names both on backup and restore. However, the full path
 513                 name of the file must be less than 1024 bytes.  Also, when
 514                 a tar archive is created, smbclient's tar option places all
 515                 files in the archive with relative names, not absolute names.
 516                 </para>
 517
 518                 <para><emphasis>Tar Filenames</emphasis></para>
 519
 520                 <para>All file names can be given as DOS path names (with '\'
 521                 as the component separator) or as UNIX path names (with '/' as
 522                 the component separator). </para>
 523
 524                 <para><emphasis>Examples</emphasis></para>
 525
 526                 <para>Restore from tar file backup.tar into myshare on mypc
 527                 (no password on share). </para>
 528
 529                 <para><command>smbclient //mypc/myshare "" -N -Tx backup.tar
 530                 </command></para>
 531
 532                 <para>Restore everything except <filename>users/docs</filename>
 533                 </para>
 534
 535                 <para><command>smbclient //mypc/myshare "" -N -TXx backup.tar
 536                 users/docs</command></para>
 537
 538                 <para>Create a tar file of the files beneath <filename>
 539                 users/docs</filename>. </para>
 540
 541                 <para><command>smbclient //mypc/myshare "" -N -Tc
 542                 backup.tar users/docs </command></para>
 543
 544                 <para>Create the same tar file as above, but now use
 545                 a DOS path name. </para>
 546
 547                 <para><command>smbclient //mypc/myshare "" -N -tc backup.tar
 548                 users\edocs </command></para>
 549
 550                 <para>Create a tar file of all the files and directories in
 551                 the share. </para>
 552
 553                 <para><command>smbclient //mypc/myshare "" -N -Tc backup.tar *
 554                 </command></para>
 555                 </listitem>
 556                 </varlistentry>
 557
 558
 559                 <varlistentry>
 560                 <term>-D initial directory</term>
 561                 <listitem><para>Change to initial directory before starting. Probably
 562                 only of any use with the tar -T option. </para></listitem>
 563                 </varlistentry>
 564
 565
 566
 567                 <varlistentry>
 568                 <term>-c command string</term>
 569                 <listitem><para>command string is a semicolon separated list of
 570                 commands to be executed instead of prompting from stdin. <parameter>
 571                 -N</parameter> is implied by <parameter>-c</parameter>.</para>
 572
 573                 <para>This is particularly useful in scripts and for printing stdin
 574                 to the server, e.g. <command>-c 'print -'</command>. </para></listitem>
 575                 </varlistentry>
 576         </variablelist>
 577 </refsect1>
 578
 579
 580 <refsect1>
 581         <title>OPERATIONS</title>
 582
 583         <para>Once the client is running, the user is presented with
 584         a prompt : </para>
 585
 586         <para><prompt>smb:\&gt; </prompt></para>
 587
 588         <para>The backslash ("\") indicates the current working directory
 589         on the server, and will change if the current working directory
 590         is changed. </para>
 591
 592         <para>The prompt indicates that the client is ready and waiting to
 593         carry out a user command. Each command is a single word, optionally
 594         followed by parameters specific to that command. Command and parameters
 595         are space-delimited unless these notes specifically
 596         state otherwise. All commands are case-insensitive.  Parameters to
 597         commands may or may not be case sensitive, depending on the command.
 598         </para>
 599
 600         <para>You can specify file names which have spaces in them by quoting
 601         the name with double quotes, for example "a long file name". </para>
 602
 603         <para>Parameters shown in square brackets (e.g., "[parameter]") are
 604         optional.  If not given, the command will use suitable defaults. Parameters
 605         shown in angle brackets (e.g., "&lt;parameter&gt;") are required.
 606         </para>
 607
 608
 609         <para>Note that all commands operating on the server are actually
 610         performed by issuing a request to the server. Thus the behavior may
 611         vary from server to server, depending on how the server was implemented.
 612         </para>
 613
 614         <para>The commands available are given here in alphabetical order. </para>
 615
 616         <variablelist>
 617                 <varlistentry>
 618                 <term>? [command]</term>
 619                 <listitem><para>If "command" is specified, the ? command will display
 620                 a brief informative message about the specified command.  If no
 621                 command is specified, a list of available commands will
 622                 be displayed. </para></listitem>
 623                 </varlistentry>
 624
 625
 626                 <varlistentry>
 627                 <term>! [shell command]</term>
 628                 <listitem><para>If "shell command" is specified, the !
 629                 command will execute a shell locally and run the specified shell
 630                 command. If no command is specified, a local shell will be run.
 631                 </para></listitem>
 632                 </varlistentry>
 633
 634
 635
 636                 <varlistentry>
 637                 <term>cd [directory name]</term>
 638                 <listitem><para>If "directory name" is specified, the current
 639                 working directory on the server will be changed to the directory
 640                 specified. This operation will fail if for any reason the specified
 641                 directory is inaccessible. </para>
 642
 643                 <para>If no directory name is specified, the current working
 644                 directory on the server will be reported. </para></listitem>
 645                 </varlistentry>
 646
 647
 648                 <varlistentry>
 649                 <term>del &lt;mask&gt;</term>
 650                 <listitem><para>The client will request that the server attempt
 651                 to delete all files matching "mask" from the current working
 652                 directory on the server. </para></listitem>
 653                 </varlistentry>
 654
 655
 656                 <varlistentry>
 657                 <term>dir &lt;mask&gt;</term>
 658                 <listitem><para>A list of the files matching "mask" in the current
 659                 working directory on the server will be retrieved from the server
 660                 and displayed. </para></listitem>
 661                 </varlistentry>
 662
 663
 664                 <varlistentry>
 665                 <term>exit</term>
 666                 <listitem><para>Terminate the connection with the server and exit
 667                 from the program. </para></listitem>
 668                 </varlistentry>
 669
 670
 671                 <varlistentry>
 672                 <term>get &lt;remote file name&gt; [local file name]</term>
 673                 <listitem><para>Copy the file called "remote file name" from
 674                 the server to the machine running the client. If specified, name
 675                 the local copy "local file name".  Note that all transfers in
 676                 <command>smbclient</command> are binary. See also the
 677                 lowercase command. </para></listitem>
 678                 </varlistentry>
 679
 680
 681
 682                 <varlistentry>
 683                 <term>help [command]</term>
 684                 <listitem><para>See the ? command above. </para></listitem>
 685                 </varlistentry>
 686
 687
 688                 <varlistentry>
 689                 <term>lcd [directory name]</term>
 690                 <listitem><para>If "directory name" is specified, the current
 691                 working directory on the local machine will be changed to
 692                 the directory specified. This operation will fail if for any
 693                 reason the specified directory is inaccessible. </para>
 694
 695                 <para>If no directory name is specified, the name of the
 696                 current working directory on the local machine will be reported.
 697                 </para></listitem>
 698                 </varlistentry>
 699
 700
 701                 <varlistentry>
 702                 <term>lowercase</term>
 703                 <listitem><para>Toggle lowercasing of filenames for the get and
 704                 mget commands. </para>
 705
 706                 <para>When lowercasing is toggled ON, local filenames are converted
 707                 to lowercase when using the get and mget commands. This is
 708                 often useful when copying (say) MSDOS files from a server, because
 709                 lowercase filenames are the norm on UNIX systems. </para></listitem>
 710                 </varlistentry>
 711
 712
 713
 714                 <varlistentry>
 715                 <term>ls &lt;mask&gt;</term>
 716                 <listitem><para>See the dir command above. </para></listitem>
 717                 </varlistentry>
 718
 719
 720                 <varlistentry>
 721                 <term>mask &lt;mask&gt;</term>
 722                 <listitem><para>This command allows the user to set up a mask
 723                 which will be used during recursive operation of the mget and
 724                 mput commands. </para>
 725
 726                 <para>The masks specified to the mget and mput commands act as
 727                 filters for directories rather than files when recursion is
 728                 toggled ON. </para>
 729
 730                 <para>The mask specified with the mask command is necessary
 731                 to filter files within those directories. For example, if the
 732                 mask specified in an mget command is "source*" and the mask
 733                 specified with the mask command is "*.c" and recursion is
 734                 toggled ON, the mget command will retrieve all files matching
 735                 "*.c" in all directories below and including all directories
 736                 matching "source*" in the current working directory. </para>
 737
 738                 <para>Note that the value for mask defaults to blank (equivalent
 739                 to "*") and remains so until the mask command is used to change it.
 740                 It retains the most recently specified value indefinitely. To
 741                 avoid unexpected results it would be wise to change the value of
 742                 mask back to "*" after using the mget or mput commands. </para></listitem>
 743                 </varlistentry>
 744
 745
 746                 <varlistentry>
 747                 <term>md &lt;directory name&gt;</term>
 748                 <listitem><para>See the mkdir command. </para></listitem>
 749                 </varlistentry>
 750
 751
 752                 <varlistentry>
 753                 <term>mget &lt;mask&gt;</term>
 754                 <listitem><para>Copy all files matching mask from the server to
 755                 the machine running the client. </para>
 756
 757                 <para>Note that mask is interpreted differently during recursive
 758                 operation and non-recursive operation - refer to the recurse and
 759                 mask commands for more information. Note that all transfers in
 760                 smbclient are binary. See also the lowercase command. </para></listitem>
 761                 </varlistentry>
 762
 763
 764                 <varlistentry>
 765                 <term>mkdir &lt;directory name&gt;</term>
 766                 <listitem><para>Create a new directory on the server (user access
 767                 privileges permitting) with the specified name. </para></listitem>
 768                 </varlistentry>
 769
 770
 771                 <varlistentry>
 772                 <term>mput &lt;mask&gt;</term>
 773                 <listitem><para>Copy all files matching mask in the current working
 774                 directory on the local machine to the current working directory on
 775                 the server. </para>
 776
 777                 <para>Note that mask is interpreted differently during recursive
 778                 operation and non-recursive operation - refer to the recurse and mask
 779                 commands for more information. Note that all transfers in smbclient
 780                 are binary. </para></listitem>
 781                 </varlistentry>
 782
 783
 784                 <varlistentry>
 785                 <term>print &lt;file name&gt;</term>
 786                 <listitem><para>Print the specified file from the local machine
 787                 through a printable service on the server. </para>
 788
 789                 <para>See also the printmode command.</para></listitem>
 790                 </varlistentry>
 791
 792
 793
 794                 <varlistentry>
 795                 <term>printmode &lt;graphics or text&gt;</term>
 796                 <listitem><para>Set the print mode to suit either binary data
 797                 (such as graphical information) or text. Subsequent print
 798                 commands will use the currently set print mode. </para></listitem>
 799                 </varlistentry>
 800
 801
 802                 <varlistentry>
 803                 <term>prompt</term>
 804                 <listitem><para>Toggle prompting for filenames during operation
 805                 of the mget and mput commands. </para>
 806
 807                 <para>When toggled ON, the user will be prompted to confirm
 808                 the transfer of each file during these commands. When toggled
 809                 OFF, all specified files will be transferred without prompting.
 810                 </para></listitem>
 811                 </varlistentry>
 812
 813
 814                 <varlistentry>
 815                 <term>put &lt;local file name&gt; [remote file name]</term>
 816                 <listitem><para>Copy the file called "local file name" from the
 817                 machine running the client to the server. If specified,
 818                 name the remote copy "remote file name". Note that all transfers
 819                 in smbclient are binary. See also the lowercase command.
 820                 </para></listitem>
 821                 </varlistentry>
 822
 823
 824
 825                 <varlistentry>
 826                 <term>queue</term>
 827                 <listitem><para>Displays the print queue, showing the job id,
 828                 name, size and current status. </para></listitem>
 829                 </varlistentry>
 830
 831
 832                 <varlistentry>
 833                 <term>quit</term>
 834                 <listitem><para>See the exit command. </para></listitem>
 835                 </varlistentry>
 836
 837
 838                 <varlistentry>
 839                 <term>rd &lt;directory name&gt;</term>
 840                 <listitem><para>See the rmdir command. </para></listitem>
 841                 </varlistentry>
 842
 843
 844                 <varlistentry>
 845                 <term>recurse</term>
 846                 <listitem><para>Toggle directory recursion for the commands mget
 847                 and mput. </para>
 848
 849                 <para>When toggled ON, these commands will process all directories
 850                 in the source directory (i.e., the directory they are copying
 851                 from ) and will recurse into any that match the mask specified
 852                 to the command. Only files that match the mask specified using
 853                 the mask command will be retrieved. See also the mask command.
 854                 </para>
 855
 856                 <para>When recursion is toggled OFF, only files from the current
 857                 working directory on the source machine that match the mask specified
 858                 to the mget or mput commands will be copied, and any mask specified
 859                 using the mask command will be ignored. </para></listitem>
 860                 </varlistentry>
 861
 862
 863
 864                 <varlistentry>
 865                 <term>rm &lt;mask&gt;</term>
 866                 <listitem><para>Remove all files matching mask from the current
 867                 working directory on the server. </para></listitem>
 868                 </varlistentry>
 869
 870
 871                 <varlistentry>
 872                 <term>rmdir &lt;directory name&gt;</term>
 873                 <listitem><para>Remove the specified directory (user access
 874                 privileges permitting) from the server. </para></listitem>
 875                 </varlistentry>
 876
 877
 878                 <varlistentry>
 879                 <term>tar &lt;c|x&gt;[IXbgNa]</term>
 880                 <listitem><para>Performs a tar operation - see the <parameter>-T
 881                 </parameter> command line option above. Behavior may be affected
 882                 by the tarmode command (see below). Using g (incremental) and N
 883                 (newer) will affect tarmode settings. Note that using the "-" option
 884                 with tar x may not work - use the command line option instead.
 885                 </para></listitem>
 886                 </varlistentry>
 887
 888
 889                 <varlistentry>
 890                 <term>blocksize &lt;blocksize&gt;</term>
 891                 <listitem><para>Blocksize. Must be followed by a valid (greater
 892                 than zero) blocksize. Causes tar file to be written out in
 893                 blocksize*TBLOCK (usually 512 byte) blocks. </para></listitem>
 894                 </varlistentry>
 895
 896
 897                 <varlistentry>
 898                 <term>tarmode &lt;full|inc|reset|noreset&gt;</term>
 899                 <listitem><para>Changes tar's behavior with regard to archive
 900                 bits. In full mode, tar will back up everything regardless of the
 901                 archive bit setting (this is the default mode). In incremental mode,
 902                 tar will only back up files with the archive bit set. In reset mode,
 903                 tar will reset the archive bit on all files it backs up (implies
 904                 read/write share). </para></listitem>
 905                 </varlistentry>
 906
 907
 908                 <varlistentry>
 909                 <term>setmode &lt;filename&gt; &lt;perm=[+|\-]rsha&gt;</term>
 910                 <listitem><para>A version of the DOS attrib command to set
 911                 file permissions. For example: </para>
 912
 913                 <para><command>setmode myfile +r </command></para>
 914
 915                 <para>would make myfile read only. </para></listitem>
 916                 </varlistentry>
 917
 918         </variablelist>
 919 </refsect1>
 920
 921 <refsect1>
 922         <title>NOTES</title>
 923
 924         <para>Some servers are fussy about the case of supplied usernames,
 925         passwords, share names (AKA service names) and machine names.
 926         If you fail to connect try giving all parameters in uppercase.
 927         </para>
 928
 929         <para>It is often necessary to use the -n option when connecting
 930         to some types of servers. For example OS/2 LanManager insists
 931         on a valid NetBIOS name being used, so you need to supply a valid
 932         name that would be known to the server.</para>
 933
 934         <para>smbclient supports long file names where the server
 935         supports the LANMAN2 protocol or above. </para>
 936 </refsect1>
 937
 938 <refsect1>
 939         <title>ENVIRONMENT VARIABLES</title>
 940
 941         <para>The variable <parameter>$USER</parameter> may contain the
 942         username of the person  using the client. This information is
 943         used only if the protocol  level is high enough to support
 944         session-level passwords.</para>
 945
 946
 947         <para>The variable <parameter>$PASSWD</parameter> may contain
 948         the password of the person using the client.  This information is
 949         used only if the protocol level is high enough to support
 950         session-level passwords. </para>
 951 </refsect1>
 952
 953
 954 <refsect1>
 955         <title>INSTALLATION</title>
 956
 957         <para>The location of the client program is a matter for
 958         individual system administrators. The following are thus
 959         suggestions only. </para>
 960
 961         <para>It is recommended that the smbclient software be installed
 962         in the <filename>/usr/local/samba/bin/</filename> or <filename>
 963         /usr/samba/bin/</filename> directory, this directory readable
 964         by all, writeable only by root. The client program itself should
 965         be executable by all. The client should <emphasis>NOT</emphasis> be
 966         setuid or setgid! </para>
 967
 968         <para>The client log files should be put in a directory readable
 969         and writeable only by the user. </para>
 970
 971         <para>To test the client, you will need to know the name of a
 972         running SMB/CIFS server. It is possible to run <command>smbd(8)
 973         </command> an ordinary user - running that server as a daemon
 974         on a user-accessible port (typically any port number over 1024)
 975         would provide a suitable test server. </para>
 976 </refsect1>
 977
 978
 979 <refsect1>
 980         <title>DIAGNOSTICS</title>
 981
 982         <para>Most diagnostics issued by the client are logged in a
 983         specified log file. The log file name is specified at compile time,
 984         but may be overridden on the command line. </para>
 985
 986         <para>The number and nature of diagnostics available depends
 987         on the debug level used by the client. If you have problems,
 988         set the debug level to 3 and peruse the log files. </para>
 989 </refsect1>
 990
 991
 992 <refsect1>
 993         <title>VERSION</title>
 994
 995         <para>This man page is correct for version 2.2 of
 996         the Samba suite.</para>
 997 </refsect1>
 998
 999
1000 <refsect1>
1001         <title>AUTHOR</title>
1002
1003         <para>The original Samba software and related utilities
1004         were created by Andrew Tridgell. Samba is now developed
1005         by the Samba Team as an Open Source project similar
1006         to the way the Linux kernel is developed.</para>
1007
1008         <para>The original Samba man pages were written by Karl Auer.
1009         The man page sources were converted to YODL format (another
1010         excellent piece of Open Source software, available at
1011         <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
1012         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
1013         release by Jeremy Allison.  The conversion to DocBook for
1014         Samba 2.2 was done by Gerald Carter</para>
1015 </refsect1>
1016
1017 </refentry>