samba4wins HOWTO
================
(Version 1.0.7)
Status: 12.01.2009

NOTE: The location of wins_config.ldb has changed
      from /etc/samba4wins/ to /var/lib/samba4wins/private/

Please take a look at samba4wins-NEWS.txt for more changes
between releases
(a copy can be found under 
 /usr/share/doc/packages/samba4wins/ (SLES9) or
 /usr/share/doc/samba4wins/ (RHEL4,Debian)).

Some useful links:
==================
For an overview of the WINS Replication please read this:
http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dnarnetbios/html/msdn_winswp.asp
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnw2k/html/msdn_winsoverview.asp
http://msdn.microsoft.com/en-us/library/cc215024(PROT.10).aspx

Ethereal >= 0.10.13 has a dissector for the WINS-Replication
http://www.ethereal.com/

Configuration
=============
/etc/samba4wins/samba4wins.conf:

This file has the same syntax as the smb.conf from samba3.

These are the global parameters that matter:
--------------------------------------------
But you should try to keep the default values == an empty file

"netbios name"
"workgroup"
"interfaces"
"bind interfaces only"
"log level" you should may run with log level = 4 for testing
These parameters are like in samba3 smb.conf.

"nbtd:disable_broadcast"
Set this to "yes" disables listening on the broadcast ip-addresses on the udp port 137.
This is needed when using samba4wins together with samba-3.0.21.
The default is "no".

"nbtd:wins_prepend1Bto1Cqueries"
Normally queries for 0x1C names (all logon servers for a domain) will return the
first address of the 0x1B names (domain master browser and PDC) as first address in the
result list. As many Client only use the first address in the list by default, all clients
will use the same server (the PDC). Windows servers have an option to disable this behavior
(since Windows 2000 Service Pack 2). Set this parameter to "no" to disable prepending
of 0x1B addresses.
The default is "yes".

"nbtd:wins_randomize1Clist"
Normally queries for 0x1C names will return the addresses in the same order as they're stored
in the database, that means first all addresses which have been directly registered at the local
wins server and then all addresses registered at other servers. Windows servers have an option
to change this behavior and randomize the returned addresses. Set this parameter to "yes"
and samba4wins will sort the address list depending on the client address and the matching bits
of the addresses, the first address is randomized based on depending on the 
"nbtd:wins_randomize1Clist_mask" parameter.
The default is "no".

"nbtd:wins_randomize1Clist_mask"
If the "nbtd:wins_randomize1Clist" parameter is set to "yes", then randomizing of the first
returned address is based on the specified netmask. If there are addresses which are in the
same subnet as the client address, the first returned address is randomly choosen out them.
Otherwise the first returned address is randomly choosen out of all addresses.
The default is "255.255.255.0".

"dns proxy"
Specifies that when acting as a WINS server and finding that a NetBIOS name has not been registered,
should treat the NetBIOS name word-for-word as a DNS name and do a lookup with the DNS server for
that name on behalf of the name-querying client.
Note that the maximum length for a NetBIOS name is 15 characters, so the DNS name (or DNS alias)
can likewise only be 15 characters, maximum.
The default is "yes".

"wins hook"
When samba4wins allows you to call an external program for all changes to the WINS database.
The primary use for this option is to allow the dynamic update of external name resolution
databases such as dynamic DNS.
The wins hook parameter specifies the name of a script or executable that will be called as follows:
 - wins_hook operation name nametype ttl IP_list
 - The first argument is the operation and is one of "add", "delete", or "refresh".
   In most cases the operation can be ignored as the rest of the parameters provide sufficient information.
   Note that "refresh" may sometimes be called when the name has not previously been added,
   in that case it should be treated as an add.
 - The second argument is the NetBIOS name.
 - The third argument is the NetBIOS name type as a 2 digit hexadecimal number.
 - The fourth argument is the TTL (time to live) for the name in seconds.
 - The fifth and subsequent arguments are the IP addresses currently registered for that name.
   If this list is empty then the name should be deleted.
An example script that calls the BIND dynamic DNS update program nsupdate is
provided in examples directory of the Samba 3.0.* source code.

"winsdb:local_owner"
This specifies the address that is stored in the winsOwner attribute, of
locally registered winsRecord-objects.
The default is to use the ip-address of the first network interface.

"max wins ttl"
This is the maximum 'time to live' of NetBIOS names that smbd4wins will grant will be (in seconds).
You should never need to change this parameter.
The default is 518400 (= 6 days = 6*24*60*60).

"min wins ttl" 10
This is the minimum 'time to live' of NetBIOS names that smbd4wins will grant will be (in seconds).

"wreplsrv:renew_interval"
This is the interval till records become released.
The default is 518400 (= 6 days = 6*24*60*60)
(NOT used really yet).

"wreplsrv:tombstone_interval"
This is the interval till released records become tombstone
the default is 518400 (= 6 days = 6*24*60*60).

"wreplsrv:tombstone_timeout" 
This is the interval till tombstone records are deleted from the database.
The default is 86400 (= 1 day = 1*24*60*60).

"wreplsrv:tombstone_extra_timeout"
This is the time the server needs to be up till we'll remove tombstone records
from our database.
The default is 259200 (= 3 days = 3*24*60*60).

"wreplsrv:verify_interval"
This interval till we verify active replica records with the owning wins server.
NOTE: this is currently not implemented.
The default value is 2073600 (= 24 days = 24*24*60*60).

"wreplsrv:scavenging_interval"
This is the interval between 2 scavenging runis which cleanup the database
and changes the states of expired name records.
The default value is half of the "wreplsrv:renew_interval".

"wreplsrv:periodic_interval"
This maximum interval between 2 periodicly scheduled runs:
e.g. this is the maximal interval where we check for wins.ldb changes and do push notiications
     to our push partners
e.g. this is the maximal interval where we check for wins_config.ldb changes
     and reload the partner configuration
This default value is 15 seconds.

"wreplsrv:propagate name releases"
If the "wreplsrv:propagate name releases" parameter is set to "yes", then
explicit (from the client) and implicit (via the scavenging) name releases
are propagated to the other servers directly, even if there are still other
addresses active, this applies to SPECIAL GROUP (2) and MULTIHOMED (3) entries.
Also the replication conflict merge algorithm for SPECIAL GROUP (2) entries
discards replica addresses where the address owner is the local server,
if the address was not stored localy before. The merge result is
propagated directly in case an address was discarded.
A Windows servers doesn't propagate name releases of SPECIAL GROUP (2)
and MULTIHOMED (3) entries directly, which means that Windows servers may
return different results to name queries for SPECIAL GROUP (2) and MULTIHOMED (3)
names. The option doesn't have much negative impact if Windows servers are
arround, but be aware that they might return unexpected results.
The default value is "no".

Configure WINS-Replication-Partners
===================================
/var/lib/samba4wins/private/wins_config.ldb

Please be very careful when you edit the wins_config.ldb file!

Adding a new replication partner
--------------------------------
Run this 'ldbedit -H /var/lib/samba4wins/private/wins_config.ldb -a' command (see Notes about ldbedit below).
Then add this for replicating with 'WINSSERVER-02' at ip-address 192.168.9.9:
(Note: the ',CN=PARTNERS' is important!)

Example1 (simple):
<-------------------------------->
dn: CN=WINSSERVER-02,CN=PARTNERS
objectClass: wreplPartner
address: 192.168.9.9
<-------------------------------->

Example1 (extended):
<-------------------------------->
dn: CN=WINSSERVER-02,CN=PARTNERS
objectClass: wreplPartner
address: 192.168.9.9
type: 0x3
pullInterval: 1800
pullRetryInterval: 30
pushChangeCount: 0
pushUseInform: 1
<-------------------------------->

Both versions of Example1 result in the same, the only difference is that
the extended one explictily specifies the default values. When you're ready
just store the file within your editor and exit the editor. 

The meanings of the attributes of a 'wreplPartner' object:
----------------------------------------------------------

address:
This is the ip-address of the replication partner, that we use to contact
the partner when pulling from him, but it's also the address which the partner
needs to use as source ip-addres, when he contacts us!

type:
This has the following meaning:
0x0 => disabled partner
0x1 => the partner is only a PULL-Partner
0x2 => the partner is only a PUSH-Partner
0x3 => the partner is a PULL- and PUSH-Partner
the default is 0x3 (pull and push)

pullInterval:
This is the interval in seconds, between 2 PULL-Replications
to the partner.
The default is 1800 (= 30 mins)
The value 0 means to not try active pull attempts at all to this partner.

pullRetryInterval:
This is the interval in seconds, that will be waited, after a pull replication
error happens to the partner. Because using linear interval steps for the retry
attempts isn't a good idea, we use this:
wait_interval = MIN(pullInterval, error_count * pullRetryInterval)
The default is 30 (seconds).

pushChangeCount:
This is the number of database changes, before we send a push notification to the partner.
The value 0 means to not do active push notifications at all to this partner.

pushUseInform:
This is a boolean parameter (1 or 0), that controls whether we should use a
persistent connection and WREPL_REPL_INFORM messages for the push notifications.
With old servers (NT4) an autofallback is done using the old WREPL_REPL_UPDATE messages.
The default value is 1. The default has changed since version 1.0.7.

ourAddress:
This is the address which we will use as source address, when we contact the partner.
This is only needed when we have multiple local network interfaces, by default smbd4wins
uses the 'best' interface. If you got NT_STATUS_NETWORK_ACCESS_DENIED errors you may need
to set this attribute, otherwise just skip it
(use ethereal to make sure the correct source address is used).

Notes about ldbedit
-------------------
ldbedit uses the EDITOR env-variable, or 'vi' as fallback
to open the search result in LDIF format. You can then edit the records
as you wish, add new records or delete them. When you save and exit
the editor, ldbedit calculates the LDIF diff, and applies the changes
to the database. Note the 'distinguishedName' attribute is autogenerated,
and won't be stored in the database. also see 'ldbedit --help'.

Backup .ldb files
-----------------
Use something like this to backup the ldb-database files.

#~>ldbsearch -d 0 -H /var/lib/samba4wins/wins.ldb "objectClass=*" > /backup/wins-backup.ldif
#~>ldbsearch -d 0 -H /var/lib/samba4wins/private/wins_config.ldb "objectClass=*" > /backup/wins_config-backup.ldif

or maybe just backup static records...
#~>ldbsearch -d 0 -H /var/lib/samba4wins/wins.ldb "(|(objectClass=winsMaxVersion)(isStatic=1))" > /backup/wins-static.ldif

Restore .ldb files
------------------
Use something like this to restore the ldb-database file from a ldif-file.

#~>ldbadd -d 0 -H /var/lib/samba4wins/wins.ldb < /backup/wins-backup.ldif
#~>ldbadd -d 0 -H /var/lib/samba4wins/private/wins_config.ldb < /backup/wins_config-backup.ldif

Please note that ldbadd will not overwrite existing records in an already present database.

Start/Stop
==========
rcsmbd4wins start
rcsmbd4wins stop

Debian:
/etc/init.d/smbd4wins start
/etc/init.d/smbd4wins stop

Log-File
========
/var/log/samba4wins/smbd4wins.log

Database-File
=============
/var/lib/samba4wins/wins.ldb

Please be very careful when you edit the wins.ldb file yourself!

You can look at the database records also with ldbedit or ldbsearch:

ldbedit -H /var/lib/samba4wins/wins.ldb -a
ldbsearch -H /var/lib/samba4wins/wins.ldb

The database has a special entry CN=VERSION that holds the max version id
counter for the local server.
For looking only at this entry, call:
ldbedit -H /var/lib/samba4wins/wins.ldb objectClass=winsMaxVersion
or
ldbedit -H /var/lib/samba4wins/wins.ldb DN=CN=VERSION

It will look like this after at least
one name record was registered with the local wins server:
<----------------------------->
dn: CN=VERSION
objectClass: winsMaxVersion
maxVersion: 64
<----------------------------->

The database also contains the name records, look at all records call:
ldbedit -H /var/lib/samba4wins/wins.ldb objectClass=winsRecord

for only specific records use this:
ldbedit -H /var/lib/samba4wins/wins.ldb name=DOMAIN1
or
ldbedit -H /var/lib/samba4wins/wins.ldb type=0x1C
or
ldbedit -H /var/lib/samba4wins/wins.ldb (&(name=DOMAIN1)(recordState=0))
or ...

this is an example name record:
<------------------------------------------------------------------------>
dn: name=DOMAIN1,type=0x1C
objectClass: winsRecord
type: 0x1C
name: DOMAIN1
recordType: 2
recordState: 0
nodeType: 0
isStatic: 0
expireTime: 20060110201752.0Z
winsOwner: 192.168.9.9
versionID: 55654
address: 192.168.9.56;winsOwner:192.168.9.9;expireTime:20060110201752.0Z;
address: 192.168.4.66;winsOwner:192.168.4.9;expireTime:20060103135509.0Z;
<------------------------------------------------------------------------>

The meanings of the attributes of an 'winsRecord' object:
--------------------------------------------------------

type:
This is name type, e.g. 0x1C means DOMAIN LOGON Servers, 0x20 means file server ...

name:
The name for the record.

recordType:
This means the following:
0 => UNIQUE name record
1 => NORMAL GROUP name record
2 => SPECIAL GROUP name record (e.g. 0x1C)
3 => MULTIHOMED name record

recordState:
0 => ACTIVE
1 => RELEASED
3 => TOMBSTONE

nodeType:
0 => B-NODE
1 => P-NODE
2 => M-NODE
3 => H-NODE

isStatic:
1 => This is a static record and it won't be overwritten via a WINS registration nor 
     via WINS replication.
0 => This is a normal dynamic record.

winsOwner:
This is the WINS server where the name owner registerd the name.
For static records which are added via ldbedit you can use
0.0.0.0 here.

versionID;
This is the version id of the record relative to the winsOwner, when a record is registered
locally, this is taken from the CN=VERSION record's maxVersion attribute,
(which is incremented at the same time).
NOTE: If you create your own (static) records using ldbedit, you need to manually keep the CN=VERSION's
      maxVersion in sync!!! If not, some records will not be replicated to the partners.

address:
This can be a multivalued attribute if the recordType is SPECIAL GROUP (2) or MULTIHOMED (3).
This is the address attached to the name record with the per address winsOwner and expireTime.
The winsOwner and expireTime per address is needed to handle replication conflicts
between SPECIAL GROUP and MULTIHOMED records correctly.

Testing
=======
You can use nmblookup from samba3 to do some name queries.
Note: You may need to use '--configfile=/dev/null' or '-s /dev/null'
      as additional option to nmblookup, when you have the 'socket address'
      parameter set in your smb.conf

Using Samba 3.0.21 and samba4wins on an alias network interface
===============================================================
If you want to use samba4wins on a server where you already run 
Samba 3.0.21, you need the following extra configuration.

Example setup:
You have a server with a network interface:
eth0 ip:192.168.9.1 netmask:255.255.255.0 broadcast:192.168.9.255

Usually the following sockets are used to listen on:

smbd:
0.0.0.0:139 tcp
0.0.0.0:445 tcp

nmbd:
192.168.9.1:137 udp
0.0.0.0:137 udp
192.168.9.1:138 udp
0.0.0.0:138 udp

In this case all incoming packets would go through the 0.0.0.0:* sockets.
If you would start smbd4wins, it wouldn't be possible to listen on port 137
as nmdd already listens there with the wildcard ip.

So what you need is to make nmbd not using the wildcard address,
and we need a seperate unicast address for smbd4wins.

This will add the 192.168.9.2 as 2nd address to the eth0 interface:
ifconfig eth0:2 192.168.9.2 netmask 255.255.255 broadcast 192.168.9.255

To make nmbd not using the wildcard address, you need this:
so what you need is the following in your smb.conf (for samba3!)
<------ /etc/samba/smb.conf --------------->
[globals]
	...
	netbios name = SERVER1
	...
	# only use the given interfaces
	bind interfaces only = yes
	# this is the unicast address
	interfaces = 192.168.9.1
	# this is the broadcast address
	socket address = 192.168.9.255

	# as we want to use samba4wins as wins server
	# set the address here
	wins server = 192.168.9.2
	...
<------------------------------------------>

smbd4wins should only act as wins server and should in this case only handle unicast
requests, as it's imposible to have 2 unix process listening on the same broadcast address
and the same port (192.168.9.255 port 127 in this case).
Also it should use a different netbios name!

<------ /etc/samba4wins/samba4wins.conf --------------->
[globals]
	...
	# it's important that this netbios name is different from 
	# the one that's used for samba3!
	netbios name = SERVER1-WINS
	...
	# only use the given interfaces
	bind interfaces only = yes
	# this is the unicast address
	interfaces = 192.168.9.2
	# samba4wins is only a wins server, 
	# and broadcasts are handled by samba3
	# so disable listening on the broadcast address
	nbtd:disable_broadcast = yes

	# as we want to ourself as wins server
	# and don't listen on 127.0.0.1
	# we need to explicit set the wins server here
	wins server = 192.168.9.2
	...
<------------------------------------------>

After these changes, the use of listening sockets should be like this:

smbd:
192.168.9.1:139 tcp
192.168.9.1:445 tcp

nmbd:
192.168.9.1:137 udp
192.168.9.255:137 udp
192.168.9.1:138 udp
192.168.9.255:138 udp

smbd4wins:
192.168.9.2:42 tcp
192.168.9.2:137 udp

Note: port 42 is used for the wins replication.

Note: You need to use '--configfile=/dev/null' or '-s /dev/null'
      as additional option to nmblookup, for this setup!

samba4wins-check-names.pl
=========================
This a very useful monitoring tool to
monitor the state of wins names in a system
with mutiple wins servers, where the local
one has to be samba4wins (or a plain samba4).

The example below will check the name SERVER3#20
on the local wins.ldb on wins server 172.31.1.1.
The wins servers 172.31.2.1, 172.31.3.1 will be
checked too. The addresses from the wins.ldb and
wins server will be compared to the given addresses.
The result will be logged to
/var/log/samba4wins-check/SERVER3.log and
/var/run/samba4wins-check/SERVER3.status will hold
result in machine readable form. This command can
take longer depending on the amount of remote wins server
and addresses.

The second command will read the result from
/var/run/samba4wins-check/SERVER3.status and will
output it as as oneline string. This command
should run really fast as it only reads data
from the local filesystem.

The exit code of both commands is the same.
0 - OK
1 - Warning
2 - Error
3 - Unknown Error

samba4wins-chec-name.pl \
    --mode getdata \
    --name "SERVER3" \
    --type 20 \
    --address 172.31.1.3 \
    --address 172.31.2.3 \
    --address 172.31.3.3 \
    --local-owner 172.31.1.1 \
    --remote-wins-server 172.31.2.1 \
    --remote-wins-server 172.31.3.1 \
    --log-file /var/log/samba4wins-check/SERVER3.log \
    --status-file /var/run/samba4wins-check/SERVER3.status

samba4wins-check-name.pl \
    --mode getstatus \
    --status-file /var/run/samba4wins-check/SERVER3.status

Feedback
========
For comments, questions and updates please contact samba4wins@SerNet.DE
