1mailto(samba@samba.org) 2 3manpage(smb.conf htmlcommand((5)))(5)(23 Oct 1998)(Samba)(SAMBA) 4 5label(NAME) 6manpagename(smb.conf)(The configuration file for the Samba suite) 7 8label(SYNOPSIS) 9manpagesynopsis() 10 11bf(smb.conf) The bf(smb.conf) file is a configuration file for the 12Samba suite. bf(smb.conf) contains runtime configuration information 13for the Samba programs. The bf(smb.conf) file is designed to be 14configured and administered by the url(bf(swat (8)))(swat.8.html) 15program. The complete description of the file format and possible 16parameters held within are here for reference purposes. 17 18label(FILEFORMAT) 19manpagesection(FILE FORMAT) 20 21The file consists of sections and parameters. A section begins with 22the name of the section in square brackets and continues until the 23next section begins. Sections contain parameters of the form 24 25tt('name = value') 26 27The file is line-based - that is, each newline-terminated line 28represents either a comment, a section name or a parameter. 29 30Section and parameter names are not case sensitive. 31 32Only the first equals sign in a parameter is significant. Whitespace 33before or after the first equals sign is discarded. Leading, trailing 34and internal whitespace in section and parameter names is 35irrelevant. Leading and trailing whitespace in a parameter value is 36discarded. Internal whitespace within a parameter value is retained 37verbatim. 38 39Any line beginning with a semicolon (';') or a hash ('#') character is 40ignored, as are lines containing only whitespace. 41 42Any line ending in a tt('\') is "continued" on the next line in the 43customary UNIX fashion. 44 45The values following the equals sign in parameters are all either a 46string (no quotes needed) or a boolean, which may be given as yes/no, 470/1 or true/false. Case is not significant in boolean values, but is 48preserved in string values. Some items such as create modes are 49numeric. 50 51label(SECTIONDESCRIPTIONS) 52manpagesection(SECTION DESCRIPTIONS) 53 54Each section in the configuration file (except for the 55link(bf([global]))(global) section) describes a shared resource (known 56as a em("share")). The section name is the name of the shared resource 57and the parameters within the section define the shares attributes. 58 59There are three special sections, link(bf([global]))(global), 60link(bf([homes]))(homes) and link(bf([printers]))(printers), which are 61described under link(bf('special sections'))(SPECIALSECTIONS). The 62following notes apply to ordinary section descriptions. 63 64A share consists of a directory to which access is being given plus 65a description of the access rights which are granted to the user of 66the service. Some housekeeping options are also specifiable. 67 68Sections are either filespace services (used by the client as an 69extension of their native file systems) or printable services (used by 70the client to access print services on the host running the server). 71 72Sections may be designated link(bf(guest))(guestok) services, in which 73case no password is required to access them. A specified UNIX 74link(bf(guest account))(guestaccount) is used to define access 75privileges in this case. 76 77Sections other than guest services will require a password to access 78them. The client provides the username. As older clients only provide 79passwords and not usernames, you may specify a list of usernames to 80check against the password using the link(bf("user="))(user) option in 81the share definition. For modern clients such as Windows 95/98 and 82Windows NT, this should not be necessary. 83 84Note that the access rights granted by the server are masked by the 85access rights granted to the specified or guest UNIX user by the host 86system. The server does not grant more access than the host system 87grants. 88 89The following sample section defines a file space share. The user has 90write access to the path tt(/home/bar). The share is accessed via 91the share name "foo": 92 93verb( 94 95 [foo] 96 path = /home/bar 97 writeable = true 98 99) 100 101The following sample section defines a printable share. The share 102is readonly, but printable. That is, the only write access permitted 103is via calls to open, write to and close a spool file. The 104link(bf('guest ok'))(guestok) parameter means access will be permitted 105as the default guest user (specified elsewhere): 106 107verb( 108 [aprinter] 109 path = /usr/spool/public 110 writeable = false 111 printable = true 112 guest ok = true 113) 114 115label(SPECIALSECTIONS) 116manpagesection(SPECIAL SECTIONS) 117 118startdit() 119 120label(global) 121dit(bf(The [global] section)) 122 123Parameters in this section apply to the server as a whole, or are 124defaults for sections which do not specifically define certain 125items. See the notes under link(bf('PARAMETERS'))(PARAMETERS) for more 126information. 127 128label(homes) 129dit(bf(The [homes] section)) 130 131If a section called tt('homes') is included in the configuration file, 132services connecting clients to their home directories can be created 133on the fly by the server. 134 135When the connection request is made, the existing sections are 136scanned. If a match is found, it is used. If no match is found, the 137requested section name is treated as a user name and looked up in the 138local password file. If the name exists and the correct password has 139been given, a share is created by cloning the [homes] section. 140 141Some modifications are then made to the newly created share: 142 143startit() 144 145it() The share name is changed from tt('homes') to the located 146username 147 148it() If no path was given, the path is set to the user's home 149directory. 150 151endit() 152 153If you decide to use a link(bf(path=))(path) line in your [homes] 154section then you may find it useful to use the link(bf(%S))(percentS) 155macro. For example : 156 157tt(path=/data/pchome/%S) 158 159would be useful if you have different home directories for your PCs 160than for UNIX access. 161 162This is a fast and simple way to give a large number of clients access 163to their home directories with a minimum of fuss. 164 165A similar process occurs if the requested section name is tt("homes"), 166except that the share name is not changed to that of the requesting 167user. This method of using the [homes] section works well if different 168users share a client PC. 169 170The [homes] section can specify all the parameters a normal service 171section can specify, though some make more sense than others. The 172following is a typical and suitable [homes] section: 173 174verb( 175 [homes] 176 writeable = yes 177) 178 179An important point is that if guest access is specified in the [homes] 180section, all home directories will be visible to all clients 181bf(without a password). In the very unlikely event that this is 182actually desirable, it would be wise to also specify link(bf(read only 183access))(readonly). 184 185Note that the link(bf(browseable))(browseable) flag for auto home 186directories will be inherited from the global browseable flag, not the 187[homes] browseable flag. This is useful as it means setting 188browseable=no in the [homes] section will hide the [homes] share but 189make any auto home directories visible. 190 191label(printers) 192dit(bf(The [printers] section)) 193 194This section works like link(bf([homes]))(homes), but for printers. 195 196If a bf([printers]) section occurs in the configuration file, users are 197able to connect to any printer specified in the local host's printcap 198file. 199 200When a connection request is made, the existing sections are 201scanned. If a match is found, it is used. If no match is found, but a 202link(bf([homes]))(homes) section exists, it is used as described 203above. Otherwise, the requested section name is treated as a printer 204name and the appropriate printcap file is scanned to see if the 205requested section name is a valid printer share name. If a match is 206found, a new printer share is created by cloning the bf([printers]) 207section. 208 209A few modifications are then made to the newly created share: 210 211startit() 212 213it() The share name is set to the located printer name 214 215it() If no printer name was given, the printer name is set to the 216located printer name 217 218it() If the share does not permit guest access and no username was 219given, the username is set to the located printer name. 220 221endit() 222 223Note that the bf([printers]) service MUST be printable - if you specify 224otherwise, the server will refuse to load the configuration file. 225 226Typically the path specified would be that of a world-writeable spool 227directory with the sticky bit set on it. A typical bf([printers]) entry 228would look like this: 229 230verb( 231 [printers] 232 path = /usr/spool/public 233 guest ok = yes 234 printable = yes 235) 236 237All aliases given for a printer in the printcap file are legitimate 238printer names as far as the server is concerned. If your printing 239subsystem doesn't work like that, you will have to set up a 240pseudo-printcap. This is a file consisting of one or more lines like 241this: 242 243verb( alias|alias|alias|alias... ) 244 245Each alias should be an acceptable printer name for your printing 246subsystem. In the link(bf([global]))(global) section, specify the new 247file as your printcap. The server will then only recognize names 248found in your pseudo-printcap, which of course can contain whatever 249aliases you like. The same technique could be used simply to limit 250access to a subset of your local printers. 251 252An alias, by the way, is defined as any component of the first entry 253of a printcap record. Records are separated by newlines, components 254(if there are more than one) are separated by vertical bar symbols 255("|"). 256 257NOTE: On SYSV systems which use lpstat to determine what printers are 258defined on the system you may be able to use link(bf("printcap name = 259lpstat"))(printcapname) to automatically obtain a list of 260printers. See the link(bf("printcap name"))(printcapname) option for 261more details. 262 263enddit() 264 265label(PARAMETERS) 266manpagesection(PARAMETERS) 267 268Parameters define the specific attributes of sections. 269 270Some parameters are specific to the link(bf([global]))(global) section 271(e.g., link(bf(security))(security)). Some parameters are usable in 272all sections (e.g., link(bf(create mode))(createmode)). All others are 273permissible only in normal sections. For the purposes of the following 274descriptions the link(bf([homes]))(homes) and 275link(bf([printers]))(printers) sections will be considered normal. 276The letter tt('G') in parentheses indicates that a parameter is 277specific to the link(bf([global]))(global) section. The letter tt('S') 278indicates that a parameter can be specified in a service specific 279section. Note that all tt('S') parameters can also be specified in the 280link(bf([global]))(global) section - in which case they will define 281the default behavior for all services. 282 283Parameters are arranged here in alphabetical order - this may not 284create best bedfellows, but at least you can find them! Where there 285are synonyms, the preferred synonym is described, others refer to the 286preferred synonym. 287 288label(VARIABLESUBSTITUTIONS) 289manpagesection(VARIABLE SUBSTITUTIONS) 290 291Many of the strings that are settable in the config file can take 292substitutions. For example the option link(bf(tt("path = 293/tmp/%u")))(path) would be interpreted as tt("path = /tmp/john") if 294the user connected with the username john. 295 296These substitutions are mostly noted in the descriptions below, but 297there are some general substitutions which apply whenever they might 298be relevant. These are: 299 300startit() 301 302label(percentS) 303it() bf(%S) = the name of the current service, if any. 304 305label(percentP) 306it() bf(%P) = the root directory of the current service, if any. 307 308label(percentu) 309it() bf(%u) = user name of the current service, if any. 310 311label(percentg) 312it() bf(%g) = primary group name of link(bf(%u))(percentu). 313 314label(percentU) 315it() bf(%U) = session user name (the user name that 316the client wanted, not necessarily the same as the one they got). 317 318label(percentG) 319it() bf(%G) = primary group name of link(bf(%U))(percentU). 320 321label(percentH) 322it() bf(%H) = the home directory of the user given by link(bf(%u))(percentu). 323 324label(percentv) 325it() bf(%v) = the Samba version. 326 327label(percenth) 328it() bf(%h) = the internet hostname that Samba is running on. 329 330label(percentm) 331it() bf(%m) = the NetBIOS name of the client machine (very useful). 332 333label(percentL) 334it() bf(%L) = the NetBIOS name of the server. This allows you to change your 335config based on what the client calls you. Your server can have a "dual 336personality". 337 338label(percentM) 339it() bf(%M) = the internet name of the client machine. 340 341label(percentN) 342it() bf(%N) = the name of your NIS home directory server. This is 343obtained from your NIS auto.map entry. If you have not compiled Samba 344with the bf(--with-automount) option then this value will be the same 345as link(bf(%L))(percentL). 346 347label(percentp) 348it() bf(%p) = the path of the service's home directory, obtained from your NIS 349auto.map entry. The NIS auto.map entry is split up as "%N:%p". 350 351label(percentR) 352it() bf(%R) = the selected protocol level after protocol 353negotiation. It can be one of CORE, COREPLUS, LANMAN1, LANMAN2 or NT1. 354 355label(percentd) 356it() bf(%d) = The process id of the current server process. 357 358label(percenta) 359it() bf(%a) = the architecture of the remote 360machine. Only some are recognized, and those may not be 100% 361reliable. It currently recognizes Samba, WfWg, WinNT and 362Win95. Anything else will be known as "UNKNOWN". If it gets it wrong 363then sending a level 3 log to email(samba@samba.org) 364should allow it to be fixed. 365 366label(percentI) 367it() bf(%I) = The IP address of the client machine. 368 369label(percentT) 370it() bf(%T) = the current date and time. 371 372endit() 373 374There are some quite creative things that can be done with these 375substitutions and other smb.conf options. 376 377label(NAMEMANGLING) 378manpagesection(NAME MANGLING) 379 380Samba supports em("name mangling") so that DOS and Windows clients can 381use files that don't conform to the 8.3 format. It can also be set to 382adjust the case of 8.3 format filenames. 383 384There are several options that control the way mangling is performed, 385and they are grouped here rather than listed separately. For the 386defaults look at the output of the testparm program. 387 388All of these options can be set separately for each service (or 389globally, of course). 390 391The options are: 392 393label(manglecaseoption) 394bf("mangle case = yes/no") controls if names that have characters that 395aren't of the "default" case are mangled. For example, if this is yes 396then a name like tt("Mail") would be mangled. Default em(no). 397 398label(casesensitiveoption) 399bf("case sensitive = yes/no") controls whether filenames are case 400sensitive. If they aren't then Samba must do a filename search and 401match on passed names. Default em(no). 402 403label(defaultcaseoption) 404bf("default case = upper/lower") controls what the default case is for new 405filenames. Default em(lower). 406 407label(preservecaseoption) 408bf("preserve case = yes/no") controls if new files are created with the 409case that the client passes, or if they are forced to be the tt("default") 410case. Default em(Yes). 411 412label(shortpreservecaseoption) 413 414bf("short preserve case = yes/no") controls if new files which conform 415to 8.3 syntax, that is all in upper case and of suitable length, are 416created upper case, or if they are forced to be the tt("default") 417case. This option can be use with link(bf("preserve case = 418yes"))(preservecaseoption) to permit long filenames to retain their 419case, while short names are lowered. Default em(Yes). 420 421By default, Samba 2.0 has the same semantics as a Windows NT 422server, in that it is case insensitive but case preserving. 423 424label(NOTEABOUTUSERNAMEPASSWORDVALIDATION) 425manpagesection(NOTE ABOUT USERNAME/PASSWORD VALIDATION) 426 427There are a number of ways in which a user can connect to a 428service. The server follows the following steps in determining if it 429will allow a connection to a specified service. If all the steps fail 430then the connection request is rejected. If one of the steps pass then 431the following steps are not checked. 432 433If the service is marked link(bf("guest only = yes"))(guestonly) then 434steps 1 to 5 are skipped. 435 436starteit() 437 438eit() Step 1: If the client has passed a username/password pair and 439that username/password pair is validated by the UNIX system's password 440programs then the connection is made as that username. Note that this 441includes the tt(\\server\service%username) method of passing a 442username. 443 444eit() Step 2: If the client has previously registered a username with 445the system and now supplies a correct password for that username then 446the connection is allowed. 447 448eit() Step 3: The client's netbios name and any previously used user 449names are checked against the supplied password, if they match then 450the connection is allowed as the corresponding user. 451 452eit() Step 4: If the client has previously validated a 453username/password pair with the server and the client has passed the 454validation token then that username is used. This step is skipped if 455link(bf("revalidate = yes"))(revalidate) for this service. 456 457eit() Step 5: If a link(bf("user = "))(user) field is given in the 458smb.conf file for the service and the client has supplied a password, 459and that password matches (according to the UNIX system's password 460checking) with one of the usernames from the link(bf(user=))(user) 461field then the connection is made as the username in the 462link(bf("user="))(user) line. If one of the username in the 463link(bf(user=))(user) list begins with a tt('@') then that name 464expands to a list of names in the group of the same name. 465 466eit() Step 6: If the service is a guest service then a connection is 467made as the username given in the link(bf("guest account 468="))(guestaccount) for the service, irrespective of the supplied 469password. 470 471endeit() 472 473label(COMPLETELISTOFGLOBALPARAMETERS) 474manpagesection(COMPLETE LIST OF GLOBAL PARAMETERS) 475 476Here is a list of all global parameters. See the section of each 477parameter for details. Note that some are synonyms. 478 479startit() 480 481it() link(bf(add user script))(adduserscript) 482 483it() link(bf(allow trusted domains))(allowtrusteddomains) 484 485it() link(bf(announce as))(announceas) 486 487it() link(bf(announce version))(announceversion) 488 489it() link(bf(auto services))(autoservices) 490 491it() link(bf(bind interfaces only))(bindinterfacesonly) 492 493it() link(bf(browse list))(browselist) 494 495it() link(bf(change notify timeout))(changenotifytimeout) 496 497it() link(bf(character set))(characterset) 498 499it() link(bf(client code page))(clientcodepage) 500 501it() link(bf(coding system))(codingsystem) 502 503it() link(bf(config file))(configfile) 504 505it() link(bf(deadtime))(deadtime) 506 507it() link(bf(debug hires timestamp))(debughirestimestamp) 508 509it() link(bf(debug pid))(debugpid) 510 511it() link(bf(debug timestamp))(debugtimestamp) 512 513it() link(bf(debug uid))(debuguid) 514 515it() link(bf(debug level))(debuglevel) 516 517it() link(bf(default))(default) 518 519it() link(bf(default service))(defaultservice) 520 521it() link(bf(delete user script))(deleteuserscript) 522 523it() link(bf(dfree command))(dfreecommand) 524 525it() link(bf(dns proxy))(dnsproxy) 526 527it() link(bf(domain admin group))(domainadmingroup) 528 529it() link(bf(domain admin users))(domainadminusers) 530 531it() link(bf(domain groups))(domaingroups) 532 533it() link(bf(domain guest group))(domainguestgroup) 534 535it() link(bf(domain guest users))(domainguestusers) 536 537it() link(bf(domain logons))(domainlogons) 538 539it() link(bf(domain master))(domainmaster) 540 541it() link(bf(encrypt passwords))(encryptpasswords) 542 543it() link(bf(getwd cache))(getwdcache) 544 545it() link(bf(homedir map))(homedirmap) 546 547it() link(bf(hosts equiv))(hostsequiv) 548 549it() link(bf(interfaces))(interfaces) 550 551it() link(bf(keepalive))(keepalive) 552 553it() link(bf(kernel oplocks))(kerneloplocks) 554 555it() link(bf(ldap filter))(ldapfilter) 556 557it() link(bf(ldap port))(ldapport) 558 559it() link(bf(ldap root))(ldaproot) 560 561it() link(bf(ldap root passwd))(ldaprootpasswd) 562 563it() link(bf(ldap server))(ldapserver) 564 565it() link(bf(ldap suffix))(ldapsuffix) 566 567it() link(bf(lm announce))(lmannounce) 568 569it() link(bf(lm interval))(lminterval) 570 571it() link(bf(load printers))(loadprinters) 572 573it() link(bf(local master))(localmaster) 574 575it() link(bf(lock dir))(lockdir) 576 577it() link(bf(lock directory))(lockdirectory) 578 579it() link(bf(log file))(logfile) 580 581it() link(bf(log level))(loglevel) 582 583it() link(bf(logon drive))(logondrive) 584 585it() link(bf(logon home))(logonhome) 586 587it() link(bf(logon path))(logonpath) 588 589it() link(bf(logon script))(logonscript) 590 591it() link(bf(lpq cache time))(lpqcachetime) 592 593it() link(bf(machine password timeout))(machinepasswordtimeout) 594 595it() link(bf(mangled stack))(mangledstack) 596 597it() link(bf(map to guest))(maptoguest) 598 599it() link(bf(max disk size))(maxdisksize) 600 601it() link(bf(max log size))(maxlogsize) 602 603it() link(bf(max mux))(maxmux) 604 605it() link(bf(max open files))(maxopenfiles) 606 607it() link(bf(max packet))(maxpacket) 608 609it() link(bf(max ttl))(maxttl) 610 611it() link(bf(max wins ttl))(maxwinsttl) 612 613it() link(bf(max xmit))(maxxmit) 614 615it() link(bf(message command))(messagecommand) 616 617it() link(bf(min passwd length))(minpasswdlength) 618 619it() link(bf(min password length))(minpasswordlength) 620 621it() link(bf(min wins ttl))(minwinsttl) 622 623it() link(bf(name resolve order))(nameresolveorder) 624 625it() link(bf(netbios aliases))(netbiosaliases) 626 627it() link(bf(netbios name))(netbiosname) 628 629it() link(bf(netbios scope))(netbiosscope) 630 631it() link(bf(nis homedir))(nishomedir) 632 633it() link(bf(nt acl support))(ntaclsupport) 634 635it() link(bf(nt pipe support))(ntpipesupport) 636 637it() link(bf(nt smb support))(ntsmbsupport) 638 639it() link(bf(null passwords))(nullpasswords) 640 641it() link(bf(ole locking compatibility))(olelockingcompatibility) 642 643it() link(bf(oplock break wait time))(oplockbreakwaittime) 644 645it() link(bf(os level))(oslevel) 646 647it() link(bf(packet size))(packetsize) 648 649it() link(bf(panic action))(panicaction) 650 651it() link(bf(passwd chat))(passwdchat) 652 653it() link(bf(passwd chat debug))(passwdchatdebug) 654 655it() link(bf(passwd program))(passwdprogram) 656 657it() link(bf(password level))(passwordlevel) 658 659it() link(bf(password server))(passwordserver) 660 661it() link(bf(prefered master))(preferedmaster) 662 663it() link(bf(preferred master))(preferredmaster) 664 665it() link(bf(preload))(preload) 666 667it() link(bf(printcap))(printcap) 668 669it() link(bf(printcap name))(printcapname) 670 671it() link(bf(printer driver file))(printerdriverfile) 672 673it() link(bf(protocol))(protocol) 674 675it() link(bf(read bmpx))(readbmpx) 676 677it() link(bf(read prediction))(readprediction) 678 679it() link(bf(read raw))(readraw) 680 681it() link(bf(read size))(readsize) 682 683it() link(bf(remote announce))(remoteannounce) 684 685it() link(bf(remote browse sync))(remotebrowsesync) 686 687it() link(bf(restrict anonymous))(restrictanonymous) 688 689it() link(bf(root))(root) 690 691it() link(bf(root dir))(rootdir) 692 693it() link(bf(root directory))(rootdirectory) 694 695it() link(bf(security))(security) 696 697it() link(bf(server string))(serverstring) 698 699it() link(bf(shared mem size))(sharedmemsize) 700 701it() link(bf(smb passwd file))(smbpasswdfile) 702 703it() link(bf(smbrun))(smbrun) 704 705it() link(bf(socket address))(socketaddress) 706 707it() link(bf(socket options))(socketoptions) 708 709it() link(bf(source environment))(sourceenvironment) 710 711it() link(bf(ssl))(ssl) 712 713it() link(bf(ssl CA certDir))(sslCAcertDir) 714 715it() link(bf(ssl CA certFile))(sslCAcertFile) 716 717it() link(bf(ssl ciphers))(sslciphers) 718 719it() link(bf(ssl client cert))(sslclientcert) 720 721it() link(bf(ssl client key))(sslclientkey) 722 723it() link(bf(ssl compatibility))(sslcompatibility) 724 725it() link(bf(ssl hosts))(sslhosts) 726 727it() link(bf(ssl hosts resign))(sslhostsresign) 728 729it() link(bf(ssl require clientcert))(sslrequireclientcert) 730 731it() link(bf(ssl require servercert))(sslrequireservercert) 732 733it() link(bf(ssl server cert))(sslservercert) 734 735it() link(bf(ssl server key))(sslserverkey) 736 737it() link(bf(ssl version))(sslversion) 738 739it() link(bf(stat cache))(statcache) 740 741it() link(bf(stat cache size))(statcachesize) 742 743it() link(bf(strip dot))(stripdot) 744 745it() link(bf(syslog))(syslog) 746 747it() link(bf(syslog only))(syslogonly) 748 749it() link(bf(time offset))(timeoffset) 750 751it() link(bf(time server))(timeserver) 752 753it() link(bf(timestamp logs))(timestamplogs) 754 755it() link(bf(unix password sync))(unixpasswordsync) 756 757it() link(bf(unix realname))(unixrealname) 758 759it() link(bf(update encrypted))(updateencrypted) 760 761it() link(bf(use rhosts))(userhosts) 762 763it() link(bf(username level))(usernamelevel) 764 765it() link(bf(username map))(usernamemap) 766 767it() link(bf(utmp consolidate))(utmpconsolidate) 768 769it() link(bf(utmp directory))(utmpdirectory) 770 771it() link(bf(utmp hostname))(utmphostname) 772 773it() link(bf(valid chars))(validchars) 774 775it() link(bf(wins hook))(winshook) 776 777it() link(bf(wins proxy))(winsproxy) 778 779it() link(bf(wins server))(winsserver) 780 781it() link(bf(wins support))(winssupport) 782 783it() link(bf(workgroup))(workgroup) 784 785it() link(bf(write raw))(writeraw) 786 787it() link(bf(wtmp directory))(wtmpdirectory) 788 789endit() 790 791label(COMPLETELISTOFSERVICEPARAMETERS) 792manpagesection(COMPLETE LIST OF SERVICE PARAMETERS) 793 794Here is a list of all service parameters. See the section of each 795parameter for details. Note that some are synonyms. 796 797startit() 798 799it() link(bf(admin users))(adminusers) 800 801it() link(bf(allow hosts))(allowhosts) 802 803it() link(bf(alternate permissions))(alternatepermissions) 804 805it() link(bf(available))(available) 806 807it() link(bf(blocking locks))(blockinglocks) 808 809it() link(bf(browsable))(browsable) 810 811it() link(bf(browseable))(browseable) 812 813it() link(bf(case sensitive))(casesensitive) 814 815it() link(bf(casesignames))(casesignames) 816 817it() link(bf(comment))(comment) 818 819it() link(bf(copy))(copy) 820 821it() link(bf(create mask))(createmask) 822 823it() link(bf(create mode))(createmode) 824 825it() link(bf(default case))(defaultcase) 826 827it() link(bf(delete readonly))(deletereadonly) 828 829it() link(bf(delete veto files))(deletevetofiles) 830 831it() link(bf(deny hosts))(denyhosts) 832 833it() link(bf(directory))(directory) 834 835it() link(bf(directory mask))(directorymask) 836 837it() link(bf(directory mode))(directorymode) 838 839it() link(bf(directory security mask))(directorysecuritymask) 840 841it() link(bf(dont descend))(dontdescend) 842 843it() link(bf(dos filetime resolution))(dosfiletimeresolution) 844 845it() link(bf(dos filetimes))(dosfiletimes) 846 847it() link(bf(exec))(exec) 848 849it() link(bf(fake directory create times))(fakedirectorycreatetimes) 850 851it() link(bf(fake oplocks))(fakeoplocks) 852 853it() link(bf(follow symlinks))(followsymlinks) 854 855it() link(bf(force create mode))(forcecreatemode) 856 857it() link(bf(force directory mode))(forcedirectorymode) 858 859it() link(bf(force directory security mode))(forcedirectorysecuritymode) 860 861it() link(bf(force group))(forcegroup) 862 863it() link(bf(force security mode))(forcesecuritymode) 864 865it() link(bf(force user))(forceuser) 866 867it() link(bf(fstype))(fstype) 868 869it() link(bf(group))(group) 870 871it() link(bf(guest account))(guestaccount) 872 873it() link(bf(guest ok))(guestok) 874 875it() link(bf(guest only))(guestonly) 876 877it() link(bf(hide dot files))(hidedotfiles) 878 879it() link(bf(hide files))(hidefiles) 880 881it() link(bf(hosts allow))(hostsallow) 882 883it() link(bf(hosts deny))(hostsdeny) 884 885it() link(bf(include))(include) 886 887it() link(bf(inherit permissions))(inheritpermissions) 888 889it() link(bf(invalid users))(invalidusers) 890 891it() link(bf(level2 oplocks))(level2oplocks) 892 893it() link(bf(locking))(locking) 894 895it() link(bf(lppause command))(lppausecommand) 896 897it() link(bf(lpq command))(lpqcommand) 898 899it() link(bf(lpresume command))(lpresumecommand) 900 901it() link(bf(lprm command))(lprmcommand) 902 903it() link(bf(magic output))(magicoutput) 904 905it() link(bf(magic script))(magicscript) 906 907it() link(bf(mangle case))(manglecase) 908 909it() link(bf(mangle locks))(manglelocks) 910 911it() link(bf(mangled map))(mangledmap) 912 913it() link(bf(mangled names))(manglednames) 914 915it() link(bf(mangling char))(manglingchar) 916 917it() link(bf(map archive))(maparchive) 918 919it() link(bf(map hidden))(maphidden) 920 921it() link(bf(map system))(mapsystem) 922 923it() link(bf(max connections))(maxconnections) 924 925it() link(bf(min print space))(minprintspace) 926 927it() link(bf(only guest))(onlyguest) 928 929it() link(bf(only user))(onlyuser) 930 931it() link(bf(oplock contention limit))(oplockcontentionlimit) 932 933it() link(bf(oplocks))(oplocks) 934 935it() link(bf(path))(path) 936 937it() link(bf(postexec))(postexec) 938 939it() link(bf(postscript))(postscript) 940 941it() link(bf(preexec))(preexec) 942 943it() link(bf(preexec close))(preexecclose) 944 945it() link(bf(preserve case))(preservecase) 946 947it() link(bf(print command))(printcommand) 948 949it() link(bf(print ok))(printok) 950 951it() link(bf(printable))(printable) 952 953it() link(bf(printer))(printer) 954 955it() link(bf(printer driver))(printerdriver) 956 957it() link(bf(printer driver location))(printerdriverlocation) 958 959it() link(bf(printer name))(printername) 960 961it() link(bf(printing))(printing) 962 963it() link(bf(public))(public) 964 965it() link(bf(queuepause command))(queuepausecommand) 966 967it() link(bf(queueresume command))(queueresumecommand) 968 969it() link(bf(read list))(readlist) 970 971it() link(bf(read only))(readonly) 972 973it() link(bf(revalidate))(revalidate) 974 975it() link(bf(root postexec))(rootpostexec) 976 977it() link(bf(root preexec))(rootpreexec) 978 979it() link(bf(root preexec close))(rootpreexecclose) 980 981it() link(bf(security mask))(securitymask) 982 983it() link(bf(set directory))(setdirectory) 984 985it() link(bf(share modes))(sharemodes) 986 987it() link(bf(short preserve case))(shortpreservecase) 988 989it() link(bf(status))(status) 990 991it() link(bf(strict locking))(strictlocking) 992 993it() link(bf(strict sync))(strictsync) 994 995it() link(bf(sync always))(syncalways) 996 997it() link(bf(user))(user) 998 999it() link(bf(username))(username) 1000 1001it() link(bf(users))(users) 1002 1003it() link(bf(utmp))(utmp) 1004 1005it() link(bf(valid users))(validusers) 1006 1007it() link(bf(veto files))(vetofiles) 1008 1009it() link(bf(veto oplock files))(vetooplockfiles) 1010 1011it() link(bf(volume))(volume) 1012 1013it() link(bf(wide links))(widelinks) 1014 1015it() link(bf(writable))(writable) 1016 1017it() link(bf(write cache size))(writecachesize) 1018 1019it() link(bf(write list))(writelist) 1020 1021it() link(bf(write ok))(writeok) 1022 1023it() link(bf(writeable))(writeable) 1024 1025endit() 1026 1027label(EXPLANATIONOFEACHPARAMETER) 1028manpagesection(EXPLANATION OF EACH PARAMETER) 1029 1030startdit() 1031 1032label(adduserscript) 1033dit(bf(add user script (G))) 1034 1035This is the full pathname to a script that will be run em(AS ROOT) by 1036url(bf(smbd (8)))(smbd.8.html) under special circumstances decribed 1037below. 1038 1039Normally, a Samba server requires that UNIX users are created for all 1040users accessing files on this server. For sites that use Windows NT 1041account databases as their primary user database creating these users 1042and keeping the user list in sync with the Windows NT PDC is an 1043onerous task. This option allows url(bf(smbd))(smbd.8.html) to create 1044the required UNIX users em(ON DEMAND) when a user accesses the Samba 1045server. 1046 1047In order to use this option, url(bf(smbd))(smbd.8.html) must be set to 1048link(bf(security=server))(securityequalserver) or 1049link(bf(security=domain))(securityequaldomain) and bf("add user script") 1050must be set to a full pathname for a script that will create a UNIX user 1051given one argument of bf(%u), which expands into the UNIX user name to 1052create. 1053 1054When the Windows user attempts to access the Samba server, at 1055em("login")(session setup in the SMB protocol) time, 1056url(bf(smbd))(smbd.8.html) contacts the link(bf(password 1057server))(passwordserver) and attempts to authenticate the given user 1058with the given password. If the authentication succeeds then 1059url(bf(smbd))(smbd.8.html) attempts to find a UNIX user in the UNIX 1060password database to map the Windows user into. If this lookup fails, 1061and bf("add user script") is set then url(bf(smbd))(smbd.8.html) will 1062call the specified script em(AS ROOT), expanding any bf(%u) argument 1063to be the user name to create. 1064 1065If this script successfully creates the user then 1066url(bf(smbd))(smbd.8.html) will continue on as though the UNIX user 1067already existed. In this way, UNIX users are dynamically created to 1068match existing Windows NT accounts. 1069 1070See also link(bf(security=server))(securityequalserver), 1071link(bf(security=domain))(securityequaldomain), link(bf(password 1072server))(passwordserver), link(bf(delete user 1073script))(deleteuserscript). 1074 1075 bf(Default:) 1076tt( add user script = <empty string>) 1077 1078 bf(Example:) 1079tt( add user script = /usr/local/samba/bin/add_user %u) 1080 1081label(adminusers) 1082dit(bf(admin users (S))) 1083 1084This is a list of users who will be granted administrative privileges 1085on the share. This means that they will do all file operations as the 1086super-user (root). 1087 1088You should use this option very carefully, as any user in this list 1089will be able to do anything they like on the share, irrespective of 1090file permissions. 1091 1092 bf(Default:) nl() 1093tt( no admin users) 1094 1095 bf(Example:) nl() 1096tt( admin users = jason) 1097 1098label(allow hosts) 1099dit(bf(allow hosts (S))) 1100 1101Synonym for link(bf(hosts allow))(hostsallow). 1102 1103label(allowtrusteddomains) 1104dit(bf(allow trusted domains (G))) 1105 1106This option only takes effect when the link(bf(security))(security) 1107option is set to bf(server) or bf(domain). If it is set to no, 1108then attempts to connect to a resource from a domain or workgroup other than 1109the one which smbd is running in will fail, even if that domain 1110is trusted by the remote server doing the authentication. 1111 1112This is useful if you only want your Samba server to serve resources 1113to users in the domain it is a member of. As an example, suppose that there are 1114two domains DOMA and DOMB. DOMB is trusted by DOMA, which contains 1115the Samba server. Under normal circumstances, a user with an account 1116in DOMB can then access the resources of a UNIX account with the same 1117account name on the Samba server even if they do not have an account 1118in DOMA. This can make implementing a security boundary difficult. 1119 1120 bf(Default:) 1121tt( allow trusted domains = Yes) 1122 1123 bf(Example:) 1124tt( allow trusted domains = No) 1125 1126label(alternatepermissions) 1127dit(bf(alternate permissions (S))) 1128 1129This is a deprecated parameter. It no longer has any effect in Samba2.0. 1130In previous versions of Samba it affected the way the DOS "read only" 1131attribute was mapped for a file. In Samba2.0 a file is marked "read only" 1132if the UNIX file does not have the 'w' bit set for the owner of the file, 1133regardless if the owner of the file is the currently logged on user or not. 1134 1135label(announceas) 1136dit(bf(announce as (G))) 1137 1138This specifies what type of server url(bf(nmbd))(nmbd.8.html) will 1139announce itself as, to a network neighborhood browse list. By default 1140this is set to Windows NT. The valid options are : "NT", which is a 1141synonym for "NT Server", "NT Server", "NT Workstation", "Win95" or 1142"WfW" meaning Windows NT Server, Windows NT Workstation, Windows 95 1143and Windows for Workgroups respectively. Do not change this parameter 1144unless you have a specific need to stop Samba appearing as an NT server 1145as this may prevent Samba servers from participating as browser servers correctly. 1146 1147 bf(Default:) 1148tt( announce as = NT Server) 1149 1150 bf(Example) 1151tt( announce as = Win95) 1152 1153label(announceversion) 1154dit(bf(announce version (G))) 1155 1156This specifies the major and minor version numbers that nmbd will use 1157when announcing itself as a server. The default is 4.2. Do not change 1158this parameter unless you have a specific need to set a Samba server 1159to be a downlevel server. 1160 1161 bf(Default:) 1162tt( announce version = 4.2) 1163 1164 bf(Example:) 1165tt( announce version = 2.0) 1166 1167 1168label(autoservices) 1169dit(bf(auto services (G))) 1170 1171This is a list of services that you want to be automatically added to 1172the browse lists. This is most useful for homes and printers services 1173that would otherwise not be visible. 1174 1175Note that if you just want all printers in your printcap file loaded 1176then the link(bf("load printers"))(loadprinters) option is easier. 1177 1178 bf(Default:) 1179tt( no auto services) 1180 1181 bf(Example:) 1182tt( auto services = fred lp colorlp) 1183 1184label(available) 1185dit(bf(available (S))) 1186 1187This parameter lets you em('turn off') a service. If tt('available = no'), 1188then em(ALL) attempts to connect to the service will fail. Such failures 1189are logged. 1190 1191 bf(Default:) 1192tt( available = yes) 1193 1194 bf(Example:) 1195tt( available = no) 1196 1197label(bindinterfacesonly) 1198dit(bf(bind interfaces only (G))) 1199 1200This global parameter allows the Samba admin to limit what interfaces 1201on a machine will serve smb requests. If affects file service 1202url(bf(smbd))(smbd.8.html) and name service url(bf(nmbd))(nmbd.8.html) 1203in slightly different ways. 1204 1205For name service it causes url(bf(nmbd))(nmbd.8.html) to bind to ports 1206137 and 138 on the interfaces listed in the 1207link(bf('interfaces'))(interfaces) 1208parameter. url(bf(nmbd))(nmbd.8.html) also binds to the 'all 1209addresses' interface (0.0.0.0) on ports 137 and 138 for the purposes 1210of reading broadcast messages. If this option is not set then 1211url(bf(nmbd))(nmbd.8.html) will service name requests on all of these 1212sockets. If bf("bind interfaces only") is set then 1213url(bf(nmbd))(nmbd.8.html) will check the source address of any 1214packets coming in on the broadcast sockets and discard any that don't 1215match the broadcast addresses of the interfaces in the 1216link(bf('interfaces'))(interfaces) parameter list. As unicast packets 1217are received on the other sockets it allows url(bf(nmbd))(nmbd.8.html) 1218to refuse to serve names to machines that send packets that arrive 1219through any interfaces not listed in the 1220link(bf("interfaces"))(interfaces) list. IP Source address spoofing 1221does defeat this simple check, however so it must not be used 1222seriously as a security feature for url(bf(nmbd))(nmbd.8.html). 1223 1224For file service it causes url(bf(smbd))(smbd.8.html) to bind only to 1225the interface list given in the link(bf('interfaces'))(interfaces) 1226parameter. This restricts the networks that url(bf(smbd))(smbd.8.html) 1227will serve to packets coming in those interfaces. Note that you 1228should not use this parameter for machines that are serving PPP or 1229other intermittent or non-broadcast network interfaces as it will not 1230cope with non-permanent interfaces. 1231 1232If bf("bind interfaces only") is set then unless the network address 1233em(127.0.0.1) is added to the link(bf('interfaces'))(interfaces) parameter 1234list url(bf(smbpasswd))(smbpasswd.8.html) and 1235url(bf(swat))(swat.8.html) may not work as expected due to the 1236reasons covered below. 1237 1238To change a users SMB password, the url(bf(smbpasswd))(smbpasswd.8.html) 1239by default connects to the em("localhost" - 127.0.0.1) address as an SMB 1240client to issue the password change request. If bf("bind interfaces only") 1241is set then unless the network address em(127.0.0.1) is added to the 1242link(bf('interfaces'))(interfaces) parameter list then 1243url(bf(smbpasswd))(smbpasswd.8.html) will fail to connect in it's 1244default mode. url(bf(smbpasswd))(smbpasswd.8.html) can be forced to 1245use the primary IP interface of the local host by using its 1246url(bf("-r remote machine"))(smbpasswd.8.html#minusr) parameter, with 1247bf("remote machine") set to the IP name of the primary interface 1248of the local host. 1249 1250The url(bf(swat))(swat.8.html) status page tries to connect with 1251url(bf(smbd))(smbd.8.html) and url(bf(nmbd))(nmbd.8.html) at the address 1252em(127.0.0.1) to determine if they are running. Not adding em(127.0.0.1) will cause 1253url(bf(smbd))(smbd.8.html) and url(bf(nmbd))(nmbd.8.html) to always show 1254"not running" even if they really are. This can prevent 1255url(bf(swat))(swat.8.html) from starting/stopping/restarting 1256url(bf(smbd))(smbd.8.html) and url(bf(nmbd))(nmbd.8.html). 1257 1258 bf(Default:) 1259tt( bind interfaces only = False) 1260 1261 bf(Example:) 1262tt( bind interfaces only = True) 1263 1264label(blockinglocks) 1265dit(bf(blocking locks (S))) 1266 1267This parameter controls the behavior of url(bf(smbd))(smbd.8.html) when 1268given a request by a client to obtain a byte range lock on a region 1269of an open file, and the request has a time limit associated with it. 1270 1271If this parameter is set and the lock range requested cannot be 1272immediately satisfied, Samba 2.0 will internally queue the lock 1273request, and periodically attempt to obtain the lock until the 1274timeout period expires. 1275 1276If this parameter is set to "False", then Samba 2.0 will behave 1277as previous versions of Samba would and will fail the lock 1278request immediately if the lock range cannot be obtained. 1279 1280This parameter can be set per share. 1281 1282 bf(Default:) 1283tt( blocking locks = True) 1284 1285 bf(Example:) 1286tt( blocking locks = False) 1287 1288label(browsable) 1289dit(bf(browsable (S))) 1290 1291Synonym for link(bf(browseable))(browseable). 1292 1293label(browselist) 1294dit(bf(browse list(G))) 1295 1296This controls whether url(bf(smbd))(smbd.8.html) will serve a browse 1297list to a client doing a NetServerEnum call. Normally set to true. You 1298should never need to change this. 1299 1300 bf(Default:) 1301tt( browse list = Yes) 1302 1303label(browseable) 1304dit(bf(browseable)) 1305 1306This controls whether this share is seen in the list of available 1307shares in a net view and in the browse list. 1308 1309 bf(Default:) 1310tt( browseable = Yes) 1311 1312 bf(Example:) 1313tt( browseable = No) 1314 1315label(casesensitive) 1316dit(bf(case sensitive (S))) 1317 1318See the discussion in the section link(bf(NAME MANGLING))(NAMEMANGLING). 1319 1320label(casesignames) 1321dit(bf(casesignames (S))) 1322 1323Synonym for link(bf("case sensitive"))(casesensitive). 1324 1325label(changenotifytimeout) 1326dit(bf(change notify timeout (G))) 1327 1328One of the new NT SMB requests that Samba 2.0 supports is the 1329"ChangeNotify" requests. This SMB allows a client to tell a server to 1330em("watch") a particular directory for any changes and only reply to 1331the SMB request when a change has occurred. Such constant scanning of 1332a directory is expensive under UNIX, hence an 1333url(bf(smbd))(smbd.8.html) daemon only performs such a scan on each 1334requested directory once every bf(change notify timeout) seconds. 1335 1336bf(change notify timeout) is specified in units of seconds. 1337 1338 bf(Default:) 1339tt( change notify timeout = 60) 1340 1341 bf(Example:) 1342tt( change notify timeout = 300) 1343 1344Would change the scan time to every 5 minutes. 1345 1346label(characterset) 1347dit(bf(character set (G))) 1348 1349This allows a smbd to map incoming filenames from a DOS Code page (see 1350the link(bf(client code page))(clientcodepage) parameter) to several 1351built in UNIX character sets. The built in code page translations are: 1352 1353startit() 1354 1355it() bf(ISO8859-1) Western European UNIX character set. The parameter 1356link(bf(client code page))(clientcodepage) em(MUST) be set to code 1357page 850 if the bf(character set) parameter is set to iso8859-1 1358in order for the conversion to the UNIX character set to be done 1359correctly. 1360 1361it() bf(ISO8859-2) Eastern European UNIX character set. The parameter 1362link(bf(client code page))(clientcodepage) em(MUST) be set to code 1363page 852 if the bf(character set) parameter is set to ISO8859-2 1364in order for the conversion to the UNIX character set to be done 1365correctly. 1366 1367it() bf(ISO8859-5) Russian Cyrillic UNIX character set. The parameter 1368link(bf(client code page))(clientcodepage) em(MUST) be set to code 1369page 866 if the bf(character set) parameter is set to ISO8859-5 1370in order for the conversion to the UNIX character set to be done 1371correctly. 1372 1373it() bf(ISO8859-7) Greek UNIX character set. The parameter 1374link(bf(client code page))(clientcodepage) em(MUST) be set to code 1375page 737 if the bf(character set) parameter is set to ISO8859-7 1376in order for the conversion to the UNIX character set to be done 1377correctly. 1378 1379it() bf(KOI8-R) Alternate mapping for Russian Cyrillic UNIX 1380character set. The parameter link(bf(client code 1381page))(clientcodepage) em(MUST) be set to code page 866 if the 1382bf(character set) parameter is set to KOI8-R in order for the 1383conversion to the UNIX character set to be done correctly. 1384 1385endit() 1386 1387em(BUG). These MSDOS code page to UNIX character set mappings should 1388be dynamic, like the loading of MS DOS code pages, not static. 1389 1390See also link(bf(client code page))(clientcodepage). Normally this 1391parameter is not set, meaning no filename translation is done. 1392 1393 bf(Default:) 1394tt( character set = <empty string>) 1395 1396 bf(Example:) 1397tt( character set = ISO8859-1) 1398 1399label(clientcodepage) 1400dit(bf(client code page (G))) 1401 1402This parameter specifies the DOS code page that the clients accessing 1403Samba are using. To determine what code page a Windows or DOS client 1404is using, open a DOS command prompt and type the command "chcp". This 1405will output the code page. The default for USA MS-DOS, Windows 95, and 1406Windows NT releases is code page 437. The default for western european 1407releases of the above operating systems is code page 850. 1408 1409This parameter tells url(bf(smbd))(smbd.8.html) which of the 1410tt(codepage.XXX) files to dynamically load on startup. These files, 1411described more fully in the manual page url(bf(make_smbcodepage 1412(1)))(make_smbcodepage.1.html), tell url(bf(smbd))(smbd.8.html) how 1413to map lower to upper case characters to provide the case insensitivity 1414of filenames that Windows clients expect. 1415 1416Samba currently ships with the following code page files : 1417 1418startit() 1419 1420it() bf(Code Page 437 - MS-DOS Latin US) 1421 1422it() bf(Code Page 737 - Windows '95 Greek) 1423 1424it() bf(Code Page 850 - MS-DOS Latin 1) 1425 1426it() bf(Code Page 852 - MS-DOS Latin 2) 1427 1428it() bf(Code Page 861 - MS-DOS Icelandic) 1429 1430it() bf(Code Page 866 - MS-DOS Cyrillic) 1431 1432it() bf(Code Page 932 - MS-DOS Japanese SJIS) 1433 1434it() bf(Code Page 936 - MS-DOS Simplified Chinese) 1435 1436it() bf(Code Page 949 - MS-DOS Korean Hangul) 1437 1438it() bf(Code Page 950 - MS-DOS Traditional Chinese) 1439 1440endit() 1441 1442Thus this parameter may have any of the values 437, 737, 850, 852, 1443861, 932, 936, 949, or 950. If you don't find the codepage you need, 1444read the comments in one of the other codepage files and the 1445url(bf(make_smbcodepage (1)))(make_smbcodepage.1.html) man page and 1446write one. Please remember to donate it back to the Samba user 1447community. 1448 1449This parameter co-operates with the link(bf("valid 1450chars"))(validchars) parameter in determining what characters are 1451valid in filenames and how capitalization is done. If you set both 1452this parameter and the link(bf("valid chars"))(validchars) parameter 1453the bf("client code page") parameter em(MUST) be set before the 1454link(bf("valid chars"))(validchars) parameter in the bf(smb.conf) 1455file. The link(bf("valid chars"))(validchars) string will then augment 1456the character settings in the "client code page" parameter. 1457 1458If not set, bf("client code page") defaults to 850. 1459 1460See also : link(bf("valid chars"))(validchars) 1461 1462 bf(Default:) 1463tt( client code page = 850) 1464 1465 bf(Example:) 1466tt( client code page = 936) 1467 1468label(codingsystem) 1469dit(bf(codingsystem (G))) 1470 1471This parameter is used to determine how incoming Shift-JIS Japanese 1472characters are mapped from the incoming link(bf("client code 1473page"))(clientcodepage) used by the client, into file names in the 1474UNIX filesystem. Only useful if link(bf("client code 1475page"))(clientcodepage) is set to 932 (Japanese Shift-JIS). 1476 1477The options are : 1478 1479startit() 1480 1481it() bf(SJIS) Shift-JIS. Does no conversion of the incoming filename. 1482 1483it() bf(JIS8, J8BB, J8BH, J8@B, J8@J, J8@H ) Convert from incoming 1484Shift-JIS to eight bit JIS code with different shift-in, shift out 1485codes. 1486 1487it() bf(JIS7, J7BB, J7BH, J7@B, J7@J, J7@H ) Convert from incoming 1488Shift-JIS to seven bit JIS code with different shift-in, shift out 1489codes. 1490 1491it() bf(JUNET, JUBB, JUBH, JU@B, JU@J, JU@H ) Convert from incoming 1492Shift-JIS to JUNET code with different shift-in, shift out codes. 1493 1494it() bf(EUC) Convert an incoming Shift-JIS character to EUC code. 1495 1496it() bf(HEX) Convert an incoming Shift-JIS character to a 3 byte hex 1497representation, i.e. tt(:AB). 1498 1499it() bf(CAP) Convert an incoming Shift-JIS character to the 3 byte hex 1500representation used by the Columbia AppleTalk Program (CAP), 1501i.e. tt(:AB). This is used for compatibility between Samba and CAP. 1502 1503endit() 1504 1505label(comment) 1506dit(bf(comment (S))) 1507 1508This is a text field that is seen next to a share when a client does a 1509queries the server, either via the network neighborhood or via "net 1510view" to list what shares are available. 1511 1512If you want to set the string that is displayed next to the machine 1513name then see the server string command. 1514 1515 bf(Default:) 1516tt( No comment string) 1517 1518 bf(Example:) 1519tt( comment = Fred's Files) 1520 1521label(configfile) 1522dit(bf(config file (G))) 1523 1524This allows you to override the config file to use, instead of the 1525default (usually bf(smb.conf)). There is a chicken and egg problem 1526here as this option is set in the config file! 1527 1528For this reason, if the name of the config file has changed when the 1529parameters are loaded then it will reload them from the new config 1530file. 1531 1532This option takes the usual substitutions, which can be very useful. 1533 1534If the config file doesn't exist then it won't be loaded (allowing you 1535to special case the config files of just a few clients). 1536 1537 bf(Example:) 1538tt( config file = /usr/local/samba/lib/smb.conf.%m) 1539 1540label(copy) 1541dit(bf(copy (S))) 1542 1543This parameter allows you to em('clone') service entries. The specified 1544service is simply duplicated under the current service's name. Any 1545parameters specified in the current section will override those in the 1546section being copied. 1547 1548This feature lets you set up a 'template' service and create similar 1549services easily. Note that the service being copied must occur earlier 1550in the configuration file than the service doing the copying. 1551 1552 bf(Default:) 1553tt( none) 1554 1555 bf(Example:) 1556tt( copy = otherservice) 1557 1558label(createmask) 1559dit(bf(create mask (S))) 1560 1561A synonym for this parameter is link(bf('create mode'))(createmode). 1562 1563When a file is created, the necessary permissions are calculated 1564according to the mapping from DOS modes to UNIX permissions, and the 1565resulting UNIX mode is then bit-wise 'AND'ed with this parameter. 1566This parameter may be thought of as a bit-wise MASK for the UNIX modes 1567of a file. Any bit em(*not*) set here will be removed from the modes set 1568on a file when it is created. 1569 1570The default value of this parameter removes the 'group' and 'other' 1571write and execute bits from the UNIX modes. 1572 1573Following this Samba will bit-wise 'OR' the UNIX mode created from 1574this parameter with the value of the "force create mode" parameter 1575which is set to 000 by default. 1576 1577This parameter does not affect directory modes. See the parameter 1578link(bf('directory mode'))(directorymode) for details. 1579 1580See also the link(bf("force create mode"))(forcecreatemode) parameter 1581for forcing particular mode bits to be set on created files. See also 1582the link(bf("directory mode"))(directorymode) parameter for masking 1583mode bits on created directories. 1584See also the link(bf("inherit permissions"))(inheritpermissions) parameter. 1585 1586 bf(Default:) 1587tt( create mask = 0744) 1588 1589 bf(Example:) 1590tt( create mask = 0775) 1591 1592label(createmode) 1593dit(bf(create mode (S))) 1594 1595This is a synonym for link(bf(create mask))(createmask). 1596 1597label(deadtime) 1598dit(bf(deadtime (G))) 1599 1600The value of the parameter (a decimal integer) represents the number 1601of minutes of inactivity before a connection is considered dead, and 1602it is disconnected. The deadtime only takes effect if the number of 1603open files is zero. 1604 1605This is useful to stop a server's resources being exhausted by a large 1606number of inactive connections. 1607 1608Most clients have an auto-reconnect feature when a connection is 1609broken so in most cases this parameter should be transparent to users. 1610 1611Using this parameter with a timeout of a few minutes is recommended 1612for most systems. 1613 1614A deadtime of zero indicates that no auto-disconnection should be 1615performed. 1616 1617 bf(Default:) 1618tt( deadtime = 0) 1619 1620 bf(Example:) 1621tt( deadtime = 15) 1622 1623label(debughirestimestamp) 1624dit(bf(debug hires timestamp (G))) 1625 1626Sometimes the timestamps in the log messages are needed with a 1627resolution of higher that seconds, this boolean parameter adds 1628microsecond resolution to the timestamp message header when turned on. 1629 1630Note that the parameter link(bf(debug timestamp))(debugtimestamp) 1631must be on for this to have an effect. 1632 1633 bf(Default:) 1634tt( debug hires timestamp = No) 1635 1636 bf(Example:) 1637tt( debug hires timestamp = Yes) 1638 1639label(debugtimestamp) 1640dit(bf(debug timestamp (G))) 1641 1642Samba2.0 debug log messages are timestamped by default. If you are 1643running at a high link(bf("debug level"))(debuglevel) these timestamps 1644can be distracting. This boolean parameter allows timestamping to be turned 1645off. 1646 1647 bf(Default:) 1648tt( debug timestamp = Yes) 1649 1650 bf(Example:) 1651tt( debug timestamp = No) 1652 1653label(debugpid) 1654dit(bf(debug pid (G))) 1655 1656When using only one log file for more then one forked smbd-process 1657there may be hard to follow which process outputs which message. 1658This boolean parameter is adds the process-id to the timestamp message 1659headers in the logfile when turned on. 1660 1661Note that the parameter link(bf(debug timestamp))(debugtimestamp) 1662must be on for this to have an effect. 1663 1664 bf(Default:) 1665tt( debug pid = No) 1666 1667 bf(Example:) 1668tt( debug pid = Yes) 1669 1670label(debuguid) 1671dit(bf(debug uid (G))) 1672 1673Samba is sometimes run as root and sometime run as the connected 1674user, this boolean parameter inserts the current euid, egid, uid 1675and gid to the timestamp message headers in the log file if turned on. 1676 1677Note that the parameter link(bf(debug timestamp))(debugtimestamp) 1678must be on for this to have an effect. 1679 1680 bf(Default:) 1681tt( debug uid = No) 1682 1683 bf(Example:) 1684tt( debug uid = Yes) 1685 1686label(debuglevel) 1687dit(bf(debug level (G))) 1688 1689The value of the parameter (an integer) allows the debug level 1690(logging level) to be specified in the bf(smb.conf) file. This is to 1691give greater flexibility in the configuration of the system. 1692 1693The default will be the debug level specified on the command line 1694or level zero if none was specified. 1695 1696 bf(Example:) 1697tt( debug level = 3) 1698 1699label(default) 1700dit(bf(default (G))) 1701 1702A synonym for link(bf(default service))(defaultservice). 1703 1704label(defaultcase) 1705dit(bf(default case (S))) 1706 1707See the section on link(bf("NAME MANGLING"))(NAMEMANGLING). Also note 1708the link(bf("short preserve case"))(shortpreservecase) parameter. 1709 1710label(defaultservice) 1711dit(bf(default service (G))) 1712 1713This parameter specifies the name of a service which will be connected 1714to if the service actually requested cannot be found. Note that the 1715square brackets are em(NOT) given in the parameter value (see example 1716below). 1717 1718There is no default value for this parameter. If this parameter is not 1719given, attempting to connect to a nonexistent service results in an 1720error. 1721 1722Typically the default service would be a link(bf(guest ok))(guestok), 1723link(bf(read-only))(readonly) service. 1724 1725Also note that the apparent service name will be changed to equal that 1726of the requested service, this is very useful as it allows you to use 1727macros like link(bf(%S))(percentS) to make a wildcard service. 1728 1729Note also that any tt('_') characters in the name of the service used 1730in the default service will get mapped to a tt('/'). This allows for 1731interesting things. 1732 1733 1734 bf(Example:) 1735verb( 1736 default service = pub 1737 1738 [pub] 1739 path = /%S 1740) 1741 1742label(deleteuserscript) 1743dit(bf(delete user script (G))) 1744 1745This is the full pathname to a script that will be run em(AS ROOT) by 1746url(bf(smbd (8)))(smbd.8.html) under special circumstances decribed 1747below. 1748 1749Normally, a Samba server requires that UNIX users are created for all 1750users accessing files on this server. For sites that use Windows NT 1751account databases as their primary user database creating these users 1752and keeping the user list in sync with the Windows NT PDC is an 1753onerous task. This option allows url(bf(smbd))(smbd.8.html) to delete 1754the required UNIX users em(ON DEMAND) when a user accesses the Samba 1755server and the Windows NT user no longer exists. 1756 1757In order to use this option, url(bf(smbd))(smbd.8.html) must be set to 1758link(bf(security=domain))(securityequaldomain) and bf("delete user 1759script") must be set to a full pathname for a script that will delete 1760a UNIX user given one argument of bf(%u), which expands into the UNIX 1761user name to delete. em(NOTE) that this is different to the 1762link(bf(add user script))(adduserscript) which will work with the 1763link(bf(security=server))(securityequalserver) option as well as 1764link(bf(security=domain))(securityequaldomain). The reason for this 1765is only when Samba is a domain member does it get the information 1766on an attempted user logon that a user no longer exists. In the 1767link(bf(security=server))(securityequalserver) mode a missing user 1768is treated the same as an invalid password logon attempt. Deleting 1769the user in this circumstance would not be a good idea. 1770 1771When the Windows user attempts to access the Samba server, at 1772em("login")(session setup in the SMB protocol) time, 1773url(bf(smbd))(smbd.8.html) contacts the link(bf(password 1774server))(passwordserver) and attempts to authenticate the given user 1775with the given password. If the authentication fails with the specific 1776Domain error code meaning that the user no longer exists then 1777url(bf(smbd))(smbd.8.html) attempts to find a UNIX user in the UNIX 1778password database that matches the Windows user account. If this lookup succeeds, 1779and bf("delete user script") is set then url(bf(smbd))(smbd.8.html) will 1780call the specified script em(AS ROOT), expanding any bf(%u) argument 1781to be the user name to delete. 1782 1783This script should delete the given UNIX username. In this way, UNIX 1784users are dynamically deleted to match existing Windows NT accounts. 1785 1786See also link(bf(security=domain))(securityequaldomain), 1787link(bf(password server))(passwordserver), link(bf(add user 1788script))(adduserscript). 1789 1790 bf(Default:) 1791tt( delete user script = <empty string>) 1792 1793 bf(Example:) 1794tt( delete user script = /usr/local/samba/bin/del_user %u) 1795 1796label(deletereadonly) 1797dit(bf(delete readonly (S))) 1798 1799This parameter allows readonly files to be deleted. This is not 1800normal DOS semantics, but is allowed by UNIX. 1801 1802This option may be useful for running applications such as rcs, where 1803UNIX file ownership prevents changing file permissions, and DOS 1804semantics prevent deletion of a read only file. 1805 1806 bf(Default:) 1807tt( delete readonly = No) 1808 1809 bf(Example:) 1810tt( delete readonly = Yes) 1811 1812label(deletevetofiles) 1813dit(bf(delete veto files (S))) 1814 1815This option is used when Samba is attempting to delete a directory 1816that contains one or more vetoed directories (see the link(bf('veto 1817files'))(vetofiles) option). If this option is set to False (the 1818default) then if a vetoed directory contains any non-vetoed files or 1819directories then the directory delete will fail. This is usually what 1820you want. 1821 1822If this option is set to True, then Samba will attempt to recursively 1823delete any files and directories within the vetoed directory. This can 1824be useful for integration with file serving systems such as bf(NetAtalk), 1825which create meta-files within directories you might normally veto 1826DOS/Windows users from seeing (e.g. tt(.AppleDouble)) 1827 1828Setting tt('delete veto files = True') allows these directories to be 1829transparently deleted when the parent directory is deleted (so long 1830as the user has permissions to do so). 1831 1832See also the link(bf(veto files))(vetofiles) parameter. 1833 1834 bf(Default:) 1835tt( delete veto files = False) 1836 1837 bf(Example:) 1838tt( delete veto files = True) 1839 1840label(denyhosts) 1841dit(bf(deny hosts (S))) 1842 1843Synonym for link(bf(hosts deny))(hostsdeny). 1844 1845label(dfreecommand) 1846dit(bf(dfree command (G))) 1847 1848The dfree command setting should only be used on systems where a 1849problem occurs with the internal disk space calculations. This has 1850been known to happen with Ultrix, but may occur with other operating 1851systems. The symptom that was seen was an error of "Abort Retry 1852Ignore" at the end of each directory listing. 1853 1854This setting allows the replacement of the internal routines to 1855calculate the total disk space and amount available with an external 1856routine. The example below gives a possible script that might fulfill 1857this function. 1858 1859The external program will be passed a single parameter indicating a 1860directory in the filesystem being queried. This will typically consist 1861of the string tt("./"). The script should return two integers in 1862ascii. The first should be the total disk space in blocks, and the 1863second should be the number of available blocks. An optional third 1864return value can give the block size in bytes. The default blocksize 1865is 1024 bytes. 1866 1867Note: Your script should em(NOT) be setuid or setgid and should be 1868owned by (and writeable only by) root! 1869 1870 bf(Default:) 1871tt( By default internal routines for determining the disk capacity 1872and remaining space will be used.) 1873 1874 bf(Example:) 1875tt( dfree command = /usr/local/samba/bin/dfree) 1876 1877Where the script dfree (which must be made executable) could be: 1878 1879verb( 1880 #!/bin/sh 1881 df $1 | tail -1 | awk '{print $2" "$4}' 1882) 1883 1884or perhaps (on Sys V based systems): 1885 1886verb( 1887 #!/bin/sh 1888 /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' 1889) 1890 1891 Note that you may have to replace the command names with full 1892path names on some systems. 1893 1894label(directory) 1895dit(bf(directory (S))) 1896 1897Synonym for link(bf(path))(path). 1898 1899label(directorymask) 1900dit(bf(directory mask (S))) 1901 1902This parameter is the octal modes which are used when converting DOS 1903modes to UNIX modes when creating UNIX directories. 1904 1905When a directory is created, the necessary permissions are calculated 1906according to the mapping from DOS modes to UNIX permissions, and the 1907resulting UNIX mode is then bit-wise 'AND'ed with this parameter. 1908This parameter may be thought of as a bit-wise MASK for the UNIX modes 1909of a directory. Any bit em(*not*) set here will be removed from the 1910modes set on a directory when it is created. 1911 1912The default value of this parameter removes the 'group' and 'other' 1913write bits from the UNIX mode, allowing only the user who owns the 1914directory to modify it. 1915 1916Following this Samba will bit-wise 'OR' the UNIX mode created from 1917this parameter with the value of the "force directory mode" 1918parameter. This parameter is set to 000 by default (i.e. no extra mode 1919bits are added). 1920 1921See the link(bf("force directory mode"))(forcedirectorymode) parameter 1922to cause particular mode bits to always be set on created directories. 1923 1924See also the link(bf("create mode"))(createmode) parameter for masking 1925mode bits on created files, and the link(bf("directory security mask"))(directorysecuritymask) 1926parameter. 1927 1928See also the link(bf("inherit permissions"))(inheritpermissions) parameter. 1929 1930 bf(Default:) 1931tt( directory mask = 0755) 1932 1933 bf(Example:) 1934tt( directory mask = 0775) 1935 1936label(directorymode) 1937dit(bf(directory mode (S))) 1938 1939Synonym for link(bf(directory mask))(directorymask). 1940 1941label(directorysecuritymask) 1942dit(bf(directory security mask (S))) 1943 1944This parameter controls what UNIX permission bits can be modified 1945when a Windows NT client is manipulating the UNIX permission on a 1946directory using the native NT security dialog box. 1947 1948This parameter is applied as a mask (AND'ed with) to the changed 1949permission bits, thus preventing any bits not in this mask from 1950being modified. Essentially, zero bits in this mask may be treated 1951as a set of bits the user is not allowed to change. 1952 1953If not set explicitly this parameter is set to the same value as the 1954link(bf(directory mask))(directorymask) parameter. To allow a user to 1955modify all the user/group/world permissions on a directory, set this 1956parameter to 0777. 1957 1958em(Note) that users who can access the Samba server through other 1959means can easily bypass this restriction, so it is primarily 1960useful for standalone "appliance" systems. Administrators of 1961most normal systems will probably want to set it to 0777. 1962 1963See also the link(bf(force directory security 1964mode))(forcedirectorysecuritymode), link(bf(security 1965mask))(securitymask), link(bf(force security mode))(forcesecuritymode) 1966parameters. 1967 1968 bf(Default:) 1969tt( directory security mask = <same as directory mask>) 1970 1971 bf(Example:) 1972tt( directory security mask = 0777) 1973 1974label(dnsproxy) 1975dit(bf(dns proxy (G))) 1976 1977Specifies that url(bf(nmbd))(nmbd.8.html) when acting as a WINS 1978server and finding that a NetBIOS name has not been registered, should 1979treat the NetBIOS name word-for-word as a DNS name and do a lookup 1980with the DNS server for that name on behalf of the name-querying 1981client. 1982 1983Note that the maximum length for a NetBIOS name is 15 characters, so 1984the DNS name (or DNS alias) can likewise only be 15 characters, 1985maximum. 1986 1987url(bf(nmbd))(nmbd.8.html) spawns a second copy of itself to do the 1988DNS name lookup requests, as doing a name lookup is a blocking action. 1989 1990See also the parameter link(bf(wins support))(winssupport). 1991 1992 bf(Default:) 1993tt( dns proxy = yes) 1994 1995label(domainadmingroup) 1996bf(domain admin group (G)) 1997 1998This is an bf(EXPERIMENTAL) parameter that is part of the unfinished 1999Samba NT Domain Controller Code. It may be removed in a later release. 2000To work with the latest code builds that may have more support for 2001Samba NT Domain Controller functionality please subscribe to the 2002mailing list bf(Samba-ntdom) available by sending email to 2003email(listproc@samba.org) 2004 2005label(domainadminusers) 2006dit(bf(domain admin users (G))) 2007 2008This is an bf(EXPERIMENTAL) parameter that is part of the unfinished 2009Samba NT Domain Controller Code. It may be removed in a later release. 2010To work with the latest code builds that may have more support for 2011Samba NT Domain Controller functionality please subscribe to the 2012mailing list bf(Samba-ntdom) available by sending email to 2013email(listproc@samba.org) 2014 2015label(domaingroups) 2016dit(bf(domain groups (G))) 2017 2018This is an bf(EXPERIMENTAL) parameter that is part of the unfinished 2019Samba NT Domain Controller Code. It may be removed in a later release. 2020To work with the latest code builds that may have more support for 2021Samba NT Domain Controller functionality please subscribe to the 2022mailing list bf(Samba-ntdom) available by sending email to 2023email(listproc@samba.org) 2024 2025label(domainguestgroup) 2026dit(bf(domain guest group (G))) 2027 2028This is an bf(EXPERIMENTAL) parameter that is part of the unfinished 2029Samba NT Domain Controller Code. It may be removed in a later release. 2030To work with the latest code builds that may have more support for 2031Samba NT Domain Controller functionality please subscribe to the 2032mailing list bf(Samba-ntdom) available by sending email to 2033email(listproc@samba.org) 2034 2035label(domainguestusers) 2036dit(bf(domain guest users (G))) 2037 2038This is an bf(EXPERIMENTAL) parameter that is part of the unfinished 2039Samba NT Domain Controller Code. It may be removed in a later release. 2040To work with the latest code builds that may have more support for 2041Samba NT Domain Controller functionality please subscribe to the 2042mailing list bf(Samba-ntdom) available by sending email to 2043email(listproc@samba.org) 2044 2045label(domainlogons) 2046dit(bf(domain logons (G))) 2047 2048If set to true, the Samba server will serve Windows 95/98 Domain 2049logons for the link(bf(workgroup))(workgroup) it is in. For more 2050details on setting up this feature see the file DOMAINS.txt in the 2051Samba documentation directory tt(docs/) shipped with the source code. 2052 2053Note that Win95/98 Domain logons are em(NOT) the same as Windows 2054NT Domain logons. NT Domain logons require a Primary Domain Controller 2055(PDC) for the Domain. It is intended that in a future release Samba 2056will be able to provide this functionality for Windows NT clients 2057also. 2058 2059 bf(Default:) 2060tt( domain logons = no) 2061 2062label(domainmaster) 2063dit(bf(domain master (G))) 2064 2065Tell url(bf(nmbd))(nmbd.8.html) to enable WAN-wide browse list 2066collation. Setting this option causes url(bf(nmbd))(nmbd.8.html) to 2067claim a special domain specific NetBIOS name that identifies it as a 2068domain master browser for its given 2069link(bf(workgroup))(workgroup). Local master browsers in the same 2070link(bf(workgroup))(workgroup) on broadcast-isolated subnets will give 2071this url(bf(nmbd))(nmbd.8.html) their local browse lists, and then 2072ask url(bf(smbd))(smbd.8.html) for a complete copy of the browse list 2073for the whole wide area network. Browser clients will then contact 2074their local master browser, and will receive the domain-wide browse 2075list, instead of just the list for their broadcast-isolated subnet. 2076 2077Note that Windows NT Primary Domain Controllers expect to be able to 2078claim this link(bf(workgroup))(workgroup) specific special NetBIOS 2079name that identifies them as domain master browsers for that 2080link(bf(workgroup))(workgroup) by default (i.e. there is no way to 2081prevent a Windows NT PDC from attempting to do this). This means that 2082if this parameter is set and url(bf(nmbd))(nmbd.8.html) claims the 2083special name for a link(bf(workgroup))(workgroup) before a Windows NT 2084PDC is able to do so then cross subnet browsing will behave strangely 2085and may fail. 2086 2087 bf(Default:) 2088tt( domain master = no) 2089 2090label(dont descend) 2091dit(bf(dont descend (S))) 2092 2093There are certain directories on some systems (e.g., the tt(/proc) tree 2094under Linux) that are either not of interest to clients or are 2095infinitely deep (recursive). This parameter allows you to specify a 2096comma-delimited list of directories that the server should always show 2097as empty. 2098 2099Note that Samba can be very fussy about the exact format of the "dont 2100descend" entries. For example you may need tt("./proc") instead of 2101just tt("/proc"). Experimentation is the best policy :-) 2102 2103 bf(Default:) 2104tt( none (i.e., all directories are OK to descend)) 2105 2106 bf(Example:) 2107tt( dont descend = /proc,/dev) 2108 2109label(dosfiletimeresolution) 2110dit(bf(dos filetime resolution (S))) 2111 2112Under the DOS and Windows FAT filesystem, the finest granularity on 2113time resolution is two seconds. Setting this parameter for a share 2114causes Samba to round the reported time down to the nearest two second 2115boundary when a query call that requires one second resolution is made 2116to url(bf(smbd))(smbd.8.html). 2117 2118This option is mainly used as a compatibility option for Visual C++ 2119when used against Samba shares. If oplocks are enabled on a share, 2120Visual C++ uses two different time reading calls to check if a file 2121has changed since it was last read. One of these calls uses a 2122one-second granularity, the other uses a two second granularity. As 2123the two second call rounds any odd second down, then if the file has a 2124timestamp of an odd number of seconds then the two timestamps will not 2125match and Visual C++ will keep reporting the file has changed. Setting 2126this option causes the two timestamps to match, and Visual C++ is 2127happy. 2128 2129 bf(Default:) 2130tt( dos filetime resolution = False) 2131 2132 bf(Example:) 2133tt( dos filetime resolution = True) 2134 2135label(dos filetimes) 2136dit(bf(dos filetimes (S))) 2137 2138Under DOS and Windows, if a user can write to a file they can change 2139the timestamp on it. Under POSIX semantics, only the owner of the file 2140or root may change the timestamp. By default, Samba runs with POSIX 2141semantics and refuses to change the timestamp on a file if the user 2142smbd is acting on behalf of is not the file owner. Setting this option 2143to True allows DOS semantics and smbd will change the file timestamp as 2144DOS requires. 2145 2146 bf(Default:) 2147tt( dos filetimes = False) 2148 2149 bf(Example:) 2150tt( dos filetimes = True) 2151 2152label(encryptpasswords) 2153dit(bf(encrypt passwords (G))) 2154 2155This boolean controls whether encrypted passwords will be negotiated 2156with the client. Note that Windows NT 4.0 SP3 and above and also 2157Windows 98 will by default expect encrypted passwords unless a 2158registry entry is changed. To use encrypted passwords in Samba see the 2159file ENCRYPTION.txt in the Samba documentation directory tt(docs/) 2160shipped with the source code. 2161 2162In order for encrypted passwords to work correctly 2163url(bf(smbd))(smbd.8.html) must either have access to a local 2164url(bf(smbpasswd (5)))(smbpasswd.5.html) file (see the 2165url(bf(smbpasswd (8)))(smbpasswd.8.html) program for information on 2166how to set up and maintain this file), or set the 2167link(bf(security=))(security) parameter to either 2168link(bf("server"))(securityequalserver) or 2169link(bf("domain"))(securityequaldomain) which causes 2170url(bf(smbd))(smbd.8.html) to authenticate against another server. 2171 2172label(exec) 2173dit(bf(exec (S))) 2174 2175This is a synonym for link(bf(preexec))(preexec). 2176 2177label(fake directory create times) 2178dit(bf(fake directory create times (S))) 2179 2180NTFS and Windows VFAT file systems keep a create time for all files 2181and directories. This is not the same as the ctime - status change 2182time - that Unix keeps, so Samba by default reports the earliest of 2183the various times Unix does keep. Setting this parameter for a share 2184causes Samba to always report midnight 1-1-1980 as the create time for 2185directories. 2186 2187This option is mainly used as a compatibility option for Visual C++ 2188when used against Samba shares. Visual C++ generated makefiles have 2189the object directory as a dependency for each object file, and a make 2190rule to create the directory. Also, when NMAKE compares timestamps it 2191uses the creation time when examining a directory. Thus the object 2192directory will be created if it does not exist, but once it does exist 2193it will always have an earlier timestamp than the object files it 2194contains. 2195 2196However, Unix time semantics mean that the create time reported by 2197Samba will be updated whenever a file is created or deleted in the 2198directory. NMAKE therefore finds all object files in the object 2199directory bar the last one built are out of date compared to the 2200directory and rebuilds them. Enabling this option ensures directories 2201always predate their contents and an NMAKE build will proceed as 2202expected. 2203 2204 bf(Default:) 2205tt( fake directory create times = False) 2206 2207 bf(Example:) 2208tt( fake directory create times = True) 2209 2210label(fakeoplocks) 2211dit(bf(fake oplocks (S))) 2212 2213Oplocks are the way that SMB clients get permission from a server to 2214locally cache file operations. If a server grants an oplock 2215(opportunistic lock) then the client is free to assume that it is the 2216only one accessing the file and it will aggressively cache file 2217data. With some oplock types the client may even cache file open/close 2218operations. This can give enormous performance benefits. 2219 2220When you set tt("fake oplocks = yes") url(bf(smbd))(smbd.8.html) will 2221always grant oplock requests no matter how many clients are using the 2222file. 2223 2224It is generally much better to use the real link(bf(oplocks))(oplocks) 2225support rather than this parameter. 2226 2227If you enable this option on all read-only shares or shares that you 2228know will only be accessed from one client at a time such as 2229physically read-only media like CDROMs, you will see a big performance 2230improvement on many operations. If you enable this option on shares 2231where multiple clients may be accessing the files read-write at the 2232same time you can get data corruption. Use this option carefully! 2233 2234This option is disabled by default. 2235 2236label(followsymlinks) 2237dit(bf(follow symlinks (S))) 2238 2239This parameter allows the Samba administrator to stop 2240url(bf(smbd))(smbd.8.html) from following symbolic links in a 2241particular share. Setting this parameter to em("No") prevents any file 2242or directory that is a symbolic link from being followed (the user 2243will get an error). This option is very useful to stop users from 2244adding a symbolic link to tt(/etc/passwd) in their home directory for 2245instance. However it will slow filename lookups down slightly. 2246 2247This option is enabled (i.e. url(bf(smbd))(smbd.8.html) will follow 2248symbolic links) by default. 2249 2250label(forcecreatemode) 2251dit(bf(force create mode (S))) 2252 2253This parameter specifies a set of UNIX mode bit permissions that will 2254em(*always*) be set on a file by Samba. This is done by bitwise 2255'OR'ing these bits onto the mode bits of a file that is being created 2256or having its permissions changed. The default for this parameter is 2257(in octal) 000. The modes in this parameter are bitwise 'OR'ed onto 2258the file mode after the mask set in the link(bf("create 2259mask"))(createmask) parameter is applied. 2260 2261See also the parameter link(bf("create mask"))(createmask) for details 2262on masking mode bits on files. 2263 2264See also the link(bf("inherit permissions"))(inheritpermissions) parameter. 2265 2266 bf(Default:) 2267tt( force create mode = 000) 2268 2269 bf(Example:) 2270tt( force create mode = 0755) 2271 2272would force all created files to have read and execute permissions set 2273for 'group' and 'other' as well as the read/write/execute bits set for 2274the 'user'. 2275 2276label(forcedirectorymode) 2277dit(bf(force directory mode (S))) 2278 2279This parameter specifies a set of UNIX mode bit permissions that will 2280em(*always*) be set on a directory created by Samba. This is done by 2281bitwise 'OR'ing these bits onto the mode bits of a directory that is 2282being created. The default for this parameter is (in octal) 0000 which 2283will not add any extra permission bits to a created directory. This 2284operation is done after the mode mask in the parameter 2285link(bf("directory mask"))(directorymask) is applied. 2286 2287See also the parameter link(bf("directory mask"))(directorymask) for 2288details on masking mode bits on created directories. 2289 2290See also the link(bf("inherit permissions"))(inheritpermissions) parameter. 2291 2292 bf(Default:) 2293tt( force directory mode = 000) 2294 2295 bf(Example:) 2296tt( force directory mode = 0755) 2297 2298would force all created directories to have read and execute 2299permissions set for 'group' and 'other' as well as the 2300read/write/execute bits set for the 'user'. 2301 2302label(forcedirectorysecuritymode) 2303dit(bf(force directory security mode (S))) 2304 2305This parameter controls what UNIX permission bits can be modified when 2306a Windows NT client is manipulating the UNIX permission on a directory 2307using the native NT security dialog box. 2308 2309This parameter is applied as a mask (OR'ed with) to the changed 2310permission bits, thus forcing any bits in this mask that the user may 2311have modified to be on. Essentially, one bits in this mask may be 2312treated as a set of bits that, when modifying security on a directory, 2313the user has always set to be 'on'. 2314 2315If not set explicitly this parameter is set to the same value as the 2316link(bf(force directory mode))(forcedirectorymode) parameter. To allow 2317a user to modify all the user/group/world permissions on a directory, 2318with restrictions set this parameter to 000. 2319 2320em(Note) that users who can access the Samba server through other 2321means can easily bypass this restriction, so it is primarily 2322useful for standalone "appliance" systems. Administrators of 2323most normal systems will probably want to set it to 0000. 2324 2325See also the link(bf(directory security mask))(directorysecuritymask), 2326link(bf(security mask))(securitymask), link(bf(force security 2327mode))(forcesecuritymode) parameters. 2328 2329 bf(Default:) 2330tt( force directory security mode = <same as force directory mode>) 2331 2332 bf(Example:) 2333tt( force directory security mode = 0) 2334 2335label(forcegroup) 2336dit(bf(force group (S))) 2337 2338This specifies a UNIX group name that will be assigned as the default 2339primary group for all users connecting to this service. This is useful 2340for sharing files by ensuring that all access to files on service will 2341use the named group for their permissions checking. Thus, by assigning 2342permissions for this group to the files and directories within this 2343service the Samba administrator can restrict or allow sharing of these 2344files. 2345 2346In Samba 2.0.5 and above this parameter has extended functionality in the following 2347way. If the group name listed here has a '+' character prepended to it 2348then the current user accessing the share only has the primary group 2349default assigned to this group if they are already assigned as a member 2350of that group. This allows an administrator to decide that only users 2351who are already in a particular group will create files with group 2352ownership set to that group. This gives a finer granularity of ownership 2353assignment. For example, the setting tt(force group = +sys) means 2354that only users who are already in group sys will have their default 2355primary group assigned to sys when accessing this Samba share. All 2356other users will retain their ordinary primary group. 2357 2358If the link(bf("force user"))(forceuser) parameter is also set the 2359group specified in bf(force group) will override the primary group 2360set in link(bf("force user"))(forceuser). 2361 2362See also link(bf("force user"))(forceuser) 2363 2364 bf(Default:) 2365tt( no forced group) 2366 2367 bf(Example:) 2368tt( force group = agroup) 2369 2370label(forcesecuritymode) 2371dit(bf(force security mode (S))) 2372 2373This parameter controls what UNIX permission bits can be modified when 2374a Windows NT client is manipulating the UNIX permission on a file 2375using the native NT security dialog box. 2376 2377This parameter is applied as a mask (OR'ed with) to the changed 2378permission bits, thus forcing any bits in this mask that the user may 2379have modified to be on. Essentially, one bits in this mask may be 2380treated as a set of bits that, when modifying security on a file, the 2381user has always set to be 'on'. 2382 2383If not set explicitly this parameter is set to the same value as the 2384link(bf(force create mode))(forcecreatemode) parameter. To allow 2385a user to modify all the user/group/world permissions on a file, 2386with no restrictions set this parameter to 000. 2387 2388em(Note) that users who can access the Samba server through other 2389means can easily bypass this restriction, so it is primarily 2390useful for standalone "appliance" systems. Administrators of 2391most normal systems will probably want to set it to 0000. 2392 2393See also the link(bf(force directory security 2394mode))(forcedirectorysecuritymode), link(bf(directory security 2395mask))(directorysecuritymask), link(bf(security mask))(securitymask) 2396parameters. 2397 2398 bf(Default:) 2399tt( force security mode = <same as force create mode>) 2400 2401 bf(Example:) 2402tt( force security mode = 0) 2403 2404label(forceuser) 2405dit(bf(force user (S))) 2406 2407This specifies a UNIX user name that will be assigned as the default 2408user for all users connecting to this service. This is useful for 2409sharing files. You should also use it carefully as using it 2410incorrectly can cause security problems. 2411 2412This user name only gets used once a connection is established. Thus 2413clients still need to connect as a valid user and supply a valid 2414password. Once connected, all file operations will be performed as the 2415tt("forced user"), no matter what username the client connected as. 2416 2417This can be very useful. 2418 2419In Samba 2.0.5 and above this parameter also causes the primary 2420group of the forced user to be used as the primary group for all 2421file activity. Prior to 2.0.5 the primary group was left as the 2422primary group of the connecting user (this was a bug). 2423 2424See also link(bf("force group"))(forcegroup) 2425 2426 bf(Default:) 2427tt( no forced user) 2428 2429 bf(Example:) 2430tt( force user = auser) 2431 2432label(fstype) 2433dit(bf(fstype (S))) 2434 2435This parameter allows the administrator to configure the string that 2436specifies the type of filesystem a share is using that is reported by 2437url(bf(smbd))(smbd.8.html) when a client queries the filesystem type 2438for a share. The default type is bf("NTFS") for compatibility with 2439Windows NT but this can be changed to other strings such as "Samba" or 2440"FAT" if required. 2441 2442 bf(Default:) 2443tt( fstype = NTFS) 2444 2445 bf(Example:) 2446tt( fstype = Samba) 2447 2448label(getwdcache) 2449dit(bf(getwd cache (G))) 2450 2451This is a tuning option. When this is enabled a caching algorithm 2452will be used to reduce the time taken for getwd() calls. This can have 2453a significant impact on performance, especially when the 2454link(bf(widelinks))(widelinks) parameter is set to False. 2455 2456 bf(Default:) 2457tt( getwd cache = No) 2458 2459 bf(Example:) 2460tt( getwd cache = Yes) 2461 2462label(group) 2463dit(bf(group (S))) 2464 2465Synonym for link(bf("force group"))(forcegroup). 2466 2467label(guestaccount) 2468dit(bf(guest account (S))) 2469 2470This is a username which will be used for access to services which are 2471specified as link(bf('guest ok'))(guestok) (see below). Whatever 2472privileges this user has will be available to any client connecting to 2473the guest service. Typically this user will exist in the password 2474file, but will not have a valid login. The user account bf("ftp") is 2475often a good choice for this parameter. If a username is specified in 2476a given service, the specified username overrides this one. 2477 2478One some systems the default guest account "nobody" may not be able to 2479print. Use another account in this case. You should test this by 2480trying to log in as your guest user (perhaps by using the tt("su -") 2481command) and trying to print using the system print command such as 2482bf(lpr (1)) or bf(lp (1)). 2483 2484 bf(Default:) 2485tt( specified at compile time, usually "nobody") 2486 2487 bf(Example:) 2488tt( guest account = ftp) 2489 2490label(guestok) 2491dit(bf(guest ok (S))) 2492 2493If this parameter is em('yes') for a service, then no password is 2494required to connect to the service. Privileges will be those of the 2495link(bf(guest account))(guestaccount). 2496 2497See the section below on link(bf(security))(security) for more 2498information about this option. 2499 2500 bf(Default:) 2501tt( guest ok = no) 2502 2503 bf(Example:) 2504tt( guest ok = yes) 2505 2506label(guestonly) 2507dit(bf(guest only (S))) 2508 2509If this parameter is em('yes') for a service, then only guest 2510connections to the service are permitted. This parameter will have no 2511affect if link(bf("guest ok"))(guestok) or link(bf("public"))(public) 2512is not set for the service. 2513 2514See the section below on link(bf(security))(security) for more 2515information about this option. 2516 2517 bf(Default:) 2518tt( guest only = no) 2519 2520 bf(Example:) 2521tt( guest only = yes) 2522 2523label(hidedotfiles) 2524dit(bf(hide dot files (S))) 2525 2526This is a boolean parameter that controls whether files starting with 2527a dot appear as hidden files. 2528 2529 bf(Default:) 2530tt( hide dot files = yes) 2531 2532 bf(Example:) 2533tt( hide dot files = no) 2534 2535 2536label(hidefiles) 2537dit(bf(hide files(S))) 2538 2539This is a list of files or directories that are not visible but are 2540accessible. The DOS 'hidden' attribute is applied to any files or 2541directories that match. 2542 2543Each entry in the list must be separated by a tt('/'), which allows 2544spaces to be included in the entry. tt('*') and tt('?') can be used 2545to specify multiple files or directories as in DOS wildcards. 2546 2547Each entry must be a Unix path, not a DOS path and must not include the 2548Unix directory separator tt('/'). 2549 2550Note that the case sensitivity option is applicable in hiding files. 2551 2552Setting this parameter will affect the performance of Samba, as it 2553will be forced to check all files and directories for a match as they 2554are scanned. 2555 2556See also link(bf("hide dot files"))(hidedotfiles), link(bf("veto 2557files"))(vetofiles) and link(bf("case sensitive"))(casesensitive). 2558 2559 bf(Default) 2560verb( 2561 No files or directories are hidden by this option (dot files are 2562 hidden by default because of the "hide dot files" option). 2563) 2564 2565 bf(Example) 2566tt( hide files = /.*/DesktopFolderDB/TrashFor%m/resource.frk/) 2567 2568The above example is based on files that the Macintosh SMB client 2569(DAVE) available from url(bf(Thursby))(http://www.thursby.com) creates for 2570internal use, and also still hides all files beginning with a dot. 2571 2572label(homedirmap) 2573dit(bf(homedir map (G))) 2574 2575If link(bf("nis homedir"))(nishomedir) is true, and 2576url(bf(smbd))(smbd.8.html) is also acting as a Win95/98 link(bf(logon 2577server))(domainlogons) then this parameter specifies the NIS (or YP) 2578map from which the server for the user's home directory should be 2579extracted. At present, only the Sun auto.home map format is 2580understood. The form of the map is: 2581 2582tt(username server:/some/file/system) 2583 2584and the program will extract the servername from before the first 2585tt(':'). There should probably be a better parsing system that copes 2586with different map formats and also Amd (another automounter) maps. 2587 2588NB: A working NIS is required on the system for this option to work. 2589 2590See also link(bf("nis homedir"))(nishomedir), link(bf(domain 2591logons))(domainlogons). 2592 2593 bf(Default:) 2594tt( homedir map = auto.home) 2595 2596 bf(Example:) 2597tt( homedir map = amd.homedir) 2598 2599label(hostsallow) 2600dit(bf(hosts allow (S))) 2601 2602A synonym for this parameter is link(bf('allow hosts'))(allowhosts) 2603 2604This parameter is a comma, space, or tab delimited set of hosts which 2605are permitted to access a service. 2606 2607If specified in the link(bf([global]))(global) section then it will 2608apply to all services, regardless of whether the individual service 2609has a different setting. 2610 2611You can specify the hosts by name or IP number. For example, you could 2612restrict access to only the hosts on a Class C subnet with something 2613like tt("allow hosts = 150.203.5."). The full syntax of the list is 2614described in the man page bf(hosts_access (5)). Note that this man 2615page may not be present on your system, so a brief description will 2616be given here also. 2617 2618Note that the localhost address 127.0.0.1 will always be allowed 2619access unless specifically denied by a "hosts deny" option. 2620 2621You can also specify hosts by network/netmask pairs and by netgroup 2622names if your system supports netgroups. The em(EXCEPT) keyword can also 2623be used to limit a wildcard list. The following examples may provide 2624some help: 2625 2626bf(Example 1): allow all IPs in 150.203.*.* except one 2627 2628tt( hosts allow = 150.203. EXCEPT 150.203.6.66) 2629 2630bf(Example 2): allow hosts that match the given network/netmask 2631 2632tt( hosts allow = 150.203.15.0/255.255.255.0) 2633 2634bf(Example 3): allow a couple of hosts 2635 2636tt( hosts allow = lapland, arvidsjaur) 2637 2638bf(Example 4): allow only hosts in NIS netgroup "foonet", but 2639deny access from one particular host 2640 2641tt( hosts allow = @foonet) 2642 2643tt( hosts deny = pirate) 2644 2645Note that access still requires suitable user-level passwords. 2646 2647See url(bf(testparm (1)))(testparm.1.html) for a way of testing your 2648host access to see if it does what you expect. 2649 2650 bf(Default:) 2651tt( none (i.e., all hosts permitted access)) 2652 2653 bf(Example:) 2654tt( allow hosts = 150.203.5. myhost.mynet.edu.au) 2655 2656 2657label(hostsdeny) 2658dit(bf(hosts deny (S))) 2659 2660The opposite of link(bf('hosts allow'))(hostsallow) - hosts listed 2661here are em(NOT) permitted access to services unless the specific 2662services have their own lists to override this one. Where the lists 2663conflict, the link(bf('allow'))(hostsallow) list takes precedence. 2664 2665 bf(Default:) 2666tt( none (i.e., no hosts specifically excluded)) 2667 2668 bf(Example:) 2669tt( hosts deny = 150.203.4. badhost.mynet.edu.au) 2670 2671label(hostsequiv) 2672dit(bf(hosts equiv (G))) 2673 2674If this global parameter is a non-null string, it specifies the name 2675of a file to read for the names of hosts and users who will be allowed 2676access without specifying a password. 2677 2678This is not be confused with link(bf(hosts allow))(hostsallow) which 2679is about hosts access to services and is more useful for guest 2680services. bf(hosts equiv) may be useful for NT clients which will not 2681supply passwords to samba. 2682 2683NOTE: The use of bf(hosts equiv) can be a major security hole. This is 2684because you are trusting the PC to supply the correct username. It is 2685very easy to get a PC to supply a false username. I recommend that the 2686bf(hosts equiv) option be only used if you really know what you are 2687doing, or perhaps on a home network where you trust your spouse and 2688kids. And only if you em(really) trust them :-). 2689 2690 bf(Default) 2691tt( No host equivalences) 2692 2693 bf(Example) 2694tt( hosts equiv = /etc/hosts.equiv) 2695 2696label(include) 2697dit(bf(include (G))) 2698 2699This allows you to include one config file inside another. The file 2700is included literally, as though typed in place. 2701 2702It takes the standard substitutions, except link(bf(%u))(percentu), 2703link(bf(%P))(percentP) and link(bf(%S))(percentS). 2704 2705label(inheritpermissions) 2706dit(bf(inherit permissions (S))) 2707 2708The permissions on new files and directories are normally governed by 2709link(bf("create mask"))(createmask), 2710link(bf("directory mask"))(directorymask), 2711link(bf("force create mode"))(forcecreatemode) and 2712link(bf("force directory mode"))(forcedirectorymode) 2713but the boolean inherit permissions parameter overrides this. 2714 2715New directories inherit the mode of the parent directory, 2716including bits such as setgid. 2717 2718New files inherit their read/write bits from the parent directory. 2719Their execute bits continue to be determined by 2720link(bf("map archive"))(maparchive), 2721link(bf("map hidden"))(maphidden) and 2722link(bf("map system"))(mapsystem) as usual. 2723 2724Note that the setuid bit is *never* set via inheritance 2725(the code explicitly prohibits this). 2726 2727This can be particularly useful on large systems with many users, 2728perhaps several thousand, 2729to allow a single bf([homes]) share to be used flexibly by each user. 2730 2731See also link(bf("create mask"))(createmask), link(bf("directory mask"))(directorymask), 2732link(bf("force create mode"))(forcecreatemode) and 2733link(bf("force directory mode"))(forcedirectorymode). 2734 2735 bf(Default) 2736tt( inherit permissions = no) 2737 2738 bf(Example) 2739tt( inherit permissions = yes) 2740 2741label(interfaces) 2742dit(bf(interfaces (G))) 2743 2744This option allows you to override the default network interfaces list 2745that Samba will use for browsing, name registration and other NBT 2746traffic. By default Samba will query the kernel for the list of all 2747active interfaces and use any interfaces except 127.0.0.1 that are 2748broadcast capable. 2749 2750The option takes a list of interface strings. Each string can be in 2751any of the following forms: 2752 2753startit() 2754it() a network interface name (such as eth0). This may include 2755 shell-like wildcards so eth* will match any interface starting 2756 with the substring "eth" 2757it() an IP address. In this case the netmask is determined 2758 from the list of interfaces obtained from the kernel 2759it() an IP/mask pair. 2760it() a broadcast/mask pair. 2761endit() 2762 2763The "mask" parameters can either be a bit length (such as 24 for a C 2764class network) or a full netmask in dotted decmal form. 2765 2766The "IP" parameters above can either be a full dotted decimal IP 2767address or a hostname which will be looked up via the OSes normal 2768hostname resolution mechanisms. 2769 2770For example, the following line: 2771 2772tt(interfaces = eth0 192.168.2.10/24 192.168.3.10/255.255.255.0) 2773 2774would configure three network interfaces corresponding to the eth0 2775device and IP addresses 192.168.2.10 and 192.168.3.10. The netmasks of 2776the latter two interfaces would be set to 255.255.255.0. 2777 2778See also link(bf("bind interfaces only"))(bindinterfacesonly). 2779 2780label(invalidusers) 2781dit(bf(invalid users (S))) 2782 2783This is a list of users that should not be allowed to login to this 2784service. This is really a em("paranoid") check to absolutely ensure an 2785improper setting does not breach your security. 2786 2787A name starting with a tt('@') is interpreted as an NIS netgroup first 2788(if your system supports NIS), and then as a UNIX group if the name 2789was not found in the NIS netgroup database. 2790 2791A name starting with tt('+') is interpreted only by looking in the 2792UNIX group database. A name starting with tt('&') is interpreted only 2793by looking in the NIS netgroup database (this requires NIS to be 2794working on your system). The characters tt('+') and tt('&') may be 2795used at the start of the name in either order so the value 2796tt("+&group") means check the UNIX group database, followed by the NIS 2797netgroup database, and the value tt("&+group") means check the NIS 2798netgroup database, followed by the UNIX group database (the same as 2799the tt('@') prefix). 2800 2801The current servicename is substituted for 2802link(bf(%S))(percentS). This is useful in the link(bf([homes]))(homes) 2803section. 2804 2805See also link(bf("valid users"))(validusers). 2806 2807 bf(Default:) 2808tt( No invalid users) 2809 2810 bf(Example:) 2811tt( invalid users = root fred admin @wheel) 2812 2813label(keepalive) 2814dit(bf(keepalive (G))) 2815 2816The value of the parameter (an integer) represents the number of 2817seconds between bf('keepalive') packets. If this parameter is zero, no 2818keepalive packets will be sent. Keepalive packets, if sent, allow the 2819server to tell whether a client is still present and responding. 2820 2821Keepalives should, in general, not be needed if the socket being used 2822has the SO_KEEPALIVE attribute set on it (see link(bf("socket 2823options"))(socketoptions)). Basically you should only use this option 2824if you strike difficulties. 2825 2826 bf(Default:) 2827tt( keepalive = 0) 2828 2829 bf(Example:) 2830tt( keepalive = 60) 2831 2832label(kerneloplocks) 2833dit(bf(kernel oplocks (G))) 2834 2835For UNIXs that support kernel based link(bf(oplocks))(oplocks) 2836(currently only IRIX but hopefully also Linux and FreeBSD soon) this 2837parameter allows the use of them to be turned on or off. 2838 2839Kernel oplocks support allows Samba link(bf(oplocks))(oplocks) to be 2840broken whenever a local UNIX process or NFS operation accesses a file 2841that url(bf(smbd))(smbd.8.html) has oplocked. This allows complete 2842data consistency between SMB/CIFS, NFS and local file access (and is a 2843em(very) cool feature :-). 2844 2845This parameter defaults to em("On") on systems that have the support, 2846and em("off") on systems that don't. You should never need to touch 2847this parameter. 2848 2849See also the link(bf("oplocks"))(oplocks) and link(bf("level2 oplocks"))(level2oplocks) 2850parameters. 2851 2852label(ldapfilter) 2853dit(bf(ldap filter (G))) 2854 2855This parameter is part of the em(EXPERIMENTAL) Samba support for a 2856password database stored on an LDAP server back-end. These options 2857are only available if your version of Samba was configured with 2858the bf(--with-ldap) option. 2859 2860This parameter specifies an LDAP search filter used to search for a 2861user name in the LDAP database. It must contain the string 2862link(bf(%u))(percentU) which will be replaced with the user being 2863searched for. 2864 2865 bf(Default:) 2866tt( empty string.) 2867 2868label(ldapport) 2869dit(bf(ldap port (G))) 2870 2871This parameter is part of the em(EXPERIMENTAL) Samba support for a 2872password database stored on an LDAP server back-end. These options 2873are only available if your version of Samba was configured with 2874the bf(--with-ldap) option. 2875 2876This parameter specifies the TCP port number to use to contact 2877the LDAP server on. 2878 2879 bf(Default:) 2880tt( ldap port = 389.) 2881 2882label(ldaproot) 2883dit(bf(ldap root (G))) 2884 2885This parameter is part of the em(EXPERIMENTAL) Samba support for a 2886password database stored on an LDAP server back-end. These options 2887are only available if your version of Samba was configured with 2888the bf(--with-ldap) option. 2889 2890This parameter specifies the entity to bind to the LDAP server 2891as (essentially the LDAP username) in order to be able to perform 2892queries and modifications on the LDAP database. 2893 2894See also link(bf(ldap root passwd))(ldaprootpasswd). 2895 2896 bf(Default:) 2897tt( empty string (no user defined)) 2898 2899label(ldaprootpasswd) 2900dit(bf(ldap root passwd (G))) 2901 2902This parameter is part of the em(EXPERIMENTAL) Samba support for a 2903password database stored on an LDAP server back-end. These options 2904are only available if your version of Samba was configured with 2905the bf(--with-ldap) option. 2906 2907This parameter specifies the password for the entity to bind to the 2908LDAP server as (the password for this LDAP username) in order to be 2909able to perform queries and modifications on the LDAP database. 2910 2911em(BUGS:) This parameter should em(NOT) be a readable parameter 2912in the bf(smb.conf) file and will be removed once a correct 2913storage place is found. 2914 2915See also link(bf(ldap root))(ldaproot). 2916 2917 bf(Default:) 2918tt( empty string.) 2919 2920label(ldapserver) 2921dit(bf(ldap server (G))) 2922 2923This parameter is part of the em(EXPERIMENTAL) Samba support for a 2924password database stored on an LDAP server back-end. These options 2925are only available if your version of Samba was configured with 2926the bf(--with-ldap) option. 2927 2928This parameter specifies the DNS name of the LDAP server to use 2929for SMB/CIFS authentication purposes. 2930 2931 bf(Default:) 2932tt( ldap server = localhost) 2933 2934label(ldapsuffix) 2935dit(bf(ldap suffix (G))) 2936 2937This parameter is part of the em(EXPERIMENTAL) Samba support for a 2938password database stored on an LDAP server back-end. These options 2939are only available if your version of Samba was configured with 2940the bf(--with-ldap) option. 2941 2942This parameter specifies the tt("dn") or LDAP em("distinguished name") 2943that tells url(bf(smbd))(smbd.8.html) to start from when searching 2944for an entry in the LDAP password database. 2945 2946 bf(Default:) 2947tt( empty string.) 2948 2949label(level2oplocks) 2950dit(bf(level2 oplocks (S))) 2951 2952This parameter (new in Samba 2.0.5) controls whether Samba supports 2953level2 (read-only) oplocks on a share. In Samba 2.0.5 this parameter 2954defaults to "False" as the code is new, but will default to "True" 2955in a later release. 2956 2957Level2, or read-only oplocks allow Windows NT clients that have an 2958oplock on a file to downgrade from a read-write oplock to a read-only 2959oplock once a second client opens the file (instead of releasing all 2960oplocks on a second open, as in traditional, exclusive oplocks). This 2961allows all openers of the file that support level2 oplocks to cache 2962the file for read-ahead only (ie. they may not cache writes or lock 2963requests) and increases performance for many acesses of files that 2964are not commonly written (such as application .EXE files). 2965 2966Once one of the clients which have a read-only oplock writes to 2967the file all clients are notified (no reply is needed or waited 2968for) and told to break their oplocks to "none" and delete any 2969read-ahead caches. 2970 2971It is recommended that this parameter be turned on to speed access 2972to shared executables (and also to test the code :-). 2973 2974For more discussions on level2 oplocks see the CIFS spec. 2975 2976Currently, if link(bf("kernel oplocks"))(kerneloplocks) are supported 2977then level2 oplocks are not granted (even if this parameter is set 2978to tt("true")). Note also, the link(bf("oplocks"))(oplocks) parameter must 2979be set to "true" on this share in order for this parameter to have any 2980effect. 2981 2982See also the link(bf("oplocks"))(oplocks) and link(bf("kernel oplocks"))(kerneloplocks) parameters. 2983 2984 bf(Default:) 2985tt( level2 oplocks = False) 2986 2987 bf(Example:) 2988tt( level2 oplocks = True) 2989 2990label(lmannounce) 2991dit(bf(lm announce (G))) 2992 2993This parameter determines if url(bf(nmbd))(nmbd.8.html) will produce 2994Lanman announce broadcasts that are needed by bf(OS/2) clients in order 2995for them to see the Samba server in their browse list. This parameter 2996can have three values, tt("true"), tt("false"), or tt("auto"). The 2997default is tt("auto"). If set to tt("false") Samba will never produce 2998these broadcasts. If set to tt("true") Samba will produce Lanman 2999announce broadcasts at a frequency set by the parameter link(bf("lm 3000interval"))(lminterval). If set to tt("auto") Samba will not send Lanman 3001announce broadcasts by default but will listen for them. If it hears 3002such a broadcast on the wire it will then start sending them at a 3003frequency set by the parameter link(bf("lm interval"))(lminterval). 3004 3005See also link(bf("lm interval"))(lminterval). 3006 3007 bf(Default:) 3008tt( lm announce = auto) 3009 3010 bf(Example:) 3011tt( lm announce = true) 3012 3013label(lminterval) 3014dit(bf(lm interval (G))) 3015 3016If Samba is set to produce Lanman announce broadcasts needed by 3017bf(OS/2) clients (see the link(bf("lm announce"))(lmannounce) 3018parameter) then this parameter defines the frequency in seconds with 3019which they will be made. If this is set to zero then no Lanman 3020announcements will be made despite the setting of the link(bf("lm 3021announce"))(lmannounce) parameter. 3022 3023See also link(bf("lm announce"))(lmannounce). 3024 3025 bf(Default:) 3026tt( lm interval = 60) 3027 3028 bf(Example:) 3029tt( lm interval = 120) 3030 3031label(loadprinters) 3032dit(bf(load printers (G))) 3033 3034A boolean variable that controls whether all printers in the printcap 3035will be loaded for browsing by default. See the 3036link(bf("printers"))(printers) section for more details. 3037 3038 bf(Default:) 3039tt( load printers = yes) 3040 3041 bf(Example:) 3042tt( load printers = no) 3043 3044label(localmaster) 3045dit(bf(local master (G))) 3046 3047This option allows url(bf(nmbd))(nmbd.8.html) to try and become a 3048local master browser on a subnet. If set to False then 3049url(bf(nmbd))(nmbd.8.html) will not attempt to become a local master 3050browser on a subnet and will also lose in all browsing elections. By 3051default this value is set to true. Setting this value to true doesn't 3052mean that Samba will em(become) the local master browser on a subnet, 3053just that url(bf(nmbd))(nmbd.8.html) will em(participate) in 3054elections for local master browser. 3055 3056Setting this value to False will cause url(bf(nmbd))(nmbd.8.html) 3057em(never) to become a local master browser. 3058 3059 bf(Default:) 3060tt( local master = yes) 3061 3062label(lock dir) 3063dit(bf(lock dir (G))) 3064 3065Synonym for link(bf("lock directory"))(lockdirectory). 3066 3067label(lockdirectory) 3068dit(bf(lock directory (G))) 3069 3070This option specifies the directory where lock files will be placed. 3071The lock files are used to implement the link(bf("max 3072connections"))(maxconnections) option. 3073 3074 bf(Default:) 3075tt( lock directory = /tmp/samba) 3076 3077 bf(Example:) 3078tt( lock directory = /usr/local/samba/var/locks) 3079 3080label(locking) 3081dit(bf(locking (S))) 3082 3083This controls whether or not locking will be performed by the server 3084in response to lock requests from the client. 3085 3086If tt("locking = no"), all lock and unlock requests will appear to 3087succeed and all lock queries will indicate that the queried lock is 3088clear. 3089 3090If tt("locking = yes"), real locking will be performed by the server. 3091 3092This option em(may) be useful for read-only filesystems which em(may) 3093not need locking (such as cdrom drives), although setting this 3094parameter of tt("no") is not really recommended even in this case. 3095 3096Be careful about disabling locking either globally or in a specific 3097service, as lack of locking may result in data corruption. You should 3098never need to set this parameter. 3099 3100 bf(Default:) 3101tt( locking = yes) 3102 3103 bf(Example:) 3104tt( locking = no) 3105 3106label(logfile) 3107dit(bf(log file (G))) 3108 3109This options allows you to override the name of the Samba log file 3110(also known as the debug file). 3111 3112This option takes the standard substitutions, allowing you to have 3113separate log files for each user or machine. 3114 3115 bf(Example:) 3116tt( log file = /usr/local/samba/var/log.%m) 3117 3118label(loglevel) 3119dit(bf(log level (G))) 3120 3121Synonym for link(bf("debug level"))(debuglevel). 3122 3123label(logondrive) 3124dit(bf(logon drive (G))) 3125 3126This parameter specifies the local path to which the home directory 3127will be connected (see link(bf("logon home"))(logonhome)) and is only 3128used by NT Workstations. 3129 3130Note that this option is only useful if Samba is set up as a 3131link(bf(logon server))(domainlogons). 3132 3133 bf(Example:) 3134tt( logon drive = h:) 3135 3136label(logonhome) 3137dit(bf(logon home (G))) 3138 3139This parameter specifies the home directory location when a Win95/98 or 3140NT Workstation logs into a Samba PDC. It allows you to do 3141 3142tt("NET USE H: /HOME") 3143 3144from a command prompt, for example. 3145 3146This option takes the standard substitutions, allowing you to have 3147separate logon scripts for each user or machine. 3148 3149This parameter can be used with Win9X workstations to ensure that 3150roaming profiles are stored in a subdirectory of the user's home 3151directory. This is done in the following way: 3152 3153tt(" logon home = \\%L\%U\profile") 3154 3155This tells Samba to return the above string, with substitutions made 3156when a client requests the info, generally in a NetUserGetInfo request. 3157Win9X clients truncate the info to \\server\share when a user does tt("net use /home"), 3158but use the whole string when dealing with profiles. 3159 3160Note that in prior versions of Samba, the tt("logon path") was returned rather than 3161tt("logon home"). This broke tt("net use /home") but allowed profiles outside the 3162home directory. The current implementation is correct, and can be used for profiles 3163if you use the above trick. 3164 3165Note that this option is only useful if Samba is set up as a 3166link(bf(logon server))(domainlogons). 3167 3168 bf(Example:) 3169tt( logon home = "\\remote_smb_server\%U") 3170 3171 bf(Default:) 3172tt( logon home = "\\%N\%U") 3173 3174label(logonpath) 3175dit(bf(logon path (G))) 3176 3177This parameter specifies the home directory where roaming profiles 3178(NTuser.dat etc files for Windows NT) are stored. Contrary to previous 3179versions of these manual pages, it has nothing to do with Win 9X roaming 3180profiles. To find out how to handle roaming profiles for Win 9X system, see 3181the tt("logon home") parameter. 3182 3183This option takes the standard substitutions, allowing you to have 3184separate logon scripts for each user or machine. It also specifies 3185the directory from which the tt("application data"), (tt("desktop"), tt("start menu"), 3186tt("network neighborhood"), tt("programs") and other folders, and their 3187contents, are loaded and displayed on your Windows NT client. 3188 3189The share and the path must be readable by the user for the 3190preferences and directories to be loaded onto the Windows NT 3191client. The share must be writeable when the logs in for the first 3192time, in order that the Windows NT client can create the NTuser.dat 3193and other directories. 3194 3195Thereafter, the directories and any of the contents can, if required, be 3196made read-only. It is not advisable that the NTuser.dat file be made 3197read-only - rename it to NTuser.man to achieve the desired effect (a 3198em(MAN)datory profile). 3199 3200Windows clients can sometimes maintain a connection to the [homes] 3201share, even though there is no user logged in. Therefore, it is vital 3202that the logon path does not include a reference to the homes share 3203(i.e. setting this parameter to tt(\\%N\HOMES\profile_path) will cause 3204problems). 3205 3206This option takes the standard substitutions, allowing you to have 3207separate logon scripts for each user or machine. 3208 3209Note that this option is only useful if Samba is set up as a 3210link(bf(logon server))(domainlogons). 3211 3212 bf(Default:) 3213tt( logon path = \\%N\%U\profile) 3214 3215 bf(Example:) 3216tt( logon path = \\PROFILESERVER\HOME_DIR\%U\PROFILE) 3217 3218label(logonscript) 3219dit(bf(logon script (G))) 3220 3221This parameter specifies the batch file (.bat) or NT command file 3222(.cmd) to be downloaded and run on a machine when a user successfully 3223logs in. The file must contain the DOS style cr/lf line endings. 3224Using a DOS-style editor to create the file is recommended. 3225 3226The script must be a relative path to the tt([netlogon]) service. If 3227the tt([netlogon]) service specifies a link(bf(path))(path) of 3228/usr/local/samba/netlogon, and logon script = STARTUP.BAT, then the 3229file that will be downloaded is: 3230 3231tt(/usr/local/samba/netlogon/STARTUP.BAT) 3232 3233The contents of the batch file is entirely your choice. A suggested 3234command would be to add tt(NET TIME \\SERVER /SET /YES), to force every 3235machine to synchronize clocks with the same time server. Another use 3236would be to add tt(NET USE U: \\SERVER\UTILS) for commonly used 3237utilities, or tt(NET USE Q: \\SERVER\ISO9001_QA) for example. 3238 3239Note that it is particularly important not to allow write access to 3240the tt([netlogon]) share, or to grant users write permission on the 3241batch files in a secure environment, as this would allow the batch 3242files to be arbitrarily modified and security to be breached. 3243 3244This option takes the standard substitutions, allowing you to have 3245separate logon scripts for each user or machine. 3246 3247Note that this option is only useful if Samba is set up as a 3248link(bf(logon server))(domainlogons). 3249 3250 bf(Example:) 3251tt( logon script = scripts\%U.bat) 3252 3253label(lppausecommand) 3254dit(bf(lppause command (S))) 3255 3256This parameter specifies the command to be executed on the server host 3257in order to stop printing or spooling a specific print job. 3258 3259This command should be a program or script which takes a printer name 3260and job number to pause the print job. One way of implementing this is 3261by using job priorities, where jobs having a too low priority won't be 3262sent to the printer. 3263 3264If a tt("%p") is given then the printername is put in its place. A 3265tt("%j") is replaced with the job number (an integer). On HPUX (see 3266link(bf(printing=hpux))(printing)), if the tt("-p%p") option is added 3267to the lpq command, the job will show up with the correct status, 3268i.e. if the job priority is lower than the set fence priority it will 3269have the PAUSED status, whereas if the priority is equal or higher it 3270will have the SPOOLED or PRINTING status. 3271 3272Note that it is good practice to include the absolute path in the 3273lppause command as the PATH may not be available to the server. 3274 3275See also the link(bf("printing"))(printing) parameter. 3276 3277 bf(Default:) 3278 Currently no default value is given to this string, unless the 3279value of the link(bf("printing"))(printing) parameter is tt(SYSV), in 3280which case the default is : 3281 3282tt( lp -i %p-%j -H hold) 3283 3284or if the value of the link(bf("printing"))(printing) parameter is tt(softq), 3285then the default is: 3286 3287tt( qstat -s -j%j -h) 3288 3289 bf(Example for HPUX:) 3290 lppause command = /usr/bin/lpalt %p-%j -p0 3291 3292label(lpqcachetime) 3293dit(bf(lpq cache time (G))) 3294 3295This controls how long lpq info will be cached for to prevent the 3296bf(lpq) command being called too often. A separate cache is kept for 3297each variation of the bf(lpq) command used by the system, so if you 3298use different bf(lpq) commands for different users then they won't 3299share cache information. 3300 3301The cache files are stored in tt(/tmp/lpq.xxxx) where xxxx is a hash of 3302the bf(lpq) command in use. 3303 3304The default is 10 seconds, meaning that the cached results of a 3305previous identical bf(lpq) command will be used if the cached data is 3306less than 10 seconds old. A large value may be advisable if your 3307bf(lpq) command is very slow. 3308 3309A value of 0 will disable caching completely. 3310 3311See also the link(bf("printing"))(printing) parameter. 3312 3313 bf(Default:) 3314tt( lpq cache time = 10) 3315 3316 bf(Example:) 3317tt( lpq cache time = 30) 3318 3319label(lpqcommand) 3320dit(bf(lpq command (S))) 3321 3322This parameter specifies the command to be executed on the server host 3323in order to obtain tt("lpq")-style printer status information. 3324 3325This command should be a program or script which takes a printer name 3326as its only parameter and outputs printer status information. 3327 3328Currently eight styles of printer status information are supported; 3329BSD, AIX, LPRNG, PLP, SYSV, HPUX, QNX and SOFTQ. This covers most UNIX 3330systems. You control which type is expected using the 3331link(bf("printing ="))(printing) option. 3332 3333Some clients (notably Windows for Workgroups) may not correctly send 3334the connection number for the printer they are requesting status 3335information about. To get around this, the server reports on the first 3336printer service connected to by the client. This only happens if the 3337connection number sent is invalid. 3338 3339If a tt(%p) is given then the printername is put in its place. Otherwise 3340it is placed at the end of the command. 3341 3342Note that it is good practice to include the absolute path in the bf(lpq 3343command) as the PATH may not be available to the server. 3344 3345See also the link(bf("printing"))(printing) parameter. 3346 3347 bf(Default:) 3348tt( depends on the setting of printing =) 3349 3350 bf(Example:) 3351tt( lpq command = /usr/bin/lpq %p) 3352 3353label(lpresumecommand) 3354dit(bf(lpresume command (S))) 3355 3356This parameter specifies the command to be executed on the server host 3357in order to restart or continue printing or spooling a specific print 3358job. 3359 3360This command should be a program or script which takes a printer name 3361and job number to resume the print job. See also the link(bf("lppause 3362command"))(lppausecommand) parameter. 3363 3364If a tt(%p) is given then the printername is put in its place. A 3365tt(%j) is replaced with the job number (an integer). 3366 3367Note that it is good practice to include the absolute path in the bf(lpresume 3368command) as the PATH may not be available to the server. 3369 3370See also the link(bf("printing"))(printing) parameter. 3371 3372 bf(Default:) 3373 3374 Currently no default value is given to this string, unless the 3375value of the link(bf("printing"))(printing) parameter is tt(SYSV), in 3376which case the default is : 3377 3378tt( lp -i %p-%j -H resume) 3379 3380or if the value of the link(bf("printing"))(printing) parameter is tt(softq), 3381then the default is: 3382 3383tt( qstat -s -j%j -r) 3384 3385 bf(Example for HPUX:) 3386tt( lpresume command = /usr/bin/lpalt %p-%j -p2) 3387 3388label(lprmcommand) 3389dit(bf(lprm command (S))) 3390 3391This parameter specifies the command to be executed on the server host 3392in order to delete a print job. 3393 3394This command should be a program or script which takes a printer name 3395and job number, and deletes the print job. 3396 3397If a tt(%p) is given then the printername is put in its place. A 3398tt(%j) is replaced with the job number (an integer). 3399 3400Note that it is good practice to include the absolute path in the 3401bf(lprm command) as the PATH may not be available to the server. 3402 3403See also the link(bf("printing"))(printing) parameter. 3404 3405 bf(Default:) 3406tt( depends on the setting of "printing =") 3407 3408 bf(Example 1:) 3409tt( lprm command = /usr/bin/lprm -P%p %j) 3410 3411 bf(Example 2:) 3412tt( lprm command = /usr/bin/cancel %p-%j) 3413 3414label(machinepasswordtimeout) 3415dit(bf(machine password timeout (G))) 3416 3417If a Samba server is a member of an Windows NT Domain (see the 3418link(bf("security=domain"))(securityequaldomain)) parameter) then 3419periodically a running url(bf(smbd))(smbd.8.html) process will try and 3420change the bf(MACHINE ACCOUNT PASWORD) stored in the file called 3421tt(<Domain>.<Machine>.mac) where tt(<Domain>) is the name of the 3422Domain we are a member of and tt(<Machine>) is the primary 3423link(bf("NetBIOS name"))(netbiosname) of the machine 3424url(bf(smbd))(smbd.8.html) is running on. This parameter specifies how 3425often this password will be changed, in seconds. The default is one 3426week (expressed in seconds), the same as a Windows NT Domain member 3427server. 3428 3429See also url(bf(smbpasswd (8)))(smbpasswd.8.html), and the 3430link(bf("security=domain"))(securityequaldomain)) parameter. 3431 3432 bf(Default:) 3433tt( machine password timeout = 604800) 3434 3435label(magicoutput) 3436dit(bf(magic output (S))) 3437 3438This parameter specifies the name of a file which will contain output 3439created by a magic script (see the link(bf("magic 3440script"))(magicscript) parameter below). 3441 3442Warning: If two clients use the same link(bf("magic 3443script"))(magicscript) in the same directory the output file content 3444is undefined. 3445 3446 bf(Default:) 3447tt( magic output = <magic script name>.out) 3448 3449 bf(Example:) 3450tt( magic output = myfile.txt) 3451 3452label(magicscript) 3453dit(bf(magic script (S))) 3454 3455This parameter specifies the name of a file which, if opened, will be 3456executed by the server when the file is closed. This allows a UNIX 3457script to be sent to the Samba host and executed on behalf of the 3458connected user. 3459 3460Scripts executed in this way will be deleted upon completion, 3461permissions permitting. 3462 3463If the script generates output, output will be sent to the file 3464specified by the link(bf("magic output"))(magicoutput) parameter (see 3465above). 3466 3467Note that some shells are unable to interpret scripts containing 3468carriage-return-linefeed instead of linefeed as the end-of-line 3469marker. Magic scripts must be executable em("as is") on the host, 3470which for some hosts and some shells will require filtering at the DOS 3471end. 3472 3473Magic scripts are em(EXPERIMENTAL) and should em(NOT) be relied upon. 3474 3475 bf(Default:) 3476tt( None. Magic scripts disabled.) 3477 3478 bf(Example:) 3479tt( magic script = user.csh) 3480 3481label(manglecase) 3482dit(bf(mangle case (S))) 3483 3484See the section on link(bf("NAME MANGLING"))(NAMEMANGLING). 3485 3486label(manglelocks) 3487dit(bf(mangle locks (S))) 3488 3489This option is was introduced with Samba 2.0.4 and above and has been 3490removed in Samba 2.0.6 as Samba now dynamically configures such things 3491on 32 bit systems. 3492 3493label(mangledmap) 3494dit(bf(mangled map (S))) 3495 3496This is for those who want to directly map UNIX file names which can 3497not be represented on Windows/DOS. The mangling of names is not always 3498what is needed. In particular you may have documents with file 3499extensions that differ between DOS and UNIX. For example, under UNIX 3500it is common to use tt(".html") for HTML files, whereas under 3501Windows/DOS tt(".htm") is more commonly used. 3502 3503So to map tt("html") to tt("htm") you would use: 3504 3505tt( mangled map = (*.html *.htm)) 3506 3507One very useful case is to remove the annoying tt(";1") off the ends 3508of filenames on some CDROMS (only visible under some UNIXs). To do 3509this use a map of (*;1 *). 3510 3511 bf(default:) 3512tt( no mangled map) 3513 3514 bf(Example:) 3515tt( mangled map = (*;1 *)) 3516 3517label(manglednames) 3518dit(bf(mangled names (S))) 3519 3520This controls whether non-DOS names under UNIX should be mapped to 3521DOS-compatible names ("mangled") and made visible, or whether non-DOS 3522names should simply be ignored. 3523 3524See the section on link(bf("NAME MANGLING"))(NAMEMANGLING) for details 3525on how to control the mangling process. 3526 3527If mangling is used then the mangling algorithm is as follows: 3528 3529startit() 3530 3531it() The first (up to) five alphanumeric characters before the 3532rightmost dot of the filename are preserved, forced to upper case, and 3533appear as the first (up to) five characters of the mangled name. 3534 3535it() A tilde tt("~") is appended to the first part of the mangled 3536name, followed by a two-character unique sequence, based on the 3537original root name (i.e., the original filename minus its final 3538extension). The final extension is included in the hash calculation 3539only if it contains any upper case characters or is longer than three 3540characters. 3541 3542Note that the character to use may be specified using the 3543link(bf("mangling char"))(manglingchar) option, if you don't like 3544tt('~'). 3545 3546it() The first three alphanumeric characters of the final extension 3547are preserved, forced to upper case and appear as the extension of the 3548mangled name. The final extension is defined as that part of the 3549original filename after the rightmost dot. If there are no dots in the 3550filename, the mangled name will have no extension (except in the case 3551of link(bf("hidden files"))(hidefiles) - see below). 3552 3553it() Files whose UNIX name begins with a dot will be presented as DOS 3554hidden files. The mangled name will be created as for other filenames, 3555but with the leading dot removed and tt("___") as its extension regardless 3556of actual original extension (that's three underscores). 3557 3558endit() 3559 3560The two-digit hash value consists of upper case alphanumeric 3561characters. 3562 3563This algorithm can cause name collisions only if files in a directory 3564share the same first five alphanumeric characters. The probability of 3565such a clash is 1/1300. 3566 3567The name mangling (if enabled) allows a file to be copied between UNIX 3568directories from Windows/DOS while retaining the long UNIX 3569filename. UNIX files can be renamed to a new extension from 3570Windows/DOS and will retain the same basename. Mangled names do not 3571change between sessions. 3572 3573 bf(Default:) 3574tt( mangled names = yes) 3575 3576 bf(Example:) 3577tt( mangled names = no) 3578 3579label(manglingchar) 3580dit(bf(mangling char (S))) 3581 3582This controls what character is used as the em("magic") character in 3583link(bf(name mangling))(manglednames). The default is a tt('~') but 3584this may interfere with some software. Use this option to set it to 3585whatever you prefer. 3586 3587 bf(Default:) 3588tt( mangling char = ~) 3589 3590 bf(Example:) 3591tt( mangling char = ^) 3592 3593label(mangledstack) 3594dit(bf(mangled stack (G))) 3595 3596This parameter controls the number of mangled names that should be 3597cached in the Samba server url(bf(smbd))(smbd.8.html). 3598 3599This stack is a list of recently mangled base names (extensions are 3600only maintained if they are longer than 3 characters or contains upper 3601case characters). 3602 3603The larger this value, the more likely it is that mangled names can be 3604successfully converted to correct long UNIX names. However, large 3605stack sizes will slow most directory access. Smaller stacks save 3606memory in the server (each stack element costs 256 bytes). 3607 3608It is not possible to absolutely guarantee correct long file names, so 3609be prepared for some surprises! 3610 3611 bf(Default:) 3612tt( mangled stack = 50) 3613 3614 bf(Example:) 3615tt( mangled stack = 100) 3616 3617label(maparchive) 3618dit(bf(map archive (S))) 3619 3620This controls whether the DOS archive attribute should be mapped to 3621the UNIX owner execute bit. The DOS archive bit is set when a file 3622has been modified since its last backup. One motivation for this 3623option it to keep Samba/your PC from making any file it touches from 3624becoming executable under UNIX. This can be quite annoying for shared 3625source code, documents, etc... 3626 3627Note that this requires the link(bf("create mask"))(createmask) 3628parameter to be set such that owner execute bit is not masked out 3629(i.e. it must include 100). See the parameter link(bf("create 3630mask"))(createmask) for details. 3631 3632 bf(Default:) 3633tt( map archive = yes) 3634 3635 bf(Example:) 3636tt( map archive = no) 3637 3638label(maphidden) 3639dit(bf(map hidden (S))) 3640 3641This controls whether DOS style hidden files should be mapped to the 3642UNIX world execute bit. 3643 3644Note that this requires the link(bf("create mask"))(createmask) to be 3645set such that the world execute bit is not masked out (i.e. it must 3646include 001). See the parameter link(bf("create mask"))(createmask) 3647for details. 3648 3649 bf(Default:) 3650tt( map hidden = no) 3651 3652 bf(Example:) 3653tt( map hidden = yes) 3654 3655label(mapsystem) 3656dit(bf(map system (S))) 3657 3658This controls whether DOS style system files should be mapped to the 3659UNIX group execute bit. 3660 3661Note that this requires the link(bf("create mask"))(createmask) to be 3662set such that the group execute bit is not masked out (i.e. it must 3663include 010). See the parameter link(bf("create mask"))(createmask) 3664for details. 3665 3666 bf(Default:) 3667tt( map system = no) 3668 3669 bf(Example:) 3670tt( map system = yes) 3671 3672label(maptoguest) 3673dit(bf(map to guest (G))) 3674 3675This parameter is only useful in link(bf(security))(security) modes 3676other than link(bf("security=share"))(securityequalshare) - i.e. user, 3677server, and domain. 3678 3679This parameter can take three different values, which tell 3680url(bf(smbd))(smbd.8.html) what to do with user login requests that 3681don't match a valid UNIX user in some way. 3682 3683The three settings are : 3684 3685startit() 3686 3687it() bf("Never") - Means user login requests with an invalid password 3688are rejected. This is the default. 3689 3690it() bf("Bad User") - Means user logins with an invalid password are 3691rejected, unless the username does not exist, in which case it is 3692treated as a guest login and mapped into the link(bf("guest 3693account"))(guestaccount). 3694 3695it() bf("Bad Password") - Means user logins with an invalid 3696password are treated as a guest login and mapped into the 3697link(bf("guest account"))(guestaccount). Note that this can 3698cause problems as it means that any user incorrectly typing their 3699password will be silently logged on a bf("guest") - and 3700will not know the reason they cannot access files they think 3701they should - there will have been no message given to them 3702that they got their password wrong. Helpdesk services will 3703em(*hate*) you if you set the bf("map to guest") parameter 3704this way :-). 3705 3706endit() 3707 3708Note that this parameter is needed to set up bf("Guest") share 3709services when using link(bf(security))(security) modes other than 3710share. This is because in these modes the name of the resource being 3711requested is em(*not*) sent to the server until after the server has 3712successfully authenticated the client so the server cannot make 3713authentication decisions at the correct time (connection to the 3714share) for bf("Guest") shares. 3715 3716For people familiar with the older Samba releases, this parameter 3717maps to the old compile-time setting of the GUEST_SESSSETUP value 3718in local.h. 3719 3720 bf(Default:) 3721tt( map to guest = Never) 3722 bf(Example): 3723tt( map to guest = Bad User) 3724 3725label(maxconnections) 3726dit(bf(max connections (S))) 3727 3728This option allows the number of simultaneous connections to a service 3729to be limited. If bf("max connections") is greater than 0 then 3730connections will be refused if this number of connections to the 3731service are already open. A value of zero mean an unlimited number of 3732connections may be made. 3733 3734Record lock files are used to implement this feature. The lock files 3735will be stored in the directory specified by the link(bf("lock 3736directory"))(lockdirectory) option. 3737 3738 bf(Default:) 3739tt( max connections = 0) 3740 3741 bf(Example:) 3742tt( max connections = 10) 3743 3744label(maxdisksize) 3745dit(bf(max disk size (G))) 3746 3747This option allows you to put an upper limit on the apparent size of 3748disks. If you set this option to 100 then all shares will appear to be 3749not larger than 100 MB in size. 3750 3751Note that this option does not limit the amount of data you can put on 3752the disk. In the above case you could still store much more than 100 3753MB on the disk, but if a client ever asks for the amount of free disk 3754space or the total disk size then the result will be bounded by the 3755amount specified in bf("max disk size"). 3756 3757This option is primarily useful to work around bugs in some pieces of 3758software that can't handle very large disks, particularly disks over 37591GB in size. 3760 3761A bf("max disk size") of 0 means no limit. 3762 3763 bf(Default:) 3764tt( max disk size = 0) 3765 3766 bf(Example:) 3767tt( max disk size = 1000) 3768 3769label(maxlogsize) 3770dit(bf(max log size (G))) 3771 3772This option (an integer in kilobytes) specifies the max size the log 3773file should grow to. Samba periodically checks the size and if it is 3774exceeded it will rename the file, adding a tt(".old") extension. 3775 3776A size of 0 means no limit. 3777 3778 bf(Default:) 3779tt( max log size = 5000) 3780 3781 bf(Example:) 3782tt( max log size = 1000) 3783 3784label(maxmux) 3785dit(bf(max mux (G))) 3786 3787This option controls the maximum number of outstanding simultaneous 3788SMB operations that samba tells the client it will allow. You should 3789never need to set this parameter. 3790 3791 bf(Default:) 3792tt( max mux = 50) 3793 3794label(maxopenfiles) 3795dit(bf(max open files (G))) 3796 3797This parameter limits the maximum number of open files that one 3798url(bf(smbd))(smbd.8.html) file serving process may have open for 3799a client at any one time. The default for this parameter is set 3800very high (10,000) as Samba uses only one bit per unopened file. 3801 3802The limit of the number of open files is usually set by the 3803UNIX per-process file descriptor limit rather than this parameter 3804so you should never need to touch this parameter. 3805 3806 bf(Default:) 3807tt( max open files = 10000) 3808 3809label(maxpacket) 3810dit(bf(max packet (G))) 3811 3812Synonym for link(bf("packet size"))(packetsize). 3813 3814label(maxttl) 3815dit(bf(max ttl (G))) 3816 3817This option tells url(bf(nmbd))(nmbd.8.html) what the default 'time 3818to live' of NetBIOS names should be (in seconds) when 3819url(bf(nmbd))(nmbd.8.html) is requesting a name using either a 3820broadcast packet or from a WINS server. You should never need to 3821change this parameter. The default is 3 days. 3822 3823 bf(Default:) 3824tt( max ttl = 259200) 3825 3826label(maxwinsttl) 3827dit(bf(max wins ttl (G))) 3828 3829This option tells url(bf(nmbd))(nmbd.8.html) when acting as a WINS 3830server link(bf((wins support =true)))(winssupport) what the maximum 3831'time to live' of NetBIOS names that url(bf(nmbd))(nmbd.8.html) will 3832grant will be (in seconds). You should never need to change this 3833parameter. The default is 6 days (518400 seconds). 3834 3835See also the link(bf("min wins ttl"))(minwinsttl) parameter. 3836 3837 bf(Default:) 3838tt( max wins ttl = 518400) 3839 3840label(maxxmit) 3841dit(bf(max xmit (G))) 3842 3843This option controls the maximum packet size that will be negotiated 3844by Samba. The default is 65535, which is the maximum. In some cases 3845you may find you get better performance with a smaller value. A value 3846below 2048 is likely to cause problems. 3847 3848 bf(Default:) 3849tt( max xmit = 65535) 3850 3851 bf(Example:) 3852tt( max xmit = 8192) 3853 3854label(messagecommand) 3855dit(bf(message command (G))) 3856 3857This specifies what command to run when the server receives a WinPopup 3858style message. 3859 3860This would normally be a command that would deliver the message 3861somehow. How this is to be done is up to your imagination. 3862 3863An example is: 3864 3865tt( message command = csh -c 'xedit %s;rm %s' &) 3866 3867This delivers the message using bf(xedit), then removes it 3868afterwards. em(NOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN 3869IMMEDIATELY). That's why I have the tt('&') on the end. If it doesn't 3870return immediately then your PCs may freeze when sending messages 3871(they should recover after 30secs, hopefully). 3872 3873All messages are delivered as the global guest user. The command takes 3874the standard substitutions, although link(bf(%u))(percentu) won't work 3875(link(bf(%U))(percentU) may be better in this case). 3876 3877Apart from the standard substitutions, some additional ones apply. In 3878particular: 3879 3880startit() 3881 3882it() tt("%s") = the filename containing the message. 3883 3884it() tt("%t") = the destination that the message was sent to (probably the server 3885name). 3886 3887it() tt("%f") = who the message is from. 3888 3889endit() 3890 3891You could make this command send mail, or whatever else takes your 3892fancy. Please let us know of any really interesting ideas you have. 3893 3894Here's a way of sending the messages as mail to root: 3895 3896tt(message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s) 3897 3898If you don't have a message command then the message won't be 3899delivered and Samba will tell the sender there was an 3900error. Unfortunately WfWg totally ignores the error code and carries 3901on regardless, saying that the message was delivered. 3902 3903If you want to silently delete it then try: 3904 3905tt("message command = rm %s"). 3906 3907 bf(Default:) 3908tt( no message command) 3909 3910 bf(Example:) 3911tt( message command = csh -c 'xedit %s;rm %s' &) 3912 3913label(minprintspace) 3914dit(bf(min print space (S))) 3915 3916This sets the minimum amount of free disk space that must be available 3917before a user will be able to spool a print job. It is specified in 3918kilobytes. The default is 0, which means a user can always spool a print 3919job. 3920 3921See also the link(bf(printing))(printing) parameter. 3922 3923 bf(Default:) 3924tt( min print space = 0) 3925 3926 bf(Example:) 3927tt( min print space = 2000) 3928 3929label(minpasswdlength) 3930dit(bf(min passwd length (G))) 3931 3932Synonym for link(bf("min password length"))(minpasswordlength). 3933 3934label(minpasswordlength) 3935dit(bf(min password length (G))) 3936 3937This option sets the minimum length in characters of a plaintext password 3938than smbd will accept when performing UNIX password changing. 3939 3940See also link(bf("unix password sync"))(unixpasswordsync), 3941link(bf("passwd program"))(passwdprogram) and link(bf("passwd chat 3942debug"))(passwdchatdebug). 3943 3944 bf(Default:) 3945tt( min password length = 5) 3946 3947 3948label(minwinsttl) 3949dit(bf(min wins ttl (G))) 3950 3951This option tells url(bf(nmbd))(nmbd.8.html) when acting as a WINS 3952server link(bf((wins support = true)))(winssupport) what the minimum 3953'time to live' of NetBIOS names that url(bf(nmbd))(nmbd.8.html) will 3954grant will be (in seconds). You should never need to change this 3955parameter. The default is 6 hours (21600 seconds). 3956 3957 bf(Default:) 3958tt( min wins ttl = 21600) 3959 3960 3961label(nameresolveorder) 3962dit(bf(name resolve order (G))) 3963 3964This option is used by the programs in the Samba suite to determine 3965what naming services and in what order to resolve host names to IP 3966addresses. The option takes a space separated string of different name 3967resolution options. 3968 3969The options are :"lmhosts", "host", "wins" and "bcast". They cause 3970names to be resolved as follows : 3971 3972startit() 3973 3974it() bf(lmhosts) : Lookup an IP address in the Samba lmhosts file. 3975If the line in lmhosts has no name type attached to the NetBIOS 3976name (see the url(bf(lmhosts (5)))(lmhosts.5.html) for details) then 3977any name type matches for lookup. 3978 3979it() bf(host) : Do a standard host name to IP address resolution, 3980using the system /etc/hosts, NIS, or DNS lookups. This method of name 3981resolution is operating system depended for instance on IRIX or 3982Solaris this may be controlled by the em(/etc/nsswitch.conf) file). 3983Note that this method is only used if the NetBIOS name type being 3984queried is the 0x20 (server) name type, otherwise it is ignored. 3985 3986it() bf(wins) : Query a name with the IP address listed in the 3987link(bf(wins server))(winsserver) parameter. If no WINS server has 3988been specified this method will be ignored. 3989 3990it() bf(bcast) : Do a broadcast on each of the known local interfaces 3991listed in the link(bf(interfaces))(interfaces) parameter. This is the 3992least reliable of the name resolution methods as it depends on the 3993target host being on a locally connected subnet. 3994 3995endit() 3996 3997 bf(Default:) 3998tt( name resolve order = lmhosts host wins bcast) 3999 4000 bf(Example:) 4001tt( name resolve order = lmhosts bcast host) 4002 4003This will cause the local lmhosts file to be examined first, followed 4004by a broadcast attempt, followed by a normal system hostname lookup. 4005 4006label(netbiosaliases) 4007dit(bf(netbios aliases (G))) 4008 4009This is a list of NetBIOS names that url(bf(nmbd))(nmbd.8.html) will 4010advertise as additional names by which the Samba server is known. This 4011allows one machine to appear in browse lists under multiple names. If 4012a machine is acting as a link(bf(browse server))(localmaster) or 4013link(bf(logon server))(domainlogons) none of these names will be 4014advertised as either browse server or logon servers, only the primary 4015name of the machine will be advertised with these capabilities. 4016 4017See also link(bf("netbios name"))(netbiosname). 4018 4019 bf(Default:) 4020tt( empty string (no additional names)) 4021 4022 bf(Example:) 4023tt( netbios aliases = TEST TEST1 TEST2) 4024 4025label(netbiosname) 4026dit(bf(netbios name (G))) 4027 4028This sets the NetBIOS name by which a Samba server is known. By 4029default it is the same as the first component of the host's DNS name. 4030If a machine is a link(bf(browse server))(localmaster) or 4031link(bf(logon server))(domainlogons) this name (or the first component 4032of the hosts DNS name) will be the name that these services are 4033advertised under. 4034 4035See also link(bf("netbios aliases"))(netbiosaliases). 4036 4037 bf(Default:) 4038tt( Machine DNS name.) 4039 4040 bf(Example:) 4041tt( netbios name = MYNAME) 4042 4043label(netbiosscope) 4044dit(bf(netbios scope (G))) 4045 4046This sets the NetBIOS scope that Samba will operate under. This should 4047not be set unless every machine on your LAN also sets this value. 4048 4049label(nishomedir) 4050dit(bf(nis homedir (G))) 4051 4052Get the home share server from a NIS map. For UNIX systems that use an 4053automounter, the user's home directory will often be mounted on a 4054workstation on demand from a remote server. 4055 4056When the Samba logon server is not the actual home directory server, 4057but is mounting the home directories via NFS then two network hops 4058would be required to access the users home directory if the logon 4059server told the client to use itself as the SMB server for home 4060directories (one over SMB and one over NFS). This can be very 4061slow. 4062 4063This option allows Samba to return the home share as being on a 4064different server to the logon server and as long as a Samba daemon is 4065running on the home directory server, it will be mounted on the Samba 4066client directly from the directory server. When Samba is returning the 4067home share to the client, it will consult the NIS map specified in 4068link(bf("homedir map"))(homedirmap) and return the server listed 4069there. 4070 4071Note that for this option to work there must be a working NIS 4072system and the Samba server with this option must also be a 4073link(bf(logon server))(domainlogons). 4074 4075 bf(Default:) 4076tt( nis homedir = false) 4077 4078 bf(Example:) 4079tt( nis homedir = true) 4080 4081label(ntaclsupport) 4082dit(bf(nt acl support (G))) 4083 4084This boolean parameter controls whether url(bf(smbd))(smbd.8.html) 4085will attempt to map UNIX permissions into Windows NT access control lists. 4086 4087 bf(Default:) 4088tt( nt acl support = yes) 4089 4090 bf(Example:) 4091tt( nt acl support = no) 4092 4093label(ntpipesupport) 4094dit(bf(nt pipe support (G))) 4095 4096This boolean parameter controls whether url(bf(smbd))(smbd.8.html) 4097will allow Windows NT clients to connect to the NT SMB specific 4098tt(IPC$) pipes. This is a developer debugging option and can be left 4099alone. 4100 4101 bf(Default:) 4102tt( nt pipe support = yes) 4103 4104label(ntsmbsupport) 4105dit(bf(nt smb support (G))) 4106 4107This boolean parameter controls whether url(bf(smbd))(smbd.8.html) 4108will negotiate NT specific SMB support with Windows NT 4109clients. Although this is a developer debugging option and should be 4110left alone, benchmarking has discovered that Windows NT clients give 4111faster performance with this option set to tt("no"). This is still 4112being investigated. If this option is set to tt("no") then Samba 4113offers exactly the same SMB calls that versions prior to Samba2.0 4114offered. This information may be of use if any users are having 4115problems with NT SMB support. 4116 4117 bf(Default:) 4118tt( nt support = yes) 4119 4120label(nullpasswords) 4121dit(bf(null passwords (G))) 4122 4123Allow or disallow client access to accounts that have null passwords. 4124 4125See also url(bf(smbpasswd (5)))(smbpasswd.5.html). 4126 4127 bf(Default:) 4128tt( null passwords = no) 4129 4130 bf(Example:) 4131tt( null passwords = yes) 4132 4133label(olelockingcompatibility) 4134dit(bf(ole locking compatibility (G))) 4135 4136This parameter allows an administrator to turn off the byte range lock 4137manipulation that is done within Samba to give compatibility for OLE 4138applications. Windows OLE applications use byte range locking as a 4139form of inter-process communication, by locking ranges of bytes around 4140the 2^32 region of a file range. This can cause certain UNIX lock 4141managers to crash or otherwise cause problems. Setting this parameter 4142to tt("no") means you trust your UNIX lock manager to handle such cases 4143correctly. 4144 4145 bf(Default:) 4146tt( ole locking compatibility = yes) 4147 4148 bf(Example:) 4149tt( ole locking compatibility = no) 4150 4151label(onlyguest) 4152dit(bf(only guest (S))) 4153 4154A synonym for link(bf("guest only"))(guestonly). 4155 4156label(onlyuser) 4157dit(bf(only user (S))) 4158 4159This is a boolean option that controls whether connections with 4160usernames not in the link(bf(user=))(user) list will be allowed. By 4161default this option is disabled so a client can supply a username to 4162be used by the server. 4163 4164Note that this also means Samba won't try to deduce usernames from the 4165service name. This can be annoying for the link(bf([homes]))(homes) 4166section. To get around this you could use "link(bf(user))(user) = 4167link(bf(%S))(percentS)" which means your link(bf("user"))(user) list 4168will be just the service name, which for home directories is the name 4169of the user. 4170 4171See also the link(bf(user))(user) parameter. 4172 4173 bf(Default:) 4174tt( only user = False) 4175 4176 bf(Example:) 4177tt( only user = True) 4178 4179label(oplocks) 4180dit(bf(oplocks (S))) 4181 4182This boolean option tells smbd whether to issue oplocks (opportunistic 4183locks) to file open requests on this share. The oplock code can 4184dramatically (approx. 30% or more) improve the speed of access to files 4185on Samba servers. It allows the clients to aggressively cache files 4186locally and you may want to disable this option for unreliable network 4187environments (it is turned on by default in Windows NT Servers). For 4188more information see the file Speed.txt in the Samba docs/ directory. 4189 4190Oplocks may be selectively turned off on certain files on a per share basis. 4191See the 'veto oplock files' parameter. On some systems oplocks are recognized 4192by the underlying operating system. This allows data synchronization between 4193all access to oplocked files, whether it be via Samba or NFS or a local 4194UNIX process. See the link(bf(kernel oplocks))(kerneloplocks) parameter 4195for details. 4196 4197See also the link(bf("kernel oplocks"))(kerneloplocks) and 4198link(bf("level2 oplocks"))(level2oplocks) parameters. 4199 4200 bf(Default:) 4201tt( oplocks = True) 4202 4203 bf(Example:) 4204tt( oplocks = False) 4205 4206label(oplockbreakwaittime) 4207dit(bf(oplock break wait time (G))) 4208 4209This is a tuning parameter added due to bugs in both Windows 9x and WinNT. 4210If Samba responds to a client too quickly when that client issues an SMB that 4211can cause an oplock break request, then the client redirector can fail and 4212not respond to the break request. This tuning parameter (which is set in 4213milliseconds) is the amount of time Samba will wait before sending an 4214oplock break request to such (broken) clients. 4215 4216em(DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA 4217OPLOCK CODE). 4218 4219 bf(Default:) 4220tt( oplock break wait time = 10) 4221 4222label(oplockcontentionlimit) 4223dit(bf(oplock contention limit (S))) 4224 4225This is a em(very) advanced url(bf(smbd))(smbd.8.html) tuning option to improve 4226the efficiency of the granting of oplocks under multiple client contention for the same file. 4227 4228In brief it specifies a number, which causes smbd not to grant an oplock even 4229when requested if the approximate number of clients contending for an oplock on 4230the same file goes over this limit. This causes url(bf(smbd))(smbd.8.html) to 4231behave in a similar way to Windows NT. 4232 4233em(DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA 4234OPLOCK CODE). 4235 4236 bf(Default:) 4237tt( oplock contention limit = 2) 4238 4239label(oslevel) 4240dit(bf(os level (G))) 4241 4242This integer value controls what level Samba advertises itself as for 4243browse elections. The value of this parameter determines whether 4244url(bf(nmbd))(nmbd.8.html) has a chance of becoming a local master 4245browser for the link(bf(WORKGROUP))(workgroup) in the local broadcast 4246area. The default is zero, which means url(bf(nmbd))(nmbd.8.html) will 4247lose elections to Windows machines. See BROWSING.txt in the Samba 4248docs/ directory for details. 4249 4250 bf(Default:) 4251tt( os level = 20) 4252 4253 bf(Example:) 4254tt( os level = 65 ; This will win against any NT Server) 4255 4256label(packetsize) 4257dit(bf(packet size (G))) 4258 4259This is a deprecated parameter that has no effect on the current 4260Samba code. It is left in the parameter list to prevent breaking 4261old bf(smb.conf) files. 4262 4263label(panicaction) 4264dit(bf(panic action (G))) 4265 4266This is a Samba developer option that allows a system command to be 4267called when either url(bf(smbd))(smbd.8.html) or 4268url(bf(nmbd))(nmbd.8.html) crashes. This is usually used to draw 4269attention to the fact that a problem occurred. 4270 4271 bf(Default:) 4272tt( panic action = <empty string>) 4273 4274label(passwdchat) 4275dit(bf(passwd chat (G))) 4276 4277This string controls the em("chat") conversation that takes places 4278between url(bf(smbd))(smbd.8.html) and the local password changing 4279program to change the users password. The string describes a sequence 4280of response-receive pairs that url(bf(smbd))(smbd.8.html) uses to 4281determine what to send to the link(bf(passwd))(passwdprogram) program 4282and what to expect back. If the expected output is not received then 4283the password is not changed. 4284 4285This chat sequence is often quite site specific, depending on what 4286local methods are used for password control (such as NIS etc). 4287 4288The string can contain the macros tt("%o") and tt("%n") which are 4289substituted for the old and new passwords respectively. It can also 4290contain the standard macros tt("\n"), tt("\r"), tt("\t") and tt("\s") 4291to give line-feed, carriage-return, tab and space. 4292 4293The string can also contain a tt('*') which matches any sequence of 4294characters. 4295 4296Double quotes can be used to collect strings with spaces in them into 4297a single string. 4298 4299If the send string in any part of the chat sequence is a fullstop 4300tt(".") then no string is sent. Similarly, is the expect string is a 4301fullstop then no string is expected. 4302 4303Note that if the link(bf("unix password sync"))(unixpasswordsync) 4304parameter is set to true, then this sequence is called em(*AS ROOT*) 4305when the SMB password in the smbpasswd file is being changed, without 4306access to the old password cleartext. In this case the old password 4307cleartext is set to tt("") (the empty string). 4308 4309See also link(bf("unix password sync"))(unixpasswordsync), 4310link(bf("passwd program"))(passwdprogram) and link(bf("passwd chat 4311debug"))(passwdchatdebug). 4312 4313 bf(Example:) 4314verb( passwd chat = "*Enter OLD password*" %o\n "*Enter NEW password*" %n\n \ 4315 "*Reenter NEW password*" %n\n "*Password changed*" 4316) 4317 4318 bf(Default:) 4319verb( passwd chat = *old*password* %o\n *new*password* %n\n *new*password* %n\n *changed*) 4320 4321label(passwdchatdebug) 4322dit(bf(passwd chat debug (G))) 4323 4324This boolean specifies if the passwd chat script parameter is run in 4325tt("debug") mode. In this mode the strings passed to and received from 4326the passwd chat are printed in the url(bf(smbd))(smbd.8.html) log with 4327a link(bf("debug level"))(debuglevel) of 100. This is a dangerous 4328option as it will allow plaintext passwords to be seen in the 4329url(bf(smbd))(smbd.8.html) log. It is available to help Samba admins 4330debug their link(bf("passwd chat"))(passwdchat) scripts when calling 4331the link(bf("passwd program"))(passwdprogram) and should be turned off 4332after this has been done. This parameter is off by default. 4333 4334See also link(bf("passwd chat"))(passwdchat), link(bf("passwd 4335program"))(passwdprogram). 4336 4337 bf(Example:) 4338tt( passwd chat debug = True) 4339 4340 bf(Default:) 4341tt( passwd chat debug = False) 4342 4343label(passwdprogram) 4344dit(bf(passwd program (G))) 4345 4346The name of a program that can be used to set UNIX user passwords. 4347Any occurrences of link(bf(%u))(percentu) will be replaced with the 4348user name. The user name is checked for existence before calling the 4349password changing program. 4350 4351Also note that many passwd programs insist in em("reasonable") 4352passwords, such as a minimum length, or the inclusion of mixed case 4353chars and digits. This can pose a problem as some clients (such as 4354Windows for Workgroups) uppercase the password before sending it. 4355 4356em(Note) that if the link(bf("unix password sync"))(unixpasswordsync) 4357parameter is set to tt("True") then this program is called em(*AS 4358ROOT*) before the SMB password in the 4359url(bf(smbpasswd))(smbpasswd.5.html) file is changed. If this UNIX 4360password change fails, then url(bf(smbd))(smbd.8.html) will fail to 4361change the SMB password also (this is by design). 4362 4363If the link(bf("unix password sync"))(unixpasswordsync) parameter is 4364set this parameter em(MUST USE ABSOLUTE PATHS) for em(ALL) programs 4365called, and must be examined for security implications. Note that by 4366default link(bf("unix password sync"))(unixpasswordsync) is set to 4367tt("False"). 4368 4369See also link(bf("unix password sync"))(unixpasswordsync). 4370 4371 bf(Default:) 4372tt( passwd program = /bin/passwd) 4373 4374 bf(Example:) 4375tt( passwd program = /sbin/passwd %u) 4376 4377label(passwordlevel) 4378dit(bf(password level (G))) 4379 4380Some client/server combinations have difficulty with mixed-case 4381passwords. One offending client is Windows for Workgroups, which for 4382some reason forces passwords to upper case when using the LANMAN1 4383protocol, but leaves them alone when using COREPLUS! 4384 4385This parameter defines the maximum number of characters that may be 4386upper case in passwords. 4387 4388For example, say the password given was tt("FRED"). If bf(password 4389level) is set to 1, the following combinations would be tried if 4390tt("FRED") failed: 4391 4392tt("Fred"), tt("fred"), tt("fRed"), tt("frEd"), tt("freD") 4393 4394If bf(password level) was set to 2, the following combinations would 4395also be tried: 4396 4397tt("FRed"), tt("FrEd"), tt("FreD"), tt("fREd"), tt("fReD"), 4398tt("frED"), tt(..) 4399 4400And so on. 4401 4402The higher value this parameter is set to the more likely it is that a 4403mixed case password will be matched against a single case 4404password. However, you should be aware that use of this parameter 4405reduces security and increases the time taken to process a new 4406connection. 4407 4408A value of zero will cause only two attempts to be made - the password 4409as is and the password in all-lower case. 4410 4411 bf(Default:) 4412tt( password level = 0) 4413 4414 bf(Example:) 4415tt( password level = 4) 4416 4417label(passwordserver) 4418dit(bf(password server (G))) 4419 4420By specifying the name of another SMB server (such as a WinNT box) 4421with this option, and using link(bf("security = domain"))(security) or 4422link(bf("security = server"))(security) you can get Samba to do all 4423its username/password validation via a remote server. 4424 4425This options sets the name of the password server to use. It must be a 4426NetBIOS name, so if the machine's NetBIOS name is different from its 4427internet name then you may have to add its NetBIOS name to the lmhosts 4428file which is stored in the same directory as the bf(smb.conf) file. 4429 4430The name of the password server is looked up using the parameter 4431link(bf("name resolve order="))(nameresolveorder) and so may resolved 4432by any method and order described in that parameter. 4433 4434The password server much be a machine capable of using the "LM1.2X002" 4435or the "LM NT 0.12" protocol, and it must be in user level security 4436mode. 4437 4438NOTE: Using a password server means your UNIX box (running Samba) is 4439only as secure as your password server. em(DO NOT CHOOSE A PASSWORD 4440SERVER THAT YOU DON'T COMPLETELY TRUST). 4441 4442Never point a Samba server at itself for password serving. This will 4443cause a loop and could lock up your Samba server! 4444 4445The name of the password server takes the standard substitutions, but 4446probably the only useful one is link(bf(%m))(percentm), which means 4447the Samba server will use the incoming client as the password 4448server. If you use this then you better trust your clients, and you 4449better restrict them with hosts allow! 4450 4451If the link(bf("security"))(security) parameter is set to 4452bf("domain"), then the list of machines in this option must be a list 4453of Primary or Backup Domain controllers for the 4454link(bf(Domain))(workgroup) or the character tt(*), as the Samba server is cryptographicly 4455in that domain, and will use cryptographicly authenticated RPC calls 4456to authenticate the user logging on. The advantage of using 4457link(bf("security=domain"))(securityequaldomain) is that if you list 4458several hosts in the bf("password server") option then 4459url(bf(smbd))(smbd.8.html) will try each in turn till it finds one 4460that responds. This is useful in case your primary server goes down. 4461 4462If the bf("password server") option is set to the character tt(*), 4463then Samba will attempt to auto-locate the Primary or Backup Domain controllers 4464to authenticate against by doing a query for the name tt(WORKGROUP<1C>) 4465and then contacting each server returned in the list of IP addresses 4466from the link(bf(name resolution))(nameresolveorder) source. 4467 4468If the link(bf("security"))(security) parameter is set to 4469link(bf("server"))(securityequalserver), then there are different 4470restrictions that link(bf("security=domain"))(securityequaldomain) 4471doesn't suffer from: 4472 4473startit() 4474 4475it() You may list several password servers in the bf("password server") 4476parameter, however if an url(bf(smbd))(smbd.8.html) makes a connection 4477to a password server, and then the password server fails, no more 4478users will be able to be authenticated from this 4479url(bf(smbd))(smbd.8.html). This is a restriction of the SMB/CIFS 4480protocol when in link(bf("security=server"))(securityequalserver) mode 4481and cannot be fixed in Samba. 4482 4483it() If you are using a Windows NT server as your password server then 4484you will have to ensure that your users are able to login from the 4485Samba server, as when in 4486link(bf("security=server"))(securityequalserver) mode the network 4487logon will appear to come from there rather than from the users 4488workstation. 4489 4490endit() 4491 4492See also the link(bf("security"))(security) parameter. 4493 4494 bf(Default:) 4495tt( password server = <empty string>) 4496 4497 bf(Example:) 4498tt( password server = NT-PDC, NT-BDC1, NT-BDC2) 4499 4500 bf(Example:) 4501tt( password server = *) 4502 4503label(path) 4504dit(bf(path (S))) 4505 4506This parameter specifies a directory to which the user of the service 4507is to be given access. In the case of printable services, this is 4508where print data will spool prior to being submitted to the host for 4509printing. 4510 4511For a printable service offering guest access, the service should be 4512readonly and the path should be world-writeable and have the sticky bit 4513set. This is not mandatory of course, but you probably won't get the 4514results you expect if you do otherwise. 4515 4516Any occurrences of link(bf(%u))(percentu) in the path will be replaced 4517with the UNIX username that the client is using on this 4518connection. Any occurrences of link(bf(%m))(percentm) will be replaced 4519by the NetBIOS name of the machine they are connecting from. These 4520replacements are very useful for setting up pseudo home directories 4521for users. 4522 4523Note that this path will be based on link(bf("root dir"))(rootdir) if 4524one was specified. 4525 4526 bf(Default:) 4527tt( none) 4528 4529 bf(Example:) 4530tt( path = /home/fred) 4531 4532label(postexec) 4533dit(bf(postexec (S))) 4534 4535This option specifies a command to be run whenever the service is 4536disconnected. It takes the usual substitutions. The command may be run 4537as the root on some systems. 4538 4539An interesting example may be do unmount server resources: 4540 4541tt(postexec = /etc/umount /cdrom) 4542 4543See also link(bf(preexec))(preexec). 4544 4545 bf(Default:) 4546tt( none (no command executed)) 4547 4548 bf(Example:) 4549tt( postexec = echo "%u disconnected from %S from %m (%I)" >> /tmp/log) 4550 4551label(postscript) 4552dit(bf(postscript (S))) 4553 4554This parameter forces a printer to interpret the print files as 4555postscript. This is done by adding a tt(%!) to the start of print output. 4556 4557This is most useful when you have lots of PCs that persist in putting 4558a control-D at the start of print jobs, which then confuses your 4559printer. 4560 4561 bf(Default:) 4562tt( postscript = False) 4563 4564 bf(Example:) 4565tt( postscript = True) 4566 4567label(preexec) 4568dit(bf(preexec (S))) 4569 4570This option specifies a command to be run whenever the service is 4571connected to. It takes the usual substitutions. 4572 4573An interesting example is to send the users a welcome message every 4574time they log in. Maybe a message of the day? Here is an example: 4575 4576verb( 4577 preexec = csh -c 'echo \"Welcome to %S!\" | \ 4578 /usr/local/samba/bin/smbclient -M %m -I %I' & 4579) 4580 4581Of course, this could get annoying after a while :-) 4582 4583See also link(bf(preexec close))(preexecclose) and link(bf(postexec))(postexec). 4584 4585 bf(Default:) 4586tt( none (no command executed)) 4587 4588 bf(Example:) 4589tt( preexec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log) 4590 4591label(preexecclose) 4592dit(bf(preexec close (S))) 4593 4594This boolean option controls whether a non-zero return code from 4595link(bf("preexec"))(preexec) should close the service being connected to. 4596 4597 bf(Default:) 4598tt( preexec close = no) 4599 4600 bf(Example:) 4601tt( preexec close = yes) 4602 4603label(preferredmaster) 4604dit(bf(preferred master (G))) 4605 4606This boolean parameter controls if url(bf(nmbd))(nmbd.8.html) is a 4607preferred master browser for its workgroup. 4608 4609If this is set to true, on startup, url(bf(nmbd))(nmbd.8.html) will 4610force an election, and it will have a slight advantage in winning the 4611election. It is recommended that this parameter is used in 4612conjunction with link(bf("domain master = yes"))(domainmaster), so 4613that url(bf(nmbd))(nmbd.8.html) can guarantee becoming a domain 4614master. 4615 4616Use this option with caution, because if there are several hosts 4617(whether Samba servers, Windows 95 or NT) that are preferred master 4618browsers on the same subnet, they will each periodically and 4619continuously attempt to become the local master browser. This will 4620result in unnecessary broadcast traffic and reduced browsing 4621capabilities. 4622 4623See also link(bf(os level))(oslevel). 4624 4625 bf(Default:) 4626tt( preferred master = no) 4627 4628 bf(Example:) 4629tt( preferred master = yes) 4630 4631label(preferedmaster) 4632dit(bf(prefered master (G))) 4633 4634Synonym for link(bf("preferred master"))(preferredmaster) for people 4635who cannot spell :-). 4636 4637label(preload) 4638dit(bf(preload)) 4639Synonym for link(bf("auto services"))(autoservices). 4640 4641label(preservecase) 4642dit(bf(preserve case (S))) 4643 4644This controls if new filenames are created with the case that the 4645client passes, or if they are forced to be the tt("default") case. 4646 4647 bf(Default:) 4648tt( preserve case = yes) 4649 4650See the section on link(bf("NAME MANGLING"))(NAMEMANGLING) for a 4651fuller discussion. 4652 4653label(printcommand) 4654dit(bf(print command (S))) 4655 4656After a print job has finished spooling to a service, this command 4657will be used via a tt(system()) call to process the spool 4658file. Typically the command specified will submit the spool file to 4659the host's printing subsystem, but there is no requirement that this 4660be the case. The server will not remove the spool file, so whatever 4661command you specify should remove the spool file when it has been 4662processed, otherwise you will need to manually remove old spool files. 4663 4664The print command is simply a text string. It will be used verbatim, 4665with two exceptions: All occurrences of tt("%s") and tt("%f") will be 4666replaced by the appropriate spool file name, and all occurrences of 4667tt("%p") will be replaced by the appropriate printer name. The spool 4668file name is generated automatically by the server, the printer name 4669is discussed below. 4670 4671The print command em(MUST) contain at least one occurrence of tt("%s") 4672or tt("%f") - the tt("%p") is optional. At the time a job is 4673submitted, if no printer name is supplied the tt("%p") will be 4674silently removed from the printer command. 4675 4676If specified in the link(bf("[global]"))(global) section, the print 4677command given will be used for any printable service that does not 4678have its own print command specified. 4679 4680If there is neither a specified print command for a printable service 4681nor a global print command, spool files will be created but not 4682processed and (most importantly) not removed. 4683 4684Note that printing may fail on some UNIXs from the tt("nobody") 4685account. If this happens then create an alternative guest account that 4686can print and set the link(bf("guest account"))(guestaccount) in the 4687link(bf("[global]"))(global) section. 4688 4689You can form quite complex print commands by realizing that they are 4690just passed to a shell. For example the following will log a print 4691job, print the file, then remove it. Note that tt(';') is the usual 4692separator for command in shell scripts. 4693 4694tt(print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s) 4695 4696You may have to vary this command considerably depending on how you 4697normally print files on your system. The default for the parameter 4698varies depending on the setting of the link(bf("printing="))(printing) 4699parameter. 4700 4701 bf(Default:) 4702 For link(bf("printing="))(printing) BSD, AIX, QNX, LPRNG or PLP : 4703tt( print command = lpr -r -P%p %s) 4704 4705 For link(bf("printing="))(printing) SYS or HPUX : 4706tt( print command = lp -c -d%p %s; rm %s) 4707 4708 For link(bf("printing="))(printing) SOFTQ : 4709tt( print command = lp -d%p -s %s; rm %s) 4710 4711 bf(Example:) 4712tt( print command = /usr/local/samba/bin/myprintscript %p %s) 4713 4714label(printok) 4715dit(bf(print ok (S))) 4716 4717Synonym for link(bf(printable))(printable). 4718 4719label(printable) 4720dit(bf(printable (S))) 4721 4722If this parameter is tt("yes"), then clients may open, write to and 4723submit spool files on the directory specified for the service. 4724 4725Note that a printable service will ALWAYS allow writing to the service 4726path (user privileges permitting) via the spooling of print data. The 4727link(bf("writeable"))(writeable) parameter controls only non-printing 4728access to the resource. 4729 4730 bf(Default:) 4731tt( printable = no) 4732 4733 bf(Example:) 4734tt( printable = yes) 4735 4736label(printcap) 4737dit(bf(printcap (G))) 4738 4739Synonym for link(bf(printcapname))(printcapname). 4740 4741label(printcapname) 4742dit(bf(printcap name (G))) 4743 4744This parameter may be used to override the compiled-in default 4745printcap name used by the server (usually /etc/printcap). See the 4746discussion of the link(bf([printers]))(printers) section above for 4747reasons why you might want to do this. 4748 4749On System V systems that use bf(lpstat) to list available printers you 4750can use tt("printcap name = lpstat") to automatically obtain lists of 4751available printers. This is the default for systems that define SYSV 4752at configure time in Samba (this includes most System V based 4753systems). If bf("printcap name") is set to bf(lpstat) on these systems 4754then Samba will launch tt("lpstat -v") and attempt to parse the output 4755to obtain a printer list. 4756 4757A minimal printcap file would look something like this: 4758 4759verb( 4760 print1|My Printer 1 4761 print2|My Printer 2 4762 print3|My Printer 3 4763 print4|My Printer 4 4764 print5|My Printer 5 4765) 4766 4767where the tt('|') separates aliases of a printer. The fact that the 4768second alias has a space in it gives a hint to Samba that it's a 4769comment. 4770 4771em(NOTE): Under AIX the default printcap name is 4772tt("/etc/qconfig"). Samba will assume the file is in AIX tt("qconfig") 4773format if the string tt("/qconfig") appears in the printcap filename. 4774 4775 bf(Default:) 4776tt( printcap name = /etc/printcap) 4777 4778 bf(Example:) 4779tt( printcap name = /etc/myprintcap) 4780 4781label(printer) 4782dit(bf(printer (S))) 4783 4784This parameter specifies the name of the printer to which print jobs 4785spooled through a printable service will be sent. 4786 4787If specified in the link(bf([global]))(global) section, the printer 4788name given will be used for any printable service that does not have 4789its own printer name specified. 4790 4791 bf(Default:) 4792 none (but may be tt("lp") on many systems) 4793 4794 bf(Example:) 4795 printer name = laserwriter 4796 4797label(printerdriver) 4798dit(bf(printer driver (S))) 4799 4800This option allows you to control the string that clients receive when 4801they ask the server for the printer driver associated with a 4802printer. If you are using Windows95 or WindowsNT then you can use this 4803to automate the setup of printers on your system. 4804 4805You need to set this parameter to the exact string (case sensitive) 4806that describes the appropriate printer driver for your system. If you 4807don't know the exact string to use then you should first try with no 4808bf("printer driver") option set and the client will give you a list of 4809printer drivers. The appropriate strings are shown in a scrollbox 4810after you have chosen the printer manufacturer. 4811 4812See also link(bf("printer driver file"))(printerdriverfile). 4813 4814 bf(Example:) 4815 printer driver = HP LaserJet 4L 4816 4817label(printerdriverfile) 4818dit(bf(printer driver file (G))) 4819 4820This parameter tells Samba where the printer driver definition file, 4821used when serving drivers to Windows 95 clients, is to be found. If 4822this is not set, the default is : 4823 4824tt(SAMBA_INSTALL_DIRECTORY/lib/printers.def) 4825 4826This file is created from Windows 95 tt("msprint.def") files found on 4827the Windows 95 client system. For more details on setting up serving 4828of printer drivers to Windows 95 clients, see the documentation file 4829in the docs/ directory, PRINTER_DRIVER.txt. 4830 4831 bf(Default:) 4832tt( None (set in compile).) 4833 4834 bf(Example:) 4835tt( printer driver file = /usr/local/samba/printers/drivers.def) 4836 4837See also link(bf("printer driver location"))(printerdriverlocation). 4838 4839label(printerdriverlocation) 4840dit(bf(printer driver location (S))) 4841 4842This parameter tells clients of a particular printer share where to 4843find the printer driver files for the automatic installation of 4844drivers for Windows 95 machines. If Samba is set up to serve printer 4845drivers to Windows 95 machines, this should be set to 4846 4847tt(\\MACHINE\PRINTER$) 4848 4849Where MACHINE is the NetBIOS name of your Samba server, and PRINTER$ 4850is a share you set up for serving printer driver files. For more 4851details on setting this up see the documentation file in the docs/ 4852directory, PRINTER_DRIVER.txt. 4853 4854 bf(Default:) 4855tt( None) 4856 4857 bf(Example:) 4858tt( printer driver location = \\MACHINE\PRINTER$) 4859 4860See also link(bf("printer driver file"))(printerdriverfile). 4861 4862label(printername) 4863dit(bf(printer name (S))) 4864 4865Synonym for link(bf(printer))(printer). 4866 4867label(printing) 4868dit(bf(printing (S))) 4869 4870This parameters controls how printer status information is interpreted 4871on your system. It also affects the default values for the 4872link(bf("print command"))(printcommand), link(bf("lpq 4873command"))(lpqcommand) link(bf("lppause command"))(lppausecommand), 4874link(bf("lpresume command"))(lpresumecommand), and link(bf("lprm 4875command"))(lprmcommand) if specified in the link(bf([global]))(global) 4876section. 4877 4878Currently eight printing styles are supported. They are 4879bf("printing=BSD"), bf("printing=AIX"), bf("printing=LPRNG"), 4880bf("printing=PLP"), 4881bf("printing=SYSV"),bf("printing="HPUX"),bf("printing=QNX") and 4882bf("printing=SOFTQ"). 4883 4884To see what the defaults are for the other print commands when using 4885the various options use the url(bf("testparm"))(testparm.1.html) program. 4886 4887This option can be set on a per printer basis 4888 4889See also the discussion in the link(bf([printers]))(printers) section. 4890 4891label(protocol) 4892dit(bf(protocol (G))) 4893 4894The value of the parameter (a string) is the highest protocol level 4895that will be supported by the server. 4896 4897Possible values are : 4898 4899startit() 4900 4901it() CORE: Earliest version. No concept of user names. 4902 4903it() COREPLUS: Slight improvements on CORE for efficiency. 4904 4905it() LANMAN1: First em("modern") version of the protocol. Long 4906filename support. 4907 4908it() LANMAN2: Updates to Lanman1 protocol. 4909 4910it() NT1: Current up to date version of the protocol. Used by Windows 4911NT. Known as CIFS. 4912 4913endit() 4914 4915Normally this option should not be set as the automatic negotiation 4916phase in the SMB protocol takes care of choosing the appropriate 4917protocol. 4918 4919 bf(Default:) 4920tt( protocol = NT1) 4921 4922 bf(Example:) 4923tt( protocol = LANMAN1) 4924 4925label(public) 4926dit(bf(public (S))) 4927 4928Synonym for link(bf("guest ok"))(guestok). 4929 4930label(queuepausecommand) 4931dit(bf(queuepause command (S))) 4932 4933This parameter specifies the command to be executed on the server host 4934in order to pause the printerqueue. 4935 4936This command should be a program or script which takes a printer name 4937as its only parameter and stops the printerqueue, such that no longer 4938jobs are submitted to the printer. 4939 4940This command is not supported by Windows for Workgroups, but can be 4941issued from the Printer's window under Windows 95 & NT. 4942 4943If a tt("%p") is given then the printername is put in its 4944place. Otherwise it is placed at the end of the command. 4945 4946Note that it is good practice to include the absolute path in the 4947command as the PATH may not be available to the server. 4948 4949 bf(Default:) 4950tt( depends on the setting of "printing =") 4951 4952 bf(Example:) 4953tt( queuepause command = disable %p) 4954 4955label(queueresumecommand) 4956dit(bf(queueresume command (S))) 4957 4958This parameter specifies the command to be executed on the server host 4959in order to resume the printerqueue. It is the command to undo the 4960behavior that is caused by the previous parameter 4961(link(bf("queuepause command))(queuepausecommand)). 4962 4963This command should be a program or script which takes a printer name 4964as its only parameter and resumes the printerqueue, such that queued 4965jobs are resubmitted to the printer. 4966 4967This command is not supported by Windows for Workgroups, but can be 4968issued from the Printer's window under Windows 95 & NT. 4969 4970If a tt("%p") is given then the printername is put in its 4971place. Otherwise it is placed at the end of the command. 4972 4973Note that it is good practice to include the absolute path in the 4974command as the PATH may not be available to the server. 4975 4976 bf(Default:) 4977tt( depends on the setting of "printing =") 4978 4979 bf(Example:) 4980tt( queuepause command = enable %p) 4981 4982label(read bmpx) 4983dit(bf(read bmpx (G))) 4984 4985This boolean parameter controls whether url(bf(smbd))(smbd.8.html) 4986will support the "Read Block Multiplex" SMB. This is now rarely used 4987and defaults to off. You should never need to set this parameter. 4988 4989 bf(Default:) 4990 read bmpx = No 4991 4992label(readlist) 4993dit(bf(read list (S))) 4994 4995This is a list of users that are given read-only access to a 4996service. If the connecting user is in this list then they will not be 4997given write access, no matter what the link(bf("writeable"))(writeable) 4998option is set to. The list can include group names using the syntax 4999described in the link(bf("invalid users"))(invalidusers) parameter. 5000 5001See also the link(bf("write list"))(writelist) parameter and 5002the link(bf("invalid users"))(invalidusers) parameter. 5003 5004 bf(Default:) 5005tt( read list = <empty string>) 5006 5007 bf(Example:) 5008tt( read list = mary, @students) 5009 5010label(readonly) 5011dit(bf(read only (S))) 5012 5013Note that this is an inverted synonym for 5014link(bf("writeable"))(writeable). 5015 5016label(readprediction) 5017dit(bf(read prediction (G))) 5018 5019em(NOTE): This code is currently disabled in Samba2.0 and 5020may be removed at a later date. Hence this parameter has 5021no effect. 5022 5023This options enables or disables the read prediction code used to 5024speed up reads from the server. When enabled the server will try to 5025pre-read data from the last accessed file that was opened read-only 5026while waiting for packets. 5027 5028 bf(Default:) 5029tt( read prediction = False) 5030 5031label(readraw) 5032dit(bf(read raw (G))) 5033 5034This parameter controls whether or not the server will support the raw 5035read SMB requests when transferring data to clients. 5036 5037If enabled, raw reads allow reads of 65535 bytes in one packet. This 5038typically provides a major performance benefit. 5039 5040However, some clients either negotiate the allowable block size 5041incorrectly or are incapable of supporting larger block sizes, and for 5042these clients you may need to disable raw reads. 5043 5044In general this parameter should be viewed as a system tuning tool and left 5045severely alone. See also link(bf("write raw"))(writeraw). 5046 5047 bf(Default:) 5048tt( read raw = yes) 5049 5050label(readsize) 5051dit(bf(read size (G))) 5052 5053The option bf("read size") affects the overlap of disk reads/writes 5054with network reads/writes. If the amount of data being transferred in 5055several of the SMB commands (currently SMBwrite, SMBwriteX and 5056SMBreadbraw) is larger than this value then the server begins writing 5057the data before it has received the whole packet from the network, or 5058in the case of SMBreadbraw, it begins writing to the network before 5059all the data has been read from disk. 5060 5061This overlapping works best when the speeds of disk and network access 5062are similar, having very little effect when the speed of one is much 5063greater than the other. 5064 5065The default value is 16384, but very little experimentation has been 5066done yet to determine the optimal value, and it is likely that the 5067best value will vary greatly between systems anyway. A value over 506865536 is pointless and will cause you to allocate memory 5069unnecessarily. 5070 5071 bf(Default:) 5072tt( read size = 16384) 5073 5074 bf(Example:) 5075tt( read size = 8192) 5076 5077label(remoteannounce) 5078dit(bf(remote announce (G))) 5079 5080This option allows you to setup url(bf(nmbd))(nmbd.8.html) to 5081periodically announce itself to arbitrary IP addresses with an 5082arbitrary workgroup name. 5083 5084This is useful if you want your Samba server to appear in a remote 5085workgroup for which the normal browse propagation rules don't 5086work. The remote workgroup can be anywhere that you can send IP 5087packets to. 5088 5089For example: 5090 5091tt( remote announce = 192.168.2.255/SERVERS 192.168.4.255/STAFF) 5092 5093the above line would cause nmbd to announce itself to the two given IP 5094addresses using the given workgroup names. If you leave out the 5095workgroup name then the one given in the 5096link(bf("workgroup"))(workgroup) parameter is used instead. 5097 5098The IP addresses you choose would normally be the broadcast addresses 5099of the remote networks, but can also be the IP addresses of known 5100browse masters if your network config is that stable. 5101 5102See the documentation file BROWSING.txt in the docs/ directory. 5103 5104 bf(Default:) 5105tt( remote announce = <empty string>) 5106 5107 bf(Example:) 5108tt( remote announce = 192.168.2.255/SERVERS 192.168.4.255/STAFF) 5109 5110label(remotebrowsesync) 5111dit(bf(remote browse sync (G))) 5112 5113This option allows you to setup url(bf(nmbd))(nmbd.8.html) to 5114periodically request synchronization of browse lists with the master 5115browser of a samba server that is on a remote segment. This option 5116will allow you to gain browse lists for multiple workgroups across 5117routed networks. This is done in a manner that does not work with any 5118non-samba servers. 5119 5120This is useful if you want your Samba server and all local clients to 5121appear in a remote workgroup for which the normal browse propagation 5122rules don't work. The remote workgroup can be anywhere that you can 5123send IP packets to. 5124 5125For example: 5126 5127tt( remote browse sync = 192.168.2.255 192.168.4.255) 5128 5129the above line would cause url(bf(nmbd))(nmbd.8.html) to request the 5130master browser on the specified subnets or addresses to synchronize 5131their browse lists with the local server. 5132 5133The IP addresses you choose would normally be the broadcast addresses 5134of the remote networks, but can also be the IP addresses of known 5135browse masters if your network config is that stable. If a machine IP 5136address is given Samba makes NO attempt to validate that the remote 5137machine is available, is listening, nor that it is in fact the browse 5138master on it's segment. 5139 5140 bf(Default:) 5141tt( remote browse sync = <empty string>) 5142 5143 bf(Example:) 5144tt( remote browse sync = 192.168.2.255 192.168.4.255) 5145 5146 5147label(restrict anonymous) 5148dit(bf(restrict anonymous (G))) 5149 5150This is a boolean parameter. If it is true, then anonymous access 5151to the server will be restricted, namely in the case where the server 5152is expecting the client to send a username, but it doesn't. Setting 5153it to true will force these anonymous connections to be denied, and 5154the client will be required to always supply a username and password 5155when connecting. Use of this parameter is only recommened for homogenous 5156NT client environments. 5157 5158This parameter makes the use of macro expansions that rely 5159on the username (%U, %G, etc) consistant. NT 4.0 likes to use 5160anonymous connections when refreshing the share list, and this 5161is a way to work around that. 5162 5163When restrict anonymous is true, all anonymous connections are denied 5164no matter what they are for. This can effect the ability of a machine 5165to access the samba Primary Domain Controller to revalidate it's machine 5166account after someone else has logged on the client interactively. The 5167NT client will display a message saying that the machine's account in 5168the domain doesn't exist or the password is bad. The best way to deal 5169with this is to reboot NT client machines between interactive logons, 5170using "Shutdown and Restart", rather than "Close all programs and logon 5171as a different user". 5172 5173 bf(Default:) 5174tt( restrict anonymous = false) 5175 5176 bf(Example:) 5177tt( restrict anonymous = true) 5178 5179label(revalidate) 5180dit(bf(revalidate (S))) 5181 5182Note that this option only works with 5183link(bf("security=share"))(securityequalshare) and will be ignored if 5184this is not the case. 5185 5186This option controls whether Samba will allow a previously validated 5187username/password pair to be used to attach to a share. Thus if you 5188connect to tt(\\server\share1) then to tt(\\server\share2) it won't 5189automatically allow the client to request connection to the second 5190share as the same username as the first without a password. 5191 5192If bf("revalidate") is tt("True") then the client will be denied 5193automatic access as the same username. 5194 5195 bf(Default:) 5196tt( revalidate = False) 5197 5198 bf(Example:) 5199tt( revalidate = True) 5200 5201label(root) 5202dit(bf(root (G))) 5203 5204Synonym for link(bf("root directory"))(rootdirectory). 5205 5206label(rootdir) 5207dit(bf(root dir (G))) 5208 5209Synonym for link(bf("root directory"))(rootdirectory). 5210 5211label(rootdirectory) 5212dit(bf(root directory (G))) 5213 5214The server will tt("chroot()") (i.e. Change it's root directory) to 5215this directory on startup. This is not strictly necessary for secure 5216operation. Even without it the server will deny access to files not in 5217one of the service entries. It may also check for, and deny access to, 5218soft links to other parts of the filesystem, or attempts to use 5219tt("..") in file names to access other directories (depending on the 5220setting of the link(bf("wide links"))(widelinks) parameter). 5221 5222Adding a bf("root directory") entry other than tt("/") adds an extra 5223level of security, but at a price. It absolutely ensures that no 5224access is given to files not in the sub-tree specified in the bf("root 5225directory") option, em(*including*) some files needed for complete 5226operation of the server. To maintain full operability of the server 5227you will need to mirror some system files into the bf("root 5228directory") tree. In particular you will need to mirror /etc/passwd 5229(or a subset of it), and any binaries or configuration files needed 5230for printing (if required). The set of files that must be mirrored is 5231operating system dependent. 5232 5233 bf(Default:) 5234tt( root directory = /) 5235 5236bf(Example:) 5237tt( root directory = /homes/smb) 5238 5239label(rootpostexec) 5240dit(bf(root postexec (S))) 5241 5242This is the same as the link(bf("postexec"))(postexec) parameter 5243except that the command is run as root. This is useful for unmounting 5244filesystems (such as cdroms) after a connection is closed. 5245 5246See also link(bf("postexec"))(postexec). 5247 5248label(rootpreexec) 5249dit(bf(root preexec (S))) 5250 5251This is the same as the link(bf("preexec"))(preexec) parameter except 5252that the command is run as root. This is useful for mounting 5253filesystems (such as cdroms) before a connection is finalized. 5254 5255See also link(bf("preexec"))(preexec) 5256and link(bf("root preexec close"))(rootpreexecclose). 5257 5258label(rootpreexecclose) 5259dit(bf(root preexec close (S))) 5260 5261This is the same as the link(bf("preexec close"))(preexecclose) parameter 5262except that the command is run as root. 5263 5264See also link(bf("preexec"))(preexec), link(bf("preexec close"))(preexecclose). 5265 5266label(security) 5267dit(bf(security (G))) 5268 5269This option affects how clients respond to Samba and is one of the most 5270important settings in the bf(smb.conf) file. 5271 5272The option sets the tt("security mode bit") in replies to protocol 5273negotiations with url(bf(smbd))(smbd.8.html) to turn share level 5274security on or off. Clients decide based on this bit whether (and how) 5275to transfer user and password information to the server. 5276 5277The default is link("security=user")(securityequaluser), as this is 5278the most common setting needed when talking to Windows 98 and Windows 5279NT. 5280 5281The alternatives are link(bf("security = share"))(securityequalshare), 5282link(bf("security = server"))(securityequalserver) or 5283link(bf("security=domain"))(securityequaldomain). 5284 5285em(*****NOTE THAT THIS DEFAULT IS DIFFERENT IN SAMBA2.0 THAN FOR 5286PREVIOUS VERSIONS OF SAMBA *******). 5287 5288In previous versions of Samba the default was 5289link(bf("security=share"))(securityequalshare) mainly because that was 5290the only option at one stage. 5291 5292There is a bug in WfWg that has relevance to this setting. When in 5293user or server level security a WfWg client will totally ignore the 5294password you type in the "connect drive" dialog box. This makes it 5295very difficult (if not impossible) to connect to a Samba service as 5296anyone except the user that you are logged into WfWg as. 5297 5298If your PCs use usernames that are the same as their usernames on the 5299UNIX machine then you will want to use bf("security = user"). If you 5300mostly use usernames that don't exist on the UNIX box then use 5301bf("security = share"). 5302 5303You should also use link(bf(security=share))(securityequalshare) if 5304you want to mainly setup shares without a password (guest 5305shares). This is commonly used for a shared printer server. It is more 5306difficult to setup guest shares with 5307link(bf(security=user))(securityequaluser), see the link(bf("map to 5308guest"))(maptoguest)parameter for details. 5309 5310It is possible to use url(bf(smbd))(smbd.8.html) in a em("hybrid 5311mode") where it is offers both user and share level security under 5312different link(bf(NetBIOS aliases))(netbiosaliases). See the 5313link(bf(NetBIOS aliases))(netbiosaliases) and the 5314link(bf(include))(include) parameters for more information. 5315 5316The different settings will now be explained. 5317 5318startdit() 5319 5320label(securityequalshare) 5321dit(bf("security=share")) When clients connect to a share level 5322security server then need not log onto the server with a valid 5323username and password before attempting to connect to a shared 5324resource (although modern clients such as Windows 95/98 and Windows NT 5325will send a logon request with a username but no password when talking 5326to a bf(security=share) server). Instead, the clients send 5327authentication information (passwords) on a per-share basis, at the 5328time they attempt to connect to that share. 5329 5330Note that url(bf(smbd))(smbd.8.html) em(*ALWAYS*) uses a valid UNIX 5331user to act on behalf of the client, even in bf("security=share") 5332level security. 5333 5334As clients are not required to send a username to the server 5335in share level security, url(bf(smbd))(smbd.8.html) uses several 5336techniques to determine the correct UNIX user to use on behalf 5337of the client. 5338 5339A list of possible UNIX usernames to match with the given 5340client password is constructed using the following methods : 5341 5342startit() 5343 5344it() If the link(bf("guest only"))(guestonly) parameter is set, then 5345all the other stages are missed and only the link(bf("guest 5346account"))(guestaccount) username is checked. 5347 5348it() Is a username is sent with the share connection request, then 5349this username (after mapping - see link(bf("username 5350map"))(usernamemap)), is added as a potential username. 5351 5352it() If the client did a previous em("logon") request (the 5353SessionSetup SMB call) then the username sent in this SMB 5354will be added as a potential username. 5355 5356it() The name of the service the client requested is added 5357as a potential username. 5358 5359it() The NetBIOS name of the client is added to the list as a 5360potential username. 5361 5362it() Any users on the link(bf("user"))(user) list are added 5363as potential usernames. 5364 5365endit() 5366 5367If the link(bf("guest only"))(guestonly) parameter is not set, then 5368this list is then tried with the supplied password. The first user for 5369whom the password matches will be used as the UNIX user. 5370 5371If the link(bf("guest only"))(guestonly) parameter is set, or no 5372username can be determined then if the share is marked as available to 5373the link(bf("guest account"))(guestaccount), then this guest user will 5374be used, otherwise access is denied. 5375 5376Note that it can be em(*very*) confusing in share-level security as to 5377which UNIX username will eventually be used in granting access. 5378 5379See also the section link(bf("NOTE ABOUT USERNAME/PASSWORD 5380VALIDATION"))(NOTEABOUTUSERNAMEPASSWORDVALIDATION). 5381 5382label(securityequaluser) 5383dit(bf("security=user")) 5384 5385This is the default security setting in Samba2.0. With user-level 5386security a client must first tt("log-on") with a valid username and 5387password (which can be mapped using the link(bf("username 5388map"))(usernamemap) parameter). Encrypted passwords (see the 5389link(bf("encrypted passwords"))(encryptpasswords) parameter) can also 5390be used in this security mode. Parameters such as 5391link(bf("user"))(user) and link(bf("guest only"))(guestonly), if set 5392are then applied and may change the UNIX user to use on this 5393connection, but only after the user has been successfully 5394authenticated. 5395 5396em(Note) that the name of the resource being requested is 5397em(*not*) sent to the server until after the server has successfully 5398authenticated the client. This is why guest shares don't work in user 5399level security without allowing the server to automatically map unknown 5400users into the link(bf("guest account"))(guestaccount). See the 5401link(bf("map to guest"))(maptoguest) parameter for details on 5402doing this. 5403 5404See also the section link(bf("NOTE ABOUT USERNAME/PASSWORD 5405VALIDATION"))(NOTEABOUTUSERNAMEPASSWORDVALIDATION). 5406 5407label(securityequalserver) 5408dit(bf("security=server")) 5409 5410In this mode Samba will try to validate the username/password by 5411passing it to another SMB server, such as an NT box. If this fails it 5412will revert to bf("security = user"), but note that if encrypted 5413passwords have been negotiated then Samba cannot revert back to 5414checking the UNIX password file, it must have a valid smbpasswd file 5415to check users against. See the documentation file in the docs/ 5416directory ENCRYPTION.txt for details on how to set this up. 5417 5418em(Note) that from the clients point of view bf("security=server") is 5419the same as link(bf("security=user"))(securityequaluser). It only 5420affects how the server deals with the authentication, it does not in 5421any way affect what the client sees. 5422 5423em(Note) that the name of the resource being requested is 5424em(*not*) sent to the server until after the server has successfully 5425authenticated the client. This is why guest shares don't work in server 5426level security without allowing the server to automatically map unknown 5427users into the link(bf("guest account"))(guestaccount). See the 5428link(bf("map to guest"))(maptoguest) parameter for details on 5429doing this. 5430 5431See also the section link(bf("NOTE ABOUT USERNAME/PASSWORD 5432VALIDATION"))(NOTEABOUTUSERNAMEPASSWORDVALIDATION). 5433 5434See also the link(bf("password server"))(passwordserver) parameter. 5435and the link(bf("encrypted passwords"))(encryptpasswords) parameter. 5436 5437label(securityequaldomain) 5438dit(bf("security=domain")) 5439 5440This mode will only work correctly if 5441url(bf(smbpasswd))(smbpasswd.8.html) has been used to add this machine 5442into a Windows NT Domain. It expects the link(bf("encrypted 5443passwords"))(encryptpasswords) parameter to be set to tt("true"). In 5444this mode Samba will try to validate the username/password by passing 5445it to a Windows NT Primary or Backup Domain Controller, in exactly the 5446same way that a Windows NT Server would do. 5447 5448em(Note) that a valid UNIX user must still exist as well as the 5449account on the Domain Controller to allow Samba to have a valid 5450UNIX account to map file access to. 5451 5452em(Note) that from the clients point of view bf("security=domain") is 5453the same as link(bf("security=user"))(securityequaluser). It only 5454affects how the server deals with the authentication, it does not in 5455any way affect what the client sees. 5456 5457em(Note) that the name of the resource being requested is 5458em(*not*) sent to the server until after the server has successfully 5459authenticated the client. This is why guest shares don't work in domain 5460level security without allowing the server to automatically map unknown 5461users into the link(bf("guest account"))(guestaccount). See the 5462link(bf("map to guest"))(maptoguest) parameter for details on 5463doing this. 5464 5465em(BUG:) There is currently a bug in the implementation of 5466bf("security=domain) with respect to multi-byte character 5467set usernames. The communication with a Domain Controller 5468must be done in UNICODE and Samba currently does not widen 5469multi-byte user names to UNICODE correctly, thus a multi-byte 5470username will not be recognized correctly at the Domain Controller. 5471This issue will be addressed in a future release. 5472 5473See also the section link(bf("NOTE ABOUT USERNAME/PASSWORD 5474VALIDATION"))(NOTEABOUTUSERNAMEPASSWORDVALIDATION). 5475 5476See also the link(bf("password server"))(passwordserver) parameter. 5477and the link(bf("encrypted passwords"))(encryptpasswords) parameter. 5478 5479enddit() 5480 5481 bf(Default:) 5482tt( security = USER) 5483 5484 bf(Example:) 5485tt( security = DOMAIN) 5486 5487label(securitymask) 5488dit(bf(security mask (S))) 5489 5490This parameter controls what UNIX permission bits can be modified 5491when a Windows NT client is manipulating the UNIX permission on a 5492file using the native NT security dialog box. 5493 5494This parameter is applied as a mask (AND'ed with) to the changed 5495permission bits, thus preventing any bits not in this mask from 5496being modified. Essentially, zero bits in this mask may be treated 5497as a set of bits the user is not allowed to change. 5498 5499If not set explicitly this parameter is set to the same value as the 5500link(bf(create mask))(createmask) parameter. To allow a user to 5501modify all the user/group/world permissions on a file, set this 5502parameter to 0777. 5503 5504em(Note) that users who can access the Samba server through other 5505means can easily bypass this restriction, so it is primarily 5506useful for standalone "appliance" systems. Administrators of 5507most normal systems will probably want to set it to 0777. 5508 5509See also the link(bf(force directory security 5510mode))(forcedirectorysecuritymode), link(bf(directory security 5511mask))(directorysecuritymask), link(bf(force security 5512mode))(forcesecuritymode) parameters. 5513 5514 bf(Default:) 5515tt( security mask = <same as create mask>) 5516 5517 bf(Example:) 5518tt( security mask = 0777) 5519 5520 5521label(serverstring) 5522dit(bf(server string (G))) 5523 5524This controls what string will show up in the printer comment box in 5525print manager and next to the IPC connection in tt("net view"). It can be 5526any string that you wish to show to your users. 5527 5528It also sets what will appear in browse lists next to the machine 5529name. 5530 5531A tt("%v") will be replaced with the Samba version number. 5532 5533A tt("%h") will be replaced with the hostname. 5534 5535 bf(Default:) 5536tt( server string = Samba %v) 5537 5538 bf(Example:) 5539tt( server string = University of GNUs Samba Server) 5540 5541label(setdirectory) 5542dit(bf(set directory (S))) 5543 5544If tt("set directory = no"), then users of the service may not use the 5545setdir command to change directory. 5546 5547The setdir command is only implemented in the Digital Pathworks 5548client. See the Pathworks documentation for details. 5549 5550 bf(Default:) 5551tt( set directory = no) 5552 5553 bf(Example:) 5554tt( set directory = yes) 5555 5556label(sharemodes) 5557dit(bf(share modes (S))) 5558 5559This enables or disables the honoring of the tt("share modes") during a 5560file open. These modes are used by clients to gain exclusive read or 5561write access to a file. 5562 5563These open modes are not directly supported by UNIX, so they are 5564simulated using shared memory, or lock files if your UNIX doesn't 5565support shared memory (almost all do). 5566 5567The share modes that are enabled by this option are DENY_DOS, 5568DENY_ALL, DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB. 5569 5570This option gives full share compatibility and enabled by default. 5571 5572You should em(*NEVER*) turn this parameter off as many Windows 5573applications will break if you do so. 5574 5575 bf(Default:) 5576tt( share modes = yes) 5577 5578label(sharedmemsize) 5579dit(bf(shared mem size (G))) 5580 5581It specifies the size of the shared memory (in bytes) to use between 5582url(bf(smbd))(smbd.8.html) processes. This parameter defaults to one 5583megabyte of shared memory. It is possible that if you have a large 5584server with many files open simultaneously that you may need to 5585increase this parameter. Signs that this parameter is set too low are 5586users reporting strange problems trying to save files (locking errors) 5587and error messages in the smbd log looking like tt("ERROR 5588smb_shm_alloc : alloc of XX bytes failed"). 5589 5590If your OS refuses the size that Samba asks for then Samba will try a 5591smaller size, reducing by a factor of 0.8 until the OS accepts it. 5592 5593 bf(Default:) 5594tt( shared mem size = 1048576) 5595 5596 bf(Example:) 5597tt( shared mem size = 5242880 ; Set to 5mb for a large number of files.) 5598 5599label(shortpreservecase) 5600dit(bf(short preserve case (S))) 5601 5602This boolean parameter controls if new files which conform to 8.3 5603syntax, that is all in upper case and of suitable length, are created 5604upper case, or if they are forced to be the tt("default") case. This 5605option can be use with link(bf("preserve case 5606=yes"))(preservecaseoption) to permit long filenames to retain their 5607case, while short names are lowered. Default em(Yes). 5608 5609See the section on link(bf(NAME MANGLING))(NAMEMANGLING). 5610 5611 bf(Default:) 5612tt( short preserve case = yes) 5613 5614label(smbpasswdfile) 5615dit(bf(smb passwd file (G))) 5616 5617This option sets the path to the encrypted smbpasswd file. By default 5618the path to the smbpasswd file is compiled into Samba. 5619 5620 bf(Default:) 5621tt( smb passwd file= <compiled default>) 5622 5623 bf(Example:) 5624tt( smb passwd file = /usr/samba/private/smbpasswd) 5625 5626label(smbrun) 5627dit(bf(smbrun (G))) 5628 5629This sets the full path to the bf(smbrun) binary. This defaults to the 5630value in the Makefile. 5631 5632You must get this path right for many services to work correctly. 5633 5634You should not need to change this parameter so long as Samba 5635is installed correctly. 5636 5637 bf(Default:) 5638tt( smbrun=<compiled default>) 5639 5640 bf(Example:) 5641tt( smbrun = /usr/local/samba/bin/smbrun) 5642 5643label(socketaddress) 5644dit(bf(socket address (G))) 5645 5646This option allows you to control what address Samba will listen for 5647connections on. This is used to support multiple virtual interfaces on 5648the one server, each with a different configuration. 5649 5650By default samba will accept connections on any address. 5651 5652 bf(Example:) 5653tt( socket address = 192.168.2.20) 5654 5655label(socketoptions) 5656dit(bf(socket options (G))) 5657 5658This option allows you to set socket options to be used when talking 5659with the client. 5660 5661Socket options are controls on the networking layer of the operating 5662systems which allow the connection to be tuned. 5663 5664This option will typically be used to tune your Samba server for 5665optimal performance for your local network. There is no way that Samba 5666can know what the optimal parameters are for your net, so you must 5667experiment and choose them yourself. We strongly suggest you read the 5668appropriate documentation for your operating system first (perhaps 5669bf("man setsockopt") will help). 5670 5671You may find that on some systems Samba will say "Unknown socket 5672option" when you supply an option. This means you either incorrectly 5673typed it or you need to add an include file to includes.h for your OS. 5674If the latter is the case please send the patch to 5675email(samba@samba.org). 5676 5677Any of the supported socket options may be combined in any way you 5678like, as long as your OS allows it. 5679 5680This is the list of socket options currently settable using this 5681option: 5682 5683startit() 5684 5685it() SO_KEEPALIVE 5686 5687it() SO_REUSEADDR 5688 5689it() SO_BROADCAST 5690 5691it() TCP_NODELAY 5692 5693it() IPTOS_LOWDELAY 5694 5695it() IPTOS_THROUGHPUT 5696 5697it() SO_SNDBUF * 5698 5699it() SO_RCVBUF * 5700 5701it() SO_SNDLOWAT * 5702 5703it() SO_RCVLOWAT * 5704 5705endit() 5706 5707Those marked with a tt(*) take an integer argument. The others can 5708optionally take a 1 or 0 argument to enable or disable the option, by 5709default they will be enabled if you don't specify 1 or 0. 5710 5711To specify an argument use the syntax SOME_OPTION=VALUE for example 5712tt(SO_SNDBUF=8192). Note that you must not have any spaces before or after 5713the = sign. 5714 5715If you are on a local network then a sensible option might be 5716 5717tt(socket options = IPTOS_LOWDELAY) 5718 5719If you have a local network then you could try: 5720 5721tt(socket options = IPTOS_LOWDELAY TCP_NODELAY) 5722 5723If you are on a wide area network then perhaps try setting 5724IPTOS_THROUGHPUT. 5725 5726Note that several of the options may cause your Samba server to fail 5727completely. Use these options with caution! 5728 5729 bf(Default:) 5730tt( socket options = TCP_NODELAY) 5731 5732 bf(Example:) 5733tt( socket options = IPTOS_LOWDELAY) 5734 5735label(sourceenvironment) 5736dit(bf(source environment (G))) 5737 5738This parameter causes Samba to set environment variables as per the 5739content of the file named. 5740 5741The file bf(must) be owned by root and not world writable in order 5742to be read (this is a security check). 5743 5744If the value of this parameter starts with a "|" character then Samba will 5745treat that value as a pipe command to open and will set the environment 5746variables from the oput of the pipe. This command must not be world writable 5747and must reside in a directory that is not world writable. 5748 5749The contents of the file or the output of the pipe should be formatted 5750as the output of the standard Unix env(1) command. This is of the form : 5751 5752Example environment entry: 5753tt( SAMBA_NETBIOS_NAME=myhostname ) 5754 5755 bf(Default:) 5756tt(No default value) 5757 5758 bf(Examples:) 5759 5760tt( source environment = |/etc/smb.conf.sh) 5761 5762tt( source environment = /usr/local/smb_env_vars) 5763 5764label(ssl) 5765dit(bf(ssl (G))) 5766 5767This variable is part of SSL-enabled Samba. This is only available if 5768the SSL libraries have been compiled on your system and the configure 5769option tt("--with-ssl") was given at configure time. 5770 5771em(Note) that for export control reasons this code is em(**NOT**) 5772enabled by default in any current binary version of Samba. 5773 5774This variable enables or disables the entire SSL mode. If it is set to 5775"no", the SSL enabled samba behaves exactly like the non-SSL samba. If 5776set to "yes", it depends on the variables link(bf("ssl 5777hosts"))(sslhosts) and link(bf("ssl hosts resign"))(sslhostsresign) 5778whether an SSL connection will be required. 5779 5780 bf(Default:) 5781tt( ssl=no) 5782 bf(Example:) 5783tt( ssl=yes) 5784 5785label(sslCAcertDir) 5786dit(bf(ssl CA certDir (G))) 5787 5788This variable is part of SSL-enabled Samba. This is only available if 5789the SSL libraries have been compiled on your system and the configure 5790option tt("--with-ssl") was given at configure time. 5791 5792em(Note) that for export control reasons this code is em(**NOT**) 5793enabled by default in any current binary version of Samba. 5794 5795This variable defines where to look up the Certification 5796Authorities. The given directory should contain one file for each CA 5797that samba will trust. The file name must be the hash value over the 5798"Distinguished Name" of the CA. How this directory is set up is 5799explained later in this document. All files within the directory that 5800don't fit into this naming scheme are ignored. You don't need this 5801variable if you don't verify client certificates. 5802 5803 bf(Default:) 5804tt( ssl CA certDir = /usr/local/ssl/certs) 5805 5806label(sslCAcertFile) 5807dit(bf(ssl CA certFile (G))) 5808 5809This variable is part of SSL-enabled Samba. This is only available if 5810the SSL libraries have been compiled on your system and the configure 5811option tt("--with-ssl") was given at configure time. 5812 5813em(Note) that for export control reasons this code is em(**NOT**) 5814enabled by default in any current binary version of Samba. 5815 5816This variable is a second way to define the trusted CAs. The 5817certificates of the trusted CAs are collected in one big file and this 5818variable points to the file. You will probably only use one of the two 5819ways to define your CAs. The first choice is preferable if you have 5820many CAs or want to be flexible, the second is preferable if you only 5821have one CA and want to keep things simple (you won't need to create 5822the hashed file names). You don't need this variable if you don't 5823verify client certificates. 5824 5825 bf(Default:) 5826tt( ssl CA certFile = /usr/local/ssl/certs/trustedCAs.pem) 5827 5828label(sslciphers) 5829dit(bf(ssl ciphers (G))) 5830 5831This variable is part of SSL-enabled Samba. This is only available if 5832the SSL libraries have been compiled on your system and the configure 5833option tt("--with-ssl") was given at configure time. 5834 5835em(Note) that for export control reasons this code is em(**NOT**) 5836enabled by default in any current binary version of Samba. 5837 5838This variable defines the ciphers that should be offered during SSL 5839negotiation. You should not set this variable unless you know what you 5840are doing. 5841 5842label(sslclientcert) 5843dit(bf(ssl client cert (G))) 5844 5845This variable is part of SSL-enabled Samba. This is only available if 5846the SSL libraries have been compiled on your system and the configure 5847option tt("--with-ssl") was given at configure time. 5848 5849em(Note) that for export control reasons this code is em(**NOT**) 5850enabled by default in any current binary version of Samba. 5851 5852The certificate in this file is used by 5853url(bf(smbclient))(smbclient.1.html) if it exists. It's needed if the 5854server requires a client certificate. 5855 5856 bf(Default:) 5857tt( ssl client cert = /usr/local/ssl/certs/smbclient.pem) 5858 5859label(sslclientkey) 5860dit(bf(ssl client key (G))) 5861 5862This variable is part of SSL-enabled Samba. This is only available if 5863the SSL libraries have been compiled on your system and the configure 5864option tt("--with-ssl") was given at configure time. 5865 5866em(Note) that for export control reasons this code is em(**NOT**) 5867enabled by default in any current binary version of Samba. 5868 5869This is the private key for url(bf(smbclient))(smbclient.1.html). It's 5870only needed if the client should have a certificate. 5871 5872 bf(Default:) 5873tt( ssl client key = /usr/local/ssl/private/smbclient.pem) 5874 5875label(sslcompatibility) 5876dit(bf(ssl compatibility (G))) 5877 5878This variable is part of SSL-enabled Samba. This is only available if 5879the SSL libraries have been compiled on your system and the configure 5880option tt("--with-ssl") was given at configure time. 5881 5882em(Note) that for export control reasons this code is em(**NOT**) 5883enabled by default in any current binary version of Samba. 5884 5885This variable defines whether SSLeay should be configured for bug 5886compatibility with other SSL implementations. This is probably not 5887desirable because currently no clients with SSL implementations other 5888than SSLeay exist. 5889 5890 bf(Default:) 5891tt( ssl compatibility = no) 5892 5893label(sslhosts) 5894dit(bf(ssl hosts (G))) 5895 5896See link(bf("ssl hosts resign"))(sslhostsresign). 5897 5898label(sslhostsresign) 5899dit(bf(ssl hosts resign (G))) 5900 5901This variable is part of SSL-enabled Samba. This is only available if 5902the SSL libraries have been compiled on your system and the configure 5903option tt("--with-ssl") was given at configure time. 5904 5905em(Note) that for export control reasons this code is em(**NOT**) 5906enabled by default in any current binary version of Samba. 5907 5908These two variables define whether samba will go into SSL mode or 5909not. If none of them is defined, samba will allow only SSL 5910connections. If the link(bf("ssl hosts"))(sslhosts) variable lists 5911hosts (by IP-address, IP-address range, net group or name), only these 5912hosts will be forced into SSL mode. If the bf("ssl hosts resign") 5913variable lists hosts, only these hosts will NOT be forced into SSL 5914mode. The syntax for these two variables is the same as for the 5915link(bf("hosts allow"))(hostsallow) and link(bf("hosts 5916deny"))(hostsdeny) pair of variables, only that the subject of the 5917decision is different: It's not the access right but whether SSL is 5918used or not. See the link(bf("allow hosts"))(allowhosts) parameter for 5919details. The example below requires SSL connections from all hosts 5920outside the local net (which is 192.168.*.*). 5921 5922 bf(Default:) 5923tt( ssl hosts = <empty string>) 5924tt( ssl hosts resign = <empty string>) 5925 5926 bf(Example:) 5927tt( ssl hosts resign = 192.168.) 5928 5929label(sslrequireclientcert) 5930dit(bf(ssl require clientcert (G))) 5931 5932This variable is part of SSL-enabled Samba. This is only available if 5933the SSL libraries have been compiled on your system and the configure 5934option tt("--with-ssl") was given at configure time. 5935 5936em(Note) that for export control reasons this code is em(**NOT**) 5937enabled by default in any current binary version of Samba. 5938 5939If this variable is set to tt("yes"), the server will not tolerate 5940connections from clients that don't have a valid certificate. The 5941directory/file given in link(bf("ssl CA certDir"))(sslCAcertDir) and 5942link(bf("ssl CA certFile"))(sslCAcertFile) will be used to look up the 5943CAs that issued the client's certificate. If the certificate can't be 5944verified positively, the connection will be terminated. If this 5945variable is set to tt("no"), clients don't need certificates. Contrary 5946to web applications you really em(*should*) require client 5947certificates. In the web environment the client's data is sensitive 5948(credit card numbers) and the server must prove to be trustworthy. In 5949a file server environment the server's data will be sensitive and the 5950clients must prove to be trustworthy. 5951 5952 bf(Default:) 5953tt( ssl require clientcert = no) 5954 5955label(sslrequireservercert) 5956dit(bf(ssl require servercert (G))) 5957 5958This variable is part of SSL-enabled Samba. This is only available if 5959the SSL libraries have been compiled on your system and the configure 5960option tt("--with-ssl") was given at configure time. 5961 5962em(Note) that for export control reasons this code is em(**NOT**) 5963enabled by default in any current binary version of Samba. 5964 5965If this variable is set to tt("yes"), the 5966url(bf(smbclient))(smbclient.1.html) will request a certificate from 5967the server. Same as link(bf("ssl require 5968clientcert"))(sslrequireclientcert) for the server. 5969 5970 bf(Default:) 5971tt( ssl require servercert = no) 5972 5973label(sslservercert) 5974dit(bf(ssl server cert (G))) 5975 5976This variable is part of SSL-enabled Samba. This is only available if 5977the SSL libraries have been compiled on your system and the configure 5978option tt("--with-ssl") was given at configure time. 5979 5980em(Note) that for export control reasons this code is em(**NOT**) 5981enabled by default in any current binary version of Samba. 5982 5983This is the file containing the server's certificate. The server _must_ 5984have a certificate. The file may also contain the server's private key. 5985See later for how certificates and private keys are created. 5986 5987 bf(Default:) 5988tt( ssl server cert = <empty string>) 5989 5990label(sslserverkey) 5991dit(bf(ssl server key (G))) 5992 5993This variable is part of SSL-enabled Samba. This is only available if 5994the SSL libraries have been compiled on your system and the configure 5995option tt("--with-ssl") was given at configure time. 5996 5997em(Note) that for export control reasons this code is em(**NOT**) 5998enabled by default in any current binary version of Samba. 5999 6000This file contains the private key of the server. If this variable is 6001not defined, the key is looked up in the certificate file (it may be 6002appended to the certificate). The server em(*must*) have a private key 6003and the certificate em(*must*) match this private key. 6004 6005 bf(Default:) 6006tt( ssl server key = <empty string>) 6007 6008label(sslversion) 6009dit(bf(ssl version (G))) 6010 6011This variable is part of SSL-enabled Samba. This is only available if 6012the SSL libraries have been compiled on your system and the configure 6013option tt("--with-ssl") was given at configure time. 6014 6015em(Note) that for export control reasons this code is em(**NOT**) 6016enabled by default in any current binary version of Samba. 6017 6018This enumeration variable defines the versions of the SSL protocol 6019that will be used. tt("ssl2or3") allows dynamic negotiation of SSL v2 6020or v3, tt("ssl2") results in SSL v2, tt("ssl3") results in SSL v3 and 6021"tls1" results in TLS v1. TLS (Transport Layer Security) is the 6022(proposed?) new standard for SSL. 6023 6024 bf(Default:) 6025tt( ssl version = "ssl2or3") 6026 6027label(statcache) 6028dit(bf(stat cache (G))) 6029 6030This parameter determines if url(bf(smbd))(smbd.8.html) will use a 6031cache in order to speed up case insensitive name mappings. You should 6032never need to change this parameter. 6033 6034 bf(Default:) 6035tt( stat cache = yes) 6036 6037label(statcachesize) 6038dit(bf(stat cache size (G))) 6039 6040This parameter determines the number of entries in the link(bf(stat 6041cache))(statcache). You should never need to change this parameter. 6042 6043 bf(Default:) 6044tt( stat cache size = 50) 6045 6046label(status) 6047dit(bf(status (G))) 6048 6049This enables or disables logging of connections to a status file that 6050url(bf(smbstatus))(smbstatus.1.html) can read. 6051 6052With this disabled url(bf(smbstatus))(smbstatus.1.html) won't be able 6053to tell you what connections are active. You should never need to 6054change this parameter. 6055 6056 bf(Default:) 6057 status = yes 6058 6059label(strictlocking) 6060dit(bf(strict locking (S))) 6061 6062This is a boolean that controls the handling of file locking in the 6063server. When this is set to tt("yes") the server will check every read and 6064write access for file locks, and deny access if locks exist. This can 6065be slow on some systems. 6066 6067When strict locking is tt("no") the server does file lock checks only 6068when the client explicitly asks for them. 6069 6070Well behaved clients always ask for lock checks when it is important, 6071so in the vast majority of cases bf("strict locking = no") is 6072preferable. 6073 6074 bf(Default:) 6075tt( strict locking = no) 6076 6077 bf(Example:) 6078tt( strict locking = yes) 6079 6080label(strictsync) 6081dit(bf(strict sync (S))) 6082 6083Many Windows applications (including the Windows 98 explorer shell) 6084seem to confuse flushing buffer contents to disk with doing a sync to 6085disk. Under UNIX, a sync call forces the process to be suspended until 6086the kernel has ensured that all outstanding data in kernel disk 6087buffers has been safely stored onto stable storage. This is very slow 6088and should only be done rarely. Setting this parameter to "no" (the 6089default) means that smbd ignores the Windows applications requests for 6090a sync call. There is only a possibility of losing data if the 6091operating system itself that Samba is running on crashes, so there is 6092little danger in this default setting. In addition, this fixes many 6093performance problems that people have reported with the new Windows98 6094explorer shell file copies. 6095 6096See also the link(bf("sync always"))(syncalways) parameter. 6097 6098 bf(Default:) 6099tt( strict sync = no) 6100 6101 bf(Example:) 6102tt( strict sync = yes) 6103 6104label(stripdot) 6105dit(bf(strip dot (G))) 6106 6107This is a boolean that controls whether to strip trailing dots off 6108UNIX filenames. This helps with some CDROMs that have filenames ending 6109in a single dot. 6110 6111 bf(Default:) 6112tt( strip dot = no) 6113 6114 bf(Example:) 6115tt( strip dot = yes) 6116 6117label(syncalways) 6118dit(bf(sync always (S))) 6119 6120This is a boolean parameter that controls whether writes will always 6121be written to stable storage before the write call returns. If this is 6122false then the server will be guided by the client's request in each 6123write call (clients can set a bit indicating that a particular write 6124should be synchronous). If this is true then every write will be 6125followed by a fsync() call to ensure the data is written to disk. 6126Note that the link(bf("strict sync"))(strictsync) parameter must be 6127set to tt("yes") in order for this parameter to have any affect. 6128 6129See also the link(bf("strict sync"))(strictsync) parameter. 6130 6131 bf(Default:) 6132tt( sync always = no) 6133 6134 bf(Example:) 6135tt( sync always = yes) 6136 6137label(syslog) 6138dit(bf(syslog (G))) 6139 6140This parameter maps how Samba debug messages are logged onto the 6141system syslog logging levels. Samba debug level zero maps onto syslog 6142LOG_ERR, debug level one maps onto LOG_WARNING, debug level two maps 6143onto LOG_NOTICE, debug level three maps onto LOG_INFO. All higher 6144levels are mapped to LOG_DEBUG. 6145 6146This paramter sets the threshold for sending messages to syslog. 6147Only messages with debug level less than this value will be sent 6148to syslog. 6149 6150 bf(Default:) 6151tt( syslog = 1) 6152 6153label(syslogonly) 6154dit(bf(syslog only (G))) 6155 6156If this parameter is set then Samba debug messages are logged into the 6157system syslog only, and not to the debug log files. 6158 6159 bf(Default:) 6160tt( syslog only = no) 6161 6162label(timeoffset) 6163dit(bf(time offset (G))) 6164 6165This parameter is a setting in minutes to add to the normal GMT to 6166local time conversion. This is useful if you are serving a lot of PCs 6167that have incorrect daylight saving time handling. 6168 6169 bf(Default:) 6170tt( time offset = 0) 6171 6172 bf(Example:) 6173tt( time offset = 60) 6174 6175label(timeserver) 6176 6177dit(bf(time server (G))) 6178 6179This parameter determines if url(bf(nmbd))(nmbd.8.html) advertises 6180itself as a time server to Windows clients. The default is False. 6181 6182 bf(Default:) 6183tt( time server = False) 6184 6185 bf(Example:) 6186tt( time server = True) 6187 6188label(timestamplogs) 6189dit(bf(timestamp logs (G))) 6190 6191Synonym for url(bf("debug timestamp"))(debugtimestamp). 6192 6193label(unixpasswordsync) 6194dit(bf(unix password sync (G))) 6195 6196This boolean parameter controls whether Samba attempts to synchronize 6197the UNIX password with the SMB password when the encrypted SMB 6198password in the smbpasswd file is changed. If this is set to true the 6199program specified in the link(bf("passwd program"))(passwdprogram) 6200parameter is called em(*AS ROOT*) - to allow the new UNIX password to be 6201set without access to the old UNIX password (as the SMB password has 6202change code has no access to the old password cleartext, only the 6203new). By default this is set to tt("false"). 6204 6205See also link(bf("passwd program"))(passwdprogram), link(bf("passwd 6206chat"))(passwdchat). 6207 6208 bf(Default:) 6209tt( unix password sync = False) 6210 6211 bf(Example:) 6212tt( unix password sync = True) 6213 6214label(unixrealname) 6215dit(bf(unix realname (G))) 6216 6217This boolean parameter when set causes samba to supply the real name 6218field from the unix password file to the client. This is useful for 6219setting up mail clients and WWW browsers on systems used by more than 6220one person. 6221 6222 bf(Default:) 6223tt( unix realname = no) 6224 6225 bf(Example:) 6226tt( unix realname = yes) 6227 6228label(updateencrypted) 6229dit(bf(update encrypted (G))) 6230 6231This boolean parameter allows a user logging on with a plaintext 6232password to have their encrypted (hashed) password in the smbpasswd 6233file to be updated automatically as they log on. This option allows a 6234site to migrate from plaintext password authentication (users 6235authenticate with plaintext password over the wire, and are checked 6236against a UNIX account database) to encrypted password authentication 6237(the SMB challenge/response authentication mechanism) without forcing 6238all users to re-enter their passwords via smbpasswd at the time the 6239change is made. This is a convenience option to allow the change over 6240to encrypted passwords to be made over a longer period. Once all users 6241have encrypted representations of their passwords in the smbpasswd 6242file this parameter should be set to tt("off"). 6243 6244In order for this parameter to work correctly the link(bf("encrypt 6245passwords"))(encryptpasswords) parameter must be set to tt("no") when 6246this parameter is set to tt("yes"). 6247 6248Note that even when this parameter is set a user authenticating to 6249smbd must still enter a valid password in order to connect correctly, 6250and to update their hashed (smbpasswd) passwords. 6251 6252 bf(Default:) 6253tt( update encrypted = no) 6254 6255 bf(Example:) 6256tt( update encrypted = yes) 6257 6258label(userhosts) 6259dit(bf(use rhosts (G))) 6260 6261If this global parameter is a true, it specifies that the UNIX users 6262tt(".rhosts") file in their home directory will be read to find the 6263names of hosts and users who will be allowed access without specifying 6264a password. 6265 6266NOTE: The use of bf(use rhosts) can be a major security hole. This is 6267because you are trusting the PC to supply the correct username. It is 6268very easy to get a PC to supply a false username. I recommend that the 6269bf(use rhosts) option be only used if you really know what you are 6270doing. 6271 6272 bf(Default:) 6273tt( use rhosts = no) 6274 6275 bf(Example:) 6276tt( use rhosts = yes) 6277 6278label(user) 6279dit(bf(user (S))) 6280 6281Synonym for link(bf("username"))(username). 6282 6283label(users) 6284dit(bf(users (S))) 6285 6286Synonym for link(bf("username"))(username). 6287 6288label(username) 6289dit(bf(username (S))) 6290 6291Multiple users may be specified in a comma-delimited list, in which 6292case the supplied password will be tested against each username in 6293turn (left to right). 6294 6295The bf(username=) line is needed only when the PC is unable to supply 6296its own username. This is the case for the COREPLUS protocol or where 6297your users have different WfWg usernames to UNIX usernames. In both 6298these cases you may also be better using the tt(\\server\share%user) 6299syntax instead. 6300 6301The bf(username=) line is not a great solution in many cases as it 6302means Samba will try to validate the supplied password against each of 6303the usernames in the username= line in turn. This is slow and a bad 6304idea for lots of users in case of duplicate passwords. You may get 6305timeouts or security breaches using this parameter unwisely. 6306 6307Samba relies on the underlying UNIX security. This parameter does not 6308restrict who can login, it just offers hints to the Samba server as to 6309what usernames might correspond to the supplied password. Users can 6310login as whoever they please and they will be able to do no more 6311damage than if they started a telnet session. The daemon runs as the 6312user that they log in as, so they cannot do anything that user cannot 6313do. 6314 6315To restrict a service to a particular set of users you can use the 6316link(bf("valid users="))(validusers) parameter. 6317 6318If any of the usernames begin with a tt('@') then the name will be 6319looked up first in the yp netgroups list (if Samba is compiled with 6320netgroup support), followed by a lookup in the UNIX groups database 6321and will expand to a list of all users in the group of that name. 6322 6323If any of the usernames begin with a tt('+') then the name will be 6324looked up only in the UNIX groups database and will expand to a list 6325of all users in the group of that name. 6326 6327If any of the usernames begin with a tt('&') then the name will be 6328looked up only in the yp netgroups database (if Samba is compiled with 6329netgroup support) and will expand to a list of all users in the 6330netgroup group of that name. 6331 6332Note that searching though a groups database can take quite some time, 6333and some clients may time out during the search. 6334 6335See the section link(bf("NOTE ABOUT USERNAME/PASSWORD 6336VALIDATION"))(NOTEABOUTUSERNAMEPASSWORDVALIDATION) for more 6337information on how this parameter determines access to the services. 6338 6339 bf(Default:) 6340tt( The guest account if a guest service, else the name of the service.) 6341 6342 bf(Examples:) 6343verb( 6344 username = fred 6345 username = fred, mary, jack, jane, @users, @pcgroup 6346) 6347 6348label(usernamelevel) 6349dit(bf(username level (G))) 6350 6351This option helps Samba to try and 'guess' at the real UNIX username, 6352as many DOS clients send an all-uppercase username. By default Samba 6353tries all lowercase, followed by the username with the first letter 6354capitalized, and fails if the username is not found on the UNIX 6355machine. 6356 6357If this parameter is set to non-zero the behavior changes. This 6358parameter is a number that specifies the number of uppercase 6359combinations to try whilst trying to determine the UNIX user name. The 6360higher the number the more combinations will be tried, but the slower 6361the discovery of usernames will be. Use this parameter when you have 6362strange usernames on your UNIX machine, such as tt("AstrangeUser"). 6363 6364 bf(Default:) 6365tt( username level = 0) 6366 6367 bf(Example:) 6368tt( username level = 5) 6369 6370label(usernamemap) 6371dit(bf(username map (G))) 6372 6373This option allows you to specify a file containing a mapping of 6374usernames from the clients to the server. This can be used for several 6375purposes. The most common is to map usernames that users use on DOS or 6376Windows machines to those that the UNIX box uses. The other is to map 6377multiple users to a single username so that they can more easily share 6378files. 6379 6380The map file is parsed line by line. Each line should contain a single 6381UNIX username on the left then a tt('=') followed by a list of 6382usernames on the right. The list of usernames on the right may contain 6383names of the form @group in which case they will match any UNIX 6384username in that group. The special client name tt('*') is a wildcard 6385and matches any name. Each line of the map file may be up to 1023 6386characters long. 6387 6388The file is processed on each line by taking the supplied username and 6389comparing it with each username on the right hand side of the tt('=') 6390signs. If the supplied name matches any of the names on the right hand 6391side then it is replaced with the name on the left. Processing then 6392continues with the next line. 6393 6394If any line begins with a tt('#') or a tt(';') then it is ignored 6395 6396If any line begins with an tt('!') then the processing will stop after 6397that line if a mapping was done by the line. Otherwise mapping 6398continues with every line being processed. Using tt('!') is most 6399useful when you have a wildcard mapping line later in the file. 6400 6401For example to map from the name tt("admin") or tt("administrator") to 6402the UNIX name tt("root") you would use: 6403 6404 6405tt( root = admin administrator) 6406 6407Or to map anyone in the UNIX group tt("system") to the UNIX name 6408tt("sys") you would use: 6409 6410tt( sys = @system) 6411 6412You can have as many mappings as you like in a username map file. 6413 6414If your system supports the NIS NETGROUP option then the netgroup 6415database is checked before the tt(/etc/group) database for matching 6416groups. 6417 6418You can map Windows usernames that have spaces in them by using double 6419quotes around the name. For example: 6420 6421tt( tridge = "Andrew Tridgell") 6422 6423would map the windows username tt("Andrew Tridgell") to the unix 6424username tridge. 6425 6426The following example would map mary and fred to the unix user sys, 6427and map the rest to guest. Note the use of the tt('!') to tell Samba 6428to stop processing if it gets a match on that line. 6429 6430verb( 6431 !sys = mary fred 6432 guest = * 6433) 6434 6435Note that the remapping is applied to all occurrences of 6436usernames. Thus if you connect to tt("\\server\fred") and tt("fred") 6437is remapped to tt("mary") then you will actually be connecting to 6438tt("\\server\mary") and will need to supply a password suitable for 6439tt("mary") not tt("fred"). The only exception to this is the username 6440passed to the link(bf("password server"))(passwordserver) (if you have 6441one). The password server will receive whatever username the client 6442supplies without modification. 6443 6444Also note that no reverse mapping is done. The main effect this has is 6445with printing. Users who have been mapped may have trouble deleting 6446print jobs as PrintManager under WfWg will think they don't own the 6447print job. 6448 6449 bf(Default:) 6450tt( no username map) 6451 6452 bf(Example:) 6453tt( username map = /usr/local/samba/lib/users.map) 6454 6455label(utmp) 6456dit(bf(utmp (S))) 6457 6458This boolean parameter is only available if Samba has been configured and compiled 6459with the option tt(--with-utmp). If set to True then Samba will attempt 6460to add utmp or utmpx records (depending on the UNIX system) whenever a 6461connection is made to a Samba server. Sites may use this to record the 6462user connecting to a Samba share. 6463 6464See also the link(bf("utmp directory"))(utmpdirectory) parameter. 6465 6466 bf(Default:) 6467tt(utmp = False) 6468 6469 bf(Example:) 6470tt(utmp = True) 6471 6472label(utmpconsolidate) 6473dit(bf(utmp consolidate(G))) 6474 6475This parameter is only available if Samba has been configured and compiled 6476with the option tt(--with-utmp). Normally each share create a utmp record, 6477but if there are many connections each with many shares, it can be desirable 6478to consolidate the shares down to one-per-connection. 6479 6480 bf(Default:) 6481tt(utmp consolidate = no) 6482 6483 bf(Example:) 6484tt(utmp consolidate = yes) 6485 6486label(utmpdirectory) 6487dit(bf(utmp directory(G))) 6488 6489This parameter is only available if Samba has been configured and compiled 6490with the option tt(--with-utmp). It specifies a directory pathname that is 6491used to store the utmp or utmpx files (depending on the UNIX system) that 6492record user connections to a Samba server. See also the link(bf("utmp"))(utmp) 6493parameter. By default this is not set, meaning the system will use whatever 6494utmp file the native system is set to use (usually /var/run/utmp on Linux). 6495 6496 bf(Default:) 6497tt(no utmp directory) 6498 6499 bf(Example:) 6500tt(utmp directory = /var/adm/) 6501 6502label(utmphostname) 6503dit(bf(utmp hostname(G))) 6504 6505This parameter is only available if Samba has been configured and compiled 6506with the option tt(--with-utmp). It specifies the ut_host field of the 6507utmp and wtmp records. The default is the NetBIOS name (%m), but a very 6508useful alternative might be the Internet/DNS anme (%M). 6509 6510 bf(Default:) 6511tt(utmp hostname = %m) 6512 6513 bf(Example:) 6514tt(utmp hostname = %M) 6515 6516label(validchars) 6517dit(bf(valid chars (G))) 6518 6519The option allows you to specify additional characters that should be 6520considered valid by the server in filenames. This is particularly 6521useful for national character sets, such as adding u-umlaut or a-ring. 6522 6523The option takes a list of characters in either integer or character 6524form with spaces between them. If you give two characters with a colon 6525between them then it will be taken as an lowercase:uppercase pair. 6526 6527If you have an editor capable of entering the characters into the 6528config file then it is probably easiest to use this method. Otherwise 6529you can specify the characters in octal, decimal or hexadecimal form 6530using the usual C notation. 6531 6532For example to add the single character tt('Z') to the charset (which 6533is a pointless thing to do as it's already there) you could do one of 6534the following 6535 6536verb( 6537 valid chars = Z 6538 valid chars = z:Z 6539 valid chars = 0132:0172 6540) 6541 6542The last two examples above actually add two characters, and alter the 6543uppercase and lowercase mappings appropriately. 6544 6545Note that you MUST specify this parameter after the link(bf("client 6546code page"))(clientcodepage) parameter if you have both set. If 6547link(bf("client code page"))(clientcodepage) is set after the 6548bf("valid chars") parameter the bf("valid chars") settings will be 6549overwritten. 6550 6551See also the link(bf("client code page"))(clientcodepage) parameter. 6552 6553 bf(Default:) 6554verb( 6555 Samba defaults to using a reasonable set of valid characters 6556 for English systems 6557) 6558 6559 bf(Example) 6560tt( valid chars = 0345:0305 0366:0326 0344:0304) 6561 6562The above example allows filenames to have the Swedish characters in 6563them. 6564 6565NOTE: It is actually quite difficult to correctly produce a bf("valid 6566chars") line for a particular system. To automate the process 6567email(tino@augsburg.net) has written a package called bf("validchars") 6568which will automatically produce a complete bf("valid chars") line for 6569a given client system. Look in the examples/validchars/ subdirectory 6570of your Samba source code distribution for this package. 6571 6572label(validusers) 6573dit(bf(valid users (S))) 6574 6575This is a list of users that should be allowed to login to this 6576service. Names starting with tt('@'), tt('+') and tt('&') are 6577interpreted using the same rules as described in the link(bf("invalid 6578users"))(invalidusers) parameter. 6579 6580If this is empty (the default) then any user can login. If a username 6581is in both this list and the link(bf("invalid users"))(invalidusers) 6582list then access is denied for that user. 6583 6584The current servicename is substituted for 6585link(bf("%S"))(percentS). This is useful in the 6586link(bf([homes]))(homes) section. 6587 6588See also link(bf("invalid users"))(invalidusers). 6589 6590 bf(Default:) 6591tt( No valid users list. (anyone can login)) 6592 6593 bf(Example:) 6594tt( valid users = greg, @pcusers) 6595 6596label(vetofiles) 6597dit(bf(veto files(S))) 6598 6599This is a list of files and directories that are neither visible nor 6600accessible. Each entry in the list must be separated by a tt('/'), 6601which allows spaces to be included in the entry. tt('*') and tt('?') 6602can be used to specify multiple files or directories as in DOS 6603wildcards. 6604 6605Each entry must be a unix path, not a DOS path and must em(*not*) include the 6606unix directory separator tt('/'). 6607 6608Note that the link(bf("case sensitive"))(casesensitive) option is 6609applicable in vetoing files. 6610 6611One feature of the veto files parameter that it is important to be 6612aware of, is that if a directory contains nothing but files that match 6613the veto files parameter (which means that Windows/DOS clients cannot 6614ever see them) is deleted, the veto files within that directory *are 6615automatically deleted* along with it, if the user has UNIX permissions 6616to do so. 6617 6618Setting this parameter will affect the performance of Samba, as it 6619will be forced to check all files and directories for a match as they 6620are scanned. 6621 6622See also link(bf("hide files"))(hidefiles) and link(bf("case 6623sensitive"))(casesensitive). 6624 6625 bf(Default:) 6626tt( No files or directories are vetoed.) 6627 6628 bf(Examples:) 6629 6630 Example 1. 6631 6632verb( 6633 6634 Veto any files containing the word Security, 6635 any ending in .tmp, and any directory containing the 6636 word root. 6637 6638 veto files = /*Security*/*.tmp/*root*/ 6639) 6640 6641 Example 2. 6642 6643verb( 6644 Veto the Apple specific files that a NetAtalk server 6645 creates. 6646 6647 veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/ 6648) 6649 6650label(vetooplockfiles) 6651dit(bf(veto oplock files (S))) 6652 6653This parameter is only valid when the link(bf("oplocks"))(oplocks) 6654parameter is turned on for a share. It allows the Samba administrator 6655to selectively turn off the granting of oplocks on selected files that 6656match a wildcarded list, similar to the wildcarded list used in the 6657link(bf("veto files"))(vetofiles) parameter. 6658 6659 bf(Default:) 6660tt( No files are vetoed for oplock grants.) 6661 6662 bf(Examples:) 6663 6664You might want to do this on files that you know will be heavily 6665contended for by clients. A good example of this is in the NetBench 6666SMB benchmark program, which causes heavy client contention for files 6667ending in tt(".SEM"). To cause Samba not to grant oplocks on these 6668files you would use the line (either in the link(bf([global]))(global) 6669section or in the section for the particular NetBench share : 6670 6671tt( veto oplock files = /*.SEM/) 6672 6673label(volume) 6674dit(bf(volume (S))) 6675 6676This allows you to override the volume label returned for a 6677share. Useful for CDROMs with installation programs that insist on a 6678particular volume label. 6679 6680The default is the name of the share. 6681 6682label(widelinks) 6683dit(bf(wide links (S))) 6684 6685This parameter controls whether or not links in the UNIX file system 6686may be followed by the server. Links that point to areas within the 6687directory tree exported by the server are always allowed; this 6688parameter controls access only to areas that are outside the directory 6689tree being exported. Note that only links to directories are restricted 6690by this parameter setting. Links directly to files are not disallowed. 6691 6692Note that setting this parameter can have a negative effect on your 6693server performance due to the extra system calls that Samba has to 6694do in order to perform the link checks. 6695 6696 bf(Default:) 6697tt( wide links = yes) 6698 6699 bf(Example:) 6700tt( wide links = no) 6701 6702label(winsproxy) 6703dit(bf(wins proxy (G))) 6704 6705This is a boolean that controls if url(bf(nmbd))(nmbd.8.html) will 6706respond to broadcast name queries on behalf of other hosts. You may 6707need to set this to tt("yes") for some older clients. 6708 6709 bf(Default:) 6710tt( wins proxy = no) 6711 6712label(winsserver) 6713dit(bf(wins server (G))) 6714 6715This specifies the IP address (or DNS name: IP address for preference) 6716of the WINS server that url(bf(nmbd))(nmbd.8.html) should register with. 6717If you have a WINS server on your network then you should set this to 6718the WINS server's IP. 6719 6720You should point this at your WINS server if you have a 6721multi-subnetted network. 6722 6723em(NOTE). You need to set up Samba to point to a WINS server if you 6724have multiple subnets and wish cross-subnet browsing to work correctly. 6725 6726See the documentation file BROWSING.txt in the docs/ directory of your 6727Samba source distribution. 6728 6729 bf(Default:) 6730tt( wins server = ) 6731 6732 bf(Example:) 6733tt( wins server = 192.9.200.1) 6734 6735label(winshook) 6736dit(bf(wins hook (G))) 6737 6738When Samba is running as a WINS server this allows you to call an 6739external program for all changes to the WINS database. The primary use 6740for this option is to allow the dynamic update of external name 6741resolution databases such as dynamic DNS. 6742 6743The wins hook parameter specifies the name of a script or executable 6744that will be called as follows: 6745 6746 wins_hook operation name nametype ttl IP_list 6747 6748The first argument is the operation and is one of "add", "delete", 6749or "refresh". In most cases the operation can be ignored as the rest 6750of the parameters provide sufficient information. Note that "refresh" 6751may sometimes be called when the name has not previously been added, 6752in that case it should be treated as an add. 6753 6754The second argument is the netbios name. If the name is not a legal 6755name then the wins hook is not called. Legal names contain only 6756letters, digits, hyphens, underscores and periods. 6757 6758The third argument is the netbios name type as a 2 digit hexadecimal 6759number. 6760 6761The fourth argument is the TTL (time to live) for the name in seconds. 6762 6763The fifth and subsequent arguments are the IP addresses currently 6764registered for that name. If this list is empty then the name should 6765be deleted. 6766 6767An example script that calls the BIND dynamic DNS update program 6768"nsupdate" is provided in the examples directory of the Samba source 6769code. 6770 6771label(winssupport) 6772dit(bf(wins support (G))) 6773 6774This boolean controls if the url(bf(nmbd))(nmbd.8.html) process in 6775Samba will act as a WINS server. You should not set this to true 6776unless you have a multi-subnetted network and you wish a particular 6777url(bf(nmbd))(nmbd.8.html) to be your WINS server. Note that you 6778should em(*NEVER*) set this to true on more than one machine in your 6779network. 6780 6781 bf(Default:) 6782tt( wins support = no) 6783 6784label(workgroup) 6785dit(bf(workgroup (G))) 6786 6787This controls what workgroup your server will appear to be in when 6788queried by clients. Note that this parameter also controls the Domain 6789name used with the link(bf("security=domain"))(securityequaldomain) 6790setting. 6791 6792 bf(Default:) 6793tt( set at compile time to WORKGROUP) 6794 6795 bf(Example:) 6796 workgroup = MYGROUP 6797 6798label(writable) 6799dit(bf(writable (S))) 6800 6801Synonym for link(bf("writeable"))(writeable) for people who can't spell :-). 6802 6803label(writelist) 6804dit(bf(write list (S))) 6805 6806This is a list of users that are given read-write access to a 6807service. If the connecting user is in this list then they will be 6808given write access, no matter what the link(bf("writeable"))(writeable) 6809option is set to. The list can include group names using the @group 6810syntax. 6811 6812Note that if a user is in both the read list and the write list then 6813they will be given write access. 6814 6815See also the link(bf("read list"))(readlist) option. 6816 6817 bf(Default:) 6818tt( write list = <empty string>) 6819 6820 bf(Example:) 6821tt( write list = admin, root, @staff) 6822 6823label(writecachesize) 6824dit(bf(write cache size (S))) 6825 6826This integer parameter (new with Samba 2.0.7) if set to non-zero causes Samba to create an in-memory 6827cache for each oplocked file (it does bf(not) do this for non-oplocked files). All 6828writes that the client does not request to be flushed directly to disk will be 6829stored in this cache if possible. The cache is flushed onto disk when a write 6830comes in whose offset would not fit into the cache or when the file is closed 6831by the client. Reads for the file are also served from this cache if the data 6832is stored within it. 6833 6834This cache allows Samba to batch client writes into a more efficient write 6835size for RAID disks (ie. writes may be tuned to be the RAID stripe size) and 6836can improve performance on systems where the disk subsystem is a bottleneck 6837but there is free memory for userspace programs. 6838 6839The integer parameter specifies the size of this cache (per oplocked file) 6840in bytes. 6841 6842 bf(Default:) 6843tt( write cache size = 0) 6844 6845 bf(Example:) 6846tt( write cache size = 262144) 6847for a 256k cache size per file. 6848 6849label(writeok) 6850dit(bf(write ok (S))) 6851 6852Synonym for link(bf(writeable))(writeable). 6853 6854label(writeraw) 6855dit(bf(write raw (G))) 6856 6857This parameter controls whether or not the server will support raw 6858writes SMB's when transferring data from clients. You should never 6859need to change this parameter. 6860 6861 bf(Default:) 6862tt( write raw = yes) 6863 6864label(writeable) 6865dit(bf(writeable)) 6866 6867An inverted synonym is link(bf("read only"))(readonly). 6868 6869If this parameter is tt("no"), then users of a service may not create 6870or modify files in the service's directory. 6871 6872Note that a printable service link(bf(("printable = yes")))(printable) 6873will em(*ALWAYS*) allow writing to the directory (user privileges 6874permitting), but only via spooling operations. 6875 6876 bf(Default:) 6877tt( writeable = no) 6878 6879 bf(Examples:) 6880verb( 6881 read only = no 6882 writeable = yes 6883 write ok = yes 6884) 6885 6886label(wtmpdirectory) 6887dit(bf(wtmp directory(G))) 6888 6889This parameter is only available if Samba has been configured and compiled 6890with the option tt(--with-utmp). It specifies a directory pathname that is 6891used to store the wtmp or wtmpx files (depending on the UNIX system) that 6892record user connections to a Samba server. See also the 6893link(bf("utmp directory"))(utmpdirectory) parameter. By default this is 6894not set, meaning the system will use either what has been set by 6895link(bf("utmp"))(utmp) or whatever wtmp file the native system is set to use 6896(usually /var/run/wtmp on Linux). 6897 6898 bf(Default:) 6899tt(no wtmp directory) 6900 6901 bf(Example:) 6902tt(wtmp directory = /var/adm/) 6903 6904endit() 6905 6906label(WARNINGS) 6907manpagesection(WARNINGS) 6908 6909Although the configuration file permits service names to contain 6910spaces, your client software may not. Spaces will be ignored in 6911comparisons anyway, so it shouldn't be a problem - but be aware of the 6912possibility. 6913 6914On a similar note, many clients - especially DOS clients - limit 6915service names to eight characters. url(bf(Smbd))(smbd.8.html) has no 6916such limitation, but attempts to connect from such clients will fail 6917if they truncate the service names. For this reason you should 6918probably keep your service names down to eight characters in length. 6919 6920Use of the link(bf([homes]))(homes) and link(bf([printers]))(printers) 6921special sections make life for an administrator easy, but the various 6922combinations of default attributes can be tricky. Take extreme care 6923when designing these sections. In particular, ensure that the 6924permissions on spool directories are correct. 6925 6926label(VERSION) 6927manpagesection(VERSION) 6928 6929This man page is correct for version 2.0 of the Samba suite. 6930 6931label(SEEALSO) 6932manpagesection(SEE ALSO) 6933 6934url(bf(smbd (8)))(smbd.8.html), url(bf(smbclient (1)))(smbclient.1.html), 6935url(bf(nmbd (8)))(nmbd.8.html), url(bf(testparm (1)))(testparm.1.html), 6936url(bf(testprns (1)))(testprns.1.html), url(bf(Samba))(samba.7.html), 6937url(bf(nmblookup (1)))(nmblookup.1.html), url(bf(smbpasswd (5)))(smbpasswd.5.html), 6938url(bf(smbpasswd (8)))(smbpasswd.8.html). 6939 6940label(AUTHOR) 6941manpageauthor() 6942 6943The original Samba software and related utilities were created by 6944Andrew Tridgell email(samba@samba.org). Samba is now developed 6945by the Samba Team as an Open Source project similar to the way the 6946Linux kernel is developed. 6947 6948The original Samba man pages were written by Karl Auer. The man page 6949sources were converted to YODL format (another excellent piece of Open 6950Source software, available at 6951url(bf(ftp://ftp.icce.rug.nl/pub/unix/))(ftp://ftp.icce.rug.nl/pub/unix/)) 6952and updated for the Samba2.0 release by Jeremy Allison. 6953email(samba@samba.org). 6954 6955See url(bf(samba (7)))(samba.7.html) to find out how to get a full 6956list of contributors and details on how to submit bug reports, 6957comments etc. 6958