Skip to content

Commit

Permalink
docs: Updated for the SMB protocol
Browse files Browse the repository at this point in the history 
This patch updates the documentation for the SMB/CIFS protocol.
  • Loading branch information
@captain-caveman2k
Bill Nagel authored and captain-caveman2k committed Nov 30, 2014
1 parent c8996ba commit 96c3b1a
Show file tree
Hide file tree
Showing 8 changed files with 42 additions and 5 deletions.
2 changes: 1 addition & 1 deletion docs/FAQ
View file
Expand Up @@ -134,7 +134,7 @@ FAQ

A free and easy-to-use client-side URL transfer library, supporting DICT,
FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3,
POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP.
POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP.

libcurl supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading,
Kerberos, SPNEGO, HTTP form based upload, proxies, cookies, user+password
Expand Down
6 changes: 6 additions & 0 deletions docs/FEATURES
View file
Expand Up @@ -127,6 +127,12 @@ FILE
- upload
- resume

SMB
- SMBv1 over TCP and SSL
- download
- upload
- authentication with NTLMv1

SMTP
- authentication: Plain, Login, CRAM-MD5, Digest-MD5, NTLM (*9) and Kerberos 5
(*4)
Expand Down
4 changes: 4 additions & 0 deletions docs/INTERNALS
View file
Expand Up @@ -264,6 +264,10 @@ Library

The file:// protocol is dealt with in lib/file.c.

SMB

The smb:// protocol is dealt with in lib/smb.c.

LDAP

Everything LDAP is in lib/ldap.c and lib/openldap.c
Expand Down
9 changes: 9 additions & 0 deletions docs/MANUAL
View file
Expand Up @@ -59,6 +59,10 @@ SIMPLE USAGE

curl "http://[2001:1890:1112:1::20]/"

Get a file from an SMB server:

curl -u "domain\username:passwd" smb://server.example.com/share/file.txt

This comment has been minimized.

Sign in to view

Copy link
@gvanem

gvanem Dec 2, 2014

Contributor

FYI. Connecting using SMB and no credentials throws an abort() inside memdebug.c / curl_domalloc().

Assertion failed: wantedsize != 0, file memdebug.c, line 172

Call-stack:

...
MSVCR100!abort+0x32
MSVCR100!_wassert+0x5ff
libcurl!curl_domalloc(unsigned int wantedsize = <Memory access error>, int line = <Memory access error>, char * source = <Memory access error>)+0x21 [g:\mingw32\src\inet\curl\lib\memdebug.c @ 172]
libcurl!Curl_ntlm_core_mk_nt_hash(struct SessionHandle * data = <Memory access error>, char * password = <Memory access error>, unsigned char * ntbuffer = <Memory access error>)+0x41 [g:\mingw32\src\inet\curl\lib\curl_ntlm_core.c @ 425]
DOWNLOAD TO A FILE

Get a web page and store in a local file with a specific name:
Expand Down Expand Up @@ -228,6 +232,11 @@ UPLOADING

curl --proxytunnel -x proxy:port -T localfile ftp.upload.com

SMB / SMBS

curl -T file.txt -u "domain\username:passwd"
smb://server.example.com/share/

HTTP

Upload all data on stdin to a specified HTTP site:
Expand Down
6 changes: 3 additions & 3 deletions docs/curl.1
View file
Expand Up @@ -20,7 +20,7 @@
.\" *
.\" **************************************************************************
.\"
.TH curl 1 "2 Aug 2014" "Curl 7.38.0" "Curl Manual"
.TH curl 1 "30 Nov 2014" "Curl 7.40.0" "Curl Manual"
.SH NAME
curl \- transfer a URL
.SH SYNOPSIS
Expand All @@ -30,8 +30,8 @@ curl \- transfer a URL
.B curl
is a tool to transfer data from or to a server, using one of the supported
protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,
LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP). The
command is designed to work without user interaction.
LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET
and TFTP). The command is designed to work without user interaction.

curl offers a busload of useful tricks like proxy support, user
authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer
Expand Down
1 change: 1 addition & 0 deletions docs/libcurl/opts/CURLOPT_PROTOCOLS.3
View file
Expand Up @@ -59,6 +59,7 @@ CURLPROTO_RTMPTS
CURLPROTO_RTSP
CURLPROTO_SCP
CURLPROTO_SFTP
CURLPROTO_SMB
CURLPROTO_SMTP
CURLPROTO_SMTPS
CURLPROTO_TELNET
Expand Down
3 changes: 2 additions & 1 deletion docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3
View file
Expand Up @@ -59,13 +59,14 @@ CURLPROTO_RTMPTS
CURLPROTO_RTSP
CURLPROTO_SCP
CURLPROTO_SFTP
CURLPROTO_SMB
CURLPROTO_SMTP
CURLPROTO_SMTPS
CURLPROTO_TELNET
CURLPROTO_TFTP
.fi
.SH DEFAULT
All protocols except for FILE and SCP
All protocols except for FILE, SCP and SMB.
.SH PROTOCOLS
All
.SH EXAMPLE
Expand Down
16 changes: 16 additions & 0 deletions docs/libcurl/opts/CURLOPT_URL.3
View file
Expand Up @@ -80,6 +80,8 @@ http://user:password@www.example.com

ftp://user:password@ftp.example.com

smb://domain%2fuser:password@server.example.com

imap://user:password;options@mail.example.com

pop3://user:password;options@mail.example.com
Expand Down Expand Up @@ -236,6 +238,20 @@ user's home directory
sftp://ssh.example.com/~/Documents/ - This requests a directory listing
of the Documents directory under the user's home directory

.IP SMB
The path part of a SMB request specifies the file to retrieve and from what
share and directory or the share to upload to and as such, may not be omitted.
If the user name is not embedded in the URL, it can be set with the
\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name
is embedded in the URL then it must contain the domain name and as such, the
backslash must be URL encoded as %2f.

smb://server.example.com/files/issue - This specifies the file "issue" located
in the root of the "files" share

smb://server.example.com/files/ -T issue - This specifies the file "issue" will
be uploaded to the root of the "files" share.

.IP LDAP
The path part of a LDAP request can be used to specify the: Distinguished
Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
Expand Down

5 comments on commit 96c3b1a

@captain-caveman2k
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Many thanks Gisle,

I can't seem to reproduce this with a native Visual Studio build (in either Debug or Release) as I always seem to have a valid password pointer. I tried not including the -u argument as well as -u :

However, I have pushed commit f9b7132 to prevent this from happening.

Would you be so kind to confirm whether it fixes the issue for you please?

Cheers again

Steve

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 96c3b1a Dec 2, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I rewrote as new comment since Github's markup fails on my email reply).

@captain-caveman2k:

I can't seem to reproduce this with a native Visual Studio build (in either Debug or Release)
as I always seem to have a valid password pointer.

I've always build libcurl + curl with '-DCURLDEBUG' and '-DDEBUGBUILD'
(but in MSVC release mode). Hence the assert in memdebug.c. So now when
I try w/o any user/password, I always get the content! This command:
curl.exe -v smb://localhost/G_DISK/Delme.bat

give me the contents of 'g:\Delme.bat' (only 194 bytes). But I have
no entry for localhost nor 127.0.0.1 in my %HOME/.netrc. So where does
the credential come from now? Or is it %HOME/_netrc?

However, I have pushed commit f9b7132 f9b7132
to prevent this from happening.

Would you be so kind to confirm whether it fixes the issue for you please?

This issue may have been fixed. But there are other issues with
transferring files > ~32 kB. E.g.
curl.exe -v smb://localhost/G_DISK/large-file.txt

* Marked for [closure]: SMB: failed to communicate
* Closing connection 0
* The cache now contains 0 members
curl: (26) Failed to open/read local data from file/application

Studying smb.c + smb_recv_message(), it seems to me it handles
SMB-messages like datagrams (UDP). Here:

   nbt_size = ntohs(*(unsigned short *)(buf + sizeof(unsigned short))) +
                    sizeof(unsigned int);
   if(smbc->got < nbt_size)
     return CURLE_OK;

it seems 'buf' is treated like the start of an SMB-header.
I fails to see how that can be guaranteed since TCP is used
in my case.

@gknauf
Copy link
Contributor

@gknauf gknauf commented on 96c3b1a Dec 2, 2014 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 96c3b1a Dec 2, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@captain-caveman2k : is there any reason why you dont bring this discussion to the libcurl

Not really. I only commented on the commit since I deleted any SMB-related messages to libcurl.

@captain-caveman2k
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hiya Gisle,

Was there a reason for mentioning my handle in your last comment - whilst I think this discussion should now take place on the mailing list (as we need to involve Bill) - the question was asked by Gunter and not myself ;-)

Please sign in to comment.