CIFS client updates for auto-reconnect [PSARC/2009/366 FastTrack timeout 06/24/2009]

[Jordan Brown]

Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 CIFS client updates for auto-reconnect
    1.2. Name of Document Author/Supplier:
	 Author:  Gordon Ross
    1.3  Date of This Document:
	17 June, 2009
4. Technical Description

1. Technical Description

    CIFS client updates for auto-reconnect.

2. Details
    2.1 Background and motivation

    The Solaris CIFS Client [PSARC 2005/695] provides the ability to
    mount SMB shares from Windows-compatible servers on Solaris.

    Server Message Block (SMB) is the preferred name of the protocol
    used for Windows-compatible file sharing.  The rest of this text
    uses SMB in place of CIFS.

    As currently implemented, the SMB client performs connection
    setup in the context of user commands (smbutil or mount_smbfs)
    that first asks for a connection, and keeps that connection in
    the SMB client kernel module (nsmb).  There is nothing in
    place to arrange for automatic reconnection if and when the
    server drops that connection.  See [CR 6587713].

    2.2 New or changed features

    This case proposes to add a new helper program to initiate
    reconnection when needed, installed as: /usr/lib/smbfs/smbiod
    (IOD is short for I/O Deamon, a name that comes from the
    original BSD/Darwin code used in the SMB client.)

    An smbiod process is started by one of the SMB client user
    commands (smbutil or mount_smbfs), and continues to run until
    that user no longer has any SMB client connections.  There
    will be one smbiod process for each user that has SMB client
    connections. [Note 1]

    Each smbiod processes instantiates a door service on the file
    "/tmp/.smbiod-%d" where %d is the owning Unix user ID, or the
    file "/var/run/smbiod-0" when the owner is UID zero.  The door
    file name is first unlinked, and then created with mode 600 to
    prevent use by other users.  The create is done via open with
    the O_CREAT|O_EXCL flags to prevent unintentionally opening
    something unexpected (i.e. symlink attacks).  If the unlink
    or create fails, smbiod exits with an error.

    Once running, smbiod accepts door calls asking it to make new
    connections.  Such door calls provide the server IP address
    and authentication information needed for initiating or
    re-creating a connection to a server.  Once the connection to
    the server is up, smbiod calls the "nsmb" driver via
    ioctl, becoming the IOD service thread for that connection.
    If and when a connection is dropped, the driver waits for
    other threads to request use of the connection, returns to the
    user-level smbiod to re-create the connection, and enters the
    driver again.  If a reconnection attempt fails for a temporary
    reason, the thread sleeps for 5 seconds before allowing
    requests to trigger another attempt.  If a reconnection
    attempt fails for some permanent reason (i.e. authentication
    info. no longer valid) the IOD thread exits, and attempts to
    use that connection will get the ENOTCONN error.  Such
    connections can be revived by running smbutil (or mount_smbfs)
    with new authentication information.  When a connection in
    driver loses all its references, the IOD thread returns to
    smbiod and destroys the connection.  When smbiod drops its
    last connection, it waits 15 seconds, and if no new
    connections are requested during that time, it deletes the
    door and exits.

    The new smbiod program is part of the SUNWsmbfsu package,
    along with all the other SMB client binaries.

    No direct user interface is provided by smbiod.

3. Interface table
    (no change)

4. Documentation

    New manual page smbiod(1M) describing what "smbiod" is and does,
    based on the above text.  Probably similar to nfsmapid(1M).

5. References

    http://sac.sfbay/PSARC/2005/695/

    http://docs.sun.com/app/docs/doc/819-2240/mount-smbfs-1m

    http://bugs.opensolaris.org/view_bug.do?bug_id=6584198
	(SMB Client needs authentication improvements)

    http://bugs.opensolaris.org/view_bug.do?bug_id=6587713
	(Need to reconnect after server disconnect)

6. Resources and Schedule

    n/a

Appendix, Notes

Note 1: Initial reviewers expected that the smbiod process might
run as part of an SMF service like svc:/network/smb/client.
That would be a useful improvement, but there are a few things
presently used by the SMB client connection setup code that
assume the calling thread's UID is that of the user for which
actions are being performed.  If connection setup were to be
consolidated into one process, we would first need to change
the supporting components to accept a UID (or credentials)
argument to indicate which user this connection belongs to.
It would be unfortunate to delay this important reconnection
feature for such an improvement.

6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		ON
    6.5. ARC review type: FastTrack
    6.6. ARC Exposure: open