diff options
Diffstat (limited to 'docs/manpages/smbclient.1')
| -rw-r--r-- | docs/manpages/smbclient.1 | 1133 |
1 files changed, 1133 insertions, 0 deletions
diff --git a/docs/manpages/smbclient.1 b/docs/manpages/smbclient.1 new file mode 100644 index 0000000000..5590e01296 --- /dev/null +++ b/docs/manpages/smbclient.1 @@ -0,0 +1,1133 @@ +.TH SMBCLIENT 1 17/1/1995 smbclient smbclient +.SH NAME +smbclient \- ftp-like Lan Manager client program +.SH SYNOPSIS +.B smbclient +.B servicename +[ +.B password +] [ +.B -A +] [ +.B -E +] [ +.B -L +.I host +] [ +.B -M +.I host +] [ +.B -I +.I IP number +] [ +.B -N +] [ +.B -P +] [ +.B -U +.I username +] [ +.B -d +.I debuglevel +] [ +.B -l +.I log basename +] [ +.B -n +.I netbios name +] [ +.B -O +.I socket options +] [ +.B -p +.I port number +.B -T +.I tar options +.B -D +.I initial directory +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B smbclient +is a client that can 'talk' to a Lan Manager server. It offers +an interface similar to that of the +.B ftp +program (see +.B ftp(1)). 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. + +.SH OPTIONS +.B servicename +.RS 3 +.B servicename +is the name of the service you want to use on the server. A service +name takes the form +.B "\\\\\\\\server\\\\service" +where +.B server +is the netbios name of the Lan Manager server offering the desired service and +.B service +is the name of the service offered. Thus to connect to the service "printer" +on the Lan Manager server "lanman", you would use the servicename + +.RS 10 +.B "\\\\\\\\lanman\\\\printer" +.RE + +Note that the server name required is NOT necessarily the host name of the +server! The name required is a Lan Manager server name, which may or may not +be the same as the hostname of the machine running the server. +.RE + +.B password +.RS 3 +.B +password +is the password required to access the specified service on the +specified server. If supplied, the +.B -N +option (suppress password prompt) is assumed. + +There is no default password. If no password is supplied on the command line +(either here or using the +.B -U +option (see below)) and +.B -N +is not specified, the client will prompt for a password, even if the desired +service does not require one. (If prompted for a password and none is +required, simply press ENTER to provide a null password.) + +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. + +Be cautious about including passwords in scripts. +.RE + +.B -A + +.RS 3 +This parameter, if specified, causes the maximum debug level to be selected. +Be warned that this generates prodigious amounts of debug data. There is also +a security issue involved, as at the maximum debug level cleartext passwords +may be written to some log files. +.RE + +.B -L + +.RS 3 +This option allows you to look at what services are available on a +server. You use it as "smbclient -L host" and a list should appear. +The -I option may be useful if your netbios names don't match your +tcp/ip host names or if you are trying to reach a host on another +network. For example: + +smbclient -L ftp -I ftp.microsoft.com + +will list the shares available on microsofts public server. +.RE + +.B -M + +.RS 3 +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. + +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. + +The message is also automatically truncated if the message is over +1600 bytes, as this is the limit of the protocol. + +One useful trick is to cat the message through smbclient. For example: + +cat mymessage.txt | smbclient -M FRED + +will send the message in the file "mymessage.txt" to the machine FRED. + +You may also find the -U and -I options useful, as they allow you to +control the FROM and TO parts of the message. + +Samba currently has no way of receiving WinPopup messages. + +Note: Copy WinPopup into the startup group on your WfWg PCs if you +want them to always be able to receive messages. +.RE + +.B -E + +.RS 3 +This parameter, if specified, causes the client to write messages to the +standard error stream (stderr) rather than to the standard output stream. + +By default, the client writes messages to standard output - typically the +user's tty. +.RE + +.B -I +.I IP number + +.RS 3 +.I IP number +represents the IP number of the server to connect to. It should +be specified in standard "a.b.c.d" notation. + +Normally the client will attempt to locate the specified Lan Manager server +by looking it up - that is, broadcasting a request for the given server to +identify itself. Using this parameter will force the client to assume that +the server is on the machine with the specified IP number. + +There is no default for this parameter. If not supplied, it will be determined +automatically by the client as described above. +.RE + +.B -N + +.RS 3 +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. + +Unless a password is specified on the command line or this parameter is +specified, the client will request a password. +.RE + +.B -O +.I socket options +.RS 3 + +See the socket options section of smb.conf(5) for details + +.RE +.B -P + +.RS 3 +If specified, the service requested will be connected to as a printer service +rather than as a normal filespace service. Operations such as put and get +will not be applicable for such a connection. + +By default, services will be connected to as NON-printer services. +.RE + +.B -U +.I username + +.RS 3 +.I username +is the user name that will be used by the client to make a connection, +assuming your server is running a protocol that allows for usernames. + +Some servers are fussy about the case of this name, and some insist +that it must be a valid netbios name. + +If no +.I username +is supplied, it will default to an uppercase version of the +environment variable +.B USER +or +.B LOGNAME +in that order. +If no +.I username +is supplied and neither environment variable exists the user name will +be empty. + +If the service you are connecting to requires a password, it can be supplied +using the +.B -U +option, by appending a percent symbol ("%") then the password to +.I username. +For example, to attach to a service as user "fred" with password "secret", you +would specify +.B -U +.I fred%secret +on the command line. Note that there are no spaces around the percent symbol. + +If you specify the password as part of +.I username +then the +.B -N +option (suppress password prompt) is assumed. + +If you specify the password as a parameter AND as part of +.I username +then the password as part of +.I 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. + +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. + +Be cautious about including passwords in scripts. +.RE + +.B -d +.I debuglevel +.RS 3 + +debuglevel is an integer from 0 to 5. + +The default value if this parameter is not specified is zero. + +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. + +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. +.RE + +.B -l +.I log basename + +.RS 3 +If specified, +.I log basename +specifies a base filename into which operational data from the running client +will be logged. + +The default base name is specified at compile time. + +The base name is used to generate actual log file names. For example, if the +name specified was "log", the following files would be used for log data: + +.RS 3 +log.client.debug (containing debugging information) + +log.client.in (containing inbound transaction data) + +log.client.out (containing outbound transaction data) +.RE + +The log files generated are never removed by the client. +.RE +.RE + +.B -n +.I netbios name + +.RS 3 +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. +.RE + +.B -p +.I port number +.RS 3 + +port number is a positive integer value. + +The default value if this parameter is not specified is 139. + +This number is the port number that will be used when making connections to +the server. The standard (well-known) port number for the server is 139, +hence the default. + +This parameter is not normally specified. + +.B -T +.I tar options +.RS3 + +where tar options are one or more of c,x,I,X,b,g,N or a; used as: +.LP +smbclient +.B "\\\\\\\\server\\\\share" +\-TcxIXbgNa +[ +.IR blocksize +] +[ +.IR newer-file +] +.IR tarfile +[ +.IR filenames.... +] + +.RS3 +.B c +Create a tar file on UNIX. Must be followed by the name of a tar file, +tape device or "-" for standard output. (May be useful to set debugging +low (-d0)) to avoid corrupting your tar file if using "-"). Mutually +exclusive with the x flag. + +.B x +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 c flag. + +.B I +Include files and directories. Is the default behaviour when +.IR 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 does not work for included files for extractions (yet). + +.B X +Exclude files and directories. Causes tar files to be excluded from +an extract or create. See example below. +Filename globbing does not work for excluded files (yet). + +.B b +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. + +.B g +Incremental. Only back up files that have the archive bit set. Useful +only with the c flag. + +.B N +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 c flag. + +.B a +Set archive bit. Causes the archive bit to be reset when a file is backed +up. Useful with the g (and c) flags. +.LP + +.B Examples + +smbclient \\\\mypc\\myshare "" -N -Tx backup.tar + +Restore from tar file backup.tar into myshare on mypc (no password on share). + +smbclient \\\\mypc\\myshare "" -N -TXx backup.tar users/docs + +Restore everything except users/docs + +smbclient \\\\mypc\\myshare "" -N -Tc backup.tar users/docs + +Create a tar file of the files beneath users/docs. + +.RE + +.B -D +.I initial directory + +.RS3 + +Change to initial directory before starting. Probably only of any use +with the tar (\-T) option. + + +.RE + +.SH OPERATIONS +Once the client is running, the user is presented with a prompt, "smb: \\>". +The backslash ("\\") indicates the current working directory on the server, +and will change if the current working directory is changed. + +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. + +You can specify file names which have spaces in them by quoting the +name with double quotes, for example "a long file name". + +Parameters shown in square brackets (eg., "[parameter]") are optional. If not +given, the command will use suitable defaults. Parameters shown in angle +brackets (eg., "<parameter>") are required. + +Note that all commands operating on the server are actually performed by +issuing a request to the server. Thus the behaviour may vary from server to +server, depending on how the server was implemented. + +The commands available are given here in alphabetical order. + +.B ? +.RS 3 +.B Parameters: +.RS 3 +.I [command] + +.RE +.B Description: +.RS 3 +If +.I command +is specified, the +.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. +.RE +.RE + +.B ! +.RS 3 +.B Parameters: +.RS 3 +.I [shell command] + +.RE +.B Description: +.RS 3 +If +.I shell command +is specified, the +.B ! +command will execute a shell locally and run the specified shell command. If +no command is specified, a shell will be run. +.RE +.RE + +.B cd +.RS 3 +.B Parameters: +.RS 3 +.I [directory name] + +.RE +.B Description: +.RS 3 +If +.I directory name +is specified, the current working directory +.B on the server +will be changed to the directory specified. This operation will fail if for +any reason the specified directory is inaccessible. + +If no directory name is specified, the current working directory +.B on the server +will be reported. +.RE +.RE + +.B del +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +The client will request that the server attempt to delete all files matching +.I mask +from the current working directory +.B on the server. +.RE +.RE + +.B dir +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +A list of the files matching +.I mask +in the current working directory +.B on the server +will be retrieved from the server and displayed. +.RE +.RE + +.B exit +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Terminate the connection with the server and exit from the program. +.RE +.RE + +.B get +.RS 3 +.B Parameters: +.RS 3 +.I <remote file name> [local file name] + +.RE +.B Description: +.RS 3 +Copy the file called +.I remote file name +from the server to the machine running the client. If specified, name the +local copy +.I local file name. +Note that all transfers in smbclient are binary. See also the +.B lowercase +command. +.RE +.RE + +.B help +.RS 3 +.B Parameters: +.RS 3 +.I [command] + +.RE +.B Description: +.RS 3 +See the +.B ? +command above. +.RE +.RE + +.B lcd +.RS 3 +.B Parameters: +.RS 3 +.I [directory name] + +.RE +.B Description: +.RS 3 +If +.I directory name +is specified, the current working directory +.B on the local machine +will be changed to the directory specified. This operation will fail if for +any reason the specified directory is inaccessible. + +If no directory name is specified, the name of the current working directory +.B on the local machine +will be reported. +.RE +.RE + +.B lowercase +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle lowercasing of filenames for the +.B get +and +.B mget +commands. + +When lowercasing is toggled ON, local filenames are converted to lowercase +when using the +.B get +and +.B mget +commands. This is often useful when copying (say) MSDOS files from a server, +because lowercase filenames are the norm on Unix systems. +.RE +.RE + +.B ls +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +See the +.B dir +command above. +.RE +.RE + +.B mask +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +This command allows the user to set up a mask which will be used during +recursive operation of the +.B mget +and +.B mput +commands. + +The masks specified to the +.B mget +and +.B mput +commands act as filters for directories +rather than files when recursion is toggled ON. + +The mask specified with the +.B mask +command is necessary to filter files within those directories. For example, +if the mask specified in an +.B mget +command is "source*" +.I and +the mask specified with the +.B mask +command is "*.c" +.I and +recursion is toggled ON, the +.B mget +command will retrieve all files matching "*.c" in all directories below +and including all directories matching "source*" in the current working +directory. + +Note that the value for +.I mask +defaults to blank (equivalent to "*") and remains so until the +.B 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 +or +.B mput +commands. +.RE +.RE + +.B md +.RS 3 +.B Parameters: +.RS 3 +.I <directory name> + +.RE +.B Description: +.RS 3 +See the +.B mkdir +command. +.RE +.RE + +.B mget +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +Copy all files matching +.I mask +from the server to the machine running the client. + +Note that +.I mask +is interpreted differently during recursive operation and non-recursive +operation - refer to the +.B recurse +and +.B mask +commands for more information. Note that all transfers in smbclient are +binary. See also the +.B lowercase +command. +.RE +.RE + +.B mkdir +.RS 3 +.B Parameters: +.RS 3 +.I <directory name> + +.RE +.B Description: +.RS 3 +Create a new directory +.B on the server +(user access privileges permitting) with the specified name. +.RE +.RE + +.B mput +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +Copy all files matching +.I mask +in the current working directory +.B on the local machine +to the current working directory on the server. + +Note that +.I mask +is interpreted differently during recursive operation and non-recursive +operation - refer to the +.B recurse +and +.B mask +commands for more information. Note that all transfers in smbclient are +binary. +.RE +.RE + +.B print +.RS 3 +.B Parameters: +.RS 3 +.I <file name> + +.RE +.B Description: +.RS 3 +Print the specified file +.B from the local machine +through a printable service on the server. + +See also the +.B printmode +command. +.RE +.RE + +.B printmode +.RS 3 +.B Parameters: +.RS 3 +.I <graphics or text> + +.RE +.B Description: +.RS 3 +Set the print mode to suit either binary data (such as graphical information) +or text. Subsequent +.B print +commands will use the currently set print mode. +.RE +.RE + +.B prompt +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle prompting for filenames during operation of the +.B mget +and +.B mput +commands. + +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. +.RE +.RE + +.B put +.RS 3 +.B Parameters: +.RS 3 +.I <local file name> [remote file name] + +.RE +.B Description: +.RS 3 +Copy the file called +.I local file name +from the machine running the client to the server. If specified, name the +remote copy +.I remote file name. +Note that all transfers in smbclient are binary. See also the +.B lowercase +command. +.RE +.RE + +.B queue +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Displays the print queue, showing the job id, name, size and current status. +.RE +.RE + +.B quit +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +See the +.B exit +command. +.RE +.RE + +.B rd +.RS 3 +.B Parameters: +.RS 3 +.I <directory name> + +.RE +.B Description: +.RS 3 +See the +.B rmdir +command. +.RE +.RE + +.B recurse +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle directory recursion for the commands +.B mget +and +.B mput +. + +When toggled ON, these commands will process all directories in the source +directory (ie., the directory they are copying +.I 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 +command will be retrieved. See also the +.mask +command. + +When recursion is toggled OFF, only files from the current working +directory on the source machine that match the mask specified to the +.B mget +or +.B mput +commands will be copied, and any mask specified using the +.B mask +command will be ignored. +.RE +.RE + +.B rm +.RS 3 +.B Parameters: +.RS 3 +.I <mask> + +.RE +.B Description: +.RS 3 +Remove all files matching +.I mask +from the current working directory +.B on the server. +.RE +.RE + +.B rmdir +.RS 3 +.B Parameters: +.RS 3 +.I <directory name> + +.RE +.B Description: +.RS 3 +Remove the specified directory (user access privileges permitting) +.B from the server. +.RE +.RE + +.B tar +.RS 3 +.B Parameters: +.RS 3 +.I <c|x>[IXbgNa] + +.RE +.B Description: +.RS 3 +Performs a tar operation - see -T command line option above. Behaviour +may be affected by the +.B tarmode +command (see below). Using the 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. +.RE +.RE + +.B blocksize +.RS 3 +.B Parameters +.RS 3 +.I <blocksize> + +.RE +.B Description +.RS 3 +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. +.RE +.RE + +.B tarmode +.RS 3 +.B Parameters +.RS 3 +.I <full|inc|reset|noreset> + +.RE +.B Description +.RS 3 +Changes tar's behaviour 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). +.RE +.RE + +.B setmode +.RS 3 +.B Parameters +.RS 3 +.I <filename> <perm=[+|-]rsha> + +.RE +.B Description +.RS 3 +A version of the DOS attrib command to set file permissions. For example, + +setmode myfile +r + +would make myfile read only. +.RE +.RE + +.SH NOTES +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. + +It is often necessary to use the +.B -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. + +.B smbclient +supports long file names where the server supports the LANMAN2 +protocol. + +.SH FILES +Not applicable. + +.SH ENVIRONMENT VARIABLES +.B USER +.RS 3 +The variable USER 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. +.RE + +.SH INSTALLATION +The location of the client program is a matter for individual system +administrators. The following are thus suggestions only. + +It is recommended that the client software be installed under the /usr/local +hierarchy, in a directory readable by all, writeable only by root. The client +program itself should be executable by all. The client should NOT be setuid +or setgid! + +The client log files should be put in a directory readable and writable only +by the user. + +To test the client, you will need to know the name of a running Lan manager +server. It is possible to run the smbd (see +.B smbd(8)) as 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. +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the client software, so it is possible that your version of +the client has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B smbd(8) + +.SH DIAGNOSTICS +[This section under construction] + +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. + +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. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. + +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +This man page written by Karl Auer (Karl.Auer@anu.edu.au) + +See +.B smb.conf(5) for a full list of contributors and details on how to +submit bug reports, comments etc. |