[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12

INTERNET-DRAFT                                     Christopher R. Hertel
draft-crhertel-smb-url-02.txt                                 Samba Team
Expires July 8, 2002                                     January 8, 2002


                      SMB Filesharing URL Scheme

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html

   Discussions regarding this document and the SMB URL scheme should
   take place on the jcifs@samba.org mailing list.  Information on
   joining this mailing list can be found at:
   http://lists.samba.org/listinfo/jcifs/.


Abstract

   The Server Message Block (SMB) protocol is one of the most widely
   used network filesystem protocols in existence.  This document
   describes a URL scheme for use with SMB over IETF STD 19 transport.
   The SMB URL scheme can be used to indicate SMB workgroups, servers,
   shares, files, inter-process communications pipes, print queues, and
   devices; the objects in the SMB network filesystem space.















Hertel                    Expires July 8, 2002                  [Page 1]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

Table of Contents
   1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .  2
   2. SMB URL Scheme  . . . . . . . . . . . . . . . . . . . . . . . .  3
      2.1 Server Types  . . . . . . . . . . . . . . . . . . . . . . .  3
      2.2 URL Semantics . . . . . . . . . . . . . . . . . . . . . . .  3
        2.2.1 Accessing the SMB Server Service  . . . . . . . . . . .  4
        2.2.2 Accessing the Workgroup Browse Service  . . . . . . . .  4
        2.2.3 Workgroup Names vs. SMB Server Names  . . . . . . . . .  5
      2.3 Relative SMB URLs . . . . . . . . . . . . . . . . . . . . .  6
      2.4 Fragments . . . . . . . . . . . . . . . . . . . . . . . . .  6
      2.5 Queries . . . . . . . . . . . . . . . . . . . . . . . . . .  6
      2.6 Use of the 'port' Field . . . . . . . . . . . . . . . . . .  7
      2.7. SMB over Native TCP/IP . . . . . . . . . . . . . . . . . .  7
   3. SMB Namespace . . . . . . . . . . . . . . . . . . . . . . . . .  8
   4. Authentication and Security Considerations  . . . . . . . . . .  8
   5. SMB URL Examples  . . . . . . . . . . . . . . . . . . . . . . .  9
   6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . 10
   7. URL Syntax  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
   8. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 12
   9. References  . . . . . . . . . . . . . . . . . . . . . . . . . . 12
   10. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 12
   Appendix A. SMB Implementation Resources . . . . . . . . . . . . . 13
   Appendix B. Host Identifier Syntax Comparison  . . . . . . . . . . 13
   Appendix C. Working with NetBIOS Names (Implementation Notes)  . . 13
      C.1. Resolving DNS names and IP addresses to SMB server names . 14
      C.2. Determining Server Specifier Type  . . . . . . . . . . . . 16
      C.3. Workgroup vs. SMB Server Names . . . . . . . . . . . . . . 17


1. Introduction

   The SMB (Server Message Block) protocol was developed in the 1980's
   by Dr. Barry Feigenbaum at IBM Corporation.  It was later extended by
   3Com Corporation, Intel Corporation, and Microsoft Corporation.  SMB
   was originally carried on a proprietary network transport, the
   interface to which was called NetBIOS (Network Basic Input Output
   System).  Two Internet RFCs ([RFC1001], [RFC1002]) were published
   which describe a mechanism for implementing the NetBIOS API on top of
   TCP and UDP.  Those RFCs are now known collectively as Internet
   Standard #19 (STD 19).

   Several attempts have been made to document and even standardize the
   SMB protocol (see [ONET], [SNIACIFS]), yet the further development of
   SMB remains under the control of Microsoft.  Despite its proprietary
   nature, the workings of SMB over STD 19 transport are sufficiently
   well known that SMB filesharing has been successfully implemented by
   several commercial vendors and in Open Source.  SMB server and client
   software is available for a wide variety of operating system
   platforms.  The very large number of systems which support this form
   of filesharing make an SMB URL scheme both practical and desirable.





Hertel                    Expires July 8, 2002                  [Page 2]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

2. SMB URL Scheme

   The SMB URL follows the generic URI scheme syntax for URLs as defined
   in [RFC2396], with exceptions and caveats as noted.

   An absolute SMB URL takes one of the following general forms:

      smb://
      smb://<workgroup>
      smb://<smb_server>
      smb://<smb_server>/<share>
      smb://<smb_server>/<share>/<path>

   Relative URLs are also supported.


2.1. Service Types

   There are two service types that may be referenced using the SMB URL
   scheme.  These are the SMB filesharing service (known as the "server
   service") and the workgroup browse service.  Implementations SHOULD
   support both of these service types, though some special purpose
   applications MAY choose to support only one service type.

   The SMB filesharing service provides access to SMB shares, while the
   workgroup browse service provides information about the workgroups
   and servers available on the network.


2.2. URL Semantics

   workgroup:  In an SMB filesharing network, SMB servers and clients
               are assigned membership in workgroups.  Workgroups are
               used to organize hosts for administrative purposes.
               Each workgroup is assigned a NetBIOS group name for
               identification.  Thus, the workgroup component of the SMB
               URL can be used to indicate a specific SMB filesharing
               workgroup.

               For each workgroup, a list of member SMB servers is
               maintained.  This list is known as the "browse list".
               The browse list also contains a list of all of the
               workgroups in use on the local IP subnet.  The SMB URL
               is used to access the workgroup browse list.

   smb_server: The smb_server component is used to indicate a specific
               SMB filesharing service.

               SMB filesharing services are identified by NetBIOS name
               (see [RFC1001], section 16.1.1).  In an SMB URL, SMB
               filesharing services may also be identified by DNS name
               or IP address.  A DNS name or IP address MUST be



Hertel                    Expires July 8, 2002                  [Page 3]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

               reverse-mapped (resolved) to a NetBIOS name in order to
               establish a NetBIOS Session Service connection (see
               section 3 and Appendix C, below).

   share:      A share is an object offered for use by an SMB
               filesharing service.  A share may represent the root of a
               directory tree, a set of print queues, an inter-process
               communications (IPC) port, or other sharable object.

   path:       The path identifies a resource within a share, such as
               a named pipe within an IPC share or a file within a
               directory.

               The distinction between the share and the path portion of
               the URL is semantic.  Syntactically, these are parsed as
               a single path (see [RFC2396], section 3.3).

   Operating systems that are derived from Microsoft's MS-DOS or IBM's
   PC-DOS (eg. Windows and OS/2) use a format known as Universal Naming
   Convention (UNC) to identify objects within an SMB filesharing
   network.  The UNC format uses backslashes ("\") to delimit path
   elements.  In general, an SMB URL string can be formed from a UNC
   string by simply replacing the UNC backslashes with forward slashes
   and adding the "smb:" prefix.  For example:

     UNC form                        URL form
     -----------------------------   ---------------------------------
     \\scred\src\                    smb://scred/src/
     \\scred\src\jcifs\              smb://scred/src/jcifs/
     \\scred\src\jcifs\SmbURL.java   smb://scred/src/jcifs/SmbURL.java

   2.2.1.  Accessing the SMB Server Service

      When accessing the SMB server service, the server identifier must
      be specified in the URL.  An absolute SMB URL referencing an
      instance of the SMB server service takes one of the following
      general forms:

         smb://<smb_server>
         smb://<smb_server>/<share>
         smb://<smb_server>/<share>/<path>

      Relative URLs are also supported.

   2.2.2.  Accessing the Workgroup Browse Service

      The SMB URL form

         smb://

      represents the root of the SMB URL hierarchy.  It is used to
      indicate the set of available workgroups.  When presented with



Hertel                    Expires July 8, 2002                  [Page 4]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

      this form, an application will request a copy of the browse list
      from any browse server available on the local IP subnet.  The
      browse list contains a list of all workgroups available on the
      local subnet.  Only the set of workgroup names will be returned
      by the application.

      The SMB URL form

         smb://<workgroup>
      or smb://<workgroup>/

      is used to request a list of SMB servers that are members of the
      named workgroup.  When presented with this form, an application
      will request a copy of the browse list from a workgroup member
      browse server.  The application will return only the set of SMB
      server names that represent workgroup member servers.

      The workgroup browse service does not offer SMB shares.  If the
      share component is present (for example "smb://name/share"), then
      the server type must be interpreted to be an smb_server name.

   2.2.3  Workgroup Names vs. SMB Server Names

   The syntax of a workgroup identifier is a subset of the SMB
   fileserver syntax.  The two can only be distinguished semantically.
   Appendix C outlines a mechanism for determining the service type of a
   server name.

   In rare cases, a URL string may represent both a workgroup and an SMB
   fileserver.  If this happens, the application must determine which
   interpretation should be used.  If possible, an application SHOULD
   process both interpretations.  For example, consider a web browser
   which is presented with the SMB URL string "smb://nbname/".

   - If the name "nbname" is an SMB server name, the application will
     display a list of shares offered by the server.

   - If the name "nbname" is a workgroup name, the application will
     display a list of servers which are members of that workgroup.

   - If the name "nbname" is both an SMB server name and a workgroup
     name, then the application might display the list of workgroup
     member servers followed by the list of shares.  Applications may
     also choose to display only SMB server names, or an error message.

   NetBIOS names that represent both a workgroup and an SMB server are
   not common.  This situation typically represents a misconfigured SMB
   filesharing network (see [RFC1001], section 10).







Hertel                    Expires July 8, 2002                  [Page 5]


INTERNET-DRAFT                   SMB URL                 January 8, 2001


2.3. Relative SMB URLs

   Relative SMB URLs are permitted and are resolved according to the
   rules defined in [RFC2396] section 5.2.


2.4. Fragments

   URL fragment references are permitted if the SMB URL resolves to a
   file or file-like object for which fragments have meaning.  The
   fragment syntax is:

      smb://<smb_server>/<share>/<path>#<fragment>


2.5. Queries

   STD 19 transport implements the NetBIOS API over TCP/IP.  This
   layering requires special services to map between the NetBIOS and
   IP address spaces.  These services impose context.  For example, a
   given NetBIOS name may resolve to a different IP address depending
   upon the IP subnet within which it is used, or the designated
   NetBIOS Name Server (NBNS).

   URL queries are used to specify STD 19 context, and to provide a
   small set of additional features.  SMB URL queries take the form:

   ?<keyword>=<value>

   SMB URL queries are always interpreted by the client.

   The list below specifies the keywords that are defined for the SMB
   URL.  An implementation of the SMB URL may not add additional
   keywords, as doing so would break compatibility.

   NBNS     - DNS name or IP address of the NBNS to use for NetBIOS name
              resolution.

   WINS     - Synonym for NBNS (this name references a specific vendor
              implementation, but it has fallen into common usage).

   NBDD     - DNS name or IP address of the Datagram Distribution Server
              (NBDD) to use for datagram distribution.  (Few, if any,
              current implementations of STD 19 transport implement a
              working NBDD.  This keyword is included for completeness.)

   SCOPE    - Allows specification of the scope ID (see [RFC1001],
              section 9) when the server identifier field contains a DNS
              name or IP address instead of a NetBIOS name.  If
              specified, this query field will override any scope ID
              given in the server identifier field.



Hertel                    Expires July 8, 2002                  [Page 6]


INTERNET-DRAFT                   SMB URL                 January 8, 2001


   CALLNAME - When specifying a server by DNS name or IP address, it is
              sometimes necessary to also specify the "called name" (see
              [RFC1001], section 5.3).  This tag allows the NetBIOS
              called name to be included in the URL string.

   START    - If the URL string resolves to a file, this keyword allows
              specification of a byte offset into the file at which
              reading of the file is to start.  The default START value
              is, of course, zero (0).

   OFFSET   - Synonym for START.

   LENGTH   - If the URL string resolves to a file, this keyword allows
              specification of the maximum number of bytes to read.  The
              default LENGTH value is INFINITE (which means from START
              to end-of-file).

   [RFC2396] reserves the characters ";", "/", "?", ":", "@", "&", "=",
   "+", ",", and "$" within the query component.  These characters must
   be escaped for use within a value field.  The preferred separator is
   the semi-colon (";").  The equal sign ("=") may not be used to
   separate keyword/value pairs as it is used to separate the keyword
   from the value within such pairs.


2.6. Use of the 'port' Field

   STD 19 includes a mechanism for retargeting Session Service
   connections to alternate ports.  (See [RFC1001], section 16.1.1.)
   The URL port field may be used to specify an alternate service port,
   thus bypassing the STD 19 retargeting mechanism.


2.7. SMB over Native TCP/IP

   This document presents an SMB URL for use with SMB over STD 19
   transport.  Some servers now also support SMB over native TCP/IP
   without the intervening NetBIOS session layer.  The SMB URL SHOULD
   NOT be used to identify SMB services offered over native TCP/IP.

   Newer versions of the SMB protocol suite, including implementations
   of SMB over native TCP/IP, are called "Common Internet FileSystem"
   (CIFS) by Microsoft, though no Internet standard exists for this
   suite.  The URL scheme identifier "cifs:" is suggested for use with
   SMB over native TCP.  A description of such a scheme is beyond the
   scope of this document.








Hertel                    Expires July 8, 2002                  [Page 7]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

3. SMB Namespace

   As previously described, STD 19 provides a mechanism for implementing
   the NetBIOS API on top of TCP and UPD.  In doing so, these RFCs
   describe a NetBIOS Virtual LAN system.  The virtual NetBIOS LAN has
   its own addressing mechanism which is based on the use of NetBIOS
   "names".  These names do not map directly to DNS names, and must be
   encoded before they are used.  (See [RFC1001], section 14.)  Also
   note that the NetBIOS namespace is flat, unlike the hierarchical DNS
   namespace.

   In order to connect to an SMB service, a client must know the NetBIOS
   name (NetBIOS address) of that service.  This is a requirement of
   the STD 19 Session Request.  Many SMB implementations, however, allow
   the use of DNS names and/or IP address for identifying instances of
   the SMB server service.  The DNS name or IP address must be
   reverse-mapped to a NetBIOS service name in order to establish an SMB
   session.  A mechanism for performing this reverse-mapping is outlined
   in Appendix C.

   A NetBIOS Scope ID (see [RFC1001], section 9) is sometimes used to
   identify and separate virtual NetBIOS LANs from one another.  Scope
   IDs are identical in syntax to DNS domain names.

   In practice, it is not possible to determine whether a service
   identifier is an IP address, a DNS name, or a NetBIOS name by
   examining the syntax of the identifier string itself (see Appendix
   B).  The semantics of the service identifier must be used to
   determine its classification.  A mechanism for examining host
   identifier semantics is provided in Appendix C.


4. Authentication and Security Considerations

   SMB authentication can be categorized as follows:

      o None
      o Share-based
      o User-based
      o Authentication Server-based (NT Domain)

   The authentication mechanism to be used is negotiated during
   client/server session setup.  Client applications, therefore, are
   aware of the server's authentication requirements and may prompt for
   appropriate input (password, username, authentication domain).  By
   prompting for authentication information, an application ensures that
   such information is entered by the user in a controlled manner, and
   that security measures (if any) such as password encryption or
   password hash generation are applied by the SMB protocol handler
   before the data are transmitted.





Hertel                    Expires July 8, 2002                  [Page 8]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

   This specification also provides an authentication shorthand, though
   it does collide rather spectacularly with the warning in [RFC2396],
   section 3.2.2, which recommends against exactly this sort of thing.

   The shorthand mechanism takes the following general form:

      smb://<ntdomain>;<username>:<password>@<smb_srv_name>

   This allows the specification of:

      ntdomain - The authentication domain (single-signon database
                 server) to use for authorization
      username - User account identifier
      password - Password

   These fields are all optional (see section 7, below for more
   detailed syntax).

   This syntax is of particular use with command-line applications,
   batch scripts, configuration files, etc.  That is, any situation in
   which a multi-step exchange between a user and an application is
   awkward or impossible.

   It is recommended that application authors consider carefully the
   security implications of providing support for this form.  Likewise,
   authors of documentation in HTML or other formats are advised not to
   include authentication information in such documents, either within a
   URL string or otherwise.

   The workgroup specifier does not allow for, nor require,
   user authentication information.  Any SMB URL string which includes
   user authentication information should be interpreted as an SMB
   server reference.


5. SMB URL Examples

      smb://ubiqx
         -- Indicates either a workgroup or an SMB server (or both).
            The underlying application must resolve the name in order to
            determine the service type.

      smb://scred/src
         -- Indicates the share "src" on server "scred".

      smb://neko@scred/src/jcifs/smb/SmbURL.java
         -- Indicates file /jcifs/smb/SmbURL.java within the "src" share
            on node "scred".  The username "neko" is to be used when
            connecting to the share.






Hertel                    Expires July 8, 2002                  [Page 9]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

6. Character Encoding Issues

   The only restriction that STD 19 places on the octet values that may
   be used in a NetBIOS name is that the name may not begin with an
   asterisk ('*', ASCII value 0x2A).  No other values are listed as
   excluded in the RFCs.

   Octet values less than 128 (0x80) in a NetBIOS name are commonly
   interpreted as US-ASCII characters.  Unfortunately, there is no
   convention or best practice for octet values 128 and above.

   The SMB protocol also allows clients and servers to negotiate the use
   of Unicode in share and path names.  Once again, however, there is no
   standard character set for SMB communications and no mechanism for
   negotiating which character set is to be used between the client and
   server.  It is, therefore, not possible to know which character set
   to use on the wire.

   NetBIOS names, share names, and the directory paths and filenames
   offered by an SMB server may all contain characters from outside the
   7-bit US-ASCII character set.  Applications MUST support the use of
   the URL escape sequence as described in [RFC2396] to accommodate
   octet values that represent non-US-ASCII characters.  Applications
   which support extended character sets provide the end user with a
   means of hand-configuring compatible character sets.






























Hertel                    Expires July 8, 2002                 [Page 10]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

7. URL Syntax

   The SMB URL conforms to the BNF grammar given in Appendix A of
   [RFC2396] with the additions and modifications listed below.

      smb_URL       = ( SMB_absURL | SMB_relURL )
      smb_absURL    = "smb:" smb_srv_type
      smb_relURL    = ( smb_srv_type | smb_abs_path
                                     | smb_rel_path ) [ "?" query ]

      smb_srv_type  = "//" [ ( workgroup | smb_net_path ) ]

      workgroup     = nbtname
      smb_net_path  = smb_server [ smb_abs_path [ "#" fragment ] ]
      smb_abs_path  = abs_path [ "#" fragment ]
      smb_rel_path  = rel_path [ "#" fragment ]

      smb_server    = [ [ smb_userinfo "@" ] smb_srv_name [ ":" port ] ]

      smb_srv_name  = nbtname | hostname | IPv4address
      nbtname       = netbiosname scope
      netbiosname   = 1*( netbiosnamec ) *( netbiosnamec | "*" )
      netbiosnamec  = ( alphanum | escaped  | ":" | "=" | "+" | "$" |
                        "," | "-" | "_" | "!" | "~" | "'" | "(" | ")" )
      scope         = *( "." domainlabel ) [ "." ]

      smb_userinfo  = [ ntdomain ";" ] username [ ":" password ]
      ntdomain      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )
      username      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )
      password      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )

   Notes on the above syntax:

   - Workgroups must be identified by their NetBIOS name, and may not
     include a userinfo field.

   - URL fragments may only be used with respect to path elements.

   - The syntax of the query field, within the context of the SMB URL,
     is described in section 2.5, above.












Hertel                    Expires July 8, 2002                 [Page 11]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

8. Acknowledgements

   The creation of this document would not have been possible without
   the help and guidance of

   Michael B. Allen, jCIFS Team
   David Farmer, University of Minnesota OIT
   Steven French, IBM
   Richard Sharpe, Samba Team

   and the aggregate knowledge and wisdom of

   The Samba Team
   The jCIFS Team
   The Samba-TNG Team
   and the members of the samba-technical mailing list.


9. References

   [ONET]     Microsoft Corporation, Intel Corporation, "Microsoft
              Networks/OpenNET Filesharing Protocol", Document Version
              2, Intel Part No. 138446, November 7, 1988.

   [SNIACIFS] Storage Network Industry Association CIFS Documentation
              Work Group, "Common Internet File System (CIFS)", Draft
              0.9, March 2001.

   [RFC1001]  "Protocol Standard For a NetBIOS Service on a TCP/UDP
              Transport: Concepts and Methods", RFC 1001, March 1987.

   [RFC1002]  "Protocol Standard For a NetBIOS Service on a TCP/UDP
              Transport: Detailed Specifications", RFC 1002, March 1987.

   [RFC2396]  Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
              Resource Identifiers (URI): Generic Syntax", RFC 2396,
              August 1998.


10. Author's Address

    Christopher R. Hertel
    University of Minnesota
    Networking and Telecommunications
    2218 University Avenue SE
    Minneapolis, MN  55414-3029, USA

    E'mail: crh@samba.org
            crh@ubiqx.org






Hertel                    Expires July 8, 2002                 [Page 12]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

Appendix A.  SMB Implementation Resources

   As of the time of this writing, there is no standard specification
   for the SMB protocol.  An attempt was made to provide such a standard
   in 1996, when a draft specification was submitted to the IETF.  That
   draft have since expired, but the Storage Network Industry
   Association (SNIA) has recently developed a new document based upon
   the earlier work ([SNIACIFS]).  SNIA has plans to publish the new
   document once it has been accepted by SNIA members and interested
   third-parties.  It is not clear as of this writing whether the
   document will be considered a specification, or merely a technical
   reference.


Appendix B. Service Identifier Syntax Comparison

   Based on syntax alone, is not possible to determine which type of
   service identifier is represented by the string "10.109.73.4".  It
   could be:

     - an IP address:  10.109.73.4
     - a DNS name:     10.109.73.4.ubiqx.org
     - a NetBIOS name: 10, with scope ID "109.73.4"

   Similarly, the host identifier "scred.ubiqx.org" could be read as
   either a DNS name or as NetBIOS node "scred" within scope
   "ubiqx.org".

   In order to determine the semantics of a service identifier the DNS
   service, the STD 19 name service, or the STD 19 session service must
   be consulted.  Appendix C provides mechanisms for determining service
   identifier semantics.

   Appendix A of [RFC2396] provides a BNF grammar which accepts both DNS
   names and IPv4 addresses.  Section 7 of this document provides a
   grammar for STD 19 NetBIOS names.


Appendix C.  Working with NetBIOS Names (Implementation Notes)

   The information presented in this section is intended as a guide for
   implementors.  This information is not directly relevant to the
   syntax or semantics of the SMB URL scheme itself.  The mechanism
   described below are derived from observation of existing
   implementations.  The author should not be blamed.

   NetBIOS names are addresses.  They represent communication end-points
   within a NetBIOS LAN.  [RFC1001] and [RFC1002] provide a mechanism
   for creating virtual NetBIOS LANs over TCP and UDP transport.  Part
   of that mechanism is the NetBIOS name service, which provides for
   mapping between NetBIOS names and IP addresses.  A given host system
   may register several NetBIOS names, each representing an application



Hertel                    Expires July 8, 2002                 [Page 13]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

   or service that can communicate with other applications or services
   via the NetBIOS API.

   SMB sessions are established and messages transferred via the NetBIOS
   session service (see [RFC[1001], section 5.3 and [RFC1002] section
   4.3). The system that originates the connection is the "calling"
   node, and the target node is the "called" node.  In order to
   establish an SMB session, a TCP connection must be established
   between the calling and called nodes.  If a TCP connection already
   exists, the SMB session may make use of the existing connection.

   Before a NetBIOS session can be established, the calling node must
   discover the IP address of the called node.  This is done using the
   NetBIOS name service (see [RFC1001] section 5.2 and [RFC1002] section
   4.2).  NetBIOS names are always 16 octets, padded with spaces (0x20)
   if necessary, as specified in the RFCs.  By convention, however, the
   16th octet is reserved for use as a service type indicator.  This
   field is known as the "suffix".

   The suffix is NEVER specified in an SMB URL string, but is appended
   by the implementation.

C.1.  Resolving DNS names and IP addresses to SMB server names.

   The NetBIOS session service requires that the client provide the
   NetBIOS names of both the calling and called nodes.  When connecting
   to an SMB server, the calling name is the default NetBIOS name of the
   client, space padded as described, with a suffix byte value of 0x00.
   The called name is the NetBIOS name of the server with a suffix byte
   value of 0x20.

   Applications which support the SMB URL SHOULD include support for the
   use of DNS names or IP addresses in addition to NetBIOS names when
   initiating SMB connections via NetBIOS over TCP/IP transport.  This
   functionality is an extension to the NetBIOS over TCP/IP behavior
   specified in RFC 1001 and RFC 1002, and is not part of that standard.
   It is, however, a common extension and should be supported for
   compatibility reasons, and to provide access to SMB shares in
   situations in which the NetBIOS name space cannot be guaranteed to be
   consistent.

   As stated above, the Session Request packet requires a called and a
   calling name, both of which are NetBIOS names.  In order to create a
   Session Request packet, the DNS name or IP address of the server must
   be reverse-mapped to the server's NetBIOS name.  Mechanisms for doing
   so include:

   -- Issuing a NetBIOS Adapter Status Query

      A NetBIOS Adapter Status Query is sent to the target IP address.
      (See [RFC1001] section 15.1.4 and [RFC1002] sections 4.2.17 &
      4.2.18.)  If a response is received, and if the target node is



Hertel                    Expires July 8, 2002                 [Page 14]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

      running an SMB server service, then the response will include a
      NetBIOS name with a suffix byte value of 0x20.  This NetBIOS name
      may be used as the called name in a Session Request packet.

      It is possible, though rare, that multiple entries will have a
      suffix byte of 0x20.  If this is the case, one of the other
      methods must be used to discover the SMB server service.

   -- Generic Server Name

      This method is not supported by all SMB server implementations.

      Some SMB servers will accept the generic SMB server name
      "*SMBSERVER".  A client can simply use the name "*SMBSERVER" as
      the called name in a Session Request packet.  As with all SMB
      server NetBIOS names, the "*SMBSERVER"  name must be space padded
      and terminated with a suffix byte value of 0x20.

      The "*SMBSERVER" is an illegal NetBIOS name (see [RFC1001],
      section 5.2), so it is never registered with the NetBIOS name
      service and will not be returned in a NetBIOS Adapter Status
      Response.

      If the target does not support the "*SMBSERVER" generic name, or
      if it is not running SMB services, it will return a CALLED NAME
      NOT PRESENT error.

   -- Parsing the DNS Name or IP address (guessing)

      This is the least reliable method for discovering an SMB server
      name.

      Systems which support STD 19 transport will often use the same
      base name within the DNS and NetBIOS name spaces.  Thus, the first
      label of the DNS name is a good guess at the NetBIOS name of the
      target.  If the input is an IP address rather than a DNS name, the
      a reverse lookup against the DNS MAY be performed to determine the
      DNS name.

      The first label of the DNS name consists of the initial portion of
      the DNS name string up to but not including the first dot
      character ('.').  If the label is greater than 15 bytes in length,
      it is not likely to be a NetBIOS name.  It may, however, be
      truncated to 15 bytes.  The result is then space padded to a total
      of 15 bytes, and a suffix value 0x20 is added.  This forms a valid
      NetBIOS name that may be used as a called name in a Session
      Request packet.

      If the target returns a CALLED NAME NOT PRESENT error, then the
      DNS name guess is incorrect.

      It is difficult, syntactically, to determine whether a given



Hertel                    Expires July 8, 2002                 [Page 15]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

      string is a DNS name or an IP address.  Some existing applications
      will interpret the decimal string representation of the first
      octet of an IP address as if it were a DNS label.  For example,
      given the string "192.168.101.1" some applications try using "192"
      as the called name (padded, and with the 0x20 suffix, as described
      above).  This behavior is acceptable.

   Any or all of the above MAY be tried in any order.

C.2.  Determining Server Specifier Type

   NetBIOS names, DNS names, and IP addresses can not be easily
   distinguished syntactically.  For example, the string "192.168.101.1"
   might be an IP address, but it is also a valid NetBIOS name and may
   even be a valid partially qualified DNS name.  The appropriate
   mechanism for distinguishing between these server specifier types is
   the trial-and-error method.

   Implementations SHOULD begin with the assumption that the specifier
   is a NetBIOS name.  The following process is used to test this
   assumption:

      If the name string contains dot characters ('.', ASCII 0x2E), then
      separate the name into NetBIOS name and Scope ID at the first dot.

      REPEAT

        If the resulting NetBIOS name is greater than 15 octets in
        length, then the name is not a NetBIOS name.  Exit, indicating
        failure.

        Issue an STD 19 Name Query using the NetBIOS name and Scope ID.
        A suffix value of 0x20 or 0x1D must be used.  Both values may be
        used.  See section C.3.

        If a Positive Name Query Response is received, then the name is
        a NetBIOS name.  Exit, indicating success and returning the
        NetBIOS name and scope ID as parsed.

        Find the next dot character in the original string and
        re-separate the string at that dot.

      END

   Note that the empty string is a valid Scope ID.

   If the server specifier is not a NetBIOS name, then it is either a
   DNS name or an IP address.  These are semantically equivalent.







Hertel                    Expires July 8, 2002                 [Page 16]


INTERNET-DRAFT                   SMB URL                 January 8, 2001

C.3. Workgroup vs. SMB Server Names

   If the URL string is of the form

     smb://<server>/

   then the server field may represent either an SMB server name or a
   workgroup name.  The name MUST NOT be interpreted as a workgroup name
   if:

      -- Authentication information is present in the server field.

         This is because null authentication is used when requesting a
         browse list.

      -- The server field is entered as a DNS name or an IP address.

         This is because workgroups, conceptually, represent a group of
         servers rather than an individual server and the browse list
         may be retrieved from one or more browse servers.  (A workgroup
         name is a NetBIOS group name.)

   In these cases, the server name is interpreted as a reference to an
   SMB server only.  Thus, workgroups may only be accessed via their
   NetBIOS names.

   When testing the name using the algorithm presented in section C.2, a
   NetBIOS name suffix value of 0x20 is used to find an SMB server, and
   a suffix value of 0x1D is used to find a workgroup browse server.


























Hertel                    Expires July 8, 2002                 [Page 17]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/