diff options
Diffstat (limited to 'docs/docbook/manpages/smbclient.1.sgml')
| -rw-r--r-- | docs/docbook/manpages/smbclient.1.sgml | 1651 |
1 files changed, 1017 insertions, 634 deletions
diff --git a/docs/docbook/manpages/smbclient.1.sgml b/docs/docbook/manpages/smbclient.1.sgml index 008a63bf08..7618ad451c 100644 --- a/docs/docbook/manpages/smbclient.1.sgml +++ b/docs/docbook/manpages/smbclient.1.sgml @@ -1,634 +1,1017 @@ -<!-- - - I am looking for help to finish SGML. - ---> -<!-- manual page source format generated by PolyglotMan v3.0.9 - available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> - -<RefEntry ID="smbclient."> -<RefMeta><RefEntryTitle>"smbclient</RefEntryTitle><ManVolNum>"</ManVolNum></RefMeta> - - - -<Para><RefNameDiv><Title>Name</Title>smbclient </RefEntry><RefPurpose> ftp-like client to access SMB/CIFS resources on servers - -<Para></RefSect1> - -<RefSynopsisDiv><Title>Synopsis</Title> - -<Para><B>smbclient</B> -servicename [-s smb.conf] [-O socket options][-R name resolve order] [-M NetBIOS -name] [-i scope] [-N] [-n NetBIOS name] [-d debuglevel] [-P] [-p port] [-l log -basename] [-h] [-I dest IP] [-E] [-U username] [-L NetBIOS name] [-t terminal -code] [-m max protocol] [-b buffersize] [-W workgroup] [-T<c|x>IXFqgbNan] [-D directory] -[-c command string] - -<Para></RefSect1> - -<RefSect1><Title>Description</Title> - -<Para>This program is part of the <B>Samba</B> suite. - -<Para><B>smbclient</B> -is a client that can 'talk' to an SMB/CIFS server. It offers an interface -similar to that of the ftp program (see <B><Command>ftp (1)</B></Command>). Operations include things -like getting files from the server to the local machine, putting files -from the local machine to the server, retrieving directory information -from the server and so on. - -<Para></RefSect1> - -<RefSect1><Title>Options</Title> - -<Para><ItemizedList MARK=Bullet> -<Term><B>servicename</B></Term><ListItem><Para>servicename is the name of -the service you want to use on the server. A service name takes the form -CW//server/service where <I>server</I> is the NetBIOS name of the SMB/CIFS server -offering the desired service and <I>service</I> is the name of the service offered. -Thus to connect to the service <I>printer</I> on the SMB/CIFS server <I>smbserver</I>, -you would use the servicename </Para></ListItem> -<Term>CW//smbserver/printer </Term><ListItem><Para></Para></ListItem> -<Term>Note that the server -name required is NOT necessarily the IP (DNS) </Term><ListItem><Para>host name of the server ! -The name required is a NetBIOS server name, which may or may not be the -same as the IP hostname of the machine running the server. </Para></ListItem> -<Term>The server name -is looked up according to either the </Term><ListItem><Para><B>-R</B> parameter to <B>smbclient</B> or using -the <B>name resolve order</B> parameter in the smb.conf file, allowing an administrator -to change the order and methods by which server names are looked up. </Para></ListItem> -<Term><B>password</B></Term><ListItem><Para>password -is the password required to access the specified service on the specified -server. If this parameter is supplied, the <B>-N</B> option (suppress password prompt) -is assumed. </Para></ListItem> -<Term>There is no default password. If no password is supplied on the -</Term><ListItem><Para>command line (either by using this parameter or adding a password to the -<B>-U</B> option (see below)) and the <B>-N</B> option is not specified, the client will -prompt for a password, even if the desired service does not require one. -(If no password is required, simply press ENTER to provide a null password.) -</Para></ListItem> -<Term>Note: Some servers (including OS/2 and Windows for Workgroups) insist </Term><ListItem><Para>on -an uppercase password. Lowercase or mixed case passwords may be rejected -by these servers. </Para></ListItem> -<Term>Be cautious about including passwords in scripts. </Term><ListItem><Para></Para></ListItem> -<Term><B>-s smb.conf</B></Term><ListItem><Para>This -parameter specifies the pathname to the Samba configuration file, smb.conf. -This file controls all aspects of the Samba setup on the machine and smbclient -also needs to read this file. </Para></ListItem> -<Term><B>-O socket options</B></Term><ListItem><Para>TCP socket options to set -on the client socket. See the socket options parameter in the <B><Command>smb.conf (5)</B></Command> -manpage for the list of valid options. </Para></ListItem> -<Term><B>-R name resolve order</B></Term><ListItem><Para>This option allows -the user of smbclient to determine what name resolution services to use -when looking up the NetBIOS name of the host being connected to. </Para></ListItem> -<Term>The options -are :"lmhosts", "host", "wins" and "bcast". They cause </Term><ListItem><Para>names to be resolved -as follows : </Para></ListItem> -<Term>o</Term><ListItem><Para><B>lmhosts</B> : Lookup an IP address in the Samba lmhosts file. -The lmhosts file is stored in the same directory as the <B>smb.conf</B> file. </Para></ListItem> -<Term>o</Term><ListItem><Para><B>host</B> -: Do a standard host name to IP address resolution, using the system /etc/hosts, -NIS, or DNS lookups. This method of name resolution is operating system -depended for instance on IRIX or Solaris this may be controlled by the -<I>/etc/nsswitch.conf</I> file). </Para></ListItem> -<Term>o</Term><ListItem><Para><B>wins</B> : Query a name with the IP address listed -in the <B>wins server</B> parameter in the smb.conf file. If no WINS server has -been specified this method will be ignored. </Para></ListItem> -<Term>o</Term><ListItem><Para><B>bcast</B> : Do a broadcast on each -of the known local interfaces listed in the <B>interfaces</B> parameter in the -smb.conf file. This is the least reliable of the name resolution methods -as it depends on the target host being on a locally connected subnet. </Para></ListItem> -<Term>If -this parameter is not set then the name resolve order defined </Term><ListItem><Para>in the <B>smb.conf</B> -file parameter (<B>name resolve order</B>) will be used. </Para></ListItem> -<Term>The default order is -lmhosts, host, wins, bcast and without this </Term><ListItem><Para>parameter or any entry in the -<B>"name resolve order"</B> parameter of the <B>smb.conf</B> file the name resolution -methods will be attempted in this order. </Para></ListItem> -<Term><B>-M NetBIOS name</B></Term><ListItem><Para>This options allows -you to send messages, using the "WinPopup" protocol, to another computer. -Once a connection is established you then type your message, pressing ^D -(control-D) to end. </Para></ListItem> -<Term>If the receiving computer is running WinPopup the user -will receive </Term><ListItem><Para>the message and probably a beep. If they are not running WinPopup -the message will be lost, and no error message will occur. </Para></ListItem> -<Term>The message is -also automatically truncated if the message is over </Term><ListItem><Para>1600 bytes, as this -is the limit of the protocol. </Para></ListItem> -<Term>One useful trick is to cat the message through -<B>smbclient</B>. </Term><ListItem><Para>For example: </Para></ListItem> -<Term>CWcat mymessage.txt | smbclient -M FRED </Term><ListItem><Para></Para></ListItem> -<Term>will send the -message in the file <I>mymessage.txt</I> to the machine FRED. </Term><ListItem><Para></Para></ListItem> -<Term>You may also find -the <B>-U</B> and <B>-I</B> options useful, as they allow </Term><ListItem><Para>you to control the FROM and TO -parts of the message. </Para></ListItem> -<Term>See the <B>message command</B> </Term><ListItem><Para>parameter in the <B><Command>smb.conf (5)</B></Command> -for a description of how to handle incoming WinPopup messages in Samba. -</Para></ListItem> -<Term>Note: Copy WinPopup into the startup group on your WfWg PCs if you </Term><ListItem><Para>want -them to always be able to receive messages. </Para></ListItem> -<Term><B>-i scope</B></Term><ListItem><Para>This specifies a NetBIOS -scope that smbclient will use to communicate with when generating NetBIOS -names. For details on the use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt. -NetBIOS scopes are <I>very</I> rarely used, only set this parameter if you are -the system administrator in charge of all the NetBIOS systems you communicate -with. </Para></ListItem> -<Term><B>-N</B></Term><ListItem><Para>If specified, this parameter suppresses the normal password prompt -from the client to the user. This is useful when accessing a service that -does not require a password. </Para></ListItem> -<Term>Unless a password is specified on the command -line or this parameter </Term><ListItem><Para>is specified, the client will request a password. -</Para></ListItem> -<Term><B>-n NetBIOS name</B></Term><ListItem><Para>By default, the client will use the local machine's hostname -(in uppercase) as its NetBIOS name. This parameter allows you to override -the host name and use whatever NetBIOS name you wish. </Para></ListItem> -<Term><B>-d debuglevel</B></Term><ListItem><Para>debuglevel -is an integer from 0 to 10, or the letter 'A'. </Para></ListItem> -<Term>The default value if this parameter -is not specified is zero. </Term><ListItem><Para></Para></ListItem> -<Term>The higher this value, the more detail will be -logged to the log files </Term><ListItem><Para>about the activities of the client. At level 0, -only critical errors and serious warnings will be logged. Level 1 is a reasonable -level for day to day running - it generates a small amount of information -about operations carried out. </Para></ListItem> -<Term>Levels above 1 will generate considerable -amounts of log data, and </Term><ListItem><Para>should only be used when investigating a problem. -Levels above 3 are designed for use only by developers and generate HUGE -amounts of log data, most of which is extremely cryptic. If debuglevel is -set to the letter 'A', then <I>all</I> debug messages will be printed. This setting -is for developers only (and people who <I>really</I> want to know how the code -works internally). </Para></ListItem> -<Term>Note that specifying this parameter here will override -the <B>log </B></Term><ListItem><Para>level parameter in the <B><Command>smb.conf (5)</B></Command> file. </Para></ListItem> -<Term><B>-P</B></Term><ListItem><Para>This option is no longer -used. The code in Samba2.0 now lets the server decide the device type, so -no printer specific flag is needed. </Para></ListItem> -<Term><B>-p port</B></Term><ListItem><Para>This number is the TCP port number -that will be used when making connections to the server. The standard (well-known) -TCP port number for an SMB/CIFS server is 139, which is the default. </Para></ListItem> -<Term><B>-l logfilename</B></Term><ListItem><Para>If -specified, logfilename specifies a base filename into which operational -data from the running client will be logged. </Para></ListItem> -<Term>The default base name is specified -at compile time. </Term><ListItem><Para></Para></ListItem> -<Term>The base name is used to generate actual log file names. -For example, </Term><ListItem><Para>if the name specified was "log", the debug file would be CWlog.client. -</Para></ListItem> -<Term>The log file generated is never removed by the client. </Term><ListItem><Para></Para></ListItem> -<Term><B>-h</B></Term><ListItem><Para>Print the usage -message for the client. </Para></ListItem> -<Term><B>-I IP address</B></Term><ListItem><Para>IP address is the address of the server -to connect to. It should be specified in standard "a.b.c.d" notation. </Para></ListItem> -<Term>Normally -the client would attempt to locate a named SMB/CIFS server by </Term><ListItem><Para>looking it -up via the NetBIOS name resolution mechanism described above in the <B>name -resolve order</B> parameter above. Using this parameter will force the client -to assume that the server is on the machine with the specified IP address -and the NetBIOS name component of the resource being connected to will -be ignored. </Para></ListItem> -<Term>There is no default for this parameter. If not supplied, it will -be </Term><ListItem><Para>determined automatically by the client as described above. </Para></ListItem> -<Term><B>-E</B></Term><ListItem><Para>This parameter -causes the client to write messages to the standard error stream (stderr) -rather than to the standard output stream. </Para></ListItem> -<Term>By default, the client writes -messages to standard output - typically </Term><ListItem><Para>the user's tty. </Para></ListItem> -<Term><B>-U username</B></Term><ListItem><Para>This specifies -the user name that will be used by the client to make a connection, assuming -your server is not a downlevel server that is running a protocol level -that uses passwords on shares, not on usernames. </Para></ListItem> -<Term>Some servers are fussy -about the case of this name, and some insist </Term><ListItem><Para>that it must be a valid NetBIOS -name. </Para></ListItem> -<Term>If no username is supplied, it will default to an uppercase version -of </Term><ListItem><Para>the environment variable CWUSER or CWLOGNAME in that order. If no username -is supplied and neither environment variable exists the username "GUEST" -will be used. </Para></ListItem> -<Term>If the CWUSER environment variable contains a '%' character, -</Term><ListItem><Para>everything after that will be treated as a password. This allows you to -set the environment variable to be CWUSER=username%password so that a password -is not passed on the command line (where it may be seen by the ps command). -</Para></ListItem> -<Term>You can specify a domain name as part of the username by using a </Term><ListItem><Para>username -of the form "DOMAIN/user" or "DOMAIN\user". </Para></ListItem> -<Term>If the service you are connecting -to requires a password, it can be </Term><ListItem><Para>supplied using the <B>-U</B> option, by appending -a percent symbol ("%") then the password to username. For example, to attach -to a service as user CW"fred" with password CW"secret", you would specify. - <BR> -</Para></ListItem> -<Term>CW-U fred%secret </Term><ListItem><Para><BR> -</Para></ListItem> -<Term>on the command line. Note that there are no spaces around the percent </Term><ListItem><Para>symbol. -</Para></ListItem> -<Term>If you specify the password as part of username then the <B>-N</B> option </Term><ListItem><Para>(suppress -password prompt) is assumed. </Para></ListItem> -<Term>If you specify the password as a parameter -<I>AND</I> as part of username </Term><ListItem><Para>then the password as part of username will take -precedence. Putting nothing before or nothing after the percent symbol will -cause an empty username or an empty password to be used, respectively. </Para></ListItem> -<Term>The -password may also be specified by setting up an environment </Term><ListItem><Para>variable called -CWPASSWD that contains the users password. Note that this may be very insecure -on some systems but on others allows users to script smbclient commands -without having a password appear in the command line of a process listing. -</Para></ListItem> -<Term>A third option is to use a credentials file which contains </Term><ListItem><Para>the plaintext -of the username and password. This option is mainly provided for scripts -where the admin doesn't desire to pass the credentials on the command line -or via environment variables. If this method is used, make certain that -the permissions on the file restrict access from unwanted users. See the -<B>-A</B> for more details. </Para></ListItem> -<Term>Note: Some servers (including OS/2 and Windows for Workgroups) -insist </Term><ListItem><Para>on an uppercase password. Lowercase or mixed case passwords may be -rejected by these servers. </Para></ListItem> -<Term>Be cautious about including passwords in scripts -or in the </Term><ListItem><Para>CWPASSWD environment variable. Also, on many systems the command -line of a running process may be seen via the CWps command to be safe always -allow smbclient to prompt for a password and type it in directly. </Para></ListItem> -<Term><B>-A <filename></B></Term><ListItem><Para>This -option allows you to specify a file from which to read the username and -password used in the connection. The format of the file is </Para></ListItem> -<Term>CWusername = -<value> </Term><ListItem><Para><BR> -CWpassword = <value <BR> -</Para></ListItem> -<Term>Make certain that the permissions on the file restrict access from </Term><ListItem><Para>unwanted -users. </Para></ListItem> -<Term><B>-L</B></Term><ListItem><Para>This option allows you to look at what services are available on -a server. You use it as CW"smbclient -L host" and a list should appear. The -<B>-I</B> option may be useful if your NetBIOS names don't match your tcp/ip dns -host names or if you are trying to reach a host on another network. </Para></ListItem> -<Term><B>-t terminal -code</B></Term><ListItem><Para>This option tells smbclient how to interpret filenames coming from -the remote server. Usually Asian language multibyte UNIX implementations -use different character sets than SMB/CIFS servers (<I>EUC</I> instead of <I>SJIS</I> -for example). Setting this parameter will let smbclient convert between -the UNIX filenames and the SMB filenames correctly. This option has not -been seriously tested and may have some problems. </Para></ListItem> -<Term>The terminal codes include -CWsjis, CWeuc, CWjis7, CWjis8, </Term><ListItem><Para>CWjunet, CWhex, CWcap. This is not a complete -list, check the Samba source code for the complete list. </Para></ListItem> -<Term><B>-m max protocol -level</B></Term><ListItem><Para>With the new code in Samba2.0, <B>smbclient</B> always attempts to connect -at the maximum protocols level the server supports. This parameter is preserved -for backwards compatibility, but any string following the <B>-m</B> will be ignored. -</Para></ListItem> -<Term><B>-b buffersize</B></Term><ListItem><Para>This option changes the transmit/send buffer size when getting -or putting a file from/to the server. The default is 65520 bytes. Setting -this value smaller (to 1200 bytes) has been observed to speed up file transfers -to and from a Win9x server. </Para></ListItem> -<Term><B>-W WORKGROUP</B></Term><ListItem><Para>Override the default workgroup specified -in the <B>workgroup</B> parameter of the <B>smb.conf</B> file for this connection. This -may be needed to connect to some servers. </Para></ListItem> -<Term><B>-T tar options</B></Term><ListItem><Para>smbclient may be -used to create <B><Command>tar (1)</B></Command> compatible backups of all the files on an SMB/CIFS -share. The secondary tar flags that can be given to this option are : </Para></ListItem> -<Term><B>c</B></Term><ListItem><Para>Create -a tar file on UNIX. Must be followed by the name of a tar file, tape device -or CW"-" for standard output. If using standard output you must turn the -log level to its lowest value CW-d0 to avoid corrupting your tar file. This -flag is mutually exclusive with the <B>x</B> flag. </Para></ListItem> -<Term><B>x</B></Term><ListItem><Para>Extract (restore) a local tar -file back to a share. Unless the <B>-D</B> option is given, the tar files will be -restored from the top level of the share. Must be followed by the name of -the tar file, device or CW"-" for standard input. Mutually exclusive with -the <B>c</B> flag. Restored files have their creation times (mtime) set to the -date saved in the tar file. Directories currently do not get their creation -dates restored properly. </Para></ListItem> -<Term><B>I</B></Term><ListItem><Para>Include files and directories. Is the default behavior -when filenames are specified above. Causes tar files to be included in an -extract or create (and therefore everything else to be excluded). See example -below. Filename globbing works in one of two ways. See <B>r</B> below. </Para></ListItem> -<Term><B>X</B></Term><ListItem><Para>Exclude -files and directories. Causes tar files to be excluded from an extract or -create. See example below. Filename globbing works in one of two ways now. -See <B>r</B> below. </Para></ListItem> -<Term><B>b</B></Term><ListItem><Para>Blocksize. Must be followed by a valid (greater than zero) -blocksize. Causes tar file to be written out in blocksize*TBLOCK (usually -512 byte) blocks. </Para></ListItem> -<Term><B>g</B></Term><ListItem><Para>Incremental. Only back up files that have the archive -bit set. Useful only with the <B>c</B> flag. </Para></ListItem> -<Term><B>q</B></Term><ListItem><Para>Quiet. Keeps tar from printing diagnostics -as it works. This is the same as tarmode quiet. </Para></ListItem> -<Term><B>r</B></Term><ListItem><Para>Regular expression include -or exclude. Uses regular regular expression matching for excluding or -excluding files if compiled with HAVE_REGEX_H. However this mode can be -very slow. If not compiled with HAVE_REGEX_H, does a limited wildcard match -on * and ?. </Para></ListItem> -<Term><B>N</B></Term><ListItem><Para>Newer than. Must be followed by the name of a file whose date -is compared against files found on the share during a create. Only files -newer than the file specified are backed up to the tar file. Useful only -with the <B>c</B> flag. </Para></ListItem> -<Term><B>a</B></Term><ListItem><Para>Set archive bit. Causes the archive bit to be reset when -a file is backed up. Useful with the <B>g</B> and <B>c</B> flags. </Para></ListItem> -<Term><I>Tar Long File Names</I> </Term><ListItem><Para></Para></ListItem> -<Term>smbclient's -tar option now supports long file names both on backup and </Term><ListItem><Para>restore. However, -the full path name of the file must be less than 1024 bytes. Also, when -a tar archive is created, smbclient's tar option places all files in the -archive with relative names, not absolute names. </Para></ListItem> -<Term><I>Tar Filenames</I> </Term><ListItem><Para></Para></ListItem> -<Term>All file -names can be given as DOS path names (with CW\ as the </Term><ListItem><Para>component separator) -or as UNIX path names (with CW/ as the component separator). </Para></ListItem> -<Term><I>Examples</I> </Term><ListItem><Para></Para></ListItem> -<Term>o</Term><ListItem><Para>Restore -from tar file backup.tar into myshare on mypc (no password on share). </Para></ListItem> -<Term>CWsmbclient -//mypc/myshare "" -N -Tx backup.tar </Term><ListItem><Para></Para></ListItem> -<Term>o</Term><ListItem><Para>Restore everything except users/docs -</Para></ListItem> -<Term>CWsmbclient //mypc/myshare "" -N -TXx backup.tar users/docs </Term><ListItem><Para></Para></ListItem> -<Term>o</Term><ListItem><Para>Create a tar -file of the files beneath users/docs. </Para></ListItem> -<Term>CWsmbclient //mypc/myshare "" -N -Tc -backup.tar users/docs </Term><ListItem><Para></Para></ListItem> -<Term>o</Term><ListItem><Para>Create the same tar file as above, but now use a -DOS path name. </Para></ListItem> -<Term>CWsmbclient //mypc/myshare "" -N -tc backup.tar users\edocs </Term><ListItem><Para></Para></ListItem> -<Term>o</Term><ListItem><Para>Create -a tar file of all the files and directories in the share. </Para></ListItem> -<Term>CWsmbclient //mypc/myshare -"" -N -Tc backup.tar * </Term><ListItem><Para></Para></ListItem> -<Term><B>-D initial directory</B></Term><ListItem><Para>Change to initial directory before -starting. Probably only of any use with the tar <B>-T</B> option. </Para></ListItem> -<Term><B>-c command string</B></Term><ListItem><Para>command -string is a semicolon separated list of commands to be executed instead -of prompting from stdin. <B>-N</B> is implied by <B>-c</B>. </Para></ListItem> -<Term>This is particularly useful in -scripts and for printing stdin to the </Term><ListItem><Para>server, e.g. CW-c 'print -'. </Para></ListItem> -</ItemizedList> - - -<Para></RefSect1> - -<RefSect1><Title>Operations</Title> - -<Para>Once -the client is running, the user is presented with a prompt : - -<Para>CWsmb:\> - -<Para>The -backslash ("\") <ItemizedList MARK=Bullet> -<Term>indicates the current working directory on the </Term><ListItem><Para>server, and -will change if the current working directory is changed. </Para></ListItem> -</ItemizedList> - - -<Para>The prompt indicates -that the client is ready and waiting to carry out a user command. Each command -is a single word, optionally followed by parameters specific to that command. -Command and parameters are space-delimited unless these notes specifically -state otherwise. All commands are case-insensitive. Parameters to commands -may or may not be case sensitive, depending on the command. - -<Para>You can specify -file names which have spaces in them by quoting the name with double quotes, -for example "a long file name". - -<Para>Parameters shown in square brackets (e.g., -"[parameter]") are optional. If not given, the command will use suitable -defaults. Parameters shown in angle brackets (e.g., "<parameter>") are required. - - -<Para>Note that all commands operating on the server are actually performed by -issuing a request to the server. Thus the behavior may vary from server -to server, depending on how the server was implemented. - -<Para>The commands available -are given here in alphabetical order. - -<Para><ItemizedList MARK=Bullet> -<Term><B>? [command]</B></Term><ListItem><Para>If "command" is specified, -the <B>?</B> command will display a brief informative message about the specified -command. If no command is specified, a list of available commands will -be displayed. </Para></ListItem> -<Term><B>! [shell command]</B></Term><ListItem><Para>If "shell command" is specified, the <B>!</B> command -will execute a shell locally and run the specified shell command. If no -command is specified, a local shell will be run. </Para></ListItem> -<Term><B>cd [directory name]</B></Term><ListItem><Para>If "directory -name" is specified, the current working directory on the server will be -changed to the directory specified. This operation will fail if for any -reason the specified directory is inaccessible. </Para></ListItem> -<Term>If no directory name is -specified, the current working directory on </Term><ListItem><Para>the server will be reported. -</Para></ListItem> -<Term><B>del <mask></B></Term><ListItem><Para>The client will request that the server attempt to delete all files -matching "mask" from the current working directory on the server. </Para></ListItem> -<Term><B>dir <mask></B></Term><ListItem><Para>A -list of the files matching "mask" in the current working directory on the -server will be retrieved from the server and displayed. </Para></ListItem> -<Term><B>exit</B></Term><ListItem><Para>Terminate the -connection with the server and exit from the program. </Para></ListItem> -<Term><B>get <remote file name> -[local file name]</B></Term><ListItem><Para>Copy the file called "remote file name" from the server -to the machine running the client. If specified, name the local copy "local -file name". Note that all transfers in smbclient are binary. See also the -<B>lowercase</B> command. </Para></ListItem> -<Term><B>help [command]</B></Term><ListItem><Para>See the <B>?</B> command above. </Para></ListItem> -<Term><B>lcd [directory -name]</B></Term><ListItem><Para>If "directory name" is specified, the current working directory on -the local machine will be changed to the directory specified. This operation -will fail if for any reason the specified directory is inaccessible. </Para></ListItem> -<Term>If -no directory name is specified, the name of the current working </Term><ListItem><Para>directory -on the local machine will be reported. </Para></ListItem> -<Term><B>lowercase</B></Term><ListItem><Para>Toggle lowercasing of filenames -for the <B>get</B> and <B>mget</B> commands. </Para></ListItem> -<Term>When lowercasing is toggled ON, local filenames -are converted to </Term><ListItem><Para>lowercase when using the <B>get</B> and <B>mget</B> commands. This is -often useful when copying (say) MSDOS files from a server, because lowercase -filenames are the norm on UNIX systems. </Para></ListItem> -<Term><B>ls <mask></B></Term><ListItem><Para>See the <B>dir</B> command above. -</Para></ListItem> -<Term><B>mask <mask></B></Term><ListItem><Para>This command allows the user to set up a mask which will be used -during recursive operation of the <B>mget</B> and <B>mput</B> commands. </Para></ListItem> -<Term>The masks specified -to the <B>mget</B> and </Term><ListItem><Para><B>mput</B> commands act as filters for directories rather than -files when recursion is toggled ON. </Para></ListItem> -<Term>The mask specified with the .B mask command -is necessary to filter </Term><ListItem><Para>files within those directories. For example, if the -mask specified in an <B>mget</B> command is "source*" and the mask specified with -the mask command is "*.c" and recursion is toggled ON, the <B>mget</B> command -will retrieve all files matching "*.c" in all directories below and including -all directories matching "source*" in the current working directory. </Para></ListItem> -<Term>Note -that the value for mask defaults to blank (equivalent to "*") and </Term><ListItem><Para>remains -so until the mask command is used to change it. It retains the most recently -specified value indefinitely. To avoid unexpected results it would be wise -to change the value of .I mask back to "*" after using the <B>mget</B> or <B>mput</B> -commands. </Para></ListItem> -<Term><B>md <directory name></B></Term><ListItem><Para>See the <B>mkdir</B> command. </Para></ListItem> -<Term><B>mget <mask></B></Term><ListItem><Para>Copy all files -matching mask from the server to the machine running the client. </Para></ListItem> -<Term>Note that -mask is interpreted differently during recursive operation </Term><ListItem><Para>and non-recursive -operation - refer to the <B>recurse</B> and <B>mask</B> commands for more information. -Note that all transfers in .B smbclient are binary. See also the <B>lowercase</B> -command. </Para></ListItem> -<Term><B>mkdir <directory name></B></Term><ListItem><Para>Create a new directory on the server (user -access privileges permitting) with the specified name. </Para></ListItem> -<Term><B>mput <mask></B></Term><ListItem><Para>Copy all -files matching mask in the current working directory on the local machine -to the current working directory on the server. </Para></ListItem> -<Term>Note that mask is interpreted -differently during recursive operation </Term><ListItem><Para>and non-recursive operation - refer -to the <B>recurse</B> and <B>mask</B> commands for more information. Note that all transfers -in .B smbclient are binary. </Para></ListItem> -<Term><B>print <file name></B></Term><ListItem><Para>Print the specified file from -the local machine through a printable service on the server. </Para></ListItem> -<Term>See also the -<B>printmode</B> command. </Term><ListItem><Para></Para></ListItem> -<Term><B>printmode <graphics or text></B></Term><ListItem><Para>Set the print mode to suit -either binary data (such as graphical information) or text. Subsequent print -commands will use the currently set print mode. </Para></ListItem> -<Term><B>prompt</B></Term><ListItem><Para>Toggle prompting for -filenames during operation of the <B>mget</B> and <B>mput</B> commands. </Para></ListItem> -<Term>When toggled ON, -the user will be prompted to confirm the transfer of </Term><ListItem><Para>each file during these -commands. When toggled OFF, all specified files will be transferred without -prompting. </Para></ListItem> -<Term><B>put <local file name> [remote file name]</B></Term><ListItem><Para>Copy the file called "local -file name" from the machine running the client to the server. If specified, -name the remote copy "remote file name". Note that all transfers in smbclient -are binary. See also the <B>lowercase</B> command. </Para></ListItem> -<Term><B>queue</B></Term><ListItem><Para>Displays the print queue, -showing the job id, name, size and current status. </Para></ListItem> -<Term><B>quit</B></Term><ListItem><Para>See the <B>exit</B> command. -</Para></ListItem> -<Term><B>rd <directory name></B></Term><ListItem><Para>See the <B>rmdir</B> command. </Para></ListItem> -<Term><B>recurse</B></Term><ListItem><Para>Toggle directory recursion -for the commands <B>mget</B> and <B>mput</B>. </Para></ListItem> -<Term>When toggled ON, these commands will process -all directories in the </Term><ListItem><Para>source directory (i.e., the directory they are copying -.IR from ) and will recurse into any that match the mask specified to the -command. Only files that match the mask specified using the <B>mask</B> command -will be retrieved. See also the <B>mask</B> command. </Para></ListItem> -<Term>When recursion is toggled OFF, -only files from the current working </Term><ListItem><Para>directory on the source machine that -match the mask specified to the <B>mget</B> or <B>mput</B> commands will be copied, and -any mask specified using the <B>mask</B> command will be ignored. </Para></ListItem> -<Term><B>rm <mask></B></Term><ListItem><Para>Remove -all files matching mask from the current working directory on the server. -</Para></ListItem> -<Term><B>rmdir <directory name></B></Term><ListItem><Para>Remove the specified directory (user access privileges -permitting) from the server. </Para></ListItem> -<Term><B>tar <c|x>[IXbgNa]</B></Term><ListItem><Para>Performs a tar operation - see -the <B>-T</B> command line option above. Behavior may be affected by the <B>tarmode</B> -command (see below). Using g (incremental) and N (newer) will affect tarmode -settings. Note that using the "-" option with tar x may not work - use the -command line option instead. </Para></ListItem> -<Term><B>blocksize <blocksize></B></Term><ListItem><Para>Blocksize. Must be followed -by a valid (greater than zero) blocksize. Causes tar file to be written -out in blocksize*TBLOCK (usually 512 byte) blocks. </Para></ListItem> -<Term><B>tarmode <full|inc|reset|noreset></B></Term><ListItem><Para>Changes -tar's behavior with regard to archive bits. In full mode, tar will back up -everything regardless of the archive bit setting (this is the default mode). -In incremental mode, tar will only back up files with the archive bit set. -In reset mode, tar will reset the archive bit on all files it backs up -(implies read/write share). </Para></ListItem> -<Term><B>setmode <filename> <perm=[+|\-]rsha></B></Term><ListItem><Para>A version of the -DOS attrib command to set file permissions. For example: </Para></ListItem> -<Term>CWsetmode myfile -+r </Term><ListItem><Para></Para></ListItem> -<Term>would make myfile read only. </Term><ListItem><Para></Para></ListItem> -</ItemizedList> - - -<Para></RefSect1> - -<RefSect1><Title>Notes</Title> - -<Para>Some servers are fussy about the case -of supplied usernames, passwords, share names (AKA service names) and machine -names. <ItemizedList MARK=Bullet> -<Term>If you </Term><ListItem><Para>fail to connect try giving all parameters in uppercase. </Para></ListItem> -</ItemizedList> - - -<Para>It -is often necessary to use the <B>-n</B> option when connecting to some types of -servers. For example OS/2 LanManager insists on a valid NetBIOS name being -used, so you need to supply a valid name that would be known to the server. - - -<Para>smbclient supports long file names where the server supports the LANMAN2 -protocol or above. - -<Para></RefSect1> - -<RefSect1><Title>Environment Variables</Title> - -<Para>The variable <B>USER</B> may contain the -username of the person using the client. This information is used only -if the protocol level is high enough to support session-level passwords. - - -<Para>The variable <B>PASSWD</B> may contain the password of the person using the client. - This information is used only if the protocol level is high enough to -support session-level passwords. - -<Para></RefSect1> - -<RefSect1><Title>Installation</Title> - -<Para>The location of the client program -is a matter for individual system administrators. The following are thus -suggestions only. - -<Para>It is recommended that the smbclient software be installed -in the /usr/local/samba/bin or /usr/samba/bin directory, this directory -readable by all, writeable only by root. The client program itself should -be executable by all. The client should <I>NOT</I> be setuid or setgid! - -<Para>The client -log files should be put in a directory readable and writeable only by the -user. - -<Para>To test the client, you will need to know the name of a running SMB/CIFS -server. It is possible to run <B><Command>smbd (8)</B></Command> an ordinary user - running that server -as a daemon on a user-accessible port (typically any port number over 1024) -would provide a suitable test server. - -<Para></RefSect1> - -<RefSect1><Title>Diagnostics</Title> - -<Para>Most diagnostics issued -by the client are logged in a specified log file. The log file name is specified -at compile time, but may be overridden on the command line. - -<Para>The number and -nature of diagnostics available depends on the debug level used by the -client. If you have problems, set the debug level to 3 and peruse the log -files. - -<Para></RefSect1> - -<RefSect1><Title>Version</Title> - -<Para>This man page is correct for version 2.0 of the Samba suite. - - -<Para></RefSect1> - -<RefSect1><Title>Author</Title> - -<Para>The original Samba software and related utilities were created by -Andrew Tridgell <I>samba@samba.org</I>. Samba is now developed by the Samba Team -as an Open Source project similar to the way the Linux kernel is developed. - - -<Para>The original Samba man pages were written by Karl Auer. The man page sources -were converted to YODL format (another excellent piece of Open Source software, -available at <B>ftp://ftp.icce.rug.nl/pub/unix/</B>) and updated for the Samba2.0 -release by Jeremy Allison. <I>samba@samba.org</I>. - -<Para>See <B><Command>samba (7)</B></Command> to find out how -to get a full list of contributors and details on how to submit bug reports, -comments etc. </RefSect1> - -</RefEntry> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<refentry id="smbclient"> + +<refmeta> + <refentrytitle>smbclient</refentrytitle> + <manvolnum>1</manvolnum> +</refmeta> + + +<refnamediv> + <refname>smbclient</refname> + <refpurpose>ftp-like client to access SMB/CIFS resources + on servers</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>smbclient</command> + <arg choice="req">servicename</arg> + <arg choice="opt">-b <buffer size></arg> + <arg choice="opt">-d debuglevel</arg> + <arg choice="opt">-D Directory</arg> + <arg choice="opt">-S server</arg> + <arg choice="opt">-U username</arg> + <arg choice="opt">-W workgroup</arg> + <arg choice="opt">-M <netbios name></arg> + <arg choice="opt">-m maxprotocol</arg> + <arg choice="opt">-A authfile</arg> + <arg choice="opt">-N</arg> + <arg choice="opt">-l logfile</arg> + <arg choice="opt">-L <netbios name></arg> + <arg choice="opt">-I destinationIP</arg> + <arg choice="opt">-E <terminal code></arg> + <arg choice="opt">-c <command string></arg> + <arg choice="opt">-i scope</arg> + <arg choice="opt">-O <socket options></arg> + <arg choice="opt">-p port</arg> + <arg choice="opt">-R <name resolve order></arg> + <arg choice="opt">-s <smb config file></arg> + <arg choice="opt">-T<c|x>IXFqgbNan</arg> + <arg choice="opt">password</arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This tool is part of the <ulink url="samba.7.html"> + Samba</ulink> suite.</para> + + <para><command>smbclient</command> is a client that can + 'talk' to an SMB/CIFS server. It offers an interface + similar to that of the ftp program (see <command>ftp(1)</command>). + Operations include things like getting files from the server + to the local machine, putting files from the local machine to + the server, retrieving directory information from the server + and so on. </para> +</refsect1> + + +<refsect1> + <title>OPTIONS</title> + + <variablelist> + <varlistentry> + <term>servicename</term> + <listitem><para>servicename is the name of the service + you want to use on the server. A service name takes the form + <filename>//server/service</filename> where <parameter>server + </parameter> is the NetBIOS name of the SMB/CIFS server + offering the desired service and <parameter>service</parameter> + is the name of the service offered. Thus to connect to + the service "printer" on the SMB/CIFS server "smbserver", + you would use the servicename <filename>//smbserver/printer + </filename></para> + + <para>Note that the server name required is NOT necessarily + the IP (DNS) host name of the server ! The name required is + a NetBIOS server name, which may or may not be the + same as the IP hostname of the machine running the server. + </para> + + <para>The server name is looked up according to either + the <parameter>-R</parameter> parameter to smbclient or + using the name resolve order parameter in the smb.conf file, + allowing an administrator to change the order and methods + by which server names are looked up. </para></listitem> + </varlistentry> + + <varlistentry> + <term>password</term> + <listitem><para>The password required to access the specified + service on the specified server. If this parameter is + supplied, the <parameter>-N</parameter> option (suppress + password prompt) is assumed. </para> + + <para>There is no default password. If no password is supplied + on the command line (either by using this parameter or adding + a password to the <parameter>-U</parameter> option (see + below)) and the <parameter>-N</parameter> option is not + specified, the client will prompt for a password, even if + the desired service does not require one. (If no password is + required, simply press ENTER to provide a null password.) + </para> + + <para>Note: Some servers (including OS/2 and Windows for + Workgroups) insist on an uppercase password. Lowercase + or mixed case passwords may be rejected by these servers. + </para> + + <para>Be cautious about including passwords in scripts. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-s smb.conf</term> + <listitem><para>Specifies the location of the all important + <filename>smb.conf</filename> file. </para></listitem> + </varlistentry> + + <varlistentry> + <term>-O socket options</term> + <listitem><para>TCP socket options to set on the client + socket. See the socket options parameter in the <filename> + smb.conf (5)</filename> manpage for the list of valid + options. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>name resolve order (G)</term> + <listitem><para>This option is used by the programs in the Samba + suite to determine what naming services and in what order to resolve + host names to IP addresses. The option takes a space separated + string of different name resolution options.</para> + + <para>The options are :"lmhosts", "host", "wins" and "bcast". They + cause names to be resolved as follows :</para> + + <itemizedlist> + <listitem><para><constant>lmhosts</constant> : Lookup an IP + address in the Samba lmhosts file. If the line in lmhosts has + no name type attached to the NetBIOS name (see the <ulink + url="lmhosts.5.html">lmhosts(5)</ulink> for details) then + any name type matches for lookup.</para></listitem> + + <listitem><para><constant>host</constant> : Do a standard host + name to IP address resolution, using the system <filename>/etc/hosts + </filename>, NIS, or DNS lookups. This method of name resolution + is operating system depended for instance on IRIX or Solaris this + may be controlled by the <filename>/etc/nsswitch.conf</filename> + file). Note that this method is only used if the NetBIOS name + type being queried is the 0x20 (server) name type, otherwise + it is ignored.</para></listitem> + + <listitem><para><constant>wins</constant> : Query a name with + the IP address listed in the <parameter>wins server</parameter> + parameter. If no WINS server has + been specified this method will be ignored.</para></listitem> + + <listitem><para><constant>bcast</constant> : Do a broadcast on + each of the known local interfaces listed in the + <parameter>interfaces</parameter> + parameter. This is the least reliable of the name resolution + methods as it depends on the target host being on a locally + connected subnet.</para></listitem> + </itemizedlist> + + <para>If this parameter is not set then the name resolve order + defined in the <filename>smb.conf</filename> file parameter + (name resolve order) will be used. </para> + + <para>The default order is lmhosts, host, wins, bcast and without + this parameter or any entry in the <parameter>name resolve order + </parameter> parameter of the smb.conf file the name resolution + methods will be attempted in this order. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-M NetBIOS name</term> + <listitem><para>This options allows you to send messages, using + the "WinPopup" protocol, to another computer. Once a connection is + established you then type your message, pressing ^D (control-D) to + end. </para> + + <para>If the receiving computer is running WinPopup the user will + receive the message and probably a beep. If they are not running + WinPopup the message will be lost, and no error message will + occur. </para> + + <para>The message is also automatically truncated if the message + is over 1600 bytes, as this is the limit of the protocol. + </para> + + <para>One useful trick is to cat the message through + <command>smbclient</command>. For example: <command> + cat mymessage.txt | smbclient -M FRED </command> will + send the message in the file <filename>mymessage.txt</filename> + to the machine FRED. </para> + + <para>You may also find the <parameter>-U</parameter> and + <parameter>-I</parameter> options useful, as they allow you to + control the FROM and TO parts of the message. </para> + + <para>See the message command parameter in the <filename> + smb.conf(5)</filename> for a description of how to handle incoming + WinPopup messages in Samba. </para> + + <para><emphasis>Note</emphasis>: Copy WinPopup into the startup group + on your WfWg PCs if you want them to always be able to receive + messages. </para></listitem> + </varlistentry> + + <varlistentry> + <term>-i scope</term> + <listitem><para>This specifies a NetBIOS scope that smbclient will + use to communicate with when generating NetBIOS names. For details + on the use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt. + NetBIOS scopes are <emphasis>very</emphasis> rarely used, only set + this parameter if you are the system administrator in charge of all + the NetBIOS systems you communicate with. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-N</term> + <listitem><para>If specified, this parameter suppresses the normal + password prompt from the client to the user. This is useful when + accessing a service that does not require a password. </para> + + <para>Unless a password is specified on the command line or + this parameter is specified, the client will request a + password.</para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-n NetBIOS name</term> + <listitem><para>By default, the client will use the local + machine's hostname (in uppercase) as its NetBIOS name. This parameter + allows you to override the host name and use whatever NetBIOS + name you wish. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-d debuglevel</term> + <listitem><para>debuglevel is an integer from 0 to 10, or + the letter 'A'. </para> + + <para>The default value if this parameter is not specified + is zero. </para> + + <para>The higher this value, the more detail will be logged to + the log files about the activities of the + client. At level 0, only critical errors and serious warnings will + be logged. Level 1 is a reasonable level for day to day running - + it generates a small amount of information about operations + carried out. </para> + + <para>Levels above 1 will generate considerable amounts of log + data, and should only be used when investigating a problem. + Levels above 3 are designed for use only by developers and + generate HUGE amounts of log data, most of which is extremely + cryptic. If debuglevel is set to the letter 'A', then <emphasis>all + </emphasis> debug messages will be printed. This setting + is for developers only (and people who <emphasis>really</emphasis> want + to know how the code works internally). </para> + + <para>Note that specifying this parameter here will override + the log level parameter in the <command>smb.conf (5)</command> + file. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-p port</term> + <listitem><para>This number is the TCP port number that will be used + when making connections to the server. The standard (well-known) + TCP port number for an SMB/CIFS server is 139, which is the + default. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-l logfilename</term> + <listitem><para>If specified, logfilename specifies a base filename + into which operational data from the running client will be + logged. </para> + + <para>The default base name is specified at compile time.</para> + + <para>The base name is used to generate actual log file names. + For example, if the name specified was "log", the debug file + would be <filename>log.client</filename>.</para> + + <para>The log file generated is never removed by the client. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-h</term><listitem> + <para>Print the usage message for the client. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-I IP-address</term> + <listitem><para>IP address is the address of the server to connect to. + It should be specified in standard "a.b.c.d" notation. </para> + + <para>Normally the client would attempt to locate a named + SMB/CIFS server by looking it up via the NetBIOS name resolution + mechanism described above in the <parameter>name resolve order</parameter> + parameter above. Using this parameter will force the client + to assume that the server is on the machine with the specified IP + address and the NetBIOS name component of the resource being + connected to will be ignored. </para> + + <para>There is no default for this parameter. If not supplied, + it will be determined automatically by the client as described + above. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-E</term> + <listitem><para>This parameter causes the client to write messages + to the standard error stream (stderr) rather than to the standard + output stream. </para> + + <para>By default, the client writes messages to standard output + - typically the user's tty. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-U username[%pass]</term> + <listitem><para>Sets the SMB username or username and password. + If %pass is not specified, The user will be prompted. The client + will first check the USER environment variable, then the + <parameter>$LOGNAME</parameter> variable and if either exist, the + string is uppercased. Anything in these variables following a '%' + sign will be treated as the password. If these environmental + variables are not found, the username <constant>GUEST</constant> + is used. </para> + + <para>If the password is not included in these environment + variables (using the %pass syntax), rpcclient will look for + a <parameter>$PASSWD</parameter> environment variable from which + to read the password. </para> + + <para>A third option is to use a credentials file which + contains the plaintext of the username and password. This + option is mainly provided for scripts where the admin doesn't + desire to pass the credentials on the command line or via environment + variables. If this method is used, make certain that the permissions + on the file restrict access from unwanted users. See the + <parameter>-A</parameter> for more details. </para> + + <para>Be cautious about including passwords in scripts or in + the <parameter>$PASSWD</parameter> environment variable. Also, on + many systems the command line of a running process may be seen + via the <command>ps</command> command to be safe always allow + <command>rpcclient</command> to prompt for a password and type + it in directly. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-A filename</term><listitem><para>This option allows + you to specify a file from which to read the username and + password used in the connection. The format of the file is + </para> + + <para><programlisting> +username = <value> +password = <value> + </programlisting></para> + + + <para>Make certain that the permissions on the file restrict + access from unwanted users. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-L</term> + <listitem><para>This option allows you to look at what services + are available on a server. You use it as <command>smbclient -L + host</command> and a list should appear. The <parameter>-I + </parameter> option may be useful if your NetBIOS names don't + match your tcp/ip dns host names or if you are trying to reach a + host on another network. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-t terminal code</term> + <listitem><para>This option tells smbclient how to interpret + filenames coming from the remote server. Usually Asian language + multibyte UNIX implementations use different character sets than + SMB/CIFS servers (<emphasis>EUC</emphasis> instead of <emphasis> + SJIS</emphasis> for example). Setting this parameter will let + <command>smbclient</command> convert between the UNIX filenames and + the SMB filenames correctly. This option has not been seriously tested + and may have some problems. </para> + + <para>The terminal codes include CWsjis, CWeuc, CWjis7, CWjis8, + CWjunet, CWhex, CWcap. This is not a complete list, check the Samba + source code for the complete list. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-b buffersize</term> + <listitem><para>This option changes the transmit/send buffer + size when getting or putting a file from/to the server. The default + is 65520 bytes. Setting this value smaller (to 1200 bytes) has been + observed to speed up file transfers to and from a Win9x server. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-W WORKGROUP</term> + <listitem><para>Override the default workgroup specified in the + workgroup parameter of the <filename>smb.conf</filename> file + for this connection. This may be needed to connect to some + servers. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-T tar options</term> + <listitem><para>smbclient may be used to create <command>tar(1) + </command> compatible backups of all the files on an SMB/CIFS + share. The secondary tar flags that can be given to this option + are : </para> + + <itemizedlist> + <listitem><para><parameter>c</parameter> - Create a tar file on UNIX. + Must be followed by the name of a tar file, tape device + or "-" for standard output. If using standard output you must + turn the log level to its lowest value -d0 to avoid corrupting + your tar file. This flag is mutually exclusive with the + <parameter>x</parameter> flag. </para></listitem> + + <listitem><para><parameter>x</parameter> - Extract (restore) a local + tar file back to a share. Unless the -D option is given, the tar + files will be restored from the top level of the share. Must be + followed by the name of the tar file, device or "-" for standard + input. Mutually exclusive with the <parameter>c</parameter> flag. + Restored files have their creation times (mtime) set to the + date saved in the tar file. Directories currently do not get + their creation dates restored properly. </para></listitem> + + <listitem><para><parameter>I</parameter> - Include files and directories. + Is the default behavior when filenames are specified above. Causes + tar files to be included in an extract or create (and therefore + everything else to be excluded). See example below. Filename globbing + works in one of two ways. See r below. </para></listitem> + + <listitem><para><parameter>X</parameter> - Exclude files and directories. + Causes tar files to be excluded from an extract or create. See + example below. Filename globbing works in one of two ways now. + See <parameter>r</parameter> below. </para></listitem> + + <listitem><para><parameter>b</parameter> - Blocksize. Must be followed + by a valid (greater than zero) blocksize. Causes tar file to be + written out in blocksize*TBLOCK (usually 512 byte) blocks. + </para></listitem> + + <listitem><para><parameter>g</parameter> - Incremental. Only back up + files that have the archive bit set. Useful only with the + <parameter>c</parameter> flag. </para></listitem> + + <listitem><para><parameter>q</parameter> - Quiet. Keeps tar from printing + diagnostics as it works. This is the same as tarmode quiet. + </para></listitem> + + <listitem><para><parameter>r</parameter> - Regular expression include + or exclude. Uses regular regular expression matching for + excluding or excluding files if compiled with HAVE_REGEX_H. + However this mode can be very slow. If not compiled with + HAVE_REGEX_H, does a limited wildcard match on '*' and '?'. + </para></listitem> + + <listitem><para><parameter>N</parameter> - Newer than. Must be followed + by the name of a file whose date is compared against files found + on the share during a create. Only files newer than the file + specified are backed up to the tar file. Useful only with the + <parameter>c</parameter> flag. </para></listitem> + + <listitem><para><parameter>a</parameter> - Set archive bit. Causes the + archive bit to be reset when a file is backed up. Useful with the + <parameter>g</parameter> and <parameter>c</parameter> flags. + </para></listitem> + </itemizedlist> + + <para><emphasis>Tar Long File Names</emphasis></para> + + <para><command>smbclient</command>'s tar option now supports long + file names both on backup and restore. However, the full path + name of the file must be less than 1024 bytes. Also, when + a tar archive is created, smbclient's tar option places all + files in the archive with relative names, not absolute names. + </para> + + <para><emphasis>Tar Filenames</emphasis></para> + + <para>All file names can be given as DOS path names (with '\' + as the component separator) or as UNIX path names (with '/' as + the component separator). </para> + + <para><emphasis>Examples</emphasis></para> + + <para>Restore from tar file backup.tar into myshare on mypc + (no password on share). </para> + + <para><command>smbclient //mypc/myshare "" -N -Tx backup.tar + </command></para> + + <para>Restore everything except <filename>users/docs</filename> + </para> + + <para><command>smbclient //mypc/myshare "" -N -TXx backup.tar + users/docs</command></para> + + <para>Create a tar file of the files beneath <filename> + users/docs</filename>. </para> + + <para><command>smbclient //mypc/myshare "" -N -Tc + backup.tar users/docs </command></para> + + <para>Create the same tar file as above, but now use + a DOS path name. </para> + + <para><command>smbclient //mypc/myshare "" -N -tc backup.tar + users\edocs </command></para> + + <para>Create a tar file of all the files and directories in + the share. </para> + + <para><command>smbclient //mypc/myshare "" -N -Tc backup.tar * + </command></para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>-D initial directory</term> + <listitem><para>Change to initial directory before starting. Probably + only of any use with the tar -T option. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-c command string</term> + <listitem><para>command string is a semicolon separated list of + commands to be executed instead of prompting from stdin. <parameter> + -N</parameter> is implied by <parameter>-c</parameter>.</para> + + <para>This is particularly useful in scripts and for printing stdin + to the server, e.g. <command>-c 'print -'</command>. </para></listitem> + </varlistentry> + </variablelist> +</refsect1> + + +<refsect1> + <title>OPERATIONS</title> + + <para>Once the client is running, the user is presented with + a prompt : </para> + + <para><prompt>smb:\> </prompt></para> + + <para>The backslash ("\") indicates the current working directory + on the server, and will change if the current working directory + is changed. </para> + + <para>The prompt indicates that the client is ready and waiting to + carry out a user command. Each command is a single word, optionally + followed by parameters specific to that command. Command and parameters + are space-delimited unless these notes specifically + state otherwise. All commands are case-insensitive. Parameters to + commands may or may not be case sensitive, depending on the command. + </para> + + <para>You can specify file names which have spaces in them by quoting + the name with double quotes, for example "a long file name". </para> + + <para>Parameters shown in square brackets (e.g., "[parameter]") are + optional. If not given, the command will use suitable defaults. Parameters + shown in angle brackets (e.g., "<parameter>") are required. + </para> + + + <para>Note that all commands operating on the server are actually + performed by issuing a request to the server. Thus the behavior may + vary from server to server, depending on how the server was implemented. + </para> + + <para>The commands available are given here in alphabetical order. </para> + + <variablelist> + <varlistentry> + <term>? [command]</term> + <listitem><para>If "command" is specified, the ? command will display + a brief informative message about the specified command. If no + command is specified, a list of available commands will + be displayed. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>! [shell command]</term> + <listitem><para>If "shell command" is specified, the ! + command will execute a shell locally and run the specified shell + command. If no command is specified, a local shell will be run. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>cd [directory name]</term> + <listitem><para>If "directory name" is specified, the current + working directory on the server will be changed to the directory + specified. This operation will fail if for any reason the specified + directory is inaccessible. </para> + + <para>If no directory name is specified, the current working + directory on the server will be reported. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>del <mask></term> + <listitem><para>The client will request that the server attempt + to delete all files matching "mask" from the current working + directory on the server. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>dir <mask></term> + <listitem><para>A list of the files matching "mask" in the current + working directory on the server will be retrieved from the server + and displayed. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>exit</term> + <listitem><para>Terminate the connection with the server and exit + from the program. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>get <remote file name> [local file name]</term> + <listitem><para>Copy the file called "remote file name" from + the server to the machine running the client. If specified, name + the local copy "local file name". Note that all transfers in + <command>smbclient</command> are binary. See also the + lowercase command. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>help [command]</term> + <listitem><para>See the ? command above. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>lcd [directory name]</term> + <listitem><para>If "directory name" is specified, the current + working directory on the local machine will be changed to + the directory specified. This operation will fail if for any + reason the specified directory is inaccessible. </para> + + <para>If no directory name is specified, the name of the + current working directory on the local machine will be reported. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term>lowercase</term> + <listitem><para>Toggle lowercasing of filenames for the get and + mget commands. </para> + + <para>When lowercasing is toggled ON, local filenames are converted + to lowercase when using the get and mget commands. This is + often useful when copying (say) MSDOS files from a server, because + lowercase filenames are the norm on UNIX systems. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>ls <mask></term> + <listitem><para>See the dir command above. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>mask <mask></term> + <listitem><para>This command allows the user to set up a mask + which will be used during recursive operation of the mget and + mput commands. </para> + + <para>The masks specified to the mget and mput commands act as + filters for directories rather than files when recursion is + toggled ON. </para> + + <para>The mask specified with the mask command is necessary + to filter files within those directories. For example, if the + mask specified in an mget command is "source*" and the mask + specified with the mask command is "*.c" and recursion is + toggled ON, the mget command will retrieve all files matching + "*.c" in all directories below and including all directories + matching "source*" in the current working directory. </para> + + <para>Note that the value for mask defaults to blank (equivalent + to "*") and remains so until the mask command is used to change it. + It retains the most recently specified value indefinitely. To + avoid unexpected results it would be wise to change the value of + mask back to "*" after using the mget or mput commands. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>md <directory name></term> + <listitem><para>See the mkdir command. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>mget <mask></term> + <listitem><para>Copy all files matching mask from the server to + the machine running the client. </para> + + <para>Note that mask is interpreted differently during recursive + operation and non-recursive operation - refer to the recurse and + mask commands for more information. Note that all transfers in + smbclient are binary. See also the lowercase command. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>mkdir <directory name></term> + <listitem><para>Create a new directory on the server (user access + privileges permitting) with the specified name. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>mput <mask></term> + <listitem><para>Copy all files matching mask in the current working + directory on the local machine to the current working directory on + the server. </para> + + <para>Note that mask is interpreted differently during recursive + operation and non-recursive operation - refer to the recurse and mask + commands for more information. Note that all transfers in smbclient + are binary. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>print <file name></term> + <listitem><para>Print the specified file from the local machine + through a printable service on the server. </para> + + <para>See also the printmode command.</para></listitem> + </varlistentry> + + + + <varlistentry> + <term>printmode <graphics or text></term> + <listitem><para>Set the print mode to suit either binary data + (such as graphical information) or text. Subsequent print + commands will use the currently set print mode. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>prompt</term> + <listitem><para>Toggle prompting for filenames during operation + of the mget and mput commands. </para> + + <para>When toggled ON, the user will be prompted to confirm + the transfer of each file during these commands. When toggled + OFF, all specified files will be transferred without prompting. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term>put <local file name> [remote file name]</term> + <listitem><para>Copy the file called "local file name" from the + machine running the client to the server. If specified, + name the remote copy "remote file name". Note that all transfers + in smbclient are binary. See also the lowercase command. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>queue</term> + <listitem><para>Displays the print queue, showing the job id, + name, size and current status. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>quit</term> + <listitem><para>See the exit command. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>rd <directory name></term> + <listitem><para>See the rmdir command. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>recurse</term> + <listitem><para>Toggle directory recursion for the commands mget + and mput. </para> + + <para>When toggled ON, these commands will process all directories + in the source directory (i.e., the directory they are copying + from ) and will recurse into any that match the mask specified + to the command. Only files that match the mask specified using + the mask command will be retrieved. See also the mask command. + </para> + + <para>When recursion is toggled OFF, only files from the current + working directory on the source machine that match the mask specified + to the mget or mput commands will be copied, and any mask specified + using the mask command will be ignored. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>rm <mask></term> + <listitem><para>Remove all files matching mask from the current + working directory on the server. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>rmdir <directory name></term> + <listitem><para>Remove the specified directory (user access + privileges permitting) from the server. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>tar <c|x>[IXbgNa]</term> + <listitem><para>Performs a tar operation - see the <parameter>-T + </parameter> command line option above. Behavior may be affected + by the tarmode command (see below). Using g (incremental) and N + (newer) will affect tarmode settings. Note that using the "-" option + with tar x may not work - use the command line option instead. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term>blocksize <blocksize></term> + <listitem><para>Blocksize. Must be followed by a valid (greater + than zero) blocksize. Causes tar file to be written out in + blocksize*TBLOCK (usually 512 byte) blocks. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>tarmode <full|inc|reset|noreset></term> + <listitem><para>Changes tar's behavior with regard to archive + bits. In full mode, tar will back up everything regardless of the + archive bit setting (this is the default mode). In incremental mode, + tar will only back up files with the archive bit set. In reset mode, + tar will reset the archive bit on all files it backs up (implies + read/write share). </para></listitem> + </varlistentry> + + + <varlistentry> + <term>setmode <filename> <perm=[+|\-]rsha></term> + <listitem><para>A version of the DOS attrib command to set + file permissions. For example: </para> + + <para><command>setmode myfile +r </command></para> + + <para>would make myfile read only. </para></listitem> + </varlistentry> + + </variablelist> +</refsect1> + +<refsect1> + <title>NOTES</title> + + <para>Some servers are fussy about the case of supplied usernames, + passwords, share names (AKA service names) and machine names. + If you fail to connect try giving all parameters in uppercase. + </para> + + <para>It is often necessary to use the -n option when connecting + to some types of servers. For example OS/2 LanManager insists + on a valid NetBIOS name being used, so you need to supply a valid + name that would be known to the server.</para> + + <para>smbclient supports long file names where the server + supports the LANMAN2 protocol or above. </para> +</refsect1> + +<refsect1> + <title>ENVIRONMENT VARIABLES</title> + + <para>The variable <parameter>$USER</parameter> may contain the + username of the person using the client. This information is + used only if the protocol level is high enough to support + session-level passwords.</para> + + + <para>The variable <parameter>$PASSWD</parameter> may contain + the password of the person using the client. This information is + used only if the protocol level is high enough to support + session-level passwords. </para> +</refsect1> + + +<refsect1> + <title>INSTALLATION</title> + + <para>The location of the client program is a matter for + individual system administrators. The following are thus + suggestions only. </para> + + <para>It is recommended that the smbclient software be installed + in the <filename>/usr/local/samba/bin/</filename> or <filename> + /usr/samba/bin/</filename> directory, this directory readable + by all, writeable only by root. The client program itself should + be executable by all. The client should <emphasis>NOT</emphasis> be + setuid or setgid! </para> + + <para>The client log files should be put in a directory readable + and writeable only by the user. </para> + + <para>To test the client, you will need to know the name of a + running SMB/CIFS server. It is possible to run <command>smbd(8) + </command> an ordinary user - running that server as a daemon + on a user-accessible port (typically any port number over 1024) + would provide a suitable test server. </para> +</refsect1> + + +<refsect1> + <title>DIAGNOSTICS</title> + + <para>Most diagnostics issued by the client are logged in a + specified log file. The log file name is specified at compile time, + but may be overridden on the command line. </para> + + <para>The number and nature of diagnostics available depends + on the debug level used by the client. If you have problems, + set the debug level to 3 and peruse the log files. </para> +</refsect1> + + +<refsect1> + <title>VERSION</title> + + <para>This man page is correct for version 2.2 of + the Samba suite.</para> +</refsect1> + + +<refsect1> + <title>AUTHOR</title> + + <para>The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed.</para> + + <para>The original Samba man pages were written by Karl Auer. + The man page sources were converted to YODL format (another + excellent piece of Open Source software, available at + <ulink url="ftp://ftp.icce.rug.nl/pub/unix/"> + ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 + release by Jeremy Allison. The conversion to DocBook for + Samba 2.2 was done by Gerald Carter</para> +</refsect1> + +</refentry> |