SMB auto-login mounting in FreeBSD
                    ----------------------------------
                    $Id: README.FreeBSD,v 1.3 2006/05/12 08:19:51 shelton Exp $

1. Preface
----------

This document describes, how to implement Windows featurs about auto-mounting
some shares with user login with FreeBSD implementation of SMBFS. This document
assumed, that you already have working SMBFS in your kernel (see man mount_smbfs(8),
FreeBSD Handbook chapter 9 and an sample kernel config file part below:

#
# SMB/CIFS requester
# NETSMB enables support for SMB protocol, it requires LIBMCHAIN and LIBICONV
# options.
# NETSMBCRYPTO enables support for encrypted passwords.
options         NETSMB                  #SMB/CIFS requester
options         NETSMBCRYPTO            #encrypted password support for SMB

# mchain library. It can be either loaded as KLD or compiled into kernel
options         LIBMCHAIN               #mbuf management library
options         SMBFS                   #SMB/CIFS filesystem
# Kernel side iconv library
options         LIBICONV

You will need all these for working SMBFS. Also /etc/nsmb.conf should be
configured properly (in spite of that nsmb.conf has all variables 'transparent',
documentation about SMBFS tuning in FreeBSD are very, very shy :-( You should
setup at least paremeters "workgroup" and "nbns". As nbns you should set your
WINS server (as called it in Microsoft world). For displaying filenames in
other languages, different from English (ISO-8859-1), also you sholud setup
codepage translation pairs.

I have developed helper script smb2nsmbrc (see below), which slightly simplified
/etc/nmsb.conf setup, by inserting records with codepare pairs and DNS names
(if any) about each detected Windows (and Samba also) boxes.

2. Before first run
-------------------

a. You need to install nbtscan and sudo packages. Nbtscan uses for scan network
and detect Windows boxes (in smb2nsmbrc script), sudo uses in mountsmb2 to
issue mount itself, because ordinary only root can mount/unmount filesystems

b. You MUST allow to all users, which will use this feature, run script
'mountsmb2'. This sample illustarted, how to do this with sudo, through adding
next line in 'sudoers' file:

<username> <HOSTNAME> = (root) NOPASSWD: /usr/local/bin/mountsmb2 -a -u <username>

where <username> - user name, who will mount resources
      <HOSTNAME> - host name, when run script

More info about sudoers file see man sudoers(5))

c. Before start mountsmb2 first time, you should setup your .nsmbrc file
properly. For my pity, you must setup each Windows/Samba box in your network
SEPARATELY. No default usernames, no domain logons. Looks sadly, aren't you?
smb2nsmbrc script sligtly takes this job from you. You start smb2nsmbrc, it
called nbtscan (of course, you should have nbtscan and smbutil in your path),
parsing their output, asks you about username, password and stored file
.nsmbrctmp in generated temporarly directory. Than, you insert their data in
.nsmbrc file. In .nsmbrc will similar records:

[SERVERNAME:USERNAME]
password=<encrypted password>

Encryption done with smbutil and ready for use with mount_smbfs. Nbtscan takes
one parameter - network address in CIDR format, like 10.0.1.0/24 (will scan
10.0.1.0 - 10.0.1.255) or address chunk like 10.0.1.1-10.0.1.10 (will scan
specified chunk). smb2nsmbrc creates work directory in /tmp, their name will
generated from current time in seconds, so, each time when you run smb2nsmbrc you
will receive different directories. smb2nsmbrc creates two files - one for adding
to .nsmbrc, called .nsmbrctmp, two for adding to /etc/nsmb.conf, called
nsmb.conf.tmp

d. You should create and fill your own .mssmbrc file. This is a slightly mirrored
/etc/fstab file and does similar way for mountsmb2 - describes all shares, which
should mounted auto or manually.

3. .mssmbrc file - /etc/fstab mirror for mountsmb2
--------------------------------------------------

For mounting SMB/CIFS shares with mountsmb2 .mssmbrc file plays role, similar
/etc/fstab for all system. It describes all mounting points, which can be mounted
in auto or manual modes. File format is very easy - freeform text file, when one
line consists from these chunks:

ServerName ShareName MountPoint FileMode DirMode {auto|noauto}

When FileMode and DirMode set to "none", no mode applied
When "auto" set, this share mounts when "smbmount -a" issued
DO NOT SKIP FileMode and DirMode!

Samples:
shadow	   transfer   /usr/home/shelton/smbfs/shadow/transfer  0666  0777  auto
proxy	   shelton    /usr/home/shelton/smbfs/proxy/shelton    0644  0755  auto

4. Run
------

Usually this script runs from .login file (I use /bin/tcsh as login shell) or from
.profile, when you are using /usr/local/bin/bash or simply /bin/sh. Line for
inseting into a .login file are:

sudo mountsmb2 -a -u $USER

When you run mountsmb2 manually you can specify -a to mount all shares, described
as "auto" (usual way) or mount one mountpoint, specify it with -m. Specifying
username with -u is not neccessary, when missed, it will be substituted from
$USER environment variable. So:

mountsmb2 -m /tmp/blabla

mounts share, described as mounted to mountpoint /tmp/blabla (first entry, when
aren't unique)

mountsmb2 -m /tmp/foo/bar -u someuser

mounts share, described as mounted to mountpoint /tmp/foo/bar with effective user
rights someuser.

In examples directory you can find sample files:

.login - sample start script for tcsh
.nsmbrc - sample .nsmbrc file (all passwords are fake!)
.mssmbrc - samble .mssmbrc file
sudoers - sample sudoers file
nsmb.conf - sample of /etc/nsmb.conf

4. Feedback
-----------

All these scripts and this readme file were written by Rashid N. Achilov
(shelton@granch.ru). So, you can ask me about their working and also about
any other SMB shares mounting errors, but keep in mind - I'm NOT A SMBFS
DEVELOPER, I know nothing about internal technic of kernel-side support
of SMBFS under FreeBSD. To ask with serious problems, please mail to SMB developer:
Boris Popov <bp@freebsd.org>.