Yet Another SMB URL Syntax

Christopher R. Hertel crh at
Mon Apr 9 18:12:59 GMT 2001

"Michael B. Allen" wrote:
> Chris and friends have had a little side discussion on the SMB URL
> syntax;
> he is writing an IETF draft on the topic. During the course of things
> I thought workgroups might be handled differently so I scribbled down
> yet another scheme. It is not really that different from what has been
> discussed previously on this list, except in how workgroups are handled;
> smb:// lists servers of a 'preferred workgroup' and 'smb://..' lists
> all available workgroups. Chris didn't have much to say about it and I'm
> not sure what I think but it seems to make good sense so I am submitting
> it here for comments.

Chris has been desperately trying to keep up with his workload.  Your ideas
deserved a lot more of my attention but I noticed some time this weekend
that my brain was doing a whole heck of a lot of page faulting.  Fwoob.

> BTW: The jCIFS project has implemented the *previously described* SMB
> URL syntax in full. The SmbShell example program that comes with the
> jcifs-0.5dev1 archive allows one to 'cd' around workgroups, shares,
> and servers. Kinda neat, requires Java 2.

I hope people will start to play with this rev soon.

> Yet Another SMB URL Syntax
> The semantics of using workgroups within an smb:// URL is
> problematic. There's no doubt about that. The tragedy is that workgroups
> are rarely used in this context; they are only useful for "browsing"
> with shell interfaces. And yet we must corrupt the URL syntax and our
> code to support it. For this reason I would like to purpose yet another
> smb:// URL syntax.

Quick comments.  The only use of the browse list of which I am aware is the
Network Neighborhood icon on Windows boxes.  I am sure that there are
others, but I have not stumbled across them.  Anyway, my sense is that
workgroups are most commonly used in a graphical environment.  The SMB URL
scheme will make it easier to use workgroups in a text-based shell, but I
still see them used in things like web browsers.

Regarding the problematic characteristics of adding workgroup browsing
support to the URL.  Yes, absolutely.  If the SMB URL handled only SMB
servers, shares, and paths there would be no problem.  In fact, the SMB
URL maps pretty nicely to the DOS UNC format:

  UNC FORM                     URL FORM
  \\server\share               smb://server/share
  \\server\share\dirpath       smb://server/share/dirpath
  \\server\share\dirpath\file  smb://server/share/dirpath/file

Not bad.  The SMB URL also adds the form smb://server/ to identify an SMB
server...and this is a key point.  If the server field contains an SMB
Server Service name, then smb://server/ clearly indicates that SMB server.
The utility of this form is to request a list of shares from the SMB Server

> The key principle is to push the handling of workgroups out of the
> scheme as much as possible by shifting the meaning of components up
> the hierarchy but in a way that still provides for the listing of all
> available workgroups. This is accomplished by, at first conceptually,
> stating clearly that there are *two* separate scheme levels; one to
> support the most common and intuitive usage, and the other to add support
> for workgroups.

In other words, we want to overload the SMB URL scheme.  In addition to
using the SMB URL scheme to identify Server Service servers, shares, and
paths we also want it to be able to use it to access the browser service.
This allows us to retrieve the browse list.  Note that there are two levels
within the browse list.  There is the list of all workgroups available on
the local LAN, and there is the list of all servers available within a

Mike's point, if I may be so bold, is that this overloading of the SMB URL
syntax is problematic and that one way to handle the problems that come up
is to try and separate the Server Service and the Browser Service
syntactically within the URL scheme.

More on this below.

> The Level 1 Scheme
> The level 1 scheme accommodates the most common usage of smb:// URLs
> which would be within configuration files, as an argument to a program,
> or similar to address an SMB resource.
> Level 1 Syntax:
> smb://[[domain;]username[:password]@]server/share/path
> This simple syntax would support most users needs. However, it is
> widely anticipated that the ability to enumerate files and even shares
> of a server should be enabled by making the path and share components
> optional. Thus we just add brackets to get:
> smb://[[domain;]username[:password]@]server[/share[/path]]
> As a result of leaving off these components the following would:
> smb://server          enumerate shares
> smb://server/share    enumerate directories and files
> One major problem with supporting workgroups is shell oriented behavior
> and the semantics of relative URL manipulation. For example one might
> traverse the resource hierarchy like:
> smb://server       + share --> smb://server/share
> smb://server/share + path  --> smb://server/share/path
> and back up with:
> smb://server/share/path + .. --> smb://server/share
> smb://server/share      + .. --> smb://server
> smb://server            + .. --> smb://server
> Note this last traversal would reach the root because smb:// alone is
> an illegal level 1 scheme URL.

Agreed, basically, though I note that if I type the string


into my web browser the server sends back an error message.  Thus, in
  http://server + .. --> http://
which results in an error.  Minor point.

Note that Mike's Level 1 represents URL representation of the Server
Service.  Level 2, below, is his method for adding workgroup support to the

> The Level 2 Scheme
> The level 2 smb:// URL scheme provides for the usage of workgroups to
> list the servers of a workgroup and all accessible workgroups of the
> network (much like the popular "Network Neighborhood" shell interface
> does). To ease the transition from the level 1 scheme to the level 2
> scheme a hidden 'workgroup' parameter is employed. This parameter may
> be NULL or it may be initialized to the hosts preferred workgroup.
> Level 2 Syntax:
> The level 2 syntax is broken into two specifications to improve
> readability and emphasize the separation of workgroups from the level
> 1 scheme. This first specification looks much like the level 1 syntax
> however makes the server component optional.
> smb://[[[domain;]username[:password]@]server[/share[/path]]]
> Leaving off components now has the following behavior:
> smb://server          enumerate shares
> smb://                enumerate servers of the preferred workgroup
> The second specification is simply:
> smb://[workgroup]
> Notice this overloads the server component (programmatically this requires
> querying for both the 0x20 and 0x1D names, preferably concurrently,
> to determine if the component is a server or a workgroup). This usage
> of workgroup should:
> smb://workgroup       enumerate servers of the workgroup
> This begs the question of how to enumerate all available workgroups? The
> answer is:
> smb://..
> So the problematic listing of workgroups has been pushed out of the
> equation above the root of the URL hierarchy effectively shifting
> everything up to be more congruent with traditional URL semantics. Notice
> smb:// more naturally lists servers of the preferred workgroup rather
> than workgroups. To be complete, if the preferred workgroup property is
> NULL, both smb://.. and smb:// will list all available workgroups.
> Traversing the level 2 scheme hierarchy is as follows:
> smb://          + server    --> smb://server
> smb://          + workgroup --> smb://workgroup
> smb://workgroup + server    --> smb://server
> smb://server    + share     --> smb://server/share
> and back up with:
> smb://server/share + .. --> smb://server
> smb://server       + .. --> smb://
> smb://             + .. --> smb://.. -canonicalize-> smb://
> Notice this last case is contextual. It is determined during
> canonicalization that the intention is to list all available
> workgroups. In this way the smb://.. URL reduces to the case as well.

Okay here's how it boils down...

The *only* real differences between Mike's proposal and the one that we came
up with last January is the use of default (preferred) workgroup.

In the original scheme, the form


indicated the root of the hierarchy and, therefore, would be used to request
a list of available workgroups.  Also, as in Mike's scheme, the


would be used to list the servers in the specified workgroup.

In Mike's scheme, the forms


would be used to indicate the default workgroup and the list of all
workgroups, respectively.

I think that this syntax is more complex than the original.  Here's why:

- If the default (preferred) workgroup is NULL, then the smb:// form
  either has no meaning or reverts to meaning the list of all workgroups.
  This seems inconsistent.

- The form smb://.. may be pre-parsed by existing URL parsing code.  As
  a result, the underlying SMB implementation (in, say, a web browser
  or other software that deals with multiple URL types) may not get the
  original string.  The string "smb://.." would likely be converted to
  "smb://", for example.

- Using the definitions in RFC 2396, the form "smb://" is an "absolute"
  URL.  It is also the root of the SMB URL hierarchy.  Thus, I believe
  that the correct interpretation of "smb://" is as the root of the SMB
  server space.  I personally feel that the root of the SMB server space
  should be the list of all workgroups, rather than a preferred workgroup.

- None of this precludes the use of a user-configurable preferred
  workgroup.  Applications can use the preferred workgroup as a default
  starting place, much as web browsers use the "home" page as a default
  starting place.  The Network Neighborhood also uses the local system's
  workgroup as a default starting place for workgroup browsing.

Chris -)-----

Samba Team --     -)-----   Christopher R. Hertel
jCIFS Team --   -)-----   ubiqx development, uninq.
ubiqx Team --     -)-----   crh at

More information about the samba-technical mailing list