samba4wins HOWTO ================ (Version 1.0.0) Status: 31.01.2006 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 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". "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. 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: 0 <--------------------------------> 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. Note: Because NT4 doesn't support WREPL_REPL_INFORM messages, but w2k, w2k3 and samba4wins do, the default is 0 (use the old WREPL_REPL_UPDATE) messages. 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. 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 = 172.31.9.1 # this is the broadcast address socket address = 172.31.9.255 # as we want to use samba4wins as wins server # set the address here wins server = 172.31.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 = 172.31.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 = 172.31.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. Feedback ======== For comments, questions and updates please contact samba4wins@SerNet.DE