I am just starting to implement the routines to do directory listings, and want to be able to support a model that allows the user to list all workgroups on the network, all servers in a workgroup, all shares on a server and so on.

We are working with a URI style syntax, and I wanted to propose the following:

smb: means list all workgroups on current network

smb:wg// means list all servers in workgroup wg

smb:// means list all servers in your workgroup (as defined in $USER/.smb/smb.conf

smb:[wg]//server means list all shares in server [in wg]

smb:[wg]//server/share means list all directories at top level of share on server [in wg]

smb:[wg]//server/share/path means list all directories in path in share on server [in wg]

Does anyone have any comments on this ...

.... The main difference is (as you can see) that the workgroup shows up after the // in the URI, which IMHO is a bit more "standard" and follows the recommended stuff for the file: scheme.

Yes, it is important to differentiate. If you support specifying a workgroup, it needs to be done separately from the specification of the domain. Effectively, 'domain\user' is the username you're using for authentication. What if a user wishes to browse workgroup2, using his credentials from domain1? This should be allowed, and with inter-domain trust relationships it may even be necessary.

A browse list can be thought of as a directory. It's not much different. The hierarchy would be:

Not unreasonable. That would give us something like:

smb://workgroup/[user[:password]@]host[.domain][:port]/[directory/[subdir/]][file]

where workgroup is either a workgroup or ntdomain, and calling up

smb://

would call up the list of available workgroups/ntdomains, and

smb://workgroup/

would provide the browse list of a specific workgroup/domain, etc.

Yes, I like this idea and I think eveyone else does too. The basic syntax that you have outlined is the right track. Here, I believe, are the problems that need to be resolved:

- Trust relationships. If the ntdomain of the service is different than the user's authentication ntdomain, how do we specify both? Do we need to specify both? Given:

smb://user:password@domain/server/share/path/file

The domain field would be the authentication ntdomain, since it is associated (via the @) to the user:password. As I think of it, since the server name must be unique (even if an IP address or DNS name is used) it does not matter which ntdomain the server is in. This may work without having to specify the ntdomain of a server. Can you connect to a server in a workgroup or ntdomain without specifying your own workgroup or ntdomain? I don't know enough about smb authentication...

- DNS & IP vs NetBIOS naming. The /server/ portion should allow for an IP address, a DNS name, or a NetBIOS name. If the latter, then don't forget scope. The trick here is one of knowing how to resolve the name. It could get messy.

- If the auth field (/user:password@domain/) is missing, can software be written to prompt for the missing information?

- Which subfields of the auth field are optional? Can you type /user@domain/ and be prompted for a password (if one is needed)? Is the domain itself required?

I tend to agree with you that browsing shouldn't necessarily be crammed into the same URI as smb filesharing access. For one thing, browselists don't *use* SMB. :) Unless I'm mistaken, browse lists are assembled and displayed to the client using only ports 137 and 138, and no SMB packets are ever sent. So in this sense, I do think it's a bit silly to make these browse lists available in an smb:// URL. Consensus seems to be moving toward overloading the <server> portion of the URL to represent the workgroup as needed, but I think the ambiguities this introduces, and the complexity of the additional code for resolving these ambiguities, are still a strong deterrent to this approach. We're still a long way from even reaching consensus about *how* the ambiguity should be resolved. Give precedence to a workgroup? Give precedence to a server? Let the application programmer sort it out? Display both to the user and let him decide? All of these approaches have some merit, but I think a URL which is unambiguous in the first place has more merit than any other approach.

Does there need to be a way to textually access the browse list for a workgroup? Yes. Does it need to be a url beginning with `smb://'? I don't think it does. It would be nice if typing smb:// could take us straight to a list of servers (or of workgroups? Another choice to be made :), but I don't think this feature's important enough that we should tolerate ambiguous URLs.

So the question is, can browsing be defined as a funtion of the smb protocol? Now that I have put some thaught into it beyond the quick replies earlier, I would have to say, yes. Because smb w/o netbios is no longer smb, but rather CIFS. So if SMB is specific to the netbios service, then it's probably acceptable to say that workgroup browsing is part of SMB. So with that, I reject my previous comments, and position on the use of nmb:// or nbbs://, becase netbios is required by SMB, so it would not be wrong to wrap it up into one overloaded protocol. Afterall, we don't use a dns:// protocol to browse dns zones....

Technically, browsing is built on top of the nbt (NetBIOS over TCP/IP) protocol. It uses the NetBIOS Name Service and the NetBIOS Datagram Service. It does not use either the NetBIOS Session Service or SMB. That is why reading a browse list is essentially an overloading of the smb:// URI.

Yes, and an interesting conversation. These issues are certainly not obvious and do require careful thought. What a long, strange thread it's been.

Ugh. We can't very well make that the URI syntax.

Since both the workgroup and the scope could potentially contain anything at all, there is no possible way to really tell them apart. (Who thought that up?) Given the situation, I think Chris mentioned the only viable solution: Demand a specific character be escaped if used in the workgroup or scope name. Since NT is already starting to sing a different tune when it sees a ".", that may be the best nominee for the job.

Just to summarize, I think that leaves two syntaxes:

(broswing) smb://[workgroup[.scope]]/

(specific) smb://[[domain;]user[:password]@]server/[share/[path/][file]]

With the understanding that 'server' here can be one of '<netbios_name>[.<scope>]', '<host>[.domain]', or '<ip_addr>', tested in that order, yes.

The server name also needs to have a scope, as in:

smb://[[domain;]user[:password]@]server[.scope]/[share/[path/][file]]

This is nasty but true. As with any NetBIOS name, the name exists *within* a scope, so the scope must be specified. In the above, the first step will be to use the NetBIOS Name Service to resolve the server name to an IP address so that packets may be sent. We need to send to the correct IP address, of course.

Bonus points to those who can tell me where the quote comes from.

NOTE: This document is not the last word on this subject, but I will try to update it in light of discussions. It does, however, represent my reasoning on the subject and reflects what I have gained from the discussion that went on.

There has been much discussion about the issues of browsing and directory listing in the libsmbclient library, and I wanted to progress this some more, and to lay out what I see as the important parts.

Firstly, however, some clarification on browsing.

Browsing involves a complex series of activities and protocols.

On the server side, the NBNS and NBDS are used to register browsing related names, distribute server and workgroup announcements, and manage the election of master browsers and backup browsers, etc.

On the client side, however, a broadcast request is sent to the local master browser NetBIOS name via an IP broadcast to retrieve the backup browser list, but after that, Lan Manager requests, like NetServerEnum and NetShareEnum requests are made after connecting to the IPC$ share on the browse server.

Indeed, even when you want to see all the domains/workgroups on a network, a client connects to a backup browser [I think] and sends a NetServerEnum request on the IPC$ share with a server type of 0x00000000, which causes Samba, and I assume NT servers, to list the workgroups/domains it knows about (their NetBIOS names only).

Now, my main concern is whether browsing can or should be unified with directory listing. A second question is: What should be the form of the URI used to convey all the required information, both when accessing files but also when browsing.

However, before doing that, let me say that there is little doubt that browing a single workgroup should be unified with directory listing; it is the presence of workgroups/domains that raise problems.

A very clear approach is:

smb:// means list all servers in the current workgroup.

smb://server/ means list all shares on server.

smb://server/share means list all directories in share on server.

and so on.

This has the advantage that it conforms to people'e expectations of how UNCs behave and how URLs behave. The disadvantage is that workgroups/domains from a browsing perspective do not have a natural place in this scheme, and they cannot be easily shoehorned in.

As an aside, we should conform to RFC2396 and its URI syntax. This leads to a very natural addition of authentication information, as RFC2396 provides for 'userinfo', and provides a natural mechanism for specifying a username and password, although it cautions against passing such information over the wire [see below for comments on security].

A more complete form of the syntax, then might be:

smb://[userinfo@][server[:port]][/share[/path[/file]]]

where <userinfo> could be:

[user[:password]]

A remaining question, though, is how can the domain (NT domain, that is) of authentication be indicated in the above <userinfo>. RFC2396 seems to only allow us a few remaining characters (';', ':', '&', '=', '+', '$', ',') or we must escape the character we use to mark the presence of a domain in which the authentication information is relevant.

Unless I have misinterpreted RFC2396, my suggestions would be:

[user[;domain][:password]]

or

[user[+domain][:password]]

But I am open to suggestions.

Finally, however, the issue of workgroups/domains intrudes. These would be most naturally accomodated by supplanting the server down one level, eg:

smb://[userinfo@][workgroup[/server[/share[/path[/file]]]]]

but this seems unnatural and the objection can be made that DNS-style domains are not browsed in this way with a normal URI, other mechanisms must be used to obtain the relevant list of domains.

Thus, my preference now is to exclude workgroups/domains from the URI syntax, and to use the URI syntax listed above, but I am prepared to listen to argument.

I would like to provide additional routines to list workgroups, but this itself may require the provision of authentication information, as the process of listing the workgroups requires a connection (NetBT) to the backup browser, and a TCON to the IPC$ share. This may require a SessionSetup&X with a valid username and password pair.

An open question at this stage is whether or not this authentication information should be provided using the callback facility already provided, or whether or not they should be passed in via parameters.

A NOTE ON NETBIOS NAMES

NetBIOS names are becoming increasingly obsolete. They are only required by older Microsoft OSes. Samba does not care about NetBIOS names (but does use them for virtual servers), and NT 4.0 (I believe) and certaily Win2000 allows the use of *SMBSERVER as the called name.

Thus, <server> should be allowed to be a DNS name, with CALLED names being set to *SMBSERVER, or the first component of the DNS name, or perhaps with each being tried in turn.

COMMENTS ON SECURITY

There would appear to be less of a security issue, in that these URIs will not be passed over the wire; they are for specification to the library, which will pull them apart and use the appropriate pieces where needed. If the server supports 'encrypted' passwords, then that will be used.

However, the embedding of authentication information in URIs may lead to harvesting of this information from memory and command lines, so care must be taken here.

Caldera has commissioned the development of a Samba client library that will allow Linux and UNIX programs to be written to access resources on SMB servers. The clear goal is to allow the development of applications like the Windows explorer that allow users to browse resources on Linux/UNIX systems as well as SMB servers of all types.

There has been much discussion about the issues of browsing and directory listing in the libsmbclient library, and things are starting to solidify now. This document sets out the resolution of the discussion, and represents what will be developed in libsmbclient.

Firstly, however, some clarification on browsing under Windows.

Browsing involves a complex series of activities and protocols (More details can be found in Special Edition, Using Samba and Ethereal dissects many of the SMB calls used to implement browsing).

On the server side, the NBNS and NBDS are used to register browsing related names, distribute server and workgroup announcements, and manage the election of master browsers and backup browsers, etc.

On the client side, however, a broadcast request is sent to the local master browser NetBIOS name via an IP broadcast to retrieve the backup browser list, but after that, Lan Manager requests, like NetServerEnum and NetShareEnum requests are made after connecting to the IPC$ share on the browse server.

Indeed, even when you want to see all the domains/workgroups on a network, a client connects to a backup browser and sends a NetServerEnum2 request on the IPC$ share with a server type of 0x00000000, which causes Samba, and I assume NT servers, to list the workgroups/domains it knows about (their NetBIOS names only).

A clear desire with libsmbclient is to be able support browsing as well as access to resources on servers. The question is, whether browsing of workgroups and servers can be unified with browsing of shares and directories on servers. If this can be achieved, a single interface can be provided to users of the libsmbclient library.

By noting that browsing the workgroups on a network is implemented in exactly the same way as browsing the servers in a workgroup, and that workgroup and server names are disjoint, we can unify the browsing of workgroups and servers on a network.

A very clear approach is:

This has the advantage that it conforms to people'e expectations of how UNCs behave and how URLs behave, and we get to unify workgroup and server browsing with directory listings.

As an aside, we should conform to RFC2396 and its URI syntax. This leads to a very natural addition of authentication information, as RFC2396 provides for 'userinfo', and provides a natural mechanism for specifying a username and password, although it cautions against passing such information over the wire [see below for comments on security].

A more complete form of the syntax, then might be:

smb://[[userinfo@]server[:port]][/share[/path[/file]]]

where <userinfo> could be:

[user[:password]]

A remaining question, though, is how can the domain (NT domain, that is) of authentication be indicated in the above <userinfo>. RFC2396 seems to only allow us a few remaining characters (';', ':', '&', '=', '+', '$', ',') or we must escape the character we use to mark the presence of a domain in which the authentication information is relevant.

The consensus from the list is that the best syntax for <userinfo> is

[[domain;]user[:password]]

While libsmbclient has a callback to allow authentication information to be retrieved from the caller, any <userinfo> passed in via the URI may override that provided via the callback.

The intention is that the smbc_opendir routine would be passed a URI formatted as above, and it would perform the appropriate operations to retrieve a browse-list or directory listing. Subsequent calls to smbc_readdir would return the next object in the list. Clearly, with each dirent returned, there will need to be an indication of the type of object returned as well.

A NOTE ON NETBIOS NAMES

NetBIOS names are becoming increasingly obsolete. They are only required by older Microsoft OSes. Samba does not care about NetBIOS names (but does use them for virtual servers), and NT 4.0 (I believe) and certaily Win2000 allows the use of *SMBSERVER as the called name.

Thus, <server> should be allowed to be a DNS name, with CALLED names being set to *SMBSERVER, or the first component of the DNS name, or perhaps with each being tried in turn.

However, browsing of workgroups and servers is all based around NetBIOS names, so until something like Active Directory is implemented, NetBIOS names will have to be used.

COMMENTS ON SECURITY

There would appear to be less of a security issue, in that these URIs will not be passed over the wire; they are for specification to the library, which will pull them apart and use the appropriate pieces where needed. If the server supports 'encrypted' passwords, then that will be used.

However, the embedding of authentication information in URIs may lead to harvesting of this information from memory and command lines, so care must be taken here.

ACKNOWLEDGMENTS

A number of people have made suggestions and criticisms that have been incorporated into this document. I would like to thank Chris Hertel, Michael Sweet, Michael Allen, Steve Langasek, Simo Sorce and Kevin Colby. Please accept my apologies if I have missed your contribution.

Don't forget to convert from UNIX character set to dos codepage on entry/exit to the libsmbclient functions. This took a *lot* of work to get right in previous versions of the code and needs to be maintained.

With the success of getting a win2k sp1 machine to join a samba 2.2 PDC I decided to try and build a rpm of samba so I could distribute it to my other servers with ease. I immediately ran into problems as soon as I got the custom rpm installed and configured for my PDC machine. When I first tried to join the machine to the domain I got a message of "the credential supplied conflict with a existing set of credentials" which it happened that the workgroup name I was using was the same as the domain I was trying to join. So I changed the workgroup name rebooted and tried again, which did solve the credentials problem.

The next time I got a message of "The following error occurred attempting to join the domain 'MY_DOM': The procedure number is out of range". I recompiled the rpms several times and each time changing the configure options until I had the same options the first time I got it to work. Needless to say after several hours I could not get that message to go away.

I then decided to look over the smb.conf file, which this is where I struck pay dirt. When I first started I had included the option "unix password sync = yes" so I could sync my unix passwords with my smb passwords. Well when I disabled that option I was able to join the domain just like before, without the procedure out of range message.

So apparently if you include the "unix password sync = yes" then you will receive the procedure out of range message when trying to join the machine to the domain.

If anyone is interested I have samba 2.2 "1/3/2001 cvs" version rpms and the source rpm on my home machines. They are compiled against redhat 7.0. Here is the location http://www.firerun.net/pub/i386/samba

OK, I found the problem ... A disconnect between my sources and the CVS sources meant that I uploaded an incorrect proto.h.

I am fixing now, but you can always do a 'make proto'.