diff options
Diffstat (limited to 'docs-xml/manpages/smbclient.1.xml')
| -rw-r--r-- | docs-xml/manpages/smbclient.1.xml | 1210 |
1 files changed, 1210 insertions, 0 deletions
diff --git a/docs-xml/manpages/smbclient.1.xml b/docs-xml/manpages/smbclient.1.xml new file mode 100644 index 0000000..40f9d89 --- /dev/null +++ b/docs-xml/manpages/smbclient.1.xml @@ -0,0 +1,1210 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<refentry id="smbclient.1"> + +<refmeta> + <refentrytitle>smbclient</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">Samba</refmiscinfo> + <refmiscinfo class="manual">User Commands</refmiscinfo> + <refmiscinfo class="version">&doc.version;</refmiscinfo> +</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="opt">-M|--message=HOST</arg> + <arg choice="opt">-I|--ip-address=IP</arg> + <arg choice="opt">-E|--stderr</arg> + <arg choice="opt">-L|--list=HOST</arg> + <arg choice="opt">-T|--tar=<c|x>IXFvgbNan</arg> + <arg choice="opt">-D|--directory=DIR</arg> + <arg choice="opt">-b|--send-buffer=BYTES</arg> + <arg choice="opt">-t|--timeout=SECONDS</arg> + <arg choice="opt">-p|--port=PORT</arg> + <arg choice="opt">-g|--grepable</arg> + <arg choice="opt">-q|--quiet</arg> + <arg choice="opt">-B|--browse</arg> + <arg choice="opt">-?|--help</arg> + <arg choice="opt">--usage</arg> + <arg choice="opt">-d|--debuglevel=DEBUGLEVEL</arg> + <arg choice="opt">--debug-stdout</arg> + <arg choice="opt">-s|--configfile=CONFIGFILE</arg> + <arg choice="opt">--option=name=value</arg> + <arg choice="opt">-l|--log-basename=LOGFILEBASE</arg> + <arg choice="opt">--leak-report</arg> + <arg choice="opt">--leak-report-full</arg> + <arg choice="opt">-R|--name-resolve=NAME-RESOLVE-ORDER</arg> + <arg choice="opt">-O|--socket-options=SOCKETOPTIONS</arg> + <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg> + <arg choice="opt">-n|--netbiosname=NETBIOSNAME</arg> + <arg choice="opt">--netbios-scope=SCOPE</arg> + <arg choice="opt">-W|--workgroup=WORKGROUP</arg> + <arg choice="opt">--realm=REALM</arg> + <arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg> + <arg choice="opt">-N|--no-pass</arg> + <arg choice="opt">--password=STRING</arg> + <arg choice="opt">--pw-nt-hash</arg> + <arg choice="opt">-A|--authentication-file=FILE</arg> + <arg choice="opt">-P|--machine-pass</arg> + <arg choice="opt">--simple-bind-dn=DN</arg> + <arg choice="opt">--use-kerberos=desired|required|off</arg> + <arg choice="opt">--use-krb5-ccache=CCACHE</arg> + <arg choice="opt">--use-winbind-ccache</arg> + <arg choice="opt">--client-protection=sign|encrypt|off</arg> + <arg choice="opt">-V|--version</arg> + <arg choice="opt">-c|--command=STRING</arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry> 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 <citerefentry><refentrytitle>ftp</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>). + 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|--name-resolve</parameter> parameter to <command>smbclient</command> or + using the name resolve order parameter in + the <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> 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>-M|--message 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 pipe the message through <command>smbclient</command>. + For example: smbclient -M FRED < mymessage.txt 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 <parameter>message command</parameter> parameter in the <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> 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>-p|--port 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>-g|--grepable</term> + <listitem><para>This parameter provides combined with + <parameter>-L</parameter> easy parseable output that allows processing + with utilities such as grep and cut. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-m|--max-protocol protocol</term> + <listitem><para>This allows the user to select the + highest SMB protocol level that smbclient will use to + connect to the server. By default this is set to + highest available SMB3 protocol version. + To connect using SMB2 or SMB1 protocol, use the + strings SMB2 or NT1 respectively. Note that to connect + to a Windows 2012 server with encrypted transport selecting + a max-protocol of SMB3 is required. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-P|--machine-pass</term> + <listitem><para> + Make queries to the external server using the machine account of the local server. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-I|--ip-address IP-address</term> + <listitem><para><replaceable>IP address</replaceable> 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|--stderr</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>-L|--list</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>-b|--send-buffer buffersize</term> + <listitem><para> + When sending or receiving files, smbclient uses an + internal buffer sized by the maximum number of allowed requests + to the connected server. This command allows this size to be set to any + range between 0 (which means use the default server controlled size) bytes + and 16776960 (0xFFFF00) bytes. Using the server controlled size is the + most efficient as smbclient will pipeline as many simultaneous reads or + writes needed to keep the server as busy as possible. Setting this to + any other size will slow down the transfer. This can also be set + using the <command>iosize</command> command inside smbclient. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-B|--browse</term> + <listitem><para>Browse SMB servers using DNS.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-t|--timeout <timeout-seconds></term> + <listitem><para>This allows the user to tune the default + timeout used for each SMB request. The default setting is + 20 seconds. Increase it if requests to the server sometimes + time out. This can happen when SMB3 encryption is selected + and smbclient is overwhelming the server with requests. + This can also be set using the <command>timeout</command> + command inside smbclient. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-T|--tar 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 + backup archive on the local system. 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>n</parameter> - In + combination with the <parameter>c</parameter> + flag, do not actually create the archive, + instead perform a dry run that attempts + everything that involved in creation other than + writing the file.</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 + 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 <parameter>r</parameter> below. </para></listitem> + + <listitem><para><parameter>X</parameter> - Exclude files and directories. + Causes files to be excluded from an extract or create. See + example below. Filename globbing works in one of two ways. + See <parameter>r</parameter> below. </para></listitem> + + <listitem><para><parameter>F</parameter> - File containing a list of files and directories. + The <parameter>F</parameter> causes the name following the tarfile to + create to be read as a filename that contains a list of files and directories 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 <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 (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>v</parameter> - Verbose. Makes tar + print out the files being processed. By default tar is not verbose. + This is the same as tarmode verbose. + </para></listitem> + + <listitem><para><parameter>r</parameter> - Use wildcard + matching to include or exclude. Deprecated. + </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, <command>smbclient</command>'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 <filename>backup.tar</filename> 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 the files listed in the file <filename>tarlist</filename>.</para> + + <para><command>smbclient //mypc/myshare "" -N -TcF + backup.tar tarlist</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|--directory 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 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> + + &popt.autohelp; + &cmdline.common.samba.client; + &cmdline.common.connection; + &cmdline.common.credentials; + </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 <replaceable>command</replaceable> 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 <replaceable>shell command</replaceable> 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>allinfo file</term> + <listitem><para>The client will request that the server return + all known information about a file or directory (including streams). + </para></listitem> + </varlistentry> + + <varlistentry> + <term>altname file</term> + <listitem><para>The client will request that the server return + the "alternate" name (the 8.3 name) for a file or directory. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>archive <number></term> + <listitem><para>Sets the archive level when operating on files. + 0 means ignore the archive bit, 1 means only operate on files with this bit set, + 2 means only operate on files with this bit set and reset it after operation, + 3 means operate on all files and reset it after operation. The default is 0. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>backup</term> + <listitem><para>Toggle the state of the "backup intent" flag + sent to the server on directory listings and file opens. If + the "backup intent" flag is true, the server will try and + bypass some file system checks if the user has been granted + SE_BACKUP or SE_RESTORE privileges. This state is useful when + performing a backup or restore operation. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>blocksize <number></term> + <listitem><para>Sets the blocksize parameter for a tar operation. The default is 20. + Causes tar file to be written out in blocksize*TBLOCK (normally 512 byte) units. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>cancel jobid0 [jobid1] ... [jobidN]</term> + <listitem><para>The client will request that the server cancel + the printjobs identified by the given numeric print job ids. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>case_sensitive</term> + <listitem><para>Toggles the setting of the flag in SMB packets that + tells the server to treat filenames as case sensitive. Set to OFF by + default (tells file server to treat filenames as case insensitive). Only + currently affects Samba 3.0.5 and above file servers with the case sensitive + parameter set to auto in the smb.conf. + </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>chmod file mode in octal</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. The client requests that the server + change the UNIX permissions to the given octal mode, in standard UNIX format. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>chown file uid gid</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. The client requests that the server + change the UNIX user and group ownership to the given decimal values. Note there is + currently no way to remotely look up the UNIX uid and gid values for a given name. + This may be addressed in future versions of the CIFS UNIX extensions. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>close <fileid></term> + <listitem><para>Closes a file explicitly opened by the open command. Used for + internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>del <mask></term> + <listitem><para>The client will request that the server attempt + to delete all files matching <replaceable>mask</replaceable> from the current working + directory on the server. </para></listitem> + </varlistentry> + + <varlistentry> + <term>deltree <mask></term> + <listitem><para>The client will request that the server attempt + to delete all files and directories matching <replaceable>mask</replaceable> from the current working + directory on the server. Note this will recursively delete files and directories within + the directories selected even without the recurse command being set. If any of the delete + requests fail the command will stop processing at that point, leaving files and directories + not yet processed untouched. This is by design.</para></listitem> + </varlistentry> + + <varlistentry> + <term>dir <mask></term> + <listitem><para>A list of the files matching <replaceable>mask</replaceable> in the current + working directory on the server will be retrieved from the server + and displayed. </para></listitem> + </varlistentry> + + <varlistentry> + <term>du <filename></term> + <listitem><para>Does a directory listing and then prints out the current disk usage and free space on a share. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>echo <number> <data></term> + <listitem><para>Does an SMBecho request to ping the server. Used for internal Samba testing purposes. + </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 <filename>remote file name</filename> from + the server to the machine running the client. If specified, name + the local copy <filename>local file name</filename>. Note that all transfers in + <command>smbclient</command> are binary. See also the + lowercase command. </para></listitem> + </varlistentry> + + <varlistentry> + <term>getfacl <filename></term> + <listitem><para>Requires the server support the UNIX extensions. Requests and prints + the POSIX ACL on a file. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>hardlink <src> <dest></term> + <listitem><para>Creates a hardlink on the server using Windows CIFS semantics. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>help [command]</term> + <listitem><para>See the ? command above. </para></listitem> + </varlistentry> + + <varlistentry> + <term>history</term> <listitem><para>Displays the command history.</para></listitem> + </varlistentry> + + <varlistentry> + <term>iosize <bytes></term> + <listitem><para> + When sending or receiving files, smbclient uses an + internal buffer sized by the maximum number of allowed requests + to the connected server. This command allows this size to be set to any + range between 0 (which means use the default server controlled size) bytes + and 16776960 (0xFFFF00) bytes. Using the server controlled size is the + most efficient as smbclient will pipeline as many simultaneous reads or + writes needed to keep the server as busy as possible. Setting this to + any other size will slow down the transfer. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>lcd [directory name]</term> + <listitem><para>If <replaceable>directory name</replaceable> 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>link target linkname</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. The client requests that the server + create a hard link between the linkname and target files. The linkname file + must not exist. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>listconnect</term> + <listitem><para>Show the current connections held for DFS purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>lock <filenum> <r|w> <hex-start> <hex-len></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Tries to set a POSIX + fcntl lock of the given type on the given range. Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>logon <username> <password></term> + <listitem><para>Establishes a new vuid for this session by logging on again. + Replaces the current vuid. Prints out the new vuid. Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>logoff</term> + <listitem><para>Logs the user off the server, closing the session. + Used for internal Samba testing purposes. + </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 <replaceable>mask</replaceable> from the server to + the machine running the client. </para> + + <para>Note that <replaceable>mask</replaceable> 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 + <command>smbclient</command> 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>more <file name></term> + <listitem><para>Fetch a remote file and view it with the contents + of your PAGER environment variable. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>mput <mask></term> + <listitem><para>Copy all files matching <replaceable>mask</replaceable> in the current working + directory on the local machine to the current working directory on + the server. </para> + + <para>Note that <replaceable>mask</replaceable> 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 <command>smbclient</command> + are binary. </para></listitem> + </varlistentry> + + <varlistentry> + <term>notify <dir name></term> + <listitem><para>Query a directory for change + notifications. This command issues a recursive + filechangenotify call for all possible changes. As + changes come in will print one line per change. See + <ulink url="https://msdn.microsoft.com/en-us/library/dn392331.aspx">https://msdn.microsoft.com/en-us/library/dn392331.aspx</ulink> + for a description of the action numbers that this + command prints.</para> + <para>This command never ends, it waits for event + indefinitely. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix</term> + <listitem><para>Query the remote server to see if it supports the CIFS UNIX + extensions and prints out the list of capabilities supported. If so, turn + on POSIX pathname processing and large file read/writes (if available),. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_encrypt <domain> <username> <password></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Attempt to negotiate + SMB encryption on this connection. If smbclient connected with kerberos + credentials (-k) the arguments to this command are ignored and the kerberos + credentials are used to negotiate GSSAPI signing and sealing instead. See + also the -e option to smbclient to force encryption on initial connection. + This command is new with Samba 3.2. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_open <filename> <octal mode></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Opens a remote file + using the CIFS UNIX extensions and prints a fileid. Used for internal Samba + testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_mkdir <directoryname> <octal mode></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Creates a remote directory + using the CIFS UNIX extensions with the given mode. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_rmdir <directoryname></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Deletes a remote directory + using the CIFS UNIX extensions. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_unlink <filename></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Deletes a remote file + using the CIFS UNIX extensions. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>posix_whoami</term> + <listitem><para>Query the remote server for the user token using the CIFS UNIX + extensions WHOAMI call. Prints out the guest status, user, group, group list and + sid list that the remote server is using on behalf of the logged on user. + </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></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 <filename>local file name</filename> from the + machine running the client to the server. If specified, + name the remote copy <filename>remote file name</filename>. Note that all transfers + in <command>smbclient</command> 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>readlink symlinkname</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Print + the value of the symlink "symlinkname". + </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>rename <old filename> <new filename> [-f]</term> + <listitem><para>Rename files in the current working directory on the + server from <replaceable>old filename</replaceable> to + <replaceable>new filename</replaceable>. The optional + -f switch allows for superseding the destination file, + if it exists. This is supported by NT1 protocol dialect + and SMB2 protocol family.</para></listitem> + </varlistentry> + + <varlistentry> + <term>rm <mask></term> + <listitem><para>Remove all files matching <replaceable>mask</replaceable> 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>scopy <source filename> <destination filename></term> + <listitem><para>Attempt to copy a file on the server using the + most efficient server-side copy calls. Falls back to using + read then write if server doesn't support server-side copy. + </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> + + <varlistentry> + <term>showconnect</term> + <listitem><para>Show the currently active connection held for DFS purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>stat file</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. The client requests the + UNIX basic info level and prints out the same info that the Linux stat command + would about the file. This includes the size, blocks used on disk, file type, + permissions, inode number, number of links and finally the three timestamps + (access, modify and change). If the file is a special file (symlink, character or + block device, fifo or socket) then extra information may also be printed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>symlink target linkname</term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. The client requests that the server + create a symbolic hard link between the target and linkname files. The linkname file + must not exist. Note that the server will not create a link to any path that lies + outside the currently connected share. This is enforced by the Samba 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 + <replaceable>blocksize</replaceable>*TBLOCK (512 byte) blocks. </para></listitem> + </varlistentry> + + <varlistentry> + <term>tarmode <full|inc|reset|noreset|system|nosystem|hidden|nohidden|verbose|noverbose></term> + <listitem><para>Changes tar's behavior with regard to DOS + attributes. There are 4 modes which can be turned on or + off.</para> + + <para>Incremental mode (default off). When off (using + <command>full</command>) tar will back up everything + regardless of the <emphasis>archive</emphasis> bit + setting. When on (using <command>inc</command>), tar will only + back up files with the archive bit set.</para> + + <para>Reset mode (default off). When on (using + <command>reset</command>), tar will remove the archive bit on + all files it backs up (implies read/write share). Use + <command>noreset</command> to turn off.</para> + + <para>System mode (default on). When off, tar will not backup + system files. Use <command>nosystem</command> to turn off.</para> + + <para>Hidden mode (default on). When off, tar will not backup + hidden files. Use <command>nohidden</command> to turn off.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>timeout <per-operation timeout in seconds></term> + <listitem><para>This allows the user to tune the default + timeout used for each SMB request. The default setting is + 20 seconds. Increase it if requests to the server sometimes + time out. This can happen when SMB3 encryption is selected + and smbclient is overwhelming the server with requests. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>unlock <filenum> <hex-start> <hex-len></term> + <listitem><para>This command depends on the server supporting the CIFS + UNIX extensions and will fail if the server does not. Tries to unlock a POSIX + fcntl lock on the given range. Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>volume</term> + <listitem><para>Prints the current volume name of the share. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>vuid <number></term> + <listitem><para>Changes the currently used vuid in the protocol to + the given arbitrary number. Without an argument prints out the current + vuid being used. Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>tcon <sharename></term> + <listitem><para>Establishes a new tree connect (connection to a share). + Replaces the current tree connect. Prints the new tid (tree id). + Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>tdis</term> + <listitem><para>Close the current share connection (tree disconnect). + Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>tid <number></term> + <listitem><para>Changes the current tree id (tid) in the + protocol to a new arbitrary number. Without an argument, it + prints out the tid currently used. + Used for internal Samba testing purposes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>utimes <filename> <create time> <access time> <write time> < + change time></term> + <listitem><para>Changes the timestamps on a file by name. + Times should be specified in the format [YY]YY:MM:DD-HH:MM:SS or -1 for no change. + </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>See the <command>--user</command> and + <command>--password</command> options for details on ways to + specify a username and password via an environment variable. + </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 <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> 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. </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 part of version &doc.version; 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> +</refsect1> + +</refentry> |